@pod-network/trade-sdk 0.2.0 → 0.4.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 (87) hide show
  1. package/README.md +94 -2
  2. package/dist/client.d.ts +19 -1
  3. package/dist/client.d.ts.map +1 -1
  4. package/dist/client.js +25 -13
  5. package/dist/client.js.map +1 -1
  6. package/dist/codec/bridge.d.ts +82 -0
  7. package/dist/codec/bridge.d.ts.map +1 -0
  8. package/dist/codec/bridge.js +114 -0
  9. package/dist/codec/bridge.js.map +1 -0
  10. package/dist/codec/decode.d.ts +15 -2
  11. package/dist/codec/decode.d.ts.map +1 -1
  12. package/dist/codec/decode.js +46 -6
  13. package/dist/codec/decode.js.map +1 -1
  14. package/dist/codec/direction.d.ts +10 -0
  15. package/dist/codec/direction.d.ts.map +1 -0
  16. package/dist/codec/direction.js +46 -0
  17. package/dist/codec/direction.js.map +1 -0
  18. package/dist/codec/orders-v2.d.ts +19 -0
  19. package/dist/codec/orders-v2.d.ts.map +1 -0
  20. package/dist/codec/orders-v2.js +200 -0
  21. package/dist/codec/orders-v2.js.map +1 -0
  22. package/dist/codec/units.d.ts +10 -0
  23. package/dist/codec/units.d.ts.map +1 -1
  24. package/dist/codec/units.js +25 -1
  25. package/dist/codec/units.js.map +1 -1
  26. package/dist/index.d.ts +3 -0
  27. package/dist/index.d.ts.map +1 -1
  28. package/dist/index.js +5 -0
  29. package/dist/index.js.map +1 -1
  30. package/dist/sync/orders.d.ts +71 -16
  31. package/dist/sync/orders.d.ts.map +1 -1
  32. package/dist/sync/orders.js +202 -83
  33. package/dist/sync/orders.js.map +1 -1
  34. package/dist/sync/sources.d.ts +5 -1
  35. package/dist/sync/sources.d.ts.map +1 -1
  36. package/dist/sync/sources.js +16 -0
  37. package/dist/sync/sources.js.map +1 -1
  38. package/dist/sync/withdrawals.d.ts +5 -0
  39. package/dist/sync/withdrawals.d.ts.map +1 -0
  40. package/dist/sync/withdrawals.js +172 -0
  41. package/dist/sync/withdrawals.js.map +1 -0
  42. package/dist/transport/claim.d.ts +160 -0
  43. package/dist/transport/claim.d.ts.map +1 -0
  44. package/dist/transport/claim.js +341 -0
  45. package/dist/transport/claim.js.map +1 -0
  46. package/dist/transport/jsonrpc.d.ts +16 -0
  47. package/dist/transport/jsonrpc.d.ts.map +1 -0
  48. package/dist/transport/jsonrpc.js +42 -0
  49. package/dist/transport/jsonrpc.js.map +1 -0
  50. package/dist/transport/rest.d.ts +15 -1
  51. package/dist/transport/rest.d.ts.map +1 -1
  52. package/dist/transport/rest.js +25 -1
  53. package/dist/transport/rest.js.map +1 -1
  54. package/dist/transport/ws.d.ts +22 -2
  55. package/dist/transport/ws.d.ts.map +1 -1
  56. package/dist/transport/ws.js +14 -2
  57. package/dist/transport/ws.js.map +1 -1
  58. package/dist/types/public.d.ts +212 -9
  59. package/dist/types/public.d.ts.map +1 -1
  60. package/dist/types/wire.d.ts +147 -41
  61. package/dist/types/wire.d.ts.map +1 -1
  62. package/dist/write/delegation.d.ts.map +1 -1
  63. package/dist/write/delegation.js +2 -12
  64. package/dist/write/delegation.js.map +1 -1
  65. package/dist/write/index.d.ts +26 -1
  66. package/dist/write/index.d.ts.map +1 -1
  67. package/dist/write/index.js +21 -14
  68. package/dist/write/index.js.map +1 -1
  69. package/package.json +1 -1
  70. package/src/client.ts +33 -18
  71. package/src/codec/bridge.ts +138 -0
  72. package/src/codec/decode.ts +54 -10
  73. package/src/codec/direction.ts +36 -0
  74. package/src/codec/orders-v2.ts +222 -0
  75. package/src/codec/units.ts +24 -1
  76. package/src/index.ts +16 -0
  77. package/src/sync/orders.ts +203 -83
  78. package/src/sync/sources.ts +16 -1
  79. package/src/sync/withdrawals.ts +177 -0
  80. package/src/transport/claim.ts +434 -0
  81. package/src/transport/jsonrpc.ts +54 -0
  82. package/src/transport/rest.ts +35 -7
  83. package/src/transport/ws.ts +30 -4
  84. package/src/types/public.ts +233 -7
  85. package/src/types/wire.ts +161 -29
  86. package/src/write/delegation.ts +2 -12
  87. package/src/write/index.ts +59 -13
@@ -32,6 +32,125 @@ export type OrderDirection =
32
32
  | "open_short" | "add_short" | "reduce_short" | "close_short"
33
33
  | "long_to_short" | "short_to_long" | "liquidation";
34
34
 
35
+ /**
36
+ * Why the engine refused something, as a stable identifier to branch on.
37
+ *
38
+ * Open by design: a newer node may report a code this version does not list, so
39
+ * treat an unrecognised one like `"unspecified"` — the accompanying `message` is
40
+ * then all there is. `"unspecified"` itself means the engine has not given that
41
+ * reason a name yet.
42
+ */
43
+ export type RejectCode =
44
+ | "insufficient_balance" | "invalid_price" | "zero_size" | "notional_below_minimum"
45
+ | "unknown_market" | "order_not_found" | "not_order_owner" | "stale_nonce"
46
+ | "wrong_pair" | "engine_managed_order" | "price_above_maximum" | "price_off_tick"
47
+ | "market_order_must_be_ioc" | "size_above_maximum" | "size_off_lot"
48
+ | "notional_overflow" | "notional_above_cap" | "unspecified"
49
+ | (string & {});
50
+
51
+ /**
52
+ * An amendment the engine refused. The order itself is untouched — this is the
53
+ * answer to a price/size change that did not happen.
54
+ *
55
+ * The requested price and size are echoed back because a client may have several
56
+ * amendments outstanding on one order, and they are how it tells which one this
57
+ * answers.
58
+ */
59
+ export interface AmendRejection {
60
+ /** The price that was asked for. */
61
+ requestedPrice: bigint;
62
+ /** The size that was asked for, as an unsigned magnitude. */
63
+ requestedSize: bigint;
64
+ /** Branch on this rather than on `message`. */
65
+ code: RejectCode;
66
+ /**
67
+ * Present only when the reason carries detail the code cannot — the amounts on
68
+ * `insufficient_balance`, `invalid_price` and `notional_below_minimum`, the pair on
69
+ * `unknown_market`, and the whole reason on `unspecified`. For every other code the
70
+ * message would just restate the code.
71
+ */
72
+ message?: string;
73
+ /**
74
+ * Who asked. Deliberately not the order's owner: a refusal says nothing about who
75
+ * owns the order, and on `not_order_owner` the requester is precisely who does not.
76
+ * Absent when the stream names a single account.
77
+ */
78
+ requestedBy?: Address;
79
+ /** The batch the refusal landed in (ms). */
80
+ batchMs: number;
81
+ }
82
+
83
+ /** What the engine did to an order, as `pod_orders_v2` reports it (ADR 0029 §3). */
84
+ export type OrderEventKind =
85
+ | "new" | "reject" | "fill" | "cancel" | "expire" | "modify" | "modify_reject";
86
+
87
+ /**
88
+ * The statuses an order can *close* with. Narrower than `OrderStatus`, which also
89
+ * covers the states a live order passes through — so a `switch` over this one can be
90
+ * exhaustive.
91
+ */
92
+ export type TerminalStatus = Extract<OrderStatus, "filled" | "canceled" | "margin_canceled" | "expired">;
93
+
94
+ /** One fill, plus the status it closed the order with when it did. */
95
+ export interface OrderEventFill extends PartialFill {
96
+ /**
97
+ * Base filled over the order's life **as of this fill**.
98
+ *
99
+ * Not the same as `order.filledBase`, which is where the *whole frame* left the order:
100
+ * two fills of one order in one batch would otherwise both report the final total,
101
+ * so neither matches the fill it is attached to.
102
+ */
103
+ totalBase: bigint;
104
+ /**
105
+ * Absent while the order is still working.
106
+ *
107
+ * `margin_canceled` here is the engine evicting the order for margin, reported on the
108
+ * fill that closed it. An eviction that closes an order *without* a fill arrives as a
109
+ * plain `cancel` instead: the wire cannot yet distinguish it from a user cancel (ADR
110
+ * 0029 §6 reserves a `why` for that), so do not try to re-derive it from `status`.
111
+ */
112
+ closedAs?: TerminalStatus;
113
+ }
114
+
115
+ /**
116
+ * One transition the stream reported.
117
+ *
118
+ * The alternative is diffing consecutive snapshots, which can only see net state: two
119
+ * fills in one batch collapse into one change, a fill that closes an order hides the
120
+ * partial, and a transition that changes nothing about the order — a refused amendment
121
+ * — is invisible without a synthetic marker to spot it by.
122
+ *
123
+ * Deliberately lean. `order` is the row as the whole frame left it, so durable state a
124
+ * transition leaves behind is read from there — a `reject`'s `rejectReason` annotates the
125
+ * `invalid` status it set. Detail that belongs to the transition itself, and describes
126
+ * nothing about the order afterwards, is on the event: `fill`, and `amendRejection`.
127
+ */
128
+ export interface OrderEvent {
129
+ kind: OrderEventKind;
130
+ /**
131
+ * The order it happened to, as the whole frame left it.
132
+ *
133
+ * A live row, not a copy: the stream mutates it in place as later frames arrive. Read
134
+ * it in the callback, and copy it if you keep it — a buffered event would otherwise
135
+ * show the order's present state rather than its state at the time.
136
+ */
137
+ order: Order;
138
+ /** The batch it landed in (ms). */
139
+ batchMs: number;
140
+ /** `fill` only: this fill alone, not a running total. */
141
+ fill?: OrderEventFill;
142
+ /**
143
+ * `modify_reject` only: the amendment the engine refused.
144
+ *
145
+ * On the event rather than on `order`, because the order is exactly what it is not
146
+ * about — a refusal changes nothing about it. Parked on the entity it would be
147
+ * write-once and never cleared, so an order would keep reporting a refusal it had
148
+ * long since amended past, and only when the row came from this stream rather than
149
+ * from REST.
150
+ */
151
+ amendRejection?: AmendRejection;
152
+ }
153
+
35
154
  export interface TokenInfo {
36
155
  address: Address;
37
156
  symbol: string;
@@ -117,10 +236,13 @@ export interface PartialFill {
117
236
  export interface Order {
118
237
  id: Hash;
119
238
  txHash: Hash;
120
- orderbookId?: MarketId; // REST orders; WS stream orders carry `pair` instead
239
+ orderbookId?: MarketId;
240
+ /**
241
+ * Whether the book is spot or perp, when the source said so — REST rows carry it,
242
+ * streamed ones do not. It is static market metadata rather than a fact about the
243
+ * order, so the reliable read is a join: `markets.find((m) => m.id === o.orderbookId)?.type`.
244
+ */
121
245
  marketType?: MarketType;
122
- /** Token-address pair (base/quote); present on WS stream orders. */
123
- pair?: { base: Address; quote: Address };
124
246
  side: OrderSide;
125
247
  orderType: OrderType;
126
248
  status: OrderStatus;
@@ -133,11 +255,20 @@ export interface Order {
133
255
  filledQuote: bigint;
134
256
  fee: bigint;
135
257
  effectivePrice?: bigint;
136
- deadlineMs: number;
137
- endMs: number;
138
- /** Batch-inclusion time (ms) — when the order entered the book. REST history only. */
258
+ /**
259
+ * The auction deadline the order was signed for (ms). REST only: it is a fact
260
+ * about the intent, not about when the order became real, and the
261
+ * `pod_orders_v2` frame does not carry it. To order orders, use `includedMs` —
262
+ * both sources report that.
263
+ */
264
+ deadlineMs?: number;
265
+ /** TTL expiry (ms). Undefined when the order never expires. */
266
+ endMs?: number;
267
+ /** Batch-inclusion time (ms) — when the order entered the book. */
139
268
  includedMs?: number;
140
269
  fills: PartialFill[];
270
+ /** Why the engine rejected the order; set only on `status: "invalid"`. */
271
+ rejectReason?: string;
141
272
  // perpetual-only
142
273
  reduceOnly?: boolean;
143
274
  ioc?: boolean;
@@ -201,7 +332,8 @@ export interface Trigger {
201
332
  reduceOnly: boolean;
202
333
  ioc: boolean;
203
334
  deadlineMs: number;
204
- endMs: number;
335
+ /** TTL expiry (ms). Undefined when the trigger never expires. */
336
+ endMs?: number;
205
337
  }
206
338
 
207
339
  export interface BackstopTransfer {
@@ -333,3 +465,97 @@ export interface TriggersQuery {
333
465
  orderbookId?: MarketId;
334
466
  limit?: number;
335
467
  }
468
+
469
+ // --- bridge / withdrawals (ADR 0033) ---
470
+
471
+ /**
472
+ * One bridged token, as `GET /v1/bridge/config` serves it.
473
+ *
474
+ * `min`, `max` and `decimals` are all on the **claim chain's** terms, not pod's
475
+ * 18 — see `codec/bridge.ts`, which owns that conversion.
476
+ */
477
+ export interface BridgeToken {
478
+ podToken: Address;
479
+ l1Token: Address;
480
+ /** Decimals on the claim chain, and so the withdrawal granularity on pod. */
481
+ decimals: number;
482
+ /** Smallest admissible withdrawal, in claim-chain decimals. */
483
+ min: bigint;
484
+ /** Largest admissible withdrawal, in claim-chain decimals. */
485
+ max: bigint;
486
+ }
487
+
488
+ /** Static bridge configuration — the one chain pod withdrawals settle on. */
489
+ export interface BridgeConfig {
490
+ /** `0` when the node has no bridge configured, in which case `tokens` is
491
+ * empty and no withdrawal is admissible at all. */
492
+ claimChainId: number;
493
+ /** The bridge contract on the claim chain, where `Claim` is emitted. */
494
+ sourceContract: Address;
495
+ /** Bridge version; feeds the claim-hash domain separator. */
496
+ version: number;
497
+ tokens: BridgeToken[];
498
+ }
499
+
500
+ /**
501
+ * Why a withdrawal produced no L1 claim. Any value here means **no L1 event will
502
+ * ever fire**, so a client watching only the claim chain would wait forever —
503
+ * this is the only place a reason exists.
504
+ */
505
+ export type WithdrawalError =
506
+ /** The CLOB balance did not cover it at execution. Admission deliberately
507
+ * doesn't check the balance (pending fills can raise it), so this races that. */
508
+ | "insufficient_balance"
509
+ /** The solver never included the intent before its deadline. Funds are
510
+ * untouched and the withdrawal can simply be resubmitted. */
511
+ | "not_included"
512
+ /**
513
+ * Any other reason a node reports. This set is **open by construction**: the
514
+ * node's reason enum is explicitly extensible and an app ships ahead of the
515
+ * fleet, so a spelling this build predates has to arrive verbatim rather than
516
+ * be dropped. Dropping it makes a *failed* withdrawal read as claimable —
517
+ * the one direction it is unsafe to be lossy in, because the caller then
518
+ * reports success and waits for a claim that can never land.
519
+ *
520
+ * `(string & {})` keeps the two known values in editor completion while still
521
+ * admitting the rest. Treat an unknown reason exactly like a known one, and
522
+ * show it verbatim rather than guessing which known reason it resembles.
523
+ */
524
+ | (string & {});
525
+
526
+ /** One terminal withdrawal outcome, from `pod_withdrawals` or its REST backfill. */
527
+ export interface Withdrawal {
528
+ /** `keccak(abi.encode(signer, nonce, sequence))` — derivable client-side
529
+ * before submitting, which is what lets a client match its own withdrawal. */
530
+ id: Hash;
531
+ /** The debited account: the master, for a delegated withdrawal. */
532
+ withdrawer: Address;
533
+ /** Recipient on the **claim chain**. Nothing is credited on pod. */
534
+ to: Address;
535
+ /** Pod-side token address. */
536
+ token: Address;
537
+ /** Pod's 18 decimals, as signed. The L1 claim carries this converted to the
538
+ * token's claim-chain decimals — never pass this value to `claim`. */
539
+ amount: bigint;
540
+ /** Absent when the withdrawal is claimable on L1. */
541
+ error?: WithdrawalError;
542
+ /**
543
+ * The tick's batch deadline, in **microseconds** — not the millisecond
544
+ * convention the rest of this surface uses.
545
+ *
546
+ * Deliberate: this value is also the resume cursor for `pod_withdrawals` and
547
+ * for the REST backfill, both of which compare it in micros. Narrowing it to
548
+ * ms and back would round a tick boundary and silently re-serve or skip a
549
+ * tick, so it stays in the unit the server compares.
550
+ */
551
+ timeUs: number;
552
+ }
553
+
554
+ export interface WithdrawalsQuery {
555
+ /** Batch deadline in microseconds; strictly greater. */
556
+ since?: number;
557
+ /** Last id already seen *within* the `since` tick, to resume mid-tick. */
558
+ sinceId?: Hash;
559
+ /** Server default 500, capped at 1000. */
560
+ limit?: number;
561
+ }
package/src/types/wire.ts CHANGED
@@ -3,7 +3,7 @@
3
3
  // strings; timestamps are microseconds (in `*_us` fields, or bare on candle/
4
4
  // orderbook). Decoders in ../codec/decode.ts convert these to ../types/public.
5
5
 
6
- import type { Hex } from "./public.js";
6
+ import type { Hex, OrderEventKind } from "./public.js";
7
7
 
8
8
  export type WireDecimal = string; // 1e18-scaled integer as a decimal string
9
9
 
@@ -89,8 +89,9 @@ export interface WirePartialFill {
89
89
  }
90
90
 
91
91
  export interface WireOrder {
92
- orderbook_id?: Hex; // REST only; WS raw Order carries `pair` instead
93
- market_type?: "spot" | "perp"; // REST only
92
+ orderbook_id?: Hex;
93
+ /** The order endpoints say "perpetual" where `/clob/markets` says "perp". */
94
+ market_type?: "spot" | "perp" | "perpetual";
94
95
  kind: string;
95
96
  order_id: Hex;
96
97
  tx_hash: Hex;
@@ -108,9 +109,6 @@ export interface WireOrder {
108
109
  included_batch?: number | string; // micros; batch-inclusion time (REST order history)
109
110
  effective_price?: WireDecimal | null;
110
111
  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
112
  side?: "buy" | "sell";
115
113
  reduce_only?: boolean;
116
114
  ioc?: boolean;
@@ -128,7 +126,6 @@ export interface WireOrdersPage {
128
126
 
129
127
  export interface WireTickSnapshot {
130
128
  volume: WireDecimal;
131
- minimum_expiry?: number;
132
129
  }
133
130
 
134
131
  export interface WireOrderbook {
@@ -263,29 +260,117 @@ export interface WireBackstopPage {
263
260
  solution_now: number;
264
261
  }
265
262
 
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 };
263
+ // --- pod_orders_v2 push (ADR 0029) ---
264
+ //
265
+ // One notification is one frame: everything that happened to one orderbook in one
266
+ // auction batch. The book and the batch are named once, orders created in the
267
+ // batch appear once in `orders`, and `events` are transitions referencing them.
268
+ // Optional fields are omitted at their default rather than sent, so each absence
269
+ // means something specific — noted per field.
274
270
 
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;
271
+ export interface WireOrdersFrame {
272
+ /** The orderbook these actions happened on; constant for the frame. */
273
+ book: Hex;
274
+ /** Deadline (micros) of the batch the actions **landed in**. Half of the resume cursor; `book` is the other half. */
275
+ batch: number;
276
+ /**
277
+ * Owner addresses, indexed by `orders[].a` and by events that name an order by
278
+ * `id`. Omitted when the subscription names exactly one account — decode on
279
+ * this field, not on the filter that was sent.
280
+ */
281
+ accts?: Hex[];
282
+ orders: WireOrderEntity[];
283
+ events: WireOrderEvent[];
284
+ }
285
+
286
+ /** An order as admitted: the facts that do not change. Its status is implied by the events. */
287
+ export interface WireOrderEntity {
288
+ id: Hex;
289
+ /** Creating transaction, or its parent `submitBatch` envelope. */
290
+ tx: Hex;
291
+ /** Index into the frame's `accts`; present iff `accts` is. */
292
+ a?: number;
293
+ n: number;
294
+ px: WireDecimal;
295
+ /** Signed size: the sign carries the side, so there is no side field. */
296
+ sz: WireDecimal;
297
+ /** TTL expiry (micros). **Omitted means the order never expires.** */
298
+ end?: number;
299
+ /** **Omitted means user-signed.** */
300
+ kind?: string;
301
+ /** **Omitted means a limit order.** */
302
+ type?: "market";
303
+ /** Omitted means false. */
304
+ reduce_only?: boolean;
305
+ /** Omitted means false. */
306
+ ioc?: boolean;
307
+ /** Omitted unless the order is a fired trigger's synthetic. */
308
+ trigger?: string;
309
+ /** Omitted when ungrouped. */
310
+ grouping?: string;
311
+ }
312
+
313
+ /**
314
+ * One transition, discriminated by `k`. Every event names its order by exactly
315
+ * one of `o` (an index into this frame's `orders`) or `id` (resting from an
316
+ * earlier batch, owned by `accts[a]`).
317
+ *
318
+ * Kinds are open: unknown values of `k` must be ignored rather than rejected, so
319
+ * this is a plain shape with per-kind optional fields rather than a union that
320
+ * would make an unrecognised kind unrepresentable.
321
+ */
322
+ export interface WireOrderEvent {
323
+ k: OrderEventKind | (string & {});
324
+ o?: number;
325
+ id?: Hex;
326
+ a?: number;
327
+ /** `reject`: why the engine dropped the order. `modify_reject`: detail the `code` cannot carry. */
328
+ why?: string;
329
+ /**
330
+ * `modify_reject`: index into `accts` for the account that *asked*, which is not
331
+ * necessarily the order's owner — hence not `a`. On `not_order_owner` the requester
332
+ * is precisely who does not own it.
333
+ */
334
+ by?: number;
335
+ /** `modify_reject`: the price that was asked for. */
336
+ req_px?: WireDecimal;
337
+ /** `modify_reject`: the size that was asked for, unsigned. */
338
+ req_sz?: WireDecimal;
339
+ /** `modify_reject`: the stable reason identifier — branch on this, not on `why`. */
340
+ code?: string;
341
+ /** `fill`: base filled by **this** fill. */
342
+ b?: WireDecimal;
343
+ /** `fill`: quote filled by this fill. */
344
+ q?: WireDecimal;
345
+ /**
346
+ * Total base filled over the order's life so far.
347
+ *
348
+ * Carried by `fill`, `cancel` and `expire` alike (ADR 0029 §4.1): a terminated
349
+ * order reports what it had filled, as an explicit zero rather than an omission,
350
+ * so absence never has to be read as zero. Optional only because this one shape
351
+ * covers every kind — `new`, `reject` and `modify` have no totals to report.
352
+ */
353
+ tb?: WireDecimal;
354
+ /** Total quote filled so far; travels with `tb`. */
355
+ tq?: WireDecimal;
356
+ /** Total fee charged so far; travels with `tb`. There is no per-fill counterpart. */
357
+ tf?: WireDecimal;
358
+ /** `fill`: present only on the fill that closed the order, carrying its terminal status. */
359
+ st?: "filled" | "canceled" | "margin_canceled" | "expired";
360
+ /**
361
+ * `fill` on a perp market: the owner's position after this fill, signed and
362
+ * 1e18-scaled. Omitted on spot, which has no position.
363
+ *
364
+ * The position *before* is not sent because it is derivable — `pa - sign(sz) * b`,
365
+ * the same arithmetic the engine used to produce the pair — and the transition
366
+ * between the two is what says whether the fill opened, added to, reduced, closed
367
+ * or flipped the position.
368
+ */
369
+ pa?: WireDecimal;
370
+ /** `modify`: the price after the change. */
371
+ px?: WireDecimal;
372
+ /** `modify`: the size after the change, as an **unsigned magnitude**. */
373
+ sz?: WireDecimal;
289
374
  }
290
375
 
291
376
  export interface WirePositionsPush {
@@ -299,3 +384,50 @@ export interface WireTriggersPush {
299
384
  total_count: number;
300
385
  next_cursor: string | null;
301
386
  }
387
+
388
+ // --- bridge / withdrawals (ADR 0033) ---
389
+
390
+ export interface WireBridgeToken {
391
+ pod_token: Hex;
392
+ l1_token: Hex;
393
+ decimals: number;
394
+ /** Hex-encoded U256, in claim-chain decimals. */
395
+ min: string;
396
+ max: string;
397
+ }
398
+
399
+ export interface WireBridgeConfig {
400
+ claim_chain_id: number;
401
+ source_contract: Hex;
402
+ version: number;
403
+ tokens: WireBridgeToken[];
404
+ }
405
+
406
+ /** `pod_withdrawals` delivers an ARRAY of these per tick; the REST backfill
407
+ * serves the identical shape, so a backfilled outcome is indistinguishable
408
+ * from one that arrived live. */
409
+ export interface WireWithdrawal {
410
+ withdrawal_id: Hex;
411
+ withdrawer: Hex;
412
+ to: Hex;
413
+ token: Hex;
414
+ /** Hex-encoded U256 in pod's 18 decimals — the amount as signed. */
415
+ amount: string;
416
+ /** Omitted (not null) when the withdrawal is claimable. */
417
+ error?: string | null;
418
+ timestamp_us: number;
419
+ }
420
+
421
+ /** `GET /v1/bridge/withdrawals/by-id/{id}`. Nested rather than flattened because
422
+ * `WithdrawalUpdate` carries a u128 and serde's `flatten` cannot round-trip one.
423
+ *
424
+ * `status` is always present, but it is NOT what a consumer decides on: `proof`
425
+ * takes precedence, including over a `status` this build has never seen, so an
426
+ * unfamiliar label cannot veto a certificate attached to the same response.
427
+ * `proof` is omitted (never null) until one can be assembled. `fetchClaimStatus`
428
+ * carries the full precedence. */
429
+ export interface WireWithdrawalDetail {
430
+ withdrawal: WireWithdrawal;
431
+ status: "claimable" | "pending" | "refused";
432
+ proof?: { claim_hash?: Hex | null };
433
+ }
@@ -13,6 +13,7 @@
13
13
  import { createWalletClient, defineChain, encodeFunctionData, http, parseAbi, recoverTypedDataAddress } from "viem";
14
14
  import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
15
15
  import type { Address, Hash, Hex } from "../types/public.js";
16
+ import { rpc } from "../transport/jsonrpc.js";
16
17
  import { sendRawTransaction, type PodTxRequest } from "./index.js";
17
18
 
18
19
  /** EIP-712 payload the master signs (domain "pod delegation" v1). */
@@ -92,7 +93,7 @@ export async function createDelegatedWallet(p: CreateDelegatedWalletParams): Pro
92
93
  functionName: "delegated",
93
94
  args: [p.master, validUntil, signature, tx.data],
94
95
  });
95
- const maxFeePerGas = BigInt(await rpc(p.rpcUrl, doFetch, "eth_gasPrice"));
96
+ const maxFeePerGas = BigInt(await rpc<string>(p.rpcUrl, "eth_gasPrice", [], { fetch: doFetch }));
96
97
  const prepared = await client.prepareTransactionRequest({ ...tx, data, account, chain, maxFeePerGas });
97
98
  const serialized = await client.signTransaction(prepared as never);
98
99
  return sendRawTransaction(p.rpcUrl, serialized, { fetch: doFetch });
@@ -100,14 +101,3 @@ export async function createDelegatedWallet(p: CreateDelegatedWalletParams): Pro
100
101
 
101
102
  return Object.freeze({ master: p.master, delegate: account.address, validUntil, submit });
102
103
  }
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
- }
@@ -13,6 +13,7 @@
13
13
  import { decodeAbiParameters, encodeAbiParameters, encodeFunctionData, keccak256, parseAbi } from "viem";
14
14
  import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
15
15
  import type { Address, Hash, Hex, MarketId } from "../types/public.js";
16
+ import { rpc } from "../transport/jsonrpc.js";
16
17
 
17
18
  /** The CLOB precompile (chain id 1293 / 0x50d). */
18
19
  export const CLOB_ADDRESS: Address = "0x50d0000000000000000000000000000000000002";
@@ -26,6 +27,7 @@ const CLOB_ABI = parseAbi([
26
27
  "function cancelTrigger(bytes32 orderbookId, bytes32 triggerOrder, uint128 deadline)",
27
28
  "function updateTrigger(bytes32 orderbookId, bytes32 triggerOrder, int256 newSize, uint256 newLimitPrice, uint256 newTriggerPrice, uint128 deadline)",
28
29
  "function submitBatch(bytes[] inner)",
30
+ "function withdraw(address token, address recipient, uint256 amount, uint128 deadline)",
29
31
  ]);
30
32
 
31
33
  /** ~10 years in microseconds — default far-future expiry for resting orders. */
@@ -587,18 +589,9 @@ export interface MintParams {
587
589
  * on rejection (e.g. "Minting is disabled") and Error on on-chain revert. */
588
590
  export async function mint(p: MintParams): Promise<TxReceipt> {
589
591
  const doFetch = p.fetch ?? fetch;
590
- const rpc = async (method: string): Promise<string> => {
591
- const res = await doFetch(p.rpcUrl, {
592
- method: "POST",
593
- headers: { "content-type": "application/json" },
594
- body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params: [] }),
595
- });
596
- const json = (await res.json()) as { result?: string; error?: { message?: string } };
597
- if (json.error || json.result === undefined) throw new Error(json.error?.message ?? `${method} failed`);
598
- return json.result;
599
- };
600
- const chainId = p.chainId ?? Number(await rpc("eth_chainId"));
601
- const maxFeePerGas = BigInt(await rpc("eth_gasPrice"));
592
+ const read = (method: string) => rpc<string>(p.rpcUrl, method, [], { fetch: doFetch });
593
+ const chainId = p.chainId ?? Number(await read("eth_chainId"));
594
+ const maxFeePerGas = BigInt(await read("eth_gasPrice"));
602
595
  const signer = privateKeyToAccount(generatePrivateKey());
603
596
  const data = encodeFunctionData({
604
597
  abi: MINT_ABI,
@@ -684,12 +677,65 @@ export function buildWaitlistDeposit(p: WaitlistDepositParams): SourceChainCall
684
677
  };
685
678
  }
686
679
 
680
+ // --- withdrawals (ADR 0033) --------------------------------------------------
681
+ //
682
+ // `Clob.withdraw` settles on L1 in ONE transaction: the CLOB balance is debited
683
+ // straight to the bridge's custody and N−F validators sign the L1 claim at
684
+ // solution execution. Nothing is credited to a pod account on the way, so the
685
+ // legacy `Bridge.withdraw` rules — `tx.value == amount`, a gas reserve, a second
686
+ // signature — do not apply, and MAX is the whole withdrawable balance.
687
+ //
688
+ // Two fields mean something different from the same-named ones elsewhere:
689
+ // - `recipient` is an address on the CLAIM chain, not on pod. Delegated calls
690
+ // stay pinned to the master (ADR 0018), so a session key cannot redirect it.
691
+ // - `amount` stays in pod's 18 decimals, but must be a whole number of
692
+ // claim-chain units or admission rejects it. Size it with `maxWithdrawable`
693
+ // / `quantizeWithdrawAmount` from `codec/bridge.ts` — this builder encodes
694
+ // what it is given and does no rounding of its own, because silently
695
+ // changing an amount a user signed for is worse than a clear rejection.
696
+
697
+ export interface ClobWithdrawParams {
698
+ /** Pod-side token address (native USD for cash). */
699
+ token: Address;
700
+ /** Recipient on the **claim chain**. */
701
+ recipient: Address;
702
+ /** 1e18-scaled, and a whole number of claim-chain units. */
703
+ amount: bigint;
704
+ /**
705
+ * Auction interval in microseconds (`market.auctionIntervalMs * 1000`).
706
+ *
707
+ * **Required, unlike the order builders'.** Admission refuses a deadline that
708
+ * is not a multiple of it, and the default here is a far-future timestamp with
709
+ * no reason to land on one — so an optional interval would silently produce a
710
+ * transaction that is rejected unless the clock happened to be aligned, and
711
+ * the rare one that slipped through would be stranded a decade out.
712
+ */
713
+ auctionIntervalUs: number;
714
+ deadline?: number; // ms; default far future
715
+ }
716
+
717
+ export function buildClobWithdraw(p: ClobWithdrawParams): PodTxRequest {
718
+ const nowUs = BigInt(Date.now()) * 1000n;
719
+ const deadline = alignDeadline(us(p.deadline, nowUs + FAR_US), BigInt(p.auctionIntervalUs));
720
+ const data = encodeFunctionData({
721
+ abi: CLOB_ABI,
722
+ functionName: "withdraw",
723
+ args: [p.token, p.recipient, p.amount, deadline],
724
+ }) as Hex;
725
+ return { to: CLOB_ADDRESS, data, value: 0n, type: "eip1559", maxPriorityFeePerGas: 0n, gas: 1_000_000n };
726
+ }
727
+
687
728
  /**
688
729
  * Deterministic order id: `keccak256(abi.encode(signer, nonce, sequence))`,
689
730
  * matching the engine (`trading/src/lib.rs`). `sequence` is the 0-based index
690
731
  * of the intent within a `submitBatch` (0 for a single-intent tx). Needs the
691
732
  * nonce, so it's only known up-front in managed mode; in advisory mode reconcile
692
- * by `tx_hash` from the `pod_orders` stream instead.
733
+ * by `tx` from the `pod_orders_v2` stream instead.
734
+ *
735
+ * **This is also the `withdrawal_id`** that `pod_withdrawals` reports and that
736
+ * `GET /v1/bridge/withdrawals/by-id/{id}` is keyed on — same derivation, same
737
+ * intent identity (ADR 0033 §3). `signer` is whoever signed the transaction,
738
+ * i.e. the delegate under a session key, not the debited master.
693
739
  */
694
740
  export function deriveOrderId(signer: Address, nonce: number, sequence = 0): Hash {
695
741
  return keccak256(