@elmntl/jlpd-sdk 0.2.0 → 0.13.5

package/README.md

@@ -1,469 +1,250 @@
-# JLP.D SDK
+# @elmntl/jlpd-sdk
 
-SDK for interacting with the JLP.D (JLP Deconstructed) protocol on Solana.
+TypeScript SDK for the **Elemental Vaults** on-chain stack. Wraps three Solana programs through one consistent surface so frontends, indexers, and back-end services don't need to hand-roll discriminators, PDA derivation, or account layouts.
 
-## Installation
-
-```bash
-# Using npm
-npm install git+https://github.com/elementalfund/jlpd-sdk.git
-
-# Using yarn
-yarn add git+https://github.com/elementalfund/jlpd-sdk.git
 ```
-
-Or add directly to `package.json`:
-```json
-{
-  "dependencies": {
-    "jlpd-sdk": "git+https://github.com/elementalfund/jlpd-sdk.git"
-  }
-}
-```
-
-### Peer Dependencies
-
-| Package | Version |
-|---|---|
-| `@coral-xyz/anchor` | `^0.32.1` |
-| `@solana/web3.js` | `^1.95.0` |
-| `@solana/spl-token` | `^0.4.0` |
-
-## Quick Start
-
-```typescript
-import { Connection } from "@solana/web3.js";
-import { JlpdClient } from "jlpd-sdk";
-
-// Connect to Solana mainnet
-const connection = new Connection("https://api.mainnet-beta.solana.com");
-const client = JlpdClient.mainnet(connection);
+@elmntl/jlpd-sdk
+├── /common          shared types, buffer helpers, connection type, discriminators
+├── /p-stv-core      vault management — deposits, withdraws, epochs, fees      (level N)
+├── /elemental-lend  idle-base lending sweep into Kamino + Jupiter Lend Earn   (level N − 1)
+└── /jlpd-strategy   JLP-Deconstructed yield strategy + lend-adapter wiring    (level N + 1 / N + 2)
 ```
 
-## Architecture
+## At a glance
 
-The SDK uses the Anchor IDL (`@coral-xyz/anchor` 0.32.1) for instruction serialization. All instruction builders call `program.methods.<instruction>().accounts({}).instruction()` under the hood, which ensures correct serialization from the on-chain IDL.
+| Module                       | Wraps program                                  | What it gives you                                                                                                                                                            |
+| ---------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@elmntl/jlpd-sdk/p-stv-core`     | `PSTVH77GiPqA3msXmpjAyUXdh3MytK37GCPbPzWu3Rc` | STV / GlobalConfig / WithdrawRequest / ManagerRole accounts; all 14 instruction builders (`createDepositIx`, `createClaimWithdrawIx`, `createProcessEpochIx`, `createMigrateLendIx`, …); event decoders (18 event types); the `sendSmartTx` smart sender (auto CU sim, priority fee, LUT merge); wSOL wrap/unwrap helpers; USD price fetcher |
+| `@elmntl/jlpd-sdk/elemental-lend` | `EHaGVh7p6xSxZsq4CcEEZhnV5adDvWg1gS1Rc5rLiBpC` | StrategyState / StvPosition / ManagerRole accounts; CPI + protocol instruction builders; Kamino kVault and Jupiter Lend Earn account-resolution helpers; auto-route / auto-unroute account builders for sweep flows |
+| `@elmntl/jlpd-sdk/jlpd-strategy`  | `GXqt4ZH2UUBsLWwMNJiZMXza3q7xEGChfW8XjVRjLxr5` | JlpdConfig / per-asset StrategyState / StvPosition; CPI + rebalance instruction builders (`createSwapJlpIx`, `createSettleYieldIx`, `createDepositToAdapterIx`, …); Jupiter swap quote / instruction fetchers; on-chain JLP price + custody readers |
+| `@elmntl/jlpd-sdk/common`         | (no program)                                    | Buffer reads with bounds checks, ATA derivation, the canonical `SolanaConnection` structural type, and the `StrategyStateHeader` / `StvPosition` interfaces shared across the two strategy programs |
 
-The `JlpdClient` exposes an Anchor `Program` instance for advanced use:
+## Module layout
 
-```typescript
-// Access the typed Anchor program directly
-const program = client.program;
+Every program-specific module follows the **same file shape**, so you only have to learn the pattern once:
 
-// Build instructions manually if needed
-const ix = await program.methods
-  .deposit(new BN(1_000_000_000))
-  .accounts({ user: walletPublicKey, jlpVault: client.vaultPda, /* ... */ })
-  .instruction();
 ```
+<module>/
+├── constants.ts           program ID, seeds, instruction discriminators, sizes, flags
+├── pda.ts                 findXxxPda() helpers — pure synchronous PDA derivation
+├── types.ts               account interfaces + event types
+├── accounts.ts            deserializeXxx() + fetchXxx() readers + GPA queries
+├── instructions.ts        createXxxIx() instruction builders
+├── events.ts              event decoders (p-stv-core: 1-byte disc; Anchor: 8-byte)
+└── (module-specific files)
 
-You can also create a standalone program instance:
-
-```typescript
-import { createProgram } from "jlpd-sdk";
-import type { JlpDProgram } from "jlpd-sdk";
-
-const program = createProgram(connection);
+Module-specific files:
+  p-stv-core:       remaining-accounts.ts, send-tx.ts, sol-wrap.ts, prices.ts
+  elemental-lend:   kamino-vault.ts, jupiter-lend.ts, protocol-actions.ts
+  jlpd-strategy:    swap-jlp.ts, settle-yield.ts, jlp-data.ts,
+                    jlp-borrow.ts, jupusd-earn.ts, adapter.ts
 ```
 
-## Available Pools
+Naming conventions hold across modules:
 
-| Pool       | Description |
-| ---------- | ----------- |
-| `"SOL"`    | Solana      |
-| `"USDC"`   | USD Coin    |
-| `"JupUSD"` | Jupiter USD |
-| `"BTC"`    | Bitcoin     |
-| `"ETH"`    | Ethereum    |
+| Pattern         | Returns                   | Side effects |
+| --------------- | ------------------------- | ------------ |
+| `findXxxPda`    | `[PublicKey, number]`     | none         |
+| `deserializeXxx`| typed account             | none         |
+| `fetchXxx`      | typed account             | one RPC call |
+| `createXxxIx`   | `TransactionInstruction`  | none         |
+| `buildXxx*`     | helper objects            | none         |
 
----
+`build*` is reserved for helpers that produce ephemeral data (remaining accounts, batched instruction lists). Anything that returns a wire-ready instruction is named `createXxxIx`.
 
-## User Operations
+## Naming exceptions worth knowing
 
-### Deposit
+Each program has its own `ManagerRole` PDA scoped to a different anchor account. To prevent same-named imports from shadowing each other, the helpers carry a per-program prefix:
 
-Deposit tokens and receive vault shares (jvX tokens).
+| Program         | Function                  | PDA seeds                                |
+| --------------- | ------------------------- | ---------------------------------------- |
+| p-stv-core      | `findStvManagerRolePda`   | `["manager", stv, manager]`              |
+| elemental-lend  | `findLendManagerRolePda`  | `["manager", strategy_state, manager]`   |
+| jlpd-strategy   | `findJlpdManagerRolePda`  | `["manager", config, manager]`           |
 
-```typescript
-import { BN } from "@coral-xyz/anchor";
+## Cross-cutting design
 
-const pool = client.pool("SOL");
+### `SolanaConnection` (structural type)
 
-const tx = await pool.deposit({
-  user: walletPublicKey,
-  amount: new BN(1_000_000_000), // 1 SOL (9 decimals)
-});
+Every helper that needs RPC accepts `SolanaConnection`, defined in `common/connection.ts` as a `Pick<Connection, ...>` of just the methods we use. This means callers can pass any version of `@solana/web3.js` without nominal type mismatches across SDK / consumer versions. Narrower call sites use a further `Pick` (e.g. `ProtocolActionConnection` in `elemental-lend/protocol-actions.ts` is `Pick<SolanaConnection, "getAccountInfo" | "getMultipleAccountsInfo">`).
 
-// Sign and send transaction with your wallet
-const signature = await wallet.sendTransaction(tx, connection);
-```
+### Numeric convention (BN vs number)
 
-### Withdraw
+Documented at the top of `p-stv-core/types.ts`:
 
-Burn vault shares and receive tokens back.
+- **u64 fields** are deserialized as `BN` (bn.js)
+- **u32 / u16 / u8 fields** are deserialized as plain JavaScript `number`
 
-```typescript
-const tx = await pool.withdraw({
-  user: walletPublicKey,
-  shares: new BN(500_000_000), // Amount of jvX shares to burn
-});
+Mixing the two does not auto-convert and silently truncates — when adding new fields to any account interface, follow the rule.
 
-const signature = await wallet.sendTransaction(tx, connection);
-```
+### Discriminators
 
----
+- **p-stv-core (Pinocchio)** uses 1-byte instruction discriminators (0x00–0x0C, 13 instructions). Account discriminators are still 8 bytes for Anchor compatibility.
+- **elemental-lend** and **jlpd-strategy** are Anchor 0.32.1 programs and use 8-byte instruction discriminators throughout.
+- Account discriminators that are truly shared across programs (`ManagerRole`, `StrategyState`, `StvPosition`) live once in `common/constants.ts` and are re-exported by each module.
 
-## Reading Data
+Each constant is documented inline with the source — for example `IX_ADD_MANAGER` in elemental-lend has a `// sha256("global:add_manager")[..8]` comment so an auditor can re-derive it.
 
-### Get Vault Info
+### Buffer reads
 
-```typescript
-const vault = await client.fetchVault();
+`common/buffer.ts` provides bounds-checked readers (`readPubkey`, `readU64`, `readU32`, `readU16`, `readU8`) and the corresponding writers / optional-encoders. Each read helper validates `offset + width <= data.length` and throws a descriptive `RangeError` rather than silently reading garbage when the offset is wrong.
 
-console.log("Admin:", vault.admin.toBase58());
-console.log("Manager:", vault.manager.toBase58());
-```
+### Send-tx layer
 
-### Get Pool (STV) Info
+`p-stv-core/send-tx.ts` exposes `sendSmartTx(connection, instructions, payer, signTransaction, options?)`:
 
-```typescript
-const stv = await client.fetchStv(MINTS.SOL);
-
-console.log("Price per share:", stv.pps.toString());
-console.log("Total fees accrued:", stv.accruedFeesJlx.toString());
-```
-
-### Get Exchange Rate
-
-```typescript
-const rate = await client.fetchExchangeRate("SOL");
-
-console.log("Exchange rate:", rate.rate); // e.g., 1.05 means 5% yield
-console.log("Is fresh:", rate.isFresh);
-```
+1. Pre-checks the legacy serialized size to decide if a versioned tx is needed (no double-sign).
+2. Fetches blockhash + every default LUT (lend / stv / jlpd) + Helius priority-fee in parallel.
+3. Simulates with an inflated CU limit, takes the actual `unitsConsumed`, applies a 5% buffer, and prepends the right `ComputeBudgetProgram` instructions.
+4. Falls back from legacy → versioned automatically when CU instructions push the size over `MAX_LEGACY_SIZE`.
+5. Confirms via `lastValidBlockHeight`.
 
-### Calculate APY
+The `signTransaction` callback is generic over `Transaction | VersionedTransaction` so wallets pass the same callback the SDK uses on either path. The optional `rpcUrl` field in `SmartTxOptions` is the only way the SDK reaches a Helius endpoint — it never reads private fields off the connection object.
 
-Calculate annualized return based on PPS (price per share) growth over time.
+### Address Lookup Tables
 
-```typescript
-// You need a starting PPS and timestamp (e.g., from when user deposited)
-const startPps = new BN("1000000000"); // 1.0 (9 decimals)
-const startTime = 1706140800; // Unix timestamp when PPS was recorded
+`p-stv-core/send-tx.ts` exports `DEFAULT_LUT_ADDRESSES`:
 
-// Calculate compound APY
-const apy = await client.calculateApy("SOL", startPps, startTime);
-console.log(`APY: ${(apy * 100).toFixed(2)}%`); // e.g., "APY: 12.50%"
-
-// Or calculate simple APY (non-compounded)
-const simpleApy = await client.calculateSimpleApy("SOL", startPps, startTime);
-console.log(`Simple APY: ${(simpleApy * 100).toFixed(2)}%`);
+```ts
+{
+  lend: PublicKey,   // Elemental Lend infrastructure
+  stv:  PublicKey,   // p-STV Core vaults / evMints / vault ATAs
+  jlpd: PublicKey,   // JLPD Strategy state / positions / oracles
+}
 ```
 
-**Note:** Store the user's PPS and timestamp when they deposit to calculate their personal returns later.
-
----
-
-## Manager Operations
-
-These operations require manager permissions.
-
-### Jupiter Earn (Deposit/Withdraw to Jupiter Lend)
+`sendSmartTx` always fetches all three. Consumers building transactions outside `sendSmartTx` should import these and merge them into their own LUT list. Server-side jobs (`jlpd-server/src/jobs/ltv-rebalance.ts`) use this same export — the SDK is the single source of truth.
 
-```typescript
-const pool = client.pool("SOL");
-
-// Deposit base tokens to Jupiter Lend
-const depositTx = await pool.jupEarn({
-  manager: managerPublicKey,
-  direction: "Deposit",
-  amount: new BN(1_000_000_000),
-});
+## Installation
 
-// Withdraw from Jupiter Lend
-const withdrawTx = await pool.jupEarn({
-  manager: managerPublicKey,
-  direction: "Withdraw",
-  amount: new BN(1_000_000_000),
-});
+```bash
+npm install @elmntl/jlpd-sdk
+# or
+yarn add @elmntl/jlpd-sdk
+# or
+pnpm add @elmntl/jlpd-sdk
 ```
 
-### Move Tokens Between STV and Vault
-
-```typescript
-const pool = client.pool("SOL");
+Peer dependencies must be installed in the consumer:
 
-// Move jlX tokens to vault (for JLP conversion)
-const toVaultTx = await pool.moveJlx({
-  manager: managerPublicKey,
-  direction: "ToVault",
-  jlxAmount: new BN(1_000_000_000),
-});
-
-// Move jlX tokens back from vault to STV
-const fromVaultTx = await pool.moveJlx({
-  manager: managerPublicKey,
-  direction: "FromVault",
-  jlxAmount: new BN(1_000_000_000),
-});
+```bash
+npm install @solana/web3.js@^1.95.0 @solana/spl-token@^0.4.0
 ```
 
-### Claim Fees
+## Quick examples
 
-```typescript
-const pool = client.pool("SOL");
+### Deposit base into a vault from a frontend
 
-const tx = await pool.claimFees({
-  manager: managerPublicKey,
+```ts
+import {
+  findConfigPda,
+  findStvPda,
+  findEvMintPda,
+  createDepositIx,
+  buildDepositContext,
+  sendSmartTx,
+} from "@elmntl/jlpd-sdk/p-stv-core";
+
+const [config] = findConfigPda();
+const [stv]    = findStvPda(vaultId);
+const [evMint] = findEvMintPda(vaultId);
+
+const ctx = await buildDepositContext(connection, vault);
+
+const ix = createDepositIx({
+  user, config, stv, evMint, vaultAta, baseMint, userBaseAta, userEvAta,
+  baseAmount, autoRouteCount: ctx.autoRouteCount, ...
 });
-```
 
-### Settle Yield
-
-Distributes JLP yield across all pools. Requires fetching the current JLP price.
-
-```typescript
-import { fetchJlpRate, MINTS } from "jlpd-sdk";
-
-// Fetch current JLP price from Jupiter
-const jlpRate = await fetchJlpRate(MINTS.JLP.toBase58());
-
-// Settle yield
-const admin = client.admin();
-const tx = await admin.settleYield({
-  manager: managerPublicKey,
-  jlpRate,
-});
+const sig = await sendSmartTx(
+  connection,
+  [...ctx.preInstructions, ix],
+  user,
+  signTransaction,
+);
 ```
 
----
+### Read a JLPD strategy state from a server job
 
-## Swap Operations
+```ts
+import { fetchJlpStrategyState } from "@elmntl/jlpd-sdk/jlpd-strategy";
 
-### Swap jlX to/from JLP
-
-```typescript
-const swap = client.swap();
-
-// Get a quote first
-const quote = await swap.quoteJlxJlp({
-  pool: "SOL",
-  direction: "JlxToJlp", // or "JlpToJlx"
-  amountIn: new BN(1_000_000_000),
-  slippageBps: 30, // 0.3% slippage
-});
-
-console.log("Expected output:", quote.outAmount.toString());
-console.log("Price impact:", quote.priceImpactPct, "%");
-
-// Execute the swap
-const tx = await swap.swapJlxJlp({
-  manager: managerPublicKey,
-  pool: "SOL",
-  direction: "JlxToJlp",
-  amountIn: new BN(1_000_000_000),
-  expectedOut: quote.outAmount,
-  quote,
-});
+const state = await fetchJlpStrategyState(connection, baseMint);
+console.log(`PPS: ${state.pps.toString()}`);
+console.log(`base_loaned: ${state.baseLoaned.toString()}`);
 ```
 
-### Swap Between jlX Types
+### Build a manager-only `swap_jlp` rebalance from base → JLP
 
-```typescript
-const swap = client.swap();
+```ts
+import { buildSwapJlpTransaction } from "@elmntl/jlpd-sdk/jlpd-strategy";
 
-// Get a quote
-const quote = await swap.quoteJlxJlx({
-  fromPool: "SOL",
-  toPool: "USDC",
-  amountIn: new BN(1_000_000_000),
+const result = await buildSwapJlpTransaction({
+  connection,
+  manager,
+  baseMint,
+  vaultId,
+  direction: "BaseToJlp",
+  amount: 1_000_000n,
   slippageBps: 30,
 });
 
-// Execute the swap
-const tx = await swap.swapJlxJlx({
-  manager: managerPublicKey,
-  fromPool: "SOL",
-  toPool: "USDC",
-  amountIn: new BN(1_000_000_000),
-  minOut: quote.minOutAmount,
-  quote,
-});
-```
-
----
-
-## Token Decimals Reference
-
-| Token  | Decimals | Example                 |
-| ------ | -------- | ----------------------- |
-| SOL    | 9        | `1 SOL = 1_000_000_000` |
-| USDC   | 6        | `1 USDC = 1_000_000`    |
-| JupUSD | 6        | `1 JupUSD = 1_000_000`  |
-| BTC    | 8        | `1 BTC = 100_000_000`   |
-| ETH    | 8        | `1 ETH = 100_000_000`   |
-
----
-
-## Working with BN (Big Numbers)
-
-Solana uses big integers for token amounts. Use the `BN` class:
-
-```typescript
-import { BN } from "@coral-xyz/anchor";
-
-// Create from number (small amounts only)
-const small = new BN(1000);
-
-// Create from string (recommended for large amounts)
-const large = new BN("1000000000000");
-
-// Arithmetic
-const sum = a.add(b);
-const diff = a.sub(b);
-const product = a.mul(b);
-const quotient = a.div(b);
-
-// Comparison
-a.gt(b); // greater than
-a.lt(b); // less than
-a.eq(b); // equal
-a.isZero();
-
-// Convert to display string
-const displayAmount = amount.toString();
-```
-
----
-
-## Error Handling
-
-```typescript
-import { JlpdClientError } from "jlpd-sdk";
-
-try {
-  const tx = await pool.deposit({
-    user: walletPublicKey,
-    amount: new BN(0), // Invalid amount
-  });
-} catch (error) {
-  if (error instanceof JlpdClientError) {
-    console.error("SDK Error:", error.message);
-  } else {
-    console.error("Unexpected error:", error);
-  }
-}
-```
-
----
-
-## Low-Level Instruction Builders
-
-For direct transaction construction (e.g., from a backend server), the SDK exports individual instruction builders. Each takes an Anchor `Program` instance as the first argument.
-
-```typescript
-import {
-  createProgram,
-  createDepositInstruction,
-  createWithdrawInstruction,
-  createInitOrUpdateVaultInstruction,
-  createUpdateStvInstruction,
-  createJupEarnInstruction,
-  createMoveJlxInstruction,
-  createSwapJlxJlxInstruction,
-  createSwapJlxJlpInstruction,
-  createSettleYieldInstruction,
-  createClaimFeesInstruction,
-} from "jlpd-sdk";
-
-const program = createProgram(connection);
-
-// Example: build a deposit instruction
-const ix = await createDepositInstruction(
-  program,
-  new BN(1_000_000_000),
-  {
-    user: userPubkey,
-    jlpVault: vaultPda,
-    stv: stvPda,
-    baseMint: MINTS.SOL,
-    jlMint: jlSolMint,
-    jvMint: jvSolMint,
-    userBaseAta: userSolAta,
-    userJvxAta: userJvSolAta,
-    stvBaseAta: stvSolAta,
-    stvJlxAta: stvJlSolAta,
-    tokenProgram: TOKEN_PROGRAM_ID,
-  },
-  remainingAccounts, // optional exchange rate accounts
+const sig = await sendSmartTx(
+  connection,
+  [...result.preInstructions, ...result.instructions],
+  manager,
+  signTransaction,
+  { additionalLuts: result.addressLookupTables },
 );
 ```
 
-Some accounts are auto-resolved by Anchor from the IDL (PDAs and known addresses) and should be omitted from `.accounts()`:
-
-| Instruction | Auto-resolved accounts |
-|---|---|
-| `initOrUpdateJlpVault` | `jlpVault` (PDA), `systemProgram` |
-| `initializeStv` | `stv` (PDA), `stvJlxAta` (PDA), `systemProgram`, `associatedTokenProgram`, `rent` |
-| `jupEarnDepositWithdraw` | `tokenProgram` |
-
----
-
-## Constants
-
-```typescript
-import { MINTS, JLPD_PROGRAM_ID } from "jlpd-sdk";
-
-// Token mints
-MINTS.SOL; // Native SOL mint
-MINTS.USDC; // USDC mint
-MINTS.JLP; // JLP token mint
-MINTS.WBTC; // Wrapped BTC mint
-MINTS.WETH; // Wrapped ETH mint
-
-// Program ID
-JLPD_PROGRAM_ID; // Main program address
+## Quality bar
+
+This SDK is the artifact submitted for external audit. The following invariants are enforced:
+
+- **`tsc` strict mode** with `noUnusedLocals` and `noUnusedParameters`. Zero suppressions in source.
+- **No `any`** in source code. All wallet / connection seams use proper structural types.
+- **No `@deprecated` exports.** Deprecated aliases were removed during the audit cleanup; if you find one, it's a bug.
+- **Buffer reads are bounds-checked.** Every helper in `common/buffer.ts` throws on out-of-range offsets.
+- **Discriminators are documented inline** with their derivation (`// sha256("global:deposit")[..8]`).
+- **Each module follows the same file shape** so the audit pattern is the same per program.
+
+## Project structure
+
+```
+sdk/
+├── README.md                       (this file)
+├── package.json
+├── tsconfig.json                   strict + noUnusedLocals + noUnusedParameters
+├── src/
+│   ├── index.ts                    namespace re-exports
+│   ├── common/
+│   │   ├── index.ts
+│   │   ├── constants.ts            shared discriminators, PPS_DECIMALS, BPS, staleness
+│   │   ├── connection.ts           SolanaConnection structural type
+│   │   ├── buffer.ts               bounds-checked readers / writers
+│   │   ├── ata.ts                  findAta()
+│   │   └── strategy-interface.ts   StrategyStateHeader + StvPosition + decoders
+│   ├── p-stv-core/                 vault management — Pinocchio program (13 instructions, 0x00–0x0C)
+│   │   ├── constants.ts, pda.ts, types.ts, accounts.ts, instructions.ts, events.ts
+│   │   ├── remaining-accounts.ts   context builders for deposit/claim/epoch/strategy ops
+│   │   ├── send-tx.ts              smart tx: simulate CU → priority fee → LUT → sign → confirm
+│   │   ├── sol-wrap.ts             native SOL wrap/unwrap for SOL-denominated vaults
+│   │   └── prices.ts               Jupiter Quote API USD price fetcher
+│   ├── elemental-lend/             idle-base lending — Anchor 0.32.1 program
+│   │   ├── constants.ts, pda.ts, types.ts, accounts.ts, instructions.ts
+│   │   ├── kamino-vault.ts         Kamino kVault account derivation + CPI + staleness check
+│   │   ├── jupiter-lend.ts         Jupiter Lend pool configs + auto-route account builders
+│   │   └── protocol-actions.ts     high-level protocol action tx builders
+│   └── jlpd-strategy/              JLP yield strategy — Anchor 0.32.1 program
+│       ├── constants.ts, pda.ts, types.ts, accounts.ts, instructions.ts
+│       ├── swap-jlp.ts             Jupiter swap tx builders (BaseToJlp / JlpToBase)
+│       ├── settle-yield.ts         settle_yield instruction builder
+│       ├── jlp-data.ts             JLP pool data reader (custody weights, AUM, prices)
+│       ├── jlp-borrow.ts           Jupiter Lend Borrow constants + position reading
+│       ├── jupusd-earn.ts           Jupiter Lend Earn position + APR helpers
+│       └── adapter.ts              JLPD Lend Adapter instruction builders
+├── dist/                           tsc output (published to npm; also committed for internal `file:` link consumers)
+└── scripts/
+    └── create-luts.ts              admin tool: create / extend address lookup tables
 ```
-
----
-
-## Full Example: Deposit Flow
-
-```typescript
-import { Connection, PublicKey } from "@solana/web3.js";
-import { BN } from "@coral-xyz/anchor";
-import { JlpdClient } from "jlpd-sdk";
-
-async function deposit(walletPublicKey: PublicKey, wallet: any) {
-  // 1. Create client
-  const connection = new Connection("https://api.mainnet-beta.solana.com");
-  const client = JlpdClient.mainnet(connection);
-
-  // 2. Get pool context
-  const pool = client.pool("SOL");
-
-  // 3. Check current exchange rate (optional)
-  const rate = await client.fetchExchangeRate("SOL");
-  console.log(`Current yield: ${((rate.rate - 1) * 100).toFixed(2)}%`);
-
-  // 4. Build deposit transaction
-  const tx = await pool.deposit({
-    user: walletPublicKey,
-    amount: new BN(1_000_000_000), // 1 SOL
-  });
-
-  // 5. Send transaction
-  const signature = await wallet.sendTransaction(tx, connection);
-  console.log("Transaction sent:", signature);
-
-  // 6. Confirm transaction
-  await connection.confirmTransaction(signature, "confirmed");
-  console.log("Deposit confirmed!");
-}
-```
-
----
-
-## Support
-
-For issues or questions, contact the Elemental team.