Skip to main content

Operators

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.

note

Cocoon is designed for operator-hosted deployment. Chain data, keys, transaction history, and identity documents never leave the operator's infrastructure. Ethereum receives only state roots and ZK proofs.

Requirements​

Running a Cocoon node requires three things:

  1. Docker and Docker Compose — all services are packaged as containers. No additional runtime dependencies are needed on the host.
  2. The Cocoon repository — the mvp/ directory contains the full Docker Compose stack, contract deployment scripts, and configuration templates.
  3. Environment variables — a small set of variables controls chain identity, inter-node interoperability, and admin keys. Copy .env.example to .env and 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 the operator's 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 chosen to be exposed 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 the operator's infrastructure. The operator is 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) authorizes cross-chain mint operations and contract administration. Protect it with the same controls applied to any signing key. Never commit it to version control.

Data residency. Chain state, transaction history, identity documents, and audit logs all reside within the 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 contracts are redeployed (e.g. after a chain reset), update any external integrations that hold hardcoded contract addresses.

Regulatory compliance. The operator runs 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 the operator's responsibility.

Where to Go Next​

  • Clone the repo, set the environment variables, and have the full stack running in under ten minutes.
  • Complete reference for every configuration parameter: chain, components, prover, identity contracts, torrent, auth, and RPC.
  • Full method listing for all custom JSON-RPC namespaces: token_, id_, auth_, qm_, proof_, and erigon_.