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.
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.
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.
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.
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.
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.
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
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
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
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.
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.
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.
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.
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
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
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.
--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.
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.
User Database Configuration
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.
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.
Because these are compile-time NEXT_PUBLIC_ variables, changing them requires a container rebuild (docker compose up --build).
Last updated