How the vaultactually works.

shinycapital is a gacha protocol for tokenized graded Pokémon cards on Solana. Each physical slab lives in insured storage and is represented on-chain by an NFT that is a 1:1 custodial claim on that exact card. Everything else — odds, price, randomness, payouts — is computed by the program, in public.

There are two ways to play:

• Depositors place a card NFT in the pool and back it with their own SOL. Backing is the economic engine: it sets the card's odds, feeds the pool price, and earns a share of every draw fee while the card sits in the vault.
• Participants pay one pool-wide price for a draw. A verifiable random number picks a card, weighted by backing. The winner then keeps the card — or takes an instant 85% buyback in SOL.

The loop closes on itself: draw margins fund depositor rewards, backing funds buybacks, and the price is derived from the backings — there is no oracle for card prices, no admin-set rarity table, and no external yield source anywhere in the system.

A card enters the system through a whitelisted collection: the pool authority registers the custodian's NFT collection (add_collection), and only verified members of an enabled collection can be deposited. Each NFT is minted 1:1 against a physical, graded slab held in insured storage.

Depositing (deposit_position) escrows the NFT in a program-owned account and moves your SOL backing into a dedicated per-position vault. The deposit is bounded on both sides:

• backing must be at least the pool's min_backing (launch: 0.1 ),
• and at most max_backing_ratio × the pool's harmonic mean (launch: 50×), so one whale card cannot freeze the pool's pricing.

As long as the card has not been drawn, the depositor can exit at any time: withdraw_position returns the NFT, the full backing and every accrued fee in one transaction, then closes the position. There is no lock-up and no exit penalty.

Redemption of the physical card is the NFT's whole purpose: burning the claim with the custodian triggers shipment of the slab itself.

Every active position carries a selection weight equal to the inverse of its backing. Cheaply-backed cards are common pulls; heavily-backed grails are rare. Rarity is not declared by an admin — it emerges from how much SOL depositors are willing to put behind each card.

Worked example — a pool with three cards backed at 10, 2 and 1 :

card	backing	weight (∝ 1/b)	odds
Grail	10	0.10	6.25%
Mid	2	0.50	31.25%
Common	1	1.00	62.50%

Weights live in a Fenwick (binary indexed) tree, so selecting a winner and updating a position are both O(log n) — at the pool's 512-slot capacity, a draw descends at most 9 nodes.

Every draw costs the same, pool-wide price: the harmonic mean of all active backings, plus a flat protocol margin. The harmonic mean — not the average — is the right statistic here: it is dominated by the cheap, high-odds cards you are most likely to pull, so the price tracks what a draw is actually worth.

Two implementation details matter and are mirrored bit-for-bit in the UI (lib/protocol/math.ts ↔ crates/gacha-math):

• the mean is computed in 2⁹⁶ fixed-point and rounded up (the participant pays it — the pool is never underpaid by a rounding),
• every amount is an integer number of lamports end to end; no float ever touches a balance. The price shown before you sign is the price the program charges, to the lamport.

request_draw also takes a max_price cap chosen by the participant: if deposits move the mean between signing and execution, a draw above your cap simply fails instead of overcharging you.

1. 1

   Request

   The participant pays the pool price into escrow and commits a Switchboard On-Demand randomness account in the same transaction. The request joins a strict FIFO queue — draws settle in the exact order they were paid, no exceptions, no reordering.
2. 2

   Reveal

   One slot later, the Switchboard oracle reveals the random value. The seed is bound to the commit slot, so neither the participant, the crank, nor the pool authority can grind or choose the outcome.
3. 3

   Fulfill

   fulfill_draw verifies the randomness account on-chain, walks the Fenwick tree (≤ 9 steps) to the weighted winner, removes the position from the active set, and splits the margin into the reward streams. The card is now the participant's to settle.
4. 4

   Timeout safety

   If the reveal never lands within draw_timeout_slots (launch: 150 slots ≈ 60 s), the draw can be cancelled by anyone — cancel_draw is permissionless and refunds the full price to the recorded participant. Funds cannot get stuck behind a dead oracle, and a late reveal can never be accepted.

The winner has a decision window of settle_timeout_slots (launch: 900 slots ≈ 6 minutes) and exactly two mutually exclusive outcomes — the program is built so no path can ever yield both:

If the window closes with no choice, settle_default (permissionless) applies the buyback: the card goes home to its depositor and the absent winner is still paid their 85% — the conservative outcome for both sides. The 1% keep commission is charged on the depositor's gross payout and is the treasury's only cut outside the margin; fees and crown accruals ride on top, commission-free. Every branch conserves lamports exactly — the settlement algebra in settle.rs sums to zero by construction.

Every draw's flat margin (launch: 0.05 ) is the only source of depositor rewards. It splits three ways, on-chain, at fulfillment:

The equal stream uses a classic reward-per-share accumulator (acc_fee_per_position), so claiming (claim_fees) costs O(1) whenever you like — rewards accrue whether you touch them or not, and are paid out automatically when a position is drawn or withdrawn.

The crown belongs to whoever backs the most: any position with a strictly larger backing can seize it at any time with claim_throne. If the crown is vacant — or the crowned card is itself the one being drawn — its 10% folds into the equal split rather than stranding.

The pool also tracks Σ √backing on-chain, the accounting basis for a future native-token stream weighted by the square root of backing — favouring breadth over single whales. That stream is not live: no token exists today, and nothing here is a commitment that one will.

The pool authority can tune parameters — but only inside hard bounds compiled into the program, and only through a timelock. Every change is proposed (propose_config_update), waits out the pool's timelock (launch: ≈ 36 minutes, the protocol minimum), then is applied in a second transaction — never mid-draw, and never faster than a settlement window, so the rules cannot change under a participant who has already paid.

Even a fully compromised authority key cannot set a 100% commission, a dust backing floor or an instant rule change — the bounds are not config, they are code. Authority transfer itself is two-step (transfer_authority → accept_authority), and the pool can be paused, which blocks new deposits and draws but never blocks withdrawals or settlement.

• Verifiable randomness. The program checks the Switchboard account's discriminator, seed slot and reveal slot on-chain; a stale or foreign randomness account is rejected. Late reveals are refused — past the deadline, only cancellation remains.
• Exact escrow accounting. Every lamport a participant pays is tracked in escrowed_lamports until settled or refunded; settlement algebra conserves the total by construction.
• Permissionless liveness. Fulfilling, cancelling a timed-out draw and applying the default settlement are all permissionless cranks — no single operator can hold funds hostage by going offline.
• No custodial signatures. The dApp holds no keys and signs nothing itself; every transaction is built locally and approved in your wallet.
• Bounded blast radius. Hard parameter bounds, a settlement-aware timelock, a pause switch that cannot trap funds, and a 512-position capacity per pool.