@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.
- package/README.md +94 -2
- package/dist/client.d.ts +19 -1
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +25 -13
- package/dist/client.js.map +1 -1
- package/dist/codec/bridge.d.ts +82 -0
- package/dist/codec/bridge.d.ts.map +1 -0
- package/dist/codec/bridge.js +114 -0
- package/dist/codec/bridge.js.map +1 -0
- package/dist/codec/decode.d.ts +15 -2
- package/dist/codec/decode.d.ts.map +1 -1
- package/dist/codec/decode.js +46 -6
- package/dist/codec/decode.js.map +1 -1
- package/dist/codec/direction.d.ts +10 -0
- package/dist/codec/direction.d.ts.map +1 -0
- package/dist/codec/direction.js +46 -0
- package/dist/codec/direction.js.map +1 -0
- package/dist/codec/orders-v2.d.ts +19 -0
- package/dist/codec/orders-v2.d.ts.map +1 -0
- package/dist/codec/orders-v2.js +200 -0
- package/dist/codec/orders-v2.js.map +1 -0
- package/dist/codec/units.d.ts +10 -0
- package/dist/codec/units.d.ts.map +1 -1
- package/dist/codec/units.js +25 -1
- package/dist/codec/units.js.map +1 -1
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -1
- package/dist/sync/orders.d.ts +71 -16
- package/dist/sync/orders.d.ts.map +1 -1
- package/dist/sync/orders.js +202 -83
- package/dist/sync/orders.js.map +1 -1
- package/dist/sync/sources.d.ts +5 -1
- package/dist/sync/sources.d.ts.map +1 -1
- package/dist/sync/sources.js +16 -0
- package/dist/sync/sources.js.map +1 -1
- package/dist/sync/withdrawals.d.ts +5 -0
- package/dist/sync/withdrawals.d.ts.map +1 -0
- package/dist/sync/withdrawals.js +172 -0
- package/dist/sync/withdrawals.js.map +1 -0
- package/dist/transport/claim.d.ts +160 -0
- package/dist/transport/claim.d.ts.map +1 -0
- package/dist/transport/claim.js +341 -0
- package/dist/transport/claim.js.map +1 -0
- package/dist/transport/jsonrpc.d.ts +16 -0
- package/dist/transport/jsonrpc.d.ts.map +1 -0
- package/dist/transport/jsonrpc.js +42 -0
- package/dist/transport/jsonrpc.js.map +1 -0
- package/dist/transport/rest.d.ts +15 -1
- package/dist/transport/rest.d.ts.map +1 -1
- package/dist/transport/rest.js +25 -1
- package/dist/transport/rest.js.map +1 -1
- package/dist/transport/ws.d.ts +22 -2
- package/dist/transport/ws.d.ts.map +1 -1
- package/dist/transport/ws.js +14 -2
- package/dist/transport/ws.js.map +1 -1
- package/dist/types/public.d.ts +212 -9
- package/dist/types/public.d.ts.map +1 -1
- package/dist/types/wire.d.ts +147 -41
- package/dist/types/wire.d.ts.map +1 -1
- package/dist/write/delegation.d.ts.map +1 -1
- package/dist/write/delegation.js +2 -12
- package/dist/write/delegation.js.map +1 -1
- package/dist/write/index.d.ts +26 -1
- package/dist/write/index.d.ts.map +1 -1
- package/dist/write/index.js +21 -14
- package/dist/write/index.js.map +1 -1
- package/package.json +1 -1
- package/src/client.ts +33 -18
- package/src/codec/bridge.ts +138 -0
- package/src/codec/decode.ts +54 -10
- package/src/codec/direction.ts +36 -0
- package/src/codec/orders-v2.ts +222 -0
- package/src/codec/units.ts +24 -1
- package/src/index.ts +16 -0
- package/src/sync/orders.ts +203 -83
- package/src/sync/sources.ts +16 -1
- package/src/sync/withdrawals.ts +177 -0
- package/src/transport/claim.ts +434 -0
- package/src/transport/jsonrpc.ts +54 -0
- package/src/transport/rest.ts +35 -7
- package/src/transport/ws.ts +30 -4
- package/src/types/public.ts +233 -7
- package/src/types/wire.ts +161 -29
- package/src/write/delegation.ts +2 -12
- package/src/write/index.ts +59 -13
package/src/types/public.ts
CHANGED
|
@@ -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;
|
|
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
|
-
|
|
137
|
-
|
|
138
|
-
|
|
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
|
-
|
|
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;
|
|
93
|
-
|
|
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
|
-
//
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
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
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
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
|
+
}
|
package/src/write/delegation.ts
CHANGED
|
@@ -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,
|
|
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
|
-
}
|
package/src/write/index.ts
CHANGED
|
@@ -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
|
|
591
|
-
|
|
592
|
-
|
|
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 `
|
|
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(
|