@pod-network/trade-sdk 0.5.0 → 0.7.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 (54) hide show
  1. package/README.md +7 -4
  2. package/dist/client.d.ts +1 -2
  3. package/dist/client.d.ts.map +1 -1
  4. package/dist/client.js +1 -2
  5. package/dist/client.js.map +1 -1
  6. package/dist/codec/decode.d.ts.map +1 -1
  7. package/dist/codec/decode.js +11 -4
  8. package/dist/codec/decode.js.map +1 -1
  9. package/dist/codec/orders-v2.js +2 -1
  10. package/dist/codec/orders-v2.js.map +1 -1
  11. package/dist/codec/units.d.ts +6 -0
  12. package/dist/codec/units.d.ts.map +1 -1
  13. package/dist/codec/units.js +8 -0
  14. package/dist/codec/units.js.map +1 -1
  15. package/dist/index.d.ts +1 -1
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +1 -1
  18. package/dist/index.js.map +1 -1
  19. package/dist/sync/order-preview.d.ts +4 -1
  20. package/dist/sync/order-preview.d.ts.map +1 -1
  21. package/dist/sync/order-preview.js +9 -5
  22. package/dist/sync/order-preview.js.map +1 -1
  23. package/dist/sync/sources.d.ts.map +1 -1
  24. package/dist/sync/sources.js +14 -9
  25. package/dist/sync/sources.js.map +1 -1
  26. package/dist/sync/withdrawals.js +7 -7
  27. package/dist/sync/withdrawals.js.map +1 -1
  28. package/dist/transport/ws.d.ts +1 -1
  29. package/dist/transport/ws.d.ts.map +1 -1
  30. package/dist/types/public.d.ts +14 -9
  31. package/dist/types/public.d.ts.map +1 -1
  32. package/dist/types/wire.d.ts +9 -3
  33. package/dist/types/wire.d.ts.map +1 -1
  34. package/dist/write/delegation.d.ts.map +1 -1
  35. package/dist/write/delegation.js +4 -1
  36. package/dist/write/delegation.js.map +1 -1
  37. package/dist/write/index.d.ts +39 -17
  38. package/dist/write/index.d.ts.map +1 -1
  39. package/dist/write/index.js +62 -29
  40. package/dist/write/index.js.map +1 -1
  41. package/package.json +1 -1
  42. package/src/client.ts +1 -2
  43. package/src/codec/decode.ts +13 -4
  44. package/src/codec/orders-v2.ts +2 -1
  45. package/src/codec/units.ts +9 -0
  46. package/src/index.ts +2 -1
  47. package/src/sync/order-preview.ts +13 -6
  48. package/src/sync/sources.ts +14 -9
  49. package/src/sync/withdrawals.ts +8 -8
  50. package/src/transport/ws.ts +1 -1
  51. package/src/types/public.ts +14 -9
  52. package/src/types/wire.ts +10 -4
  53. package/src/write/delegation.ts +4 -1
  54. package/src/write/index.ts +99 -49
@@ -20,7 +20,7 @@ export type OrderSide = "buy" | "sell";
20
20
  export type OrderType = "limit" | "market";
21
21
  export type OrderStatus =
22
22
  | "pending" | "active" | "filled" | "expired"
23
- | "canceled" | "margin_canceled" | "invalid";
23
+ | "canceled" | "margin_canceled" | "invalid" | "post_only_refused";
24
24
  export type OrderKind =
25
25
  | "user_signed" | "liquidation" | "triggered" | "adl" | "adl_counterparty"
26
26
  /** A backstop transfer merged into the order feed as a synthetic terminal row. */
@@ -89,7 +89,7 @@ export type OrderEventKind =
89
89
  * covers the states a live order passes through — so a `switch` over this one can be
90
90
  * exhaustive.
91
91
  */
92
- export type TerminalStatus = Extract<OrderStatus, "filled" | "canceled" | "margin_canceled" | "expired">;
92
+ export type TerminalStatus = Extract<OrderStatus, "filled" | "canceled" | "margin_canceled" | "expired" | "post_only_refused">;
93
93
 
94
94
  /** One fill, plus the status it closed the order with when it did. */
95
95
  export interface OrderEventFill extends PartialFill {
@@ -160,11 +160,15 @@ export interface TokenInfo {
160
160
  export interface Market {
161
161
  id: MarketId;
162
162
  name: string; // "BASE/QUOTE"
163
+ status: "active" | (string & {});
163
164
  type: MarketType;
164
165
  base: TokenInfo;
165
166
  quote: TokenInfo;
166
167
  tickPrecision: bigint;
168
+ /** Minimum size increment; sizes must be whole multiples (`size_off_lot`). */
167
169
  lotSize: bigint;
170
+ /** Floor on an order's notional, 0 when the market sets none. */
171
+ minNotional: bigint;
168
172
  maxLeverage: number;
169
173
  fundingWindowUs: number; // funding-accrual divisor (micros)
170
174
  makerFee: bigint;
@@ -390,8 +394,11 @@ export interface TxExplorer {
390
394
  chainId?: string;
391
395
  maxFeePerGas?: string;
392
396
  effectiveGasPrice?: string;
393
- blockNumber?: string;
394
- transactionIndex?: string;
397
+ /** Null when the tx is in no block (solutions, recovery, an intent whose
398
+ * auction tick has not run yet); a height once it is sequenced. */
399
+ blockNumber?: string | null;
400
+ /** Always null: pod does not order the transactions within a block. */
401
+ transactionIndex?: string | null;
395
402
  contractAddress?: string | null;
396
403
  [k: string]: unknown;
397
404
  }
@@ -525,10 +532,8 @@ export type WithdrawalError =
525
532
 
526
533
  /** One terminal withdrawal outcome, from `pod_withdrawals` or its REST backfill. */
527
534
  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. */
535
+ txHash: Hash;
536
+ /** The debited account. */
532
537
  withdrawer: Address;
533
538
  /** Recipient on the **claim chain**. Nothing is credited on pod. */
534
539
  to: Address;
@@ -554,7 +559,7 @@ export interface Withdrawal {
554
559
  export interface WithdrawalsQuery {
555
560
  /** Batch deadline in microseconds; strictly greater. */
556
561
  since?: number;
557
- /** Last id already seen *within* the `since` tick, to resume mid-tick. */
562
+ /** Last tx hash already seen *within* the `since` tick, to resume mid-tick. */
558
563
  sinceId?: Hash;
559
564
  /** Server default 500, capped at 1000. */
560
565
  limit?: number;
package/src/types/wire.ts CHANGED
@@ -14,6 +14,8 @@ export interface WireStatus {
14
14
  export interface WireMarketStatic {
15
15
  id: Hex;
16
16
  name: string;
17
+ /** Open, not an enum: a newer node's value must not be a type error. */
18
+ status: "active" | (string & {});
17
19
  base_token_address: Hex;
18
20
  quote_token_address: Hex;
19
21
  base_token_symbol: string;
@@ -25,7 +27,8 @@ export interface WireMarketStatic {
25
27
  maker_fee: WireDecimal;
26
28
  taker_fee: WireDecimal;
27
29
  tick_precision: WireDecimal; // 1e18-scaled price increment (decimal string)
28
- lot_size: WireDecimal;
30
+ lot_size: WireDecimal; // 1e18-scaled size increment
31
+ min_notional: WireDecimal; // 1e18-scaled notional floor ("0" = none)
29
32
  max_leverage: number;
30
33
  funding_window_us: number; // funding-accrual divisor (micros)
31
34
  }
@@ -355,8 +358,11 @@ export interface WireOrderEvent {
355
358
  tq?: WireDecimal;
356
359
  /** Total fee charged so far; travels with `tb`. There is no per-fill counterpart. */
357
360
  tf?: WireDecimal;
358
- /** `fill`: present only on the fill that closed the order, carrying its terminal status. */
359
- st?: "filled" | "canceled" | "margin_canceled" | "expired";
361
+ /**
362
+ * The terminal status an event closed the order with. On `fill`, only on the fill that
363
+ * closed it. On `cancel`, only when the engine removed the order rather than the owner.
364
+ */
365
+ st?: "filled" | "canceled" | "margin_canceled" | "expired" | "post_only_refused";
360
366
  /**
361
367
  * `fill` on a perp market: the owner's position after this fill, signed and
362
368
  * 1e18-scaled. Omitted on spot, which has no position.
@@ -407,7 +413,7 @@ export interface WireBridgeConfig {
407
413
  * serves the identical shape, so a backfilled outcome is indistinguishable
408
414
  * from one that arrived live. */
409
415
  export interface WireWithdrawal {
410
- withdrawal_id: Hex;
416
+ tx_hash: Hex;
411
417
  withdrawer: Hex;
412
418
  to: Hex;
413
419
  token: Hex;
@@ -14,7 +14,7 @@ import { createWalletClient, defineChain, encodeFunctionData, http, parseAbi, re
14
14
  import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
15
15
  import type { Address, Hash, Hex } from "../types/public.js";
16
16
  import { rpc } from "../transport/jsonrpc.js";
17
- import { sendRawTransaction, type PodTxRequest } from "./index.js";
17
+ import { CLOB_ADDRESS, sendRawTransaction, type PodTxRequest } from "./index.js";
18
18
 
19
19
  /** EIP-712 payload the master signs (domain "pod delegation" v1). */
20
20
  export function delegationTypedData(delegate: Address, validUntil: bigint, chainId: number) {
@@ -83,6 +83,9 @@ export async function createDelegatedWallet(p: CreateDelegatedWalletParams): Pro
83
83
  const doFetch = p.fetch ?? fetch;
84
84
 
85
85
  const submit = async (tx: PodTxRequest): Promise<Hash> => {
86
+ if (tx.to.toLowerCase() !== CLOB_ADDRESS) {
87
+ throw new Error(`delegation covers CLOB calls only, not ${tx.to} — sign this with the master wallet`);
88
+ }
86
89
  // Refuse to sign with a cert that can't cover a fresh intent deadline
87
90
  // (~15 min out) — the node would reject the tx as expired anyway.
88
91
  if (validUntil <= (BigInt(Date.now()) + 20n * 60_000n) * 1000n) {
@@ -1,4 +1,4 @@
1
- // Write helpers: build unsigned CLOB transactions and derive order ids. These
1
+ // Write helpers: build unsigned pod transactions and derive order ids. These
2
2
  // are pure encoding — no wallet, no key, no nonce ownership. The consumer signs
3
3
  // + broadcasts the returned request with whatever wallet it has
4
4
  // (walletClient.sendTransaction / eth_sendTransaction / Privy).
@@ -14,10 +14,17 @@ import { decodeAbiParameters, encodeAbiParameters, encodeFunctionData, keccak256
14
14
  import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
15
15
  import type { Address, Hash, Hex, MarketId } from "../types/public.js";
16
16
  import { rpc } from "../transport/jsonrpc.js";
17
+ // In codec/ so the read entry reaches it too; re-exported so all three align* are here.
18
+ import { alignSize } from "../codec/units.js";
19
+
20
+ export { alignSize };
17
21
 
18
22
  /** The CLOB precompile (chain id 1293 / 0x50d). */
19
23
  export const CLOB_ADDRESS: Address = "0x50d0000000000000000000000000000000000002";
20
24
 
25
+ /** The bridge precompile. */
26
+ export const BRIDGE_ADDRESS: Address = "0x50d0000000000000000000000000000000000001";
27
+
21
28
  const CLOB_ABI = parseAbi([
22
29
  "function submitOrder(bytes32 orderbookId, int256 size, uint256 price, uint8 orderType, uint128 deadline, uint128 ttl, bool reduceOnly, bool ioc)",
23
30
  "function cancel(bytes32 orderbookId, bytes32 canceledOrder, uint128 deadline)",
@@ -27,7 +34,10 @@ const CLOB_ABI = parseAbi([
27
34
  "function cancelTrigger(bytes32 orderbookId, bytes32 triggerOrder, uint128 deadline)",
28
35
  "function updateTrigger(bytes32 orderbookId, bytes32 triggerOrder, int256 newSize, uint256 newLimitPrice, uint256 newTriggerPrice, uint128 deadline)",
29
36
  "function submitBatch(bytes[] inner)",
30
- "function withdraw(address token, address recipient, uint256 amount, uint128 deadline)",
37
+ ]);
38
+
39
+ const BRIDGE_ABI = parseAbi([
40
+ "function withdraw(address token, address to, uint256 amount, uint128 deadline)",
31
41
  ]);
32
42
 
33
43
  /** ~10 years in microseconds — default far-future expiry for resting orders. */
@@ -45,6 +55,11 @@ export interface SubmitOrderParams {
45
55
  * like 49999.99999999999). Pass `market.tickPrecision`.
46
56
  */
47
57
  tickPrecision?: bigint;
58
+ /**
59
+ * Market `lot_size`. When given, `size` is floored to a multiple of it — the CLOB
60
+ * rejects a size off the lot grid (`size_off_lot`). Pass `market.lotSize`.
61
+ */
62
+ lotSize?: bigint;
48
63
  /**
49
64
  * Market auction interval in microseconds (`market.auctionIntervalMs * 1000`).
50
65
  * The CLOB requires `deadline` to be a multiple of it ("Deadline is not aligned
@@ -90,7 +105,9 @@ function us(ms: number | undefined, fallback: bigint): bigint {
90
105
 
91
106
  export function buildSubmitOrder(p: SubmitOrderParams): PodTxRequest {
92
107
  const nowUs = BigInt(Date.now()) * 1000n;
93
- const signedSize = p.side === "sell" ? -p.size : p.size;
108
+ // Align the magnitude before the sign: flooring a negative rounds it the wrong way.
109
+ const size = p.lotSize ? alignSize(p.size, p.lotSize) : p.size;
110
+ const signedSize = p.side === "sell" ? -size : size;
94
111
  const price = p.tickPrecision ? alignPrice(p.price, p.tickPrecision) : p.price;
95
112
  const interval = p.auctionIntervalUs ? BigInt(p.auctionIntervalUs) : 0n;
96
113
  const deadline = alignDeadline(us(p.deadline, nowUs + FAR_US), interval);
@@ -143,9 +160,13 @@ export function buildCancelOrder(
143
160
  /** Solidity `Error(string)` selector — `bytes4(keccak256("Error(string)"))`. */
144
161
  const ERROR_SELECTOR = "0x08c379a0";
145
162
 
146
- /** A reverted pod transaction, carrying the decoded CLOB reason. */
163
+ /**
164
+ * A rejected pod transaction. `data`'s shape follows `code`: −32000 validation (string),
165
+ * 3 execution revert (`Error(string)`, decoded into `reason`), −32003 rejection quorum
166
+ * (array), 999 account locked (object).
167
+ */
147
168
  export class PodTxRevertError extends Error {
148
- constructor(public reason: string, public data?: string) {
169
+ constructor(public reason: string, public data?: unknown, public code?: number) {
149
170
  super(reason);
150
171
  this.name = "PodTxRevertError";
151
172
  }
@@ -156,9 +177,11 @@ export class PodTxRevertError extends Error {
156
177
  * "Deadline is not aligned to auction interval"). Returns undefined when `data`
157
178
  * isn't an `Error(string)` payload — use this directly if you broadcast through
158
179
  * your own provider and just want to translate the revert data.
180
+ *
181
+ * `unknown` because only code 3 sends a string; the other shapes reach this too.
159
182
  */
160
- export function decodeRevertReason(data: string | null | undefined): string | undefined {
161
- if (!data || !data.startsWith(ERROR_SELECTOR)) return undefined;
183
+ export function decodeRevertReason(data: unknown): string | undefined {
184
+ if (typeof data !== "string" || !data.startsWith(ERROR_SELECTOR)) return undefined;
162
185
  try {
163
186
  return decodeAbiParameters([{ type: "string" }], `0x${data.slice(10)}` as Hex)[0];
164
187
  } catch {
@@ -183,10 +206,10 @@ export async function sendRawTransaction(
183
206
  headers: { "content-type": "application/json" },
184
207
  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_sendRawTransaction", params: [signedTx] }),
185
208
  });
186
- const json = (await res.json()) as { result?: Hash; error?: { message?: string; data?: string } };
209
+ const json = (await res.json()) as { result?: Hash; error?: { code?: number; message?: string; data?: unknown } };
187
210
  if (json.error) {
188
211
  const reason = decodeRevertReason(json.error.data) ?? json.error.message ?? "transaction failed";
189
- throw new PodTxRevertError(reason, json.error.data);
212
+ throw new PodTxRevertError(reason, json.error.data, json.error.code);
190
213
  }
191
214
  return json.result!;
192
215
  }
@@ -209,6 +232,7 @@ export interface UpdateOrderParams {
209
232
  */
210
233
  token: Address;
211
234
  tickPrecision?: bigint;
235
+ lotSize?: bigint;
212
236
  auctionIntervalUs?: number;
213
237
  deadline?: number; // ms; default far future
214
238
  }
@@ -216,13 +240,14 @@ export interface UpdateOrderParams {
216
240
  /**
217
241
  * Amend a resting order's price and/or size in place via the CLOB's native
218
242
  * `update` (no cancel+resubmit, so the order keeps its id and queue identity).
219
- * Aligns price to the tick and deadline to the auction interval, like
220
- * {@link buildSubmitOrder}.
243
+ * Aligns price to the tick, size to the lot and deadline to the auction interval,
244
+ * like {@link buildSubmitOrder}.
221
245
  */
222
246
  export function buildUpdateOrder(p: UpdateOrderParams): PodTxRequest {
223
247
  const nowUs = BigInt(Date.now()) * 1000n;
224
248
  const price = p.tickPrecision ? alignPrice(p.price, p.tickPrecision) : p.price;
225
- const size = p.size < 0n ? -p.size : p.size; // contract takes an unsigned magnitude
249
+ const mag = p.size < 0n ? -p.size : p.size; // contract takes an unsigned magnitude
250
+ const size = p.lotSize ? alignSize(mag, p.lotSize) : mag;
226
251
  const interval = p.auctionIntervalUs ? BigInt(p.auctionIntervalUs) : 0n;
227
252
  const deadline = alignDeadline(us(p.deadline, nowUs + FAR_US), interval);
228
253
  const data = encodeFunctionData({
@@ -265,6 +290,7 @@ export interface SubmitTriggerParams {
265
290
  reduceOnly?: boolean; // default true
266
291
  ioc?: boolean;
267
292
  tickPrecision?: bigint;
293
+ lotSize?: bigint;
268
294
  auctionIntervalUs?: number;
269
295
  deadline?: number; // ms; default far future
270
296
  /** Armed lifetime as a duration in ms (capped at ~30d by the CLOB); default 29d. */
@@ -273,7 +299,8 @@ export interface SubmitTriggerParams {
273
299
 
274
300
  export function buildSubmitTrigger(p: SubmitTriggerParams): PodTxRequest {
275
301
  const nowUs = BigInt(Date.now()) * 1000n;
276
- const signedSize = p.side === "sell" ? -p.size : p.size;
302
+ const size = p.lotSize ? alignSize(p.size, p.lotSize) : p.size;
303
+ const signedSize = p.side === "sell" ? -size : size;
277
304
  const align = (v: bigint) => (p.tickPrecision ? alignPrice(v, p.tickPrecision) : v);
278
305
  const triggerPrice = align(p.triggerPrice);
279
306
  const limitPrice = align(p.limitPrice ?? p.triggerPrice);
@@ -324,13 +351,15 @@ export interface UpdateTriggerParams {
324
351
  triggerPrice: bigint;
325
352
  limitPrice?: bigint;
326
353
  tickPrecision?: bigint;
354
+ lotSize?: bigint;
327
355
  auctionIntervalUs?: number;
328
356
  deadline?: number;
329
357
  }
330
358
 
331
359
  export function buildUpdateTrigger(p: UpdateTriggerParams): PodTxRequest {
332
360
  const nowUs = BigInt(Date.now()) * 1000n;
333
- const signedSize = p.side === "sell" ? -p.size : p.size;
361
+ const size = p.lotSize ? alignSize(p.size, p.lotSize) : p.size;
362
+ const signedSize = p.side === "sell" ? -size : size;
334
363
  const align = (v: bigint) => (p.tickPrecision ? alignPrice(v, p.tickPrecision) : v);
335
364
  const interval = p.auctionIntervalUs ? BigInt(p.auctionIntervalUs) : 0n;
336
365
  const deadline = alignDeadline(us(p.deadline, nowUs + FAR_US), interval);
@@ -354,10 +383,15 @@ export function buildUpdateTrigger(p: UpdateTriggerParams): PodTxRequest {
354
383
  /** ~10 years in ms — default far-future deadline shared by batched legs. */
355
384
  const FAR_MS = 10 * 365 * 24 * 3600 * 1000;
356
385
 
357
- /** Scale a 1e18 size by a 0..1 fraction (e.g. close 50% of a position). */
358
- function scaleSize(size: bigint, fraction: number): bigint {
386
+ /**
387
+ * Scale a 1e18 size by a 0..1 fraction (e.g. close 50% of a position), floored to the lot.
388
+ * The fraction's own 1e-6 resolution is no substitute — that is a proportion, the lot is
389
+ * an absolute step, and only the lot is what the CLOB checks.
390
+ */
391
+ function scaleSize(size: bigint, fraction: number, lot?: bigint): bigint {
359
392
  const f = Math.max(0, Math.min(1, fraction));
360
- return (size * BigInt(Math.round(f * 1_000_000))) / 1_000_000n;
393
+ const scaled = (size * BigInt(Math.round(f * 1_000_000))) / 1_000_000n;
394
+ return lot ? alignSize(scaled, lot) : scaled;
361
395
  }
362
396
 
363
397
  /** Wrap already-built legs into one `submitBatch` tx. Pass leg requests (their
@@ -367,7 +401,13 @@ export function buildSubmitBatch(
367
401
  legs: Array<PodTxRequest | Hex>,
368
402
  opts?: { gas?: bigint },
369
403
  ): PodTxRequest {
370
- const inner = legs.map((l) => (typeof l === "string" ? l : l.data));
404
+ const inner = legs.map((l) => {
405
+ if (typeof l === "string") return l;
406
+ if (l.to.toLowerCase() !== CLOB_ADDRESS) {
407
+ throw new Error(`submitBatch carries CLOB calls only, not a call to ${l.to}`);
408
+ }
409
+ return l.data;
410
+ });
371
411
  const data = encodeFunctionData({
372
412
  abi: CLOB_ABI,
373
413
  functionName: "submitBatch",
@@ -402,6 +442,7 @@ export interface OrderWithTriggersParams {
402
442
  takeProfit?: OrderTrigger;
403
443
  stopLoss?: OrderTrigger;
404
444
  tickPrecision?: bigint;
445
+ lotSize?: bigint;
405
446
  auctionIntervalUs?: number;
406
447
  reduceOnly?: boolean; // entry reduceOnly (rare); triggers are always reduceOnly
407
448
  ioc?: boolean;
@@ -421,13 +462,17 @@ export interface OrderWithTriggersParams {
421
462
  */
422
463
  export function buildOrderWithTriggers(p: OrderWithTriggersParams): PodTxRequest {
423
464
  const deadline = p.deadline ?? Date.now() + FAR_MS;
465
+ // Align once and hand the same size to entry and triggers: flooring only inside
466
+ // `buildSubmitOrder` would leave a whole-size trigger one lot over the position.
467
+ const size = p.lotSize ? alignSize(p.size, p.lotSize) : p.size;
424
468
  const order = buildSubmitOrder({
425
469
  orderbookId: p.orderbookId,
426
470
  side: p.side,
427
471
  orderType: p.orderType,
428
472
  price: p.price,
429
- size: p.size,
473
+ size,
430
474
  tickPrecision: p.tickPrecision,
475
+ lotSize: p.lotSize,
431
476
  auctionIntervalUs: p.auctionIntervalUs,
432
477
  reduceOnly: p.reduceOnly,
433
478
  ioc: p.ioc,
@@ -439,13 +484,14 @@ export function buildOrderWithTriggers(p: OrderWithTriggersParams): PodTxRequest
439
484
  buildSubmitTrigger({
440
485
  orderbookId: p.orderbookId,
441
486
  side: closeSide,
442
- size: scaleSize(p.size, t.sizeFraction ?? 1),
487
+ size: scaleSize(size, t.sizeFraction ?? 1, p.lotSize),
443
488
  triggerType,
444
489
  triggerPrice: t.triggerPrice,
445
490
  limitPrice: t.limitPrice,
446
491
  grouping: "position",
447
492
  reduceOnly: true,
448
493
  tickPrecision: p.tickPrecision,
494
+ lotSize: p.lotSize,
449
495
  auctionIntervalUs: p.auctionIntervalUs,
450
496
  deadline,
451
497
  ttlMs: p.triggerTtlMs,
@@ -479,6 +525,10 @@ export interface ClosePositionParams {
479
525
  /** Slippage bound in basis points for the market close. Default 500 (5%). */
480
526
  slippageBps?: number;
481
527
  tickPrecision?: bigint;
528
+ /** Market `lot_size`. A partial close is a fraction of the position and lands off the
529
+ * lot grid for most fractions; flooring leaves at most one lot open, which `reduceOnly`
530
+ * already makes the safe direction. */
531
+ lotSize?: bigint;
482
532
  auctionIntervalUs?: number;
483
533
  deadline?: number; // ms; pass a shared value when batching closes
484
534
  }
@@ -502,23 +552,27 @@ export function buildClosePosition(p: ClosePositionParams): PodTxRequest {
502
552
  size: p.size < 0n ? -p.size : p.size,
503
553
  reduceOnly: true,
504
554
  tickPrecision: p.tickPrecision,
555
+ lotSize: p.lotSize,
505
556
  auctionIntervalUs: p.auctionIntervalUs,
506
557
  deadline: p.deadline,
507
558
  });
508
559
  }
509
560
 
510
- /** A mined transaction receipt (the fields a consumer typically needs). */
561
+ /** A transaction receipt (the fields a consumer typically needs). */
511
562
  export interface TxReceipt {
512
563
  /** `success` when the tx executed (status `0x1`); `reverted` on `0x0`. */
513
564
  status: "success" | "reverted";
514
565
  transactionHash: Hash;
515
- blockNumber: bigint;
566
+ /** The height the tx was sequenced at, or `null` when it is in no block —
567
+ * `submitSolutions`, recovery txs, and an intent whose auction tick has not
568
+ * run yet. A null height is not a pending state: the receipt is still final. */
569
+ blockNumber: bigint | null;
516
570
  gasUsed: bigint;
517
571
  }
518
572
 
519
573
  /**
520
- * Poll `eth_getTransactionReceipt` until the tx is mined, then report whether it
521
- * executed or reverted. A hash from {@link sendRawTransaction} only means the
574
+ * Poll `eth_getTransactionReceipt` until a receipt exists, then report whether
575
+ * the tx executed or reverted. A hash from {@link sendRawTransaction} only means the
522
576
  * node accepted the tx into its pool — it is NOT yet confirmed. Await this to
523
577
  * know the on-chain outcome. Throws on timeout. Like the rest of this module
524
578
  * it's transport-only (raw JSON-RPC), so it needs no viem client.
@@ -539,14 +593,19 @@ export async function waitForReceipt(
539
593
  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_getTransactionReceipt", params: [hash] }),
540
594
  });
541
595
  const json = (await res.json()) as {
542
- result?: { status: string; transactionHash: Hash; blockNumber: string; gasUsed: string } | null;
596
+ result?: {
597
+ status: string;
598
+ transactionHash: Hash;
599
+ blockNumber?: string | null;
600
+ gasUsed: string;
601
+ } | null;
543
602
  };
544
603
  const r = json.result;
545
604
  if (r) {
546
605
  return {
547
606
  status: r.status === "0x1" ? "success" : "reverted",
548
607
  transactionHash: r.transactionHash,
549
- blockNumber: BigInt(r.blockNumber),
608
+ blockNumber: r.blockNumber == null ? null : BigInt(r.blockNumber),
550
609
  gasUsed: BigInt(r.gasUsed),
551
610
  };
552
611
  }
@@ -718,24 +777,20 @@ export function buildWaitlistWithdraw(p: WaitlistWithdrawParams): SourceChainCal
718
777
  };
719
778
  }
720
779
 
721
- // --- withdrawals (ADR 0033) --------------------------------------------------
780
+ // --- withdrawals (ADR 0042) --------------------------------------------------
722
781
  //
723
- // `Clob.withdraw` settles on L1 in ONE transaction: the CLOB balance is debited
724
- // straight to the bridge's custody and N−F validators sign the L1 claim at
725
- // solution execution. Nothing is credited to a pod account on the way, so the
726
- // legacy `Bridge.withdraw` rules — `tx.value == amount`, a gas reserve, a second
727
- // signature — do not apply, and MAX is the whole withdrawable balance.
782
+ // `Bridge.withdraw` settles on L1 in ONE transaction: the CLOB balance is
783
+ // debited and N−F validators sign the L1 claim at solution execution. Nothing is
784
+ // credited to a pod account on the way, so `tx.value` is zero for every token,
785
+ // native included, and MAX is the whole withdrawable balance.
728
786
  //
729
787
  // Two fields mean something different from the same-named ones elsewhere:
730
- // - `recipient` is an address on the CLAIM chain, not on pod. Delegated calls
731
- // stay pinned to the master (ADR 0018), so a session key cannot redirect it.
732
- // - `amount` stays in pod's 18 decimals, but must be a whole number of
733
- // claim-chain units or admission rejects it. Size it with `maxWithdrawable`
734
- // / `quantizeWithdrawAmount` from `codec/bridge.ts` — this builder encodes
735
- // what it is given and does no rounding of its own, because silently
736
- // changing an amount a user signed for is worse than a clear rejection.
737
-
738
- export interface ClobWithdrawParams {
788
+ // - `recipient` is an address on the CLAIM chain, not on pod.
789
+ // - `amount` stays in pod's 18 decimals but must be a whole number of
790
+ // claim-chain units; size it with `maxWithdrawable` from `codec/bridge.ts`,
791
+ // because this builder rounds nothing of its own.
792
+
793
+ export interface WithdrawParams {
739
794
  /** Pod-side token address (native USD for cash). */
740
795
  token: Address;
741
796
  /** Recipient on the **claim chain**. */
@@ -755,15 +810,15 @@ export interface ClobWithdrawParams {
755
810
  deadline?: number; // ms; default far future
756
811
  }
757
812
 
758
- export function buildClobWithdraw(p: ClobWithdrawParams): PodTxRequest {
813
+ export function buildWithdraw(p: WithdrawParams): PodTxRequest {
759
814
  const nowUs = BigInt(Date.now()) * 1000n;
760
815
  const deadline = alignDeadline(us(p.deadline, nowUs + FAR_US), BigInt(p.auctionIntervalUs));
761
816
  const data = encodeFunctionData({
762
- abi: CLOB_ABI,
817
+ abi: BRIDGE_ABI,
763
818
  functionName: "withdraw",
764
819
  args: [p.token, p.recipient, p.amount, deadline],
765
820
  }) as Hex;
766
- return { to: CLOB_ADDRESS, data, value: 0n, type: "eip1559", maxPriorityFeePerGas: 0n, gas: 1_000_000n };
821
+ return { to: BRIDGE_ADDRESS, data, value: 0n, type: "eip1559", maxPriorityFeePerGas: 0n, gas: 1_000_000n };
767
822
  }
768
823
 
769
824
  /**
@@ -772,11 +827,6 @@ export function buildClobWithdraw(p: ClobWithdrawParams): PodTxRequest {
772
827
  * of the intent within a `submitBatch` (0 for a single-intent tx). Needs the
773
828
  * nonce, so it's only known up-front in managed mode; in advisory mode reconcile
774
829
  * by `tx` from the `pod_orders_v2` stream instead.
775
- *
776
- * **This is also the `withdrawal_id`** that `pod_withdrawals` reports and that
777
- * `GET /v1/bridge/withdrawals/by-id/{id}` is keyed on — same derivation, same
778
- * intent identity (ADR 0033 §3). `signer` is whoever signed the transaction,
779
- * i.e. the delegate under a session key, not the debited master.
780
830
  */
781
831
  export function deriveOrderId(signer: Address, nonce: number, sequence = 0): Hash {
782
832
  return keccak256(