libnemo
Version:
Nano cryptocurrency wallet library.
279 lines (278 loc) • 11.7 kB
TypeScript
import { Account } from '../account';
import { Block } from '../block';
import { Rpc } from '../rpc';
export type WalletType = 'BIP-44' | 'BLAKE2b' | 'Ledger';
/**
* Represents a wallet containing numerous Nano accounts derived from a single
* source, the form of which can vary based on the type of wallet. Currently,
* three types of wallets are supported: BIP-44, BLAKE2b, and Ledger.
*/
export declare class Wallet {
#private;
/**
* @returns {boolean}
*/
static get isInternal(): boolean;
/**
* @returns {'Wallet'}
*/
static get DB_NAME(): 'Wallet';
/**
* Retrieves all wallets with encrypted secrets and unencrypted metadata from
* the database.
*
* @returns Array of objects with properties: id, type, iv, salt, encrypted
*/
static backup(): Promise<{
readonly id: string;
readonly type: "BIP-44" | "BLAKE2b" | "Ledger";
readonly iv: ArrayBuffer;
readonly salt: ArrayBuffer;
readonly encrypted: ArrayBuffer;
}[]>;
/**
* Creates a new hardware wallet manager.
*
* @param {string} type - Wallet manufacturer
* @returns {Wallet} A newly instantiated Wallet
*/
static create(type: 'Ledger'): Promise<Wallet>;
/**
* Creates a new HD wallet by using an entropy value generated using a
* cryptographically strong pseudorandom number generator.
*
* @param {string} type - Algorithm used to generate wallet and child accounts
* @param {string} password - Encrypts the wallet to lock and unlock it
* @param {string} [salt=''] - Used when generating the final seed
* @returns {Wallet} A newly instantiated Wallet
*/
static create(type: 'BIP-44' | 'BLAKE2b', password: string, mnemonicSalt?: string): Promise<Wallet>;
/**
* Imports an existing HD wallet by using an entropy value generated using a
* cryptographically strong pseudorandom number generator.NamedD
*
* @param {string} type - Algorithm used to generate wallet and child accounts
* @param {string} password - Encrypts the wallet to lock and unlock it. Discard as soon as possible after loading the wallet.
* @param {string} seed - Used to derive child accounts
* @returns Wallet in a locked state
*/
static load(type: 'BIP-44' | 'BLAKE2b', password: string, seed: string): Promise<Wallet>;
/**
* Imports an existing HD wallet by using an entropy value generated using a
* cryptographically strong pseudorandom number generator.
*
* @param {string} type - Algorithm used to generate wallet and child accounts
* @param {string} password - Encrypts the wallet to lock and unlock it. Discard as soon as possible after loading the wallet.
* @param {string} mnemonicPhrase - Used to derive the wallet seed
* @param {string} [mnemonicSalt] - Used to alter the seed derived from the mnemonic phrase
* @returns Wallet in a locked state
*/
static load(type: 'BIP-44' | 'BLAKE2b', password: string, mnemonicPhrase: string, mnemonicSalt?: string): Promise<Wallet>;
/**
* Instantiates a Wallet from an existing record in the database using its UUID.
*
* @param {string} id - Generated when the wallet was created or imported
* @returns {Promise<Wallet>} Restored locked Wallet
*/
static restore(id: string): Promise<Wallet>;
/**
* Instantiates Wallet objects from records in the database.
*
* @param {string} id - Generated when the wallet was created or imported
* @returns {Promise<Wallet[]>} Restored locked Wallets
*/
static restore(): Promise<Wallet[]>;
constructor(type: WalletType, id?: string);
addEventListener: (type: string, callback: EventListenerOrEventListenerObject | null, options?: AddEventListenerOptions | boolean) => void;
dispatchEvent: (event: Event) => boolean;
removeEventListener: (type: string, callback: EventListenerOrEventListenerObject | null, options?: EventListenerOptions | boolean) => void;
/**
* @returns UUID of the wallet.
*/
get id(): string;
/**
* @returns True if the wallet is locked, else false
*/
get isLocked(): boolean;
/**
* Algorithm or device used to create wallet and derive accounts.
*/
get type(): WalletType;
/**
* Set when calling `create()`. Self-destructs after the first read.
* @returns Mnemonic phrase used to derive the wallet seed.
*/
get mnemonic(): string | undefined;
/**
* Set when calling `create()`. Self-destructs after the first read.
* @returns Seed used to derive accounts.
*/
get seed(): string | undefined;
/**
* Retrieves an account from a wallet using its child key derivation function.
* Defaults to the first account at index 0.
*
* The returned object will have keys corresponding with the requested range
* of account indexes. The value of each key will be the Account derived for
* that index in the wallet.
*
* ```
* const account = await wallet.account(1)
* // outputs the second account of the wallet
* console.log(account)
* // { address: <...>, publicKey: <...>, index: 1, <etc...> }
* ```
*
* @param {number} index - Wallet index of account. Default: 0
* @returns Promise for the Account at the specified index
*/
account(index?: number): Promise<Account>;
/**
* Retrieves accounts from a wallet using its child key derivation function.
* Defaults to the first account at index 0.
*
* The returned object will have keys corresponding with the requested range
* of account indexes. The value of each key will be the Account derived for
* that index in the wallet.
*
* ```
* const accounts = await wallet.accounts(0, 1))
* // outputs the first and second account of the wallet
* console.log(accounts)
* // {
* // 0: {
* // address: <...>,
* // publicKey: <...>,
* // index: 0,
* // <etc...>
* // },
* // 1: {
* // address: <...>,
* // publicKey: <...>,
* // index: 1,
* // <etc...>
* // }
* // }
* // individual accounts can be referenced using array index notation
* console.log(accounts[1])
* // { address: <...>, publicKey: <...>, index: 1, <etc...> }
* ```
*
* If `from` is greater than `to`, their values will be swapped.
* @param {number} [from=0] - Start index of accounts. Default: 0
* @param {number} [to=from] - End index of accounts. Default: `from`
* @returns {Promise<Map<number, Account>>} Promise for a list of Accounts at the specified indexes
*/
accounts(from?: number, to?: number): Promise<Map<number, Account>>;
/**
* Configures Ledger connection settings.
* @param {string} connection - Transport interface to use
*/
config(settings: {
connection: 'hid' | 'ble' | 'usb';
}): Promise<void>;
/**
* Configures vault worker settings.
* @param {number} timeout - Measured in seconds of inactivity before wallet automatically locks
*/
config(settings: {
timeout: number;
}): Promise<void>;
/**
* Removes encrypted secrets in storage, releases variable references to
* allow garbage collection, and terminates vault worker.
*/
destroy(): Promise<void>;
/**
* For BIP-44 and BLAKE2b wallets, clears the seed and mnemonic from the vault.
*
* For Ledger hardware wallets, revokes permission granted by the user to
* access the Ledger device. The 'quit app' ADPU command is uncooperative, so
* this is currently the only way to ensure the connection is severed.
* `setTimeout` is used to expire any lingering transient user activation.
*/
lock(): void;
/**
* Refreshes wallet account balances, frontiers, and representatives from the
* current state on the network.
*
* A successful response will set these properties on each account.
*
* @param {(Rpc|string|URL)} rpc - RPC node information required to refresh accounts, calculate PoW, and process blocks
* @returns {Promise<Map<number, Account>>} Promise for accounts with updated balances, frontiers, and representatives
*/
refresh(rpc: Rpc | string | URL, from?: number, to?: number): Promise<Map<number, Account>>;
/**
* Signs arbitrary strings using the private key of the account at the wallet
* index specified and returns a detached signature as a hexadecimal string.
* For compatibility with other Nano tools, the data is first hashed to a
* 32-byte value using BLAKE2b. The wallet must be unlocked prior to signing.
*
* @param {number} index - Account to use for signing
* @param {(string|string[])} data - Arbitrary data to be hashed and signed
*/
sign(index: number, data: string | string[]): Promise<string>;
/**
* Signs a block using the private key of the account at the wallet index
* specified. The signature is appended to the signature field of the block
* before being returned. The wallet must be unlocked prior to signing.
*
* @param {number} index - Account to use for signing
* @param {Block} block - Block data to be hashed and signed
*/
sign(index: number, block: Block): Promise<void>;
/**
* Signs a block using a Ledger hardware wallet at the wallet index specified.
* The signature is appended to the signature field of the block before being
* returned. The wallet must be unlocked prior to signing.
*
* @param {number} index - Account to use for signing
* @param {Block} block - Block data to be hashed and signed
* @param {Block} [frontier] - Previous block data to be cached by Ledger wallet
*/
sign(index: number, block: Block, frontier?: Block): Promise<void>;
/**
* Attempts to connect to the Ledger device.
*/
unlock(): Promise<void>;
/**
* Unlocks the wallet using the same password as used prior to lock it.
*
* @param {string} password Used previously to lock the wallet
*/
unlock(password: string): Promise<void>;
/**
* Fetches the lowest-indexed unopened account from a wallet in sequential
* order. An account is unopened if it has no frontier block.
*
* @param {Rpc} rpc - RPC node information required to refresh accounts, calculate PoW, and process blocks
* @param {number} batchSize - Number of accounts to fetch and check per RPC callout
* @param {number} from - Account index from which to start the search
* @returns {Promise<Account>} The lowest-indexed unopened account belonging to the wallet
*/
unopened(rpc: Rpc, batchSize?: number, from?: number): Promise<Account>;
/**
* Updates the password used to encrypt the wallet. The wallet must be unlocked
* prior to update.
*
* @param {string} password Used to re-encrypt the wallet
*/
update(password: string): Promise<void>;
/**
* Checks whether a given seed matches the wallet seed. The wallet must be
* unlocked prior to verification.
*
* @param {string} seed - Hexadecimal seed to be matched against the wallet data
* @returns True if input matches wallet seed
*/
verify(seed: string): Promise<boolean>;
/**
* Checks whether a given mnemonic phrase matches the wallet mnemonic. If a
* personal salt was used when generating the mnemonic, it cannot be verified.
* The wallet must be unlocked prior to verification.
*
* @param {string} mnemonic - Phrase to be matched against the wallet data
* @returns True if input matches wallet mnemonic
*/
verify(mnemonic: string): Promise<boolean>;
}