Encoding/Decoding

← Back to Transactions

Description

This example demonstrates how to serialize and deserialize transactions using the transact package:

• encodeTransaction() to get msgpack bytes with TX prefix
• encodeTransactionRaw() to get msgpack bytes without prefix
• decodeTransaction() to reconstruct transaction from bytes
• encodeSignedTransaction() and decodeSignedTransaction() for signed transactions
• txId() for calculating transaction ID

Prerequisites

• LocalNet running (via algokit localnet start)

Run This Example

From the repository root:

cd examples
npm run example transact/13-encoding-decoding.ts

Code

View source on GitHub

13-encoding-decoding.ts

/**
 * Example: Encoding/Decoding
 *
 * This example demonstrates how to serialize and deserialize transactions
 * using the transact package:
 * - encodeTransaction() to get msgpack bytes with TX prefix
 * - encodeTransactionRaw() to get msgpack bytes without prefix
 * - decodeTransaction() to reconstruct transaction from bytes
 * - encodeSignedTransaction() and decodeSignedTransaction() for signed transactions
 * - txId() for calculating transaction ID
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */

import { AlgorandClient } from '@algorandfoundation/algokit-utils';
import {
  Transaction,
  TransactionType,
  assignFee,
  decodeSignedTransaction,
  decodeTransaction,
  encodeSignedTransaction,
  encodeTransaction,
  encodeTransactionRaw,
  type PaymentTransactionFields,
  type SignedTransaction,
} from '@algorandfoundation/algokit-utils/transact';
import {
  createAlgodClient,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
  shortenAddress,
} from '../shared/utils.js';

/**
 * Gets a funded account from LocalNet's KMD wallet
 */
async function getLocalNetFundedAccount(algorand: AlgorandClient) {
  return await algorand.account.kmd.getLocalNetDispenserAccount();
}

/**
 * Converts bytes to a hex string for display
 */
function bytesToHex(bytes: Uint8Array, maxLength?: number): string {
  const hex = Buffer.from(bytes).toString('hex');
  if (maxLength && hex.length > maxLength) {
    return `${hex.slice(0, maxLength)}...`;
  }
  return hex;
}

/**
 * Compare two transactions field by field
 */
function compareTransactions(original: Transaction, decoded: Transaction): boolean {
  // Compare basic fields
  if (original.type !== decoded.type) return false;
  if (original.sender.toString() !== decoded.sender.toString()) return false;
  if (original.firstValid !== decoded.firstValid) return false;
  if (original.lastValid !== decoded.lastValid) return false;
  if (original.fee !== decoded.fee) return false;
  if (original.genesisId !== decoded.genesisId) return false;

  // Compare genesis hash
  if (original.genesisHash && decoded.genesisHash) {
    if (original.genesisHash.length !== decoded.genesisHash.length) return false;
    for (let i = 0; i < original.genesisHash.length; i++) {
      if (original.genesisHash[i] !== decoded.genesisHash[i]) return false;
    }
  } else if (original.genesisHash !== decoded.genesisHash) {
    return false;
  }

  // Compare payment fields if present
  if (original.payment && decoded.payment) {
    if (original.payment.receiver.toString() !== decoded.payment.receiver.toString()) return false;
    if (original.payment.amount !== decoded.payment.amount) return false;
  } else if (original.payment !== decoded.payment) {
    return false;
  }

  return true;
}

async function main() {
  printHeader('Encoding/Decoding Example');

  // Step 1: Initialize clients
  printStep(1, 'Initialize Algod Client');
  const algod = createAlgodClient();
  const algorand = AlgorandClient.defaultLocalNet();
  printInfo('Connected to LocalNet Algod');

  // Step 2: Get accounts
  printStep(2, 'Get Accounts');
  const sender = await getLocalNetFundedAccount(algorand);
  printInfo(`Sender address: ${shortenAddress(sender.addr.toString())}`);

  const receiver = algorand.account.random();
  printInfo(`Receiver address: ${shortenAddress(receiver.addr.toString())}`);

  // Step 3: Create a transaction object
  printStep(3, 'Create Transaction Object');
  const suggestedParams = await algod.suggestedParams();

  const paymentFields: PaymentTransactionFields = {
    receiver: receiver.addr,
    amount: 1_000_000n, // 1 ALGO
  };

  const transaction = new Transaction({
    type: TransactionType.Payment,
    sender: sender.addr,
    firstValid: suggestedParams.firstValid,
    lastValid: suggestedParams.lastValid,
    genesisHash: suggestedParams.genesisHash,
    genesisId: suggestedParams.genesisId,
    payment: paymentFields,
  });

  const txWithFee = assignFee(transaction, {
    feePerByte: suggestedParams.fee,
    minFee: suggestedParams.minFee,
  });

  printInfo(`Transaction type: ${txWithFee.type}`);
  printInfo(`Amount: 1,000,000 microALGO`);
  printInfo(`Fee: ${txWithFee.fee} microALGO`);

  // Step 4: Use encodeTransaction() to get msgpack bytes with TX prefix
  printStep(4, 'Encode Transaction with TX Prefix (encodeTransaction)');

  const encodedWithPrefix = encodeTransaction(txWithFee);
  printInfo(`Encoded bytes length: ${encodedWithPrefix.length} bytes`);
  printInfo(`First bytes (hex): ${bytesToHex(encodedWithPrefix, 40)}`);
  printInfo('');
  printInfo('The "TX" prefix (0x5458) is prepended for domain separation.');
  printInfo('This prevents the same bytes from being valid in multiple contexts.');
  printInfo(
    `TX in ASCII: "${String.fromCharCode(encodedWithPrefix[0])}${String.fromCharCode(encodedWithPrefix[1])}"`,
  );

  // Step 5: Use encodeTransactionRaw() to get msgpack bytes without prefix
  printStep(5, 'Encode Transaction Raw (encodeTransactionRaw)');

  const encodedRaw = encodeTransactionRaw(txWithFee);
  printInfo(`Raw encoded bytes length: ${encodedRaw.length} bytes`);
  printInfo(`First bytes (hex): ${bytesToHex(encodedRaw, 40)}`);
  printInfo('');
  printInfo(
    `Difference in length: ${encodedWithPrefix.length - encodedRaw.length} bytes (TX prefix)`,
  );
  printInfo('Use encodeTransactionRaw() when the signing tool adds its own prefix.');

  // Step 6: Use decodeTransaction() to reconstruct from bytes
  printStep(6, 'Decode Transaction (decodeTransaction)');

  // Decode from bytes with prefix
  const decodedFromPrefix = decodeTransaction(encodedWithPrefix);
  printInfo('Decoded from bytes with TX prefix:');
  printInfo(`  Type: ${decodedFromPrefix.type}`);
  printInfo(`  Sender: ${shortenAddress(decodedFromPrefix.sender.toString())}`);
  printInfo(`  Amount: ${decodedFromPrefix.payment?.amount} microALGO`);
  printInfo(`  Fee: ${decodedFromPrefix.fee} microALGO`);

  // Decode from raw bytes (without prefix)
  const decodedFromRaw = decodeTransaction(encodedRaw);
  printInfo('');
  printInfo('Decoded from raw bytes (without prefix):');
  printInfo(`  Type: ${decodedFromRaw.type}`);
  printInfo(`  Sender: ${shortenAddress(decodedFromRaw.sender.toString())}`);
  printInfo(`  Amount: ${decodedFromRaw.payment?.amount} microALGO`);
  printInfo('');
  printInfo('Note: decodeTransaction() auto-detects and handles both formats.');

  // Step 7: Verify decoded transaction matches original
  printStep(7, 'Verify Decoded Transaction Matches Original');

  const matchesOriginal = compareTransactions(txWithFee, decodedFromPrefix);
  if (matchesOriginal) {
    printSuccess('Decoded transaction matches original!');
  } else {
    printInfo('Warning: Decoded transaction differs from original');
  }

  printInfo('');
  printInfo('Field comparison:');
  printInfo(`  Type: ${txWithFee.type} === ${decodedFromPrefix.type} ✓`);
  printInfo(
    `  Sender: ${txWithFee.sender.toString() === decodedFromPrefix.sender.toString() ? '✓' : '✗'}`,
  );
  printInfo(
    `  Receiver: ${txWithFee.payment?.receiver.toString() === decodedFromPrefix.payment?.receiver.toString() ? '✓' : '✗'}`,
  );
  printInfo(
    `  Amount: ${txWithFee.payment?.amount === decodedFromPrefix.payment?.amount ? '✓' : '✗'}`,
  );
  printInfo(`  Fee: ${txWithFee.fee === decodedFromPrefix.fee ? '✓' : '✗'}`);
  printInfo(`  First valid: ${txWithFee.firstValid === decodedFromPrefix.firstValid ? '✓' : '✗'}`);
  printInfo(`  Last valid: ${txWithFee.lastValid === decodedFromPrefix.lastValid ? '✓' : '✗'}`);

  // Step 8: Demonstrate encodeSignedTransaction() and decodeSignedTransaction()
  printStep(8, 'Encode and Decode Signed Transaction');

  // Sign the transaction
  const signedTxBytes = await sender.signer([txWithFee], [0]);
  printInfo(`Signed transaction bytes length: ${signedTxBytes[0].length} bytes`);

  // Decode the signed transaction
  const decodedSignedTx = decodeSignedTransaction(signedTxBytes[0]);
  printInfo('');
  printInfo('Decoded SignedTransaction structure:');
  printInfo(`  txn.type: ${decodedSignedTx.txn.type}`);
  printInfo(`  txn.sender: ${shortenAddress(decodedSignedTx.txn.sender.toString())}`);
  printInfo(`  sig length: ${decodedSignedTx.sig?.length ?? 0} bytes (ed25519 signature)`);

  // Re-encode the signed transaction
  const reEncodedSignedTx = encodeSignedTransaction(decodedSignedTx);
  printInfo('');
  printInfo('Re-encoded signed transaction:');
  printInfo(`  Length: ${reEncodedSignedTx.length} bytes`);

  // Verify re-encoded matches original
  let signedBytesMatch = reEncodedSignedTx.length === signedTxBytes[0].length;
  if (signedBytesMatch) {
    for (let i = 0; i < reEncodedSignedTx.length; i++) {
      if (reEncodedSignedTx[i] !== signedTxBytes[0][i]) {
        signedBytesMatch = false;
        break;
      }
    }
  }

  if (signedBytesMatch) {
    printSuccess('Re-encoded signed transaction matches original!');
  } else {
    printInfo('Re-encoded signed transaction differs (may be due to canonicalization)');
  }

  // Step 9: Show transaction ID calculation using txId()
  printStep(9, 'Calculate Transaction ID (txId)');

  const txId = txWithFee.txId();
  printInfo(`Transaction ID: ${txId}`);
  printInfo('');
  printInfo('Transaction ID calculation:');
  printInfo('  1. Encode transaction with TX prefix');
  printInfo('  2. Hash the bytes using SHA-512/256');
  printInfo('  3. Base32 encode the hash (first 52 characters)');
  printInfo('');
  printInfo(`ID length: ${txId.length} characters`);

  // Verify the decoded transaction has the same ID
  const decodedTxId = decodedFromPrefix.txId();
  if (txId === decodedTxId) {
    printSuccess('Decoded transaction has same ID as original!');
  } else {
    printInfo('Warning: Transaction IDs differ');
  }

  // Step 10: Demonstrate round-trip encoding with SignedTransaction structure
  printStep(10, 'Create and Encode SignedTransaction Manually');

  // Create a SignedTransaction structure manually (for demonstration)
  const manualSignedTx: SignedTransaction = {
    txn: txWithFee,
    sig: decodedSignedTx.sig, // Reuse the signature from earlier
  };

  const manualEncodedSignedTx = encodeSignedTransaction(manualSignedTx);
  printInfo(`Manually created SignedTransaction encoded: ${manualEncodedSignedTx.length} bytes`);

  const manualDecodedSignedTx = decodeSignedTransaction(manualEncodedSignedTx);
  printInfo(
    `Decoded back: txn.type=${manualDecodedSignedTx.txn.type}, sig present=${!!manualDecodedSignedTx.sig}`,
  );

  // Summary
  printStep(11, 'Summary');
  printInfo('');
  printInfo('Encoding functions:');
  printInfo('  encodeTransaction(tx)     - Returns msgpack bytes WITH "TX" prefix');
  printInfo('  encodeTransactionRaw(tx)  - Returns msgpack bytes WITHOUT prefix');
  printInfo('  encodeSignedTransaction() - Encodes signed transaction for network');
  printInfo('');
  printInfo('Decoding functions:');
  printInfo('  decodeTransaction(bytes)       - Decodes bytes to Transaction');
  printInfo('                                   (auto-detects prefix)');
  printInfo('  decodeSignedTransaction(bytes) - Decodes bytes to SignedTransaction');
  printInfo('');
  printInfo('Other utilities:');
  printInfo('  tx.txId() - Calculate transaction ID (hash of encoded bytes)');
  printInfo('');
  printInfo('Use cases:');
  printInfo('  - Serialize transactions for storage or transmission');
  printInfo('  - Deserialize transactions received from external sources');
  printInfo('  - Calculate transaction IDs for tracking and verification');
  printInfo('  - Inspect signed transactions to verify signature presence');

  printSuccess('Encoding/Decoding example completed!');
}

main().catch(error => {
  console.error('Error:', error);
  process.exit(1);
});

---

Other examples in Transactions

• Payment Transaction
• Payment with Close
• Asset Create
• Asset Transfer
• Asset Freeze
• Asset Clawback
• Atomic Transaction Group
• Atomic Swap
• Single Signature
• Multisig
• Logic Signature
• Fee Calculation
• Encoding/Decoding
• Application Call