Shardeum 仓库开发指南：从构建命令到 EVM 分片源码架构的完整解读

Shardeum 仓库开发指南：从构建命令到 EVM 分片源码架构的完整解读

【免费下载链接】shardeumShardeum is an EVM based autoscaling blockchain项目地址: https://gitcode.com/GitHub_Trending/sh/shardeum

本篇技术指南以仓库根目录下的 CLAUDE.md 为骨架，系统梳理 Shardeum（基于 EVM 的动态状态分片区块链）仓库的开发全流程：包括依赖安装与编译、本地网络启动、代码质量与测试命令，以及 EVM 实现、状态管理、账户体系、交易处理、存储层等核心模块的源码架构。读者读完本篇后，将能够独立完成 Shardeum 仓库的环境搭建、本地多节点网络运行、单元测试与冒烟测试执行，并掌握在该仓库中新增交易类型、修改 EVM 行为、处理账户对象的标准开发范式。

项目概览：EVM 兼容与动态状态分片

CLAUDE.md 开篇明确了 Shardeum 的定位：一个EVM 兼容（EVM-compliant）的区块链平台，通过动态状态分片（dynamic state sharding）实现可扩展性。其代码库实现了自定义 EVM、状态管理（state management）与分片机制，同时保持对以太坊生态的兼容性。

这一描述在源码层面得到印证：package.json 中的依赖既包含@ethereumjs/common、@ethereumjs/block、@ethereumjs/tx、@ethereumjs/vm等以太坊核心库（v7 系列），也包含@shardeum-foundation/core、@shardeum-foundation/lib-net、@shardeum-foundation/lib-types等分片网络基础库。整体策略是：在以太坊 EVM 语义之上叠加自研的分片网络与状态管理能力，而非从零重写一条链。Node 版本要求为20.19.3（见 package.json 的engines字段）。

开发环境搭建与必备命令

安装依赖：务必使用npm ci

CLAUDE.md 明确强调：安装依赖时使用npm ci而非npm install。

npm ci

npm ci依据 package-lock.json 做干净的全量安装，删除现有node_modules后重新安装锁定版本，保证所有开发者与 CI 环境得到完全一致的依赖树。对于依赖版本敏感、涉及大量原生模块（如sqlite3、@ethereumjs/*系列）的区块链仓库，这是避免"能编译但版本漂移"问题的关键约定。

编译 TypeScript

仓库提供两个等价的编译入口（在 package.json 中定义）：

npm run prepare # 或 npm run compile

• npm run compile实际执行tsc -p .，按根目录 tsconfig.json 编译全部 TypeScript 源码；
• npm run prepare内部就是调用npm run compile，它同时是 npm 生命周期钩子——在npm ci安装依赖后会自动触发，因此编译产物dist/通常在安装阶段就已生成。

编译产物入口为dist/src/index.js（见 package.json 的main字段），即最终运行的节点程序。

启动本地网络：shardus CLI

CLAUDE.md 提供的本地网络管理命令依赖shardus CLI（Shardeum 基于 Shardus 协议框架构建，CLI 来自 devDependency@shardeum-foundation/tools-shardus-cli）：

shardus start 10 # 以 10 个节点启动本地网络 shardus stop # 停止网络 shardus clean # 清理网络数据

shardus start 10会创建 10 个本地节点实例，便于在本地体验分片网络的多节点共识行为。值得补充的是，仓库自身在 package.json 中也封装了等价的 npm 脚本：

• npm run start→node scripts/start.js && node dist/src/index.js；
• npm run stop→node scripts/stop.js；
• npm run clean→node scripts/clean.js。

其中 scripts/start.js 通过 pm2 拉起@shardeum-foundation/archiver（归档器）与@shardeum-foundation/monitor-server（监控服务），并在http://localhost:3000提供网络监控面板——这是观察本地网络节点状态、共识进度与交易情况的最直观入口。

完整重启周期

CLAUDE.md 给出了"编译 → 停止 → 清理 → 启动"的全量重启命令：

npm run restart

在 package.json 中，该脚本展开为npm run prepare && shardus stop && shardus clean && shardus start。注意它不带节点数量参数，shardus start会回落到默认节点数。当你修改了核心源码（例如 EVM 或状态管理逻辑）需要从零验证时，npm run restart是最稳妥的起点，可避免旧实例数据与新代码之间的不一致。

代码质量与测试命令

CLAUDE.md 将质量检查分为代码规范与测试两条线：

# Lint 检查 npm run lint # 格式检查 npm run format-check # 自动修复格式 npm run format-fix # 运行单元测试 npm test # 运行指定测试文件 npm test -- path/to/test.ts # 带覆盖率的冒烟测试 npm run test:smoke

各命令在 package.json 中的实际实现为：

其中npm run test:smoke对应根目录 test/main.test.ts.disabled（正式跑测时以main.test.ts命名启用），它实际会拉起一个最小分片网络跑完整交易流程。此外 package.json 还内置了多个针对性的网络级测试脚本，如test:shardedNet（分片网络）、test:singleShardRotation（单分片轮转）、test:autoscaleNet（自动扩缩容），便于针对性地验证分片核心行为。

代码架构：核心组件逐层拆解

CLAUDE.md 将仓库划分为六个核心组件。下面结合源码逐一展开。

1. EVM 实现（src/evm_v2/）

位于 src/evm_v2/ 的自研 EVM 是"自定义 EVM"的直接体现：

• evm.ts— 主 EVM 执行引擎。其EVM类声明支持从Chainstart到Cancun的全部硬分叉（见 evm.ts），并组合了Journal（交易回滚日志）、TransientStorage（瞬态存储）、Interpreter（解释器）等组件；
• opcodes/— 逐操作码实现，除基础codes.ts（操作码表）、functions.ts（操作码行为）、gas.ts（动态 gas 计算）外，还包含EIP1283.ts、EIP2200.ts、EIP2929.ts等 EIP 专项实现，对应有 test/unit/src/evm_v2/opcodes/ 下的独立单测；
• precompiles/— 预编译合约，覆盖 01-ecrecover、02-sha256、03-ripemd160、04-identity、05-modexp、06-ecadd、07-ecmul、08-ecpairing、09-blake2f、0a-kzg-point-evaluation等以太坊标准预编译。

2. 虚拟机组装层（src/vm_v7/）

src/vm_v7/ 提供与 EthereumJS VM 兼容的组装层：

• vm.ts— VM 类，作为对外门面；
• runTx.ts— 单笔交易执行逻辑；
• runBlock.ts— 区块处理（含收据编码encodeReceipt）；
• buildBlock.ts— 区块构建器（BlockBuilder）；
• bloom/— 以太坊日志布隆过滤器。

从 src/vm_v7/index.ts 可见export const ShardeumVM = VM，即以 EthereumJS VM 的接口形式暴露，从而让上层分片逻辑与以太坊工具链保持兼容。

3. 状态管理（src/state/）

src/state/ 承担状态根的管理：

• shardeumState.ts— 核心状态实现，实现了EVMStateManagerInterface（见 shardeumState.ts），内部集成账户缓存（AccountCache）、存储缓存（StorageCache）、原始存储缓存（OriginalStorageCache）与 Trie，并提供getProof/getStorageProof等默克尔证明能力；
• transactionState.ts— 面向交易执行的状态视图，用于交易 apply 阶段的状态读写隔离；
• cache/— 性能缓存层，单测位于 test/unit/src/state/cache.test.ts。

CLAUDE.md 特别强调：状态操作必须经由shardeumState，不要直接操作 EVM 原生状态，这是分片一致性（各节点独立维护分片状态、仅通过共识提交账本变更）的基础约定。

4. 账户系统（src/types/ 与 src/shardeum/）

src/types/ 定义了分层账户类型：

• WrappedEVMAccount.ts— 标准 EVM 账户的包装形态，除ethAddress、account（以太坊Account）外，还携带timestamp、hash、receipt、readableReceipt、operatorAccountInfo等 Shardeum 侧扩展字段，并实现了基于VectorBufferStream的版本化序列化/反序列化；
• NetworkAccount.ts— 网络级系统账户，承载网络参数与全局状态；
• NodeAccount.ts— 验证节点账户，记录节点质押与身份信息。

账户操作工具集中在 src/shardeum/wrappedEVMAccountFunctions.ts，配合 src/shardeum/evmAddress.ts 的地址转换工具使用。对应单测见 test/unit/src/shardeum/WrappedEVMAccount.test.ts。

5. 交易类型（src/tx/）

除标准 EVM 交易外，src/tx/ 承载 Shardeum 原生自定义交易：

• 质押/解质押— src/tx/staking/verifyStake.ts；
• 领取奖励— src/tx/claimReward.ts；
• 初始化奖励时间— src/tx/initRewardTimes.ts；
• 设置证书时间— src/tx/setCertTime.ts；
• 违规惩罚— src/tx/penalty/（含penaltyFunctions.ts、transaction.ts、violation.ts）。

每种自定义交易都配套独立的校验逻辑与 AJV Schema（见 src/types/ajv/ 下的StakeTxSchema.ts、UnstakeTxSchema.ts、ClaimRewardTxSchema.ts、PenaltyTXSchema.ts、SetCertTimeTxSchema.ts等），并通过 src/types/enum/AJVSchemaEnum.ts 统一枚举登记——这正是"新增交易类型"工作流的落地形态。

6. 存储层（src/storage/）

src/storage/ 提供 SQLite 持久化：

• storage.ts— 存储门面，初始化时按需创建accountsEntry与riAccountsCache两张核心表，并对timestamp建索引以加速按周期查询（见 storage.ts）；
• sqlite3storage.ts— 基于sqlite3的底层实现；
• models/与utils/— 表模型定义与 SQL 操作工具（sqlOpertors.ts、schemaDefintions.ts）。

存储与ShardeumFlags.UseDBForAccounts、enableRIAccountsCache等开关联动，单测覆盖于 test/unit/src/storage/。

关键设计模式

CLAUDE.md 提炼了四条贯穿全仓库的模式，理解它们能大幅降低阅读与贡献成本：

• 账户类型分层：EVM、Network、Node 等账户都从BaseAccount等基类接口扩展，序列化逻辑按类型枚举分发（见 src/types/enum/TypeIdentifierEnum.ts）；
• 交易处理闭环：自定义交易类型在 src/tx/ 中实现，并配套特定校验器与 AJV Schema，形成"Schema 定义 → 枚举登记 → 校验 → apply"的固定链路；
• 状态访问纪律：所有状态读写一律通过shardeumState（分片状态视图），避免直接触碰 EVM 原生状态，这是分片正确性的前提；
• 配置驱动：网络级配置位于 src/config/ 的*.genesis.json与*.multisig-permissions.json系列文件（如 devnet.genesis.json、mainnet.multisig-permissions.json），运行时由 src/config/index.ts 通过deepmerge合并到默认配置之上，决定网络的初始状态与权限结构。

重要文件速查

其中 shardeumFlags.ts 是全仓库的"功能总闸"，值得重点掌握几个关键项（默认值均取自源码ShardeumFlags对象，shardeumFlags.ts）：

• ChainID: 8082— EVM 链 ID，可通过环境变量CHAIN_ID覆盖，直接影响CHAINID操作码行为；
• blockProductionRate: 6— 区块生产间隔（秒）；
• CheckNonce: true、txBalancePreCheck: true— 交易 nonce 与余额预检开关；
• UseDBForAccounts: true— 是否用 SQLite 承载内存账户；
• StakingEnabled: true、ModeEnabled: true— 质押与节点模式开关；
• debugTxEnabled: false、VerboseLogs: false— 调试期开、生产默认关的日志类开关；
• 运行时可通过 updateShardeumFlag 动态调整（含类型校验与 key 合法性校验），该函数会被网络参数同步机制调用。

测试体系

CLAUDE.md 的测试约定如下：

• 单元测试统一位于 test/unit/；
• 测试文件遵循*.test.ts命名模式；
• Jest 配置位于仓库根目录 jest.config.js；
• 测试目录内提供 mock 实现（如 test/mocks/mockShardusConfig.ts）。

从目录结构可以清晰看到测试与源码的镜像关系：每个核心模块（evm_v2、vm_v7、state、storage、tx、types、shardeum、utils、versioning、handlers、setup）都有对应的单测目录。新增功能时，按相同结构补齐测试是仓库的隐性规范。

常见开发任务指南

新增一种交易类型

CLAUDE.md 给出四步流程：

1. 在 src/tx/ 中创建 handler；
2. 将交易类型加入相关枚举（参考 src/types/enum/TypeIdentifierEnum.ts 与 AJVSchemaEnum.ts）；
3. 实现校验逻辑（含 AJV Schema，参考 src/types/ajv/ 现有模式）；
4. 在 test/unit/ 补充单元测试。

以现有的setCertTime为例，可对照 src/tx/setCertTime.ts（实现）、src/types/ajv/SetCertTimeTxSchema.ts（校验 Schema）、test/unit/src/tx/setCertTime.test.ts（单测）三条链路上观察完整范式。

修改 EVM 行为

1. 先检查 src/evm_v2/opcodes/ 中对应操作码的实现位置（如 gas 相关改 gas.ts，操作码语义改 functions.ts）；
2. 评估对状态管理的影响——EVM 执行结果最终要落到shardeumState；
3. 确保与现有合约生态的兼容性，尤其注意 EIP 语义（EIP1283/EIP2200/EIP2929对存储与访问列表的约束）。

处理账户对象

1. 复用 src/shardeum/wrappedEVMAccountFunctions.ts 中的工具函数；
2. 遵循现有账户创建/修改的模式（如序列化走serializeWrappedEVMAccount，见 WrappedEVMAccount.ts）；
3. 确保账户类型的正确分发（EVM / Network / Node 的判别与转换）。

重要开发注意事项

CLAUDE.md 在结尾归纳了维护本仓库时的硬性约定，可视为贡献者的 checklist：

• 始终使用npm ci而非npm install，保证依赖树可复现；
• 提交前必须通过 lint 与格式检查（npm run lint+npm run format-check，必要时npm run format-fix）；
• 提交 PR 前务必先在本地网络验证（shardus start 10起本地多节点网络，或npm run restart做干净重启）——分片网络的共识、轮转与状态同步问题在单测中往往无法暴露；
• 遵循既有代码模式与目录结构，新模块应尽量镜像src/与test/unit/的对应关系；
• 善用ShardeumFlags中的调试/开发开关（如VerboseLogs、debugTxEnabled、debugTraceLogs），在不改业务逻辑的前提下定位问题；
• 网络创世配置决定初始状态——修改 src/config/ 下的*.genesis.json会直接影响新网络的账户、代币与权限分配，改动需经过完整的本地网络验证。

总而言之，CLAUDE.md 为这个"EVM 兼容 + 动态状态分片"的复杂仓库提供了一份高密度的工程指南：它既给出了可立即执行的构建、运行与测试命令，又勾勒出"自定义 EVM → 状态分片 → 账户体系 → 自定义交易 → SQLite 存储"的架构主脉。以本篇为地图，配合 src/ 源码与 test/unit/ 测试镜像逐步深入，即可快速上手这一代码库的日常开发与调试工作。

【免费下载链接】shardeumShardeum is an EVM based autoscaling blockchain项目地址: https://gitcode.com/GitHub_Trending/sh/shardeum