@n1xyz/nord-ts 0.1.4 → 0.1.6

package/src/nord/client/NordAdmin.ts

@@ -1,20 +1,35 @@
-import * as proto from "../../gen/nord_pb";
 import { create } from "@bufbuild/protobuf";
-import { checkPubKeyLength } from "../../utils";
-import { KeyType } from "../../types";
+import { PublicKey } from "@solana/web3.js";
+import * as proto from "../../gen/nord_pb";
+import { decodeHex } from "../../utils";
+import { createAction, sendAction, expectReceiptKind } from "../api/actions";
 import { NordError } from "../utils/NordError";
-import { NordClient } from "./NordClient";
-import type { NordClientParams } from "./NordClient";
-import type { NordUser } from "./NordUser";
+import { Nord } from "./Nord";
+import { FeeTierConfig } from "../../gen/nord_pb";
+
+// NOTE: keep in sync with `acl.rs`.
+// NOTE: don't forget `number` as int is internally a u32.
+export enum AclRole {
+  FEE_MANAGER = 1 << 0,
+  MARKET_MANAGER = 1 << 1,
+  // TODO: unsure about this?
+  ADMIN = 1 << 31,
+}
 
+/**
+ * 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;
@@ -27,114 +42,224 @@ export interface CreateMarketParams {
   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 class NordAdmin extends NordClient {
-  private readonly signFn: (message: Uint8Array) => Promise<Uint8Array>;
+/**
+ * Parameters for updating an existing fee tier.
+ */
+export interface UpdateFeeTierParams {
+  tierId: number;
+  config: FeeTierConfig;
+}
 
-  constructor(params: NordAdminParams) {
-    const { signFn: adminSignFn, ...clientParams } = params;
-    super(clientParams);
-    this.signFn = adminSignFn;
-  }
+/**
+ * Administrative client capable of submitting privileged configuration actions.
+ */
+export class NordAdmin {
+  private readonly nord: Nord;
+  private readonly admin: PublicKey;
+  private readonly signFn: (x: Uint8Array) => Promise<Uint8Array>;
 
-  clone(): NordAdmin {
-    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;
+  private constructor({
+    nord,
+    admin,
+    signFn,
+  }: {
+    nord: Nord;
+    admin: PublicKey;
+    signFn: (x: Uint8Array) => Promise<Uint8Array>;
+  }) {
+    this.nord = nord;
+    this.admin = admin;
+    this.signFn = signFn;
   }
 
-  static fromUser(
-    user: NordUser,
-    adminSignFn: (message: Uint8Array) => Promise<Uint8Array>,
-  ): NordAdmin {
+  /** Create a new admin client.
+   *
+   * @param nord - Nord instance
+   * @param admin - The user that will be signing actions.
+   * @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.
+   */
+  public static new({
+    nord,
+    admin,
+    signFn,
+  }: Readonly<{
+    nord: Nord;
+    admin: PublicKey;
+    signFn: (m: Uint8Array) => Promise<Uint8Array>;
+  }>): NordAdmin {
     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,
+      admin,
+      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
+   */
   private async submitAction(
     kind: proto.Action["kind"],
   ): Promise<proto.Receipt> {
-    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(`Admin action ${kind.case} failed`, {
-        cause: error,
-      });
+    const timestamp = await this.nord.getTimestamp();
+    const action = createAction(timestamp, 0, kind);
+    return sendAction(
+      this.nord.webServerUrl,
+      async (xs: Uint8Array) => {
+        const signature = await this.signFn(xs);
+        if (signature.length !== 64) {
+          throw new NordError("invalid signature length; must be 64 bytes");
+        }
+        return Uint8Array.from([...xs, ...signature]);
+      },
+      action,
+    );
+  }
+
+  /** Set acl permissions for a given user.
+   *
+   * If all roles are removed, the user is removed from the acl.
+   *
+   * @param target - User to update.
+   * @param addRoles - Roles to add to the user.
+   * @param removeRoles - Reles to remove from the user.
+   */
+  async updateAcl({
+    target,
+    addRoles,
+    removeRoles,
+  }: Readonly<{
+    target: PublicKey;
+    addRoles: AclRole[];
+    removeRoles: AclRole[];
+  }>): Promise<{ actionId: bigint } & proto.Receipt_AclUpdated> {
+    const allRoles = addRoles.concat(removeRoles);
+    if (allRoles.length !== new Set(allRoles).size) {
+      throw new NordError("duplicate roles in acl update; must be unique");
     }
+
+    let mask = 0;
+    let values = 0;
+    for (const role of allRoles) {
+      mask |= role;
+    }
+    for (const role of addRoles) {
+      values |= role;
+    }
+
+    const receipt = await this.submitAction({
+      case: "updateAcl",
+      value: create(proto.Action_UpdateAclSchema, {
+        aclPubkey: this.admin.toBytes(),
+        targetPubkey: target.toBytes(),
+      }),
+    });
+    expectReceiptKind(receipt, "aclUpdated", "update acl");
+
+    return { ...receipt.kind.value, actionId: receipt.actionId };
   }
 
-  async createToken(
-    params: CreateTokenParams,
-  ): Promise<{ actionId: bigint } & proto.Receipt_InsertTokenResult> {
-    checkPubKeyLength(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,
+  }: CreateTokenParams): Promise<
+    { actionId: bigint } & proto.Receipt_InsertTokenResult
+  > {
     const receipt = await this.submitAction({
       case: "createToken",
       value: create(proto.Action_CreateTokenSchema, {
-        tokenDecimals: params.tokenDecimals,
-        weightBps: params.weightBps,
-        viewSymbol: params.viewSymbol,
-        oracleSymbol: params.oracleSymbol,
-        solAddr: params.solAddr,
+        aclPubkey: this.admin.toBytes(),
+        tokenDecimals,
+        weightBps,
+        viewSymbol,
+        oracleSymbol,
+        solAddr: mintAddr.toBytes(),
       }),
     });
-    this.expectReceiptKind(receipt, "insertTokenResult", "create token");
+    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: CreateMarketParams,
   ): Promise<{ actionId: bigint } & proto.Receipt_InsertMarketResult> {
     const receipt = await this.submitAction({
       case: "createMarket",
       value: create(proto.Action_CreateMarketSchema, {
+        aclPubkey: this.admin.toBytes(),
         sizeDecimals: params.sizeDecimals,
         priceDecimals: params.priceDecimals,
         imfBps: params.imfBps,
@@ -146,21 +271,48 @@ export class NordAdmin extends NordClient {
         baseTokenId: params.baseTokenId,
       }),
     });
-    this.expectReceiptKind(receipt, "insertMarketResult", "create market");
+    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: PythSetWormholeGuardiansParams,
   ): Promise<{ actionId: bigint } & proto.Receipt_UpdateGuardianSetResult> {
+    const addresses = params.addresses.map((address) => {
+      try {
+        const decoded = decodeHex(address);
+        if (decoded.length !== 20) {
+          throw new Error("guardian address must be 20 bytes");
+        }
+        return decoded;
+      } catch (e) {
+        throw new NordError(
+          "invalid guardian address; must be a 20 byte hex address",
+          { cause: e },
+        );
+      }
+    });
+
     const receipt = await this.submitAction({
       case: "pythSetWormholeGuardians",
       value: create(proto.Action_PythSetWormholeGuardiansSchema, {
+        aclPubkey: this.admin.toBytes(),
         guardianSetIndex: params.guardianSetIndex,
-        addresses: params.addresses,
+        addresses,
       }),
     });
-    this.expectReceiptKind(
+    expectReceiptKind(
       receipt,
       "updateGuardianSetResult",
       "update wormhole guardians",
@@ -168,42 +320,85 @@ export class NordAdmin extends NordClient {
     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: PythSetSymbolFeedParams,
   ): Promise<{ actionId: bigint } & proto.Receipt_OracleSymbolFeedResult> {
+    let priceFeedId: Uint8Array;
+    try {
+      priceFeedId = decodeHex(params.priceFeedId);
+      if (priceFeedId.length !== 32) {
+        throw new Error("price feed id must be 32 bytes");
+      }
+    } catch (e) {
+      throw new NordError("invalid price feed id; must be a 32 byte hex id", {
+        cause: e,
+      });
+    }
+
     const receipt = await this.submitAction({
       case: "pythSetSymbolFeed",
       value: create(proto.Action_PythSetSymbolFeedSchema, {
+        aclPubkey: this.admin.toBytes(),
         oracleSymbol: params.oracleSymbol,
-        priceFeedId: params.priceFeedId,
+        priceFeedId,
       }),
     });
-    this.expectReceiptKind(
-      receipt,
-      "oracleSymbolFeedResult",
-      "set symbol feed",
-    );
+    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(): Promise<{ actionId: bigint }> {
     const receipt = await this.submitAction({
       case: "pause",
-      value: create(proto.Action_PauseSchema, {}),
+      value: create(proto.Action_PauseSchema, {
+        aclPubkey: this.admin.toBytes(),
+      }),
     });
-    this.expectReceiptKind(receipt, "paused", "pause");
+    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(): Promise<{ actionId: bigint }> {
     const receipt = await this.submitAction({
       case: "unpause",
-      value: create(proto.Action_UnpauseSchema, {}),
+      value: create(proto.Action_UnpauseSchema, {
+        aclPubkey: this.admin.toBytes(),
+      }),
     });
-    this.expectReceiptKind(receipt, "unpaused", "unpause");
+    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: FreezeMarketParams,
   ): Promise<{ actionId: bigint } & proto.Receipt_MarketFreezeUpdated> {
@@ -211,12 +406,20 @@ export class NordAdmin extends NordClient {
       case: "freezeMarket",
       value: create(proto.Action_FreezeMarketSchema, {
         marketId: params.marketId,
+        aclPubkey: this.admin.toBytes(),
       }),
     });
-    this.expectReceiptKind(receipt, "marketFreezeUpdated", "freeze market");
+    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: UnfreezeMarketParams,
   ): Promise<{ actionId: bigint } & proto.Receipt_MarketFreezeUpdated> {
@@ -224,9 +427,88 @@ export class NordAdmin extends NordClient {
       case: "unfreezeMarket",
       value: create(proto.Action_UnfreezeMarketSchema, {
         marketId: params.marketId,
+        aclPubkey: this.admin.toBytes(),
+      }),
+    });
+    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: AddFeeTierParams,
+  ): Promise<{ actionId: bigint } & proto.Receipt_FeeTierAdded> {
+    const receipt = await this.submitAction({
+      case: "addFeeTier",
+      value: create(proto.Action_AddFeeTierSchema, {
+        aclPubkey: this.admin.toBytes(),
+        config: create(proto.FeeTierConfigSchema, params.config),
+      }),
+    });
+    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: UpdateFeeTierParams,
+  ): Promise<{ actionId: bigint } & proto.Receipt_FeeTierUpdated> {
+    const receipt = await this.submitAction({
+      case: "updateFeeTier",
+      value: create(proto.Action_UpdateFeeTierSchema, {
+        aclPubkey: this.admin.toBytes(),
+        id: params.tierId,
+        config: create(proto.FeeTierConfigSchema, params.config),
+      }),
+    });
+    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: number[],
+    tierId: number,
+  ): Promise<{ actionId: bigint } & proto.Receipt_AccountsTierUpdated> {
+    const receipt = await this.submitAction({
+      case: "updateAccountsTier",
+      value: create(proto.Action_UpdateAccountsTierSchema, {
+        aclPubkey: this.admin.toBytes(),
+        accounts,
+        tierId,
       }),
     });
-    this.expectReceiptKind(receipt, "marketFreezeUpdated", "unfreeze market");
+    expectReceiptKind(receipt, "accountsTierUpdated", "update accounts tier");
     return { actionId: receipt.actionId, ...receipt.kind.value };
   }
 }

package/src/nord/client/NordClient.ts

@@ -2,15 +2,8 @@ import { Connection, PublicKey } from "@solana/web3.js";
 import type { Transaction } from "@solana/web3.js";
 import * as proto from "../../gen/nord_pb";
 import { createAction, sendAction } from "../api/actions";
-import { NordError } from "../utils/NordError";
 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;
@@ -83,23 +76,4 @@ export abstract class NordClient {
   getSolanaPublicKey(): PublicKey {
     return this.address;
   }
-
-  protected expectReceiptKind<K extends ReceiptKind["case"]>(
-    receipt: proto.Receipt,
-    expected: K,
-    action: string,
-  ): asserts receipt is proto.Receipt & { kind: ExtractReceiptKind<K> } {
-    if (receipt.kind?.case !== expected) {
-      const label = this.formatReceiptError(receipt);
-      throw new NordError(`Failed to ${action}: ${label}`);
-    }
-  }
-
-  protected formatReceiptError(receipt: proto.Receipt): string {
-    if (receipt.kind?.case === "err") {
-      const err = receipt.kind.value;
-      return proto.Error[err] ?? err.toString();
-    }
-    return receipt.kind?.case ?? "unknown";
-  }
 }

package/src/nord/client/NordUser.ts

@@ -39,6 +39,7 @@ import {
   createSession,
   revokeSession,
   atomic,
+  expectReceiptKind,
   AtomicSubaction,
 } from "../api/actions";
 import { NordError } from "../utils/NordError";
@@ -737,7 +738,7 @@ export class NordUser extends NordClient {
           amount: scaledAmount,
         }),
       });
-      this.expectReceiptKind(receipt, "withdrawResult", "withdraw");
+      expectReceiptKind(receipt, "withdrawResult", "withdraw");
       return { actionId: receipt.actionId };
     } catch (error) {
       throw new NordError(
@@ -800,7 +801,7 @@ export class NordUser extends NordClient {
               : BigInt(params.clientOrderId),
         }),
       });
-      this.expectReceiptKind(receipt, "placeOrderResult", "place order");
+      expectReceiptKind(receipt, "placeOrderResult", "place order");
       const result = receipt.kind.value;
       return {
         actionId: receipt.actionId,
@@ -840,7 +841,7 @@ export class NordUser extends NordClient {
           senderAccountId: accountId,
         }),
       });
-      this.expectReceiptKind(receipt, "cancelOrderResult", "cancel order");
+      expectReceiptKind(receipt, "cancelOrderResult", "cancel order");
       return {
         actionId: receipt.actionId,
         orderId: receipt.kind.value.orderId,
@@ -900,7 +901,7 @@ export class NordUser extends NordClient {
           accountId: params.accountId,
         }),
       });
-      this.expectReceiptKind(receipt, "triggerAdded", "add trigger");
+      expectReceiptKind(receipt, "triggerAdded", "add trigger");
       return { actionId: receipt.actionId };
     } catch (error) {
       throw new NordError("Failed to add trigger", { cause: error });
@@ -939,7 +940,7 @@ export class NordUser extends NordClient {
           accountId: params.accountId,
         }),
       });
-      this.expectReceiptKind(receipt, "triggerRemoved", "remove trigger");
+      expectReceiptKind(receipt, "triggerRemoved", "remove trigger");
       return { actionId: receipt.actionId };
     } catch (error) {
       throw new NordError("Failed to remove trigger", { cause: error });
@@ -972,7 +973,7 @@ export class NordUser extends NordClient {
           amount,
         }),
       });
-      this.expectReceiptKind(receipt, "transferred", "transfer tokens");
+      expectReceiptKind(receipt, "transferred", "transfer tokens");
     } catch (error) {
       throw new NordError("Failed to transfer tokens", { cause: error });
     }