ts-sdk-account

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript SDK: Account (Signer)

TypeScript SDK：Account（签名者）

Purpose

用途

Guide creation and use of Account (signer) in

@aptos-labs/ts-sdk

. An Account holds address + key material and can sign transactions and messages. Creating an Account does NOT create the account on-chain; use faucet or transfer to fund it.

本文指导如何在

@aptos-labs/ts-sdk

中创建和使用Account（签名者）。Account包含地址和密钥材料，可对交易和消息进行签名。创建Account并不会在链上生成账户；需使用水龙头（faucet）或转账为其充值。

ALWAYS

必做事项

Use
Account.generate()
or
Account.fromPrivateKey()
only in server/script – never in frontend; use wallet adapter for end users.
Load private keys from env (e.g.
process.env.PRIVATE_KEY
) on server – never hardcode.
Use
account.accountAddress
when building transactions – pass as sender/secondary signers.

Use
aptos.signAndSubmitTransaction({ signer: account, transaction })
with the same Account instance that holds the key.

仅在服务器/脚本中使用
Account.generate()
或
Account.fromPrivateKey()
——绝不要在前端使用；面向终端用户请使用钱包适配器。
在服务器上从环境变量（如
process.env.PRIVATE_KEY
）加载私钥——绝不要硬编码。
构建交易时使用
account.accountAddress
——将其作为发送方或二级签名者传入。

使用
aptos.signAndSubmitTransaction({ signer: account, transaction })
——需传入持有密钥的同一个Account实例。

NEVER

禁止事项

Do not use
Account.generate()
or raw private keys in browser/frontend – use wallet adapter.
Do not hardcode private keys in source or commit to git.
Do not confuse
Account
(API namespace) with
Account
(signer class) – API is
```
aptos.account.*
```
; signer is the class from
```
Account
```
module (e.g.
```
Account.fromPrivateKey
```
).

不要在浏览器/前端中使用
Account.generate()
或原始私钥——请使用钱包适配器。
不要在源码中硬编码私钥或提交到Git仓库。
不要混淆
Account
（API命名空间）与
Account
（签名者类）——API是
```
aptos.account.*
```
；签名者是来自
```
Account
```
模块的类（如
```
Account.fromPrivateKey
```
）。

Account types (signing schemes)

账户类型（签名方案）

Type	Class	Use case
Ed25519 (legacy)	`Ed25519Account`	Single Ed25519 key, legacy auth
SingleKey	`SingleKeyAccount`	Ed25519 or Secp256k1, unified auth
MultiKey	`MultiKeyAccount`	Multi-sig
Keyless	`KeylessAccount`	Keyless (e.g. OIDC)
Federated Keyless	`FederatedKeylessAccount`	Federated keyless

类型	类	使用场景
Ed25519（传统版）	`Ed25519Account`	单个Ed25519密钥，传统认证
SingleKey	`SingleKeyAccount`	Ed25519或Secp256k1，统一认证
MultiKey	`MultiKeyAccount`	多签
Keyless	`KeylessAccount`	无密钥（如OIDC）
Federated Keyless	`FederatedKeylessAccount`	联邦无密钥

Generate new account (server/script only)

生成新账户（仅服务器/脚本环境）

typescript

import { Account, SigningSchemeInput } from "@aptos-labs/ts-sdk";

// Default: Ed25519 legacy
const ed25519Account = Account.generate();

// SingleKey (unified) with Ed25519
const singleKeyAccount = Account.generate({ scheme: SigningSchemeInput.Ed25519, legacy: false });

// SingleKey with Secp256k1
const secpAccount = Account.generate({ scheme: SigningSchemeInput.Secp256k1 });

// Access address and public key
const address = ed25519Account.accountAddress;
const pubKey = ed25519Account.publicKey;

typescript

import { Account, SigningSchemeInput } from "@aptos-labs/ts-sdk";

// 默认：Ed25519传统版
const ed25519Account = Account.generate();

// 采用Ed25519的SingleKey（统一版）
const singleKeyAccount = Account.generate({ scheme: SigningSchemeInput.Ed25519, legacy: false });

// 采用Secp256k1的SingleKey
const secpAccount = Account.generate({ scheme: SigningSchemeInput.Secp256k1 });

// 获取地址和公钥
const address = ed25519Account.accountAddress;
const pubKey = ed25519Account.publicKey;

From private key

从私钥创建账户

typescript

import { Account, Ed25519PrivateKey, Secp256k1PrivateKey } from "@aptos-labs/ts-sdk";

// Ed25519 legacy (default)
const privateKeyHex = process.env.PRIVATE_KEY!; // e.g. "0x..." or AIP-80 prefixed
const privateKey = new Ed25519PrivateKey(privateKeyHex);
const account = Account.fromPrivateKey({ privateKey });

// Ed25519 SingleKey (unified)
const accountSingle = Account.fromPrivateKey({
  privateKey: new Ed25519PrivateKey(privateKeyHex),
  legacy: false,
});

// Secp256k1 (always SingleKey)
const secpKey = new Secp256k1PrivateKey(process.env.SECP_KEY!);
const accountSecp = Account.fromPrivateKey({ privateKey: secpKey });

// Optional: fixed address (e.g. after key rotation)
const accountWithAddr = Account.fromPrivateKey({
  privateKey,
  address: "0x...",
});

typescript

import { Account, Ed25519PrivateKey, Secp256k1PrivateKey } from "@aptos-labs/ts-sdk";

// Ed25519传统版（默认）
const privateKeyHex = process.env.PRIVATE_KEY!; // 例如："0x..." 或AIP-80前缀格式
const privateKey = new Ed25519PrivateKey(privateKeyHex);
const account = Account.fromPrivateKey({ privateKey });

// Ed25519 SingleKey（统一版）
const accountSingle = Account.fromPrivateKey({
  privateKey: new Ed25519PrivateKey(privateKeyHex),
  legacy: false,
});

// Secp256k1（始终为SingleKey）
const secpKey = new Secp256k1PrivateKey(process.env.SECP_KEY!);
const accountSecp = Account.fromPrivateKey({ privateKey: secpKey });

// 可选：固定地址（如密钥轮换后）
const accountWithAddr = Account.fromPrivateKey({
  privateKey,
  address: "0x...",
});

From mnemonic (derivation path)

从助记词（派生路径）创建账户

typescript

import { Account } from "@aptos-labs/ts-sdk";

const mnemonic = "word1 word2 ... word12";
const path = "m/44'/637'/0'/0'/0'"; // Aptos BIP-44 path

// Ed25519 legacy
const acc = Account.fromDerivationPath({ mnemonic, path });

// Ed25519 SingleKey
const accSingle = Account.fromDerivationPath({ mnemonic, path, legacy: false });

// Secp256k1
const accSecp = Account.fromDerivationPath({
  scheme: SigningSchemeInput.Secp256k1,
  mnemonic,
  path,
});

typescript

import { Account } from "@aptos-labs/ts-sdk";

const mnemonic = "word1 word2 ... word12";
const path = "m/44'/637'/0'/0'/0'"; // Aptos BIP-44路径

// Ed25519传统版
const acc = Account.fromDerivationPath({ mnemonic, path });

// Ed25519 SingleKey
const accSingle = Account.fromDerivationPath({ mnemonic, path, legacy: false });

// Secp256k1
const accSecp = Account.fromDerivationPath({
  scheme: SigningSchemeInput.Secp256k1,
  mnemonic,
  path,
});

Auth key (for rotation / lookup)

认证密钥（用于密钥轮换/查询）

typescript

const authKey = Account.authKey({ publicKey: account.publicKey });
// Use authKey.derivedAddress() for address derivation; useful for multi-account lookup

typescript

const authKey = Account.authKey({ publicKey: account.publicKey });
// 使用authKey.derivedAddress()派生地址；适用于多账户查询

Serialization (toHex / fromHex)

序列化（toHex / fromHex）

Use when persisting or sending account (e.g. server-only, never expose private key to frontend):

typescript

import { Account, AccountUtils } from "@aptos-labs/ts-sdk";

const account = Account.generate();

// Serialize to hex (includes private key – treat as secret)
const hex = AccountUtils.toHexString(account);

// Deserialize back
const restored = AccountUtils.fromHex(hex);

// Typed deserialize
const edAccount = AccountUtils.ed25519AccountFromHex(hex);
const singleAccount = AccountUtils.singleKeyAccountFromHex(hex);
const multiAccount = AccountUtils.multiKeyAccountFromHex(hex);
const keylessAccount = AccountUtils.keylessAccountFromHex(hex);

用于持久化或传输账户（仅适用于服务器环境，绝不要向前端暴露私钥）：

typescript

import { Account, AccountUtils } from "@aptos-labs/ts-sdk";

const account = Account.generate();

// 序列化为十六进制字符串（包含私钥——需视为机密信息）
const hex = AccountUtils.toHexString(account);

// 反序列化恢复账户
const restored = AccountUtils.fromHex(hex);

// 类型化反序列化
const edAccount = AccountUtils.ed25519AccountFromHex(hex);
const singleAccount = AccountUtils.singleKeyAccountFromHex(hex);
const multiAccount = AccountUtils.multiKeyAccountFromHex(hex);
const keylessAccount = AccountUtils.keylessAccountFromHex(hex);

Signing

签名

typescript

// Sign message (returns Signature)
const sig = account.sign(messageHex);

// Sign transaction (returns Signature; for submit use aptos.transaction.sign + submit)
const txSig = account.signTransaction(rawTransaction);

// With authenticator (used by SDK internally for submit)
const auth = account.signWithAuthenticator(messageHex);

typescript

// 签名消息（返回Signature）
const sig = account.sign(messageHex);

// 签名交易（返回Signature；提交需使用aptos.transaction.sign + submit）
const txSig = account.signTransaction(rawTransaction);

// 带认证器的签名（SDK内部提交时使用）
const auth = account.signWithAuthenticator(messageHex);

Verify signature

验证签名

typescript

const ok = account.verifySignature({ message: messageHex, signature: sig });

// Async (if key type needs on-chain state)
const okAsync = await account.verifySignatureAsync({
  aptosConfig: aptos.config,
  message: messageHex,
  signature: sig,
});

typescript

const ok = account.verifySignature({ message: messageHex, signature: sig });

// 异步验证（若密钥类型需要链上状态）
const okAsync = await account.verifySignatureAsync({
  aptosConfig: aptos.config,
  message: messageHex,
  signature: sig,
});

Derive account from private key (on-chain lookup)

从私钥派生账户（链上查询）

When the same key may have multiple on-chain accounts (e.g. after rotation), use internal derivation + lookup:

typescript

// Returns list of accounts owned by this key on chain
const accounts = await aptos.deriveOwnedAccountsFromSigner({
  signer: account,
});
// Prefer wallet or explicit address for production; this is for scripts/tooling

当同一密钥可能对应多个链上账户时（如密钥轮换后），使用内部派生+查询：

typescript

// 返回该密钥在链上拥有的所有账户列表
const accounts = await aptos.deriveOwnedAccountsFromSigner({
  signer: account,
});
// 生产环境优先使用钱包或显式地址；此方法仅适用于脚本/工具

Common mistakes

常见错误

Mistake	Correct approach
Using `Account.generate()` in frontend	Use wallet adapter; generate only in server/script
Hardcoding private key	Load from `process.env` (server) and never commit
Using `aptos.account` as signer	`aptos.account` is API namespace; signer is `Account.fromPrivateKey()` / `Account.generate()`
Expecting account to exist on-chain after generate	Fund with faucet or transfer first

错误做法	正确做法
在前端使用 `Account.generate()`	使用钱包适配器；仅在服务器/脚本中生成账户
硬编码私钥	从 `process.env` 加载（服务器环境）且绝不提交到仓库
将 `aptos.account` 作为签名者使用	`aptos.account` 是API命名空间；签名者需使用 `Account.fromPrivateKey()` / `Account.generate()`
认为生成Account后链上账户就已存在	需先通过水龙头或转账为其充值

References

参考资料

SDK:

src/account/Account.ts

src/account/Ed25519Account.ts

src/account/AccountUtils.ts

src/api/account.ts

Pattern: TYPESCRIPT_SDK.md
Related: ts-sdk-client, ts-sdk-transactions, use-ts-sdk

SDK源码：

src/account/Account.ts

src/account/Ed25519Account.ts

src/account/AccountUtils.ts

src/api/account.ts

模式文档：TYPESCRIPT_SDK.md
相关文档：ts-sdk-client, ts-sdk-transactions, use-ts-sdk