| name | zkp2p-contracts-publish |
| description | Prepare, initiate, and verify @zkp2p/contracts-v2 releases through the repository's protected GitHub Actions trusted publisher. Use for release-line discovery, RC selection, package and address validation, pinned Foundry gating, npm OIDC publication, registry verification, or post-publish recovery. Never hard-code a release line or publish locally.
|
Trusted contracts package release
Read NPM_RELEASE.md, the active publishing workflow, package manifest, and
release-policy scripts completely before preparing a release. The repository
policy and workflow are authoritative.
Do not use local npm publish, npm dist-tag, an OTP, NPM_TOKEN, or another
developer credential as the normal release path.
Determine the current policy
Read, do not assume:
- package name and candidate from
packages/contracts/package.json;
- release line, dist-tag, latest baseline, environment, and allowed input shape
from
.github/workflows/publish-contracts-v2.yml;
- canonical tag format and recovery allowlist from
NPM_RELEASE.md;
- pinned Foundry version from the active CI and publish workflows.
Derive the release line by removing the allowed prerelease suffix from the
package candidate and require it to equal the workflow's release-line policy.
Do not carry a version from an older release or this skill.
Query the live npm registry and select the first unused candidate permitted by
the current policy. Every npm version is immutable.
Canonical release source
Do not trust a checkout's origin, a contributor fork, or a legacy redirect.
Resolve the release source through the canonical repository explicitly:
canonical_main_ref=refs/remotes/zkp2p-canonical/main
git fetch --no-tags https://github.com/zkp2p/zkp2p-contracts.git \
"+main:${canonical_main_ref}"
git rev-parse "$canonical_main_ref"
git rev-parse HEAD
Tags, workflow dispatch, package version, and CI evidence must all resolve to
the same canonical-main commit.
Modes and approvals
- Audit: read registry, workflow, package, tags, and CI only.
- Prepare: change version and consumer-facing metadata in a focused PR.
- RC publish: requires explicit approval for the exact version, commit, tag,
dist-tag, and workflow dispatch.
- Stable publish: requires separate explicit approval and a repository workflow
that implements stable publication.
If stable publication is not implemented by current policy, stop. Do not adapt
the RC workflow or publish locally.
Prepare the version PR
Keep package version, release-policy files, and consumer-visible documentation
consistent. Confirm package repository metadata points to
https://github.com/zkp2p/zkp2p-contracts.git.
Do not create or move a release tag before the version PR merges to canonical
main. Do not reuse an existing registry version.
Local preflight
Use a clean checkout and the repository-pinned Node/Yarn/Foundry setup. Confirm
local forge --version matches the active workflow pin; otherwise rely on CI
for Foundry evidence rather than claiming parity.
yarn install --immutable
yarn compile
yarn pkg:build
yarn pkg:test
yarn workspace @zkp2p/contracts-v2 verify:release
yarn test:release-policy
(cd packages/contracts && npm pack --dry-run --ignore-scripts --json)
The release verifier must prove current hard-cut package exports, canonical
source ABIs, and exact Base/Base Staging deployment addresses.
Do not rerun the complete Foundry suite locally when the exact commit is already
green in current CI. The publish workflow's pinned full-suite job remains an
authoritative gate and must not be weakened or skipped.
Initiate
After merge and current CI:
- Resolve canonical
main and its exact commit.
- Confirm the candidate is still unused in npm.
- Obtain explicit approval to create the exact release tag and dispatch the
trusted workflow for the named version, commit, release line, and dist-tag.
- Create the repository-controlled package tag required by current policy at
that exact commit.
- Recheck tag SHA, workflow SHA, package version, release line, dist-tag, and
latest baseline.
- Dispatch the trusted publishing workflow from canonical
main. If any
checked value changed after approval, stop and obtain new approval.
The publish job must use GitHub OIDC provenance and the protected environment
defined by current policy.
Verify
Require:
- workflow validation and pinned Foundry jobs passed for the published commit;
- npm exact version and intended dist-tag match;
- stable/latest remains unchanged for an RC;
- registry integrity and provenance match the validated tarball;
- clean installs of the exact version and intended tag expose required ABIs,
addresses, and module formats.
Recovery
If npm accepted an immutable version but registry propagation caused only a
post-publish verification failure, follow NPM_RELEASE.md recovery exactly.
Recovery verifies; it must not obtain OIDC publication authority or republish.
Recovery must run from canonical main with release_run_id set to the
original non-recovery publish run whose validated tarball npm accepted. Require
the original release tag to be an ancestor, permit only the runbook's
allowlisted release-only files after that tag, rebuild the package, rerun every
release gate, compare registry integrity to the original validated tarball, and
verify the registry without OIDC publication authority.
For content, integrity, version, provenance, or dist-tag disagreement, stop and
prepare a new forward-fix version unless current policy explicitly authorizes a
protected maintainer correction. Never rerun publication blindly.
Report
Report current release policy, derived release line, exact candidate, source and
tag SHAs, approvals, local preflight, pinned CI/Foundry evidence, workflow URL,
registry/provenance verification, and any stable boundary left unimplemented.
