ts-sdk-account

TypeScript SDK：Account（签名者）

用途

介绍如何在 @aptos-labs/ts-sdk 中创建和使用 Account（签名者）。Account 包含地址和密钥材料，可用于对交易和消息签名。创建 Account 并不会在链上创建账户；请使用水龙头或转账为其注资。

务必

1. 仅在服务端或脚本中使用 Account.generate() 或 Account.fromPrivateKey()——切勿在前端使用；面向最终用户时请使用钱包适配器。
2. 在服务端从环境变量加载私钥（例如 process.env.PRIVATE_KEY）——切勿硬编码。
3. 构建交易时使用 account.accountAddress——将其作为发送者或次要签名者传入。
4. 使用 aptos.signAndSubmitTransaction({ signer: account, transaction })，并确保使用持有该密钥的同一个 Account 实例。

切勿

1. 不要在浏览器或前端使用 Account.generate() 或原始私钥——请使用钱包适配器。
2. 不要在源代码中硬编码私钥，也不要将其提交到 Git。
3. 不要混淆 Account（API 命名空间）和 Account（签名者类）——API 为 aptos.account.*；签名者是 Account 模块中的类（例如 Account.fromPrivateKey）。

---

Account 类型（签名方案）

类型	类	用途
Ed25519（旧版）	Ed25519Account	单个 Ed25519 密钥，旧版身份验证
SingleKey	SingleKeyAccount	Ed25519 或 Secp256k1，统一身份验证
MultiKey	MultiKeyAccount	多重签名
Keyless	KeylessAccount	无密钥（例如 OIDC）
Federated Keyless	FederatedKeylessAccount	联合无密钥

---

生成新账户（仅限服务端或脚本）

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;

---

从私钥创建

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..."
});

---

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

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
});

---

身份验证密钥（用于轮换或查找）

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

---

序列化（toHex / fromHex）

在持久化或发送账户时使用（例如，仅限服务端；切勿向前端暴露私钥）：

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);

---

签名

// 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);

---

验证签名

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
});

---

根据私钥派生账户（链上查找）

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

// 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

---

常见错误

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

---

参考

• 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