feat(deploy): Ethereum V4 authoriser clone — chain-parametric deploy script + per-chain pin selector

[hardyjosh]

Deploys the V4 authoriser clone on Ethereum by running the same script
that deployed it on Base, adapted only to pick the active chain's pin.

• Deploy script (20260619-deploy-v4-authoriser-clone) — already
  chain-agnostic (it reads the impl, Safe, and role grants from libs), so the
  only change is swapping the single-chain clone lookup for a per-chain one
  (LibProdAuthoriserClones.cloneForChainId(block.chainid)). Deploy on
  Ethereum by running it with --rpc-url ethereum; on Base it self-guards
  (V4AuthoriserClonePinAlreadyHydrated) because the Base pin is set.

• Per-chain clone selection — activeChainClonePin() in the deploy script
  dispatches on block.chainid to the active chain's LibProdDeployV4 pin.
  It is a SELECTOR, not a second copy of the addresses: Base resolves the
  generated STOX_PROD_AUTHORISER_V4_CLONE pin (0x315b…) and Ethereum
  resolves STOX_PROD_AUTHORISER_V4_CLONE_ETHEREUM, an address(0)
  placeholder until the post-deploy hydrate PR fills it (the clone is a
  nonce-based CloneFactory.clone, so its address cannot be known ahead of
  the broadcast). An unpinned chain reverts
  V4AuthoriserCloneUnsupportedChain rather than falling back to another
  chain's clone. The chain ids come from LibSafeInvariants.BASE_CHAIN_ID /
  ETHEREUM_CHAIN_ID, the same constants the sibling per-chain selectors use.
  The EIP-1167 codehash is deterministic and shared, so it stays on the
  existing generated pin. No hand-written change to src/generated — the
  new Ethereum constant is emitted by BuildPointers, so the file still
  regenerates byte-for-byte.

• run-script workflow — drops the clone deploy from the Safe-artifact
  pipeline. It's a deploy-key broadcast (the key deploys the clone, assigns
  the Safe's role grants, and self-revokes admin), not a Safe-signed artifact,
  so it belongs in the manual deploy-key flow.

• Runbook (docs/ETHEREUM_BOOTSTRAP.md) — operator steps for the Ethereum
  bootstrap.

Summary by CodeRabbit

• New Features

  • Deployment workflows now support selecting Base or Ethereum as the target network.
  • Network-specific deployment verification and authoriser clone configuration are supported.
  • Generated deployment pointers now include an Ethereum V4 authoriser clone placeholder.

• Documentation

  • Clarified receipt vault upgrade steps and deployment test comments.

[coderabbitai]

📝 Walkthrough

Walkthrough

The workflow now targets Base or Ethereum. V4 authoriser clone deployment selects chain-specific pins and Safe grant expectations, rejects unsupported chains, and verifies the active-chain post-state. Generated constants and related documentation comments are updated.

Changes

Network-aware V4 deployment

Layer / File(s)	Summary
Workflow network selection .github/workflows/manual-broadcast.yaml	Manual broadcasts accept Base or Ethereum, isolate concurrency by network, and pass the selected RPC endpoint to Forge.
Chain-specific clone pinning and verification script/20260619-deploy-v4-authoriser-clone.s.sol, script/BuildPointers.sol, script/20260623-upgrade-receipt-vaults-to-v4.s.sol, test/src/concrete/deploy/StoxProdV4PostSwap.t.sol	Generated V4 deployment pointers include an Ethereum clone placeholder; deployment and post-state checks resolve active-chain pins, Safes, and expected grants, with related comments updated.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant GitHubActions
  participant forge
  participant SelectedRPC
  participant DeployV4AuthoriserClone
  participant LibSafeInvariants
  Operator->>GitHubActions: Select script and network
  GitHubActions->>forge: Pass selected RPC alias and secrets
  forge->>SelectedRPC: Execute broadcast
  SelectedRPC-->>DeployV4AuthoriserClone: Run on active chain
  DeployV4AuthoriserClone->>LibSafeInvariants: Resolve clone pin and Safe
  DeployV4AuthoriserClone->>DeployV4AuthoriserClone: Verify chain-specific post-state

Loading

Possibly related PRs

• S01-Issuer/st0x.deploy#209: Extends the same V4 authoriser clone deployment and grant-mirroring logic.
• S01-Issuer/st0x.deploy#242: Relates to the deployment flow and corresponding post-state assertions.
• S01-Issuer/st0x.deploy#252: Updates the V4 authoriser clone pin and codehash expectations used by this flow.

Suggested reviewers: thedavidmeister

Poem

I’m a rabbit hopping chain to chain,
Base and Ethereum through the rain.
Pins now follow where we go,
Safes grant the roles they know.
Clone checks bloom—no guesswork remains!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: chain-parametric V4 authoriser clone deployment with per-chain pin selection.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/rai-1095-ethereum-bootstrap

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 Checkov (3.3.8)

.github/workflows/manual-broadcast.yaml

Traceback (most recent call last):
File "/usr/local/bin/checkov", line 2, in
from checkov.main import Checkov
ModuleNotFoundError: No module named 'checkov'

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[hardyjosh]

• feat(script): deploy the Ethereum production tokens via the deploy key, matched to Base #231 : 2 dependent PRs (#257 , #259 )
• test(parity): cross-chain deployment parity pin + scheduled CI #230
• pin(ethereum): hydrate the V4 authoriser clone address #258
• feat(deploy): Ethereum V4 authoriser clone — chain-parametric deploy script + per-chain pin selector #229 👈 (View in Graphite)
• feat(tokens): add MU/AMD/AVGO/AMAT/LRCX/TTWO to the Base production token list #265
• fix(test): assert ownership of the IN-USE production beacons per chain #266
• feat(lib): chain-aware token-owner Safe assertion #267
• fix(test): retire executed-migration simulations, repoint authoriser truth #268
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/manual-broadcast.yaml:
- Around line 73-89: Update the workflow step using BASE_RPC_URL,
ETHEREUM_RPC_URL, and NETWORK so only the RPC secret corresponding to the
selected network is exposed to the Forge invocation. Remove the unconditional
injection of both RPC secrets and derive or conditionally assign the selected
value before running the command, while preserving NETWORK for --rpc-url alias
resolution.
- Around line 22-34: Validate the selected network against the chosen script
before invoking Forge in the workflow. Add an explicit script-to-network
allowlist or reject incompatible pairs so Base-only scripts such as
20260623-upgrade-receipt-vaults-to-v4.s.sol cannot run with ethereum, while
preserving valid base and Ethereum bootstrap combinations.

In `@script/20260619-deploy-v4-authoriser-clone.s.sol`:
- Around line 140-155: Add focused tests covering activeChainClonePin for Base
and Ethereum, asserting each returns its corresponding LibProdDeployV4 pin,
including the zero Ethereum placeholder when applicable. Add an
unsupported-chain test that expects V4AuthoriserCloneUnsupportedChain with the
chain ID, and ensure all selector branches are exercised.

In `@script/BuildPointers.sol`:
- Around line 334-339: Update genCurrent() to expose
STOX_PROD_AUTHORISER_V4_CLONE_ETHEREUM alongside the existing Base clone alias,
reusing the Ethereum constant emitted by genV4() so LibProdDeployCurrent stays
synchronized with the new pin.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 51f1a3ab-f26b-4921-a671-63d863723260

📥 Commits

Reviewing files that changed from the base of the PR and between d885b92 and 470e8ab.

⛔ Files ignored due to path filters (1)

• src/generated/LibProdDeployV4.sol is excluded by !**/generated/**

📒 Files selected for processing (5)

• .github/workflows/manual-broadcast.yaml
• script/20260619-deploy-v4-authoriser-clone.s.sol
• script/20260623-upgrade-receipt-vaults-to-v4.s.sol
• script/BuildPointers.sol
• test/src/concrete/deploy/StoxProdV4PostSwap.t.sol

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Constrain network choices to compatible scripts.

network is independent from script, so a Base-only script such as script/20260623-upgrade-receipt-vaults-to-v4.s.sol can be run with ethereum while the workflow still passes --broadcast. Add a script-to-network allowlist or reject incompatible pairs before invoking Forge.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/manual-broadcast.yaml around lines 22 - 34, Validate the
selected network against the chosen script before invoking Forge in the
workflow. Add an explicit script-to-network allowlist or reject incompatible
pairs so Base-only scripts such as 20260623-upgrade-receipt-vaults-to-v4.s.sol
cannot run with ethereum, while preserving valid base and Ethereum bootstrap
combinations.

[coderabbitai]

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Expose only the selected RPC secret.

Both BASE_RPC_URL and ETHEREUM_RPC_URL are injected into every Forge invocation. Any dispatched script can read the non-selected secret, and provider credentials may be embedded in these URLs. Pass only the RPC secret for the selected network.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/manual-broadcast.yaml around lines 73 - 89, Update the
workflow step using BASE_RPC_URL, ETHEREUM_RPC_URL, and NETWORK so only the RPC
secret corresponding to the selected network is exposed to the Forge invocation.
Remove the unconditional injection of both RPC secrets and derive or
conditionally assign the selected value before running the command, while
preserving NETWORK for --rpc-url alias resolution.

[coderabbitai]

🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add tests for every chain-selection branch.

This selector is the deployment safety boundary, but the supplied tests do not cover Base, Ethereum, or unsupported-chain behavior. Add focused tests for both pins, the zero Ethereum placeholder, and V4AuthoriserCloneUnsupportedChain.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@script/20260619-deploy-v4-authoriser-clone.s.sol` around lines 140 - 155, Add
focused tests covering activeChainClonePin for Base and Ethereum, asserting each
returns its corresponding LibProdDeployV4 pin, including the zero Ethereum
placeholder when applicable. Add an unsupported-chain test that expects
V4AuthoriserCloneUnsupportedChain with the chain ID, and ensure all selector
branches are exercised.

[coderabbitai]

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Keep LibProdDeployCurrent synchronized with the new pin.

genV4() now emits STOX_PROD_AUTHORISER_V4_CLONE_ETHEREUM, but genCurrent() only aliases the Base clone at Lines [364-371]. Consumers importing the current generated library cannot access the Ethereum pin.

Proposed fix

+        vm.writeLine(
+            GEN_CURRENT_PATH,
+            "address constant STOX_PROD_AUTHORISER_V4_CLONE_ETHEREUM = LibProdDeployV4.STOX_PROD_AUTHORISER_V4_CLONE_ETHEREUM;"
+        );

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	// Ethereum V4 authoriser clone — same nonce-based `CloneFactory.clone`
	// deploy as Base, so its address is non-deterministic and hand-provided
	// here (placeholder `address(0)` until the Ethereum bootstrap deploys it
	// and the hydrate PR replaces this literal). Shares the deterministic
	// EIP-1167 codehash above (same impl on every chain).
	vm.writeLine(GEN_V4_PATH, "address constant STOX_PROD_AUTHORISER_V4_CLONE_ETHEREUM = address(0);");
	// Ethereum V4 authoriser clone — same nonce-based `CloneFactory.clone`
	// deploy as Base, so its address is non-deterministic and hand-provided
	// here (placeholder `address(0)` until the Ethereum bootstrap deploys it
	// and the hydrate PR replaces this literal). Shares the deterministic
	// EIP-1167 codehash above (same impl on every chain).
	vm.writeLine(GEN_V4_PATH, "address constant STOX_PROD_AUTHORISER_V4_CLONE_ETHEREUM = address(0);");
	vm.writeLine(
	GEN_CURRENT_PATH,
	"address constant STOX_PROD_AUTHORISER_V4_CLONE_ETHEREUM = LibProdDeployV4.STOX_PROD_AUTHORISER_V4_CLONE_ETHEREUM;"
	);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@script/BuildPointers.sol` around lines 334 - 339, Update genCurrent() to
expose STOX_PROD_AUTHORISER_V4_CLONE_ETHEREUM alongside the existing Base clone
alias, reusing the Ethereum constant emitted by genV4() so LibProdDeployCurrent
stays synchronized with the new pin.

[thedavidmeister]

Reviewed 470e8ab: approve

Fresh run 29955854806 leaves one test failure — testDeployTag (0_1_8 != 0_1_16) — plus git-clean. Both inherited main-red; the MU ReceiptVaultAuthoriserMismatch pair from the 09:58 run is gone now that #265 has landed.

The chain-parametric conversion is sound. The script self-guards on Base via V4AuthoriserClonePinAlreadyHydrated, reverts with a typed error on any unpinned chain rather than borrowing another chain's clone, resolves the active chain's Safe through assertActiveChainTokenOwnerSafe, and parameterises the grant map on that Safe so Ethereum cannot be provisioned with Base's Safe in the grantee slots. The workflow passes both choice inputs via env rather than template expansion, and keys concurrency per network so a Base and an Ethereum broadcast cannot race on nonce state.

That "reverts rather than falls back" decision is load-bearing in a way worth recording. Reviewing #258 I found the Ethereum clone address 0x66566cc9… also has code on Base — a different clone, embedding the V3-era authoriser impl 0x2b4a510c…. So a fallback here would not resolve to nothing; it would resolve to a live, wrong authoriser that passes any code.length > 0 check. Only a codehash comparison separates them.

Three review findings, all disposed:

1. The body documented a LibProdAuthoriserClones that does not exist — rewritten to describe the real activeChainClonePin().
2. Raw block.chainid == 1 / == 8453 while both sibling selectors use the named constants — fixed in 470e8ab (LibSafeInvariants.ETHEREUM_CHAIN_ID / BASE_CHAIN_ID).
3. Four independent per-chain dispatch sites with nothing enforcing they agree on the supported-chain set — filed as Four independent per-chain dispatch sites — adding a chain fails at broadcast time, not compile time #272, since it is the subsystem's shape rather than this PR's defect.

Checked and fine: the leftover no-arg expectedGrants() in assertGrantsSliceInvariant only reads .length, and the map's structure is chain-agnostic; BuildPointers emitting ..._V4_CLONE_ETHEREUM keeps src/generated regenerating byte-for-byte.