use-typescript-sdk
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseUse TypeScript SDK Skill
使用TypeScript SDK技能
Core Rules
核心规则
SDK Setup
SDK配置
- ALWAYS use (the current official SDK, NOT the deprecated
@aptos-labs/ts-sdkpackage)aptos - ALWAYS create a singleton client and export it from a shared module (e.g.,
Aptos)lib/aptos.ts - ALWAYS configure the network via with environment variables
AptosConfig - ALWAYS use as the default for development (NOT devnet, which resets frequently)
Network.TESTNET
- 必须使用(这是当前官方SDK,不要使用已弃用的
@aptos-labs/ts-sdk包)aptos - 必须创建单例客户端并从公共模块导出(例如
Aptos)lib/aptos.ts - 必须通过结合环境变量配置网络
AptosConfig - 开发环境必须默认使用(不要使用会频繁重置的devnet)
Network.TESTNET
Balance & Queries
余额与查询
- ALWAYS use for APT balance queries (NOT the deprecated
aptos.getBalance()orgetAccountCoinAmount)getAccountAPTAmount
- 查询APT余额必须使用(不要使用已弃用的
aptos.getBalance()或getAccountCoinAmount)getAccountAPTAmount
Transactions
交易相关
- ALWAYS call after submitting any transaction
waitForTransaction - ALWAYS simulate transactions before submitting for critical or high-value operations
- ALWAYS wrap blockchain calls in try/catch with specific error handling
- ALWAYS use the build-sign-submit pattern: then
transaction.build.simple()signAndSubmitTransaction()
- 提交任何交易后必须调用
waitForTransaction - 关键或高价值操作提交前必须先模拟交易
- 所有区块链调用必须用try/catch包裹并做针对性错误处理
- 必须使用构建-签名-提交模式:先调用再调用
transaction.build.simple()signAndSubmitTransaction()
Security
安全规则
- NEVER hardcode private keys in source code or frontend bundles
- NEVER expose private keys in client-side code or logs
- NEVER store private keys in environment variables accessible to the browser (use prefix only for public config)
VITE_ - ALWAYS load private keys from environment variables in server-side scripts only, using
process.env
- 绝对不要在源代码或前端产物中硬编码私钥
- 绝对不要在客户端代码或日志中暴露私钥
- 绝对不要在浏览器可访问的环境变量中存储私钥(仅公开配置可以用前缀)
VITE_ - 仅可在服务端脚本中通过从环境变量加载私钥
process.env
Type Safety
类型安全
- ALWAYS use for u128 and u256 values (JavaScript
bigintloses precision)number - ALWAYS pass references as address strings in
Object<T>functionArguments - ALWAYS use typed entry/view function wrappers instead of raw string-based calls in production code
- u128和u256类型的值必须使用(JavaScript的
bigint会丢失精度)number - 在中必须将
functionArguments引用作为地址字符串传递Object<T> - 生产环境必须使用带类型的入口/视图函数封装,而非原始的字符串调用
Wallet Adapter
钱包适配器
- ALWAYS use for frontend wallet integration
@aptos-labs/wallet-adapter-react - ALWAYS wrap your app with
AptosWalletAdapterProvider - ALWAYS use hook to access wallet functions in React components
useWallet()
- 前端钱包集成必须使用
@aptos-labs/wallet-adapter-react - 必须用包裹你的应用
AptosWalletAdapterProvider - React组件中必须使用hook访问钱包功能
useWallet()
Quick Workflow
快速工作流
- Install SDK ->
npm install @aptos-labs/ts-sdk - Create client -> Singleton instance in
Aptoslib/aptos.ts - Read data -> Use for on-chain reads
aptos.view() - Write data -> Use +
aptos.transaction.build.simple()aptos.signAndSubmitTransaction() - Connect wallet -> Use for frontend dApps
@aptos-labs/wallet-adapter-react - Handle errors -> Wrap all calls in try/catch with error-type checks
- 安装SDK ->
npm install @aptos-labs/ts-sdk - 创建客户端 -> 在中创建单例
lib/aptos.ts实例Aptos - 读取数据 -> 使用读取链上数据
aptos.view() - 写入数据 -> 使用+
aptos.transaction.build.simple()aptos.signAndSubmitTransaction() - 连接钱包 -> 前端dApp使用
@aptos-labs/wallet-adapter-react - 错误处理 -> 所有调用用try/catch包裹并做错误类型检查
Key Example: Client Setup
核心示例:客户端配置
typescript
// lib/aptos.ts - Singleton client (create once, import everywhere)
import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
function getNetwork(): Network {
const network = import.meta.env.VITE_APP_NETWORK;
switch (network) {
case "mainnet":
return Network.MAINNET;
case "testnet":
return Network.TESTNET;
case "devnet":
return Network.DEVNET;
default:
return Network.TESTNET;
}
}
const config = new AptosConfig({ network: getNetwork() });
export const aptos = new Aptos(config);
export const MODULE_ADDRESS = import.meta.env.VITE_MODULE_ADDRESS;typescript
// lib/aptos.ts - 单例客户端(创建一次,全局导入)
import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
function getNetwork(): Network {
const network = import.meta.env.VITE_APP_NETWORK;
switch (network) {
case "mainnet":
return Network.MAINNET;
case "testnet":
return Network.TESTNET;
case "devnet":
return Network.DEVNET;
default:
return Network.TESTNET;
}
}
const config = new AptosConfig({ network: getNetwork() });
export const aptos = new Aptos(config);
export const MODULE_ADDRESS = import.meta.env.VITE_MODULE_ADDRESS;Key Example: View Functions (Read)
核心示例:视图函数(读操作)
typescript
// view-functions/getCount.ts
import { aptos, MODULE_ADDRESS } from "../lib/aptos";
export async function getCount(accountAddress: string): Promise<number> {
const result = await aptos.view({
payload: {
function: `${MODULE_ADDRESS}::counter::get_count`,
functionArguments: [accountAddress]
}
});
return Number(result[0]);
}
// With type arguments
export async function getCoinBalance(accountAddress: string, coinType: string): Promise<bigint> {
const result = await aptos.view({
payload: {
function: "0x1::coin::balance",
typeArguments: [coinType],
functionArguments: [accountAddress]
}
});
return BigInt(result[0] as string);
}
// Multiple return values
// Move: public fun get_listing(addr): (address, u64, bool)
export async function getListing(nftAddress: string): Promise<{ seller: string; price: number; isActive: boolean }> {
const [seller, price, isActive] = await aptos.view({
payload: {
function: `${MODULE_ADDRESS}::marketplace::get_listing`,
functionArguments: [nftAddress]
}
});
return {
seller: seller as string,
price: Number(price),
isActive: isActive as boolean
};
}typescript
// view-functions/getCount.ts
import { aptos, MODULE_ADDRESS } from "../lib/aptos";
export async function getCount(accountAddress: string): Promise<number> {
const result = await aptos.view({
payload: {
function: `${MODULE_ADDRESS}::counter::get_count`,
functionArguments: [accountAddress]
}
});
return Number(result[0]);
}
// 带类型参数的示例
export async function getCoinBalance(accountAddress: string, coinType: string): Promise<bigint> {
const result = await aptos.view({
payload: {
function: "0x1::coin::balance",
typeArguments: [coinType],
functionArguments: [accountAddress]
}
});
return BigInt(result[0] as string);
}
// 多返回值示例
// Move代码: public fun get_listing(addr): (address, u64, bool)
export async function getListing(nftAddress: string): Promise<{ seller: string; price: number; isActive: boolean }> {
const [seller, price, isActive] = await aptos.view({
payload: {
function: `${MODULE_ADDRESS}::marketplace::get_listing`,
functionArguments: [nftAddress]
}
});
return {
seller: seller as string,
price: Number(price),
isActive: isActive as boolean
};
}Key Example: Entry Functions (Write) - Server/Script
核心示例:入口函数(写操作)- 服务端/脚本
typescript
import { Account, Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
const config = new AptosConfig({ network: Network.TESTNET });
const aptos = new Aptos(config);
// Build transaction
const transaction = await aptos.transaction.build.simple({
sender: account.accountAddress,
data: {
function: `${MODULE_ADDRESS}::counter::increment`,
functionArguments: []
}
});
// Sign and submit
const pendingTx = await aptos.signAndSubmitTransaction({
signer: account,
transaction
});
// ALWAYS wait for confirmation
const committedTx = await aptos.waitForTransaction({
transactionHash: pendingTx.hash
});
console.log("Success:", committedTx.success);typescript
import { Account, Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
const config = new AptosConfig({ network: Network.TESTNET });
const aptos = new Aptos(config);
// 构建交易
const transaction = await aptos.transaction.build.simple({
sender: account.accountAddress,
data: {
function: `${MODULE_ADDRESS}::counter::increment`,
functionArguments: []
}
});
// 签名并提交
const pendingTx = await aptos.signAndSubmitTransaction({
signer: account,
transaction
});
// 必须等待交易确认
const committedTx = await aptos.waitForTransaction({
transactionHash: pendingTx.hash
});
console.log("Success:", committedTx.success);Key Example: Entry Functions (Write) - Frontend with Wallet
核心示例:入口函数(写操作)- 前端结合钱包
typescript
// entry-functions/increment.ts
import { InputTransactionData } from "@aptos-labs/wallet-adapter-react";
import { MODULE_ADDRESS } from "../lib/aptos";
export function buildIncrementPayload(): InputTransactionData {
return {
data: {
function: `${MODULE_ADDRESS}::counter::increment`,
functionArguments: [],
},
};
}
// Component usage
import { useWallet } from "@aptos-labs/wallet-adapter-react";
import { aptos } from "../lib/aptos";
import { buildIncrementPayload } from "../entry-functions/increment";
function IncrementButton() {
const { signAndSubmitTransaction } = useWallet();
const handleClick = async () => {
try {
const response = await signAndSubmitTransaction(
buildIncrementPayload(),
);
await aptos.waitForTransaction({
transactionHash: response.hash,
});
} catch (error) {
console.error("Transaction failed:", error);
}
};
return <button onClick={handleClick}>Increment</button>;
}typescript
// entry-functions/increment.ts
import { InputTransactionData } from "@aptos-labs/wallet-adapter-react";
import { MODULE_ADDRESS } from "../lib/aptos";
export function buildIncrementPayload(): InputTransactionData {
return {
data: {
function: `${MODULE_ADDRESS}::counter::increment`,
functionArguments: [],
},
};
}
// 组件中使用
import { useWallet } from "@aptos-labs/wallet-adapter-react";
import { aptos } from "../lib/aptos";
import { buildIncrementPayload } from "../entry-functions/increment";
function IncrementButton() {
const { signAndSubmitTransaction } = useWallet();
const handleClick = async () => {
try {
const response = await signAndSubmitTransaction(
buildIncrementPayload(),
);
await aptos.waitForTransaction({
transactionHash: response.hash,
});
} catch (error) {
console.error("Transaction failed:", error);
}
};
return <button onClick={handleClick}>Increment</button>;
}Key Example: Wallet Adapter Setup
核心示例:钱包适配器配置
typescript
// main.tsx or App.tsx
import { AptosWalletAdapterProvider } from "@aptos-labs/wallet-adapter-react";
import { Network } from "@aptos-labs/ts-sdk";
function App() {
return (
<AptosWalletAdapterProvider
autoConnect={true}
dappConfig={{
network: Network.TESTNET,
}}
onError={(error) => console.error("Wallet error:", error)}
>
<YourApp />
</AptosWalletAdapterProvider>
);
}
// In any child component
import { useWallet } from "@aptos-labs/wallet-adapter-react";
function WalletInfo() {
const { account, connected, connect, disconnect, wallet, wallets } =
useWallet();
if (!connected) {
return (
<div>
{wallets.map((w) => (
<button key={w.name} onClick={() => connect(w.name)}>
Connect {w.name}
</button>
))}
</div>
);
}
return (
<div>
<p>Connected: {account?.address}</p>
<p>Wallet: {wallet?.name}</p>
<button onClick={disconnect}>Disconnect</button>
</div>
);
}typescript
// main.tsx 或 App.tsx
import { AptosWalletAdapterProvider } from "@aptos-labs/wallet-adapter-react";
import { Network } from "@aptos-labs/ts-sdk";
function App() {
return (
<AptosWalletAdapterProvider
autoConnect={true}
dappConfig={{
network: Network.TESTNET,
}}
onError={(error) => console.error("Wallet error:", error)}
>
<YourApp />
</AptosWalletAdapterProvider>
);
}
// 任意子组件中使用
import { useWallet } from "@aptos-labs/wallet-adapter-react";
function WalletInfo() {
const { account, connected, connect, disconnect, wallet, wallets } =
useWallet();
if (!connected) {
return (
<div>
{wallets.map((w) => (
<button key={w.name} onClick={() => connect(w.name)}>
Connect {w.name}
</button>
))}
</div>
);
}
return (
<div>
<p>Connected: {account?.address}</p>
<p>Wallet: {wallet?.name}</p>
<button onClick={disconnect}>Disconnect</button>
</div>
);
}Key Example: Sponsored Transactions (Fee Payer)
核心示例:赞助交易(代付Gas)
typescript
import { Account, Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
const aptos = new Aptos(new AptosConfig({ network: Network.TESTNET }));
// 1. Build with fee payer flag
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 signatures
const pendingTx = await aptos.transaction.submit.simple({
transaction,
senderAuthenticator: senderAuth,
feePayerAuthenticator: feePayerAuth
});
await aptos.waitForTransaction({ transactionHash: pendingTx.hash });typescript
import { Account, Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
const aptos = new Aptos(new AptosConfig({ network: Network.TESTNET }));
// 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. Gas代付方签名(使用不同的签名方法!)
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 });Key Example: Multi-Agent Transactions
核心示例:多代理交易
typescript
// 1. Build multi-agent transaction
const transaction = await aptos.transaction.build.multiAgent({
sender: alice.accountAddress,
secondarySignerAddresses: [bob.accountAddress],
data: {
function: `${MODULE_ADDRESS}::escrow::exchange`,
functionArguments: [itemAddress, paymentAmount]
}
});
// 2. Each agent signs
const aliceAuth = aptos.transaction.sign({
signer: alice,
transaction
});
const bobAuth = aptos.transaction.sign({
signer: bob,
transaction
});
// 3. Submit with all signatures
const pendingTx = await aptos.transaction.submit.multiAgent({
transaction,
senderAuthenticator: aliceAuth,
additionalSignersAuthenticators: [bobAuth]
});
await aptos.waitForTransaction({ transactionHash: pendingTx.hash });typescript
// 1. 构建多代理交易
const transaction = await aptos.transaction.build.multiAgent({
sender: alice.accountAddress,
secondarySignerAddresses: [bob.accountAddress],
data: {
function: `${MODULE_ADDRESS}::escrow::exchange`,
functionArguments: [itemAddress, paymentAmount]
}
});
// 2. 每个代理分别签名
const aliceAuth = aptos.transaction.sign({
signer: alice,
transaction
});
const bobAuth = aptos.transaction.sign({
signer: bob,
transaction
});
// 3. 携带所有签名提交交易
const pendingTx = await aptos.transaction.submit.multiAgent({
transaction,
senderAuthenticator: aliceAuth,
additionalSignersAuthenticators: [bobAuth]
});
await aptos.waitForTransaction({ transactionHash: pendingTx.hash });Type Mappings: Move to TypeScript
类型映射:Move 到 TypeScript
| Move Type | TypeScript Type | Example |
|---|---|---|
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | Use |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | Object address as hex string |
| | Value or |
| Move 类型 | TypeScript 类型 | 示例 |
|---|---|---|
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | 大数值请使用 |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | 十六进制格式的对象地址 |
| | 值或 |
Transaction Simulation
交易模拟
typescript
// Build transaction
const transaction = await aptos.transaction.build.simple({
sender: account.accountAddress,
data: {
function: `${MODULE_ADDRESS}::counter::increment`,
functionArguments: []
}
});
// Simulate to check for errors and estimate gas
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 estimate:", simResult.gas_used);typescript
// 构建交易
const transaction = await aptos.transaction.build.simple({
sender: account.accountAddress,
data: {
function: `${MODULE_ADDRESS}::counter::increment`,
functionArguments: []
}
});
// 模拟交易检查错误并估算Gas
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 estimate:", simResult.gas_used);Gas Profiling
Gas分析
typescript
// Profile gas usage of a transaction (useful for optimization)
const gasProfile = await aptos.gasProfile({
sender: account.accountAddress,
data: {
function: `${MODULE_ADDRESS}::module::function_name`,
functionArguments: []
}
});
console.log("Gas profile:", gasProfile);typescript
// 分析交易的Gas使用情况(适合优化场景)
const gasProfile = await aptos.gasProfile({
sender: account.accountAddress,
data: {
function: `${MODULE_ADDRESS}::module::function_name`,
functionArguments: []
}
});
console.log("Gas profile:", gasProfile);Anti-patterns
反模式
- NEVER use the deprecated npm package - use
aptosinstead@aptos-labs/ts-sdk - NEVER skip after submitting - transaction may not be committed yet
waitForTransaction - NEVER hardcode module addresses - use environment variables ()
VITE_MODULE_ADDRESS - NEVER use for u128/u256 values - JavaScript loses precision above 2^53; use
numberbigint - NEVER create multiple client instances - create one singleton and share it
Aptos - NEVER ignore transaction simulation results for high-value operations
- NEVER hardcode network selection - use environment-based configuration
- NEVER store private keys in browser-accessible env vars (e.g., )
VITE_PRIVATE_KEY - NEVER use in frontend code for real users - use wallet adapter instead
Account.generate() - NEVER use raw in React - use the wallet adapter's
aptos.signAndSubmitTransactionsignAndSubmitTransaction - NEVER use - it was removed in v6.0; use batch transactions or separate calls instead
scriptComposer - NEVER use or
getAccountCoinAmount- deprecated; usegetAccountAPTAmountinsteadgetBalance()
- 绝对不要使用已弃用的npm包 - 请使用
aptos@aptos-labs/ts-sdk - 提交交易后绝对不要跳过- 此时交易可能还未上链确认
waitForTransaction - 绝对不要硬编码模块地址 - 请使用环境变量()
VITE_MODULE_ADDRESS - u128/u256类型的值绝对不要用- JavaScript在2^53以上会丢失精度,请使用
numberbigint - 绝对不要创建多个客户端实例 - 创建一个单例全局复用即可
Aptos - 高价值操作绝对不要忽略交易模拟结果
- 绝对不要硬编码网络选择 - 请使用基于环境变量的配置
- 绝对不要在浏览器可访问的环境变量中存储私钥(例如)
VITE_PRIVATE_KEY - 前端代码中绝对不要为真实用户使用- 请使用钱包适配器
Account.generate() - React中绝对不要直接使用原生的- 请使用钱包适配器提供的
aptos.signAndSubmitTransactionsignAndSubmitTransaction - 绝对不要使用- v6.0已移除该功能,请使用批量交易或单独调用替代
scriptComposer - 绝对不要使用或
getAccountCoinAmount- 已弃用,请使用getAccountAPTAmount替代getBalance()
Edge Cases to Handle
需要处理的边缘案例
| Scenario | Check | Action |
|---|---|---|
| Resource not found | | Return default value or null |
| Module not deployed | | Show "contract not deployed" message |
| Function not found | | Check function name and module address |
| Move abort | | Parse abort code, map to user-friendly error |
| Out of gas | | Increase |
| Sequence number error | | Retry after fetching fresh sequence number |
| Network timeout | | Retry with exponential backoff |
| Account does not exist | | Fund account or prompt user to create one |
| Insufficient balance | | Show balance and required amount |
| User rejected in wallet | Wallet-specific rejection error | Show "transaction cancelled" message |
| 场景 | 检查条件 | 处理方案 |
|---|---|---|
| 资源不存在 | | 返回默认值或null |
| 模块未部署 | | 展示「合约未部署」提示 |
| 函数不存在 | | 检查函数名和模块地址 |
| Move执行终止 | | 解析终止码,转换为用户友好的错误提示 |
| Gas不足 | | 提高 |
| 序列号错误 | | 获取最新序列号后重试 |
| 网络超时 | | 指数退避重试 |
| 账户不存在 | | 为账户注资或提示用户创建账户 |
| 余额不足 | | 展示当前余额和所需金额 |
| 用户在钱包中拒绝交易 | 钱包专属的拒绝错误 | 展示「交易已取消」提示 |
Error Handling Pattern
错误处理模式
typescript
async function submitTransaction(
aptos: Aptos,
signer: Account,
payload: InputGenerateTransactionPayloadData
): Promise<string> {
try {
const transaction = await aptos.transaction.build.simple({
sender: signer.accountAddress,
data: payload
});
const pendingTx = await aptos.signAndSubmitTransaction({
signer,
transaction
});
const committed = await aptos.waitForTransaction({
transactionHash: pendingTx.hash
});
if (!committed.success) {
throw new Error(`Transaction failed: ${committed.vm_status}`);
}
return pendingTx.hash;
} catch (error) {
if (error instanceof Error) {
if (error.message.includes("RESOURCE_NOT_FOUND")) {
throw new Error("Resource does not exist at the specified address");
}
if (error.message.includes("MODULE_NOT_FOUND")) {
throw new Error("Contract is not deployed at the specified address");
}
if (error.message.includes("ABORTED")) {
const match = error.message.match(/code: (\d+)/);
const code = match ? match[1] : "unknown";
throw new Error(`Contract error (code ${code})`);
}
}
throw error;
}
}typescript
async function submitTransaction(
aptos: Aptos,
signer: Account,
payload: InputGenerateTransactionPayloadData
): Promise<string> {
try {
const transaction = await aptos.transaction.build.simple({
sender: signer.accountAddress,
data: payload
});
const pendingTx = await aptos.signAndSubmitTransaction({
signer,
transaction
});
const committed = await aptos.waitForTransaction({
transactionHash: pendingTx.hash
});
if (!committed.success) {
throw new Error(`Transaction failed: ${committed.vm_status}`);
}
return pendingTx.hash;
} catch (error) {
if (error instanceof Error) {
if (error.message.includes("RESOURCE_NOT_FOUND")) {
throw new Error("Resource does not exist at the specified address");
}
if (error.message.includes("MODULE_NOT_FOUND")) {
throw new Error("Contract is not deployed at the specified address");
}
if (error.message.includes("ABORTED")) {
const match = error.message.match(/code: (\d+)/);
const code = match ? match[1] : "unknown";
throw new Error(`Contract error (code ${code})`);
}
}
throw error;
}
}File Organization Pattern
文件组织模式
src/
lib/
aptos.ts # Singleton Aptos client + MODULE_ADDRESS
view-functions/
getCount.ts # One file per view function
getListing.ts
entry-functions/
increment.ts # One file per entry function
createListing.ts
hooks/
useCounter.ts # React hooks wrapping view functions
useListing.ts
components/
WalletProvider.tsx # AptosWalletAdapterProvider wrapper
IncrementButton.tsx # Components calling entry functionssrc/
lib/
aptos.ts # 单例Aptos客户端 + MODULE_ADDRESS
view-functions/
getCount.ts # 每个视图函数单独一个文件
getListing.ts
entry-functions/
increment.ts # 每个入口函数单独一个文件
createListing.ts
hooks/
useCounter.ts # 封装视图函数的React hooks
useListing.ts
components/
WalletProvider.tsx # AptosWalletAdapterProvider封装
IncrementButton.tsx # 调用入口函数的组件SDK Version Notes (v5.2+ / v6.0)
SDK版本说明(v5.2+ / v6.0)
Balance Queries (v5.1+)
余额查询(v5.1+)
typescript
// CORRECT (v5.1+)
const balance = await aptos.getBalance({
accountAddress: account.accountAddress
});
// Returns bigint in octas (1 APT = 100_000_000 octas)
// DEPRECATED - do NOT use
// await aptos.getAccountCoinAmount(...)
// await aptos.getAccountAPTAmount(...)typescript
// 正确写法(v5.1+)
const balance = await aptos.getBalance({
accountAddress: account.accountAddress
});
// 返回以octas为单位的bigint(1 APT = 100_000_000 octas)
// 已弃用 - 请勿使用
// await aptos.getAccountCoinAmount(...)
// await aptos.getAccountAPTAmount(...)AIP-80 Private Key Format (v2.0+)
AIP-80私钥格式(v2.0+)
Ed25519 and Secp256k1 private keys now use an AIP-80 prefixed format when serialized with :
toString()typescript
const key = new Ed25519PrivateKey("0x...");
key.toString(); // Returns AIP-80 prefixed format, NOT raw hexEd25519和Secp256k1私钥通过序列化时现在使用AIP-80前缀格式:
toString()typescript
const key = new Ed25519PrivateKey("0x...");
key.toString(); // 返回带AIP-80前缀的格式,而非原始十六进制AccountAddress Parsing (v1.32+)
AccountAddress解析(v1.32+)
AccountAddress.fromString()AccountAddress.from()typescript
// CORRECT
const addr = AccountAddress.from("0x1"); // Accepts any format
const addr2 = AccountAddress.fromString("0x000000000000000000000000000000000000000000000000000000000000001"); // SHORT format only
// MAY FAIL in v1.32+
// AccountAddress.fromString("0x1") -- too short for SHORT formatAccountAddress.fromString()AccountAddress.from()typescript
// 正确写法
const addr = AccountAddress.from("0x1"); // 支持任意格式
const addr2 = AccountAddress.fromString("0x000000000000000000000000000000000000000000000000000000000000001"); // 仅支持短格式
// v1.32+可能报错
// AccountAddress.fromString("0x1") -- 短格式要求下长度不足Fungible Asset Transfers (v1.39+)
同质化资产转账(v1.39+)
typescript
// Transfer between FA stores directly
await aptos.transferFungibleAssetBetweenStores({
sender: account,
fungibleAssetMetadataAddress: metadataAddr,
senderStoreAddress: fromStore,
recipientStoreAddress: toStore,
amount: 1000n
});typescript
// 直接在FA存储之间转账
await aptos.transferFungibleAssetBetweenStores({
sender: account,
fungibleAssetMetadataAddress: metadataAddr,
senderStoreAddress: fromStore,
recipientStoreAddress: toStore,
amount: 1000n
});Bun Runtime Compatibility
Bun运行时兼容
When using Bun instead of Node.js, disable HTTP/2 in the client config:
typescript
const config = new AptosConfig({
network: Network.TESTNET,
clientConfig: { http2: false }
});使用Bun替代Node.js时,请在客户端配置中关闭HTTP/2:
typescript
const config = new AptosConfig({
network: Network.TESTNET,
clientConfig: { http2: false }
});Account Abstraction (v1.34+, AIP-104)
账户抽象(v1.34+, AIP-104)
The namespace provides APIs for custom authentication:
aptos.abstractiontypescript
// Check if AA is enabled for an account
const isEnabled = await aptos.abstraction.isAccountAbstractionEnabled({
accountAddress: "0x...",
authenticationFunction: `${MODULE_ADDRESS}::auth::authenticate`
});
// Enable AA on an account
const enableTxn = await aptos.abstraction.enableAccountAbstractionTransaction({
accountAddress: account.accountAddress,
authenticationFunction: `${MODULE_ADDRESS}::auth::authenticate`
});
// Disable AA
const disableTxn = await aptos.abstraction.disableAccountAbstractionTransaction({
accountAddress: account.accountAddress,
authenticationFunction: `${MODULE_ADDRESS}::auth::authenticate`
});
// Use AbstractedAccount for signing with custom auth logic
import { AbstractedAccount } from "@aptos-labs/ts-sdk";aptos.abstractiontypescript
// 检查账户是否开启了AA
const isEnabled = await aptos.abstraction.isAccountAbstractionEnabled({
accountAddress: "0x...",
authenticationFunction: `${MODULE_ADDRESS}::auth::authenticate`
});
// 为账户开启AA
const enableTxn = await aptos.abstraction.enableAccountAbstractionTransaction({
accountAddress: account.accountAddress,
authenticationFunction: `${MODULE_ADDRESS}::auth::authenticate`
});
// 关闭AA
const disableTxn = await aptos.abstraction.disableAccountAbstractionTransaction({
accountAddress: account.accountAddress,
authenticationFunction: `${MODULE_ADDRESS}::auth::authenticate`
});
// 使用AbstractedAccount结合自定义认证逻辑签名
import { AbstractedAccount } from "@aptos-labs/ts-sdk";References
参考资料
Detailed Patterns (references/ folder):
- - Wallet adapter setup and patterns
references/wallet-adapter.md - - Advanced transaction patterns (sponsored, multi-agent, simulation)
references/transaction-patterns.md - - Complete Move-to-TypeScript type reference
references/type-mappings.md
Pattern Documentation (patterns/ folder):
- - Complete SDK API reference
../../../patterns/fullstack/TYPESCRIPT_SDK.md
Official Documentation:
- TypeScript SDK: https://aptos.dev/build/sdks/ts-sdk
- SDK Quickstart: https://aptos.dev/build/sdks/ts-sdk/quickstart
- API Reference: https://aptos-labs.github.io/aptos-ts-sdk/
- Wallet Adapter: https://aptos.dev/build/sdks/wallet-adapter/dapp
- Sponsored Transactions: https://aptos.dev/build/sdks/ts-sdk/building-transactions/sponsoring-transactions
- Multi-Agent Transactions: https://aptos.dev/build/sdks/ts-sdk/building-transactions/multi-agent-transactions
- GitHub: https://github.com/aptos-labs/aptos-ts-sdk
Related Skills:
- - Write the Move contracts that this SDK interacts with
write-contracts - - Deploy contracts before calling them from TypeScript
deploy-contracts - - Bootstrap a fullstack project with SDK already configured
scaffold-project
详细模式说明(references/ 文件夹):
- - 钱包适配器配置与模式
references/wallet-adapter.md - - 高级交易模式(赞助交易、多代理交易、模拟)
references/transaction-patterns.md - - 完整的Move到TypeScript类型参考
references/type-mappings.md
模式文档(patterns/ 文件夹):
- - 完整的SDK API参考
../../../patterns/fullstack/TYPESCRIPT_SDK.md
官方文档:
- TypeScript SDK: https://aptos.dev/build/sdks/ts-sdk
- SDK快速入门: https://aptos.dev/build/sdks/ts-sdk/quickstart
- API参考: https://aptos-labs.github.io/aptos-ts-sdk/
- 钱包适配器: https://aptos.dev/build/sdks/wallet-adapter/dapp
- 赞助交易: https://aptos.dev/build/sdks/ts-sdk/building-transactions/sponsoring-transactions
- 多代理交易: https://aptos.dev/build/sdks/ts-sdk/building-transactions/multi-agent-transactions
- GitHub: https://github.com/aptos-labs/aptos-ts-sdk
相关技能:
- - 编写本SDK交互的Move合约
write-contracts - - 在TypeScript调用合约前先部署合约
deploy-contracts - - 初始化已经配置好SDK的全栈项目
scaffold-project