TypeScript SDK: AccountAddress

目的

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

始终遵循

1. 1. 使用 AccountAddress.from() 进行灵活输入 – 接受字符串（带或不带 0x）、Uint8Array 或现有的 AccountAddress。
2. 在API中将地址作为 AccountAddress 或字符串使用 – SDK在大多数API中接受 AccountAddressInput（字符串或 AccountAddress）。
3. 在需要AIP-40严格模式时使用 AccountAddress.fromStringStrict() / AccountAddress.fromStrict()：LONG（0x + 64个十六进制字符）或仅特殊地址使用SHORT（0x0–0xf）。
4. 使用SDK提供的派生地址辅助函数处理对象/资源/代币地址 – 不要手动实现哈希。

绝对禁止

1. 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

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

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

// 宽松模式：接受带或不带0x，SHORT或LONG格式
const addr1 = AccountAddress.from(0x1);
const addr2 = AccountAddress.from(0xaa86fe99004361f747f91342ca13c426ca0cccb0c1217677180c9493bad6ef0c);
const addr3 = AccountAddress.from(1); // 不带0x也可以

从字符串创建（严格AIP-40模式）

typescript
// 严格模式：LONG（0x + 64个字符）或仅特殊地址使用SHORT（0x0–0xf）
const addrStrict = AccountAddress.fromStringStrict(
0x0000000000000000000000000000000000000000000000000000000000000001
);
// 或者使用fromStrict处理任何AccountAddressInput
const a = AccountAddress.fromStrict(0x1); // 可以：特殊地址使用SHORT格式

从字节创建

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

内置常量

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

typescript
const addr = AccountAddress.from(0x1);
addr.toString(); // 0x1
addr.toStringLong(); // 0x0000...0001（0x后64个字符）

---

验证

typescript
const result = AccountAddress.isValid({
input: 0x1,
strict: false
});
if (result.valid) {
// 使用地址
} else {
console.log(result.invalidReason, result.invalidReasonMessage);
}

---

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

从 @aptos-labs/ts-sdk 导入（通过核心模块）：

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

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

typescript
const creator = AccountAddress.from(0x120e79e45d21ef439963580c77a023e2729db799e96e61f878fac98fde5b9cc9);
const seed = migration::migration_contract; // 或 Uint8Array
const objectAddr = createObjectAddress(creator, seed);
// objectAddr.toString() => 确定性的 0x... 地址

资源账户地址

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

代币（NFT）对象地址

typescript
const creator = AccountAddress.from(0x9d518b9b84f327eafc5f6632200ea224a818a935ffd6be5d78ada250bbc44a6);
const collectionName = SuperV Villains;
const tokenName = Nami #5962;
const tokenAddr = createTokenAddress(creator, collectionName, tokenName);
// 内部实现：seed = ${collectionName}::${tokenName} -> createObjectAddress(creator, seed)

用户派生对象地址

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

---

相等性和序列化

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

// BCS：在交易构建中使用序列化器或SDK入口/脚本辅助函数

---

常见错误

错误	正确方法
使用 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