feat: implement MultiSigAdmin contract for enhanced governance (#128)

Author: thisisouvik

.env.example

@@ -65,6 +65,10 @@ NEXT_PUBLIC_LENDING_CONTRACT_ID=
 NEXT_PUBLIC_DEFAULT_CONTRACT_ID=
 # DAO governance module controlling the platform fee (issue #22).
 NEXT_PUBLIC_GOVERNANCE_CONTRACT_ID=
+# N-of-M multisig gating rare, high-impact admin config changes (issue #73):
+# whitelisting collateral assets, fee tables, linking governance/oracle, and
+# moving insurance-fund balances. See contracts/MULTISIG_ADMIN.md.
+NEXT_PUBLIC_MULTISIG_ADMIN_CONTRACT_ID=
 
 # Soroban event indexer read models
 # Point these at a Mercury, Ensorcel, or custom subgraph/indexer deployment.
@@ -96,7 +100,10 @@ NEXT_PUBLIC_ADMIN_ADDRESS=
 CRON_SECRET=
 
 # Admin Stellar SECRET key (S...) used by the Default-Management cron to sign
-# mark_defaulted / record_default / trigger_insurance_payout on-chain.
+# mark_defaulted / record_default on-chain, and to PROPOSE (not execute)
+# insurance payouts on the MultiSigAdmin contract (issue #73) — this key must
+# itself be a registered multisig signer for that proposal to succeed. A human
+# still has to gather the remaining approvals and call `execute`.
 # SERVER-ONLY — never prefix with NEXT_PUBLIC_ and never commit a real value.
 ADMIN_SECRET_KEY=
 

__tests__/scheduler/default-management.test.ts

@@ -13,6 +13,7 @@ vi.mock("@/lib/stellar/server-contract", () => ({
   u32: (n: number) => ({ u32: n }),
   u64: (n: number) => ({ u64: n }),
   i128: (n: bigint) => ({ i128: n }),
+  tupleEnumToScVal: (variant: string, fields: unknown[]) => ({ variant, fields }),
   xlmToStroops: (xlm: number) => BigInt(Math.round(xlm * 10_000_000)),
 }));
 
@@ -101,7 +102,7 @@ describe("runDefaultManagement", () => {
     const res = await runDefaultManagement();
     expect(res.scanned).toBe(1);
     expect(res.defaulted).toBe(0);
-    expect(res.paidOut).toBe(0);
+    expect(res.payoutsProposed).toBe(0);
     expect(res.outcomes[0].skipped).toContain("grace period");
   });
 
@@ -117,7 +118,7 @@ describe("runDefaultManagement", () => {
     );
     const res = await runDefaultManagement();
     expect(res.defaulted).toBe(1);
-    expect(res.paidOut).toBe(0);
+    expect(res.payoutsProposed).toBe(0);
     expect(res.failed).toBe(0);
     expect(res.outcomes[0].actions).toContain("db:status=defaulted");
   });
@@ -132,13 +133,13 @@ describe("runDefaultManagement", () => {
     );
     const res = await runDefaultManagement();
     expect(res.defaulted).toBe(0);
-    expect(res.paidOut).toBe(0);
+    expect(res.payoutsProposed).toBe(0);
   });
 
   it("reports counts and never throws on a clean run", async () => {
     makeSupabase([], []);
     const res = await runDefaultManagement();
-    expect(res).toMatchObject({ scanned: 0, defaulted: 0, paidOut: 0, failed: 0 });
+    expect(res).toMatchObject({ scanned: 0, defaulted: 0, payoutsProposed: 0, failed: 0 });
     expect(res.ledgerTime).toBe(new Date(NOW * 1000).toISOString());
   });
 });

app/api/cron/default-management/route.ts

@@ -28,7 +28,7 @@ export async function POST(request: NextRequest) {
     console.log(
       `[default-management] Run complete in ${duration}ms: ` +
         `scanned=${result.scanned} defaulted=${result.defaulted} ` +
-        `paidOut=${result.paidOut} failed=${result.failed}`
+        `payoutsProposed=${result.payoutsProposed} failed=${result.failed}`
     );
     return NextResponse.json({ ok: true, ...result, duration });
   } catch (err) {

contracts/Cargo.lock

@@ -5,6 +5,7 @@ members = [
     "lending",
     "default_management",
     "governance",
+    "multisig_admin",
 ]
 resolver = "2"
 

contracts/Cargo.toml

@@ -0,0 +1,106 @@
+# Multi-Sig Administration Control
+
+> Implements issue **#73 — [Smart Contracts] Implement Multi-Sig administration control for platform upgrades**
+
+Rare, high-impact protocol configuration changes — whitelisting collateral
+assets ("adding pools"), changing fee tables, linking governance/oracle, and
+moving insurance-fund balances ("withdrawing protocol fees") — used to be a
+single admin key away from being changed. They now require **N-of-M approval**
+from authorised admin wallets via a new `MultiSigAdminContract`.
+
+---
+
+## 1. Located administrative operations (Task 1)
+
+| Contract | Function | Why it's in scope |
+|---|---|---|
+| Lending | `whitelist_asset` | "Adding pools" — this codebase's collateral-asset whitelist |
+| Lending | `set_flash_loan_fee_bps` | "Setting interest rate tables" |
+| Lending | `set_governance` | Linking the DAO — rare, high-impact config |
+| Reputation | `set_oracle` | Authorising who can write credit-score data |
+| Default Mgmt | `add_to_insurance` / `trigger_insurance_payout` | "Withdrawing protocol fees" — literal fund movement |
+
+**Deliberately NOT gated:** `activate_loan`, `record_payment`, `mark_defaulted`,
+`confirm_disbursement`, `record_default`, `add_reputation_event`,
+`freeze_account`/`unfreeze_account`. These are high-frequency, backend-automated
+loan-lifecycle operations (issue #23's cron, #72's liquidation keeper) — gating
+them behind async multi-party approval would break automation entirely, and
+they aren't the kind of operation the issue's examples point at.
+
+## 2. Multi-sig approval before configuration shifts (Task 2)
+
+New [`contracts/multisig_admin`](contracts/multisig_admin/src/lib.rs) contract:
+
+```
+propose(signer, action) -> id     — any signer opens a proposal (counts as their own approval)
+approve(signer, id)               — a DISTINCT signer approves, in a SEPARATE transaction
+revoke_approval(signer, id)       — withdraw an approval before execution
+cancel(proposer, id)              — proposer withdraws their own proposal
+execute(id)                       — permissionless once approvals >= threshold
+```
+
+`AdminAction` is a closed, typed enum (not a generic "any call") — every
+protected operation is explicit and independently reviewable:
+
+```rust
+pub enum AdminAction {
+    WhitelistAsset(Address, Address),               // target, asset
+    SetFlashLoanFeeBps(Address, u32),                // target, new_fee_bps
+    SetGovernance(Address, Address),                 // target, governance
+    SetOracle(Address, Address),                     // target, oracle
+    AddToInsurance(Address, i128),                   // target, amount
+    TriggerInsurancePayout(Address, u32, Address, i128), // target, loan_id, lender, amount
+    AddSigner(Address), RemoveSigner(Address), SetThreshold(u32), // self-governance
+}
+```
+
+`execute` cross-calls the target contract (`whitelist_asset`, etc.) with the
+MultiSigAdmin contract's own address as caller — the same pattern already used
+by the Governance contract (issue #22) to call `set_platform_fee_bps`.
+
+**The bypass is genuinely closed, not just supplemented.** Each target contract
+gains a one-time `set_multisig_admin(admin, multisig)` bootstrap. Once called:
+- The gated functions check `caller == multisig` — **not** `caller == admin`.
+- `set_multisig_admin` panics if called again — the original admin can never
+  quietly repoint it at a different multisig they solely control.
+- The only way forward is the multisig's own signer governance
+  (`AddSigner`/`RemoveSigner`/`SetThreshold`, themselves propose→approve→execute).
+
+## 3. Integration tests (Task 3)
+
+[`contracts/multisig_admin/src/test.rs`](contracts/multisig_admin/src/test.rs) —
+**27 tests**, using the *real* Lending, Default-Management, and Reputation
+contracts (dev-dependencies), not mocks:
+
+- **The core sequence**: distinct wallets Alice → propose, Bob → approve (separate
+  transactions) → anyone executes → asset whitelisted on-chain.
+- **The security property this issue is about**: even the *original* admin can
+  no longer call `whitelist_asset` directly once multisig is linked, and can
+  never re-link a different multisig.
+- All six protected actions exercised end-to-end (fee change, governance link,
+  oracle link, insurance fund add + payout).
+- Approval bookkeeping: non-signers rejected, double-approval rejected, revoke,
+  cancel (proposer-only), no double-execute.
+- Signer self-governance: add/remove signer, threshold change, removing a
+  signer below the threshold is rejected, and a *raised* threshold correctly
+  requires more approvals for subsequent proposals.
+
+```bash
+cd contracts && cargo test -p multisig-admin
+```
+
+## 4. Automation impact
+
+`trigger_insurance_payout` is now multisig-gated, so the default-management
+cron (issue #23) can no longer execute payouts unattended — it now
+**proposes** the payout (its key must be a registered signer) and a human
+completes the remaining approvals + `execute`. See
+[`lib/scheduler/default-management.ts`](lib/scheduler/default-management.ts).
+
+## 5. Verification
+
+Full workspace: **89/89 tests passing** (13+7+12+30+27, unchanged pre-existing
+suites + 27 new). Clippy clean (`-D warnings`). Both `wasm32-unknown-unknown`
+(CI) and `wasm32v1-none` (deploy) release builds succeed for all 6 contracts.
+Frontend: `tsc --noEmit`, ESLint, and the full vitest suite (80 tests) all pass
+after the TS client + cron updates.

contracts/MULTISIG_ADMIN.md

@@ -81,6 +81,9 @@ pub enum DataKey {
     Oracle,
     /// Stores the latest OracleCreditData for a borrower
     OracleData(Address),
+    /// Address of the MultiSigAdmin contract — the ONLY caller authorised to
+    /// register the Credit Oracle (`set_oracle`).
+    MultiSigAdmin,
 }
 
 // ─── Oracle constants ───────────────────────────────────────────────────────────
@@ -186,13 +189,34 @@ impl BorrowerReputationContract {
         Self::tier_interest_rate(&profile.reputation_tier)
     }
 
-    // ── Decentralized Credit Oracle ────────────────────────────────────────────
-
-    /// Register / rotate the authorized Credit Oracle address (admin only).
-    /// Only this address may call `submit_credit_score`.
-    pub fn set_oracle(env: Env, admin: Address, oracle: Address) {
+    /// One-time bootstrap linking the MultiSigAdmin contract (admin only).
+    /// Once set, `set_oracle` can ONLY be called by this address — a
+    /// compromised single admin key can no longer redirect who is trusted to
+    /// write credit-score data.
+    pub fn set_multisig_admin(env: Env, admin: Address, multisig: Address) {
         admin.require_auth();
         Self::assert_admin(&env, &admin);
+        if env.storage().instance().has(&DataKey::MultiSigAdmin) {
+            panic!("Multisig admin already configured");
+        }
+        env.storage().instance().set(&DataKey::MultiSigAdmin, &multisig);
+    }
+
+    pub fn get_multisig_admin(env: Env) -> Address {
+        env.storage()
+            .instance()
+            .get(&DataKey::MultiSigAdmin)
+            .expect("Multisig admin not configured")
+    }
+
+    // ── Decentralized Credit Oracle ────────────────────────────────────────────
+
+    /// Register / rotate the authorized Credit Oracle address. Multisig-gated
+    /// — see `set_multisig_admin`. Only this oracle address may call
+    /// `submit_credit_score`.
+    pub fn set_oracle(env: Env, caller: Address, oracle: Address) {
+        caller.require_auth();
+        Self::assert_multisig_admin(&env, &caller);
         env.storage().instance().set(&DataKey::Oracle, &oracle);
         env.events()
             .publish((symbol_short!("oracle"), symbol_short!("set")), oracle);
@@ -481,6 +505,17 @@ impl BorrowerReputationContract {
             panic!("Unauthorised: caller is not admin");
         }
     }
+
+    fn assert_multisig_admin(env: &Env, caller: &Address) {
+        let multisig: Address = env
+            .storage()
+            .instance()
+            .get(&DataKey::MultiSigAdmin)
+            .expect("Multisig admin not configured");
+        if *caller != multisig {
+            panic!("Unauthorised: caller is not the multisig admin");
+        }
+    }
 }
 
 #[cfg(test)]

contracts/borrower_reputation/src/lib.rs

@@ -145,6 +145,10 @@ fn setup_with_oracle() -> (Env, Address, Address, Address, Address) {
     let borrower = Address::generate(&env);
 
     client.initialize(&admin);
+    // `set_oracle` is multisig-gated (see the `multisig_admin` crate); `admin`
+    // stands in as its own "multisig" here since this suite is testing oracle
+    // ingestion, not the multisig approval flow itself.
+    client.set_multisig_admin(&admin, &admin);
     client.set_oracle(&admin, &oracle);
     client.init_borrower(&borrower);