xrpl 2.12.0 → 3.0.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xrpl",
-  "version": "2.12.0",
+  "version": "3.0.0-beta.0",
   "license": "ISC",
   "description": "A TypeScript/JavaScript API for interacting with the XRP Ledger in Node.js and the browser",
   "files": [
@@ -19,35 +19,33 @@
     "test": "test"
   },
   "browser": {
-    "ws": "./dist/npm/client/WSWrapper.js",
-    "https-proxy-agent": false
+    "ws": "./dist/npm/client/WSWrapper.js"
   },
   "dependencies": {
+    "@scure/bip32": "^1.3.1",
+    "@scure/bip39": "^1.2.1",
+    "@xrplf/isomorphic": "^1.0.0-beta.0",
+    "@xrplf/secret-numbers": "^1.0.0-beta.0",
     "bignumber.js": "^9.0.0",
-    "bip32": "^2.0.6",
-    "bip39": "^3.0.4",
-    "https-proxy-agent": "^5.0.0",
-    "lodash": "^4.17.4",
-    "ripple-address-codec": "^4.3.1",
-    "ripple-binary-codec": "^1.10.0",
-    "ripple-keypairs": "^1.3.1",
-    "ws": "^8.2.2",
-    "xrpl-secret-numbers": "^0.3.3"
+    "cross-fetch": "^4.0.0",
+    "eventemitter3": "^5.0.1",
+    "ripple-address-codec": "^5.0.0-beta.0",
+    "ripple-binary-codec": "^2.0.0-beta.0",
+    "ripple-keypairs": "^2.0.0-beta.0"
   },
   "devDependencies": {
-    "@geut/browser-node-core": "^2.0.13",
-    "@types/node": "^14.18.36",
-    "assert-browserify": "^2.0.0",
-    "browserify-fs": "^1.0.0",
-    "constants-browserify": "^1.0.0",
-    "https-browserify": "^1.0.0",
+    "@types/node": "^16.18.38",
+    "eventemitter3": "^5.0.1",
+    "https-proxy-agent": "^7.0.1",
     "karma": "^6.4.1",
     "karma-chrome-launcher": "^3.1.1",
     "karma-jasmine": "^5.1.0",
     "karma-webpack": "^5.0.0",
-    "node-polyfill-webpack-plugin": "^2.0.1",
+    "lodash": "^4.17.4",
     "react": "^18.2.0",
-    "typedoc": "^0.25.0"
+    "run-s": "^0.0.0",
+    "typedoc": "0.25.0",
+    "ws": "^8.14.2"
   },
   "resolutions": {
     "elliptic": "^6.5.4"
@@ -58,14 +56,15 @@
     "build:lib": "tsc --build tsconfig.build.json",
     "build:web": "webpack",
     "build:browserTests": "webpack --config ./test/webpack.config.js",
-    "analyze": "run-s build:web --analyze",
+    "analyze": "webpack --analyze",
     "watch": "run-s build:lib --watch",
-    "clean": "rm -rf dist build coverage",
+    "clean": "rm -rf ./dist ./coverage ./test/testCompiledForWeb tsconfig.build.tsbuildinfo",
     "docgen": "tsc --build tsconfig.docs.json && typedoc && echo js.xrpl.org >> ../../docs/CNAME",
+    "prepare": "copyfiles ../../README.md xrpl/README.md",
     "prepublish": "run-s clean build",
     "test": "jest --config=jest.config.unit.js --verbose false --silent=false",
     "test:integration": "TS_NODE_PROJECT=tsconfig.build.json jest --config=jest.config.integration.js --verbose false --silent=false --runInBand",
-    "test:browser": "npm run build && npm run build:browserTests && karma start ./karma.config.js --single-run",
+    "test:browser": "npm run build && npm run build:browserTests && karma start ./karma.config.js",
     "test:watch": "jest --watch --verbose false --silent=false --runInBand ./test/**/*.test.ts --testPathIgnorePatterns=./test/integration --testPathIgnorePatterns=./test/fixtures",
     "format": "prettier --write '{src,test}/**/*.ts'",
     "lint": "eslint . --ext .ts --max-warnings 0",
@@ -80,7 +79,15 @@
     "url": "git@github.com:XRPLF/xrpl.js.git"
   },
   "readmeFilename": "README.md",
+  "keywords": [
+    "ripple-lib",
+    "ripple",
+    "xrp",
+    "xrp ledger",
+    "xrpl"
+  ],
   "engines": {
-    "node": ">=10.13.0"
-  }
+    "node": ">=16.0.0"
+  },
+  "gitHead": "9e30f1892c20a915c47593ffb8c336595804e4e7"
 }

package/src/Wallet/authorizeChannel.ts

@@ -0,0 +1,26 @@
+import { encodeForSigningClaim } from 'ripple-binary-codec'
+import { sign } from 'ripple-keypairs'
+
+import { Wallet } from './index'
+
+/**
+ * Creates a signature that can be used to redeem a specific amount of XRP from a payment channel.
+ *
+ * @param wallet - The account that will sign for this payment channel.
+ * @param channelId - An id for the payment channel to redeem XRP from.
+ * @param amount - The amount in drops to redeem.
+ * @returns A signature that can be used to redeem a specific amount of XRP from a payment channel.
+ * @category Utilities
+ */
+export function authorizeChannel(
+  wallet: Wallet,
+  channelId: string,
+  amount: string,
+): string {
+  const signingData = encodeForSigningClaim({
+    channel: channelId,
+    amount,
+  })
+
+  return sign(signingData, wallet.privateKey)
+}

package/src/Wallet/defaultFaucets.ts

@@ -50,10 +50,6 @@ export function getFaucetHost(client: Client): FaucetNetwork | undefined {
     return FaucetNetwork.AMMDevnet
   }
 
-  if (connectionUrl.includes('sidechain-net1')) {
-    return FaucetNetwork.SidechainDevnet
-  }
-
   if (connectionUrl.includes('sidechain-net2')) {
     throw new XRPLFaucetError(
       'Cannot fund an account on an issuing chain. Accounts must be created via the bridge.',

package/src/Wallet/fundWallet.ts

@@ -1,10 +1,8 @@
-import { IncomingMessage } from 'http'
-import { request as httpsRequest, RequestOptions } from 'https'
-
+import fetch from 'cross-fetch'
 import { isValidClassicAddress } from 'ripple-address-codec'
 
 import type { Client } from '../client'
-import { RippledError, XRPLFaucetError } from '../errors'
+import { XRPLFaucetError } from '../errors'
 
 import {
   FaucetWallet,
@@ -19,53 +17,103 @@ const INTERVAL_SECONDS = 1
 // Maximum attempts to retrieve a balance
 const MAX_ATTEMPTS = 20
 
+export interface FundingOptions {
+  /**
+   *  A custom amount to fund, if undefined or null, the default amount will be 1000.
+   */
+  amount?: string
+  /**
+   * A custom host for a faucet server. On devnet, testnet, AMM devnet, and HooksV3 testnet, `fundWallet` will
+   * attempt to determine the correct server automatically. In other environments, or if you would like to customize
+   * the faucet host in devnet or testnet, you should provide the host using this option.
+   */
+  faucetHost?: string
+  /**
+   * A custom path for a faucet server. On devnet,
+   * testnet, AMM devnet, and HooksV3 testnet, `fundWallet` will
+   * attempt to determine the correct path automatically. In other environments,
+   * or if you would like to customize the faucet path in devnet or testnet,
+   * you should provide the path using this option.
+   * Ex: client.fundWallet(null,{'faucet.altnet.rippletest.net', '/accounts'})
+   * specifies a request to 'faucet.altnet.rippletest.net/accounts' to fund a new wallet.
+   */
+  faucetPath?: string
+  /**
+   * An optional field to indicate the use case context of the faucet transaction
+   * Ex: integration test, code snippets.
+   */
+  usageContext?: string
+}
+
 /**
- * The fundWallet() method is used to send an amount of XRP (usually 1000) to a new (randomly generated)
- * or existing XRP Ledger wallet.
- *
- * @example
- *
- * Example 1: Fund a randomly generated wallet
- * const { Client, Wallet } = require('xrpl')
- *
- * const client = new Client('wss://s.altnet.rippletest.net:51233')
- * await client.connect()
- * const { balance, wallet } = await client.fundWallet()
- *
- * Under the hood, this will use `Wallet.generate()` to create a new random wallet, then ask a testnet faucet
- * To send it XRP on ledger to make it a real account. If successful, this will return the new account balance in XRP
- * Along with the Wallet object to track the keys for that account. If you'd like, you can also re-fill an existing
- * Account by passing in a Wallet you already have.
- * ```ts
- * const api = new xrpl.Client("wss://s.altnet.rippletest.net:51233")
- * await api.connect()
- * const { wallet, balance } = await api.fundWallet()
- * ```
+ * Parameters to pass into a faucet request to fund an XRP account.
+ */
+export interface FaucetRequestBody {
+  /**
+   * The address to fund. If no address is provided the faucet will fund a random account.
+   */
+  destination?: string
+  /**
+   * The total amount of XRP to fund the account with.
+   */
+  xrpAmount?: string
+  /**
+   * An optional field to indicate the use case context of the faucet transaction
+   * Ex: integration test, code snippets.
+   */
+  usageContext?: string
+  /**
+   * Information about the context of where the faucet is being called from.
+   * Ex: xrpl.js or xrpl-py
+   */
+  userAgent: string
+}
+
+/**
+ * Generate a new wallet to fund if no existing wallet is provided or its address is invalid.
  *
- * Example 2: Fund wallet using a custom faucet host and known wallet address
+ * @param wallet - Optional existing wallet.
+ * @returns The wallet to fund.
+ */
+export function generateWalletToFund(wallet?: Wallet | null): Wallet {
+  if (wallet && isValidClassicAddress(wallet.classicAddress)) {
+    return wallet
+  }
+  return Wallet.generate()
+}
+
+/**
+ * Get the starting balance of the wallet.
  *
- * `fundWallet` will try to infer the url of a faucet API from the network your client is connected to.
- * There are hardcoded default faucets for popular test networks like testnet and devnet.
- * However, if you're working with a newer or more obscure network, you may have to specify the faucetHost
- * And faucetPath so `fundWallet` can ask that faucet to fund your wallet.
+ * @param client - The client object.
+ * @param classicAddress - The classic address of the wallet.
+ * @returns The starting balance.
+ */
+export async function getStartingBalance(
+  client: Client,
+  classicAddress: string,
+): Promise<number> {
+  let startingBalance = 0
+  try {
+    startingBalance = Number(await client.getXrpBalance(classicAddress))
+  } catch {
+    // startingBalance remains '0'
+  }
+  return startingBalance
+}
+
+export interface FundWalletOptions {
+  faucetHost?: string
+  faucetPath?: string
+  amount?: string
+  usageContext?: string
+}
+
+/**
  *
- * ```ts
- * const newWallet = Wallet.generate()
- * const { balance, wallet  } = await client.fundWallet(newWallet, {
- *       amount: '10',
- *       faucetHost: 'https://custom-faucet.example.com',
- *       faucetPath: '/accounts'
- *     })
- *     console.log(`Sent 10 XRP to wallet: ${address} from the given faucet. Resulting balance: ${balance} XRP`)
- *   } catch (error) {
- *     console.error(`Failed to fund wallet: ${error}`)
- *   }
- * }
- * ```
+ * Helper function to request funding from a faucet. Should not be called directly from outside the xrpl.js library.
  *
- * @param this - Client.
- * @param wallet - An existing XRPL Wallet to fund. If undefined or null, a new Wallet will be created.
- * @param options - See below.
+ * @param options - See below
  * @param options.faucetHost - A custom host for a faucet server. On devnet,
  * testnet, AMM devnet, and HooksV3 testnet, `fundWallet` will
  * attempt to determine the correct server automatically. In other environments,
@@ -79,182 +127,69 @@ const MAX_ATTEMPTS = 20
  * Ex: client.fundWallet(null,{'faucet.altnet.rippletest.net', '/accounts'})
  * specifies a request to 'faucet.altnet.rippletest.net/accounts' to fund a new wallet.
  * @param options.amount - A custom amount to fund, if undefined or null, the default amount will be 1000.
- * @param options.usageContext - An optional field to indicate the use case context of the faucet transaction
- * Ex: integration test, code snippets.
- * @returns A Wallet on the Testnet or Devnet that contains some amount of XRP,
- * and that wallet's balance in XRP.
- * @throws When either Client isn't connected or unable to fund wallet address.
+ * @param client - A connection to the XRPL to send requests and transactions.
+ * @param startingBalance - The amount of XRP in the given walletToFund on ledger already.
+ * @param walletToFund - An existing XRPL Wallet to fund.
+ * @param postBody - The content to send the faucet to indicate which address to fund, how much to fund it, and
+ * where the request is coming from.
+ * @returns A promise that resolves to a funded wallet and the balance within it.
  */
-// eslint-disable-next-line max-lines-per-function -- All lines necessary
-async function fundWallet(
-  this: Client,
-  wallet?: Wallet | null,
-  options?: {
-    faucetHost?: string
-    faucetPath?: string
-    amount?: string
-    usageContext?: string
-  },
-): Promise<{
-  wallet: Wallet
-  balance: number
-}> {
-  if (!this.isConnected()) {
-    throw new RippledError('Client not connected, cannot call faucet')
-  }
-
-  // Generate a new Wallet if no existing Wallet is provided or its address is invalid to fund
-  const walletToFund =
-    wallet && isValidClassicAddress(wallet.classicAddress)
-      ? wallet
-      : Wallet.generate()
-
-  // Create the POST request body
-  const postBody = Buffer.from(
-    new TextEncoder().encode(
-      JSON.stringify({
-        destination: walletToFund.classicAddress,
-        xrpAmount: options?.amount,
-        userAgent: 'xrpl.js',
-        usageContext: options?.usageContext,
-      }),
-    ),
-  )
-
-  let startingBalance = 0
-  try {
-    startingBalance = Number(
-      await this.getXrpBalance(walletToFund.classicAddress),
-    )
-  } catch {
-    /* startingBalance remains '0' */
-  }
-  // Options to pass to https.request
-  const httpOptions = getHTTPOptions(this, postBody, {
-    hostname: options?.faucetHost,
-    pathname: options?.faucetPath,
-  })
-
-  return returnPromise(
-    httpOptions,
-    this,
-    startingBalance,
-    walletToFund,
-    postBody,
-  )
-}
-
 // eslint-disable-next-line max-params -- Helper function created for organizational purposes
-async function returnPromise(
-  options: RequestOptions,
+export async function requestFunding(
+  options: FundingOptions,
   client: Client,
   startingBalance: number,
   walletToFund: Wallet,
-  postBody: Buffer,
+  postBody: FaucetRequestBody,
 ): Promise<{
   wallet: Wallet
   balance: number
 }> {
-  return new Promise((resolve, reject) => {
-    const request = httpsRequest(options, (response) => {
-      const chunks: Uint8Array[] = []
-      response.on('data', (data) => chunks.push(data))
-      // eslint-disable-next-line @typescript-eslint/no-misused-promises -- not actually misused, different resolve/reject
-      response.on('end', async () =>
-        onEnd(
-          response,
-          chunks,
-          client,
-          startingBalance,
-          walletToFund,
-          resolve,
-          reject,
-        ),
-      )
-    })
-    // POST the body
-    request.write(postBody)
-
-    request.on('error', (error) => {
-      reject(error)
-    })
-
-    request.end()
-  })
-}
-
-function getHTTPOptions(
-  client: Client,
-  postBody: Uint8Array,
-  options?: {
-    hostname?: string
-    pathname?: string
-  },
-): RequestOptions {
-  const finalHostname = options?.hostname ?? getFaucetHost(client)
-  const finalPathname = options?.pathname ?? getDefaultFaucetPath(finalHostname)
-  return {
-    hostname: finalHostname,
-    port: 443,
-    path: finalPathname,
+  const hostname = options.faucetHost ?? getFaucetHost(client)
+  if (!hostname) {
+    throw new XRPLFaucetError('No faucet hostname could be derived')
+  }
+  const pathname = options.faucetPath ?? getDefaultFaucetPath(hostname)
+  const response = await fetch(`https://${hostname}${pathname}`, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
-      'Content-Length': postBody.length,
     },
-  }
-}
-
-// eslint-disable-next-line max-params -- Helper function created for organizational purposes
-async function onEnd(
-  response: IncomingMessage,
-  chunks: Uint8Array[],
-  client: Client,
-  startingBalance: number,
-  walletToFund: Wallet,
-  resolve: (response: { wallet: Wallet; balance: number }) => void,
-  reject: (err: ErrorConstructor | Error | unknown) => void,
-): Promise<void> {
-  const body = Buffer.concat(chunks).toString()
+    body: JSON.stringify(postBody),
+  })
 
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- It's a FaucetWallet
+  const body = (await response.json()) as FaucetWallet
   // "application/json; charset=utf-8"
-  if (response.headers['content-type']?.startsWith('application/json')) {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- We know this is safe and correct
-    const faucetWallet: FaucetWallet = JSON.parse(body)
-    const classicAddress = faucetWallet.account.classicAddress
-    await processSuccessfulResponse(
+  if (
+    response.ok &&
+    response.headers.get('Content-Type')?.startsWith('application/json')
+  ) {
+    const classicAddress = body.account.classicAddress
+    return processSuccessfulResponse(
       client,
       classicAddress,
       walletToFund,
       startingBalance,
-      resolve,
-      reject,
-    )
-  } else {
-    reject(
-      new XRPLFaucetError(
-        `Content type is not \`application/json\`: ${JSON.stringify({
-          statusCode: response.statusCode,
-          contentType: response.headers['content-type'],
-          body,
-        })}`,
-      ),
     )
   }
+  return processError(response)
 }
 
-// eslint-disable-next-line max-params, max-lines-per-function -- Only used as a helper function, lines inc due to added balance.
+// eslint-disable-next-line max-params -- Only used as a helper function, lines inc due to added balance.
 async function processSuccessfulResponse(
   client: Client,
   classicAddress: string | undefined,
   walletToFund: Wallet,
   startingBalance: number,
-  resolve: (response: { wallet: Wallet; balance: number }) => void,
-  reject: (err: ErrorConstructor | Error | unknown) => void,
-): Promise<void> {
+): Promise<{
+  wallet: Wallet
+  balance: number
+}> {
   if (!classicAddress) {
-    reject(new XRPLFaucetError(`The faucet account is undefined`))
-    return
+    return Promise.reject(
+      new XRPLFaucetError(`The faucet account is undefined`),
+    )
   }
   try {
     // Check at regular interval if the address is enabled on the XRPL and funded
@@ -265,31 +200,37 @@ async function processSuccessfulResponse(
     )
 
     if (updatedBalance > startingBalance) {
-      resolve({
+      return {
         wallet: walletToFund,
-        balance: await getUpdatedBalance(
-          client,
-          walletToFund.classicAddress,
-          startingBalance,
-        ),
-      })
-    } else {
-      reject(
-        new XRPLFaucetError(
-          `Unable to fund address with faucet after waiting ${
-            INTERVAL_SECONDS * MAX_ATTEMPTS
-          } seconds`,
-        ),
-      )
+        balance: updatedBalance,
+      }
     }
+    throw new XRPLFaucetError(
+      `Unable to fund address with faucet after waiting ${
+        INTERVAL_SECONDS * MAX_ATTEMPTS
+      } seconds`,
+    )
   } catch (err) {
     if (err instanceof Error) {
-      reject(new XRPLFaucetError(err.message))
+      throw new XRPLFaucetError(err.message)
     }
-    reject(err)
+    throw err
   }
 }
 
+async function processError(response: Response): Promise<never> {
+  return Promise.reject(
+    new XRPLFaucetError(
+      `Request failed: ${JSON.stringify({
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- json response could be anything
+        body: (await response.json()) || {},
+        contentType: response.headers.get('Content-Type'),
+        statusCode: response.status,
+      })}`,
+    ),
+  )
+}
+
 /**
  * Check at regular interval if the address is enabled on the XRPL and funded.
  *
@@ -340,5 +281,3 @@ async function getUpdatedBalance(
     }, INTERVAL_SECONDS * 1000)
   })
 }
-
-export default fundWallet