Shield Technical Specification

This page is the technical reference for the on-chain magma_shield_vault program and the backend that drives it.

Field	Value
Program	magma_shield_vault v0.1.0
Network	Solana devnet
Program ID	4ri6AGT37GrL6mzuFdeVc6Wa2H7Q7srnCsQjkGj4v7my
Anchor version	0.32.1
Backing asset	SOL (native lamports)

Shield v2 — principal-at-risk (RISK family), yield solvent by construction

Shield is a RISK-family product: each coverage market is a parimutuel wager where the losing side (SAFE or EXPLOIT) forfeits its principal to the winner. Principal is not protected. What Shield v2 changes is the yield leg — it is now solvent by construction via on-chain, ERC-4626-style share accounting per side (the receipt-token pricePerShare pattern from YBNCM), so the vault can never pay out yield it did not actually earn. The share math and the keeper harvest are built and host-tested; the vault occupies a live devnet program ID, but the deployed bytecode is not version-stamped, so treat v2 as built, not asserted live. Oracle threshold, Arcium encryption, and admin authority remain relaxed for testing — see Devnet parameters.

Oracle & resolution

Shield coverage is resolved by an N-of-M oracle committee: a verdict stands only once a distinct-signer threshold (N) of authorized oracle signers (M, up to 5) attest the same outcome — SAFE or EXPLOIT. The mainnet target is a ≥3-of-N distinct-signer floor; testnet runs a single signer. Multiple independent data sources — on-chain price/event feeds, decentralized oracle networks, and evidence review — inform each signer's verdict, so no single source resolves a market.

Shield also gains a dedicated forensic resolution surface, magma_shield_resolution, which reuses these committee primitives and adds a mandatory security-council confirmation gate: a claim-paying EXPLOIT verdict cannot finalize without an explicit council_confirm. That program is a scaffold — designed and host-tested, not deployed. See Shield — Resolution for the full lifecycle.

The Arcium TEE processes oracle inputs for FALSE-resolution assessment without exposing individual source data — see Arcium Confidential Computing.

Dispute window

A 48-hour challenge period (RESOLUTION_TIMELOCK_SECS = 172_800) follows each resolution. During this window any party may submit counter-evidence, disputes are reviewed, and payouts are held pending resolution.

On-chain program: magma_shield_vault

Program instructions

Instruction	Caller	Description
initialize_program	Admin (once)	Sets oracle signers, treasury, pool programs, and the harvest authority
set_max_self_hedge_bps	Admin	Sets the Partnership self-hedge cap (bps ≤ 5_000); freed share flows to EXPLOIT winners
open_coverage	Admin	Opens a coverage period for a protocol
back_shield	Any wallet	Commits SOL to the SAFE or EXPLOIT pool; mints yield shares at the side's price-per-share
harvest_yield	Harvest keeper	v2 — books only real surplus SOL that arrived in a side vault; refuses to book a loss
submit_oracle_resolution	Oracle keypair	Votes SAFE or EXPLOIT after period_end
finalize_resolution	Permissionless	Executes splits after the timelock expires
claim_safe_winner	SAFE backer	Principal + share-derived yield (own vault) + pro-rata EXPLOIT principal
claim_exploit_winner	EXPLOIT backer	Principal + share-derived yield (own vault) + pro-rata SAFE principal
claim_loser_yield	Losing backer	Share-derived yield from its own vault only — principal forfeited
refund_all	Oracle / Admin	Triggers a full refund if unresolvable
claim_refund	Any backer	Claims 100% principal after refund_all
pause_program	Oracle / Admin	Emergency circuit breaker

PDA architecture

["shield_program_state"]                          → ShieldProgramState (global config)
["shield_state",   protocol_id]                   → ProtocolCoverage    (per protocol)
["shield_safe",    protocol_id]                   → safe_vault PDA      (SAFE pool SOL)
["shield_exploit", protocol_id]                   → exploit_vault PDA   (EXPLOIT pool SOL)
["shield_back",    protocol_id, backer, side_byte] → ShieldBackingRecord
["shield_oracle",  protocol_id, oracle_pubkey]    → ShieldOracleSubmission
["shield_cpi_auth"]                               → vault CPI authority (signs pool CPIs)

The ShieldOracleSubmission PDA is created with Anchor's init constraint (not init_if_needed), which enforces exactly one vote per oracle per protocol at the account level — no application-level deduplication is required.

BPS split constants

// EXPLOIT resolution — Partnership Shield
EXPLOIT_PARTNER_PROTOCOL_BPS = 5_000  // 50% → protocol wallet
EXPLOIT_PARTNER_BACKERS_BPS  = 3_500  // 35% → exploit backers pro-rata
EXPLOIT_PARTNER_CORE_BPS     = 1_200  // 12% → MAGMA Core treasury
EXPLOIT_PARTNER_SEAM_BPS     =   300  //  3% → Seam pool (CPI)

// EXPLOIT resolution — Community Shield
EXPLOIT_COMMUNITY_BACKERS_BPS = 5_800 // 58% → exploit backers pro-rata
EXPLOIT_COMMUNITY_CORE_BPS    = 3_900 // 39% → MAGMA Core treasury
EXPLOIT_COMMUNITY_SEAM_BPS    =   300 //  3% → Seam pool (CPI)

// SAFE resolution
// 100% of EXPLOIT pool → SAFE backers pro-rata (no fee on a SAFE outcome)

Discovery Multiplier

DISCOVERY_WINDOW_PCT     = 20      // first 20% of coverage window
DISCOVERY_MULTIPLIER_BPS = 20_000  // 2.0x stored in ShieldBackingRecord
DEFAULT_MULTIPLIER_BPS   = 10_000  // 1.0x for later backers

The multiplier is stored on-chain in ShieldBackingRecord.multiplier_bps and used by the backend for conviction score calculation. It does not affect direct SOL payout — payout is proportional to the raw amount_lamports.

Yield accounting (v2 — on-chain shares)

Shield v2 removes the trusted yield_lamports parameter entirely. The yield leg is now solvent by construction, using ERC-4626-style share accounting per side with lamports as the reserve asset (the pure math is host-tested in the program's share_math module):

1. Deposit mints shares. back_shield mints yield shares in the backer's side pool at the side's current price-per-share (convert_to_shares). At inception a side is at parity; once real yield is booked, a later depositor receives fewer shares for the same SOL — correctly missing yield that accrued before they arrived. An OpenZeppelin-style virtual offset (VIRTUAL_SHARES = 1_000, VIRTUAL_ASSETS = 1) mitigates first-depositor inflation.
2. Harvest books only real SOL. A trustless keeper instruction (harvest_yield, gated to the configured harvest authority) reads the side vault's actual lamport balance and books only the surplus over booked assets. It cannot be fed a fabricated number and refuses to book a loss (require!(backing ≥ old_assets, HarvestLoss)).
3. Claims derive yield from shares, capped at what was realized. At claim, a position's yield is convert_to_assets(shares) − principal, then capped so a side can never pay more yield than its realized yield (total_assets − total_principal). All conversions floor in the vault's favour — a hard invariant proven in host-model tests, not merely true on average.
4. Yield is always same-side; only principal crosses vaults. Winners and losers draw yield from their own side vault; the parimutuel principal redistribution (loser's principal → winner) is unchanged.

New per-side state on ProtocolCoverage: {safe,exploit}_total_assets (price numerator), {safe,exploit}_shares_total (denominator), and {safe,exploit}_yield_paid (the realized-yield cap), plus ShieldBackingRecord.shares and ShieldProgramState.harvest_authority. See Yield Routing for the deposit/withdraw mechanics.

External CPIs

CPI target	When
magma_seam_pool::receive_royalty_deposit	EXPLOIT finalization (3% fee)
magma_core_pool::receive_deposit	EXPLOIT finalization (12% or 39%)

ARCIUM_STUB locations

All // ARCIUM_STUB comments in back_shield and the claim_* instructions mark where Arcium MPC encryption/decryption integrates on mainnet. On devnet, amount_lamports is stored in plaintext.

Coverage period management

Coverage period:  30 / 60 / 90 days
Fee collection:   T+0 (period start)
Yield accrual:    continuous
Resolution:       oracle consensus at T+period
Dispute window:   48h post-resolution (mainnet)
Payout:           T + dispute_window if uncontested

Devnet parameters

Some values are relaxed for devnet testing (notably the oracle threshold); the resolution and admin timelocks are enforced on testnet and mainnet alike.

ORACLE_THRESHOLD           = 1                 // single oracle (mainnet: >= 3)
RESOLUTION_TIMELOCK_SECS   = 172_800           // 48h — enforced on testnet AND mainnet
ADMIN_ACTION_TIMELOCK_SECS = 259_200           // 72h — enforced on testnet AND mainnet
MIN_BACKING_LAMPORTS       = 100_000_000       // 0.1 SOL
MAX_BACKING_LAMPORTS       = 100_000_000_000   // 100 SOL

Security constraints

• No durable nonce transactions are permitted in Shield operations.
• All admin signing is performed via AWS KMS — no raw private keys.
• Treasury operations require a Squads 2-of-3 multisig.
• SIRN registration is active for all Partnership Shield protocols.

Data model (backend)

Table	Purpose
shield_positions	Per-backer position: wallet, protocol, side, amount_sol, arcium_enabled, window, yield_earned, status
shield_probe_log	Records gate-access attempts for security monitoring
shield_terms_acknowledgements	Timestamped wallet acknowledgements of Shield Terms — required before any backing

Backend routes

POST /v1/shield/back              — submit a backing position
GET  /v1/shield/protocols         — list active Shield protocols
GET  /v1/shield/protocols/:id     — protocol detail + pool state
POST /v1/shield/terms-ack         — record terms acknowledgement
POST /v1/shield/partner-apply     — partnership application
GET  /v1/shield/probe-log         — gate access log (admin)

The REST base is https://api.magmaprotocol.xyz. See the API Reference for request/response schemas.