ethereum-optimism / ethereum-optimism/optimism

op-core/superchain is unconsumable by downstream Go modules: superchain-configs.zip is gitignored

Closed
#22,678 4 comments 0 reactions 1 assignee Claimed by @sebastianst View on GitHub
Dominant language
Go
Stars
6.5k
Forks
4k
Avg merge
2d 15h
Merged PRs (30d)
145

Description

`op-core/superchain` embeds `superchain-configs.zip`, which is gitignored and generated locally from the superchain-registry submodule. The zip is therefore absent from the published Go module, and any downstream module that reaches this package fails to compile:

```
op-core/superchain/chain.go:21:12: pattern superchain-configs.zip: no matching files found
```

### Verification

- The zip is gitignored at every release tag checked: `op-node/v1.17.0`, `v1.18.0`, `v1.19.0`, `v1.19.5`, `op-contracts/v7.0.0`, `op-contracts/v8.0.0-rc.3`. Only `superchain-configs.zip.sha256` is committed.
- The published module confirms it. `$GOMODCACHE/github.com/ethereum-optimism/optimism@v1.19.5/op-core/superchain/` contains `superchain-configs.zip.sha256` but no `superchain-configs.zip`.
- `op-core/superchain/sync-superchain.sh` documents three modes (verify, refresh, external). All three require a superchain-registry checkout, so none is usable by a module consumer. There is no consumer-facing README.

The monorepo does not hit this itself because `just build-superchain-go` runs as a build prerequisite, and container builds carry `melange/pipelines/op-stack-go/sync-superchain.yaml`, whose comment documents this exact failure. Neither helps a downstream `go build`.

### Impact

Every OP Stack release from 2026-04-29 onward, when `op-core/superchain` was introduced in #20314, is unconsumable as a plain Go dependency by anything that reaches this package.

Found while upgrading `ethereum-optimism/supersim`, which reaches it via `genesis/worldgen` -> `op-chain-ops/interopgen` -> `op-core/superchain`. supersim had to pin `op-node/v1.16.13` (2026-04-21), the last release before the change, instead of the current one. See ethereum-optimism/supersim#424.

### Possible directions

1. Commit the zip. Simplest, at the cost of a binary in the tree.
2. Make the embed optional behind a build tag, with a runtime loader as the fallback for consumers that do not need the built-in configs.
3. Publish the bundle as a separate versioned Go module or artifact that consumers can depend on.

Happy to take direction on which is preferred.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.