fhEVM Coprocessor 压测流量生成器 stress-test-generator 完整指南场景配置、REST API 与源码原理【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm本指南面向需要为 fhEVM Coprocessor 全链路网关监听、ZK 输入验证、TFHE 计算、解密流程构造可控、可重复压测流量的开发者与运维人员。文章以仓库中 stress-test-generator/README.md 为核心骨架结合该模块的 Rust 源码、示例 CSV/JSON 文件与 Docker 构建方式系统讲解环境变量、场景文件格式、全部支持的事务类型、REST API 服务模式以及流量生成背后的实现原理。读完本文你将能够独立编写压测场景文件、以 CLI 或服务方式驱动压力测试并理解每条流量在数据库与 ZK 验证链路上的行为。一、模块定位为 Coprocessor 压测而生的事务生成器stress-test-generator 是 fhEVM 仓库coprocessor/fhevm-engine工作区中的一个独立二进制 crateCargo.toml编译产物名为stress_generator。它的职责不是直接压测单机性能而是按照用户设定的速率或数量持续向 Coprocessor 系统的数据库注入模拟的 FHE 事务事件ERC20 转账、DEX 兑换、加法/乘法链、ZK 输入证明、解密句柄生成等从而驱动 gw-listener、zkproof-worker、tfhe-worker、transaction-sender 等下游组件形成真实的全链路负载。从依赖关系看Cargo.toml它直接复用fhevm-engine-common、scheduler、host-listener、zkproof-worker、test-harness、tfhe-worker等本地 crate并依赖tfhe全同态加密、sqlxPostgreSQL、alloy以太坊类型与axumHTTP 服务这说明它既可以作为纯 CLI 工具单次执行场景也可以作为常驻 REST 服务远程提交压测任务。二、环境变量配置参数清单与源码默认值工具的全部运行参数通过环境变量注入由EnvConfig::new()统一读取实现见 src/utils.rs。下表完整列出 README 声明及源码确认的变量、默认值与作用环境变量默认值作用EVGEN_SCENARIOdata/evgen_scenario.csvCLI 模式下读取的分号分隔场景文件路径仅在 CLI 模式使用服务模式下场景改由 API 提交EVGEN_DB_URLpostgresql://postgres:postgres127.0.0.1:5432/coprocessor连接 Coprocessor 数据库的 PostgreSQL URL用于写入事务事件、查询 ZK 公钥/CRS、轮询验证结果ACL_CONTRACT_ADDRESS0x05fD9B5EFE0a996095f42Ed7e77c390810CF660cACL 合约地址被编码进 ZK 证明的 aux 数据见 zk_gen.rsCHAIN_ID12345主机链 Chain ID用于生成模拟句柄与写入数据库API_KEYa1503fb6-d79b-4e9e-826d-44cf262f3e05API 密钥README 声明项当前源码中未发现读取逻辑使用时以环境为准TENANT_ID1租户 IDREADME 声明项SYNTHETIC_CHAIN_LENGTH10合成基准场景MULChain、ADDChain中每条事务的链长度即单个事务内连续执行的 FheAdd/FheMul 次数MIN_DECRYPTION_TYPE0生成解密句柄时的最低 FHE 类型编号0 → FheBoolMAX_DECRYPTION_TYPE6生成解密句柄时的最高 FHE 类型编号6 → FheUint128OUTPUT_HANDLES_FOR_PUB_DECRYPTIONdata/handles_for_pub_decryptionGenPubDecHandles场景输出的公开解密句柄文件路径OUTPUT_HANDLES_FOR_USR_DECRYPTIONdata/handles_for_usr_decryptionGenUsrDecHandles场景输出的用户解密句柄文件路径关于解密类型的取值范围源码中的FheType枚举src/utils.rs给出了完整映射0FheBool、1FheUint4、2FheUint8、3FheUint16、4FheUint32、5FheUint64、6FheUint128、7FheUint160、8FheUint256、9FheBytes64、10FheBytes128、11FheBytes256。因此MIN_DECRYPTION_TYPE/MAX_DECRYPTION_TYPE实际可扩展的范围比默认的 06 更大可用于覆盖更多密文类型。三、场景文件Scenario CSV格式规范场景文件是分号分隔的 CSV无表头逐行描述一个流量场景。CSV 解析配置分隔符;、去空白、无表头、flexible 允许变长列见 src/bin/stress_generator.rs。3.1 列顺序与取值列序含义可选值说明1事务类型见 §4决定生成哪种 FHE 事件序列2ERC 转账变体Whitepaper、NoCMUX、NA仅对 ERC20/ERC7984 转账有意义其他事务填NA3生成目标Rate或CountRate每秒生成的事务数Count直接生成指定批次数量4输入模式ReuseInputs或NewInputs是否复用预先生成的输入句柄详见 §3.35依赖关系Dependent或Independent事务是否链式串联详见 §3.46合约地址十六进制地址流量注入的目标合约7用户地址十六进制地址模拟的调用者/账户8场景规格(float, integer)无限序列成对的速率或数量持续时长或迭代次数3.2 Rate 与 Count 的语义差异场景规格是速率/数量 时长/次数的成对序列且支持在同一行内书写多对。README 给出的例子1.1; 20; 3.4; 10——若目标为Rate生成器先以平均 1.1 笔/秒的速率持续 20 秒再以 3.4 笔/秒的速率持续 10 秒若目标为Count先产生1.1 × 20 22笔事务的批量紧接着再产生34笔事务的批量。对应源码实现速率模式generate_transactions_at_ratestress_generator.rs按time_between_transactions 1.0 / target_throughput计算间隔每生成一笔事务后若耗时低于间隔则休眠补齐若目标速率过高导致生成跟不上则退化为尽力而为地连续生成计数模式generate_transactions_countstress_generator.rs每对(num_transactions, iter_count)换算为iters num_transactions × iter_count次迭代逐次生成事务。仓库自带的一个直观示例是 data/minitest_002_erc20.csvERC20Transfer; NoCMUX; Count; ReuseInputs; Independent; 0xa5880e99d86F081E8D3868A8C4732C8f65dfdB08; 0xa0534e99d86F081E8D3868A8C4732C8f65dfdB07; 10.0; 2含义为以Count目标生成10.0 × 2 20笔NoCMUX变体的 ERC20 转账复用输入、事务互相独立。3.3 ReuseInputs 与 NewInputs输入生成策略NewInputs每笔事务都新生成输入——即重新执行加密 → 生成 ZK 证明 → 提交验证 → 取回句柄的完整往返能真实模拟输入验证链路的压力但会显著增加每笔事务的时延ReuseInputs启动时生成一批随机输入后放入内存缓存每合约用户组合缓存CACHED_INPUTS_COUNT 16个句柄见 zk_gen.rs后续直接复用避免反复 round-trip zkproof-worker从而让负载更集中在计算/监听链路。输入缓存的实际结构是(contract_address, user_address) → VecOptionHandle的全局哈希表zk_gen.rsget_inputs_vectorzk_gen.rs负责按策略返回新输入或命中缓存。3.4 Dependent 与 Independent事务串联Dependent事务之间链式串联前一笔的输出句柄作为后一笔的输入。README 举例Dependent 的 ERC 转账意味着场景中所有转账都汇入同一个目标钱包。这样可以在单一依赖链上持续累积计算深度压测长链场景Independent每笔事务独立执行互不依赖。实现上generate_transaction返回(Handle, Handle)两个输出句柄Dependent场景会将其保存并传入下一次生成见 stress_generator.rs。依赖句柄缓存的大小默认 128default_dependence_cache_size()见 utils.rs。四、支持的事务类型12 种场景全景README 声明了 7 种事务类型结合 src/utils.rs 的Transaction枚举工具实际支持 12 种按其注入行为可分为以下几类4.1 应用型业务事务类型行为ERC20Transfer模拟密文 ERC20 转账先做FheGe余额检查再按变体更新转出/转入余额。实现见 src/erc20.rsDEXSwapRequest模拟去中心化交易所的兑换请求涉及多组输入与双余额输出src/dex.rsDEXSwapClaim模拟兑换后的领取/结算事务src/dex.rsERC7984Transfer模拟 ERC-7984 的机密转账confidential_transfer_fromsrc/erc7984.rs其中ERC20Transfer的两种变体值得展开Whitepaper变体erc20.rs用FheGe生成余额是否充足的布尔句柄再通过FheIfThenElse条件选择转入/转出目标最后FheAdd/FheSub更新双方余额——这是 fhEVM 白皮书描述的经典转账模式NoCMUX变体erc20.rs将布尔句柄Cast为 u64与转账金额做FheMul得到实际可转金额不足则自动为 0再FheAdd/FheSub更新余额——避免使用条件选择CMUX适用于压测无 CMUX 的电路路径。4.2 合成基准事务Synthetic Bench类型行为ADDChain单笔事务内连续执行length由SYNTHETIC_CHAIN_LENGTH控制默认 10次FheAdd形成加法链MULChain同上但连续执行FheMul乘法链实现见 src/synthetics.rs每条链以next_random_handle(FheUint64)生成中间句柄循环写入FheAdd/FheMul事件仅最后一环标记为is_allowed最终句柄通过allow_handle授予AllowedForDecryption权限后返回。这类事务用于衡量计算深度对 tfhe-worker 的影响。4.3 ZK 输入验证类事务类型行为InputVerif生成并提交 ZK 输入证明等待 zkproof-worker 验证后取回密文句柄zk_gen.rsBatchInputProofs批量生成 ZK 输入证明并插入verify_proofs表zk_gen.rs用于压测输入证明批量处理吞吐4.4 解密句柄生成类事务类型行为GenPubDecHandles为MIN_DECRYPTION_TYPE到MAX_DECRYPTION_TYPE范围内的每种 FHE 类型生成一个可公开解密的句柄追加写入公开解密句柄文件synthetics.rsGenUsrDecHandles同上但句柄同时授权给合约与用户账户供用户解密流程使用synthetics.rs4.5 其他批量辅助事务类型行为BatchAllowHandles批量向allowed_handles表授予句柄权限默认关闭 pbs_computations 写入可用于准备压测前置数据BatchSubmitEncryptedBids批量提交加密竞价密封拍卖场景batch_size上限为 10MAX_NUMBER_OF_BIDS见 stress_generator.rs实现见 src/auction.rs4.6 JSON 格式场景文件除 CSV 外服务模式以及仓库 data/json 目录下使用 JSON 数组描述同样的场景字段与 CSV 列一一对应且为批量类事务额外提供可选的batch_size字段。以 example_job.json 为例[ { transaction: ERC20Transfer, variant: NoCMUX, kind: Rate, inputs: NewInputs, is_dependent: Independent, contract_address: 0xa5880e99d86F081E8D3868A8C4732C8f65dfdB08, user_address: 0xa0534e99d86F081E8D3868A8C4732C8f65dfdB07, scenario: [ [1.1, 2], [1.0, 1] ] } ]批量场景示例batch_input_proofs.json展示了batch_size: 4000的用法以 1.0 次/秒的速率持续 600 秒每次触发一批 4000 条 ZK 输入证明的生成。五、REST API 服务模式除了作为 CLI 工具一次性执行场景stress_generator还可以作为独立服务运行在远程机器上。服务内部使用容量为 100 的mpsc通道 单消费者循环串行处理任务stress_generator.rs同一时刻只运行一个 job其余排队从而保证性能指标采集的准确性。5.1 启动服务README 给出的启动方式注意服务模式下所有 ENV 变量照常配置唯独EVGEN_SCENARIO不需要因为场景由 API 提交# 配置除 EVGEN_SCENARIO 外的全部 ENV 变量 # 以服务方式运行 cargo run --release -- --run-server --listen-address 127.0.0.1:3030CLI 参数由 src/args.rs 定义除--run-server与--listen-address外还支持参数默认值说明--run-serverfalse以 API 服务模式启动缺省则执行 CLI 场景--listen-address0.0.0.0:3000HTTP 监听地址README 示例使用127.0.0.1:3030--zkproof-notify-channelevent_zkpok_new_work用于 ZK 证明事件通知的 PostgreSQLpg_notify通道名--log-levelinfo日志级别仓库还提供了 run_with_localnet.sh它会先加载./../.env-test环境文件再以--run-server --listen-address0.0.0.0:3030启动服务适合本地联调。5.2 端点一览README 声明了 4 个端点源码路由表stress_generator.rs还额外实现了任务取消端点方法路径作用POST/job入队一个新 job一组场景返回{id, scenarios_count, queued_at}HTTP 201GET/job/:id查询指定 job 的状态PATCH/job/:id取消指定 job源码额外提供README 未列出GET/status/running返回当前正在运行的 job_idGET/status/queued按执行顺序列出所有排队中的 jobjob 状态机包含四种状态Queued入队时间、Running开始时间、Completed完成时间、Cancelled取消时间定义见 stress_generator.rs。取消通过CancellationToken实现可同时作用于排队中与运行中的 jobstress_generator.rs。5.3 完整调用示例# 从 data/json 中选择/准备一个 job 文件例如 data/json/minitest_002_erc20.json # 提交 job curl -X POST http://localhost:3030/job \ -H Content-Type: application/json \ -d ./data/json/minitest_002_erc20.json # 查询 job 结果 curl -X GET http://localhost:3030/job/0job id 由进程内自增计数器分配GLOBAL_COUNTER见 stress_generator.rs服务重启后从 0 重新计数查询时以响应中返回的id为准。六、完整运行示例6.1 CLI 模式直接执行场景文件# 配置环境变量可覆盖默认值 export EVGEN_SCENARIOdata/evgen_scenario.csv export EVGEN_DB_URLpostgresql://postgres:postgres127.0.0.1:5432/coprocessor export ACL_CONTRACT_ADDRESS0x05fD9B5EFE0a996095f42Ed7e77c390810CF660c export CHAIN_ID12345 export SYNTHETIC_CHAIN_LENGTH10 export MIN_DECRYPTION_TYPE0 export MAX_DECRYPTION_TYPE6 # 编译并执行 cargo run --release不传--run-server时程序进入parse_and_execute分支stress_generator.rs解析EVGEN_SCENARIO指向的 CSV逐行并行 spawn 场景执行等待全部完成。仓库自带的默认场景 data/evgen_scenario.csv 同时覆盖了 ERC20Transfer两种变体、ADDChain、MULChain、DEXSwapRequest/Claim、InputVerif 共 9 条场景可直接作为模板。6.2 解密句柄生成与摘要回填CLI 模式执行完包含GenPubDecHandles/GenUsrDecHandles的场景后程序会额外连接数据库为句柄文件中的每一行查询ciphertext_digest表中的密文摘要64 位与 128 位并将文件更新为handle 0xdigest64 0xdigest128的格式stress_generator.rs。查询最多重试 500 次、每次间隔 200msutils.rs。对应示例见 data/minitest_003_generate_handles_for_decryption.csv 与同名的 JSON 版本。6.3 Makefile 与容器化Makefile 提供make buildrelease 编译、make preparecargo sqlx prepare离线查询缓存、make runcargo run --releaseDockerfile 采用两阶段构建builder 阶段从ghcr.io/zama-ai/fhevm/gci/rust-glibc基础镜像编译stress_generator二进制runtime 阶段使用cgr.dev/chainguard/glibc-dynamic以非 root 用户fhevm运行默认入口即stress_generator二进制。七、源码级运行原理7.1 主流程CLI 与服务两分支入口mainstress_generator.rs根据args.run_server分派服务模式初始化Context构建 axum Router后台 spawn 单一消费者循环从通道取 job 串行执行CLI 模式直接parse_and_execute先同步执行全部场景再处理解密句柄的摘要回填。Context中保存args、EnvConfig、CancellationToken与预生成的输入池inputs_poolutils.rs取消令牌贯穿速率/计数生成循环使 job 取消能及时中断事务注入。7.2 ZK 输入生成与验证链路NewInputs模式下的每笔事务都走完整 ZK 往返zk_gen.rs从数据库读取最新 TFHE 紧凑公钥pks与 CRSquery_and_save_pks内部使用DbKeyCache与CrsCache见 utils.rs用tfhe::ProvenCompactCiphertextList构建随机 u64 输入并生成带证明的密文列表将证明与(contract_address, user_address, acl_contract_address, chain_id)编码的 92 字节 aux 数据组装后插入verify_proofs表并通过pg_notify通知--zkproof-notify-channel指定的通道默认event_zkpok_new_work见 zk_gen.rs轮询verify_proofs.verified与handles字段最多重试 5000 次验证通过后按 32 字节切分返回句柄列表。BatchInputProofs则在此基础上按batch_size循环插入证明并设置retry_count 5以保证 txn-sender 首轮即删除、避免误报VerifyProofNotRequested错误zk_gen.rs。7.3 事件注入绕过交易直接写库除 ZK 类事务外ERC20Transfer、ADDChain、MULChain、GenPubDecHandles等场景并不真正发送链上交易而是构造TfheContractEvents事件如FheAdd、FheMul、FheGe、FheIfThenElse、TrivialEncrypt通过insert_tfhe_event直接写入监听器数据库allowed_outputs、operand_boundary_mask等字段由uniform_allowed_outputs与fixture_operand_boundary_mask生成见 utils.rs。句柄本身由next_random_handle按 fhEVM 句柄布局构造随机哈希 computed 标记 chain_id 类型 版本见 utils.rs。这种方式让压测负载可以绕开交易广播与区块确认的时延直击下游计算与监听链路。7.4 速率控制与依赖链速率模式以1.0 / target_throughput计算事务间隔并考虑单笔生成耗时动态补齐休眠Dependent场景通过把上一笔的输出句柄传入下一笔形成依赖链dependence_handle1/2即为链上传递的句柄stress_generator.rs。所有生成均在单个数据库事务sqlx::Transaction中完成并按场景类型 commit保证事件写入的原子性。八、小结stress-test-generator 是 fhEVM Coprocessor 压测体系的核心入口通过一套简洁的 CSV/JSON 场景描述与十个环境变量即可在 CLI 与服务两种模式下对 ERC20 转账、DEX 兑换、合成计算链、ZK 输入证明、解密句柄生成等十余种 FHE 工作负载进行速率可控、可串联、可取消的流量注入。理解其场景语义Rate/Count、ReuseInputs/NewInputs、Dependent/Independent与源码注入路径直接写库的 TFHE 事件 完整的 ZK 证明往返可以帮助你在压测 Coprocessor 时精确构造目标负载并对采集到的性能数据建立正确的因果解释。延伸阅读模块 README主程序与 REST API 实现环境变量与场景结构定义ZK 输入生成与验证ERC20 转账场景实现合成链与解密句柄生成示例场景文件CSV 与 JSON【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
