blue-js-sdk 2.0.1 → 2.1.0

package/ai-path/index.js

@@ -58,8 +58,17 @@ export {
   rpcQueryBalance,
   rpcQueryNode,
   // v1.5.2: Session recovery (referenced in docs but was missing from exports)
-  recoverOrphans,
+  recoverOrphans as recoverSession,
+  // v2.0.2: Plan operations for AI agents using subscription-based access
+  connectViaSubscription,
+  connectViaPlan,
+  subscribeToPlan,
+  hasActiveSubscription,
+  querySubscriptions,
+  queryPlanNodes,
+  queryFeeGrants,
+  buildFeeGrantMsg,
+  broadcastWithFeeGrant,
+  rpcQueryNodesForPlan,
+  rpcQuerySubscriptionsForAccount,
 } from '../index.js';
-
-// Re-export recoverOrphans as recoverSession (the name used in ai-path docs)
-export { recoverOrphans as recoverSession };

package/batch.js

@@ -142,10 +142,10 @@ async function _processBatch(client, account, batch, gigabytes, denom, ctx) {
     typeUrl: MSG_TYPES.START_SESSION,
     value: {
       from: account.address,
-      node_address: node.address,
+      nodeAddress: node.address,
       gigabytes,
       hours: 0,
-      max_price: {
+      maxPrice: {
         denom: priceEntry.denom,
         base_value: priceEntry.base_value,
         quote_value: priceEntry.quote_value,

package/chain/broadcast.js

@@ -338,10 +338,10 @@ export function buildBatchStartSession(from, nodes) {
     typeUrl: '/sentinel.node.v3.MsgStartSessionRequest',
     value: {
       from,
-      node_address: n.nodeAddress,
+      nodeAddress: n.nodeAddress,
       gigabytes: n.gigabytes || 1,
       hours: 0,
-      max_price: n.maxPrice,
+      maxPrice: n.maxPrice,
     },
   }));
 }
@@ -382,7 +382,7 @@ export function buildBatchSend(fromAddress, recipients) {
 export function buildBatchLink(provAddress, planId, nodeAddresses) {
   return nodeAddresses.map(addr => ({
     typeUrl: '/sentinel.plan.v3.MsgLinkNodeRequest',
-    value: { from: provAddress, id: BigInt(planId), node_address: addr },
+    value: { from: provAddress, id: BigInt(planId), nodeAddress: addr },
   }));
 }
 
@@ -432,6 +432,116 @@ export async function subscribeToPlan(client, fromAddress, planId, denom = 'udvp
   return { subscriptionId: BigInt(subId), txHash: result.transactionHash };
 }
 
+/**
+ * Share a subscription's bandwidth with another address.
+ * The chain only supports bytes-based sharing — there is NO time/duration field.
+ * For time-based plans (e.g. 1 month), the operator must manually remove the user
+ * when the period expires using cancelSubscription or by not renewing.
+ *
+ * @param {SigningStargateClient} client
+ * @param {string} ownerAddress - Subscription owner (sent1...)
+ * @param {number|string|bigint} subscriptionId - Subscription to share
+ * @param {string} recipientAddress - User to add (sent1...)
+ * @param {number|string|bigint} bytes - Bandwidth quota in bytes (e.g. 1073741824 = 1 GB)
+ * @returns {Promise<{ txHash: string }>}
+ */
+export async function shareSubscription(client, ownerAddress, subscriptionId, recipientAddress, bytes) {
+  const msg = {
+    typeUrl: '/sentinel.subscription.v3.MsgShareSubscriptionRequest',
+    value: { from: ownerAddress, id: BigInt(subscriptionId), accAddress: recipientAddress, bytes: String(bytes) },
+  };
+  const result = await broadcast(client, ownerAddress, [msg]);
+  return { txHash: result.transactionHash };
+}
+
+/**
+ * Share a subscription with fee grant — operator pays gas on behalf of user.
+ * Same as shareSubscription() but uses broadcastWithFeeGrant for the TX fee.
+ *
+ * @param {SigningStargateClient} client - Client with owner's wallet
+ * @param {string} ownerAddress - Subscription owner (sent1...)
+ * @param {number|string|bigint} subscriptionId - Subscription to share
+ * @param {string} recipientAddress - User to add (sent1...)
+ * @param {number|string|bigint} bytes - Bandwidth quota in bytes
+ * @param {string} granterAddress - Fee granter address (sent1...)
+ * @returns {Promise<{ txHash: string }>}
+ */
+export async function shareSubscriptionWithFeeGrant(client, ownerAddress, subscriptionId, recipientAddress, bytes, granterAddress) {
+  const msg = {
+    typeUrl: '/sentinel.subscription.v3.MsgShareSubscriptionRequest',
+    value: { from: ownerAddress, id: BigInt(subscriptionId), accAddress: recipientAddress, bytes: String(bytes) },
+  };
+  const result = await broadcastWithFeeGrant(client, ownerAddress, [msg], granterAddress);
+  return { txHash: result.transactionHash };
+}
+
+// ─── Plan User Onboarding (composite operation) ────────────────────────────
+
+/**
+ * Onboard a user to a plan subscription: subscribe → share bandwidth → optional fee grant.
+ * This is the complete "add user to plan" operation for plan operators.
+ *
+ * IMPORTANT: The chain only supports bytes-based sharing. There is NO time/duration
+ * field in MsgShareSubscriptionRequest. For time-based plans (e.g. 1 month), the
+ * operator must track expiry externally and remove/not-renew the user when time expires.
+ *
+ * Steps:
+ *   1. Subscribe to plan (operator pays, creates subscription)
+ *   2. Share the subscription with the user (allocate bytes)
+ *   3. Optionally grant fee allowance (so user's TX gas is paid by operator)
+ *
+ * @param {SigningStargateClient} client - Operator's signing client
+ * @param {string} operatorAddress - Plan operator/owner address (sent1...)
+ * @param {object} opts
+ * @param {number|string|bigint} opts.planId - Plan to subscribe to
+ * @param {string} opts.userAddress - User to onboard (sent1...)
+ * @param {number|string|bigint} opts.bytes - Bandwidth quota in bytes (e.g. 1073741824 = 1 GB)
+ * @param {string} [opts.denom='udvpn'] - Payment denomination
+ * @param {boolean} [opts.grantFee=false] - Also grant fee allowance to user
+ * @param {number} [opts.feeSpendLimit] - Max spend for fee grant in udvpn (default: 500000 = 0.5 P2P)
+ * @param {Date|string} [opts.feeExpiration] - Fee grant expiry date
+ * @param {Function} [opts.buildFeeGrant] - Custom buildFeeGrantMsg function (to avoid circular import)
+ * @returns {Promise<{ subscriptionId: bigint, shareTxHash: string, grantTxHash?: string }>}
+ */
+export async function onboardPlanUser(client, operatorAddress, opts) {
+  const {
+    planId, userAddress, bytes,
+    denom = 'udvpn',
+    grantFee = false,
+    feeSpendLimit = 500_000,
+    feeExpiration,
+    buildFeeGrant,
+  } = opts;
+
+  // Step 1: Subscribe to plan
+  const { subscriptionId, txHash: subTxHash } = await subscribeToPlan(client, operatorAddress, planId, denom);
+
+  // Step 2: Share subscription with user (bytes-based — no time/duration on chain)
+  const shareMsg = {
+    typeUrl: '/sentinel.subscription.v3.MsgShareSubscriptionRequest',
+    value: { from: operatorAddress, id: BigInt(subscriptionId), accAddress: userAddress, bytes: String(bytes) },
+  };
+  const shareResult = await broadcast(client, operatorAddress, [shareMsg]);
+
+  const result = {
+    subscriptionId,
+    subscribeTxHash: subTxHash,
+    shareTxHash: shareResult.transactionHash,
+  };
+
+  // Step 3: Optional fee grant
+  if (grantFee && buildFeeGrant) {
+    const grantMsg = buildFeeGrant(operatorAddress, userAddress, {
+      spendLimit: feeSpendLimit,
+      expiration: feeExpiration,
+    });
+    const grantResult = await broadcast(client, operatorAddress, [grantMsg]);
+    result.grantTxHash = grantResult.transactionHash;
+  }
+
+  return result;
+}
+
 /**
  * Estimate the cost of starting a session with a node.
  * Supports both gigabyte and hourly pricing. When preferHourly is true and

package/chain/client.js

@@ -43,7 +43,8 @@ import {
   encodeMsgEndLease,
 } from '../plan-operations.js';
 
-import { GAS_PRICE } from '../defaults.js';
+import { GAS_PRICE, RPC_ENDPOINTS } from '../defaults.js';
+import { ValidationError, ChainError, ErrorCodes } from '../errors.js';
 
 // ─── CosmJS Registry ─────────────────────────────────────────────────────────
 
@@ -107,12 +108,59 @@ export function buildRegistry() {
 /**
  * Create a SigningStargateClient connected to Sentinel RPC.
  * Gas price: from defaults.js GAS_PRICE (chain minimum).
+ *
+ * Signatures:
+ *   createClient(rpcUrl, wallet)  — classic: connect to specific RPC with existing wallet
+ *   createClient(mnemonic)        — convenience: create wallet from mnemonic, try RPC endpoints with failover
+ *
+ * @param {string} rpcUrlOrMnemonic - Either an RPC URL (https://...) or a BIP39 mnemonic
+ * @param {DirectSecp256k1HdWallet} [wallet] - Wallet object (required when first arg is RPC URL)
+ * @returns {Promise<SigningStargateClient>} Connected signing client with full Sentinel registry
  */
-export async function createClient(rpcUrl, wallet) {
-  return SigningStargateClient.connectWithSigner(rpcUrl, wallet, {
-    gasPrice: GasPrice.fromString(GAS_PRICE),
-    registry: buildRegistry(),
-  });
+export async function createClient(rpcUrlOrMnemonic, wallet) {
+  // Classic call: createClient(rpcUrl, wallet)
+  if (wallet) {
+    return SigningStargateClient.connectWithSigner(rpcUrlOrMnemonic, wallet, {
+      gasPrice: GasPrice.fromString(GAS_PRICE),
+      registry: buildRegistry(),
+    });
+  }
+
+  // If first arg looks like a URL, it's a missing wallet — throw helpful error
+  if (typeof rpcUrlOrMnemonic === 'string' && /^(https?|wss?):\/\//i.test(rpcUrlOrMnemonic)) {
+    throw new ValidationError(ErrorCodes.INVALID_MNEMONIC,
+      'createClient(rpcUrl, wallet): wallet parameter is required when passing an RPC URL. ' +
+      'Use createClient(mnemonic) for convenience, or createClient(rpcUrl, wallet) with an existing wallet.',
+      { value: rpcUrlOrMnemonic });
+  }
+
+  // Convenience call: createClient(mnemonic) — create wallet + try RPC endpoints
+  // Lazy import to avoid circular dependency
+  const { createWallet, validateMnemonic } = await import('./wallet.js');
+  validateMnemonic(rpcUrlOrMnemonic, 'createClient');
+  const { wallet: derivedWallet } = await createWallet(rpcUrlOrMnemonic);
+  const registry = buildRegistry();
+  const gasPrice = GasPrice.fromString(GAS_PRICE);
+
+  // Try each RPC endpoint until one connects
+  const errors = [];
+  for (const ep of RPC_ENDPOINTS) {
+    try {
+      const client = await SigningStargateClient.connectWithSigner(ep.url, derivedWallet, {
+        gasPrice,
+        registry,
+      });
+      return client;
+    } catch (err) {
+      errors.push({ endpoint: ep.url, name: ep.name, error: err.message });
+    }
+  }
+
+  // All endpoints failed
+  const tried = errors.map(e => `  ${e.name} (${e.endpoint}): ${e.error}`).join('\n');
+  throw new ChainError('ALL_ENDPOINTS_FAILED',
+    `createClient(mnemonic): failed to connect to all ${RPC_ENDPOINTS.length} RPC endpoints:\n${tried}`,
+    { endpoints: errors });
 }
 
 // ─── All Type URL Constants ──────────────────────────────────────────────────

package/chain/queries.js

@@ -394,6 +394,27 @@ export async function hasActiveSubscription(address, planId, lcdUrl) {
   return { has: false };
 }
 
+/**
+ * Query allocations for a subscription (who has how many bytes).
+ * NOTE: Uses v2 endpoint because this specific v3 query hasn't been implemented yet
+ * (returns 501). The v2 path returns the same allocation data. Same situation as /plan/v3/plans/{id}.
+ *
+ * @param {string|number|bigint} subscriptionId
+ * @param {string} [lcdUrl]
+ * @returns {Promise<Array<{ id: string, address: string, grantedBytes: string, utilisedBytes: string }>>}
+ */
+export async function querySubscriptionAllocations(subscriptionId, lcdUrl) {
+  try {
+    const data = await lcdQuery(`/sentinel/subscription/v2/subscriptions/${subscriptionId}/allocations`, { lcdUrl });
+    return (data.allocations || []).map(a => ({
+      id: a.id,
+      address: a.address,
+      grantedBytes: a.granted_bytes || '0',
+      utilisedBytes: a.utilised_bytes || '0',
+    }));
+  } catch { return []; }
+}
+
 // ─── Plan Subscriber Helpers (v25b) ──────────────────────────────────────────
 
 /**

package/connection/connect.js

@@ -440,10 +440,10 @@ export async function connectDirect(opts) {
       typeUrl: MSG_TYPES.START_SESSION,
       value: {
         from: account.address,
-        node_address: opts.nodeAddress,
+        nodeAddress: opts.nodeAddress,
         gigabytes: sessionGigabytes,
         hours: sessionHours,
-        max_price: { denom: 'udvpn', base_value: sessionMaxPrice.base_value, quote_value: sessionMaxPrice.quote_value },
+        maxPrice: { denom: 'udvpn', base_value: sessionMaxPrice.base_value, quote_value: sessionMaxPrice.quote_value },
       },
     };
 
@@ -477,10 +477,10 @@ export async function connectDirect(opts) {
       typeUrl: MSG_TYPES.START_SESSION,
       value: {
         from: account.address,
-        node_address: opts.nodeAddress,
+        nodeAddress: opts.nodeAddress,
         gigabytes: retryGigabytes,
         hours: retryHours,
-        max_price: { denom: 'udvpn', base_value: retryMaxPrice.base_value, quote_value: retryMaxPrice.quote_value },
+        maxPrice: { denom: 'udvpn', base_value: retryMaxPrice.base_value, quote_value: retryMaxPrice.quote_value },
       },
     };
     checkAborted(signal);

package/cosmjs-setup.js

@@ -50,7 +50,7 @@ import {
   encodeMsgStartLease,
   encodeMsgEndLease,
 } from './plan-operations.js';
-import { GAS_PRICE, LCD_ENDPOINTS, tryWithFallback } from './defaults.js';
+import { GAS_PRICE, RPC_ENDPOINTS, LCD_ENDPOINTS, tryWithFallback } from './defaults.js';
 import { ValidationError, NodeError, ChainError, ErrorCodes } from './errors.js';
 import path from 'path';
 import os from 'os';
@@ -216,12 +216,57 @@ export function buildRegistry() {
 /**
  * Create a SigningStargateClient connected to Sentinel RPC.
  * Gas price: from defaults.js GAS_PRICE (chain minimum).
- */
-export async function createClient(rpcUrl, wallet) {
-  return SigningStargateClient.connectWithSigner(rpcUrl, wallet, {
-    gasPrice: GasPrice.fromString(GAS_PRICE),
-    registry: buildRegistry(),
-  });
+ *
+ * Signatures:
+ *   createClient(rpcUrl, wallet)  — classic: connect to specific RPC with existing wallet
+ *   createClient(mnemonic)        — convenience: create wallet from mnemonic, try RPC endpoints with failover
+ *
+ * @param {string} rpcUrlOrMnemonic - Either an RPC URL (https://...) or a BIP39 mnemonic
+ * @param {DirectSecp256k1HdWallet} [wallet] - Wallet object (required when first arg is RPC URL)
+ * @returns {Promise<SigningStargateClient>} Connected signing client with full Sentinel registry
+ */
+export async function createClient(rpcUrlOrMnemonic, wallet) {
+  // Classic call: createClient(rpcUrl, wallet)
+  if (wallet) {
+    return SigningStargateClient.connectWithSigner(rpcUrlOrMnemonic, wallet, {
+      gasPrice: GasPrice.fromString(GAS_PRICE),
+      registry: buildRegistry(),
+    });
+  }
+
+  // If first arg looks like a URL, it's a missing wallet — throw helpful error
+  if (typeof rpcUrlOrMnemonic === 'string' && /^(https?|wss?):\/\//i.test(rpcUrlOrMnemonic)) {
+    throw new ValidationError(ErrorCodes.INVALID_MNEMONIC,
+      'createClient(rpcUrl, wallet): wallet parameter is required when passing an RPC URL. ' +
+      'Use createClient(mnemonic) for convenience, or createClient(rpcUrl, wallet) with an existing wallet.',
+      { value: rpcUrlOrMnemonic });
+  }
+
+  // Convenience call: createClient(mnemonic) — create wallet + try RPC endpoints
+  validateMnemonic(rpcUrlOrMnemonic, 'createClient');
+  const { wallet: derivedWallet } = await createWallet(rpcUrlOrMnemonic);
+  const registry = buildRegistry();
+  const gasPrice = GasPrice.fromString(GAS_PRICE);
+
+  // Try each RPC endpoint until one connects
+  const errors = [];
+  for (const ep of RPC_ENDPOINTS) {
+    try {
+      const client = await SigningStargateClient.connectWithSigner(ep.url, derivedWallet, {
+        gasPrice,
+        registry,
+      });
+      return client;
+    } catch (err) {
+      errors.push({ endpoint: ep.url, name: ep.name, error: err.message });
+    }
+  }
+
+  // All endpoints failed
+  const tried = errors.map(e => `  ${e.name} (${e.endpoint}): ${e.error}`).join('\n');
+  throw new ChainError('ALL_ENDPOINTS_FAILED',
+    `createClient(mnemonic): failed to connect to all ${RPC_ENDPOINTS.length} RPC endpoints:\n${tried}`,
+    { endpoints: errors });
 }
 
 // ─── TX Helpers ──────────────────────────────────────────────────────────────