Aptos Core Protos 指南protobuf 定义、代码生成与签名消息结构全解析【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-coreAptos 作为一条 layer 1 区块链其链上交易、事件、索引器数据等跨语言服务通信全部依赖 Protocol Buffers 完成。protos/目录是 Aptos 所有服务的 protobuf 定义与多语言生成代码的单一集散地本文以 protos/README.md 为主线结合仓库内的.proto源文件、buf 配置与生成脚本完整讲解该目录的职责划分、构建流程、核心消息结构尤其是交易签名体系帮助读者在 Rust / Python / TypeScript 中正确消费 Aptos 链上数据并能自行更新 proto 后重新生成各语言代码。目录定位为什么把 proto 与生成代码放在一起从仓库结构看protos/目录同时包含三部分内容proto 源定义位于 protos/proto/ 下的*.proto文件多语言生成代码Rustprotos/rust/、Pythonprotos/python/、TypeScriptprotos/typescript/三套由 buf / protoc 生成的代码生成脚本与 buf 配置protos/scripts/、protos/buf.work.yaml、protos/buf.rust.gen.yaml、protos/buf.ts.gen.yaml。README 明确解释了这种集中式布局的动机为了简化发布流程并尽可能避免版本冲突Aptos 将所有 proto 定义及其生成代码放在同一个地方。这意味着修改 proto 后只需运行一次生成脚本Rust / Python / TypeScript 三份代码会同步更新避免各语言各自维护一份 proto 副本而导致的漂移。proto 的顶层包组织遵循aptos.模块.版本命名规范源文件按模块分层protos/proto/aptos/ ├── indexer/ v1: filter.proto / grpc.proto / raw_data.proto ├── internal/ fullnode/v1: fullnode_data.proto ├── remote_executor/ v1: network_msg.proto ├── transaction/ v1: transaction.proto └── util/ timestamp: timestamp.proto其中 protos/proto/aptos/transaction/v1/transaction.proto 是数据模型的核心其余文件围绕它提供索引器indexer、全节点内部通信internal/fullnode、远程执行remote_executor和通用时间戳util/timestamp等能力。构建工具链buf protoc 与各语言插件生成多语言代码依赖统一的 buf 工具链。README 强调macOS 上可用 Homebrew 安装 bufbrew install bufbuild/buf/buf关键提示是buf 版本必须与 CI 保持一致。README 指出如果生成代码后出现意外的 diff应检查本地 buf 版本是否与 CI仓库根目录下的.github/workflows/check-protos.yaml工作流中使用的版本一致——Aptos 在 CI 中专门设置了 protos 检查步骤用于校验生成代码与 proto 定义是否同步、是否有意外变更。因此本地开发时保证 buf 版本与 CI 对齐是避免我什么都没改代码却变了这类困惑的第一道防线。一键生成build_protos.sh修改 protos/proto/ 下的定义后在protos/目录运行 protos/scripts/build_protos.sh 即可为所有语言重新生成代码./scripts/build_protos.sh该脚本内部逻辑见 protos/scripts/build_protos.sh依次完成前置依赖检查依次确认pre-commit、buf、poetry均已安装缺失时给出对应安装命令并退出Rust 与 TypeScript 生成遍历目录下所有*.gen.yaml模板跳过 python 相关模板执行buf generate --template filePython 生成README 和脚本注释解释了原因——目前没有便捷方式直接用 buf 生成 Python 代码避免引入远程 registry 或从源码编译 grpc因此切换到 Python 工具链即grpc_tools.protoc。脚本进入python/目录执行poetry install与poetry run poe generatepre-commit 收尾运行pre-commit run --all-files失败不阻断|| true保证生成结果符合仓库的 lint/format 规范。首次搭建install_deps.sh如果尚未安装依赖从protos/目录运行 protos/scripts/install_deps.sh./scripts/install_deps.sh该脚本假定cargo、pnpm、poetry、buf、protoc已就绪然后安装 Rust 侧生成所需的插件均使用--locked固定版本protoc-gen-prost0.4.0生成 Rust 结构体protoc-gen-prost-serde0.2.3为生成结构体补充 serde 序列化支持protoc-gen-prost-crate0.3.1生成 crate 级别的模块组织protoc-gen-tonic0.4.1生成 tonic gRPC 服务代码。而 TypeScript 的插件则无需手动安装——注释说明它们直接从 buf.build 社区插件注册表自动拉取对应 protos/buf.ts.gen.yaml 中声明的buf.build/community/stephenh-ts-proto:v1.167.9。最后同样通过poetry install安装 Python 侧依赖。buf 配置工作区、lint 与 breaking 检查protos/buf.work.yaml 定义 buf 工作区声明唯一的 proto 目录version: v1 directories: - protoprotos/proto/buf.yaml 则配置每个 proto 包的质量门槛version: v1 # detect breaking changes breaking: use: - FILE lint: use: - DEFAULT ignore_only: PACKAGE_VERSION_SUFFIX: - aptos/util/timestamp/timestamp.proto SERVICE_SUFFIX: - aptos/indexer/v1/raw_data.proto - aptos/internal/fullnode/v1/fullnode_data.proto RPC_RESPONSE_STANDARD_NAME: - aptos/indexer/v1/raw_data.proto - aptos/internal/fullnode/v1/fullnode_data.protobreaking 检查采用FILE级别的破坏性变更检测任何对现有字段的删除、类型修改或编号复用都会在 CI/本地 buf 检查中被拦截lint 检查使用DEFAULT规则集并对少数包做了ignore_only豁免注释给出了原因——timestamp.proto已被广泛采用不便改动包名后缀raw_data.proto与fullnode_data.proto中ServiceService式命名和复用响应消息RPC_RESPONSE_STANDARD_NAME属于有意设计故豁免相应规则。Rust 与 TypeScript 的生成模板protos/buf.rust.gen.yaml 开启managed模式由 buf 统一管理文件级选项与依赖依次应用四个插件输出到rust/src/pb/其中 prost 插件额外开启file_descriptor_set选项保留 FileDescriptorSet便于反射与序列化场景version: v1 managed: enabled: true plugins: - name: prost out: rust/src/pb/ opt: - file_descriptor_set - name: prost-serde out: rust/src/pb/ - name: prost-crate out: rust/src/pb/ strategy: all opt: - no_features - name: tonic out: rust/src/pb/protos/buf.ts.gen.yaml 使用 ts-proto 插件版本固定为 v1.167.9输出到typescript/src关键选项包括outputServicesgrpc-js生成 grpc/grpc-js 风格服务、forceLongbigint64 位整数用 BigInt 表示与 proto 中大量jstype JS_STRING的声明互补、useOptionalsall可选字段以可选类型呈现、useAsyncIterabletrue流式 RPC 使用 AsyncIterable、useMapTypetrue、useExactTypesfalse等生成时还开启outputIndextrue自动产出 index 聚合文件。核心数据模型transaction/v1/transaction.protoprotos/proto/aptos/transaction/v1/transaction.proto 定义了链上交易及其关联类型的完整投影是索引器、SDK 与各种下游消费端的数据基础。下面按层次拆解。Block区块的顶层容器Block消息是链上数据的入口一个区块按version单调递增的顺序容纳交易每个区块都以BlockMetadataTransaction开头其后跟随零个或多个交易直到下一个BlockMetadataTransaction为止。字段包括timestamp取自区块的BlockMetadataTransaction创世区块则为GenesisTransaction区块内所有交易共享同一时间戳height区块高度严格单调递增且无空号是区块的唯一标识uint64标注jstype JS_STRING便于 JS 生态安全表示transactions区块内全部交易chain_id标识来源链防止多链数据在同一个处理管道中被混淆。Transaction五种交易类型Transaction消息通过oneof txn_data区分交易种类TransactionType枚举取值如下enum TransactionType { TRANSACTION_TYPE_UNSPECIFIED 0; TRANSACTION_TYPE_GENESIS 1; TRANSACTION_TYPE_BLOCK_METADATA 2; TRANSACTION_TYPE_STATE_CHECKPOINT 3; TRANSACTION_TYPE_USER 4; // values 5-19 skipped for no reason TRANSACTION_TYPE_VALIDATOR 20; TRANSACTION_TYPE_BLOCK_EPILOGUE 21; }每个交易携带timestamp、version、epoch、block_height均含jstype JS_STRING标注、TransactionInfo info以及size_info大小信息。五种类型分别由BlockMetadataTransaction区块元数据、GenesisTransaction创世携带WriteSet与事件、StateCheckpointTransaction状态检查点空消息体、UserTransaction用户交易含请求与事件列表和ValidatorTransaction验证者交易包含ObservedJwkUpdate与DkgUpdate两类负载承载。TransactionInfo记录交易的执行结果hash、state_change_hash、event_root_hash、state_checkpoint_hash、gas_used、success、vm_status、accumulator_root_hash以及全部WriteSetChange变更列表是审计与回放链上状态的关键数据。用户交易与 PayloadUserTransactionRequest描述用户提交的原始请求sender、sequence_number、max_gas_amount、gas_unit_price、expiration_timestamp_secs复用aptos.util.timestamp.Timestamp、payload与signature。TransactionPayload支持五类负载enum Type { TYPE_UNSPECIFIED 0; TYPE_ENTRY_FUNCTION_PAYLOAD 1; // 入口函数 TYPE_SCRIPT_PAYLOAD 2; // Move 脚本 TYPE_WRITE_SET_PAYLOAD 4; // 写集 TYPE_MULTISIG_PAYLOAD 5; // 多签 TYPE_ENCRYPTED_TRANSACTION_PAYLOAD 6; // 加密交易 reserved 3; }EntryFunctionPayload由EntryFunctionId模块 函数名、泛型类型参数与字符串化参数组成并附带entry_function_id_str便于直接展示ScriptPayload携带MoveScriptBytecode字节码与 ABIMultisigPayload指向多签地址及可选的内部负载EncryptedTransactionPayload区分解密失败FailedDecryptionPayloadState与解密成功DecryptedPayloadState两种状态。ExtraConfigV1额外提供multisig_address与replay_protection_nonce防重放随机数两个可选配置项。WriteSet 与状态变更WriteSetChange覆盖六种链上状态变更删除/写入 Module、删除/写入 Resource、删除/写入 TableItem。例如WriteResource记录address、state_key_hash、MoveStructTag type、type_str与 JSON 字符串形式的dataWriteTableItem通过handlekey定位表项WriteTableData则保存key、key_type、value、value_type四元组。DirectWriteSet聚合所有变更与事件ScriptWriteSet则指定execute_as与脚本负载。Move 类型系统投影为让下游无需运行 Move VM 也能理解交易语义proto 完整投影了 Move 的类型体系MoveTypes枚举覆盖 bool、u8/u16/u32/u64/u128/u256、i8~i256、address、signer、vector、struct、泛型参数、引用reference与 unparsableMoveType通过oneof content承载 vector、struct、泛型下标、引用和无法解析的字符串MoveModule/MoveFunction/MoveStruct描述模块 ABI包括函数可见性Visibilityprivate/public/friend、is_entry、泛型参数约束、结构体字段、is_native、is_event、is_enum以及枚举变体MoveStructVariantMoveAbility枚举对应 Move 的 copy/drop/store/key 能力。交易签名体系从根签名到任意密钥README 的核心章节用一张 UML 类图完整刻画了transaction.proto中的签名消息结构这是理解 Aptos 账户模型与多签/代理支付机制的关键。下面将该结构原样展开UML 源见 protos/README.md并对照 proto 源码逐一说明。startuml SignatureStructure Root Signature message class Signature { Type type .. oneof signature .. Ed25519Signature ed25519 MultiEd25519Signature multi_ed25519 MultiAgentSignature multi_agent FeePayerSignature fee_payer SingleSender single_sender } enum Signature::Type { TYPE_UNSPECIFIED 0 TYPE_ED25519 1 TYPE_MULTI_ED25519 2 TYPE_MULTI_AGENT 3 TYPE_FEE_PAYER 4 TYPE_SINGLE_SENDER 6 } Ed25519Signature class Ed25519Signature { bytes public_key bytes signature } MultiEd25519Signature class MultiEd25519Signature { repeated bytes public_keys repeated bytes signatures uint32 threshold repeated uint32 public_key_indices } MultiAgentSignature class MultiAgentSignature { AccountSignature sender repeated string secondary_signer_addresses repeated AccountSignature secondary_signers } FeePayerSignature class FeePayerSignature { AccountSignature sender repeated string secondary_signer_addresses repeated AccountSignature secondary_signers string fee_payer_address AccountSignature fee_payer_signer } SingleSender class SingleSender { AccountSignature sender } AccountSignature class AccountSignature { Type type .. oneof signature .. Ed25519Signature ed25519 MultiEd25519Signature multi_ed25519 SingleKeySignature single_key_signature MultiKeySignature multi_key_signature AbstractionSignature abstraction } enum AccountSignature::Type { TYPE_UNSPECIFIED 0 TYPE_ED25519 1 TYPE_MULTI_ED25519 2 TYPE_SINGLE_KEY 4 TYPE_MULTI_KEY 5 TYPE_ABSTRACTION 6 } SingleKeySignature class SingleKeySignature { AnyPublicKey public_key AnySignature signature } MultiKeySignature class MultiKeySignature { repeated AnyPublicKey public_keys repeated IndexedSignature signatures uint32 signatures_required } AbstractionSignature class AbstractionSignature { string function_info bytes signature } IndexedSignature class IndexedSignature { uint32 index AnySignature signature } AnyPublicKey class AnyPublicKey { Type type bytes public_key } enum AnyPublicKey::Type { TYPE_UNSPECIFIED 0 TYPE_ED25519 1 TYPE_SECP256K1_ECDSA 2 TYPE_SECP256R1_ECDSA 3 TYPE_KEYLESS 4 TYPE_FEDERATED_KEYLESS 5 } AnySignature class AnySignature { Type type bytes signature (deprecated) .. oneof signature_variant .. Ed25519 ed25519 Secp256k1Ecdsa secp256k1_ecdsa WebAuthn webauthn Keyless keyless } enum AnySignature::Type { TYPE_UNSPECIFIED 0 TYPE_ED25519 1 TYPE_SECP256K1_ECDSA 2 TYPE_WEBAUTHN 3 TYPE_KEYLESS 4 } class Ed25519 { bytes signature } class Secp256k1Ecdsa { bytes signature } class WebAuthn { bytes signature } class Keyless { bytes signature } Associations Signature -- Ed25519Signature Signature -- MultiEd25519Signature Signature -- MultiAgentSignature Signature -- FeePayerSignature Signature -- SingleSender MultiAgentSignature -- AccountSignature FeePayerSignature -- AccountSignature SingleSender -- AccountSignature AccountSignature -- Ed25519Signature AccountSignature -- MultiEd25519Signature AccountSignature -- SingleKeySignature AccountSignature -- MultiKeySignature AccountSignature -- AbstractionSignature SingleKeySignature -- AnyPublicKey SingleKeySignature -- AnySignature MultiKeySignature -- AnyPublicKey MultiKeySignature -- IndexedSignature IndexedSignature -- AnySignature AnySignature -- Ed25519 AnySignature -- Secp256k1Ecdsa AnySignature -- WebAuthn AnySignature -- Keyless enduml对照 protos/proto/aptos/transaction/v1/transaction.proto 中 511~666 行的实现可将签名体系归纳为四层第一层交易级Signature顶层。直接挂在UserTransactionRequest.signature上通过oneof提供五种形态单 Ed25519、多 Ed25519阈值签名、多 AgentMultiAgent、代付 GasFeePayer与单发送者SingleSender。注意Signature.Type中TYPE_SINGLE_SENDER 6且reserved 5——proto 编号刻意保留避免与历史演进冲突。第二层账户级AccountSignature。MultiAgentSignature、FeePayerSignature与SingleSender内部统一收敛到AccountSignature它又分为五类ed25519、multi_ed25519、single_key_signature、multi_key_signature与abstraction账户抽象含function_info与原始signature字节。proto 中AccountSignature.Type同样保留 3 号位。第三层任意密钥体系AnyPublicKey/AnySignature。面向现代 Aptos 账户支持 secp256k1、WebAuthn、Keyless 等AnyPublicKey.Type枚举 ed25519、secp256k1-ecdsa、secp256r1-ecdsa、keyless、federated-keyless以及 proto 中新增的slh_dsa_sha2_128s。SingleKeySignature由AnyPublicKeyAnySignature组成MultiKeySignature则是公钥列表 IndexedSignature带下标、可乱序提交列表 signatures_required门槛。README 中的 UML 基于发布时的版本实际 proto 已进一步扩展。第四层AnySignature的签名变体。proto 明确标注signature字节字段自 1.10 起废弃[deprecated true]推荐使用oneof signature_variant下的强类型消息Ed25519、Secp256k1Ecdsa、WebAuthn、Keyless以及后加的SlhDsa_Sha2_128s。下游解析时应优先读取signature_variant仅对旧版本数据回退到裸字节字段。索引器与流式服务indexer/v1Aptos 索引器通过 gRPC 对外提供链上交易流相关定义集中在 protos/proto/aptos/indexer/v1/。raw_data.proto流式拉取protos/proto/aptos/indexer/v1/raw_data.proto 定义数据面的核心 RPCservice RawData { rpc GetTransactions(GetTransactionsRequest) returns (stream TransactionsResponse); }GetTransactionsRequest的关键参数starting_version必填流的起始版本transactions_count可选本次流返回的交易总数缺省则无限流式推送batch_size可选每个TransactionsResponse批次的交易条数缺省 1000超过 1000 的请求会被拒绝transaction_filter可选BooleanTransactionFilter过滤条件命中才下发。TransactionsResponse除交易列表外还携带chain_id与processed_rangefirst_version/last_version便于消费端确认已处理区间、断点续传。TransactionsInStorage则标记为仅供存储使用。grpc.proto服务发现与心跳protos/proto/aptos/indexer/v1/grpc.proto 面向索引器数据服务集群的控制面定义三类服务GrpcManagerHeartbeat各节点上报ServiceInfo返回known_latest_version、GetTransactions单次拉取、GetDataServiceForRequest为用户请求路由到具体data_service_addressDataServicePing区分 live/historical 服务并回传服务信息、GetTransactions流式交易下发ServiceInfo通过oneof区分LiveDataServiceInfo/HistoricalDataServiceInfo/FullnodeInfo/GrpcManagerInfo每类都携带chain_id、timestamp、known_latest_version等健康与进度信息其中LiveDataServiceInfo.min_servable_version缺省表示服务尚未就绪。filter.proto 与 fullnode_data.protoprotos/proto/aptos/indexer/v1/filter.proto 提供BooleanTransactionFilter布尔组合的交易过滤表达式供raw_data.proto与grpc.proto引用protos/proto/aptos/internal/fullnode/v1/fullnode_data.proto 则服务于全节点内部的数据同步场景fullnode data 流与索引器 gRPC 服务共同构成 Aptos 数据出口的两条路径。remote_executor下的 network_msg.proto 面向远程执行器的网络消息。通用时间戳util/timestampprotos/proto/aptos/util/timestamp/timestamp.proto 定义了跨模块复用的Timestamp消息message Timestamp { int64 seconds 1; // UTC 秒Unix epoch 起算 int32 nanos 2; // 纳秒精度的小数部分0 ~ 999,999,999 }seconds取值限定在 0001-01-01T00:00:00Z 至 9999-12-31T23:59:59Znanos非负且向前累加。该类型被交易、区块、索引器服务信息广泛引用例如UserTransactionRequest.expiration_timestamp_secs、LiveDataServiceInfo.timestamp是全仓库时间语义的唯一来源。也正因它被广泛采用buf.yaml中特意豁免了它的PACKAGE_VERSION_SUFFIXlint 规则避免破坏既有引用。生成代码与多语言使用Rust生成代码位于 protos/rust/src/pb/按包名输出为aptos.transaction.v1.rs、aptos.indexer.v1.rs、aptos.internal.fullnode.v1.rs、aptos.remote_executor.v1.rs、aptos.util.timestamp.rs等文件并配套.serde.rsserde 序列化与.tonic.rsgRPC 服务模块crate 由prost-crate插件统一生成见 protos/rust/Cargo.toml 与 protos/rust/README.md。Pythonprotos/python/README.md 说明了用法安装后直接导入生成的类即可from aptos_protos.aptos.transaction.v1.transaction_pb2 import Transaction def parse(transaction: Transaction): # Parse the transaction. ...生成代码位于 protos/python/aptos_protos/包括transaction_pb2.py、raw_data_pb2.py、raw_data_pb2_grpc.py、fullnode_data_pb2_grpc.py等由 protos/python/pyproject.toml 管理打包protos/python/CHANGELOG.md 记录版本演进。TypeScriptprotos/typescript/src/ 下按aptos/模块/v1/*.ts组织并自动生成多层index.aptos.*.ts聚合导出文件outputIndextrue的产物。由于 proto 中 64 位字段普遍标注jstype JS_STRING且 ts-proto 配置了forceLongbigintJS/TS 侧可以安全处理超出 Number 安全范围的版本号、Gas 等大整数。版本一致性工作流小结最后回到 README 强调的两个实践要点这也是贡献者改动 proto 时的标准流程保持 buf 版本与 CI 一致出现意外 diff 时先核对本地buf --version与 CI 工作流.github/workflows/check-protos.yaml所用版本改动 proto 后执行生成在protos/目录依次运行./scripts/install_deps.sh首次与./scripts/build_protos.sh一次性同步 Rust / Python / TypeScript 三套代码再提交包含生成代码的变更确保仓库中的生成产物始终与 protos/proto/ 源定义一致。Aptos 将 proto 源、buf 配置与三语言生成代码集中收纳于protos/的设计既简化了发布、又用 CI 与 breaking 检查守住了兼容性底线而交易签名 UML 所揭示的四层消息结构则是理解 Aptos 账户抽象、多签、代付与 Keyless 等现代特性的数据基础值得所有链上数据消费端开发者细读。【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-core创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Aptos Core Protos 指南：protobuf 定义、代码生成与签名消息结构全解析
Aptos Core Protos 指南protobuf 定义、代码生成与签名消息结构全解析【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-coreAptos 作为一条 layer 1 区块链其链上交易、事件、索引器数据等跨语言服务通信全部依赖 Protocol Buffers 完成。protos/目录是 Aptos 所有服务的 protobuf 定义与多语言生成代码的单一集散地本文以 protos/README.md 为主线结合仓库内的.proto源文件、buf 配置与生成脚本完整讲解该目录的职责划分、构建流程、核心消息结构尤其是交易签名体系帮助读者在 Rust / Python / TypeScript 中正确消费 Aptos 链上数据并能自行更新 proto 后重新生成各语言代码。目录定位为什么把 proto 与生成代码放在一起从仓库结构看protos/目录同时包含三部分内容proto 源定义位于 protos/proto/ 下的*.proto文件多语言生成代码Rustprotos/rust/、Pythonprotos/python/、TypeScriptprotos/typescript/三套由 buf / protoc 生成的代码生成脚本与 buf 配置protos/scripts/、protos/buf.work.yaml、protos/buf.rust.gen.yaml、protos/buf.ts.gen.yaml。README 明确解释了这种集中式布局的动机为了简化发布流程并尽可能避免版本冲突Aptos 将所有 proto 定义及其生成代码放在同一个地方。这意味着修改 proto 后只需运行一次生成脚本Rust / Python / TypeScript 三份代码会同步更新避免各语言各自维护一份 proto 副本而导致的漂移。proto 的顶层包组织遵循aptos.模块.版本命名规范源文件按模块分层protos/proto/aptos/ ├── indexer/ v1: filter.proto / grpc.proto / raw_data.proto ├── internal/ fullnode/v1: fullnode_data.proto ├── remote_executor/ v1: network_msg.proto ├── transaction/ v1: transaction.proto └── util/ timestamp: timestamp.proto其中 protos/proto/aptos/transaction/v1/transaction.proto 是数据模型的核心其余文件围绕它提供索引器indexer、全节点内部通信internal/fullnode、远程执行remote_executor和通用时间戳util/timestamp等能力。构建工具链buf protoc 与各语言插件生成多语言代码依赖统一的 buf 工具链。README 强调macOS 上可用 Homebrew 安装 bufbrew install bufbuild/buf/buf关键提示是buf 版本必须与 CI 保持一致。README 指出如果生成代码后出现意外的 diff应检查本地 buf 版本是否与 CI仓库根目录下的.github/workflows/check-protos.yaml工作流中使用的版本一致——Aptos 在 CI 中专门设置了 protos 检查步骤用于校验生成代码与 proto 定义是否同步、是否有意外变更。因此本地开发时保证 buf 版本与 CI 对齐是避免我什么都没改代码却变了这类困惑的第一道防线。一键生成build_protos.sh修改 protos/proto/ 下的定义后在protos/目录运行 protos/scripts/build_protos.sh 即可为所有语言重新生成代码./scripts/build_protos.sh该脚本内部逻辑见 protos/scripts/build_protos.sh依次完成前置依赖检查依次确认pre-commit、buf、poetry均已安装缺失时给出对应安装命令并退出Rust 与 TypeScript 生成遍历目录下所有*.gen.yaml模板跳过 python 相关模板执行buf generate --template filePython 生成README 和脚本注释解释了原因——目前没有便捷方式直接用 buf 生成 Python 代码避免引入远程 registry 或从源码编译 grpc因此切换到 Python 工具链即grpc_tools.protoc。脚本进入python/目录执行poetry install与poetry run poe generatepre-commit 收尾运行pre-commit run --all-files失败不阻断|| true保证生成结果符合仓库的 lint/format 规范。首次搭建install_deps.sh如果尚未安装依赖从protos/目录运行 protos/scripts/install_deps.sh./scripts/install_deps.sh该脚本假定cargo、pnpm、poetry、buf、protoc已就绪然后安装 Rust 侧生成所需的插件均使用--locked固定版本protoc-gen-prost0.4.0生成 Rust 结构体protoc-gen-prost-serde0.2.3为生成结构体补充 serde 序列化支持protoc-gen-prost-crate0.3.1生成 crate 级别的模块组织protoc-gen-tonic0.4.1生成 tonic gRPC 服务代码。而 TypeScript 的插件则无需手动安装——注释说明它们直接从 buf.build 社区插件注册表自动拉取对应 protos/buf.ts.gen.yaml 中声明的buf.build/community/stephenh-ts-proto:v1.167.9。最后同样通过poetry install安装 Python 侧依赖。buf 配置工作区、lint 与 breaking 检查protos/buf.work.yaml 定义 buf 工作区声明唯一的 proto 目录version: v1 directories: - protoprotos/proto/buf.yaml 则配置每个 proto 包的质量门槛version: v1 # detect breaking changes breaking: use: - FILE lint: use: - DEFAULT ignore_only: PACKAGE_VERSION_SUFFIX: - aptos/util/timestamp/timestamp.proto SERVICE_SUFFIX: - aptos/indexer/v1/raw_data.proto - aptos/internal/fullnode/v1/fullnode_data.proto RPC_RESPONSE_STANDARD_NAME: - aptos/indexer/v1/raw_data.proto - aptos/internal/fullnode/v1/fullnode_data.protobreaking 检查采用FILE级别的破坏性变更检测任何对现有字段的删除、类型修改或编号复用都会在 CI/本地 buf 检查中被拦截lint 检查使用DEFAULT规则集并对少数包做了ignore_only豁免注释给出了原因——timestamp.proto已被广泛采用不便改动包名后缀raw_data.proto与fullnode_data.proto中ServiceService式命名和复用响应消息RPC_RESPONSE_STANDARD_NAME属于有意设计故豁免相应规则。Rust 与 TypeScript 的生成模板protos/buf.rust.gen.yaml 开启managed模式由 buf 统一管理文件级选项与依赖依次应用四个插件输出到rust/src/pb/其中 prost 插件额外开启file_descriptor_set选项保留 FileDescriptorSet便于反射与序列化场景version: v1 managed: enabled: true plugins: - name: prost out: rust/src/pb/ opt: - file_descriptor_set - name: prost-serde out: rust/src/pb/ - name: prost-crate out: rust/src/pb/ strategy: all opt: - no_features - name: tonic out: rust/src/pb/protos/buf.ts.gen.yaml 使用 ts-proto 插件版本固定为 v1.167.9输出到typescript/src关键选项包括outputServicesgrpc-js生成 grpc/grpc-js 风格服务、forceLongbigint64 位整数用 BigInt 表示与 proto 中大量jstype JS_STRING的声明互补、useOptionalsall可选字段以可选类型呈现、useAsyncIterabletrue流式 RPC 使用 AsyncIterable、useMapTypetrue、useExactTypesfalse等生成时还开启outputIndextrue自动产出 index 聚合文件。核心数据模型transaction/v1/transaction.protoprotos/proto/aptos/transaction/v1/transaction.proto 定义了链上交易及其关联类型的完整投影是索引器、SDK 与各种下游消费端的数据基础。下面按层次拆解。Block区块的顶层容器Block消息是链上数据的入口一个区块按version单调递增的顺序容纳交易每个区块都以BlockMetadataTransaction开头其后跟随零个或多个交易直到下一个BlockMetadataTransaction为止。字段包括timestamp取自区块的BlockMetadataTransaction创世区块则为GenesisTransaction区块内所有交易共享同一时间戳height区块高度严格单调递增且无空号是区块的唯一标识uint64标注jstype JS_STRING便于 JS 生态安全表示transactions区块内全部交易chain_id标识来源链防止多链数据在同一个处理管道中被混淆。Transaction五种交易类型Transaction消息通过oneof txn_data区分交易种类TransactionType枚举取值如下enum TransactionType { TRANSACTION_TYPE_UNSPECIFIED 0; TRANSACTION_TYPE_GENESIS 1; TRANSACTION_TYPE_BLOCK_METADATA 2; TRANSACTION_TYPE_STATE_CHECKPOINT 3; TRANSACTION_TYPE_USER 4; // values 5-19 skipped for no reason TRANSACTION_TYPE_VALIDATOR 20; TRANSACTION_TYPE_BLOCK_EPILOGUE 21; }每个交易携带timestamp、version、epoch、block_height均含jstype JS_STRING标注、TransactionInfo info以及size_info大小信息。五种类型分别由BlockMetadataTransaction区块元数据、GenesisTransaction创世携带WriteSet与事件、StateCheckpointTransaction状态检查点空消息体、UserTransaction用户交易含请求与事件列表和ValidatorTransaction验证者交易包含ObservedJwkUpdate与DkgUpdate两类负载承载。TransactionInfo记录交易的执行结果hash、state_change_hash、event_root_hash、state_checkpoint_hash、gas_used、success、vm_status、accumulator_root_hash以及全部WriteSetChange变更列表是审计与回放链上状态的关键数据。用户交易与 PayloadUserTransactionRequest描述用户提交的原始请求sender、sequence_number、max_gas_amount、gas_unit_price、expiration_timestamp_secs复用aptos.util.timestamp.Timestamp、payload与signature。TransactionPayload支持五类负载enum Type { TYPE_UNSPECIFIED 0; TYPE_ENTRY_FUNCTION_PAYLOAD 1; // 入口函数 TYPE_SCRIPT_PAYLOAD 2; // Move 脚本 TYPE_WRITE_SET_PAYLOAD 4; // 写集 TYPE_MULTISIG_PAYLOAD 5; // 多签 TYPE_ENCRYPTED_TRANSACTION_PAYLOAD 6; // 加密交易 reserved 3; }EntryFunctionPayload由EntryFunctionId模块 函数名、泛型类型参数与字符串化参数组成并附带entry_function_id_str便于直接展示ScriptPayload携带MoveScriptBytecode字节码与 ABIMultisigPayload指向多签地址及可选的内部负载EncryptedTransactionPayload区分解密失败FailedDecryptionPayloadState与解密成功DecryptedPayloadState两种状态。ExtraConfigV1额外提供multisig_address与replay_protection_nonce防重放随机数两个可选配置项。WriteSet 与状态变更WriteSetChange覆盖六种链上状态变更删除/写入 Module、删除/写入 Resource、删除/写入 TableItem。例如WriteResource记录address、state_key_hash、MoveStructTag type、type_str与 JSON 字符串形式的dataWriteTableItem通过handlekey定位表项WriteTableData则保存key、key_type、value、value_type四元组。DirectWriteSet聚合所有变更与事件ScriptWriteSet则指定execute_as与脚本负载。Move 类型系统投影为让下游无需运行 Move VM 也能理解交易语义proto 完整投影了 Move 的类型体系MoveTypes枚举覆盖 bool、u8/u16/u32/u64/u128/u256、i8~i256、address、signer、vector、struct、泛型参数、引用reference与 unparsableMoveType通过oneof content承载 vector、struct、泛型下标、引用和无法解析的字符串MoveModule/MoveFunction/MoveStruct描述模块 ABI包括函数可见性Visibilityprivate/public/friend、is_entry、泛型参数约束、结构体字段、is_native、is_event、is_enum以及枚举变体MoveStructVariantMoveAbility枚举对应 Move 的 copy/drop/store/key 能力。交易签名体系从根签名到任意密钥README 的核心章节用一张 UML 类图完整刻画了transaction.proto中的签名消息结构这是理解 Aptos 账户模型与多签/代理支付机制的关键。下面将该结构原样展开UML 源见 protos/README.md并对照 proto 源码逐一说明。startuml SignatureStructure Root Signature message class Signature { Type type .. oneof signature .. Ed25519Signature ed25519 MultiEd25519Signature multi_ed25519 MultiAgentSignature multi_agent FeePayerSignature fee_payer SingleSender single_sender } enum Signature::Type { TYPE_UNSPECIFIED 0 TYPE_ED25519 1 TYPE_MULTI_ED25519 2 TYPE_MULTI_AGENT 3 TYPE_FEE_PAYER 4 TYPE_SINGLE_SENDER 6 } Ed25519Signature class Ed25519Signature { bytes public_key bytes signature } MultiEd25519Signature class MultiEd25519Signature { repeated bytes public_keys repeated bytes signatures uint32 threshold repeated uint32 public_key_indices } MultiAgentSignature class MultiAgentSignature { AccountSignature sender repeated string secondary_signer_addresses repeated AccountSignature secondary_signers } FeePayerSignature class FeePayerSignature { AccountSignature sender repeated string secondary_signer_addresses repeated AccountSignature secondary_signers string fee_payer_address AccountSignature fee_payer_signer } SingleSender class SingleSender { AccountSignature sender } AccountSignature class AccountSignature { Type type .. oneof signature .. Ed25519Signature ed25519 MultiEd25519Signature multi_ed25519 SingleKeySignature single_key_signature MultiKeySignature multi_key_signature AbstractionSignature abstraction } enum AccountSignature::Type { TYPE_UNSPECIFIED 0 TYPE_ED25519 1 TYPE_MULTI_ED25519 2 TYPE_SINGLE_KEY 4 TYPE_MULTI_KEY 5 TYPE_ABSTRACTION 6 } SingleKeySignature class SingleKeySignature { AnyPublicKey public_key AnySignature signature } MultiKeySignature class MultiKeySignature { repeated AnyPublicKey public_keys repeated IndexedSignature signatures uint32 signatures_required } AbstractionSignature class AbstractionSignature { string function_info bytes signature } IndexedSignature class IndexedSignature { uint32 index AnySignature signature } AnyPublicKey class AnyPublicKey { Type type bytes public_key } enum AnyPublicKey::Type { TYPE_UNSPECIFIED 0 TYPE_ED25519 1 TYPE_SECP256K1_ECDSA 2 TYPE_SECP256R1_ECDSA 3 TYPE_KEYLESS 4 TYPE_FEDERATED_KEYLESS 5 } AnySignature class AnySignature { Type type bytes signature (deprecated) .. oneof signature_variant .. Ed25519 ed25519 Secp256k1Ecdsa secp256k1_ecdsa WebAuthn webauthn Keyless keyless } enum AnySignature::Type { TYPE_UNSPECIFIED 0 TYPE_ED25519 1 TYPE_SECP256K1_ECDSA 2 TYPE_WEBAUTHN 3 TYPE_KEYLESS 4 } class Ed25519 { bytes signature } class Secp256k1Ecdsa { bytes signature } class WebAuthn { bytes signature } class Keyless { bytes signature } Associations Signature -- Ed25519Signature Signature -- MultiEd25519Signature Signature -- MultiAgentSignature Signature -- FeePayerSignature Signature -- SingleSender MultiAgentSignature -- AccountSignature FeePayerSignature -- AccountSignature SingleSender -- AccountSignature AccountSignature -- Ed25519Signature AccountSignature -- MultiEd25519Signature AccountSignature -- SingleKeySignature AccountSignature -- MultiKeySignature AccountSignature -- AbstractionSignature SingleKeySignature -- AnyPublicKey SingleKeySignature -- AnySignature MultiKeySignature -- AnyPublicKey MultiKeySignature -- IndexedSignature IndexedSignature -- AnySignature AnySignature -- Ed25519 AnySignature -- Secp256k1Ecdsa AnySignature -- WebAuthn AnySignature -- Keyless enduml对照 protos/proto/aptos/transaction/v1/transaction.proto 中 511~666 行的实现可将签名体系归纳为四层第一层交易级Signature顶层。直接挂在UserTransactionRequest.signature上通过oneof提供五种形态单 Ed25519、多 Ed25519阈值签名、多 AgentMultiAgent、代付 GasFeePayer与单发送者SingleSender。注意Signature.Type中TYPE_SINGLE_SENDER 6且reserved 5——proto 编号刻意保留避免与历史演进冲突。第二层账户级AccountSignature。MultiAgentSignature、FeePayerSignature与SingleSender内部统一收敛到AccountSignature它又分为五类ed25519、multi_ed25519、single_key_signature、multi_key_signature与abstraction账户抽象含function_info与原始signature字节。proto 中AccountSignature.Type同样保留 3 号位。第三层任意密钥体系AnyPublicKey/AnySignature。面向现代 Aptos 账户支持 secp256k1、WebAuthn、Keyless 等AnyPublicKey.Type枚举 ed25519、secp256k1-ecdsa、secp256r1-ecdsa、keyless、federated-keyless以及 proto 中新增的slh_dsa_sha2_128s。SingleKeySignature由AnyPublicKeyAnySignature组成MultiKeySignature则是公钥列表 IndexedSignature带下标、可乱序提交列表 signatures_required门槛。README 中的 UML 基于发布时的版本实际 proto 已进一步扩展。第四层AnySignature的签名变体。proto 明确标注signature字节字段自 1.10 起废弃[deprecated true]推荐使用oneof signature_variant下的强类型消息Ed25519、Secp256k1Ecdsa、WebAuthn、Keyless以及后加的SlhDsa_Sha2_128s。下游解析时应优先读取signature_variant仅对旧版本数据回退到裸字节字段。索引器与流式服务indexer/v1Aptos 索引器通过 gRPC 对外提供链上交易流相关定义集中在 protos/proto/aptos/indexer/v1/。raw_data.proto流式拉取protos/proto/aptos/indexer/v1/raw_data.proto 定义数据面的核心 RPCservice RawData { rpc GetTransactions(GetTransactionsRequest) returns (stream TransactionsResponse); }GetTransactionsRequest的关键参数starting_version必填流的起始版本transactions_count可选本次流返回的交易总数缺省则无限流式推送batch_size可选每个TransactionsResponse批次的交易条数缺省 1000超过 1000 的请求会被拒绝transaction_filter可选BooleanTransactionFilter过滤条件命中才下发。TransactionsResponse除交易列表外还携带chain_id与processed_rangefirst_version/last_version便于消费端确认已处理区间、断点续传。TransactionsInStorage则标记为仅供存储使用。grpc.proto服务发现与心跳protos/proto/aptos/indexer/v1/grpc.proto 面向索引器数据服务集群的控制面定义三类服务GrpcManagerHeartbeat各节点上报ServiceInfo返回known_latest_version、GetTransactions单次拉取、GetDataServiceForRequest为用户请求路由到具体data_service_addressDataServicePing区分 live/historical 服务并回传服务信息、GetTransactions流式交易下发ServiceInfo通过oneof区分LiveDataServiceInfo/HistoricalDataServiceInfo/FullnodeInfo/GrpcManagerInfo每类都携带chain_id、timestamp、known_latest_version等健康与进度信息其中LiveDataServiceInfo.min_servable_version缺省表示服务尚未就绪。filter.proto 与 fullnode_data.protoprotos/proto/aptos/indexer/v1/filter.proto 提供BooleanTransactionFilter布尔组合的交易过滤表达式供raw_data.proto与grpc.proto引用protos/proto/aptos/internal/fullnode/v1/fullnode_data.proto 则服务于全节点内部的数据同步场景fullnode data 流与索引器 gRPC 服务共同构成 Aptos 数据出口的两条路径。remote_executor下的 network_msg.proto 面向远程执行器的网络消息。通用时间戳util/timestampprotos/proto/aptos/util/timestamp/timestamp.proto 定义了跨模块复用的Timestamp消息message Timestamp { int64 seconds 1; // UTC 秒Unix epoch 起算 int32 nanos 2; // 纳秒精度的小数部分0 ~ 999,999,999 }seconds取值限定在 0001-01-01T00:00:00Z 至 9999-12-31T23:59:59Znanos非负且向前累加。该类型被交易、区块、索引器服务信息广泛引用例如UserTransactionRequest.expiration_timestamp_secs、LiveDataServiceInfo.timestamp是全仓库时间语义的唯一来源。也正因它被广泛采用buf.yaml中特意豁免了它的PACKAGE_VERSION_SUFFIXlint 规则避免破坏既有引用。生成代码与多语言使用Rust生成代码位于 protos/rust/src/pb/按包名输出为aptos.transaction.v1.rs、aptos.indexer.v1.rs、aptos.internal.fullnode.v1.rs、aptos.remote_executor.v1.rs、aptos.util.timestamp.rs等文件并配套.serde.rsserde 序列化与.tonic.rsgRPC 服务模块crate 由prost-crate插件统一生成见 protos/rust/Cargo.toml 与 protos/rust/README.md。Pythonprotos/python/README.md 说明了用法安装后直接导入生成的类即可from aptos_protos.aptos.transaction.v1.transaction_pb2 import Transaction def parse(transaction: Transaction): # Parse the transaction. ...生成代码位于 protos/python/aptos_protos/包括transaction_pb2.py、raw_data_pb2.py、raw_data_pb2_grpc.py、fullnode_data_pb2_grpc.py等由 protos/python/pyproject.toml 管理打包protos/python/CHANGELOG.md 记录版本演进。TypeScriptprotos/typescript/src/ 下按aptos/模块/v1/*.ts组织并自动生成多层index.aptos.*.ts聚合导出文件outputIndextrue的产物。由于 proto 中 64 位字段普遍标注jstype JS_STRING且 ts-proto 配置了forceLongbigintJS/TS 侧可以安全处理超出 Number 安全范围的版本号、Gas 等大整数。版本一致性工作流小结最后回到 README 强调的两个实践要点这也是贡献者改动 proto 时的标准流程保持 buf 版本与 CI 一致出现意外 diff 时先核对本地buf --version与 CI 工作流.github/workflows/check-protos.yaml所用版本改动 proto 后执行生成在protos/目录依次运行./scripts/install_deps.sh首次与./scripts/build_protos.sh一次性同步 Rust / Python / TypeScript 三套代码再提交包含生成代码的变更确保仓库中的生成产物始终与 protos/proto/ 源定义一致。Aptos 将 proto 源、buf 配置与三语言生成代码集中收纳于protos/的设计既简化了发布、又用 CI 与 breaking 检查守住了兼容性底线而交易签名 UML 所揭示的四层消息结构则是理解 Aptos 账户抽象、多签、代付与 Keyless 等现代特性的数据基础值得所有链上数据消费端开发者细读。【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-core创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考