> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fade.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Instructions reference

> Every instruction: who may call it, its accounts, its arguments and what it checks.

Account flags: **S** signer, **W** writable. Accounts marked *derived* are PDAs the generated client fills in for you. Every instruction also takes `event_authority` and `program` (Anchor's self-CPI event accounts); they are omitted from the tables. Amounts are in base units: USDC 6 decimals, shares 9.

## Wagers

### `open_wager`

Opens a wager. Signed by the app and the stake owner.

| Arg | Type | Meaning |
| - | - | - |
| `stake` | `u64` | USDC base units |
| `paytable` | `Vec<Bucket { p: u64, m: u64 }>` | 1 to 32 buckets; `p` in billionths summing to 1e9, `m` in bps |
| `integrator_fee_bps` | `u64` | The app's fee, 0 to 500 |
| `nonce` | `u64` | Must equal the app record's `next_nonce` |

| Account | Flags | Notes |
| - | - | - |
| `integrator_authority` | S | The app's identity: a key, or a program's `["fade-integrator"]` PDA |
| `payer` | S W | Pays rent, oracle prefund and crank fee; receives refunds at close |
| `stake_owner` | S | Owner of `stake_source` |
| `stake_source` | W | Legacy SPL USDC account owned by `stake_owner` |
| `config` | derived | |
| `pool` | W derived | |
| `integrator` | W derived | `["integrator", integrator_authority]`, created if absent |
| `fee_account` | W | USDC account; stored by the first wager, must match afterwards |
| `protocol_treasury` | W | Must equal `config.protocol_treasury` |
| `vault_usdc` | W derived | Pool USDC |
| `beneficiary` | | USDC account the payout goes to, stored |
| `wager` | W derived | `["wager", integrator, nonce]`, created |
| `vrf_payer` | W derived | `["vrf-payer", wager]`, prefunded |
| `orao_network_state` | derived | ORAO's network state; the fee is read from it |
| `usdc_mint` | | Must equal `config.usdc_mint` |
| `token_program`, `system_program` | | |

**Checks, in order.** No remaining accounts; new wagers not paused; new apps not paused if this creates the record; app not paused; fee account is a USDC account and matches the record; nonce; paytable shape (`BucketCount`, `ProbabilityRange`, `ProbabilitySum`, `MultiplierCeiling`); expected return (`PaytableOverpays`); app fee bound (`IntegratorFeeTooHigh`); edge floor (`EdgeFloor`); drawdown breaker; stake bounds; per-wager cap, app ceiling, utilisation, κ and gross solvency against the pool after this wager. Then it moves the protocol fee, the app fee and the pool credit from the stake, prefunds `vrf_payer` with twice ORAO's fee plus a pending request's rent, moves the crank fee into the wager, updates the books and snapshots everything into the wager. Emits `IntegratorCreated` (first wager) and `WagerOpened`.

### `request_randomness`

Binds the wager to an ORAO request. Anyone, from `open_slot + 2` until `expiry_slot`.

| Account | Flags | Notes |
| - | - | - |
| `caller` | S W | Receives the 50 000-lamport request share |
| `wager` | W derived | Must be `Open` |
| `vrf_payer` | W derived | Pays ORAO |
| `slot_hashes` | | The `SlotHashes` sysvar |
| `orao_network_state` | W derived | |
| `orao_treasury` | W | Must match ORAO's network state |
| `request` | W | ORAO's request PDA for the derived seed |
| `orao_program` | | `VRFzZoJdhFWL8rkvu87LpKM3RbcVezpMEc6X5GVDr7y` |
| `system_program` | | |

**Checks.** Request window (`RequestWindow`); finds `s*`, the first slot in `SlotHashes` after `open_slot` (`EntropyUnavailable` if none); derives `seed = SHA256("FADE/ORAO-SEED/v1" ‖ program ‖ wager ‖ open_slot ‖ s* ‖ h*)`; requires `request` to be ORAO's account for that seed (`WrongRandomnessAccount`) and the treasury to match (`TreasuryMismatch`). A request account someone already created at that address is accepted after owner and type checks. Stores `s*`, `h*`, the seed and the request; status becomes `Requested`. Emits `RandomnessRequested`.

### `settle_wager`

Draws the outcome and pays it. Anyone, once ORAO has fulfilled; no deadline.

| Account | Flags | Notes |
| - | - | - |
| `caller` | S W | Receives the 200 000-lamport settle share |
| `config`, `pool` | derived | `pool` W |
| `integrator` | W | `wager.integrator` |
| `wager` | W | Must be `Requested` |
| `vrf_payer` | W derived | Drained to the payer |
| `randomness` | | `wager.randomness`, fulfilled |
| `beneficiary` | W | `wager.beneficiary` |
| `payout_escrow` | W derived | Used if the beneficiary cannot receive |
| `vault_usdc`, `vault_authority` | derived | |
| `payer` | W | `wager.payer`: receives rent and refunds |
| `usdc_mint`, `token_program`, `system_program` | | |

**Checks.** No remaining accounts; status; the randomness account is ORAO's, bound to this wager, fulfilled, with the stored seed and a non-zero value. The outcome is `SHA256("FADE/OUTCOME/v1" ‖ program ‖ wager ‖ seed ‖ R ‖ i)` read as 128-bit words with rejection sampling, mapped onto the stored paytable's cumulative probabilities. Releases the reservation, pays `stake × m / 10 000` to the beneficiary (or to the escrow, status `PayoutPending`), returns the prefund, pays the settler and closes the wager. Never re-reads live parameters or caps. Emits `WagerSettled`.

### `expire_wager`

Forfeits a wager whose randomness never arrived. Anyone, after `expiry_slot`.

| Account | Flags | Notes |
| - | - | - |
| `caller` | S W | Receives the 200 000-lamport share |
| `pool` | W derived | |
| `integrator` | W | |
| `wager` | W derived | |
| `vrf_payer` | W derived | |
| `randomness` | | The bound request if there is one (must be unfulfilled), any account otherwise |
| `payer` | W | `wager.payer` |
| `system_program` | | |

**Checks.** `NotExpired` before `expiry_slot`; `AlreadyFulfilled` if the randomness has arrived. The pool keeps the pool credit; the reservation is released; SOL returns to the payer. Emits `WagerExpired`.

### `claim_payout`

Delivers a payout parked at settlement. Anyone.

| Account | Flags | Notes |
| - | - | - |
| `caller` | S | |
| `config` | derived | |
| `wager` | W derived | Must be `PayoutPending` |
| `beneficiary` | W | `wager.beneficiary` (`BeneficiaryMismatch` otherwise) |
| `payout_escrow`, `vault_authority` | derived | |
| `payer` | W | `wager.payer`: receives the wager's rent |
| `usdc_mint`, `token_program` | | |

Fails while the beneficiary still cannot receive; retry later. Emits `PayoutClaimed`.

### `set_fee_account`

The only way to move an app's fee destination. Signed by `integrator_authority`.

| Account | Flags | Notes |
| - | - | - |
| `integrator_authority` | S | |
| `config` | derived | |
| `integrator` | W derived | |
| `fee_account` | | Any USDC account |

Emits `FeeAccountChanged`.

## Liquidity

### `request_deposit`

| Arg | Type |
| - | - |
| `amount` | `u64`, USDC base units |

| Account | Flags | Notes |
| - | - | - |
| `owner` | S W | |
| `owner_usdc` | W | Source USDC account |
| `owner_shares` | W derived | Owner's associated share account, created if needed |
| `config`, `queue` | derived | `queue` W |
| `pool` | W, optional | Required when this request opens an epoch (`PoolRequired`) |
| `deposit_queue_usdc`, `share_mint` | derived | |
| `usdc_mint`, `clock`, `instructions` sysvar | | |
| `request` | W derived | `["deposit", joining epoch, owner]` |
| programs | | token, associated token, system |

**Checks.** Allowlist of top-level instructions (`ForbiddenComposition`); deposits not paused; `amount ≥ min_deposit`, and `≥ min_first_deposit` while no share exists. Joins the epoch computed from the queue and the clock (never an argument). Moves the USDC to the deposit queue and the SOL fees into the request and, if below target, the strike fund. Emits `DepositRequested`.

### `request_withdraw`

| Arg | Type |
| - | - |
| `shares` | `u64`, share base units |

Accounts mirror `request_deposit`, with `owner_shares` (W) as the source, `owner_usdc` derived (the owner's associated USDC account) and `share_escrow` instead of the deposit queue. **Checks.** Allowlist; at least one share or the owner's whole balance. Never blocked by a pause. Emits `WithdrawRequested`.

### `strike_epoch`

Prices the live epoch. Anyone.

| Account | Flags |
| - | - |
| `caller` | S W; advances the record's rent if the fund cannot, receives `STRIKE_REWARD` |
| `config`, `queue`, `pool`, `record` (`["epoch", current epoch]`) | derived; `queue`, `pool`, `record` W |
| `deposit_queue_usdc`, `vault_usdc`, `payable_usdc`, `share_mint`, `share_escrow`, `share_claims` | W derived |
| `vault_authority`, `usdc_mint`, `token_program`, `system_program` | |

**Checks.** A live epoch (`NoLiveEpoch`); its close has passed (`EpochNotClosed`); no wager opened before the close is still open (`StrikeNotClean`). Prices on settled assets at the close, mints for deposits, burns for withdrawals (rationed if needed), writes the `EpochRecord`, promotes the next epoch, pays the striker. Emits `EpochStruck`.

### `claim_deposit`

Delivers the shares of a struck deposit request. Anyone; the request's `CLAIM_FEE` pays the caller.

| Account | Flags | Notes |
| - | - | - |
| `caller` | S W | |
| `config` | derived | |
| `request` | W derived | |
| `owner` | W | `request.owner`: receives the request's rent |
| `record` | W, optional | The request's epoch record; absent once the request is parked |
| `owner_shares` | W | Owner's canonical share account |
| `share_claims`, `share_mint`, `vault_authority` | derived | |
| `rent_receiver` | W, optional | The record's `rent_payer`, needed by the claim that closes it |
| `owner_destination` | W, optional | For a parked request only, with the owner's signature |
| `token_program` | | |

Emits `DepositClaimed`, or `ClaimDelivered` for a parked request.

### `claim_withdraw`

Delivers the USDC of a struck withdrawal request, possibly served across several epochs. Anyone; same fee.

| Account | Flags | Notes |
| - | - | - |
| `caller` | S W | |
| `config` | derived | |
| `request` | W derived | |
| `owner` | W | Receives the rent |
| `at_record` | W, optional | The record the chain is read at |
| `entry_record` | W, optional | The request's own record, on its first claim |
| `owner_usdc` | W | Owner's canonical USDC account |
| `payable_usdc`, `vault_authority` | derived | |
| `usdc_mint` | | |
| `rent_receiver`, `entry_rent_receiver` | W, optional | Rent payers of records this claim closes |
| `owner_destination` | W, optional | Parked requests only, owner signs |
| `token_program` | | |

Emits `WithdrawClaimed`, or `ClaimDelivered`.

## Governance

### `initialize`

One-time setup by the program's upgrade authority: creates `Config`, `Pool`, `Queue` and the vault's token accounts, sets the council, guardian, treasury and parameters, and seeds the strike fund. Args: `council: Pubkey`, `guardian: Pubkey`, `params: RiskParams`.

### `set_params`

Council only. Arg: `params: RiskParams`. Applies at once if every change tightens; otherwise queues it behind the longest delay of the fields it loosens. Emits `ParamsChanged`.

### `apply_params`

Anyone, once the pending change is due (`ChangeNotDue` before). Emits `ParamsApplied`.

### `cancel_params`

Council only. Drops the pending change. Emits `ParamsCancelled`.

### `set_pause_flags`

Args: `pause_flags: u8`, `integrator_paused: Option<bool>`. Signed by the guardian or the council. The guardian may only **set** flags; clearing any flag, globally or for one app, requires the council (`GuardianCannotUnpause`). Optional `integrator` account to pause one app. Emits `PauseFlagsChanged`.

| Bit | Flag | Stops |
| - | - | - |
| `1 << 0` | `PAUSE_WAGERS` | New wagers |
| `1 << 1` | `PAUSE_DEPOSITS` | New deposit requests |
| `1 << 2` | `PAUSE_NEW_INTEGRATORS` | Wagers that would create a new app record |

No flag affects settlement, expiry, payout claims, the strike, LP claims or withdrawal requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.