refactor(invariants): structured token table + per-chain-Safe-parametric invariants

[hardyjosh]

Groundwork for the Ethereum bootstrap. Makes the production-state
invariants resolve the token-owner Safe per chain and introduces a
structured token table. No behavioural change on Base — every existing
call site keeps its exact semantics (pinned by test).

• LibTokenInvariants — new TokenInstance struct (underlying ticker as
  the chain-agnostic join key + receipt / receipt-vault / wrapped-vault
  triple) and productionTokensBase() as the structured source of truth;
  productionReceiptVaults() now derives from it so the two accessors
  cannot drift. (Carries the SKHY 21st entry pulled through from main.)

• LibAuthoriserInvariants — expectedGrants / assertExpectedGrants
  gain an overload parameterised over the token-owner Safe address, so the
  role-grant STRUCTURE (5 _ADMIN Safe + 3 service action + 3 Safe action)
  is defined once and filled with a given chain's Safe. The no-arg Base
  overloads delegate to the parametric ones with the pinned Base Safe, so
  the Base grant map is unchanged pair-for-pair.

• LibInvariants — assertProductionState resolves the token-owner Safe
  from block.chainid (LibSafeInvariants.safeForChainId) and asserts the
  Safe policy matches Base, so the same production-state assertion runs on
  any supported chain.

Supersedes the earlier LibChainPrincipals approach (a per-chain principal
struct), which was removed in favour of shared principals + a single
per-chain Safe address — the only thing that actually differs per chain.

Summary by CodeRabbit

• Improvements

  • Production-state checks now support token and authoriser configurations across multiple chains.
  • Token ownership and authoriser validation use a consistent production token inventory.
  • Authoriser grant verification now accommodates each chain’s token-owner Safe while preserving required service permissions.
  • Existing validation entry points remain compatible with prior configurations.

• Tests

  • Added live Base-network coverage for production-state invariant validation.

[coderabbitai]

📝 Walkthrough

Walkthrough

The invariant libraries now support chain-specific token tables, Safe addresses, and authoriser grant expectations. Base wrappers remain available, and a fork-based test validates equivalent Base invariant entrypoints.

Changes

Production invariant generalisation

Layer / File(s)	Summary
Token table and parameterized vault checks src/lib/LibTokenInvariants.sol	Adds TokenInstance records and derives receipt-vault ownership and authoriser checks from the production token table.
Multi-chain production-state pre-flight src/lib/LibInvariants.sol, test/src/lib/LibInvariants.t.sol	Resolves the Safe by chain ID, validates supplied token data and authoriser state, and tests the Base fork path.
Chain-specific authoriser grant expectations src/lib/LibAuthoriserInvariants.sol	Parameterizes _ADMIN grantees by token-owner Safe while preserving existing overloads and service signer grants.

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

Possibly related PRs

• S01-Issuer/st0x.deploy#197: Adds related receipt-vault authoriser migration and invariant checks.
• S01-Issuer/st0x.deploy#201: Modifies the same authoriser grant invariant logic.
• S01-Issuer/st0x.deploy#209: Uses the parameterized authoriser grant expectations in clone deployment and mirroring.

Suggested reviewers: thedavidmeister, thedavidmeister

Poem

I’m a rabbit who hops through the grants,
With token tables tucked in my pants.
Safe by chain, vaults aligned,
Every pinned role is checked and defined.
Base still passes—what delightful romance!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main refactor: structured token tables and per-chain Safe parameterization for invariants.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/rai-1096-chain-principals

---

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 , #258 )
• test(parity): cross-chain deployment parity pin + scheduled CI #230
• feat(deploy): Ethereum V4 authoriser clone — chain-parametric deploy script + per-chain pin selector #229
• refactor(invariants): structured token table + per-chain-Safe-parametric invariants #228 👈 (View in Graphite)
• feat(beacon): migrate Ethereum production beacons to the Ethereum Safe #262
• feat(safe): Ethereum token-owner Safe — distinct per-chain address pin + policy-parity #232
• feat(deploy): ship the audited 0.1.1 production set to Ethereum mainnet #227
• main

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