Skip to content

About

TypeScript SDK for composing multiple Aptos Move entry-function calls into one atomic script transaction. Supports single-signer, multi-signer, and fee-payer flows.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

Aptos Script Composer SDK

CI npm

Compose multiple Aptos Move entry-function calls into one script transaction. The SDK builds on @aptos-labs/ts-sdk and @aptos-labs/script-composer-pack (WASM), and supports single-signer, multi-agent, and fee-payer transactions.

For the official Aptos guide, see Invoke chains of Move calls with Dynamic Script Composer.

Why use it?

A transaction normally invokes one entry function. Script Composer lets an application describe several compatible calls, including calls that consume values returned by earlier calls, and execute them atomically in one Aptos transaction.

Install

pnpm add @aptos-labs/script-composer-sdk @aptos-labs/ts-sdk @aptos-labs/script-composer-pack

The SDK supports @aptos-labs/ts-sdk major versions 3 through 7. Use Node.js 22 or a current LTS release for this repository and its examples.

Browser applications also need the buffer peer dependency and a global polyfill before initializing the SDK:

pnpm add buffer
import { Buffer } from 'buffer';

(window as typeof window & { Buffer: typeof Buffer }).Buffer = Buffer;

The React and Next.js examples in this repository follow this pattern.

Quick start

This example builds a transaction that transfers APT on Testnet. By default, the composer fetches the Move ABI and bytecode it needs from the configured network. Building a transaction does not sign or submit it.

import { Aptos, AptosConfig, Network } from '@aptos-labs/ts-sdk';
import { BuildScriptComposerTransaction, CallArgument } from '@aptos-labs/script-composer-sdk';

const config = new AptosConfig({ network: Network.TESTNET });
const sender = '0x...';
const recipient = '0x...';

const transaction = await BuildScriptComposerTransaction({
  sender,
  aptosConfig: config,
  builder: async (composer) => {
    await composer.addBatchedCalls({
      function: '0x1::aptos_account::transfer',
      functionArguments: [CallArgument.newSigner(0), recipient, 1_000],
    });
    return composer;
  },
});

// Safe for a quick integration check; no transaction is submitted.
const result = await new Aptos(config).transaction.simulate.simple({ transaction });
console.log(result);

To submit a transaction, sign the returned transaction with the appropriate accounts using @aptos-labs/ts-sdk, then submit the resulting authenticator. See the Aptos TypeScript SDK documentation for account management and signing APIs.

Core concepts

Automatic and manual module loading

addBatchedCalls uses allowFetch: true by default. The composer fetches missing Move module ABI and bytecode from the configured full node, which is convenient for connected applications.

For offline or controlled environments, set options.allowFetch to false and provide both moduleAbi and moduleBytecodes. You can also preload modules with getModuleInner and composer.storeModule as shown in the Node example.

Generic Move functions and typeArguments

When a Move entry function is generic, pass concrete type tags through typeArguments. The composer also loads any modules required by those type tags:

await composer.addBatchedCalls({
  function: '0x1::coin::transfer',
  typeArguments: ['0x1::aptos_coin::AptosCoin'],
  functionArguments: [CallArgument.newSigner(0), recipient, 1_000],
});

Connecting calls with returned values

addBatchedCalls returns CallArgument[]. Pass a returned item into a later call's functionArguments to compose dependent operations without leaving the transaction:

const [createdObject] = await composer.addBatchedCalls({ /* first call */ });
await composer.addBatchedCalls({
  function: '0x...::module::consume',
  functionArguments: [createdObject],
});

Move ability rules still apply at composition time. Values without drop must be consumed by a later call, and values without copy can only be forwarded once. See the official Script Composer guide for examples.

Signers, multi-agent transactions, and fee payers

  • CallArgument.newSigner(0) refers to the primary sender. Secondary signers are indexed starting at 1.
  • Use BuildScriptComposerTransaction for a normal, single-signer transaction.
  • Use BuildScriptComposerMultiAgentTransaction when calls require secondary signers and/or a fee payer. It returns a transaction that each required account must sign before submission.
  • For a sponsored transaction with only the primary sender and no secondary signers, you can also pass withFeePayer: true to BuildScriptComposerTransaction.
  • A fee payer pays gas; it is not an additional Move-function signer unless the Move call itself requires one.

Simulating before submission

  • Single-signer transactions: aptos.transaction.simulate.simple({ transaction })
  • Multi-agent transactions: aptos.transaction.simulate.multiAgent({ transaction, ... }) with the public keys for each required signer

Examples

Example Demonstrates Run from repository root
Node.js Auto-fetch and preloaded-module composition, then simulation on Testnet pnpm --filter example-nodejs start
Multi-agent Node.js Secondary signers and fee-payer transaction construction pnpm --filter example-multi-agent-nodejs start
React Browser UI for composing and simulating transactions pnpm --filter react-project dev
Next.js Browser UI including multi-agent flows pnpm --filter nextjs-project dev

Examples construct or simulate transactions only unless their documentation explicitly says otherwise. Review function arguments, account addresses, and network configuration before adapting an example to submit real transactions.

Development

git clone https://github.com/aptos-labs/script-composer-sdk.git
cd script-composer-sdk
pnpm install
pnpm build
pnpm test

The repository is a pnpm workspace. SDK source is in packages/sdk; runnable applications live under examples.

Releases

This project uses Changesets. Changes that affect the published SDK should include a changeset:

pnpm changeset

Merging changesets to main creates or updates a version PR; merging that PR publishes the package through .github/workflows/release.yml.

Maintainers: configure the GitHub App (APTOS_LABS_BOT_APP_ID, APTOS_LABS_BOT_APP_PRIVATE_KEY) and npm Trusted Publisher for that workflow before the first automated release.

Support and security

For defects and feature requests, open a GitHub issue. Do not report security vulnerabilities in a public issue; follow Aptos Labs' security reporting process instead.

About

TypeScript SDK for composing multiple Aptos Move entry-function calls into one atomic script transaction. Supports single-signer, multi-signer, and fee-payer flows.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages