@zoguxprotocol/client-js 0.2.0

package/src/clients/validator-client.ts

@@ -0,0 +1,103 @@
+import { QueryClient, TxExtension, setupTxExtension } from '@cosmjs/stargate';
+import { Tendermint37Client } from '@cosmjs/tendermint-rpc';
+import Long from 'long';
+import protobuf from 'protobufjs';
+
+import {
+  ValidatorConfig,
+  BROADCAST_POLL_INTERVAL_MS,
+  BROADCAST_TIMEOUT_MS,
+  SelectedGasDenom,
+} from './constants';
+import { Get } from './modules/get';
+import { Post } from './modules/post';
+import { TendermintClient } from './modules/tendermintClient';
+
+// Required for encoding and decoding queries that are of type Long.
+// Must be done once but since the individal modules should be usable
+// - must be set in each module that encounters encoding/decoding Longs.
+// Reference: https://github.com/protobufjs/protobuf.js/issues/921
+protobuf.util.Long = Long;
+protobuf.configure();
+
+export class ValidatorClient {
+  public readonly config: ValidatorConfig;
+  private _get?: Get;
+  private _post?: Post;
+
+  /**
+   * @description Connect to a validator client
+   *
+   * @returns The validator client
+   */
+  static async connect(config: ValidatorConfig): Promise<ValidatorClient> {
+    const client = new ValidatorClient(config);
+    await client.initialize();
+    return client;
+  }
+
+  private constructor(config: ValidatorConfig) {
+    this.config = config;
+  }
+
+  /**
+   * @description Get the query module, used for retrieving on-chain data.
+   *
+   * @returns The query module
+   */
+  get get(): Get {
+    return this._get!;
+  }
+
+  /**
+   * @description transaction module, used for sending transactions.
+   *
+   * @returns The transaction module
+   */
+  get post(): Post {
+    return this._post!;
+  }
+
+  get selectedGasDenom(): SelectedGasDenom | undefined {
+    if (!this._post) return undefined;
+    return this._post.selectedGasDenom;
+  }
+
+  setSelectedGasDenom(gasDenom: SelectedGasDenom): void {
+    if (!this._post) throw new Error('Post module not initialized');
+
+    this._post.setSelectedGasDenom(gasDenom);
+  }
+
+  /**
+   * @description populate account number cache in the Post module for performance.
+   */
+  async populateAccountNumberCache(address: string): Promise<void> {
+    if (!this._post) throw new Error('Post module not initialized');
+    await this._post.populateAccountNumberCache(address);
+  }
+
+  private async initialize(): Promise<void> {
+    const tendermint37Client: Tendermint37Client = await Tendermint37Client.connect(
+      this.config.restEndpoint,
+    );
+
+    const tendermintClient = new TendermintClient(tendermint37Client, {
+      broadcastPollIntervalMs: BROADCAST_POLL_INTERVAL_MS,
+      broadcastTimeoutMs: BROADCAST_TIMEOUT_MS,
+    });
+    const queryClient: QueryClient & TxExtension = QueryClient.withExtensions(
+      tendermint37Client,
+      setupTxExtension,
+    );
+    this._get = new Get(tendermintClient, queryClient);
+    this._post = new Post(
+      this._get!,
+      this.config.chainId,
+      this.config.denoms,
+      this.config.defaultClientMemo,
+      this.config.useTimestampNonce,
+      this.config.timestampNonceOffsetMs,
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// Types.
+export * from './types';
+
+// Utility functions.
+export * as helpers from './lib/helpers';
+export * as onboarding from './lib/onboarding';
+export * as tradingKeyUtils from './lib/trading-key-utils';
+export * as utils from './lib/utils';
+export * as validation from './lib/validation';
+
+export { CompositeClient } from './clients/composite-client';
+export { FaucetClient } from './clients/faucet-client';
+export { IndexerClient } from './clients/indexer-client';
+export { default as LocalWallet } from './clients/modules/local-wallet';
+export { NobleClient } from './clients/noble-client';
+export { SocketClient } from './clients/socket-client';
+export { SubaccountInfo as SubaccountClient, SubaccountInfo } from './clients/subaccount';
+export { ValidatorClient } from './clients/validator-client';
+export { encodeJson, ByteArrayEncoding } from './lib/helpers';
+export { NetworkOptimizer } from './network_optimizer';

package/src/lib/constants.ts

@@ -0,0 +1,28 @@
+import { StdFee } from '@cosmjs/stargate';
+
+// Bech32 Prefix
+export const BECH32_PREFIX = 'zogux';
+export const NOBLE_BECH32_PREFIX = 'noble';
+
+// Broadcast Defaults
+export const BROADCAST_POLL_INTERVAL_MS: number = 300;
+export const BROADCAST_TIMEOUT_MS: number = 8_000;
+
+// API Defaults
+export const API_TIMEOUT_DEFAULT_MS: number = 5_000;
+
+// Gas
+export const GAS_MULTIPLIER: number = 1.6;
+
+export const ZERO_FEE: StdFee = {
+  amount: [],
+  gas: '0',
+};
+
+// Validation
+export const MAX_UINT_32 = 4_294_967_295;
+export const MAX_SUBACCOUNT_NUMBER = 128_000;
+
+export const DEFAULT_SEQUENCE: number = 0;
+
+export const SERIALIZED_INT_ZERO: Uint8Array = Uint8Array.from([0x02]);

package/src/lib/errors.ts

@@ -0,0 +1,38 @@
+import { BroadcastTxSyncResponse } from '@cosmjs/tendermint-rpc/build/tendermint37';
+
+/**
+ * An edge-case was hit in the client that should never have been reached.
+ */
+export class UnexpectedClientError extends Error {
+  constructor() {
+    super('An unexpected error occurred on the client');
+    this.name = 'UnexpectedClientError';
+  }
+}
+
+/**
+ * An error occurred during the broadcasting process.
+ */
+export class BroadcastErrorObject extends Error {
+  result: BroadcastTxSyncResponse;
+  code: number;
+  codespace?: string;
+
+  constructor(message: string, result: BroadcastTxSyncResponse) {
+    super(message);
+    this.name = 'BroadcastError';
+    this.result = result;
+    this.code = result.code;
+    this.codespace = result.codespace;
+  }
+}
+
+/**
+ * User error occurred during a client operation.
+ */
+export class UserError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'UserError';
+  }
+}

package/src/lib/helpers.ts

@@ -0,0 +1,99 @@
+import { toHex } from '@cosmjs/encoding';
+import BigNumber from 'bignumber.js';
+import Long from 'long';
+
+import { PartialTransactionOptions, TransactionOptions } from '../types';
+import { DEFAULT_SEQUENCE } from './constants';
+
+/**
+ * @description Either return undefined or insert default sequence value into
+ * `partialTransactionOptions` if it does not exist.
+ *
+ * @returns undefined or full TransactionOptions.
+ */
+export function convertPartialTransactionOptionsToFull(
+  partialTransactionOptions?: PartialTransactionOptions,
+): TransactionOptions | undefined {
+  if (partialTransactionOptions === undefined) {
+    return undefined;
+  }
+
+  return {
+    sequence: DEFAULT_SEQUENCE,
+    ...partialTransactionOptions,
+  };
+}
+
+/**
+ * @description Strip '0x' prefix from input string. If there is no '0x' prefix, return the original
+ * input.
+ *
+ * @returns input without '0x' prefix or original input if no prefix.
+ */
+export function stripHexPrefix(input: string): string {
+  if (input.indexOf('0x') === 0) {
+    return input.slice(2);
+  }
+
+  return input;
+}
+
+function toBigInt(u: Uint8Array): BigInt {
+  if (u.length <= 1) {
+    return BigInt(0);
+  }
+  // eslint-disable-next-line no-bitwise
+  const negated: boolean = (u[0] & 1) === 1;
+  const hex: string = Buffer.from(u.slice(1)).toString('hex');
+  const abs: bigint = BigInt(`0x${hex}`);
+  return negated ? -abs : abs;
+}
+
+export function bigIntToBytes(value: bigint): Uint8Array {
+  const absoluteValue = value < 0 ? value * BigInt(-1) : value;
+  const nonPaddedHexValue = absoluteValue.toString(16);
+  const paddedHexValue =
+    nonPaddedHexValue.length % 2 === 0 ? nonPaddedHexValue : `0${nonPaddedHexValue}`;
+  const numberBytes = Buffer.from(paddedHexValue, 'hex');
+  const signedBytes = Uint8Array.of(value < 0 ? 3 : 2, ...numberBytes);
+  return signedBytes;
+}
+
+export enum ByteArrayEncoding {
+  HEX = 'hex',
+  BIGINT = 'bigint',
+}
+
+export function encodeJson(
+  object?: Object,
+  byteArrayEncoding: ByteArrayEncoding = ByteArrayEncoding.HEX,
+): string {
+  // eslint-disable-next-line prefer-arrow-callback
+  return JSON.stringify(object, function replacer(_key, value) {
+    // Even though we set the an UInt8Array as the value,
+    // it comes in here as an object with UInt8Array as the buffer property.
+    if (value instanceof BigNumber) {
+      return value.toString();
+    }
+    if (typeof value === 'bigint') {
+      return value.toString();
+    }
+    if (value instanceof Long) {
+      return value.toString();
+    }
+    if (value?.buffer instanceof Uint8Array) {
+      if (byteArrayEncoding === ByteArrayEncoding.HEX) {
+        return toHex(value.buffer);
+      } else {
+        return toBigInt(value.buffer).toString();
+      }
+    } else if (value instanceof Uint8Array) {
+      if (byteArrayEncoding === ByteArrayEncoding.HEX) {
+        return toHex(value);
+      } else {
+        return toBigInt(value).toString();
+      }
+    }
+    return value;
+  });
+}

package/src/lib/onboarding.ts

@@ -0,0 +1,96 @@
+import { HDKey } from '@scure/bip32';
+import { entropyToMnemonic, mnemonicToSeedSync } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english';
+import { keccak256 } from 'ethereum-cryptography/keccak';
+
+import { stripHexPrefix } from './helpers';
+
+/**
+ * @description Get Mnemonic and priv/pub keys from privateKeyBytes and BIP44 HD path
+ *
+ * @url https://github.com/confio/cosmos-hd-key-derivation-spec#bip44
+ *
+ * @param entropy used to generate mnemonic
+ *
+ * @param path BIP44 HD Path. Default is The Cosmos Hub path
+ *
+ * @throws Error if the hdkey does not exist
+ *
+ * @returns Mnemonic and priv/pub keys
+ */
+export const exportMnemonicAndPrivateKey = (
+  entropy: Uint8Array,
+  path: string = "m/44'/118'/0'/0/0",
+): {
+  mnemonic: string;
+  privateKey: Uint8Array | null;
+  publicKey: Uint8Array | null;
+} => {
+  const mnemonic = entropyToMnemonic(entropy, wordlist);
+  const { privateKey, publicKey } = deriveHDKeyFromMnemonic(mnemonic, path);
+  return {
+    mnemonic,
+    privateKey,
+    publicKey,
+  };
+};
+
+/**
+ * @description Get private information for onboarding using an Ethereum Signature.
+ *
+ * @returns Mnemonic and Public/Private HD keys
+ */
+export const deriveHDKeyFromEthereumSignature = (
+  signature: string,
+): {
+  mnemonic: string;
+  privateKey: Uint8Array | null;
+  publicKey: Uint8Array | null;
+} => {
+  const buffer = Buffer.from(stripHexPrefix(signature), 'hex');
+
+  if (buffer.length !== 65) {
+    throw new Error('Signature must be 65 bytes');
+  }
+
+  // Remove the 'v' value by taking only the first 64 bytes of the signature
+  const rsValues = buffer.subarray(0, 64);
+  // Hash the 'r' and 's' values down to 32 bytes (256 bits) using Keccak-256
+  const entropy = keccak256(rsValues);
+  return exportMnemonicAndPrivateKey(entropy);
+};
+
+/**
+ * @description Derive priv/pub keys from mnemonic and BIP44 HD path
+ *
+ * @url https://github.com/confio/cosmos-hd-key-derivation-spec#bip44
+ *
+ * @param mnemonic used to generate seed
+ *
+ * @param path BIP44 HD Path. Default is The Cosmos Hub path
+ *
+ * @throws Error if the hdkey does not exist
+ *
+ * @returns Priv/pub keys
+ */
+export const deriveHDKeyFromMnemonic = (
+  mnemonic: string,
+  path: string = "m/44'/118'/0'/0/0",
+): {
+  privateKey: Uint8Array | null;
+  publicKey: Uint8Array | null;
+} => {
+  const seed = mnemonicToSeedSync(mnemonic);
+
+  const hdkey = HDKey.fromMasterSeed(seed);
+  const derivedHdkey = hdkey.derive(path);
+
+  if (!hdkey.privateKey) {
+    throw new Error('null hd key');
+  }
+
+  return {
+    privateKey: derivedHdkey.privateKey,
+    publicKey: derivedHdkey.publicKey,
+  };
+};

package/src/lib/trading-key-utils.ts

@@ -0,0 +1,136 @@
+import { fromBase64, toBase64, toBech32, toHex } from '@cosmjs/encoding';
+import { rawSecp256k1PubkeyToRawAddress } from '@cosmjs/tendermint-rpc';
+import { generateMnemonic } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english';
+
+import {
+  Authenticator,
+  AuthenticatorType,
+  TYPE_URL_BATCH_CANCEL,
+  TYPE_URL_MSG_CANCEL_ORDER,
+  TYPE_URL_MSG_PLACE_ORDER,
+} from '../clients/constants';
+import { type Get } from '../clients/modules/get';
+import LocalWallet from '../clients/modules/local-wallet';
+import { BECH32_PREFIX } from './constants';
+import { deriveHDKeyFromMnemonic } from './onboarding';
+
+export const createNewRandomZoguxWallet = async (): Promise<
+  { privateKeyHex: string; mnemonic: string; publicKey: string; address: string } | undefined
+> => {
+  const mnemonic = generateMnemonic(wordlist, 128);
+  const { privateKey: privateKeyRaw } = deriveHDKeyFromMnemonic(mnemonic);
+  const wallet = await LocalWallet.fromMnemonic(mnemonic, BECH32_PREFIX);
+
+  const privateKeyHex = privateKeyRaw != null ? `0x${toHex(privateKeyRaw)}` : undefined;
+  const publicKey = wallet.pubKey;
+  const address = wallet.address;
+
+  if (privateKeyHex == null || publicKey == null || address == null) {
+    return undefined;
+  }
+
+  return {
+    // 12 english words
+    mnemonic,
+    // toHex of the raw private key bits
+    privateKeyHex,
+    // base64, not hex
+    publicKey: publicKey.value,
+    // valid zogux address corresponding to the key pair
+    address,
+  };
+};
+
+// arguments to authorize a given wallet public key to trade on behalf of the user.
+// allows place order, cancel order, batch cancel on subaccount 0 only.
+export const getAuthorizeNewTradingKeyArguments = ({
+  generatedWalletPubKey,
+}: {
+  generatedWalletPubKey: string;
+}): { type: AuthenticatorType; data: Uint8Array } => {
+  const wrapAndEncode64 = (s: string): string => toBase64(new TextEncoder().encode(s));
+
+  const messageFilterSubAuth = [
+    {
+      type: AuthenticatorType.MESSAGE_FILTER,
+      config: wrapAndEncode64(TYPE_URL_MSG_PLACE_ORDER),
+    },
+    {
+      type: AuthenticatorType.MESSAGE_FILTER,
+      config: wrapAndEncode64(TYPE_URL_MSG_CANCEL_ORDER),
+    },
+    {
+      type: AuthenticatorType.MESSAGE_FILTER,
+      config: wrapAndEncode64(TYPE_URL_BATCH_CANCEL),
+    },
+  ];
+
+  const anyOfMessageFilterConfigB64 = wrapAndEncode64(JSON.stringify(messageFilterSubAuth));
+
+  const subAuth = [
+    {
+      type: AuthenticatorType.SIGNATURE_VERIFICATION,
+      config: generatedWalletPubKey,
+    },
+    {
+      type: AuthenticatorType.ANY_OF,
+      config: anyOfMessageFilterConfigB64,
+    },
+    // we limit to cross markets to make it slightly harder to drain user funds on low liquidity markets with trading keys
+    // could undo this in the future if people are angry about it
+    {
+      type: AuthenticatorType.SUBACCOUNT_FILTER,
+      config: wrapAndEncode64('0'),
+    },
+  ];
+
+  const jsonString = JSON.stringify(subAuth);
+  const encodedData = new TextEncoder().encode(jsonString);
+  const topLevelType = AuthenticatorType.ALL_OF;
+
+  return {
+    type: topLevelType,
+    data: encodedData,
+  };
+};
+
+// redeclared to keep sub bundle size small
+type Awaited<T> = T extends Promise<infer U> ? U : T;
+const isTruthy = <T>(n?: T | false | null | undefined | 0): n is T => Boolean(n);
+
+// just parses out keys that match the format created in getAuthorizeNewTradingKeyArguments
+export const getAuthorizedTradingKeysMetadata = (
+  authorizedKeys: Awaited<ReturnType<Get['getAuthenticators']>>['accountAuthenticators'],
+): Array<{ id: string; publicKey: string; address: string }> => {
+  return authorizedKeys
+    .map(({ config, id, type }) => {
+      if (type !== AuthenticatorType.ALL_OF) {
+        return null;
+      }
+      const parsedConfig = JSON.parse(new TextDecoder().decode(config)) as
+        | Authenticator[]
+        | undefined;
+      if (parsedConfig == null) {
+        return null;
+      }
+
+      const publicKey = parsedConfig.find(
+        (t) => t.type === AuthenticatorType.SIGNATURE_VERIFICATION,
+      )?.config;
+      if (publicKey == null || typeof publicKey !== 'string') {
+        return null;
+      }
+
+      const address = toBech32(
+        BECH32_PREFIX,
+        rawSecp256k1PubkeyToRawAddress(fromBase64(publicKey)),
+      );
+      return {
+        id: id.toString(),
+        publicKey,
+        address,
+      };
+    })
+    .filter(isTruthy);
+};

package/src/lib/utils.ts

@@ -0,0 +1,84 @@
+import { AxiosProxyConfig } from 'axios';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+
+import { MAX_UINT_32 } from '../clients/constants';
+
+/**
+ * Returns a random integer value between 0 and (n-1).
+ */
+export function randomInt(n: number): number {
+  return Math.floor(Math.random() * n);
+}
+
+/**
+ * Generate a random clientId.
+ */
+export function generateRandomClientId(): number {
+  return randomInt(MAX_UINT_32 + 1);
+}
+
+/**
+ * Deterministically generate a valid clientId from an arbitrary string by performing a
+ * quick hashing function on the string.
+ */
+export function clientIdFromString(input: string): number {
+  let hash: number = 0;
+  if (input.length === 0) return hash;
+  for (let i = 0; i < input.length; i++) {
+    hash = (hash << 5) - hash + input.charCodeAt(i); // eslint-disable-line no-bitwise
+    hash |= 0; // eslint-disable-line no-bitwise
+  }
+
+  // Bitwise operators covert the value to a 32-bit integer.
+  // We must coerce this into a 32-bit unsigned integer.
+  return hash + 2 ** 31;
+}
+
+/**
+ * Pauses the execution of the program for a specified time.
+ * @param ms - The number of milliseconds to pause the program.
+ * @returns A promise that resolves after the specified number of milliseconds.
+ */
+export async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Returns a title to use for a gov proposal that adds a new market.
+ *
+ * @param ticker ticker symbol for the new market.
+ * @returns title for the gov proposal.
+ */
+export function getGovAddNewMarketTitle(ticker: string): string {
+  return `Add ${ticker} perpetual market`;
+}
+
+/**
+ * Returns a summary to use for a gov proposal that adds a new market.
+ *
+ * @param ticker ticker symbol for the new market.
+ * @param delayBlocks number of blocks to wait before activating the market.
+ * @returns summary for the gov proposal.
+ */
+export function getGovAddNewMarketSummary(ticker: string, delayBlocks: number): string {
+  return `Add the x/prices, x/perpetuals and x/clob parameters needed for a ${ticker} perpetual market. Create the market in INITIALIZING status and transition it to ACTIVE status after ${delayBlocks} blocks.`;
+}
+
+export function calculateClockOffsetFromFetchDateHeader(
+  clientRequestStartTime: number,
+  serverReportedTime: number,
+  clientRequestEndTime: number,
+): number {
+  // use midpoint, so assume that time for request reach server === time for response to reach us
+  const estimatedLocalTimeAtServerArrival = (clientRequestStartTime + clientRequestEndTime) / 2;
+
+  // we need an offset such that estimatedLocalTimeAtServerArrival + offset = serverReportedTime
+  const offset = serverReportedTime - estimatedLocalTimeAtServerArrival;
+
+  return Math.floor(offset);
+}
+
+export function getProxyAgent(proxy: AxiosProxyConfig): HttpsProxyAgent<string> {
+  const auth = proxy.auth ? `${proxy.auth.username}:${proxy.auth.password}@` : '';
+  return new HttpsProxyAgent(`${proxy.protocol}://${auth}${proxy.host}:${proxy.port}`);
+}