@metaflux-dex/client 0.0.3 → 0.0.6

package/src/{native.ts → native/digest.ts}

@@ -1,8 +1,8 @@
-// MTF-native signed-action digest + envelope construction.
+// MTF-native signed-action digest + envelope construction (signing core).
 //
 // 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`).
+// server's native-action signature verifier.
 //
 // digest = keccak256(0x1901 || domainSep5 || structHash)
 //   domainSep5 = keccak256(
@@ -16,21 +16,16 @@
 // 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.
+// from a parsed object. The `build*Action` functions in `./actions.js` are the
+// single source of those bytes.
 
 import {
   deriveAddressFromPubkey,
   keccak256,
   recoverPubkey,
   signSecp256k1,
-} from './wasm.js';
-import type {
-  NativeBuilder,
-  NativeCancel,
-  NativeOrder,
-  NativeSignedAction,
-} from './types.js';
+} from '../wallet/wasm.js';
+import type { NativeSignedAction } from '../types/index.js';
 
 const MTF_DOMAIN_TYPE =
   'EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)';
@@ -70,7 +65,7 @@ export function nextNonce(): bigint {
 /// 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 {
+export 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);
@@ -83,7 +78,7 @@ function be32(value: bigint): Uint8Array {
 }
 
 /// Concatenate 32-byte chunks into one buffer.
-function concat32(...chunks: Uint8Array[]): Uint8Array {
+export function concat32(...chunks: Uint8Array[]): Uint8Array {
   const out = new Uint8Array(chunks.length * 32);
   chunks.forEach((c, i) => {
     if (c.length !== 32) {
@@ -95,7 +90,7 @@ function concat32(...chunks: Uint8Array[]): Uint8Array {
 }
 
 /// Compute the 5-field MTF-native EIP-712 domain separator.
-async function domainSeparator(chainId: number): Promise<Uint8Array> {
+export 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'));
@@ -138,7 +133,7 @@ export async function nativeActionDigest(
 }
 
 /// Lowercase hex (no `0x`) of a byte buffer.
-function toHex(bytes: Uint8Array): string {
+export function toHex(bytes: Uint8Array): string {
   let out = '';
   for (const b of bytes) out += b.toString(16).padStart(2, '0');
   return out;
@@ -151,84 +146,10 @@ function toHex(bytes: Uint8Array): string {
 /// / 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 {
+export 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
@@ -278,27 +199,27 @@ export function nativeRequestBody(signed: NativeSignedAction): string {
 
 // ---- validation helpers (fail loud before anything reaches the signed body) ----
 
-function validateAddress(addr: string, field: string): void {
+export 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 {
+export 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 {
+export 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 {
+export function validateU64(value: number, field: string): void {
   if (!Number.isInteger(value) || value < 0) {
     throw new RangeError(`${field} must be a non-negative integer`);
   }
@@ -309,7 +230,69 @@ function validateU64(value: number, field: string): void {
   }
 }
 
-function hexToBytes(hex: string): Uint8Array {
+/// Validate a `u32` field passed as a plain `number` (e.g. dst_chain,
+/// window_ms, action-own nonces). Same shape as `validateMarket` but with a
+/// caller-supplied field name for the error message.
+export function validateU32(value: number, field: string): void {
+  if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) {
+    throw new RangeError(`${field} must be a u32`);
+  }
+}
+
+/// Validate a `u16` field passed as a plain `number` (e.g. management_fee_bps).
+export function validateU16(value: number, field: string): void {
+  if (!Number.isInteger(value) || value < 0 || value > 0xffff) {
+    throw new RangeError(`${field} must be a u16 (0..=65535)`);
+  }
+}
+
+/// Validate a `u8` field passed as a plain `number` (e.g. threshold).
+export function validateU8(value: number, field: string): void {
+  if (!Number.isInteger(value) || value < 0 || value > 0xff) {
+    throw new RangeError(`${field} must be a u8 (0..=255)`);
+  }
+}
+
+/// Validate a `u128` field passed as a `bigint`, emitted as a bare unquoted
+/// integer literal on the wire (serde u128 JSON number form). Rejects negatives
+/// and values that overflow 128 bits.
+export function validateU128(value: bigint, field: string): void {
+  if (typeof value !== 'bigint') {
+    throw new RangeError(`${field} must be a bigint`);
+  }
+  if (value < 0n) throw new RangeError(`${field} must be non-negative`);
+  if (value >= 1n << 128n) throw new RangeError(`${field} overflows u128`);
+}
+
+/// 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
+/// be JSON strings to preserve fractional precision past 2^53. Accepts an
+/// optional sign, integer and/or fractional parts; rejects empty / malformed
+/// input and (by default) non-positive values.
+export function validateDecimalString(
+  value: string,
+  field: string,
+  opts: { allowZero?: boolean; allowNegative?: boolean } = {},
+): void {
+  if (typeof value !== 'string') {
+    throw new RangeError(`${field} must be a decimal string`);
+  }
+  if (!/^-?(?:\d+\.?\d*|\.\d+)$/.test(value)) {
+    throw new RangeError(`${field} must be a decimal string, got '${value}'`);
+  }
+  const negative = value.startsWith('-');
+  if (negative && !opts.allowNegative) {
+    throw new RangeError(`${field} must be non-negative`);
+  }
+  // Reject a pure-zero magnitude (e.g. "0", "0.0", "-0.00") unless allowed.
+  const isZero = /^-?0*\.?0*$/.test(value);
+  if (isZero && !opts.allowZero) {
+    throw new RangeError(`${field} must be greater than zero`);
+  }
+}
+
+export 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++) {

package/src/native/index.ts

@@ -0,0 +1,5 @@
+// Re-export barrel for the native signed-action surface: the signing core
+// (`digest.ts`) and the canonical action builders (`actions.ts`).
+
+export * from './digest.js';
+export * from './actions.js';

package/src/{http.ts → rest/http.ts}

@@ -6,7 +6,7 @@
 // caller has authenticated), and (c) translating the gateway's CCXT-
 // compat error envelope `{ "error": "..." }` into a typed exception.
 
-import type { ErrorEnvelope } from './types.js';
+import type { ErrorEnvelope } from '../types/index.js';
 
 /// Thrown when the gateway responds with a non-2xx status. Carries the
 /// status code + the message extracted from `{ "error": "..." }` (or

package/src/{info.ts → rest/info.ts}

@@ -1,8 +1,7 @@
 // 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
+// Byte-for-byte mirror of the server's `/info` dispatcher and per-handler
+// shapes (per the KB spec metaflux-knowledges/api/rest/info.md). 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
@@ -23,7 +22,7 @@
 // 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
+// typed `string` in `../types/info/index.js` to match the node's decimal-string
 // encoding; ids / counts / bps stay `number`.
 
 import { httpRequest } from './http.js';
@@ -66,7 +65,7 @@ import type {
   VaultState,
   VaultSummaries,
   WebData2,
-} from './info-types.js';
+} from '../types/info/index.js';
 
 /// The committed `{type, data}` response envelope every `/info` query returns.
 interface InfoEnvelope<T> {
@@ -183,7 +182,11 @@ export class InfoApi {
 
   // ── HL-node parity reads ────────────────────────────────────────────────
 
-  /// `spot_meta` — spot pair universe. No parameters.
+  /// `spot_meta` — spot pair universe + token registry. No parameters.
+  ///
+  /// Each pair's `name` is derived as `{base}/{quote}` from the token
+  /// registry; the numeric `id` is the compact `coin` label spot prints carry
+  /// on the WS `trades` / `candles` / `fills` channels.
   async spotMeta(): Promise<SpotMeta> {
     return this.post<SpotMeta>({ type: 'spot_meta' });
   }

package/src/types/account.ts

@@ -0,0 +1,111 @@
+// MTF-native account / margin / agent action payload types.
+//
+// All sender-authorized: the recovered signer is the account whose state
+// mutates, so none carry an `owner` field. Decimal magnitudes (`delta` /
+// `amount` / `value`) ride the wire as JSON strings to preserve precision; ids,
+// leverage, and bps are plain integers.
+
+/// `update_leverage` — set the per-asset leverage (and optionally flip to
+/// isolated margin).
+export interface UpdateLeverage {
+  /// Target asset / market id (`u32`).
+  asset: number;
+  /// New leverage multiplier (`u32`, e.g. `10`).
+  leverage: number;
+  /// `true` also switches the asset to isolated margin.
+  is_isolated: boolean;
+}
+
+/// `update_isolated_margin` — add or remove isolated margin on an open position.
+export interface UpdateIsolatedMargin {
+  /// Target asset / market id (`u32`).
+  asset: number;
+  /// Signed margin delta as a decimal string (`+` adds, `-` withdraws).
+  delta: string;
+}
+
+/// `top_up_isolated_only_margin` — top up a strict-isolated-only position.
+export interface TopUpIsolatedOnlyMargin {
+  /// Target asset / market id (`u32`).
+  asset: number;
+  /// Amount to add, as a positive decimal string.
+  amount: string;
+}
+
+/// `user_portfolio_margin` — enroll into or out of portfolio margin.
+export interface UserPortfolioMargin {
+  /// `true` = enroll, `false` = unenroll.
+  enroll: boolean;
+}
+
+/// `set_display_name` — set the account display name (handle).
+export interface SetDisplayName {
+  /// Human-readable handle (e.g. `alice.mtf`).
+  display_name: string;
+}
+
+/// `set_referrer` — set the account referrer (one-time, immutable once set).
+export interface SetReferrer {
+  /// `0x`-hex 20-byte referrer address.
+  referrer: string;
+}
+
+/// `approve_agent` — approve an agent wallet to sign on behalf of this account.
+export interface ApproveAgent {
+  /// `0x`-hex 20-byte agent address.
+  agent: string;
+  /// Optional human-readable agent label.
+  name?: string;
+  /// Optional expiry (unix ms). Omit for never-expires.
+  expires_at_ms?: number;
+}
+
+/// `approve_builder_fee` — approve a builder to charge up to `max_bps` on this
+/// account's orders. `max_bps = 0` revokes.
+export interface ApproveBuilderFee {
+  /// `0x`-hex 20-byte builder address.
+  builder: string;
+  /// Maximum approved fee in basis points (`u16`).
+  max_bps: number;
+}
+
+/// `convert_to_multi_sig_user` — convert the account to an M-of-N multisig.
+export interface ConvertToMultiSigUser {
+  /// `0x`-hex 20-byte authorized signer addresses.
+  signers: string[];
+  /// Signature threshold `M` of `signers.length` (`u32`).
+  threshold: number;
+}
+
+/// `user_dex_abstraction` — toggle the account's DEX-abstraction opt-in flag.
+export interface UserDexAbstraction {
+  /// `true` = opt in, `false` = opt out.
+  enabled: boolean;
+}
+
+/// `user_set_abstraction` — set a self-scoped abstraction config value.
+export interface UserSetAbstraction {
+  /// Sub-type tag (`u8`, 0..=255); interpretation is config-defined.
+  kind: number;
+  /// Setting value as a decimal string.
+  value: string;
+}
+
+/// `agent_set_abstraction` — an approved agent sets an abstraction config value
+/// for `user`. The node verifies the signer is an approved agent of `user`.
+export interface AgentSetAbstraction {
+  /// `0x`-hex 20-byte account whose config the agent is updating.
+  user: string;
+  /// Sub-type tag (`u8`, 0..=255).
+  kind: number;
+  /// Setting value as a decimal string.
+  value: string;
+}
+
+/// `priority_bid` — pay a priority fee (bps) for block-front placement.
+export interface PriorityBid {
+  /// Asset this bid is bound to (`u32`).
+  asset: number;
+  /// Bid in basis points (`u16`).
+  bid_bps: number;
+}

package/src/types/encrypted.ts

@@ -0,0 +1,21 @@
+// MTF-native encrypted-order action payload type.
+//
+// Sender-authorized: the recovered signer is the submitter. Decryption shares
+// accumulate over subsequent blocks until `threshold` is met; the order is then
+// revealed (checked against `commitment`) and matched.
+
+/// `submit_encrypted_order` — submit a threshold-encrypted order ciphertext.
+export interface SubmitEncryptedOrder {
+  /// Ciphertext bytes — emitted as a JSON array of byte numbers.
+  ciphertext: Uint8Array;
+  /// 32-byte `keccak(plaintext‖salt)` commitment binding the revealed order —
+  /// emitted as a JSON array of 32 byte numbers.
+  commitment: Uint8Array;
+  /// Threshold of decryption shares required to reveal (`u8`, `>= 1`).
+  threshold: number;
+  /// Earliest block at which the ciphertext can be revealed (`u64`).
+  target_block: number;
+  /// Deadline (unix ms) by which the order must be revealed, else it expires
+  /// (`u64`).
+  reveal_deadline_ms: number;
+}

package/src/types/governance.ts

@@ -0,0 +1,27 @@
+// MTF-native governance / operator action payload types.
+//
+// Sender-authorized, with action-level authorization enforced by the node at
+// dispatch: `set_metaliquidity_whitelist` requires validator membership, and
+// `register_metaliquidity_operator` requires the signer to be the vault leader.
+
+/// `set_metaliquidity_whitelist` — set an MLP whitelist membership (validator
+/// vote).
+export interface SetMetaliquidityWhitelist {
+  /// `0x`-hex 20-byte address whose membership is being set.
+  address: string;
+  /// `true` adds to the whitelist, `false` removes.
+  allowed: boolean;
+}
+
+/// `register_metaliquidity_operator` — register or revoke an external strategy
+/// operator for a vault.
+export interface RegisterMetaliquidityOperator {
+  /// Target vault id (`u64`).
+  vault_id: number;
+  /// `0x`-hex 20-byte operator address.
+  operator: string;
+  /// `true` registers, `false` revokes.
+  allowed: boolean;
+  /// Optional expiry (unix ms). Omit for never-expires.
+  expires_at_ms?: number;
+}

package/src/types/index.ts

@@ -0,0 +1,79 @@
+// Re-export barrel for every type module.
+//
+// Keeping the type surface behind one barrel means internal modules import from
+// `../types/index.js` and the public `src/index.ts` re-exports from here.
+
+export type {
+  Order,
+  Builder,
+  SignedOrder,
+  OrderAck,
+  Market,
+  Position,
+  Side,
+  Tif,
+  StpMode,
+  ErrorEnvelope,
+  // MTF-native action types.
+  NativeOrder,
+  NativeCancel,
+  NativeBuilder,
+  NativeSide,
+  NativePositionSide,
+  NativeOrderKind,
+  NativeTif,
+  NativeStpMode,
+  NativeSetPositionMode,
+  NativeSignedAction,
+  NativeExchangeAck,
+  OrderStatus,
+  // Order-management actions.
+  OrderGrouping,
+  Modify,
+  BatchModify,
+  BatchOrder,
+  BatchCancel,
+  CancelByCloid,
+  ScheduleCancel,
+  CancelAllOrders,
+} from './trading.js';
+export type {
+  NativeSpotOrder,
+  NativeSpotCancel,
+  NativeSpotMarginDeposit,
+  NativeSpotMarginWithdraw,
+  NativeSpotMarginOpen,
+  NativeSpotMarginClose,
+  NativeEarnDeposit,
+  NativeEarnWithdraw,
+} from './spot.js';
+export type {
+  UpdateLeverage,
+  UpdateIsolatedMargin,
+  TopUpIsolatedOnlyMargin,
+  UserPortfolioMargin,
+  SetDisplayName,
+  SetReferrer,
+  ApproveAgent,
+  ApproveBuilderFee,
+  ConvertToMultiSigUser,
+  UserDexAbstraction,
+  UserSetAbstraction,
+  AgentSetAbstraction,
+  PriorityBid,
+} from './account.js';
+export type { TokenDelegate, ClaimRewards, LinkStakingUser } from './staking.js';
+export type { TwapOrder, TwapCancel } from './twap.js';
+export type {
+  SetMetaliquidityWhitelist,
+  RegisterMetaliquidityOperator,
+} from './governance.js';
+export type { MbChain, MbWithdraw } from './meta-bridge.js';
+export type {
+  VaultKind,
+  CreateVault,
+  VaultTransfer,
+  VaultModify,
+  VaultWithdraw,
+} from './vault.js';
+export type { SubmitEncryptedOrder } from './encrypted.js';