xrpl 1.0.0-mpt-beta

package/dist/npm/utils/stringConversion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stringConversion.d.ts","sourceRoot":"","sources":["../../../src/utils/stringConversion.ts"],"names":[],"mappings":"AAYA,iBAAS,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAaD,iBAAS,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAS,GAAG,MAAM,CAElE;AAED,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,CAAA"}

package/dist/npm/utils/stringConversion.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertStringToHex = exports.convertHexToString = void 0;
+const utils_1 = require("@xrplf/isomorphic/utils");
+function convertStringToHex(string) {
+    return (0, utils_1.stringToHex)(string);
+}
+exports.convertStringToHex = convertStringToHex;
+function convertHexToString(hex, encoding = 'utf8') {
+    return (0, utils_1.hexToString)(hex, encoding);
+}
+exports.convertHexToString = convertHexToString;
+//# sourceMappingURL=stringConversion.js.map

package/dist/npm/utils/stringConversion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stringConversion.js","sourceRoot":"","sources":["../../../src/utils/stringConversion.ts"],"names":[],"mappings":";;;AAAA,mDAAkE;AAYlE,SAAS,kBAAkB,CAAC,MAAc;IACxC,OAAO,IAAA,mBAAW,EAAC,MAAM,CAAC,CAAA;AAC5B,CAAC;AAiB4B,gDAAkB;AAJ/C,SAAS,kBAAkB,CAAC,GAAW,EAAE,QAAQ,GAAG,MAAM;IACxD,OAAO,IAAA,mBAAW,EAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;AACnC,CAAC;AAEQ,gDAAkB"}

package/dist/npm/utils/timeConversion.d.ts

@@ -0,0 +1,6 @@
+declare function rippleTimeToUnixTime(rpepoch: number): number;
+declare function unixTimeToRippleTime(timestamp: number): number;
+declare function rippleTimeToISOTime(rippleTime: number): string;
+declare function isoTimeToRippleTime(iso8601: string | Date): number;
+export { rippleTimeToUnixTime, unixTimeToRippleTime, rippleTimeToISOTime, isoTimeToRippleTime, };
+//# sourceMappingURL=timeConversion.d.ts.map

package/dist/npm/utils/timeConversion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeConversion.d.ts","sourceRoot":"","sources":["../../../src/utils/timeConversion.ts"],"names":[],"mappings":"AASA,iBAAS,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AASD,iBAAS,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvD;AASD,iBAAS,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvD;AASD,iBAAS,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAG3D;AAED,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,CAAA"}

package/dist/npm/utils/timeConversion.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isoTimeToRippleTime = exports.rippleTimeToISOTime = exports.unixTimeToRippleTime = exports.rippleTimeToUnixTime = void 0;
+const RIPPLE_EPOCH_DIFF = 0x386d4380;
+function rippleTimeToUnixTime(rpepoch) {
+    return (rpepoch + RIPPLE_EPOCH_DIFF) * 1000;
+}
+exports.rippleTimeToUnixTime = rippleTimeToUnixTime;
+function unixTimeToRippleTime(timestamp) {
+    return Math.round(timestamp / 1000) - RIPPLE_EPOCH_DIFF;
+}
+exports.unixTimeToRippleTime = unixTimeToRippleTime;
+function rippleTimeToISOTime(rippleTime) {
+    return new Date(rippleTimeToUnixTime(rippleTime)).toISOString();
+}
+exports.rippleTimeToISOTime = rippleTimeToISOTime;
+function isoTimeToRippleTime(iso8601) {
+    const isoDate = typeof iso8601 === 'string' ? new Date(iso8601) : iso8601;
+    return unixTimeToRippleTime(isoDate.getTime());
+}
+exports.isoTimeToRippleTime = isoTimeToRippleTime;
+//# sourceMappingURL=timeConversion.js.map

package/dist/npm/utils/timeConversion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeConversion.js","sourceRoot":"","sources":["../../../src/utils/timeConversion.ts"],"names":[],"mappings":";;;AAAA,MAAM,iBAAiB,GAAG,UAAU,CAAA;AASpC,SAAS,oBAAoB,CAAC,OAAe;IAC3C,OAAO,CAAC,OAAO,GAAG,iBAAiB,CAAC,GAAG,IAAI,CAAA;AAC7C,CAAC;AAqCC,oDAAoB;AA5BtB,SAAS,oBAAoB,CAAC,SAAiB;IAC7C,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,iBAAiB,CAAA;AACzD,CAAC;AA2BC,oDAAoB;AAlBtB,SAAS,mBAAmB,CAAC,UAAkB;IAC7C,OAAO,IAAI,IAAI,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,EAAE,CAAA;AACjE,CAAC;AAiBC,kDAAmB;AARrB,SAAS,mBAAmB,CAAC,OAAsB;IACjD,MAAM,OAAO,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;IACzE,OAAO,oBAAoB,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;AAChD,CAAC;AAMC,kDAAmB"}

package/dist/npm/utils/verifyPaymentChannelClaim.d.ts

@@ -0,0 +1,3 @@
+declare function verifyPaymentChannelClaim(channel: string, xrpAmount: string, signature: string, publicKey: string): boolean;
+export default verifyPaymentChannelClaim;
+//# sourceMappingURL=verifyPaymentChannelClaim.d.ts.map

package/dist/npm/utils/verifyPaymentChannelClaim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifyPaymentChannelClaim.d.ts","sourceRoot":"","sources":["../../../src/utils/verifyPaymentChannelClaim.ts"],"names":[],"mappings":"AAgBA,iBAAS,yBAAyB,CAChC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAMT;AAED,eAAe,yBAAyB,CAAA"}

package/dist/npm/utils/verifyPaymentChannelClaim.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ripple_binary_codec_1 = require("ripple-binary-codec");
+const ripple_keypairs_1 = require("ripple-keypairs");
+const xrpConversion_1 = require("./xrpConversion");
+function verifyPaymentChannelClaim(channel, xrpAmount, signature, publicKey) {
+    const signingData = (0, ripple_binary_codec_1.encodeForSigningClaim)({
+        channel,
+        amount: (0, xrpConversion_1.xrpToDrops)(xrpAmount),
+    });
+    return (0, ripple_keypairs_1.verify)(signingData, signature, publicKey);
+}
+exports.default = verifyPaymentChannelClaim;
+//# sourceMappingURL=verifyPaymentChannelClaim.js.map

package/dist/npm/utils/verifyPaymentChannelClaim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifyPaymentChannelClaim.js","sourceRoot":"","sources":["../../../src/utils/verifyPaymentChannelClaim.ts"],"names":[],"mappings":";;AAAA,6DAA2D;AAC3D,qDAAwC;AAExC,mDAA4C;AAa5C,SAAS,yBAAyB,CAChC,OAAe,EACf,SAAiB,EACjB,SAAiB,EACjB,SAAiB;IAEjB,MAAM,WAAW,GAAG,IAAA,2CAAqB,EAAC;QACxC,OAAO;QACP,MAAM,EAAE,IAAA,0BAAU,EAAC,SAAS,CAAC;KAC9B,CAAC,CAAA;IACF,OAAO,IAAA,wBAAM,EAAC,WAAW,EAAE,SAAS,EAAE,SAAS,CAAC,CAAA;AAClD,CAAC;AAED,kBAAe,yBAAyB,CAAA"}

package/dist/npm/utils/xrpConversion.d.ts

@@ -0,0 +1,4 @@
+import BigNumber from 'bignumber.js';
+export declare function dropsToXrp(dropsToConvert: BigNumber.Value): number;
+export declare function xrpToDrops(xrpToConvert: BigNumber.Value): string;
+//# sourceMappingURL=xrpConversion.d.ts.map

package/dist/npm/utils/xrpConversion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xrpConversion.d.ts","sourceRoot":"","sources":["../../../src/utils/xrpConversion.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,cAAc,CAAA;AAiBpC,wBAAgB,UAAU,CAAC,cAAc,EAAE,SAAS,CAAC,KAAK,GAAG,MAAM,CAoClE;AAUD,wBAAgB,UAAU,CAAC,YAAY,EAAE,SAAS,CAAC,KAAK,GAAG,MAAM,CAwChE"}

package/dist/npm/utils/xrpConversion.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.xrpToDrops = exports.dropsToXrp = void 0;
+const bignumber_js_1 = __importDefault(require("bignumber.js"));
+const errors_1 = require("../errors");
+const DROPS_PER_XRP = 1000000.0;
+const MAX_FRACTION_LENGTH = 6;
+const BASE_TEN = 10;
+const SANITY_CHECK = /^-?[0-9.]+$/u;
+function dropsToXrp(dropsToConvert) {
+    const drops = new bignumber_js_1.default(dropsToConvert).toString(BASE_TEN);
+    if (typeof dropsToConvert === 'string' && drops === 'NaN') {
+        throw new errors_1.ValidationError(`dropsToXrp: invalid value '${dropsToConvert}', should be a BigNumber or string-encoded number.`);
+    }
+    if (drops.includes('.')) {
+        throw new errors_1.ValidationError(`dropsToXrp: value '${drops}' has too many decimal places.`);
+    }
+    if (!SANITY_CHECK.exec(drops)) {
+        throw new errors_1.ValidationError(`dropsToXrp: failed sanity check -` +
+            ` value '${drops}',` +
+            ` does not match (^-?[0-9]+$).`);
+    }
+    return new bignumber_js_1.default(drops).dividedBy(DROPS_PER_XRP).toNumber();
+}
+exports.dropsToXrp = dropsToXrp;
+function xrpToDrops(xrpToConvert) {
+    const xrp = new bignumber_js_1.default(xrpToConvert).toString(BASE_TEN);
+    if (typeof xrpToConvert === 'string' && xrp === 'NaN') {
+        throw new errors_1.ValidationError(`xrpToDrops: invalid value '${xrpToConvert}', should be a BigNumber or string-encoded number.`);
+    }
+    if (!SANITY_CHECK.exec(xrp)) {
+        throw new errors_1.ValidationError(`xrpToDrops: failed sanity check - value '${xrp}', does not match (^-?[0-9.]+$).`);
+    }
+    const components = xrp.split('.');
+    if (components.length > 2) {
+        throw new errors_1.ValidationError(`xrpToDrops: failed sanity check - value '${xrp}' has too many decimal points.`);
+    }
+    const fraction = components[1] || '0';
+    if (fraction.length > MAX_FRACTION_LENGTH) {
+        throw new errors_1.ValidationError(`xrpToDrops: value '${xrp}' has too many decimal places.`);
+    }
+    return new bignumber_js_1.default(xrp)
+        .times(DROPS_PER_XRP)
+        .integerValue(bignumber_js_1.default.ROUND_FLOOR)
+        .toString(BASE_TEN);
+}
+exports.xrpToDrops = xrpToDrops;
+//# sourceMappingURL=xrpConversion.js.map

package/dist/npm/utils/xrpConversion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xrpConversion.js","sourceRoot":"","sources":["../../../src/utils/xrpConversion.ts"],"names":[],"mappings":";;;;;;AAAA,gEAAoC;AAEpC,sCAA2C;AAE3C,MAAM,aAAa,GAAG,SAAS,CAAA;AAC/B,MAAM,mBAAmB,GAAG,CAAC,CAAA;AAC7B,MAAM,QAAQ,GAAG,EAAE,CAAA;AACnB,MAAM,YAAY,GAAG,cAAc,CAAA;AAUnC,SAAgB,UAAU,CAAC,cAA+B;IAMxD,MAAM,KAAK,GAAG,IAAI,sBAAS,CAAC,cAAc,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAG9D,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,KAAK,KAAK,KAAK,EAAE;QACzD,MAAM,IAAI,wBAAe,CACvB,8BAA8B,cAAc,oDAAoD,CACjG,CAAA;KACF;IAGD,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;QACvB,MAAM,IAAI,wBAAe,CACvB,sBAAsB,KAAK,gCAAgC,CAC5D,CAAA;KACF;IAOD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;QAC7B,MAAM,IAAI,wBAAe,CACvB,mCAAmC;YACjC,WAAW,KAAK,IAAI;YACpB,+BAA+B,CAClC,CAAA;KACF;IAED,OAAO,IAAI,sBAAS,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE,CAAA;AACjE,CAAC;AApCD,gCAoCC;AAUD,SAAgB,UAAU,CAAC,YAA6B;IAEtD,MAAM,GAAG,GAAG,IAAI,sBAAS,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAG1D,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,GAAG,KAAK,KAAK,EAAE;QACrD,MAAM,IAAI,wBAAe,CACvB,8BAA8B,YAAY,oDAAoD,CAC/F,CAAA;KACF;IAOD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;QAC3B,MAAM,IAAI,wBAAe,CACvB,4CAA4C,GAAG,kCAAkC,CAClF,CAAA;KACF;IAED,MAAM,UAAU,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACjC,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE;QACzB,MAAM,IAAI,wBAAe,CACvB,4CAA4C,GAAG,gCAAgC,CAChF,CAAA;KACF;IAED,MAAM,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,IAAI,GAAG,CAAA;IACrC,IAAI,QAAQ,CAAC,MAAM,GAAG,mBAAmB,EAAE;QACzC,MAAM,IAAI,wBAAe,CACvB,sBAAsB,GAAG,gCAAgC,CAC1D,CAAA;KACF;IAED,OAAO,IAAI,sBAAS,CAAC,GAAG,CAAC;SACtB,KAAK,CAAC,aAAa,CAAC;SACpB,YAAY,CAAC,sBAAS,CAAC,WAAW,CAAC;SACnC,QAAQ,CAAC,QAAQ,CAAC,CAAA;AACvB,CAAC;AAxCD,gCAwCC"}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "xrpl",
+  "version": "1.0.0-mpt-beta",
+  "license": "ISC",
+  "description": "A TypeScript/JavaScript API for interacting with the XRP Ledger in Node.js and the browser",
+  "files": [
+    "build/xrpl-latest-min.js",
+    "build/xrpl-latest-min.js.map",
+    "build/xrpl-latest.js",
+    "build/xrpl-latest.js.map",
+    "dist/npm/*",
+    "src/*"
+  ],
+  "main": "dist/npm/",
+  "unpkg": "build/xrpl-latest-min.js",
+  "jsdelivr": "build/xrpl-latest-min.js",
+  "types": "dist/npm/index.d.ts",
+  "directories": {
+    "test": "test"
+  },
+  "browser": {
+    "ws": "./dist/npm/client/WSWrapper.js"
+  },
+  "dependencies": {
+    "@scure/bip32": "^1.3.1",
+    "@scure/bip39": "^1.2.1",
+    "@xrplf/isomorphic": "^1.0.0",
+    "@xrplf/secret-numbers": "^1.0.0",
+    "bignumber.js": "^9.0.0",
+    "cross-fetch": "^4.0.0",
+    "eventemitter3": "^5.0.1",
+    "ripple-address-codec": "^5.0.0",
+    "ripple-binary-codec": "^1.0.0-mpt-beta",
+    "ripple-keypairs": "^2.0.0"
+  },
+  "devDependencies": {
+    "@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",
+    "lodash": "^4.17.4",
+    "react": "^18.2.0",
+    "run-s": "^0.0.0",
+    "typedoc": "0.25.0",
+    "ws": "^8.14.2"
+  },
+  "resolutions": {
+    "elliptic": "^6.5.4"
+  },
+  "scripts": {
+    "build": "run-s build:lib build:snippets build:web",
+    "build:snippets": "tsc --build ./snippets/tsconfig.json",
+    "build:lib": "tsc --build tsconfig.build.json",
+    "build:web": "webpack",
+    "build:browserTests": "webpack --config ./test/webpack.config.js",
+    "analyze": "webpack --analyze",
+    "watch": "run-s build:lib --watch",
+    "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",
+    "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",
+    "perf": "./scripts/perf_test.sh",
+    "compile:snippets": "tsc -p snippets/tsconfig.json",
+    "start:snippet": "npm run compile:snippets && node",
+    "inspect:snippet": "npm run compile:snippets && node inspect"
+  },
+  "prettier": "@xrplf/prettier-config",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:XRPLF/xrpl.js.git"
+  },
+  "readmeFilename": "README.md",
+  "keywords": [
+    "ripple-lib",
+    "ripple",
+    "xrp",
+    "xrp ledger",
+    "xrpl"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "gitHead": "a9d5a9bf98cc25ebd788f6c02a64f82c20b5b06a"
+}

package/src/ECDSA.ts

@@ -0,0 +1,6 @@
+enum ECDSA {
+  ed25519 = 'ed25519',
+  secp256k1 = 'ecdsa-secp256k1',
+}
+
+export default ECDSA

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

@@ -0,0 +1,70 @@
+import type { Client } from '../client'
+import { XRPLFaucetError } from '../errors'
+
+export interface FaucetWallet {
+  account: {
+    xAddress: string
+    classicAddress?: string
+    secret: string
+  }
+  amount: number
+  balance: number
+}
+
+export enum FaucetNetwork {
+  Testnet = 'faucet.altnet.rippletest.net',
+  Devnet = 'faucet.devnet.rippletest.net',
+  HooksV3Testnet = 'hooks-testnet-v3.xrpl-labs.com',
+}
+
+export const FaucetNetworkPaths: Record<string, string> = {
+  [FaucetNetwork.Testnet]: '/accounts',
+  [FaucetNetwork.Devnet]: '/accounts',
+  [FaucetNetwork.HooksV3Testnet]: '/accounts',
+}
+
+/**
+ * Get the faucet host based on the Client connection.
+ *
+ * @param client - Client.
+ * @returns A {@link FaucetNetwork}.
+ * @throws When the client url is not on altnet or devnet.
+ */
+export function getFaucetHost(client: Client): FaucetNetwork | undefined {
+  const connectionUrl = client.url
+
+  if (connectionUrl.includes('hooks-testnet-v3')) {
+    return FaucetNetwork.HooksV3Testnet
+  }
+
+  // 'altnet' for Ripple Testnet server and 'testnet' for XRPL Labs Testnet server
+  if (connectionUrl.includes('altnet') || connectionUrl.includes('testnet')) {
+    return FaucetNetwork.Testnet
+  }
+
+  if (connectionUrl.includes('sidechain-net2')) {
+    throw new XRPLFaucetError(
+      'Cannot fund an account on an issuing chain. Accounts must be created via the bridge.',
+    )
+  }
+
+  if (connectionUrl.includes('devnet')) {
+    return FaucetNetwork.Devnet
+  }
+
+  throw new XRPLFaucetError('Faucet URL is not defined or inferrable.')
+}
+
+/**
+ * Get the faucet pathname based on the faucet hostname.
+ *
+ * @param hostname - hostname.
+ * @returns A String with the correct path for the input hostname.
+ * If hostname undefined or cannot find (key, value) pair in {@link FaucetNetworkPaths}, defaults to '/accounts'
+ */
+export function getDefaultFaucetPath(hostname: string | undefined): string {
+  if (hostname === undefined) {
+    return '/accounts'
+  }
+  return FaucetNetworkPaths[hostname] || '/accounts'
+}

package/src/Wallet/fundWallet.ts

@@ -0,0 +1,283 @@
+import fetch from 'cross-fetch'
+import { isValidClassicAddress } from 'ripple-address-codec'
+
+import type { Client } from '../client'
+import { XRPLFaucetError } from '../errors'
+
+import {
+  FaucetWallet,
+  getFaucetHost,
+  getDefaultFaucetPath,
+} from './defaultFaucets'
+
+import { Wallet } from '.'
+
+// Interval to check an account balance
+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
+}
+
+/**
+ * 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.
+ *
+ * @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.
+ *
+ * @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
+}
+
+/**
+ *
+ * Helper function to request funding from a faucet. Should not be called directly from outside the xrpl.js library.
+ *
+ * @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,
+ * or if you would like to customize the faucet host in devnet or testnet,
+ * you should provide the host using this option.
+ * @param options.faucetPath - 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.
+ * @param options.amount - A custom amount to fund, if undefined or null, the default amount will be 1000.
+ * @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-params -- Helper function created for organizational purposes
+export async function requestFunding(
+  options: FundingOptions,
+  client: Client,
+  startingBalance: number,
+  walletToFund: Wallet,
+  postBody: FaucetRequestBody,
+): Promise<{
+  wallet: Wallet
+  balance: number
+}> {
+  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',
+    },
+    body: JSON.stringify(postBody),
+  })
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- it can be anything
+  const body = await response.json()
+  if (
+    response.ok &&
+    response.headers.get('Content-Type')?.startsWith('application/json')
+  ) {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- It's a FaucetWallet
+    const classicAddress = (body as FaucetWallet).account.classicAddress
+    return processSuccessfulResponse(
+      client,
+      classicAddress,
+      walletToFund,
+      startingBalance,
+    )
+  }
+  return processError(response, body)
+}
+
+// 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,
+): Promise<{
+  wallet: Wallet
+  balance: number
+}> {
+  if (!classicAddress) {
+    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
+    const updatedBalance = await getUpdatedBalance(
+      client,
+      classicAddress,
+      startingBalance,
+    )
+
+    if (updatedBalance > startingBalance) {
+      return {
+        wallet: walletToFund,
+        balance: updatedBalance,
+      }
+    }
+    throw new XRPLFaucetError(
+      `Unable to fund address with faucet after waiting ${
+        INTERVAL_SECONDS * MAX_ATTEMPTS
+      } seconds`,
+    )
+  } catch (err) {
+    if (err instanceof Error) {
+      throw new XRPLFaucetError(err.message)
+    }
+    throw err
+  }
+}
+
+async function processError(response: Response, body): 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: body || {},
+        contentType: response.headers.get('Content-Type'),
+        statusCode: response.status,
+      })}`,
+    ),
+  )
+}
+
+/**
+ * Check at regular interval if the address is enabled on the XRPL and funded.
+ *
+ * @param client - Client.
+ * @param address - The account address to check.
+ * @param originalBalance - The initial balance before the funding.
+ * @returns A Promise boolean.
+ */
+async function getUpdatedBalance(
+  client: Client,
+  address: string,
+  originalBalance: number,
+): Promise<number> {
+  return new Promise((resolve, reject) => {
+    let attempts = MAX_ATTEMPTS
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- Not actually misused here, different resolve
+    const interval = setInterval(async () => {
+      if (attempts < 0) {
+        clearInterval(interval)
+        resolve(originalBalance)
+      } else {
+        attempts -= 1
+      }
+
+      try {
+        let newBalance
+        try {
+          newBalance = Number(await client.getXrpBalance(address))
+        } catch {
+          /* newBalance remains undefined */
+        }
+
+        if (newBalance > originalBalance) {
+          clearInterval(interval)
+          resolve(newBalance)
+        }
+      } catch (err) {
+        clearInterval(interval)
+        if (err instanceof Error) {
+          reject(
+            new XRPLFaucetError(
+              `Unable to check if the address ${address} balance has increased. Error: ${err.message}`,
+            ),
+          )
+        }
+        reject(err)
+      }
+    }, INTERVAL_SECONDS * 1000)
+  })
+}