@panoptic-eng/sdk 1.0.3 → 1.0.5

package/README.md

@@ -1,139 +1,211 @@
 # @panoptic-eng/sdk
 
-TypeScript SDK for interacting with Panoptic v2 protocol.
+TypeScript SDK for interacting with the Panoptic v2 perpetual options protocol on EVM chains.
 
-## Prerequisites
+## Quick Start
 
-- **Node.js** `>=20.19.0 <23.0.0` (see `.nvmrc` in repo root)
-- **pnpm** package manager
-
-## Setup
-
-### 1. Install Node.js (via nvm)
-
-```sh
-# Install nvm if you don't have it
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+```bash
+npm install @panoptic-eng/sdk viem
+```
 
-# Restart terminal, then install the correct Node version
-nvm install
-nvm use
+```typescript
+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/v2'
+
+// 1. Setup clients
+const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY')
+const client = createPublicClient({ chain: sepolia, transport: http() })
+const walletClient = createWalletClient({ account, chain: sepolia, transport: http() })
+
+// 2. Read pool data
+const pool = await getPool({ client, poolAddress: '0x...', chainId: 11155111n })
+
+// 3. Approve + deposit collateral
+await approveAndWait({
+  client,
+  walletClient,
+  account: account.address,
+  tokenAddress: pool.poolKey.currency0,
+  spenderAddress: pool.collateralTracker0.address,
+  amount: 2n ** 256n - 1n,
+})
+await depositAndWait({
+  client,
+  walletClient,
+  account: account.address,
+  collateralTrackerAddress: pool.collateralTracker0.address,
+  assets: parseUnits('1', 18),
+})
+
+// 4. Build a position and simulate
+const { poolId } = await fetchPoolId({ client, poolAddress: '0x...' })
+const tokenId = createTokenIdBuilder(poolId)
+  .addCall({ strike: 200_000n, width: 10n, optionRatio: 1n })
+  .build()
+
+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,
+})
+
+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),
+)
+
+// 5. Execute
+await openPositionAndWait({
+  client,
+  walletClient,
+  account: account.address,
+  poolAddress: '0x...',
+  tokenId,
+  positionSize: 10n ** 15n,
+  existingPositionIds: [],
+  tickLimitLow: limits.low,
+  tickLimitHigh: limits.high,
+})
 ```
 
-### 2. Install pnpm
+## Feature Overview
 
-```sh
-# Option A: via corepack (recommended, built into Node 16.13+)
-corepack enable
+| Category | Capabilities |
+|----------|-------------|
+| **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) |
 
-# Option B: via npm
-npm install -g pnpm
-```
+## Documentation
 
-### 3. Install dependencies
+| 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)                      |
 
-From the monorepo root:
+## Notes
 
-```sh
-pnpm install
-pnpm add @panoptic-eng/sdk react viem wagmi
-```
+- `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`).
 
-### 4. Generate types
+### Example Bots
 
-The SDK uses code generation for contract ABIs and GraphQL types:
+| 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 |
 
-```sh
-cd packages/sdk
-pnpm codegen
-```
+---
 
-This runs:
-- `codegen:graphql` - Generates TypeScript types from GraphQL schema
-- `codegen:wagmi` - Generates TypeScript types from contract ABIs
+## Contributing
 
-### 5. Set up environment (for fork tests)
+### Prerequisites
 
-```sh
-cp .env.template .env
-# Add your Alchemy API key to .env
-```
+- **Node.js** `>=20.19.0 <23.0.0` (see `.nvmrc` in repo root)
+- **pnpm** package manager
 
-## Development
+### Setup
 
 ```sh
-# Build the SDK
-pnpm build
+# Install Node.js via nvm
+nvm install && nvm use
 
-# Watch mode (rebuilds on changes)
-pnpm dev
+# Enable pnpm
+corepack enable
 
-# Type checking
-pnpm typecheck
+# Install dependencies (from monorepo root)
+pnpm install
 
-# Linting
-pnpm lint
-pnpm lint:fix
+# Generate contract types
+cd packages/sdk
+pnpm codegen
 ```
 
-## Testing
+### Development
 
 ```sh
-# Run unit tests
-pnpm test
-
-# Run fork tests (requires ALCHEMY_API_KEY)
-pnpm test:fork
+pnpm build          # Build the SDK
+pnpm dev            # Watch mode
+pnpm typecheck      # Type checking
+pnpm lint           # Linting
+pnpm lint:fix       # Auto-fix lint issues
+```
 
-# Watch mode for fork tests
-pnpm test:fork:watch
+### Testing
 
-# Run all tests (unit + fork)
-pnpm test:examples
+```sh
+pnpm test              # Unit tests
+pnpm test:fork         # Fork tests (requires ALCHEMY_API_KEY in .env)
+pnpm test:fork:watch   # Watch mode for fork tests
+pnpm test:examples     # All tests (unit + fork)
 ```
 
-## Project Structure
+### Project Structure
 
-```
+```text
 packages/sdk/
+├── docs/                       # SDK documentation
 ├── src/
 │   ├── panoptic/
-│   │   └── v2/              # Panoptic v2 SDK
-│   │       ├── clients/     # Client utilities (getBlockMeta, etc.)
-│   │       ├── errors/      # Error types
-│   │       ├── simulations/ # Transaction simulations
-│   │       ├── sync/        # Position sync and tracking
-│   │       ├── types/       # TypeScript types
-│   │       ├── utils/       # Utility functions
-│   │       └── examples/    # Example implementations
-│   │           ├── basic/           # Basic read/write examples
-│   │           ├── liquidation-bot/ # Liquidation bot example
-│   │           └── oracle-poker/    # Oracle poker bot example
-│   └── generated/           # Auto-generated contract types
-├── contracts/               # Contract ABIs (synced from contracts repo)
-├── graphql/                 # GraphQL schema and queries
-└── scripts/                 # Build and sync scripts
+│   │   └── v2/                 # Panoptic v2 SDK
+│   │       ├── reads/          # Pool, position, account reads
+│   │       ├── writes/         # Transaction functions
+│   │       ├── simulations/    # Dry-run simulations
+│   │       ├── tokenId/        # TokenId encoding/decoding
+│   │       ├── sync/           # Position tracking via events
+│   │       ├── events/         # Event watching and polling
+│   │       ├── formatters/     # Display formatters
+│   │       ├── greeks/         # Client-side greeks
+│   │       ├── bot/            # Bot utilities
+│   │       ├── clients/        # viem client helpers
+│   │       ├── storage/        # Storage adapters
+│   │       ├── errors/         # Typed error classes
+│   │       ├── types/          # TypeScript types
+│   │       ├── utils/          # Constants
+│   │       └── examples/       # Example scripts
+│   └── generated/              # Auto-generated contract types
+├── contracts/                  # Contract ABIs
+└── scripts/                    # Build and sync scripts
 ```
 
-## Contract ABIs
+### Contract ABIs
 
 Contract ABIs are synced from the main contracts repository. See [ABI_GENERATION.md](./ABI_GENERATION.md) for details.
 
-To sync ABIs:
-
 ```sh
 pnpm sync-contracts
 ```
-
-## Usage
-
-```typescript
-import {
-  simulateOpenPosition,
-  simulateClosePosition,
-  getBlockMeta,
-  TokenIdBuilder,
-} from '@panoptic-eng/sdk'
-```
-
-See the [examples](./src/panoptic/v2/examples/) directory for usage patterns.