# Configuration

Cocoon's configuration is split across environment variables (set in `.env` or passed directly to Docker Compose) and static configuration files baked into the chain image at build time. This page covers every parameter.

{% hint style="info" %}
All environment variables have sensible defaults for local development. For production deployments, review every section marked with a warning and replace demo values with your own.
{% endhint %}

## Chain Configuration

These parameters define the identity and consensus rules of the chain. They are set in `chain/genesis.json` and compiled into the Erigon image at build time. To change them, modify the genesis file and rebuild the `erigon` image.

| Parameter              | Type       | Default (Chain A)          | Description                                                                                 |
| ---------------------- | ---------- | -------------------------- | ------------------------------------------------------------------------------------------- |
| `config.chainId`       | integer    | `33`                       | EVM chain ID. Must be unique across all connected chains. Chain B uses `34`.                |
| `config.clique.period` | integer    | `1`                        | Block time in seconds (Clique PoA).                                                         |
| `config.clique.epoch`  | integer    | `30000`                    | Clique epoch length in blocks.                                                              |
| `gasLimit`             | hex string | `0x1c9c380`                | Block gas limit (\~30 million).                                                             |
| `baseFeePerGas`        | hex string | `0x3B9ACA00`               | Initial base fee (1 Gwei).                                                                  |
| `extradata`            | hex string | *(sealer address encoded)* | Clique sealer address embedded in genesis extradata. Must contain the admin/sealer address. |
| `alloc`                | object     | 10 pre-funded accounts     | Genesis account allocations. Replace with your operator and admin addresses for production. |

{% hint style="danger" %}
**Production deployments:** replace all `alloc` addresses with your own. The defaults are the well-known Hardhat/Anvil test accounts whose private keys are public knowledge. Any funds sent to those addresses can be stolen.
{% endhint %}

## Components Configuration

Cocoon components are Erigon modules that implement the platform's extended functionality. They are enabled via a `components.cfg` file mounted into the Erigon container and via the `GENESIS` and `DATADIR` environment variables.

| Component                   | Key        | Default   | Description                                                                                            |
| --------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------ |
| Permissioned Tokens         | `tokens`   | `enabled` | ERC-3643 token engine with compliance hooks (`token_*` RPC namespace).                                 |
| Digital Bearer Certificates | `dbc`      | `enabled` | RingCT confidential cash layer. Requires `tokens` to be enabled.                                       |
| Identity Registry           | `identity` | `enabled` | OnchainID / ERC-734/735 identity and claims engine (`id_*` RPC namespace).                             |
| Authorization               | `auth`     | `enabled` | UCAN capability delegation and EIP-8141 frame transaction handling (`auth_*` namespace).               |
| Torrent Storage             | `torrent`  | `enabled` | BitTorrent-backed content-addressed document store (`erigon_resolveTorrent`, `erigon_publishTorrent`). |
| WebF                        | `webf`     | `enabled` | On-chain web hosting via torrent-ccip (`erigon_publishWebSite`, `erigon_getWebSite`).                  |
| Prover                      | `prover`   | `enabled` | ZK proof generation pipeline. Can be disabled if you run the prover on a separate host.                |
| Verifier                    | `verifier` | `enabled` | Validates incoming proofs before state acceptance.                                                     |
| QMTree                      | `qmtree`   | `enabled` | Merkle-tree state commitment scheme used by the prover (`qm_*` namespace).                             |

## Backend Proxy Configuration

The backend proxy (`backend/`) is configured entirely via environment variables.

### Core Settings

| Variable            | Type     | Default                                       | Description                                                                                                               |
| ------------------- | -------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `CHAIN_RPC_URL`     | string   | `http://localhost:8545`                       | URL of the Erigon JSON-RPC endpoint. In Docker Compose this is `http://erigon:8545`.                                      |
| `USER_DB_URL`       | string   | `http://localhost:8548`                       | URL of the user database service.                                                                                         |
| `PROXY_PORT`        | string   | `8546`                                        | Port the backend proxy listens on.                                                                                        |
| `AUDIT_DB_PATH`     | string   | `./data/audit.db`                             | Path to the SQLite audit log file. Use a volume-mounted path in production.                                               |
| `AUTH_MODE`         | string   | `advisory`                                    | `advisory`: log auth failures but allow through. `strict`: reject unauthenticated or invalid-session calls with HTTP 401. |
| `LOCAL_CHAIN_ID`    | integer  | `33`                                          | Chain ID of the local Erigon node. Used for IBAN routing. Must match `chainId` in genesis.                                |
| `ALLOWED_ORIGINS`   | string   | `http://localhost:3000,http://localhost:3001` | Comma-separated list of allowed CORS origins.                                                                             |
| `SESSION_CACHE_TTL` | duration | `5s`                                          | How long to cache validated session tokens before re-validating with user DB.                                             |

### RPC Configuration

| Variable                      | Type    | Default                 | Description                                                                                     |
| ----------------------------- | ------- | ----------------------- | ----------------------------------------------------------------------------------------------- |
| `PERMISSION_REGISTRY_ADDRESS` | address | *(from deployments)*    | Address of the on-chain `PermissionRegistry` contract. If blank, permission checks are skipped. |
| `DEPLOYMENTS_PATH`            | string  | `/app/deployments.json` | Path to the `deployments.json` file that maps contract names to addresses.                      |

### Interoperability Configuration

| Variable            | Type    | Default          | Description                                                                                                                                                    |
| ------------------- | ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INTEROP_ENABLED`   | bool    | `false`          | Set to `true` to enable the cross-chain interop listener.                                                                                                      |
| `INTEROP_ADMIN`     | address | *(demo address)* | Ethereum address of the admin account that signs cross-chain mint/burn transactions.                                                                           |
| `INTEROP_ADMIN_KEY` | string  | *(empty)*        | Hex-encoded private key (no `0x` prefix) for the interop admin account. Required when `INTEROP_ENABLED=true`.                                                  |
| `PEER_CHAINS`       | string  | *(empty)*        | Comma-separated list of peer chain descriptors in the format `chainId=rpcUrl=deploymentsPath`. Example: `34=http://erigon2:8545=/app/deployments.chain2.json`. |

{% hint style="danger" %}
**`INTEROP_ADMIN_KEY` is a signing key.** Store it in a secrets manager (Vault, AWS Secrets Manager, etc.) and inject it at runtime. Never hardcode it in `docker-compose.yml` or commit it to version control.
{% endhint %}

## Prover Configuration

The prover (`prover/`) is a Rust service that generates ZK proofs of chain state transitions. It communicates with Erigon over a local socket.

| Parameter           | Type    | Default                 | Description                                                                                                    |
| ------------------- | ------- | ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `PROVER_BACKEND`    | string  | `zilkworm`              | Proof backend to use. Options: `zilkworm` (default, fastest), `sp1`, `risc0`.                                  |
| `PROVER_ENDPOINT`   | string  | `http://localhost:9090` | gRPC endpoint the prover listens on. Erigon calls this to request proofs.                                      |
| `PROVER_WORKERS`    | integer | `2`                     | Number of parallel proof workers. Increase for higher throughput at the cost of CPU.                           |
| `PROVER_BATCH_SIZE` | integer | `100`                   | Number of blocks to batch into a single proof. Larger batches are more efficient but introduce higher latency. |
| `PROOF_STORE_PATH`  | string  | `./data/proofs`         | Directory where generated proofs are persisted before posting to Ethereum.                                     |
| `ETH_ANCHOR_RPC`    | string  | *(empty)*               | Ethereum RPC URL for posting state roots. If empty, proofs are generated but not posted.                       |
| `ETH_ANCHOR_KEY`    | string  | *(empty)*               | Signing key for the Ethereum anchor transaction.                                                               |

## Identity and Token Contract Addresses

After first-boot contract deployment, the addresses below are written to `deployments.json`. You can override any address by setting the corresponding environment variable on the backend service — useful when deploying to an existing chain with pre-deployed contracts.

| Variable                           | Contract                 | Description                                                                          |
| ---------------------------------- | ------------------------ | ------------------------------------------------------------------------------------ |
| `PERMISSION_REGISTRY_ADDRESS`      | `PermissionRegistry`     | Controls which addresses have which roles (Admin, Operator, Trader, Compliance).     |
| `MMF_TOKEN_ADDRESS`                | `MMFToken`               | Default money market fund ERC-3643 token.                                            |
| `STABLECOIN_ADDRESS`               | `Stablecoin`             | Default USD-pegged stablecoin used as the subscription currency.                     |
| `STATE_ANCHOR_REGISTRY_ADDRESS`    | `StateAnchorRegistry`    | On-chain registry of posted state roots.                                             |
| `IDENTITY_REGISTRY_ADDRESS`        | `IdentityRegistry`       | ERC-3643 identity registry linking investor addresses to on-chain identities.        |
| `CLAIM_TOPICS_REGISTRY_ADDRESS`    | `ClaimTopicsRegistry`    | Registry of recognised claim topics (KYC status, accreditation, jurisdiction, etc.). |
| `TRUSTED_ISSUERS_REGISTRY_ADDRESS` | `TrustedIssuersRegistry` | Registry of claim issuers trusted by the compliance layer.                           |

## Torrent Storage Configuration

| Parameter               | Type        | Default                  | Description                                                                                     |
| ----------------------- | ----------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
| `TORRENT_ANNOUNCE_URLS` | string list | *(internal tracker)*     | BitTorrent tracker announce URLs. Comma-separated. Private trackers recommended for production. |
| `TORRENT_CACHE_PATH`    | string      | `/data/torrent-cache`    | Local directory for torrent piece cache. Mount on fast local storage.                           |
| `TORRENT_KEYSTORE_PATH` | string      | `/data/torrent-keystore` | Path to the keystore used for signing torrent-ccip content references.                          |
| `TORRENT_MAX_PEERS`     | integer     | `50`                     | Maximum number of BitTorrent peer connections.                                                  |

## Auth (UCAN) Configuration

| Parameter                   | Type    | Default              | Description                                                                                                                |
| --------------------------- | ------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `UCAN_VERIFIER_CONTRACT`    | address | *(from deployments)* | Address of the on-chain UCAN verifier contract. Validates capability delegations presented in EIP-8141 frame transactions. |
| `UCAN_REVOCATION_REGISTRY`  | address | *(from deployments)* | Address of the revocation registry. The auth component checks this before accepting a delegation.                          |
| `UCAN_MAX_DELEGATION_DEPTH` | integer | `5`                  | Maximum depth of the UCAN delegation chain. Longer chains are rejected.                                                    |

## RPC Configuration

Erigon's RPC server is configured via command-line flags set in the container's entrypoint. The defaults expose all Cocoon namespaces.

| Parameter           | Type        | Default                                      | Description                                                                                                                                                |
| ------------------- | ----------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--http.api`        | string list | `eth,net,web3,token,id,auth,qm,proof,erigon` | Comma-separated list of enabled RPC namespaces.                                                                                                            |
| `--http.corsdomain` | string      | `*` (dev)                                    | Allowed CORS origins for direct Erigon RPC access. In production, set to the backend proxy's internal address only and do not expose port 8545 externally. |
| `--http.addr`       | string      | `0.0.0.0`                                    | Address Erigon binds the HTTP RPC server to. In production, bind to `127.0.0.1` and access only via the backend proxy.                                     |
| `--http.port`       | integer     | `8545`                                       | HTTP RPC port.                                                                                                                                             |
| `--authrpc.addr`    | string      | `127.0.0.1`                                  | Address for the authenticated Engine API (used internally).                                                                                                |
| `--authrpc.port`    | integer     | `8551`                                       | Engine API port.                                                                                                                                           |

{% hint style="warning" %}
**Never expose port 8545 directly to the internet.** All external RPC traffic should pass through the backend proxy on port 8546, which applies session validation, CORS enforcement, and audit logging.
{% endhint %}

## User Database Configuration

| Variable       | Type    | Default           | Description                                                                                        |
| -------------- | ------- | ----------------- | -------------------------------------------------------------------------------------------------- |
| `PORT`         | integer | `8548`            | Port the user DB service listens on.                                                               |
| `DB_PATH`      | string  | `./userdb.sqlite` | Path to the SQLite database. Use a volume-mounted path so data persists across container restarts. |
| `KYC_DOCS_DIR` | string  | `./kyc_docs`      | Directory where uploaded KYC documents are stored. Encrypt this directory at rest in production.   |

## Frontend and Dashboard Configuration

Both the admin dashboard (`dashboard/`) and the investor frontends (`frontend/`, `frontend2/`) are Next.js applications built with compile-time environment variables.

| Build Arg / Variable      | Default               | Description                                                                                                  |
| ------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `NEXT_PUBLIC_PROXY_URL`   | `http://backend:8546` | URL of the backend proxy. Set to the publicly accessible URL of the proxy when deploying for external users. |
| `NEXT_PUBLIC_USER_DB_URL` | `http://user_db:8548` | URL of the user database.                                                                                    |
| `NEXT_PUBLIC_CHAIN_ID`    | `33`                  | Chain ID the frontend connects to. Set to `34` for the Chain B investor frontend.                            |
| `NEXT_PUBLIC_BRAND`       | *(empty)*             | Optional brand name displayed in the frontend UI.                                                            |

{% hint style="info" %}
Because these are compile-time `NEXT_PUBLIC_` variables, changing them requires a container rebuild (`docker compose up --build`).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cocoon.erigon.tech/operators/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.