Phoenix perpetuals

Phoenix perpetuals: how to use the knowledge base

License

CC BY 4.0. This skill and knowledge/phoenix/ are markpaper materials. Publication/adaptation requires credit to “markpaper — Phoenix knowledge base,” a link to the original and license, and indication of changes. Preserve attribution when moving material. Terms: LICENSE.md.

Index: knowledge/phoenix/README.md. Public metadata and documentation were checked through 2026-10-03. The evaluated dependency surface is Rise 0.5.28 plus @solana/kit 4.0.0; observations and simulations are separately dated.

SDK and implemented scope

Use @markpaper/phoenix-kit (packages/phoenix-kit, Apache-2.0) for its implemented primitives: exact numbers, canonical address, markets, public rest, decoded/stable account, exact ids, pending, pure orders, margin, onchain, binding, and pure ops. The package README maps exported functions to topic files.

The signer and unsigned delegation builder are separate experimental entries. Imported helpers do not submit transactions themselves. The toolkit does not provide isolated-child registration/funding/trading orchestration, an onboarding UI, strategy, or a complete tiered margin calculator. New upstream builders do not automatically expand this package's support.

A. Read the relevant file first

Read needed sections plus pitfalls/open questions before editing protocol code. Disclose documentation-only and experimental behavior when it materially affects the task. Verify changing public parameters from current official sources.

Topic	Reference
REST endpoints, state/view decoding, trusted slots	knowledge/phoenix/api-and-reads.md
Exact ticks/lots, status, isolated-only, RWA bands	knowledge/phoenix/markets-and-numbers.md
Packets, exact identity, result/fill/cancel evidence	knowledge/phoenix/orders.md
Base58, header/capabilities, delegation/binding, key risk	knowledge/phoenix/account-and-delegation.md
Equity, free margin, mark valuation, fees	knowledge/phoenix/margin.md
SDK dependencies, intent journal, signing/delegation	knowledge/phoenix/signing-and-sidecar.md
Packet/CU ceilings, fees, REST/RPC pacing	knowledge/phoenix/rate-limits-and-costs.md
Startup, recovery, diagnostics, verification	knowledge/phoenix/ops.md
Dated traps and uncertainty	knowledge/phoenix/pitfalls.md

B. Invariants that change implementation decisions

1. Base lot is 10^-baseLotsDecimals, including negative decimals; quote lot is 10^-6 USD. Use createQuant and explicit rounding; float-floor SDK price conversion can shift one tick. → markets-and-numbers.md §1
2. Identity is market plus exact u64 price and sequence. Bid sequence is at least 2^63; reject JSON numbers. Base58 case is significant. → orders.md §2, account-and-delegation.md §1
3. State uses owner authority/PDA index; equity view uses trader PDA. Omitted arrays can be empty, but malformed arrays/foreign identity invalidate the read. → api-and-reads.md §1–2
4. Reject slots below accepted/own-fill evidence. Stable state/view/state agreement supplies plausibility, not universal freshness; equityAvailable does not claim the view is fresh. Idle-slot meaning remains unresolved. → api-and-reads.md §3
5. minBaseLotsToFill must be zero for ordinary partial IoC. Last-valid-slot and blockhash lifetime are different boundaries. → orders.md §1
6. Confirmed transactions can fill/post/cancel nothing. Interpret return data from the engine perspective, slot-qualified delta, rejection events, and effective cancel/no-found evidence. → orders.md §3, §5
7. Resting reduce-only quantity did not shrink with exposure; later zero-position matching is unverified. Do not promise it cannot reverse exposure. → orders.md §4
8. Source book ceiling is 64 per trader/market/side. Toolkit cancellation ceiling is 30 IDs; still check the final 1232-byte packet and CU limit. Split only a known failed batch, never an unknown one. → orders.md §5
9. Initial binding is unknown and blocks writes until verified. Compare signer identity and raw program-owned header; capability restrictions are separate from identity. Later unknown retains the last proved verdict. → account-and-delegation.md §2–3
10. SwapNative collateral risk is experimental source analysis, not a proven drain. Report flag-based open/closed/unknown evidence without overstating permission safety. → account-and-delegation.md §4
11. Resting margin uses mark valuation under the observed tier/risk-factor conditions. Do not publish an order-price estimate as a complete margin model. → margin.md §2
12. After-hours can trade inside a fresh band; discard it at calendar/index expiry. Clamp-edge behavior and post-only market acceptance are experimental. → markets-and-numbers.md §3–4
13. One intent produces at most one signature. Persist before sending, rebroadcast identical bytes, retain unresolved work across restart, and resolve unknowns before conflicting intents. → signing-and-sidecar.md §2–3
14. Workload windows, CU/priority fees, inflight capacity, SOL floor, and caps are explicit caller configuration. Fees can apply to landed failures; preflight and chain results differ. → rate-limits-and-costs.md §1–4

C. Implement and validate within the task's scope

• Use exact helper APIs and retain separate local refusal, preflight rejection, landed failure, confirmed empty result, post/fill, and unknown states.
• Generate synthetic keys/bytes for fixtures. Never publish a scrubbed live transaction blob whose encoded identities remain.
• Public smoke is unauthenticated and read-only. Simulation of a user account, delegation signing, and order submission are separate actions within the user's authorization.
• Experimental signer/delegation paths require offline dependency/tests and current-chain validation before fund-bearing use. A passing build does not prove packet acceptance.
• For a consequential unverified mechanic, identify the uncertainty and the smallest relevant evidence needed. Do not invent application policy or new exchange functionality.

D. Investigate a discrepancy

Start from raw header/capabilities, current metadata/band, signer intent/signature, RPC transaction metadata/return data, effective cancel logs, and trusted state/view slots. Diagnose from primary evidence before alerts. Record only public mechanics with a date and confidence; exclude account identifiers, exact experiment values, encoded snapshots, and private operational labels.