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.

note

All environment variables have sensible defaults for local development. For production deployments, review every section marked with a warning and replace demo values with production ones.

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 the operator and admin addresses for production.

danger

Production deployments: replace all alloc addresses with operator and admin addresses. 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.

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 when the prover runs 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.

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.

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. Any address can be overridden 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 recognized 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.

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.

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.

note

Because these are compile-time NEXT_PUBLIC_ variables, changing them requires a container rebuild (docker compose up --build).