[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

playground/Dockerfile.sourcify

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

Good point for image optimization! I've updated both compose files to use postgres:16 for the sourcify-db service to match the main db service.
✅ Fixed

The sourcify DB is failing to get up, I'm guessing it's targeting the same port as the main DB.

This isn't actually a port conflict - sourcify-db doesn't expose any external ports (only the main db exposes 5432:5432).

The error is a PostgreSQL version mismatch that happens when containers aren't rebuilt after pulling changes.

Solution - reset volumes and rebuild:
docker compose -f docker-compose.non-interactive.yml down --remove-orphans --volumes
docker compose -f docker-compose.non-interactive.yml up --build

I confirmed this fixes the issue locally - sourcify-db comes up healthy after the rebuild.

I've ran these, they worked (nice find on the volumes, I cleaned my env but forgot them!)

The sourcify image is still not cooperating (bunch of panics like the one below):

sourcify-1 | goroutine 37 gp=0xc000458700 m=nil [chan receive]: sourcify-1 | runtime.gopark(0x0?, 0x0?, 0x0?, 0x0?, 0x0?) sourcify-1 | /home/runner/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.23.0.linux-amd64/src/runtime/proc.go:424 +0xce fp=0xc0001b1f18 sp=0xc0001b1ef8 pc=0x47096e sourcify-1 | runtime.chanrecv(0xc0000da540, 0x0, 0x1) sourcify-1 | /home/runner/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.23.0.linux-amd64/src/runtime/chan.go:639 +0x41c fp=0xc0001b1f90 sp=0xc0001b1f18 pc=0x40b87c sourcify-1 | runtime.chanrecv1(0x0?, 0x0?) sourcify-1 | /home/runner/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.23.0.linux-amd64/src/runtime/chan.go:489 +0x12 fp=0xc0001b1fb8 sp=0xc0001b1f90 pc=0x40b432 sourcify-1 | runtime.unique_runtime_registerUniqueMapCleanup.func1(...) sourcify-1 | /home/runner/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.23.0.linux-amd64/src/runtime/mgc.go:1732 sourcify-1 | runtime.unique_runtime_registerUniqueMapCleanup.gowrap1() sourcify-1 | /home/runner/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.23.0.linux-amd64/src/runtime/mgc.go:1735 +0x2f fp=0xc0001b1fe0 sp=0xc0001b1fb8 pc=0x41edcf sourcify-1 | runtime.goexit({}) sourcify-1 | /home/runner/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.23.0.linux-amd64/src/runtime/asm_amd64.s:1700 +0x1 fp=0xc0001b1fe8 sp=0xc0001b1fe0 pc=0x478b61 sourcify-1 | created by unique.runtime_registerUniqueMapCleanup in goroutine 1 sourcify-1 | /home/runner/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.23.0.linux-amd64/src/runtime/mgc.go:1730 +0x96

- Fix heredoc EOF quoting to enable variable expansion in otterscan-entrypoint.sh - Update Node.js from v22 to v24 (current LTS) in Dockerfile.sourcify - Update Sourcify repo to argotorg/sourcify with explicit master branch - Align sourcify-db postgres version to 16 (matching main db service)

jmg-duarte · 2026-01-07T13:37:23Z

The non-interactive.yml file - Have you tried with docker-compose.fork.yml instead?

@augustocollerone does it actually work for you? The refreshing mechanism was super slow when I was running it on docker, so much so I didn't even tried running. I'll try it now!

augustocollerone · 2026-01-07T13:37:57Z

The non-interactive.yml file - Have you tried with docker-compose.fork.yml instead?

@augustocollerone does it actually work for you? The refreshing mechanism was super slow when I was running it on docker, so much so I didn't even tried running. I'll try it now!

yes it takes really long, like 10 minutes but it works for me!

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

augustocollerone requested review from MartinquaXD and jmg-duarte January 7, 2026 13:36

[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

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jmg-duarte commented Jan 7, 2026

Uh oh!

augustocollerone commented Jan 7, 2026

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