Govern roles, admin, upgrades and wind-downs from the console

[luchobonatti]

Summary

Closes #197

The Governance tab lists every role holder and lets each contract's admin grant and revoke roles, hand over admin in two steps, and propose, apply or cancel upgrades and wind-downs.

Changes

• Role holders are enumerated on the vault, oracle and share token; each admin grants and revokes its own contract's roles
• Admin handover: the pending transfer is read from the ledger; the admin offers it with an expiry and can cancel it; the pending address accepts it
• Vault upgrades (code hash or delay) with their ETA; apply once the ETA is reached and the vault is not paused; wind-down propose and cancel
• Actions the contract permits but that can break the vault need a confirmation before signing: revoking the vault's share-token manager, merging vault roles, handing over admin, applying a code upgrade, proposing a wind-down
• Action checks show as pass or fail; a row reads Ready, Blocked, No change or Unavailable
• renounce_admin is not offered

Acceptance criteria

• Role holders per contract shown; grant and revoke with the resulting holder list
• Admin handover as two steps, with the pending transfer and its expiry shown
• Pending upgrade and wind-down proposals shown with their ETA
• renounce_admin not offered

Test plan

Automated tests

npm run test — 1433 passing.

Manual verification

1. On a local network, open /admin/governance as governance: every role holder per contract, and the grant, revoke, handover, upgrade and wind-down actions.
2. Revoke the share-token Manager from the vault: the action stays blocked until its confirmation is ticked.

Breaking changes

None.

Checklist

• Self-reviewed my own diff
• Tests added or updated
• Docs updated (if applicable)
• No unrelated changes bundled in

Screenshots

None.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
strata-vault-kit-app	Ready	Preview	Oct 14, 2026 1:40pm UTC

[Copilot]

🔵 Needs a closer look

It is a large, security-sensitive surface controlling role grants, admin handover, code upgrades, and wind-downs, with error-code mappings against the OZ access-control crate that cannot be verified in this environment, so final human review is warranted.

0 open findings

What changed in this PR

This PR adds a Governance admin surface to the vault console, implementing issue #197. It lets each contract's admin enumerate role holders, grant/revoke roles, run the two-step admin handover (offer with expiry, cancel, accept), and propose/apply/cancel vault upgrades and wind-downs. Actions that are safe-but-dangerous (revoking the vault's share-token manager, merging vault roles, handing over admin, applying a code upgrade, proposing a wind-down) require an explicit confirmation before signing, and renounce_admin is intentionally not offered. The work spans a new on-chain read (readPendingAdmins), new state/transaction hooks, a new page module with action specs, and a shared refactor of the action-rail field model (adding select/confirm field kinds and replacing the "N unmet" readiness with a "Blocked" status rendered as per-condition pass/fail/pending).

Changes:

• New governance surface end-to-end: readPendingAdmins + pendingAdmins/useGovernanceState/useGovernanceTransactions hooks, the governance.ts spec/metrics module, and the GovernanceSection component wired into AdminPanel.
• useAdminAuthority now enumerates full role-member lists (not just the first holder), tracks share-token manager and per-contract pending admins, and grants the governance surface to the relevant admins and pending admins.
• Shared action-rail refactor: RailField union (ActionField | SelectField | ConfirmField), new condition rendering with accessible pass/fail/pending status, and TransactionModal governance copy + error-code reasons.

File	Description
app-lib/​readContract.ts /​ .test.ts	Adds readPendingAdmins reading temporary PendingAdmin keys + archival settings; parameterizes durability.
app/​src/​hooks/​pendingAdmins.ts	Shared pendingAdminsQuery, governanceReadsKey, and GovernedContract definitions.
app/​src/​hooks/​useGovernanceState.ts /​ .test.ts	Assembles handovers and upgrade/wind-down/pause state for the surface.
app/​src/​hooks/​useGovernanceTransactions.ts	Role/handover/upgrade/wind-down write hooks via the adminTransaction factory with query-invalidation keys.
app/​src/​hooks/​useAdminAuthority.ts /​ .test.ts	Full role-member enumeration, pending-admin surfacing, governance-surface grants.
app/​src/​pages/​governance.ts /​ .test.ts	Action specs, conditions, confirmations, expiry math, and metrics groups.
app/​src/​pages/​actions.ts /​ .test.ts	RailField union, generic Spec/toAction, blocked readiness.
app/​src/​components/​admin/​GovernanceSection.tsx /​ .test.tsx	New surface component: flows, submit dispatch, modal wiring.
app/​src/​components/​admin/​CycleActionRail.tsx /​ .module.css /​ .test.tsx	Select/confirm inputs, accessible condition status rendering.
app/​src/​components/​vault/​TransactionModal.tsx /​ .test.tsx /​ .module.css	Governance copy and contract-error reasons (codes 2002–2203, 6046–6060).
app/​src/​components/​vault/​MetricsStrip.tsx /​ .test.tsx	Optional title for exposing full text behind a shortened value.
app/​src/​pages/​cycle.ts, configuration.ts	Hoist shared DAY constant to cycle.ts.
app/​src/​pages/​AdminPanel.tsx /​ .test.tsx, App.test.tsx, CycleSection.test.tsx, useAdminTransaction.test.ts	Wire holders/governance through the panel and update affected tests.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.