@metaflux-dex/client 0.0.1

package/src/info.ts

@@ -0,0 +1,355 @@
+// MTF-native `/info` read API — typed request builders + envelope unwrap.
+//
+// Byte-for-byte mirror of the server dispatcher
+// (`metaflux/crates/api-node/src/rest/info.rs::handle_info`) and the per-handler
+// shapes in `info/{reads,markets,hl_parity}.rs`. Every request is a
+// `POST /info` whose body is `{"type": "<discriminator>", ...params}` —
+// snake_case field names, the exact convention the node decodes. The node's
+// `/info` surface is MTF-native ONLY; the HL `type` aliases (`meta` etc.) live
+// on the gateway's hl_compat layer, not here.
+//
+// ENVELOPE. Every successful response is `{"type": "<query>", "data": {...}}`.
+// `post` validates the echoed `type` and returns the unwrapped `data` typed —
+// the unwrap lives in exactly one place (`post`). The `raw<T>()` escape hatch
+// returns the unwrapped `data` too (use `rawEnvelope` for the full envelope).
+//
+// KEYING. The node `/info` is keyed by `0x` hex address for account / staking /
+// vault / user reads (`account_state`, `staking_state`, `frontend_open_orders`,
+// every hl_parity user read), by `vault` (0x) for `vault_state`, by `asset_id`
+// or `coin` for `market_info`, and by `market_id` (u32) for the book / trade /
+// funding reads. The account-history reads (`open_orders`, `user_fills`,
+// `agents`, `sub_accounts`) accept EITHER `address` (0x) OR `account_id` (u64).
+// There is NO numeric-id-only keying for accounts and NO gateway id translation
+// on this surface.
+//
+// Money magnitudes that can exceed JS `Number.MAX_SAFE_INTEGER` (2^53) are
+// typed `string` in `./info-types.js` to match the node's decimal-string
+// encoding; ids / counts / bps stay `number`.
+
+import { httpRequest } from './http.js';
+import type {
+  AccountState,
+  ActiveAssetData,
+  Agents,
+  BlockInfo,
+  DelegatorSummary,
+  ExchangeStatus,
+  FeeSchedule,
+  FrontendOpenOrders,
+  FundingHistory,
+  GossipRootIps,
+  L2Book,
+  LeadingVaults,
+  Liquidatable,
+  MarginTable,
+  MarketInfo,
+  MaxBuilderFee,
+  MaxMarketOrderNtls,
+  Mip3ActiveBids,
+  NodeInfo,
+  OpenOrders,
+  PerpDexs,
+  PerpsAtOpenInterestCap,
+  RecentTrades,
+  SpotClearinghouseState,
+  SpotDeployState,
+  SpotMeta,
+  StakingState,
+  SubAccounts,
+  UserFills,
+  UserRateLimit,
+  UserRole,
+  UserToMultiSigSigners,
+  UserVaultEquities,
+  ValidatorL1Votes,
+  ValidatorSummaries,
+  VaultState,
+  VaultSummaries,
+  WebData2,
+} from './info-types.js';
+
+/// The committed `{type, data}` response envelope every `/info` query returns.
+interface InfoEnvelope<T> {
+  type: string;
+  data: T;
+}
+
+/// An account-scoped read accepts EITHER a `0x` address OR an internal
+/// `account_id` (u64). Used by `open_orders` / `user_fills` / `agents` /
+/// `sub_accounts`, mirroring the node's `resolve_account`.
+export type AccountRef = { address: string } | { account_id: number };
+
+/// `/info` namespace handle. Each method POSTs a typed `{"type": ...}` body to
+/// `POST <baseUrl>/info`, validates the `{type, data}` envelope, and returns
+/// the unwrapped `data`.
+///
+/// No signing required — these are read-only queries. Construct via
+/// `Client.info` or directly with a base URL.
+export class InfoApi {
+  constructor(private readonly baseUrl: string) {}
+
+  // ── documented core reads ──────────────────────────────────────────────
+
+  /// `node_info` — static node identity + protocol version.
+  async nodeInfo(): Promise<NodeInfo> {
+    return this.post<NodeInfo>({ type: 'node_info' });
+  }
+
+  /// `account_state` — rich per-account snapshot keyed by `address` (0x hex).
+  async accountState(address: string): Promise<AccountState> {
+    return this.post<AccountState>({ type: 'account_state', address });
+  }
+
+  /// `market_info` — rich per-market snapshot by canonical `asset_id` (u32).
+  async marketInfo(assetId: number): Promise<MarketInfo> {
+    return this.post<MarketInfo>({ type: 'market_info', asset_id: assetId });
+  }
+
+  /// `market_info` — rich per-market snapshot by human-readable `coin`.
+  async marketInfoByCoin(coin: string): Promise<MarketInfo> {
+    return this.post<MarketInfo>({ type: 'market_info', coin });
+  }
+
+  /// `markets` — every registered MIP-3 perp market (array of `MarketInfo`).
+  async markets(): Promise<MarketInfo[]> {
+    return this.post<MarketInfo[]>({ type: 'markets' });
+  }
+
+  /// `vault_state` — per-vault snapshot keyed by vault `address` (0x hex).
+  async vaultState(vaultAddress: string): Promise<VaultState> {
+    return this.post<VaultState>({ type: 'vault_state', vault: vaultAddress });
+  }
+
+  /// `staking_state` — per-account staking snapshot keyed by `address` (0x).
+  async stakingState(address: string): Promise<StakingState> {
+    return this.post<StakingState>({ type: 'staking_state', address });
+  }
+
+  /// `fee_schedule` — protocol fee schedule.
+  async feeSchedule(): Promise<FeeSchedule> {
+    return this.post<FeeSchedule>({ type: 'fee_schedule' });
+  }
+
+  // ── book / trade / account-history reads ────────────────────────────────
+
+  /// `open_orders` — account-scoped resting orders. Keyed by `address` (0x) or
+  /// `account_id` (u64).
+  async openOrders(ref: AccountRef): Promise<OpenOrders> {
+    return this.post<OpenOrders>({ type: 'open_orders', ...ref });
+  }
+
+  /// `l2_book` — market-scoped aggregated bid/ask levels by `market_id` (u32).
+  async l2Book(marketId: number): Promise<L2Book> {
+    return this.post<L2Book>({ type: 'l2_book', market_id: marketId });
+  }
+
+  /// `recent_trades` — market-scoped trade tape by `market_id` (u32).
+  async recentTrades(marketId: number): Promise<RecentTrades> {
+    return this.post<RecentTrades>({ type: 'recent_trades', market_id: marketId });
+  }
+
+  /// `user_fills` — account-scoped fill history. Keyed by `address` (0x) or
+  /// `account_id` (u64).
+  async userFills(ref: AccountRef): Promise<UserFills> {
+    return this.post<UserFills>({ type: 'user_fills', ...ref });
+  }
+
+  /// `funding_history` — market-scoped funding premium samples by `market_id`.
+  async fundingHistory(marketId: number): Promise<FundingHistory> {
+    return this.post<FundingHistory>({ type: 'funding_history', market_id: marketId });
+  }
+
+  /// `block_info` — latest committed block metadata. No parameters.
+  async blockInfo(): Promise<BlockInfo> {
+    return this.post<BlockInfo>({ type: 'block_info' });
+  }
+
+  /// `agents` — approved agent / API wallets. Keyed by `address` (0x) or
+  /// `account_id` (u64).
+  async agents(ref: AccountRef): Promise<Agents> {
+    return this.post<Agents>({ type: 'agents', ...ref });
+  }
+
+  /// `sub_accounts` — sub-accounts of an account. Keyed by `address` (0x) or
+  /// `account_id` (u64).
+  async subAccounts(ref: AccountRef): Promise<SubAccounts> {
+    return this.post<SubAccounts>({ type: 'sub_accounts', ...ref });
+  }
+
+  /// `mip3_active_bids` — MIP-3 permissionless perp-deploy auction snapshot.
+  async mip3ActiveBids(): Promise<Mip3ActiveBids> {
+    return this.post<Mip3ActiveBids>({ type: 'mip3_active_bids' });
+  }
+
+  // ── HL-node parity reads ────────────────────────────────────────────────
+
+  /// `spot_meta` — spot pair universe. No parameters.
+  async spotMeta(): Promise<SpotMeta> {
+    return this.post<SpotMeta>({ type: 'spot_meta' });
+  }
+
+  /// `spot_clearinghouse_state` — per-account spot token balances by `address`.
+  async spotClearinghouseState(address: string): Promise<SpotClearinghouseState> {
+    return this.post<SpotClearinghouseState>({
+      type: 'spot_clearinghouse_state',
+      address,
+    });
+  }
+
+  /// `exchange_status` — global trading status. No parameters.
+  async exchangeStatus(): Promise<ExchangeStatus> {
+    return this.post<ExchangeStatus>({ type: 'exchange_status' });
+  }
+
+  /// `frontend_open_orders` — resting orders + tif / cloid / trigger by
+  /// `address` (0x).
+  async frontendOpenOrders(address: string): Promise<FrontendOpenOrders> {
+    return this.post<FrontendOpenOrders>({ type: 'frontend_open_orders', address });
+  }
+
+  /// `liquidatable` — accounts currently flagged for liquidation. No params.
+  async liquidatable(): Promise<Liquidatable> {
+    return this.post<Liquidatable>({ type: 'liquidatable' });
+  }
+
+  /// `active_asset_data` — a user's per-asset leverage / margin-mode / max
+  /// trade by `address` (0x) + `asset_id` (u32).
+  async activeAssetData(address: string, assetId: number): Promise<ActiveAssetData> {
+    return this.post<ActiveAssetData>({
+      type: 'active_asset_data',
+      address,
+      asset_id: assetId,
+    });
+  }
+
+  /// `max_market_order_ntls` — per-asset max market-order notional. No params.
+  async maxMarketOrderNtls(): Promise<MaxMarketOrderNtls> {
+    return this.post<MaxMarketOrderNtls>({ type: 'max_market_order_ntls' });
+  }
+
+  /// `vault_summaries` — all vaults summary. No parameters.
+  async vaultSummaries(): Promise<VaultSummaries> {
+    return this.post<VaultSummaries>({ type: 'vault_summaries' });
+  }
+
+  /// `user_vault_equities` — vaults a user has deposited into by `address` (0x).
+  async userVaultEquities(address: string): Promise<UserVaultEquities> {
+    return this.post<UserVaultEquities>({ type: 'user_vault_equities', address });
+  }
+
+  /// `leading_vaults` — vaults led by the user by `address` (0x).
+  async leadingVaults(address: string): Promise<LeadingVaults> {
+    return this.post<LeadingVaults>({ type: 'leading_vaults', address });
+  }
+
+  /// `user_rate_limit` — a user's action stats / rate-limit budget by `address`.
+  async userRateLimit(address: string): Promise<UserRateLimit> {
+    return this.post<UserRateLimit>({ type: 'user_rate_limit', address });
+  }
+
+  /// `spot_deploy_state` — MIP-1 spot-pair-deploy gas-auction state. No params.
+  async spotDeployState(): Promise<SpotDeployState> {
+    return this.post<SpotDeployState>({ type: 'spot_deploy_state' });
+  }
+
+  /// `delegator_summary` — staking summary for an `address` (0x).
+  async delegatorSummary(address: string): Promise<DelegatorSummary> {
+    return this.post<DelegatorSummary>({ type: 'delegator_summary', address });
+  }
+
+  /// `max_builder_fee` — approved builder-fee ceiling for `(address, builder)`,
+  /// both 0x.
+  async maxBuilderFee(address: string, builder: string): Promise<MaxBuilderFee> {
+    return this.post<MaxBuilderFee>({ type: 'max_builder_fee', address, builder });
+  }
+
+  /// `user_to_multi_sig_signers` — multisig config for an `address` (0x).
+  async userToMultiSigSigners(address: string): Promise<UserToMultiSigSigners> {
+    return this.post<UserToMultiSigSigners>({
+      type: 'user_to_multi_sig_signers',
+      address,
+    });
+  }
+
+  /// `user_role` — derived account role for an `address` (0x).
+  async userRole(address: string): Promise<UserRole> {
+    return this.post<UserRole>({ type: 'user_role', address });
+  }
+
+  /// `perps_at_open_interest_cap` — assets whose OI is at/over the cap. No params.
+  async perpsAtOpenInterestCap(): Promise<PerpsAtOpenInterestCap> {
+    return this.post<PerpsAtOpenInterestCap>({ type: 'perps_at_open_interest_cap' });
+  }
+
+  /// `validator_l1_votes` — current validator L1 votes. No parameters.
+  async validatorL1Votes(): Promise<ValidatorL1Votes> {
+    return this.post<ValidatorL1Votes>({ type: 'validator_l1_votes' });
+  }
+
+  /// `margin_table` — the margin-tier table (one effective tier per market).
+  async marginTable(): Promise<MarginTable> {
+    return this.post<MarginTable>({ type: 'margin_table' });
+  }
+
+  /// `perp_dexs` — list the perp DEX(es). No parameters.
+  async perpDexs(): Promise<PerpDexs> {
+    return this.post<PerpDexs>({ type: 'perp_dexs' });
+  }
+
+  /// `validator_summaries` — per-validator snapshot. No parameters.
+  async validatorSummaries(): Promise<ValidatorSummaries> {
+    return this.post<ValidatorSummaries>({ type: 'validator_summaries' });
+  }
+
+  /// `gossip_root_ips` — configured gossip root/seed peer endpoints. No params.
+  async gossipRootIps(): Promise<GossipRootIps> {
+    return this.post<GossipRootIps>({ type: 'gossip_root_ips' });
+  }
+
+  /// `web_data2` — composite frontend snapshot by `address` (0x).
+  async webData2(address: string): Promise<WebData2> {
+    return this.post<WebData2>({ type: 'web_data2', address });
+  }
+
+  // ── escape hatches ──────────────────────────────────────────────────────
+
+  /// Raw escape hatch — POST an arbitrary `{type, ...}` body to `/info`,
+  /// validate the envelope, and return the unwrapped `data` typed. For request
+  /// shapes the SDK doesn't yet model.
+  async raw<T = unknown>(body: { type: string; [k: string]: unknown }): Promise<T> {
+    return this.post<T>(body);
+  }
+
+  /// Like `raw`, but returns the full `{type, data}` envelope rather than just
+  /// the unwrapped `data` — for callers that want to inspect the echoed `type`.
+  async rawEnvelope<T = unknown>(body: {
+    type: string;
+    [k: string]: unknown;
+  }): Promise<InfoEnvelope<T>> {
+    return httpRequest<InfoEnvelope<T>>(this.baseUrl, '/info', {
+      method: 'POST',
+      json: body,
+    });
+  }
+
+  /// POST a typed body, validate the `{type, data}` envelope echoes the request
+  /// `type`, and return the unwrapped `data`. The single place the envelope is
+  /// peeled — every typed method routes through here.
+  private async post<T>(body: { type: string; [k: string]: unknown }): Promise<T> {
+    const env = await httpRequest<InfoEnvelope<T>>(this.baseUrl, '/info', {
+      method: 'POST',
+      json: body,
+    });
+    if (env === null || typeof env !== 'object' || !('data' in env)) {
+      throw new TypeError(
+        `/info ${body.type}: response is not a {type, data} envelope`,
+      );
+    }
+    if (env.type !== body.type) {
+      throw new TypeError(
+        `/info ${body.type}: response type mismatch — got '${env.type}'`,
+      );
+    }
+    return env.data;
+  }
+}

package/src/native.ts

@@ -0,0 +1,307 @@
+// MTF-native signed-action digest + envelope construction.
+//
+// This is the byte-exact TS twin of the Rust SDK reference
+// (`metaflux-client-rust/src/rest/exchange.rs::ActionSignedDigest`) and the
+// server verifier (`metaflux/crates/core-state/src/signing.rs`).
+//
+// digest = keccak256(0x1901 || domainSep5 || structHash)
+//   domainSep5 = keccak256(
+//       keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)")
+//       || keccak256("MetaFlux") || keccak256("1")
+//       || chainId_be32 || verifyingContract_padded32 )   // verifyingContract = 0x0
+//   structHash = keccak256(
+//       keccak256("MetaFluxAction(string action,uint64 nonce)")
+//       || keccak256(action_json_bytes) || nonce_be32 )
+//
+// CRITICAL: the signature is verified over the EXACT `action` bytes the server
+// receives (it parses `action` as `serde_json::value::RawValue`). So the same
+// JSON string MUST be both signed and sent verbatim — never re-stringified
+// from a parsed object. `buildNativeOrderAction` is the single source of those
+// bytes.
+
+import {
+  deriveAddressFromPubkey,
+  keccak256,
+  recoverPubkey,
+  signSecp256k1,
+} from './wasm.js';
+import type {
+  NativeBuilder,
+  NativeCancel,
+  NativeOrder,
+  NativeSignedAction,
+} from './types.js';
+
+const MTF_DOMAIN_TYPE =
+  'EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)';
+const MTF_ACTION_TYPE = 'MetaFluxAction(string action,uint64 nonce)';
+
+/// Default MTF chain id (matches `MTF_CHAIN_ID` in the Rust SDK + the server
+/// KAT vector). Pinned to 998 provisionally; configurable post-S10.
+export const MTF_CHAIN_ID = 998;
+
+const enc = new TextEncoder();
+
+let nonceClock = 0n;
+
+/// Strictly-increasing replay nonce — at least the current unix-ms, but bumped
+/// past the last issued value so a burst of orders within one millisecond gets
+/// distinct nonces. The server's per-account window tolerates out-of-order
+/// delivery but rejects collisions, so a raw `Date.now()` would drop the
+/// 2nd-and-later order in a same-ms burst.
+export function nextNonce(): bigint {
+  const now = BigInt(Date.now());
+  nonceClock = now > nonceClock ? now : nonceClock + 1n;
+  return nonceClock;
+}
+
+/// Encode a `bigint` as a 32-byte big-endian buffer (uint256 / nonce slot).
+/// The value rides in the low bytes; high bytes are zero. Rejects negatives
+/// and values that overflow 256 bits.
+function be32(value: bigint): Uint8Array {
+  if (value < 0n) throw new RangeError('be32: value must be non-negative');
+  if (value >= 1n << 256n) throw new RangeError('be32: value overflows uint256');
+  const out = new Uint8Array(32);
+  let v = value;
+  for (let i = 31; i >= 0 && v > 0n; i--) {
+    out[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  return out;
+}
+
+/// Concatenate 32-byte chunks into one buffer.
+function concat32(...chunks: Uint8Array[]): Uint8Array {
+  const out = new Uint8Array(chunks.length * 32);
+  chunks.forEach((c, i) => {
+    if (c.length !== 32) {
+      throw new RangeError(`concat32: chunk ${i} is ${c.length} bytes, want 32`);
+    }
+    out.set(c, i * 32);
+  });
+  return out;
+}
+
+/// Compute the 5-field MTF-native EIP-712 domain separator.
+async function domainSeparator(chainId: number): Promise<Uint8Array> {
+  const typeHash = await keccak256(enc.encode(MTF_DOMAIN_TYPE));
+  const nameHash = await keccak256(enc.encode('MetaFlux'));
+  const versionHash = await keccak256(enc.encode('1'));
+  const chainIdBe = be32(BigInt(chainId));
+  // verifyingContract = 0x0 address, left-padded to 32 bytes => all zeros.
+  const verifyingPadded = new Uint8Array(32);
+  return keccak256(
+    concat32(typeHash, nameHash, versionHash, chainIdBe, verifyingPadded),
+  );
+}
+
+/// Compute the native action EIP-712 digest over the EXACT `actionJson` bytes.
+///
+/// Returns the 32-byte digest the wallet signs. `actionJson` MUST be the
+/// identical string later POSTed in the `action` field (raw, not re-parsed).
+export async function nativeActionDigest(
+  actionJson: string,
+  nonce: bigint,
+  chainId: number = MTF_CHAIN_ID,
+): Promise<Uint8Array> {
+  if (nonce < 0n) throw new RangeError('nonce must be non-negative');
+  if (nonce >= 1n << 64n) throw new RangeError('nonce overflows u64');
+
+  const actionTypeHash = await keccak256(enc.encode(MTF_ACTION_TYPE));
+  const actionHash = await keccak256(enc.encode(actionJson));
+  const nonceBe = be32(nonce);
+  const structHash = await keccak256(
+    concat32(actionTypeHash, actionHash, nonceBe),
+  );
+
+  const domainSep = await domainSeparator(chainId);
+
+  // EIP-712 envelope: keccak256(0x19 || 0x01 || domainSep || structHash).
+  const envelope = new Uint8Array(2 + 32 + 32);
+  envelope[0] = 0x19;
+  envelope[1] = 0x01;
+  envelope.set(domainSep, 2);
+  envelope.set(structHash, 34);
+  return keccak256(envelope);
+}
+
+/// Lowercase hex (no `0x`) of a byte buffer.
+function toHex(bytes: Uint8Array): string {
+  let out = '';
+  for (const b of bytes) out += b.toString(16).padStart(2, '0');
+  return out;
+}
+
+/// JSON-escape a string for inclusion in the hand-built action body. We build
+/// the action JSON manually (rather than `JSON.stringify`-ing an object) so
+/// the byte layout is fully under our control and matches the server's
+/// expectation field-for-field. The only string values are `0x`-hex addresses
+/// / cloids and fixed enum tokens, none of which contain characters needing
+/// escaping — but we escape defensively so a malformed input can never inject
+/// raw control bytes into the signed payload.
+function jsonStr(s: string): string {
+  return JSON.stringify(s);
+}
+
+/// Build the canonical native `submit_order` action JSON string.
+///
+/// Field order mirrors the server `NativeOrder` exactly. Optional `cloid` /
+/// `builder` are omitted entirely when absent (matching the server's
+/// `#[serde(default)]` + KAT vector, where neither appears). The returned
+/// string is BOTH what gets signed and what gets sent — do not re-serialize.
+export function buildNativeOrderAction(order: NativeOrder): string {
+  validateAddress(order.owner, 'owner');
+  validateMarket(order.market);
+  validateU64(order.size, 'size');
+  validateU64(order.limit_px, 'limit_px');
+
+  const parts: string[] = [
+    `${jsonStr('owner')}:${jsonStr(order.owner)}`,
+    `${jsonStr('market')}:${order.market}`,
+    `${jsonStr('side')}:${jsonStr(order.side)}`,
+    `${jsonStr('kind')}:${jsonStr(order.kind)}`,
+    `${jsonStr('size')}:${order.size}`,
+    `${jsonStr('limit_px')}:${order.limit_px}`,
+    `${jsonStr('tif')}:${jsonStr(order.tif)}`,
+    `${jsonStr('stp_mode')}:${jsonStr(order.stp_mode)}`,
+    `${jsonStr('reduce_only')}:${order.reduce_only ? 'true' : 'false'}`,
+  ];
+  if (order.cloid !== undefined) {
+    validateCloid(order.cloid);
+    parts.push(`${jsonStr('cloid')}:${jsonStr(order.cloid)}`);
+  }
+  if (order.builder !== undefined) {
+    parts.push(`${jsonStr('builder')}:${buildBuilder(order.builder)}`);
+  }
+  const orderJson = `{${parts.join(',')}}`;
+  return `{${jsonStr('type')}:${jsonStr('submit_order')},${jsonStr('order')}:${orderJson}}`;
+}
+
+/// Serialize a builder carve in the server-expected `{fee, user}` order.
+function buildBuilder(b: NativeBuilder): string {
+  if (!Number.isInteger(b.fee) || b.fee < 0 || b.fee > 0xffff) {
+    throw new RangeError('builder.fee must be a u16 (0..=65535)');
+  }
+  validateAddress(b.user, 'builder.user');
+  return `{${jsonStr('fee')}:${b.fee},${jsonStr('user')}:${jsonStr(b.user)}}`;
+}
+
+/// Build the canonical native `cancel_order` action JSON string.
+///
+/// Field order mirrors the server `NativeCancel` exactly
+/// (`metaflux/crates/api-node/src/rest/native_action.rs`): `owner`, `market`,
+/// then `oid` / `cloid` when present. The server's `CancelParams` bridge
+/// cancels by `oid`, so an `oid` is REQUIRED for the cancel to lower
+/// successfully (a `cloid`-only cancel is accepted on the wire but rejected at
+/// lowering with `CancelMissingOid`); we still emit either form so the bytes
+/// stay caller-controlled. The returned string is BOTH signed and sent.
+export function buildNativeCancelAction(cancel: NativeCancel): string {
+  validateAddress(cancel.owner, 'owner');
+  validateMarket(cancel.market);
+  if (cancel.oid === undefined && cancel.cloid === undefined) {
+    throw new RangeError('cancel requires an oid (server cancels by oid)');
+  }
+  const parts: string[] = [
+    `${jsonStr('owner')}:${jsonStr(cancel.owner)}`,
+    `${jsonStr('market')}:${cancel.market}`,
+  ];
+  if (cancel.oid !== undefined) {
+    validateU64(cancel.oid, 'oid');
+    parts.push(`${jsonStr('oid')}:${cancel.oid}`);
+  }
+  if (cancel.cloid !== undefined) {
+    validateCloid(cancel.cloid);
+    parts.push(`${jsonStr('cloid')}:${jsonStr(cancel.cloid)}`);
+  }
+  const cancelJson = `{${parts.join(',')}}`;
+  return `{${jsonStr('type')}:${jsonStr('cancel_order')},${jsonStr('cancel')}:${cancelJson}}`;
+}
+
+/// Sign a pre-built action JSON string with the given private key.
+///
+/// The returned envelope's `actionJson` is the SAME string passed in — the
+/// caller must POST it verbatim so the server verifies over identical bytes.
+export async function signNativeAction(
+  privateKey: Uint8Array,
+  actionJson: string,
+  nonce: bigint,
+  chainId: number = MTF_CHAIN_ID,
+): Promise<NativeSignedAction> {
+  if (privateKey.length !== 32) {
+    throw new RangeError('privateKey must be exactly 32 bytes');
+  }
+  const digest = await nativeActionDigest(actionJson, nonce, chainId);
+  const sig = await signSecp256k1(privateKey, digest);
+  return { actionJson, nonce, signature: `0x${toHex(sig)}` };
+}
+
+/// Recover the 20-byte signer address from a native signed action — handy for
+/// asserting the owner field locally before POSTing.
+export async function recoverNativeSigner(
+  signed: NativeSignedAction,
+  chainId: number = MTF_CHAIN_ID,
+): Promise<string> {
+  const digest = await nativeActionDigest(
+    signed.actionJson,
+    signed.nonce,
+    chainId,
+  );
+  const sigHex = signed.signature.startsWith('0x')
+    ? signed.signature.slice(2)
+    : signed.signature;
+  const sig = hexToBytes(sigHex);
+  const pubkey = await recoverPubkey(sig, digest);
+  const addr = await deriveAddressFromPubkey(pubkey);
+  return `0x${toHex(addr)}`;
+}
+
+/// Assemble the full `POST /exchange` request body STRING.
+///
+/// Hand-built so the `action` field carries the exact signed bytes (no
+/// re-stringify of a parsed object). The body shape is
+/// `{"action":<actionJson>,"nonce":<u64>,"signature":"0x.."}`.
+export function nativeRequestBody(signed: NativeSignedAction): string {
+  return `{${jsonStr('action')}:${signed.actionJson},${jsonStr('nonce')}:${signed.nonce},${jsonStr('signature')}:${jsonStr(signed.signature)}}`;
+}
+
+// ---- validation helpers (fail loud before anything reaches the signed body) ----
+
+function validateAddress(addr: string, field: string): void {
+  const hex = addr.startsWith('0x') ? addr.slice(2) : addr;
+  if (hex.length !== 40 || !/^[0-9a-fA-F]{40}$/.test(hex)) {
+    throw new RangeError(`${field} must be a 0x-prefixed 20-byte hex address`);
+  }
+}
+
+function validateCloid(cloid: string): void {
+  const hex = cloid.startsWith('0x') ? cloid.slice(2) : cloid;
+  if (hex.length !== 32 || !/^[0-9a-fA-F]{32}$/.test(hex)) {
+    throw new RangeError('cloid must be a 0x-prefixed 16-byte hex string');
+  }
+}
+
+function validateMarket(market: number): void {
+  if (!Number.isInteger(market) || market < 0 || market > 0xffffffff) {
+    throw new RangeError('market must be a u32');
+  }
+}
+
+function validateU64(value: number, field: string): void {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new RangeError(`${field} must be a non-negative integer`);
+  }
+  if (value > Number.MAX_SAFE_INTEGER) {
+    throw new RangeError(
+      `${field} exceeds Number.MAX_SAFE_INTEGER; use a value below 2^53`,
+    );
+  }
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) throw new RangeError('hex length must be even');
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}