@n1xyz/nord-ts 0.1.4 → 0.1.5

package/dist/nord/client/NordAdmin.d.ts

@@ -1,14 +1,20 @@
+import { PublicKey } from "@solana/web3.js";
 import * as proto from "../../gen/nord_pb";
-import { NordClient } from "./NordClient";
-import type { NordClientParams } from "./NordClient";
-import type { NordUser } from "./NordUser";
+import { Nord } from "./Nord";
+import { FeeTierConfig } from "../../gen/nord_pb";
+/**
+ * Parameters required to register a new token via the admin API.
+ */
 export interface CreateTokenParams {
     tokenDecimals: number;
     weightBps: number;
     viewSymbol: string;
     oracleSymbol: string;
-    solAddr: Uint8Array;
+    mintAddr: PublicKey;
 }
+/**
+ * Parameters used when creating a new market.
+ */
 export interface CreateMarketParams {
     sizeDecimals: number;
     priceDecimals: number;
@@ -20,51 +26,211 @@ export interface CreateMarketParams {
     oracleSymbol: string;
     baseTokenId: number;
 }
+/**
+ * Configuration for updating the Wormhole guardian set on the oracle.
+ */
 export interface PythSetWormholeGuardiansParams {
     guardianSetIndex: number;
-    addresses: Uint8Array[];
+    addresses: string[];
 }
+/**
+ * Parameters required to link an oracle symbol to a Pyth price feed.
+ */
 export interface PythSetSymbolFeedParams {
     oracleSymbol: string;
-    priceFeedId: Uint8Array;
+    priceFeedId: string;
 }
+/**
+ * Identifies a market that should be frozen.
+ */
 export interface FreezeMarketParams {
     marketId: number;
 }
+/**
+ * Identifies a market that should be unfrozen.
+ */
 export interface UnfreezeMarketParams {
     marketId: number;
 }
-export interface NordAdminParams extends NordClientParams {
-    signFn: (message: Uint8Array) => Promise<Uint8Array>;
+/**
+ * Parameters for adding a new fee tier.
+ */
+export interface AddFeeTierParams {
+    config: FeeTierConfig;
 }
-export declare class NordAdmin extends NordClient {
+/**
+ * Parameters for updating an existing fee tier.
+ */
+export interface UpdateFeeTierParams {
+    tierId: number;
+    config: FeeTierConfig;
+}
+/**
+ * Administrative client capable of submitting privileged configuration actions.
+ */
+export declare class NordAdmin {
+    private readonly nord;
     private readonly signFn;
-    constructor(params: NordAdminParams);
-    clone(): NordAdmin;
-    static fromUser(user: NordUser, adminSignFn: (message: Uint8Array) => Promise<Uint8Array>): NordAdmin;
+    private constructor();
+    /** Create a new admin client.
+     *
+     * @param nord - Nord instance
+     * @param signFn - Function to sign messages with the admin's wallet.
+     *
+     * `signFn` must sign the _hex-encoded_ message, not the raw message itself, for
+     * the purpose of being compatible with Solana wallets.
+     *
+     * In practice, you will do something along the lines of:
+     *
+     * ```typescript
+     * (x) => wallet.signMessage(new TextEncoder().encode(x.toHex()));
+     * ```
+     *
+     * For a software signing key, this might look more like:
+     *
+     * ```typescript
+     * (x) => nacl.sign.detached(new TextEncoder().encode(x.toHex()), sk);
+     * ``
+     *
+     * where `nacl` is the tweetnacl library.
+     */
+    static new({ nord, signFn, }: Readonly<{
+        nord: Nord;
+        signFn: (m: Uint8Array) => Promise<Uint8Array>;
+    }>): NordAdmin;
+    /**
+     * Submit an action and append the admin signature before sending it to Nord.
+     *
+     * @param kind - Action payload describing the admin request
+     * @throws {NordError} If signing or submission fails
+     */
     private submitAction;
-    createToken(params: CreateTokenParams): Promise<{
+    /**
+     * Register a new token that can be listed on Nord.
+     *
+     * @param params - Token configuration values
+     * @returns Action identifier and resulting token metadata
+     * @throws {NordError} If the action submission fails
+     */
+    createToken({ tokenDecimals, weightBps, viewSymbol, oracleSymbol, mintAddr, }: CreateTokenParams): Promise<{
         actionId: bigint;
     } & proto.Receipt_InsertTokenResult>;
+    /**
+     * Open a new market with the provided trading parameters.
+     *
+     * @param params - Market configuration to apply
+     * @returns Action identifier and resulting market metadata
+     * @throws {NordError} If the action submission fails
+     */
     createMarket(params: CreateMarketParams): Promise<{
         actionId: bigint;
     } & proto.Receipt_InsertMarketResult>;
+    /**
+     * Update the Pyth guardian set used for verifying Wormhole messages.
+     *
+     * Each address must decode from a 20-byte hex string (with or without a
+     * leading `0x` prefix). The engine validates the supplied guardian set index
+     * before applying the update.
+     *
+     * @param params - Guardian set index and guardian addresses
+     * @returns Action identifier and guardian update receipt
+     * @throws {NordError} If the action submission fails
+     */
     pythSetWormholeGuardians(params: PythSetWormholeGuardiansParams): Promise<{
         actionId: bigint;
     } & proto.Receipt_UpdateGuardianSetResult>;
+    /**
+     * Link an oracle symbol to a specific Pyth price feed.
+     *
+     * The price feed identifier must decode to 32 bytes (with or without a
+     * leading `0x` prefix). Use this call to create or update the mapping used
+     * by the oracle integration.
+     *
+     * @param params - Oracle symbol and price feed identifier
+     * @returns Action identifier and symbol feed receipt
+     * @throws {NordError} If the action submission fails
+     */
     pythSetSymbolFeed(params: PythSetSymbolFeedParams): Promise<{
         actionId: bigint;
     } & proto.Receipt_OracleSymbolFeedResult>;
+    /**
+     * Pause all trading activity on the exchange.
+     *
+     * @returns Action identifier confirming the pause
+     * @throws {NordError} If the action submission fails
+     */
     pause(): Promise<{
         actionId: bigint;
     }>;
+    /**
+     * Resume trading activity after a pause.
+     *
+     * @returns Action identifier confirming the unpause
+     * @throws {NordError} If the action submission fails
+     */
     unpause(): Promise<{
         actionId: bigint;
     }>;
+    /**
+     * Freeze an individual market, preventing new trades and orders.
+     *
+     * @param params - Target market identifier
+     * @returns Action identifier and freeze receipt
+     * @throws {NordError} If the action submission fails
+     */
     freezeMarket(params: FreezeMarketParams): Promise<{
         actionId: bigint;
     } & proto.Receipt_MarketFreezeUpdated>;
+    /**
+     * Unfreeze a market that was previously halted.
+     *
+     * @param params - Target market identifier
+     * @returns Action identifier and freeze receipt
+     * @throws {NordError} If the action submission fails
+     */
     unfreezeMarket(params: UnfreezeMarketParams): Promise<{
         actionId: bigint;
     } & proto.Receipt_MarketFreezeUpdated>;
+    /**
+     * Append a new fee tier to the account bracket configuration.
+     *
+     * - The engine supports at most 16 tiers (ids 0–15). Tier 0 is reserved for
+     *   the default Nord fees; use `updateFeeTier` if you need to change it.
+     * - The first appended tier receives id 1, and subsequent tiers increment the id.
+     *
+     * @param params - Fee tier configuration to insert
+     * @returns Action identifier and fee tier addition receipt
+     * @throws {NordError} If the action submission fails or the new tier exceeds the maximum range (0-15).
+     */
+    addFeeTier(params: AddFeeTierParams): Promise<{
+        actionId: bigint;
+    } & proto.Receipt_FeeTierAdded>;
+    /**
+     * Update an existing fee tier with new maker/taker rates.
+     *
+     * Tier identifiers must already exist; attempting to update a missing tier
+     * causes the action to fail.
+     *
+     * @param params - Fee tier identifier and updated configuration
+     * @returns Action identifier and fee tier update receipt
+     * @throws {NordError} If the action submission fails or the tier ID exceeds the configured range.
+     */
+    updateFeeTier(params: UpdateFeeTierParams): Promise<{
+        actionId: bigint;
+    } & proto.Receipt_FeeTierUpdated>;
+    /**
+     * Assign a fee tier to one or more accounts.
+     *
+     * The tier id must be within the configured range (0–15). Every account starts
+     * on tier 0; assigning it to another tier requires that tier to exist already.
+     * Invalid account ids or tier ids cause the action to fail.
+     *
+     * @param accounts - Account IDs to update
+     * @param tierId - Target fee tier identifier
+     * @returns Action identifier and accounts-tier receipt
+     * @throws {NordError} If the tier id exceeds the configured range or an account id is invalid.
+     */
+    updateAccountsTier(accounts: number[], tierId: number): Promise<{
+        actionId: bigint;
+    } & proto.Receipt_AccountsTierUpdated>;
 }

package/dist/nord/client/NordAdmin.js

@@ -34,79 +34,92 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NordAdmin = void 0;
-const proto = __importStar(require("../../gen/nord_pb"));
 const protobuf_1 = require("@bufbuild/protobuf");
+const proto = __importStar(require("../../gen/nord_pb"));
 const utils_1 = require("../../utils");
-const types_1 = require("../../types");
+const actions_1 = require("../api/actions");
 const NordError_1 = require("../utils/NordError");
-const NordClient_1 = require("./NordClient");
-class NordAdmin extends NordClient_1.NordClient {
-    constructor(params) {
-        const { signFn: adminSignFn, ...clientParams } = params;
-        super(clientParams);
-        this.signFn = adminSignFn;
-    }
-    clone() {
-        const copy = new NordAdmin({
-            nord: this.nord,
-            address: this.address,
-            walletSignFn: this.walletSignFn,
-            sessionSignFn: this.sessionSignFn,
-            transactionSignFn: this.transactionSignFn,
-            connection: this.connection,
-            sessionId: this.sessionId,
-            sessionPubKey: new Uint8Array(this.sessionPubKey),
-            publicKey: this.publicKey,
-            signFn: this.signFn,
-        });
-        this.cloneClientState(copy);
-        return copy;
+/**
+ * Administrative client capable of submitting privileged configuration actions.
+ */
+class NordAdmin {
+    constructor({ nord, signFn, }) {
+        this.nord = nord;
+        this.signFn = signFn;
     }
-    static fromUser(user, adminSignFn) {
+    /** Create a new admin client.
+     *
+     * @param nord - Nord instance
+     * @param signFn - Function to sign messages with the admin's wallet.
+     *
+     * `signFn` must sign the _hex-encoded_ message, not the raw message itself, for
+     * the purpose of being compatible with Solana wallets.
+     *
+     * In practice, you will do something along the lines of:
+     *
+     * ```typescript
+     * (x) => wallet.signMessage(new TextEncoder().encode(x.toHex()));
+     * ```
+     *
+     * For a software signing key, this might look more like:
+     *
+     * ```typescript
+     * (x) => nacl.sign.detached(new TextEncoder().encode(x.toHex()), sk);
+     * ``
+     *
+     * where `nacl` is the tweetnacl library.
+     */
+    static new({ nord, signFn, }) {
         return new NordAdmin({
-            nord: user.nord,
-            address: user.address,
-            walletSignFn: user.walletSignFn,
-            sessionSignFn: user.sessionSignFn,
-            transactionSignFn: user.transactionSignFn,
-            connection: user.connection,
-            sessionId: user.sessionId,
-            sessionPubKey: new Uint8Array(user.sessionPubKey),
-            publicKey: user.publicKey,
-            signFn: adminSignFn,
+            nord,
+            signFn,
         });
     }
+    /**
+     * Submit an action and append the admin signature before sending it to Nord.
+     *
+     * @param kind - Action payload describing the admin request
+     * @throws {NordError} If signing or submission fails
+     */
     async submitAction(kind) {
-        try {
-            return await this.submitSignedAction(kind, async (message) => {
-                const signature = await this.signFn(message);
-                const signed = new Uint8Array(message.length + signature.length);
-                signed.set(message);
-                signed.set(signature, message.length);
-                return signed;
-            });
-        }
-        catch (error) {
-            throw new NordError_1.NordError(`Admin action ${kind.case} failed`, {
-                cause: error,
-            });
-        }
+        const timestamp = await this.nord.getTimestamp();
+        const action = (0, actions_1.createAction)(timestamp, 0, kind);
+        return (0, actions_1.sendAction)(this.nord.webServerUrl, async (xs) => {
+            const signature = await this.signFn(xs);
+            if (signature.length !== 64) {
+                throw new NordError_1.NordError("invalid signature length; must be 64 bytes");
+            }
+            return Uint8Array.from([...xs, ...signature]);
+        }, action);
     }
-    async createToken(params) {
-        (0, utils_1.checkPubKeyLength)(types_1.KeyType.Ed25519, params.solAddr.length);
+    /**
+     * Register a new token that can be listed on Nord.
+     *
+     * @param params - Token configuration values
+     * @returns Action identifier and resulting token metadata
+     * @throws {NordError} If the action submission fails
+     */
+    async createToken({ tokenDecimals, weightBps, viewSymbol, oracleSymbol, mintAddr, }) {
         const receipt = await this.submitAction({
             case: "createToken",
             value: (0, protobuf_1.create)(proto.Action_CreateTokenSchema, {
-                tokenDecimals: params.tokenDecimals,
-                weightBps: params.weightBps,
-                viewSymbol: params.viewSymbol,
-                oracleSymbol: params.oracleSymbol,
-                solAddr: params.solAddr,
+                tokenDecimals,
+                weightBps,
+                viewSymbol,
+                oracleSymbol,
+                solAddr: mintAddr.toBytes(),
             }),
         });
-        this.expectReceiptKind(receipt, "insertTokenResult", "create token");
+        (0, actions_1.expectReceiptKind)(receipt, "insertTokenResult", "create token");
         return { actionId: receipt.actionId, ...receipt.kind.value };
     }
+    /**
+     * Open a new market with the provided trading parameters.
+     *
+     * @param params - Market configuration to apply
+     * @returns Action identifier and resulting market metadata
+     * @throws {NordError} If the action submission fails
+     */
     async createMarket(params) {
         const receipt = await this.submitAction({
             case: "createMarket",
@@ -122,47 +135,112 @@ class NordAdmin extends NordClient_1.NordClient {
                 baseTokenId: params.baseTokenId,
             }),
         });
-        this.expectReceiptKind(receipt, "insertMarketResult", "create market");
+        (0, actions_1.expectReceiptKind)(receipt, "insertMarketResult", "create market");
         return { actionId: receipt.actionId, ...receipt.kind.value };
     }
+    /**
+     * Update the Pyth guardian set used for verifying Wormhole messages.
+     *
+     * Each address must decode from a 20-byte hex string (with or without a
+     * leading `0x` prefix). The engine validates the supplied guardian set index
+     * before applying the update.
+     *
+     * @param params - Guardian set index and guardian addresses
+     * @returns Action identifier and guardian update receipt
+     * @throws {NordError} If the action submission fails
+     */
     async pythSetWormholeGuardians(params) {
+        const addresses = params.addresses.map((address) => {
+            try {
+                const decoded = (0, utils_1.decodeHex)(address);
+                if (decoded.length !== 20) {
+                    throw new Error("guardian address must be 20 bytes");
+                }
+                return decoded;
+            }
+            catch (e) {
+                throw new NordError_1.NordError("invalid guardian address; must be a 20 byte hex address", { cause: e });
+            }
+        });
         const receipt = await this.submitAction({
             case: "pythSetWormholeGuardians",
             value: (0, protobuf_1.create)(proto.Action_PythSetWormholeGuardiansSchema, {
                 guardianSetIndex: params.guardianSetIndex,
-                addresses: params.addresses,
+                addresses,
             }),
         });
-        this.expectReceiptKind(receipt, "updateGuardianSetResult", "update wormhole guardians");
+        (0, actions_1.expectReceiptKind)(receipt, "updateGuardianSetResult", "update wormhole guardians");
         return { actionId: receipt.actionId, ...receipt.kind.value };
     }
+    /**
+     * Link an oracle symbol to a specific Pyth price feed.
+     *
+     * The price feed identifier must decode to 32 bytes (with or without a
+     * leading `0x` prefix). Use this call to create or update the mapping used
+     * by the oracle integration.
+     *
+     * @param params - Oracle symbol and price feed identifier
+     * @returns Action identifier and symbol feed receipt
+     * @throws {NordError} If the action submission fails
+     */
     async pythSetSymbolFeed(params) {
+        let priceFeedId;
+        try {
+            priceFeedId = (0, utils_1.decodeHex)(params.priceFeedId);
+            if (priceFeedId.length !== 32) {
+                throw new Error("price feed id must be 32 bytes");
+            }
+        }
+        catch (e) {
+            throw new NordError_1.NordError("invalid price feed id; must be a 32 byte hex id", {
+                cause: e,
+            });
+        }
         const receipt = await this.submitAction({
             case: "pythSetSymbolFeed",
             value: (0, protobuf_1.create)(proto.Action_PythSetSymbolFeedSchema, {
                 oracleSymbol: params.oracleSymbol,
-                priceFeedId: params.priceFeedId,
+                priceFeedId,
             }),
         });
-        this.expectReceiptKind(receipt, "oracleSymbolFeedResult", "set symbol feed");
+        (0, actions_1.expectReceiptKind)(receipt, "oracleSymbolFeedResult", "set symbol feed");
         return { actionId: receipt.actionId, ...receipt.kind.value };
     }
+    /**
+     * Pause all trading activity on the exchange.
+     *
+     * @returns Action identifier confirming the pause
+     * @throws {NordError} If the action submission fails
+     */
     async pause() {
         const receipt = await this.submitAction({
             case: "pause",
             value: (0, protobuf_1.create)(proto.Action_PauseSchema, {}),
         });
-        this.expectReceiptKind(receipt, "paused", "pause");
+        (0, actions_1.expectReceiptKind)(receipt, "paused", "pause");
         return { actionId: receipt.actionId };
     }
+    /**
+     * Resume trading activity after a pause.
+     *
+     * @returns Action identifier confirming the unpause
+     * @throws {NordError} If the action submission fails
+     */
     async unpause() {
         const receipt = await this.submitAction({
             case: "unpause",
             value: (0, protobuf_1.create)(proto.Action_UnpauseSchema, {}),
         });
-        this.expectReceiptKind(receipt, "unpaused", "unpause");
+        (0, actions_1.expectReceiptKind)(receipt, "unpaused", "unpause");
         return { actionId: receipt.actionId };
     }
+    /**
+     * Freeze an individual market, preventing new trades and orders.
+     *
+     * @param params - Target market identifier
+     * @returns Action identifier and freeze receipt
+     * @throws {NordError} If the action submission fails
+     */
     async freezeMarket(params) {
         const receipt = await this.submitAction({
             case: "freezeMarket",
@@ -170,9 +248,16 @@ class NordAdmin extends NordClient_1.NordClient {
                 marketId: params.marketId,
             }),
         });
-        this.expectReceiptKind(receipt, "marketFreezeUpdated", "freeze market");
+        (0, actions_1.expectReceiptKind)(receipt, "marketFreezeUpdated", "freeze market");
         return { actionId: receipt.actionId, ...receipt.kind.value };
     }
+    /**
+     * Unfreeze a market that was previously halted.
+     *
+     * @param params - Target market identifier
+     * @returns Action identifier and freeze receipt
+     * @throws {NordError} If the action submission fails
+     */
     async unfreezeMarket(params) {
         const receipt = await this.submitAction({
             case: "unfreezeMarket",
@@ -180,7 +265,72 @@ class NordAdmin extends NordClient_1.NordClient {
                 marketId: params.marketId,
             }),
         });
-        this.expectReceiptKind(receipt, "marketFreezeUpdated", "unfreeze market");
+        (0, actions_1.expectReceiptKind)(receipt, "marketFreezeUpdated", "unfreeze market");
+        return { actionId: receipt.actionId, ...receipt.kind.value };
+    }
+    /**
+     * Append a new fee tier to the account bracket configuration.
+     *
+     * - The engine supports at most 16 tiers (ids 0–15). Tier 0 is reserved for
+     *   the default Nord fees; use `updateFeeTier` if you need to change it.
+     * - The first appended tier receives id 1, and subsequent tiers increment the id.
+     *
+     * @param params - Fee tier configuration to insert
+     * @returns Action identifier and fee tier addition receipt
+     * @throws {NordError} If the action submission fails or the new tier exceeds the maximum range (0-15).
+     */
+    async addFeeTier(params) {
+        const receipt = await this.submitAction({
+            case: "addFeeTier",
+            value: (0, protobuf_1.create)(proto.Action_AddFeeTierSchema, {
+                config: (0, protobuf_1.create)(proto.FeeTierConfigSchema, params.config),
+            }),
+        });
+        (0, actions_1.expectReceiptKind)(receipt, "feeTierAdded", "add fee tier");
+        return { actionId: receipt.actionId, ...receipt.kind.value };
+    }
+    /**
+     * Update an existing fee tier with new maker/taker rates.
+     *
+     * Tier identifiers must already exist; attempting to update a missing tier
+     * causes the action to fail.
+     *
+     * @param params - Fee tier identifier and updated configuration
+     * @returns Action identifier and fee tier update receipt
+     * @throws {NordError} If the action submission fails or the tier ID exceeds the configured range.
+     */
+    async updateFeeTier(params) {
+        const receipt = await this.submitAction({
+            case: "updateFeeTier",
+            value: (0, protobuf_1.create)(proto.Action_UpdateFeeTierSchema, {
+                id: params.tierId,
+                config: (0, protobuf_1.create)(proto.FeeTierConfigSchema, params.config),
+            }),
+        });
+        (0, actions_1.expectReceiptKind)(receipt, "feeTierUpdated", "update fee tier");
+        return { actionId: receipt.actionId, ...receipt.kind.value };
+    }
+    /**
+     * Assign a fee tier to one or more accounts.
+     *
+     * The tier id must be within the configured range (0–15). Every account starts
+     * on tier 0; assigning it to another tier requires that tier to exist already.
+     * Invalid account ids or tier ids cause the action to fail.
+     *
+     * @param accounts - Account IDs to update
+     * @param tierId - Target fee tier identifier
+     * @returns Action identifier and accounts-tier receipt
+     * @throws {NordError} If the tier id exceeds the configured range or an account id is invalid.
+     */
+    async updateAccountsTier(accounts, tierId) {
+        const receipt = await this.submitAction({
+            case: "updateAccountsTier",
+            value: (0, protobuf_1.create)(proto.Action_UpdateAccountsTierSchema, {
+                accounts,
+                tierId,
+            }),
+        });
+        (0, actions_1.expectReceiptKind)(receipt, "accountsTierUpdated", "update accounts tier");
         return { actionId: receipt.actionId, ...receipt.kind.value };
     }
 }

package/dist/nord/client/NordClient.d.ts

@@ -2,10 +2,6 @@ import { Connection, PublicKey } from "@solana/web3.js";
 import type { Transaction } from "@solana/web3.js";
 import * as proto from "../../gen/nord_pb";
 import { Nord } from "./Nord";
-type ReceiptKind = NonNullable<proto.Receipt["kind"]>;
-type ExtractReceiptKind<K extends ReceiptKind["case"]> = Extract<ReceiptKind, {
-    case: K;
-}>;
 export interface NordClientParams {
     nord: Nord;
     address: PublicKey;
@@ -34,9 +30,4 @@ export declare abstract class NordClient {
     protected nextActionNonce(): number;
     protected cloneClientState(target: NordClient): void;
     getSolanaPublicKey(): PublicKey;
-    protected expectReceiptKind<K extends ReceiptKind["case"]>(receipt: proto.Receipt, expected: K, action: string): asserts receipt is proto.Receipt & {
-        kind: ExtractReceiptKind<K>;
-    };
-    protected formatReceiptError(receipt: proto.Receipt): string;
 }
-export {};