SKILL.md
vregistry-66b33fa · 7.2 KB
---
name: phoenix
license: CC-BY-4.0. Publication and distribution require attribution to “markpaper — Phoenix knowledge base.” Full terms are in LICENSE.md next to the skill.
description: Use for Phoenix perpetuals exchange integrations on Solana involving Rise SDK, exact lots/ticks and u64 IDs, trader PDA and position-authority binding, REST account snapshots, program return data, cancellation, margin, RWA bands, or experimental signing. Triggers—Phoenix perpetuals, Phoenix Eternal, perp-api.phoenix.trade, @ellipsis-labs/rise, @markpaper/phoenix-kit, Phoenix order, Phoenix delegation. Excludes the Phoenix web framework and older Phoenix spot-market integrations.
---
# 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](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.