@0xmonaco/core 1.0.53 → 1.0.55

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/websocket/websocket.js

@@ -847,10 +847,9 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
                     sendAuthenticate();
                     resubscribeAll();
                     options.onStatusChange?.("connected");
-                    // Resync-join order: resume the live stream first (auth +
-                    // subscribe above), then tell the app to refetch snapshots and
-                    // reconcile by (id, updatedAt) — events racing the snapshot are
-                    // newer than the rows they duplicate.
+                    // 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.
                     if (pendingResyncCode !== null) {
                         const code = pendingResyncCode;
                         pendingResyncCode = null;
@@ -1242,8 +1241,8 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
      * Subscribe to authenticated user's position updates.
      * Requires authentication - user is identified from the signed session-key
      * handshake. Omit `tradingPairId` for all pairs, or pass one to filter.
-     * Lag policy is Conflate: a lagging subscriber is fast-forwarded, no gap
-     * signal.
+     * Detected broadcast lag closes the connection with 1013; reconcile
+     * missed keys and terminal updates on reconnect.
      */
     const subscribePositions = (handler, tradingPairId, onSnapshot) => {
         if (!handler) {
@@ -1290,8 +1289,8 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
      * Subscribe to the authenticated user's account-level margin health updates
      * (equity, collateral, free collateral, margin ratio, maintenance
      * requirement). Requires authentication - the user is identified from the
-     * signed session-key handshake. Lag policy is Conflate: a lagging subscriber
-     * is fast-forwarded, no gap signal. Each frame is a terminal-state snapshot
+     * signed session-key handshake. Detected broadcast lag closes the connection
+     * with 1013; reconnect and reconcile missed state. Each frame is a terminal-state snapshot
      * per margin account, not an additive delta.
      */
     const subscribeAccount = (handler, onSnapshot) => {
@@ -1317,8 +1316,8 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
      * of the current active-pair list arrives before the live diffs; a
      * subscriber joining a channel this client already holds is replayed the
      * current baseline from a local cache instead (the server snapshots only
-     * genuinely new wire subscriptions). Lag policy is Conflate: a lagging
-     * subscriber is fast-forwarded, no gap signal.
+     * genuinely new wire subscriptions). Detected broadcast lag closes the connection
+     * with 1013; a new wire subscription provides a fresh baseline.
      */
     const subscribeInstruments = (handler, tradingPairId, onSnapshot) => {
         if (!handler) {

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.53",
+	"version": "1.0.55",
 	"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.53",
-		"@0xmonaco/types": "1.0.53",
+		"@0xmonaco/contracts": "1.0.55",
+		"@0xmonaco/types": "1.0.55",
 		"@noble/curves": "^1.9.1",
 		"@noble/hashes": "^1.8.0",
 		"http-status-codes": "^2.3.0"