[M1] Add Otterscan & Sourcify integration to playground #4000

augustocollerone · 2025-12-19T22:17:08Z

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

Start the playground:

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

Verify services are healthy:

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

Test cloud mode (default): View any well-known contract in Otterscan - source code should be visible
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 · 2025-12-19T22:17:18Z

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

augustocollerone · 2025-12-19T22:19:36Z

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

ifqbuilder · 2025-12-19T22:23:20Z

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 · 2025-12-23T12:11:36Z

playground/otterscan-entrypoint.sh

+case "${SOURCIFY_MODE:-cloud}" in
+  local)
+    echo "Using LOCAL Sourcify as primary source"
+    cat > "$CONFIG_FILE" << 'EOF'


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 · 2025-12-23T12:11:58Z

playground/otterscan-entrypoint.sh

+    ;;
+  cloud|*)
+    echo "Using CLOUD Sourcify as primary source"
+    cat > "$CONFIG_FILE" << 'EOF'


Same here.

Suggested change

cat > "$CONFIG_FILE" << 'EOF'

cat > "$CONFIG_FILE" << EOF

github-actions · 2025-12-31T00:10:24Z

This pull request has been marked as stale because it has been inactive a while. Please update this pull request or it will be automatically closed.

jmg-duarte

I ran docker compose -f docker-compose.non-interactive.yml up -d and it failed "upping" the sourcify service with a series of errors related to (seemingly) the database migrations

sourcify-1  | === Sourcify Server Starting ===
sourcify-1  | Waiting for database...
sourcify-1  | Database is ready!
sourcify-1  | Running database migrations...
sourcify-1  | runtime: lfstack.push invalid packing: node=0xffffb431d800 cnt=0x1 packed=0xffffb431d8000001 -> node=0xffffffffb431d800
sourcify-1  | fatal error: lfstack.push

I'm running Podman Compose on an M4 Pro, MacOS Sequoia 15.6

jmg-duarte · 2026-01-05T11:07:00Z

playground/Dockerfile.sourcify

@@ -0,0 +1,31 @@
+FROM node:22-bookworm-slim


New LTS is 24, is it a requirement to use 22?

jmg-duarte · 2026-01-05T11:07:48Z

playground/Dockerfile.sourcify

+    apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Clone Sourcify with submodules
+RUN git clone --depth 1 --recurse-submodules https://github.com/ethereum/sourcify.git /sourcify


It seems like the new repo is at https://github.com/argotorg/sourcify and the default branch is staging, should we use another branch?

jmg-duarte · 2026-01-05T11:18:32Z

playground/docker-compose.non-interactive.yml


+  # Sourcify - Contract verification service
+  sourcify-db:
+    image: postgres:15-alpine


We're using postgres-16, I wonder if we can use the same image here to avoid downloading two postgres images

ifqbuilder and others added 10 commits December 11, 2025 19:39

Added Otterscan to docker-compose files

872d4db

Merge remote-tracking branch 'origin' into feature/cow-explorer-main

d6e322b

Fix Dockerfile

3c11ff2

Update Otterscan readme details

6e8acb6

Sourcify included in docker-compose

8519ffa

Sourcify cleanup

98fa7ec

Update docker-compose.fork.yml

ff75c1f

Sourcify env variable config

f7e8ff5

Sourcify local url param

0660cb8

Update README.md

f92810a

github-actions bot added a commit that referenced this pull request Dec 19, 2025

@augustocollerone has signed the CLA in #4000

79dd55f

github-actions bot added a commit that referenced this pull request Dec 19, 2025

@ifqbuilder has signed the CLA in #4000

6c91b49

augustocollerone marked this pull request as ready for review December 19, 2025 22:39

augustocollerone requested a review from a team as a code owner December 19, 2025 22:39

MartinquaXD reviewed Dec 23, 2025

View reviewed changes

This was referenced Dec 26, 2025

[M2] Integrate block explorer URL override for Otterscan #4012

Open

[M2] feat(common-utils): add REACT_APP_BLOCK_EXPLORER_URL environment variable override cowprotocol/cowswap#6774

Open

github-actions bot added the stale label Dec 31, 2025

jmg-duarte reviewed Jan 5, 2026

View reviewed changes

github-actions bot removed the stale label Jan 6, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[M1] Add Otterscan & Sourcify integration to playground #4000

[M1] Add Otterscan & Sourcify integration to playground #4000

augustocollerone commented Dec 19, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Dec 19, 2025 •

edited

Loading

Uh oh!

augustocollerone commented Dec 19, 2025

Uh oh!

ifqbuilder commented Dec 19, 2025

Uh oh!

MartinquaXD left a comment

Uh oh!

MartinquaXD Dec 23, 2025

Uh oh!

MartinquaXD Dec 23, 2025

Uh oh!

github-actions bot commented Dec 31, 2025

Uh oh!

jmg-duarte left a comment

Uh oh!

jmg-duarte Jan 5, 2026

Uh oh!

jmg-duarte Jan 5, 2026

Uh oh!

jmg-duarte Jan 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

[M1] Add Otterscan & Sourcify integration to playground #4000

Are you sure you want to change the base?

[M1] Add Otterscan & Sourcify integration to playground #4000

Conversation

augustocollerone commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Milestone 1 Deliverables

Otterscan Integration

Contract Verification Setup

Success Criteria

Commits

Changes

New Files

Modified Files

Architecture

Configuration Options

Sourcify Mode

Contract Verification

Testing

Next Milestones

Uh oh!

github-actions bot commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

augustocollerone commented Dec 19, 2025

Uh oh!

ifqbuilder commented Dec 19, 2025

Uh oh!

MartinquaXD left a comment

Choose a reason for hiding this comment

Uh oh!

MartinquaXD Dec 23, 2025

Choose a reason for hiding this comment

Uh oh!

MartinquaXD Dec 23, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Dec 31, 2025

Uh oh!

jmg-duarte left a comment

Choose a reason for hiding this comment

Uh oh!

jmg-duarte Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

jmg-duarte Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

jmg-duarte Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

augustocollerone commented Dec 19, 2025 •

edited

Loading

github-actions bot commented Dec 19, 2025 •

edited

Loading