@picon-finance/dlmm-sdk 1.18.2 → 1.18.3

package/README.md

@@ -1,6 +1,9 @@
 # @picon-finance/dlmm-sdk
 
-TypeScript SDK for the [Picon DLMM](https://github.com/picon-finance) protocol on Solana, built on [`@solana/kit`](https://github.com/anza-xyz/kit).
+TypeScript SDK for the [Picon DLMM](https://github.com/picon-finance) protocol on Solana,
+built on [`@solana/kit`](https://github.com/anza-xyz/kit).
+
+Full protocol and integration docs: **[docs.picon.finance](https://docs.picon.finance)**.
 
 ## Install
 
@@ -23,9 +26,13 @@ supported consumption splits into two scenarios:
 
 ## Usage
 
-The SDK is built around stateful classes (`DlmmProgram`, `Pool`, `Position`, `BinArray`) that cache on-chain state to avoid redundant RPC round trips. Every method returns unsigned `Instruction`s (never signs or sends) — build, sign, and send the transaction yourself with `@solana/kit`.
+The SDK is built around stateful classes — `DlmmProgram`, `Pool`, `Position`, `BinArray` — that
+cache on-chain state to avoid redundant RPC round trips. Every method returns unsigned
+`Instruction`s and never signs or sends; you build, sign, and send the transaction yourself with
+`@solana/kit`.
 
-For low-level access — raw instruction builders, account decoders, PDA derivation — the Codama-generated client is exposed as `generated`, and used internally by the SDK itself.
+For low-level access — raw instruction builders, account decoders, PDA derivation — the
+Codama-generated client is exposed as `generated`, and used internally by the SDK itself.
 
 ```ts
 import {
@@ -39,12 +46,13 @@ import {
   sendAndConfirmTransactionFactory,
   createSolanaRpcSubscriptions,
 } from "@solana/kit";
-import { DlmmProgram, events, DistributionMode, DEVNET_PROGRAM_ADDRESS } from "@picon-finance/dlmm-sdk";
+import { DlmmProgram, events, DistributionMode } from "@picon-finance/dlmm-sdk";
 
 const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
 
-// Omit programAddress to target mainnet; pass DEVNET_PROGRAM_ADDRESS (or your own) otherwise.
-const dlmmProgram = new DlmmProgram(rpc, DEVNET_PROGRAM_ADDRESS);
+// Omit programAddress to target mainnet. Testing against devnet instead? Import
+// DEVNET_PROGRAM_ADDRESS and pass it as the second argument here.
+const dlmmProgram = new DlmmProgram(rpc);
 
 // Fetch and cache a pool's account data, mints, and token programs in one call.
 const pool = await dlmmProgram.getPool(poolAddress);
@@ -73,6 +81,8 @@ const signedTransaction = await signTransactionMessageWithSigners(transactionMes
 
 ### Positions
 
+#### Open, deposit, claim, withdraw, close
+
 ```ts
 // Open a position and deposit in one flow.
 const openPositionIxs = await pool.openPosition(ownerSigner, positionMintSigner, {
@@ -102,13 +112,19 @@ const withdrawIxs = await position.withdraw(ownerSigner, { bpsToRemove: 5_000 })
 const closeIx = await position.close(ownerSigner);
 ```
 
-`position.data` exposes the decoded on-chain `Position` account (`pool`, `positionMint`, `lowerBinId`, `upperBinId`, `feeStates`, ...) directly from the cached account — no extra fetch needed:
+#### Reading position state
+
+`position.data` exposes the decoded on-chain `Position` account (`pool`, `positionMint`,
+`lowerBinId`, `upperBinId`, `feeStates`, ...) directly from the cached account — no extra fetch
+needed:
 
 ```ts
 console.log(position.data.lowerBinId, position.data.upperBinId);
 ```
 
-`position.getInfo()` returns a full summary: deposited amounts and the total fee a `claimFee` call would sweep right now, each in both `gross*` (before any Token-2022 transfer fee) and `net*` (what you'd actually receive) forms, plus the per-bin data they're summed from:
+`position.getInfo()` returns a full summary: deposited amounts and the total fee a `claimFee`
+call would sweep right now, each in both `gross*` (before any Token-2022 transfer fee) and
+`net*` (what you'd actually receive) forms, plus the per-bin data they're summed from:
 
 ```ts
 const info = await position.getInfo();
@@ -116,7 +132,9 @@ console.log(`Deposited: ${info.netAmountX} X / ${info.netAmountY} Y`);
 console.log(`Claimable fee: ${info.netFeeX} X / ${info.netFeeY} Y`);
 ```
 
-`info.bins` (same as calling `position.getBinInfos()` directly) is the per-bin breakdown `getInfo()` sums to produce those totals — always raw, since `gross*`/`net*` only apply once, to the aggregate:
+`info.bins` (same as calling `position.getBinInfos()` directly) is the per-bin breakdown
+`getInfo()` sums to produce those totals. It's always raw — `gross*`/`net*` only apply once,
+to the aggregate:
 
 ```ts
 for (const { bin, amountX, amountY, feeX, feeY } of position.getBinInfos()) {
@@ -124,21 +142,36 @@ for (const { bin, amountX, amountY, feeX, feeY } of position.getBinInfos()) {
 }
 ```
 
-Both are computed entirely from cached position + bin array data — `getBinInfos()` makes no RPC calls at all; `getInfo()` makes one round trip (via `Pool.getTransferFees()`) to resolve each mint's live transfer-fee rate.
+Both are computed entirely from cached position + bin array data. `getBinInfos()` makes no RPC
+calls at all; `getInfo()` makes one round trip (via `Pool.getTransferFees()`) to resolve each
+mint's live transfer-fee rate.
 
-`Pool.getTransferFees()` resolves each mint's active [Token-2022 transfer-fee](https://spl.solana.com/token-2022/extensions#transfer-fees) config from cached mint data — `undefined` per side means that mint has no `TransferFeeConfig` extension, not that the fee is zero:
+`Pool.getTransferFees()` resolves each mint's active
+[Token-2022 transfer-fee](https://spl.solana.com/token-2022/extensions#transfer-fees) config
+from cached mint data. `undefined` per side means that mint has no `TransferFeeConfig`
+extension — not that the fee is zero:
 
 ```ts
 const { transferFeeX, transferFeeY } = await pool.getTransferFees();
 ```
 
-`Pool.getFeeRates(now?)` returns the base/dynamic/total fee rate the pool would charge for a swap at `now` (defaults to the current time) — decays the dynamic fee state first, the same "clock sim" the on-chain program runs right before pricing a real swap, so this reflects what a swap would actually pay rather than the raw, potentially stale, stored volatility accumulator:
+`Pool.getFeeRates(now?)` returns the base/dynamic/total fee rate the pool would charge for a
+swap at `now` (defaults to the current time). It decays the dynamic fee state first — the same
+"clock sim" the on-chain program runs right before pricing a real swap — so this reflects what
+a swap would actually pay, rather than the raw, potentially stale, stored volatility
+accumulator:
 
 ```ts
 const { baseFeeRate, dynamicFeeRate, totalFeeRate } = await pool.getFeeRates();
 ```
 
-`swapExactIn`/`swapExactOut`/`quoteExactIn`/`quoteExactOut`/`sync` don't take a bin-array-count parameter — the quote methods always quote against the protocol max traversal window (`MAX_BIN_ARRAYS_PER_TRAVERSAL`) internally, then the matching swap method trims the bin-array set down to only what the quote says it actually needs (plus a one-array drift margin), so you never pay for more accounts than the trade is likely to touch:
+#### Swaps and quotes
+
+`swapExactIn`/`swapExactOut`/`quoteExactIn`/`quoteExactOut`/`sync` don't take a
+bin-array-count parameter. The quote methods always quote against the protocol max traversal
+window (`MAX_BIN_ARRAYS_PER_TRAVERSAL`) internally, then the matching swap method trims the
+bin-array set down to only what the quote says it actually needs (plus a one-array drift
+margin) — so you never pay for more accounts than the trade is likely to touch:
 
 ```ts
 // quoteExactIn() is a thin wrapper — same internal fetch/simulate/trim as swapExactIn(), just
@@ -161,9 +194,18 @@ const { quoteOutput: exactOutQuote, instructions: exactOutInstructions } = await
 });
 ```
 
-`Pool.sync(user, desiredBinId)` repositions the pool's active bin toward `desiredBinId` across empty bins only — also always uses the max traversal window, no count parameter.
+`Pool.sync(user, desiredBinId)` repositions the pool's active bin toward `desiredBinId` across
+empty bins only — also always uses the max traversal window, no count parameter.
+
+#### Transfer hooks
 
-If either mint carries an active Token-2022 `TransferHook` extension, `swapExactIn()`/`swapExactOut()` (and every position method below) resolve and append its extra accounts automatically — nothing to configure. `Pool.resolveTransferHookAccountsX(transferAccounts)`/`resolveTransferHookAccountsY(transferAccounts)` are exposed publicly if you need to resolve them yourself for a custom instruction.
+If either mint carries an active Token-2022 `TransferHook` extension, `swapExactIn()`/
+`swapExactOut()` (and every position method above) resolve and append its extra accounts
+automatically — nothing to configure. `Pool.resolveTransferHookAccountsX(transferAccounts)`/
+`resolveTransferHookAccountsY(transferAccounts)` are exposed publicly if you need to resolve
+them yourself for a custom instruction.
+
+#### Looking up positions
 
 Refresh a position's cached state after it changes on-chain (e.g. after a deposit lands):
 
@@ -171,7 +213,8 @@ Refresh a position's cached state after it changes on-chain (e.g. after a deposi
 await position.refresh();
 ```
 
-Look up several positions at once, e.g. every position minted to a given owner across all their pools:
+Look up several positions at once, e.g. every position minted to a given owner across all
+their pools:
 
 ```ts
 // Map<poolAddress, positionMintAddress[]>
@@ -190,7 +233,16 @@ Or fetch a single position directly if you already know its address:
 const positionByAddress = await pool.getPosition(positionAddress);
 ```
 
-Claim fees across many positions at once with `Position.claimAllFees()` — it skips positions with nothing pending (checked locally, no extra RPC) and batches the rest into `DEFAULT_POSITIONS_PER_CLAIM`-sized (overridable via a third argument) instruction groups, one per transaction, sharing a single set of ATA setup/teardown instructions across the whole batch rather than repeating them per position. All positions must belong to the same pool:
+#### Claiming across positions
+
+Claim fees across many positions at once with `Position.claimAllFees()`:
+
+- Skips positions with nothing pending (checked locally, no extra RPC).
+- Batches the rest into `DEFAULT_POSITIONS_PER_CLAIM`-sized (overridable via a third argument)
+  instruction groups, one per transaction.
+- Shares a single set of ATA setup/teardown instructions across the whole batch, rather than
+  repeating them per position.
+- Requires all positions to belong to the same pool.
 
 ```ts
 const positions = await pool.getAllPositionsByPositionMints(positionMints);
@@ -203,7 +255,12 @@ for (const claimIxs of claimTxs) {
 
 ### Price math
 
-`getBaseBinPrice(binStep)`, `getBinPrice(baseBinPrice, binId)`, and `getBinPriceFromStep(binStep, binId)` are direct `bigint` ports of the on-chain Q64.64 price math (`bin_math.rs`'s `base_bin_price`/`bin_price`/`bin_price_from_step`) — useful for computing a bin's price without an RPC round trip, e.g. when picking `lowerBinId`/`upperBinId` for a new position before it exists on-chain. `getBinPrice`/`getBinPriceFromStep` return `undefined` (mirroring the Rust `Option`) if `binId` is outside the representable range for that `binStep`:
+`getBaseBinPrice(binStep)`, `getBinPrice(baseBinPrice, binId)`, and
+`getBinPriceFromStep(binStep, binId)` are direct `bigint` ports of the on-chain Q64.64 price
+math. They're useful for computing a bin's price without an RPC round trip — e.g. when picking
+`lowerBinId`/`upperBinId` for a new position before it exists on-chain. `getBinPrice`/
+`getBinPriceFromStep` return `undefined` if `binId` is outside the representable range for that
+`binStep`:
 
 ```ts
 import { getBinPriceFromStep } from "@picon-finance/dlmm-sdk";
@@ -213,19 +270,24 @@ const rawPrice = getBinPriceFromStep(pool.data.binStep, pool.activeBinId); // Q6
 
 ### Events
 
-Event decoding and subscriptions are a separate, opt-in feature under the `events` namespace — independent of `DlmmProgram`/`Pool`/`Position`/`BinArray`:
+Event decoding and subscriptions are a separate, opt-in feature under the `events` namespace —
+independent of `DlmmProgram`/`Pool`/`Position`/`BinArray`:
 
 ```ts
 const rpcSubscriptions = createSolanaRpcSubscriptions("wss://api.mainnet-beta.solana.com");
 
+// Omit programAddress to target mainnet, same as DlmmProgram above. Testing against devnet
+// instead? Import DEVNET_PROGRAM_ADDRESS and pass it as { programAddress: DEVNET_PROGRAM_ADDRESS }.
 const unsubscribe = await events.onEvent(rpcSubscriptions, (event) => {
   console.log(event.name, event.data);
-}, { programAddress: DEVNET_PROGRAM_ADDRESS });
+});
 
 // unsubscribe() when done.
 ```
 
-`MAINNET_PROGRAM_ADDRESS` and `DEVNET_PROGRAM_ADDRESS` are both exported for convenience; omitting `programAddress` defaults to mainnet.
+`MAINNET_PROGRAM_ADDRESS` and `DEVNET_PROGRAM_ADDRESS` are both exported for convenience.
+Everywhere above that takes a `programAddress`, omitting it defaults to mainnet — pass
+`DEVNET_PROGRAM_ADDRESS` explicitly to point the same code at devnet instead.
 
 ## License
 

package/dist/picon_dlmm.json

@@ -4,7 +4,7 @@
         "name": "picon_dlmm",
         "version": "1.1.2",
         "spec": "0.1.0",
-        "description": "Created with Anchor"
+        "description": "Picon DLMM program"
     },
     "instructions": [
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picon-finance/dlmm-sdk",
-  "version": "1.18.2",
+  "version": "1.18.3",
   "description": "Typescript SDK for interacting with the Picon DLMM protocol",
   "author": "Picon Finance",
   "license": "MIT",
@@ -46,9 +46,9 @@
     "@solana-program/system": "^0.13.0",
     "@solana-program/token": "^0.15.0",
     "@solana-program/token-2022": "^0.15.0",
-    "@solana/kit": "^7.1.0",
-    "@solana/program-client-core": "^7.1.0",
-    "@solana/transaction-messages": "^7.1.0"
+    "@solana/kit": "^7.1.1",
+    "@solana/program-client-core": "^7.1.1",
+    "@solana/transaction-messages": "^7.1.1"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/picon_dlmm.json

@@ -4,7 +4,7 @@
     "name": "picon_dlmm",
     "version": "1.1.2",
     "spec": "0.1.0",
-    "description": "Created with Anchor"
+    "description": "Picon DLMM program"
   },
   "instructions": [
     {