Skip to main content

Your First Transaction

This tutorial describes how to generate and submit transactions to the Aptos blockchain, and verify these submitted transactions. The transfer-coin example used in this tutorial is built with the Aptos SDKs.

Step 1: Pick an SDK​

Install your preferred SDK from the below list:

Step 2: Run the example​

Clone the @aptos-labs/ts-sdk repo:

git clone https://github.com/aptos-labs/aptos-ts-sdk.git

Navigate to the Typescript SDK examples directory:

cd aptos-ts-sdk/examples/typescript

Install the necessary dependencies:

pnpm install

Run the transfer_coin example:

pnpm run transfer_coin

Step 3: Understand the output​

An output very similar to the following will appear after executing the above command:

=== Addresses ===

Alice's address is: 0xbd20517751571ba3fd06326c23761bc0bc69cf450898ffb43412fbe670c28806
Bob's address is: 0x8705f98a74f5efe17740276ed75031927402c3a965e10f2ee16cda46d99d8f7f

=== Initial Balances ===

Alice's balance is: 100000000
Bob's balance is: 0

=== Transfer 1000000 from Alice to Bob ===

Committed transaction: 0xc0d348afdfc34ae2c48971b253ece727cc9980dde182e2f2c42834552cbbf04c

=== Balances after transfer ===

Alice's balance is: 98899100
Bob's balance is: 1000000

The above output demonstrates that the transfer-coin example executes the following steps:

  • Initializing the Aptos client.
  • The creation of two accounts: Alice and Bob.
  • The funding and creation of Alice's account from a faucet.
  • The transferring of 1000000 coins from Alice to Bob.
  • The 1100900 coins of gas paid for by Alice to make that transfer.

Step 4: The SDK in depth​

The transfer-coin example code uses helper functions to interact with the REST API. This section reviews each of the calls and gives insights into functionality.

See the full code

See the TypeScript transfer_coin for the complete code as you follow the below steps.

Step 4.1: Initializing the clients​

In the first step, the transfer_coin example initializes the Aptos client:

const APTOS_NETWORK: Network =
  NetworkToNetworkName[process.env.APTOS_NETWORK] || Network.DEVNET;
const config = new AptosConfig({ network: APTOS_NETWORK });
const aptos = new Aptos(config);
tip

By default, the Aptos client points to Aptos devnet services. However, it can be configured with the network input argument

Step 4.2: Creating local accounts​

The next step is to create two accounts locally. Accounts represent both on and off-chain state. Off-chain state consists of an address and the public/private key pair used to authenticate ownership. This step demonstrates how to generate that off-chain state.

const alice = Account.generate();
const bob = Account.generate();

Step 4.3: Creating blockchain accounts​

In Aptos, each account must have an on-chain representation in order to receive tokens and coins and interact with other dApps. An account represents a medium for storing assets; hence, it must be explicitly created. This example leverages the Faucet to create and fund Alice's account and to create but not fund Bob's account:

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

Step 4.4: Reading balances​

In this step, the SDK translates a single call into the process of querying a resource and reading a field from that resource.

const aliceBalance = await balance("Alice", alice.accountAddress);
const bobBalance = await balance("Bob", bob.accountAddress);

Behind the scenes, the balance function uses the SDK getAccountAPTAmount function that queries the Indexer service and reads the current stored value:

const balance = async (
  name: string,
  accountAddress: AccountAddress,
): Promise<number> => {
  const amount = await aptos.getAccountAPTAmount({
    accountAddress,
  });
  console.log(`${name}'s balance is: ${amount}`);
  return amount;
};

Step 4.5: Transferring​

Like the previous step, this is another helper step that constructs a transaction transferring the coins from Alice to Bob. The SDK provides a helper function to generate a transferCoinTransaction transaction that can be simulated or submitted to chain. Once a transaction has been submitted to chain, the API will return a transaction hash that can be used in the subsequent step to check on the transaction status. The Aptos blockchain does perform a handful of validation checks on submission; and if any of those fail, the user will instead be given an error. These validations use the transaction signature and unused sequence number, and submitting the transaction to the appropriate chain.

const transaction = await aptos.transferCoinTransaction({
  sender: alice,
  recipient: bob.accountAddress,
  amount: TRANSFER_AMOUNT,
});
const pendingTxn = await aptos.signAndSubmitTransaction({
  signer: alice,
  transaction,
});

Behind the scenes, the transferCoinTransaction function generates a transaction payload that can be simulated or submitted to chain:

export async function transferCoinTransaction(args: {
  aptosConfig: AptosConfig;
  sender: Account;
  recipient: AccountAddressInput;
  amount: AnyNumber;
  coinType?: MoveStructId;
  options?: InputGenerateTransactionOptions;
}): Promise<SingleSignerTransaction> {
  const { aptosConfig, sender, recipient, amount, coinType, options } = args;
  const coinStructType = coinType ?? APTOS_COIN;
  const transaction = await generateTransaction({
    aptosConfig,
    sender: sender.accountAddress,
    data: {
      function: "0x1::aptos_account::transfer_coins",
      typeArguments: [coinStructType],
      functionArguments: [recipient, amount],
    },
    options,
  });

  return transaction;
}

Breaking the above down into pieces:

  1. transfer_coins internally is a EntryFunction in the Aptos Account Move module, i.e. an entry function in Move that is directly callable.
  2. The Move function is stored on the aptos_account module: 0x1::aptos_account.
  3. The transfer_coins functions uses the Coin Move module
  4. Because the Coin module can be used by other coins, the transferCoinTransaction must explicitly specify which coin type to transfer. If not specified with coinType it defaults to 0x1::aptos_coin::AptosCoin.

Step 4.6: Waiting for transaction resolution​

In the TypeScript SDK, just calling waitForTransaction is sufficient to wait for the transaction to complete. The function will return the Transaction returned by the API once it is processed (either successfully or unsuccessfully) or throw an error if processing time exceeds the timeout.

const response = await aptos.waitForTransaction({
  transactionHash: pendingTxn.hash,
});

Supporting documentation​