@zilliqa-js/account NPM

@zilliqa-js/account

Classes for managing accounts and account-related actions.

Interfaces

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.

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.

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

// 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

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

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

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

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

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
  }
}();