Orca Whirlpools

The Orca Whirlpools Core SDK provides advanced functionalities for interacting with the Whirlpool Program on Solana. It is designed for Rust projects requiring precise math and quote calculations for liquidity and swap operations.

Key components include:

• Math Library: Functions for operations related to bundles, positions, prices, ticks, and tokens (e.g., determining position status or price conversions).
• Quote Library: Utility functions for generating quotes for actions like increasing liquidity, collecting fees/rewards, and swapping.

The @orca-so/whirlpools-client provides granular, low-level control for interacting with the Whirlpool Program on Solana. It is designed for advanced use cases where the high-level @orca-so/whirlpools SDK might be too abstract.

Key Features

• Codama Client: Uses generated code based on the Whirlpool Program IDL to handle the encoding and decoding of instructions and account data.
• GPA (Get Program Accounts) Filters: Utilities to selectively and efficiently fetch program account data using filters.
• PDA (Program Derived Addresses) Utilities: Helper functions to derive addresses for accounts within the Whirlpool Program.

Orca provides three distinct SDK tiers depending on the level of abstraction and control you require for interacting with the Whirlpool Program on Solana and Eclipse:

1. High-Level SDK: The recommended choice for most developers. It abstracts complex logic like tick array management, pool/position management, and swap execution. Requires Solana Kit.
2. Core SDK: A math-focused library providing essential utilities for liquidity pool calculations (e.g., position status, price conversions, and quotes for swaps or liquidity adjustments). It is written in Rust and provided as WebAssembly (Wasm) for TypeScript integration.
3. Low-Level SDK: An autogenerated SDK (via Codama from the IDL) that provides direct access to Solana accounts, instructions, and transactions. Use this if you need granular, low-level control over program operations. Requires Solana Kit.

The Whirlpools SDK suite is divided into three tiers depending on your needs for abstraction and control:

1. High-Level SDK: Recommended for most developers. It abstracts complexities like tick array management and provides simplified interfaces for managing pools, positions, and executing swaps.
2. Core SDK: Provides essential math utilities and quote calculations (e.g., position status, price conversions, and swap quotes). It is written in Rust and available as WebAssembly (Wasm) for TypeScript integration.
3. Low-Level SDK: Autogenerated from the Whirlpool Program's IDL. It provides direct access to Solana accounts, instructions, and transactions for developers requiring granular control.

The Core SDK is a specialized library for performing the mathematical operations necessary when working with liquidity pools. It is compiled to WebAssembly (Wasm) to allow seamless use within TypeScript projects. Use it for:

• Determining position status.
• Performing price conversions.
• Computing quotes for adjusting liquidity.
• Computing quotes for swaps.

The Low-Level SDK is autogenerated from the Whirlpool Interface Description Language (IDL) using Codama. It is intended for developers who need complete control over the underlying program mechanics. It provides direct access to:

• Solana accounts.
• Program instructions.
• Transactions.

Note: This SDK requires the Solana Kit to function.

The High-Level SDK is the primary recommendation for developers looking to integrate Whirlpools into applications. It builds upon the Core and Low-Level SDKs to simplify complex tasks. It is ideal for:

• Managing liquidity pools and positions.
• Executing swaps.
• Handling tick array management automatically.

Note: This SDK requires the Solana Kit to function.

Every SDK function requires a WhirlpoolDeployment to know which program and configuration to target. The SDK provides named constants for official deployments:

• WhirlpoolDeployment.mainnet: Mutable mainnet program with mainnet config.
• WhirlpoolDeployment.devnet: Mutable devnet program with devnet config.
• WhirlpoolDeployment.mainnetImmutable: Immutable mainnet program with mainnet config.
• WhirlpoolDeployment.custom(programId, configAddress): Used for local validators or forks.

If omitted, the SDK defaults to WhirlpoolDeployment.mainnet.

import { WhirlpoolDeployment } from "@orca-so/whirlpools";

const deployment = WhirlpoolDeployment.devnet;

Install the @orca-so/whirlpools-client package via npm to access low-level functionalities for interacting with the Whirlpool Program on Solana.

Important Compatibility Note: This SDK uses Solana Kit. It is not compatible with Solana Web3.js.

npm install @orca-so/whirlpools-client

To use the Orca Whirlpools Core SDK in your Rust project, add the orca_whirlpools_core crate to your Cargo.toml using cargo add.

cargo add orca_whirlpools_core

If you want to use this example outside of the monorepo, follow these steps:

1. Copy the directory to your local machine.
2. Update the package.json dependency for @orca-so/whirlpools from the workspace version to a specific published version:

   "@orca-so/whirlpools": "^{current version}"

3. Install dependencies using npm install or yarn install.
4. Start the server using npm run start or yarn start.