@pod-network/trade-sdk 0.1.0-rc.0

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 (102) hide show
  1. package/README.md +113 -0
  2. package/dist/client.d.ts +93 -0
  3. package/dist/client.d.ts.map +1 -0
  4. package/dist/client.js +168 -0
  5. package/dist/client.js.map +1 -0
  6. package/dist/codec/decode.d.ts +22 -0
  7. package/dist/codec/decode.d.ts.map +1 -0
  8. package/dist/codec/decode.js +251 -0
  9. package/dist/codec/decode.js.map +1 -0
  10. package/dist/codec/fixed.d.ts +11 -0
  11. package/dist/codec/fixed.d.ts.map +1 -0
  12. package/dist/codec/fixed.js +37 -0
  13. package/dist/codec/fixed.js.map +1 -0
  14. package/dist/codec/resolution.d.ts +14 -0
  15. package/dist/codec/resolution.d.ts.map +1 -0
  16. package/dist/codec/resolution.js +35 -0
  17. package/dist/codec/resolution.js.map +1 -0
  18. package/dist/codec/units.d.ts +35 -0
  19. package/dist/codec/units.d.ts.map +1 -0
  20. package/dist/codec/units.js +86 -0
  21. package/dist/codec/units.js.map +1 -0
  22. package/dist/datafeed.d.ts +4 -0
  23. package/dist/datafeed.d.ts.map +1 -0
  24. package/dist/datafeed.js +73 -0
  25. package/dist/datafeed.js.map +1 -0
  26. package/dist/index.d.ts +20 -0
  27. package/dist/index.d.ts.map +1 -0
  28. package/dist/index.js +19 -0
  29. package/dist/index.js.map +1 -0
  30. package/dist/stores/resource.d.ts +50 -0
  31. package/dist/stores/resource.d.ts.map +1 -0
  32. package/dist/stores/resource.js +154 -0
  33. package/dist/stores/resource.js.map +1 -0
  34. package/dist/sync/account-metrics.d.ts +26 -0
  35. package/dist/sync/account-metrics.d.ts.map +1 -0
  36. package/dist/sync/account-metrics.js +41 -0
  37. package/dist/sync/account-metrics.js.map +1 -0
  38. package/dist/sync/candles.d.ts +68 -0
  39. package/dist/sync/candles.d.ts.map +1 -0
  40. package/dist/sync/candles.js +318 -0
  41. package/dist/sync/candles.js.map +1 -0
  42. package/dist/sync/order-preview.d.ts +74 -0
  43. package/dist/sync/order-preview.d.ts.map +1 -0
  44. package/dist/sync/order-preview.js +86 -0
  45. package/dist/sync/order-preview.js.map +1 -0
  46. package/dist/sync/orders.d.ts +49 -0
  47. package/dist/sync/orders.d.ts.map +1 -0
  48. package/dist/sync/orders.js +210 -0
  49. package/dist/sync/orders.js.map +1 -0
  50. package/dist/sync/positions-live.d.ts +3 -0
  51. package/dist/sync/positions-live.d.ts.map +1 -0
  52. package/dist/sync/positions-live.js +86 -0
  53. package/dist/sync/positions-live.js.map +1 -0
  54. package/dist/sync/sources.d.ts +40 -0
  55. package/dist/sync/sources.d.ts.map +1 -0
  56. package/dist/sync/sources.js +197 -0
  57. package/dist/sync/sources.js.map +1 -0
  58. package/dist/transport/rest.d.ts +83 -0
  59. package/dist/transport/rest.d.ts.map +1 -0
  60. package/dist/transport/rest.js +146 -0
  61. package/dist/transport/rest.js.map +1 -0
  62. package/dist/transport/ws.d.ts +60 -0
  63. package/dist/transport/ws.d.ts.map +1 -0
  64. package/dist/transport/ws.js +235 -0
  65. package/dist/transport/ws.js.map +1 -0
  66. package/dist/types/public.d.ts +292 -0
  67. package/dist/types/public.d.ts.map +1 -0
  68. package/dist/types/public.js +4 -0
  69. package/dist/types/public.js.map +1 -0
  70. package/dist/types/wire.d.ts +283 -0
  71. package/dist/types/wire.d.ts.map +1 -0
  72. package/dist/types/wire.js +6 -0
  73. package/dist/types/wire.js.map +1 -0
  74. package/dist/write/delegation.d.ts +54 -0
  75. package/dist/write/delegation.d.ts.map +1 -0
  76. package/dist/write/delegation.js +81 -0
  77. package/dist/write/delegation.js.map +1 -0
  78. package/dist/write/index.d.ts +261 -0
  79. package/dist/write/index.d.ts.map +1 -0
  80. package/dist/write/index.js +428 -0
  81. package/dist/write/index.js.map +1 -0
  82. package/package.json +43 -0
  83. package/src/client.ts +229 -0
  84. package/src/codec/decode.ts +277 -0
  85. package/src/codec/fixed.ts +41 -0
  86. package/src/codec/resolution.ts +39 -0
  87. package/src/codec/units.ts +100 -0
  88. package/src/datafeed.ts +94 -0
  89. package/src/index.ts +49 -0
  90. package/src/stores/resource.ts +172 -0
  91. package/src/sync/account-metrics.ts +71 -0
  92. package/src/sync/candles.ts +326 -0
  93. package/src/sync/order-preview.ts +152 -0
  94. package/src/sync/orders.ts +205 -0
  95. package/src/sync/positions-live.ts +102 -0
  96. package/src/sync/sources.ts +239 -0
  97. package/src/transport/rest.ts +213 -0
  98. package/src/transport/ws.ts +255 -0
  99. package/src/types/public.ts +335 -0
  100. package/src/types/wire.ts +301 -0
  101. package/src/write/delegation.ts +113 -0
  102. package/src/write/index.ts +642 -0
@@ -0,0 +1,301 @@
1
+ // Raw JSON shapes exactly as the indexer emits them (REST `/clob/*` and the
2
+ // `pod_*` WebSocket channels). snake_case; numerics are 1e18-scaled decimal
3
+ // strings; timestamps are microseconds (in `*_us` fields, or bare on candle/
4
+ // orderbook). Decoders in ../codec/decode.ts convert these to ../types/public.
5
+
6
+ import type { Hex } from "./public.js";
7
+
8
+ export type WireDecimal = string; // 1e18-scaled integer as a decimal string
9
+
10
+ export interface WireStatus {
11
+ solution_now: number; // micros
12
+ }
13
+
14
+ export interface WireMarketStatic {
15
+ id: Hex;
16
+ name: string;
17
+ base_token_address: Hex;
18
+ quote_token_address: Hex;
19
+ base_token_symbol: string;
20
+ quote_token_symbol: string;
21
+ base_token_name: string;
22
+ quote_token_name: string;
23
+ market_type: "spot" | "perp";
24
+ auction_interval_us: number;
25
+ maker_fee: WireDecimal;
26
+ taker_fee: WireDecimal;
27
+ tick_precision: WireDecimal; // 1e18-scaled price increment (decimal string)
28
+ lot_size: WireDecimal;
29
+ max_leverage: number;
30
+ funding_window_us: number; // funding-accrual divisor (micros)
31
+ }
32
+
33
+ export interface WireMarketDynamics {
34
+ orderbook_id: Hex;
35
+ last_clearing_price: WireDecimal;
36
+ volume_24h: WireDecimal;
37
+ high_24h: WireDecimal;
38
+ low_24h: WireDecimal;
39
+ price_change_24h: number; // bps
40
+ oracle_price?: WireDecimal | null;
41
+ mark_price?: WireDecimal | null;
42
+ funding_rate?: WireDecimal | null;
43
+ funding_index?: WireDecimal | null;
44
+ funding_last_updated_us?: number | null;
45
+ open_interest?: WireDecimal | null;
46
+ }
47
+
48
+ /** pod_markets push uses `orderbook` instead of `orderbook_id`. */
49
+ export interface WireMarketDynamicsPush extends Omit<WireMarketDynamics, "orderbook_id"> {
50
+ orderbook: Hex;
51
+ }
52
+
53
+ export interface WireMarketStatsPage {
54
+ solution_now: number;
55
+ markets: WireMarketDynamics[];
56
+ }
57
+
58
+ export interface WireCandle {
59
+ timestamp: number; // micros
60
+ open: WireDecimal;
61
+ close: WireDecimal;
62
+ high: WireDecimal;
63
+ low: WireDecimal;
64
+ volume: WireDecimal;
65
+ quote_volume: WireDecimal;
66
+ }
67
+
68
+ /** GET /clob/candles envelope: candles + continuation metadata. */
69
+ export interface WireCandlesEnvelope {
70
+ candles: WireCandle[]; // newest-first
71
+ resolution: string;
72
+ range: { from_us: number; to_us: number } | null; // oldest->newest bucket returned
73
+ solution_now_us: number; // indexer's newest indexed deadline
74
+ }
75
+
76
+ /** pod_candles per-tick hint. */
77
+ export interface WireCandleTick {
78
+ orderbook: Hex;
79
+ timestamp_us: number;
80
+ price: WireDecimal;
81
+ volume: WireDecimal;
82
+ }
83
+
84
+ export interface WirePartialFill {
85
+ base_amount: WireDecimal;
86
+ quote_amount: WireDecimal;
87
+ timestamp: number; // micros
88
+ price: WireDecimal;
89
+ }
90
+
91
+ export interface WireOrder {
92
+ orderbook_id?: Hex; // REST only; WS raw Order carries `pair` instead
93
+ market_type?: "spot" | "perp"; // REST only
94
+ kind: string;
95
+ order_id: Hex;
96
+ tx_hash: Hex;
97
+ bidder: Hex;
98
+ nonce: number;
99
+ order_type: "limit" | "market";
100
+ status: string;
101
+ price: WireDecimal;
102
+ initial_size: WireDecimal; // signed
103
+ filled_base_amount: WireDecimal;
104
+ filled_quote_amount: WireDecimal;
105
+ fee: WireDecimal;
106
+ deadline: number | string; // micros
107
+ end: number | string; // micros
108
+ included_batch?: number | string; // micros; batch-inclusion time (REST order history)
109
+ effective_price?: WireDecimal | null;
110
+ fills?: WirePartialFill[];
111
+ /** Present on WS stream orders (raw engine Order) instead of orderbook_id. */
112
+ pair?: { base: Hex; quote: Hex };
113
+ /** Present on REST orders; absent on the WS raw Order (derive from `initial_size`). */
114
+ side?: "buy" | "sell";
115
+ reduce_only?: boolean;
116
+ ioc?: boolean;
117
+ direction?: string;
118
+ grouping?: WireDecimal;
119
+ trigger_type?: string | null;
120
+ }
121
+
122
+ export interface WireOrdersPage {
123
+ orders: WireOrder[];
124
+ next_cursor: string | null;
125
+ total_count: number;
126
+ solution_now: number;
127
+ }
128
+
129
+ export interface WireTickSnapshot {
130
+ volume: WireDecimal;
131
+ minimum_expiry?: number;
132
+ }
133
+
134
+ export interface WireOrderbook {
135
+ orderbook_id?: Hex;
136
+ clob_id?: Hex;
137
+ buys: Record<string, WireTickSnapshot>; // decimal price string -> tick
138
+ sells: Record<string, WireTickSnapshot>;
139
+ buys_count: number;
140
+ sells_count: number;
141
+ grouping_precision: WireDecimal;
142
+ timestamp: number; // micros
143
+ new_orders_count: number;
144
+ clearing_price?: WireDecimal | null;
145
+ oracle_price?: WireDecimal | null;
146
+ funding_rate?: WireDecimal | null;
147
+ funding_index?: WireDecimal | null;
148
+ funding_last_updated?: number | null;
149
+ }
150
+
151
+ export interface WireSpotPosition {
152
+ kind: "spot";
153
+ orderbook_id?: Hex;
154
+ token: Hex;
155
+ balance: WireDecimal;
156
+ free_balance: WireDecimal;
157
+ locked_balance: WireDecimal;
158
+ cost_basis: WireDecimal;
159
+ mark_price: WireDecimal;
160
+ unrealized_pnl: WireDecimal;
161
+ realized_pnl: WireDecimal;
162
+ }
163
+
164
+ export interface WirePerpPosition {
165
+ kind: "perp";
166
+ orderbook_id: Hex;
167
+ side: "long" | "short";
168
+ size: WireDecimal;
169
+ notional: WireDecimal;
170
+ entry_price: WireDecimal;
171
+ mark_price: WireDecimal;
172
+ margin: WireDecimal;
173
+ leverage: WireDecimal;
174
+ funding_accrued: WireDecimal;
175
+ entry_funding: WireDecimal;
176
+ liquidation_price: WireDecimal;
177
+ unrealized_pnl: WireDecimal;
178
+ realized_pnl: WireDecimal;
179
+ }
180
+
181
+ export type WirePosition = WireSpotPosition | WirePerpPosition;
182
+
183
+ export interface WirePositionsSnapshot {
184
+ positions: WirePosition[];
185
+ total_unrealized_pnl: WireDecimal;
186
+ total_realized_pnl: WireDecimal;
187
+ perps_equity: WireDecimal;
188
+ account_value: WireDecimal;
189
+ cash: WireDecimal;
190
+ withdrawable_cash: WireDecimal;
191
+ }
192
+
193
+ export interface WireSpotHolding {
194
+ orderbook_id: Hex;
195
+ base_symbol: string;
196
+ quote_symbol: string;
197
+ balance: WireDecimal;
198
+ free_balance: WireDecimal;
199
+ locked_balance: WireDecimal;
200
+ cost_basis: WireDecimal;
201
+ mark_price: WireDecimal;
202
+ unrealized_pnl: WireDecimal;
203
+ realized_pnl: WireDecimal;
204
+ }
205
+
206
+ export interface WireBalances {
207
+ balances: WireSpotHolding[];
208
+ cash: WireDecimal;
209
+ withdrawable_cash: WireDecimal;
210
+ net_deposits: WireDecimal;
211
+ }
212
+
213
+ /** `/clob/leaderboard` (and RPC ob_getRankedPositions) share this shape. Only
214
+ * the aggregate PnL fields of each account's positions block are read. */
215
+ export interface WireRankedAccount {
216
+ account: Hex;
217
+ positions: {
218
+ total_unrealized_pnl: WireDecimal;
219
+ total_realized_pnl: WireDecimal;
220
+ account_value: WireDecimal;
221
+ };
222
+ }
223
+
224
+ export interface WireLeaderboard {
225
+ ranked: WireRankedAccount[];
226
+ total: number;
227
+ }
228
+
229
+ export interface WireTrigger {
230
+ orderbook_id: Hex;
231
+ order_id: Hex;
232
+ tx_hash: Hex;
233
+ bidder: Hex;
234
+ nonce: number;
235
+ size: WireDecimal; // signed
236
+ limit_price: WireDecimal;
237
+ trigger_price: WireDecimal;
238
+ trigger_type: string;
239
+ reduce_only: boolean;
240
+ ioc: boolean;
241
+ deadline: number | string;
242
+ end: number | string;
243
+ }
244
+
245
+ export interface WireTriggersPage {
246
+ triggers: WireTrigger[];
247
+ total_count: number;
248
+ next_cursor: string | null;
249
+ }
250
+
251
+ export interface WireBackstopTransfer {
252
+ orderbook_id?: Hex;
253
+ size: WireDecimal;
254
+ cash: WireDecimal;
255
+ mark_price: WireDecimal;
256
+ equity: WireDecimal;
257
+ timestamp_us: number;
258
+ }
259
+
260
+ export interface WireBackstopPage {
261
+ backstop_transfers: WireBackstopTransfer[];
262
+ total_count: number;
263
+ solution_now: number;
264
+ }
265
+
266
+ // pod_orders push: tagged union on `type`.
267
+ export type WireOrderUpdate =
268
+ | ({ type: "new" } & WireOrder)
269
+ | ({ type: "invalid" } & WireOrder)
270
+ | ({ type: "fill" } & WireOrderFill)
271
+ | { type: "expired"; order_id: Hex }
272
+ | { type: "canceled"; order_id: Hex }
273
+ | { type: "modified"; order_id: Hex; new_price: WireDecimal; new_size: WireDecimal };
274
+
275
+ export interface WireOrderFill {
276
+ orderbook_id: Hex;
277
+ order_id: Hex;
278
+ tx_hash: Hex;
279
+ bidder: Hex;
280
+ status: string;
281
+ base_amount: WireDecimal;
282
+ quote_amount: WireDecimal;
283
+ filled_base_amount: WireDecimal;
284
+ filled_quote_amount: WireDecimal;
285
+ effective_price?: WireDecimal | null;
286
+ fee: WireDecimal;
287
+ position_before?: WireDecimal | null;
288
+ position_after?: WireDecimal | null;
289
+ }
290
+
291
+ export interface WirePositionsPush {
292
+ account: Hex;
293
+ data: WirePositionsSnapshot;
294
+ }
295
+
296
+ export interface WireTriggersPush {
297
+ account: Hex;
298
+ triggers: WireTrigger[];
299
+ total_count: number;
300
+ next_cursor: string | null;
301
+ }
@@ -0,0 +1,113 @@
1
+ // Ephemeral-key delegation, mirroring node/src/delegation/mod.rs (stateless):
2
+ // the master wallet signs one EIP-712 `DelegationAuth { delegate, validUntil }`
3
+ // authorizing a freshly generated ephemeral key; every CLOB tx is then wrapped
4
+ // in the gas-exempt `delegated(master, validUntil, signature, inner)` envelope
5
+ // and signed by that key. No on-chain registration — the cert rides in each tx.
6
+ //
7
+ // SECURITY INVARIANT: the ephemeral private key exists ONLY inside the closure
8
+ // created by createDelegatedWallet() — it is never exported, never persisted,
9
+ // never attached to any object that leaves this module. The only capability a
10
+ // DelegatedWallet exposes is submit(); "logging out" is dropping the object.
11
+ // Keep it that way.
12
+
13
+ import { createWalletClient, defineChain, encodeFunctionData, http, parseAbi, recoverTypedDataAddress } from "viem";
14
+ import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
15
+ import type { Address, Hash, Hex } from "../types/public.js";
16
+ import { sendRawTransaction, type PodTxRequest } from "./index.js";
17
+
18
+ /** EIP-712 payload the master signs (domain "pod delegation" v1). */
19
+ export function delegationTypedData(delegate: Address, validUntil: bigint, chainId: number) {
20
+ return {
21
+ domain: { name: "pod delegation", version: "1", chainId },
22
+ types: { DelegationAuth: [
23
+ { name: "delegate", type: "address" },
24
+ { name: "validUntil", type: "uint64" },
25
+ ] },
26
+ primaryType: "DelegationAuth",
27
+ message: { delegate, validUntil },
28
+ } as const;
29
+ }
30
+
31
+ export type DelegationTypedData = ReturnType<typeof delegationTypedData>;
32
+
33
+ const DELEGATED_ABI = parseAbi([
34
+ "function delegated(address master, uint64 validUntil, bytes signature, bytes inner)",
35
+ ]);
36
+
37
+ /** A trading session: public cert facts + the one capability, submit(). */
38
+ export interface DelegatedWallet {
39
+ readonly master: Address;
40
+ readonly delegate: Address;
41
+ /** Cert expiry in MICROSECONDS — must cover every inner intent deadline. */
42
+ readonly validUntil: bigint;
43
+ /** Wrap `tx` in the delegated envelope, sign with the ephemeral key, and
44
+ * broadcast (raw send, CLOB revert reasons decoded). Returns the tx hash. */
45
+ submit(tx: PodTxRequest): Promise<Hash>;
46
+ }
47
+
48
+ export interface CreateDelegatedWalletParams {
49
+ master: Address;
50
+ chainId: number;
51
+ /** Node JSON-RPC HTTP endpoint (nonce, gas price, broadcast). */
52
+ rpcUrl: string;
53
+ /** The master wallet's typed-data prompt (the one signature of the flow). */
54
+ signTypedData: (td: DelegationTypedData) => Promise<Hex>;
55
+ /** Delegation lifetime in ms; must cover every intent deadline issued during it. */
56
+ ttlMs: number;
57
+ fetch?: typeof fetch;
58
+ }
59
+
60
+ /**
61
+ * Create a session: generate an ephemeral key, have the master sign the
62
+ * delegation via `signTypedData`, and verify the returned signature actually
63
+ * recovers to `master` before trusting it (catches a wrong active account in
64
+ * the wallet at login instead of a confusing node revert later).
65
+ */
66
+ export async function createDelegatedWallet(p: CreateDelegatedWalletParams): Promise<DelegatedWallet> {
67
+ const account = privateKeyToAccount(generatePrivateKey());
68
+ const validUntil = (BigInt(Date.now()) + BigInt(p.ttlMs)) * 1000n; // µs
69
+ const typedData = delegationTypedData(account.address, validUntil, p.chainId);
70
+ const signature = await p.signTypedData(typedData);
71
+ const recovered = await recoverTypedDataAddress({ ...typedData, signature });
72
+ if (recovered.toLowerCase() !== p.master.toLowerCase()) {
73
+ throw new Error(`delegation signed by ${recovered}, not ${p.master} — is the right account active?`);
74
+ }
75
+
76
+ const chain = defineChain({
77
+ id: p.chainId, name: `pod-${p.chainId}`,
78
+ nativeCurrency: { name: "pETH", symbol: "pETH", decimals: 18 },
79
+ rpcUrls: { default: { http: [p.rpcUrl] } },
80
+ });
81
+ const client = createWalletClient({ account, chain, transport: http(p.rpcUrl) });
82
+ const doFetch = p.fetch ?? fetch;
83
+
84
+ const submit = async (tx: PodTxRequest): Promise<Hash> => {
85
+ // Refuse to sign with a cert that can't cover a fresh intent deadline
86
+ // (~15 min out) — the node would reject the tx as expired anyway.
87
+ if (validUntil <= (BigInt(Date.now()) + 20n * 60_000n) * 1000n) {
88
+ throw new Error("delegation expired — re-authorize the wallet");
89
+ }
90
+ const data = encodeFunctionData({
91
+ abi: DELEGATED_ABI,
92
+ functionName: "delegated",
93
+ args: [p.master, validUntil, signature, tx.data],
94
+ });
95
+ const maxFeePerGas = BigInt(await rpc(p.rpcUrl, doFetch, "eth_gasPrice"));
96
+ const prepared = await client.prepareTransactionRequest({ ...tx, data, account, chain, maxFeePerGas });
97
+ const serialized = await client.signTransaction(prepared as never);
98
+ return sendRawTransaction(p.rpcUrl, serialized, { fetch: doFetch });
99
+ };
100
+
101
+ return Object.freeze({ master: p.master, delegate: account.address, validUntil, submit });
102
+ }
103
+
104
+ async function rpc(rpcUrl: string, doFetch: typeof fetch, method: string): Promise<string> {
105
+ const res = await doFetch(rpcUrl, {
106
+ method: "POST",
107
+ headers: { "content-type": "application/json" },
108
+ body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params: [] }),
109
+ });
110
+ const json = (await res.json()) as { result?: string; error?: { message?: string } };
111
+ if (json.error || json.result === undefined) throw new Error(json.error?.message ?? `${method} failed`);
112
+ return json.result;
113
+ }