feat(multichain): HyperEVM token-owner Safe pin plumbing (RAI-1511)

[hardyjosh]

• STOX_TOKEN_OWNER_SAFE_HYPEREVM = address(0) until the freshly-created
  HyperEVM Safe's address lands (canonical Safe v1.4.1 infra verified live
  on HyperEVM at the canonical addresses, 2026-07-22).
• safeForChainId branch for chain 999 — every consumer of
  assertActiveChainTokenOwnerSafe becomes HyperEVM-aware the moment the
  pin hydrates, with zero further code changes.
• HyperEvmTokenOwnerSafeParityTest, mirroring the Ethereum parity pin:
  PENDING (loud) while the pin is unhydrated, then asserts the shared
  policy against the live HyperEVM Safe. Second loud PENDING gate on the
  RPC env: the shared rainix test workflow has no HyperEVM secret slot
  yet, so CI cannot fork HyperEVM until rainix grows one (noted for
  follow-up in RAI-1511).

Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01VPs1hCTxusmaSeFKvoc4Kr

Summary by CodeRabbit

• New Features

  • Added support for resolving the designated token-owner Safe on HyperEVM.
  • Added HyperEVM chain configuration for scheduled and standard validation workflows.

• Tests

  • Added validation confirming the HyperEVM token-owner Safe matches the required owners, approval threshold, and identity policy.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds HyperEVM Safe address routing for chain ID 999, validates the pinned Safe against shared invariants on a fork, and passes the HyperEVM RPC secret to Rainix workflows.

Changes

HyperEVM Safe support

Layer / File(s)	Summary
HyperEVM Safe routing src/lib/LibSafeInvariants.sol	The library defines the HyperEVM token-owner Safe address and returns it for chain ID 999.
Parity validation and fork CI test/src/concrete/deploy/HyperEvmTokenOwnerSafeParity.t.sol, .github/workflows/rainix-sol.yaml, .github/workflows/rainix-sol-scheduled.yaml	The fork test checks the Safe owner set, threshold, and identity policy. Both Rainix workflows pass RPC_URL_HYPEREVM_FORK.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• S01-Issuer/st0x.deploy#189: Introduces the Safe infrastructure extended by this change.
• S01-Issuer/st0x.deploy#228: Adds related per-chain Safe parameterization and invariants.
• S01-Issuer/st0x.deploy#273: Adds related HyperEVM support and configures the same RPC secret.

Suggested reviewers: thedavidmeister

Poem

A rabbit checks the Safe at night,
Chain nine-nine-nine resolves just right.
The fork confirms each owner’s place,
Rainix carries RPC grace.
Hop, hop—HyperEVM joins the race!

🚥 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 identifies the HyperEVM token-owner Safe plumbing, which is the main change in the pull request.
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/hyperevm-safe-pin

---

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]

• ops(script): HyperEVM token deploy (RAI-1511) #278 : 2 dependent PRs (#284 , #291 )
• pin(invariants): HyperEVM invariant surface (RAI-1511) #277
• ops(script): HyperEVM beacon-owner migration + 0.1.1 beacon lib generalisation (RAI-1511) #276
• feat(multichain): HyperEVM token-owner Safe pin plumbing (RAI-1511) #275 👈 (View in Graphite)
• feat(multichain): HyperEVM V4 authoriser clone pin plumbing (RAI-1511) #274
• feat(authoriser): additional service signer — canonical pin + provisioning #280
• main

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

[thedavidmeister]

Forwarded the HyperEVM RPC secret; the parity test now actually runs

Head is now 9f18d50fa8afac41cfa53011085fbe3b6837787b. Two changes.

1. RPC_URL_HYPEREVM_FORK pass-through

rainix's reusable workflow already declares the slot — rainix-sol.yaml line 21 in rainlanguage/rainix, forwarded to rainix-sol-test.yaml line 21, where the rpc-preflight step binds RAINIX_RPC_SECRET_HYPEREVM / RAINIX_RPC_VARS_HYPEREVM (lines 80-81). This repo's callers just never passed it through, so HYPEREVM_RPC_URL was absent in CI. One line added to each of the two callers, in the existing alphabetical position between FLARE and POLYGON:

.github/workflows/rainix-sol.yaml
.github/workflows/rainix-sol-scheduled.yaml

      RPC_URL_HYPEREVM_FORK: ${{ secrets.RPC_URL_HYPEREVM_FORK }}

The scheduled workflow had the identical omission, so it is fixed too — a daily parity re-run that silently skips HyperEVM is exactly the drift this workflow exists to catch.

2. Both PENDING return guards deleted from HyperEvmTokenOwnerSafeParity.t.sol

• The hyperevmSafe == address(0) guard was already dead code: STOX_TOKEN_OWNER_SAFE_HYPEREVM ships non-zero at 0x3840aeDaEc8e82f79d8F6a8F6ADCa271E13E0329.
• The HYPEREVM_RPC_URL guard turned a missing fork endpoint into a silent pass. With the secret carried, that skip is what the docstring itself asked to remove.

The test is now fork-and-assert unconditionally, and the docstring follows the code — the pending-gate prose is gone.

Also corrected a false claim in the same docstring: it said the HyperEVM Safe "is a distinct address from the other chains' Safes". It is not. STOX_TOKEN_OWNER_SAFE_HYPEREVM is byte-identical to STOX_TOKEN_OWNER_SAFE_ETHEREUM (both 0x3840aeDa…), deliberately — the canonical Safe proxy factory with the same initializer yields the same CREATE2 address across chains, exactly as LibSafeInvariants.sol line 216-223 documents twelve lines from the constant. The test asserts no distinctness anywhere, so nothing but the prose was wrong. (Note the sibling EthereumTokenOwnerSafeParityTest does assert distinctness from Base, and correctly so — that Safe genuinely is a distinct per-chain address. Only the HyperEVM copy of the sentence was wrong.)

LibSafeInvariants.sol is untouched by this push — no constant changed, no change to the assertTokenOwnerSafePolicy call.

Live-run evidence

Preflight, confirming the Safe proxy genuinely exists on HyperEVM (chain id 0x3e7 = 999):

$ curl -s -X POST -H 'Content-Type: application/json' \
    --data '{"jsonrpc":"2.0","id":1,"method":"eth_getCode","params":["0x3840aeDaEc8e82f79d8F6a8F6ADCa271E13E0329","latest"]}' \
    https://rpc.hyperliquid.xyz/evm
{"jsonrpc":"2.0","id":1,"result":"0x608060405273ffffffffffffffffffffffffffffffffffffffff600054167fa619486e…"}

That is the Safe v1.4.1 SafeProxy runtime bytecode, not an empty account.

The test, against live HyperEVM state, in the repo's own CI toolchain:

$ HYPEREVM_RPC_URL=https://rpc.hyperliquid.xyz/evm \
  nix develop github:rainlanguage/rainix/53e96a7d0a97d7c7c75c3b2412521324776fdac6#sol-shell \
    -c forge test --match-path 'test/src/concrete/deploy/HyperEvmTokenOwnerSafeParity.t.sol' -vvv

Compiling 183 files with Solc 0.8.25
Solc 0.8.25 finished in 5.73s
Compiler run successful!

Ran 1 test for test/src/concrete/deploy/HyperEvmTokenOwnerSafeParity.t.sol:HyperEvmTokenOwnerSafeParityTest
[PASS] testHyperEvmSafeMatchesSharedPolicy() (gas: 58694)
Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 5.51s (5.51s CPU time)

assertTokenOwnerSafePolicy passes on live HyperEVM state: owner set (order-insensitive), threshold, v1.4.1 identity. The gas figure is the tell that it really forked and made the calls rather than returning early.

And the negative case, proving the skip is genuinely gone — same command with HYPEREVM_RPC_URL unset:

[FAIL: vm.createSelectFork: environment variable `HYPEREVM_RPC_URL` not found] testHyperEvmSafeMatchesSharedPolicy() (gas: 3188)
Suite result: FAILED. 0 passed; 1 failed; 0 skipped

A missing RPC is now a hard failure instead of a green skip, which is the whole point of the change. Full-project compile (183 files) succeeded and forge fmt --check is clean.

Raised, not fixed

Nothing blocking. One observation: this branch's CI has never had a HyperEVM RPC, so the run on 9f18d50 is the first time this test executes in CI — if the repo secret RPC_URL_HYPEREVM_FORK is not actually populated, the job will now go red rather than skip. That is the intended behaviour, but it is worth watching the first run rather than assuming.

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@test/src/concrete/deploy/HyperEvmTokenOwnerSafeParity.t.sol`:
- Around line 25-26: Update the HyperEVM parity test to assert block.chainid
equals LibSafeInvariants.HYPEREVM_CHAIN_ID, resolve the Safe via
assertActiveChainTokenOwnerSafe(block.chainid), and compare the resolved address
against both pinned Safe addresses instead of reading
STOX_TOKEN_OWNER_SAFE_HYPEREVM directly.

🪄 Autofix

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 Plus

Run ID: 63b5725a-ee6a-45d8-936b-bf6b4f7c3187

📥 Commits

Reviewing files that changed from the base of the PR and between 13d77f3 and 9f18d50.

📒 Files selected for processing (4)

• .github/workflows/rainix-sol-scheduled.yaml
• .github/workflows/rainix-sol.yaml
• src/lib/LibSafeInvariants.sol
• test/src/concrete/deploy/HyperEvmTokenOwnerSafeParity.t.sol

[coderabbitai]

🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Exercise the HyperEVM routing path in this parity test.

The production consumer in src/lib/LibInvariants.sol:45-54 resolves the Safe through assertActiveChainTokenOwnerSafe, but this test reads STOX_TOKEN_OWNER_SAFE_HYPEREVM directly. A broken safeForChainId(999) branch can pass this test. Because the HyperEVM and Ethereum pins share an address, an incorrectly selected Ethereum fork can also pass.

Assert block.chainid == LibSafeInvariants.HYPEREVM_CHAIN_ID, resolve the Safe through assertActiveChainTokenOwnerSafe(block.chainid), and compare the result with both pinned addresses.

Proposed fix

         vm.createSelectFork(LibStoxDeployNetworks.HYPEREVM);
-        LibSafeInvariants.assertTokenOwnerSafePolicy(IGnosisSafe(hyperevmSafe));
+        assertEq(block.chainid, LibSafeInvariants.HYPEREVM_CHAIN_ID);
+        IGnosisSafe resolvedSafe = IGnosisSafe(
+            LibSafeInvariants.assertActiveChainTokenOwnerSafe(block.chainid)
+        );
+        assertEq(address(resolvedSafe), hyperevmSafe);
+        assertEq(address(resolvedSafe), LibSafeInvariants.STOX_TOKEN_OWNER_SAFE_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

	vm.createSelectFork(LibStoxDeployNetworks.HYPEREVM);
	LibSafeInvariants.assertTokenOwnerSafePolicy(IGnosisSafe(hyperevmSafe));
	vm.createSelectFork(LibStoxDeployNetworks.HYPEREVM);
	assertEq(block.chainid, LibSafeInvariants.HYPEREVM_CHAIN_ID);
	IGnosisSafe resolvedSafe = IGnosisSafe(
	LibSafeInvariants.assertActiveChainTokenOwnerSafe(block.chainid)
	);
	assertEq(address(resolvedSafe), hyperevmSafe);
	assertEq(address(resolvedSafe), LibSafeInvariants.STOX_TOKEN_OWNER_SAFE_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 `@test/src/concrete/deploy/HyperEvmTokenOwnerSafeParity.t.sol` around lines 25
- 26, Update the HyperEVM parity test to assert block.chainid equals
LibSafeInvariants.HYPEREVM_CHAIN_ID, resolve the Safe via
assertActiveChainTokenOwnerSafe(block.chainid), and compare the resolved address
against both pinned Safe addresses instead of reading
STOX_TOKEN_OWNER_SAFE_HYPEREVM directly.

[thedavidmeister]

Reviewed 9f18d50: pass

The HyperEVM Safe pin, with the coverage now actually executing rather than skipping.

Verified against the chain, not the repo. eth_getCode on HyperEVM at 0x3840aeDaEc8e82f79d8F6a8F6ADCa271E13E0329 returns the Safe proxy runtime (0x608060527…a619486e, the masterCopy() selector), so the pinned Safe genuinely exists there. It is byte-identical to STOX_TOKEN_OWNER_SAFE_ETHEREUM deliberately: the canonical Safe proxy factory with the same initializer gives the same CREATE2 address across chains, exactly as the constant's own doc states.

Verified in CI, not only locally. rainix-sol / test on this head:

Ran 1 test for test/src/concrete/deploy/HyperEvmTokenOwnerSafeParity.t.sol:HyperEvmTokenOwnerSafeParityTest
[PASS] testHyperEvmSafeMatchesSharedPolicy() (gas: 58694)

Same gas as the local run against https://rpc.hyperliquid.xyz/evm, so the job forked live HyperEVM state and assertTokenOwnerSafePolicy held. This is the first CI run in which this test executes at all.

What changed since my first read, and why it matters. As originally written both branches returned early — an address(0) guard that was already dead (the constant ships non-zero) and an HYPEREVM_RPC_URL guard that always fired, because .github/workflows/rainix-sol.yaml forwards six RPC secrets to the shared rainix workflow and RPC_URL_HYPEREVM_FORK was not among them. rainix has declared that slot all along (rainix-sol.yaml line 21, bound as RAINIX_RPC_SECRET_HYPEREVM in its rpc-preflight step); only the caller was missing the pass-through. One line in each of rainix-sol.yaml and rainix-sol-scheduled.yaml — the scheduled workflow had the identical omission, and fixing one without the other would have left the nightly still skipping.

The skip is provably gone rather than merely edited: with HYPEREVM_RPC_URL unset the test now fails at vm.createSelectFork instead of logging PENDING and passing green.

One docstring correction. The contract's doc claimed the Safe "is a distinct address from the other chains' Safes". It is not, the test asserts no such thing, and the constant twelve lines away says the opposite. That false premise is precisely what led me to misread the sibling pin in #274 as a copy-paste defect before the chain corrected me — an identical address across chains reads as a bug unless something states it is deterministic. Now it does.

Rulings-conformance:

• Enumerate authority from the chain, never from repo greps. OBEYED: every claim above rests on eth_getCode or a CI log, not on reading a constant.
• Coverage, not manual verification. OBEYED, and this is the substance: a guard that returns early is not coverage, and the negative case was run to prove its removal bites.
• Comments describe CURRENT behaviour only. OBEYED: the pending-gate prose went with the gates it described.
• *.deploy repos are audited code, internally consistent. LibSafeInvariants.sol's constants and assertTokenOwnerSafePolicy are untouched.
• Never invent scope. The sibling EthereumTokenOwnerSafeParityTest carries the same now-dead address(0) guard and was deliberately left alone — raised, not fixed.

CI: every check passes. Merging with --merge per the standing no-squash rule for Graphite stacks; 276 is based on this head branch and will need retargeting to main.