This is the canonical wire-format reference for the percli Solana program. It documents every instruction's discriminator, account list, argument layout, emitted events, error codes, and the engine call it dispatches to. Use this document when:

• Building an off-chain client in a language other than Rust.
• Auditing a third-party integration that talks to percli directly.
• Reproducing transactions for forensic analysis.

For the high-level operator workflow, see DEPLOYMENT.md.

Layout version: v1 (MARKET_DISCRIMINATOR_V1 = b"percmrk\x01"). Programs running v0.9.x markets must run migrate_header_v1 before any other instruction will succeed.

[ws] = writable signer, [r] = read-only non-signer, etc.

All arguments are Borsh-encoded in the order listed and prefixed with the 8-byte Anchor discriminator (sha256("global:<snake_case_name>")[0..8]). The full instruction data layout is:

<8-byte discriminator><borsh args>

Every market PDA has the same on-disk layout:

[0..8)              discriminator (b"percmrk" + version byte)
[8..176)            MarketHeader (168 bytes, v1 layout)
[176..176 + E)      RiskEngine state (E = SBF size_of::<RiskEngine>())

Add 8 to each offset for the absolute position inside the account data buffer.

Discriminator: 0x2323bdc19b30aacb (sha256("global:initialize_market")[0..8]) Auth: Authority (becomes header.authority) Engine call: RiskEngine::init_in_place(params, init_slot, init_oracle_price)

struct InitializeMarketArgs {
    init_slot: u64,
    init_oracle_price: u64,
    params: RiskParamsInput, // 15 × u64, see below
}

struct RiskParamsInput {
    warmup_period_slots: u64,
    maintenance_margin_bps: u64,
    initial_margin_bps: u64,
    trading_fee_bps: u64,
    max_accounts: u64,
    new_account_fee: u64,
    maintenance_fee_per_slot: u64,
    max_crank_staleness_slots: u64,
    liquidation_fee_bps: u64,
    liquidation_fee_cap: u64,
    min_liquidation_abs: u64,
    min_initial_deposit: u64,
    min_nonzero_mm_req: u64,
    min_nonzero_im_req: u64,
    insurance_floor: u64,
}

MarketInitialized {
    authority: Pubkey,
    mint: Pubkey,
    oracle: Pubkey,
    matcher: Pubkey,
    init_slot: u64,
    init_oracle_price: u64,
}

Discriminator: 0xf223c68952e1f2b6 Auth: Account owner (signer) Engine call: RiskEngine::deposit(account_idx, amount, ...)

struct DepositArgs { account_idx: u16, amount: u64 }

Deposited { user: Pubkey, account_idx: u16, amount: u64 }

AccountNotFound, Unauthorized, AccountIndexOutOfRange, AmountOverflow, InsufficientBalance, plus any underlying SPL token transfer error.

Discriminator: 0xb712469c946da122 Auth: Account owner (signer) Engine call: RiskEngine::withdraw(account_idx, amount, funding_rate, ...)

struct WithdrawArgs { account_idx: u16, amount: u64, funding_rate: i64 }

Withdrawn { user: Pubkey, account_idx: u16, amount: u64 }

Unauthorized, Undercollateralized, InsufficientBalance, AccountIndexOutOfRange, AmountOverflow.

Discriminator: 0xb2901ad8f1bbce82 Auth: Matcher (signer must equal header.matcher) Engine call: RiskEngine::trade(a, b, size_q, exec_price, funding_rate, ...)

struct TradeArgs {
    account_a: u16,
    account_b: u16,
    size_q: i128,
    exec_price: u64,
    funding_rate: i64,
}

TradeExecuted { matcher: Pubkey, account_a: u16, account_b: u16, size_q: i128, exec_price: u64 }

Unauthorized, InvalidMatchingEngine, PositionSizeMismatch, AccountKindMismatch, SideBlocked, Undercollateralized, AccountIndexOutOfRange.

Discriminator: 0x00e803c37c756935 Auth: Permissionless Engine call: RiskEngine::crank(oracle_price, slot, funding_rate)

Reads the latest Pyth price and applies it as the new mark.

struct CrankArgs { funding_rate: i64 }

Cranked { cranker: Pubkey, oracle_price: u64, slot: u64 }

InvalidOraclePrice, StaleOracle, InvalidOraclePriceValue, Unauthorized (if oracle pubkey doesn't match header).

Discriminator: 0xdfb3e27d302e274a Auth: Permissionless Engine call: RiskEngine::liquidate(account_idx, funding_rate) Returns: bool — true if the account was actually liquidated.

struct LiquidateArgs { account_idx: u16, funding_rate: i64 }

Liquidated { liquidator: Pubkey, account_idx: u16, liquidated: bool }

AccountIndexOutOfRange, AccountNotFound.

Discriminator: 0xaf2ab957908366d4 Auth: Account owner (signer) Engine call: RiskEngine::settle(account_idx, funding_rate)

struct SettleArgs { account_idx: u16, funding_rate: i64 }

Settled { user: Pubkey, account_idx: u16 }

Unauthorized, AccountIndexOutOfRange.

Discriminator: 0x7dff950e6e224818 Auth: Account owner (signer) Engine call: RiskEngine::close_account(account_idx, funding_rate)

struct CloseAccountArgs { account_idx: u16, funding_rate: i64 }

AccountClosed { user: Pubkey, account_idx: u16 }

Unauthorized, AccountIndexOutOfRange, Undercollateralized (if there's residual debt).

Discriminator: 0xe6d9263c2b208dd2 Auth: Permissionless Engine call: RiskEngine::reclaim_account(account_idx)

Permissionlessly reclaims a slot whose owner has zero collateral, zero position, and zero fee debt — typically a closed account whose owner has walked away. Frees the slot for reuse.

struct ReclaimAccountArgs { account_idx: u16 }

AccountReclaimed { reclaimer: Pubkey, account_idx: u16 }

AccountIndexOutOfRange, AccountNotFound.

Discriminator: 0xc9859176eb595abd Auth: Authority only Engine call: RiskEngine::withdraw_insurance(amount)

struct WithdrawInsuranceArgs { amount: u64 }

InsuranceWithdrawn { authority: Pubkey, amount: u64 }

Unauthorized, InsufficientBalance (would breach insurance_floor).

Discriminator: 0xa5be6dc7a347316e Auth: Permissionless Engine call: RiskEngine::top_up_insurance(amount)

struct TopUpInsuranceArgs { amount: u64 }

InsuranceToppedUp { depositor: Pubkey, amount: u64 }

AmountOverflow, plus SPL transfer errors.

Discriminator: 0x7a749118bcace52c Auth: Account owner (signer) Engine call: RiskEngine::deposit_fee_credits(account_idx, amount)

Lets an account holder pre-pay accumulated fees without touching the trading collateral.

struct DepositFeeCreditsArgs { account_idx: u16, amount: u64 }

FeeCreditsDeposited { user: Pubkey, account_idx: u16, amount: u64 }

Unauthorized, AccountIndexOutOfRange, AmountOverflow.

Discriminator: 0x71b5227b854f5da2 Auth: Account owner (signer) Engine call: RiskEngine::convert_released_pnl(account_idx, x_req, oracle_price, slot, funding_rate)

Converts matured (post-warmup) realized PnL into withdrawable collateral. Reads the current oracle price as part of the conversion math.

struct ConvertReleasedPnlArgs { account_idx: u16, x_req: u64, funding_rate: i64 }

PnlConverted { user: Pubkey, account_idx: u16, x_req: u64 }

Unauthorized, PnlNotWarmedUp, AccountIndexOutOfRange, StaleOracle, InvalidOraclePrice, InvalidOraclePriceValue.

Discriminator: 0x67b8692c22f08f59 Auth: Permissionless Engine call: RiskEngine::accrue_market(oracle_price, slot)

Mark-to-market + funding accrual without touching individual accounts. Cheaper than crank when you only need to advance the global state.

None.

MarketAccrued { signer: Pubkey, oracle_price: u64, slot: u64 }

StaleOracle, InvalidOraclePrice, InvalidOraclePriceValue, Unauthorized (oracle pubkey mismatch).

Discriminator: 0x4d0f04f0c4768b97 Auth: Authority only

Rotates the matcher signing key. The new matcher takes effect immediately.

struct UpdateMatcherArgs { new_matcher: Pubkey }

MatcherUpdated { authority: Pubkey, old_matcher: Pubkey, new_matcher: Pubkey }

Unauthorized.

Discriminator: 0x7029d112f8e2fcbc Auth: Authority only

Rotates the Pyth oracle account. The new oracle is validated on the next crank / accrue_market / convert_released_pnl call.

None.

OracleUpdated { authority: Pubkey, old_oracle: Pubkey, new_oracle: Pubkey }

Unauthorized.

Discriminator: 0x30a94c48e5b437a1 Auth: Authority only

Step 1 of the two-step authority handoff. Writes new_authority into header.pending_authority without rotating header.authority. Self-transfer is rejected with Unauthorized. Passing Pubkey::default() cancels any in-flight transfer and emits AuthorityTransferCancelled instead of AuthorityTransferInitiated.

struct TransferAuthorityArgs { new_authority: Pubkey }

// Emitted when new_authority != Pubkey::default()
AuthorityTransferInitiated {
    market: Pubkey,
    old_authority: Pubkey,
    pending_authority: Pubkey,
}

// Emitted when new_authority == Pubkey::default()
AuthorityTransferCancelled {
    market: Pubkey,
    authority: Pubkey,
    previous_pending: Pubkey,
}

AccountNotFound (not a v1 market), Unauthorized (signer mismatch or self-transfer), CorruptState (header deserialization failed).

Discriminator: 0x6b56c65b210c6ba0 Auth: Pending authority only

Step 2 of the two-step handoff. Rotates header.authority to header.pending_authority and clears pending_authority.

None.

AuthorityAccepted { market: Pubkey, old_authority: Pubkey, new_authority: Pubkey }

AccountNotFound (not a v1 market), NoPendingAuthority (pending_authority == default), Unauthorized (signer doesn't match pending or signer is Pubkey::default()).

Discriminator: 0x4cd8855fd38625cd Auth: Authority only (must match the v0-encoded authority)

One-time, idempotent-by-rejection migration from the legacy v0.9 layout (136-byte header) to the v1.0 layout (168-byte header). Performed in-place via copy_within — no realloc and no rent top-up are needed because real v0.9 mainnet accounts were created with a host-side allocation that's strictly larger than the SBF v1 size.

None.

1. Verify program ownership (Anchor owner constraint).
2. Verify discriminator [0..7] == b"percmrk" and version byte [7]:
   • 0x01 → AlreadyMigrated.
   • non-0x74 → NotLegacyLayout.
3. Re-derive the Market PDA from the v0-encoded authority and verify the stored bump matches the canonical PDA bump (CorruptState if not).
4. Verify the signer matches the v0-encoded authority.
5. Shift engine bytes from [144..) to [176..) via copy_within.
6. Write the v1 header at [8..176) with pending_authority = default, preserving authority/mint/oracle/matcher/bump/vault_bump.
7. Stamp data[7] = 0x01.

HeaderMigrated {
    authority: Pubkey,
    market: Pubkey,
    mint: Pubkey,
    oracle: Pubkey,
    matcher: Pubkey,
    /// Actual on-chain data.len() after migration. Migration is in-place,
    /// so this equals the v0 host-side account size (NOT the SBF v1 size).
    account_size: u64,
}

AccountNotFound (wrong owner, too small, or [0..7] != b"percmrk"), AlreadyMigrated (version byte already 0x01), NotLegacyLayout (version byte is neither 0x01 nor 0x74), Unauthorized (signer mismatch), CorruptState (PDA bump mismatch).

These are computed from sha256("global:<snake_case_name>")[0..8]. Verify locally:

python3 -c '
import hashlib, sys
print(hashlib.sha256(("global:" + sys.argv[1]).encode()).hexdigest()[:16])
' initialize_market
# → 2323bdc19b30aacb