Identifies which release, or which commit, of an Offchain Labs contract repo a deployed contract
was built from, using only a standard RPC (eth_getCode, eth_getStorageAt, eth_call).
CI builds each source repo's tags and the heads of its release and hotfix branches, fingerprints
every deployable contract, and publishes the results here as static JSON. A reference walker
discovers and identifies every contract of a chain.
Design: contract-registry-spec.md (BLK-491). Status: prototype. Sources: nitro-contracts,
every tag from v3.2.0 onward, plus the releases from v3.0.0 on (backfilled; see "Backfill");
token-bridge-contracts, every tag from v1.0.1-beta.0, the first that reproduces Arbitrum One's
and Nova's canonical bridge; and upgrade-executor, every tag from v1.0.0, its whole release
history (see "Backfill").
To get the version of the contract at an address:
import { Registry, Rpc } from '<this repo>/walker'
// Registry.open() reads this repo's main branch, resolved to a commit once, so every file comes
// from one snapshot. One registry covers every source repo: a lookup searches all of them.
const registry = await Registry.open()
const v = await registry.getVersion(new Rpc(rpcUrl), address)
// e.g. { version: 'v3.2.0', repo: 'OffchainLabs/nitro-contracts' }, or nullgetVersion returns the repo with the version, because tag names overlap across source repos.
Registry.open(spec) opens another snapshot: github:<owner>/<repo>@<ref>, git:<path>@<rev>,
or a directory.
What a version means. A version is the earliest release in the registry's range for that
source whose build contains the code: the first non-prerelease tag, else the first prerelease tag,
else a manual entry's label, else <ref>@<commit>. So nitro-contracts code unchanged since
v2.1.0 reports v3.0.0, the first release the registry builds, and the token bridge's
canonical bridge reports v1.0.1-beta.0, the prerelease that first contains it. "Backfill" gives
each source's range.
getVersion does this:
EIP1967_IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc
SECONDARY_IMPLEMENTATION_SLOT = 0x2b1dbce74324248c222f0ec2d5ed7bd323cfc425b336f0253c5ccfda7265546d
EIP1967_BEACON_SLOT = 0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50
getVersion(rpc, address) -> { version, repo } | null:
entry = lookup(rpc.getCode(address))
if entry != null and not (entry.role == "proxy" and (entry.beaconSlot or len(entry.implementationSlots) == 1)):
return versionAndRepo(entry) # logic, proxy admins, and two-slot proxies report themselves
# a one-slot proxy, a beacon proxy, or unknown code (maybe a proxy the registry doesn't have)
impls = implementations(rpc, address, entry)
if impls.secondary: return null # unknown code with both slots set (an old RollupProxy): no version of its own
if not impls.implementation: return null
implEntry = lookup(rpc.getCode(impls.implementation))
return implEntry ? versionAndRepo(implEntry) : null
implementations(rpc, address, entry) -> { implementation?, secondary? }:
# an address is the last 20 bytes of a slot whose other 12 bytes are zero; zero slots are left out
if entry != null and entry.beaconSlot: # a beacon proxy: what its beacon says
return { implementation: beaconImplementation(rpc, slot(entry.beaconSlot)) }
if entry != null: # a one-slot proxy: the slot its entry lists
return { implementation: slot(entry.implementationSlots[0]) }
impl = slot(EIP1967_IMPLEMENTATION_SLOT) # unknown code: probe the known slots
secondary = slot(SECONDARY_IMPLEMENTATION_SLOT)
if impl or secondary: return { implementation: impl, secondary: secondary }
return { implementation: beaconImplementation(rpc, slot(EIP1967_BEACON_SLOT)) }
beaconImplementation(rpc, beacon) -> address | null:
if not beacon: return null
# eth_call implementation() (selector 0x5c60da1b) on the beacon; a revert, or a result
# that isn't a nonzero address in its first 32 bytes, gives null
return address in rpc.call(beacon, 0x5c60da1b)
versionAndRepo(entry) -> { version, repo }:
return { version: versionOf(entry), repo: entry.repo }
versionOf(entry) -> string:
releases = [t for t in entry.tags if not isPrerelease(t)] # tags are in semver order
if releases: return releases[0]
if entry.tags: return entry.tags[0]
if entry.label: return entry.label # a manual entry
return entry.ref + "@" + entry.commit[:12] # e.g. release-3.3.0@abcdef012345
lookup(code) -> entry | null:
# every read at one commit of this repo
index = registry/index.json # read once; if it is missing, this isn't a layout-v2 snapshot: fail
if len(code) not in index.codeLengths: return null
for entry in registry/by-length/<len(code)>.json .entries: # that length's entries of every source
masked = copy of code
for range in entry.maskedRanges:
for offset in range.offsets: zero masked[offset : offset + range.length]
zero the last entry.cborMetadataLength bytes of masked
if keccak256(masked) == entry.fingerprint: return entry
return null
The choices it makes:
- A proxy with one implementation slot (
TransparentUpgradeableProxy,ERC1967Proxy) reports its implementation's version and repo. The implementation can come from another source than the proxy: a nitro-contracts proxy in front of another repo's logic reports that repo. - A beacon proxy (OpenZeppelin's
BeaconProxy, and the token bridge'sClonableBeaconProxy, the code of each standard token the bridge deploys on the child chain) reports its implementation too: the one its beacon returns. Its entry has abeaconSlotinstead ofimplementationSlots.getVersionreads the beacon's address from that slot and calls the beacon'simplementation(), so itsrpcneedscallas well asgetCodeandgetStorageAt. A reverting call must throwExecutionError(asRpc's does); other errors are passed on. RollupProxyandAdminFallbackProxy, which have two slots, report themselves, as do logic andProxyAdmin. A two-slot proxy's version is the release its proxy code came from, and it can lag the logic behind it: upgrades replace the logic, never the proxy.- Code in no tag at all was built only as the head of a release or hotfix branch. It gives
<ref>@<first 12 hex digits of commit>, the branch and head commit it was first built from, e.g.release-3.3.0@abcdef012345. That commit contains the code, but isn't necessarily the first commit that does: only branch heads are built. Once a tag contains the code, the tag wins. - Unknown code may be a proxy the registry doesn't have, in front of logic it does: on Arbitrum One, for example, many core proxies are early nitro-contracts builds, older than the registry's range, and the Arbitrum DAO's upgrade executors sit behind proxy code that no source builds. So unknown code is probed at the EIP-1967 implementation slot and, like a one-slot proxy, reports the version of the implementation there. If that slot and the secondary slot are both zero, the EIP-1967 beacon slot is probed, and a beacon there is asked for its implementation, as for a beacon proxy. That is safe for any unknown code: these are the standard slots, and the fallback can only return a version if it reaches code the registry recognises.
- Unknown code whose secondary slot is set is a two-slot proxy (an old
RollupProxy) and gives null, whatever its other slots hold, since a two-slot proxy reports its own version, which here is unknown. It never reports the admin logic in its EIP-1967 slot, and its beacon slot isn't read. - Unknown code gives null if its EIP-1967 and beacon slots are both zero, or the implementation is
unknown or has no code. So does a one-slot proxy whose slot is zero or whose implementation is
unknown or has no code, and a beacon proxy whose beacon slot is zero, whose beacon's
implementation()reverts or returns no address, or whose implementation is unknown or has no code. - A snapshot with no
registry/index.json(an older commit of this repo, from before layout v2) makes every lookup throw, rather than answer null.
For more than a version: registry.lookup(code) returns the matched entry (repo, contracts,
role, tags, ref, commit, ...), and decodeImmutables(code, entry) reads its immutables
(maxDataSize, isUsingFeeToken, ...). walk discovers and identifies every contract of a chain
from one address (see "Look up and walk").
A contract's fingerprint is keccak256 of its runtime code with every byte filled in at deploy time
zeroed. An entry lists those bytes as maskedRanges (name, type, offsets, length each):
the Solidity immutables, plus the addresses of linked libraries (<link <file>:<library>>) and a
library's own address (<library address>). The trailing CBOR metadata section, cborMetadataLength
bytes, is zeroed too. On-chain code matches an entry when it has the entry's length and the same
hash after masking with the entry's ranges.
decodeImmutables(code, entry) reads matched code's immutables, by name and decoded by type
(maxDataSize, isUsingFeeToken, isDelayBufferable, __self, ...); the walker and the lookup
CLI report them as immutables. The <…> ranges are masked but not reported: they say where the
code was deployed, not how it was configured.
Libraries with no external functions are not recorded: they are only ever inlined, never linked or deployed, and all compile to the same 45-byte stub. Libraries with an external function (a public constant's getter counts) are kept.
Besides the fingerprint and its masks (codeLength, maskedRanges, cborMetadataLength), an
entry says what the code is:
role:logic,proxyorproxy-admin. Aproxyentry also hasimplementationSlots, the storage slots that hold its implementation addresses, in order, or, for a beacon proxy,beaconSlot, the slot that holds its beacon's address; never both. So a client that identifies proxy code knows to read those slots and identify the code at each address, or to ask the beacon for itsimplementation()and identify the code there. Roles come fromcontractRolesinconfig/<source>/sources.json(unlisted contracts are logic), in the same form:{"role": "proxy", "implementationSlots": [...]},{"role": "proxy", "beaconSlot": "0x..."}or{"role": "proxy-admin"}. For nitro-contracts,TransparentUpgradeableProxyandERC1967Proxylist the EIP-1967 slot;RollupProxyandAdminFallbackProxylist it and the secondary (user-logic) slot;ProxyAdminandUpgradeableBeaconareproxy-admins. A beacon proxy (OpenZeppelin'sBeaconProxy) lists EIP-1967's beacon slot,0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50. Contracts that compile to one fingerprint must have the same role, slots and beacon slot included. The role is copied into the entry when it is written, and entries are write-once, so list a contract before its first build is published.refandcommit: the ref the entry was first built from, and the commit it pointed at then.refis a tag (v3.2.0) or a release or hotfix branch whose head was built (release-3.3.0). Only tags and branch heads are built, never a branch's earlier commits, socommitcontains the code but isn't necessarily the earliest commit that does. When a new tag and a new branch head bring the same new code in one run, the entry names the tag. Entries are write-once: code first built from a release branch keeps naming that branch after a tag includes it (the tag shows in the entry'stagsinregistry/by-length/) and after the branch is deleted. A manual entry, which has alabel, may have a nullreforcommit(see "Manual entries").packages: for contracts compiled from an installed dependency package, the package and version, e.g.{"@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy": "@openzeppelin/contracts@4.7.3"}. It maps each such contract's name, so an entry whose contracts come from several packages, or from a package and the repo's own code, stays unambiguous. Contracts not listed are the source repo's own code; the field is absent when all of them are. None of them is another source's package: publish refuses that code (see "Across sources"). The version is read from the package'spackage.jsonin the build checkout. Likerefandcommit, it records the first build that produced the fingerprint: a later build may compile the same code from another version of the package, and the entry doesn't change.
config/<source>/sources.json which refs are published; how to fetch, build (profiles
by ref range) and check the source repo; its npm
packages; proxies; reviewed range pairs
config/<source>/out-of-scope-getters.json getters the walker doesn't follow
schema/ JSON schemas for every file type
registry/<source>/entries/<fingerprint>.json one per distinct fingerprint, in one source only (see
"Across sources"); write-once
registry/<source>/tags/<tag>.json contract -> fingerprint for a tag's build; write-once
registry/<source>/branches/<branch>.json same for the head of a live release or hotfix branch;
overwritten, and removed with the branch
registry/by-length/<codeLength>.json generated, all sources: every entry of that length,
with its tags
registry/index.json generated, all sources: code lengths present; per
source, its repo and getters
<source> is a source's id, its directory in sources.json (nitro-contracts). Each source's
inputs are under registry/<source>/; the generated views combine every source, so one lookup
covers them all. by-length and index.json are taken, so no source can use them as its id.
The views are generated from the inputs and never hand-edited. registry/by-length/<len>.json
lists every entry of that length, sorted by fingerprint; each keeps its own repo, and its tags
come from its own source's tag files only (tag names overlap across source repos).
registry/index.json lists the code lengths that have a file and, per source, its repo and
getters: those of its own entries and of every entry its tag and branch files reference. The walker
calls a source's getters on code it doesn't know. The views have schemaVersion 2; entries, tags,
branches and config stay at 1.
Read every file at one commit of this repo, never across a push.
npm ci
# version of the contract at an address, as getVersion gives it (a proxy reports its implementation)
node tools/src/cli/version.ts --rpc $RPC --address 0x... # prints e.g. "v3.2.0 OffchainLabs/nitro-contracts"; unknown: exit 1
# identify one contract (the code at the address itself, as JSON)
node tools/src/cli/lookup.ts --rpc $RPC --address 0x...
# walk a chain from any core contract (JSON on stdout)
node tools/src/cli/walk.ts --rpc $RPC --start <rollup, inbox or token bridge router> [--source nitro-contracts] [--registry github:<owner>/<repo>@main]version and lookup search every source. Given several --addresses, version prints
<address> <version> <repo>, or <address> unknown, per line. The lookup CLI prints, for each
address, the entry as match (or null), with its repo, version and immutables. Every CLI
reads the registry in this checkout unless given --registry.
A walk belongs to one source: code the registry doesn't know is probed with that source's
getters, that source's out-of-scope list applies (unless --out-of-scope gives another), and the
summary intersects that source's logic. --source names it, by id. Without it, the walk takes the
source of the start contract's logic: of the first of these that matches an entry, in order: its
implementation, its secondary implementation, its own code. So a proxy belongs to the source of the
logic behind it, not to the source that owns its proxy code. If nothing at the start matches and the registry has
only one source, the walk takes that one; otherwise it fails and asks for --source. Arbitrum
One's rollup (0x5eF0D09d… on Ethereum) is such a start: its proxy and both implementations
predate the registry's range.
From TypeScript: import { walk, Registry, Rpc } from '<this repo>/walker' (run
npm run build:walker to emit dist/). walk({ start, rpc, registry }) takes source and
outOfScope (a list of getter signatures) as options, with the same defaults.
The walker identifies each contract's code: matched code is { status: "matched", codeLength, match }, where match is the one matching entry with its repo, its own version, its tags
and the code's immutables. For a proxy entry it reads the slots the entry lists: the first
gives the node's implementation, the second its secondaryImplementation. For a beacon proxy it
reads the entry's beaconSlot and calls the beacon's implementation(): the node's
implementation is { slot, beacon, address, code }, with the beacon slot and the beacon's
address. A beacon whose implementation() reverts or returns no address gives no implementation.
Either way, the getters of the proxy's code and of its implementation are called on the proxy.
Logic and proxy-admin code isn't probed. Code the registry doesn't know (for example a release
older than the registry's range, or a proxy built outside it, like the one in front of the
Arbitrum DAO's upgrade executor on each chain) is probed at the EIP-1967 and secondary slots and,
if both are zero, at the beacon slot.
A getter in the source's out-of-scope list (config/<source>/out-of-scope-getters.json) leads to a
leaf. A leaf is labelled with the edges that reached it (RollupProxy.owner()) and identified like
any other contract, implementations included, so a rollup's owner() shows which upgrade executor
owns it. A leaf is never expanded: no getters are called on it and no closest entry is looked for,
and its code raises no warning and doesn't count in the summary.
A key in the out-of-scope list is either a getter signature, such as owner(), out of scope on
every contract, or a contract name and a signature, such as L1WethGateway.l2Weth(), out of scope
only on contracts whose code or implementation matches an entry with a contract of that name (the
part after : in its fully qualified name). The second kind is for a getter that returns an
address on another chain in some contracts and one on the same chain in others. In the token
bridge, L1WethGateway.l2Weth(), on the parent chain, is an address on the child chain, while
L2WethGateway.l2Weth(), on the child chain, is that chain's own WETH. Code the registry doesn't
know only sees the first kind.
summary.tags is the intersection of the tag sets of the matched in-scope logic code of the walk's
repo: the releases the deployment is consistent with. Proxies and proxy admins are still identified
in the nodes, but left out of the summary: upgrades replace implementations, never proxies, so
after an upgrade to a release that changed proxy code they would empty the intersection.
summary.matchedInScope counts every role. In-scope code matched to another repo never enters the
intersection, since its tags are another repo's releases: summary.otherRepoInScope lists it, with
its address, repo and version.
The output doesn't depend on RPC timing: nodes come in order of depth, then in-scope first, then by address; warnings by kind (unknown code, implementations with no code, reverted getters, conflicting getters), then in node order.
Everything runs here ("pull" model); the source repos need no CI or credentials.
publish.yml(schedule, manual): builds every newv*tag in range (see "Backfill"), and the head of everyrelease-*andhotfix*branch whose head has changed. Nothing else is built: notmainordevelop, and not a release or hotfix branch's earlier commits. Each new tag is built from scratch, with the build profile its commit selects. If its commit was also built as a release or hotfix head (recorded in a branch file, or built in the same run), the tag build must reproduce that build's fingerprints; otherwise there is nothing to compare it with. The run writes entries (for code no source has an entry for yet; see "Across sources"), tag files and branch files (a deleted branch's file is removed; its entries stay), checks that entries of one code length mask the same bytes, in every source (so no code can match two; a conflict fails the whole run, and its alert says how to review the pair and list it inreviewedRangePairs), regenerates the views, deploys test chains from each new tag and changed head in the check's range and walks them (see "Test chains"), and lands everything as one commit. It checks that each new tag equalsv+package.jsonversion at its commit; a mismatch is published anyway and raises an alert until the tag is listed intagValidation.allowlist. The test-chain check requires all in-scope code, proxies and proxy admins included, to match an entry from that commit's build. It also reads the known slots (EIP-1967's implementation and beacon slots, and the secondary slot, plus any other slot the source'scontractRoleslists) on every matched contract, and fails if one that its entry doesn't list holds an address: a proxy missing fromcontractRoles, or listed with the wrong slots.reconcile.yml(daily): the same run, plus an alert for any published ref that should already have been processed.ci.yml(every push and PR): schemas; no two sources share an id, a repo or an npm package; each source'soutOfScopeGettersisconfig/<source>/out-of-scope-getters.json, the file the walker reads (publish's test-chain check reads the field); nothing outside the layout (a source's directory at the top of the repo, or anything inregistry/but configured sources,by-length/andindex.json); generated files match their inputs; one entry per fingerprint across sources, and an entry for every fingerprint a tag or branch file lists; shared code's role agrees with its owner's entry in every source'scontractRoles; no source's entries, tags or branches have another source's package code; the range invariant across sources (with every source'sreviewedRangePairs);entries/andtags/files are append-only. Append-only compares content with the base, so a file moved intoregistry/passes, and a changed or deleted one fails wherever it moved.
A run publishes each source in turn, in id order (every configured source unless --source names
some), and lands each as its own commit: the source's files under registry/<source>/ and the
regenerated views. A failed run discards both. One run at a time per work directory, since every
run rewrites the shared views.
Failures open or update one GitHub issue per failure kind and source repo, and close it once every
item is resolved. A build or test-chain failure at a branch head also resolves once the branch has
a newer head or is deleted, since only current heads are built. Locally, --alerts local:<dir>
writes the same alerts as JSON files.
node tools/src/cli/publish.ts [--source nitro-contracts ...] [--reconcile] [--push] [--alerts github:<owner>/<repo>]
node tools/src/cli/check.ts --source nitro-contracts --rev v3.2.0 # test-chain check of one commit, writes nothing
node tools/src/cli/rebuild.ts --source nitro-contracts (--tag v3.2.0 | --all) # rebuild tags, compare with their tags/ files
node tools/src/cli/generate.ts [--check] # regenerate the views (--check: compare only)
node tools/src/cli/ci-check.ts --base origin/main
npm test && npm run test:integrationOne lookup searches every source, so the registry's rules hold across sources. Publish,
add-entry and ci-check apply them to the entries of every configured source:
-
One entry per fingerprint. A fingerprint has one entry, in one source's
entries/. Publish andadd-entrylook a fingerprint up in every source before writing one. When a build produces code that another source already has an entry for (shared code, such as a proxy both repos compile from the same package), publish writes no entry. The build's tag or branch file lists the fingerprint as usual, and the other source's entry is the one lookups find. That entry'stagscome from its own source's tag files only (tag names overlap across sources), so shared code reports the version and repo of the source that owns it; itspackagessays where the code comes from. -
Who owns shared code. The source that published it first. A run publishes sources in id order, whatever order
--sourcenames them in, so on a fresh backfill the owner is the first source by id whose build produced the code. -
Roles agree. The role a source's
contractRolesgives shared code must be the owner's entry'srole,implementationSlotsandbeaconSlot. Otherwise the run fails and publishes nothing, and its alert names both configs.ci-checkapplies the same rule to every fingerprint a source's tag and branch files list whose entry another source owns, so a later change to either config can't break it unnoticed. The entry is write-once, so the fix is normally in the publishing source'scontractRoles. Within one source, roles aren't rechecked: a proxy added tocontractRolesafter its first build was published keeps its old entry, and failing every later build that contains it would leave no way forward. -
The range invariant spans sources. Entries of one code length mask the same bytes, whichever source they are in, apart from reviewed pairs. Every source's
reviewedRangePairscounts for every check, so a pair from two sources goes in either source's config. The conflict report names each entry's source and the configs the pair can go in. -
Every listed fingerprint has an entry. Each fingerprint in a tag or branch file has an entry in some source (
ci-check). -
A source never publishes another source's code. A build compiles its dependencies too, and some are other sources: the token bridge installs
@arbitrum/nitro-contractsand@offchainlabs/upgrade-executor, and has nitro-contracts as the submodulelib/nitro-contracts. Published, that code would get entries with this source's repo and versions, built with its settings. Each source lists the npm package names its code is installed under innpmPackages(required: itspackage.jsonname, every name it has had, or[]for a repo with no package; no two sources may list the same one):@arbitrum/nitro-contracts,@arbitrum/token-bridge-contractsand@offchainlabs/upgrade-executor. A contract a build would fingerprint is another source's code when its file is anywhere inside another source's package or repo:- it was compiled from an installed package (the
packagesfield) that is one of that source'snpmPackages, by the name in the installedpackage.json, so an npm alias counts; - its path names one of those packages at its start (a Hardhat import name, or a copy at the top
of the repo) or after a
node_modules/directory (Foundry's names, nested installs); or - it is in a git submodule, nested ones included, whose URL in
.gitmodulesis that source'srepoon GitHub (HTTPS, SSH or relative).
Publish refuses such a build before writing anything: the run fails (
publish-error) and publishes nothing, and its message names each contract, the package or submodule, the source it belongs to and the exclude to add to the build profile (the package or submodule directory and/**, e.g.@offchainlabs/upgrade-executor/**orlib/**). This holds for shared code too, so the tag or branch file doesn't list it either. Publish also fails while a built commit'spackage.jsonname isn't in its own source'snpmPackages, so a new or renamed package can't go unlisted.add-entryrefuses a contract from another source's package or repo and names the--sourceit belongs to.ci-checkchecks the data: no entry'spackages, and no contract name in an entry, tag or branch file, names another source's package. It can't see submodules (the data doesn't record them); publish checks those when it builds. A file vendored some other way, copied into the repo's own directories, isn't recognised: excludes still need review. - it was compiled from an installed package (the
The test-chain check deploys a source's contracts from the commit being published on local anvil
nodes, walks them with the registry, and fails on in-scope code that doesn't match an entry from
that commit's build, on an in-scope getter that returns zero, on a probed slot holding an address
the walk didn't read, and on a walk that can't complete. A source's testChains.deployer names its
deployer, tools/src/testchain/<deployer>.ts. It runs its scripts (tools/testchain/<deployer>/)
inside the built checkout, so the deployment comes from that commit's own deploy code and
artifacts, and returns the walks: for each, a name, the address it starts from and the node it
reads. Each walk's problems are reported under its name. A result is cached per commit, keyed by
CHECK_VERSION, the source's out-of-scope list and the deployer's code (its module, the helpers
the deployers share, common.ts, and its scripts).
- nitro-contracts deploys the RollupCreator with the commit's deploy scripts, creates four rollups (ETH or ERC20 fee token, delay-bufferable or not) with every optional address set, and walks each from its rollup. The deployment takes under 20 seconds.
- token-bridge-contracts needs a parent chain with a rollup, and a child chain that executes
retryable tickets. Two token bridges and 25 walks up to
v1.2.5(four and 50 with the yield-bearing bridges ondevelop); deploying and walking takes about 10 seconds.- Parent chain. One anvil. The creator and its templates come from the commit's own
deployL1TokenBridgeCreator(scripts/atomicTokenBridgeDeployer.ts). Each variant gets the parent side of a rollup: nitro-contracts'BridgeandInbox(ERC20BridgeandERC20Inboxwith a fee token) behind proxies, the rollup'sProxyAdminandUpgradeExecutor, and a stand-in for the rollup contract that answersowner()andchainId(), the only calls the creator makes to it. The nitro-contracts artifacts come from the npm release@arbitrum/nitro-contracts@1.1.1(its integrity hash is checked), not the checkout's, whose version varies by tag. - Variants. ETH and an ERC20 fee token, plus the yield-bearing bridge of each where the
creator has
createYbbTokenBridge. The deployer creates a token bridge for each, and deposits a token through each ETH router; on a yield-bearing bridge, the deposit also deploys the token's MasterVault on the parent chain. - Child chains. One anvil per variant, with the rollup's chain id, replays the retryables the
variant's Inbox recorded, in order: each from its sender (aliased by the Inbox) by
impersonation, to its destination or, if that is zero, as a contract creation, as ArbOS runs
them. So the child side is what the creator's own retryables deploy, at the addresses the
creator predicted, which the deployer checks. The child anvils run Prague, not Osaka: Osaka's
per-transaction gas cap (2^24) is barely above the transaction that deploys the child side
(15.4M gas at
v1.2.5). - Walks. From the creator; each variant's parent-chain contracts (
inboxToL1Deployment: router and gateways); its child-chain contracts (inboxToL2Deployment, the factory and the bridged token); and the MasterVault. Beforev1.2.0the creator keeps no such record, so the addresses come from itsOrbitTokenBridgeCreatedevent and itsgetCanonicalL2*(chainId), as those releases' own deploy script collects them. Two are left out: the parent chain's WETH (external code) and the child chain's upgrade executor (upgrade-executor's logic behind a token bridge proxy; walks reach it throughowner(), as a leaf).
- Parent chain. One anvil. The creator and its templates come from the commit's own
Each deployer has a CLI that deploys from a built checkout and prints the addresses as JSON:
node tools/src/testchain/<deployer>-cli.ts --checkout <dir> [--keep].
rebuild.ts shows that a source's published tags reproduce. It rebuilds each tag from scratch,
at the commit its tag file records and with the build profile that commit selects, and compares
the fingerprints with the tag file. --tag names tags; --all takes every tag file of the
source, building a commit that several tags share once. It prints one JSON report on stdout: per
tag, the commit, profile, contract count, whether it reproduced, and a build failure or the
contracts that differ. It exits 0 if every tag reproduced, 1 if any differs or fails to build, and
2 if it can't run (an unknown source or tag, or no tag files). It writes nothing to the data; build
logs are under the work directory, in logs/<source>/<commit>.fresh.log.
rebuild.yml (manual) runs it in CI, on the same toolchain as publish. Inputs: source
(required) and tag (empty for every tag file). It has read-only permissions and never pushes.
The run's summary lists each tag's result, and the report and build logs are uploaded as the
rebuild-report artifact. It reads the data at the ref it runs on, so a data branch can be
checked before its PR merges:
gh workflow run rebuild.yml --ref <branch> -f source=<id> # every tag file of the source
gh workflow run rebuild.yml --ref main -f source=nitro-contracts -f tag=v3.2.0 # one tagGitHub only dispatches a workflow that is on the default branch; the run then uses the branch's copy of the workflow and of the data.
Three settings in config/<source>/sources.json let the registry cover releases older than its
start tag. Each is a selector over source commits, and the run applies them per tag.
Which tags are published: start. A tag is published when its commit is start.tag's or
descends from it, prereleases included. With start.releasesFrom, so is every release tag (a
semver version with no prerelease part) at or above that version, wherever its commit is. For
nitro-contracts, {"tag": "v3.2.0", "releasesFrom": "v3.0.0"} adds v3.0.0, v3.1.0 and
v3.1.1; v3.1.1 is on a side branch, not an ancestor of v3.2.0. Prereleases before
v3.2.0 stay out: v3.0.1-beta.*, v3.1.0-qol and v3.2.0-beta.0. Branch heads must still
descend from start.tag.
How each commit is built: builds[].when. The first profile whose when matches the commit
builds it. A selector can require descendantOf, notDescendantOf, refs, and tags: a
published tag at the commit whose semver version is at least tags.from and below
tags.before, by semver precedence. A commit that no profile matches fails the run ("no build
profile matches commit"), so a tag is never built with settings meant for other releases.
nitro-contracts has two profiles, both on Node 24, Foundry v1.9.0 and yarn 1.22.22:
| Profile | Selects | Outputs |
|---|---|---|
hardhat-foundry-0.8.17 |
descendants of v3.2.0 |
Hardhat (deployed), Foundry (parity with Hardhat only), Foundry Yul profile (deployed) |
hardhat-0.8.17-v3.0-v3.1 |
tags >= v3.0.0 and < v3.2.0 |
Hardhat (deployed), Foundry Yul profile (deployed); no parity check |
The v3.0-v3.1 profile has no Foundry parity output, because those releases' Foundry build
isn't the deployed build. Their foundry.toml doesn't pin solc, so Foundry compiles the ^0.8.x
pragmas with the newest solc (0.8.34 today), not 0.8.17. It also sets evm_version = 'cancun'
and lacks Hardhat's per-file optimizer runs (20 for RollupUserLogic, 200 for
EdgeChallengeManager). Their deploy scripts use the Hardhat artifacts. The repo's own parity
check (yarn test:bytecodes, from PR #358) first ships in v3.2.0.
The Yul profile is deployed: the deploy scripts read out/yul/Reader4844.yul/Reader4844.json.
Its commands follow the releases' own build:forge:yul script, with two changes:
--skip '*.sol': the releases' Yul profile doesn't skip Solidity, and builds the tests without their remappings.--no-lint: Foundry v1.9.0's lint step fails on Yul.
The Yul build also sets FOUNDRY_SOLC_VERSION=0.8.24. Unpinned, Foundry would compile it with
whatever solc is newest, so the fingerprint would change with each solc release. Every solc from
0.8.23 on compiles it to the same 87 bytes, identical to the Reader4844 that Arbitrum One's
SequencerInbox uses (0x15b25E3f…d4ca).
Which commits get a test-chain check: testChains.when. For nitro-contracts it is
{"descendantOf": ["v3.2.0"]}, because the deployer targets v3.2.0's createRollup. For
token-bridge-contracts it is {"descendantOf": ["v1.1.1"]}: the v1.0.1-beta.* releases have no
creator, and up to v1.1.0, deployL1TokenBridgeCreator estimates the child chain's factory
deployment on a live child chain (Arbitrum's NodeInterface), which an anvil doesn't have. A
published commit outside it is built and published without the check, and not silently: the run
that publishes it (a new tag, or a branch head that changed) lists it in checksSkipped (commit,
refs, reason), logs test-chain check skipped for <refs>, and names it in the data commit's
message. Later runs don't repeat it for an unchanged branch head. check.ts --rev refuses such a commit.
Going further back. Lower start.releasesFrom; that one line is the range rule. Then:
- Make a profile cover the new tags: widen
tags.fromif the toolchain still works, or add a profile. - Check that
contractRoleslists every proxy and proxy admin those builds produce, under its exact name. Entries are write-once, and the role is copied in when one is written. - Check that each new tag equals
v+package.jsonversion, or allowlist it.
The run checks the range invariant against every existing entry of every source, as for any new tag.
OffchainLabs/token-bridge-contracts builds the token bridge: the gateway routers and gateways of
both chains, the child chain's tokens (StandardArbERC20, aeWETH) and their beacon, and the
Orbit creator (L1AtomicTokenBridgeCreator, L2AtomicTokenBridgeFactory). The registry covers its
release history from v1.0.1-beta.0: start is {"tag": "v1.0.1-beta.0"}, so 15 v* tags are
published, v1.0.1-beta.0 to v1.2.5, prereleases included, and the heads of release-main,
release-1.1.1 and hotfix/add-sbom-export. v1.1.0-alpha.0 and v1.1.0-alpha.1 are on a side
branch, so they stay out. Every tag equals v + package.json version.
What real chains run, and the version getVersion reports for it:
| Code | Version |
|---|---|
Arbitrum One's and Nova's canonical bridge (deployed 2021 to 2023 from an older repo): router and gateway logic on both chains, StandardArbERC20, Nova's aeWETH, Arbitrum One's proxy admins and beacon, and the DAO's reverse gateways for ARB |
v1.0.1-beta.0: that code is only in the v1.0.1-beta.* prereleases |
| The creators' L1 and L2 templates (Ethereum and Arbitrum One), and the routers and gateways of the Orbit chains created from them (still in 2026) | v1.1.0 |
The creators' L2AtomicTokenBridgeFactory template |
v1.2.0 |
The creators (Ethereum, Arbitrum One, Nova) and their L1TokenBridgeRetryableSender |
v1.2.2 |
Two contracts of Arbitrum One's 2021 bridge are older than any tag and unknown: its aeWETH logic
(0x8b194bEa…) and its BeaconProxyFactory (0x3fE38087…). Nova's proxies, beacon and
BeaconProxyFactory come from a 2022 build that no tag reproduces; the logic behind its proxies is
known, so getVersion reaches it through the slot probe for unknown code. Arbitrum One's
Classic-era core proxies on Ethereum (its Inbox 0x4Dbd4fc5…, among others) were compiled from the
same OpenZeppelin 3.4.2 TransparentUpgradeableProxy with the same settings as v1.0.1-beta.*, so
they match that entry: lookup reports token bridge proxy code, getVersion reports the
nitro-contracts logic behind it, and a nitro-contracts walk lists them in
summary.otherRepoInScope.
-
Two profiles, Hardhat only, both on Node 24 and yarn 1.22.22:
Profile Selects Builds hardhat-0.6.11-oz3commits that don't descend from v1.1.0-beta.0v1.0.1-beta.*andrelease-main: gateways at solc 0.6.11, OpenZeppelin 3.4.2hardhat-0.8.16-oz4descendants of v1.1.0-beta.0that don't descend from3f643a0cv1.1.0-beta.0tov1.2.5,release-1.1.1andhotfix/add-sbom-export: solc 0.8.16, OpenZeppelin 4.8.3The Hardhat build is the deployed one: the deploy scripts use its artifacts. There's no Foundry parity output. The repo builds with
bytecodeHash: ipfs, so the two toolchains' raw bytes differ, and three factories embed other contracts' creation code, metadata hash included, so even their masked code differs. -
The YBB guard.
3f643a0c("add L1YbbBridgeDeployer lib", 2026-02-05, ondevelop) setfoundry.tomlto 200 optimizer runs, while Hardhat stays at 100. No published ref contains it yet. A release that does matches no profile and fails the run, so its deployed toolchain gets decided before anything of it is published. -
Setup.
yarn install --ignore-scripts, because av1.0.1-beta.*dependency's postinstall fails (phantomjs-prebuilt); no tag has install scripts of its own. Submodules are fetched over HTTPS (git -c url.https://github.com/.insteadOf=git@github.com: submodule update ...): the tags fromv1.1.0-beta.0tov1.2.0pointlib/nitro-contractsat an SSH URL, which CI can't clone. The output setsINTERFACE_TESTER_SOLC_VERSIONto empty: when it is set, the Hardhat config adds that solc to its compilers, which would change the compiler of every^0.8file. -
Excludes. Tests and mocks (
contracts/tokenbridge/test/**and the test directories), and other sources' code, which publish would refuse (see "Across sources"):@offchainlabs/upgrade-executor/**(the repo compiles its own copy ofUpgradeExecutor, never deployed),@arbitrum/nitro-contracts/**, andlib/**, which holds thelib/nitro-contractssubmodule. -
Roles. OpenZeppelin's
TransparentUpgradeableProxy,UpgradeableProxy(3.4.2) andERC1967Proxy(4.8.3) are proxies at the EIP-1967 slot;ProxyAdminandUpgradeableBeaconare proxy admins. OpenZeppelin'sBeaconProxyand the repo'sClonableBeaconProxy, which compile to one fingerprint, are beacon proxies, so a bridged token reports its beacon's implementation: Arbitrum One's LINK (0xf97f4df7…) reportsv1.0.1-beta.0, fromStandardArbERC20. -
Test chains from
v1.1.1on (see "Test chains"): every tag fromv1.1.1tov1.2.5and the head ofhotfix/add-sbom-exportpass. Older releases are published without the check; their out-of-scope list was checked by walking real chains (below).
Out of scope. The token bridge is mostly pointers to the other chain, so its list
(config/token-bridge-contracts/out-of-scope-getters.json) is long:
- addresses on the other chain:
counterpartGateway(),l2BeaconProxyFactory(),canonicalL2FactoryAddress(),l1Address(), thev1.1.xcreators'getCanonicalL2*(uint256), andL1WethGateway.l2Weth(). On the child chain,L2WethGateway.l2Weth()is that chain's own aeWETH, so it stays in scope; - other repos and external code:
inbox()(nitro-contracts),owner()(an upgrade executor or an account),l1Weth()(WETH9),l1USDC()andl2USDC(); - accounts:
burner(),usdcOwnershipTransferrer(),getCurrentBlockCoinbase(), and the legacywhitelist(); - the creator's child-chain templates (
l2RouterTemplate(), ...): code to copy, initialised with placeholder addresses (0x…dEaD). They are still identified, as leaves. Likewise the beacon'sUpgradeableBeacon.implementation(), theStandardArbERC20logic that bridged tokens run: code, not an instance, so its own getters are unset. It is identified as a leaf, and as each bridged token's implementation; - zero by design: a router's own
router()(L1GatewayRouter,L1OrbitGatewayRouter,L2GatewayRouter). A gateway'srouter()stays in scope.
Walks from Arbitrum One's routers (Ethereum and Arbitrum One), its WETH gateways and LINK, both creators, Nova's routers and a 2026 Orbit chain's router match every in-scope contract except Arbitrum One's two 2021 ones and Nova's 2022 proxies, beacon and factory; no in-scope getter reaches an account.
OffchainLabs/upgrade-executor builds one contract, UpgradeExecutor. The registry covers its
whole release history: start is {"tag": "v1.0.0"}, so every v* tag from v1.0.0 is
published (v1.0.0, v1.1.0-beta.0, v1.1.0, v1.1.1-beta.0, v1.1.1), and the heads of
release-conf and hotfix/add-sbom-export. v1.0.0-beta.2 is on a side branch from before
v1.0.0, so it stays out.
The tags give two fingerprints. v1.0.0 is the DAO's original 2023 UpgradeExecutor logic on
Ethereum, Arbitrum One and Nova (deployed before the repo existed, from identical code). v1.1.0
is what every later tag and both branch heads build, and what every current upgrade executor
runs: the DAO's on all three chains since their 2025 upgrade, and the templates in
nitro-contracts' RollupCreator and the token bridge creator. Its entry's ref is
v1.1.0-beta.0, the first tag that built it; getVersion reports v1.1.0, the first release.
- Allowlist.
v1.1.0was tagged later on thev1.1.0-beta.0commit, whosepackage.jsonsays1.1.0-beta.0. Every other tag equalsv+package.jsonversion. - One profile,
hardhat-0.8.16, for every commit. The Hardhat build (solc 0.8.16, 20000 optimizer runs) is the deployed one: the npm package ships it, and nitro-contracts' deploy scripts use that artifact. The output sets two environment variables so the build doesn't depend on its surroundings:FOUNDRY_PROFILE=default, because the Hardhat config picks its solc settings by that variable; andTS_NODE_SKIP_PROJECT=true, because the repo has notsconfig.json, so Hardhat's ts-node would load the nearest one above the checkout (this repo's, when the work directory is inside it, which fails). The config loadshardhat-foundry, soforgemust be installed. - No roles, no out-of-scope getters, no test chains (
testChains: null). The repo builds no proxies, andUpgradeExecutorhas no address getters, so a walk from it is one node. Its proxy always comes from another repo, so it couldn't match the commit's own build, as the check requires.
Upgrade executors show up as leaves of other sources' walks: a nitro-contracts rollup's
owner() is identified, implementation included, and not expanded (see "Look up and walk"). An
Orbit chain's upgrade executor is a nitro-contracts TransparentUpgradeableProxy in front of
UpgradeExecutor, so getVersion reports v1.1.0 OffchainLabs/upgrade-executor for it (on
Arbitrum One, 0x76a0fd6e…4eb8c). The DAO's upgrade executors sit behind proxy code that no
source builds, so getVersion finds their logic through the EIP-1967 slot probe for unknown
code.
A manual entry is for code that no published ref builds: a one-off or patched build deployed
somewhere. Arbitrum One's Bridge implementation (0xfE4749061Fb052c354aaC65b9Fb0cCD7e20D2418, on
Ethereum) is one. Its entry has the label v3.1.0-callfilter, which getVersion reports unless a
tag later builds the same code, and a null ref and commit. Publish never builds or rewrites a
manual entry.
To add one:
-
Build the contract. The build must reproduce the deployed bytecode exactly, so use the build the deployment used: its source, solc version and settings (optimizer runs,
evmVersion,viaIR, metadata hash). These may differ from the source's build profiles insources.json. -
Run
add-entryon the build output, with the address of a deployed instance. This Bridge, for example, matches only a Foundry build with the metadata hash turned off (bytecode_hash = 'none'), so the example reads whatforge build --build-infowrites:node tools/src/cli/add-entry.ts --source nitro-contracts --checkout /path/to/checkout \ --build-info out/build-info --layout standard-json \ --contract src/bridge/Bridge.sol:Bridge \ --rpc $RPC --address 0xfE4749061Fb052c354aaC65b9Fb0cCD7e20D2418 \ --label v3.1.0-callfilter --notes 'Arbitrum One Bridge implementation, a patched build based on v3.1.0'
--build-info,--layoutand--artifactsare as in asources.jsonoutput, relative to--checkout. A Hardhat build takes--layout hardhatand--artifacts.--sourceis required, with no default: it picks the entry's directory (registry/<source>/entries/), itsrepoand thecontractRolesits role comes from, and the entry is write-once.--blockdefaults tolatest. -
Check what it prints:
getVersionshould give your label and the source's repo (herev3.1.0-callfilter OffchainLabs/nitro-contracts; a one-slot proxy gives its implementation's version and repo), and any names it lists must be public (see below). -
Run
node tools/src/cli/ci-check.ts --base origin/main, commit on a branch and open a PR.
add-entry extracts the contract as publish does, and writes nothing unless the result matches the
code at the address. On a mismatch it prints both lengths and metadata trailers, and where the code
before the trailers differs. A trailer that differs alone usually means another metadata hash
setting; a different solc version or code means other settings or source. It also refuses a
missing label, a label that is a published tag of the source, another source's code (from its npm
package or a submodule of its repo; it names the --source the contract belongs to), a
fingerprint that already has an entry in any source (it names that source and what its entry
reports), and an entry that breaks
the range invariant, checked against every source's entries (see "Across sources"). The role
comes from contractRoles and packages from the checkout, as in publish. It then writes the
entry, regenerates registry/by-length/ and registry/index.json, and prints the entry's path,
its fingerprint and what getVersion reports for the address. It builds nothing and commits
nothing.
--ref and --commit default to null. Set them only for a build of a public commit: --ref must
point at --commit in the source repo at its url in sources.json, and the checkout must be at
that commit with no changes to tracked files.
Private source. If the build comes from a private repo, nothing that identifies it may appear
in the entry, its label or notes, the commit message, or config: not the repo's name, a branch,
commit, author or commit message, nor a file, contract or function name that only exists there.
Never add a private repo to sources.json. Fields derived from the bytecode are fine, since the
deployed code is public on chain. The names in contracts, getters and maskedRanges come from
the source, not the bytecode, so add-entry lists any that no other entry, of any source, has.
Before committing, grep the diff and the commit message for the private repo's identifiers.
Trust. CI checks the schema, the generated views, one entry per fingerprint, range conflicts
across sources and that entries are append-only. Nothing rebuilds a manual entry. Its correctness
rests on the person who added it; the on-chain match when add-entry writes it is the check.
Layout v2 and one lookup across sources (2026-11-16). One break for every client that reads
main. Clients pinned to an earlier commit keep working, since old commits keep the old layout.
- Data moved under
registry/: a source's inputs are inregistry/<source>/(was<source>/), and the generated views combine every source, inregistry/by-length/andregistry/index.json(schemaVersion2). Aby-lengthentry keeps its ownrepo; the index lists each source'srepoand getters. new Registry(source, 'nitro-contracts')is nownew Registry(source), orawait Registry.open(spec), which also resolves the spec (default: this repo'smain).getVersionreturns{ version, repo }instead of a string, because tag names overlap across sources.- Lookups read
registry/index.jsonfirst. A snapshot without it, such as an older commit of this repo, throws instead of answering null for everything. walktakes an optionalsource(a source id, inferred from the start) instead ofrepo, andoutOfScopeis optional (default: the source's list in the registry). Walk output hasschemaVersion2: out-of-scope leaves are identified, each match has itsversion, the summary intersects only the walk's repo and lists other repos' code inotherRepoInScope, and warnings come in a fixed order.- CLIs:
versionprints<version> <repo>;versionandlookupsearch every source and take no--source;walk's--sourceis optional;add-entry,checkandrebuildrequire--source, with no default. - Beacon proxies: a proxy entry (and its
contractRolesvalue) can have abeaconSlotinstead ofimplementationSlots, andgetVersion, the walker and the test-chain check follow it to the beacon's implementation.getVersion'srpcneedscallas well asgetCodeandgetStorageAt. Unknown code is also probed at the beacon slot when its EIP-1967 and secondary slots are zero. - Out-of-scope keys can name a contract (
L1WethGateway.l2Weth()) as well as be a bare getter signature.