blue-js-sdk 2.1.0 → 2.2.0

package/ai-path/connect.js

@@ -19,6 +19,8 @@
 import {
   connectAuto,
   connectDirect,
+  connectViaSubscription,
+  connectViaPlan,
   disconnect as sdkDisconnect,
   isConnected,
   getStatus,
@@ -32,9 +34,12 @@ import {
   getBalance as sdkGetBalance,
   tryWithFallback,
   RPC_ENDPOINTS,
+  LCD_ENDPOINTS,
+  queryFeeGrant,
   // v1.5.0: RPC queries (protobuf, ~10x faster than LCD for balance checks)
   createRpcQueryClientWithFallback,
   rpcQueryBalance,
+  rpcQueryFeeGrant,
   // v1.5.0: Typed event parsers (replaces string matching for session ID extraction)
   extractSessionIdTyped,
   NodeEventCreateSession,
@@ -191,6 +196,18 @@ function humanError(err) {
       message: 'Connection was cancelled.',
       nextAction: 'none',
     },
+    FEE_GRANT_NOT_FOUND: {
+      message: 'No fee grant from operator to agent. Operator must provision a grant first.',
+      nextAction: 'request_fee_grant',
+    },
+    FEE_GRANT_EXPIRED: {
+      message: 'Fee grant has expired. Operator must renew the grant.',
+      nextAction: 'request_fee_grant_renewal',
+    },
+    FEE_GRANT_EXHAUSTED: {
+      message: 'Fee grant spend limit exhausted. Operator must top up the grant.',
+      nextAction: 'request_fee_grant_renewal',
+    },
   };
 
   const entry = messages[code];
@@ -245,6 +262,14 @@ async function preValidateBalance(mnemonic) {
 /**
  * Connect to Sentinel dVPN. The ONE function an AI agent needs.
  *
+ * Three connection modes:
+ *   1. Direct payment — agent pays per-session from own wallet (default)
+ *   2. Subscription — operator provisioned a subscription for this agent
+ *   3. Plan — subscribe to plan + start session (optionally fee-granted)
+ *
+ * For modes 2 & 3, set opts.feeGranter to the operator's address — the
+ * agent can have 0 P2P balance and the operator covers gas.
+ *
  * Every step is logged with numbered phases (STEP 1/7 through STEP 7/7)
  * so an autonomous agent can track progress and diagnose failures.
  *
@@ -254,6 +279,9 @@ async function preValidateBalance(mnemonic) {
  * @param {string} [opts.nodeAddress] - Specific node (sentnode1...). Skips auto-pick.
  * @param {string} [opts.dns] - DNS preset: 'google', 'cloudflare', 'hns'
  * @param {string} [opts.protocol] - Preferred protocol: 'wireguard' or 'v2ray'
+ * @param {string|number} [opts.subscriptionId] - Connect via existing subscription (operator-provisioned)
+ * @param {string|number} [opts.planId] - Connect via plan (subscribes + starts session)
+ * @param {string} [opts.feeGranter] - Operator address that pays gas (sent1...). Skips balance check.
  * @param {function} [opts.onProgress] - Progress callback: (stage, message) => void
  * @param {number} [opts.timeout] - Connection timeout in ms (default: 120000 — 2 minutes)
  * @param {boolean} [opts.silent] - If true, suppress step-by-step console output
@@ -338,15 +366,114 @@ export async function connect(opts = {}) {
   const balCheck = await preValidateBalance(opts.mnemonic);
   log(3, totalSteps, 'BALANCE', `Balance: ${balCheck.p2p} | Sufficient: ${balCheck.sufficient}`);
 
-  if (!balCheck.sufficient && !opts.dryRun) {
+  // Skip balance gate when fee granter is set — agent may have 0 P2P, operator pays gas
+  if (!balCheck.sufficient && !opts.dryRun && !opts.feeGranter) {
     const err = new Error(`Insufficient balance: ${balCheck.p2p}. Need at least ${formatP2P(MIN_BALANCE_UDVPN)}. Fund address: ${walletAddress}`);
     err.code = 'INSUFFICIENT_BALANCE';
     err.nextAction = 'fund_wallet';
     err.details = { address: walletAddress, balance: balCheck.p2p, minimum: formatP2P(MIN_BALANCE_UDVPN) };
     throw err;
   }
+  if (opts.feeGranter && !balCheck.sufficient) {
+    log(3, totalSteps, 'BALANCE', `Balance below minimum but fee granter ${opts.feeGranter} covers gas`);
+  }
   timings.balance = Date.now() - t0;
 
+  // ── STEP 3.5: Fee Grant Validity Check (when feeGranter is set) ───────────
+  // Verify the fee grant exists on-chain and hasn't expired before attempting
+  // a connection that would fail at broadcast time.
+
+  if (opts.feeGranter) {
+    try {
+      // RPC first (protobuf, ~10x faster), LCD fallback
+      let grant = null;
+      try {
+        const rpcClient = await createRpcQueryClientWithFallback();
+        grant = await rpcQueryFeeGrant(rpcClient, opts.feeGranter, walletAddress);
+      } catch {
+        // RPC failed — fall back to LCD with failover
+        const lcdResult = await tryWithFallback(
+          LCD_ENDPOINTS,
+          async (endpoint) => {
+            const url = endpoint?.url || endpoint;
+            return queryFeeGrant(url, opts.feeGranter, walletAddress);
+          },
+          'fee grant pre-check (LCD fallback)',
+        );
+        grant = lcdResult.result;
+      }
+
+      if (!grant) {
+        const err = new Error(`No fee grant found from ${opts.feeGranter} to ${walletAddress}. Operator must create a fee grant before agent can connect with 0 P2P.`);
+        err.code = 'FEE_GRANT_NOT_FOUND';
+        err.nextAction = 'request_fee_grant';
+        err.details = { granter: opts.feeGranter, grantee: walletAddress };
+        throw err;
+      }
+
+      // Unwrap grant structure: AllowedMsgAllowance > BasicAllowance
+      // Chain returns: { allowance: { "@type": "AllowedMsg...", allowance: { "@type": "Basic...", spend_limit, expiration }, allowed_messages: [...] } }
+      const outerAllowance = grant.allowance || grant;
+      const isAllowedMsg = outerAllowance['@type']?.includes('AllowedMsgAllowance');
+      const inner = isAllowedMsg ? (outerAllowance.allowance || outerAllowance) : outerAllowance;
+      const expiration = inner.expiration || outerAllowance.expiration;
+
+      // Check expiration
+      if (expiration) {
+        const expiresAt = new Date(expiration);
+        const now = new Date();
+        if (expiresAt <= now) {
+          const err = new Error(`Fee grant from ${opts.feeGranter} expired at ${expiresAt.toISOString()}. Operator must renew the fee grant.`);
+          err.code = 'FEE_GRANT_EXPIRED';
+          err.nextAction = 'request_fee_grant_renewal';
+          err.details = { granter: opts.feeGranter, grantee: walletAddress, expiredAt: expiresAt.toISOString() };
+          throw err;
+        }
+
+        const hoursLeft = (expiresAt - now) / 3600000;
+        if (hoursLeft < 1) {
+          log(3, totalSteps, 'FEE_GRANT', `Warning: Fee grant expires in ${Math.round(hoursLeft * 60)} minutes`);
+        } else {
+          log(3, totalSteps, 'FEE_GRANT', `Fee grant valid, expires ${expiresAt.toISOString()} (${Math.round(hoursLeft)}h remaining)`);
+        }
+      } else {
+        log(3, totalSteps, 'FEE_GRANT', 'Fee grant valid (no expiration)');
+      }
+
+      // Check spend_limit — if set, ensure there's enough remaining for at least one TX
+      const spendLimit = inner.spend_limit;
+      if (spendLimit && Array.isArray(spendLimit)) {
+        const udvpnLimit = spendLimit.find(c => c.denom === 'udvpn');
+        if (udvpnLimit) {
+          const remaining = parseInt(udvpnLimit.amount, 10) || 0;
+          if (remaining < 20000) { // 20,000 udvpn = minimum for one session TX
+            const err = new Error(`Fee grant from ${opts.feeGranter} has insufficient spend limit: ${remaining} udvpn remaining (need 20,000 for session TX). Operator must top up the grant.`);
+            err.code = 'FEE_GRANT_EXHAUSTED';
+            err.nextAction = 'request_fee_grant_renewal';
+            err.details = { granter: opts.feeGranter, grantee: walletAddress, remainingUdvpn: remaining };
+            throw err;
+          }
+          log(3, totalSteps, 'FEE_GRANT', `Spend limit: ${remaining} udvpn remaining`);
+        }
+      }
+
+      // Check allowed_messages — verify it includes the messages we need
+      const allowedMessages = isAllowedMsg ? (outerAllowance.allowed_messages || []) : [];
+      if (allowedMessages.length > 0) {
+        const needsStart = allowedMessages.some(m =>
+          m.includes('MsgStartSession') || m.includes('MsgStartSessionRequest'),
+        );
+        if (!needsStart) {
+          log(3, totalSteps, 'FEE_GRANT', `Warning: allowed_messages doesn't include MsgStartSession — TX may fail`);
+        }
+      }
+    } catch (err) {
+      if (err.code === 'FEE_GRANT_NOT_FOUND' || err.code === 'FEE_GRANT_EXPIRED' || err.code === 'FEE_GRANT_EXHAUSTED') throw err;
+      // Non-critical — LCD query failed but fee grant may still work at broadcast time
+      log(3, totalSteps, 'FEE_GRANT', `Could not verify fee grant (${err.message}) — proceeding anyway`);
+    }
+  }
+
   // ── STEP 4/7: Node Selection ──────────────────────────────────────────────
 
   t0 = Date.now();
@@ -549,14 +676,31 @@ export async function connect(opts = {}) {
   try {
     let result;
 
-    if (resolvedNodeAddress) {
+    // ── Connection mode: subscription > plan > direct > auto ──────────────
+    if (opts.subscriptionId) {
+      // Subscription mode — operator already provisioned a subscription for this agent
+      log(5, totalSteps, 'SESSION', `Connecting via subscription ${opts.subscriptionId}${opts.feeGranter ? ' (fee granted)' : ''}...`);
+      sdkOpts.subscriptionId = opts.subscriptionId;
+      if (opts.feeGranter) sdkOpts.feeGranter = opts.feeGranter;
+      if (resolvedNodeAddress) sdkOpts.nodeAddress = resolvedNodeAddress;
+      result = await connectViaSubscription(sdkOpts);
+    } else if (opts.planId) {
+      // Plan mode — subscribe to plan + start session (optionally fee-granted)
+      log(5, totalSteps, 'SESSION', `Connecting via plan ${opts.planId}${opts.feeGranter ? ' (fee granted)' : ''}...`);
+      sdkOpts.planId = opts.planId;
+      if (opts.feeGranter) sdkOpts.feeGranter = opts.feeGranter;
+      if (resolvedNodeAddress) sdkOpts.nodeAddress = resolvedNodeAddress;
+      result = await connectViaPlan(sdkOpts);
+    } else if (resolvedNodeAddress) {
       // Direct connection — either user specified nodeAddress or country discovery found one
       sdkOpts.nodeAddress = resolvedNodeAddress;
+      if (opts.feeGranter) sdkOpts.feeGranter = opts.feeGranter;
       result = await connectDirect(sdkOpts);
     } else {
       // No country filter or country discovery found nothing — auto-select globally
       // Use higher maxAttempts to search more nodes
       if (!sdkOpts.maxAttempts) sdkOpts.maxAttempts = 5;
+      if (opts.feeGranter) sdkOpts.feeGranter = opts.feeGranter;
       result = await connectAuto(sdkOpts);
     }
 

package/ai-path/index.js

@@ -65,10 +65,15 @@ export {
   subscribeToPlan,
   hasActiveSubscription,
   querySubscriptions,
+  querySubscriptionAllocations,
   queryPlanNodes,
   queryFeeGrants,
   buildFeeGrantMsg,
   broadcastWithFeeGrant,
+  // v2.1.0: Subscription sharing + onboarding (operator provisions agent access)
+  shareSubscription,
+  shareSubscriptionWithFeeGrant,
+  onboardPlanUser,
   rpcQueryNodesForPlan,
   rpcQuerySubscriptionsForAccount,
 } from '../index.js';

package/ai-path/pricing.js

@@ -6,7 +6,7 @@
 
 import {
   estimateSessionCost,
-  estimateSessionPrice,
+  getNodePrices,
   formatP2P,
   PRICING_REFERENCE,
   DENOM,
@@ -81,11 +81,12 @@ export async function estimateCost(opts = {}) {
   const gb = opts.gigabytes || 1;
   const gasCost = 40000; // ~0.04 P2P per TX
 
-  // If specific node given, get exact price
+  // If specific node given, get exact price via RPC-first node query
   if (opts.nodeAddress) {
     try {
-      const price = await estimateSessionPrice(opts.nodeAddress, gb);
-      const total = price.udvpn || price.amount || 0;
+      const prices = await getNodePrices(opts.nodeAddress);
+      const perGbUdvpn = prices.gigabyte.udvpn || 0;
+      const total = perGbUdvpn * gb;
       const grandTotal = total + gasCost;
 
       const result = {