Migrate treasury authority to multi-sig (Squads / Realms) pre-mainnet

[alrimarleskovar]

Problem

Today, the config.treasury authority and the program upgrade authority on all 4 deployed devnet programs are pinned to a single keypair (64XM177Vm6zirzQnjU1juQ9TLqDsZVsCcZzfgEgVCffm). For mainnet with real USDC, this is a single point of compromise.

What this blocks

MAINNET_READINESS.md §3.6 (upgrade authority) + §3.7 (treasury authority) — both marked 🔵⛔ hard mainnet blockers.

Proposed solution

Pre-mainnet:

1. Select multi-sig platform — Squads Protocol (Solana-native, well-audited) is the primary candidate; Realms / Mean Finance are alternatives
2. Configure a 3-of-5 multi-sig for treasury authority + upgrade authority — signers split across:
   • 1 founder
   • 1 technical lead
   • 1 security advisor / external
   • 2 board members or backup
3. Migrate config.treasury — propose new treasury via existing 7-day timelock pattern from PR fix(roundfi-core): treasury rotation hardening — timelock + one-way lock (Option C) #122; commit via commit_new_treasury to the multi-sig PDA
4. Migrate upgrade authority — solana program set-upgrade-authority from current single key to the multi-sig PDA on all 4 deployed programs
5. Refresh OtterSec verify-build attestation PDAs — same signer rotation
6. Operational runbook — docs/operations/multisig-recovery.md (key-loss procedure, signer-rotation procedure, emergency-pause-via-multisig procedure)

Acceptance criteria

• Squads/Realms multi-sig deployed on devnet first (smoke test)
• config.treasury migrated via timelock → multi-sig PDA on devnet
• Upgrade authority rotated on all 4 programs (devnet)
• Repeat for mainnet on launch day
• OtterSec attestation PDAs refreshed
• docs/operations/multisig-recovery.md shipped
• MAINNET_READINESS.md §3.6/§3.7 moved from 🔵⛔ to ✅

Estimated scope

Medium — multi-sig setup is well-trodden but the authority rotation is one-way; needs careful staging on devnet first.

References

• MAINNET_READINESS.md §3.6 + §3.7
• docs/operations/key-rotation.md
• PR fix(roundfi-core): treasury rotation hardening — timelock + one-way lock (Option C) #122 — treasury timelock pattern (reused here)
• Squads Protocol

[alrimarleskovar]

Status update — Squads rotation rehearsal executed ✅

The first acceptance criterion ("Squads/Realms multi-sig deployed on devnet first (smoke test)") was achieved 2026-05-16 via PR #369.

Rehearsal log artifact: docs/operations/rehearsal-logs/2026-05-16-squads-rotation-rehearsal.md

What was validated end-to-end on devnet

4 phases on-chain (against a parallel test deploy at 6WuSo1ut...7Rpn, canonical 8LVrgxKw...QQjw + Pool 1/2/3 untouched):

Phase	Instruction	Tx
A	propose_new_authority	4pfiQLAEzpoz...
B	cancel_new_authority (kill-switch)	s1NDWguUm...
C-a	propose_new_authority (re-propose)	2dhWa68945...
C-b	commit_new_authority (post-timelock)	2xeWvuDTa4...

Final on-chain state: live=6Y6BL1mq... (rotated), pending=11111... (cleared), eta=0 (clean).

Audit-worthy findings surfaced during rehearsal execution

1. Canonical devnet ProtocolConfig (3c9MmoM8...) is pre-PR feat(roundfi-core): timelocked protocol authority rotation (Squads #3.6) #323 — 317 bytes vs current code expects 381 (delta = pending_authority Pubkey + pending_authority_eta i64). A realloc migration ix is required before Squads rotation can be exercised against the original ProtocolConfig. Tracked as a gap for the next devnet refresh sprint. This is the main blocker for closing this issue — the test on the parallel deploy validated the ix logic, but the canonical config needs migration before the actual mainnet ceremony rotation flow.
2. Script offset bug in scripts/devnet/squads-rehearsal-{verify,commit-authority}.ts — fixed in PR chore(operations): squads rotation rehearsal executed 2026-05-16 + offset fix #369 (offset 311→313, 343→345; root cause: struct's pub const SIZE comment listed pending_authority BEFORE lp_share_bps but Borsh serializes in declaration order).

What's NOT yet validated by this rehearsal

• Real Squads v4 multisig vault PDA derivation + member signing flow (the rehearsal used a single throwaway pubkey as proxy for the vault). This is exercised separately on the mainnet ceremony day via the Squads web UI per docs/operations/squads-multisig-procedure.md §3-§5.
• Mainnet authority rotation against canonical (blocked on the realloc migration above).

Remaining acceptance criteria

• Squads/Realms multi-sig deployed on devnet first (smoke test) — PR chore(operations): squads rotation rehearsal executed 2026-05-16 + offset fix #369
• config.treasury migrated via timelock → multi-sig PDA on devnet (separate ix: propose_new_treasury / commit_new_treasury, same pattern)
• Upgrade authority rotated on all 4 programs (devnet)
• Repeat for mainnet on launch day
• OtterSec attestation PDAs refreshed (next devnet refresh)
• docs/operations/multisig-recovery.md shipped
• MAINNET_READINESS.md §3.6/§3.7 moved from 🔵⛔ to ✅

Related PRs from today: #367 (Squads rehearsal quickstart + pnpm aliases), #369 (execution log + offset fix).

---

Generated by Claude Code

[alrimarleskovar]

Acceptance item shipped — docs/operations/multisig-recovery.md

One of the open checkboxes (docs/operations/multisig-recovery.md) is now delivered on branch claude/implement-roundfi-desktop-SRV6l (commit 6f3a9c2).

The existing docs covered setup/ceremony thoroughly (squads-multisig-procedure.md, squads-mainnet-ceremony-checklist.md, key-rotation.md, emergency-response.md) but there was no consolidated recovery runbook. This fills that gap without duplicating them. Three procedures:

• R1 — signer key loss / compromise. Triage (lost vs compromised), the "are you still ≥ threshold?" gate, member remove+replace via Squads config tx, and the key property that a single-member swap does NOT require an on-chain authority rotation (vault PDA is unchanged). Includes the terminal "below threshold (lost 3 of 5)" case — no on-chain recovery, relaunch territory.
• R2 — planned signer rotation. Departure / custody upgrade; mechanically R1 Step 2 but unhurried + pre-announced. Notes the departing member's approval is not required.
• R3 — emergency pause via the multisig. The multisig-execution detail behind emergency-response.md's decision tree, the 3-of-5 latency tax, and both sides of the break-glass sub-multisig open decision (the one already flagged in this issue / emergency-response.md §pause-latency).

What this does NOT close

This is the docs checkbox only. The issue stays open — the remaining criteria are on-chain ceremony / operator work that can't be exercised from CI:

• config.treasury migrated via timelock → multi-sig PDA on devnet
• Upgrade authority rotated on all 4 programs (devnet)
• Repeat for mainnet on launch day
• OtterSec attestation PDAs refreshed
• docs/operations/multisig-recovery.md shipped — this commit
• MAINNET_READINESS.md §3.6/§3.7 moved from 🔵⛔ to ✅

One open design decision the recovery doc documents both sides of but does not decide: break-glass pause sub-multisig vs full 3-of-5 pause latency. Worth resolving before the ceremony.

---

Generated by Claude Code

---

Generated by Claude Code