@elmntl/jlpd-sdk 0.1.0

package/README.md

@@ -0,0 +1,363 @@
+# JLP.D SDK
+
+SDK for interacting with the JLP.D (JLP Deconstructed) protocol on Solana.
+
+## 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"
+  }
+}
+```
+
+## 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);
+```
+
+## Available Pools
+
+| Pool       | Description |
+| ---------- | ----------- |
+| `"SOL"`    | Solana      |
+| `"USDC"`   | USD Coin    |
+| `"JupUSD"` | Jupiter USD |
+| `"BTC"`    | Bitcoin     |
+| `"ETH"`    | Ethereum    |
+
+---
+
+## User Operations
+
+### Deposit
+
+Deposit tokens and receive vault shares (jvX tokens).
+
+```typescript
+import { BN } from "@coral-xyz/anchor";
+
+const pool = client.pool("SOL");
+
+const tx = await pool.deposit({
+  user: walletPublicKey,
+  amount: new BN(1_000_000_000), // 1 SOL (9 decimals)
+});
+
+// Sign and send transaction with your wallet
+const signature = await wallet.sendTransaction(tx, connection);
+```
+
+### Withdraw
+
+Burn vault shares and receive tokens back.
+
+```typescript
+const tx = await pool.withdraw({
+  user: walletPublicKey,
+  shares: new BN(500_000_000), // Amount of jvX shares to burn
+});
+
+const signature = await wallet.sendTransaction(tx, connection);
+```
+
+---
+
+## Reading Data
+
+### Get Vault Info
+
+```typescript
+const vault = await client.fetchVault();
+
+console.log("Admin:", vault.admin.toBase58());
+console.log("Manager:", vault.manager.toBase58());
+```
+
+### Get Pool (STV) Info
+
+```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);
+```
+
+---
+
+## Manager Operations
+
+These operations require manager permissions.
+
+### Jupiter Earn (Deposit/Withdraw to Jupiter Lend)
+
+```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),
+});
+
+// Withdraw from Jupiter Lend
+const withdrawTx = await pool.jupEarn({
+  manager: managerPublicKey,
+  direction: "Withdraw",
+  amount: new BN(1_000_000_000),
+});
+```
+
+### Move Tokens Between STV and Vault
+
+```typescript
+const pool = client.pool("SOL");
+
+// 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),
+});
+```
+
+### Claim Fees
+
+```typescript
+const pool = client.pool("SOL");
+
+const tx = await pool.claimFees({
+  manager: managerPublicKey,
+});
+```
+
+### 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,
+});
+```
+
+---
+
+## Swap Operations
+
+### 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,
+});
+```
+
+### Swap Between jlX Types
+
+```typescript
+const swap = client.swap();
+
+// Get a quote
+const quote = await swap.quoteJlxJlx({
+  fromPool: "SOL",
+  toPool: "USDC",
+  amountIn: new BN(1_000_000_000),
+  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);
+  }
+}
+```
+
+---
+
+## 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
+```
+
+---
+
+## 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.