Introduction
This section is for engineers and platform teams deploying and operating Cocoon inside their own infrastructure. It covers everything from first-boot to production configuration.
Cocoon is designed for operator-hosted deployment. Your chain data, keys, transaction history, and identity documents never leave your infrastructure. Ethereum receives only state roots and ZK proofs.
What You Need
Running a Cocoon node requires three things:
Docker and Docker Compose — all services are packaged as containers. No additional runtime dependencies are needed on the host.
The Cocoon repository — the
mvp/directory contains the full Docker Compose stack, contract deployment scripts, and configuration templates.Environment variables — a small set of variables controls chain identity, inter-node interoperability, and admin keys. Copy
.env.exampleto.envand fill in the required values before starting.
The stack is intentionally self-contained. A developer laptop can run the full two-chain configuration. A production deployment runs the same images on dedicated infrastructure behind your network perimeter.
Deployment Architecture
Single-node (one chain)
The simplest deployment runs a single Erigon node (Chain A, ID 33) with its associated backend proxy, admin dashboard, investor frontend, user database, and block explorer.
This is the default configuration and the right starting point for most operators. All services communicate over an internal Docker network; only the ports you choose to expose are reachable from outside the host.
Multi-node (two chains with interop)
The full MVP stack runs two independent chains (Chain A, ID 33 and Chain B, ID 34) with a cross-chain interoperability listener. Each chain has its own Erigon node, backend proxy, and investor frontend. The admin dashboard and user database are shared.
The interop listener watches each chain for cross-chain transfer events and calls the corresponding mint/burn on the peer chain using a configured admin key. See Configuration for INTEROP_* environment variables.
Operator Responsibilities
Running a Cocoon node places several obligations on the operating institution:
Infrastructure and availability. Cocoon runs entirely within your infrastructure. You are responsible for uptime, backup, and disaster recovery of chain data volumes (erigon-data, erigon2-data) and the user database (userdb-data).
Key management. The admin key (INTEROP_ADMIN_KEY) authorises cross-chain mint operations and contract administration. Protect it with the same controls you would apply to any signing key. Never commit it to version control.
Data residency. Chain state, transaction history, identity documents, and audit logs all reside within your deployment. Do not expose the Erigon RPC port (8545) directly to the internet; traffic should pass through the backend proxy (8546), which enforces session validation and audit logging.
Contract deployment. On first boot the deploy container deploys all token, identity, and compliance contracts from the contracts/ directory. The resulting addresses are written to deployments.json. If you redeploy contracts (e.g. after a chain reset), update any external integrations that hold hardcoded contract addresses.
Regulatory compliance. You operate the KYC/AML claim-issuance workflow. The platform enforces claims at transfer time, but the decisions behind those claims — who is approved, under what conditions, and for how long — remain your responsibility.
Where to Go Next
Last updated