Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/solana-labs/perpetuals
Solana perpetuals reference implementation
https://github.com/solana-labs/perpetuals
Last synced: 2 months ago
JSON representation
Solana perpetuals reference implementation
- Host: GitHub
- URL: https://github.com/solana-labs/perpetuals
- Owner: solana-labs
- License: other
- Created: 2023-04-20T02:23:17.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2023-10-26T22:30:37.000Z (about 1 year ago)
- Last Synced: 2024-09-28T09:42:37.788Z (2 months ago)
- Language: Rust
- Size: 16.9 MB
- Stars: 74
- Watchers: 8
- Forks: 41
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Audit: audit/Solana_Labs_Perpetuals_Solana_Program_Security_Audit_Report_Halborn_Final.pdf
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome - solana-labs/perpetuals - Solana perpetuals reference implementation (Rust)
README
# Solana Perpetuals
## Introduction
Solana Perpetuals protocol is an open-source implementation of a non-custodial decentralized exchange that supports leveraged trading in a variety of assets.
## Quick start
### Setup Environment
1. Clone the repository from .
2. Install the latest Solana tools from . If you already have Solana tools, run `solana-install update` to get the latest compatible version.
3. Install the latest Rust stable from . If you already have Rust, run `rustup update` to get the latest version.
4. Install the latest Anchor framework from . If you already have Anchor, run `avm update` to get the latest version.
Rustfmt is used to format the code. It requires `nightly` features to be activated:
5. Install `nightly` rust toolchain.
6. Execute `git config core.hooksPath .githooks` to activate pre-commit hooks.
#### [Optional] Vscode setup
1. Install `rust-analyzer` extension
2. If formatting doesn't work, make sure that `rust-analyzer.rustfmt.extraArgs` is set to `+nightly`
### Build
First, generate a new key for the program address with `solana-keygen new -o `. Then replace the existing program ID with the newly generated address in `Anchor.toml` and `programs/perpetuals/src/lib.rs`.
Also, 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.
To build the program run `anchor build` command from the `perpetuals` directory:
```sh
cd perpetuals
anchor build
```
### Test
Integration and unit tests (Rust) can be started as follows:
```sh
cargo test-bpf -- --nocapture
```
Integration tests (Typescript) can be started as follows:
```sh
npm install
anchor test -- --features test
```
By default, integration tests are executed on a local validator, so it won't cost you any SOL.
### Deploy
To deploy the program to the devnet and upload the IDL use the following commands:
```sh
anchor deploy --provider.cluster devnet --program-keypair
anchor idl init --provider.cluster devnet --filepath ./target/idl/perpetuals.json
```
### Initialize
A 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.
To initialize deployed program, run the following commands:
```sh
cd app
npm install
npm install -g npx
npx ts-node src/cli.ts -k init --min-signatures ...
```
Where `` is the file path to the wallet that was set as the upgrade authority of the program upon deployment. ``, `` 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 `` with `-k` option. The intermediate state is recorded on-chain so that commands can be executed on different computers.
To change program authority, run:
```sh
solana program set-upgrade-authority --new-upgrade-authority
```
To change program authority back, run:
```sh
solana program set-upgrade-authority --new-upgrade-authority -k
```
To change protocol admins or minimum required signatures, run:
```sh
npx ts-node src/cli.ts -k set-authority --min-signatures ...
```
To validate initialized program:
```sh
npx ts-node src/cli.ts -k get-multisig
npx ts-node src/cli.ts -k get-perpetuals
```
Before 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:
```sh
npx ts-node src/cli.ts -k add-pool
npx ts-node src/cli.ts -k add-custody [-s] [-v] [-t]
```
Where `` is a random name you want to assign to the pool, `` is the mint address of the token, and `` 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`.
For example:
```sh
npx ts-node src/cli.ts -k add-pool TestPool1
npx ts-node src/cli.ts -k add-custody TestPool1 So11111111111111111111111111111111111111112 J83w4HKfqxwcq3BEMMkPFSppX3gqekLyLJBexebFVkix
```
To validate added pools and custodies, run:
```sh
npx ts-node src/cli.ts -k get-pool
npx ts-node src/cli.ts -k get-custody
```
or
```sh
npx ts-node src/cli.ts -k get-pools
npx ts-node src/cli.ts -k get-custodies
```
To add liquidity, run:
```sh
npx ts-node src/cli.ts -k add-liquidity --amount-in --min-amount-out
```
For it to work, make sure the wallet's LM token ATA is initialized and the wallet hold enough tokens to provide as liquidity.
To initialize wallet's token ATA, run:
```sh
npx ts-node src/cli.ts -k get-lp-token-mint
spl-token create-account --owner --fee-payer
```
CLI offers other useful commands. You can get the list of all of them by running the following:
```sh
npx ts-node src/cli.ts --help
```
## UI (Deprecated)
### 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.
We 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.
In the main directory, run `./migrations/migrate-target.sh` to copy over the target build directory to the ui.
Now, you can use the following CLI commands to quickly spin-up a `TestPool1` consisting of the three following tokens.
Sol Token: `J83w4HKfqxwcq3BEMMkPFSppX3gqekLyLJBexebFVkix`
Test Token oracle: `BLArYBCUYhdWiY8PCUTpvFE21iaJq85dvxLk9bYMobcU`
USDC oracle: `5SSkXsEKQepHHAewytPVwdej4epN1nxgLVM84L4KXgy7`
```
cd app
npx ts-node src/cli.ts -k add-pool TestPool1
npx ts-node src/cli.ts -k add-custody TestPool1 So11111111111111111111111111111111111111112 J83w4HKfqxwcq3BEMMkPFSppX3gqekLyLJBexebFVkix
npx ts-node src/cli.ts -k add-custody TestPool1 6QGdQbaZEgpXqqbGwXJZXwbZ9xJnthfyYNZ92ARzTdAX BLArYBCUYhdWiY8PCUTpvFE21iaJq85dvxLk9bYMobcU
npx ts-node src/cli.ts -k add-custody TestPool1 Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr 5SSkXsEKQepHHAewytPVwdej4epN1nxgLVM84L4KXgy7 true
```
Now, use the following commands to build and run the UI, (navigate to localhost:3000 to use the UI):
```
cd ../ui
yarn install
yarn dev
```
## Support
If 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).
If 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 [email protected] instead.
## Contributing
Contributions are very welcome. Please refer to the [Contributing](https://github.com/solana-labs/solana/blob/master/CONTRIBUTING.md) guidelines for more information.
## License
Solana Perpetuals codebase is released under [Apache License 2.0](LICENSE).
## Disclaimer
By accessing or using Solana Perpetuals or any of its components, you accept and agree with the [Disclaimer](DISCLAIMER.md).