技能名称: ts-sdk-transactions

详细描述:

TypeScript SDK：交易

目的

指导使用 @aptos-labs/ts-sdk 进行交易的构建、签名、提交和模拟。遵循 构建 → 签名 → 提交 → 等待 模式；可选择在提交前进行模拟。

始终

1. 1. 提交后调用 aptos.waitForTransaction({ transactionHash }) – 不要假设 signAndSubmitTransaction 后交易已提交。
2. 对入口函数负载使用 aptos.transaction.build.simple() – 传递 sender 和 data: { function, functionArguments, typeArguments? }。
3. 对关键/高价值流程在提交前进行模拟 – 使用 aptos.transaction.simulate.simple() 并检查 success 和 vm_status。
4. 对签名者使用与构建时 sender 地址相同的 Account 实例（例如，account.accountAddress 作为发送者，account 作为签名者）。

绝不

1. 1. 不要跳过 waitForTransaction – 提交返回的是交易被接受时，而非已提交时。
2. 不要使用已弃用的 scriptComposer（已在 v6 中移除）– 使用单独的交易或批量模式。
3. 不要在 functionArguments 中使用 number 表示 u64/u128/u256 – 在需要时使用 bigint 以避免精度损失。

标准流程（简单交易）

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

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

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

// 2. 签名并提交
const pendingTx = await aptos.signAndSubmitTransaction({
signer: account,
transaction
});

// 3. 等待提交
const committedTx = await aptos.waitForTransaction({
transactionHash: pendingTx.hash
});

if (!committedTx.success) {
throw new Error(交易失败: ${committedTx.vm_status});
}

构建选项

typescript
// 带类型参数（例如代币类型）
const transaction = await aptos.transaction.build.simple({
sender: account.accountAddress,
data: {
function: 0x1::coin::transfer,
typeArguments: [0x1::aptos_coin::AptosCoin],
functionArguments: [recipientAddress, amount]
}
});

// 可选：最大 gas、过期时间等（完整选项见 SDK 类型）
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)
}
});

模拟（提交前）

typescript
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(模拟失败: ${simResult.vm_status});
}
console.log(使用的 Gas:, simResult.gas_used);

赞助交易（费用支付者）

typescript
// 1. 使用费用支付者构建
const transaction = await aptos.transaction.build.simple({
sender: sender.accountAddress,
withFeePayer: true,
data: {
function: ${MODULE_ADDRESS}::counter::increment,
functionArguments: []
}
});

// 2. 发送者签名
const senderAuth = aptos.transaction.sign({
signer: sender,
transaction
});

// 3. 费用支付者签名（不同方法）
const feePayerAuth = aptos.transaction.signAsFeePayer({
signer: feePayer,
transaction
});

// 4. 使用两个认证器提交
const pendingTx = await aptos.transaction.submit.simple({
transaction,
senderAuthenticator: senderAuth,
feePayerAuthenticator: feePayerAuth
});

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

多代理交易

typescript
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 选项

typescript
const committed = await aptos.waitForTransaction({
transactionHash: pendingTx.hash,
options: {
timeoutSecs: 60,
checkSuccess: true // 如果交易失败则抛出异常
}
});

Gas 分析

typescript
const gasProfile = await aptos.gasProfile({
sender: account.accountAddress,
data: {
function: ${MODULEADDRESS}::module::functionname,
functionArguments: []
}
});
console.log(Gas 分析:, gasProfile);

常见错误

参考

• - SDK: src/api/transaction.ts, src/internal/transactionSubmission.ts, src/internal/transaction.ts
• 模式: TYPESCRIPTSDK.md
• 相关: ts-sdk-account, ts-sdk-client,