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)

Devnet beta

The program is live on devnet. Several parameters (oracle threshold, timelocks, Arcium encryption, admin authority) are relaxed for testing and must be tightened before mainnet — see Devnet parameters.

Oracle architecture

Shield resolution uses a 4-source consensus mechanism. Mainnet requires 3-of-4 agreement.

Source	Type	Weight
Pyth Network	On-chain price / event feed	1
Switchboard	Decentralized oracle network	1
RedStone	Pull-based oracle	1
AI Oracle (Grok + Tavily)	Web intelligence + on-chain analysis	1

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 follows each resolution on mainnet. During this window any party may submit counter-evidence, governance reviews disputes, 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
open_coverage	Admin	Opens a coverage period for a protocol
back_shield	Any wallet	Commits SOL to the SAFE or EXPLOIT pool
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	Claims principal + yield + EXPLOIT pool share
claim_exploit_winner	EXPLOIT backer	Claims principal + yield + SAFE pool share
claim_loser_yield	Losing backer	Claims yield 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 pattern

Yield is tracked off-chain by the backend (the same pattern as magma_backing_vault):

• The backend monitors DeFi protocol positions (Kamino / Marinade / Save).
• It computes yield_lamports = current_value − principal_deposited.
• It passes yield_lamports as a parameter to claim_safe_winner / claim_exploit_winner / claim_loser_yield.
• On devnet, yield_lamports = 0 (no actual DeFi deposit).
• On mainnet, this is real yield from DeFi protocol APIs.

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

These values are relaxed for devnet testing and must be changed for mainnet.

ORACLE_THRESHOLD           = 1                 // single oracle (mainnet: >= 3)
RESOLUTION_TIMELOCK_SECS   = 0                 // instant   (mainnet: 172_800 = 48h)
ADMIN_ACTION_TIMELOCK_SECS = 0                 // instant   (mainnet: 259_200 = 72h)
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.