Aptos 交易执行层在 MonoMove VM 上的落地：aptos-transaction-executor 源码级解析

Aptos 交易执行层在 MonoMove VM 上的落地aptos-transaction-executor 源码级解析【免费下载链接】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本指南以third_party/move/mono-move/aptos-transaction-executor目录下 AGENTS.md经 CLAUDE.md 的AGENTS.md引用指向为核心围绕该 crate 在 MonoMove 虚拟机上复刻传统 AptosVM 交易执行角色的设计展开。你将掌握用户交易prologue → payload → epilogue三阶段执行链路、未物化结果TxnOutcome的语义、系统交易的无计量执行约定、预执行检查的四类边界以及如何通过差分测试验证新旧 VM 行为一致。一、crate 定位MonoMove 生态中的交易执行层mono-move-aptos-transaction-executor是 MonoMove 项目在third_party/move/mono-move下承担「传统 AptosVM 角色」的执行层。其 crate 描述与包名为mono-move-aptos-transaction-executor见 Cargo.toml依赖mono-move-core、mono-move-runtime、mono-move-loader、mono-move-natives、mono-move-output、mono-move-global-context等 MonoMove 基础组件同时复用aptos-types、aptos-vm-environment、aptos-gas-schedule等传统 Aptos 类型。从 lib.rs 可以看到它的公共 API 面AptosTransactionExecutor执行器主体executor.rsTxnOutcome单笔交易的未物化结果outcome.rs一组错误类型DiscardReason、ExecutionStage、ExecutionStatus、MoveExecutionFailure、PreExecutionCheckFailure、MaterializationError、SystemTxnFailure、NoEffectsReasonerrors.rsproduction_natives生产环境原生函数注册表AptosDataProvider、GroupMembers、decode_group_members供物化阶段合并资源组写集的数据访问接口。AGENTS.md 明确其边界区块级协调逻辑位于本 crate 之上本 crate 只负责单笔交易的执行产出「未物化」的结果交给上层协调者决定何时以及是否渲染成存储格式。二、核心模型用户交易与系统交易的两条执行路径AGENTS.md 开篇即定义了两类交易的根本差异用户交易运行prologue → payload → epilogue并产生未物化的TxnOutcome系统交易无计量unmetered、免手续费运行。区块级协调位于本 crate 之上。这一分发逻辑实现在 executor.rs 的execute_transaction中交易类型处理方式UserTransaction进入execute_user_transaction走完整三阶段流程BlockMetadata/BlockMetadataExt执行区块元数据系统交易BlockEpilogue执行区块尾系统交易失败不中止区块GenesisTransactionDiscarded(Unsupported)当前不支持StateCheckpointExecutedNoEffects(NothingToExecute)——链上无事可做仅作为状态树检查点标记ValidatorTransactionDiscarded(Unsupported)留给区块协调者2.1 用户交易prologue → payload → epilogue用户交易的完整流程在 execute.rs 的execute_user_transaction_impl中可按源码注释分成五个阶段预执行检查Pre-execution checks在触碰任何状态之前用TxnMetadata gas 参数构建PreExecutionChecker并执行四类检查详见第四节失败即Discard会话搭建Session setup通过Loader::new_with_policy创建惰性加载器LoadingPolicy::Lazy(LoweringPolicy::Lazy)以GasMeter::new(max_gas)构建InterpreterContext并注入TransactionContextExtension携带交易哈希、脚本哈希、链 ID、会话计数器等Prologue调用run_prologue校验交易认证密钥、序列号或 nonce、费用覆盖能力等。关键设计随后立即checkpoint保证 payload 失败回滚后 prologue 的副作用如 nonce 插入得以保留Payload根据TransactionExecutableRef分发到call_entry_function或run_script。payload 失败时rollback(mut interp, 1)丢弃其效果但交易仍继续进入 epilogue 收费Epilogue调用run_epilogue完成清理计费、递增序列号等。这里存在三种收尾路径epilogue 成功保留 payload 结果payload 已失败且 epilogue 也失败只能Discard源码注释指出这不应发生除非执行器有 bugpayload 成功但 epilogue 失败回滚 payload 效果并重试 epilogue交易仍提交并收费。2.2 系统交易无计量、免手续费、失败即中止区块system_txns/mod.rs 的模块注释给出了系统交易的铁律由共识产生、unmetered、fee-free、总是预期成功——一旦意外失败整个区块必须中止。每个子模块对应一种系统交易block_metadata区块元数据block_epilogue区块尾commonsystem_txn_outcome、SystemTxnMetadata、call_block_function等共享逻辑。以 block_epilogue.rs 为例其语义与用户交易有本质区别BlockEpiloguePayload::V0不携带费用分配链上无事可做直接返回ExecutedNoEffects(NothingToExecute)V1/V2携带FeeDistribution::V0 { amount }将分配表validator 地址与金额的键值集作为参数调用框架的block_epilogue函数失败不回滚区块调用失败时落入TxnOutcome::ExecutedNoEffects(BlockEpilogueFailed(failure))——这是一个「携带失败信息的空成功」与用户交易「失败即 discard/回滚」完全不同。2.3 unmetered 模式为回放与仿真而生executor.rs 暴露了without_metering()构造器将unmetered置为 true使 payload 无计量运行、epilogue 收取零费用。源码注释说明这是为「需要 gas 无关输出的回放replay与仿真simulation类调用方」设计的。三、TxnOutcome未物化结果与物化边界AGENTS.md 强调「物化是可选的执行路径上任何代码都不得调用materialize/」这是本 crate 最重要的架构约定之一。对应地outcome.rs 定义了四种结果变体变体含义Discarded(DiscardReason)无副作用被拒绝只有拒绝原因可观察UnexpectedSystemTransactionFailure(SystemTxnFailure)系统交易意外失败无单笔输出整个区块必须中止ExecutedNoEffects(NoEffectsReason)已提交但无副作用、零费用。用于「无事可做」的交易以及「失败被吸收」的区块尾Executed { status, fee_statement, effects }已执行无论 payload 是否成功都收费副作用真实存在其中Executed携带的是SessionEffectsmono-move-runtime 的会话效果而非写集write set。TxnOutcome::materializeoutcome.rs负责把未物化结果强制渲染成TransactionOutput序列化写集合并资源组成员、定稿事件、将执行状态转换为TransactionStatus。值得注意的是物化时的错误语义MaterializationError只在效果无法转换为存储格式如 BCS 序列化失败时出现——这是异常路径不同于作为正常结果携带在输出状态里的 discarderrors.rs。源码注释还标注了TODO(perf)物化目前仅为兼容性与测试服务区块协调者未来应直接处理 effects。四、预执行检查触碰状态前的四道闸门pre_execution_checks.rs 的run_checks依次执行四类检查全部通过后才允许执行器接触状态交易大小上限check_transaction_size与 gas 参数中的max_transaction_size_in_bytes比较超限即TransactionTooLargegas 单价边界check_gas_price_bounds校验min_price_per_gas_unit与max_price_per_gas_unit对应GasPriceBelowMinimum/GasPriceAboveMaximumgas 预算上限check_gas_budget_upper_boundmax_gas不得超过maximum_number_of_gas_units否则GasBudgetAboveBound预算覆盖基础成本check_gas_budget_covers_base_costs预算至少覆盖「交易固有成本intrinsic gas 认证附加费」其中 keyless 认证KEYLESS_BASE_COST与 SLH-DSA 签名SLH_DSA_SHA2_128S_BASE_COST按 gas feature version 计算不足则GasBudgetBelowIntrinsicCost。对应地errors.rs 定义了PreExecutionCheckFailure的五个错误变体并在注释中明确了单位约定「大小为字节gas 为 gas 单位价格为每 gas 单位 octa」。该模块还有两处明确的完整性 TODOgovernance 脚本的更大体积配额max_transaction_size_in_bytes_gov与账户创建可负担性检查待支持惰性账户创建后补上。测试侧e2e.rs 的gas_checks_discard_like_v1用超大交易、超预算、低于固有成本、超高单价四类用例验证新旧 VM 的 discard 状态码完全一致EXCEEDED_MAX_TRANSACTION_SIZE、MAX_GAS_UNITS_EXCEEDS_MAX_GAS_UNITS_BOUND、MAX_GAS_UNITS_BELOW_MIN_TRANSACTION_GAS_UNITS、GAS_UNIT_PRICE_ABOVE_MAX_BOUND。五、错误模型执行阶段的精确归因本 crate 的错误建模非常精细全部分布在 errors.rs值得逐一理解执行阶段ExecutionStagePrologue、Payload、Epilogue、EpilogueAfterRollbackpayload 回滚后的 epilogue、EpilogueRetry首次 epilogue 失败后的重试。它让「交易在哪一步失败」一目了然是后续状态码映射的依据。交易参数拒绝InvalidArguments按检查顺序定义了七种拒绝原因——native 入口函数交易不可直接调用、非entry函数、函数有返回值、signer 参数出现在非 signer 参数之后、参数类型不允许、参数数量不匹配、signer 数量不匹配、参数无法解码。脚本拒绝ScriptRejection仅两种——编译器标记为不稳定主网不运行与脚本发射事件脚本不允许。Move 执行失败MoveExecutionFailure统一收敛为四类Move abort含 code/message/location、参数被拒绝、脚本被拒、VM 运行时错误。call_result函数errors.rs把RuntimeStatus收敛为成功或 abortis_cant_pay_fee_abort则用于识别「费用支付方无法覆盖费用」这一特殊 abort。交易级失败DiscardReasonUnsupported执行器暂不支持的交易形态、Deprecated任何 VM 都不再支持的载荷、PreExecutionCheck、InvalidTypeArgument、Failure带 stage 与 failure、InvariantViolation。六、工作假设当前实现刻意遵循的边界AGENTS.md 的「Working assumptions」部分是最有价值的实现契约直接决定了开发与评审方向只支持最新功能集所有链上 feature 与最新 gas feature version 均启用只需支持该组合即可不移植旧验证路径、旧 gas 版本或 feature-flag 分支载荷面收窄entry function 与 script 是仅有的两种受支持载荷其余均为TODO(completeness)。这在 execute.rs 有直接体现——Encrypted/Empty载荷被Unsupported丢弃module-bundle 载荷被标记为Deprecatedgas 刻意不完整MonoMove 的 gas 单位未校准IO gas 与存储费用未计费因此不要把与旧 VM 的 gas 差异当作回归缺陷。这一点在 execute.rs 的placeholder_fee_statement中体现得淋漓尽致io_gas_units(0)、storage_fee_octas(0)、storage_fee_refund_octas(0)只有执行 gas 与总费用被填充prologue 之后必提交必收费交易一旦通过 prologue无论 payload 成败都会提交并收取费用对应ExecutionStatus::Success/Failure均入账的语义物化可选执行路径不得调用materialize/何时物化由上层协调者决定。七、测试与验证与旧 VM 的差分对拍AGENTS.md 给出了测试入口cargo test -p mono-move-aptos-transaction-executor测试主体是 tests/e2e.rs1244 行其核心方法论是差分测试用FakeExecutor构建 genesis 状态在同一初始状态上分别用旧 VM 与本 crate 执行同一笔交易再比较状态status、写集write set与事件events仅屏蔽 gas 相关的费用槽位。比较逻辑compare_outputse2e.rs值得关注写集 key 集合必须完全一致assert_eq!(v1_keys, v2_keys)允许内容差异的只有嵌入费用的槽位费用支付方的主存储object group与0xa的 APT metadata 对象supply事件序列的类型必须一致payload 除0x1::transaction_fee::FeeStatement、0x1::fungible_asset::Withdraw、0x1::coin::CoinWithdraw三类 gas 相关事件外必须逐字节相等双保险断言若没有任何写集差异说明两 VM 都没收费测试直接失败——防止屏蔽逻辑「空转」。测试覆盖面相当完整可作为本 crate 行为规范的「活文档」正常路径p2p_transfer_matches_v1余额充足的转账写集与事件全量对拍失败回滚p2p_transfer_insufficient_balance_aborts_like_v1payload abort、效果回滚、失败 epilogue 仍收费并递增序列号p2p_transfer_draining_fee_payer_aborts_like_v1耗尽余额后 epilogue 无法收费用回滚后从恢复的余额扣费以 cant-pay-fee abort 保留参数拒绝non_entry_function_rejected_like_v1、returning_function_rejected_like_v1、reference_parameter_rejected_like_v1、signer_after_argument_rejected_like_v1、option_of_private_struct_rejected_like_v1、native_function_rejected_like_v1——通过 MASM 汇编构造框架中不存在的「不可调用 entry 函数」UNCALLABLE_ENTRY_FUNCTIONS脚本路径script_transfer_matches_v1、script_serialized_argument_matches_v1、script_abort_matches_v1、script_runtime_error_matches_v1、event_emitting_script_refused_like_v1、undeserializable_script_kept_like_v1、script_cache_hit_matches_v1验证同一全局上下文内脚本缓存的命中路径系统交易block_metadata_matches_v1区块元数据在两侧均无计量运行因此无需任何 gas 屏蔽输出逐字节一致。八、已知限制与接线前置条件AGENTS.md 的「Before wiring to the block coordinator」一节列出了接入区块协调者前必须解决的两个缺口参数验证不完整相比 AptosVM 通过参数构造器完成的校验本 crate 尚缺两类——白名单框架类型上的值检查String的 UTF-8 有效性、Option长度、ObjectT存在性以及公共 struct/enum 参数。对应 entry_func.rs 中的TODO(security, completeness)标记多代理交易未测试execute_payload中标注TODO(completeness): multi-agent transactions are untested。不过测试里已有一例extra_signers_rejected_like_v1——向单 signer 入口函数提供两个发送者会被拒绝说明 signer 数量不匹配的路径已有覆盖。其他散见于源码的 TODO 同样值得注意gas 计量未校准TODO(metering)、类型参数 interning 可能污染全局缓存TODO(security)、加载策略尚不可配置TODO(completeness)、code::request_publish待解析为模块写集等。九、代码组织约定AGENTS.md 的「Conventions」只规定了一件事在 lib.rs 中严格执行模块保持私有任何公开项都从lib.rs重新导出lib.rs不包含其他内容。从目录结构看内部按职责划分为五组user_txn/用户交易args、entry_func、execute、metadata、pre_execution_checks、script、validation共 7 个模块system_txns/系统交易block_epilogue、block_metadata、commonmaterialize/物化txn_output、vm_status、mod单文件模块calls、errors、executor、natives、outcome、providers。结语mono-move-aptos-transaction-executor用约十余个源码模块加一份 1200 余行的差分测试把传统 AptosVM 的交易执行职责「翻译」到 MonoMove 虚拟机用户交易三阶段执行、系统交易无计量铁律、未物化TxnOutcome与显式物化边界、四类预执行检查、以及以cargo test -p mono-move-aptos-transaction-executor一键对拍的验证体系。阅读本 crate 的最佳路径是先读 AGENTS.md 建立工作假设再沿execute.rs的执行流逐段对照 errors.rs 与 outcome.rs最后用 e2e.rs 的用例反推行为契约。若你要在此基础上继续开发请务必遵守「不移植旧路径」「不把 gas 差异当回归」「执行路径不调用 materialize」这三条核心约定。【免费下载链接】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），仅供参考