@n1xyz/nord-ts 0.1.5 → 0.1.7

package/src/{nord/client → client}/NordAdmin.ts

@@ -1,81 +1,19 @@
 import { create } from "@bufbuild/protobuf";
-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 { PublicKey, Transaction } from "@solana/web3.js";
+import * as proto from "../gen/nord_pb";
+import { decodeHex, signUserPayload } from "../utils";
+import { createAction, sendAction, expectReceiptKind } from "../actions";
+import { NordError } from "../error";
 import { Nord } from "./Nord";
-import { FeeTierConfig } from "../../gen/nord_pb";
+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;
-  mintAddr: PublicKey;
-}
-
-/**
- * Parameters used when creating a new market.
- */
-export interface CreateMarketParams {
-  sizeDecimals: number;
-  priceDecimals: number;
-  imfBps: number;
-  cmfBps: number;
-  mmfBps: number;
-  marketType: proto.MarketType;
-  viewSymbol: string;
-  oracleSymbol: string;
-  baseTokenId: number;
-}
-
-/**
- * Configuration for updating the Wormhole guardian set on the oracle.
- */
-export interface PythSetWormholeGuardiansParams {
-  guardianSetIndex: number;
-  addresses: string[];
-}
-
-/**
- * Parameters required to link an oracle symbol to a Pyth price feed.
- */
-export interface PythSetSymbolFeedParams {
-  oracleSymbol: string;
-  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;
-}
-
-/**
- * Parameters for adding a new fee tier.
- */
-export interface AddFeeTierParams {
-  config: FeeTierConfig;
-}
-
-/**
- * Parameters for updating an existing fee tier.
- */
-export interface UpdateFeeTierParams {
-  tierId: number;
-  config: FeeTierConfig;
+// 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,
 }
 
 /**
@@ -83,50 +21,41 @@ export interface UpdateFeeTierParams {
  */
 export class NordAdmin {
   private readonly nord: Nord;
-  private readonly signFn: (x: Uint8Array) => Promise<Uint8Array>;
+  private readonly admin: PublicKey;
+  private readonly signFn: (_: Transaction) => Promise<Transaction>;
 
   private constructor({
     nord,
+    admin,
     signFn,
   }: {
     nord: Nord;
-    signFn: (x: Uint8Array) => Promise<Uint8Array>;
+    admin: PublicKey;
+    signFn: (x: Transaction) => Promise<Transaction>;
   }) {
     this.nord = nord;
+    this.admin = admin;
     this.signFn = signFn;
   }
 
   /** 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;
-    signFn: (m: Uint8Array) => Promise<Uint8Array>;
+    admin: PublicKey;
+    signFn: (m: Transaction) => Promise<Transaction>;
   }>): NordAdmin {
     return new NordAdmin({
       nord,
+      admin,
       signFn,
     });
   }
@@ -143,22 +72,72 @@ export class NordAdmin {
     const timestamp = await this.nord.getTimestamp();
     const action = createAction(timestamp, 0, kind);
     return sendAction(
-      this.nord.webServerUrl,
+      this.nord.httpClient,
       async (xs: Uint8Array) => {
-        const signature = await this.signFn(xs);
-        if (signature.length !== 64) {
-          throw new NordError("invalid signature length; must be 64 bytes");
-        }
+        const signature = await signUserPayload({
+          payload: xs,
+          user: this.admin,
+          signTransaction: this.signFn,
+        });
         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(),
+        rolesValue: values,
+        rolesMask: mask,
+      }),
+    });
+    expectReceiptKind(receipt, "aclUpdated", "update acl");
+
+    return { ...receipt.kind.value, actionId: receipt.actionId };
+  }
+
   /**
    * Register a new token that can be listed on Nord.
    *
-   * @param params - Token configuration values
+   * @param tokenDecimals - Decimal shift used when parsing deposits/withdrawals
+   * @param weightBps - Risk weight in basis points applied in account value calculations
+   * @param viewSymbol - Symbol surfaced to Nord clients
+   * @param oracleSymbol - Symbol resolved by the oracle adapter
+   * @param mintAddr - Solana mint backing this token
    * @returns Action identifier and resulting token metadata
    * @throws {NordError} If the action submission fails
    */
@@ -168,12 +147,17 @@ export class NordAdmin {
     viewSymbol,
     oracleSymbol,
     mintAddr,
-  }: CreateTokenParams): Promise<
-    { actionId: bigint } & proto.Receipt_InsertTokenResult
-  > {
+  }: Readonly<{
+    tokenDecimals: number;
+    weightBps: number;
+    viewSymbol: string;
+    oracleSymbol: string;
+    mintAddr: PublicKey;
+  }>): Promise<{ actionId: bigint } & proto.Receipt_InsertTokenResult> {
     const receipt = await this.submitAction({
       case: "createToken",
       value: create(proto.Action_CreateTokenSchema, {
+        aclPubkey: this.admin.toBytes(),
         tokenDecimals,
         weightBps,
         viewSymbol,
@@ -188,25 +172,52 @@ export class NordAdmin {
   /**
    * Open a new market with the provided trading parameters.
    *
-   * @param params - Market configuration to apply
+   * @param sizeDecimals - Decimal shift for contract sizes
+   * @param priceDecimals - Decimal shift for price ticks
+   * @param imfBps - Base initial margin fraction (IMF) in basis points, see docs/MARKETS.md
+   * @param cmfBps - Cancel margin fraction (CMF) in basis points, see docs/MARKETS.md
+   * @param mmfBps - Maintenance margin fraction (MMF) in basis points, see docs/MARKETS.md
+   * @param marketType - Spot or perpetual market type
+   * @param viewSymbol - Symbol exposed to Nord clients
+   * @param oracleSymbol - Symbol resolved by the oracle adapter
+   * @param baseTokenId - Registered base token backing this market
    * @returns Action identifier and resulting market metadata
    * @throws {NordError} If the action submission fails
    */
-  async createMarket(
-    params: CreateMarketParams,
-  ): Promise<{ actionId: bigint } & proto.Receipt_InsertMarketResult> {
+  async createMarket({
+    sizeDecimals,
+    priceDecimals,
+    imfBps,
+    cmfBps,
+    mmfBps,
+    marketType,
+    viewSymbol,
+    oracleSymbol,
+    baseTokenId,
+  }: Readonly<{
+    sizeDecimals: number;
+    priceDecimals: number;
+    imfBps: number;
+    cmfBps: number;
+    mmfBps: number;
+    marketType: proto.MarketType;
+    viewSymbol: string;
+    oracleSymbol: string;
+    baseTokenId: number;
+  }>): Promise<{ actionId: bigint } & proto.Receipt_InsertMarketResult> {
     const receipt = await this.submitAction({
       case: "createMarket",
       value: create(proto.Action_CreateMarketSchema, {
-        sizeDecimals: params.sizeDecimals,
-        priceDecimals: params.priceDecimals,
-        imfBps: params.imfBps,
-        cmfBps: params.cmfBps,
-        mmfBps: params.mmfBps,
-        marketType: params.marketType,
-        viewSymbol: params.viewSymbol,
-        oracleSymbol: params.oracleSymbol,
-        baseTokenId: params.baseTokenId,
+        aclPubkey: this.admin.toBytes(),
+        sizeDecimals,
+        priceDecimals,
+        imfBps,
+        cmfBps,
+        mmfBps,
+        marketType,
+        viewSymbol,
+        oracleSymbol,
+        baseTokenId,
       }),
     });
     expectReceiptKind(receipt, "insertMarketResult", "create market");
@@ -220,14 +231,19 @@ export class NordAdmin {
    * leading `0x` prefix). The engine validates the supplied guardian set index
    * before applying the update.
    *
-   * @param params - Guardian set index and guardian addresses
+   * @param guardianSetIndex - Wormhole guardian set index that must already exist
+   * @param addresses - 20-byte hex-encoded 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) => {
+  async pythSetWormholeGuardians({
+    guardianSetIndex,
+    addresses,
+  }: Readonly<{
+    guardianSetIndex: number;
+    addresses: readonly string[];
+  }>): Promise<{ actionId: bigint } & proto.Receipt_UpdateGuardianSetResult> {
+    const parsedAddresses = addresses.map((address) => {
       try {
         const decoded = decodeHex(address);
         if (decoded.length !== 20) {
@@ -245,8 +261,9 @@ export class NordAdmin {
     const receipt = await this.submitAction({
       case: "pythSetWormholeGuardians",
       value: create(proto.Action_PythSetWormholeGuardiansSchema, {
-        guardianSetIndex: params.guardianSetIndex,
-        addresses,
+        aclPubkey: this.admin.toBytes(),
+        guardianSetIndex,
+        addresses: parsedAddresses,
       }),
     });
     expectReceiptKind(
@@ -264,16 +281,21 @@ export class NordAdmin {
    * 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
+   * @param oracleSymbol - Symbol resolved by the oracle adapter
+   * @param priceFeedId - 32-byte hex-encoded Pyth 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> {
+  async pythSetSymbolFeed({
+    oracleSymbol,
+    priceFeedId: priceFeedIdHex,
+  }: Readonly<{
+    oracleSymbol: string;
+    priceFeedId: string;
+  }>): Promise<{ actionId: bigint } & proto.Receipt_OracleSymbolFeedResult> {
     let priceFeedId: Uint8Array;
     try {
-      priceFeedId = decodeHex(params.priceFeedId);
+      priceFeedId = decodeHex(priceFeedIdHex);
       if (priceFeedId.length !== 32) {
         throw new Error("price feed id must be 32 bytes");
       }
@@ -286,7 +308,8 @@ export class NordAdmin {
     const receipt = await this.submitAction({
       case: "pythSetSymbolFeed",
       value: create(proto.Action_PythSetSymbolFeedSchema, {
-        oracleSymbol: params.oracleSymbol,
+        aclPubkey: this.admin.toBytes(),
+        oracleSymbol,
         priceFeedId,
       }),
     });
@@ -303,7 +326,9 @@ export class NordAdmin {
   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(),
+      }),
     });
     expectReceiptKind(receipt, "paused", "pause");
     return { actionId: receipt.actionId };
@@ -318,7 +343,9 @@ export class NordAdmin {
   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(),
+      }),
     });
     expectReceiptKind(receipt, "unpaused", "unpause");
     return { actionId: receipt.actionId };
@@ -327,17 +354,20 @@ export class NordAdmin {
   /**
    * Freeze an individual market, preventing new trades and orders.
    *
-   * @param params - Target market identifier
+   * @param marketId - 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> {
+  async freezeMarket({
+    marketId,
+  }: Readonly<{
+    marketId: number;
+  }>): Promise<{ actionId: bigint } & proto.Receipt_MarketFreezeUpdated> {
     const receipt = await this.submitAction({
       case: "freezeMarket",
       value: create(proto.Action_FreezeMarketSchema, {
-        marketId: params.marketId,
+        marketId,
+        aclPubkey: this.admin.toBytes(),
       }),
     });
     expectReceiptKind(receipt, "marketFreezeUpdated", "freeze market");
@@ -347,17 +377,20 @@ export class NordAdmin {
   /**
    * Unfreeze a market that was previously halted.
    *
-   * @param params - Target market identifier
+   * @param marketId - 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> {
+  async unfreezeMarket({
+    marketId,
+  }: Readonly<{
+    marketId: number;
+  }>): Promise<{ actionId: bigint } & proto.Receipt_MarketFreezeUpdated> {
     const receipt = await this.submitAction({
       case: "unfreezeMarket",
       value: create(proto.Action_UnfreezeMarketSchema, {
-        marketId: params.marketId,
+        marketId,
+        aclPubkey: this.admin.toBytes(),
       }),
     });
     expectReceiptKind(receipt, "marketFreezeUpdated", "unfreeze market");
@@ -371,17 +404,20 @@ export class NordAdmin {
    *   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
+   * @param config - 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> {
+  async addFeeTier({
+    config,
+  }: Readonly<{
+    config: FeeTierConfig;
+  }>): Promise<{ actionId: bigint } & proto.Receipt_FeeTierAdded> {
     const receipt = await this.submitAction({
       case: "addFeeTier",
       value: create(proto.Action_AddFeeTierSchema, {
-        config: create(proto.FeeTierConfigSchema, params.config),
+        aclPubkey: this.admin.toBytes(),
+        config: create(proto.FeeTierConfigSchema, config),
       }),
     });
     expectReceiptKind(receipt, "feeTierAdded", "add fee tier");
@@ -394,18 +430,24 @@ export class NordAdmin {
    * Tier identifiers must already exist; attempting to update a missing tier
    * causes the action to fail.
    *
-   * @param params - Fee tier identifier and updated configuration
+   * @param tierId - Existing fee tier identifier to update
+   * @param config - Replacement configuration for the tier
    * @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> {
+  async updateFeeTier({
+    tierId,
+    config,
+  }: Readonly<{
+    tierId: number;
+    config: FeeTierConfig;
+  }>): Promise<{ actionId: bigint } & proto.Receipt_FeeTierUpdated> {
     const receipt = await this.submitAction({
       case: "updateFeeTier",
       value: create(proto.Action_UpdateFeeTierSchema, {
-        id: params.tierId,
-        config: create(proto.FeeTierConfigSchema, params.config),
+        aclPubkey: this.admin.toBytes(),
+        id: tierId,
+        config: create(proto.FeeTierConfigSchema, config),
       }),
     });
     expectReceiptKind(receipt, "feeTierUpdated", "update fee tier");
@@ -431,6 +473,7 @@ export class NordAdmin {
     const receipt = await this.submitAction({
       case: "updateAccountsTier",
       value: create(proto.Action_UpdateAccountsTierSchema, {
+        aclPubkey: this.admin.toBytes(),
         accounts,
         tierId,
       }),