Add perpetual futures exchange example in Anchor and Quasar#47
Open
mikemaccana wants to merge 1 commit into
Open
Add perpetual futures exchange example in Anchor and Quasar#47mikemaccana wants to merge 1 commit into
mikemaccana wants to merge 1 commit into
Conversation
…r + Quasar) Adds a perpetual-futures exchange example under finance/perpetual-futures/, modelled on the oracle-priced, pool-collateralized design used by Jupiter Perpetuals and GMX (and the open-source solana-labs/perpetuals reference that Adrena and Flash Trade fork). Liquidity providers fund a shared pool and are the counterparty to every trade; traders open leveraged long or short positions priced at a Switchboard oracle, pay open/close and funding fees, and are liquidated permissionlessly once their equity falls below the maintenance margin. Both framework implementations expose the same seven instruction handlers — initialize_pool, add_liquidity, remove_liquidity, open_position, close_position, liquidate_position, collect_fees — and share the same design: - Liquidity-provider shares priced against mark-to-market assets-under-management derived from per-side open-interest accumulators, so an exiting provider cannot dodge an in-flight trader profit. - Reserved-liquidity solvency model: each open position reserves its notional size, an open is allowed only while the reserve stays backed by liquidity (which also caps open interest), recoverable profit is capped at the reserve so a winner can always be paid, and liquidity-provider withdrawals can take only the unreserved remainder. - A cumulative funding index in which the heavier open-interest side pays the pool over time. - Oracle reads validated for staleness (by slot), positivity, scale, and a confidence band that must stay within a per-pool maximum. - All money math in u128 with checked arithmetic, multiply-before-divide, rounding toward the protocol; transfer_checked; checks-effects-interactions; slippage bounds on every state-changing handler. Anchor (finance/perpetual-futures/anchor): a perpetual-futures program plus a mock-switchboard companion program that supplies a deterministic price+confidence feed for tests and documents the swap-in point for a real Switchboard On-Demand feed. Covered by 22 LiteSVM integration tests. Quasar (finance/perpetual-futures/quasar): a port with 12 quasar-svm tests. It keeps one position per (pool, owner) because Quasar's address constraint can reference account inputs but not instruction arguments, so the side is stored in the position rather than used as a seed; the oracle feed is supplied directly in tests rather than via a companion program. Docs: a finance-oriented README following the repository's program-flow format (participants, sample USDC/NVDAx tokens, per-step instruction and account tables) with concept links, a terminology glossary, design notes relating the example to percolator and solana-labs/perpetuals, and a Financial Software entry in the root README. Also commits the QuickNode Solana coding skill under .claude/skills/ (with a tracked .gitignore exception) so it is available in Claude Code web sessions. https://claude.ai/code/session_01YNkQe8eneL4FxCu96kmjVr
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a complete perpetual futures exchange implementation as a teaching example, provided in two parallel implementations: one using Anchor and one using Quasar. The exchange allows users to make leveraged bets on asset prices without owning the underlying asset, with liquidity providers funding the pool and serving as counterparties to traders.
Key Changes
Core Program Implementation (Anchor)
perpetual-futuresprogram: Full exchange implementation with pool creation, liquidity provision, position management, funding accrual, and liquidationmock-switchboardprogram: Test-only oracle feed for price dataCore Program Implementation (Quasar)
quasar-perpetual-futuresimplementation with identical design and behavior to the Anchor versionquasar-svmInstructions (both implementations)
initialize_pool: Create a market for a collateral token priced by an oracle feedadd_liquidity/remove_liquidity: Liquidity provider operationsopen_position/close_position: Trader leverage operationsliquidate_position: Liquidation of unhealthy positionscollect_fees: Protocol fee collectionShared Logic
Documentation
Notable Implementation Details
transfer_checkedcarries decimal information through all CPIsThe implementation serves as a reference for building oracle-priced, LP-pool perpetual futures exchanges on Solana, following the design patterns used by Jupiter Perpetuals and GMX.
https://claude.ai/code/session_01YNkQe8eneL4FxCu96kmjVr