@aptos-labs/ts-sdk - v5.1.4
    Preparing search index...

    Class Transaction

    Represents a transaction in the Aptos blockchain, providing methods to build, simulate, submit, and manage transactions. This class encapsulates functionalities for querying transaction details, estimating gas prices, signing transactions, and handling transaction states.

    This class is used as part of the Aptos object, so should be called like so:

    import { Account, Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

    const APTOS_COIN = "0x1::aptos_coin::AptosCoin";
    const COIN_STORE = `0x1::coin::CoinStore<${APTOS_COIN}>`;
    const ALICE_INITIAL_BALANCE = 100_000_000;
    const TRANSFER_AMOUNT = 100;

    async function example() {
    console.log(
    "This example will create two accounts (Alice and Bob), fund them, and transfer between them.",
    );

    // Set up the client
    const config = new AptosConfig({ network: Network.DEVNET });
    const aptos = new Aptos(config);

    // Generate two account credentials
    // Each account has a private key, a public key, and an address
    const alice = Account.generate();
    const bob = Account.generate();

    console.log("=== Addresses ===\n");
    console.log(`Alice's address is: ${alice.accountAddress}`);
    console.log(`Bob's address is: ${bob.accountAddress}`);

    // Fund the accounts using a faucet
    console.log("\n=== Funding accounts ===\n");

    await aptos.fundAccount({
    accountAddress: alice.accountAddress,
    amount: ALICE_INITIAL_BALANCE,
    });

    // Send a transaction from Alice's account to Bob's account
    const txn = await aptos.transaction.build.simple({
    sender: alice.accountAddress,
    data: {
    // All transactions on Aptos are implemented via smart contracts.
    function: "0x1::aptos_account::transfer",
    functionArguments: [bob.accountAddress, 100],
    },
    });

    console.log("\n=== Transfer transaction ===\n");
    // Both signs and submits
    const committedTxn = await aptos.signAndSubmitTransaction({
    signer: alice,
    transaction: txn,
    });
    // Waits for Aptos to verify and execute the transaction
    const executedTransaction = await aptos.waitForTransaction({
    transactionHash: committedTxn.hash,
    });
    console.log("Transaction hash:", executedTransaction.hash);

    console.log("\n=== Balances after transfer ===\n");
    const newAliceAccountBalance = await aptos.getAccountResource({
    accountAddress: alice.accountAddress,
    resourceType: COIN_STORE,
    });
    const newAliceBalance = Number(newAliceAccountBalance.coin.value);
    console.log(`Alice's balance is: ${newAliceBalance}`);

    const newBobAccountBalance = await aptos.getAccountResource({
    accountAddress: bob.accountAddress,
    resourceType: COIN_STORE,
    });
    const newBobBalance = Number(newBobAccountBalance.coin.value);
    console.log(`Bob's balance is: ${newBobBalance}`);
    }

    example();
    Index

    Properties

    build: Build
    config: AptosConfig
    simulate: Simulate
    submit: Submit

    Transaction

    • Creates an instance of the Aptos client with the specified configuration. This allows you to interact with the Aptos blockchain using the provided settings.

      Parameters

      • config: AptosConfig

        The configuration settings for the Aptos client.

      Returns Transaction

      import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

      async function runExample() {
      // Create a new Aptos client instance
      const config = new AptosConfig({ network: Network.TESTNET }); // Specify the network
      const aptos = new Aptos(config);

      console.log("Aptos client created successfully:", aptos);
      }
      runExample().catch(console.error);
    • Parameters

      Returns Promise<void>

      Prefer to use aptos.transaction.batch.forSingleAccount()

      Batch transactions for a single account by submitting multiple transaction payloads. This function is useful for efficiently processing and submitting transactions that do not depend on each other, such as batch funding or batch token minting.

      Error if any worker failure occurs during submission.

      import { Aptos, AptosConfig, Network, Account } from "@aptos-labs/ts-sdk";

      const config = new AptosConfig({ network: Network.TESTNET });
      const aptos = new Aptos(config);
      const sender = Account.generate(); // Generate a new account for sending transactions

      async function runExample() {
      const transactions = [
      { }, // Build your first transaction payload
      { }, // Build your second transaction payload
      ];

      // Batch transactions for the single account
      await aptos.batchTransactionsForSingleAccount({
      sender,
      data: transactions,
      });

      console.log("Batch transactions submitted successfully.");
      }
      runExample().catch(console.error);
    • Estimates the gas unit price required to process a transaction on the Aptos blockchain in a timely manner. This helps users to understand the cost associated with their transactions. https://api.mainnet.aptoslabs.com/v1/spec#/operations/estimate_gas_price

      Returns Promise<GasEstimation>

      An object containing the estimated gas price.

      import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

      const config = new AptosConfig({ network: Network.TESTNET }); // Specify your network
      const aptos = new Aptos(config);

      async function runExample() {
      // Getting the gas price estimation
      const gasPriceEstimation = await aptos.getGasPriceEstimation();

      console.log("Estimated Gas Price:", gasPriceEstimation);
      }
      runExample().catch(console.error);
    • Returns a signing message for a transaction, allowing a user to sign it using their preferred method before submission to the network.

      Parameters

      Returns Uint8Array

      import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

      const config = new AptosConfig({ network: Network.TESTNET });
      const aptos = new Aptos(config);

      async function runExample() {
      const transaction = await aptos.transaction.build.simple({
      sender: "0x1", // replace with a real sender address
      data: {
      function: "0x1::aptos_account::transfer",
      functionArguments: ["0x2", 100], // replace with a real destination address
      },
      });

      const message = await aptos.getSigningMessage({ transaction });
      console.log(message);
      }
      runExample().catch(console.error);
    • Queries on-chain transactions by their transaction hash, returning both pending and committed transactions.

      Parameters

      • args: { transactionHash: HexInput }

        The arguments for querying the transaction.

        • transactionHash: HexInput

          The transaction hash should be a hex-encoded bytes string with a 0x prefix.

      Returns Promise<TransactionResponse>

      The transaction from the mempool (pending) or the on-chain (committed) transaction.

      import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

      const config = new AptosConfig({ network: Network.TESTNET });
      const aptos = new Aptos(config);

      async function runExample() {
      // Fetch a transaction by its hash
      const transaction = await aptos.getTransactionByHash({ transactionHash: "0x123" }); // replace with a real transaction hash

      console.log(transaction);
      }
      runExample().catch(console.error);
    • Queries on-chain transaction by version. This function will not return pending transactions.

      Parameters

      • args: { ledgerVersion: AnyNumber }

        The arguments for querying the transaction.

        • ledgerVersion: AnyNumber

          Transaction version is an unsigned 64-bit number.

      Returns Promise<TransactionResponse>

      On-chain transaction. Only on-chain transactions have versions, so this function cannot be used to query pending transactions.

      import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

      const config = new AptosConfig({ network: Network.TESTNET });
      const aptos = new Aptos(config);

      async function runExample() {
      // Fetching a transaction by its version
      const transaction = await aptos.getTransactionByVersion({ ledgerVersion: 1 }); // replace 1 with a real version
      console.log(transaction);
      }
      runExample().catch(console.error);
    • Queries on-chain transactions, excluding pending transactions. Use this function to retrieve historical transactions from the blockchain.

      Parameters

      Returns Promise<TransactionResponse[]>

      An array of on-chain transactions.

      import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

      const config = new AptosConfig({ network: Network.TESTNET });
      const aptos = new Aptos(config);

      async function runExample() {
      // Fetch transactions with pagination
      const transactions = await aptos.getTransactions({
      options: {
      offset: 0, // Start from the first transaction
      limit: 10, // Limit to 10 results
      },
      });

      console.log(transactions);
      }
      runExample().catch(console.error);
    • Defines if the specified transaction is currently in a pending state. This function helps you determine the status of a transaction using its hash.

      Parameters

      • args: { transactionHash: HexInput }

        The arguments for the function.

        • transactionHash: HexInput

          A hash of the transaction in hexadecimal format.

      Returns Promise<boolean>

      true if the transaction is in a pending state and false otherwise.

      import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

      const config = new AptosConfig({ network: Network.TESTNET });
      const aptos = new Aptos(config);

      async function runExample() {
      // Check if the transaction is pending using its hash
      const isPendingTransaction = await aptos.isPendingTransaction({ transactionHash: "0x123" }); // replace with a real transaction hash
      console.log("Is the transaction pending?", isPendingTransaction);
      }
      runExample().catch(console.error);
    • Generates a transaction to publish a Move package to the blockchain. This function helps you create a transaction that can be simulated or submitted to the chain for publishing a package.

      To get the metadataBytes and byteCode, can compile using Aptos CLI with command aptos move compile --save-metadata ...,

      https://aptos.dev/tutorials/your-first-dapp/#step-4-publish-a-move-module

      Parameters

      Returns Promise<SimpleTransaction>

      A SimpleTransaction that can be simulated or submitted to the chain.

      import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

      const config = new AptosConfig({ network: Network.TESTNET });
      const aptos = new Aptos(config);

      async function runExample() {
      // Replace with a real account address
      const account = "0x1";
      const metadataBytes = "0x..."; // replace with real metadata bytes
      const byteCode = "0x..."; // replace with real module bytecode

      const transaction = await aptos.publishPackageTransaction({
      account,
      metadataBytes,
      moduleBytecode: [byteCode],
      });

      console.log(transaction);
      }
      runExample().catch(console.error);
    • Rotates the authentication key for a given account. Once an account is rotated, only the new private key or keyless signing scheme can be used to sign transactions for the account.

      Parameters

      Returns Promise<SimpleTransaction>

      SimpleTransaction that can be submitted to rotate the auth key

      This function supports three modes of rotation:

      1. Using a target Account object (toAccount)
      2. Using a new private key (toNewPrivateKey)

      For Ed25519 accounts, the function will use a challenge-based rotation that requires signatures from both the old and new keys. For multi-key accounts like MultiEd25519Account, the function will use a challenge-based rotation that requires signatures from both keys. For other account types, the function will use an unverified rotation that only requires the new public key.

      // Create and submit transaction to rotate the auth key
      const transaction = await aptos.rotateAuthKey({
      fromAccount,
      toAccount: toAccount,
      });

      // Sign and submit the transaction
      const pendingTransaction = await aptos.signAndSubmitTransaction({
      signer: fromAccount,
      transaction,
      });
    • Rotates the authentication key for a given account without verifying the new key.

      Accounts with their auth key rotated via this function will be derivable via the getAccountsForPublicKey and deriveOwnedAccountsFromSigner functions however the public key will be unverified (no proof of ownership). Thus includeUnverified must be set to true to derive the account until the public key is verified via signing a transaction.

      Parameters

      Returns Promise<SimpleTransaction>

      A simple transaction object that can be submitted to the network.

      // Create and submit transaction to rotate the auth key
      const transaction = await aptos.rotateAuthKeyUnverified({
      fromAccount,
      toNewPublicKey,
      });

      // Sign and submit the transaction
      const pendingTransaction = await aptos.signAndSubmitTransaction({
      signer: fromAccount,
      transaction,
      });
    • Sign a transaction that can later be submitted to the chain. This function is essential for ensuring the authenticity of the transaction by using the provided account's signing capabilities.

      Parameters

      Returns AccountAuthenticator

      AccountAuthenticator - The authenticator for the signed transaction.

      import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

      const config = new AptosConfig({ network: Network.TESTNET });
      const aptos = new Aptos(config);

      async function runExample() {
      const sender = Account.generate(); // Generate a new account for signing
      const transaction = await aptos.transaction.build.simple({
      sender: sender.accountAddress,
      data: {
      function: "0x1::aptos_account::transfer",
      functionArguments: [ "0x1", 100 ], // replace with a real account address and amount
      },
      });

      const signedTransaction = await aptos.transaction.sign({
      signer: sender,
      transaction,
      }); // Sign the transaction

      console.log("Signed Transaction:", signedTransaction);
      }
      runExample().catch(console.error);
    • Sign and submit a single signer transaction to the blockchain. This function allows you to execute a transaction after signing it with the specified account.

      Parameters

      Returns Promise<PendingTransactionResponse>

      PendingTransactionResponse

      import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

      const config = new AptosConfig({ network: Network.TESTNET });
      const aptos = new Aptos(config);

      async function runExample() {
      const sender = Account.generate(); // Generate a new account for sending the transaction
      const transaction = await aptos.transaction.build.simple({
      sender: sender.accountAddress,
      data: {
      function: "0x1::aptos_account::transfer",
      functionArguments: [ "0x1", 100 ], // replace with a real account address
      },
      });

      // Sign and submit the transaction
      const pendingTransaction = await aptos.signAndSubmitTransaction({
      signer: sender,
      transaction,
      });

      console.log(pendingTransaction);
      }
      runExample().catch(console.error);
    • Sign a transaction as a fee payer that can later be submitted to the chain. This function ensures that the transaction is marked with the fee payer's address, allowing it to be processed correctly.

      Parameters

      • args: { signer: Account; transaction: AnyRawTransaction }

        The arguments for signing the transaction.

        • signer: Account

          The fee payer signer account.

        • transaction: AnyRawTransaction

          A raw transaction to sign on. This transaction must include a feePayerAddress property.

      Returns AccountAuthenticator

      AccountAuthenticator - The authenticator for the signed transaction.

      import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

      const config = new AptosConfig({ network: Network.TESTNET });
      const aptos = new Aptos(config);

      async function runExample() {
      const sender = Account.generate(); // Generate a new account for the fee payer
      const transaction = await aptos.transaction.build.simple({
      // All transactions on Aptos are implemented via smart contracts.
      function: "0x1::aptos_account::transfer",
      functionArguments: [sender.accountAddress, 100],
      feePayerAddress: sender.accountAddress, // Set the fee payer address
      });

      const signedTransaction = await aptos.transaction.signAsFeePayer({
      signer: sender,
      transaction,
      });

      console.log("Signed transaction as fee payer:", signedTransaction);
      }
      runExample().catch(console.error);
    • Waits for a transaction to move past the pending state and provides the transaction response. There are 4 cases.

      1. Transaction is successfully processed and committed to the chain.
        • The function will resolve with the transaction response from the API.
      2. Transaction is rejected for some reason, and is therefore not committed to the blockchain.
        • The function will throw an AptosApiError with an HTTP status code indicating some problem with the request.
      3. Transaction is committed but execution failed, meaning no changes were written to the blockchain state.
        • If checkSuccess is true, the function will throw a FailedTransactionError If checkSuccess is false, the function will resolve with the transaction response where the success field is false.
      4. Transaction does not move past the pending state within args.options.timeoutSecs seconds.
        • The function will throw a WaitForTransactionError

      Parameters

      Returns Promise<CommittedTransactionResponse>

      The transaction on-chain response.

      import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

      const config = new AptosConfig({ network: Network.TESTNET });
      const aptos = new Aptos(config);

      async function runExample() {
      // Wait for a transaction to complete using its hash
      const transactionHash = "0x123"; // replace with a real transaction hash
      const transactionResponse = await aptos.waitForTransaction({
      transactionHash,
      options: {
      timeoutSecs: 30, // specify your own timeout if needed
      checkSuccess: true,
      },
      });

      console.log(transactionResponse);
      }
      runExample().catch(console.error);