ts-sdk-address

TypeScript SDK：AccountAddress

用途

指导在 @aptos-labs/ts-sdk 中正确创建、解析和格式化账户地址。地址是 32 字节的值；字符串格式遵循 AIP-40。

始终

1. 灵活处理输入时使用 AccountAddress.from()——接受字符串（带或不带 0x）、Uint8Array 或现有的 AccountAddress。
2. 在 API 中使用 AccountAddress 或字符串表示地址——大多数 API 都接受 AccountAddressInput（字符串或 AccountAddress）。
3. 需要严格遵循 AIP-40 时使用 AccountAddress.fromStringStrict() / AccountAddress.fromStrict()：LONG（0x + 64 个十六进制字符），或者仅对特殊地址使用 SHORT（0x0–0xf）。
4. 使用 SDK 提供的派生地址辅助函数来获取对象、资源和代币地址——不要自行编写哈希逻辑。

切勿

1. 不要直接比较原始字符串——使用 addr.equals(other)，或通过 AccountAddress.from() 进行规范化。
2. 不要假定非特殊地址可以使用 SHORT 格式——严格模式下，非特殊地址必须使用 LONG 格式（64 个十六进制字符）。
3. 不要对账户地址使用 Hex 类——仅使用 AccountAddress（请遵循 SDK 文档）。

---

地址格式（AIP-40）

• **长度：**32 字节（LONG 格式为 64 个十六进制字符）。
• **字符串：**必须以 0x 开头。LONG = 0x + 64 个十六进制字符；SHORT = 最短形式（例如 0x1、0xf）。
• 特殊地址：0x0–0xf（最后一个字节 < 16，其余字节均为零）。这些地址可以使用 SHORT 格式（0x1、0xa）。
• 参考：AIP-40。

---

创建 AccountAddress

从字符串创建（推荐：宽松模式）

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

// Relaxed: accepts with or without 0x, SHORT or LONG
const addr1 = AccountAddress.from("0x1");
const addr2 = AccountAddress.from("0xaa86fe99004361f747f91342ca13c426ca0cccb0c1217677180c9493bad6ef0c");
const addr3 = AccountAddress.from("1"); // no 0x ok

从字符串创建（严格遵循 AIP-40）

// Strict: LONG (0x + 64 chars) or SHORT only for special (0x0–0xf)
const addrStrict = AccountAddress.fromStringStrict(
  "0x0000000000000000000000000000000000000000000000000000000000000001"
);
// Or use fromStrict for any AccountAddressInput
const a = AccountAddress.fromStrict("0x1"); // ok: special address in SHORT form

从字节创建

const bytes = new Uint8Array(32);
bytes[31] = 1;
const addr = new AccountAddress(bytes);
// or
const addrFrom = AccountAddress.from(bytes);

内置常量

AccountAddress.ZERO; // 0x0
AccountAddress.ONE; // 0x1
AccountAddress.TWO; // 0x2
AccountAddress.THREE; // 0x3
AccountAddress.FOUR; // 0x4
AccountAddress.A; // 0xa

---

字符串输出

方法	使用场景
addr.toString()	AIP-40 默认格式：特殊地址使用 SHORT，其他地址使用 LONG
addr.toStringLong()	始终输出 0x + 64 个十六进制字符
addr.toStringShort()	最短形式（不含前导零）
addr.toStringLongWithoutPrefix()	64 个十六进制字符，不含 0x

const addr = AccountAddress.from("0x1");
addr.toString(); // "0x1"
addr.toStringLong(); // "0x0000...0001" (64 chars after 0x)

---

验证

const result = AccountAddress.isValid({
  input: "0x1",
  strict: false
});
if (result.valid) {
  // use address
} else {
  console.log(result.invalidReason, result.invalidReasonMessage);
}

---

派生地址（对象／资源／代币／用户派生）

从 @aptos-labs/ts-sdk（通过 core）导入：

import {
  AccountAddress,
  createObjectAddress,
  createResourceAddress,
  createTokenAddress,
  createUserDerivedObjectAddress
} from "@aptos-labs/ts-sdk";

对象地址（例如，命名对象）

const creator = AccountAddress.from("0x120e79e45d21ef439963580c77a023e2729db799e96e61f878fac98fde5b9cc9");
const seed = "migration::migration_contract"; // or Uint8Array
const objectAddr = createObjectAddress(creator, seed);
// objectAddr.toString() => deterministic 0x... address

资源账户地址

const creator = AccountAddress.from("0x41e724e1d4fce6472ffcb5c9886770893eb49489e3f531d0aa97bf951e66d70c");
const seed = "create_resource::create_resource";
const resourceAddr = createResourceAddress(creator, seed);

代币（NFT）对象地址

const creator = AccountAddress.from("0x9d518b9b84f327eafc5f6632200ea224a818a935ffd6be5d78ada250bbc44a6");
const collectionName = "SuperV Villains";
const tokenName = "Nami #5962";
const tokenAddr = createTokenAddress(creator, collectionName, tokenName);
// Internally: seed = `${collectionName}::${tokenName}` -> createObjectAddress(creator, seed)

用户派生对象地址

const sourceAddress = AccountAddress.from("0x653a60dab27fe8f3859414973d218e1b7551c778a8650a7055a85c0f8041b2a4");
const deriveFromAddress = AccountAddress.from("0xa");
const userDerivedAddr = createUserDerivedObjectAddress(sourceAddress, deriveFromAddress);

---

相等性和序列化

const a = AccountAddress.from("0x1");
const b = AccountAddress.from("0x0000000000000000000000000000000000000000000000000000000000000001");
a.equals(b); // true

// BCS: use serializer or SDK entry/script helpers in transaction building

---

常见错误

错误	正确做法
对账户地址使用 Hex	仅使用 AccountAddress
使用 === 比较字符串	使用 addr1.equals(addr2)，或通过 AccountAddress.from() 规范化后再比较
在严格模式下对非特殊地址使用 SHORT	使用 LONG（0x + 64 个十六进制字符），或使用 AccountAddress.from()（宽松模式）
自行编写对象地址哈希逻辑	使用 createObjectAddress / createTokenAddress / createResourceAddress / createUserDerivedObjectAddress

---

参考

• SDK：src/core/accountAddress.ts、src/core/account/utils/address.ts
• AIP-40：https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-40.md
• 模式：TYPESCRIPT_SDK.md