FHEVM Coprocessor 实战指南FHE 计算服务的架构、部署配置与 GPU 镜像构建【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevmFHEVM Coprocessor 是 fhevm 全栈框架中负责实际执行全同态加密FHE计算的后端服务。本指南以 coprocessor/README.md 为主线结合仓库源码fhevm-engine 工作区、Helm 部署模板和配套文档Coprocessor Backend、Configuration、Architecture完整讲解 Coprocessor 的架构组成、本地密钥生成、从源码安装、各微服务的全部命令行参数、AWS RDS IAM 认证、GPU 镜像构建原理与 OpenTelemetry 遥测规范。读完后你将具备从零部署、调优并理解 FHEVM Coprocessor 全链路的能力。FHEVM Coprocessor 是什么FHEVM Coprocessor为 FHE 计算提供执行服务execution service。它是与 geth 节点并行的链下offchain组件当主机区块链host blockchain执行包含 FHE 操作的事务时Coprocessor 负责完成实际的密文运算。Coprocessor 本身由多个微服务组成例如 FHE 计算compute、输入验证input verify、事务发送transaction sending、事件监听listening to events等。根据 Coprocessor Backend 文档后端由以下组件构成listeners监听器把链上事件传播到数据库和 Gatewayserver服务器处理来自 Gateway 的输入插入请求向数据库写计算请求和 FHE 密文读取请求PostgreSQL 数据库存储计算请求和 FHE 密文worker计算 worker从数据库读取计算请求执行 FHE 计算并把结果密文写回数据库。服务器与 worker 既可以作为独立进程运行也可以合并为单一进程运行——无论哪种方式它们之间都通过数据库通信。此外Coprocessor 后端支持多租户multi-tenancy可以为不同的主机区块链、在不同的 FHE 密钥下分别执行 FHE 计算。从源码结构看这一架构在 coprocessor/fhevm-engine/Cargo.toml 的 workspace 中得到了印证其成员包括tfhe-worker、fhevm-engine-common、host-listener、gw-listener、sns-worker、transaction-sender、zkproof-worker、test-harness、stress-test-generator、upgrade-controller、consensus-detector。两种部署形态FHEVM-native 与 FHEVM-coprocessorREADME 明确列出两大主要特性面向FHEVM-native的Executor服务详见 executor.md面向FHEVM-coprocessor的Coprocessor服务详见 coprocessor_backend.md。两者的核心差别在于 FHE 计算发生的位置native 形态将执行器嵌入链内而 coprocessor 形态把计算移出链外、与主机区块链并行部署。本指南聚焦 coprocessor 形态。整体架构与数据流Architecture 文档 给出了 Coprocessor 与周边组件的关系关键事实如下Coprocessor 是链下组件包含三部分执行主机区块链全部区块的全节点full node、执行 FHE 计算的执行器executor、用于存储 FHE 密文的本地数据库当 Coprocessor 执行区块并检测到 FHE 操作时executor 子组件实际执行 FHE 计算并从本地数据库以及 DA加载/存储 FHE 密文数据可用性层DA是本地 Coprocessor 数据库的可公开验证镜像目的是让任何人通过检查 Coprocessor 发布到 DA 的结果来验证其行为是否合规Gateway负责输入验证、解密、重加密以及主机区块链验证者集合更新这些操作均通过/在 KMS 中完成。FHE 计算如何被拆分为两段FHE Computation 文档 解释了 FHEVM-coprocessor 中区块执行被拆成的两个阶段符号执行Symbolic Execution链上发生在 FHEVMExecutor.sol 合约内EVM 内部。EVM 把一个区块内所有请求的 FHE 操作连同其输入 handle 和对应的结果 handle 累积起来并以链上事件logs形式发出。FHE 计算FHE Computation链下host-listener 将这些事件摄入 Coprocessor 数据库worker 随后执行真正的密文运算。由于符号执行只需要 handle 而不需要真实密文FHE 计算可以在区块提交之后异步完成只有用户需要查看明文解密或重加密时才需要真实的 FHE 密文。对应的时序如下摘自 fhe_computation.md并行执行由于 Coprocessor 能从摄入的事件中提取数据依赖关系它可以在多个线程上并行执行 FHE 计算。截至当前文档所述Coprocessor 使用一种简单策略在多个线程上调度 FHE 计算更优的调度策略会在未来引入并做成可配置项。快速开始生成 FHE 密钥为了测试目的可以按如下方式生成一组密钥$ cd fhevm-engine/fhevm-engine-common $ cargo run generate-keys密钥默认存储在fhevm-engine/fhevm-keys目录下。从源码实现看该命令的实现位于 generate_keys.rs它创建FhevmKeys::new()实例转换为SerializedFhevmKeys后调用save_to_disk()落盘。该二进制在 fhevm-engine-common/Cargo.toml 中以generate-keys为名注册。tfhe-worker的 tfhe_worker.rs 也支持通过--generate-fhe-keys参数生成密钥后直接退出见下文 CLI 说明。依赖与安装依赖清单按照 README 与 tfhe-worker 的 README本地开发/部署需要docker-compose用于拉起本地 PostgreSQL 等基础设施rust编译各 Rust 微服务sqlx-cli数据库迁移工具安装命令为cargo install sqlx-clianvil仅测试需要Foundry 自带的本地以太坊节点安装说明见官方 Foundry 文档https://book.getfoundry.sh/getting-started/installation。安装 Coprocessor在仓库的coprocessor/fhevm-engine/coprocessor目录下执行$ cd fhevm-engine/coprocessor $ cargo install --path .本地开发环境的数据库准备结合 tfhe-worker/README.md 的开发流程完整的本地环境准备步骤如下# 1. 启动数据库容器 docker compose up -d # 2. 导出数据库 URL export DATABASE_URLpostgres://postgres:postgreslocalhost/coprocessor # 3. 创建数据库 sqlx db create # 4. 执行迁移 sqlx migrate run # 5. 运行首个可用的 coprocessor smoke test重建库 后台 worker make recreate_db cargo run -- --run-bg-worker --worker-polling-interval-ms 1000如需进入 PostgreSQL shell 排查数据docker exec -u postgres -it fhevm-coprocessor-db-1 psql coprocessor服务配置各微服务命令行参数详解Coprocessor 由多个二进制组成。下面按 README 的顺序逐一给出每个服务的完整--help输出与关键参数解读。tfhe-workerFHE 计算核心$ tfhe_worker --help Usage: tfhe_worker [OPTIONS] Options: --run-bg-worker Run the background worker --generate-fhe-keys Generate fhe keys and exit --work-items-batch-size WORK_ITEMS_BATCH_SIZE Work items batch size [default: 10] --tenant-key-cache-size TENANT_KEY_CACHE_SIZE Tenant key cache size [default: 32] --coprocessor-fhe-threads COPROCESSOR_FHE_THREADS Coprocessor FHE processing threads [default: 8] --tokio-threads TOKIO_THREADS Tokio Async IO threads [default: 4] --pg-pool-max-connections PG_POOL_MAX_CONNECTIONS Postgres pool max connections [default: 10] --metrics-addr METRICS_ADDR Prometheus metrics server address [default: 0.0.0.0:9100] --database-url DATABASE_URL Postgres database url. If unspecified DATABASE_URL environment variable is used其中配套的命令行工具cli提供租户管理与冒烟测试能力$ cli --help Usage: cli COMMAND Commands: insert-tenant Inserts tenant into specified database smoke-test Coprocessor smoke test help Print this message or the help of the given subcommand(s) Options: -h, --help Print help -V, --version Print versioninsert-tenant用于把租户即某条主机链的 API key、合约地址信息插入数据库是 host-listener 等组件能按租户工作multi-tenancy的前提smoke-test则用于端到端验证 Coprocessor 是否可工作。关于线程池的重要说明Configuration 文档 特别指出 Coprocessor 后端存在两个线程池tokio 线程池由--tokio-threads设置负责异步任务这些线程不应被阻塞FHE 计算线程池由--coprocessor-fhe-threads设置真正运行 FHE 计算的线程。coprocessor --help的完整输出与tfhe_worker基本一致另含--service-name参数默认值coprocessor用于 OTLP traces 中的服务名Usage: coprocessor [OPTIONS] Options: --run-bg-worker Run the background worker --generate-fhe-keys Generate fhe keys and exit --work-items-batch-size WORK_ITEMS_BATCH_SIZE Work items batch size [default: 10] --tenant-key-cache-size TENANT_KEY_CACHE_SIZE Tenant key cache size [default: 32] --coprocessor-fhe-threads COPROCESSOR_FHE_THREADS Coprocessor FHE processing threads [default: 8] --tokio-threads TOKIO_THREADS Tokio Async IO threads [default: 4] --pg-pool-max-connections PG_POOL_MAX_CONNECTIONS Postgres pool max connections [default: 10] --metrics-addr METRICS_ADDR Prometheus metrics server address [default: 0.0.0.0:9100] --database-url DATABASE_URL Postgres database url. If unspecified DATABASE_URL environment variable is used --service-name SERVICE_NAME Coprocessor service name in OTLP traces [default: coprocessor] -h, --help Print help -V, --version Print versionhost-listener消费链上 FHE 操作事件host-listener 负责观察主机区块链的区块执行把合约发出的符号执行事件传播到数据库从而把链上执行延伸到链下。$ host_listener --help Usage: host_listener [OPTIONS] --acl-contract-address ACL_CONTRACT_ADDRESS --tfhe-contract-address TFHE_CONTRACT_ADDRESS Options: --url URL [default: ws://0.0.0.0:8545] --acl-contract-address ACL_CONTRACT_ADDRESS --tfhe-contract-address TFHE_CONTRACT_ADDRESS --kms-generation-address KMS_GENERATION_ADDRESS [default: ] --database-url DATABASE_URL [default: postgresql://postgres:postgreslocalhost:5432/coprocessor] --start-at-block START_AT_BLOCK Can be negative from last block --end-at-block END_AT_BLOCK End catchup at this block (can be negative from last block) --catchup-margin CATCHUP_MARGIN Catchup margin relative the last seen block [default: 5] --catchup-paging CATCHUP_PAGING Catchup paging size in number of blocks [default: 100] --initial-block-time INITIAL_BLOCK_TIME Initial block time, refined on each block [default: 12] --log-level LOG_LEVEL [default: INFO] --health-port HEALTH_PORT Health check port [default: 8080] --dependence-cache-size DEPENDENCE_CACHE_SIZE Pre-computation dependence chain cache size [default: 10000] --dependence-by-connexity Dependence chain are connected components --dependence-cross-block Dependence chain are across blocks --dependent-ops-max-per-chain DEPENDENT_OPS_MAX_PER_CHAIN Max dependent ops per chain before slow-lane (0 disables; startup promotes all chains to fast) [default: 0] --reorg-maximum-duration-in-blocks REORG_MAXIMUM_DURATION_IN_BLOCKS Maximum duration in blocks to detect reorgs [default: 50] --service-name SERVICE_NAME service name in OTLP traces [env: OTEL_SERVICE_NAME] [default: host-listener] --catchup-finalization-in-blocks CATCHUP_FINALIZATION_IN_BLOCKS Maximum number of blocks to wait before a block is finalized [default: 20] --only-catchup-loop Run only catchup loop without real-time subscription --catchup-loop-sleep-secs CATCHUP_LOOP_SLEEP_SECS Sleep duration in seconds between catchup loop iterations [default: 60] --timeout-request-websocket TIMEOUT_REQUEST_WEBSOCKET Timeout in seconds for RPC calls over websocket [default: 15] -h, --help Print help -V, --version Print version关键参数解读--acl-contract-address与--tfhe-contract-address为必填分别指向主机链上的 ACL 合约与 TFHE 合约--url是连接主机区块链节点的 WebSocket 地址默认ws://0.0.0.0:8545追赶catchup相关参数--start-at-block/--end-at-block支持负数相对最新区块的偏移--catchup-margin默认 5 个区块、--catchup-paging每批 100 个区块、--catchup-finalization-in-blocks等待终局的最大区块数默认 20、--only-catchup-loop只运行追赶循环不做实时订阅依赖链调度相关参数--dependence-cache-size预计算依赖链缓存默认 10000、--dependence-by-connexity依赖链为连通分量、--dependence-cross-block依赖链跨区块、--dependent-ops-max-per-chain每个依赖链在进入慢车道前允许的最大依赖操作数0 表示禁用启动时将所有链提升为快速重组织检测--reorg-maximum-duration-in-blocks默认 50 个区块。根据 host-listener/README.mdhost-listener 默认会把 TFHE 操作事件传播到数据库若要关闭该传播可传入空的--database-url。其host_listener_consumer变体从 broker消息队列消费监听事件并写入匹配的 coprocessor 工作任务broker 地址可通过--url、--broker-url或BROKER_URL环境变量指定BROKER_URLredis://listener-redis:6379 host_listener_consumer \ --database-urlpostgresql://postgres:testmdp0.0.0.0:5432/coprocessor \ --acl-contract-addressACL_CONTRACT_ADDRESS \ --tfhe-contract-addressTFHE_CONTRACT_ADDRESS \ --chain-idCHAIN_ID而host_listener_poller会把进度记录在host_listener_poller_state.last_caught_up_block表中当该行缺失新库、新链或新增加 poller时必须用--seed-start-block指定起始区块非负值表示绝对区块高度0表示创世块负值表示启动时落后当前最新区块的块数。不带该参数时 poller 会直接报错退出从而把缺失配置的问题暴露在部署阶段而非运行阶段。gw-listener监听 Gateway 链事件$ gw_listener --help Usage: gw_listener [OPTIONS] --gw-url GW_URL --input-verification-address INPUT_VERIFICATION_ADDRESS Options: --database-url DATABASE_URL --database-pool-size DATABASE_POOL_SIZE [default: 16] --verify-proof-req-database-channel VERIFY_PROOF_REQ_DATABASE_CHANNEL [default: event_zkpok_new_work] --gw-url GW_URL -i, --input-verification-address INPUT_VERIFICATION_ADDRESS --error-sleep-initial-secs ERROR_SLEEP_INITIAL_SECS [default: 1] --error-sleep-max-secs ERROR_SLEEP_MAX_SECS [default: 10] --health-check-port HEALTH_CHECK_PORT [default: 8080] --metrics-addr METRICS_ADDR Prometheus metrics server address [default: 0.0.0.0:9100] --health-check-timeout HEALTH_CHECK_TIMEOUT [default: 4s] --provider-max-retries PROVIDER_MAX_RETRIES [default: 4294967295] --provider-retry-interval PROVIDER_RETRY_INTERVAL [default: 4s] --log-level LOG_LEVEL [default: INFO] --get-logs-poll-interval GET_LOGS_POLL_INTERVAL [default: 1s] --get-logs-block-batch-size GET_LOGS_BLOCK_BATCH_SIZE [default: 100] --service-name SERVICE_NAME gw-listener service name in OTLP traces [default: gw-listener] -h, --help Print help -V, --version Print version关键参数解读--gw-url与-i, --input-verification-address为必填数据库相关--database-pool-size默认 16--verify-proof-req-database-channel默认event_zkpok_new_work表示它把需要零知识证明验证的新工作写入该数据库通知频道供 zkproof-worker 消费事件拉取--get-logs-poll-interval默认 1s--get-logs-block-batch-size默认每批 100 个区块错误退避--error-sleep-initial-secs1s与--error-sleep-max-secs10s失败重试时间按指数退避在上限内增长健康检查与指标--health-check-port8080、--health-check-timeout4s、--metrics-addr0.0.0.0:9100。transaction-sender把计算结果写回链上$ transaction_sender --help Usage: transaction_sender [OPTIONS] --input-verification-address INPUT_VERIFICATION_ADDRESS --ciphertext-commits-address CIPHERTEXT_COMMITS_ADDRESS --gateway-url GATEWAY_URL Options: -i, --input-verification-address INPUT_VERIFICATION_ADDRESS -c, --ciphertext-commits-address CIPHERTEXT_COMMITS_ADDRESS -g, --gateway-url GATEWAY_URL -s, --signer-type SIGNER_TYPE [default: private-key] [possible values: private-key, aws-kms] -p, --private-key PRIVATE_KEY -d, --database-url DATABASE_URL --database-pool-size DATABASE_POOL_SIZE [default: 10] --database-polling-interval-secs DATABASE_POLLING_INTERVAL_SECS [default: 1] --verify-proof-resp-database-channel VERIFY_PROOF_RESP_DATABASE_CHANNEL [default: event_zkpok_computed] --add-ciphertexts-database-channel ADD_CIPHERTEXTS_DATABASE_CHANNEL [default: event_ciphertexts_uploaded] --verify-proof-resp-batch-limit VERIFY_PROOF_RESP_BATCH_LIMIT [default: 128] --verify-proof-resp-max-retries VERIFY_PROOF_RESP_MAX_RETRIES [default: 6] --verify-proof-remove-after-max-retries --add-ciphertexts-batch-limit ADD_CIPHERTEXTS_BATCH_LIMIT [default: 10] --add-ciphertexts-max-retries ADD_CIPHERTEXTS_MAX_RETRIES [default: 2147483647] --error-sleep-initial-secs ERROR_SLEEP_INITIAL_SECS [default: 1] --error-sleep-max-secs ERROR_SLEEP_MAX_SECS [default: 300] --txn-receipt-timeout-secs TXN_RECEIPT_TIMEOUT_SECS [default: 10] --required-txn-confirmations REQUIRED_TXN_CONFIRMATIONS [default: 0] --review-after-unlimited-retries REVIEW_AFTER_UNLIMITED_RETRIES [default: 30] --provider-max-retries PROVIDER_MAX_RETRIES [default: 4294967295] --provider-retry-interval PROVIDER_RETRY_INTERVAL [default: 4s] --health-check-port HEALTH_CHECK_PORT [default: 8080] --metrics-addr METRICS_ADDR Prometheus metrics server address [default: 0.0.0.0:9100] --health-check-timeout HEALTH_CHECK_TIMEOUT [default: 4s] --log-level LOG_LEVEL [default: INFO] --gas-limit-overprovision-percent GAS_LIMIT_OVERPROVISION_PERCENT [default: 300] --graceful-shutdown-timeout GRACEFUL_SHUTDOWN_TIMEOUT [default: 8s] --service-name SERVICE_NAME service name in OTLP traces [default: txn-sender] --metric-host-txn-latency METRIC_HOST_TXN_LATENCY Prometheus metrics: coprocessor_host_txn_latency_seconds [default: 0.1:60.0:0.1] --metric-zkproof-txn-latency METRIC_ZKPROOF_TXN_LATENCY Prometheus metrics: coprocessor_zkproof_txn_latency_seconds [default: 0.1:60.0:0.1] -h, --help Print help -V, --version Print version签名与交易参数说明三个必填参数-i/--input-verification-address、-c/--ciphertext-commits-addressCiphertextCommits 合约地址、-g/--gateway-url-s/--signer-type支持private-key默认与aws-kms两种签名方式使用private-key签名方式时-p, --private-key PRIVATE_KEY变为必填使用aws-kms签名方式时支持标准AWS_*环境变量例如AWS_REGION、AWS_ACCESS_KEY_ID即用户名、AWS_SECRET_ACCESS_KEY即密码等。批处理与重试参数--verify-proof-resp-batch-limit每批最多 128 个证明响应、--verify-proof-resp-max-retries默认 6 次可加--verify-proof-remove-after-max-retries在超限后移除该项、--add-ciphertexts-max-retries默认2147483647即近乎无限重试与--review-after-unlimited-retries默认 30指示无限重试场景下多少秒后需要人工介入审查。Gas 与确认--gas-limit-overprovision-percent默认 300即按估算 gas 的 3 倍上浮预留、--required-txn-confirmations默认 0、--txn-receipt-timeout-secs默认 10s。sns-worker 与 zkproof-worker在 workspace Cargo.toml 中可以看到sns-worker与zkproof-worker两个成员。结合 README 的 GPU 章节它们与tfhe-worker一起被列为“执行 FHE 工作的三个服务”其二进制入口分别为 sns_worker.rs 与 zkproof_worker.rs。sns-worker内部包含 AWS 上传aws_upload.rs、S3 迁移、噪声压缩squash_noise.rs等模块zkproof-worker负责为零知识证明相关任务执行计算。执行 FHE 工作的三个服务均支持 GPU 镜像见下文。Helm 部署视角的参数组织从 charts/coprocessor/values.yaml 可以看出生产部署中这些参数的注入方式commonConfig统一管理databaseUrl、databaseUser、databasePassword、databaseEndpoint支持value或valueFrom引用 Secret/ConfigMap、tenantApiKey、主机链的aclContractAddress/fhevmExecutorContractAddress/kmsGenerationContractAddress/protocolConfigContractAddress、Gateway 链的gatewayUrl与gatewayContractAddressesinputVerification、ciphertextCommits、gatewayConfig、multichainAcl等这些值最终渲染进各个 Deployment 的命令行参数与环境变量。AWS RDS / PostgreSQL IAM 认证当使用 AWS RDS/PostgreSQL 的 IAM 数据库认证时DATABASE_URL不应包含密码。使用如下形式的 URLpostgresql://coprocessormy-db.cluster-xyz.eu-west-2.rds.amazonaws.com:5432/coprocessor并设置DATABASE_IAM_AUTH_ENABLEDtrue启用 IAM 认证DATABASE_IAM_REGION固定 IAM token 签名所使用的 AWS 区域DATABASE_SSL_ROOT_CERT_PATH指向 CA 证书包路径用于对 RDS 端点执行verify-fullTLS。Configuration 文档 补充说明运行时将从默认的 AWS credential provider chain 获取 AWS 凭证自动生成 15 分钟有效期的 IAM token并在连接池中的连接过期前自动刷新。这些环境变量在 Helm 侧对应commonConfig.databaseAuthMode: iam模式见 charts/coprocessor/values.yaml该模式会自动注入DATABASE_IAM_AUTH_ENABLEDtrue、DATABASE_IAM_REGION和DATABASE_SSL_ROOT_CERT_PATHdatabaseSslRootCert.enabled: true时图表会把仓库自带的 configs/global-rds-ca-root.pem 渲染成 ConfigMap 并挂载进每个组件。GPU 镜像构建约束、标签语义与部署影响哪些服务有 GPU 镜像执行 FHE 工作的三个服务——tfhe-worker、sns-worker、zkproof-worker——可以发布为 GPU 镜像由 CI 工作流coprocessor-gpu-docker-build.yml构建。其余服务没有 GPU 路径保持纯 CPU 镜像。标签即计算能力没有“通用 GPU 标签”一个 GPU 镜像只针对一种计算能力compute capability其标签明确标注是哪一种。标签形如ghcr.io/zama-ai/fhevm/coprocessor/sns-worker:v0.15.0-cuda12.2-sm90 ^version ^toolkit ^compute capability这并非装饰。tfhe-cuda-backend在编译时根据当时可见的设备选择 CUDA 架构条件架构MULTI_ARCHcargo feature75, 80, 86, 89 —— 没有 90因此不支持 H100编译时可见设备native即只针对该设备无设备70Volta并伴随 CMake 警告由于docker build不向构建过程暴露 GPUbuildx 没有--gpus如果按 CPU 镜像的方式构建 GPU 镜像CMake 会静默选择第三条分支产出sm_70二进制——这对一批 H100 来说是完全错误的。因此工作流在GPU runner 上编译CMake 检测到设备并构建native然后用 Dockerfile.gpu 打包结果。计算能力通过nvidia-smi从设备上读取而不是从 runner 配置推断因此标签不可能声称二进制不具备的能力。部署层面的后果sm_90镜像只能在 H100 上运行、不能在 L40 上运行反之亦然。必须选择与硬件匹配的标签这里故意没有浮动的:gpu标签因为“某个 GPU”恰恰是把不可运行镜像送进集群的歧义来源。runner 机型不是自由选择实例使用与 GPU 基准测试任务相同的provider::profile (hardware)字符串选择由 ci/parse_benchmark_profile.py 解析映射到 slab 后端Scaleway 用terraformHyperstack 用hyperstack并且在请求任何实例之前会拒绝不在 ci/slab.toml 中的 profile。默认值是scaleway::single-h100 (H100-1-80G)Scaleway 的 H100 供应量远高于 Hyperstack且生产环境就是 H100。只提供单 GPU profile——编译不会从八块 GPU 中获益反而会长时间占用稀缺的多 GPU 实例。hyperstack::l40是为 L40 部署准备的不能替代 H100 构建——差异是功能性的不只是调参问题CMake 把检测到的能力烘焙进CUDA_ARCH编译定义tfhe-cuda-backend会基于它启用真实代码。#if CUDA_ARCH 900遍布可编程 bootstrap核心 FHE 操作包括只有 Hopper 才提供的 thread-block-clustertbc路径。在 L40 上构建得到CUDA_ARCH890这些路径会被编译掉cubin 本身就是架构相关的因此即使代码相同L40 构建的镜像也无法在 H100 上加载。所以 L40 构建对 L40 硬件是有效产物对其他任何设备都是错误产物。当计算能力不是 90 时运行摘要会明确说明。仅支持手动触发。没有 tag 或 push 触发GPU 构建会占用稀缺的 GPU runner 长达一次 tfhe-rs CUDA 编译的时间且产物只对一种设备类别有效不适合自动触发。镜像里有什么运行时基础镜像与 CPU 镜像使用同一个 Chainguard pincgr.dev/zama.ai/glibc-dynamic因此 GPU worker 不比 CPU 兄弟服务更特权、供应链面也不更大。该基础镜像是 distroless——没有包管理器也没有 shell——所以唯一缺少的库libcudart.so.12从编译该二进制的工具包中复制进来。libstdc和libgcc_s不复制基础镜像已提供旁边放一份旧拷贝反而有遮蔽新版本的风险。glibc 的兼容性在两个方向上都成立Scaleway 镜像是 Ubuntu 24.04glibc 2.39Hyperstack 是 22.042.35而生产基础镜像提供glibc 2.43从一个已发布的 CPU 镜像中读取。两种构建都能在其上运行下面的 exec 检查会在将来不再成立时把它暴露出来。在真实构建上测得镜像107 MB对比 Ubuntu CUDA-base加 apt 的 437 MB以及打包了 cuBLAS、cuFFT、cuSPARSEworker 从不链接的 CUDA-runtime变体的 3.65 GB。镜像携带默认CMD但不是通过指定二进制名实现的一个 Dockerfile 服务三个服务而 Dockerfile 无法把构建参数插值进 exec 形式的CMD替代方案要么需要 distroless 基础镜像没有的 shell要么把 57 MB 的二进制再复制一份。于是工作流在二进制旁放置一个固定名字的相对符号链接worker - sns_worker十字节CMD [/usr/local/bin/worker]运行它。它是CMD而不是ENTRYPOINT因此编排栈中显式的command: [sns_worker, --database-url…]会直接替换它与 CPU 镜像行为完全一致默认CMD带来的好处是docker create和docker run可以在裸镜像上工作——这正是把二进制从镜像中取出的方式。二进制自身仍以本名出现在PATH上。推送到镜像仓库前的守卫二进制必须链接libcudartCPU 构建完全不链接 CUDA 运行时这能区分真正的 GPU 构建与中途丢弃--features gpu的构建每个镜像必须能实际exec用--version检查不需要数据库、不需要设备。这能捕获构建主机与运行时基础镜像之间的 glibc 或缺失库不匹配——开发期间两个方向都验证过针对 glibc 过旧的基础镜像退出码为 1针对 Chainguard 基础镜像退出码为 0。运行方式仅支持 Dispatch 触发push默认关闭便于在任何东西进入镜像仓库前先检查一次运行。在没有 cgr.dev 凭证的情况下测试时runtime-base输入可选用 Chainguard 的公共cgr.dev/chainguard/glibc-dynamic:latest与生产 pin 同一镜像族此时会跳过 cgr.dev 登录步骤。没有来自任何其他镜像仓库的镜像进入流水线libcudart从编译二进制的工具包中复制因此发布时运行时与编译器版本在构造上就一致标签中的 CUDA 版本从nvcc读取而不是取自可能与之不一致的输入。遥测风格指南tracing OpenTelemetryCoprocessor 各服务使用tracingspan 作为默认遥测 API并接入 OpenTelemetryOTLP。以下是仓库内各服务必须遵守的规则。规则用函数/span 名作为操作名不要添加operation ...span 字段不要把高基数标识符挂到 span 属性上不要在 span 上放txn_id、transaction_hash或handle如需调试把这些值记录到 event/log 行中异步工作用.instrument(...)包装 future不要跨.await持有span.enter()guard错误退出时设置 OTEL 错误状态仅仅记录日志不足以让 trace 看到错误保持 span 字段低基数、便于聚合好的例子有request_id、计数、布尔值、重试桶、链 id。推荐代码片段用#[tracing::instrument]声明整个函数为一个 spanskip_all避免记录大对象参数#[tracing::instrument(skip_all)] async fn process_proof(...) - anyhow::Result() { // business logic Ok(()) }对一段异步数据库操作单独建立 span并用.instrument(...)包裹 futureuse tracing::Instrument; let db_insert_span tracing::info_span!(db_insert, request_id); async { sqlx::query(UPDATE ...).execute(pool).await?; Ok::(), sqlx::Error(()) } .instrument(db_insert_span.clone()) .await?;在错误出口设置 OTEL 错误状态use tracing_opentelemetry::OpenTelemetrySpanExt; if let Err(err) do_work().instrument(span.clone()).await { span.context().span().set_status(opentelemetry::trace::Status::error(err.to_string())); return Err(err.into()); }这些片段在仓库中与tracing、tracing-opentelemetry、opentelemetry-otlp等依赖见 coprocessor/fhevm-engine/Cargo.toml配套使用各服务的--service-name参数即对应 OTLP trace 中的服务名。从代码与测试进一步验证workspace 组成与依赖coprocessor/fhevm-engine/Cargo.toml 展示了所有微服务成员及统一的依赖版本tfhe 1.6.3、sqlx 0.8.6、alloy 2.2.0、opentelemetry 0.29 等并对 release profile 启用了 fat LTO密钥生成实现generate_keys.rs 是cargo run generate-keys的实际入口tfhe-worker 入口tfhe_worker.rs 展示了--generate-fhe-keys与正常启动start_runtime的分支逻辑GPU 打包 DockerfileDockerfile.gpu 注释完整记录了 CUDA 架构选择逻辑、Chainguard 基础镜像选择、libcudart拷贝、固定名符号链接CMD、uid/gid 10000:10001 以及CUDA_MODULE_LOADINGEAGER的取舍生产部署配置charts/coprocessor/values.yaml 与 charts/coprocessor/templates 中的各 Deployment 模板展示了全部服务在生产 Kubernetes 集群中的参数注入方式基准测试负载tfhe-worker/README.md 提供了independent_300、dependent_1000_50x20、traffic_1000_200x5_10x100_lag2等标准 ERC20 基准场景及其 Grafana/SQL 查询方式可用于验证 worker 的依赖链调度与并行执行能力。结语FHEVM Coprocessor 把全同态加密计算从 EVM 符号执行中剥离出来形成一套由 host-listener、gw-listener、tfhe-worker、sns-worker、zkproof-worker、transaction-sender 等微服务构成的链下执行体系通过 PostgreSQL 解耦事件摄入与密文计算并利用依赖链实现并行调度。部署时既可以用cargo install从源码构建也可以消费 CPU/GPU 两种预构建镜像——GPU 镜像需严格按计算能力选择标签生产环境还支持 AWS RDS IAM 认证与 OpenTelemetry 全链路追踪。结合 coprocessor/docs 下的架构、配置与基准测试文档即可完成从单机冒烟测试到生产集群部署的全过程。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FHEVM Coprocessor 实战指南：FHE 计算服务的架构、部署配置与 GPU 镜像构建
FHEVM Coprocessor 实战指南FHE 计算服务的架构、部署配置与 GPU 镜像构建【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevmFHEVM Coprocessor 是 fhevm 全栈框架中负责实际执行全同态加密FHE计算的后端服务。本指南以 coprocessor/README.md 为主线结合仓库源码fhevm-engine 工作区、Helm 部署模板和配套文档Coprocessor Backend、Configuration、Architecture完整讲解 Coprocessor 的架构组成、本地密钥生成、从源码安装、各微服务的全部命令行参数、AWS RDS IAM 认证、GPU 镜像构建原理与 OpenTelemetry 遥测规范。读完后你将具备从零部署、调优并理解 FHEVM Coprocessor 全链路的能力。FHEVM Coprocessor 是什么FHEVM Coprocessor为 FHE 计算提供执行服务execution service。它是与 geth 节点并行的链下offchain组件当主机区块链host blockchain执行包含 FHE 操作的事务时Coprocessor 负责完成实际的密文运算。Coprocessor 本身由多个微服务组成例如 FHE 计算compute、输入验证input verify、事务发送transaction sending、事件监听listening to events等。根据 Coprocessor Backend 文档后端由以下组件构成listeners监听器把链上事件传播到数据库和 Gatewayserver服务器处理来自 Gateway 的输入插入请求向数据库写计算请求和 FHE 密文读取请求PostgreSQL 数据库存储计算请求和 FHE 密文worker计算 worker从数据库读取计算请求执行 FHE 计算并把结果密文写回数据库。服务器与 worker 既可以作为独立进程运行也可以合并为单一进程运行——无论哪种方式它们之间都通过数据库通信。此外Coprocessor 后端支持多租户multi-tenancy可以为不同的主机区块链、在不同的 FHE 密钥下分别执行 FHE 计算。从源码结构看这一架构在 coprocessor/fhevm-engine/Cargo.toml 的 workspace 中得到了印证其成员包括tfhe-worker、fhevm-engine-common、host-listener、gw-listener、sns-worker、transaction-sender、zkproof-worker、test-harness、stress-test-generator、upgrade-controller、consensus-detector。两种部署形态FHEVM-native 与 FHEVM-coprocessorREADME 明确列出两大主要特性面向FHEVM-native的Executor服务详见 executor.md面向FHEVM-coprocessor的Coprocessor服务详见 coprocessor_backend.md。两者的核心差别在于 FHE 计算发生的位置native 形态将执行器嵌入链内而 coprocessor 形态把计算移出链外、与主机区块链并行部署。本指南聚焦 coprocessor 形态。整体架构与数据流Architecture 文档 给出了 Coprocessor 与周边组件的关系关键事实如下Coprocessor 是链下组件包含三部分执行主机区块链全部区块的全节点full node、执行 FHE 计算的执行器executor、用于存储 FHE 密文的本地数据库当 Coprocessor 执行区块并检测到 FHE 操作时executor 子组件实际执行 FHE 计算并从本地数据库以及 DA加载/存储 FHE 密文数据可用性层DA是本地 Coprocessor 数据库的可公开验证镜像目的是让任何人通过检查 Coprocessor 发布到 DA 的结果来验证其行为是否合规Gateway负责输入验证、解密、重加密以及主机区块链验证者集合更新这些操作均通过/在 KMS 中完成。FHE 计算如何被拆分为两段FHE Computation 文档 解释了 FHEVM-coprocessor 中区块执行被拆成的两个阶段符号执行Symbolic Execution链上发生在 FHEVMExecutor.sol 合约内EVM 内部。EVM 把一个区块内所有请求的 FHE 操作连同其输入 handle 和对应的结果 handle 累积起来并以链上事件logs形式发出。FHE 计算FHE Computation链下host-listener 将这些事件摄入 Coprocessor 数据库worker 随后执行真正的密文运算。由于符号执行只需要 handle 而不需要真实密文FHE 计算可以在区块提交之后异步完成只有用户需要查看明文解密或重加密时才需要真实的 FHE 密文。对应的时序如下摘自 fhe_computation.md并行执行由于 Coprocessor 能从摄入的事件中提取数据依赖关系它可以在多个线程上并行执行 FHE 计算。截至当前文档所述Coprocessor 使用一种简单策略在多个线程上调度 FHE 计算更优的调度策略会在未来引入并做成可配置项。快速开始生成 FHE 密钥为了测试目的可以按如下方式生成一组密钥$ cd fhevm-engine/fhevm-engine-common $ cargo run generate-keys密钥默认存储在fhevm-engine/fhevm-keys目录下。从源码实现看该命令的实现位于 generate_keys.rs它创建FhevmKeys::new()实例转换为SerializedFhevmKeys后调用save_to_disk()落盘。该二进制在 fhevm-engine-common/Cargo.toml 中以generate-keys为名注册。tfhe-worker的 tfhe_worker.rs 也支持通过--generate-fhe-keys参数生成密钥后直接退出见下文 CLI 说明。依赖与安装依赖清单按照 README 与 tfhe-worker 的 README本地开发/部署需要docker-compose用于拉起本地 PostgreSQL 等基础设施rust编译各 Rust 微服务sqlx-cli数据库迁移工具安装命令为cargo install sqlx-clianvil仅测试需要Foundry 自带的本地以太坊节点安装说明见官方 Foundry 文档https://book.getfoundry.sh/getting-started/installation。安装 Coprocessor在仓库的coprocessor/fhevm-engine/coprocessor目录下执行$ cd fhevm-engine/coprocessor $ cargo install --path .本地开发环境的数据库准备结合 tfhe-worker/README.md 的开发流程完整的本地环境准备步骤如下# 1. 启动数据库容器 docker compose up -d # 2. 导出数据库 URL export DATABASE_URLpostgres://postgres:postgreslocalhost/coprocessor # 3. 创建数据库 sqlx db create # 4. 执行迁移 sqlx migrate run # 5. 运行首个可用的 coprocessor smoke test重建库 后台 worker make recreate_db cargo run -- --run-bg-worker --worker-polling-interval-ms 1000如需进入 PostgreSQL shell 排查数据docker exec -u postgres -it fhevm-coprocessor-db-1 psql coprocessor服务配置各微服务命令行参数详解Coprocessor 由多个二进制组成。下面按 README 的顺序逐一给出每个服务的完整--help输出与关键参数解读。tfhe-workerFHE 计算核心$ tfhe_worker --help Usage: tfhe_worker [OPTIONS] Options: --run-bg-worker Run the background worker --generate-fhe-keys Generate fhe keys and exit --work-items-batch-size WORK_ITEMS_BATCH_SIZE Work items batch size [default: 10] --tenant-key-cache-size TENANT_KEY_CACHE_SIZE Tenant key cache size [default: 32] --coprocessor-fhe-threads COPROCESSOR_FHE_THREADS Coprocessor FHE processing threads [default: 8] --tokio-threads TOKIO_THREADS Tokio Async IO threads [default: 4] --pg-pool-max-connections PG_POOL_MAX_CONNECTIONS Postgres pool max connections [default: 10] --metrics-addr METRICS_ADDR Prometheus metrics server address [default: 0.0.0.0:9100] --database-url DATABASE_URL Postgres database url. If unspecified DATABASE_URL environment variable is used其中配套的命令行工具cli提供租户管理与冒烟测试能力$ cli --help Usage: cli COMMAND Commands: insert-tenant Inserts tenant into specified database smoke-test Coprocessor smoke test help Print this message or the help of the given subcommand(s) Options: -h, --help Print help -V, --version Print versioninsert-tenant用于把租户即某条主机链的 API key、合约地址信息插入数据库是 host-listener 等组件能按租户工作multi-tenancy的前提smoke-test则用于端到端验证 Coprocessor 是否可工作。关于线程池的重要说明Configuration 文档 特别指出 Coprocessor 后端存在两个线程池tokio 线程池由--tokio-threads设置负责异步任务这些线程不应被阻塞FHE 计算线程池由--coprocessor-fhe-threads设置真正运行 FHE 计算的线程。coprocessor --help的完整输出与tfhe_worker基本一致另含--service-name参数默认值coprocessor用于 OTLP traces 中的服务名Usage: coprocessor [OPTIONS] Options: --run-bg-worker Run the background worker --generate-fhe-keys Generate fhe keys and exit --work-items-batch-size WORK_ITEMS_BATCH_SIZE Work items batch size [default: 10] --tenant-key-cache-size TENANT_KEY_CACHE_SIZE Tenant key cache size [default: 32] --coprocessor-fhe-threads COPROCESSOR_FHE_THREADS Coprocessor FHE processing threads [default: 8] --tokio-threads TOKIO_THREADS Tokio Async IO threads [default: 4] --pg-pool-max-connections PG_POOL_MAX_CONNECTIONS Postgres pool max connections [default: 10] --metrics-addr METRICS_ADDR Prometheus metrics server address [default: 0.0.0.0:9100] --database-url DATABASE_URL Postgres database url. If unspecified DATABASE_URL environment variable is used --service-name SERVICE_NAME Coprocessor service name in OTLP traces [default: coprocessor] -h, --help Print help -V, --version Print versionhost-listener消费链上 FHE 操作事件host-listener 负责观察主机区块链的区块执行把合约发出的符号执行事件传播到数据库从而把链上执行延伸到链下。$ host_listener --help Usage: host_listener [OPTIONS] --acl-contract-address ACL_CONTRACT_ADDRESS --tfhe-contract-address TFHE_CONTRACT_ADDRESS Options: --url URL [default: ws://0.0.0.0:8545] --acl-contract-address ACL_CONTRACT_ADDRESS --tfhe-contract-address TFHE_CONTRACT_ADDRESS --kms-generation-address KMS_GENERATION_ADDRESS [default: ] --database-url DATABASE_URL [default: postgresql://postgres:postgreslocalhost:5432/coprocessor] --start-at-block START_AT_BLOCK Can be negative from last block --end-at-block END_AT_BLOCK End catchup at this block (can be negative from last block) --catchup-margin CATCHUP_MARGIN Catchup margin relative the last seen block [default: 5] --catchup-paging CATCHUP_PAGING Catchup paging size in number of blocks [default: 100] --initial-block-time INITIAL_BLOCK_TIME Initial block time, refined on each block [default: 12] --log-level LOG_LEVEL [default: INFO] --health-port HEALTH_PORT Health check port [default: 8080] --dependence-cache-size DEPENDENCE_CACHE_SIZE Pre-computation dependence chain cache size [default: 10000] --dependence-by-connexity Dependence chain are connected components --dependence-cross-block Dependence chain are across blocks --dependent-ops-max-per-chain DEPENDENT_OPS_MAX_PER_CHAIN Max dependent ops per chain before slow-lane (0 disables; startup promotes all chains to fast) [default: 0] --reorg-maximum-duration-in-blocks REORG_MAXIMUM_DURATION_IN_BLOCKS Maximum duration in blocks to detect reorgs [default: 50] --service-name SERVICE_NAME service name in OTLP traces [env: OTEL_SERVICE_NAME] [default: host-listener] --catchup-finalization-in-blocks CATCHUP_FINALIZATION_IN_BLOCKS Maximum number of blocks to wait before a block is finalized [default: 20] --only-catchup-loop Run only catchup loop without real-time subscription --catchup-loop-sleep-secs CATCHUP_LOOP_SLEEP_SECS Sleep duration in seconds between catchup loop iterations [default: 60] --timeout-request-websocket TIMEOUT_REQUEST_WEBSOCKET Timeout in seconds for RPC calls over websocket [default: 15] -h, --help Print help -V, --version Print version关键参数解读--acl-contract-address与--tfhe-contract-address为必填分别指向主机链上的 ACL 合约与 TFHE 合约--url是连接主机区块链节点的 WebSocket 地址默认ws://0.0.0.0:8545追赶catchup相关参数--start-at-block/--end-at-block支持负数相对最新区块的偏移--catchup-margin默认 5 个区块、--catchup-paging每批 100 个区块、--catchup-finalization-in-blocks等待终局的最大区块数默认 20、--only-catchup-loop只运行追赶循环不做实时订阅依赖链调度相关参数--dependence-cache-size预计算依赖链缓存默认 10000、--dependence-by-connexity依赖链为连通分量、--dependence-cross-block依赖链跨区块、--dependent-ops-max-per-chain每个依赖链在进入慢车道前允许的最大依赖操作数0 表示禁用启动时将所有链提升为快速重组织检测--reorg-maximum-duration-in-blocks默认 50 个区块。根据 host-listener/README.mdhost-listener 默认会把 TFHE 操作事件传播到数据库若要关闭该传播可传入空的--database-url。其host_listener_consumer变体从 broker消息队列消费监听事件并写入匹配的 coprocessor 工作任务broker 地址可通过--url、--broker-url或BROKER_URL环境变量指定BROKER_URLredis://listener-redis:6379 host_listener_consumer \ --database-urlpostgresql://postgres:testmdp0.0.0.0:5432/coprocessor \ --acl-contract-addressACL_CONTRACT_ADDRESS \ --tfhe-contract-addressTFHE_CONTRACT_ADDRESS \ --chain-idCHAIN_ID而host_listener_poller会把进度记录在host_listener_poller_state.last_caught_up_block表中当该行缺失新库、新链或新增加 poller时必须用--seed-start-block指定起始区块非负值表示绝对区块高度0表示创世块负值表示启动时落后当前最新区块的块数。不带该参数时 poller 会直接报错退出从而把缺失配置的问题暴露在部署阶段而非运行阶段。gw-listener监听 Gateway 链事件$ gw_listener --help Usage: gw_listener [OPTIONS] --gw-url GW_URL --input-verification-address INPUT_VERIFICATION_ADDRESS Options: --database-url DATABASE_URL --database-pool-size DATABASE_POOL_SIZE [default: 16] --verify-proof-req-database-channel VERIFY_PROOF_REQ_DATABASE_CHANNEL [default: event_zkpok_new_work] --gw-url GW_URL -i, --input-verification-address INPUT_VERIFICATION_ADDRESS --error-sleep-initial-secs ERROR_SLEEP_INITIAL_SECS [default: 1] --error-sleep-max-secs ERROR_SLEEP_MAX_SECS [default: 10] --health-check-port HEALTH_CHECK_PORT [default: 8080] --metrics-addr METRICS_ADDR Prometheus metrics server address [default: 0.0.0.0:9100] --health-check-timeout HEALTH_CHECK_TIMEOUT [default: 4s] --provider-max-retries PROVIDER_MAX_RETRIES [default: 4294967295] --provider-retry-interval PROVIDER_RETRY_INTERVAL [default: 4s] --log-level LOG_LEVEL [default: INFO] --get-logs-poll-interval GET_LOGS_POLL_INTERVAL [default: 1s] --get-logs-block-batch-size GET_LOGS_BLOCK_BATCH_SIZE [default: 100] --service-name SERVICE_NAME gw-listener service name in OTLP traces [default: gw-listener] -h, --help Print help -V, --version Print version关键参数解读--gw-url与-i, --input-verification-address为必填数据库相关--database-pool-size默认 16--verify-proof-req-database-channel默认event_zkpok_new_work表示它把需要零知识证明验证的新工作写入该数据库通知频道供 zkproof-worker 消费事件拉取--get-logs-poll-interval默认 1s--get-logs-block-batch-size默认每批 100 个区块错误退避--error-sleep-initial-secs1s与--error-sleep-max-secs10s失败重试时间按指数退避在上限内增长健康检查与指标--health-check-port8080、--health-check-timeout4s、--metrics-addr0.0.0.0:9100。transaction-sender把计算结果写回链上$ transaction_sender --help Usage: transaction_sender [OPTIONS] --input-verification-address INPUT_VERIFICATION_ADDRESS --ciphertext-commits-address CIPHERTEXT_COMMITS_ADDRESS --gateway-url GATEWAY_URL Options: -i, --input-verification-address INPUT_VERIFICATION_ADDRESS -c, --ciphertext-commits-address CIPHERTEXT_COMMITS_ADDRESS -g, --gateway-url GATEWAY_URL -s, --signer-type SIGNER_TYPE [default: private-key] [possible values: private-key, aws-kms] -p, --private-key PRIVATE_KEY -d, --database-url DATABASE_URL --database-pool-size DATABASE_POOL_SIZE [default: 10] --database-polling-interval-secs DATABASE_POLLING_INTERVAL_SECS [default: 1] --verify-proof-resp-database-channel VERIFY_PROOF_RESP_DATABASE_CHANNEL [default: event_zkpok_computed] --add-ciphertexts-database-channel ADD_CIPHERTEXTS_DATABASE_CHANNEL [default: event_ciphertexts_uploaded] --verify-proof-resp-batch-limit VERIFY_PROOF_RESP_BATCH_LIMIT [default: 128] --verify-proof-resp-max-retries VERIFY_PROOF_RESP_MAX_RETRIES [default: 6] --verify-proof-remove-after-max-retries --add-ciphertexts-batch-limit ADD_CIPHERTEXTS_BATCH_LIMIT [default: 10] --add-ciphertexts-max-retries ADD_CIPHERTEXTS_MAX_RETRIES [default: 2147483647] --error-sleep-initial-secs ERROR_SLEEP_INITIAL_SECS [default: 1] --error-sleep-max-secs ERROR_SLEEP_MAX_SECS [default: 300] --txn-receipt-timeout-secs TXN_RECEIPT_TIMEOUT_SECS [default: 10] --required-txn-confirmations REQUIRED_TXN_CONFIRMATIONS [default: 0] --review-after-unlimited-retries REVIEW_AFTER_UNLIMITED_RETRIES [default: 30] --provider-max-retries PROVIDER_MAX_RETRIES [default: 4294967295] --provider-retry-interval PROVIDER_RETRY_INTERVAL [default: 4s] --health-check-port HEALTH_CHECK_PORT [default: 8080] --metrics-addr METRICS_ADDR Prometheus metrics server address [default: 0.0.0.0:9100] --health-check-timeout HEALTH_CHECK_TIMEOUT [default: 4s] --log-level LOG_LEVEL [default: INFO] --gas-limit-overprovision-percent GAS_LIMIT_OVERPROVISION_PERCENT [default: 300] --graceful-shutdown-timeout GRACEFUL_SHUTDOWN_TIMEOUT [default: 8s] --service-name SERVICE_NAME service name in OTLP traces [default: txn-sender] --metric-host-txn-latency METRIC_HOST_TXN_LATENCY Prometheus metrics: coprocessor_host_txn_latency_seconds [default: 0.1:60.0:0.1] --metric-zkproof-txn-latency METRIC_ZKPROOF_TXN_LATENCY Prometheus metrics: coprocessor_zkproof_txn_latency_seconds [default: 0.1:60.0:0.1] -h, --help Print help -V, --version Print version签名与交易参数说明三个必填参数-i/--input-verification-address、-c/--ciphertext-commits-addressCiphertextCommits 合约地址、-g/--gateway-url-s/--signer-type支持private-key默认与aws-kms两种签名方式使用private-key签名方式时-p, --private-key PRIVATE_KEY变为必填使用aws-kms签名方式时支持标准AWS_*环境变量例如AWS_REGION、AWS_ACCESS_KEY_ID即用户名、AWS_SECRET_ACCESS_KEY即密码等。批处理与重试参数--verify-proof-resp-batch-limit每批最多 128 个证明响应、--verify-proof-resp-max-retries默认 6 次可加--verify-proof-remove-after-max-retries在超限后移除该项、--add-ciphertexts-max-retries默认2147483647即近乎无限重试与--review-after-unlimited-retries默认 30指示无限重试场景下多少秒后需要人工介入审查。Gas 与确认--gas-limit-overprovision-percent默认 300即按估算 gas 的 3 倍上浮预留、--required-txn-confirmations默认 0、--txn-receipt-timeout-secs默认 10s。sns-worker 与 zkproof-worker在 workspace Cargo.toml 中可以看到sns-worker与zkproof-worker两个成员。结合 README 的 GPU 章节它们与tfhe-worker一起被列为“执行 FHE 工作的三个服务”其二进制入口分别为 sns_worker.rs 与 zkproof_worker.rs。sns-worker内部包含 AWS 上传aws_upload.rs、S3 迁移、噪声压缩squash_noise.rs等模块zkproof-worker负责为零知识证明相关任务执行计算。执行 FHE 工作的三个服务均支持 GPU 镜像见下文。Helm 部署视角的参数组织从 charts/coprocessor/values.yaml 可以看出生产部署中这些参数的注入方式commonConfig统一管理databaseUrl、databaseUser、databasePassword、databaseEndpoint支持value或valueFrom引用 Secret/ConfigMap、tenantApiKey、主机链的aclContractAddress/fhevmExecutorContractAddress/kmsGenerationContractAddress/protocolConfigContractAddress、Gateway 链的gatewayUrl与gatewayContractAddressesinputVerification、ciphertextCommits、gatewayConfig、multichainAcl等这些值最终渲染进各个 Deployment 的命令行参数与环境变量。AWS RDS / PostgreSQL IAM 认证当使用 AWS RDS/PostgreSQL 的 IAM 数据库认证时DATABASE_URL不应包含密码。使用如下形式的 URLpostgresql://coprocessormy-db.cluster-xyz.eu-west-2.rds.amazonaws.com:5432/coprocessor并设置DATABASE_IAM_AUTH_ENABLEDtrue启用 IAM 认证DATABASE_IAM_REGION固定 IAM token 签名所使用的 AWS 区域DATABASE_SSL_ROOT_CERT_PATH指向 CA 证书包路径用于对 RDS 端点执行verify-fullTLS。Configuration 文档 补充说明运行时将从默认的 AWS credential provider chain 获取 AWS 凭证自动生成 15 分钟有效期的 IAM token并在连接池中的连接过期前自动刷新。这些环境变量在 Helm 侧对应commonConfig.databaseAuthMode: iam模式见 charts/coprocessor/values.yaml该模式会自动注入DATABASE_IAM_AUTH_ENABLEDtrue、DATABASE_IAM_REGION和DATABASE_SSL_ROOT_CERT_PATHdatabaseSslRootCert.enabled: true时图表会把仓库自带的 configs/global-rds-ca-root.pem 渲染成 ConfigMap 并挂载进每个组件。GPU 镜像构建约束、标签语义与部署影响哪些服务有 GPU 镜像执行 FHE 工作的三个服务——tfhe-worker、sns-worker、zkproof-worker——可以发布为 GPU 镜像由 CI 工作流coprocessor-gpu-docker-build.yml构建。其余服务没有 GPU 路径保持纯 CPU 镜像。标签即计算能力没有“通用 GPU 标签”一个 GPU 镜像只针对一种计算能力compute capability其标签明确标注是哪一种。标签形如ghcr.io/zama-ai/fhevm/coprocessor/sns-worker:v0.15.0-cuda12.2-sm90 ^version ^toolkit ^compute capability这并非装饰。tfhe-cuda-backend在编译时根据当时可见的设备选择 CUDA 架构条件架构MULTI_ARCHcargo feature75, 80, 86, 89 —— 没有 90因此不支持 H100编译时可见设备native即只针对该设备无设备70Volta并伴随 CMake 警告由于docker build不向构建过程暴露 GPUbuildx 没有--gpus如果按 CPU 镜像的方式构建 GPU 镜像CMake 会静默选择第三条分支产出sm_70二进制——这对一批 H100 来说是完全错误的。因此工作流在GPU runner 上编译CMake 检测到设备并构建native然后用 Dockerfile.gpu 打包结果。计算能力通过nvidia-smi从设备上读取而不是从 runner 配置推断因此标签不可能声称二进制不具备的能力。部署层面的后果sm_90镜像只能在 H100 上运行、不能在 L40 上运行反之亦然。必须选择与硬件匹配的标签这里故意没有浮动的:gpu标签因为“某个 GPU”恰恰是把不可运行镜像送进集群的歧义来源。runner 机型不是自由选择实例使用与 GPU 基准测试任务相同的provider::profile (hardware)字符串选择由 ci/parse_benchmark_profile.py 解析映射到 slab 后端Scaleway 用terraformHyperstack 用hyperstack并且在请求任何实例之前会拒绝不在 ci/slab.toml 中的 profile。默认值是scaleway::single-h100 (H100-1-80G)Scaleway 的 H100 供应量远高于 Hyperstack且生产环境就是 H100。只提供单 GPU profile——编译不会从八块 GPU 中获益反而会长时间占用稀缺的多 GPU 实例。hyperstack::l40是为 L40 部署准备的不能替代 H100 构建——差异是功能性的不只是调参问题CMake 把检测到的能力烘焙进CUDA_ARCH编译定义tfhe-cuda-backend会基于它启用真实代码。#if CUDA_ARCH 900遍布可编程 bootstrap核心 FHE 操作包括只有 Hopper 才提供的 thread-block-clustertbc路径。在 L40 上构建得到CUDA_ARCH890这些路径会被编译掉cubin 本身就是架构相关的因此即使代码相同L40 构建的镜像也无法在 H100 上加载。所以 L40 构建对 L40 硬件是有效产物对其他任何设备都是错误产物。当计算能力不是 90 时运行摘要会明确说明。仅支持手动触发。没有 tag 或 push 触发GPU 构建会占用稀缺的 GPU runner 长达一次 tfhe-rs CUDA 编译的时间且产物只对一种设备类别有效不适合自动触发。镜像里有什么运行时基础镜像与 CPU 镜像使用同一个 Chainguard pincgr.dev/zama.ai/glibc-dynamic因此 GPU worker 不比 CPU 兄弟服务更特权、供应链面也不更大。该基础镜像是 distroless——没有包管理器也没有 shell——所以唯一缺少的库libcudart.so.12从编译该二进制的工具包中复制进来。libstdc和libgcc_s不复制基础镜像已提供旁边放一份旧拷贝反而有遮蔽新版本的风险。glibc 的兼容性在两个方向上都成立Scaleway 镜像是 Ubuntu 24.04glibc 2.39Hyperstack 是 22.042.35而生产基础镜像提供glibc 2.43从一个已发布的 CPU 镜像中读取。两种构建都能在其上运行下面的 exec 检查会在将来不再成立时把它暴露出来。在真实构建上测得镜像107 MB对比 Ubuntu CUDA-base加 apt 的 437 MB以及打包了 cuBLAS、cuFFT、cuSPARSEworker 从不链接的 CUDA-runtime变体的 3.65 GB。镜像携带默认CMD但不是通过指定二进制名实现的一个 Dockerfile 服务三个服务而 Dockerfile 无法把构建参数插值进 exec 形式的CMD替代方案要么需要 distroless 基础镜像没有的 shell要么把 57 MB 的二进制再复制一份。于是工作流在二进制旁放置一个固定名字的相对符号链接worker - sns_worker十字节CMD [/usr/local/bin/worker]运行它。它是CMD而不是ENTRYPOINT因此编排栈中显式的command: [sns_worker, --database-url…]会直接替换它与 CPU 镜像行为完全一致默认CMD带来的好处是docker create和docker run可以在裸镜像上工作——这正是把二进制从镜像中取出的方式。二进制自身仍以本名出现在PATH上。推送到镜像仓库前的守卫二进制必须链接libcudartCPU 构建完全不链接 CUDA 运行时这能区分真正的 GPU 构建与中途丢弃--features gpu的构建每个镜像必须能实际exec用--version检查不需要数据库、不需要设备。这能捕获构建主机与运行时基础镜像之间的 glibc 或缺失库不匹配——开发期间两个方向都验证过针对 glibc 过旧的基础镜像退出码为 1针对 Chainguard 基础镜像退出码为 0。运行方式仅支持 Dispatch 触发push默认关闭便于在任何东西进入镜像仓库前先检查一次运行。在没有 cgr.dev 凭证的情况下测试时runtime-base输入可选用 Chainguard 的公共cgr.dev/chainguard/glibc-dynamic:latest与生产 pin 同一镜像族此时会跳过 cgr.dev 登录步骤。没有来自任何其他镜像仓库的镜像进入流水线libcudart从编译二进制的工具包中复制因此发布时运行时与编译器版本在构造上就一致标签中的 CUDA 版本从nvcc读取而不是取自可能与之不一致的输入。遥测风格指南tracing OpenTelemetryCoprocessor 各服务使用tracingspan 作为默认遥测 API并接入 OpenTelemetryOTLP。以下是仓库内各服务必须遵守的规则。规则用函数/span 名作为操作名不要添加operation ...span 字段不要把高基数标识符挂到 span 属性上不要在 span 上放txn_id、transaction_hash或handle如需调试把这些值记录到 event/log 行中异步工作用.instrument(...)包装 future不要跨.await持有span.enter()guard错误退出时设置 OTEL 错误状态仅仅记录日志不足以让 trace 看到错误保持 span 字段低基数、便于聚合好的例子有request_id、计数、布尔值、重试桶、链 id。推荐代码片段用#[tracing::instrument]声明整个函数为一个 spanskip_all避免记录大对象参数#[tracing::instrument(skip_all)] async fn process_proof(...) - anyhow::Result() { // business logic Ok(()) }对一段异步数据库操作单独建立 span并用.instrument(...)包裹 futureuse tracing::Instrument; let db_insert_span tracing::info_span!(db_insert, request_id); async { sqlx::query(UPDATE ...).execute(pool).await?; Ok::(), sqlx::Error(()) } .instrument(db_insert_span.clone()) .await?;在错误出口设置 OTEL 错误状态use tracing_opentelemetry::OpenTelemetrySpanExt; if let Err(err) do_work().instrument(span.clone()).await { span.context().span().set_status(opentelemetry::trace::Status::error(err.to_string())); return Err(err.into()); }这些片段在仓库中与tracing、tracing-opentelemetry、opentelemetry-otlp等依赖见 coprocessor/fhevm-engine/Cargo.toml配套使用各服务的--service-name参数即对应 OTLP trace 中的服务名。从代码与测试进一步验证workspace 组成与依赖coprocessor/fhevm-engine/Cargo.toml 展示了所有微服务成员及统一的依赖版本tfhe 1.6.3、sqlx 0.8.6、alloy 2.2.0、opentelemetry 0.29 等并对 release profile 启用了 fat LTO密钥生成实现generate_keys.rs 是cargo run generate-keys的实际入口tfhe-worker 入口tfhe_worker.rs 展示了--generate-fhe-keys与正常启动start_runtime的分支逻辑GPU 打包 DockerfileDockerfile.gpu 注释完整记录了 CUDA 架构选择逻辑、Chainguard 基础镜像选择、libcudart拷贝、固定名符号链接CMD、uid/gid 10000:10001 以及CUDA_MODULE_LOADINGEAGER的取舍生产部署配置charts/coprocessor/values.yaml 与 charts/coprocessor/templates 中的各 Deployment 模板展示了全部服务在生产 Kubernetes 集群中的参数注入方式基准测试负载tfhe-worker/README.md 提供了independent_300、dependent_1000_50x20、traffic_1000_200x5_10x100_lag2等标准 ERC20 基准场景及其 Grafana/SQL 查询方式可用于验证 worker 的依赖链调度与并行执行能力。结语FHEVM Coprocessor 把全同态加密计算从 EVM 符号执行中剥离出来形成一套由 host-listener、gw-listener、tfhe-worker、sns-worker、zkproof-worker、transaction-sender 等微服务构成的链下执行体系通过 PostgreSQL 解耦事件摄入与密文计算并利用依赖链实现并行调度。部署时既可以用cargo install从源码构建也可以消费 CPU/GPU 两种预构建镜像——GPU 镜像需严格按计算能力选择标签生产环境还支持 AWS RDS IAM 认证与 OpenTelemetry 全链路追踪。结合 coprocessor/docs 下的架构、配置与基准测试文档即可完成从单机冒烟测试到生产集群部署的全过程。【免费下载链接】fhevmFHEVM, a full-stack framework for integrating Fully Homomorphic Encryption (FHE) with blockchain applications项目地址: https://gitcode.com/GitHub_Trending/fh/fhevm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考