# FHEVM API specifications # Gateway API Specifications ## Endpoints

GET /keyurl ---- Retrieve links for retrieving the public keys and CRS' in the system.

#### Description This endpoint returns a JSON object containing URLs from an S3 bucket, allowing the client to download key files such as the blockchain public key, CRS files for input proof generation, the bootstrap key, and the address and public verification keys for each of the MPC servers running the TKMS. For each file (with the exception of the verification key and address), a list of cryptographic signatures is provided to ensure the integrity and authenticity of the downloaded content. These signatures should be considered as a multi-sig. This means that instead of needing all the signatures to validate the content, only a subset, specifically >1/3 of the total signatures (if n nodes are signing), is required to verify that the content is legitimate. No query parameters are required, as the gateway is already preconfigured for a specific blockchain. #### Query Parameters No parameters. #### Headers None. #### Response **Success (200 OK)** The request is successful, and the response will include a JSON object with a `status` and a `response`. The response again consists of the following elements: - `crs`: A map of containing information on the different CRS'. The key of the map is the max amount of bits the CRS can support proofs for. The value is an object of the following elements for the given CRS: * `data_id`: The 20 byte (lower-case) hex encoded handle/ID identifying the CRS. * `param_choice`: An integer representing the choice of parameters for the public key to be used with the CRS. * `signatures`: A list of signatures (one from each MPC party constituting the TKMS backend). Each signature is a hex (lower-case) encoded EIP712 signature on the `safe_serialization` of `PublicParam`. * `urls`: A list of URLs where the data can be fetched. The data at the end-point is a `safe_serialization` of `PublicParam`. - `fhe_key_info`: A list of objects, each representing information on a key-set in the system. More specifically each element consists of the following: * `fhe_public_key`: An element which contains information about the public encryption key of a FHE key set. More specifically it consists of the following elements: * `data_id`: The 20 byte (lower-case) hex encoded handle/ID identifying the key. * `param_choice`: An integer representing the choice of parameters used to generate the key. * `signatures`: A list of signatures (one from each MPC party constituting the TKMS backend). Each signature is a hex (lower-case) encoded EIP712 signature on the `safe_serialization` of `CompactPublicKey`. * `urls`: A list of URLs where the data can be fetched. The data at the end-point is a `safe_serialization` of `CompactPublicKey`. * `fhe_server_key`: An element which contains information about the server key (the key used to perform FHE operations on ciphertexts) of a FHE key set. More specifically it consists of the following elements: * `data_id`: The 20 byte (lower-case) hex encoded handle/ID identifying the key. * `param_choice`: An integer representing the choice of parameters used to generate the key. * `signatures`: A list of signatures (one from each MPC party constituting the TKMS backend). Each signature is a hex (lower-case) encoded EIP712 signature on the `safe_serialization` of `CompactPublicKey`. * `urls`: A list of URLs where the data can be fetched. The data at the end-point is a `safe_serialization` of `ServerKey`. - `verf_public_key`: **Deprecated and will be removed in the future. Should instead be fetched directly from the config contract on the TKMS blockchain** A list containing of elements, where each element is the information about a TKMS MPC server's signing key. That is, the key which a server uses to sign requests. More specifically each element of the vector consists of the following: * `key_id`: The 20 byte (lower-case) hex encoded handle/ID identifying the key. Currently this value is static for signing keys. That is, it will always be `408d8cbaa51dece7f782fe04ba0b1c1d017b1088`. * `server_id`: The integer ID of the server whose key is being described in the current element. This is an integer in the range [1; n], where n is the amount of MPC servers. * `verf_public_key_url`: The URL end-point of the given server where a serialization of the signing key can be found. The signing key is a `safe_serialization` of `PublicSigKey`. * `verf_public_key_address`: The URL end-point of the given server where a file containing the human-readable Ethereum address of the server's signing key. For example the following: ```json { "response": { "crs": { "256": { "data_id": "d8d94eb3a23d22d3eb6b5e7b694e8afcd571d906", "param_choice": 1, "signatures": [ "0d13...", "4250...", "a42c...", "fhb5..." ], "urls": [ "https://s3.amazonaws.com/bucket-name-1/PUB-p1/CRS/d8d94eb3a23d22d3eb6b5e7b694e8afcd571d906", "https://s3.amazonaws.com/bucket-name-4/PUB-p4/CRS/d8d94eb3a23d22d3eb6b5e7b694e8afcd571d906", "https://s3.amazonaws.com/bucket-name-2/PUB-p2/CRS/d8d94eb3a23d22d3eb6b5e7b694e8afcd571d906", "https://s3.amazonaws.com/bucket-name-3/PUB-p3/CRS/d8d94eb3a23d22d3eb6b5e7b694e8afcd571d906" ] } }, "fhe_key_info": [ { "fhe_public_key": { "data_id": "408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "param_choice": 1, "signatures": [ "cdff...", "123c...", "00ff...", "a367..." ], "urls": [ "https://s3.amazonaws.com/bucket-name-1/PUB-p1/PublicKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "https://s3.amazonaws.com/bucket-name-4/PUB-p4/PublicKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "https://s3.amazonaws.com/bucket-name-2/PUB-p2/PublicKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "https://s3.amazonaws.com/bucket-name-3/PUB-p3/PublicKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088" ] }, "fhe_server_key": { "data_id": "408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "param_choice": 1, "signatures": [ "839b...", "baef...", "55cc...", "81a4..." ], "urls": [ "https://s3.amazonaws.com/bucket-name-1/PUB-p1/ServerKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "https://s3.amazonaws.com/bucket-name-4/PUB-p4/ServerKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "https://s3.amazonaws.com/bucket-name-2/PUB-p2/ServerKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "https://s3.amazonaws.com/bucket-name-3/PUB-p3/ServerKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088" ] } } ], "verf_public_key": [ { "key_id": "408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "server_id": 1, "verf_public_key_address": "https://s3.amazonaws.com/bucket-name-1/PUB-p1/VerfAddress/408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "verf_public_key_url": "https://s3.amazonaws.com/bucket-name-1/PUB-p1/VerfKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088" }, { "key_id": "408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "server_id": 4, "verf_public_key_address": "https://s3.amazonaws.com/bucket-name-4/PUB-p4/VerfAddress/408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "verf_public_key_url": "https://s3.amazonaws.com/bucket-name-4//PUB-p4/VerfKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088" }, { "key_id": "408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "server_id": 2, "verf_public_key_address": "https://s3.amazonaws.com/bucket-name-2/PUB-p2/VerfAddress/408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "verf_public_key_url": "https://s3.amazonaws.com/bucket-name-2/PUB-p2/VerfKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088" }, { "key_id": "408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "server_id": 3, "verf_public_key_address": "https://s3.amazonaws.com/bucket-name-3/PUB-p3/VerfAddress/408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "verf_public_key_url": "https://s3.amazonaws.com/bucket-name-3/PUB-p3/VerfKey/408d8cbaa51dece7f782fe04ba0b1c1d017b1088" } ] }, "status": "success" } ``` **Error Responses** | Status Code | Error Code | Description | | ----------- | ------------ | ------------------------------------------------ | | 400 | `BadRequest` | The request is invalid or missing required parameters. | | 404 | `NotFound` | The requested resource was not found. | | 500 | `ServerError` | An internal server error occurred. | #### Example Error Responses ```json { "error": "BadRequest", "message": "The request is invalid or missing required parameters." } ``` ```json { "error": "NotFound", "message": "The requested resource was not found." } ``` ```json { "error": "ServerError", "message": "An internal server error occurred. Please try again later." } ```

POST /verify_proven_ct ---- Input a batch of proven ciphertexts to be validated by the TKMS.

#### Description This endpoint returns a JSON object containing all the signatures on the proven ciphertexts from the TKMS servers. Furthermore the response contains some meta-information distinguishing if the response is for the co-processor setting or FHEVM native setting. In case of the co-processor setting, then the ciphertext storage handles and a signature from the co-processor attesting correct storage is also included. The signatures from the TKMS should be considered as a multi-sig. This means that instead of needing all the signatures to validate the content, only a subset, specifically >1/3 of the total signatures, is required to verify that the content is legitimate. #### Query Parameters Multiple parameters must be supplied in JSON format: - `contract_address`: An EIP-55 encoded address (that is, including the `0x` prefix) of the contract where the proven ciphertext is to be submitted. - `caller_address`: An EIP-55 encoded address (that is, including the `0x` prefix) of the user who is providing the encrypted input. - `crs_id`: The 20 byte (lower-case) hex encoded handle/ID identifying the CRS used to construct the proof. - `key_id`: The 20 byte (lower-case) hex encoded handle/ID identifying the public key used to encrypt the ciphertext with. - `ct_proof`: A hex encoding of the serialization of the proven ciphertext. More specifically the TFHE-RS object `ProvenCompactCiphertextList` serialized using `safe_serialization`. ```json { "contract_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed", "caller_address": "0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb" , "crs_id": "d8d94eb3a23d22d3eb6b5e7b694e8afcd571d906", "key_id": "408d8cbaa51dece7f782fe04ba0b1c1d017b1088", "ct_proof": "cdff...", } ``` #### Headers None. #### Response **Success (200 OK)** The request is successful, and the response will include a JSON object with a `status` and a `response` which consists of the following: - `handles`: A vector of handles to each of the ciphertexts which have been proven knowledge of. A handle is a 32 byte (lower-case) hex encoded handle/ID identifying the ciphertext. - `kms_signatures`: A list of signatures (one for each of the TKMS servers that respond to the query). Each signature is a hex (lower-case) encoded EIP712 signature on the `safe_serialization` of `ProvenCompactCiphertextList`. - `listener_type`: An enum expressing whether the result is for an FHEVM native (`FHEVM_NATIVE`) or co-processor respectively (`COPROCESSOR`). - `proof_of_storage`: An optional signature from the co-processor. More specifically if FHEVM native is used it will be an empty string, otherwise it will be a hex (lower-case) encoded EIP712 signature on the request. For example the following: ```json { "response": { "handles": [ "0748b542afe2353c86cb707e3d21044b0be1fd18efc7cbaa6a415af055bfb358", "054ab4515b1541878723431005054f154e15e45e15800adb67879679df670456" ], "kms_signatures":[ "15a4f9a8eb61459cfba7d103d8f911fb04ce91ecf841b34c49c0d56a70b896d20cbc31986188f91efc3842b7df215cee8acb40178daedb8b63d0ba5d199bce121c", "118165165165423465234414c4c468a4d9684d8e18186d6f786161b4b436c58787cc68418186d6f786161b4b98461166a6a6668e8e118542c154867aab238abd79", "1c849848940128065242121b2b12121ed876986da251561650c654564d684654e51610879a9a9798b78b78e7f8787d87c8c8894a454547809586616161464cc8a8", "10c864ac145423466798808098c098b09a8908d6432da4544f5e54566b76740454654a54c65454565d65d657e44651241561342441234128888063304854897893", ], "listener_type": "COPROCESSOR", "proof_of_storage": "17acd15648740c00849f489498489e4600a60a06068d484b084894988333000cff798751651498d68768753567a4356787c45787e79i8f64d128218927897c8789" }, "status": "success" } ``` **Error Responses** | Status Code | Error Code | Description | | ----------- | ------------ | ------------------------------------------------ | | 400 | `BadRequest` | The request is invalid or missing required parameters. | | 404 | `NotFound` | The requested resource was not found. | | 500 | `ServerError` | An internal server error occurred. | #### Example Error Responses ```json { "error": "BadRequest", "message": "The request is invalid or missing required parameters." } ``` ```json { "error": "NotFound", "message": "The requested resource was not found." } ``` ```json { "error": "ServerError", "message": "An internal server error occurred. Please try again later." } ```

POST /reencrypt ---- Decrypt a ciphertext under an ephemeral key s.t. a client can learn the decrypted value privately.

#### Description This end-point returns a JSON object containing a signcryption of the plaintext value of an FHE ciphertext that has been (obliviously) decrypted by the TKMS. More specifically the TKMS servers carry out a partial decryption resulting in each of them knowing a secret share of the plaintext (meaning that multiple servers need to maliciously collude in order to learn the decrypted plaintext). They each then signcrypt their share of the plaintext. The response consists of each of these signcryptions along with meta information about the threshold setup and which server provides each signcrypted share of the result. Since the signcryption is based on secret sharing it means that only a subset, specifically >1/3 of the total responses, is required to recover the result (assuming all returned signcryptions are correct). #### Query Parameters Multiple parameters must be supplied in JSON format: - `signature`: A hex (lower-case) encoded EIP712 signature on the public encryption key, `enc_key`, under which the of the ciphertext in question will be reencrypted. - `client_address`: An EIP-55 encoded address (that is, including the `0x` prefix) of the end-user who is supposed to learn the reencrypted response. - `enc_key`: The hex (lower-case) encoded public encryption key (libsodium) which the reencryption should be signcrypted under. - `ciphertext_handle`: The 32 byte (lower-case) hex encoded handle/ID identifying the ciphertext and hence allowing the gateway to fetch it. - `eip712_verifying_contract`: An EIP-55 encoded address (that is, including the `0x` prefix) of the contract holding the ciphertext to reencrypt. ```json { "signature": "15a4f9a8eb61459cfba7d103d8f911fb04ce91ecf841b34c49c0d56a70b896d20cbc31986188f91efc3842b7df215cee8acb40178daedb8b63d0ba5d199bce121c", "client_address": "0x17853A630aAe15AED549B2B874de08B73C0F59c5", "enc_key": "2000000000000000df2fcacb774f03187f3802a27259f45c06d33cefa68d9c53426b15ad531aa822", "ciphertext_handle": "0748b542afe2353c86cb707e3d21044b0be1fd18efc7cbaa6a415af055bfb358", "eip712_verifying_contract": "0x66f9664f97F2b50F62D13eA064982f936dE76657" } ``` #### Headers None. #### Response **Success (200 OK)** The request is successful, and the response will include a JSON object with a `status` and a `response` which is a list of responses from each TKMS. More specifically each element in the list consists of the following: - `payload`: A bincode encoding of the signcryption from a single server along with meta information including the server ID, threshold parameter, type of value encrypted and the specific public key of the server supplying the specific response. - `signature`: An EIP712 signature which is hex (low-case) encoded. For example the following: ```json { "response": [ { "payload": "161c5...", "signature": "15a4f9a8eb61459cfba7d103d8f911fb04ce91ecf841b34c49c0d56a70b896d20cbc31986188f91efc3842b7df215cee8acb40178daedb8b63d0ba5d199bce121c" }, { "payload": "44546...", "signature": "118165165165423465234414c4c468a4d9684d8e18186d6f786161b4b436c58787cc68418186d6f786161b4b98461166a6a6668e8e118542c154867aab238abd79" }, { "payload": "54cd5...", "signature": "1c849848940128065242121b2b12121ed876986da251561650c654564d684654e51610879a9a9798b78b78e7f8787d87c8c8894a454547809586616161464cc8a8" }, { "payload": "a516b...", "signature": "10c864ac145423466798808098c098b09a8908d6432da4544f5e54566b76740454654a54c65454565d65d657e44651241561342441234128888063304854897893" }, ], "status": "success" } ``` **Error Responses** | Status Code | Error Code | Description | | ----------- | ------------ | ------------------------------------------------ | | 400 | `BadRequest` | The request is invalid or missing required parameters. | | 404 | `NotFound` | The requested resource was not found. | | 500 | `ServerError` | An internal server error occurred. | #### Example Error Responses ```json { "error": "BadRequest", "message": "The request is invalid or missing required parameters." } ``` ```json { "error": "NotFound", "message": "The requested resource was not found." } ``` ```json { "error": "ServerError", "message": "An internal server error occurred. Please try again later." } ```

## Smart Contract selectors All smart contract selectors can be found in the [contract selectors](../../selectors.txt) file. { "name": "cli-fhevm-sdk", "type": "module", "private": true, "bin": { "fhevm-sdk": "./bin/fhevm-sdk.mjs" }, "engines": { "node": ">=22.0.0" }, "scripts": { "build": "tsdown", "cli": "node dist/index.mjs", "cli:dev": "node --import tsx index.ts", "test": "vitest run", "typecheck": "tsc --noEmit" }, "devDependencies": { "tsdown": "^0.22.2", "tsx": "^4.21.0", "vitest": "^3.2.4" }, "dependencies": { "@cli-fhevm-sdk/toolkit": "workspace:*", "@commander-js/extra-typings": "^15.0.0", "@fhevm/sdk": "0.13.2", "@pnpm/tabtab": "^0.5.4", "commander": "^15.0.0", "consola": "^3.4.2", "viem": "^2.50.4" } } { "extends": "../../tsconfig.base.json" } # Design Skill Path: `sdk/cli-js-sdk/packages/load-test/docs/design/dual-relayer-dispatch.md` [View Raw Content on GitHub](https://raw.githubusercontent.com/zama-ai/fhevm/HEAD/sdk/cli-js-sdk/packages/load-test/docs/design/dual-relayer-dispatch.md) # Docs Skill Path: `sdk/cli-js-sdk/packages/load-test/docs/OPERATIONS.md` [View Raw Content on GitHub](https://raw.githubusercontent.com/zama-ai/fhevm/HEAD/sdk/cli-js-sdk/packages/load-test/docs/OPERATIONS.md) { "name": "@cli-fhevm-sdk/load-test", "version": "0.1.0", "type": "module", "private": true, "engines": { "node": ">=22.0.0" }, "scripts": { "load-test": "node --import tsx index.ts", "typecheck": "tsc --noEmit", "test": "vitest run" }, "dependencies": { "@cli-fhevm-sdk/toolkit": "workspace:*", "@commander-js/extra-typings": "^15.0.0", "@fhevm/sdk": "0.13.2", "commander": "^15.0.0", "consola": "^3.4.2", "hdr-histogram-js": "^3.0.0", "piscina": "^5.1.3", "undici": "^7.16.0", "viem": "^2.50.4", "zod": "^4.1.12" }, "devDependencies": { "tsx": "^4.21.0", "vitest": "^3.2.4" } } # Load-test Skill Path: `sdk/cli-js-sdk/packages/load-test/tsconfig.json` [View Raw Content on GitHub](https://raw.githubusercontent.com/zama-ai/fhevm/HEAD/sdk/cli-js-sdk/packages/load-test/tsconfig.json) # Toolkit Skill Path: `sdk/cli-js-sdk/packages/toolkit/package.json` [View Raw Content on GitHub](https://raw.githubusercontent.com/zama-ai/fhevm/HEAD/sdk/cli-js-sdk/packages/toolkit/package.json) # Toolkit Skill Path: `sdk/cli-js-sdk/packages/toolkit/tsconfig.json` [View Raw Content on GitHub](https://raw.githubusercontent.com/zama-ai/fhevm/HEAD/sdk/cli-js-sdk/packages/toolkit/tsconfig.json) # relayer-http — development guide This file is living: add a rule or change a description here whenever a feature lands that affects them, in the same change. It describes a minimal first version. ## What this repo is The Zama relayer over HTTP. It replaces the gateway-chain decryption path: request handlers receive the SDK's decryption requests and the `kms_aggregator` module fans them out to the KMS connector endpoints and aggregates the t-of-n answers. **Minimal first version**: the handlers and the fan-out/aggregation only. - No ACL check and no ciphertext-commit (readiness) check in the relayer: the connector's worker performs them and their failures come back as connector error codes. Both can come back later as optional modules in front of the aggregator. - No database, no queue, no cache, no response storage. ## Layout ``` relayer-http/ ├── Cargo.toml, Cargo.lock, rust-toolchain.toml # workspace, exact dependency pins (=x.y.z), toolchain 1.97.1 ├── Dockerfile # container image, built from the repository root (see Container image) ├── .gitignore # target/, config/*.local.yaml (local variants of the configuration) ├── config/config.yaml # example configuration: name, log, http, kms_aggregator ├── dev/ # local development tooling: Makefile, per-topology configs, proxy port-forwards, flow scripts; start with its README.md └── crates/relayer-http/src/ ├── main.rs # load config → init logging → App → serve until SIGINT/SIGTERM → drain → exit ├── lib.rs # App: the one shared state (both aggregators, http config, shutdown token) ├── config.rs # RelayerConfig, LogConfig, HttpConfig: YAML + APP_

__ overrides ├── logging.rs # tracing subscriber (json | pretty | compact, RUST_LOG) + Log: one request's identifiers on every line ├── endpoint/ # the HTTP layer; start with its docs.md │ ├── mod.rs # router() and serve() │ ├── error.rs # ApiError: the one error body and its mapping │ ├── validate.rs # rules shared by the routes (handles, extraData) │ ├── ops.rs # GET /liveness, GET /healthz │ └── flows/{mod,user_decrypt,public_decrypt}.rs # one file per route: wire types, validation, handler (logs each step) └── kms_aggregator/ # fan-out to the KMS connectors and t-of-n aggregation; start with its docs.md ├── mod.rs, config.rs, client.rs, call.rs, aggregator.rs ├── flows/{mod,user_decrypt,public_decrypt}.rs # one file per flow: checks, counting, output ├── mock.rs, scenarios.rs # test only: scripted connector, YAML scenario runner └── scenarios/*.yaml # behaviour scenarios, run by cargo test ``` Two modules, each with its `docs.md` next to the code: `endpoint/docs.md` (routes, payloads, responses, every error code and its mapping) and `kms_aggregator/docs.md` (how an aggregation runs, one node call, checks, configuration → behaviour). The implementation plans live outside the repository (`relayer_specs_plans/`). ## Configuration One YAML file (`config/config.yaml` is the example), four sections: `name`, `log` (optional, defaults to JSON lines), `http` (bind address, body limit, body read timeout, supported chain ids) and `kms_aggregator` (deadline, retries, thresholds, optional checks, the KMS endpoints). Any field can be overridden with `APP_

__` (durations carry a unit, e.g. `APP_KMS_AGGREGATOR__CALL__TIMEOUT=7s`). API keys are never in the file: each endpoint names the env var holding its key. Local variants go to `config/*.local.yaml`, ignored by git. ## Commands From `relayer-http/`: ```sh cargo fmt -- --check # not --all: cargo-fmt would follow the kms-connector-api path dependency into generated bindings cargo clippy --workspace --all-targets -- -W clippy::perf -W clippy::suspicious -W clippy::style -D warnings cargo test --workspace cargo test -p relayer-http yaml_scenarios # the aggregator scenarios only cargo run -p relayer-http -- config/config.yaml # needs the KMS__API_KEY env vars named in the config ``` Every change must pass the first three. Check exit codes strictly (a grep on the output hides a failing build). Against the local fhevm stack: `make -C dev up` (connector proxies and their host port-forwards), `make -C dev run` (the relayer with the config matching the running topology), `make -C dev public-decrypt` / `user-decrypt` (one flow each, from the e2e container), `make -C dev check` (the three commands above). See `dev/README.md`. ## Container image `Dockerfile` follows the relayer's and the kms-connector's model: the golden `rust-glibc` builder pinned by `RUST_IMAGE_VERSION` (single source of truth: `rust-toolchain.toml`, read by the CI template), `cargo build --locked --release`, a `glibc-dynamic` runtime running as the `fhevm` user, no configuration baked in. The build context is the **repository root**: the crate depends on `kms-connector/crates/api` by path and that workspace references its siblings, which the Dockerfile copies at the same relative places. ```sh # from the repository root docker build -f relayer-http/Dockerfile --build-arg RUST_IMAGE_VERSION=1.97.1 -t relayer-http . docker run --rm -p 8080:8080 -v "$PWD/relayer-http/config/config.yaml:/app/config/config.yaml:ro" \ -e KMS_00_API_KEY=... relayer-http # the config is mounted at /app/config/config.yaml ``` CI publishes the image as `ghcr.io/zama-ai/fhevm/relayer-http` through `.github/workflows/relayer-http-docker-build.yml` (pushes to `main`/`release/*`, releases, manual runs, or a call from the e2e orchestrator). The two other workflows, `relayer-http-tests.yml` and `relayer-http-dependency-analysis.yml`, run on pull requests: the three commands above, then `cargo update -w --locked`, `cargo-deny check license` against `deny.toml` (every allowed license must be used) and `cargo-audit audit` with `.cargo/audit.toml`. All three are gated on changes under `relayer-http/**`, `kms-connector/crates/api/**` and `kms-connector/Cargo.toml`. ## Rules **No gateway interaction.** The relayer never talks to the gateway chain and carries no gateway-specific configuration, optional checks included. Every on-chain read goes to a host chain through host contracts, Ethereum being the reference. **No unexpected panic.** Both crate roots deny `clippy::unwrap_used`, `expect_used`, `indexing_slicing` and `panic` (allowed in tests). Every failure is a typed error returned to the caller. Configuration validation bounds every value the runtime arithmetic relies on (`call.timeout <= 60s`, `backoff_max <= call.timeout`, semaphore size capped) so that no arithmetic can overflow later. A panic inside a spawned task is counted as a failure, never propagated. **Fail fast.** Never wait for something that cannot change the outcome: when `counted + pending < threshold` the remaining calls are cancelled at once. One deadline per request, no queue, no ETA; the client retries. **HPA compatible.** No per-request state outside the request's own future: no shared map, no registry, no sticky session. Every replica is identical; the call semaphore is per pod. If per-request state is ever needed, it goes behind a trait so that Redis (or another store) can back it later. **Errors.** Modules return typed errors (`thiserror`), with what the caller needs to act (counts, dominant connector error). Errors are logged once, at the boundary that answers the client. No `error!` inside a module for an expected failure. **Logging.** `tracing` only, structured fields, short messages. Every endpoint line about a request goes through its `Log` (`logging.rs`) and carries `request_id`, `flow`, `handles`, `decryption_id`, the last two `none` until known: a known event is a method on `Log`, any other line is `log!(level, log, fields…, "message")`. Aggregator lines carry the same identifiers through the `aggregation` span; a task spawned for a request inherits it (`in_current_span`). Every failed node attempt is one `warn`. Never log request or response bodies, shares, signatures, header values or URLs. The subscriber is installed by `main`, never by a module; `log:` is optional and defaults to JSON lines (`log.format`: `json` | `pretty` | `compact`, plus the relayer's `show_*` switches); the level filter is `RUST_LOG`, default `warn,relayer_http=info`. **Configuration.** Nested structs use `deny_unknown_fields`; `validate()` messages name the field with its dotted path (`kms_aggregator.call.timeout must …`); secrets appear only as env var names; durations carry a unit. **Minimal code.** Few types, one function per loop, a one-line doc comment per item, no framework where a function does. Production-ready means no panic, typed errors, logs, cancellation and tests, not features. **Compatibility.** The connector interface comes from the `kms-connector-api` crate (path dependency, never its `endpoint` feature): DTOs, routes, error codes and their `retryable` flag are used as they are, never redefined. **Tests.** A unit test per function, next to it. Paused tokio time (`start_paused`) for anything timed, so durations are exact and tests are instant. Behaviour is described in YAML scenarios run by `cargo test`; adding a case is adding a file. **Documentation.** Every module has a `docs.md` produced with the module and updated in the same change as any behaviour change, plus a one-line doc comment on every item. The error code table in `endpoint/docs.md` (every code, its status, when it happens, how aggregation errors map to it) is updated in the same change as any change to that mapping. This `CLAUDE.md` is updated the same way: new rules and changed descriptions land with the feature that motivates them. # @cli-fhevm-sdk/load-test Protocol load-test tool for both the legacy relayer and relayer v2. It provides model-aware load generation built on the workspace toolkit and `@fhevm/sdk`, with pre-generated payload pools, implementation-agnostic client evidence, capability-detected Prometheus metrics, and machine-readable reports. ```text plan → explicit prepare (when needed) → execute → collect → report ``` **Operators:** see [`docs/OPERATIONS.md`](./docs/OPERATIONS.md). Start with `suite plan `. A normal `suite run` never creates missing pool material: use `suite prepare`, or add `--prepare` to explicitly authorize the local CPU and funded on-chain work before execution. `suite show ` (built-in name or suite JSON path) prints the resolved suite as JSON, including every resolved entry, mirroring `scenario show`. ## How each flow is driven | Flow | Transport | Payload source | Verification | | --- | --- | --- | --- | | `input-proof` | raw HTTP (undici `Pool`) | pre-generated ZK-proof payloads (piscina workers) | `accepted` + returned handles equal locally computed handles | | `public-decrypt` | `@fhevm/sdk` | unique k-combinations of pooled public FHETest handles | SDK signature verification and typed cleartexts vs known plaintexts | | `user-decrypt` | `@fhevm/sdk` (`decryptValues`) | pooled private handles, reusable | SDK KMS verification/reconstruction; plaintext vs known value | | `delegated-user-decrypt` | `@fhevm/sdk` (`decryptValues`) | pooled delegator-owned handles + ACL delegation | same as user-decrypt, with a delegated permit | SDK-driven flows pass the run `AbortSignal`, timeout, and per-request `x-request-id` through the SDK relayer options. Progress events provide job, retry, submit, poll, timeout, and error metadata for the request record. User-decrypt permit lifetime is derived from the request timeout plus a two-minute clock-skew allowance, rounded up to the smallest whole-day duration the v13 SDK accepts. SDK verification/reconstruction failures after a successful relayer GET are recorded as `verify_failed`, not ordinary transport failures. Terminal client outcomes are intentionally disjoint: | Outcome | Meaning | | --- | --- | | `succeeded` | terminal success and local verification passed | | `submit_failed` | transport failure or non-202 response before a job existed | | `failed` | the relayer reported a valid terminal failure | | `verify_failed` | a valid success response failed cryptographic/value verification | | `timed_out` | the per-request deadline elapsed before a terminal response | | `protocol_error` | a success-status relayer envelope violated the runtime wire schema | | `aborted` | the operator or suite lifecycle deliberately cancelled the leg | `pollCount` is the number of GET attempts issued. It is a dimensionless count, not a retry index or duration; reports expose count statistics without `Ms` suffixes. Aborted legs are reported separately and excluded from workload error rate denominators. With `--relayer-b-url`, SDK-driven A/B measurements are independent target legs over the same claimed workload item. User/delegated legs generate independent transport keys and permits; they are not byte-identical raw dispatches and must not be assumed to deduplicate. See [`docs/design/dual-relayer-dispatch.md`](./docs/design/dual-relayer-dispatch.md). **Dedup constraint.** Relayer dedup is permanent for successful requests, so input-proof payloads and public-decrypt handle combinations are single-use per environment. Pools are consumed through persisted cursors that advance *before* use — an aborted run skips items, never reuses one. User-decrypt requests are always unique because the dedup hash includes the per-leg transport public key. ## Setup Environment (read from the workspace-root `.env` or the environment): - `MNEMONIC` — funding wallet; handle pools derive parallel HD lanes from it (`PRIVATE_KEY` works too, but limits pool creation to one lane). - `DELEGATE_PRIVATE_KEY` — sign-only delegate account for `delegated-user-decrypt` pools when no mnemonic is set (with a mnemonic the delegate is derived at a reserved HD index). - Host-chain RPC override: `SEPOLIA_RPC_URL` for `testnet` and `devnet`, `POLYGON_AMOY_RPC_URL` for `testnet-amoy` and `devnet-amoy`, `MAINNET_RPC_URL` for `mainnet`, and `POLYGON_RPC_URL` for `polygon`. Public network defaults are used when the matching variable and `--rpc-url` are both absent. - `ZAMA_FHEVM_API_KEY` — optional SDK and raw-relayer API-key authentication. - `ZAMA_FHEVM_API_KEY_B` — optional distinct API key for the candidate relayer (`--relayer-b-url`); falls back to `ZAMA_FHEVM_API_KEY` when unset. - `LOAD_TEST_RELAYER_URL`, `LOAD_TEST_NETWORK`, `LOAD_TEST_DATA_DIR`, `LOAD_TEST_RELAYER_CONFIG` — defaults for the matching CLI flags. All commands run from this directory with `node --import tsx index.ts …` (alias: `pnpm load-test …`). ## Pools ```bash # Single-use input-proof payloads (CPU-bound; uses a worker pool) node --import tsx index.ts pool add input-proof --count 2000 --value-types uint64 # Decrypt handle pools (on-chain FHETest transactions; the expensive step) node --import tsx index.ts pool add public-decrypt --count 20 --lanes 4 node --import tsx index.ts pool add user-decrypt --count 4 node --import tsx index.ts pool add delegated-user-decrypt --count 4 node --import tsx index.ts pool status ``` `pool add` has one subcommand per flow, and each exposes only the flags that flow consumes: `input-proof` takes `--threads`; the on-chain decrypt flows take `--lanes` and `--encrypt-concurrency`; `delegated-user-decrypt` additionally takes `--delegation-days`. All accept `--count` and `--value-types`. `pool status` labels each delegated owner ACL as healthy, expired, or missing. A pool of *n* public handles serves C(n, k) unique k-handle public-decrypt requests (`handlesPerRequest` in the scenario), so handle creation amortizes across many requests. Pools live under `/pools//`. User/delegated pools retain reusable handles and account/delegation metadata; they intentionally do not persist transport private keys or signed permits. Those are generated independently inside each SDK target leg. ## Load models - **Open** fixes arrivals: "Can the relayer sustain X new requests/sec?" Submissions are scheduled independently of response latency, so late jobs do not reduce offered load. - **Closed** fixes active clients: "Can Y active clients run with acceptable latency, and what throughput results?" Each VU runs request → terminal or timeout → optional think time → next request. - **Drain** fixes backlog size: submit N jobs near-instantly, then poll all to completion. This validates backlog correctness and configured drain rate. `thinkTimeMs` is the closed-model pause between completed workflows. It is not the poll interval; polling still honors `Retry-After` while one request is in progress. Closed scenarios without `maxIterations` are duration-bound. They are allowed for reusable user/delegated handles. Closed `input-proof` and `public-decrypt` scenarios must set `maxIterations`, because those pools are single-use. ## Running scenarios ```bash node --import tsx index.ts scenario plan open-steady --rps 20 --duration 600 --out /tmp/open-steady-plan node --import tsx index.ts scenario prepare open-steady --rps 20 --duration 600 node --import tsx index.ts scenario run open-steady --rps 20 --duration 600 --flow input-proof node --import tsx index.ts scenario run open-ramp --rps 10 --duration 120 node --import tsx index.ts scenario run closed-steady --vus 20 --duration 600 --flow user-decrypt node --import tsx index.ts scenario run closed-ramp --vus 5 --duration 120 --flow delegated-user-decrypt node --import tsx index.ts scenario run drain --count 1000 --rps 200 node --import tsx index.ts scenario run scenarios/my-scenario.json --baseline baselines/testnet/open-steady.json ``` Built-ins (`scenario list` / `scenario show `): `baseline`, `smoke`, `open-steady`, `open-ramp`, `open-spike`, `open-soak`, `open-mixed`, `closed-steady`, `closed-ramp`, `closed-soak`, `drain`. Steady-state defaults are gentle (well under the protocol ceilings of ~20 rps input-proof and ~10 rps combined decrypt), with one intentional exception: the saturation probes `open-ramp` and `open-spike` deliberately reach or exceed the ceilings to measure capacity and recovery. `open-ramp` steps above the ceiling and so emits the advisory ceiling warning by design (expected, not a misconfiguration). Any resolved scenario whose peak per-flow rate exceeds a ceiling emits that advisory warning but still runs. Custom scenarios are JSON documents validated against the schema in `src/scenario/schema.ts` (flow mix and weights, load shape, timeouts, thresholds, saturation stop). `scenario run` is the canonical entry point. The same overrides apply to built-ins, custom JSON scenarios, and suite-entry `params`; they are resolved before pool planning. Unsupported shape/option combinations fail instead of being ignored: - `--rps` replaces a constant or burst rate. For segmented shapes it scales the complete rate profile relative to its first positive configured rate. - `--vus` replaces steady VUs. For staged closed shapes it scales every stage relative to the first stage, rounding to positive integers. - `--duration` replaces a steady duration, or **each** segment/stage duration; it is not a total-duration override. - `--count` is burst-only. `--think-time` and `--max-iterations` are closed-model-only. - `--flow` is valid only for a single-flow scenario. It preserves that flow entry's weight and `handlesPerRequest`; multi-flow scenarios reject it. Read-only commands (`scenario list`, `scenario plan`, `suite list`, `suite plan`, `baseline list`, `pool status`, `report diff`) accept `--format text|json`. In `json` mode they print exactly one JSON document to stdout and suppress the info/success/warning log lines, so the output is safe to pipe into `jq` or a script; errors still go to stderr. Operator-authored JSON definitions are intentionally untracked by the local ignore policies in `scenarios/` and `suites/`. JSON paths are resolved from the load-test process working directory, not relative to a referring suite file. The commands documented here run from this package directory; the workspace `pnpm load-test` alias also launches the package there. Within a suite, use a package-relative path such as `scenarios/my-scenario.json` or an absolute path for a definition stored elsewhere. ## Collectors (all optional; absence degrades the report, never the run) - **Prometheus** — scrapes the configured relayer `/metrics` every 5 s and is agnostic to the server implementation; the report records capability and scrape-health information, then reports only signals actually exported by that relayer. Scrape counts, current attempt state, timestamps, and the most recent failure are retained so a recovered scrape is distinguishable from both uninterrupted collection and current outage. Capabilities are detected from exported metric families. Legacy request-status gauges provide queue depth and stage durations, while legacy throttler gauges report peak and final in-process queue depth. Relayer v2 metrics retain their native semantics: input-proof inserts/duration, transaction outcomes/duration/errors, recovery runs/items/duration, wallet-lease state/transitions, DB errors, and HTTP endpoint/status counts. Missing families stay unavailable rather than being inferred across implementations. Counter or histogram resets are marked as conservative lower bounds, including aggregate HTTP totals and rates. Neither current exporter exposes sqlx pool connection/acquire-wait families. - **Config snapshot** (`--relayer-config `) — embeds the relayer config file in the report after recursively redacting secret-bearing fields and credential material; throughput is config-capped, so reports without the non-secret operational settings are harder to interpret. ## Outputs Each run writes to `/runs/-/`: - `report.json` — canonical machine-readable report. - `report.md` — human rendering (also produced by `report render `). - `requests.jsonl` — one record per request (sent/echoed request ids, jobId, submit latency, poll count, terminal latency, outcome, error label). - `requests-a.jsonl` and, for dual-target runs, `requests-b.jsonl` — the same per-request records split by target, for isolated per-leg analysis. - `metrics-a.jsonl` and, for dual-target runs, `metrics-b.jsonl` — retained Prometheus collector time series. - `injector-runtime.jsonl` — the load-test process's own runtime samples (event-loop lag/utilization, CPU, RSS, GC) plus scheduler dispatch-lag, backpressure, drop, and abandon accounting, independent of the relayer. Planning and preparation evidence uses the same stable names: - `pool-plan.json` is the authoritative, versioned machine-readable live observation; `pool-plan.md` is its human-readable mirror. - Explicit preparation also writes authoritative `preparation.json` plus `preparation.md`. Standalone preparation defaults to `/preparations/-scenario-/`; when a `scenario run --prepare` actually needs preparation, it places that evidence in the run directory. - Scenario and suite plan commands write evidence only when `--out ` is given; without it they remain read-only and print the plan without creating directories. - `suite prepare` defaults under `/preparations/`; `suite run` writes its plan, optional preparation evidence, scenario reports, and suite summary under one run root. - `scenario run` likewise allocates one stable run root and records its initial live plan there before deciding whether to execute. A deficient run without `--prepare` exits 2 and leaves that plan evidence for review; a ready run proceeds without redundant preparation even if `--prepare` was supplied. The shared operator summary keeps units explicit: finite workloads show a request budget, duration-bound closed decrypt workloads show a reusable-handle target instead of inventing a request count, and deficits are pool creation units. Planned actions are labeled `[LOCAL CPU]` or `[ON-CHAIN]`; handle actions state the funded setter-transaction count, while delegated ACL costs are identified separately. Dedicated `scenario prepare` and `suite prepare` still write no-op preparation evidence when pools are ready, but the readiness gate runs only immediately before a fresh plan's first actual action. Each `pool-plan` and `preparation` file is flushed and atomically renamed independently. Their JSON is authoritative; a crash between JSON and Markdown publication can leave the mirror from a different attempt. This durability claim does not extend to suite summaries, suite-preparation wrappers, or streaming JSONL. The scenario digest binds the fully resolved, ordered scenario definitions and suite pause, while the recorded environment identity binds the target network, chain, contract, relayer origins, and API paths. Compare both fields—neither alone identifies the complete plan. Stored plans are evidence only: preparation always computes a fresh live plan and then re-inspects before declaring readiness. Artifacts omit configured RPC URLs and data directories, strip relayer URL userinfo/query data, and bound and sanitize recognized credential patterns in error text. Sanitization is defensive rather than a guarantee against every possible secret format; inspect artifacts before sharing them. The report records the run model (`open`, `closed`, or `drain`) and each flow's driver (`raw-http` for input-proof, `sdk` for decrypt flows). It leads with an **Executive Summary**: target identity, model/status/window, planned versus submitted workflows and achieved rate, threshold/correctness verdicts, performance evidence, injector assessment, and telemetry coverage. When the evidence supports actionable findings, **Diagnosis** follows with severity-tagged flags and concrete recommendations. Below it: per-flow client histograms; **client results by load stage** for ramp/sweep scenarios; capability-gated relayer metric deltas and relayer-side **HTTP** status distribution; **backlog-by-stage** (where the queue sat, and whether it drained or grew); **process/host** RSS·CPU·FD trends with drift-per-hour for soaks; and the relayer config snapshot. This package intentionally does not connect to PostgreSQL. Server-row correlation, poll-free server e2e comparison, and database-timestamp pipeline stages are future adapter boundaries in the report model, not data collected by the current command surface. Command exit codes are stable for automation: - `0`: operation completed and acceptance checks passed (or an unchecked plan merely reported work). - `1`: operational failure, threshold breach, baseline regression, or preparation that did not produce readiness. - `2`: `plan --require-ready` found required work, or `run` recorded the plan and was safely blocked before pool preparation and workload execution because preparation was not explicitly authorized. - `130`: interrupted by the operator. ```bash node --import tsx index.ts report diff baselines/testnet/open-steady.json runs//report.json # --max-latency-increase : allowed relative p95/p99 latency increase (default 0.20) # --max-error-rate-increase : allowed absolute error-rate increase, range [0, 1] (default 0.01) ``` Baseline reads are strictly schema-validated. After reviewing a completed suite, publish all of its threshold-passing reports in one explicit operation: ```bash node --import tsx index.ts baseline bless runs/ --baselines-dir baselines # Add --accept-regressions only when intentionally accepting measured regressions. node --import tsx index.ts baseline list --baselines-dir baselines # Prints / and its last-updated time for every stored baseline. ``` Blessing recomputes each candidate against the baseline currently at the destination; suite-summary diff metadata is informational and cannot authorize a regression. Artifact paths containing symlink components below the selected suite or baseline root are refused. Commit the resulting `baselines//.json` files. This repository does not currently schedule load tests in GitHub Actions; wire the suite command into environment-specific CI only where credentials, funding, and a dedicated relayer are available. ## Development ```bash pnpm typecheck pnpm test # vitest unit tests (scheduler, pools, parser, verification, reports) ``` The input-proof worker uses the public `generateZkProof` action and keeps one initialized SDK context per worker thread. # Architecture The repository is a pnpm workspace. Use the existing boundaries when adding behavior. ## Packages - `packages/toolkit` (`@cli-fhevm-sdk/toolkit`): the library layer. It wraps `@fhevm/sdk` and FHETest with importable flows and must not depend on CLI packages (`commander`, `consola`, `@pnpm/tabtab`). - `packages/cli` (`cli-fhevm-sdk`): commander command registration and the `fhevm-sdk` binary. It consumes the toolkit through `@cli-fhevm-sdk/toolkit` package imports (root export or deep subpaths such as `@cli-fhevm-sdk/toolkit/flows/input-proof`), never through relative paths. - `packages/load-test` (`@cli-fhevm-sdk/load-test`): a private operator application, not a publishable SDK library. It owns load models, durable pools, raw relayer wire validation, collectors, reports, baselines, and its Commander surface. It may use public `@fhevm/sdk` entry points directly for SDK-native workload journeys and proof workers, and uses the toolkit for shared network, account, contract, ACL, and value behavior. Load orchestration must not move into toolkit. The toolkit's `exports` map points at TypeScript source; the CLI build (`tsdown`) bundles the toolkit into `packages/cli/dist/` via `deps.alwaysBundle` while keeping npm dependencies external. Because of that, the toolkit's runtime npm dependencies must also be declared in `packages/cli/package.json`. ## Toolkit boundaries (`packages/toolkit/src`) - `flows`: orchestration only. Compose config, SDK, contract, ACL, transaction, and value helpers here. Group command families into subfolders such as `fhe-test`, `public-decrypt`, `user-decrypt`, `delegated-user-decrypt`, and `token`. - `fhevm`: `@fhevm/sdk` adapters and SDK response normalization. - `fhe-test`: FHETest ABI and contract reads/writes. - `token`: ERC-7984 confidential token ABI and contract reads/writes. - `acl`: ACL delegation reads/writes. - `config`: network registry, runtime config, account loading, and client contexts. - `values`: clear-value parsing, random values, and JSON serialization helpers. - `shared`: cross-cutting helpers like progress and transaction waiting. - `types.ts`: networks, FHE value types, and flow result types shared across packages. - `index.ts`: the public API barrel; keep new public functions exported from here. Deep subpath exports stay available for lazy loading. Keep SDK integration on entry points declared by `@fhevm/sdk`; do not resolve or import files from its private `_esm`, `_cjs`, or internal source layout. Toolkit permit APIs use seconds, matching `@fhevm/sdk`. Human-facing CLI options may use days, but must convert at the CLI boundary. Custom FHEVM chains must include the host-chain `protocolConfig` contract used by the SDK to resolve the protocol and compatible WASM versions. ## CLI boundaries (`packages/cli`) - `src/cli`: command registration, argument parsing, stdout/stderr behavior. - `bin/completion-server.mjs`: static tab completion resolver. It must stay lightweight and must not import TypeScript runtime, SDK clients, config, or flows. When adding a command, prefer: 1. CLI module in `packages/cli/src/cli/commands`. 2. Flow module in the matching `packages/toolkit/src/flows/` folder. 3. Adapter changes only at the boundary being crossed. Keep raw SDK response casts and raw contract calls out of CLI and flow code when practical. Keep expensive flow and SDK imports inside command actions, not at CLI module top level. ## Load-test boundaries (`packages/load-test/src`) - `scenario` and `suite`: validated workload data, exact flow allocation, pool planning, and sequential suite orchestration. - `runner` and `flows`: scheduler lifecycle plus one executor per relayer flow. - `relayer`: bounded, runtime-validated raw HTTP protocol adapters. Never trust wire data through TypeScript casts. - `pool`: durable pool schemas, writers, cursors, and on-chain/off-chain preparation. - `collectors` and `report`: optional observations, strict versioned report schema, rendering, comparison, and explicit baseline blessing. - `cli`: argument parsing and lazy action wiring only. Report and baseline reads must pass the versioned runtime schema. A missing baseline may skip a comparison; a corrupt or incompatible baseline must fail. Baseline mutation belongs only to the explicit `baseline bless` command and is staged only after every suite report validates. # CLI Use these tools for CLI work: - `commander` for CLI interface - `@commander-js/extra-typings` for TypeScript types - `consola` for Elegant Console Wrapper - `@pnpm/tabtab` for shell tab completion Behavioral guidance: - Keep progress and status logs on stderr. - Keep the final machine-readable response on stdout as JSON. - Update `README.md` examples and this guidance when changing command behavior, options, outputs, defaults, or supported flows. - Global options may be passed before or after subcommands; use `optsWithGlobals()` from the command action context. - The CLI ships as the `fhevm-sdk` binary (`packages/cli/bin/fhevm-sdk.mjs`, exposed via `pnpm link` run from `packages/cli`) and runs compiled `packages/cli/dist/index.mjs`; run `pnpm run build` before linking or using `pnpm run cli`. - Use `pnpm run cli:dev` for source-mode CLI checks without rebuilding. - The workspace-root `.env` is loaded by `packages/cli/src/env.ts` relative to the repository, not the working directory; shell variables take precedence. - `completion-server` is invoked by tabtab's shell templates; the binary routes it to `packages/cli/bin/completion-server.mjs` before loading `tsx` or runtime flow modules. Keep its stdout limited to completion items. - Keep completion metadata in `packages/cli/bin/completion-server.mjs` aligned with command help whenever changing commands, options, choices, or descriptions. - Keep CLI command modules free of top-level flow imports. Runtime flow modules should be loaded with dynamic imports inside `.action()` handlers so help and completion startup stay fast. - FHETest is the only contract target, except `token transfer`/`token balance`, which target ERC-7984 confidential tokens and require `--contract` since there is no per-network token default. - Networks may target different host chains; do not assume Ethereum Sepolia for every network. - Keep decrypt-family naming consistent: the `direct` subcommand does direct handle decryption, while `fresh` and `stored` are FHETest demo subcommands. - The decrypt family roots (`user-decrypt`, `public-decrypt`, `delegated-user-decrypt`) are pure dispatchers with no options of their own; their `direct` subcommands decrypt existing `--handle` values from any contract, where `--contract` is the ACL pairing contract and defaults to FHETest. A bare root command with no subcommand prints help. - `fresh` creates or stores a new FHETest handle before decrypting. - `stored` reads an existing FHETest handle from the wallet/account/delegator type slots (defaulting to the bool slot); it has no `--handle`. - Public decrypt `fresh` stores with `makePublic=true`. - User decrypt and delegated user decrypt `fresh` store with `makePublic=false`. - Delegated flows use `PRIVATE_KEY`/`MNEMONIC` for the delegate and `DELEGATOR_PRIVATE_KEY`/`DELEGATOR_MNEMONIC` for the encrypted data owner. - `fhe-test inspect` is read-only. Keep raw `--handle` inspection mutually exclusive with account/type inspection. - `fhe-test inspect --type ` defaults `--account` to the wallet address loaded from `PRIVATE_KEY`/`MNEMONIC` when no account is provided. - `fhe-test init --bulk` calls the contract-level all-types initializer and is mutually exclusive with `--type`. - `fhe-test init --type ` may be repeated to initialize selected types without bulk mode. - `fhe-test init` returns `transactionHashes` as an array because non-bulk initialization may send one transaction per initialized type. - `fhe-test op` exposes FHETest operator demos as explicit subcommands, not as a generic `--type` flag. Keep operation names aligned with the underlying behavior, such as `add-uint64` and `xor-uint256`. - `token transfer` uses `confidentialTransferFrom` when `--from` is set, spending an existing operator allowance instead of the loaded wallet's own balance. - `token transfer` returns `transferredHandle` because ERC-7984 does not revert on insufficient balance; the token ACL lets the recipient (not the sender) decrypt it with `user-decrypt direct --handle --contract `. - `token transfer --verify` decrypts the sender balance before/after and reports `deltaMatches` (`balanceBefore - balanceAfter === `); it is rejected together with `--from` because the operator wallet cannot decrypt the `--from` account's balance. - `token balance --account` defaults to the wallet address loaded from `PRIVATE_KEY`/`MNEMONIC` when omitted. # TypeScript Engine Default to Node.js with pnpm. The repository is a pnpm workspace (`packages/*`); run root scripts from the workspace root and use `pnpm --filter ` to target one package. - Use `pnpm install` for dependency installation. - Use `pnpm run

References Skill

Explore Related Technologies & Topics