[M1] Add Otterscan & Sourcify integration to playground

[augustocollerone]

Summary

This PR delivers Milestone 1: Otterscan Integration of the CoW Grants Program RFP: CoW Protocol Playground Block Explorer Integration proposal by CoBuilders.

Integrates Otterscan block explorer with Sourcify contract verification into the CoW Protocol Playground, enabling developers to browse transactions and view verified contract source code locally.

Milestone 1 Deliverables

Otterscan Integration

• Seamless Otterscan integration into existing Docker Compose (fork and non-interactive modes)
• Production-ready configuration with optimized settings for Anvil
• Service networking and dependencies configured
• All Otterscan features working correctly (traces, gas profiling, contract viewing)

Contract Verification Setup

• Otterscan configured to support contract verification
• Option to use local Sourcify service OR default Sourcify endpoints (SOURCIFY_MODE env var)
• Verification working with both approaches
• Configuration options documented

Success Criteria

"Otterscan is fully functional with all debugging features available, and contract verification is working."

• Otterscan available at http://localhost:8003
• Local Sourcify available at http://localhost:5555
• Contract verification via Foundry or Sourcify API
• Verified source code viewable in Otterscan

Commits

Commit	Description
872d4db	Added Otterscan to docker-compose files
d6e322b	Merge remote-tracking branch 'origin'
3c11ff2	Fix Dockerfile
6e8acb6	Update Otterscan readme details
8519ffa	Sourcify included in docker-compose
98fa7ec	Sourcify cleanup
ff75c1f	Update docker-compose.fork.yml
f7e8ff5	Sourcify env variable config
0660cb8	Sourcify local url param
f92810a	Update README.md

Changes

New Files

File	Description
Dockerfile.sourcify	Builds Sourcify server with automatic database migrations
Dockerfile.otterscan	Custom Otterscan with configurable Sourcify source
sourcify-entrypoint.sh	Handles DB migrations and server startup
otterscan-entrypoint.sh	Configures Sourcify source based on SOURCIFY_MODE
sourcify-chains.json	Chain configuration for local Sourcify (mainnet fork + Anvil)

Modified Files

File	Changes
docker-compose.fork.yml	Added Otterscan, Sourcify, Sourcify DB services with health checks
docker-compose.non-interactive.yml	Same changes as above
.env.example	Added SOURCIFY_MODE configuration variable
README.md	Added Otterscan and Sourcify documentation
Dockerfile	Minor fix

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Otterscan  │────▶│  Sourcify   │────▶│ Sourcify DB │
│  (port 8003)│     │ (port 5555) │     │ (PostgreSQL)│
└─────────────┘     └─────────────┘     └─────────────┘
        │
        ▼
┌─────────────┐
│    Chain    │
│  (Anvil)    │
│ (port 8545) │
└─────────────┘

Configuration Options

Sourcify Mode

The SOURCIFY_MODE environment variable controls which Sourcify source Otterscan uses:

Mode	Description	Use Case
cloud (default)	Public Sourcify repository	View source for well-known contracts (CoW Protocol, USDC, etc.)
local	Local Sourcify instance	View source for contracts you deploy and verify locally

# In .env
SOURCIFY_MODE=cloud  # or "local"

After changing, recreate the Otterscan container:

docker compose -f docker-compose.fork.yml up -d otterscan

Contract Verification

Using Foundry:

forge verify-contract \
  --verifier sourcify \
  --verifier-url http://localhost:5555 \
  <contract_address> \
  src/MyContract.sol:MyContract

Using Sourcify API:

curl -X POST http://localhost:5555/verify \
  -H "Content-Type: application/json" \
  -d '{"address": "0x...", "chain": "1", "files": {...}}'

Testing

1. Start the playground:

   docker compose -f docker-compose.fork.yml up --build

2. Verify services are healthy:

   curl http://localhost:5555/health  # Sourcify
   # Browse to http://localhost:8003  # Otterscan

3. Test cloud mode (default): View any well-known contract in Otterscan - source code should be visible

4. Test local mode:

   • Set SOURCIFY_MODE=local in .env
   • Recreate Otterscan container
   • Deploy and verify a contract
   • View verified source in Otterscan

Next Milestones

Milestone	Description	Status
M1	Otterscan Integration	This PR
M2	Frontend Integration (CoW Swap & Explorer URL modifications)	Pending
M3	Documentation	Pending

---

Submitted by CoBuilders as part of the CoW Grants Program

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[augustocollerone]

I have read the CLA Document and I hereby sign the CLA

[ifqbuilder]

I have read the CLA Document and I hereby sign the CLA

[MartinquaXD]

Thanks for you contribution! 🚀
Other than the small modification I had to apply, this worked like a charm on my first simple test. Will play a bit more with it over the holidays and do a full review.

[MartinquaXD]

I had to remove the ' to enable variable expansion. With 'EOF' this command literally wrote ${ERIGON_URL} into the file instead of http://127.0.0.1:8545.

Suggested change

	cat > "$CONFIG_FILE" << 'EOF'
	cat > "$CONFIG_FILE" << EOF

[MartinquaXD]

Same here.

Suggested change

	cat > "$CONFIG_FILE" << 'EOF'
	cat > "$CONFIG_FILE" << EOF