Quick Start

This guide takes you from zero to a running Cocoon stack in under ten minutes. By the end you will have two Erigon chains, the backend proxy, admin dashboard, investor frontends, user database, and block explorer all running locally via Docker Compose.

Prerequisites

Requirement	Minimum	Notes
Docker Engine	24.x or later	Docker Desktop also works
Docker Compose	v2.20 or later	Bundled with Docker Desktop
Git	Any recent version	For cloning the repo
RAM	16 GB recommended	8 GB minimum for single-chain only
Disk	20 GB free	For chain data volumes
CPU	4 cores recommended	The prover is CPU-intensive

Apple Silicon (M-series) users: all images build natively for linux/arm64. If you encounter exec format error on any container, ensure Docker Desktop is set to use the native ARM engine, not Rosetta emulation.

Step 1 — Clone the Repository

git clone https://github.com/your-org/cocoon.git
cd cocoon

The stack lives in the mvp/ subdirectory:

cd mvp

All subsequent commands in this guide are run from the mvp/ directory.

Step 2 — Configure Environment Variables

Copy the example environment file and open it in your editor:

Linux / macOS

cp .env.example .env
$EDITOR .env

Windows (PowerShell)

The minimum required values are:

# Admin account — used for contract deployment and interop signing
# Use a dedicated key; never reuse a personal or production wallet key
INTEROP_ADMIN=0xYourAdminAddress
INTEROP_ADMIN_KEY=your_private_key_hex_no_0x_prefix

# Auth mode: "advisory" logs auth failures; "strict" rejects unauthenticated calls
AUTH_MODE=advisory

# Origins allowed to call the backend proxy (comma-separated)
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001,http://localhost:3011

Never commit .env to version control. The file contains your admin private key. Verify .env is listed in .gitignore before proceeding.

For a full list of supported variables see Configuration.

Step 3 — Start the Stack

Using make

make

The Makefile target runs docker compose up --build -d and tails the logs.

Using Docker Compose directly

Single chain only

Docker builds all images on first run. This takes 3–8 minutes depending on your machine and network. Subsequent starts are fast because layers are cached.

Step 4 — Wait for Services to Become Healthy

The stack uses Docker health checks. The deploy and deploy-chain2 one-shot containers wait for their respective Erigon nodes to be healthy before deploying contracts. You can watch progress:

docker compose ps

Expected output when everything is up:

NAME              STATUS              PORTS
erigon            healthy             0.0.0.0:8545->8545/tcp
erigon2           healthy             0.0.0.0:8555->8545/tcp
deploy            exited (0)
deploy-chain2     exited (0)
backend           healthy             0.0.0.0:8546->8546/tcp
backend2          healthy             0.0.0.0:8556->8546/tcp
user_db           healthy             0.0.0.0:8548->8548/tcp
dashboard         running             0.0.0.0:3000->3000/tcp
frontend          running             0.0.0.0:3001->3001/tcp
frontend2         running             0.0.0.0:3011->3001/tcp
explorer          running             0.0.0.0:3002->3002/tcp

The deploy containers exit with code 0 when contract deployment succeeds. If they show exited (1), check the logs with docker compose logs deploy.

Step 5 — Verify the Stack

Check the backend health endpoint:

curl http://localhost:8546/health

Expected response:

{"status":"ok","chainReachable":true}

Check the Erigon RPC directly:

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"net_version","params":[]}' \
  http://localhost:8545 | python3 -m json.tool

Expected response (Chain A):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "33"
}

Check the latest block:

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' \
  http://localhost:8545

The block number should be increasing (the Clique PoA engine produces a block every second).

Check the user database:

curl http://localhost:8548/health

Expected: {"status":"ok"}

Open the dashboard:

Navigate to http://localhost:3000 in your browser. The admin dashboard shows token balances, recent transfers, and the audit log for Chain A.

Open the block explorer:

Navigate to http://localhost:3002. Blocks appear in real time as the chain produces them.

Step 6 — Confirm Contract Deployment

Contract addresses are written to deployments.json after the deploy container completes. Verify the file exists and contains addresses:

cat deployments.json

You should see a JSON object with chainId: 33 and addresses for PermissionRegistry, MMFToken, Stablecoin, and the Uniswap V3 pool contracts.

For Chain B:

cat deployments.chain2.json

Next Steps

With the stack running you can:

Onboard an investor

Use the admin dashboard to whitelist an address on the MMF token, or call token_onboardInvestor directly via the RPC.

Issue a token subscription

Have a whitelisted investor call token_subscribe or use the investor frontend at port 3001 to subscribe stablecoin for MMF shares.

Deploy a custom token

Call token_deploy via the RPC to deploy a new ERC-3643 permissioned token with your own compliance parameters.

Configure for production

Review the full Configuration reference and harden the deployment: replace demo keys, restrict port exposure, and enable strict auth mode.

Stopping the Stack

docker compose down

To stop and remove all data volumes (full reset):

docker compose down -v

docker compose down -v deletes all chain data and the user database. Contract addresses in deployments.json will no longer match the new chain state. Only use this for a clean development reset.

Viewing Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f backend

# Last 100 lines of Erigon
docker compose logs --tail=100 erigon