@0xmonaco/core 1.0.54 → 1.0.56

package/dist/api/base.d.ts

@@ -20,7 +20,7 @@
  * }
  * ```
  */
-import type { SessionCredentials } from "@0xmonaco/types";
+import type { RequestSigning, SessionCredentials } from "@0xmonaco/types";
 import { type SessionKeypair } from "../crypto/session";
 export interface RetryOptions {
     maxRetries?: number;
@@ -32,6 +32,9 @@ export declare abstract class BaseAPI {
     protected sessionKeypair?: SessionKeypair;
     /** Application secret key (`sk_...`) sent in the `x-server-key` header for backend-authenticated requests. */
     protected serverKey?: string;
+    private requestSigning;
+    /** Opt in only after the target server supports RFC 9421. No automatic downgrade. */
+    setRequestSigning(protocol: RequestSigning): void;
     protected retryOptions: Required<RetryOptions>;
     /**
      * Creates a new BaseAPI instance.
@@ -108,10 +111,11 @@ export declare abstract class BaseAPI {
     /**
      * Compute the per-request ed25519 signature headers.
      *
-     * The signed payload is `METHOD\nPATH_WITH_QUERY\nTIMESTAMP_MS\nSHA256_BODY_HEX`,
+     * Legacy signing uses `METHOD\nPATH_WITH_QUERY\nTIMESTAMP_MS\nSHA256_BODY_HEX`,
      * matching the server (`handlers::auth::compose_signing_string`). `endpoint`
      * is the path-with-query exactly as sent; the body hash covers the raw bytes
-     * so a request can't be replayed with a different body.
+     * so a request cannot be reused with a different body. RFC 9421 is opt-in
+     * and covers the final URL path/query plus Content-Digest.
      */
     private buildSignatureHeaders;
     /**

package/dist/api/base.js

@@ -22,6 +22,7 @@
  */
 import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils";
 import { StatusCodes } from "http-status-codes";
+import { buildHttpSignatureHeaders } from "../crypto/http-signatures";
 import { composeSigningString, keypairFromHex, sha256Hex, signMessage } from "../crypto/session";
 import { APIError } from "../errors";
 /**
@@ -146,6 +147,13 @@ export class BaseAPI {
     sessionKeypair;
     /** Application secret key (`sk_...`) sent in the `x-server-key` header for backend-authenticated requests. */
     serverKey;
+    requestSigning = "legacy";
+    /** Opt in only after the target server supports RFC 9421. No automatic downgrade. */
+    setRequestSigning(protocol) {
+        if (protocol !== "legacy" && protocol !== "rfc9421")
+            throw new Error("Unsupported request signing protocol");
+        this.requestSigning = protocol;
+    }
     retryOptions;
     /**
      * Creates a new BaseAPI instance.
@@ -389,22 +397,32 @@ export class BaseAPI {
         const url = `${this.apiUrl}${endpoint}`;
         const requestBody = this.parseRequestBody(options.body);
         const signatureHeaders = this.buildSignatureHeaders(endpoint, options);
+        let extraHeaders = options.headers;
+        if (this.requestSigning === "rfc9421") {
+            const normalized = {};
+            new Headers(options.headers).forEach((value, name) => {
+                normalized[name] = value;
+            });
+            extraHeaders = normalized;
+        }
         return this.executeRequest(url, endpoint, {
             ...options,
+            ...(this.requestSigning === "rfc9421" ? { redirect: "error" } : {}),
             headers: {
                 "Content-Type": "application/json",
+                ...extraHeaders,
                 ...signatureHeaders,
-                ...options.headers,
             },
         }, requestBody);
     }
     /**
      * Compute the per-request ed25519 signature headers.
      *
-     * The signed payload is `METHOD\nPATH_WITH_QUERY\nTIMESTAMP_MS\nSHA256_BODY_HEX`,
+     * Legacy signing uses `METHOD\nPATH_WITH_QUERY\nTIMESTAMP_MS\nSHA256_BODY_HEX`,
      * matching the server (`handlers::auth::compose_signing_string`). `endpoint`
      * is the path-with-query exactly as sent; the body hash covers the raw bytes
-     * so a request can't be replayed with a different body.
+     * so a request cannot be reused with a different body. RFC 9421 is opt-in
+     * and covers the final URL path/query plus Content-Digest.
      */
     buildSignatureHeaders(endpoint, options) {
         if (!this.sessionKeypair) {
@@ -414,6 +432,17 @@ export class BaseAPI {
             });
         }
         const method = (options.method ?? "GET").toUpperCase();
+        if (this.requestSigning === "rfc9421") {
+            if (options.body != null && typeof options.body !== "string")
+                throw new Error("Signed requests require a string body");
+            const headers = new Headers(options.headers);
+            for (const name of ["signature", "signature-input", "content-digest", "x-monaco-publickey", "x-monaco-timestamp", "x-monaco-signature"]) {
+                if (headers.has(name))
+                    throw new Error("Signature headers are managed by the SDK");
+            }
+            const url = new URL(`${this.apiUrl}${endpoint}`);
+            return buildHttpSignatureHeaders(this.sessionKeypair, method, url.pathname + url.search, utf8ToBytes(options.body ?? ""), Math.floor(Date.now() / 1000));
+        }
         const timestampMs = Date.now();
         const bodyBytes = typeof options.body === "string" ? utf8ToBytes(options.body) : new Uint8Array(0);
         const bodyHash = sha256Hex(bodyBytes);

package/dist/api/perp/routes.d.ts

@@ -164,6 +164,7 @@ export declare const perpRoutes: {
     };
     readonly sweeper: {
         readonly register: () => string;
+        readonly chains: () => string;
     };
     readonly whitelist: {
         readonly submit: () => string;

package/dist/api/perp/routes.js

@@ -89,6 +89,7 @@ export const perpRoutes = {
     },
     sweeper: {
         register: () => `${API_V1}/sweeper/register`,
+        chains: () => `${API_V1}/sweeper/chains`,
     },
     whitelist: {
         submit: () => `${API_V1}/whitelist`,

package/dist/api/sweeper/api.d.ts

@@ -22,7 +22,7 @@
  * const margin = await sdk.sweeper.register({ depositTarget: "margin" });
  * ```
  */
-import type { RegisterSweeperRequest, RegisterSweeperResponse, SweeperAPI } from "@0xmonaco/types";
+import type { GetSweeperChainsResponse, RegisterSweeperRequest, RegisterSweeperResponse, SweeperAPI } from "@0xmonaco/types";
 import { BaseAPI } from "../base";
 export declare class SweeperAPIImpl extends BaseAPI implements SweeperAPI {
     /**
@@ -42,10 +42,25 @@ export declare class SweeperAPIImpl extends BaseAPI implements SweeperAPI {
      * rather than a guarantee, since a deposit the backend cannot route to
      * collateral is credited to the spot wallet instead.
      *
+     * The deposit address is identical on every supported chain and one
+     * registration is watched on all of them (see {@link getChains} for the
+     * set), so there is nothing chain-specific to pass.
+     *
      * @param body - Optionally the destination ledger; everything else comes
      *   from the session
      * @returns Promise resolving to the deposit address and the initial-check
      *   state
      */
     register(body?: RegisterSweeperRequest): Promise<RegisterSweeperResponse>;
+    /**
+     * The chains and assets the sweeper watches: where a registered deposit
+     * address accepts deposits, which tokens are swept on each chain, and each
+     * token's minimum sweep amount in raw base units.
+     *
+     * Public — no session needed. The set changes only with operator
+     * configuration, so it is safe to cache briefly.
+     *
+     * @returns Promise resolving to the supported chain/asset listing
+     */
+    getChains(): Promise<GetSweeperChainsResponse>;
 }

package/dist/api/sweeper/api.js

@@ -69,6 +69,10 @@ export class SweeperAPIImpl extends BaseAPI {
      * rather than a guarantee, since a deposit the backend cannot route to
      * collateral is credited to the spot wallet instead.
      *
+     * The deposit address is identical on every supported chain and one
+     * registration is watched on all of them (see {@link getChains} for the
+     * set), so there is nothing chain-specific to pass.
+     *
      * @param body - Optionally the destination ledger; everything else comes
      *   from the session
      * @returns Promise resolving to the deposit address and the initial-check
@@ -82,4 +86,19 @@ export class SweeperAPIImpl extends BaseAPI {
             body: JSON.stringify(wireBody),
         });
     }
+    /**
+     * The chains and assets the sweeper watches: where a registered deposit
+     * address accepts deposits, which tokens are swept on each chain, and each
+     * token's minimum sweep amount in raw base units.
+     *
+     * Public — no session needed. The set changes only with operator
+     * configuration, so it is safe to cache briefly.
+     *
+     * @returns Promise resolving to the supported chain/asset listing
+     */
+    async getChains() {
+        return await this.makePublicRequest(perpRoutes.sweeper.chains(), {
+            method: "GET",
+        });
+    }
 }

package/dist/api/websocket/websocket.js

@@ -82,6 +82,12 @@ function readOptionalNumber(source, field) {
     }
     return value;
 }
+function readOptionalSequence(source, field) {
+    const value = source[field];
+    if (value === undefined || value === null)
+        return undefined;
+    return readSequence(source, field);
+}
 function readStringArray(source, field) {
     const value = source[field];
     if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
@@ -492,6 +498,7 @@ function parseUserBalanceEventData(raw) {
         lockedRaw: readString(data, "lockedRaw"),
         total: readString(data, "total"),
         totalRaw: readString(data, "totalRaw"),
+        version: readOptionalSequence(data, "version"),
         // Free-form on the wire and read leniently: a snapshot row carries the
         // `snapshot` literal, a live frame the mutation cause, and a reason added
         // server-side after this SDK shipped must not drop the row (0XM-2627).
@@ -500,6 +507,20 @@ function parseUserBalanceEventData(raw) {
         updatedAt: readString(data, "updatedAt"),
     };
 }
+/**
+ * Parse one row from a `balances` channel snapshot.
+ *
+ * `version` is read leniently, for the same reason `reason` is: a pre-feature
+ * server sends no version at all, and rejecting the row would drop the entire
+ * subscribe-time baseline for a client whose SDK is ahead of the server it is
+ * talking to. `UserBalanceEventData.version` is optional precisely so an absent
+ * value is representable, and consumers already treat it as the unranked
+ * sentinel. A version that IS present is still validated — `readSequence`
+ * rejects negative and unsafe values.
+ */
+function parseBalanceSnapshotItem(raw) {
+    return parseUserBalanceEventData(raw);
+}
 /**
  * Parse one resting order from an `orders` channel snapshot.
  *
@@ -847,9 +868,14 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
                     sendAuthenticate();
                     resubscribeAll();
                     options.onStatusChange?.("connected");
-                    // Send auth/subscribe requests before asking the application to
-                    // reconcile. This callback does not wait for acknowledgements or
-                    // snapshots, and the SDK does not perform REST recovery itself.
+                    // Resync-join order: the live stream resumes first (auth +
+                    // subscribe above), then the application is asked to refetch
+                    // snapshots and reconcile against each channel's authoritative
+                    // identity/version. Balance ordering uses the durable row version,
+                    // never `updatedAt`, arrival time, or receiver backlog.
+                    //
+                    // This callback waits for neither acknowledgements nor snapshots,
+                    // and the SDK performs no REST recovery itself.
                     if (pendingResyncCode !== null) {
                         const code = pendingResyncCode;
                         pendingResyncCode = null;
@@ -1201,7 +1227,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             catch (err) {
                 console.error("WebSocket: Error processing balance event", err);
             }
-        }, onSnapshot && snapshotFrameHandler("balances", parseUserBalanceEventData, onSnapshot));
+        }, onSnapshot && snapshotFrameHandler("balances", parseBalanceSnapshotItem, onSnapshot));
     };
     const subscribeConditionalOrders = (handler, tradingPairId, onSnapshot) => {
         if (!handler) {

package/dist/coverage.d.ts

@@ -35,6 +35,7 @@ export declare const COVERED: {
     get_market_stats: string;
     get_my_fee_tier: string;
     get_pulse: string;
+    get_sweeper_chains: string;
     get_my_trader_code: string;
     get_rewards_balance: string;
     get_trader_code_info: string;

package/dist/coverage.js

@@ -35,6 +35,7 @@ export const COVERED = {
     get_market_stats: "getMarketStats",
     get_my_fee_tier: "getMyFeeTier",
     get_pulse: "pulse.getPulse",
+    get_sweeper_chains: "sweeper.getChains",
     get_my_trader_code: "pitpass.getMyTraderCode",
     get_rewards_balance: "pitpass.getRewardsBalance",
     get_trader_code_info: "pitpass.getTraderCodeInfo",

package/dist/crypto/http-signatures.d.ts

@@ -0,0 +1,3 @@
+import type { SessionKeypair } from "./session";
+/** Sign an already URL-encoded path/query and the exact bytes that will be sent. */
+export declare function buildHttpSignatureHeaders(keypair: SessionKeypair, method: string, target: string, body: Uint8Array, created: number): Record<string, string>;

package/dist/crypto/http-signatures.js

@@ -0,0 +1,26 @@
+/** Monaco's RFC 9421 Ed25519 profile; key registration remains wallet-authorized. */
+import { ed25519 } from "@noble/curves/ed25519";
+import { sha256 } from "@noble/hashes/sha2";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils";
+function base64(bytes) {
+    return btoa(String.fromCharCode(...bytes));
+}
+/** Sign an already URL-encoded path/query and the exact bytes that will be sent. */
+export function buildHttpSignatureHeaders(keypair, method, target, body, created) {
+    if (!Number.isSafeInteger(created) || created < 0 || created > 999_999_999_999_999)
+        throw new Error("Invalid signature creation time");
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: reject control characters before constructing signature lines
+    if (!/^[A-Z]+$/.test(method) || !target.startsWith("/") || /[\s#\u0000-\u001f\u007f]/.test(target))
+        throw new Error("Invalid signature request target");
+    const queryIndex = target.indexOf("?");
+    const path = queryIndex < 0 ? target : target.slice(0, queryIndex);
+    const query = queryIndex < 0 ? "?" : target.slice(queryIndex);
+    const digest = `sha-256=:${base64(sha256(body))}:`;
+    const params = `("@method" "@path" "@query" "content-digest");created=${created};keyid="${bytesToHex(keypair.publicKey)}";alg="ed25519"`;
+    const base = `"@method": ${method}\n"@path": ${path}\n"@query": ${query}\n"content-digest": ${digest}\n"@signature-params": ${params}`;
+    return {
+        "Signature-Input": `monaco=${params}`,
+        Signature: `monaco=:${base64(ed25519.sign(utf8ToBytes(base), keypair.privateKey))}:`,
+        "Content-Digest": digest,
+    };
+}

package/dist/sdk.js

@@ -181,26 +181,30 @@ export class MonacoSDKImpl {
             this.walletClient = cfg.walletClient;
         }
         // Instantiate APIs (wallet-dependent APIs will be initialized lazily or error if wallet not set)
-        this.applications = new ApplicationsAPIImpl(apiUrl);
-        this.market = new MarketAPIImpl(apiUrl);
-        this.marginAccounts = new MarginAccountsAPIImpl(apiUrl);
-        this.positions = new PositionsAPIImpl(apiUrl);
-        this.portfolio = new PortfolioAPIImpl(apiUrl);
-        this.subAccounts = new SubAccountsAPIImpl(apiUrl);
-        this.faucet = new FaucetAPIImpl(apiUrl);
-        this.sweeper = new SweeperAPIImpl(apiUrl);
-        this.whitelist = new WhitelistAPIImpl(apiUrl);
-        this.pulse = new PulseAPIImpl(apiUrl);
-        this.auth = new AuthAPIImpl(this.walletClient, this.chain, apiUrl);
-        this.delegatedAgents = new DelegatedAgentsAPIImpl(apiUrl);
-        this.fees = new FeesAPIImpl(apiUrl);
-        this.pitpass = new PitpassAPIImpl(apiUrl);
-        this.profile = new ProfileAPIImpl(apiUrl);
-        this.vault = new VaultAPIImpl(this.publicClient, this.walletClient, this.chain, this.applications, this.profile, apiUrl);
-        this.withdrawals = new WithdrawalsAPIImpl(apiUrl);
-        this.trading = new TradingAPIImpl(apiUrl);
-        this.orderbook = new OrderbookAPIImpl(apiUrl);
-        this.trades = new TradesAPIImpl(apiUrl);
+        const configureSigning = (api) => {
+            api.setRequestSigning(cfg.requestSigning ?? "legacy");
+            return api;
+        };
+        this.applications = configureSigning(new ApplicationsAPIImpl(apiUrl));
+        this.market = configureSigning(new MarketAPIImpl(apiUrl));
+        this.marginAccounts = configureSigning(new MarginAccountsAPIImpl(apiUrl));
+        this.positions = configureSigning(new PositionsAPIImpl(apiUrl));
+        this.portfolio = configureSigning(new PortfolioAPIImpl(apiUrl));
+        this.subAccounts = configureSigning(new SubAccountsAPIImpl(apiUrl));
+        this.faucet = configureSigning(new FaucetAPIImpl(apiUrl));
+        this.sweeper = configureSigning(new SweeperAPIImpl(apiUrl));
+        this.whitelist = configureSigning(new WhitelistAPIImpl(apiUrl));
+        this.pulse = configureSigning(new PulseAPIImpl(apiUrl));
+        this.auth = configureSigning(new AuthAPIImpl(this.walletClient, this.chain, apiUrl));
+        this.delegatedAgents = configureSigning(new DelegatedAgentsAPIImpl(apiUrl));
+        this.fees = configureSigning(new FeesAPIImpl(apiUrl));
+        this.pitpass = configureSigning(new PitpassAPIImpl(apiUrl));
+        this.profile = configureSigning(new ProfileAPIImpl(apiUrl));
+        this.vault = configureSigning(new VaultAPIImpl(this.publicClient, this.walletClient, this.chain, this.applications, this.profile, apiUrl));
+        this.withdrawals = configureSigning(new WithdrawalsAPIImpl(apiUrl));
+        this.trading = configureSigning(new TradingAPIImpl(apiUrl));
+        this.orderbook = configureSigning(new OrderbookAPIImpl(apiUrl));
+        this.trades = configureSigning(new TradesAPIImpl(apiUrl));
         // Thread the reconnect/resync knobs and callbacks from SDK config into the
         // internally-built ws client. The session keypair is not passed here — it
         // is propagated on login via propagateSession/setSessionKeypair.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/core",
-	"version": "1.0.54",
+	"version": "1.0.56",
 	"type": "module",
 	"homepage": "https://docs.0xmonaco.com/sdk/typescript",
 	"main": "./dist/index.js",
@@ -19,8 +19,8 @@
 		"viem": "^2.45.2"
 	},
 	"dependencies": {
-		"@0xmonaco/contracts": "1.0.54",
-		"@0xmonaco/types": "1.0.54",
+		"@0xmonaco/contracts": "1.0.56",
+		"@0xmonaco/types": "1.0.56",
 		"@noble/curves": "^1.9.1",
 		"@noble/hashes": "^1.8.0",
 		"http-status-codes": "^2.3.0"