feat: publish contract addresses and a release manifest with each release by re-gius · Pull Request #242 · paritytech/dotns

re-gius · 2026-08-20T09:48:55Z

Description

Releases currently ship ABIs but no contract addresses, so a consumer gets the interface and still doesn't know how to call the contracts without scraping a doc or hardcoding a set. This publishes deployments.json (addresses per network) and release-manifest.json (what the release contains) as standalone assets and at the root of the zip, generated from the committed deployment manifests. Both are in the pre-publish asset check, so a release either carries them or doesn't publish.

It also removes the repo's two other copies of addresses: the 17-address list in DEPLOYMENTS.md, which had already drifted once (6f1e6fbc), and the PINNED_FACTORY literal in deploy-contracts.yml, now read from the manifest.

deployments/<network>/<chain-id>.json becomes the only tracked copy.

New scripts/js/release-metadata.mjs: it has no dependencies, uses cast for chain reads, with build, validate, changelog and verify. A small new workflow runs validate on PRs touching deployments/** or the contract list, so a duplicate address or malformed manifest fails there rather than when a release is cut.

Type

Scope

Related Issues

Follows #222 , which made the ABI artifact trustworthy. This PR extends that artifact with addresses.

Fixes

Fixes #118 .

Checklist

Code

Follows project style
forge build passes
forge test passes
No new compiler warnings

Testing

New tests added for changed behavior
Fuzz tests added where applicable
Invariant tests verified

Security

No new selfdestruct or delegatecall
Access control reviewed
No storage layout conflicts (for upgradeable contracts)

Documentation

NatSpec updated on changed interfaces
README updated if needed

Breaking Changes

No breaking changes
Breaking changes documented below

Breaking changes: none for on-chain behaviour or for existing release assets, which keep their names and shapes. One thing to be aware of: anything scraping the address list out of DEPLOYMENTS.md will no longer find it and should read deployments/<network>/<chain-id>.json or the published deployments.json.

How to test

Not a contracts change, so forge test exercises none of it. From a checkout of this branch:

# the two release files, from the committed manifests plus the current build
forge build && bun scripts/js/release-metadata.mjs build --tag v0.0.0-test --out /tmp/rel
cat /tmp/rel/deployments.json /tmp/rel/release-manifest.json

# what CI now runs on a manifest change; needs no build
bun scripts/js/release-metadata.mjs validate

# check a network against a live chain (needs an eth-rpc endpoint)
bun run deployments:verify --network paseo-assethub --rpc <eth-rpc-url>

The end-to-end check that matters is a dry run of Publish Beta Package with a throwaway version, the same method used to validate #237. I will run it before merging it.

Notes

The manifest is updated by hand, and stays the single source of truth. A live deploy commits only its markdown report in dotns-releases; nothing writes addresses back here. The next step after this merges is for dotns-releases to open that PR automatically. RELEASE_ARTIFACTS.md states this plainly rather than implying a mechanism that doesn't exist. The manifest is accurate today, the latest report for each live network reproduces the canonical set with no differences.

github-actions · 2026-08-20T09:49:06Z

CI Summary

Check	Result
Deploy Contracts	Reproduces the committed manifest; resume verified
PR Title	PR Title Valid
Labels	Unknown
Secret Scan	Passed - No secrets detected

Deploy Contracts

Deployed addresses vs the committed manifest

Expected is the committed manifest; actual is this CI deployment of the same pipeline.

View full logs

Labels

dependencies, other, type: docs

re-gius · 2026-08-21T06:58:07Z

New release flow, documented in RELEASE_ARTIFACTS.md. For a release that changes contract code:

Cut a pre-release. It carries the ABIs and release-manifest.json, and no addresses. The code is not deployed yet at this point, so the recorded addresses still belong to the previous deployment.
Deploy that tag from dotns-releases. Deploying a tag rather than a branch is what ties the addresses to the code that produced them.
Record the resulting addresses in deployments/<network>/<chain-id>.json (manually for now).
Cut the release from a commit that differs from the deployed tag only by that record, after running deployments:verify against the network.

A release that changes no contract code skips all of this.

Step 3 is manual today. The next piece of work is for dotns-releases to open that PR itself and make everything automated (checks, recording addresses, ...).

sphamjoli

Collapsing the three copies of the addresses into one tracked manifest and generating the rest from it fixes the drift from 6f1e6fb. Reading the factory out of the canonical manifest at CI time instead of repeating the literal means the two cannot disagree, and running validate on PRs fails a bad manifest before a release does. A few suggestions below, mostly non-blocking; the validate() tidy-up is the one worth doing.

sphamjoli · 2026-08-21T09:27:20Z

+    const contracts = contractsFromManifest(path);
+    log(`${network} (chain ${chainId}): ${Object.keys(contracts).length} addresses`);
+  }
+  const missing = readContractNames().filter(


Small thing: the contract list gets read and parsed here, then again on line 175 just to log the count. Reading it once into a variable and reusing it would avoid the second parse.

Fixed in 824137d : read only once now

sphamjoli · 2026-08-21T09:27:20Z

+    log(`${network} (chain ${chainId}): ${Object.keys(contracts).length} addresses`);
+  }
+  const missing = readContractNames().filter(
+    (name) => !existsSync(join(ROOT, "out", `${name}.sol`, `${name}.json`)) && !sourceExists(name),


sourceExists runs a separate git ls-files for every contract name. On the new metadata job there is no forge build, so out/ is absent and all 32 listed contracts fall through to their own git call. Listing the tracked sources once and checking membership would do the same work more simply. I checked that a set built from the sources resolves the same 32 names as the per-name globs, so it is behaviour preserving. Happy to make the change if you would like it.

Done in 824137d and thanks for checking. trackedSourceNames() now lists contracts once and builds a Set of basenames.

sphamjoli · 2026-08-21T09:27:20Z

+      cwd: ROOT,
+      encoding: "utf8",
+    });
+    return found.trim() !== "";


This catches any git failure and returns false, so a genuine git error surfaces as "no source or build artefact", which is a little misleading. It fails safe, so only a clarity point, and folding this into a single sources lookup avoids it anyway.

Changed in 824137d - a real git failure reports itself now

sphamjoli · 2026-08-21T09:27:20Z

+  const changed = Object.keys(current).filter(
+    (name) =>
+      previous[name] &&
+      JSON.stringify(previous[name].contracts) !== JSON.stringify(current[name].contracts),


This compares the two address sets by serialising them. It is fine today because Foundry writes the manifests with sorted keys, so both sides serialise in the same order, but it does tie the "addresses changed" note to that ordering. If a manifest were ever hand-edited into a different key order, the notes would announce a move that did not happen. Comparing per address, or sorting keys first, would make it robust. Minor.

Fixed in 824137d - sameAddresses() compares per label and case-insensitively now

sphamjoli · 2026-08-21T09:27:20Z

@@ -0,0 +1,370 @@
+#!/usr/bin/env bun


The file has a bun shebang but is always invoked as bun scripts/..., so the shebang is never used and the file is not executable. Worth a glance in case it was meant to run directly, otherwise fine to leave.

Good finding, removed in 824137d

sphamjoli · 2026-08-21T09:27:20Z

+
+Two ways to protect yourself. Resolve addresses through the protocol registry at runtime, so the chain is the authority and the published file is only a starting point. Or check a release against a chain yourself with `deployments:verify` before relying on it.
+
+The manual step is deliberate for now, and this file stays the single source of truth for addresses either way. The next step is for a deployment to update it automatically, so recording addresses stops depending on someone remembering. Later, publishing can read the chain and refuse to publish addresses that disagree with it.


Optional: this is a roadmap note in a reference doc. If no issue tracks it, a reader cannot act on it. Drop it, or link the issue.

Right, removed and created #245

publish contract addresses and a release manifest with each release

9da45db

github-actions Bot added dependencies Pull requests that update a dependency file other type: docs labels Aug 20, 2026

Merge branch 'master' into re-gius/publish-deployments-artifact

b843145

re-gius marked this pull request as ready for review August 20, 2026 10:10

re-gius requested review from sphamjoli and waytwotall as code owners August 20, 2026 10:10

remove addresses from pre-releases

46042fb

sphamjoli requested changes Aug 21, 2026

View reviewed changes

CR fixes

824137d

re-gius requested a review from sphamjoli August 21, 2026 13:16


		Two ways to protect yourself. Resolve addresses through the protocol registry at runtime, so the chain is the authority and the published file is only a starting point. Or check a release against a chain yourself with `deployments:verify` before relying on it.

		The manual step is deliberate for now, and this file stays the single source of truth for addresses either way. The next step is for a deployment to update it automatically, so recording addresses stops depending on someone remembering. Later, publishing can read the chain and refuse to publish addresses that disagree with it.

Uh oh!

Conversation

re-gius commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type

Scope

Related Issues

Fixes

Checklist

Code

Testing

Security

Documentation

Breaking Changes

How to test

Notes

Uh oh!

github-actions Bot commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CI Summary

Deployed addresses vs the committed manifest

Uh oh!

re-gius commented Aug 21, 2026

Uh oh!

sphamjoli left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sphamjoli Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

re-gius commented Aug 20, 2026 •

edited

Loading

github-actions Bot commented Aug 20, 2026 •

edited

Loading

sphamjoli left a comment •

edited

Loading

sphamjoli Aug 21, 2026 •

edited

Loading