ts-sdk-transactions

TypeScript SDK：交易

目的

介绍如何使用 @aptos-labs/ts-sdk 构建、签名、提交和模拟交易。采用构建 → 签名 → 提交 → 等待的模式；也可以选择在提交前进行模拟。

务必

1. 提交后调用 aptos.waitForTransaction({ transactionHash })——不要认为调用 signAndSubmitTransaction 后交易就已提交。
2. 对入口函数载荷使用 aptos.transaction.build.simple()——传入 sender 和 data: { function, functionArguments, typeArguments? }。
3. 对关键或高价值流程，在提交前进行模拟——使用 aptos.transaction.simulate.simple() 并检查 success 和 vm_status。
4. 构建时，将同一个 Account 实例用于签名者，并将其用于 sender 地址（例如，将 account.accountAddress 用作 sender，将 account 用作签名者）。

切勿

1. 不要跳过 waitForTransaction——交易被接受时就会返回，不代表交易已提交。
2. 不要使用已弃用的 scriptComposer（已在 v6 中移除）——请使用独立交易或批处理模式。
3. 不要在 functionArguments 中使用 number 表示 u64/u128/u256——需要时请使用 bigint，以避免精度 损失。

---

标准流程（简单交易）

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

const aptos = new Aptos(new AptosConfig({ network: Network.TESTNET }));
const MODULE_ADDRESS = "0x...";

// 1. Build
const transaction = await aptos.transaction.build.simple({
  sender: account.accountAddress,
  data: {
    function: `${MODULE_ADDRESS}::counter::increment`,
    functionArguments: []
  }
});

// 2. Sign and submit
const pendingTx = await aptos.signAndSubmitTransaction({
  signer: account,
  transaction
});

// 3. Wait for commitment
const committedTx = await aptos.waitForTransaction({
  transactionHash: pendingTx.hash
});

if (!committedTx.success) {
  throw new Error(`Tx failed: ${committedTx.vm_status}`);
}

---

构建选项

// With type arguments (e.g. coin type)
const transaction = await aptos.transaction.build.simple({
  sender: account.accountAddress,
  data: {
    function: "0x1::coin::transfer",
    typeArguments: ["0x1::aptos_coin::AptosCoin"],
    functionArguments: [recipientAddress, amount]
  }
});

// Optional: max gas, expiry, etc. (see SDK types for full options)
const transactionWithOptions = await aptos.transaction.build.simple({
  sender: account.accountAddress,
  data: { function: "...", functionArguments: [] },
  options: {
    maxGasAmount: 2000n,
    gasUnitPrice: 100n,
    expireTimestamp: BigInt(Math.floor(Date.now() / 1000) + 600)
  }
});

---

模拟（提交前）

const transaction = await aptos.transaction.build.simple({
  sender: account.accountAddress,
  data: {
    function: `${MODULE_ADDRESS}::counter::increment`,
    functionArguments: []
  }
});

const [simResult] = await aptos.transaction.simulate.simple({
  signerPublicKey: account.publicKey,
  transaction
});

if (!simResult.success) {
  throw new Error(`Simulation failed: ${simResult.vm_status}`);
}
console.log("Gas used:", simResult.gas_used);

---

赞助交易（费用支付方）

// 1. Build with fee payer
const transaction = await aptos.transaction.build.simple({
  sender: sender.accountAddress,
  withFeePayer: true,
  data: {
    function: `${MODULE_ADDRESS}::counter::increment`,
    functionArguments: []
  }
});

// 2. Sender signs
const senderAuth = aptos.transaction.sign({
  signer: sender,
  transaction
});

// 3. Fee payer signs (different method)
const feePayerAuth = aptos.transaction.signAsFeePayer({
  signer: feePayer,
  transaction
});

// 4. Submit with both authenticators
const pendingTx = await aptos.transaction.submit.simple({
  transaction,
  senderAuthenticator: senderAuth,
  feePayerAuthenticator: feePayerAuth
});

await aptos.waitForTransaction({ transactionHash: pendingTx.hash });

---

多 Agent 交易

const transaction = await aptos.transaction.build.multiAgent({
  sender: alice.accountAddress,
  secondarySignerAddresses: [bob.accountAddress],
  data: {
    function: `${MODULE_ADDRESS}::escrow::exchange`,
    functionArguments: [itemAddress, amount]
  }
});

const aliceAuth = aptos.transaction.sign({ signer: alice, transaction });
const bobAuth = aptos.transaction.sign({ signer: bob, transaction });

const pendingTx = await aptos.transaction.submit.multiAgent({
  transaction,
  senderAuthenticator: aliceAuth,
  additionalSignersAuthenticators: [bobAuth]
});

await aptos.waitForTransaction({ transactionHash: pendingTx.hash });

---

waitForTransaction 选项

const committed = await aptos.waitForTransaction({
  transactionHash: pendingTx.hash,
  options: {
    timeoutSecs: 60,
    checkSuccess: true // throw if tx failed
  }
});

---

Gas 配置分析

const gasProfile = await aptos.gasProfile({
  sender: account.accountAddress,
  data: {
    function: `${MODULE_ADDRESS}::module::function_name`,
    functionArguments: []
  }
});
console.log("Gas profile:", gasProfile);

---

常见错误

错误	正确做法
未调用 waitForTransaction	始终等待并检查 committedTx.success
使用 number 表示大额数值	在 functionArguments 中使用 bigint 表示 u64/u128/u256
提交时签名者错误	使用地址为发送方的 Account（或视情况使用费用支付方／额外签名者）
以为 scriptComposer 仍然存在	使用独立交易或批处理；scriptComposer 已在 v6 中移除

---

参考

• SDK：src/api/transaction.ts、src/internal/transactionSubmission.ts、src/internal/transaction.ts
• 模式：TYPESCRIPT_SDK.md
• 相关内容：ts-sdk-account、ts-sdk-client、 ts-sdk-wallet-adapter、use-ts-sdk