@panoptic-eng/sdk 1.0.3 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +114 -97
  2. package/dist/index.d.ts.map +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,139 +1,156 @@
1
1
  # @panoptic-eng/sdk
2
2
 
3
- TypeScript SDK for interacting with Panoptic v2 protocol.
3
+ TypeScript SDK for interacting with the Panoptic v2 perpetual options protocol on EVM chains.
4
4
 
5
- ## Prerequisites
5
+ ## Quick Start
6
6
 
7
- - **Node.js** `>=20.19.0 <23.0.0` (see `.nvmrc` in repo root)
8
- - **pnpm** package manager
7
+ ```bash
8
+ npm install @panoptic-eng/sdk viem
9
+ ```
9
10
 
10
- ## Setup
11
+ ```typescript
12
+ import { createPublicClient, createWalletClient, http, parseUnits } from 'viem'
13
+ import { sepolia } from 'viem/chains'
14
+ import { privateKeyToAccount } from 'viem/accounts'
15
+ import {
16
+ getPool, fetchPoolId, approveAndWait, depositAndWait,
17
+ createTokenIdBuilder, simulateOpenPosition, openPositionAndWait,
18
+ tickLimits, formatTokenAmount,
19
+ } from '@panoptic-eng/sdk'
11
20
 
12
- ### 1. Install Node.js (via nvm)
21
+ // 1. Setup clients
22
+ const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY')
23
+ const client = createPublicClient({ chain: sepolia, transport: http() })
24
+ const walletClient = createWalletClient({ account, chain: sepolia, transport: http() })
25
+
26
+ // 2. Read pool data
27
+ const pool = await getPool({ client, poolAddress: '0x...', chainId: 11155111n })
28
+
29
+ // 3. Approve + deposit collateral
30
+ await approveAndWait({
31
+ client, walletClient, account: account.address,
32
+ tokenAddress: pool.poolKey.currency0,
33
+ spenderAddress: pool.collateralTracker0.address,
34
+ amount: 2n ** 256n - 1n,
35
+ })
36
+ await depositAndWait({
37
+ client, walletClient, account: account.address,
38
+ collateralTrackerAddress: pool.collateralTracker0.address,
39
+ assets: parseUnits('1', 18),
40
+ })
41
+
42
+ // 4. Build a position and simulate
43
+ const { poolId } = await fetchPoolId({ client, poolAddress: '0x...' })
44
+ const tokenId = createTokenIdBuilder(poolId)
45
+ .addCall({ strike: 200_000n, width: 10n, optionRatio: 1n })
46
+ .build()
47
+
48
+ const limits = tickLimits(pool.currentTick, 500n)
49
+ const sim = await simulateOpenPosition({
50
+ client, poolAddress: '0x...', account: account.address,
51
+ tokenId, positionSize: 10n ** 15n, existingPositionIds: [],
52
+ tickLimitLow: limits.low, tickLimitHigh: limits.high,
53
+ })
54
+
55
+ if (!sim.success) throw new Error(`Simulation failed: ${sim.error}`)
56
+ console.log('Gas estimate:', sim.gasEstimate)
57
+ console.log('Token0 required:', formatTokenAmount(
58
+ sim.data.amount0Required, BigInt(pool.collateralTracker0.decimals), 6n
59
+ ))
60
+
61
+ // 5. Execute
62
+ await openPositionAndWait({
63
+ client, walletClient, account: account.address, poolAddress: '0x...',
64
+ tokenId, positionSize: 10n ** 15n, existingPositionIds: [],
65
+ tickLimitLow: limits.low, tickLimitHigh: limits.high,
66
+ })
67
+ ```
13
68
 
14
- ```sh
15
- # Install nvm if you don't have it
16
- curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
69
+ ## Documentation
17
70
 
18
- # Restart terminal, then install the correct Node version
19
- nvm install
20
- nvm use
21
- ```
71
+ | Document | Description |
72
+ |----------|-------------|
73
+ | [Getting Started](./docs/GETTING_STARTED.md) | Full walkthrough: setup, deposit, build positions, simulate, trade, monitor, close |
74
+ | [API Reference](./docs/SDK_API_REFERENCE.md) | Every exported function grouped by module with signatures and descriptions |
75
+ | [Examples](./src/panoptic/v2/examples/) | Runnable example scripts (bots, fork tests, common workflows) |
22
76
 
23
- ### 2. Install pnpm
77
+ ---
24
78
 
25
- ```sh
26
- # Option A: via corepack (recommended, built into Node 16.13+)
27
- corepack enable
79
+ ## Contributing
28
80
 
29
- # Option B: via npm
30
- npm install -g pnpm
31
- ```
81
+ ### Prerequisites
32
82
 
33
- ### 3. Install dependencies
83
+ - **Node.js** `>=20.19.0 <23.0.0` (see `.nvmrc` in repo root)
84
+ - **pnpm** package manager
34
85
 
35
- From the monorepo root:
86
+ ### Setup
36
87
 
37
88
  ```sh
38
- pnpm install
39
- pnpm add @panoptic-eng/sdk react viem wagmi
40
- ```
89
+ # Install Node.js via nvm
90
+ nvm install && nvm use
41
91
 
42
- ### 4. Generate types
92
+ # Enable pnpm
93
+ corepack enable
43
94
 
44
- The SDK uses code generation for contract ABIs and GraphQL types:
95
+ # Install dependencies (from monorepo root)
96
+ pnpm install
45
97
 
46
- ```sh
98
+ # Generate contract types
47
99
  cd packages/sdk
48
100
  pnpm codegen
49
101
  ```
50
102
 
51
- This runs:
52
- - `codegen:graphql` - Generates TypeScript types from GraphQL schema
53
- - `codegen:wagmi` - Generates TypeScript types from contract ABIs
54
-
55
- ### 5. Set up environment (for fork tests)
103
+ ### Development
56
104
 
57
105
  ```sh
58
- cp .env.template .env
59
- # Add your Alchemy API key to .env
106
+ pnpm build # Build the SDK
107
+ pnpm dev # Watch mode
108
+ pnpm typecheck # Type checking
109
+ pnpm lint # Linting
110
+ pnpm lint:fix # Auto-fix lint issues
60
111
  ```
61
112
 
62
- ## Development
113
+ ### Testing
63
114
 
64
115
  ```sh
65
- # Build the SDK
66
- pnpm build
67
-
68
- # Watch mode (rebuilds on changes)
69
- pnpm dev
70
-
71
- # Type checking
72
- pnpm typecheck
73
-
74
- # Linting
75
- pnpm lint
76
- pnpm lint:fix
77
- ```
78
-
79
- ## Testing
80
-
81
- ```sh
82
- # Run unit tests
83
- pnpm test
84
-
85
- # Run fork tests (requires ALCHEMY_API_KEY)
86
- pnpm test:fork
87
-
88
- # Watch mode for fork tests
89
- pnpm test:fork:watch
90
-
91
- # Run all tests (unit + fork)
92
- pnpm test:examples
116
+ pnpm test # Unit tests
117
+ pnpm test:fork # Fork tests (requires ALCHEMY_API_KEY in .env)
118
+ pnpm test:fork:watch # Watch mode for fork tests
119
+ pnpm test:examples # All tests (unit + fork)
93
120
  ```
94
121
 
95
- ## Project Structure
122
+ ### Project Structure
96
123
 
97
- ```
124
+ ```text
98
125
  packages/sdk/
126
+ ├── docs/ # SDK documentation
99
127
  ├── src/
100
128
  │ ├── panoptic/
101
- │ │ └── v2/ # Panoptic v2 SDK
102
- │ │ ├── clients/ # Client utilities (getBlockMeta, etc.)
103
- │ │ ├── errors/ # Error types
104
- │ │ ├── simulations/ # Transaction simulations
105
- │ │ ├── sync/ # Position sync and tracking
106
- │ │ ├── types/ # TypeScript types
107
- │ │ ├── utils/ # Utility functions
108
- │ │ └── examples/ # Example implementations
109
- │ │ ├── basic/ # Basic read/write examples
110
- │ │ ├── liquidation-bot/ # Liquidation bot example
111
- │ │ └── oracle-poker/ # Oracle poker bot example
112
- │ └── generated/ # Auto-generated contract types
113
- ├── contracts/ # Contract ABIs (synced from contracts repo)
114
- ├── graphql/ # GraphQL schema and queries
115
- └── scripts/ # Build and sync scripts
129
+ │ │ └── v2/ # Panoptic v2 SDK
130
+ │ │ ├── reads/ # Pool, position, account reads
131
+ │ │ ├── writes/ # Transaction functions
132
+ │ │ ├── simulations/ # Dry-run simulations
133
+ │ │ ├── tokenId/ # TokenId encoding/decoding
134
+ │ │ ├── sync/ # Position tracking via events
135
+ │ │ ├── events/ # Event watching and polling
136
+ │ │ ├── formatters/ # Display formatters
137
+ │ │ ├── greeks/ # Client-side greeks
138
+ │ │ ├── bot/ # Bot utilities
139
+ │ │ ├── clients/ # viem client helpers
140
+ │ │ ├── storage/ # Storage adapters
141
+ │ │ ├── errors/ # Typed error classes
142
+ │ │ ├── types/ # TypeScript types
143
+ │ │ ├── utils/ # Constants
144
+ │ │ └── examples/ # Example scripts
145
+ │ └── generated/ # Auto-generated contract types
146
+ ├── contracts/ # Contract ABIs
147
+ └── scripts/ # Build and sync scripts
116
148
  ```
117
149
 
118
- ## Contract ABIs
150
+ ### Contract ABIs
119
151
 
120
152
  Contract ABIs are synced from the main contracts repository. See [ABI_GENERATION.md](./ABI_GENERATION.md) for details.
121
153
 
122
- To sync ABIs:
123
-
124
154
  ```sh
125
155
  pnpm sync-contracts
126
156
  ```
127
-
128
- ## Usage
129
-
130
- ```typescript
131
- import {
132
- simulateOpenPosition,
133
- simulateClosePosition,
134
- getBlockMeta,
135
- TokenIdBuilder,
136
- } from '@panoptic-eng/sdk'
137
- ```
138
-
139
- See the [examples](./src/panoptic/v2/examples/) directory for usage patterns.