namillum

# @zilliqa-js/account > Classes for managing accounts and account-related actions. ## Interfaces ```typescript export interface TxReceipt { success: boolean; cumulative_gas: number; } interface TxParams { version: number; toAddr: string; amount: BN; gasPrice: BN; gasLimit: Long; code?: string; data?: string; receipt?: TxReceipt; nonce?: number; pubKey?: string; signature?: string; } ``` When you give `nonce`, you should give `pubKey` together. ## Classes ### `Account` Class for managing an account (i.e., a private/public keypair). #### `Account(privateKey: string, nonce?: number): Account` ##### Parameters - `privateKey`: `string` - hex-encoded private key - `nonce`: `number` (optional) - the current nonce ##### Returns - `Account` - an `Account` instance. #### Members ##### `privateKey: string` ##### `publicKey: string` ##### `address: string` ##### `nonce: number` #### Static Methods ##### `static fromFile(file: string, passphrase: string): Promise<Account>` Generates an account from any JSON-encoded string that complies with the [Web3 Secret Storage definition](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition). ###### Parameters - `file`: `string` - JSON-encoded string containing the keystore file. - `passphrase`: `string` - passphrase used to encrypt the file. ###### Returns - `Promise<Account>` - an `Account` instance, initialised with the details provided by the keystore file. #### Instance Methods ##### `toFile(passphrase: string, kdf: 'pbkdf2' |'scrypt' = 'scrypt'): Promise<Account>` Encrypts and JSON-encodes the account. Complies with the [Web3 Secret Storage definition](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition). ###### Parameters - `passphrase`: `string` - passphrase used to encrypt the file. - `kdf`: `'pbkdf2' | 'scrypt'` - the key derivation function to use for encryption. ###### Returns - `Promise<string>` - the JSON-encoded string of the keystore file. ##### `signTransaction(bytes: Buffer): string` Signs arbitrary bytes (most often transactions) using a Schnorr signing scheme. ###### Parameters - `bytes`: `Buffer` - a `Buffer` of the `protobuf` encoded transaction bytes. ###### Returns - `string` - hex-encoded signature over the bytes, using the instance private key. ### `Wallet` Class for managing multiple accounts. #### `Wallet(provider: Provider, accounts?: Account[] = []): Wallet` ##### Parameters - `provider`: `Provider` - a Provider instance (see `@zilliqa-js/core`). Required for signing. - `accounts`: `Account[]` (optional) - an array of `Account` instances to pre-populate the wallet with. ##### Returns - `Wallet` #### Members ##### `accounts: { [address: string]: Account }` An object consisting of `address: Account` KV pairs. By default, an empty object. ##### `defaultAccount: Account` The default account used for signing transactions. By default, `undefined`. It is set to the `0`-indexed account when a `Wallet` instance is constructed. #### Instance methods ##### `create(): void` Creates a new keypair with a randomly-generated private key. The new account is accessible by address. This method mutates the `Wallet` instance. ###### Parameters None ###### Returns - `string` - address of the new account. ##### `addByPrivateKey(privateKey: string): string` Adds an `Account` to the `Wallet`. ###### Parameters - `privateKey`: `string` - hex-encoded private key. ###### Returns - `string` - the corresponing address, computer from the private key. ##### `addByKeystore(keystore: string, passphrase: string): Promise<string>` Adds an account by keystore. This method is asynchronous and returns a `Promise<string>`, in order not to block on the underlying decryption operation. ###### Parameters - `keystore`: `string` - JSON-encoded keystore file. - `passphrase`: `string` - the passphrase used to encode the keystore file. ###### Returns - `Promise<string>` - the corresponding address. ##### `addByMnemonic(phrase: string, index: number = 0): string` Adds an `Account` by use of a mnemonic as specified in BIP-32 and BIP-39 ###### Parameters - `phrase`: `string` - the 12-word mnemonic to use. - `index`: `number` (Optional) - the index of the child key. ###### Returns - `string` - the corresponding address. ##### `export(address: string, passphrase, string, kdf: 'pbkdf2' | 'scrypt'): Promise<string>` - Exports an `Account` to a keystore file, encrypted with a passphrase. ###### Parameters - `address`: `string` - the address of the selected account. - `passphrase`: `string` - the passphrase to encrypt the `Account` with. - `kdf`: `'pbkdf2' | 'scrypt'` - key derivation function. ###### Returns - `Promise<string>` - the JSON-encoded keystore file. ##### `remove(address: string): boolean` - Exports an `Account` to a keystore file, encrypted with a passphrase. ###### Parameters - `address`: `string` - the address of the account to remove. ###### Returns - `boolean` - whether the `Account` was successfully removed. ##### `setDefault(address: string): void` Sets the default account to sign with. ###### Parameters - `address`: `string` - the address of the account to set as default. ###### Returns - `void` ##### `sign(transaction: Transaction, offlineSign?: boolean): Promise<Transaction>` Sign a `Transaction` with the default `Account`. This method is asynchronous as it will attempt to obtain the `nonce` from the `Provider`. There is an offline mode that can be activated manually by setting the optional `offlineSign` parameter. ###### Parameters - `transaction`: `Transaction` - a `Transaction` instance. - `offlineSign`: `boolean` (optional) - toggles offline signing on/off. Defaults to `false` if the field is not set. If explicitly set to `true`, offline mode is used and does not require internet connection to sign a transaction. ###### Note\*\*: In offline mode, the nonce must be explicitly set in the Transacti object. ###### Returns - `Promise<Transaction>` - a signed transaction. ##### `signWith(transaction: Transaction, address: string, offlineSign?: boolean): Promise<Transaction>` Sign a `Transaction` with the chosen `Account`. This method is asynchronous as it will attempt to obtain the `nonce` from the `Provider`. There is an offline mode that can be activated manually by setting the optional `offlineSign` parameter. ###### Parameters - `transaction`: `Transaction` - a `Transaction` instance. - `address`: `string` - the address of the `Account` to be used for signing. - `offlineSign`: `boolean` (optional) - toggles offline signing on/off. Defaults to `false` if the field is not set. If explicitly set to `true`, offline mode is used and does not require internet connection to sign a transaction. ###### Note\*\*: In offline mode, the nonce must be explicitly set in the Transacti object. ###### Returns - `Promise<Transaction>` - a signed transaction. ##### `signBatch(txList: Transaction[]): Promise<Transaction[]>` Sign a list of `Transaction` with the default `Account`. This method is asynchronous as it will attempt to obtain the `nonce` from the `Provider`. ###### Parameters - `txList`: `Transaction[]` - a list of `Transaction` instances. ###### Returns - `Promise<Transaction[]>` - a list of signed transactions. ###### Example ```js // zilliqa, wallet obj declaration omitted for clarity let txList = []; for (let i = 0; i < 2; i++) { // create a new transaction object const tx = zilliqa.transactions.new( { version: VERSION, toAddr: "0xA54E49719267E8312510D7b78598ceF16ff127CE", amount: new BN(units.toQa("1", units.Units.Zil)), gasPrice: units.toQa("2000", units.Units.Li), gasLimit: Long.fromNumber(1), }, false ); txList.push(tx); } // sign the batch transactions sequentially const batchResult = await zilliqa.wallet.signBatch(txList); for (const signedTx of batchResult) { // nonce must be different console.log("The signed transaction nonce is: %o", signedTx.nonce); console.log("The signed transaction signature is: %o\n", signedTx.signature); } ``` ### `Transaction` A class that represents a single `Transaction` on the Zilliqa network. It is a functor. Its purpose is to encode the possible states a Transaction can be in: Confirmed, Rejected, Pending, or Initialised (i.e., not broadcasted). #### Members ##### `bytes: Buffer` A getter `protobuf` that returns a `Buffer` of `protobuf`-encoded bytes. This is a convenience member that allows a `Transaction` to be signed easily. ##### `senderAddress: string` A getter than computes the address of the `Transaction` sender. If there is no sender public key set, returns `0x00000000000000000000000000000000000000000000`. ##### `txParams: TxParams` A getter that returns the current `TxParams`. #### Static Methods ##### `static confirm(params: TxParams, provider: Provider): Transaction` Instantiates a `Transaction` in `Confirmed` state. ###### Parameters - `params`: `TxParams` - core fields to initialise the `Transaction` with. - `provider`: `Provider` - a `Provider` instance. ###### Returns - `Transaction` - the newly-Instantiated `Transaction`. ###### Example ```typescript import { HTTPProvider } from "@zilliqa-js/core"; import { Transaction } from "@zilliqa-js/account"; const txParams = { version: 0, toAddr: "20_byte_hex_string", amount: new BN(8), gasPrice: new BN(100), gasLimit: Long.fromNumber(888), }; const tx = Transaction.confirm(txParams, new HTTPProvider("http://my-api.com")); expect(tx.isConfirmed()).toBeTruthy(); ``` ##### `static reject(params: TxParams, provider: Provider): Transaction` Instantiates a `Transaction` in `Rejected` state. ###### Parameters - `params`: `TxParams` - core fields to initialise the `Transaction` with. - `provider`: `Provider` - a `Provider` instance. ###### Returns - `Transaction` - the newly-Instantiated `Transaction`. ###### Example ```typescript import { HTTPProvider } from "@zilliqa-js/core"; import { Transaction } from "@zilliqa-js/account"; const txParams = { version: 0, toAddr: "20_byte_hex_string", amount: new BN(8), gasPrice: new BN(100), gasLimit: Long.fromNumber(888), }; const tx = Transaction.reject(txParams, new HTTPProvider("http://my-api.com")); expect(tx.isRejected()).toBeTruthy(); ``` #### Instance Methods ##### `confirm(txHash: string, maxAttempts: number = 33, interval: number = 1000): Promise<Transaction>` Checks whether the `Transaction` is confirmed on the blockchain, by verifying the its `receipt` status (`boolean`). This method uses an exponential backoff to poll the lookup node. By default, the number of attempts made is 33, with a starting interval of 1000ms. ###### Parameters - `txHash`: `string` - the transaction hash to use for polling. - `maxAttempts`: `number = 33` (Optional) - the maximum number of attempts before setting status as `Rejected`. - `interval`: `number = 1000` (Optional) - the initial interval. This grows exponentially between attempts. ###### Returns - `Promise<Transaction>` - `Transaction` with its status confirmed onchain. ###### Example ```typescript import { HTTPProvider } from '@zilliqa-js/core'; import { Transaction } from '@zilliqa-js/account'; // hash can be obtained from CreateTransaction const my_hash = 'some_known_tx_hash'; conts tx = new Transaction(params, new HTTPProvider('http://my-api.com')); tx.confirm(some_hash) .map((tx) => // do something) .catch((err) => // handle the error); ``` ##### `blockConfirm(txHash: string, maxblockCount: number = 4, interval: number = 1000): Promise<Transaction>` Checks whether the `Transaction` is confirmed on the blockchain, by verifying the its `receipt` status (`boolean`). This method uses latest blockNumber to get the transaction receipt, which is more frendily to remote lookup node. By default, the number of blockCount is 4, with a starting interval of 1000ms. The member `Transaction.blockConfirmation` will count the block numbers during the process. ###### Parameters - `txHash`: `string` - the transaction hash to use for polling. - `maxblockCount`: `number = 4` (Optional) - the maximum number of block count before setting status as `Rejected`. - `interval`: `number = 1000` (Optional) - the initial interval. This grows exponentially between attempts. ###### Returns - `Promise<Transaction>` - `Transaction` with its status confirmed onchain. ###### Example ```typescript import { HTTPProvider } from '@zilliqa-js/core'; import { Transaction } from '@zilliqa-js/account'; // hash can be obtained from CreateTransaction const my_hash = 'some_known_tx_hash'; conts tx = new Transaction(params, new HTTPProvider('http://my-api.com')); tx.blockConfirm(some_hash) .map((tx) => // do something) .catch((err) => // handle the error); ``` ##### `map(txHash): Transaction` Maps over the transaction, taking a callback that accepts `TxParams`. The user may freely mutate the Transaction, and will receive the newly-mutated transaction. The object returned is merged into the target `Transaction`. ###### Parameters - `fn`: `(prev: TxParams) => TxParams)` - the transaction hash to use for polling. exponentially between attempts. ###### Returns - `Transaction`. ###### Example ```typescript import { HTTPProvider } from '@zilliqa-js/core'; import { Transaction } from '@zilliqa-js/account'; // hash can be obtained from CreateTransaction const my_hash = 'some_known_tx_hash'; let tx = new Transaction(params, new HTTPProvider('http://my-api.com')); async () => { try { tx = await tx.confirm(some_hash); if (tx.isConfirmed()) { .map((tx) => { // do something, but must always return `TxParams`. // generally, you should avoid performing side effects in `map`. return tx }); } } catch (err) { // handle this error somehow } }(); ``` ### Functions #### `encodeTransactionProto(tx: TxParams): Buffer` Encodes a transaction with `protobuf` and returns its bytes as a Buffer. Used for providing a payload to `signTransaction`. ##### Parameters - `tx`: `TxParams` - plain object containing core transaction fields that must be used when generating a signature. ##### Returns - `Buffer` - the bytes of the `protobuf`-serialised transaction fields.