@sentico-labs/sdk 0.1.0-preview.1

package/dist/src/signing.js

@@ -0,0 +1,149 @@
+/**
+ * Local (client-side) canonical encoding and signing-hash computation for
+ * Senticore trading actions.
+ *
+ * This removes the `POST /api/v1/trading/actions/hash` roundtrip from the
+ * order hot path: the canonical bytes and the blake3 signing hash are
+ * computed locally, signed locally, and submitted in a single HTTP call.
+ *
+ * CANONICAL ENCODING RULES (must match `senticore-types` byte-for-byte):
+ * - JSON with NO whitespace.
+ * - Object keys in Rust struct DECLARATION order (NOT alphabetical). The
+ *   `canonicalPayload` echoed by the server /hash endpoint is alphabetically
+ *   sorted for display — hashing that JSON gives a DIFFERENT hash. Always
+ *   hash the declaration-order encoding produced here.
+ * - Field names in snake_case (the internal wire names).
+ * - Optional fields are ALWAYS serialized (as null when absent).
+ * - Account ids are 0x-prefixed lowercase hex (20 bytes), order ids
+ *   0x-prefixed lowercase hex (32 bytes).
+ * - Enums: Side "Bid"/"Ask"; Book "YES"/"NO"; time_in_force / stp_mode /
+ *   trigger_direction / conditional_kind in snake_case.
+ * - The outcome variant is serialized with its INTERNAL tag "PlaceOrder"
+ *   (the public alias "OutcomePlaceOrder" is an input-side name only).
+ * - hash = blake3("SENTICORE/ACTION_PAYLOAD/v1" || canonical_bytes).
+ *
+ * Golden vectors pinning compatibility with the backend live in
+ * `tests/signing.test.ts` and in `senticore-types::tests::signing_hash_golden_vectors`.
+ */
+import { blake3 } from "@noble/hashes/blake3";
+export const ACTION_PAYLOAD_DOMAIN_V1 = "SENTICORE/ACTION_PAYLOAD/v1";
+// -----------------------------
+// Canonical JSON writer
+// -----------------------------
+function writeUint(value, field) {
+    if (typeof value === "bigint") {
+        if (value < 0n)
+            throw new Error(`${field} must be non-negative`);
+        return value.toString(10);
+    }
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`${field} must be a non-negative safe integer (use bigint above 2^53-1)`);
+    }
+    return value.toString(10);
+}
+function writeString(value) {
+    return JSON.stringify(value);
+}
+function writeHexBytes(value, bytes, field) {
+    const normalized = value.toLowerCase();
+    if (!/^0x[0-9a-f]+$/.test(normalized) || normalized.length !== 2 + bytes * 2) {
+        throw new Error(`${field} must be 0x-prefixed hex of ${bytes} bytes`);
+    }
+    return writeString(normalized);
+}
+function writeOptionalUint(value, field) {
+    return value === null || value === undefined ? "null" : writeUint(value, field);
+}
+function writeOptionalString(value) {
+    return value === null || value === undefined ? "null" : writeString(value);
+}
+function writeOrderFlags(flags) {
+    return (`"stp_mode":${writeOptionalString(flags.stpMode)},` +
+        `"time_in_force":${writeOptionalString(flags.timeInForce)},` +
+        `"is_market":${flags.isMarket === true},` +
+        `"reduce_only":${flags.reduceOnly === true},` +
+        `"expires_at":${writeOptionalUint(flags.expiresAt, "expiresAt")}`);
+}
+function writeSpotLegBody(leg, withBook) {
+    const book = withBook
+        ? `"book":${writeString(leg.book)},`
+        : "";
+    const cancel = leg.cancelOrderId === null || leg.cancelOrderId === undefined
+        ? "null"
+        : writeHexBytes(leg.cancelOrderId, 32, "cancelOrderId");
+    return (`{"cancel_order_id":${cancel},` +
+        book +
+        `"side":${writeString(leg.side)},` +
+        `"price":${writeUint(leg.price, "price")},` +
+        `"qty":${writeUint(leg.qty, "qty")},` +
+        writeOrderFlags(leg) +
+        `}`);
+}
+function writeAction(action) {
+    switch (action.kind) {
+        case "SpotPlaceOrder":
+            return (`{"SpotPlaceOrder":{` +
+                `"market":${writeUint(action.market, "market")},` +
+                `"side":${writeString(action.side)},` +
+                `"price":${writeUint(action.price, "price")},` +
+                `"qty":${writeUint(action.qty, "qty")},` +
+                writeOrderFlags(action) +
+                `}}`);
+        case "OutcomePlaceOrder":
+            // Internal canonical tag is PlaceOrder; book comes right after market.
+            return (`{"PlaceOrder":{` +
+                `"market":${writeUint(action.market, "market")},` +
+                `"book":${writeString(action.book)},` +
+                `"side":${writeString(action.side)},` +
+                `"price":${writeUint(action.price, "price")},` +
+                `"qty":${writeUint(action.qty, "qty")},` +
+                writeOrderFlags(action) +
+                `}}`);
+        case "Cancel":
+            return `{"Cancel":{"order_id":${writeHexBytes(action.orderId, 32, "orderId")}}}`;
+        case "AmendOrder":
+            return (`{"AmendOrder":{` +
+                `"order_id":${writeHexBytes(action.orderId, 32, "orderId")},` +
+                `"new_qty":${writeUint(action.newQty, "newQty")}}}`);
+        case "SpotQuoteReplace":
+            return (`{"SpotQuoteReplace":{` +
+                `"market":${writeUint(action.market, "market")},` +
+                `"legs":[${action.legs.map((leg) => writeSpotLegBody(leg, false)).join(",")}]}}`);
+        case "QuoteReplace":
+            return (`{"QuoteReplace":{` +
+                `"market":${writeUint(action.market, "market")},` +
+                `"legs":[${action.legs.map((leg) => writeSpotLegBody(leg, true)).join(",")}]}}`);
+        default: {
+            const exhaustive = action;
+            throw new Error(`unsupported action ${exhaustive.kind}`);
+        }
+    }
+}
+/**
+ * Canonical declaration-order JSON for an action payload — the EXACT bytes
+ * the backend hashes and persists.
+ */
+export function canonicalActionPayloadJson(payload) {
+    return (`{"account":${writeHexBytes(payload.account, 20, "account")},` +
+        `"nonce":${writeUint(payload.nonce, "nonce")},` +
+        `"nonce_reservation_id":${writeOptionalString(payload.nonceReservationId)},` +
+        `"ts":${writeUint(payload.ts, "ts")},` +
+        `"action":${writeAction(payload.action)}}`);
+}
+/** blake3(domain || canonical_bytes) as raw bytes. */
+export function actionSigningHash(payload) {
+    const canonical = new TextEncoder().encode(canonicalActionPayloadJson(payload));
+    const domain = new TextEncoder().encode(ACTION_PAYLOAD_DOMAIN_V1);
+    const joined = new Uint8Array(domain.length + canonical.length);
+    joined.set(domain, 0);
+    joined.set(canonical, domain.length);
+    return blake3(joined);
+}
+/** blake3 signing hash as 0x-prefixed lowercase hex. */
+export function actionSigningHashHex(payload) {
+    const hash = actionSigningHash(payload);
+    let hex = "";
+    for (const byte of hash)
+        hex += byte.toString(16).padStart(2, "0");
+    return `0x${hex}`;
+}

package/dist/src/types.d.ts

@@ -0,0 +1,156 @@
+export type HexAddress = `0x${string}`;
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonRecord = Record<string, JsonValue>;
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export interface SenticoreSdkConfig {
+    publicHttpBaseUrl: string;
+    tradingHttpBaseUrl: string;
+    publicWsUrl: string;
+    privateWsUrl: string;
+    orderEntryHttpBaseUrl?: string;
+    orderEntryBinaryPath?: string;
+    orderEntryApiKey?: string;
+    /** @deprecated Use orderEntryHttpBaseUrl. */
+    mmHttpBaseUrl?: string;
+    /** @deprecated Use orderEntryBinaryPath. */
+    mmBinaryPath?: string;
+    bearerToken?: string;
+    /** @deprecated Use orderEntryApiKey. */
+    mmApiKey?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    retryBackoffMs?: number;
+    userAgent?: string;
+    headers?: Record<string, string>;
+    fetch?: FetchLike;
+    WebSocketCtor?: typeof WebSocket;
+}
+export interface NormalizedSenticoreSdkConfig {
+    publicHttpBaseUrl: string;
+    tradingHttpBaseUrl: string;
+    publicWsUrl: string;
+    privateWsUrl: string;
+    orderEntryHttpBaseUrl: string;
+    orderEntryBinaryPath: string;
+    orderEntryApiKey?: string;
+    mmHttpBaseUrl: string;
+    mmBinaryPath: string;
+    bearerToken?: string;
+    mmApiKey?: string;
+    timeoutMs: number;
+    maxRetries: number;
+    retryBackoffMs: number;
+    userAgent: string;
+    headers: Record<string, string>;
+    fetch: FetchLike;
+    WebSocketCtor?: typeof WebSocket;
+}
+export interface RateLimitInfo {
+    limit?: string;
+    remaining?: string;
+    reset?: string;
+    retryAfter?: string;
+    raw: Record<string, string>;
+}
+export interface ApiResponse<T = unknown> {
+    data: T;
+    status: number;
+    headers: Headers;
+    requestId?: string;
+    rateLimit?: RateLimitInfo;
+}
+export interface RequestOptions {
+    bearerToken?: string;
+    idempotencyKey?: string;
+    headers?: Record<string, string>;
+    retry?: boolean;
+}
+export interface WsSessionTokenResponse {
+    ok: boolean;
+    account: HexAddress;
+    scope: "private_ws:read";
+    tokenType: "Bearer";
+    token: string;
+    issuedAtMs: number;
+    expiresAtMs: number;
+    ttlMs: number;
+    ipBound: boolean;
+    clientId?: string;
+}
+export interface SubscribeRequest {
+    id?: string | number;
+    method: "subscribe" | "unsubscribe";
+    subscription: Record<string, unknown>;
+}
+export interface AuthRequest {
+    id?: string | number;
+    method: "auth";
+    authorization: string;
+}
+export interface SenticoreWsFrame<T = unknown> {
+    type?: string;
+    event?: string;
+    channel?: string;
+    seq?: number | null;
+    prev_seq?: number | null;
+    ts?: number;
+    data?: T;
+    error?: unknown;
+    id?: string | number | null;
+    [key: string]: unknown;
+}
+export interface Signature {
+    scheme: string;
+    bytes: number[] | Uint8Array | string;
+}
+export interface SignedAction {
+    payload: Record<string, unknown>;
+    signature: Signature;
+}
+export interface MmActionBatch {
+    version: 1;
+    actions: SignedAction[];
+    idempotencyKey?: string;
+}
+export interface MmActionBatchResponse {
+    ok: boolean;
+    seqs: number[];
+    derivedOrderIds: Array<string | null>;
+    error: string | null;
+    responseMode?: string;
+    acceptedActions?: number;
+    lastSeq?: number;
+    seqChecksum?: string;
+    ackMode?: string;
+    ackClass?: string;
+    durableLsn?: number;
+    durablePendingSeqs?: number;
+    rateLimit?: Record<string, unknown> | null;
+    signals?: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+export type OrderEntryActionBatch = MmActionBatch;
+export type OrderEntryActionBatchResponse = MmActionBatchResponse;
+export interface PrivateWsTokenOptions {
+    ttlMs?: number;
+    clientId?: string;
+}
+export interface MarketOrderbookOptions {
+    book?: "YES" | "NO";
+    depth?: number;
+}
+export interface MarketTradesOptions {
+    limit?: number;
+}
+export interface MarketCandlesOptions {
+    tf?: "1m" | "5m" | "15m" | "1h" | "4h" | "1d" | "1D" | "1W";
+    beforeTs?: number;
+    countBack?: number;
+}
+export interface NonceReservationOptions extends RequestOptions {
+    count?: number;
+    ttlMs?: number;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/ws.d.ts

@@ -0,0 +1,13 @@
+import type { NormalizedSenticoreSdkConfig, SenticoreSdkConfig, SenticoreWsFrame, SubscribeRequest, WsSessionTokenResponse } from "./types.js";
+export declare class SenticoreWsClient {
+    private readonly config;
+    constructor(config: SenticoreSdkConfig | NormalizedSenticoreSdkConfig);
+    connectPublic(onMessage: (frame: SenticoreWsFrame) => void): WebSocket;
+    connectPrivate(account: string, token: string | WsSessionTokenResponse, onMessage: (frame: SenticoreWsFrame) => void): WebSocket;
+    authenticate(socket: WebSocket, token: string, id?: string | number): void;
+    subscribe(socket: WebSocket, subscription: SubscribeRequest["subscription"], id?: string): void;
+    unsubscribe(socket: WebSocket, subscription: SubscribeRequest["subscription"], id?: string): void;
+    parseFrame(data: string | ArrayBuffer | Blob): SenticoreWsFrame;
+    private connect;
+}
+export declare function isReplayGapFrame(frame: SenticoreWsFrame): boolean;

package/dist/src/ws.js

@@ -0,0 +1,78 @@
+import { normalizeConfig } from "./config.js";
+import { ReplayGapError } from "./errors.js";
+export class SenticoreWsClient {
+    config;
+    constructor(config) {
+        this.config = normalizeConfig(config);
+    }
+    connectPublic(onMessage) {
+        return this.connect(this.config.publicWsUrl, onMessage);
+    }
+    connectPrivate(account, token, onMessage) {
+        const url = this.config.privateWsUrl.replace("{account}", account);
+        const socket = this.connect(url, onMessage);
+        socket.addEventListener("open", () => {
+            this.authenticate(socket, typeof token === "string" ? token : token.token);
+        });
+        return socket;
+    }
+    authenticate(socket, token, id = "auth-1") {
+        const authorization = token.startsWith("Bearer ") ? token : `Bearer ${token}`;
+        const auth = {
+            id,
+            method: "auth",
+            authorization
+        };
+        socket.send(JSON.stringify(auth));
+    }
+    subscribe(socket, subscription, id = "sub-1") {
+        const payload = {
+            id,
+            method: "subscribe",
+            subscription
+        };
+        socket.send(JSON.stringify(payload));
+    }
+    unsubscribe(socket, subscription, id = "unsub-1") {
+        const payload = {
+            id,
+            method: "unsubscribe",
+            subscription
+        };
+        socket.send(JSON.stringify(payload));
+    }
+    parseFrame(data) {
+        if (typeof data !== "string") {
+            throw new Error("Senticore WebSocket binary frames are not supported by parseFrame");
+        }
+        const frame = JSON.parse(data);
+        if (isReplayGapFrame(frame)) {
+            throw new ReplayGapError("Senticore WebSocket replay gap", frame);
+        }
+        return frame;
+    }
+    connect(url, onMessage) {
+        const WebSocketCtor = this.config.WebSocketCtor;
+        if (!WebSocketCtor) {
+            throw new Error("Senticore SDK requires WebSocket or config.WebSocketCtor");
+        }
+        const socket = new WebSocketCtor(url);
+        socket.addEventListener("message", (event) => {
+            onMessage(this.parseFrame(event.data));
+        });
+        return socket;
+    }
+}
+export function isReplayGapFrame(frame) {
+    const type = String(frame.type ?? frame.event ?? "").toLowerCase();
+    if (type.includes("gap"))
+        return true;
+    if (typeof frame.error === "string")
+        return frame.error.toLowerCase().includes("gap");
+    if (frame.error && typeof frame.error === "object") {
+        const record = frame.error;
+        return String(record.code ?? "").toLowerCase().includes("gap") ||
+            String(record.message ?? "").toLowerCase().includes("gap");
+    }
+    return false;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@sentico-labs/sdk",
+  "version": "0.1.0-preview.1",
+  "private": false,
+  "description": "Institutional TypeScript SDK for Senticore HTTP, WebSocket, and Order Entry.",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "dist/examples",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test dist/tests",
+    "prepack": "npm run build",
+    "pack:check": "npm pack --dry-run",
+    "verify": "npm run check && npm run test && npm run pack:check",
+    "verify:ci": "npm run verify"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.6.3"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.8.0"
+  }
+}