NonCustodialWallet

NonCustodialWallet

Non-Custodial Wallet using nChain Threshold Signature Scheme

This wallet distributes key management across multiple participants, requiring a threshold number to sign transactions.

Parameters:

  • n: Total number of participants
  • t: Threshold polynomial degree (t+1 to reconstruct, 2t+1 to sign)

Common configurations:

  • 2-of-3: n=3, t=1 (3 participants, 3 needed to sign)
  • 3-of-5: n=5, t=2 (5 participants, 5 needed to sign)

Note: Due to the INVSS protocol, signing requires 2t+1 participants.

Constructor

new NonCustodialWallet(network, n, t)

Description:

  • Create a new non-custodial wallet

Source:
Parameters:
Name Type Description
network string

'main' or 'test'
n number

Total number of participants
t number

Threshold polynomial degree

Members

derivedAddresses :Map.<string, Object>

Description:

  • Cache of derived addresses

Source:

Cache of derived addresses

Type:
  • Map.<string, Object>

masterKeys :Object|null

Description:

  • BIP32 master keys (extendedPrivateKey, extendedPublicKey)

Source:

BIP32 master keys (extendedPrivateKey, extendedPublicKey)

Type:
  • Object | null

mnemonic :string|null

Description:

  • BIP39 mnemonic phrase

Source:

BIP39 mnemonic phrase

Type:
  • string | null

Methods

_exportShares()

Description:

  • Export shares from the internal scheme for backup

Source:

_reconstructPublicKey()

Description:

  • Reconstruct the aggregate public key from shares

Source:

canSign() → {boolean}

Description:

  • Check if wallet can sign (has private key access)

Source:
Returns:

True if wallet can sign

Type
boolean

canSignHD() → {boolean}

Description:

  • Check if HD wallet can sign (separate from TSS)

Source:
Returns:

True if HD signing is available

Type
boolean

clear()

Description:

  • Clear sensitive data

Source:

clearAddressCache()

Description:

  • Clear the derived addresses cache

Source:

createTransaction() → {TransactionBuilder}

Description:

  • Create a new transaction builder

Source:
Returns:

Transaction builder instance

Type
TransactionBuilder

deriveAddress(account, change, index, type) → {Object}

Description:

  • Derive an HD address at the specified BIP path Requires HD wallet initialization via createNewHD(), fromMnemonic(), or fromSeed()

Source:
Parameters:
Name Type Default Description
account number 0

Account index (hardened)
change number 0

Change index (0=external/receiving, 1=internal/change)
index number 0

Address index
type string segwit

Address type ('legacy', 'wrapped-segwit', 'segwit', 'taproot')
Returns:

Derived address details

Type
Object

destroy() → {void}

Description:

  • Securely clear all sensitive data (overwrites buffers)

Source:
Returns:
Type
void

exportShares() → {Object}

Description:

  • Export shares for backup

Source:
Returns:

Exportable data

Type
Object

exportWIF(account, change, index, type) → {string|null}

Description:

  • Export HD-derived private key as WIF

Source:
Parameters:
Name Type Default Description
account number 0

Account index
change number 0

Change index
index number 0

Address index
type string segwit

Address type
Returns:

WIF-encoded private key

Type
string | null

generateEphemeralKeys(count)

Description:

  • Generate more ephemeral keys for signing

Source:
Parameters:
Name Type Default Description
count number 10

Number of keys to generate

getAddress(type) → {string}

Description:

  • Get wallet address

Source:
Parameters:
Name Type Default Description
type string segwit

'segwit' or 'taproot'
Returns:

Bitcoin address

Type
string

getAddressCount() → {number}

Description:

  • Get total count of derived addresses

Source:
Returns:

Address count

Type
number

getAddresses(account, type, count) → {Array.<Object>}

Description:

  • Get multiple addresses of a specific type for an account

Source:
Parameters:
Name Type Default Description
account number 0

Account index
type string segwit

Address type
count number 20

Number of addresses to generate
Returns:

Array of address details

Type
Array.<Object>

getChangeAddress(account, index, type) → {Object}

Description:

  • Get a change (internal) address from HD derivation

Source:
Parameters:
Name Type Default Description
account number 0

Account index
index number 0

Address index
type string segwit

Address type
Returns:

Address details

Type
Object

getExtendedPrivateKey() → {string|null}

Description:

  • Get the extended private key (xprv/tprv)

Source:
Returns:

Extended private key or null

Type
string | null

getExtendedPublicKey() → {string|null}

Description:

  • Get the extended public key (xpub/tpub)

Source:
Returns:

Extended public key or null

Type
string | null

getMnemonic() → {string|null}

Description:

  • Get the wallet's mnemonic phrase (if available)

Source:
Returns:

Mnemonic phrase or null

Type
string | null

getNetwork() → {string}

Description:

  • Get the wallet's network type

Source:
Returns:

Network type ('main' or 'test')

Type
string

getPublicKey() → {Buffer}

Description:

  • Get the aggregate public key

Source:
Returns:

Compressed public key

Type
Buffer

getReceivingAddress(account, index, type) → {Object}

Description:

  • Get a receiving (external) address from HD derivation

Source:
Parameters:
Name Type Default Description
account number 0

Account index
index number 0

Address index
type string segwit

Address type
Returns:

Address details

Type
Object

getShare(index) → {Object}

Description:

  • Get a specific participant's share

Source:
Parameters:
Name Type Description
index number

Participant index (1-indexed)
Returns:

Share data

Type
Object

getShares() → {Array}

Description:

  • Get all shares for distribution to participants

Source:
Returns:

Array of share objects

Type
Array

getThresholdConfig() → {Object}

Description:

  • Get threshold configuration

Source:
Returns:

Configuration details

Type
Object

hasHD() → {boolean}

Description:

  • Check if HD derivation is available

Source:
Returns:

True if HD is available

Type
boolean

initialize(ephemeralKeyCount)

Description:

  • Initialize the wallet with TSS key generation

Source:
Parameters:
Name Type Default Description
ephemeralKeyCount number 10

Number of ephemeral keys to pre-generate

listAddresses() → {Array.<Object>}

Description:

  • List all derived addresses

Source:
Returns:

Array of all derived address objects

Type
Array.<Object>

sign(messageHash, participantIndices) → {Object}

Description:

  • Sign a message hash using threshold signature

Source:
Parameters:
Name Type Default Description
messageHash Buffer | string

32-byte message hash
participantIndices Array.<number> null

Indices of signing participants
Returns:

Signature {r, s, signature}

Type
Object

signMessage(message, participantIndices) → {Object}

Description:

  • Sign a message (with Bitcoin message prefix)

Source:
Parameters:
Name Type Default Description
message string | Buffer

Message to sign
participantIndices Array.<number> null

Signing participants
Returns:

Signature

Type
Object

(async) signMessageBIP322(message, account, index, type) → {Promise.<Buffer>}

Description:

  • Sign a message using BIP322 (for SegWit/Taproot HD addresses)

Source:
Parameters:
Name Type Default Description
message string | Buffer

Message to sign
account number 0

Account index
index number 0

Address index
type string segwit

Address type ('segwit' or 'taproot')
Returns:

BIP322 signature

Type
Promise.<Buffer>

signMessageHD(message, account, index, type) → {Object}

Description:

  • Sign a message using HD-derived key (legacy Bitcoin message format)

Source:
Parameters:
Name Type Default Description
message string | Buffer

Message to sign
account number 0

Account index
index number 0

Address index
type string segwit

Address type for signing
Returns:

Signature result

Type
Object

(async) signTransaction(builder, inputInfo) → {Promise.<TransactionBuilder>}

Description:

  • Sign a transaction with HD-derived wallet keys Note: This signs using HD-derived keys, not TSS aggregate key

Source:
Parameters:
Name Type Description
builder TransactionBuilder

Transaction builder with inputs added
inputInfo Array.<Object>

Array of {account, change, index, type} for each input
Returns:

Signed transaction builder

Type
Promise.<TransactionBuilder>

toJSON() → {Object}

Description:

  • Export wallet for serialization

Source:
Returns:

Serialized wallet data

Type
Object

verify(messageHash, signature) → {boolean}

Description:

  • Verify a signature

Source:
Parameters:
Name Type Description
messageHash Buffer | string

Message hash
signature Object | Buffer

Signature to verify
Returns:

True if valid

Type
boolean

verifyMessageHD(message, signature, publicKey) → {boolean}

Description:

  • Verify a signed message using HD public key

Source:
Parameters:
Name Type Description
message string | Buffer

Original message
signature Object

Signature to verify
publicKey string | Buffer

Public key to verify against
Returns:

True if signature is valid

Type
boolean

(static) createNew(network, n, t, ephemeralKeyCount) → {Object}

Description:

  • Create a new wallet with fresh key generation

Source:
Parameters:
Name Type Default Description
network string main

Network type
n number 3

Total participants (default 3)
t number 1

Threshold degree (default 1, meaning 3-of-3 for signing)
ephemeralKeyCount number 10

Pre-generated ephemeral keys
Returns:

Wallet and shares

Type
Object

(static) createNewHD(network, n, t, strength, ephemeralKeyCount) → {Object}

Description:

  • Create a new HD wallet with fresh mnemonic and TSS key generation

Source:
Parameters:
Name Type Default Description
network string main

Network type ('main' or 'test')
n number 3

Total participants (default 3)
t number 1

Threshold degree (default 1)
strength number 256

Mnemonic strength (128, 160, 192, 224, 256)
ephemeralKeyCount number 10

Pre-generated ephemeral keys
Returns:
Type
Object

(static) fromExtendedKey(network, extendedKey, n, t, ephemeralKeyCount) → {NonCustodialWallet}

Description:

  • Create a wallet from an extended key (xprv/xpub/tprv/tpub) Note: TSS is still used for signing; HD is for address derivation only

Source:
Parameters:
Name Type Default Description
network string

Network type ('main' or 'test')
extendedKey string

BIP32 extended key
n number 3

Total participants
t number 1

Threshold degree
ephemeralKeyCount number 10

Pre-generated ephemeral keys
Returns:

Wallet instance

Type
NonCustodialWallet

(static) fromMnemonic(network, mnemonic, n, t, passphrase, ephemeralKeyCount) → {NonCustodialWallet}

Description:

  • Restore an HD wallet from a BIP39 mnemonic phrase

Source:
Parameters:
Name Type Default Description
network string

Network type ('main' or 'test')
mnemonic string

BIP39 mnemonic phrase (12-24 words)
n number 3

Total participants
t number 1

Threshold degree
passphrase string

Optional BIP39 passphrase
ephemeralKeyCount number 10

Pre-generated ephemeral keys
Returns:

Restored wallet

Type
NonCustodialWallet

(static) fromSeed(network, seed, n, t, ephemeralKeyCount) → {NonCustodialWallet}

Description:

  • Create an HD wallet from a raw seed

Source:
Parameters:
Name Type Default Description
network string

Network type ('main' or 'test')
seed string | Buffer

64-byte seed as hex string or Buffer
n number 3

Total participants
t number 1

Threshold degree
ephemeralKeyCount number 10

Pre-generated ephemeral keys
Returns:

Wallet instance

Type
NonCustodialWallet

(static) fromShares(network, shares, t) → {NonCustodialWallet}

Description:

  • Restore wallet from exported shares (limited functionality) Note: Full signing requires the complete JVRSS state

Source:
Parameters:
Name Type Description
network string

Network type
shares Array

Exported shares
t number

Threshold degree
Returns:

Restored wallet

Type
NonCustodialWallet

(static) fromWIF(wif, n, t, ephemeralKeyCount) → {NonCustodialWallet}

Description:

  • Create a wallet from a WIF private key (single-key mode for HD addresses) Note: TSS is still used for aggregate key; WIF enables single-key HD derivation

Source:
Parameters:
Name Type Default Description
wif string

WIF-encoded private key
n number 3

Total participants for TSS
t number 1

Threshold degree
ephemeralKeyCount number 10

Pre-generated ephemeral keys
Returns:

Wallet instance

Type
NonCustodialWallet

(static) importShares(exportedData) → {NonCustodialWallet}

Description:

  • Import shares from backup

Source:
Parameters:
Name Type Description
exportedData Object

Previously exported data
Returns:

Restored wallet

Type
NonCustodialWallet