dhali-js 1.0.0

package/.github/workflows/publish.yaml

@@ -0,0 +1,28 @@
+name: Publish to npm
+
+# Trigger on any semver tag push (e.g. v1.2.3)
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18.x
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

package/.github/workflows/tests.yaml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22.x]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test

package/.prettierignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dhali
+
+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.

package/README.md

@@ -0,0 +1,93 @@
+# dhali-js
+
+A JavaScript library for managing XRPL payment channels and generating auth tokens for use with [Dhali](https://dhali.io) APIs.  
+Leverages [xrpl.js](https://github.com/XRPLF/xrpl.js) and **only ever performs local signing**—your private key never leaves your environment.
+
+---
+
+## Installation
+
+```bash
+npm install dhali-js
+````
+
+---
+
+## Quick Start
+
+```js
+import { Wallet, Client } from 'xrpl'
+import {
+  ChannelNotFound,
+  DhaliChannelManager
+} from 'dhali-js'
+
+// 1. Load your wallet from secret
+const seed = 'sXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+const wallet = Wallet.fromSeed(seed)
+
+// 2. Create the manager (connects automatically under the hood)
+const dhaliManager = new DhaliChannelManager(wallet)
+
+async function getPaymentClaim() {
+  try {
+    // Get an auth token
+    return await dhaliManager.getAuthToken()
+  } catch (err) {
+    if (err instanceof ChannelNotFound) {
+      // If no channel exists, create one with 1 XRP (1 000 000 drops)
+      await dhaliManager.deposit(1_000_000)
+      return await dhaliManager.getAuthToken()
+    }
+    throw err
+  }
+}
+
+;(async () => {
+  for (let i = 0; i < 2; i++) {
+    const token = await getPaymentClaim()
+    const url = `https://xrplcluster.dhali.io?payment-claim=${token}`
+    // ... use token in your fetch/post to Dhali API ...
+  }
+})()
+```
+
+---
+
+## API
+
+### `new DhaliChannelManager(wallet: xrpl.Wallet)`
+
+* **wallet**: an `xrpl.js` `Wallet` instance (e.g. `Wallet.fromSeed`).
+
+---
+
+### `async deposit(amountDrops: number) → Promise<object>`
+
+* **amountDrops**: Number of XRP drops (e.g. `1_000_000` = 1 XRP).
+* **Returns**: The JSON result of the `PaymentChannelCreate` or `PaymentChannelFund` transaction.
+
+---
+
+### `async getAuthToken(amountDrops?: number) → Promise<string>`
+
+* **amountDrops** (optional): How many drops to authorize; defaults to full channel balance.
+* **Returns**: A base64-encoded JSON string containing your signed claim.
+* **Throws**:
+
+  * `ChannelNotFound` if there is no open channel.
+  * `Error` if `amountDrops` exceeds channel capacity.
+
+---
+
+## Errors
+
+* **ChannelNotFound**
+  Thrown when `getAuthToken` finds no channel from your wallet to Dhali’s receiver.
+
+---
+
+## Security
+
+All XRPL interactions and claim-signatures are done locally via `xrpl.js` + `ripple-keypairs`.
+Your private key never leaves your machine.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "dhali-js",
+  "version": "1.0.0",
+  "description": "A JavaScript library for managing XRPL payment channels and generating auth tokens for Dhali APIs",
+  "main": "src/index.js",
+  "type": "commonjs",
+  "scripts": {
+    "test": "jest",
+    "format": "prettier --write \"src/**/*.js\" \"tests/**/*.js\""
+  },
+  "keywords": [
+    "xrpl",
+    "payment-channel",
+    "dhali",
+    "xrpl.js"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "ripple-keypairs": "^2.0.0",
+    "xrpl": "^4.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.0.0",
+    "prettier": "^3.5.3"
+  }
+}

package/src/dhali/DhaliChannelManager.js

@@ -0,0 +1,110 @@
+const { Client } = require("xrpl");
+const { buildPaychanAuthHexStringToBeSigned } = require("./createSignedClaim");
+const { sign: signClaim } = require("ripple-keypairs");
+
+class ChannelNotFound extends Error {}
+
+/**
+ * A management tool for generating payment claims for use with Dhali APIs.
+ */
+class DhaliChannelManager {
+  /**
+   * @param {xrpl.Wallet} wallet
+   */
+  constructor(wallet) {
+    this.client = new Client("wss://s1.ripple.com:51234/");
+    this.ready = this.client.connect();
+    this.wallet = wallet;
+    this.destination = "rLggTEwmTe3eJgyQbCSk4wQazow2TeKrtR";
+    this.protocol = "XRPL.MAINNET";
+  }
+
+  async _findChannel() {
+    await this.ready;
+    const resp = await this.client.request({
+      command: "account_channels",
+      account: this.wallet.classicAddress,
+      destination_account: this.destination,
+      ledger_index: "validated",
+    });
+    const channels = resp.result.channels || [];
+    if (channels.length === 0) {
+      throw new ChannelNotFound(
+        `No open payment channel from ${this.wallet.classicAddress} to ${this.destination}`,
+      );
+    }
+    return channels[0];
+  }
+
+  /**
+   * Create or fund a payment channel.
+   * @param {number} amountDrops
+   * @returns {Promise<object>}
+   */
+  async deposit(amountDrops) {
+    await this.ready;
+    let tx;
+    try {
+      const ch = await this._findChannel();
+      tx = {
+        TransactionType: "PaymentChannelFund",
+        Account: this.wallet.classicAddress,
+        Channel: ch.channel_id,
+        Amount: amountDrops.toString(),
+      };
+    } catch (err) {
+      if (!(err instanceof ChannelNotFound)) throw err;
+      tx = {
+        TransactionType: "PaymentChannelCreate",
+        Account: this.wallet.classicAddress,
+        Destination: this.destination,
+        Amount: amountDrops.toString(),
+        SettleDelay: 86400 * 14,
+        PublicKey: this.wallet.publicKey,
+      };
+    }
+    // autofill sequence, fee, etc.
+    const prepared = await this.client.autofill(tx);
+    // sign
+    const signed = this.wallet.sign(prepared);
+    const txBlob = signed.tx_blob || signed.signedTransaction;
+    // submit & wait
+    const result = await this.client.submitAndWait(txBlob);
+    return result.result;
+  }
+
+  /**
+   * Generate a base64-encoded payment claim.
+   * @param {number=} amountDrops
+   * @returns {Promise<string>}
+   */
+  async getAuthToken(amountDrops) {
+    await this.ready;
+    const ch = await this._findChannel();
+    const total = BigInt(ch.amount);
+    const allowed = amountDrops != null ? BigInt(amountDrops) : total;
+    if (allowed > total) {
+      throw new Error(
+        `Requested auth ${allowed} exceeds channel capacity ${total}`,
+      );
+    }
+    const claimHex = buildPaychanAuthHexStringToBeSigned(
+      ch.channel_id,
+      allowed.toString(),
+    );
+    const signature = signClaim(claimHex, this.wallet.privateKey);
+    const claim = {
+      version: "2",
+      account: this.wallet.classicAddress,
+      protocol: this.protocol,
+      currency: { code: "XRP", scale: 6 },
+      destination_account: this.destination,
+      authorized_to_claim: allowed.toString(),
+      channel_id: ch.channel_id,
+      signature,
+    };
+    return Buffer.from(JSON.stringify(claim)).toString("base64");
+  }
+}
+
+module.exports = { DhaliChannelManager, ChannelNotFound };

package/src/dhali/createSignedClaim.js

@@ -0,0 +1,66 @@
+const HASH_PREFIX_PAYMENT_CHANNEL_CLAIM = 0x434c4d00;
+
+/**
+ * @private
+ */
+function _serializePaychanAuthorization(channelIdBytes, dropsBigInt) {
+  if (!Buffer.isBuffer(channelIdBytes) || channelIdBytes.length !== 32) {
+    throw new Error(
+      `Invalid channelId length ${channelIdBytes.length}; must be 32 bytes.`,
+    );
+  }
+  // 1) 4-byte prefix
+  const prefix = Buffer.alloc(4);
+  prefix.writeUInt32BE(HASH_PREFIX_PAYMENT_CHANNEL_CLAIM, 0);
+
+  // 2) channelIdBytes (32 bytes)
+  // 3) split drops into two 4-byte words
+  const highBig = dropsBigInt >> 32n;
+  const lowBig = dropsBigInt & 0xffffffffn;
+  const high = Number(highBig);
+  const low = Number(lowBig);
+  const amountBuf = Buffer.alloc(8);
+  amountBuf.writeUInt32BE(high, 0);
+  amountBuf.writeUInt32BE(low, 4);
+
+  return Buffer.concat([prefix, channelIdBytes, amountBuf]);
+}
+
+/**
+ * Build the hex-string that you pass to an XRPL signer to sign a payment-channel claim.
+ *
+ * @param {string} channelIdHex 64-char hex string
+ * @param {string} amountStr    integer string of drops
+ * @returns {string} uppercase hex
+ */
+function buildPaychanAuthHexStringToBeSigned(channelIdHex, amountStr) {
+  let channelIdBytes;
+
+  channelIdBytes = Buffer.from(channelIdHex, "hex");
+
+  if (channelIdBytes.length !== 32) {
+    throw new Error(
+      `Invalid channelId length ${channelIdBytes.length}; must be 32 bytes.`,
+    );
+  }
+
+  let dropsBig;
+  try {
+    dropsBig = BigInt(amountStr);
+  } catch {
+    throw new Error("Invalid amount format.");
+  }
+
+  if (dropsBig < 0n) {
+    throw new Error("Amount cannot be negative.");
+  }
+
+  const msg = _serializePaychanAuthorization(channelIdBytes, dropsBig);
+  return msg.toString("hex").toUpperCase();
+}
+
+module.exports = {
+  buildPaychanAuthHexStringToBeSigned,
+  // exposed for testing
+  _serializePaychanAuthorization,
+};

package/src/index.js

@@ -0,0 +1,15 @@
+const {
+  buildPaychanAuthHexStringToBeSigned,
+  _serializePaychanAuthorization,
+} = require("./dhali/createSignedClaim");
+const {
+  DhaliChannelManager,
+  ChannelNotFound,
+} = require("./dhali/DhaliChannelManager");
+
+module.exports = {
+  buildPaychanAuthHexStringToBeSigned,
+  _serializePaychanAuthorization,
+  DhaliChannelManager,
+  ChannelNotFound,
+};

package/tests/DhaliChannelManager.test.js

@@ -0,0 +1,220 @@
+// tests/DhaliChannelManager.test.js
+
+// 1) MOCK xrpl.js BEFORE importing any code that instantiates Client
+jest.mock("xrpl", () => {
+  // Return an object with the Client class stubbed
+  return {
+    Client: jest.fn().mockImplementation(() => {
+      return {
+        // connect() returns a resolved Promise so await this.ready never hangs
+        connect: () => Promise.resolve(),
+        // stubbed methods your code calls:
+        request: jest.fn(),
+        autofill: jest.fn(),
+        submitAndWait: jest.fn(),
+        disconnect: jest.fn(),
+        // preserve .url for the constructor test
+        url: "wss://s1.ripple.com:51234/",
+      };
+    }),
+  };
+});
+
+// 2) MOCK ripple-keypairs BEFORE importing DhaliChannelManager
+jest.mock("ripple-keypairs", () => ({
+  // We'll override this mock's behavior inside individual tests
+  sign: jest.fn(),
+}));
+
+jest.mock("../src/dhali/createSignedClaim", () => ({
+  buildPaychanAuthHexStringToBeSigned: jest.fn(),
+  // If you need to expose _serializePaychanAuthorization, add it here too:
+  // _serializePaychanAuthorization: jest.fn(),
+}));
+
+// 3) Now import everything under test
+const createSignedClaim = require("../src/dhali/createSignedClaim");
+const { sign: mockRippleSign } = require("ripple-keypairs");
+const {
+  DhaliChannelManager,
+  ChannelNotFound,
+} = require("../src/dhali/DhaliChannelManager");
+
+describe("DhaliChannelManager", () => {
+  const CHANNEL_ID = "AB".repeat(32);
+  let wallet;
+  let manager;
+
+  beforeEach(() => {
+    // 4) Create a minimal fake wallet
+    wallet = {
+      classicAddress: "rTESTADDRESS",
+      publicKey: "PUBKEY",
+      privateKey: "PRIVKEY",
+      // sign() is used for transaction signing
+      sign: jest.fn().mockReturnValue({ signedTransaction: "TX_BLOB" }),
+    };
+    // 5) Instantiate the manager. client.connect() is already stubbed.
+    manager = new DhaliChannelManager(wallet);
+    // 6) Short-circuit any `await this.ready` if your constructor awaits client.connect()
+    manager.ready = Promise.resolve();
+  });
+
+  afterEach(() => {
+    // 7) Restore any spies on createSignedClaim so tests remain isolated
+    if (createSignedClaim.buildPaychanAuthHexStringToBeSigned.mockRestore) {
+      createSignedClaim.buildPaychanAuthHexStringToBeSigned.mockRestore();
+    }
+  });
+
+  test("constructor sets defaults", () => {
+    expect(manager.wallet).toBe(wallet);
+    expect(manager.protocol).toBe("XRPL.MAINNET");
+    expect(manager.destination).toBe("rLggTEwmTe3eJgyQbCSk4wQazow2TeKrtR");
+    // client.url comes from our mock above
+    expect(manager.client.url).toBe("wss://s1.ripple.com:51234/");
+  });
+
+  describe("_findChannel", () => {
+    test("returns first channel when present", async () => {
+      const fakeChannel = { channel_id: "CHAN123", amount: "1000" };
+      manager.client.request.mockResolvedValue({
+        result: { channels: [fakeChannel] },
+      });
+
+      const ch = await manager._findChannel();
+      expect(ch).toBe(fakeChannel);
+      // verify the exact request payload
+      expect(manager.client.request).toHaveBeenCalledWith({
+        command: "account_channels",
+        account: wallet.classicAddress,
+        destination_account: manager.destination,
+        ledger_index: "validated",
+      });
+    });
+
+    test("throws ChannelNotFound when none", async () => {
+      manager.client.request.mockResolvedValue({ result: { channels: [] } });
+
+      await expect(manager._findChannel()).rejects.toThrow(ChannelNotFound);
+      await expect(manager._findChannel()).rejects.toThrow(
+        wallet.classicAddress,
+      );
+      await expect(manager._findChannel()).rejects.toThrow(manager.destination);
+    });
+  });
+
+  describe("deposit", () => {
+    test("funds existing channel", async () => {
+      // _findChannel resolves => fund path
+      const fakeChannel = { channel_id: "CHANID", amount: "500" };
+      manager._findChannel = jest.fn().mockResolvedValue(fakeChannel);
+
+      // stub autofill + submitAndWait from our Client mock
+      manager.client.autofill.mockResolvedValue({ foo: "bar" });
+      manager.client.submitAndWait.mockResolvedValue({
+        result: { status: "funded" },
+      });
+
+      const res = await manager.deposit(100);
+      expect(res).toEqual({ status: "funded" });
+
+      // ensure autofill got the correct PaymentChannelFund payload
+      expect(manager.client.autofill).toHaveBeenCalledWith({
+        TransactionType: "PaymentChannelFund",
+        Account: wallet.classicAddress,
+        Channel: fakeChannel.channel_id,
+        Amount: "100",
+      });
+      // ensure we submitted the signed blob returned by wallet.sign()
+      expect(manager.client.submitAndWait).toHaveBeenCalledWith("TX_BLOB");
+    });
+
+    test("creates channel if none exists", async () => {
+      // _findChannel rejects with ChannelNotFound => create path
+      manager._findChannel = jest
+        .fn()
+        .mockRejectedValue(new ChannelNotFound("nope"));
+
+      manager.client.autofill.mockResolvedValue({ baz: "qux" });
+      manager.client.submitAndWait.mockResolvedValue({
+        result: { status: "created" },
+      });
+
+      const res = await manager.deposit(200);
+      expect(res).toEqual({ status: "created" });
+
+      expect(manager.client.autofill).toHaveBeenCalledWith({
+        TransactionType: "PaymentChannelCreate",
+        Account: wallet.classicAddress,
+        Destination: manager.destination,
+        Amount: "200",
+        SettleDelay: 86400 * 14,
+        PublicKey: wallet.publicKey,
+      });
+      expect(manager.client.submitAndWait).toHaveBeenCalledWith("TX_BLOB");
+    });
+  });
+
+  describe("getAuthToken", () => {
+    test("success with default amount", async () => {
+      // stub channel lookup
+      manager._findChannel = jest.fn().mockResolvedValue({
+        channel_id: CHANNEL_ID,
+        amount: "1001",
+      });
+
+      // 8) SPY on the hex-builder instead of reassigning it
+      const claimSpy = jest
+        .spyOn(createSignedClaim, "buildPaychanAuthHexStringToBeSigned")
+        .mockReturnValue("CLAIMHEX");
+
+      // stub signature
+      mockRippleSign.mockReturnValue("SIGVALUE");
+
+      const token = await manager.getAuthToken();
+      const decoded = JSON.parse(Buffer.from(token, "base64").toString("utf8"));
+
+      expect(decoded).toMatchObject({
+        version: "2",
+        account: wallet.classicAddress,
+        protocol: manager.protocol,
+        currency: { code: "XRP", scale: 6 },
+        destination_account: manager.destination,
+        authorized_to_claim: "1001",
+        channel_id: CHANNEL_ID,
+        signature: "SIGVALUE",
+      });
+
+      // ensure our spy was called with correct args
+      expect(claimSpy).toHaveBeenCalledWith(CHANNEL_ID, "1001");
+    });
+
+    test("success with specific amount", async () => {
+      manager._findChannel = jest.fn().mockResolvedValue({
+        channel_id: CHANNEL_ID,
+        amount: "500",
+      });
+
+      const claimSpy = jest
+        .spyOn(createSignedClaim, "buildPaychanAuthHexStringToBeSigned")
+        .mockReturnValue("CLAIMHEX2");
+      mockRippleSign.mockReturnValue("SIG2");
+
+      const token = await manager.getAuthToken(200);
+      const decoded = JSON.parse(Buffer.from(token, "base64").toString("utf8"));
+      expect(decoded.authorized_to_claim).toBe("200");
+      expect(claimSpy).toHaveBeenCalledWith(CHANNEL_ID, "200");
+    });
+
+    test("throws if amount exceeds capacity", async () => {
+      manager._findChannel = jest.fn().mockResolvedValue({
+        channel_id: CHANNEL_ID,
+        amount: "100",
+      });
+      await expect(manager.getAuthToken(200)).rejects.toThrow(
+        /exceeds channel capacity/,
+      );
+    });
+  });
+});

package/tests/createSignedClaim.test.js

@@ -0,0 +1,57 @@
+const {
+  _serializePaychanAuthorization,
+  buildPaychanAuthHexStringToBeSigned,
+} = require("../src/dhali/createSignedClaim");
+
+describe("_serializePaychanAuthorization", () => {
+  test("throws if channelIdBytes length is not 32", () => {
+    expect(() =>
+      _serializePaychanAuthorization(Buffer.alloc(31), 1000n),
+    ).toThrow("Invalid channelId length 31; must be 32 bytes.");
+  });
+
+  test("serializes correctly", () => {
+    // 32 bytes of 0xAA
+    const channelIdBytes = Buffer.alloc(32, 0xaa);
+    // a 64-bit drops value
+    const drops = 0x1122334455667788n;
+
+    const buf = _serializePaychanAuthorization(channelIdBytes, drops);
+
+    // prefix = 0x434C4D00
+    expect(buf.slice(0, 4).toString("hex")).toBe("434c4d00");
+    // next 32 bytes are the channelId
+    expect(buf.slice(4, 4 + 32)).toEqual(channelIdBytes);
+    // final 8 bytes = high + low words
+    expect(buf.slice(36).toString("hex")).toBe("1122334455667788");
+  });
+});
+
+describe("buildPaychanAuthHexStringToBeSigned", () => {
+  const zeroHex64 = "00".repeat(32);
+
+  test("negative amount throws", () => {
+    expect(() => buildPaychanAuthHexStringToBeSigned(zeroHex64, "-1")).toThrow(
+      "Amount cannot be negative.",
+    );
+  });
+
+  test("non-numeric amount throws", () => {
+    expect(() => buildPaychanAuthHexStringToBeSigned(zeroHex64, "foo")).toThrow(
+      "Invalid amount format.",
+    );
+  });
+
+  test("produces correct uppercase hex", () => {
+    const channelHex = "AA".repeat(32);
+    const amountStr = "123456";
+    const hexStr = buildPaychanAuthHexStringToBeSigned(channelHex, amountStr);
+    const expected = _serializePaychanAuthorization(
+      Buffer.from(channelHex, "hex"),
+      BigInt(amountStr),
+    )
+      .toString("hex")
+      .toUpperCase();
+    expect(hexStr).toBe(expected);
+  });
+});