[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

nachfq · 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

My docker versions are the following:

- Docker: 27.2.1 - Docker Compose: v2.40.3-desktop.1

What versions are you using? Also have you tried running the playground in the main branch? meaning, without our changes

@jmg-duarte were you able test this?

Apologies for the delay. I find it weird that you can run this as is, the playground driver.toml actually has an issue.

And I still can't run sourcify/otterscan on my Mac, I was able to run this on my Linux machine (x86) though which hints me that the go images are not being correctly built for ARM

Maybe docker is able to emulate or cross build correctly but not everyone can be expected to run docker (as you see, I dont, and I've met others running lima, etc)

Would be nice to have this working with alternative container runtimes too, to avoid "it works on my machine"

Hey @jmg-duarte, I've pushed a fix that should help with the ARM architecture issues.

What changed:

The Sourcify Dockerfile was hardcoding the dbmate-linux-amd64 binary, which doesn't work natively on ARM machines. I've updated it to:

Auto-detect the host architecture

Map to the correct dbmate binary (supports amd64, arm64, i386, armhf)

Fail fast with a clear error if the architecture is unsupported

Verify the binary works during build

Please try building again with a clean slate:
docker compose -f docker-compose.non-interactive.yml down --remove-orphans --volumes
docker compose -f docker-compose.non-interactive.yml up --build

A couple of questions:

Were you able to run the playground on main branch (without this PR's changes)? That would help us isolate whether this is a pre-existing issue or something introduced in this PR.

Did you try running Otterscan with SOURCIFY_MODE=cloud (pointing to the cloud Sourcify instead of local)? If so, did that work?

You mentioned there's an issue with driver.toml - could you elaborate on what's broken there?

Thanks for the update, it works now (on Podman)! The issue was clearly something to do with emulation and possibly cross building.

The driver issue is due to the driver.toml missing the tx-gas-limit field at the top of the file, like the example.toml — this is not related to the PR, I just found it curious

Details

2026-01-19T11:32:33.117Z ERROR observe::tracing: thread 'main' panicked at /src/crates/driver/src/infra/config/file/load.rs:36:13: failed to parse TOML config at "/driver.toml": Error { inner: Error { inner: TomlError { message: "missing field `tx-gas-limit`", raw: Some( "[[solver]]\nname = \"baseline\" # Arbitrary name given to this solver, must be unique\nendpoint = \"http://baseline\"\nabsolute-slippage = \"40000000000000000\" # Denominated in wei, optional\nrelative-slippage = \"0.1\" # Percentage in the [0, 1] range\naccount = \"0x2a871d0798f97d79848a013d4936a73bf4cc922c825d33c1cf7073dff6d409c6\" # Known test private key\n\n[submission]\ngas-price-cap = \"1000000000000\"\n\n[[submission.mempool]]\nmempool = \"public\"\n\n[liquidity]\nbase-tokens = [\n \"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\", # WETH\n \"0x6B175474E89094C44Da98b954EedeAC495271d0F\", # DAI\n \"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48\", # USDC\n \"0xdAC17F958D2ee523a2206206994597C13D831ec7\", # USDT\n \"0xc00e94Cb662C3520282E6f5717214004A7f26888\", # COMP\n \"0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2\", # MKR\n \"0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599\", # WBTC\n \"0x6810e776880C02933D47DB1b9fc05908e5386b96\", # GNO\n]\n\n[[liquidity.uniswap-v2]] # Uniswap V2 configuration\npreset = \"uniswap-v2\"\n", ), keys: [], span: Some( 0..0, ), }, }, }

- 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!

mfw78 · 2026-01-16T19:29:12Z

That is a fair point regarding container runtime compatibility. It would certainly improve the developer experience for those not using Docker directly.

However, I believe this falls outside the scope of the current grant, which was defined as integrating Otterscan into the existing Docker Compose setup. Broader runtime compatibility would affect the entire playground infrastructure, not merely the Otterscan integration.

Perhaps something to consider for a future improvement or separate proposal. For now, I would suggest we evaluate this PR against the agreed Milestone 1 deliverables.

I have tested this PR and can confirm it functions in accordance with the guidance provided. The implementation satisfies Milestone 1 as defined in the grant proposal.

The dbmate binary download was hardcoded to amd64, which breaks builds on ARM64 machines (Apple Silicon) when using alternative container runtimes like Podman or lima that don't have automatic x86 emulation. Changes: - Detect host architecture using dpkg --print-architecture - Map dpkg naming to dbmate naming (i386→386, armhf→arm) - Add clear error message for unsupported architectures - Verify binary works with dbmate --version after download Supports: amd64, arm64, i386, armhf

nachfq 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

Closed

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

Merged

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

augustocollerone force-pushed the feature/cow-explorer-main branch from b53c542 to 775f11a Compare January 16, 2026 19:40

jmg-duarte approved these changes Jan 19, 2026

View reviewed changes

jmg-duarte added this pull request to the merge queue Jan 20, 2026

Merged via the queue into cowprotocol:main with commit d7f0c8c Jan 20, 2026
19 checks passed

github-actions bot locked and limited conversation to collaborators Jan 20, 2026

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

[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!

nachfq 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!

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

What changed:

A couple of questions:

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!

mfw78 commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

augustocollerone commented Dec 19, 2025 •

edited

Loading

github-actions bot commented Dec 19, 2025 •

edited

Loading

mfw78 commented Jan 16, 2026 •

edited

Loading