verify-deployment-pr

Verify Deployment PR

READ-ONLY audit of an already-executed deployment PR. Never broadcast a transaction, never edit files, never re-run the live deployment. All on-chain data comes from the block explorer (via sol2uml/Etherscan) or a read-only RPC.

Step 0 — Prerequisites (fail fast)

1. All commands run from contracts/: cd contracts.
2. Require contracts/.env with PROVIDER_URL and ETHERSCAN_API_KEY: grep -oE '^(PROVIDER_URL|ETHERSCAN_API_KEY)=' .env. Source it for shell use: set -a; . ./.env; set +a (so $ETHERSCAN_API_KEY is available to sol2uml).
   • Missing ETHERSCAN_API_KEY → checks 2/3/4 can't run → STOP and report the blocker.
3. Require gh authenticated (gh auth status). If absent, ask the user to paste the PR body + deployed-address list rather than failing.
4. Require sol2uml on PATH (command -v sol2uml). If absent: npm i -g sol2uml.
5. Verify you are on the correct branch. This is the most important prereq: every check diffs the on-chain deployment against the local code, so a wrong branch (or a dirty tree) silently produces meaningless results. Match the checkout to the PR head:
   • gh pr view "$PR" --json headRefName,state,mergeCommit
   • git rev-parse --abbrev-ref HEAD and git status --porcelain
   • Require the current branch to equal the PR's headRefName, OR — if the PR is already merged — that the checkout contains its merge commit (git merge-base --is-ancestor <mergeCommit> HEAD).
   • On mismatch or a dirty working tree → STOP. Tell the user to gh pr checkout <PR> (or git checkout <headRefName> / git stash) and re-run. Do not verify against the wrong code.

Step 1 — Gather PR context

1. PR=$1. gh pr view "$PR" --json title,body,files,baseRefName,headRefName,state,url.
2. Find the changed Foundry deploy script(s): git diff --name-only origin/master...HEAD -- 'contracts/scripts/deploy/**/*.s.sol' (or read the PR files). Ignore 000_Example.s.sol. The folder under scripts/deploy/<network>/ gives the network (mainnet, base, sonic, hyperevm, …) — use it for sol2uml --network <net> and map it to the chain deployment file (build/deployments-1.json, -8453.json, -146.json, -999.json, etc.).
3. From each script's _execute(), enumerate every contract creation (new <Contract>(args)) and every _recordDeployment("<KEY>", address(...), type(<Contract>).name) call. Resolve <KEY> → address from the matching entry in the chain deployment JSON's contracts array (.name, .implementation). The JSON field is named implementation even for proxies and non-implementation contracts. If a newly recorded key is absent from the committed JSON, mark checks 1/3/4 ❌.
4. The script identifier is the string passed to AbstractDeployScript("<ID>"). Resolve its proposalId, tsDeployment, and tsGovernance from the matching entry in the chain deployment JSON's executions array. Build expected governance actions from _buildGovernanceProposal() calls to govProposal.action(target, "signature(types)", abi.encode(args)). If proposalId is 0/absent while governance is expected, mark check 5 ⚠️ ("no proposalId recorded — resolve from on-chain Governor events or ask the deployer").
5. Working set: [{key, contractType, address, constructorArgs, proposalId, network, deployScript}].