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 ciCLAUDE.md 明确强调安装依赖时使用npm ci而非npm install。npm cinpm ci依据 package-lock.json 做干净的全量安装删除现有node_modules后重新安装锁定版本保证所有开发者与 CI 环境得到完全一致的依赖树。对于依赖版本敏感、涉及大量原生模块如sqlite3、ethereumjs/*系列的区块链仓库这是避免能编译但版本漂移问题的关键约定。编译 TypeScript仓库提供两个等价的编译入口在 package.json 中定义npm run prepare # 或 npm run compilenpm 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 CLICLAUDE.md 提供的本地网络管理命令依赖shardus CLIShardeum 基于 Shardus 协议框架构建CLI 来自 devDependencyshardeum-foundation/tools-shardus-clishardus 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.jsnpm run stop→node scripts/stop.jsnpm 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 linteslint ./src/**/*.ts仅对src/下 TypeScript 源码做 ESLint 检查含eslint-plugin-security等安全规则npm run format-checkprettier --check ./src/**/*.ts校验格式是否符合 prettier.config.js 约定npm run format-fixprettier --write ./src/**/*.ts自动改写格式建议提交前运行npm testjest运行 jest.config.js 配置下的全部测试npm run test:smoke带minNodes20、nodesPerConsensusGroup5、NODE_ENVDEBUG等环境变量的 jest针对main.test.ts起 20 节点的冒烟/集成测试其中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— 区块处理含收据编码encodeReceiptbuildBlock.ts— 区块构建器BlockBuilderbloom/— 以太坊日志布隆过滤器。从 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.tssqlite3storage.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合并到默认配置之上决定网络的初始状态与权限结构。重要文件速查文件作用src/shardeum/shardeumConstants.ts网络常量与地址如全局账户地址、oneSHM 10^18的单位换算、时间常量src/shardeum/evmAddress.ts地址转换工具src/config/multisig-permissions.json多签权限配置CLAUDE.md 中写作multisig.json仓库实际文件名为multisig-permissions.jsonsrc/shardeum/shardeumFlags.ts全部调试/功能开关及默认值其中 shardeumFlags.ts 是全仓库的功能总闸值得重点掌握几个关键项默认值均取自源码ShardeumFlags对象shardeumFlags.tsChainID: 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 给出四步流程在 src/tx/ 中创建 handler将交易类型加入相关枚举参考 src/types/enum/TypeIdentifierEnum.ts 与 AJVSchemaEnum.ts实现校验逻辑含 AJV Schema参考 src/types/ajv/ 现有模式在 test/unit/ 补充单元测试。以现有的setCertTime为例可对照 src/tx/setCertTime.ts实现、src/types/ajv/SetCertTimeTxSchema.ts校验 Schema、test/unit/src/tx/setCertTime.test.ts单测三条链路上观察完整范式。修改 EVM 行为先检查 src/evm_v2/opcodes/ 中对应操作码的实现位置如 gas 相关改 gas.ts操作码语义改 functions.ts评估对状态管理的影响——EVM 执行结果最终要落到shardeumState确保与现有合约生态的兼容性尤其注意 EIP 语义EIP1283/EIP2200/EIP2929对存储与访问列表的约束。处理账户对象复用 src/shardeum/wrappedEVMAccountFunctions.ts 中的工具函数遵循现有账户创建/修改的模式如序列化走serializeWrappedEVMAccount见 WrappedEVMAccount.ts确保账户类型的正确分发EVM / Network / Node 的判别与转换。重要开发注意事项CLAUDE.md 在结尾归纳了维护本仓库时的硬性约定可视为贡献者的 checklist始终使用npm ci而非npm install保证依赖树可复现提交前必须通过 lint 与格式检查npm run lintnpm 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 ciCLAUDE.md 明确强调安装依赖时使用npm ci而非npm install。npm cinpm ci依据 package-lock.json 做干净的全量安装删除现有node_modules后重新安装锁定版本保证所有开发者与 CI 环境得到完全一致的依赖树。对于依赖版本敏感、涉及大量原生模块如sqlite3、ethereumjs/*系列的区块链仓库这是避免能编译但版本漂移问题的关键约定。编译 TypeScript仓库提供两个等价的编译入口在 package.json 中定义npm run prepare # 或 npm run compilenpm 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 CLICLAUDE.md 提供的本地网络管理命令依赖shardus CLIShardeum 基于 Shardus 协议框架构建CLI 来自 devDependencyshardeum-foundation/tools-shardus-clishardus 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.jsnpm run stop→node scripts/stop.jsnpm 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 linteslint ./src/**/*.ts仅对src/下 TypeScript 源码做 ESLint 检查含eslint-plugin-security等安全规则npm run format-checkprettier --check ./src/**/*.ts校验格式是否符合 prettier.config.js 约定npm run format-fixprettier --write ./src/**/*.ts自动改写格式建议提交前运行npm testjest运行 jest.config.js 配置下的全部测试npm run test:smoke带minNodes20、nodesPerConsensusGroup5、NODE_ENVDEBUG等环境变量的 jest针对main.test.ts起 20 节点的冒烟/集成测试其中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— 区块处理含收据编码encodeReceiptbuildBlock.ts— 区块构建器BlockBuilderbloom/— 以太坊日志布隆过滤器。从 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.tssqlite3storage.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合并到默认配置之上决定网络的初始状态与权限结构。重要文件速查文件作用src/shardeum/shardeumConstants.ts网络常量与地址如全局账户地址、oneSHM 10^18的单位换算、时间常量src/shardeum/evmAddress.ts地址转换工具src/config/multisig-permissions.json多签权限配置CLAUDE.md 中写作multisig.json仓库实际文件名为multisig-permissions.jsonsrc/shardeum/shardeumFlags.ts全部调试/功能开关及默认值其中 shardeumFlags.ts 是全仓库的功能总闸值得重点掌握几个关键项默认值均取自源码ShardeumFlags对象shardeumFlags.tsChainID: 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 给出四步流程在 src/tx/ 中创建 handler将交易类型加入相关枚举参考 src/types/enum/TypeIdentifierEnum.ts 与 AJVSchemaEnum.ts实现校验逻辑含 AJV Schema参考 src/types/ajv/ 现有模式在 test/unit/ 补充单元测试。以现有的setCertTime为例可对照 src/tx/setCertTime.ts实现、src/types/ajv/SetCertTimeTxSchema.ts校验 Schema、test/unit/src/tx/setCertTime.test.ts单测三条链路上观察完整范式。修改 EVM 行为先检查 src/evm_v2/opcodes/ 中对应操作码的实现位置如 gas 相关改 gas.ts操作码语义改 functions.ts评估对状态管理的影响——EVM 执行结果最终要落到shardeumState确保与现有合约生态的兼容性尤其注意 EIP 语义EIP1283/EIP2200/EIP2929对存储与访问列表的约束。处理账户对象复用 src/shardeum/wrappedEVMAccountFunctions.ts 中的工具函数遵循现有账户创建/修改的模式如序列化走serializeWrappedEVMAccount见 WrappedEVMAccount.ts确保账户类型的正确分发EVM / Network / Node 的判别与转换。重要开发注意事项CLAUDE.md 在结尾归纳了维护本仓库时的硬性约定可视为贡献者的 checklist始终使用npm ci而非npm install保证依赖树可复现提交前必须通过 lint 与格式检查npm run lintnpm 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考