dhali-js 3.0.4 → 3.1.0

package/.github/workflows/tests.yaml

@@ -25,8 +25,11 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Run tests
-        run: npm test
+      - name: Run unit tests
+        run: npm test tests/DhaliChannelManager.test.js tests/DhaliEthChannelManager.test.js tests/createSignedClaim.test.js tests/utils.test.js
+
+      - name: Run integration tests
+        run: npm test tests/integration.test.js
 
       - name: Run lint
         run: npx tsc src/dhali/*.js --allowJs --checkJs --noEmit --moduleResolution node --module commonjs --target esnext --skipLibCheck

package/README.md

@@ -148,6 +148,81 @@ async function main() {
 main();
 ```
 
+
+---
+
+## Asset Management (for Providers)
+
+If you have an API you want to monetize on Dhali, you can use the `DhaliAssetManager` to create and update your asset on the network.
+
+### 1. Create an Asset
+
+This generates an **Asset ID (UUID)**.
+
+#### XRPL Setup
+```js
+const { Wallet } = require('xrpl');
+const wallet = Wallet.fromSeed("s..."); // Your XRPL seed
+```
+
+#### EVM Setup
+```js
+const { createWalletClient, http } = require('viem');
+const { privateKeyToAccount } = require('viem/accounts');
+const { sepolia } = require('viem/chains');
+
+const walletClient = createWalletClient({
+    account: privateKeyToAccount("0x..."),
+    chain: sepolia,
+    transport: http()
+});
+```
+
+#### Initialization & Creation
+```js
+const { DhaliAssetManager, WalletDescriptor, Currency } = require('dhali-js');
+
+async function main() {
+    // For XRPL
+    const manager = DhaliAssetManager.xrpl(wallet);
+    const walletDescriptor = new WalletDescriptor(wallet.classicAddress, "XRPL.TESTNET");
+    
+    // OR For EVM
+    // const manager = DhaliAssetManager.evm(walletClient);
+    // const walletDescriptor = new WalletDescriptor(walletClient.account.address, "SEPOLIA");
+
+    const currency = new Currency("XRPL.TESTNET", "XRP", 6);
+
+    // Create the asset
+    const result = await manager.createAsset(walletDescriptor, currency);
+    console.log("Your new Asset ID:", result.uuid);
+}
+```
+
+Once created, your asset is represented by an **off-chain facilitator address**:  
+`https://x402.api.dhali.io/<uuid>`
+
+This facilitator is used for protocol-level concerns like verification and settlement, while your actual service requests are sent to your **Resource Server**.
+
+### 2. Update an Asset
+
+You can update your asset's metadata (name, rates, etc.) at any time.
+
+```js
+const { AssetUpdates } = require('dhali-js');
+
+async function main() {
+    const updates = new AssetUpdates({
+        name: "My Optimized AI API",
+        earning_rate: 100,            // 100 drops per request
+        earning_type: "per_request"   // or "per_second"
+    });
+
+    const result = await manager.updateAsset(assetId, walletDescriptor, updates);
+    console.log("Asset updated successfully");
+}
+```
+
 ---
 
 ## API Reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dhali-js",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "description": "A JavaScript library for managing XRPL payment channels and generating auth tokens for Dhali APIs",
   "main": "src/index.js",
   "type": "commonjs",
@@ -18,6 +18,7 @@
   "dependencies": {
     "ripple-keypairs": "^2.0.0",
     "viem": "^2.23.5",
+    "ws": "^8.18.0",
     "xrpl": "^4.0.0"
   },
   "devDependencies": {

package/src/dhali/AssetUpdates.js

@@ -0,0 +1,67 @@
+class AssetUpdates {
+    /**
+     * @param {Object} options
+     * @param {string} [options.name]
+     * @param {number} [options.earningRate]
+     * @param {string} [options.earningType]
+     * @param {string} [options.url]
+     * @param {Object} [options.headers]
+     * @param {string} [options.docs]
+     * @param {number} [options.maxSurcharge]
+     * @param {number} [options.assetPricingRate]
+     * @param {number} [options.assetPricingMaxSurcharge]
+     * @param {Object} [options.assetPricingCurrency]
+     */
+    constructor({
+        name,
+        earningRate,
+        earningType,
+        url,
+        headers,
+        docs,
+        maxSurcharge,
+        assetPricingRate,
+        assetPricingMaxSurcharge,
+        assetPricingCurrency
+    } = {}) {
+        this.name = name;
+        this.earningRate = earningRate;
+        this.earningType = earningType;
+        this.url = url;
+        this.headers = headers;
+        this.docs = docs;
+        this.maxSurcharge = maxSurcharge;
+        this.assetPricingRate = assetPricingRate;
+        this.assetPricingMaxSurcharge = assetPricingMaxSurcharge;
+        this.assetPricingCurrency = assetPricingCurrency;
+    }
+
+    /**
+     * Converts the updates to the format expected by api-admin-gateway
+     * @returns {Object}
+     */
+    toGatewayFormat() {
+        const updates = {};
+        if (this.name !== undefined) updates["name"] = this.name;
+        if (this.earningRate !== undefined) updates["asset_earning_rate"] = this.earningRate;
+        if (this.earningType !== undefined) updates["asset_earning_type"] = this.earningType;
+        if (this.docs !== undefined) updates["docs"] = this.docs;
+        if (this.maxSurcharge !== undefined) updates["asset_earning_max_surcharge"] = this.maxSurcharge;
+        if (this.assetPricingRate !== undefined) updates["asset_pricing_rate"] = this.assetPricingRate;
+        if (this.assetPricingMaxSurcharge !== undefined) updates["asset_pricing_max_surcharge"] = this.assetPricingMaxSurcharge;
+        if (this.assetPricingCurrency !== undefined) updates["asset_pricing_currency"] = this.assetPricingCurrency;
+
+        // Credentials/URL and headers are special
+        if (this.url !== undefined || this.headers !== undefined) {
+            updates["api_credentials"] = {};
+            if (this.url !== undefined) updates["api_credentials"]["url"] = this.url;
+            if (this.headers !== undefined) {
+                Object.assign(updates["api_credentials"], this.headers);
+            }
+        }
+
+        return updates;
+    }
+}
+
+module.exports = { AssetUpdates };

package/src/dhali/BaseAssetManager.js

@@ -0,0 +1,182 @@
+const { WebSocket } = require('ws');
+const Currency = require('./Currency');
+const { AssetUpdates } = require('./AssetUpdates');
+const { WalletDescriptor } = require('./WalletDescriptor');
+const { fetchPublicConfig } = require('./configUtils');
+
+class BaseAssetManager {
+    /**
+     * @param {any} wallet
+     * @param {string} [baseUrl]
+     */
+    constructor(wallet, baseUrl) {
+        this.baseUrl = baseUrl ? baseUrl.replace(/^http/, 'ws') : undefined;
+        this.wallet = wallet;
+    }
+
+    async _resolveBaseUrl() {
+        if (this.baseUrl) return;
+        const config = await fetchPublicConfig();
+        const rootUrl = config.ROOT_API_ADMIN_URL;
+        if (!rootUrl) {
+            throw new Error("ROOT_API_ADMIN_URL not found in public config");
+        }
+        this.baseUrl = rootUrl.replace(/^http/, 'ws');
+    }
+
+    /**
+     * Abstract method to handle protocol-specific signing
+     * @protected
+     * @returns {Promise<any>}
+     */
+    async _performSigning(typedData, walletDescriptor) {
+        throw new Error("_performSigning must be implemented by subclass");
+    }
+
+    async _handleAuth(ws, message, walletDescriptor) {
+        if (message.schema === 'api_admin_gateway_message_to_be_signed') {
+            const { message: typedData } = message;
+            const authResponse = await this._performSigning(typedData, walletDescriptor);
+            ws.send(JSON.stringify(authResponse));
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * @param {WalletDescriptor} walletDescriptor
+     * @param {Currency} currency
+     */
+    async createAsset(walletDescriptor, currency) {
+        await this._resolveBaseUrl();
+        if (!(walletDescriptor instanceof WalletDescriptor)) {
+            throw new Error('walletDescriptor must be an instance of WalletDescriptor');
+        }
+        if (!(currency instanceof Currency)) {
+            throw new Error('currency must be an instance of Currency');
+        }
+
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(`${this.baseUrl}/create`);
+
+            ws.on('open', () => {
+                ws.send(JSON.stringify({
+                    owner: walletDescriptor.toJson(),
+                    currency: {
+                        code: currency.code,
+                        scale: currency.scale,
+                        issuer: currency.tokenAddress
+                    }
+                }));
+            });
+
+            ws.on('message', async (data) => {
+                const message = JSON.parse(data.toString());
+
+                try {
+                    if (await this._handleAuth(ws, message, walletDescriptor)) {
+                        return;
+                    }
+
+                    if (message.schema === 'api_admin_gateway_request_wallet_json') {
+                        ws.send(JSON.stringify({
+                            schema: 'api_admin_gateway_wallet_json_response',
+                            wallet: walletDescriptor.toJson()
+                        }));
+                    } else if (message.schema === 'api_admin_gateway_create_successful') {
+                        resolve(message);
+                        ws.close();
+                    } else if (message.qr_code_url) {
+                        console.log('Scan this QR code to authenticate:', message.qr_code_url);
+                    } else if (message.error) {
+                        reject(new Error(message.error));
+                        ws.close();
+                    }
+                } catch (err) {
+                    reject(err);
+                    ws.close();
+                }
+            });
+
+            ws.on('error', (error) => {
+                reject(error);
+            });
+
+            ws.on('close', (code, reason) => {
+                if (code !== 1000 && code !== 1005) {
+                    reject(new Error(`WebSocket closed with code ${code}: ${reason}`));
+                }
+            });
+        });
+    }
+
+    /**
+     * @param {string} dhaliId
+     * @param {WalletDescriptor} walletDescriptor
+     * @param {AssetUpdates} updates
+     */
+    async updateAsset(dhaliId, walletDescriptor, updates) {
+        await this._resolveBaseUrl();
+        if (!(walletDescriptor instanceof WalletDescriptor)) {
+            throw new Error('walletDescriptor must be an instance of WalletDescriptor');
+        }
+        if (!(updates instanceof AssetUpdates)) {
+            throw new Error('updates must be an instance of AssetUpdates');
+        }
+
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(`${this.baseUrl}/${dhaliId}/update`);
+
+            ws.on('message', async (data) => {
+                const message = JSON.parse(data.toString());
+
+                try {
+                    if (await this._handleAuth(ws, message, walletDescriptor)) {
+                        return;
+                    }
+
+                    if (message.schema === 'api_admin_gateway_request_wallet_json') {
+                        ws.send(JSON.stringify({
+                            schema: 'api_admin_gateway_wallet_json_response',
+                            wallet: walletDescriptor.toJson()
+                        }));
+                    } else if (message.schema === 'api_admin_gateway_authentication_successful') {
+                        ws.send(JSON.stringify({
+                            schema: 'api_admin_gateway_prefill_request',
+                            schema_version: '1.0'
+                        }));
+                    } else if (message.schema === 'api_admin_gateway_prefill_response') {
+                        ws.send(JSON.stringify({
+                            schema: 'api_admin_gateway_update_request',
+                            schema_version: '1.0',
+                            updates: updates.toGatewayFormat()
+                        }));
+                    } else if (message.schema === 'api_admin_gateway_update_response') {
+                        resolve(message);
+                        ws.close();
+                    } else if (message.qr_code_url) {
+                        console.log('Scan this QR code to authenticate:', message.qr_code_url);
+                    } else if (message.error || message.status === 'failed') {
+                        reject(new Error(message.error || 'Update failed'));
+                        ws.close();
+                    }
+                } catch (err) {
+                    reject(err);
+                    ws.close();
+                }
+            });
+
+            ws.on('error', (error) => {
+                reject(error);
+            });
+
+            ws.on('close', (code, reason) => {
+                if (code !== 1000 && code !== 1005) {
+                    reject(new Error(`WebSocket closed with code ${code}: ${reason}`));
+                }
+            });
+        });
+    }
+}
+
+module.exports = { BaseAssetManager };

package/src/dhali/DhaliAssetManager.js

@@ -0,0 +1,25 @@
+const { DhaliXrplAssetManager } = require('./DhaliXrplAssetManager');
+const { DhaliEthAssetManager } = require('./DhaliEthAssetManager');
+
+/**
+ * Factory for creating asset managers.
+ */
+const DhaliAssetManager = {
+    /**
+     * @param {import("xrpl").Wallet} wallet
+     * @returns {DhaliXrplAssetManager}
+     */
+    xrpl: (wallet) => {
+        return new DhaliXrplAssetManager(wallet);
+    },
+
+    /**
+     * @param {import("viem").WalletClient} walletClient
+     * @returns {DhaliEthAssetManager}
+     */
+    evm: (walletClient) => {
+        return new DhaliEthAssetManager(walletClient);
+    }
+};
+
+module.exports = { DhaliAssetManager };

package/src/dhali/DhaliEthAssetManager.js

@@ -0,0 +1,35 @@
+const { BaseAssetManager } = require('./BaseAssetManager');
+
+/**
+ * DhaliAssetManager for EVM protocol.
+ */
+class DhaliEthAssetManager extends BaseAssetManager {
+    /**
+     * @param {import("viem").WalletClient} walletClient
+     * @param {string} [baseUrl]
+     */
+    constructor(walletClient, baseUrl) {
+        super(walletClient, baseUrl);
+    }
+
+    /**
+     * @protected
+     */
+    async _performSigning(typedData, walletDescriptor) {
+        const [account] = await this.wallet.getAddresses();
+        const signature = await this.wallet.signTypedData({
+            account: this.wallet.account || account,
+            domain: typedData.domain,
+            types: typedData.types,
+            primaryType: typedData.primaryType,
+            message: typedData.message
+        });
+
+        return {
+            schema: 'api_admin_gateway_signed_message_response',
+            signature: signature
+        };
+    }
+}
+
+module.exports = { DhaliEthAssetManager };

package/src/dhali/DhaliXrplAssetManager.js

@@ -0,0 +1,32 @@
+const { BaseAssetManager } = require('./BaseAssetManager');
+const { sign: signClaim } = require("ripple-keypairs");
+
+/**
+ * DhaliAssetManager for XRPL protocol.
+ */
+class DhaliXrplAssetManager extends BaseAssetManager {
+    /**
+     * @param {import("xrpl").Wallet} wallet
+     * @param {string} [baseUrl]
+     */
+    constructor(wallet, baseUrl) {
+        super(wallet, baseUrl);
+    }
+
+    /**
+     * @protected
+     */
+    async _performSigning(typedData, walletDescriptor) {
+        // The backend expects the message as a JSON string for XRPL
+        const messageToSign = JSON.stringify(typedData);
+        const signature = signClaim(Buffer.from(messageToSign).toString('hex'), this.wallet.privateKey);
+
+        return {
+            schema: 'api_admin_gateway_signed_message_response',
+            signature: signature.toUpperCase(),
+            public_key: this.wallet.publicKey
+        };
+    }
+}
+
+module.exports = { DhaliXrplAssetManager };

package/src/dhali/WalletDescriptor.js

@@ -0,0 +1,27 @@
+class WalletDescriptor {
+    /**
+     * @param {string} address - The classic address of the wallet
+     * @param {string} protocol - The network protocol (e.g., 'XRPL.TESTNET', 'ETHEREUM')
+     * @param {string} [type='Dhali-js'] - The type of wallet (defaults to 'Dhali-js')
+     */
+    constructor(address, protocol, type = 'Dhali-js') {
+        this.address = address;
+        this.protocol = protocol;
+        this.type = type;
+    }
+
+    /**
+     * Converts to JSON format expected by Dhali backend
+     * @returns {Object}
+     */
+    toJson() {
+        return {
+            address: this.address,
+            wallet_id: this.address, // Backward compatibility or specific gateway requirement
+            type: this.type,
+            protocol: this.protocol
+        };
+    }
+}
+
+module.exports = { WalletDescriptor };

package/src/index.js

@@ -1,9 +1,15 @@
 const { DhaliChannelManager } = require("./dhali/DhaliChannelManager");
-const { DhaliXrplChannelManager, ChannelNotFound } = require("./dhali/DhaliXrplChannelManager");
+const { DhaliXrplChannelManager } = require("./dhali/DhaliXrplChannelManager");
 const { DhaliEthChannelManager } = require("./dhali/DhaliEthChannelManager");
+const { DhaliAssetManager } = require("./dhali/DhaliAssetManager");
+const { BaseAssetManager } = require("./dhali/BaseAssetManager");
+const { DhaliXrplAssetManager } = require("./dhali/DhaliXrplAssetManager");
+const { DhaliEthAssetManager } = require("./dhali/DhaliEthAssetManager");
+const { WalletDescriptor } = require("./dhali/WalletDescriptor");
+const { AssetUpdates } = require("./dhali/AssetUpdates");
 const Currency = require("./dhali/Currency");
-const { getAvailableDhaliCurrencies } = require("./dhali/configUtils");
-const { wrapAsX402PaymentPayload } = require("./dhali/utils");
+const { fetchPublicConfig, retrieveChannelIdFromFirestoreRest, notifyAdminGateway, getAvailableDhaliCurrencies } = require("./dhali/configUtils");
+const { wrapAsX402PaymentPayload, ChannelNotFound } = require("./dhali/utils");
 
 module.exports = {
   DhaliChannelManager,
@@ -12,5 +18,14 @@ module.exports = {
   ChannelNotFound,
   Currency,
   getAvailableDhaliCurrencies,
-  wrapAsX402PaymentPayload
+  DhaliAssetManager,
+  BaseAssetManager,
+  DhaliXrplAssetManager,
+  DhaliEthAssetManager,
+  WalletDescriptor,
+  AssetUpdates,
+  fetchPublicConfig,
+  retrieveChannelIdFromFirestoreRest,
+  notifyAdminGateway,
+  wrapAsX402PaymentPayload,
 };

package/tests/integration.test.js

@@ -0,0 +1,78 @@
+const { Wallet } = require('xrpl');
+const { DhaliAssetManager } = require('../src/dhali/DhaliAssetManager');
+const { WalletDescriptor } = require('../src/dhali/WalletDescriptor');
+const Currency = require('../src/dhali/Currency');
+const { AssetUpdates } = require('../src/dhali/AssetUpdates');
+
+describe('Dhali-js Integration Test', () => {
+    let wallet;
+    let manager;
+
+    beforeAll(() => {
+        wallet = Wallet.generate();
+        manager = DhaliAssetManager.xrpl(wallet);
+    });
+
+    test('should create and update an asset', async () => {
+        const walletDescriptor = new WalletDescriptor(wallet.address, "XRPL.TESTNET");
+        const currency = new Currency("XRPL.TESTNET", "XRP", 6);
+
+        // 1. Create Asset
+        console.log('Creating asset...');
+        const createResult = await manager.createAsset(walletDescriptor, currency);
+        expect(createResult.schema).toBe('api_admin_gateway_create_successful');
+        expect(createResult.uuid).toBeDefined();
+        const assetId = createResult.uuid;
+        console.log('Asset created with UUID:', assetId);
+
+        // 2. Update Asset
+        console.log('Updating asset...');
+        const updates = new AssetUpdates({
+            name: "Integration Test Asset",
+            earning_rate: 100,
+            earning_type: "per_request"
+        });
+
+        const updateResult = await manager.updateAsset(assetId, walletDescriptor, updates);
+        expect(updateResult.schema).toBe('api_admin_gateway_update_response');
+        console.log('Asset updated successfully');
+    }, 30000); // Increased timeout for live API calls
+
+    test('should create and update an EVM asset', async () => {
+        const { createWalletClient, http } = require('viem');
+        const { generatePrivateKey, privateKeyToAccount } = require('viem/accounts');
+        const { sepolia } = require('viem/chains');
+
+        const privateKey = generatePrivateKey();
+        const account = privateKeyToAccount(privateKey);
+        const walletClient = createWalletClient({
+            account,
+            chain: sepolia,
+            transport: http()
+        });
+
+        const evmManager = DhaliAssetManager.evm(walletClient);
+        const walletDescriptor = new WalletDescriptor(account.address, "SEPOLIA");
+        const currency = new Currency("SEPOLIA", "ETH", 18);
+
+        // 1. Create Asset
+        console.log('Creating EVM asset...');
+        const createResult = await evmManager.createAsset(walletDescriptor, currency);
+        expect(createResult.schema).toBe('api_admin_gateway_create_successful');
+        expect(createResult.uuid).toBeDefined();
+        const assetId = createResult.uuid;
+        console.log('EVM Asset created with UUID:', assetId);
+
+        // 2. Update Asset
+        console.log('Updating EVM asset...');
+        const updates = new AssetUpdates({
+            name: "Integration Test Asset EVM",
+            earning_rate: 0.001,
+            earning_type: "per_request"
+        });
+
+        const updateResult = await evmManager.updateAsset(assetId, walletDescriptor, updates);
+        expect(updateResult.schema).toBe('api_admin_gateway_update_response');
+        console.log('EVM Asset updated successfully');
+    }, 30000);
+});