Low-level API

The Low-level API provides granular control over the entire transaction lifecycle. Unlike the High-level API which abstracts away the details, these methods allow you to manually construct, encode, sign, and send transactions. This is ideal for advanced scenarios, such as multi-signature workflows where different parties need to sign a transaction before it's broadcasted.

This API is organized into four main groups of methods, each corresponding to a stage in the transaction lifecycle:

1. Encode

   Prepare a transaction and serialize it into a binary buffer.

2. Sign

   Add a digital signature to an encoded transaction.

3. Multi-sign

   Add multiple digital signatures to a transaction.

4. Send

   Broadcast a signed transaction to the blockchain.

Encoding Transactions

Encoding is the first step in creating a transaction. The encode[Type]Tx methods take the core transaction data (itx) and wrap it in a standard transaction structure, adding necessary details like the chainId and nonce. The result is a human-readable transaction object and a binary buffer ready for signing.

There is an encode method for every transaction type supported by the chain. You can get a full list by calling client.getTxEncodeMethods().

encode[Type]Tx(payload)

Encodes a transaction without signing it.

Parameters

Returns

Example

TransferV2Tx

const { encodeTransferV2Tx } = client;
const senderWallet = fromRandom();
const receiverAddress = 'z1...';

const { object, buffer } = await encodeTransferV2Tx({
  tx: {
    itx: {
      to: receiverAddress,
      value: await client.fromTokenToUnit(10), // Transfer 10 native tokens
    },
  },
  wallet: senderWallet,
});

console.log('Encoded TX Object:', object);
console.log('Buffer to Sign:', buffer.toString('hex'));

Signing Transactions

The sign[Type]Tx methods build on the encoding step by adding a digital signature. These methods encode the transaction and then use the provided wallet to sign the resulting binary buffer.

You can get a full list of available signing methods by calling client.getTxSignMethods().

sign[Type]Tx(payload)

Encodes and signs a transaction.

Parameters

Returns

Example

TransferV2Tx

const { signTransferV2Tx } = client;
const senderWallet = fromRandom();
const receiverAddress = 'z1...';

const signedTx = await signTransferV2Tx({
  tx: {
    itx: {
      to: receiverAddress,
      value: await client.fromTokenToUnit(10),
    },
  },
  wallet: senderWallet,
});

console.log('Signed TX:', signedTx);

Sending Transactions

The send[Type]Tx methods are responsible for broadcasting a transaction to the blockchain. These methods can perform the signing step implicitly if an unsigned transaction and a wallet are provided, or they can send a transaction that has already been signed.

A full list of send methods is available via client.getTxSendMethods().

send[Type]Tx(payload)

Signs (if necessary) and sends a transaction to the chain.

Parameters

Returns

Example: Auto-Signing

TransferV2Tx

const { sendTransferV2Tx } = client;
const senderWallet = fromRandom();
const receiverAddress = 'z1...';

// The client will sign this transaction using senderWallet before sending.
const txHash = await sendTransferV2Tx({
  tx: {
    itx: {
      to: receiverAddress,
      value: await client.fromTokenToUnit(10),
    },
  },
  wallet: senderWallet,
});

console.log('Transaction sent with hash:', txHash);

Example: Sending a Pre-Signed Transaction

TransferV2Tx

// Assume signedTx is from the sign[Type]Tx example
const { sendTransferV2Tx } = client;

const txHash = await sendTransferV2Tx({
  tx: signedTx, // Pass the entire signed transaction object
  wallet: senderWallet,
});

console.log('Pre-signed transaction sent with hash:', txHash);

Multi-Signature Transactions

For workflows requiring multiple signatures (like an atomic swap), the multiSign[Type]Tx methods are used. The process involves one party signing the transaction first (using a standard sign[Type]Tx method), and subsequent parties adding their signatures using the corresponding multiSign[Type]Tx method.

You can get a list of transactions that support multiple signatures via client.getTxMultiSignMethods().

multiSign[Type]Tx(payload)

Adds a signature to a transaction that already has one or more signatures.

Parameters

Returns

Example: Atomic Swap (ExchangeV2Tx)

ExchangeV2Tx

// Wallets for two parties
const aliceWallet = fromRandom();
const bobWallet = fromRandom();

// 1. Alice prepares and signs the initial exchange transaction
const exchangeTx = {
  itx: {
    to: bobWallet.address,
    sender: {
      value: await client.fromTokenToUnit(10), // Alice offers 10 tokens
    },
    receiver: {
      value: await client.fromTokenToUnit(5), // Alice demands 5 tokens
    },
  },
};

const signedByAlice = await client.signExchangeV2Tx({
  tx: exchangeTx,
  wallet: aliceWallet,
});

// 2. Alice sends `signedByAlice` to Bob. Bob adds his signature.
const signedByBoth = await client.multiSignExchangeV2Tx({
  tx: signedByAlice,
  wallet: bobWallet,
});

// 3. Bob sends `signedByBoth` back to Alice. Alice sends the final transaction.
const txHash = await client.sendExchangeV2Tx({
  tx: signedByBoth,
  wallet: aliceWallet, // The sender wallet is used to submit
});

console.log('Atomic swap transaction sent:', txHash);