{"id":14238046,"url":"https://github.com/solana-labs/perpetuals","last_synced_at":"2025-10-19T09:32:13.221Z","repository":{"id":162321346,"uuid":"630261264","full_name":"solana-labs/perpetuals","owner":"solana-labs","description":"Solana perpetuals reference implementation","archived":false,"fork":false,"pushed_at":"2023-10-26T22:30:37.000Z","size":17702,"stargazers_count":74,"open_issues_count":4,"forks_count":41,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-09-28T09:42:37.788Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/solana-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit/Solana_Labs_Perpetuals_Solana_Program_Security_Audit_Report_Halborn_Final.pdf","citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-20T02:23:17.000Z","updated_at":"2024-09-24T09:39:36.000Z","dependencies_parsed_at":"2023-10-16T11:25:10.936Z","dependency_job_id":"778938ce-356b-4d09-8fa1-936e6fe098ee","html_url":"https://github.com/solana-labs/perpetuals","commit_stats":{"total_commits":81,"total_committers":7,"mean_commits":"11.571428571428571","dds":0.345679012345679,"last_synced_commit":"ebfb4972ea5d1cde8580a7e8c7b9dbd1fdb2b002"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solana-labs%2Fperpetuals","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solana-labs%2Fperpetuals/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solana-labs%2Fperpetuals/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solana-labs%2Fperpetuals/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solana-labs","download_url":"https://codeload.github.com/solana-labs/perpetuals/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219869246,"owners_count":16555571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-21T02:00:45.909Z","updated_at":"2025-10-19T09:32:05.525Z","avatar_url":"https://github.com/solana-labs.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# Solana Perpetuals\n\n## Introduction\n\nSolana Perpetuals protocol is an open-source implementation of a non-custodial decentralized exchange that supports leveraged trading in a variety of assets.\n\n## Quick start\n\n### Setup Environment\n\n1. Clone the repository from \u003chttps://github.com/solana-labs/perpetuals.git\u003e.\n2. Install the latest Solana tools from \u003chttps://docs.solana.com/cli/install-solana-cli-tools\u003e. If you already have Solana tools, run `solana-install update` to get the latest compatible version.\n3. Install the latest Rust stable from \u003chttps://rustup.rs/\u003e. If you already have Rust, run `rustup update` to get the latest version.\n4. Install the latest Anchor framework from \u003chttps://www.anchor-lang.com/docs/installation\u003e. If you already have Anchor, run `avm update` to get the latest version.\n\nRustfmt is used to format the code. It requires `nightly` features to be activated:\n\n5. Install `nightly` rust toolchain. \u003chttps://rust-lang.github.io/rustup/installation/index.html#installing-nightly\u003e\n6. Execute `git config core.hooksPath .githooks` to activate pre-commit hooks.\n\n#### [Optional] Vscode setup\n\n1. Install `rust-analyzer` extension\n2. If formatting doesn't work, make sure that `rust-analyzer.rustfmt.extraArgs` is set to `+nightly`\n\n### Build\n\nFirst, generate a new key for the program address with `solana-keygen new -o \u003cPROG_ID_JSON\u003e`. Then replace the existing program ID with the newly generated address in `Anchor.toml` and `programs/perpetuals/src/lib.rs`.\n\nAlso, ensure the path to your wallet in `Anchor.toml` is correct. Alternatively, when running Anchor deploy or test commands, you can specify your wallet with `--provider.wallet` argument. The wallet's pubkey will be set as an upgrade authority upon initial deployment of the program. It is strongly recommended to make upgrade authority a multisig when deploying to the mainnet.\n\nTo build the program run `anchor build` command from the `perpetuals` directory:\n\n```sh\ncd perpetuals\nanchor build\n```\n\n### Test\n\nIntegration and unit tests (Rust) can be started as follows:\n\n```sh\ncargo test-bpf -- --nocapture\n```\n\nIntegration tests (Typescript) can be started as follows:\n\n```sh\nnpm install\nanchor test -- --features test\n```\n\nBy default, integration tests are executed on a local validator, so it won't cost you any SOL.\n\n### Deploy\n\nTo deploy the program to the devnet and upload the IDL use the following commands:\n\n```sh\nanchor deploy --provider.cluster devnet --program-keypair \u003cPROG_ID_JSON\u003e\nanchor idl init --provider.cluster devnet --filepath ./target/idl/perpetuals.json \u003cPROGRAM ID\u003e\n```\n\n### Initialize\n\nA small CLI Typescript client is included to help you initialize and manage the program. By default script uses devnet cluster. Add `-u https://api.mainnet-beta.solana.com` to all of the commands if you plan to execute them on mainnet.\n\nTo initialize deployed program, run the following commands:\n\n```sh\ncd app\nnpm install\nnpm install -g npx\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e init --min-signatures \u003cint\u003e \u003cADMIN_PUBKEY1\u003e \u003cADMIN_PUBKEY2\u003e ...\n```\n\nWhere `\u003cADMIN_WALLET\u003e` is the file path to the wallet that was set as the upgrade authority of the program upon deployment. `\u003cADMIN_PUBKEY1\u003e`, `\u003cADMIN_PUBKEY2\u003e` etc., will be set as protocol admins, and `min-signatures` will be required to execute privileged instructions. To provide multiple signatures, just execute exactly the same command multiple times specifying different `\u003cADMIN_WALLET\u003e` with `-k` option. The intermediate state is recorded on-chain so that commands can be executed on different computers.\n\nTo change program authority, run:\n\n```sh\nsolana program set-upgrade-authority \u003cPROGRAM_ADDRESS\u003e --new-upgrade-authority \u003cNEW_UPGRADE_AUTHORITY\u003e\n```\n\nTo change program authority back, run:\n\n```sh\nsolana program set-upgrade-authority \u003cPROGRAM_ADDRESS\u003e --new-upgrade-authority \u003cNEW_UPGRADE_AUTHORITY\u003e -k \u003cCURRENT_AUTHORITY_KEYPAIR\u003e\n```\n\nTo change protocol admins or minimum required signatures, run:\n\n```sh\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e set-authority --min-signatures \u003cint\u003e \u003cADMIN_PUBKEY1\u003e \u003cADMIN_PUBKEY2\u003e ...\n```\n\nTo validate initialized program:\n\n```sh\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e get-multisig\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e get-perpetuals\n```\n\nBefore the program can accept any liquidity or open a trade, you need to create a token pool and add one or more token custodies to it:\n\n```sh\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e add-pool \u003cPOOL_NAME\u003e\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e add-custody [-s] [-v] [-t] \u003cPOOL_NAME\u003e \u003cTOKEN_MINT\u003e \u003cTOKEN_ORACLE\u003e\n```\n\nWhere `\u003cPOOL_NAME\u003e` is a random name you want to assign to the pool, `\u003cTOKEN_MINT\u003e` is the mint address of the token, and `\u003cTOKEN_ORACLE\u003e` is the corresponding Pyth price account that can be found on [this page](https://pyth.network/price-feeds?cluster=devnet). `-s` flag specifies whether the custody is for a stablecoin. `-v` flag is used to create a virtual/synthetic custody. More information on the latter can be found [here](SYNTHETICS.md). `-t` flag specifies the type of the oracle to be used for the custody: `custom`, `pyth` or `none`.\n\nFor example:\n\n```sh\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e add-pool TestPool1\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e add-custody TestPool1 So11111111111111111111111111111111111111112 J83w4HKfqxwcq3BEMMkPFSppX3gqekLyLJBexebFVkix\n```\n\nTo validate added pools and custodies, run:\n\n```sh\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e get-pool \u003cPOOL_NAME\u003e\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e get-custody \u003cPOOL_NAME\u003e \u003cTOKEN_MINT\u003e\n```\n\nor\n\n```sh\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e get-pools\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e get-custodies \u003cPOOL_NAME\u003e\n```\n\nTo add liquidity, run:\n\n```sh\nnpx ts-node src/cli.ts -k \u003cWALLET\u003e add-liquidity \u003cPOOL_NAME\u003e \u003cTOKEN_MINT\u003e --amount-in \u003cAMOUNT_IN\u003e --min-amount-out \u003cMIN_AMOUNT_OUT\u003e\n```\n\nFor it to work, make sure the wallet's LM token ATA is initialized and the wallet hold enough tokens to provide as liquidity.\n\nTo initialize wallet's token ATA, run:\n\n```sh\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e get-lp-token-mint \u003cPOOL_NAME\u003e\n\nspl-token create-account \u003cLM_TOKEN_MINT\u003e --owner \u003cWALLET\u003e --fee-payer \u003cPAYER_WALLET\u003e\n```\n\nCLI offers other useful commands. You can get the list of all of them by running the following:\n\n```sh\nnpx ts-node src/cli.ts --help\n```\n\n## UI (Deprecated)\n\n### UI doesn't support the latest version of the on-chain program. The code is still available but for the reference only. Latest supported commit is 34f9bbb.\n\nWe have implemented a coressponding UI for the smartcontract, written in Typescript/Tailwind/Next. To quickly spin up a UI linked to the contract, first follow the previous directions to build the contract, and to init the exchange.\n\nIn the main directory, run `./migrations/migrate-target.sh` to copy over the target build directory to the ui.\n\nNow, you can use the following CLI commands to quickly spin-up a `TestPool1` consisting of the three following tokens.\n\nSol Token: `J83w4HKfqxwcq3BEMMkPFSppX3gqekLyLJBexebFVkix`\n\nTest Token oracle: `BLArYBCUYhdWiY8PCUTpvFE21iaJq85dvxLk9bYMobcU`\n\nUSDC oracle: `5SSkXsEKQepHHAewytPVwdej4epN1nxgLVM84L4KXgy7`\n\n```\ncd app\n\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e add-pool TestPool1\n\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e add-custody TestPool1 So11111111111111111111111111111111111111112 J83w4HKfqxwcq3BEMMkPFSppX3gqekLyLJBexebFVkix\n\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e add-custody TestPool1 6QGdQbaZEgpXqqbGwXJZXwbZ9xJnthfyYNZ92ARzTdAX BLArYBCUYhdWiY8PCUTpvFE21iaJq85dvxLk9bYMobcU\n\nnpx ts-node src/cli.ts -k \u003cADMIN_WALLET\u003e add-custody TestPool1 Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr 5SSkXsEKQepHHAewytPVwdej4epN1nxgLVM84L4KXgy7 true\n```\n\nNow, use the following commands to build and run the UI, (navigate to localhost:3000 to use the UI):\n\n```\ncd ../ui\nyarn install\nyarn dev\n```\n\n## Support\n\nIf you are experiencing technical difficulties while working with the Perpetuals codebase, open an issue on [Github](https://github.com/solana-labs/perpetuals/issues). For more general questions about programming on Solana blockchain use [StackExchange](https://solana.stackexchange.com).\n\nIf you find a bug in the code, you can raise an issue on [Github](https://github.com/solana-labs/perpetuals/issues). But if this is a security issue, please don't disclose it on Github or in public channels. Send information to solana.farms@protonmail.com instead.\n\n## Contributing\n\nContributions are very welcome. Please refer to the [Contributing](https://github.com/solana-labs/solana/blob/master/CONTRIBUTING.md) guidelines for more information.\n\n## License\n\nSolana Perpetuals codebase is released under [Apache License 2.0](LICENSE).\n\n## Disclaimer\n\nBy accessing or using Solana Perpetuals or any of its components, you accept and agree with the [Disclaimer](DISCLAIMER.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolana-labs%2Fperpetuals","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolana-labs%2Fperpetuals","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolana-labs%2Fperpetuals/lists"}