@metaflux-dex/client 0.0.5 → 0.1.0

package/src/native/actions.ts

@@ -14,11 +14,13 @@ import {
   validateAddress,
   validateCloid,
   validateDecimalString,
+  validateI128,
   validateMarket,
   validateU8,
   validateU16,
   validateU32,
   validateU64,
+  validateU128,
 } from './digest.js';
 import type {
   AgentSetAbstraction,
@@ -31,7 +33,11 @@ import type {
   CancelByCloid,
   ClaimRewards,
   ConvertToMultiSigUser,
+  CoreSide,
   CreateVault,
+  CrossChainSend,
+  EncryptedOrderSubmit,
+  FbaSubmit,
   LinkStakingUser,
   MbWithdraw,
   Modify,
@@ -49,6 +55,8 @@ import type {
   NativeSpotOrder,
   PriorityBid,
   RegisterMetaliquidityOperator,
+  RfqAccept,
+  RfqRequest,
   ScheduleCancel,
   SetDisplayName,
   SetMetaliquidityWhitelist,
@@ -63,6 +71,7 @@ import type {
   UserDexAbstraction,
   UserPortfolioMargin,
   UserSetAbstraction,
+  VaultDistribute,
   VaultModify,
   VaultTransfer,
   VaultWithdraw,
@@ -665,6 +674,19 @@ export function buildNativeVaultWithdrawAction(params: VaultWithdraw): string {
   );
 }
 
+/// `vault_distribute` — follower deposits USD into a vault, minting shares at
+/// the current NAV. The deposit amount rides the **`pnl`** field (a legacy node
+/// name) as a positive decimal string; `vault_id` is a bare number. Wrapper key
+/// is `params`. Forward-compat: see the module note on the RFQ/FBA builders.
+export function buildNativeVaultDistributeAction(params: VaultDistribute): string {
+  validateU64(params.vault_id, 'vault_id');
+  validateDecimalString(params.pnl, 'pnl');
+  return wrapParams(
+    'vault_distribute',
+    `{${jsonStr('vault_id')}:${params.vault_id},${jsonStr('pnl')}:${jsonStr(params.pnl)}}`,
+  );
+}
+
 // ---- MetaBridge ----
 
 /// `mb_withdraw` — withdraw cross-collateral to a destination chain. `dst_addr`
@@ -818,3 +840,116 @@ export function buildNativeEarnWithdrawAction(
   const paramsJson = `{${jsonStr('asset')}:${params.asset},${jsonStr('shares')}:${jsonStr(params.shares)}}`;
   return `{${jsonStr('type')}:${jsonStr('earn_withdraw')},${jsonStr('params')}:${paramsJson}}`;
 }
+
+// ============================================================================
+// RFQ / FBA / cross-chain / encrypted (forward-compat).
+//
+// The node recognizes these action tags but currently lowers them to
+// `UnsupportedAction` on the public `/exchange` path (the real handlers run on
+// the EVM core-writer path). The SDK emits the byte-correct wire shape each core
+// param struct expects, so these become live the moment the node bridges them —
+// no SDK change required. Note the per-action wrapper keys differ:
+// `rfq` / `accept` / `submit` / `msg` / `encrypted` (NOT `params`).
+//
+// Traps mirrored from the node's plain `#[derive(Serialize)]`:
+//   - `side` is PascalCase (`"Bid"`/`"Ask"`), distinct from the snake_case
+//     `"bid"`/`"ask"` the perp/spot order builders use.
+//   - `size` is a `u128` and `limit_px`/`price` are `i128`, emitted as bare JSON
+//     numbers (the size/px planes can exceed 2^53, so they ride as `bigint`).
+//   - `limit_px` (RFQ) / `stp_group` (RFQ + FBA) carry no serde default on the
+//     node, so the key MUST be present — emit `null` when absent, do NOT omit.
+//   - byte arrays (`recipient`, `ciphertext`, `commitment`) are JSON arrays of
+//     byte-numbers, NOT 0x-hex strings.
+// ============================================================================
+
+/// Render a PascalCase core side token (`"Bid"`/`"Ask"`), failing loud on any
+/// other value (a snake_case `"bid"`/`"ask"` here would be silently rejected by
+/// the core handler).
+function coreSideToken(side: CoreSide, field: string): string {
+  if (side !== 'Bid' && side !== 'Ask') {
+    throw new RangeError(`${field} must be "Bid" or "Ask" (PascalCase CoreSide)`);
+  }
+  return jsonStr(side);
+}
+
+/// Serialize a byte buffer as a JSON array of unsigned byte-numbers, optionally
+/// pinning an exact length.
+function byteArrayJson(bytes: Uint8Array, field: string, len?: number): string {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new RangeError(`${field} must be a Uint8Array`);
+  }
+  if (len !== undefined && bytes.length !== len) {
+    throw new RangeError(`${field} must be exactly ${len} bytes`);
+  }
+  return `[${Array.from(bytes).join(',')}]`;
+}
+
+/// `rfq_request` — taker opens an RFQ session. Wrapper key is **`rfq`**. `side`
+/// is PascalCase; `limit_px` (`i128`) and `stp_group` (`u64`) keys are ALWAYS
+/// present (`null` when absent — the node has no serde default).
+export function buildNativeRfqRequestAction(params: RfqRequest): string {
+  validateMarket(params.market);
+  validateU128(params.size, 'size');
+  validateU64(params.expiry_ms, 'expiry_ms');
+  if (params.limit_px !== null) {
+    validateI128(params.limit_px, 'limit_px');
+  }
+  if (params.stp_group !== null) {
+    validateU64(params.stp_group, 'stp_group');
+  }
+  const limitPx = params.limit_px === null ? 'null' : params.limit_px.toString();
+  const stpGroup = params.stp_group === null ? 'null' : `${params.stp_group}`;
+  const rfqJson = `{${jsonStr('market')}:${params.market},${jsonStr('side')}:${coreSideToken(params.side, 'side')},${jsonStr('size')}:${params.size},${jsonStr('limit_px')}:${limitPx},${jsonStr('expiry_ms')}:${params.expiry_ms},${jsonStr('stp_group')}:${stpGroup}}`;
+  return `{${jsonStr('type')}:${jsonStr('rfq_request')},${jsonStr('rfq')}:${rfqJson}}`;
+}
+
+/// `rfq_accept` — taker crosses against a specific resting quote. Wrapper key is
+/// **`accept`** (NOT `rfq`).
+export function buildNativeRfqAcceptAction(params: RfqAccept): string {
+  validateU64(params.rfq_id, 'rfq_id');
+  validateU32(params.quote_idx, 'quote_idx');
+  validateU128(params.size, 'size');
+  const acceptJson = `{${jsonStr('rfq_id')}:${params.rfq_id},${jsonStr('quote_idx')}:${params.quote_idx},${jsonStr('size')}:${params.size}}`;
+  return `{${jsonStr('type')}:${jsonStr('rfq_accept')},${jsonStr('accept')}:${acceptJson}}`;
+}
+
+/// `fba_submit` — submit into a market's frequent-batch-auction pool. Wrapper
+/// key is **`submit`**. The price field is **`price`** (NOT `limit_px`); `side`
+/// is PascalCase; `stp_group` key is ALWAYS present (`null` when absent).
+export function buildNativeFbaSubmitAction(params: FbaSubmit): string {
+  validateMarket(params.market);
+  validateU128(params.size, 'size');
+  validateI128(params.price, 'price');
+  if (params.stp_group !== null) {
+    validateU64(params.stp_group, 'stp_group');
+  }
+  const stpGroup = params.stp_group === null ? 'null' : `${params.stp_group}`;
+  const submitJson = `{${jsonStr('market')}:${params.market},${jsonStr('side')}:${coreSideToken(params.side, 'side')},${jsonStr('size')}:${params.size},${jsonStr('price')}:${params.price},${jsonStr('stp_group')}:${stpGroup}}`;
+  return `{${jsonStr('type')}:${jsonStr('fba_submit')},${jsonStr('submit')}:${submitJson}}`;
+}
+
+/// `cross_chain_send` — initiate a chain-agnostic cross-chain transfer. Wrapper
+/// key is **`msg`**. `recipient` is a 32-byte array; `amount` (`u128`) is a bare
+/// JSON number (NOT hex).
+export function buildNativeCrossChainSendAction(params: CrossChainSend): string {
+  validateU32(params.dst_chain_id, 'dst_chain_id');
+  const recipient = byteArrayJson(params.recipient, 'recipient', 32);
+  validateU32(params.token, 'token');
+  validateU128(params.amount, 'amount');
+  validateU64(params.nonce, 'nonce');
+  const msgJson = `{${jsonStr('dst_chain_id')}:${params.dst_chain_id},${jsonStr('recipient')}:${recipient},${jsonStr('token')}:${params.token},${jsonStr('amount')}:${params.amount},${jsonStr('nonce')}:${params.nonce}}`;
+  return `{${jsonStr('type')}:${jsonStr('cross_chain_send')},${jsonStr('msg')}:${msgJson}}`;
+}
+
+/// `encrypted_order_submit` — submit a threshold-encrypted order. Wrapper key is
+/// **`encrypted`**. Only 3 fields — DISTINCT from `submit_encrypted_order`
+/// (5 fields, key `params`). `ciphertext`/`commitment` are byte arrays.
+export function buildNativeEncryptedOrderSubmitAction(
+  params: EncryptedOrderSubmit,
+): string {
+  const ct = byteArrayJson(params.ciphertext, 'ciphertext');
+  const cm = byteArrayJson(params.commitment, 'commitment', 32);
+  validateU64(params.reveal_deadline_ms, 'reveal_deadline_ms');
+  const encJson = `{${jsonStr('ciphertext')}:${ct},${jsonStr('commitment')}:${cm},${jsonStr('reveal_deadline_ms')}:${params.reveal_deadline_ms}}`;
+  return `{${jsonStr('type')}:${jsonStr('encrypted_order_submit')},${jsonStr('encrypted')}:${encJson}}`;
+}

package/src/native/digest.ts

@@ -264,6 +264,18 @@ export function validateU128(value: bigint, field: string): void {
   if (value >= 1n << 128n) throw new RangeError(`${field} overflows u128`);
 }
 
+/// Validate an `i128` field passed as a `bigint`, emitted as a bare unquoted
+/// integer literal on the wire (serde i128 JSON number form). Accepts the full
+/// signed-128-bit range `[-2^127, 2^127)`.
+export function validateI128(value: bigint, field: string): void {
+  if (typeof value !== 'bigint') {
+    throw new RangeError(`${field} must be a bigint`);
+  }
+  if (value < -(1n << 127n) || value >= 1n << 127n) {
+    throw new RangeError(`${field} overflows i128`);
+  }
+}
+
 /// Validate a decimal magnitude passed as a string and emitted as a JSON
 /// **string** on the wire (e.g. spot-margin `amount` / `borrow`, Earn
 /// `shares`). The server decodes these as a fixed-point `Decimal`, so they must

package/src/types/cross-chain.ts

@@ -0,0 +1,32 @@
+// MTF-native cross-chain action payload type.
+//
+// Forward-compat: the node recognizes the `cross_chain_send` action tag but
+// currently lowers it to `UnsupportedAction` on the public `/exchange` path
+// (the real handler runs on the EVM core-writer path). The SDK emits the
+// byte-correct shape the node's `evm_integration` `CrossChainSendParams`
+// decoder expects, so it goes live the moment the node bridges it.
+
+/// `cross_chain_send` — initiate a chain-agnostic cross-chain transfer (queued
+/// to the bridge outbox). Mirrors the node's `evm_integration`
+/// `CrossChainSendParams`. The action envelope wraps this under the key **`msg`**.
+///
+/// Traps: the action field is `dst_chain_id` (the read-only `CrossChainMsg`
+/// snapshot uses `dst_chain`); under the node's plain `#[derive(Serialize)]`,
+/// `recipient: [u8; 32]` is a JSON **array of 32 byte-numbers** and `amount`
+/// (`u128`) is a JSON **number** — NOT 0x-hex strings.
+export interface CrossChainSend {
+  /// Destination chain id (`u32`).
+  dst_chain_id: number;
+  /// Chain-agnostic 32-byte recipient (EVM = left-padded 20-byte address).
+  /// Serializes as a JSON array of 32 byte-numbers — pass a 32-byte
+  /// `Uint8Array`.
+  recipient: Uint8Array;
+  /// MTF asset id (`u32`) — NOT a destination-chain token address.
+  token: number;
+  /// Amount in the MTF asset's native fixed-point (`u128`). `bigint` — emitted
+  /// as a bare JSON number, NOT hex.
+  amount: bigint;
+  /// Application-supplied idempotency nonce (`u64`); `(sender, nonce)` is the
+  /// key.
+  nonce: number;
+}

package/src/types/encrypted.ts

@@ -19,3 +19,26 @@ export interface SubmitEncryptedOrder {
   /// (`u64`).
   reveal_deadline_ms: number;
 }
+
+/// `encrypted_order_submit` — submit a threshold-encrypted order under the
+/// node's `evm_integration` `EncryptedOrderSubmitParams`. The action envelope
+/// wraps this under the key **`encrypted`**.
+///
+/// DISTINCT from `SubmitEncryptedOrder`: that 5-field type backs the *different*
+/// `submit_encrypted_order` tag (key `params`, the real bridged handler). This
+/// 3-field type has **no** `threshold` / `target_block`.
+///
+/// Forward-compat: the node currently answers this tag with `UnsupportedAction`
+/// on the public `/exchange` path; the SDK emits the byte-correct shape the core
+/// handler will accept once the bridge lands.
+export interface EncryptedOrderSubmit {
+  /// Threshold-encrypted order bytes (node decoder bounds this at 4096).
+  /// Emitted as a JSON array of byte numbers — pass a `Uint8Array`.
+  ciphertext: Uint8Array;
+  /// 32-byte `keccak(plaintext‖salt)` commitment. Emitted as a JSON array of
+  /// 32 byte numbers — pass a 32-byte `Uint8Array`.
+  commitment: Uint8Array;
+  /// Absolute consensus-time ms by which a valid plaintext must be revealed
+  /// (`u64`).
+  reveal_deadline_ms: number;
+}

package/src/types/fba.ts

@@ -0,0 +1,32 @@
+// MTF-native FBA (Frequent Batch Auction) action payload type.
+//
+// Forward-compat: the node recognizes the `fba_submit` action tag but currently
+// lowers it to `UnsupportedAction` on the public `/exchange` path. The SDK emits
+// the byte-correct shape the core `FbaSubmitParams` decoder expects, so it goes
+// live the moment the node bridges the handler — no SDK change required.
+
+import type { CoreSide } from './rfq.js';
+
+/// `fba_submit` — submit an order into a market's frequent-batch-auction pool.
+/// Mirrors the node's `core_state` `FbaSubmitParams`. The action envelope wraps
+/// this under the key **`submit`**.
+///
+/// Traps mirrored from the node: `side` is PascalCase (`CoreSide`), the price
+/// field is named **`price`** (NOT `limit_px` as in spot/perp orders), and
+/// `stp_group` carries no serde default so the key must be present (`null` when
+/// absent).
+export interface FbaSubmit {
+  /// Target market (`u32`).
+  market: number;
+  /// Side — serializes PascalCase (`"Bid"`/`"Ask"`).
+  side: CoreSide;
+  /// Submitted size (`u128`, `>= pool.min_lot`). `bigint` — emitted as a bare
+  /// JSON number.
+  size: bigint;
+  /// Limit / worst-acceptable price (`i128`, `> 0`). Field is **`price`** per
+  /// the core struct — NOT `limit_px`. `bigint` — emitted as a bare number.
+  price: bigint;
+  /// Optional STP group (`u64`). The key is ALWAYS present: `null` when absent
+  /// (do NOT omit).
+  stp_group: number | null;
+}

package/src/types/index.ts

@@ -75,5 +75,9 @@ export type {
   VaultTransfer,
   VaultModify,
   VaultWithdraw,
+  VaultDistribute,
 } from './vault.js';
-export type { SubmitEncryptedOrder } from './encrypted.js';
+export type { SubmitEncryptedOrder, EncryptedOrderSubmit } from './encrypted.js';
+export type { CoreSide, RfqRequest, RfqAccept } from './rfq.js';
+export type { FbaSubmit } from './fba.js';
+export type { CrossChainSend } from './cross-chain.js';

package/src/types/info/core.ts

@@ -97,22 +97,28 @@ export interface Funding {
   next_payment_ts: number;
 }
 
+/// Market kind. The deployed gateway emits lowercase `"perp"` / `"spot"`.
+export type MarketKind = 'perp' | 'spot';
+
 /// `market_info` / `markets` element — rich per-market metadata.
 ///
-/// `mark_px` is the on-book mark in the 1e8 fixed-point plane; `oracle_px` is
-/// the index price in the whole-USDC plane. Both are `"0"` when unset. (These
-/// two price fields are emitted by the node `market_record` builder; they are
-/// not yet listed in the KB field table but are part of the live wire shape.)
+/// `mark_px` and `oracle_px` are whole-USDC decimal strings (tick-snapped;
+/// `"0"` fallback). `sz_decimals` is load-bearing for size encoding — raw
+/// order/position `size` = `whole_units × 10^sz_decimals`, NOT derivable from
+/// `step_size`.
 export interface MarketInfo {
   /// Canonical asset id.
   asset_id: number;
   /// Human-readable market name (e.g. `"BTC"`).
   name: string;
-  /// Market kind — currently always `"Perp"`.
-  kind: string;
-  /// On-book mark price, 1e8 fixed-point as a decimal string.
+  /// Market kind — lowercase `"perp"` / `"spot"`.
+  kind: MarketKind;
+  /// Size precision: raw order/position `size` = `whole_units × 10^sz_decimals`.
+  /// Load-bearing for size encoding — NOT derivable from `step_size`.
+  sz_decimals: number;
+  /// Mark price, whole-USDC plane as a decimal string (`"0"` fallback).
   mark_px: string;
-  /// Oracle/index price, whole-USDC plane as a decimal string.
+  /// Oracle/index price, whole-USDC plane as a decimal string (`"0"` fallback).
   oracle_px: string;
   /// Tick size (smallest price increment), fixed-point string.
   tick_size: string;
@@ -201,14 +207,23 @@ export interface FeeTier {
 }
 
 /// `fee_schedule` — protocol fee schedule. Fee rates are decimal bps strings;
-/// `burn_ratio` is a decimal fraction string (`"0.30"` = 30%).
+/// `burn_ratio` is a decimal fraction string in `[0, 1]` (`"0.8"` = 80%) — NOT
+/// bps, do not scale it by 10000. `tiers[0]` is the authoritative carrier of
+/// maker/taker when the top-level pair is absent.
 export interface FeeSchedule {
-  /// Volume-tier ladder.
+  /// Top-level base maker fee, decimal bps string. Present on the deployed
+  /// gateway; ABSENT from a node built from current source — fall back to
+  /// `tiers[0].maker_bps` when `undefined`.
+  maker_bps?: string;
+  /// Top-level base taker fee, decimal bps string. See `maker_bps`.
+  taker_bps?: string;
+  /// Volume-tier ladder (authoritative carrier of maker/taker).
   tiers: FeeTier[];
-  /// Builder rebate, decimal bps string.
+  /// Max additional builder-code rebate, decimal bps string.
   builder_rebate_bps: string;
-  /// Fraction of fees burned, decimal fraction string.
+  /// Burn fraction of the non-referrer remainder, decimal fraction string in
+  /// `[0, 1]` (NOT bps).
   burn_ratio: string;
-  /// Referrer share, decimal bps string.
+  /// Referrer share of the base taker take, decimal bps string.
   referrer_share_bps: string;
 }

package/src/types/info/index.ts

@@ -11,6 +11,7 @@ export type {
   Tier,
   MarginMode,
   MarketInfo,
+  MarketKind,
   Funding,
   VaultState,
   StakingState,

package/src/types/info/reads.ts

@@ -5,18 +5,30 @@
 // Money magnitudes that can exceed 2^53 are typed `string`.
 
 /// One resting order inside an `OpenOrders` response.
+///
+/// `px` is x1e8 fixed-point (positive canonical price for **both** sides);
+/// `size` is raw lots (`whole × 10^sz_decimals`). `side` is lowercase
+/// `"bid"`/`"ask"`. `oid` / `market_id` / `inserted_at_ms` are bare integers.
+///
+/// LIVE GATEWAY GAP: a resting order currently reads back with `oid: 0` and
+/// `inserted_at_ms: 0` even though it is on the book — so an order is NOT
+/// reliably cancellable by the `oid` from this snapshot, and it carries no
+/// `cloid`. Until the gateway populates `oid`, the oid-independent workaround
+/// for reconcile / ghost-sweep is the `cancel_all_orders` exchange action
+/// (`Client.cancelAllOrders`, keyed by account / asset) rather than per-oid
+/// cancels.
 export interface OpenOrder {
-  /// Server order id.
+  /// Server order id. See the note: currently `0` on the gateway.
   oid: number;
   /// Asset / market id the order rests on.
   market_id: number;
-  /// Order side.
+  /// Order side, lowercase `"bid"` / `"ask"`.
   side: 'bid' | 'ask';
-  /// Resting price, fixed-point decimal string.
+  /// Resting price, x1e8 fixed-point decimal string.
   px: string;
-  /// Remaining size, fixed-point decimal string.
+  /// Remaining size, raw lots (`whole × 10^sz_decimals`) decimal string.
   size: string;
-  /// Insertion timestamp (consensus ms).
+  /// Insertion timestamp (consensus ms). See the note: currently `0`.
   inserted_at_ms: number;
 }
 

package/src/types/rfq.ts

@@ -0,0 +1,55 @@
+// MTF-native RFQ (Request-for-Quote) action payload types.
+//
+// Forward-compat: the node recognizes the `rfq_request` / `rfq_accept` action
+// tags but currently lowers them to `UnsupportedAction` on the public
+// `/exchange` path (the real handlers run on the EVM core-writer path). The SDK
+// emits the byte-correct wire shape each core param struct expects, so these
+// go live the moment the node bridges them — no SDK change required.
+
+/// Order side as the **core** RFQ / FBA action handlers deserialize it:
+/// PascalCase `"Bid"` / `"Ask"`.
+///
+/// Deliberately distinct from the snake_case `NativeSide` (`"bid"`/`"ask"`)
+/// used by the perp/spot order builders: the node's `core_state::Side` enum
+/// carries no `#[serde(rename_all)]`, so the `rfq_request` / `fba_submit`
+/// payloads expect PascalCase tokens. Reusing the snake_case side would
+/// silently emit `"bid"`/`"ask"` that the core handlers reject.
+export type CoreSide = 'Bid' | 'Ask';
+
+/// `rfq_request` — a taker opens an RFQ session asking MMs to quote. Mirrors the
+/// node's `core_state` `RfqRequestParams`. The action envelope wraps this under
+/// the key **`rfq`** (not `params`).
+///
+/// `limit_px` and `stp_group` carry NO serde default on the node, so the keys
+/// must always be present — an absent value serializes as JSON `null` (the SDK
+/// does NOT skip them).
+export interface RfqRequest {
+  /// Market to request a quote on (`u32`).
+  market: number;
+  /// Taker side — serializes PascalCase (`"Bid"`/`"Ask"`).
+  side: CoreSide;
+  /// Requested size (`u128`, `> 0`). `bigint` — emitted as a bare JSON number.
+  size: bigint;
+  /// Optional worst-acceptable price (`i128`). The key is ALWAYS present:
+  /// `null` when absent (do NOT omit). `bigint` — emitted as a bare number.
+  limit_px: bigint | null;
+  /// Server-clock expiry (ms, `u64`). `0` lets the node default to `ts_ms + 5000`.
+  expiry_ms: number;
+  /// Optional STP group id (`u64`). The key is ALWAYS present: `null` when
+  /// absent (do NOT omit).
+  stp_group: number | null;
+}
+
+/// `rfq_accept` — a taker crosses against a specific resting quote. Mirrors the
+/// node's `RfqAcceptParams`. The action envelope wraps this under the key
+/// **`accept`** — note the family inconsistency (`rfq_request` uses `rfq`,
+/// `rfq_accept` uses `accept`).
+export interface RfqAccept {
+  /// Parent RFQ session id (`u64`).
+  rfq_id: number;
+  /// Index of the accepted quote in the session's quote vector (`u32`).
+  quote_idx: number;
+  /// Accepted size (`u128`, `<= min(request.size, quote.max_size)`). `bigint` —
+  /// emitted as a bare JSON number.
+  size: bigint;
+}

package/src/types/vault.ts

@@ -53,3 +53,24 @@ export interface VaultWithdraw {
   /// Shares to redeem, as a decimal string.
   shares: string;
 }
+
+/// `vault_distribute` — a follower deposits USD into a vault and receives shares
+/// at the current NAV (subject to the per-vault withdrawal lock). Mirrors the
+/// node's `core_state` `VaultDistributeParams`; the action envelope wraps this
+/// under the key **`params`**.
+///
+/// **Trap:** the deposit-amount field is named **`pnl`** (a legacy name on the
+/// node), NOT `amount`/`deposit`. It is a positive USD amount encoded as a
+/// decimal string (the SDK's decimal-on-the-wire convention, matching
+/// `vault_transfer` / `vault_withdraw`).
+///
+/// Forward-compat: the node currently answers this tag with `UnsupportedAction`
+/// on the public `/exchange` path; the SDK emits the byte-correct shape the core
+/// handler will accept once the bridge lands.
+export interface VaultDistribute {
+  /// Target vault id (`u64`). Serializes as a bare JSON number.
+  vault_id: number;
+  /// Deposit amount in USD as a positive decimal string. Node field name is
+  /// `pnl` (legacy) — do NOT rename.
+  pnl: string;
+}