@n1xyz/nord-ts 0.3.5 → 0.3.6

package/README.md

@@ -110,6 +110,27 @@ try {
 }
 ```
 
+### Quote-Sized Orders
+
+For orders limited by quote amount (e.g., USD value), pass a single decimal value:
+
+```typescript
+// Place a market/limit order capped by quote value
+await user.placeOrder({
+  marketId: 0,
+  side: Side.Bid,
+  fillMode: FillMode.Limit,
+  isReduceOnly: false,
+  // Limit by quote: $100 at $50,000 results in ~0.002 BTC
+  quoteSize: 100,
+});
+```
+
+Notes:
+- `quoteSize` is a positive decimal representing the desired quote amount.
+- The wire format encodes quote amount as a 128-bit value scaled by `price_decimals + size_decimals` of the target market.
+- At least one limit must be provided among `size`, `price`, or `quoteSize`.
+
 ### Deposits and Withdrawals
 
 ```typescript

package/dist/actions.d.ts

@@ -2,7 +2,7 @@ import Decimal from "decimal.js";
 import * as proto from "./gen/nord_pb";
 import { paths } from "./gen/openapi";
 import { Client } from "openapi-fetch";
-import { FillMode, Side, QuoteSize } from "./types";
+import { FillMode, Side } from "./types";
 import { BigIntValue } from "./utils";
 import { PublicKey, Transaction } from "@solana/web3.js";
 type ReceiptKind = NonNullable<proto.Receipt["kind"]>;
@@ -41,7 +41,7 @@ export type AtomicSubaction = {
     priceDecimals: number;
     size?: Decimal.Value;
     price?: Decimal.Value;
-    quoteSize?: QuoteSize;
+    quoteSize?: Decimal.Value;
     clientOrderId?: BigIntValue;
 } | {
     kind: "cancel";

package/dist/actions.js

@@ -0,0 +1,184 @@
+import * as proto from "./gen/nord_pb";
+import { create } from "@bufbuild/protobuf";
+import { fillModeToProtoFillMode, Side } from "./types";
+import { assert, decodeLengthDelimited, SESSION_TTL, toScaledU64, signUserPayload, } from "./utils";
+import { sizeDelimitedEncode } from "@bufbuild/protobuf/wire";
+import { NordError } from "./error";
+export function formatReceiptError(receipt) {
+    if (receipt.kind?.case === "err") {
+        const err = receipt.kind.value;
+        return proto.Error[err] ?? err.toString();
+    }
+    return receipt.kind?.case ?? "unknown";
+}
+export function expectReceiptKind(receipt, expected, action) {
+    if (receipt.kind?.case !== expected) {
+        const label = formatReceiptError(receipt);
+        throw new NordError(`Failed to ${action}: ${label}`);
+    }
+}
+async function sessionSign(signFn, message) {
+    const signature = await signFn(message);
+    return new Uint8Array([...message, ...signature]);
+}
+// Helper to create an action with common fields
+export function createAction(currentTimestamp, nonce, kind) {
+    return create(proto.ActionSchema, {
+        currentTimestamp,
+        nonce,
+        kind,
+    });
+}
+export async function sendAction(client, makeSignedMessage, action) {
+    const body = await prepareAction(action, makeSignedMessage);
+    const response = await client.POST("/action", {
+        params: {
+            header: {
+                "content-type": "application/octet-stream",
+            },
+        },
+        body: body,
+        // NOTE: openapi-fetch ignores headers and types/const headers in schema, and always assume all things are JSON
+        // to handle multi type bodies, need these overrides and later adhoc parsing
+        bodySerializer: (body) => body,
+        parseAs: "stream",
+    });
+    if (response.error) {
+        throw new Error(`Failed to ${action.kind.case}, HTTP status ${JSON.stringify(response.error)}`);
+    }
+    const rawResp = new Uint8Array(await response.response.arrayBuffer());
+    const resp = decodeLengthDelimited(rawResp, proto.ReceiptSchema);
+    if (resp.kind?.case === "err") {
+        throw new Error(`Could not execute ${action.kind.case}, reason: ${proto.Error[resp.kind.value]}`);
+    }
+    return resp;
+}
+// Given action and signature function, prepare the signed message to send to server as `body`.
+// `makeSignedMessage` must include the original message and signature.
+export async function prepareAction(action, makeSignedMessage) {
+    const encoded = sizeDelimitedEncode(proto.ActionSchema, action);
+    // NOTE(agent): keep in sync with MAX_ENCODED_ACTION_SIZE in Rust code
+    const MAX_ENCODED_ACTION_SIZE = 1024;
+    if (encoded.byteLength > MAX_ENCODED_ACTION_SIZE) {
+        console.warn("Encoded message:", encoded);
+        throw new Error(`Encoded message size (${encoded.byteLength} bytes) is greater than max payload size (${MAX_ENCODED_ACTION_SIZE} bytes).`);
+    }
+    const body = await makeSignedMessage(encoded);
+    if (body.byteLength > MAX_ENCODED_ACTION_SIZE) {
+        console.warn("Encoded length:", encoded.byteLength);
+        throw new Error(`Signed message size (${body.byteLength} bytes) is greater than max payload size (${MAX_ENCODED_ACTION_SIZE} bytes).`);
+    }
+    return body;
+}
+export async function createSession(client, signMessage, currentTimestamp, nonce, params) {
+    let expiry = 0n;
+    if (params.expiryTimestamp !== undefined) {
+        expiry = params.expiryTimestamp;
+        assert(expiry > currentTimestamp, "Cannot set expiry timestamp in the past");
+    }
+    else {
+        expiry = currentTimestamp + SESSION_TTL;
+    }
+    const action = createAction(currentTimestamp, nonce, {
+        case: "createSession",
+        value: create(proto.Action_CreateSessionSchema, {
+            userPubkey: params.userPubkey.toBytes(),
+            blstPubkey: params.sessionPubkey.toBytes(),
+            expiryTimestamp: expiry,
+        }),
+    });
+    const resp = await sendAction(client, async (payload) => {
+        return new Uint8Array([
+            ...payload,
+            ...(await signUserPayload({
+                payload,
+                signMessage,
+            })),
+        ]);
+    }, action);
+    if (resp.kind?.case === "createSessionResult") {
+        return {
+            actionId: resp.actionId,
+            sessionId: resp.kind.value.sessionId,
+        };
+    }
+    else {
+        throw new Error(`Unexpected receipt kind ${resp.kind?.case}`);
+    }
+}
+export async function revokeSession(client, signMessage, currentTimestamp, nonce, params) {
+    const action = createAction(currentTimestamp, nonce, {
+        case: "revokeSession",
+        value: create(proto.Action_RevokeSessionSchema, {
+            sessionId: BigInt(params.sessionId),
+        }),
+    });
+    const resp = await sendAction(client, async (payload) => {
+        return new Uint8Array([
+            ...payload,
+            ...(await signUserPayload({
+                payload,
+                signMessage,
+            })),
+        ]);
+    }, action);
+    return { actionId: resp.actionId };
+}
+export async function atomic(client, signFn, currentTimestamp, nonce, params) {
+    assert(params.actions.length > 0 && params.actions.length <= 4, "Atomic action must contain between 1 and 4 sub-actions");
+    const subactions = params.actions.map((a) => {
+        if (a.kind === "place") {
+            const price = toScaledU64(a.price ?? 0, a.priceDecimals);
+            const size = toScaledU64(a.size ?? 0, a.sizeDecimals);
+            const scaledQuote = a.quoteSize
+                ? a.quoteSize.toWire(a.priceDecimals, a.sizeDecimals)
+                : undefined;
+            // Require at least one limit to be set (non-zero size, non-zero price, or quoteSize)
+            assert(price > 0n || size > 0n || scaledQuote !== undefined, "OrderLimit must include at least one of: size, price, or quoteSize");
+            const tradeOrPlace = create(proto.TradeOrPlaceSchema, {
+                marketId: a.marketId,
+                orderType: create(proto.OrderTypeSchema, {
+                    side: a.side === Side.Bid ? proto.Side.BID : proto.Side.ASK,
+                    fillMode: fillModeToProtoFillMode(a.fillMode),
+                    isReduceOnly: a.isReduceOnly,
+                }),
+                limit: create(proto.OrderLimitSchema, {
+                    price,
+                    size,
+                    quoteSize: scaledQuote === undefined
+                        ? undefined
+                        : create(proto.QuoteSizeSchema, {
+                            size: scaledQuote.size,
+                            price: scaledQuote.price,
+                        }),
+                }),
+                clientOrderId: a.clientOrderId === undefined ? undefined : BigInt(a.clientOrderId),
+            });
+            return create(proto.AtomicSubactionKindSchema, {
+                inner: { case: "tradeOrPlace", value: tradeOrPlace },
+            });
+        }
+        return create(proto.AtomicSubactionKindSchema, {
+            inner: {
+                case: "cancelOrder",
+                value: create(proto.CancelOrderSchema, { orderId: BigInt(a.orderId) }),
+            },
+        });
+    });
+    const action = createAction(currentTimestamp, nonce, {
+        case: "atomic",
+        value: create(proto.AtomicSchema, {
+            sessionId: BigInt(params.sessionId),
+            accountId: params.accountId, // optional
+            actions: subactions,
+        }),
+    });
+    const resp = await sendAction(client, (m) => sessionSign(signFn, m), action);
+    if (resp.kind?.case === "atomic") {
+        return {
+            actionId: resp.actionId,
+            results: resp.kind.value.results,
+        };
+    }
+    throw new Error(`Unexpected receipt kind ${resp.kind?.case}`);
+}