dhali-js 2.1.0 → 3.0.3

package/.github/workflows/tests.yaml

@@ -29,4 +29,4 @@ jobs:
         run: npm test
 
       - name: Run lint
-        run: npx tsc src/dhali/*.js --allowJs --checkJs --noEmit --moduleResolution node --module commonjs --target esnext
+        run: npx tsc src/dhali/*.js --allowJs --checkJs --noEmit --moduleResolution node --module commonjs --target esnext --skipLibCheck

package/README.md

@@ -16,6 +16,9 @@ Includes support for **Machine-to-Machine (M2M) payments** using seamless off-ch
 npm install dhali-js
 ```
 
+> [!TIP]
+> The examples below use CommonJS (`require`). Because they use `await`, the code is wrapped in an `async function main() { ... }` which is called immediately. To run these, simply save them to a `.js` file and run `node document.js`.
+
 ---
 
 ## Quick Start: Machine-to-Machine Payments
@@ -28,69 +31,87 @@ Uses `xrpl.js` for local signing.
 const { Client, Wallet } = require('xrpl')
 const { DhaliChannelManager, ChannelNotFound, Currency } = require('dhali-js')
 
-const seed    = "sXXX..."
-const wallet  = Wallet.fromSeed(seed)
-const client  = new Client("wss://s.altnet.rippletest.net:51233")
-await client.connect()
-
-const currency = new Currency("XRP", 6)
-
-// Use Factory
-const manager = DhaliChannelManager.xrpl(wallet, client, "XRPL.TESTNET", currency)
-
-// Generate Claim
-let token;
-try {
-    token = await manager.getAuthToken();
-} catch (error) {
-    if (error.name === "ChannelNotFound") {
-       await manager.deposit(1000000); // Deposit 1 XRP
-       token = await manager.getAuthToken();
-    } else {
-       throw error;
+async function main() {
+    const seed    = "sXXX..."
+    const wallet  = Wallet.fromSeed(seed)
+    const client  = new Client("wss://s.altnet.rippletest.net:51233")
+    await client.connect()
+
+    const currency = new Currency("XRPL.TESTNET", "XRP", 6)
+
+    // Use Factory
+    const manager = DhaliChannelManager.xrpl(wallet, client, currency)
+
+    // Generate Claim
+    const amount = Math.floor(1.0 * Math.pow(10, currency.scale)); // 1 XRP
+    let token;
+    try {
+        token = await manager.getAuthToken();
+    } catch (error) {
+        if (error.name === "ChannelNotFound") {
+           await manager.deposit(amount);
+           token = await manager.getAuthToken();
+        } else {
+           throw error;
+        }
     }
+    console.log('XRPL Token:', token);
 }
-console.log('XRPL Token:', token);
+
+main();
 ```
 
 ### 2. Ethereum (EVM)
 
-Uses `ethers` (v6) for EIP-712 signing.
+Uses `viem` for EIP-712 signing.
 
 ```js
-const { ethers } = require('ethers')
+const { createWalletClient, createPublicClient, http } = require('viem')
+const { privateKeyToAccount } = require('viem/accounts')
+const { mainnet, sepolia } = require('viem/chains')
 const { DhaliChannelManager, getAvailableDhaliCurrencies } = require('dhali-js')
 
-// 1. Setup Signer
-const provider = new ethers.JsonRpcProvider("https://rpc.ankr.com/eth_sepolia")
-const signer   = new ethers.Wallet("0x...", provider)
-
-// 2. Fetch Available Currencies
-const configs = await getAvailableDhaliCurrencies()
-const sepoliaUsdc = configs["SEPOLIA"]["USDC"]
-
-// 3. Instantiate Manager with Dynamic Config
-const manager = DhaliChannelManager.evm(
-    signer,
-    provider,
-    "SEPOLIA",
-    sepoliaUsdc.currency
-)
-
-// 4. Generate Claim
-// 4. Generate Claim
-let token;
-try {
-    token = await manager.getAuthToken(1000000); // 1.00 USDC
-} catch (error) {
-    if (error.name === "ChannelNotFound") {
-       await manager.deposit(1000000); // Deposit 1.00 USDC
-       token = await manager.getAuthToken(1000000);
-    } else {
-       throw error;
+async function main() {
+    // 1. Setup Clients
+    const account = privateKeyToAccount('0x...')
+    const publicClient = createPublicClient({
+      chain: sepolia,
+      transport: http()
+    })
+    const walletClient = createWalletClient({
+      account,
+      chain: sepolia,
+      transport: http()
+    })
+
+    // 2. Fetch Available Currencies
+    const currencies = await getAvailableDhaliCurrencies()
+    const sepoliaUsdc = currencies.find(c => c.network === "SEPOLIA" && c.code === "USDC")
+
+    // 3. Instantiate Manager with Dynamic Config
+    const manager = DhaliChannelManager.evm(
+        walletClient,
+        publicClient,
+        sepoliaUsdc
+    )
+
+    // 4. Generate Claim
+    const amount = Math.floor(0.1 * Math.pow(10, sepoliaUsdc.scale)); // 0.10 USDC
+    let token;
+    try {
+        token = await manager.getAuthToken(amount);
+    } catch (error) {
+        if (error.name === "ChannelNotFound") {
+           await manager.deposit(amount);
+           token = await manager.getAuthToken(amount);
+        } else {
+           throw error;
+        }
     }
+    console.log('EVM Token:', token);
 }
-console.log('EVM Token:', token);
+
+main();
 ```
 
 ---
@@ -104,26 +125,64 @@ const url = `https://xrplcluster.dhali.io?payment-claim=${token}`
 const response = await fetch(url, { method: 'POST', body: ... })
 ```
 
+## Standardized x402 Payments
+
+For APIs that follow the x402 standard, you may need to wrap your auth token with the payment requirement (retrieved from the `payment-required` header of a 402 response).
+
+```js
+const { wrapAsX402PaymentPayload } = require('dhali-js');
+
+async function main() {
+    // 1. Get your token as usual
+    const token = await manager.getAuthToken();
+
+    // 2. Get the payment requirement from the 'payment-required' header of a 402 response
+    const paymentRequirement = response.headers.get("payment-required");
+
+    // 3. Wrap into an x402 payload
+    const x402Payload = wrapAsX402PaymentPayload(token, paymentRequirement);
+
+    // 4. Use 'x402Payload' in the 'Payment' header
+}
+
+main();
+```
+
 ---
 
 ## API Reference
 
-### `DhaliChannelManager`
+### `DhaliChannelManager` (Factory)
+
+* `.xrpl(wallet, client, currency)`: Returns `DhaliXrplChannelManager`.
+* `.evm(walletClient, publicClient, currency)`: Returns `DhaliEthChannelManager`.
 
-* `.xrpl(wallet, client, protocol, currency)`: Returns `DhaliXrplChannelManager`.
-* `.evm(signer, provider, protocol, currency)`: Returns `DhaliEthChannelManager`.
+### `DhaliEthChannelManager` & `DhaliXrplChannelManager`
+
+Both managers provide the following core methods:
+
+* `async deposit(amount)`: Deposits funds into a payment channel. For EVM/XRPL, `amount` is in base units (wei/drops, etc). If no channel exists, it creates one; if it exists, it funds it.
+* `async getAuthToken(amount = null)`: Generates a base64-encoded payment claim. If `amount` is provided, the claim is authorized up to that value. Defaults to total channel capacity if `amount` is `null`.
 
 ### `getAvailableDhaliCurrencies()`
 
-Returns a Promise resolving to:
+Returns a Promise resolving to an array of `Currency` objects:
 ```js
-{
-    "SEPOLIA": {
-        "USDC": { currency: ..., destinationAddress: ... },
-        ...
-    },
+[
+    { network: "SEPOLIA", code: "USDC", scale: 6, tokenAddress: "..." },
     ...
-}
+]
 ```
 
+---
+
+## Utilities
+
+### `wrapAsX402PaymentPayload(token, paymentRequirement)`
+
+Wraps an auth token and a payment requirement (retrieved from a 402 response header) into a base64-encoded x402-compliant payload.
+
+* **`token`**: The base64-encoded claim generated by `getAuthToken()`.
+* **`paymentRequirement`**: The base64-encoded requirement string from the `payment-required` header.
+
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dhali-js",
-  "version": "2.1.0",
+  "version": "3.0.3",
   "description": "A JavaScript library for managing XRPL payment channels and generating auth tokens for Dhali APIs",
   "main": "src/index.js",
   "type": "commonjs",
@@ -16,8 +16,8 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "ethers": "^6.0.0",
     "ripple-keypairs": "^2.0.0",
+    "viem": "^2.23.5",
     "xrpl": "^4.0.0"
   },
   "devDependencies": {

package/src/dhali/Currency.js

@@ -1,5 +1,6 @@
 class Currency {
-    constructor(code, scale, tokenAddress = null) {
+    constructor(network, code, scale, tokenAddress = null) {
+        this.network = network;
         this.code = code;
         this.scale = scale;
         this.tokenAddress = tokenAddress;

package/src/dhali/DhaliChannelManager.js

@@ -5,30 +5,27 @@ const DhaliChannelManager = {
   /**
    * @param {import("xrpl").Wallet} wallet
    * @param {import("xrpl").Client} client
-   * @param {string} protocol
    * @param {import("./Currency")} currency
    * @param {typeof fetch} [httpClient] - Injected HTTP client
    * @param {object} [publicConfig]
    * @returns {DhaliXrplChannelManager}
    */
-  xrpl: (wallet, client, protocol, currency, httpClient, publicConfig) => {
-    return new DhaliXrplChannelManager(wallet, client, protocol, currency, httpClient, publicConfig);
+  xrpl: (wallet, client, currency, httpClient, publicConfig) => {
+    return new DhaliXrplChannelManager(wallet, client, currency, httpClient, publicConfig);
   },
 
   /**
-   * @param {import("ethers").Signer} signer
-   * @param {import("ethers").Provider} provider
-   * @param {string} protocol
+   * @param {import("viem").WalletClient} walletClient
+   * @param {import("viem").PublicClient} publicClient
    * @param {import("./Currency")} currency
    * @param {typeof fetch} [httpClient] - Injected HTTP client
    * @param {object} [publicConfig]
    * @returns {DhaliEthChannelManager}
    */
-  evm: (signer, provider, protocol, currency, httpClient, publicConfig) => {
+  evm: (walletClient, publicClient, currency, httpClient, publicConfig) => {
     return new DhaliEthChannelManager(
-      signer,
-      provider,
-      protocol,
+      walletClient,
+      publicClient,
       currency,
       httpClient,
       publicConfig