@panoptic-eng/sdk 1.0.4 → 1.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Axicon Labs Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -13,10 +13,16 @@ import { createPublicClient, createWalletClient, http, parseUnits } from 'viem'
 import { sepolia } from 'viem/chains'
 import { privateKeyToAccount } from 'viem/accounts'
 import {
-  getPool, fetchPoolId, approveAndWait, depositAndWait,
-  createTokenIdBuilder, simulateOpenPosition, openPositionAndWait,
-  tickLimits, formatTokenAmount,
-} from '@panoptic-eng/sdk'
+  getPool,
+  fetchPoolId,
+  approveAndWait,
+  depositAndWait,
+  createTokenIdBuilder,
+  simulateOpenPosition,
+  openPositionAndWait,
+  tickLimits,
+  formatTokenAmount,
+} from '@panoptic-eng/sdk/v2'
 
 // 1. Setup clients
 const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY')
@@ -28,13 +34,17 @@ const pool = await getPool({ client, poolAddress: '0x...', chainId: 11155111n })
 
 // 3. Approve + deposit collateral
 await approveAndWait({
-  client, walletClient, account: account.address,
+  client,
+  walletClient,
+  account: account.address,
   tokenAddress: pool.poolKey.currency0,
   spenderAddress: pool.collateralTracker0.address,
   amount: 2n ** 256n - 1n,
 })
 await depositAndWait({
-  client, walletClient, account: account.address,
+  client,
+  walletClient,
+  account: account.address,
   collateralTrackerAddress: pool.collateralTracker0.address,
   assets: parseUnits('1', 18),
 })
@@ -47,32 +57,77 @@ const tokenId = createTokenIdBuilder(poolId)
 
 const limits = tickLimits(pool.currentTick, 500n)
 const sim = await simulateOpenPosition({
-  client, poolAddress: '0x...', account: account.address,
-  tokenId, positionSize: 10n ** 15n, existingPositionIds: [],
-  tickLimitLow: limits.low, tickLimitHigh: limits.high,
+  client,
+  poolAddress: '0x...',
+  account: account.address,
+  tokenId,
+  positionSize: 10n ** 15n,
+  existingPositionIds: [],
+  tickLimitLow: limits.low,
+  tickLimitHigh: limits.high,
 })
 
 if (!sim.success) throw new Error(`Simulation failed: ${sim.error}`)
 console.log('Gas estimate:', sim.gasEstimate)
-console.log('Token0 required:', formatTokenAmount(
-  sim.data.amount0Required, BigInt(pool.collateralTracker0.decimals), 6n
-))
+console.log(
+  'Token0 required:',
+  formatTokenAmount(sim.data.amount0Required, BigInt(pool.collateralTracker0.decimals), 6n),
+)
 
 // 5. Execute
 await openPositionAndWait({
-  client, walletClient, account: account.address, poolAddress: '0x...',
-  tokenId, positionSize: 10n ** 15n, existingPositionIds: [],
-  tickLimitLow: limits.low, tickLimitHigh: limits.high,
+  client,
+  walletClient,
+  account: account.address,
+  poolAddress: '0x...',
+  tokenId,
+  positionSize: 10n ** 15n,
+  existingPositionIds: [],
+  tickLimitLow: limits.low,
+  tickLimitHigh: limits.high,
 })
 ```
 
-## Documentation
+## Feature Overview
 
-| Document | Description |
+| Category | Capabilities |
 |----------|-------------|
-| [Getting Started](./docs/GETTING_STARTED.md) | Full walkthrough: setup, deposit, build positions, simulate, trade, monitor, close |
-| [API Reference](./docs/SDK_API_REFERENCE.md) | Every exported function grouped by module with signatures and descriptions |
-| [Examples](./src/panoptic/v2/examples/) | Runnable example scripts (bots, fork tests, common workflows) |
+| **Pool Data** | Full pool state, utilization, oracle, risk parameters, liquidity distribution, interest rates |
+| **Trading** | Open, close, roll positions with simulation-first workflow; tick limit slippage control |
+| **Collateral** | ERC-4626 vault deposits/withdrawals, approval helpers, collateral estimation, max position sizing |
+| **TokenId Builder** | Chainable builder for calls, puts, loans, credits; multi-leg spreads (up to 4 legs) |
+| **Risk & Margin** | Margin buffer, liquidation prices, net liquidation value, collateral-across-ticks analysis |
+| **Liquidation** | Liquidation checks, simulation, execution; force exercise for ITM longs |
+| **Greeks** | Client-side value, delta, gamma in natural token units; swap-aware delta; loan effective delta |
+| **Events** | WebSocket watcher, resilient subscription with auto-reconnect, HTTP polling |
+| **Position Tracking** | Event-based sync with resumable checkpoints; file and memory storage adapters |
+| **Trade History** | Local trade history with filters, realized PnL aggregation |
+| **Price History** | Historical tick/sqrtPriceX96 data, streamia (premia) history, Uniswap fee history |
+| **Bot Utilities** | Data freshness assertions, pool health checks, safe mode guards, RPC error classifiers |
+| **Oracle** | Oracle state reads, poke with epoch rate-limit handling |
+| **Pool Deployment** | Mine vanity pool addresses, simulate and deploy new Panoptic pools |
+| **Formatters** | Prices, token amounts, BPS, utilization, WAD values — all with explicit precision |
+| **Errors** | Typed error classes for every failure mode (revert decoding, RPC, validation) |
+
+## Documentation
+
+| Document                                     | Description                                                                        |
+| -------------------------------------------- | ---------------------------------------------------------------------------------- |
+| [Getting Started](./docs/GETTING_STARTED.md) | Full walkthrough: setup → deposit → trade → greeks → risk → events → bots → deployment |
+| [API Reference](./docs/SDK_API_REFERENCE.md) | Every exported function grouped by module with signatures and descriptions         |
+| [Examples](./src/panoptic/v2/examples/)      | Runnable example scripts (bots, fork tests, common workflows)                      |
+
+## Notes
+
+- `GetVaultHistory` applies `first`/`skip` independently per event stream. For unified timeline pagination, merge and sort all streams client-side first, then page that merged array (for example, with a helper like `fetchVaultHistoryRows`).
+
+### Example Bots
+
+| Directory | Description |
+|-----------|-------------|
+| [`examples/liquidation-bot/`](./src/panoptic/v2/examples/liquidation-bot/) | Monitors accounts, detects undercollateralized positions, and executes liquidations |
+| [`examples/oracle-poker/`](./src/panoptic/v2/examples/oracle-poker/) | Keeps Panoptic oracle observations fresh by poking within epoch constraints |
+| [`examples/reverse-gamma-scalping/`](./src/panoptic/v2/examples/reverse-gamma-scalping/) | Delta-hedged strategy using loans, credits, and swap-aware greeks |
 
 ---
 

package/dist/cow/index.d.ts

@@ -0,0 +1,5 @@
+import { APP_DATA_DOC$1 as APP_DATA_DOC, APP_DATA_HASH$1 as APP_DATA_HASH, BestVenue, COW_API_URLS$1 as COW_API_URLS, COW_CANCELLATION_TYPES$1 as COW_CANCELLATION_TYPES, COW_NATIVE_ETH$1 as COW_NATIVE_ETH, COW_ORDER_TYPES$1 as COW_ORDER_TYPES, COW_SETTLEMENT$1 as COW_SETTLEMENT, COW_VAULT_RELAYER$1 as COW_VAULT_RELAYER, CowApiError$1 as CowApiError, CowNativeTokenError$1 as CowNativeTokenError, CowOrderTooSmallError$1 as CowOrderTooSmallError, CowTokenInfo, CowUnsupportedChainError$1 as CowUnsupportedChainError, DEFAULT_VALID_FOR_SECONDS$1 as DEFAULT_VALID_FOR_SECONDS, FindCowTokenParams, PickBestVenueParams, SwapVenue, XSTOCK_WRAPPERS$1 as XSTOCK_WRAPPERS, XstockWrapperInfo, XstockWrapperRegistry, approveErc20ForCow$1 as approveErc20ForCow, cancelCowOrder$1 as cancelCowOrder, checkCowApproval$1 as checkCowApproval, cowDomain$1 as cowDomain, findCowToken$1 as findCowToken, getCowOrderStatus$1 as getCowOrderStatus, getXstockUnderlying$1 as getXstockUnderlying, getXstockWrapper$1 as getXstockWrapper, isCowSupportedChain$1 as isCowSupportedChain, isXstockUnderlying$1 as isXstockUnderlying, isXstockWrapper$1 as isXstockWrapper, pickBestVenue$1 as pickBestVenue, quoteCowSwap$1 as quoteCowSwap, signAndSubmitCowOrder$1 as signAndSubmitCowOrder } from "../index-BuJcj5aO.js";
+import "../index-DVMjZi1E.js";
+import "../irm-CGykVo3q.js";
+import { ApproveErc20ForCowParams, CancelCowOrderParams, CheckCowApprovalParams, CowApprovalStatus, CowOrderKind, CowOrderResult, CowOrderState, CowOrderStatus, CowQuote, GetCowOrderStatusParams, QuoteCowSwapParams, SignAndSubmitCowOrderParams } from "../types-CRvvn2ce.js";
+export { APP_DATA_DOC, APP_DATA_HASH, ApproveErc20ForCowParams, BestVenue, COW_API_URLS, COW_CANCELLATION_TYPES, COW_NATIVE_ETH, COW_ORDER_TYPES, COW_SETTLEMENT, COW_VAULT_RELAYER, CancelCowOrderParams, CheckCowApprovalParams, CowApiError, CowApprovalStatus, CowNativeTokenError, CowOrderKind, CowOrderResult, CowOrderState, CowOrderStatus, CowOrderTooSmallError, CowQuote, CowTokenInfo, CowUnsupportedChainError, DEFAULT_VALID_FOR_SECONDS, FindCowTokenParams, GetCowOrderStatusParams, PickBestVenueParams, QuoteCowSwapParams, SignAndSubmitCowOrderParams, SwapVenue, XSTOCK_WRAPPERS, XstockWrapperInfo, XstockWrapperRegistry, approveErc20ForCow, cancelCowOrder, checkCowApproval, cowDomain, findCowToken, getCowOrderStatus, getXstockUnderlying, getXstockWrapper, isCowSupportedChain, isXstockUnderlying, isXstockWrapper, pickBestVenue, quoteCowSwap, signAndSubmitCowOrder };

package/dist/cow/index.js

@@ -0,0 +1,5 @@
+import "../position-FxaZi608.js";
+import { APP_DATA_DOC, APP_DATA_HASH, COW_API_URLS, COW_CANCELLATION_TYPES, COW_NATIVE_ETH, COW_ORDER_TYPES, COW_SETTLEMENT, COW_VAULT_RELAYER, CowApiError, CowNativeTokenError, CowOrderTooSmallError, CowUnsupportedChainError, DEFAULT_VALID_FOR_SECONDS, XSTOCK_WRAPPERS, approveErc20ForCow, cancelCowOrder, checkCowApproval, cowDomain, findCowToken, getCowOrderStatus, getXstockUnderlying, getXstockWrapper, isCowSupportedChain, isXstockUnderlying, isXstockWrapper, pickBestVenue, quoteCowSwap, signAndSubmitCowOrder } from "../cow-Dy-Cd09v.js";
+import "../writes-CVCD6Ers.js";
+
+export { APP_DATA_DOC, APP_DATA_HASH, COW_API_URLS, COW_CANCELLATION_TYPES, COW_NATIVE_ETH, COW_ORDER_TYPES, COW_SETTLEMENT, COW_VAULT_RELAYER, CowApiError, CowNativeTokenError, CowOrderTooSmallError, CowUnsupportedChainError, DEFAULT_VALID_FOR_SECONDS, XSTOCK_WRAPPERS, approveErc20ForCow, cancelCowOrder, checkCowApproval, cowDomain, findCowToken, getCowOrderStatus, getXstockUnderlying, getXstockWrapper, isCowSupportedChain, isXstockUnderlying, isXstockWrapper, pickBestVenue, quoteCowSwap, signAndSubmitCowOrder };

package/dist/cow/types.d.ts

@@ -0,0 +1,4 @@
+import "../index-DVMjZi1E.js";
+import "../irm-CGykVo3q.js";
+import { ApproveErc20ForCowParams, CancelCowOrderParams, CheckCowApprovalParams, CowApprovalStatus, CowOrderKind, CowOrderResult, CowOrderState, CowOrderStatus, CowQuote, GetCowOrderStatusParams, QuoteCowSwapParams, SignAndSubmitCowOrderParams } from "../types-CRvvn2ce.js";
+export { ApproveErc20ForCowParams, CancelCowOrderParams, CheckCowApprovalParams, CowApprovalStatus, CowOrderKind, CowOrderResult, CowOrderState, CowOrderStatus, CowQuote, GetCowOrderStatusParams, QuoteCowSwapParams, SignAndSubmitCowOrderParams };