Shield Resolution

SCAFFOLD — NOT DEPLOYED — NOT AUDITED

magma_shield_resolution is a Phase-1 scaffold prepared for review. Its declared program id is an explicit local placeholder (a locally generated keypair, not a deploy authority), it is not deployed to any cluster, and its devnet manifest carries "deployed": false — consumers must skip it. No audit has been completed. This page documents the design and the shipped scaffold logic; it is not a live deployment.

Shield coverage today is opened and resolved through the oracle path built into magma_shield_vault. This program is where Shield resolution is heading — a dedicated surface with a mandatory human gate.

Why Shield gets its own resolution program

Shield adjudicates a high-stakes, subjective question — was a covered protocol actually exploited? — where a wrong EXPLOIT verdict pays claims out of the SAFE pool. That risk profile warrants a dedicated resolution surface rather than folding Shield into the generic engine.

Rather than reinvent the wheel, magma_shield_resolution reuses the same primitives as MAGMA's generic resolution engine but keeps Shield's own lifecycle and custody local, and adds the one thing the generic engine deliberately lacks: a mandatory security-council confirmation gate.

Reused oracle primitives

Primitive	What it does here
N-of-M oracle committee	An authorized signer set (M, up to 5) with a distinct-signer threshold (N). A verdict stands only once N distinct authorized signers attest the same outcome, deduplicated via a signer bitmap. Fails closed until a committee is set.
Evidence attestation	Each attestation carries an `evidence_uri` (off-chain forensic bundle) and a `ruleset_hash` that must equal the resolution's committed rules hash — a verdict can't be produced against rules that were swapped after the fact.
SOL dispute bond + escrow	A dispute is opened by posting a SOL bond into a per-resolution escrow PDA. Bonds are refunded if the dispute prevails and slashed to the security council if the standing verdict holds.
Finalize timelock	A default-accept challenge window (mainnet default 48h): if a standing verdict is not disputed or overridden before the window closes, it can be finalized.

The addition: a mandatory security-council gate

The generic engine is designed to finalize permissionlessly. Shield does not allow that for a claim-paying outcome. Here, an EXPLOIT verdict cannot finalize without an explicit security-council confirmation (council_confirm). The council is a distinct authority from both the admin and the oracle committee (on mainnet, a Squads multisig).

EXPLOIT (pays claims from the SAFE pool) → requires council_confirmed == true before finalize will lock it (can_finalize returns CouncilConfirmationRequired otherwise). There is deliberately no config field or admin path that bypasses this gate.
SAFE and refund outcomes do not need council confirmation — they don't create a claim against the other side's principal.

Lifecycle

 open_resolution        Admin/opener snapshots the committee + timelock for this coverage.
    │                   (Committee/threshold are frozen per-resolution; a later rotation
    ▼                    cannot change a live one.)
 attest(evidence)       Authorized oracle signers attest an outcome + evidence_uri, with a
    │                   ruleset_hash that must match the committed rules. N distinct signers
    │                   on the same outcome cross the threshold.
    │                   (Before the coverage window closes, ONLY an early EXPLOIT is accepted.)
    ▼
 SafeProposed  ──or──  ExploitProposed        Standing verdict; challenge window opens.
    │                        │
    │  (optional) dispute    │  (optional) dispute — post a SOL bond; committee may attest an
    │                        │               overriding outcome, which re-opens a fresh window.
    │                        ▼
    │                 council_confirm          MANDATORY for EXPLOIT. Security council only.
    ▼                        ▼
 finalize ───────────────────────────────────► winning_outcome locked.
    │   Default-accept once the window elapses AND (EXPLOIT ⇒ council confirmed).
    ▼
 vault opens claims          magma_shield_vault consumes winning_outcome and opens the
                             matching SAFE / EXPLOIT / refund claim path.

refund_resolution is a separate admin/committee path for an unresolvable coverage — it routes the vault to its 100%-principal refund flow and voids any standing verdict.

Instructions

Instruction	Caller	Description
`init_config`	Deployer (once)	Sets admin, security council, dispute bond; bakes mainnet-safe defaults (48h timelock, empty committee = fail-closed)
`set_oracle_committee`	Admin	Sets/rotates the authorized signer set (M) and distinct-signer threshold (N); only affects resolutions opened afterward
`update_config`	Admin	Tunes timelock, dispute bond, pause, admin/council — no field resolves a verdict or bypasses the gate
`open_resolution`	Admin/opener	Opens a resolution for a coverage window; snapshots the committee + timelock
`attest`	Oracle signer	Attests an outcome + evidence (`evidence_uri`, `ruleset_hash`); at threshold sets the standing verdict and opens the challenge window
`council_confirm`	Security council	The mandatory gate — required before an EXPLOIT verdict can finalize
`dispute`	Any wallet	Posts a SOL bond to dispute the standing verdict within its window
`finalize`	Any wallet	Default-accept lock after the window elapses (EXPLOIT ⇒ council confirmed)
`refund_resolution`	Admin/oracle	Marks a coverage unresolvable → vault refund path
`settle_dispute_bond`	Any wallet	Refunds a prevailing disputer's bond, or slashes it to the council if the verdict held

Custody boundary

This program holds only dispute bonds. All coverage principal and yield stays in magma_shield_vault, whose settlement math (parimutuel principal + v2 yield shares) is unchanged. On finalization the vault reads this resolution's winning_outcome to open the matching claim path — and for an EXPLOIT verdict it must additionally observe council_confirmed before paying.

The gate is not enforced by the live vault yet

In the currently-deployed system, magma_shield_vault::finalize_resolution is permissionless (anyone may call it once the oracle threshold and 48h timelock are met) and performs no council check — the deployed vault has no security_council field. The scaffold's vault payout-CPI boundary (where the vault would read council_confirmed) is the documented integration point and is intentionally not wired in this scaffold. Until magma_shield_resolution is deployed and the vault reads its verdict, the council gate is a designed-but-not-yet-connected control.

Committee and window parameters

Parameter	Value
Max oracle signers (M)	`MAX_ORACLE_SIGNERS = 5`
Mainnet distinct-signer floor (N)	`MIN_ORACLE_THRESHOLD = 3` (relaxable only behind a documented testnet flag)
Finalize / dispute window	`DEFAULT_FINALIZE_TIMELOCK_SECS = 172_800` (48h); `MIN_FINALIZE_TIMELOCK_SECS = 21_600` (6h floor)
Disputes per resolution	`MAX_DISPUTES = 8` (deeper tiered escalation is a mainnet extension)
Evidence / reason URI	`MAX_URI_LEN = 200` on-chain; the bundle lives off-chain (Arweave/IPFS)

Status and deferred work

Real + host-tested in the scaffold: committee attestation with the distinct-signer threshold, the evidence + ruleset_hash commitment, the one-level SOL dispute bond, the finalize timelock, and the security-council gate (exploit_cannot_finalize_without_council_gate is a host test).
Deferred to mainnet: ed25519 offline attestation, tiered dispute escalation beyond one rung, the magma_shield_vault payout-CPI wiring, and the admin → Squads multisig hand-off.
Not deployed, not audited. The program id is an explicit placeholder; deployment is gated on provisioning a real keypair and completing a security audit.

Why Shield gets its own resolution program​

Reused oracle primitives​

The addition: a mandatory security-council gate​

Lifecycle​

Instructions​

Custody boundary​

Committee and window parameters​

Status and deferred work​

See also​