How orca-so/typescript-sdk works
Project Type and Purpose
• The project is a legacy TypeScript SDK for the Orca platform (specifically providing support for the now-deprecated “legacy pools”). Its purpose is to offer a collection of APIs to facilitate integration with Orca’s liquidity pools, token swaps, liquidity deposits/withdrawals, and farming operations on the Solana blockchain.
• The README makes it clear that developers use this SDK to interact with Orca’s trading, liquidity, and farm mechanisms, and that the underlying network interactions are done over Solana (using libraries like @solana/web3.js).
Analyzing the File Structure
• Top-Level Files & Configs: The presence of configuration files (.eslintrc, .prettierrc, tsconfig.json, package.json) indicates a well-structured, type-safe library.
• Constants Directory: Under “src/constants” you see various files for general and network-specific configurations (e.g., devnet-specific constants for farms, pools, and tokens). This is used to configure key parameters and addresses for different networks.
• Model Directory: The “src/model” folder contains the core business logic implementations. There are submodules dedicated to “orca”, which is further divided into nested components like “farm” and “pool”. This segment encapsulates the actual operations and algorithms (e.g., quote building, farm types, pool operations) that drive the SDK.
• Public Directory: The “src/public” folder exposes the SDK’s API components. Notice that there are separate subdirectories for “devnet”, “farms”, “main”, “pools”, and extensive utility folders. This layout clearly separates the externally accessible interfaces from internal logic.
• Utilities: Under “src/public/utils” you have helper functions (for numbers, web3 interactions, time, etc.) crucial for transforming and building the necessary blockchain interactions.
• Test Directory: The “test” folder shows unit and integration tests that cover key model and utility modules.
a. Main Components to Include:
• API Consumer/Application Layer: Represents the client code that uses the SDK (as demonstrated in the README’s example usage).
• Public API Layer: (src/public) This is the interface provided to developers, exposing core functionalities like pool swaps, deposits/withdrawals, and farm operations.
• Business Logic/Model Layer: (src/model) Contains the implementation of core functionalities – the orca modules for pools, farms, quote builders, etc.
• Configuration Layer: (src/constants) This module hosts configuration data for network-specific details such as pool addresses, token parameters, and farm configurations.
• Utility/Helper Layer: (src/public/utils) Provides helper functions for handling numbers (Decimal, OrcaU64 conversions), web3-specific operations, and transaction building, which are essential for blockchain interactions.
• External Blockchain Integration: Include the external Solana network (as well as its token program, SPL token swap contracts) which the SDK interacts with via @solana/web3.js.
b. Relationships and Interactions:
• The API Consumer calls public-facing functions from the Public API Layer.
• The Public API Layer uses the Model Layer classes to execute operations like token swaps, liquidity management, and farm operations.
• The Model Layer depends on the Constants to get preconfigured values (like token addresses, pool configuration) and leverages Utility functions for calculations, formatting, and blockchain transaction assembly.
• Transactions and network operations flow from the SDK to the External Blockchain (e.g., Solana mainnet or devnet), via the web3 connection.
c. Highlighting Architectural Patterns:
• Modular separation: Clear separation between configuration (constants), domain logic (model), and interface (public).
• Abstraction & Reusability: Utilities for handling common tasks (decimal arithmetic, token formatting, web3 instruction handling) are extracted to keep components decoupled.
• Environment Segmentation: Presence of both “devnet” and “main” directories under public and constants shows that the SDK supports different operational environments in a neat, segregated manner.
d. Relevant Technologies and Frameworks:
• TypeScript: Ensures type safety and clarity across all layers.
• @solana/web3.js: Used for blockchain interactions with the Solana network.
• Decimal.js: Handling high-precision arithmetic for token/value operations.
• Testing frameworks like Jest (jest.config.js present) for quality assurance.
• Various design libraries (orchestrated through specific directories like “orca-factory”, “quote-builder”, etc.) that model the business logic.
Instructing the Principal Software Engineer to Include the Following
• Clearly labeled components for each module:
• “API Consumer / Client Code”
• “Public API Layer (src/public)” – with submodules if applicable (Farms, Pools, Main, Devnet)
• “Business Logic / Model Layer (src/model)” – distinguishing between pool logic, farm logic, and quote building.
• “Configuration Layer (src/constants)” – with nodes for mainnet and devnet configurations.
• “Utility Layer (src/public/utils)” – indicating clusters for numbers, web3 operations, and instructions.
• “External Blockchain” – Solana network, showing its key contracts (SPL Token Swap, etc).
• From the Client Application to the Public API.
• From the Public API to the Model and Utility layers.
• Outbound from Model/Utilities to the External Blockchain.
• Annotations where needed to explain interaction details, such as the conversion of Decimal values to OrcaU64 and the role of web3 instructions in transaction building.