xrpl 1.0.0-mpt-beta

package/src/Wallet/walletFromSecretNumbers.ts

@@ -0,0 +1,37 @@
+import { Account } from '@xrplf/secret-numbers'
+
+import ECDSA from '../ECDSA'
+
+import { Wallet } from '.'
+
+/**
+ * Derives a wallet from secret numbers.
+ * NOTE: This uses a default encoding algorithm of secp256k1 to match the popular wallet
+ * [Xumm (aka Xaman)](https://xumm.app/)'s behavior.
+ * This may be different from the DEFAULT_ALGORITHM for other ways to generate a Wallet.
+ *
+ * @param secretNumbers - A string consisting of 8 times 6 numbers (whitespace delimited) used to derive a wallet.
+ * @param opts - (Optional) Options to derive a Wallet.
+ * @param opts.masterAddress - Include if a Wallet uses a Regular Key Pair. It must be the master address of the account.
+ * @param opts.algorithm - The digital signature algorithm to generate an address for.
+ * @returns A Wallet derived from secret numbers.
+ * @throws ValidationError if unable to derive private key from secret number input.
+ */
+export function walletFromSecretNumbers(
+  secretNumbers: string[] | string,
+  opts?: { masterAddress?: string; algorithm?: ECDSA },
+): Wallet {
+  const secret = new Account(secretNumbers).getFamilySeed()
+  const updatedOpts: { masterAddress?: string; algorithm?: ECDSA } = {
+    masterAddress: undefined,
+    algorithm: undefined,
+  }
+  // Use secp256k1 since that's the algorithm used by popular wallets like Xumm when generating secret number accounts
+  if (opts === undefined) {
+    updatedOpts.algorithm = ECDSA.secp256k1
+  } else {
+    updatedOpts.masterAddress = opts.masterAddress
+    updatedOpts.algorithm = opts.algorithm ?? ECDSA.secp256k1
+  }
+  return Wallet.fromSecret(secret, updatedOpts)
+}

package/src/client/ConnectionManager.ts

@@ -0,0 +1,40 @@
+/**
+ * Manage all the requests made to the websocket, and their async responses
+ * that come in from the WebSocket. Because they come in over the WS connection
+ * after-the-fact.
+ */
+export default class ConnectionManager {
+  private promisesAwaitingConnection: Array<{
+    resolve: (value?: void | PromiseLike<void>) => void
+    reject: (value?: Error) => void
+  }> = []
+
+  /**
+   * Resolves all awaiting connections.
+   */
+  public resolveAllAwaiting(): void {
+    this.promisesAwaitingConnection.map(({ resolve }) => resolve())
+    this.promisesAwaitingConnection = []
+  }
+
+  /**
+   * Rejects all awaiting connections.
+   *
+   * @param error - Error to throw in the rejection.
+   */
+  public rejectAllAwaiting(error: Error): void {
+    this.promisesAwaitingConnection.map(({ reject }) => reject(error))
+    this.promisesAwaitingConnection = []
+  }
+
+  /**
+   * Await a new connection.
+   *
+   * @returns A promise for resolving the connection.
+   */
+  public async awaitConnection(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.promisesAwaitingConnection.push({ resolve, reject })
+    })
+  }
+}

package/src/client/ExponentialBackoff.ts

@@ -0,0 +1,71 @@
+/*
+ * Original code based on "backo" - https://github.com/segmentio/backo
+ * MIT License - Copyright 2014 Segment.io
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy,
+ * modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software
+ * is furnished to do so, subject to the following conditions:
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+interface ExponentialBackoffOptions {
+  // The min backoff duration.
+  min?: number
+  // The max backoff duration.
+  max?: number
+}
+
+const DEFAULT_MIN = 100
+const DEFAULT_MAX = 1000
+
+/**
+ * A Back off strategy that increases exponentially. Useful with repeated
+ * setTimeout calls over a network (where the destination may be down).
+ */
+export default class ExponentialBackoff {
+  private readonly ms: number
+  private readonly max: number
+  private readonly factor: number = 2
+  private numAttempts = 0
+
+  /**
+   * Constructs an ExponentialBackoff object.
+   *
+   * @param opts - The options for the object.
+   */
+  public constructor(opts: ExponentialBackoffOptions = {}) {
+    this.ms = opts.min ?? DEFAULT_MIN
+    this.max = opts.max ?? DEFAULT_MAX
+  }
+
+  /**
+   * Number of attempts for backoff so far.
+   *
+   * @returns Number of attempts.
+   */
+  public get attempts(): number {
+    return this.numAttempts
+  }
+
+  /**
+   * Return the backoff duration.
+   *
+   * @returns The backoff duration in milliseconds.
+   */
+  public duration(): number {
+    const ms = this.ms * this.factor ** this.numAttempts
+    this.numAttempts += 1
+    return Math.floor(Math.min(ms, this.max))
+  }
+
+  /**
+   * Reset the number of attempts.
+   */
+  public reset(): void {
+    this.numAttempts = 0
+  }
+}

package/src/client/RequestManager.ts

@@ -0,0 +1,220 @@
+import {
+  ResponseFormatError,
+  RippledError,
+  TimeoutError,
+  XrplError,
+} from '../errors'
+import { Response, RequestResponseMap } from '../models/methods'
+import { BaseRequest, ErrorResponse } from '../models/methods/baseMethod'
+
+interface PromiseEntry<T> {
+  resolve: (value: T | PromiseLike<T>) => void
+  reject: (value: Error) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+/**
+ * Manage all the requests made to the websocket, and their async responses
+ * that come in from the WebSocket. Responses come in over the WS connection
+ * after-the-fact, so this manager will tie that response to resolve the
+ * original request.
+ */
+export default class RequestManager {
+  private nextId = 0
+  private readonly promisesAwaitingResponse = new Map<
+    string | number,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Necessary and typed wrapper in addPromise method
+    PromiseEntry<any>
+  >()
+
+  /**
+   * Adds a promise to the collection of promises awaiting response. Handles typing with generics.
+   *
+   * @template T The generic type parameter representing the resolved value type.
+   * @param newId - The identifier for the new promise.
+   * @param timer - The timer associated with the promise.
+   * @returns A promise that resolves to the specified generic type.
+   */
+  public async addPromise<R extends BaseRequest, T = RequestResponseMap<R>>(
+    newId: string | number,
+    timer: ReturnType<typeof setTimeout>,
+  ): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      this.promisesAwaitingResponse.set(newId, {
+        resolve,
+        reject,
+        timer,
+      })
+    })
+  }
+
+  /**
+   * Successfully resolves a request.
+   *
+   * @param id - ID of the request.
+   * @param response - Response to return.
+   * @throws Error if no existing promise with the given ID.
+   */
+  public resolve(id: string | number, response: Response): void {
+    const promise = this.promisesAwaitingResponse.get(id)
+    if (promise == null) {
+      throw new XrplError(`No existing promise with id ${id}`, {
+        type: 'resolve',
+        response,
+      })
+    }
+    clearTimeout(promise.timer)
+    promise.resolve(response)
+    this.deletePromise(id)
+  }
+
+  /**
+   * Rejects a request.
+   *
+   * @param id - ID of the request.
+   * @param error - Error to throw with the reject.
+   * @throws Error if no existing promise with the given ID.
+   */
+  public reject(id: string | number, error: Error): void {
+    const promise = this.promisesAwaitingResponse.get(id)
+    if (promise == null) {
+      throw new XrplError(`No existing promise with id ${id}`, {
+        type: 'reject',
+        error,
+      })
+    }
+    clearTimeout(promise.timer)
+    // TODO: figure out how to have a better stack trace for an error
+    promise.reject(error)
+    this.deletePromise(id)
+  }
+
+  /**
+   * Reject all pending requests.
+   *
+   * @param error - Error to throw with the reject.
+   */
+  public rejectAll(error: Error): void {
+    this.promisesAwaitingResponse.forEach((_promise, id, _map) => {
+      this.reject(id, error)
+      this.deletePromise(id)
+    })
+  }
+
+  /**
+   * Creates a new WebSocket request. This sets up a timeout timer to catch
+   * hung responses, and a promise that will resolve with the response once
+   * the response is seen & handled.
+   *
+   * @param request - Request to create.
+   * @param timeout - Timeout length to catch hung responses.
+   * @returns Request ID, new request form, and the promise for resolving the request.
+   * @throws XrplError if request with the same ID is already pending.
+   */
+  public createRequest<R extends BaseRequest, T = RequestResponseMap<R>>(
+    request: R,
+    timeout: number,
+  ): [string | number, string, Promise<T>] {
+    let newId: string | number
+    if (request.id == null) {
+      newId = this.nextId
+      this.nextId += 1
+    } else {
+      newId = request.id
+    }
+    const newRequest = JSON.stringify({ ...request, id: newId })
+    // Typing required for Jest running in browser
+    const timer: ReturnType<typeof setTimeout> = setTimeout(() => {
+      this.reject(
+        newId,
+        new TimeoutError(
+          `Timeout for request: ${JSON.stringify(request)} with id ${newId}`,
+          request,
+        ),
+      )
+    }, timeout)
+    /*
+     * Node.js won't exit if a timer is still running, so we tell Node to ignore.
+     * (Node will still wait for the request to complete).
+     */
+    // The following type assertions are required to get this code to pass in browser environments
+    // where setTimeout has a different type
+    // eslint-disable-next-line max-len -- Necessary to disable both rules.
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access -- Reason above.
+    if ((timer as unknown as any).unref) {
+      // eslint-disable-next-line max-len -- Necessary to disable both rules.
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call -- Reason above.
+      ;(timer as unknown as any).unref()
+    }
+    if (this.promisesAwaitingResponse.has(newId)) {
+      clearTimeout(timer)
+      throw new XrplError(
+        `Response with id '${newId}' is already pending`,
+        request,
+      )
+    }
+    const newPromise = new Promise<T>((resolve, reject) => {
+      this.promisesAwaitingResponse.set(newId, {
+        resolve,
+        reject,
+        timer,
+      })
+    })
+
+    return [newId, newRequest, newPromise]
+  }
+
+  /**
+   * Handle a "response". Responses match to the earlier request handlers,
+   * and resolve/reject based on the data received.
+   *
+   * @param response - The response to handle.
+   * @throws ResponseFormatError if the response format is invalid, RippledError if rippled returns an error.
+   */
+  public handleResponse(response: Partial<Response | ErrorResponse>): void {
+    if (
+      response.id == null ||
+      !(typeof response.id === 'string' || typeof response.id === 'number')
+    ) {
+      throw new ResponseFormatError('valid id not found in response', response)
+    }
+    if (!this.promisesAwaitingResponse.has(response.id)) {
+      return
+    }
+    if (response.status == null) {
+      const error = new ResponseFormatError('Response has no status')
+      this.reject(response.id, error)
+    }
+    if (response.status === 'error') {
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- We know this must be true
+      const errorResponse = response as Partial<ErrorResponse>
+      const error = new RippledError(
+        errorResponse.error_message ?? errorResponse.error,
+        errorResponse,
+      )
+      this.reject(response.id, error)
+      return
+    }
+    if (response.status !== 'success') {
+      const error = new ResponseFormatError(
+        `unrecognized response.status: ${response.status ?? ''}`,
+        response,
+      )
+      this.reject(response.id, error)
+      return
+    }
+    // status no longer needed because error is thrown if status is not "success"
+    delete response.status
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Must be a valid Response here
+    this.resolve(response.id, response as unknown as Response)
+  }
+
+  /**
+   * Delete a promise after it has been returned.
+   *
+   * @param id - ID of the request.
+   */
+  private deletePromise(id: string | number): void {
+    this.promisesAwaitingResponse.delete(id)
+  }
+}