@bithomp/xrpl-api 2.3.6

package/README.md

@@ -0,0 +1,101 @@
+# @Bithomp/xrpl-api
+
+A Bithomp JavaScript/TypeScript library for interacting with the XRP Ledger
+Library designed to be a single point of access to the XRP Ledger. It uses multiple connections to the XRP Ledger and selects the best one for the request. If the connection is lost, the library will automatically reconnect.
+
+The library also supports the creation of a validator list.
+
+In an existing project (with `package.json`), install `@bithomp/xrpl-api`:
+
+```Shell
+# install package
+$ npm install --save @bithomp/xrpl-api
+```
+
+# Example of use
+
+## Account info
+
+```JS
+const BithompXRPL = require("@bithomp/xrpl-api");
+
+// setup connection
+const config = [
+  {
+    "url": "wss://xrplcluster.com",
+    "type": "regular,history,gateway_balances,last_close,manifest",
+    "connectionTimeout": 10000
+  },
+  {
+    "url": "wss://s2.ripple.com",
+    "type": "regular,history",
+    "connectionTimeout": 10000
+  },
+  {
+    "url": "wss://s2-clio.ripple.com",
+    "type": "clio,account_objects",
+    "connectionTimeout": 10000
+  }
+];
+
+// Global setup for all connections, if you have multiple connections, like in example, the library will use them by type and(or) by better response time
+BithompXRPL.Client.setup(config);
+
+// connect to all servers
+await BithompXRPL.Client.connect();
+
+// send request
+const accountInfo = await BithompXRPL.Client.getAccountInfo("rsuUjfWxrACCAwGQDsNeZUhpzXf1n1NK5Z");
+
+// when complete, disconnect
+BithompXRPL.Client.disconnect();
+```
+
+## Create Validator List
+
+_Setup connection_, it is required to get validators details from the ledger.
+
+```JS
+const BithompXRPL = require("@bithomp/xrpl-api");
+// setup connection
+const config = [
+  {
+    "url": "wss://xrplcluster.com",
+    "connectionTimeout": 10000
+  }
+];
+BithompXRPL.Client.setup(config);
+
+// connect
+await BithompXRPL.Client.connect();
+
+// validator secrets
+const vk = {
+  privateKey: "p__________________________",
+  publicKey: "ED________________________________",
+};
+
+// signing secrets
+const sk = {
+  privateKey: "p__________________________",
+  publicKey: "03_______________________________",
+};
+
+// validator list, public addresses, they have to be avalable on the ledger for accessing to manifest
+const validators = ["nHBidG3pZK11zQD6kpNDoAhDxH6WLGui6ZxSbUx7LSqLHsgzMPec"];
+const sequence = 1; // sequence number
+const expiration = 1696508603; // in unixtime (seconds)
+const vl = await BithompXRPL.Client.createVL(vk, sk, sequence, expiration, validators);
+
+// vl will contain the signed validator list with
+// {
+//   "blob": "...",
+//   "manifest": "...", // signed with vk.privateKey and sk.privateKey
+//   "signature": "...", // signed with sk.privateKey
+//   "version": 1,
+//   "public_key": "..." // vk.publicKey
+// }
+
+//  disconnect
+BithompXRPL.Client.disconnect();
+```

package/lib/base58.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="node" />
+export declare function decode(value: string): null | Buffer;
+export declare function encode(buffer: Buffer | number[] | Uint8Array): null | string;

package/lib/base58.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encode = exports.decode = void 0;
+const R_B58_DICT = "rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz";
+const base_x_1 = __importDefault(require("base-x"));
+const base58 = (0, base_x_1.default)(R_B58_DICT);
+function decode(value) {
+    if (!value) {
+        return null;
+    }
+    try {
+        return Buffer.from(base58.decode(value));
+    }
+    catch (e) {
+    }
+    return null;
+}
+exports.decode = decode;
+function encode(buffer) {
+    if (!buffer) {
+        return null;
+    }
+    try {
+        return base58.encode(buffer);
+    }
+    catch (e) {
+    }
+    return null;
+}
+exports.encode = encode;

package/lib/client.d.ts

@@ -0,0 +1,19 @@
+import { Connection, ConnectionOptions } from "./connection";
+export * from "./ledger";
+export declare let feeCushion: number;
+export declare let logger: any;
+export interface ClientOptions extends ConnectionOptions {
+    feeCushion?: number;
+    maxFeeXRP?: string;
+    logger?: any;
+}
+export interface ClientConnection {
+    url: string;
+    type?: string;
+    timeout?: number;
+    connectionTimeout?: number;
+}
+export declare function setup(servers: ClientConnection[], options?: ClientOptions): void;
+export declare function connect(): Promise<void>;
+export declare function disconnect(): void;
+export declare function findConnection(type?: string, url?: string, strongFilter?: boolean, hash?: string): Connection | null;

package/lib/client.js

@@ -0,0 +1,122 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findConnection = exports.disconnect = exports.connect = exports.setup = exports.logger = exports.feeCushion = void 0;
+const connection_1 = require("./connection");
+__exportStar(require("./ledger"), exports);
+exports.feeCushion = 1.3;
+let clientConnections = [];
+function setup(servers, options = {}) {
+    exports.logger = options.logger;
+    exports.logger?.debug({
+        service: "Bithomp::XRPL::Client",
+        function: "setup",
+    });
+    if (servers) {
+        disconnect();
+        clientConnections = [];
+        for (const server of servers) {
+            clientConnections.push(new connection_1.Connection(server.url, server.type, {
+                logger: options.logger,
+                timeout: server.timeout,
+                connectionTimeout: server.connectionTimeout,
+            }));
+        }
+    }
+    if (options.feeCushion) {
+        exports.feeCushion = options.feeCushion;
+    }
+}
+exports.setup = setup;
+async function connect() {
+    exports.logger?.debug({
+        service: "Bithomp::XRPL::Client",
+        function: "connect",
+    });
+    for (const connection of clientConnections) {
+        await connection.connect();
+    }
+}
+exports.connect = connect;
+function disconnect() {
+    exports.logger?.debug({
+        service: "Bithomp::XRPL::Client",
+        function: "disconnect",
+    });
+    for (const connection of clientConnections) {
+        connection.disconnect();
+    }
+}
+exports.disconnect = disconnect;
+function findConnection(type, url, strongFilter, hash) {
+    if (!strongFilter) {
+        if (clientConnections.length === 0) {
+            return null;
+        }
+        else if (clientConnections.length === 1) {
+            return clientConnections[0];
+        }
+    }
+    let connections = clientConnections.filter((con) => {
+        if (!con.isConnected()) {
+            return false;
+        }
+        if (typeof url === "string" && con.url !== url) {
+            return false;
+        }
+        if (typeof hash === "string" && con.hash !== hash) {
+            return false;
+        }
+        if (typeof type !== "string") {
+            return true;
+        }
+        if (con.types.length === 0) {
+            return false;
+        }
+        const foundTypes = type.split(",").map((t) => {
+            t = t.trim();
+            if (t[0] === "!") {
+                return !con.types.includes(t.slice(1));
+            }
+            else {
+                return con.types.includes(t);
+            }
+        });
+        for (const found of foundTypes) {
+            if (!found) {
+                return false;
+            }
+        }
+        return true;
+    });
+    if (!strongFilter) {
+        if (connections.length === 0) {
+            connections = [...clientConnections];
+        }
+    }
+    connections = connections.sort(sortHelperConnections);
+    return connections[0];
+}
+exports.findConnection = findConnection;
+function sortHelperConnections(a, b) {
+    if (a.getLatencyMs() < b.getLatencyMs()) {
+        return -1;
+    }
+    if (a.getLatencyMs() > b.getLatencyMs()) {
+        return 1;
+    }
+    return 0;
+}

package/lib/common/errors/index.d.ts

@@ -0,0 +1,3 @@
+import { RippleError } from "./ripple_error";
+import { ValidationError } from "./validation_error";
+export { RippleError, ValidationError };

package/lib/common/errors/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = exports.RippleError = void 0;
+const ripple_error_1 = require("./ripple_error");
+Object.defineProperty(exports, "RippleError", { enumerable: true, get: function () { return ripple_error_1.RippleError; } });
+const validation_error_1 = require("./validation_error");
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return validation_error_1.ValidationError; } });

package/lib/common/errors/ripple_error.d.ts

@@ -0,0 +1,9 @@
+declare class RippleError extends Error {
+    name: string;
+    message: string;
+    data?: any;
+    constructor(message?: string, data?: any);
+    toString(): string;
+    inspect(): string;
+}
+export { RippleError };

package/lib/common/errors/ripple_error.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RippleError = void 0;
+const util_1 = require("util");
+const utils_1 = require("./utils");
+class RippleError extends Error {
+    constructor(message = "", data) {
+        super(message);
+        this.name = (0, utils_1.getConstructorName)(this);
+        this.message = message;
+        this.data = data;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    toString() {
+        let result = "[" + this.name + "(" + this.message;
+        if (this.data) {
+            result += ", " + (0, util_1.inspect)(this.data);
+        }
+        result += ")]";
+        return result;
+    }
+    inspect() {
+        return this.toString();
+    }
+}
+exports.RippleError = RippleError;

package/lib/common/errors/utils.d.ts

@@ -0,0 +1,2 @@
+declare function getConstructorName(object: object): string | undefined;
+export { getConstructorName };

package/lib/common/errors/utils.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConstructorName = void 0;
+function getConstructorName(object) {
+    if (object.constructor.name) {
+        return object.constructor.name;
+    }
+    const constructorString = object.constructor.toString();
+    const functionConstructor = constructorString.match(/^function\s+([^(]*)/);
+    const classConstructor = constructorString.match(/^class\s([^\s]*)/);
+    if (functionConstructor) {
+        return functionConstructor[1];
+    }
+    else if (classConstructor) {
+        return classConstructor[1];
+    }
+    return undefined;
+}
+exports.getConstructorName = getConstructorName;

package/lib/common/errors/validation_error.d.ts

@@ -0,0 +1,4 @@
+import { RippleError } from "./ripple_error";
+declare class ValidationError extends RippleError {
+}
+export { ValidationError };

package/lib/common/errors/validation_error.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = void 0;
+const ripple_error_1 = require("./ripple_error");
+class ValidationError extends ripple_error_1.RippleError {
+}
+exports.ValidationError = ValidationError;

package/lib/common/index.d.ts

@@ -0,0 +1,6 @@
+import * as errors from "./errors";
+import sha512Half from "./sha512Half";
+export * from "./utils";
+export { errors, sha512Half };
+export declare const dropsInXRP = 1000000;
+export declare const BLACKHOLE_ACCOUNTS: string[];

package/lib/common/index.js

@@ -0,0 +1,44 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BLACKHOLE_ACCOUNTS = exports.dropsInXRP = exports.sha512Half = exports.errors = void 0;
+const errors = __importStar(require("./errors"));
+exports.errors = errors;
+const sha512Half_1 = __importDefault(require("./sha512Half"));
+exports.sha512Half = sha512Half_1.default;
+__exportStar(require("./utils"), exports);
+exports.dropsInXRP = 1000000;
+exports.BLACKHOLE_ACCOUNTS = [
+    "rrrrrrrrrrrrrrrrrrrrrhoLvTp",
+    "rrrrrrrrrrrrrrrrrrrrBZbvji",
+    "rrrrrrrrrrrrrrrrrNAMEtxvNvQ",
+    "rrrrrrrrrrrrrrrrrrrn5RM1rHd",
+];

package/lib/common/sha512Half.d.ts

@@ -0,0 +1,2 @@
+declare function sha512Half(hex: string): string;
+export default sha512Half;

package/lib/common/sha512Half.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const crypto_1 = require("crypto");
+const HASH_SIZE = 64;
+function sha512Half(hex) {
+    return (0, crypto_1.createHash)('sha512')
+        .update(Buffer.from(hex, 'hex'))
+        .digest('hex')
+        .toUpperCase()
+        .slice(0, HASH_SIZE);
+}
+exports.default = sha512Half;

package/lib/common/utils.d.ts

@@ -0,0 +1,10 @@
+import BigNumber from "bignumber.js";
+export type SortDirection = -1 | 0 | 1;
+export declare function signum(num: number): SortDirection;
+export declare function compareTransactions(first: any, second: any): SortDirection;
+export declare function sleep(ms: number): Promise<void>;
+export declare function createMarker(hash: string, marker?: any): any;
+export declare function parseMarker(marker?: any): any;
+export declare function dropsToXrp(drops: BigNumber.Value): string;
+export declare function xrpToDrops(xrp: BigNumber.Value): string;
+export declare function removeUndefined<T extends object>(obj: T): T;

package/lib/common/utils.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeUndefined = exports.xrpToDrops = exports.dropsToXrp = exports.parseMarker = exports.createMarker = exports.sleep = exports.compareTransactions = exports.signum = void 0;
+const lodash_1 = __importDefault(require("lodash"));
+const bignumber_js_1 = __importDefault(require("bignumber.js"));
+const errors_1 = require("./errors");
+function signum(num) {
+    return num === 0 ? 0 : num > 0 ? 1 : -1;
+}
+exports.signum = signum;
+function compareTransactions(first, second) {
+    if (!first.tx || !first.meta || !second.tx || !second.meta) {
+        return 0;
+    }
+    if (first.tx.ledger_index === second.tx.ledger_index) {
+        return signum(first.meta.TransactionIndex - second.meta.TransactionIndex);
+    }
+    return first.tx.ledger_index < second.tx.ledger_index ? -1 : 1;
+}
+exports.compareTransactions = compareTransactions;
+async function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+exports.sleep = sleep;
+function createMarker(hash, marker) {
+    if (marker === undefined) {
+        return undefined;
+    }
+    if (marker === null) {
+        return undefined;
+    }
+    if (typeof marker === "string") {
+        return `${hash},${marker}`;
+    }
+    if (typeof marker === "object") {
+        marker.bithompHash = hash;
+    }
+    return marker;
+}
+exports.createMarker = createMarker;
+function parseMarker(marker) {
+    let hash;
+    if (typeof marker === "object" && marker.bithompHash) {
+        hash = marker.bithompHash;
+        delete marker.bithompHash;
+        return { hash, marker };
+    }
+    if (typeof marker !== "string") {
+        return { hash, marker };
+    }
+    if (marker) {
+        const markerParams = marker.split(",");
+        if (markerParams.length > 1) {
+            hash = markerParams[0];
+            markerParams.shift();
+            marker = markerParams.join(",");
+        }
+    }
+    return { hash, marker };
+}
+exports.parseMarker = parseMarker;
+function dropsToXrp(drops) {
+    if (typeof drops === "string") {
+        if (!drops.match(/^-?[0-9]*\.?[0-9]*$/)) {
+            throw new errors_1.ValidationError(`dropsToXrp: invalid value '${drops}',` + ` should be a number matching (^-?[0-9]*\\.?[0-9]*$).`);
+        }
+        else if (drops === ".") {
+            throw new errors_1.ValidationError(`dropsToXrp: invalid value '${drops}',` + ` should be a BigNumber or string-encoded number.`);
+        }
+    }
+    drops = new bignumber_js_1.default(drops).toString(10);
+    if (drops.includes(".")) {
+        throw new errors_1.ValidationError(`dropsToXrp: value '${drops}' has` + ` too many decimal places.`);
+    }
+    if (!drops.match(/^-?[0-9]+$/)) {
+        throw new errors_1.ValidationError(`dropsToXrp: failed sanity check -` + ` value '${drops}',` + ` does not match (^-?[0-9]+$).`);
+    }
+    return new bignumber_js_1.default(drops).dividedBy(1000000.0).toString(10);
+}
+exports.dropsToXrp = dropsToXrp;
+function xrpToDrops(xrp) {
+    if (typeof xrp === "string") {
+        if (!xrp.match(/^-?[0-9]*\.?[0-9]*$/)) {
+            throw new errors_1.ValidationError(`xrpToDrops: invalid value '${xrp}',` + ` should be a number matching (^-?[0-9]*\\.?[0-9]*$).`);
+        }
+        else if (xrp === ".") {
+            throw new errors_1.ValidationError(`xrpToDrops: invalid value '${xrp}',` + ` should be a BigNumber or string-encoded number.`);
+        }
+    }
+    xrp = new bignumber_js_1.default(xrp).toString(10);
+    if (!xrp.match(/^-?[0-9.]+$/)) {
+        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 > 6) {
+        throw new errors_1.ValidationError(`xrpToDrops: value '${xrp}' has` + ` too many decimal places.`);
+    }
+    return new bignumber_js_1.default(xrp).times(1000000.0).integerValue(bignumber_js_1.default.ROUND_FLOOR).toString(10);
+}
+exports.xrpToDrops = xrpToDrops;
+function removeUndefined(obj) {
+    return lodash_1.default.omitBy(obj, (value) => value == null);
+}
+exports.removeUndefined = removeUndefined;

package/lib/connection.d.ts

@@ -0,0 +1,57 @@
+/// <reference types="node" />
+import { EventEmitter } from "events";
+import { Request, Response } from "xrpl";
+export interface ConnectionOptions {
+    logger?: any;
+    timeout?: number;
+    connectionTimeout?: number;
+}
+export interface LatencyInfo {
+    timestamp: Date;
+    delta: number;
+}
+export interface ConnectionStreamsInfo {
+    ledger: number;
+    consensus?: number;
+    manifests?: number;
+    peer_status?: number;
+    transactions?: number;
+    transactions_proposed?: number;
+    server?: number;
+    validations?: number;
+}
+export interface ConnectionAccountsInfo {
+    [key: string]: number;
+}
+declare class Connection extends EventEmitter {
+    private client?;
+    readonly url: string;
+    readonly type?: string;
+    readonly types: string[];
+    latency: LatencyInfo[];
+    readonly logger?: any;
+    readonly timeout?: number;
+    readonly connectionTimeout?: number;
+    readonly hash?: string;
+    private shutdown;
+    private connectionTimer;
+    streams: ConnectionStreamsInfo;
+    accounts: ConnectionAccountsInfo;
+    private streamsSubscribed;
+    constructor(url: string, type?: string, options?: ConnectionOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    request(request: Request, options?: any): Promise<Response | any>;
+    submit(transaction: string): Promise<Response | any>;
+    isConnected(): boolean;
+    getLatencyMs(): number;
+    private updateLatency;
+    private reconnect;
+    private setupEmitter;
+    private updateSubscriptions;
+    private subscribe;
+    private unsubscribe;
+    private connectionValidation;
+    private connectionValidationTimeout;
+}
+export { Connection };