# BCS（二进制规范序列化）技能 ## 概述 BCS（Binary Canonical Serialization）是一种专为 Move 编程语言设计的二进制序列化格式，广泛应用于 Sui 区块链生态系统中。 Sui TypeScript SDK 提供了类型安全、高效的序列化系统，支持原始类型、复合类型和 Sui 特定类型。 ## 快速入门 ### 安装和导入 // 从 @mysten/sui 导入 BCS（包括特定于 Sui 的类型）从 '@mysten/sui/bcs' 导入 { bcs }； // 或者从 @mysten/bcs 导入基础 BCS 从 '@mysten/bcs' 导入 { bcs }； ### 基本序列化示例从 '@mysten/sui/bcs' 导入 { bcs }； // 序列化原始类型 const u32Bytes = bcs.u32().serialize(42).toBytes(); const stringBytes = bcs.string().serialize("hello").toBytes(); // 反序列化 const 值 = bcs.u32().parse(u32Bytes); const text = bcs.string().parse(stringBytes); // 使用 Sui 特定类型 const addressBytes = bcs.Address.serialize('0x0000...0000'); const 地址 = bcs.Address.parse(addressBytes); ## 核心组件 ### BCS 类型系统 BCS 类型系统构建在“BcsType”泛型类之上： * **类型安全**：编译时和运行时类型检查 * **转换支持**：输入/输出类型转换 * **惰性求值** ：支持递归类型定义 * **验证** ：运行时数据验证 ### BcsType 基类 **位置**：`https://github.com/MystenLabs/ts-sdks/tree/main/packages/bcs/src/bcs-type.ts` `BcsType` 是所有 BCS 类型的抽象基类，提供： * 序列化/反序列化操作 * 类型验证和转换 * 基本编码支持（Base58、Base64、Hex） * 序列化尺寸计算 ### BCS 工厂方法 **位置**：`https://github.com/MystenLabs/ts-sdks/tree/main/packages/bcs/src/bcs.ts` 工厂方法创建各种 BCS 类型： * **基本类型**：u8、u16、u32、u64、u128、u256、bool、string * **复合类型**：结构体、枚举、元组、向量、映射、选项 * **特殊类型** ：固定数组、字节向量、LEB128编码 ### 读取器/写入器组件 * **BcsReader** ：读取二进制数据 * **BcsWriter** : 写入二进制数据 * **SerializedBcs** ：序列化数据的包装器，提供编码方法 ## 原始类型有关原始类型（包括整数、布尔值和字符串）的详细信息，请参阅[原始类型]()。 BCS 支持以下原语类型： * **整数类型**：u8、u16、u32、u64、u128、u256、uleb128（可变长度） * **布尔类型** : bool * **字符串类型** ：带有 LEB128 长度前缀的 UTF-8 编码字符串 ### 基本用法 // 整数序列化 const u32Bytes = bcs.u32().serialize(42).toBytes(); // 布尔序列化 const boolBytes = bcs.bool().serialize(true).toBytes(); // 字符串序列化 const stringBytes = bcs.string().serialize("Hello").toBytes(); ## 复合类型有关复合类型（包括结构体、枚举、向量、元组、选项和映射）的全面介绍，请参阅复合类型。 BCS 提供以下复合类型： ### 结构将相关字段组织成命名结构。 const Person = bcs.struct('Person', { 名称：bcs.string(), 年龄：bcs.u8(), 余额：bcs.u64(), }); ### 枚举使用可选的关联数据定义变体类型。 const Status = bcs.enum('状态', { 待处理：空，活动：bcs.u64(), 不活动：bcs.string(), }); ###向量同质元素的集合。 const NumberVector = bcs.vector(bcs.u32()); ### 元组固定大小的异构元素集合。 const Pair = bcs.tuple([bcs.string(), bcs.u64()]); ### 选项可选值（部分/无模式）。 constOptionalNumber = bcs.option(bcs.u64()); ### 地图键值映射。 const StringToNumberMap = bcs.map(bcs.string(), bcs.u32()); ## 特定类型有关 Sui 区块链特定类型（包括地址、对象引用、交易类型和 Move 类型）的详细信息，请参阅 [Sui 特定类型]()。 Sui 使用区块链特定类型扩展了基础 BCS： ### 地址类型带验证的 32 字节区块链地址。 bcs.Address.serialize('0x123...'); ### 对象引用类型对 Sui 对象的引用（拥有、共享、接收）。 bcs.SuiObjectRef.serialize(objectRef); bcs.SharedObjectRef.serialize(sharedObjectRef); ### 交易相关类型交易数据、种类和气体配置。 bcs.TransactionData.serialize(transactionData); bcs.GasData.serialize(gasData); ### 密钥和签名类型用于交易授权的加密类型。 bcs.PublicKey.serialize(publicKeyBytes); bcs.MultiSig.serialize(multiSigData); ### 移动类型移动编程语言类型系统表示。 bcs.TypeTag.serialize(typeTag); bcs.StructTag.serialize(structTag); ## 序列化模式有关序列化模式的综合示例（包括基本操作、复杂数据结构和递归类型），请参阅序列化模式。 ### 基本模式 * 直接序列化为字节 * 编码为十六进制、base64、base58 * 从编码字符串解析 const 序列化 = bcs.u32().serialize(42); const hex = serialized.toHex(); const 值 = bcs.u32().parseFromHex(hex); ### 复杂结构定义并序列化分层数据结构。 const Account = bcs.struct('帐户', { 地址：bcs.string(), 余额：bcs.u64(), 交易：bcs.vector(交易), }); ### 递归类型通过惰性求值处理自引用数据结构。 const TreeNode = bcs.struct('TreeNode', { 值：bcs.u64(), 孩子：bcs.lazy(() => bcs.vector(TreeNode)), }); ## 转型支持有关类型转换、验证模式和链式转换的详细示例，请参阅[转换支持]()。 ### 类型转换在序列化/反序列化期间在不同数据表示形式之间进行转换。 const StringNumber = bcs.string().transform({ 输入：（val：数字）=> val.toString（），输出：（val：字符串）=> parseInt（val）， }); ### 验证转换添加数据验证逻辑以确保数据完整性。 const PositiveNumber = bcs.u32().transform({ 输入：（val：数字）=> { if (val <= 0) throw new Error('值必须为正'); 返回值； }, 输出：（val：数字）=> val， }); ### 链式变换组合多种转换以进行复杂的数据处理。 const ProcessedString = bcs.string() .transform({ /* 修剪 */ }) .transform({ /* 大写 */ }); ## 性能考虑因素有关大小预测、零拷贝操作和缓存等详细性能优化策略，请参阅[性能注意事项]()。 ### 尺寸预测在实际序列化之前估计序列化大小。 const size = schema.serializedSize(data); ### 零拷贝操作最大限度地减少数据复制以获得更好的性能。 const ByteVectorType = bcs.byteVector(); const 序列化 = ByteVectorType.serialize(existingBuffer); ### 缓存优化重用类型实例和缓冲区。 const PersonType = bcs.struct('Person', { /* 字段 */ }); // 跨多个序列化重用 ## 与交易集成有关 BCS 与 Sui 事务集成的完整示例，包括参数序列化、事务数据处理和对象引用，请参阅[与事务集成]()。 ### 在交易中使用BCS 序列化事务参数的自定义类型。 const tx = 新交易(); tx.moveCall({ 目标：'0x2::示例::函数'，参数：[ tx.pure(bcs.U64.序列化(100n)), tx.pure.address('0xaddress'), ], }); ### 交易数据序列化序列化完整的交易数据以供签名和提交。 const serializedTxData = bcs.TransactionData.serialize(transactionData); ### 对象参数类型序列化不同类型的对象引用。 bcs.ObjectArg.serialize(objectArg); ## 自定义 BCS 类型有关创建自定义 BCS 类型、扩展现有类型和类型注册的详细指南，请参阅[自定义 BCS 类型]()。 ### 创建自定义类型为专门的数据格式实现自定义序列化逻辑。 const CustomType = new BcsType({ name: '自定义类型', read: (reader) => { /* 反序列化 */ }, write: (value, writer) => { /* 序列化 */ }, }); ### 扩展现有类型使用转换将自定义行为添加到内置类型。 const 增强型 U32 = bcs.u32().transform({ 输入：(val) => val * 2, 输出：(val) => val / 2, }); ### 类型注册注册特定于应用程序的类型以供重用。 bcs.registerStructType('用户', { id: '地址', 名称：'字符串'，年龄：'u8'， }); ## 工作流程有关完整的工作流程示例，包括 Sui 对象序列化、事务验证和自定义类型注册，请参阅[工作流程]()。 ### 常见工作流程 * **Sui Object Serialization** ：序列化和反序列化区块链对象 * **交易数据验证** ：使用 BCS 验证交易格式 * **自定义类型注册** ：注册特定于应用程序的类型 * **批处理** ：高效处理多个操作 * **错误处理**：优雅的错误恢复模式 ### 示例：交易验证函数 validateTransactionData（数据：任意）：布尔值 { 尝试{ bcs.TransactionData.serialize(数据); 返回真； } 抓住 { 返回假； } } ### 示例：类型注册函数registerAppTypes() { bcs.registerStructType('用户', { id: '地址', 名称：'字符串'，年龄：'u8'， }); } ## 最佳实践有关类型安全、性能优化、兼容性和安全性的全面最佳实践，请参阅[最佳实践]()。 ### 主要建议 * **类型安全**：使用 TypeScript 接口和运行时验证 * **性能**：重用类型实例并预测大小 * **兼容性** ：添加版本字段并保持向后兼容性 * **安全性**：验证输入并强制执行大小限制 * **文档** ：记录模式并提供使用示例 ### 基本实践 1. 在序列化之前始终验证外部输入 2.使用TypeScript进行编译时类型检查 3. 实施适当的错误处理和恢复 4. 测试序列化/反序列化往返 5. 文档数据格式和版本控制策略 ## 参考文件有关特定主题的详细信息，请参阅“reference/”目录中的以下文件： * **[Primitive Types]()** ：整数、布尔和字符串类型 * **[复合类型]()**：结构、枚举、向量、元组、选项和映射 * **[Sui-Specific Types]()** ：地址、对象引用、交易类型和移动类型 * **[序列化模式]()**：基本和复杂的序列化模式，递归类型 * **[转换支持]()**：类型转换、验证和链式转换 * **[性能注意事项]()**：大小预测、零拷贝操作、缓存和优化 * **[与交易集成]()** : Sui 交易中的 BCS 使用，参数序列化 * **[自定义 BCS 类型]()** ：创建自定义类型、扩展现有类型、类型注册 * **[工作流程]()**：完整的工作流程示例和模式 * **[最佳实践]()**：类型安全、性能、兼容性和安全指南 ## 相关技能 * [sui-transaction-building](): 了解 BCS 在交易构建中的使用 * [sui-keypair-cryptography]()：了解公钥和签名的 BCS 序列化 ## 参考文献 * **官方文档**： * **源代码**：`https://github.com/MystenLabs/ts-sdks/tree/main/packages/bcs/src/`和`https://github.com/MystenLabs/ts-sdks/tree/main/packages/typescript/src/bcs/` * **测试用例**：`https://github.com/MystenLabs/ts-sdks/tree/main/packages/bcs/tests/` * **TypeScript 类型定义** : `https://github.com/MystenLabs/ts-sdks/tree/main/packages/bcs/src/types.ts` ** ** _该技能帮助 Claude Code 理解 Sui BCS 序列化，提供实用的代码示例和使用指南。当用户需要处理Sui区块链数据序列化时，参考该技能可以提供准确的TypeScript代码和最佳实践。_

隋BC

包含技能