From e16cf30c6368422363391f58bf3f7857b48e3712 Mon Sep 17 00:00:00 2001 From: Calin <57701767+calintje@users.noreply.github.com> Date: Mon, 28 Oct 2024 15:33:01 +0100 Subject: [PATCH] "Getting Started" docs for TS SDK (#378) * Base docs organization * Update welcome * Update Getting Started docs. Add environment setup, create pool, open position. * Finalize draft for ts-sdk docs * Fix spelling. Fix linter issue. Fix linking. * Resolve comments * Rename files. Remove 'Monitor' category. Fix links, fix build. * Streamline content for conceptual and usage-focused guides. Move detailed function explanation to Typedocs. * Fix typos * Fix links * Resolve comments * Update explainer on divergence loss --------- Co-authored-by: calintje --- docs/whirlpool/docs/01-Welcome.mdx | 47 +++++++++ .../01-Account Architecture.md | 3 + .../02-Price & Ticks.md | 1 + .../03-Understanding Tick Arrays.md | 1 + .../04-Tokenized Positions.md | 1 + .../05-Whirlpool Fees.md | 1 + .../img/architecture-overview.png | Bin 0 -> 7254 bytes .../03-Whirlpools SDK/01-Environment Setup.md | 73 ++++++++++++++ .../02-Whirlpool Management/01-Create Pool.md | 94 +++++++++++++++++ .../02-Whirlpool Management/02-Fetch Pools.md | 66 ++++++++++++ .../01-Open Position.md | 93 +++++++++++++++++ .../02-Fetch Positions.md | 43 ++++++++ .../03-Adjust Liquidity.md | 57 +++++++++++ .../03-Position Management/04-Harvest.md | 47 +++++++++ .../05-Close Position.md | 45 +++++++++ .../docs/03-Whirlpools SDK/04-Trade.md | 57 +++++++++++ .../docs/04-Tutorials/01-Token Project.md | 7 ++ docs/whirlpool/docs/home.md | 8 -- docs/whirlpool/docusaurus.config.js | 6 +- docs/whirlpool/src/theme/DocCard/index.js | 95 ++++++++++++++++++ .../src/theme/DocCard/styles.module.css | 28 ++++++ 21 files changed, 760 insertions(+), 13 deletions(-) create mode 100644 docs/whirlpool/docs/01-Welcome.mdx create mode 100644 docs/whirlpool/docs/02-Whirlpools Overview/01-Account Architecture.md create mode 100644 docs/whirlpool/docs/02-Whirlpools Overview/02-Price & Ticks.md create mode 100644 docs/whirlpool/docs/02-Whirlpools Overview/03-Understanding Tick Arrays.md create mode 100644 docs/whirlpool/docs/02-Whirlpools Overview/04-Tokenized Positions.md create mode 100644 docs/whirlpool/docs/02-Whirlpools Overview/05-Whirlpool Fees.md create mode 100644 docs/whirlpool/docs/02-Whirlpools Overview/img/architecture-overview.png create mode 100644 docs/whirlpool/docs/03-Whirlpools SDK/01-Environment Setup.md create mode 100644 docs/whirlpool/docs/03-Whirlpools SDK/02-Whirlpool Management/01-Create Pool.md create mode 100644 docs/whirlpool/docs/03-Whirlpools SDK/02-Whirlpool Management/02-Fetch Pools.md create mode 100644 docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/01-Open Position.md create mode 100644 docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/02-Fetch Positions.md create mode 100644 docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/03-Adjust Liquidity.md create mode 100644 docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/04-Harvest.md create mode 100644 docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/05-Close Position.md create mode 100644 docs/whirlpool/docs/03-Whirlpools SDK/04-Trade.md create mode 100644 docs/whirlpool/docs/04-Tutorials/01-Token Project.md delete mode 100644 docs/whirlpool/docs/home.md create mode 100644 docs/whirlpool/src/theme/DocCard/index.js create mode 100644 docs/whirlpool/src/theme/DocCard/styles.module.css diff --git a/docs/whirlpool/docs/01-Welcome.mdx b/docs/whirlpool/docs/01-Welcome.mdx new file mode 100644 index 00000000..c7c70ee1 --- /dev/null +++ b/docs/whirlpool/docs/01-Welcome.mdx @@ -0,0 +1,47 @@ +--- +sidebar_position: 1 +slug: / +--- +import DocCard from '@theme/DocCard'; + +# Welcome + +Whirlpools is an open-sourced concentrated liquidity automated market maker (CLAMM) program built for the Solana ecosystem. + + + +## Introduction to Solana. + +On Solana, all data is stored in what is referred to as accounts. The way accounts are organized on Solana is similar to a key-value store, where each entry in the database is called an account. The key is the account's address, and the value is the data stored in the account. + +Some accounts only store data, such as a token account for your favorite token. Other accounts store programs. For example, there is a Token Program responsible for managing token accounts and transfers. Every time you send a token, you're sending a transaction to the Token Program, which updates the balances of the accounts involved. + +The Whirlpools Program is also a program. It can create new data accounts if you instruct it to, and even set you as the owner of those accounts. Accounts that you can own include Splash Pools, Concentrated Liquidity Pools, and liquidity positions. For these accounts, you'll pay rent. But here's the good part: this is no ordinary rent—you get the full rent back if you decide to close the account! You only pay the transaction costs on the Solana network, which, as you may know, are very low. You can also instruct the program to swap tokens against one of the many liquidity pools that hold the tokens you'd like to trade. + +You interact with the Solana network by sending transactions to interact with accounts. Transactions are a sequence of instructions that are executed atomically on the network. The execution logic for these instructions is stored in programs (smart contracts) that run on the network. + +Interacting with the Solana network and its many existing programs is easier than you might think. There are several SDKs available to simplify the process. + +## Whirlpools SDK + +The Whirlpools SDK is an open-source library that allows developers to interact with the Whirlpools Program and is intended to be used in conjunction with the Solana SDK. Simply put, you use the Whirlpools SDK to create instructions, and the Solana SDK to send them to the network. + +Some of the main features are: +- Create instructions to set up a new pool, open positions, add or remove liquidity, and swap tokens. +- Get quotes for swaps. +- Query the state of pools to retrieve information about asset prices, liquidity, and fees. + +## How to use this documentation + +In the next section you will find information about the Whirlpools Program and its architecture. + +In the following sections you will find information about the Whirlpools SDK and how to use it to interact with the program. + +We also provide start-to-end tutorials for specific use cases combining the Whirlpools SDK with the Solana SDK. + +If you have any questions or need help, feel free to reach out to us on the [Discord](https://discord.orca.so). \ No newline at end of file diff --git a/docs/whirlpool/docs/02-Whirlpools Overview/01-Account Architecture.md b/docs/whirlpool/docs/02-Whirlpools Overview/01-Account Architecture.md new file mode 100644 index 00000000..035f02d3 --- /dev/null +++ b/docs/whirlpool/docs/02-Whirlpools Overview/01-Account Architecture.md @@ -0,0 +1,3 @@ +# Account Architecture + +Coming soon \ No newline at end of file diff --git a/docs/whirlpool/docs/02-Whirlpools Overview/02-Price & Ticks.md b/docs/whirlpool/docs/02-Whirlpools Overview/02-Price & Ticks.md new file mode 100644 index 00000000..fe4d5d35 --- /dev/null +++ b/docs/whirlpool/docs/02-Whirlpools Overview/02-Price & Ticks.md @@ -0,0 +1 @@ +Coming soon \ No newline at end of file diff --git a/docs/whirlpool/docs/02-Whirlpools Overview/03-Understanding Tick Arrays.md b/docs/whirlpool/docs/02-Whirlpools Overview/03-Understanding Tick Arrays.md new file mode 100644 index 00000000..fe4d5d35 --- /dev/null +++ b/docs/whirlpool/docs/02-Whirlpools Overview/03-Understanding Tick Arrays.md @@ -0,0 +1 @@ +Coming soon \ No newline at end of file diff --git a/docs/whirlpool/docs/02-Whirlpools Overview/04-Tokenized Positions.md b/docs/whirlpool/docs/02-Whirlpools Overview/04-Tokenized Positions.md new file mode 100644 index 00000000..fe4d5d35 --- /dev/null +++ b/docs/whirlpool/docs/02-Whirlpools Overview/04-Tokenized Positions.md @@ -0,0 +1 @@ +Coming soon \ No newline at end of file diff --git a/docs/whirlpool/docs/02-Whirlpools Overview/05-Whirlpool Fees.md b/docs/whirlpool/docs/02-Whirlpools Overview/05-Whirlpool Fees.md new file mode 100644 index 00000000..fe4d5d35 --- /dev/null +++ b/docs/whirlpool/docs/02-Whirlpools Overview/05-Whirlpool Fees.md @@ -0,0 +1 @@ +Coming soon \ No newline at end of file diff --git a/docs/whirlpool/docs/02-Whirlpools Overview/img/architecture-overview.png b/docs/whirlpool/docs/02-Whirlpools Overview/img/architecture-overview.png new file mode 100644 index 0000000000000000000000000000000000000000..1a18c93f028ed8724693f08c71b140a23e582c6a GIT binary patch literal 7254 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 F{|BZ6@QVNd literal 0 HcmV?d00001 diff --git a/docs/whirlpool/docs/03-Whirlpools SDK/01-Environment Setup.md b/docs/whirlpool/docs/03-Whirlpools SDK/01-Environment Setup.md new file mode 100644 index 00000000..5fa099e2 --- /dev/null +++ b/docs/whirlpool/docs/03-Whirlpools SDK/01-Environment Setup.md @@ -0,0 +1,73 @@ +# Environment setup + +This document covers the essential setup required to start building on Orca’s SDK using the Whirlpools protocol. It includes wallet setup, RPC client configuration, airdropping tokens for testing, and the basics of interacting with the Solana ecosystem. + +## Prerequisites + +Before you start, ensure you have Node.js version 20 or higher installed on your machine. Download it from the official website: https://nodejs.org/. + +## 1. Initialize a new project +Create a new project directory: + +```bash +mkdir whirlpools +cd whirlpools +``` + +Initialize a new Node.js project: + +```bash +npm init -y +``` + +Install the necessary packages: + +```bash +npm install typescript @orca-so/whirlpools @solana/web3.js@rc +``` + +Initialize the project as a TypeScript project: + +```bash +npx tsc --init +``` + +## 3. Wallet Creation + +You can create a wallet using `generateKeyPairSigner()` from the Solana SDK. + +```tsx +import { generateKeyPairSigner } from '@solana/web3.js'; + +const wallet = await generateKeyPairSigner(); +``` + +> ⚠️ Important: Never share your private key publicly. + +## 4. Airdrop SOL to Your Wallet + +Once your wallet is created, you will need some SOL to pay for transactions. You can request an airdrop of SOL from the network, but this is only available on **Devnet** and **Testnet**. + +```tsx +import { generateKeyPair, createSolanaRpc, devnet, getAddressFromPublicKey } from '@solana/web3.js'; + +const devnetRpc = createSolanaRpc(devnet('https://api.devnet.solana.com')); +const wallet = await generateKeyPairSigner(); +devnetRpc.requestAirdrop( + wallet.address, + lamports(1000000000n) +).send() +``` + +## 5. Set the FUNDER for Transactions + +After funding your wallet, you can set the wallet as the **FUNDER** for future transactions within the SDK. The funder is the account that will cover the transaction costs for initializing pools, providing liquidity, etc. +```tsx +import { setDefaultFunder } from '@orca-so/whirlpools'; + +setDefaultFunder(wallet); +``` + +## Next steps + +Once you’ve completed the setup, you can move on to building more complex functionalities using the Orca SDK, such as creating and managing pools, providing liquidity, etc. Refer to individual function documentation to use this wallet setup in action. \ No newline at end of file diff --git a/docs/whirlpool/docs/03-Whirlpools SDK/02-Whirlpool Management/01-Create Pool.md b/docs/whirlpool/docs/03-Whirlpools SDK/02-Whirlpool Management/01-Create Pool.md new file mode 100644 index 00000000..707840e2 --- /dev/null +++ b/docs/whirlpool/docs/03-Whirlpools SDK/02-Whirlpool Management/01-Create Pool.md @@ -0,0 +1,94 @@ +--- +sidebar_label: Create Liquidity Pools +--- + +# Creating Liquidity Pools on Orca + +Creating liquidity pools on Orca is an essential step for launching your token and enabling trading. In this guide, we'll explore two types of liquidity pools available in the Orca ecosystem, **Splash Pools** and **Concentrated Liquidity Pools**, and help you understand how to create them, their differences, and which one best suits your needs. + +## 1. Introduction to Pool Types + +### Overview + +Liquidity pools are a foundational concept in DeFi, enabling users to trade tokens without relying on traditional order books. On Orca, liquidity pools provide the means for traders to swap between two tokens, while liquidity providers earn fees by supplying the tokens to the pool. + +### Splash Pools vs. Concentrated Liquidity Pools + +- **Splash Pools**: Splash Pools are the simplest type of liquidity pool. They are ideal for those looking to launch a new token with minimal parameters. You only need to provide the mint addresses of the two tokens and set the initial price. Splash Pools offer an easy entry point into liquidity provision, making them especially appealing for community-driven projects like memecoins. These projects often prioritize community engagement over technical complexity, and Splash Pools provide a straightforward way to get started. + +- **Concentrated Liquidity Pools:** Concentrated Liquidity Pools are more advanced and allow liquidity providers to concentrate their liquidity within specific price ranges. This results in higher capital efficiency but requires a deeper understanding of how to manage liquidity. Concentrated Liquidity Pools are better suited for experienced users who want greater control over their liquidity. + +## 2. Getting Started Guide + +Before creating a Splash Pool or a Concentrated Liquidity Pool, ensure you have completed the environment setup: +- **RPC Setup**: Use a Solana RPC client to communicate with the blockchain. +- **Wallet Creation**: Create a wallet to interact with the Solana network. +- **Devnet Airdrop**: Fund your wallet with a Solana devnet airdrop to cover transaction fees. + +For more details, refer to our [Environment Setup Guide](../01-Environment%20Setup.md) + +### Creating Splash Pools + +Splash Pools are the easiest way to get started: + +1. **Token Mint Addresses**: Provide the mint addresses of the two tokens that will make up the liquidity pool. The order of the tokens is important: the first token will be priced in terms of the second token. This means that the price you set will reflect how many units of the second token are needed to equal one unit of the first token. For example, if you set the price to 0.0001 SOL, this means that one unit of the first token is worth 0.0001 units of the second token (SOL). Make sure to verify the order of your tokens. +2. **Initial Price**: Set the initial price of token 1 in terms of token 2. +3. **Funder**: This will be your wallet, which will fund the initialization process. +4. **Create Instructions**: Use the appropriate function to generate the required pool creation instructions. + ```tsx + import { createSplashPoolInstructions } from '@orca-so/whirlpools' + + const { poolAddress, instructions, initializationCost } = await createSplashPoolInstructions( + rpc, + tokenMintOne, + tokenMintTwo, + initialPrice, + wallet + ); + ``` +5. Submit Transaction: Include the generated pool creation instructions in a Solana transaction and send it to the network using the Solana SDK. + +### Creating Concentrated Liquidity Pools + +Concentrated Liquidity Pools offer more flexibility: + +1. **Token Mint Addresses**: Provide the two token mints. +2. **Tick Spacing**: Set the tick spacing, which defines the intervals for price ticks. Visit [this link](https://orca-so.gitbook.io/orca-developer-portal/whirlpools/interacting-with-the-protocol/orca-whirlpools-parameters#initialized-feetier-and-tickspacing) to learn more about the available values of tick spacing and their corresponding fee rates. +3. **Initial Price**: Specify the initial price of token 1 in terms of token 2. +4. **Funder**: This can be your wallet, which will fund the pool initialization. If the funder is not specified, the default wallet will be used. You can configure the default wallet through the SDK. +5. **Create instructions**: Use the appropriate function to create the pool. + ```tsx + import { createConcentratedLiquidityPool } from '@orca-so/whirlpools' + + const { poolAddress, instructions, initializationCost } = await createConcentratedLiquidityPool( + rpc, + tokenMintOne, + tokenMintTwo, + tickSpacing, + initialPrice, + wallet + ); + ``` +6. **Submit Transaction**: Include the generated pool creation instructions in a Solana transaction and send it to the network using the Solana SDK. + +### Comparison +| Feature | Splash Pools | Concentrated Liquidity Pools | +| ------------------ | ------------------ | -------------------------------- | +| Complexity | Low | High | +| Initial Parameters | Token mints, price | Token mints, tick spacing, price | +| Capital Efficiency | Moderate | High | +| Ideal For | Beginners | Advanced Users | + +## 3. Usage Examples + +### Launching a Token Pair with a Splash Pool + +Suppose you want to launch a new memecoin and pair it with USDC. You can leverage the simplicity of Splash Pools to quickly set up the pool with an initial price. This is ideal if you want to keep things simple and start earning trading fees with minimal configuration. For example, if a development team is building a launchpad for memecoins, Splash Pools are an ideal solution. + +### Creating a Concentrated Liquidity Pool for Efficiency + +If you want to maximize capital efficiency, you can use the flexibility of Concentrated Liquidity Pools to define specific price ranges for your liquidity. This approach is beneficial when you expect price movements within certain bounds and want to concentrate liquidity accordingly. For example, a DeFi protocol might use a Concentrated Liquidity Pool to facilitate a stablecoin-stablecoin pair, where the price is expected to remain within a tight range. By concentrating liquidity in this range, the protocol can maximize returns for liquidity providers and reduce slippage for traders. + +## 4. Next Steps + +After creating a liquidity pool, the pool is still empty and requires liquidity for people to trade against. To make the pool functional, open a position and add liquidity. This enables traders to swap between tokens and helps you start earning fees. \ No newline at end of file diff --git a/docs/whirlpool/docs/03-Whirlpools SDK/02-Whirlpool Management/02-Fetch Pools.md b/docs/whirlpool/docs/03-Whirlpools SDK/02-Whirlpool Management/02-Fetch Pools.md new file mode 100644 index 00000000..0fafa689 --- /dev/null +++ b/docs/whirlpool/docs/03-Whirlpools SDK/02-Whirlpool Management/02-Fetch Pools.md @@ -0,0 +1,66 @@ +--- +sidebar_label: Fetch Liquidity Pools +--- + +# Fetching Liquidity Pools on Orca + +Monitoring and fetching details about liquidity pools on Orca is crucial for understanding their current state, whether you want to gather insights in a Splash Pool, a Concentrated Liquidity Pool, or all pools between specific token pairs. This guide will explain how to interact with the available functions to retrieve these details. + +## 1. Overview of Pool Fetching + +Fetching liquidity pool details helps developers gain insight into the current state of the pool, whether it is initialized or uninitialized, and retrieve relevant metrics like liquidity, price, and fee rates. + +The SDKs offer three main functions to help developers monitor the pools: +- **Fetch Splash Pool**: Fetches the details of a specific Splash Pool. +- **Fetch Concentrated Liquidity Pool**: Fetches the details of a specific Concentrated Liquidity Pool. +- **Fetch Pools**: Fetches all possible liquidity pools between two token mints, with various tick spacings. + +### Initialized vs. Uninitialized Pools +> Skip this section if you're using Splash Pools. + +Each token pair can have multiple pools based on different tick spacings, corresponding to various fee tiers. When using the Fetch Concentrated Liquidity Pool function, it’s possible to request a pool with a tick spacing that hasn't been used to create a pool for the given token pair. In this case, you’ll receive a pool object with default parameters and an additional field `initialized = false`, indicating that the pool has not been set up. + +Similarly, when using Fetch Pools, which iterates through all possible tick spacings for a given token pair, uninitialized pools can also be returned in this manner. The function will return both initialized and uninitialized pools, allowing you to identify pools that have not yet been created. + +## 2. Getting Started Guide + +### Fetching a Splash Pool + +1. **Token Mint Addresses**: Provide the mint addresses of the two tokens that make up the liquidity pool. +2. **Fetch Pool Details**: Use the appropriate function to fetch the details of the specified Splash Pool. + +```tsx +const poolInfo = await fetchSplashPool( + rpc, + tokenMintOne, + tokenMintTwo +); +``` + +### Fetching a Concentrated Liquidity Pool + +1. **Token Mint Addresses**: Provide the mint addresses of the two tokens that make up the liquidity pool. +2. **Tick Spacing**: Specify the tick spacing, which defines the intervals for price ticks. +3. **Fetch Pool Details**: Use the appropriate function to fetch the details of the specified Concentrated Liquidity Pool. + +```tsx +const poolInfo = await fetchConcentratedLiquidityPool( + rpc, + tokenMintOne, + tokenMintTwo, + tickSpacing +); +``` + +### Fetching Pools by Token Pairs + +1. **Token Mint Addresses**: Provide the mint addresses of the two tokens that make up the liquidity pool. +2. **Fetch Pool Details**: Use the appropriate function to fetch the details of the specified pools. + +```tsx +const pools = await fetchWhirlPools( + rpc, + tokenMintOne, + tokenMintTwo +); +``` \ No newline at end of file diff --git a/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/01-Open Position.md b/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/01-Open Position.md new file mode 100644 index 00000000..ff490726 --- /dev/null +++ b/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/01-Open Position.md @@ -0,0 +1,93 @@ +--- +sidebar_label: Open a position +--- + +# Opening a Position + +Opening a position in liquidity pools on Orca is a fundamental step for providing liquidity and earning fees. In this guide, we'll explore how to open a position in both **Splash Pools** and **Concentrated Liquidity Pools**, their differences, and which approach is suitable for different use cases. + +## 1. Introduction to Positions in Pools + +A position in a liquidity pool represents your contribution of liquidity, which allows traders to swap between tokens while you earn a share of the trading fees. When you open a position, you decide how much liquidity to add, and this liquidity can later be adjusted or removed. + +- **Splash Pools**: Provide liquidity without specifying a price range. Ideal for those seeking a simple way to start providing liquidity. + +- **Concentrated Liquidity Pools**: Allow you to provide liquidity within a specified price range, enabling higher capital efficiency but requiring more advanced management. + +Upon creation of the position, an NFT will be minted to represent ownership of the position. This NFT is used by the program to verify your ownership when adjusting liquidity, harvesting rewards, or closing the position. + +> ⚠️ **Risk of Divergence loss**: The ratio of Token A to Token B that you deposit as liquidity is determined by several factors, including the current price. As trades occur against the pool, the amounts of Token A and Token B in the pool — and in your position — will change, which affects the price of the tokens relative to each other. This can work to your advantage, but it may also result in the combined value of your tokens (including any earned fees and rewards) being lower than when you initially provided liquidity. + +> ⚠️ Do not burn the position NFT, as burning it will result in the indefinite loss of your position and liquidity. + +## 2. Getting Started Guide + +Before opening a position, ensure you have completed the environment setup: +- **RPC Setup**: Use a Solana RPC client to communicate with the blockchain. +- **Wallet Creation**: Create a wallet to interact with the Solana network. +- **Devnet Airdrop**: Fund your wallet with a Solana Devnet airdrop to cover transaction fees. + +For more details, refer to our [Environment Setup Guide](../01-Environment%20Setup.md) + +### Opening a Position in Splash Pools + +1. **Pool Address**: Provide the address of the Splash Pool where you want to open a position. +2. **Liquidity Parameters**: Choose how you want to provide liquidity. You only need to provide one of these parameters, and the function will compute the others in the returned quote based on the current price of the pool: + - `liquidity`: Specify the liquidity value to provide. + - `tokenA`: Specify the amount of token A (first token in the pool). + - `tokenB`: Specify the amount of token B (second token in the pool). +3. **Slippage Tolerance**: Set the maximum slippage tolerance (optional, defaults to 1%). Slippage refers to the difference between the expected price and the actual price at which the transaction is executed. A lower slippage tolerance reduces the risk of price changes during the transaction but may lead to failed transactions if the market moves too quickly. +4. **Funder**: This will be your wallet, which will fund the transaction. +5. **Create Instructions**: Use the appropriate function to generate the necessary instructions. + ```tsx + const { quote, instructions, initializationCost } = await openFullRangePositionInstructions( + devnetRpc, + poolAddress, + param, + slippageTolerance, + wallet + ); + ``` +6. **Submit Transaction**: Include the generated instructions in a Solana transaction and send it to the network using the Solana SDK. Ensure that you have enough of both Token A and Token B as calculated in the quote, or the transaction will fail. + +### Opening a Position in Concentrated Liquidity Pools + +1. **Pool Address**: Provide the address of the Concentrated Liquidity Pool where you want to open a position. +2. **Liquidity Parameters**: Choose how you want to provide liquidity. You only need to provide one of these parameters, and the function will compute the others in the returned quote based on the price range and the current price of the pool: + - `liquidity`: Specify the liquidity value to provide. + - `tokenA`: Specify the amount of token A (first token in the pool). + - `tokenB`: Specify the amount of token B (second token in the pool). +3. **Price Range**: Set the lower and upper bounds of the price range within which your liquidity will be active. The current price and the specified price range will influence the quote amounts. If the current price is in the middle of your price range, the ratio of token A to token B will reflect that price. However, if the current price is outside your range, you will only deposit one token, resulting in one-sided liquidity. Note that your position will only earn fees when the price falls within your selected price range, so it’s important to choose a range where you expect the price to remain active. +3. **Slippage Tolerance**: Set the maximum slippage tolerance (optional, defaults to 1%). Slippage refers to the difference between the expected token amounts and the actual amounts deposited into the liquidity pool. A lower slippage tolerance reduces the risk of depositing more tokens than expected but may lead to failed transactions if the market moves too quickly. For example, if you expect to deposit 100 units of Token A and 1,000 units of Token B, with a 1% slippage tolerance, the maximum amounts would be 101 Token A and 1,010 Token B. +4. **Funder**: This can be your wallet, which will fund the pool initialization. If the funder is not specified, the default wallet will be used. You can configure the default wallet through the SDK. +5. **Create Instructions**: Use the appropriate function to generate the necessary instructions. + ```tsx + const { quote, instructions, initializationCost } = await openPositionInstructions( + rpc, + poolAddress, + param, + slippageTolerance, + wallet + ); + ``` +6. **Submit Transaction**: Include the generated instructions in a Solana transaction and send it to the network using the Solana SDK. Ensure that you have enough of both Token A and Token B as calculated in the quote, or the transaction will fail. + +> ⚠️ You cannot use this function on Splash Pools, as this function is specifically for Concentrated Liquidity Pools. + +## 3. Usage examples + +### Opening a Position in a Splash Pool + +Suppose you want to provide 1,000,000 tokens of Token A at a price of 0.0001 SOL. You will also need to provide 100 SOL as Token B to match the price. By using the SDK to open full range positions, you ensure that your liquidity is spread evenly across all price levels. This approach is ideal if you are launching a new token and want to facilitate easy swaps for traders. + +### Opening a Position in a Concentrated Liquidity Pool + +If you want to maximize capital efficiency, you can open a position in a Concentrated Liquidity Pool. For example, if the current price is at 0.01 and you want to maximize profitability, you could use the SDK to deposit liquidity between the price range of 0.009 and 0.011. This approach allows you to focus your liquidity in a narrow range, making it more effective and potentially more profitable. + +## Next Steps + +After opening a position, you can: +- [Add or Remove Liquidity](03-Adjust%20Liquidity.md): Adjust the amount of liquidity in your position based on market conditions. +- [Harvest Rewards](04-Harvest.md): Collect rewards and fees without closing the position. +- [Monitor Performance](02-Fetch%20Positions.md): Track your position's performance and earned fees. +- [Close Position](05-Close%20Position.md): When you decide to exit, close the position and withdraw the provided tokens along with any earned fees. \ No newline at end of file diff --git a/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/02-Fetch Positions.md b/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/02-Fetch Positions.md new file mode 100644 index 00000000..2a0e5f6e --- /dev/null +++ b/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/02-Fetch Positions.md @@ -0,0 +1,43 @@ +--- +sidebar_label: Fetch Positions +--- + +# Fetching Positions + +Retrieving details about positions held in liquidity pools is an essential part of managing your liquidity and monitoring performance. This guide explains how to use the SDK to gather information about all active positions held by a given wallet. + +## 1. Overview of Fetching Positions + +Fetching positions helps developers retrieve information on liquidity positions associated with a specific wallet. It scans the Solana blockchain for token accounts owned by the wallet, determines which ones represent positions, and decodes the data to provide detailed information about each position. + +With this function, you can: +- Identify all liquidity positions held by a wallet. +- Gather information about liquidity, price ranges, and fees earned. + +## 2. Getting Started Guide + +### Fetching Positions for a Wallet + +Fetching positions is a straightforward process: + +1. **RPC Client**: Use a Solana RPC client to interact with the blockchain. +2. **Wallet Address**: Provide the wallet address of the user whose positions you want to fetch. +3. **Fetch Positions**: Use the appropriate function to retrieve all positions held by the specified wallet. + +```tsx +const positions = await fetchPositionsForOwner(rpc, wallet.address); +``` + +## 3. Usage example + +Suppose you want to monitor all active positions held by a wallet. By using the SDK to fetch positions, you can retrieve detailed information about each position, including liquidity amounts, associated pools, and earned rewards. This data can also be used to build a bot that rebalances or repositions liquidity according to a strategy defined by an algorithmic trader. Monitoring position performance helps in making informed decisions about adjusting, rebalancing, or closing positions. + +## 4. Next steps + +After fetching positions, you could: + +- [Add or Remove Liquidity](03-Adjust%20Liquidity.md): Adjust the amount of liquidity in your position based on market conditions. +- [Harvest Rewards](04-Harvest.md): Collect rewards and fees without closing the position. +- [Close Position](05-Close%20Position.md): When you decide to exit, close the position and withdraw the provided tokens along with any earned fees. + +By fetching the positions, you gain visibility into your liquidity positions and can take necessary actions to optimize returns. \ No newline at end of file diff --git a/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/03-Adjust Liquidity.md b/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/03-Adjust Liquidity.md new file mode 100644 index 00000000..2409cb2c --- /dev/null +++ b/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/03-Adjust Liquidity.md @@ -0,0 +1,57 @@ +--- +sidebar_label: Adjust Liquidity +--- + +# Adjusting Liquidity in Your Positions + +Once you’ve opened a position in an Orca Whirlpool, you may need to adjust the amount of liquidity you've provided to align with market conditions or your strategy. Whether you want to add more liquidity to capture additional fees or withdraw liquidity to reduce exposure or realize profits, the Whirlpools SDK provides functions for both. + +This guide explains how to use the SDK functions to increase and decrease the liquidity in your position. + +## 1. Overview of Adjusting Liquidity + +The SDK functions for increasing or decreasing liquidity work similarly, enabling you to modify the liquidity of an existing position. You can specify the liquidity directly or provide amounts of token A or token B to increase or decrease liquidity. + +With these functions, you can: +- Increase liquidity to potentially earn more fees as trading volume grows. +- Decrease liquidity to reduce exposure or withdraw profits. + +## 2. Getting Started Guide + +### Adjusting Liquidity in a Position + +Adjusting liquidity in an existing position can be done as follows: + +1. **RPC Client**: Use a Solana RPC client to interact with the blockchain. +2. **Position Mint**: Provide the mint address of the NFT representing your position. This NFT serves as proof of ownership of the position you want to adjust. +3. **Liquidity Parameters**: Choose how you want to adjust liquidity. You only need to provide one of these parameters, and the function will compute the others in the returned quote based on the current price of the pool and the price range of the position: + - `liquidity`: Specify the liquidity value to add or remove. + - `tokenA`: Specify the amount of token A to add or withdraw. + - `tokenB`: Specify the amount of token B to add or withdraw. +4. **Slippage tolerance**: Set the maximum slippage tolerance (optional, defaults to 1%). Slippage refers to the difference between the expected token amounts added or removed when adjusting liquidity and the actual amounts that are ultimately deposited or withdrawn. A lower slippage tolerance reduces the risk of depositing or withdrawing more or fewer tokens than intended, but it may lead to failed transactions if the market moves too quickly. +5. **Funder**: This can be your wallet, which will fund the pool initialization. If a funder is not specified, the default wallet will be used. You can configure the default wallet through the SDK. +6. **Create Instructions**: Use the appropriate function to generate the necessary instructions. + ```tsx + const {quote, instructions, initializationCost} = await increaseLiquidityInstructions( + rpc, + positionMint, + param, + slippageTolerance, + wallet + ) + ``` +7. **Submit Transaction**: Include the generated instructions in a Solana transaction and send it to the network using the Solana SDK. + +## 3. Usage example + +You are creating a bot to manage investors' funds and want to optimize returns. Such a bot could rebalance liquidity based on market signals to maintain a specific target price range or to optimize fee collection during periods of high volatility. + +## 4. Next steps + +After adjusting liquidity, you can: + +- [Monitor Performance](02-Fetch%20Positions.md): Track your adjusted position to evaluate its performance and earned fees. +- [Harvest Rewards](04-Harvest.md): Collect any earned fees and rewards without closing your position. +- Make Further Adjustments: Depending on market conditions, continue to adjust liquidity as needed to maximize returns or manage risk. + +By using the SDK to adjust liquidity, you gain flexibility in managing your positions and optimizing your liquidity provision strategy. \ No newline at end of file diff --git a/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/04-Harvest.md b/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/04-Harvest.md new file mode 100644 index 00000000..f83c436a --- /dev/null +++ b/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/04-Harvest.md @@ -0,0 +1,47 @@ +--- +sidebar_label: Harvest +--- + +# Harvesting a Position + +Harvesting a position in Orca Whirlpools allows you to collect any accumulated fees and rewards without closing the position. This process is useful when you want to claim your earnings while keeping your liquidity active in the pool, ensuring you continue to benefit from potential future fees. + +## 1. Overview of Harvesting a Position + +The SDK helps you generate the instructions needed to collect fees and rewards from a position without closing it. This allows you to realize your earnings while maintaining liquidity in the pool. + +With this function, you can: +- Collect accumulated trading fees from your position. +- Harvest rewards earned by providing liquidity, all while keeping the position active. + +## 2. Getting Started Guide + +### Step-by-Step Guide to Harvesting a Position + +To harvest fees and rewards from a position, follow these steps: +1. **RPC Client**: Use a Solana RPC client to interact with the blockchain. +2. **Position Mint**: Provide the mint address of the NFT representing your position. This NFT serves as proof of ownership and represents the liquidity in the position. +3. **Authority**: This can be your wallet, which will fund the pool initialization. If the authority is not specified, the default wallet will be used. You can configure the default wallet through the SDK. +4. **Create Instructions**: Use the appropriate function to generate the necessary instructions to harvest fees and rewards. +```tsx + const { feesQuote, rewardsQuote, instructions } = await harvestPositionInstructions( + rpc, + positionMint, + wallet + ); +``` +5. **Submit Transaction**: Include the generated instructions in a Solana transaction and send it to the network using the Solana SDK. + +## 3. Usage Example + +Suppose you are a developer creating a bot to manage investments for a group of investors. The bot periodically collects accumulated fees and rewards from liquidity positions to distribute profits among investors. By using the SDK, you can generate the instructions to collect earnings from each active position without closing it, allowing the liquidity to continue generating returns and potentially reinvest your earned fees into the position. + +## 4. Next Steps + +After harvesting fees and rewards, you can: + +- [Monitor Performance](02-Fetch%20Positions.md): Keep track of your position to evaluate future earnings and the overall performance. +- Reinvest Earnings: Use the harvested fees and rewards to add more liquidity or diversify your positions. +- Harvest Regularly: Regularly collect your earnings to maintain optimal capital efficiency while keeping your liquidity active. + +By using the SDK, you can maximize the benefits of providing liquidity while keeping your position open and continuously earning fees. \ No newline at end of file diff --git a/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/05-Close Position.md b/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/05-Close Position.md new file mode 100644 index 00000000..fa600582 --- /dev/null +++ b/docs/whirlpool/docs/03-Whirlpools SDK/03-Position Management/05-Close Position.md @@ -0,0 +1,45 @@ +--- +sidebar_label: Close Position +--- + +# Close a Position + +Once you've provided liquidity in a pool, there may come a time when you want to close your position entirely. The SDK allows you to fully remove liquidity from the pool, collect any outstanding fees and rewards, and close the position. This is useful when you want to exit the pool, either to realize profits or to reallocate capital to other opportunities. + +This guide explains how to use the SDK to close a position. + +## 1. Overview of Closing a Position + +When using the SDK to fully close a liquidity position, you generate all the necessary instructions. It performs the following key actions: + +1. Collect Fees: Retrieves any fees earned from trades involving your liquidity. +2. Collect Rewards: Retrieves any rewards you've accumulated for the pool. +3. Decrease Liquidity: Removes any remaining liquidity in the position. +4. Close Position: Closes the position and returns the tokens in your account. + + +## 2. Getting Started Guide + +### Closing a Position + +To close a position and withdraw all liquidity, follow these steps: +1. **RPC Client**: Use a Solana RPC client to interact with the blockchain. +2. **Position Mint**: Provide the mint address of the NFT representing your position. This NFT serves as proof of ownership and represents the liquidity in the position. +3. **Parameters for Liquidity**: Define the parameters for decreasing liquidity. This can be specified as a liquidity amount or as specific token amounts. +4. **Slippage Tolerance**: Set the maximum slippage tolerance (optional, defaults to 1%). Slippage refers to the difference between the expected token amounts you receive when closing a position and the actual amounts returned to your wallet. A lower slippage tolerance reduces the risk of receiving fewer tokens than expected but may lead to failed transactions if the market moves too quickly. For example, if you expect to receive 100 units of Token A and 1,000 units of Token B when closing your position, with a 1% slippage tolerance, the minimum amounts returned would be 99 Token A and 990 Token B. +5. **Authority**: This can be your wallet, which will fund the pool initialization. If the authority is not specified, the default wallet will be used. You can configure the default wallet through the SDK. +6. **Create Instructions**: Use the appropriate function to generate the necessary instructions. + ```tsx + const { instructions, quote, feesQuote, rewardsQuote } = await closePositionInstructions( + rpc, + positionMint, + param, + slippageTolerance, + wallet + ); + ``` +7. **Submit Transaction**: Include the generated instructions in a Solana transaction and send it to the network using the Solana SDK. + +## 3. Usage Example + +Suppose your trading strategy predicts that the current price range will lead to divergence loss, and you need to close the position to avoid further losses. Using the SDK, you can generate the instructions to collect all accumulated fees, rewards, and remove liquidity to prevent further losses. diff --git a/docs/whirlpool/docs/03-Whirlpools SDK/04-Trade.md b/docs/whirlpool/docs/03-Whirlpools SDK/04-Trade.md new file mode 100644 index 00000000..f31108a8 --- /dev/null +++ b/docs/whirlpool/docs/03-Whirlpools SDK/04-Trade.md @@ -0,0 +1,57 @@ +--- +sidebar_label: Trade +--- + +# Executing a Token Swap + +You can use the SDK to execute a token swap on Orca. Whether you're swapping a specific amount of input tokens or looking to receive a precise amount of output tokens, this function handles the preparation of token accounts, liquidity data, and instruction assembly. It also manages slippage tolerance to ensure that swaps are executed within acceptable price changes. + +This guide explains how to use the SDK to perform a token swap in an Orca Whirlpool. + +## 1. Overview of Executing a Token Swap + +The SDK allows you to swap tokens between different pools on Orca. It handles the calculation of token amounts, manages slippage, and assembles the necessary instructions for executing the swap. + +With this function, you can: +- Swap an exact amount of input tokens for the maximum possible output. +- Specify the desired amount of output tokens and determine the necessary input. +- Control slippage to manage your risk during volatile market conditions. + +## 2. Getting Started Guide + +Before creating a Splash Pool or a Concentrated Liquidity Pool, ensure you have completed the environment setup: +- **RPC Setup**: Use a Solana RPC client to communicate with the blockchain. +- **Wallet Creation**: Create a wallet to interact with the Solana network. +- **Devnet Airdrop**: Fund your wallet with a Solana devnet airdrop to cover transaction fees. + +For more details, refer to our [Environment Setup Guide](./01-Environment%20Setup.md) + +### Executing a Token Swap +To execute a token swap in an Orca Whirlpool, follow these steps: + +1. **RPC Client**: Use a Solana RPC client to interact with the blockchain. +2. **Pool Address**: Provide the address of the Orca Whirlpool pool where the swap will take place. +3. **Swap Parameters**: Define the swap parameters. You only need to provide one of these parameters, and the function will compute the others in the returned quote based on the current price of the pool: + - `inputAmount`: Specify the amount of tokens to swap (if exact input). + - `outputAmount`: Specify the desired amount of tokens to receive (if exact output). + - `mint`: Provide the mint address of the token you want to swap out. +4. **Slippage tolerance**: Set the maximum slippage tolerance (optional, defaults to 1%). Slippage refers to the difference between the expected amounts of tokens received or sent during the swap and the actual amounts executed. A lower slippage tolerance reduces the risk of receiving fewer tokens than expected, but may lead to failed transactions if the market moves too quickly. For example, if you expect to receive 1,000 units of Token B for 100 units of Token A, with a 1% slippage tolerance, the maximum Token A spent will be 101, and the minimum Token B received will be 990. +5. **Signer**: This can be your wallet, which will fund the pool initialization. If a signer is not specified, the default wallet will be used. You can configure the default wallet through the SDK. +6. **Create Instructions**: Use the appropriate function to generate the necessary instructions for the swap. + ```tsx + const { instructions, quote } = await swapInstructions( + rpc, + { + inputAmount: amount, + mint: mintAddress + }, + poolAddress, + slippageTolerance, + wallet + ); + ``` +7. **Submit Transaction**: Include the generated instructions in a Solana transaction and send it to the network using the Solana SDK. + +### 3. Example Usage + +Suppose you are developing an arbitrage bot that looks for price discrepancies between different liquidity pools on Orca. By using the SDK, the bot can retrieve the quote object for a potential swap, which includes details about the token amounts and expected output. The bot can quickly compare quotes from multiple pools to identify arbitrage opportunities and execute profitable swaps. diff --git a/docs/whirlpool/docs/04-Tutorials/01-Token Project.md b/docs/whirlpool/docs/04-Tutorials/01-Token Project.md new file mode 100644 index 00000000..1da6a473 --- /dev/null +++ b/docs/whirlpool/docs/04-Tutorials/01-Token Project.md @@ -0,0 +1,7 @@ +--- +sidebar_label: Token Project +--- + +# A Complete Token Project: Start to Finish + +Coming Soon \ No newline at end of file diff --git a/docs/whirlpool/docs/home.md b/docs/whirlpool/docs/home.md deleted file mode 100644 index cf5702cd..00000000 --- a/docs/whirlpool/docs/home.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -sidebar_position: 1 -slug: / ---- - -# Readme - -Coming soon diff --git a/docs/whirlpool/docusaurus.config.js b/docs/whirlpool/docusaurus.config.js index 363eda93..16f14c8f 100644 --- a/docs/whirlpool/docusaurus.config.js +++ b/docs/whirlpool/docusaurus.config.js @@ -19,15 +19,11 @@ export default { locales: ["en"], }, - markdown: { - format: "md", - }, - staticDirectories: ["static", "../ts/dist", "../legacy/dist", "../rust/dist"], presets: [ [ - "classic", + "@docusaurus/preset-classic", { docs: { routeBasePath: "/", diff --git a/docs/whirlpool/src/theme/DocCard/index.js b/docs/whirlpool/src/theme/DocCard/index.js new file mode 100644 index 00000000..5771c865 --- /dev/null +++ b/docs/whirlpool/src/theme/DocCard/index.js @@ -0,0 +1,95 @@ +import React from 'react'; +import clsx from 'clsx'; +import Link from '@docusaurus/Link'; +import { + useDocById, + findFirstSidebarItemLink, +} from '@docusaurus/plugin-content-docs/client'; +import {usePluralForm} from '@docusaurus/theme-common'; +import isInternalUrl from '@docusaurus/isInternalUrl'; +import {translate} from '@docusaurus/Translate'; +import Heading from '@theme/Heading'; +import styles from './styles.module.css'; + +function useCategoryItemsPlural() { + const {selectMessage} = usePluralForm(); + return (count) => + selectMessage( + count, + translate( + { + message: '1 item|{count} items', + id: 'theme.docs.DocCard.categoryDescription.plurals', + description: + 'The default description for a category card in the generated index about how many items this category includes', + }, + {count}, + ), + ); +} +function CardContainer({href, children}) { + return ( + + {children} + + ); +} +function CardLayout({href, icon, title, description}) { + return ( + + + {icon} {title} + + {description && ( +

+ {description} +

+ )} + + ); +} +function CardCategory({item}) { + const href = findFirstSidebarItemLink(item); + const categoryItemsPlural = useCategoryItemsPlural(); + // Unexpected: categories that don't have a link have been filtered upfront + if (!href) { + return null; + } + return ( + + ); +} +function CardLink({item}) { + const icon = isInternalUrl(item.href) ? '📄️' : '🔗'; + const doc = useDocById(item.docId ?? undefined); + return ( + + ); +} +export default function DocCard({item}) { + switch (item.type) { + case 'link': + return ; + case 'category': + return ; + default: + throw new Error(`unknown item type ${JSON.stringify(item)}`); + } +} diff --git a/docs/whirlpool/src/theme/DocCard/styles.module.css b/docs/whirlpool/src/theme/DocCard/styles.module.css new file mode 100644 index 00000000..9669ff3a --- /dev/null +++ b/docs/whirlpool/src/theme/DocCard/styles.module.css @@ -0,0 +1,28 @@ +.cardContainer { + --ifm-link-color: var(--ifm-color-emphasis-800); + --ifm-link-hover-color: var(--ifm-color-emphasis-700); + --ifm-link-hover-decoration: none; + + margin-bottom: var(--ifm-paragraph-margin-bottom); + box-shadow: 0 1.5px 3px 0 rgb(0 0 0 / 15%); + border: 1px solid var(--ifm-color-emphasis-200); + transition: all var(--ifm-transition-fast) ease; + transition-property: border, box-shadow; +} + +.cardContainer:hover { + border-color: var(--ifm-color-primary); + box-shadow: 0 3px 6px 0 rgb(0 0 0 / 20%); +} + +.cardContainer *:last-child { + margin-bottom: 0; +} + +.cardTitle { + font-size: 1.2rem; +} + +.cardDescription { + font-size: 0.8rem; +}