blue-js-sdk 2.0.3 → 2.1.1

package/ai-path/cli.js

@@ -125,6 +125,9 @@ function showHelp() {
   console.log(`  --protocol <type>   Protocol: wireguard or v2ray`);
   console.log(`  --dns <preset>      DNS: google, cloudflare, or hns (Handshake)`);
   console.log(`  --node <address>    Connect to specific node (sentnode1...)`);
+  console.log(`  --subscription <id> Connect via operator-provisioned subscription`);
+  console.log(`  --plan <id>         Connect via plan (subscribe + start session)`);
+  console.log(`  --fee-granter <addr> Operator address that pays gas (sent1...)`);
   console.log('');
   console.log(`${c.bold}NODES OPTIONS${c.reset}`);
   console.log(`  --country <code>    Filter by country`);
@@ -143,6 +146,10 @@ function showHelp() {
   console.log(`  sentinel-ai connect --country DE --protocol wireguard`);
   console.log(`  sentinel-ai connect --node sentnode1abc...`);
   console.log('');
+  console.log(`  ${c.dim}# Connect via subscription (operator-provisioned, zero P2P needed)${c.reset}`);
+  console.log(`  sentinel-ai connect --subscription 1165072 --fee-granter sent1operator...`);
+  console.log(`  sentinel-ai connect --plan 42 --fee-granter sent1operator...`);
+  console.log('');
   console.log(`  ${c.dim}# List nodes${c.reset}`);
   console.log(`  sentinel-ai nodes --country US --limit 10`);
   console.log('');
@@ -295,12 +302,18 @@ async function cmdConnect(flags) {
   if (flags.protocol) opts.protocol = flags.protocol;
   if (flags.dns) opts.dns = flags.dns;
   if (flags.node) opts.nodeAddress = flags.node;
+  if (flags.subscription) opts.subscriptionId = flags.subscription;
+  if (flags.plan) opts.planId = flags.plan;
+  if (flags['fee-granter']) opts.feeGranter = flags['fee-granter'];
 
   console.log(`${info} Connecting to Sentinel dVPN...`);
   if (flags.country) console.log(`  Country:  ${c.cyan}${flags.country}${c.reset}`);
   if (flags.protocol) console.log(`  Protocol: ${c.cyan}${flags.protocol}${c.reset}`);
   if (flags.dns) console.log(`  DNS:      ${c.cyan}${flags.dns}${c.reset}`);
   if (flags.node) console.log(`  Node:     ${c.cyan}${flags.node}${c.reset}`);
+  if (flags.subscription) console.log(`  Subscription: ${c.cyan}${flags.subscription}${c.reset}`);
+  if (flags.plan) console.log(`  Plan:     ${c.cyan}${flags.plan}${c.reset}`);
+  if (flags['fee-granter']) console.log(`  Fee granter: ${c.cyan}${flags['fee-granter']}${c.reset}`);
   console.log('');
 
   const { connect, disconnect } = await import('./index.js');

package/ai-path/connect.js

@@ -19,6 +19,8 @@
 import {
   connectAuto,
   connectDirect,
+  connectViaSubscription,
+  connectViaPlan,
   disconnect as sdkDisconnect,
   isConnected,
   getStatus,
@@ -245,6 +247,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 +264,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,13 +351,17 @@ 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 4/7: Node Selection ──────────────────────────────────────────────
@@ -549,7 +566,22 @@ 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;
       result = await connectDirect(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/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/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

@@ -130,7 +130,7 @@ async function connectInternal(opts, paymentStrategy, retryStrategy, state = _de
   try {
     const bal = await getBalance(client, account.address);
     progress(onProgress, logFn, 'wallet', `${account.address} | ${bal.dvpn.toFixed(1)} P2P`);
-    if (!opts.dryRun && bal.udvpn < 100000) {
+    if (!opts.dryRun && !opts.feeGranter && bal.udvpn < 100000) {
       throw new ChainError(ErrorCodes.INSUFFICIENT_BALANCE,
         `Wallet has ${bal.dvpn.toFixed(2)} P2P — need at least 0.1 P2P for a session. Fund address ${account.address} with P2P tokens.`,
         { balance: bal, address: account.address }
@@ -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);
@@ -769,8 +769,23 @@ export async function connectViaSubscription(opts) {
     };
 
     checkAborted(signal);
-    progress(null, opts.log || defaultLog, 'session', `Starting session via subscription ${opts.subscriptionId}...`);
-    const result = await broadcastWithInactiveRetry(client, account.address, [msg], opts.log || defaultLog, opts.onProgress);
+
+    // Fee grant: operator pays gas for the agent (e.g., x402 managed plan flow)
+    const feeGranter = opts.feeGranter || null;
+    progress(null, opts.log || defaultLog, 'session', `Starting session via subscription ${opts.subscriptionId}${feeGranter ? ' (fee granted)' : ''}...`);
+
+    let result;
+    if (feeGranter) {
+      try {
+        result = await broadcastWithFeeGrant(client, account.address, [msg], feeGranter);
+      } catch (feeErr) {
+        // Fee grant TX failed — fall back to user-paid
+        progress(null, opts.log || defaultLog, 'session', 'Fee grant failed, paying gas from wallet...');
+        result = await broadcastWithInactiveRetry(client, account.address, [msg], opts.log || defaultLog, opts.onProgress);
+      }
+    } else {
+      result = await broadcastWithInactiveRetry(client, account.address, [msg], opts.log || defaultLog, opts.onProgress);
+    }
     const extracted = extractId(result, /session/i, ['session_id', 'id']);
     if (!extracted) throw new ChainError(ErrorCodes.SESSION_EXTRACT_FAILED, 'Failed to extract session ID from subscription TX result', { txHash: result.transactionHash });
     const sessionId = BigInt(extracted);