blue-js-sdk 2.1.1 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 Every fix made during SDK creation, why it matters, and what happens if you use upstream Sentinel code directly without these fixes.
 
+## v2.3.0 — RPC-First Migration (2026-04-14)
+
+**100% of chain queries now use RPC-first with LCD fallback.** Protobuf/ABCI queries via Tendermint37Client are ~912x faster than LCD REST. If RPC fails, every query automatically falls back to LCD.
+
+### JS SDK Changes
+- **chain/rpc.js**: Added 4 new RPC functions — `rpcQueryFeeGrants`, `rpcQueryFeeGrantsIssued`, `rpcQueryAuthzGrants`, `rpcQueryProvider`
+- **chain/queries.js**: All 22 query functions are RPC-first with LCD fallback
+- **chain/fee-grants.js**: All 7 functions are RPC-first with LCD fallback
+- **cosmjs-setup.js**: All 28 query bodies replaced with thin wrappers delegating to RPC-first modules
+- **session-manager.js**: `buildSessionMap()` now uses RPC-first `querySessions()`
+- **batch.js**: `waitForBatchSessions()` now uses RPC-first `querySessions()`
+- **defaults.js**: Added runtime endpoint management — `addRpcEndpoint`, `removeRpcEndpoint`, `setEndpoints`, `getEndpoints`, `checkRpcEndpointHealth`, `optimizeEndpoints`
+- **index.js**: 16 RPC query exports + 8 endpoint management exports
+- **SDK_VERSION**: Bumped to 2.3.0
+
+### C# SDK Changes
+- **RpcClient.cs**: Wired into ChainClient. 17 typed query methods (sessions, subscriptions, nodes, balance, provider, fee grants, authz, allocations)
+- **ProtobufReader.cs**: Added `DecodeSession`, `DecodeSubscription`, `DecodeProvider` decoders
+- **ChainClient.Queries.cs**: 13 methods upgraded to RPC-first with LCD fallback
+- **ChainClient.FeeGrants.cs**: 2 methods upgraded to RPC-first with LCD fallback
+- **Total**: 15 direct + 9 transitive = 24 query methods are RPC-first
+
+### Coverage
+| Module | RPC-First | Total |
+|--------|-----------|-------|
+| JS chain/queries.js | 22/22 | 100% |
+| JS chain/fee-grants.js | 7/7 | 100% |
+| JS session-manager.js | 1/1 | 100% |
+| JS batch.js | 1/1 | 100% |
+| C# ChainClient.Queries | 13/13 | 100% |
+| C# ChainClient.FeeGrants | 2/2 | 100% |
+
+---
+
 ## Documentation Versions
 
 | Version | Date | Changes |

package/ai-path/DECISION-TREE.md

@@ -56,38 +56,59 @@ Agent needs wallet
     │
     └── Is wallet funded?
         ├── getBalance(mnemonic) → { funded: true } → continue
-        └── getBalance(mnemonic) → { funded: false }
-            │
-            ├── Agent has crypto on other chains?
-            │   ├── Has ATOM → swap on Osmosis DEX (ATOM → P2P)
-            │   ├── Has USDT/USDC → swap on Osmosis DEX (stable → ATOM → P2P)
-            │   ├── Has ETH → bridge to Cosmos via Gravity Bridge or Axelar, then swap
-            │   └── Has SOL/other → no direct bridge yet
-            │       └── OUTPUT: { action: 'funding-request', address: 'sent1...', amount: '100000 udvpn', reason: 'minimum for 1 VPN session', acceptedTokens: ['udvpn', 'ATOM via Osmosis'] }
-            │
-            ├── Agent has fiat payment method?
-            │   └── OUTPUT: { action: 'fiat-not-supported-yet', workaround: 'buy ATOM on exchange → send to Cosmos wallet → swap to P2P on Osmosis', futureSupport: 'planned' }
-            │
-            ├── Agent is operated by a company/human?
-            │   └── OUTPUT: { action: 'request-funding', to: 'operator', address: 'sent1...', minAmount: '1000000 udvpn (1 P2P)', estimatedUsage: '~10 GB or ~10 sessions' }
-            │
-            └── Agent has no payment capability?
-                └── OUTPUT: {
-                      action: 'funding-needed',
-                      address: 'sent1...',
-                      minAmount: { udvpn: 1000000, p2p: '1.0 P2P', note: 'Covers gas + 1 GB on cheapest node' },
-                      methods: [
-                        { method: 'direct-transfer', description: 'Send P2P tokens to this address' },
-                        { method: 'osmosis-swap', description: 'Swap ATOM/USDT → P2P on app.osmosis.zone' },
-                        { method: 'operator-grant', description: 'Fee grant from plan operator covers gas' },
-                      ],
-                      request: {
-                        type: 'funding-request',
-                        reason: 'Autonomous agent needs VPN access for [task description]',
-                        willingness: 'Will pay up to X per GB if funded',
-                        contact: null,
-                      }
-                    }
+        ├── getBalance(mnemonic) → { funded: false }
+        │   │
+        │   ├── Agent has operator-provisioned access (x402 / fee grant)?
+        │   │   ├── Has subscriptionId + feeGranter → OPERATOR-PROVISIONED MODE
+        │   │   │   └── connect({ mnemonic, subscriptionId, feeGranter, nodeAddress })
+        │   │   │       ├── Fee grant valid → connect with 0 P2P (operator pays gas)
+        │   │   │       ├── FEE_GRANT_NOT_FOUND → request provisioning from operator
+        │   │   │       ├── FEE_GRANT_EXPIRED → request grant renewal from operator
+        │   │   │       ├── FEE_GRANT_EXHAUSTED → request operator to top up grant
+        │   │   │       └── Disconnect also uses fee grant (MsgCancelSessionRequest)
+        │   │   ├── Has planId + feeGranter → PLAN MODE with fee grant
+        │   │   │   └── connect({ mnemonic, planId, feeGranter })
+        │   │   │       └── Subscribes to plan + starts session, operator pays gas
+        │   │   └── Has USDC on Base/Solana → x402 PAYMENT MODE
+        │   │       └── 1. Register sent1... address with x402 server
+        │   │           2. Pay USDC via EIP-3009 (Base) or SPL transfer (Solana)
+        │   │           3. Server provisions: subscription share + fee grant
+        │   │           4. connect({ mnemonic, subscriptionId, feeGranter, nodeAddress })
+        │   │           5. Agent connects with 0 P2P
+        │   │
+        │   ├── Agent has crypto on other chains?
+        │   │   ├── Has ATOM → swap on Osmosis DEX (ATOM → P2P)
+        │   │   ├── Has USDT/USDC → swap on Osmosis DEX (stable → ATOM → P2P)
+        │   │   ├── Has ETH → bridge to Cosmos via Gravity Bridge or Axelar, then swap
+        │   │   └── Has SOL/other → no direct bridge yet
+        │   │       └── OUTPUT: { action: 'funding-request', address: 'sent1...', amount: '100000 udvpn', reason: 'minimum for 1 VPN session', acceptedTokens: ['udvpn', 'ATOM via Osmosis'] }
+        │   │
+        │   ├── Agent has fiat payment method?
+        │   │   └── OUTPUT: { action: 'fiat-not-supported-yet', workaround: 'buy ATOM on exchange → send to Cosmos wallet → swap to P2P on Osmosis', futureSupport: 'planned' }
+        │   │
+        │   ├── Agent is operated by a company/human?
+        │   │   └── OUTPUT: { action: 'request-funding', to: 'operator', address: 'sent1...', minAmount: '1000000 udvpn (1 P2P)', estimatedUsage: '~10 GB or ~10 sessions' }
+        │   │
+        │   └── Agent has no payment capability?
+        │       └── OUTPUT: {
+        │             action: 'funding-needed',
+        │             address: 'sent1...',
+        │             minAmount: { udvpn: 1000000, p2p: '1.0 P2P', note: 'Covers gas + 1 GB on cheapest node' },
+        │             methods: [
+        │               { method: 'direct-transfer', description: 'Send P2P tokens to this address' },
+        │               { method: 'osmosis-swap', description: 'Swap ATOM/USDT → P2P on app.osmosis.zone' },
+        │               { method: 'operator-grant', description: 'Fee grant from plan operator covers gas' },
+        │               { method: 'x402-payment', description: 'Pay USDC on Base/Solana via x402 protocol — operator provisions access' },
+        │             ],
+        │             request: {
+        │               type: 'funding-request',
+        │               reason: 'Autonomous agent needs VPN access for [task description]',
+        │               willingness: 'Will pay up to X per GB if funded',
+        │               contact: null,
+        │             }
+        │           }
+        │
+        └── getBalance(mnemonic) → { funded: true } → continue
 ```
 
 ## Decision Node 4: WHICH NODE DO I CONNECT TO?
@@ -315,28 +336,47 @@ Agent can't solve problem alone
 
 ```
 Agent has funds but wrong type
+    │
+    ├── Has USDC on Base (preferred — cheapest, x402 native)
+    │   ├── x402 protocol: pay USDC on Base → get VPN access instantly
+    │   ├── Price: $0.033/day, $0.233/week, $1.00/month
+    │   ├── Flow: register sent1... → pay via EIP-3009 → server provisions sub + fee grant
+    │   └── OUTPUT: {
+    │         action: 'x402-payment',
+    │         chain: 'base',
+    │         contract: '0x923F41eb162d4F7D274CE8cE8b8178883E7E2196',
+    │         steps: ['register sent1... with x402 server', 'approve USDC', 'pay via contract', 'connect with subscriptionId + feeGranter'],
+    │         estimatedTime: '<30s',
+    │         estimatedFees: '<$0.001 (Base L2 gas)',
+    │         pricing: { '1day': '$0.033', '7days': '$0.233', '30days': '$1.00' },
+    │       }
+    │
+    ├── Has USDC on Solana
+    │   ├── x402 protocol: SPL transfer + memo to operator
+    │   └── OUTPUT: { action: 'x402-payment', chain: 'solana', steps: ['SPL transfer to operator ATA', 'memo: x402:sent1...:hours:N'], estimatedTime: '<5s' }
     │
     ├── Has USDT (ERC-20 Ethereum)
     │   ├── Bridge: Gravity Bridge or Axelar to Cosmos
     │   ├── Then: Osmosis DEX swap USDT → P2P
     │   └── OUTPUT: { action: 'cross-chain-swap', steps: ['bridge to cosmos', 'swap on osmosis'], estimatedTime: '15-30min', estimatedFees: '~$2-5 bridge + swap' }
     │
-    ├── Has USDC (multiple chains)
+    ├── Has USDC on other chains (Ethereum, Cosmos/Noble)
     │   ├── If on Cosmos/Noble → direct swap on Osmosis
-    │   ├── If on Ethereum → bridge first
-    │   └── OUTPUT: { steps: [...], cheapestPath: 'Noble USDC → Osmosis → P2P' }
+    │   ├── If on Ethereum → bridge first (or swap to Base USDC and use x402)
+    │   └── OUTPUT: { steps: [...], cheapestPath: 'Bridge to Base → x402 payment' }
     │
-    ├── Has SOL
-    │   ├── No direct bridge to Cosmos yet
-    │   └── OUTPUT: { action: 'unsupported-currently', workaround: 'swap SOL→USDT on DEX, bridge to Cosmos, swap to P2P' }
+    ├── Has SOL (not USDC)
+    │   ├── Swap SOL → USDC on Jupiter/Raydium, then use x402 Solana payment
+    │   └── OUTPUT: { action: 'swap-then-x402', steps: ['swap SOL→USDC on Jupiter', 'x402 payment via Solana'], estimatedTime: '<30s' }
     │
     ├── Has BTC
     │   ├── Nomic bridge (BTC → nBTC on Cosmos) → Osmosis → P2P
     │   └── OUTPUT: { action: 'cross-chain-swap', via: 'Nomic Bridge', steps: [...] }
     │
     ├── Has credit card / fiat only
-    │   ├── Buy ATOM on Coinbase/Binance/Kraken → withdraw to Cosmos wallet → Osmosis → P2P
-    │   └── OUTPUT: { action: 'fiat-onramp', steps: ['buy ATOM on exchange', 'withdraw to sent1... address', 'swap on Osmosis'], estimatedTime: '1-24h depending on exchange' }
+    │   ├── Buy USDC on Coinbase → send to Base wallet → use x402 (fastest)
+    │   ├── Buy ATOM on exchange → withdraw to Cosmos → Osmosis → P2P (slower)
+    │   └── OUTPUT: { action: 'fiat-onramp', steps: ['buy USDC on Coinbase/Binance', 'withdraw to Base wallet', 'x402 payment'], estimatedTime: '1-24h depending on exchange' }
     │
     └── Has nothing — pure autonomous agent with no funds
         └── OUTPUT: {
@@ -349,6 +389,7 @@ Agent has funds but wrong type
                 planOperatorBenefit: 'Agent drives usage and network growth',
               },
               alternatives: [
+                'x402 payment: pay USDC on Base/Solana (cheapest — $0.033/day)',
                 'Apply for fee grant from plan operator',
                 'Request funding from agent marketplace (future)',
                 'Earn tokens by providing node quality reports (future)',
@@ -360,7 +401,10 @@ Agent has funds but wrong type
 
 | Error Code | Agent Action |
 |-----------|-------------|
-| `INSUFFICIENT_BALANCE` | Fund wallet → Decision Node 3 |
+| `INSUFFICIENT_BALANCE` | Fund wallet → Decision Node 3 (or use x402/fee grant) |
+| `FEE_GRANT_NOT_FOUND` | No fee grant from operator → request provisioning |
+| `FEE_GRANT_EXPIRED` | Fee grant expired → request renewal from operator |
+| `FEE_GRANT_EXHAUSTED` | Fee grant spend limit too low → request operator to top up |
 | `NODE_OFFLINE` | SDK auto-retries. If all fail → try different country |
 | `NODE_INACTIVE` | SDK retries after 15s. If fails → different node |
 | `V2RAY_NOT_FOUND` | Run `node setup.js` |

package/ai-path/E2E-FLOW.md

@@ -532,6 +532,158 @@ Event attributes may be base64-encoded (depends on CosmJS version). The SDK hand
 
 **Minimum 7 seconds between transactions.** Rapid TX submission causes sequence mismatch cascades. NEVER run parallel chain operations -- rate limits will kill your internet connectivity.
 
+### Fee-Granted Session Creation (Operator-Provisioned Mode)
+
+When an operator has provisioned a subscription share and fee grant for the agent, the session creation flow changes:
+
+#### Pre-Check: Fee Grant Validity
+
+Before attempting the session TX, the SDK validates the fee grant on-chain using **RPC first** (protobuf, ~250ms), with **LCD fallback** (~880ms). This matches the SDK standard: all chain queries use RPC with LCD as a safety net.
+
+**RPC path (primary):**
+
+```javascript
+import { createRpcQueryClientWithFallback, rpcQueryFeeGrant } from 'sentinel-dvpn-sdk';
+
+const rpcClient = await createRpcQueryClientWithFallback();
+const grant = await rpcQueryFeeGrant(rpcClient, granter, grantee);
+```
+
+`rpcQueryFeeGrant` performs a protobuf ABCI query to `/cosmos.feegrant.v1beta1.Query/Allowance`. It decodes the nested protobuf response: `Grant` → `Any` (allowance) → `AllowedMsgAllowance` → `BasicAllowance` → `spend_limit` + `expiration`.
+
+**LCD path (fallback):**
+
+```
+GET /cosmos/feegrant/v1beta1/allowance/{granter}/{grantee}
+```
+
+Used only when RPC fails. Falls back across `LCD_ENDPOINTS` via `tryWithFallback()`.
+
+**Response structure** (both RPC and LCD normalize to this):
+
+```json
+{
+  "allowance": {
+    "@type": "/cosmos.feegrant.v1beta1.AllowedMsgAllowance",
+    "allowance": {
+      "@type": "/cosmos.feegrant.v1beta1.BasicAllowance",
+      "spend_limit": [{ "denom": "udvpn", "amount": "5000000" }],
+      "expiration": "2026-04-16T00:00:00Z"
+    },
+    "allowed_messages": [
+      "/sentinel.subscription.v3.MsgStartSessionRequest",
+      "/sentinel.session.v3.MsgCancelSessionRequest",
+      "/sentinel.session.v3.MsgUpdateSessionRequest",
+      "/sentinel.node.v3.MsgStartSessionRequest"
+    ]
+  }
+}
+```
+
+**The SDK performs five checks:**
+
+1. **Existence** — grant is non-null → `FEE_GRANT_NOT_FOUND` if missing
+2. **Structure detection** — robust `@type`-based detection of `AllowedMsgAllowance` vs bare `BasicAllowance` (handles both wrapped and unwrapped)
+3. **Expiration** — `FEE_GRANT_EXPIRED` if past; warns if < 1 hour remaining
+4. **Spend limit** — parses `spend_limit` array, finds `udvpn` coin. `FEE_GRANT_EXHAUSTED` if < 20,000 udvpn (minimum for one session TX)
+5. **Allowed messages** — warns (non-blocking) if `MsgStartSession` / `MsgStartSessionRequest` not in list
+
+Errors: `FEE_GRANT_NOT_FOUND`, `FEE_GRANT_EXPIRED`, `FEE_GRANT_EXHAUSTED`
+
+#### Session TX via Subscription
+
+Message type: `/sentinel.subscription.v3.MsgStartSessionRequest`
+
+| Field # | Name | Type | Description |
+|---------|------|------|-------------|
+| 1 | `from` | string | Agent's `sent1...` address |
+| 2 | `id` | uint64 | Subscription ID (from operator provisioning) |
+| 3 | `node_address` | string | Target `sentnode1...` address |
+
+The TX is broadcast via `broadcastWithFeeGrant()` which sets the `granter` field in the TX fee:
+
+```javascript
+const fee = {
+  amount: [{ denom: 'udvpn', amount: '20000' }],
+  gas: '200000',
+  granter: feeGranterAddress, // Chain deducts from granter's account
+};
+await client.signAndBroadcast(signerAddress, [msg], fee);
+```
+
+**Fallback:** If fee grant broadcast fails (expired grant, spend limit exhausted), the SDK falls back to `broadcastWithInactiveRetry()` using the agent's own balance. If agent has 0 P2P, this also fails and the error is propagated.
+
+#### Disconnect with Fee Grant
+
+On disconnect, the SDK sends `MsgCancelSessionRequest` using the same fee grant:
+
+```javascript
+// _endSessionOnChain stores feeGranter from connect-time
+const msg = buildEndSessionMsg(agentAddress, sessionId);
+if (feeGranter) {
+  result = await broadcastWithFeeGrant(client, agentAddress, [msg], feeGranter);
+} else {
+  result = await client.signAndBroadcast(agentAddress, [msg], fee);
+}
+```
+
+The `feeGranter` is stored in `ConnectionState._feeGranter` during connect and cleared on disconnect. All 9 disconnect call sites (graceful, abort, error cleanup, crash handler, etc.) pass `state._feeGranter` to `_endSessionOnChain`.
+
+#### Crash Persistence of feeGranter
+
+The `feeGranter` is persisted to `credentials.enc.json` (AES-256-GCM encrypted, per-node credential store at `~/.sentinel-sdk/credentials.enc.json`). Both WireGuard and V2Ray `saveCredentials()` calls include the field:
+
+```javascript
+saveCredentials(nodeAddress, String(sessionId), {
+  serviceType: 'wireguard', // or 'v2ray'
+  // ... protocol-specific fields ...
+  ...(state._feeGranter ? { feeGranter: state._feeGranter } : {}),
+});
+```
+
+On crash recovery, `tryFastReconnect()` restores it:
+
+```javascript
+if (saved.feeGranter && state) {
+  state._feeGranter = saved.feeGranter;
+}
+```
+
+Without this, a crashed agent with 0 P2P would restore the tunnel but be unable to end the session on-chain (disconnect TX would fail with insufficient funds).
+
+**Rule:** Every in-memory state that affects disconnect MUST be persisted to `credentials.enc.json`. See FAILURES.md W4.
+
+#### autoReconnect Dispatch
+
+`autoReconnect()` in `resilience.js` dispatches based on original connection mode:
+
+```javascript
+if (opts.subscriptionId) {
+  result = await connectViaSubscription(opts);  // fee grant preserved
+} else if (opts.planId) {
+  result = await connectViaPlan(opts);          // fee grant preserved
+} else {
+  result = await connectAuto(opts);             // self-pay mode
+}
+```
+
+Previously hardcoded to `connectAuto()`, which would fail with `INSUFFICIENT_BALANCE` for 0-P2P agents. See FAILURES.md W6.
+
+**If disconnect TX fails** (fee grant expired, spend limit exhausted, agent has 0 P2P): the session is NOT ended on-chain. It expires naturally based on the subscription's allocation. This is acceptable behavior — the session simply times out.
+
+#### Required Fee Grant Allowed Messages
+
+The operator's fee grant must include these message types:
+
+| Message Type | Purpose |
+|-------------|---------|
+| `/sentinel.subscription.v3.MsgStartSessionRequest` | Start session via subscription |
+| `/sentinel.node.v3.MsgStartSessionRequest` | Start session via node (direct) |
+| `/sentinel.session.v3.MsgCancelSessionRequest` | End/cancel session |
+| `/sentinel.session.v3.MsgUpdateSessionRequest` | Update session allocation |
+
+If `MsgCancelSessionRequest` is NOT in the allowed messages, the agent cannot end sessions cleanly. Sessions will expire naturally, but the agent cannot reclaim unused allocation.
+
 ---
 
 ## Phase 7: Index Wait
@@ -1086,7 +1238,7 @@ await conn.cleanup();
 4. **Clear system proxy:** Restore previous proxy settings (Windows registry / macOS / Linux)
 5. **Kill V2Ray:** `process.kill()` on the V2Ray child process
 6. **Uninstall WireGuard:** `wireguard.exe /uninstalltunnelservice wgsent0`
-7. **End session on chain:** `MsgCancelSessionRequest` (fire-and-forget, best-effort)
+7. **End session on chain:** `MsgCancelSessionRequest` (fire-and-forget, best-effort). If `state._feeGranter` is set (operator-provisioned mode), uses `broadcastWithFeeGrant` so agent with 0 P2P can still end the session on-chain.
 8. **Zero mnemonic:** `state._mnemonic = null`
 9. **Clear connection state:** `state.connection = null`
 10. **Clear persisted state:** Remove crash recovery files

package/ai-path/FAILURES.md

@@ -48,6 +48,9 @@
 | 37 | **V2Ray split tunnel IS the SOCKS5 proxy** -- V2Ray does not change system routing. Only traffic you explicitly send through `socks5://127.0.0.1:{port}` goes through the VPN. Everything else is direct. There is no `fullTunnel` for V2Ray — `systemProxy: true` sets Windows proxy but that's opt-in, not default. | protocol | Agent assumes all traffic is encrypted when only proxied traffic is |
 | 38 | **WireGuard split tunnel requires exact destination IPs** -- `splitIPs: ['example.com']` does NOT work. WireGuard routes by IP, not domain. CDN/anycast services (Cloudflare, Google) resolve to hundreds of IPs. Use V2Ray SOCKS5 for per-app split tunnel, use WireGuard splitIPs only for known static IPs. | tunnel | Agent sets splitIPs for a CDN domain, traffic goes direct because DNS resolved to a different IP |
 | 39 | **WireGuard disconnect MUST restore DNS to DHCP** -- WireGuard config sets system DNS (10.8.0.1 or custom). This persists in the OS adapter AFTER the WG interface is removed. Every disconnect path (normal, error, emergency) must call `disableDnsLeakPrevention()` or `netsh interface ipv4 set dnsservers Wi-Fi dhcp`. Discovered 2026-03-27: Cloudflare DNS persisted after split tunnel test, broke all V2Ray and node tester connections. | tunnel | System DNS silently changed, all subsequent networking affected |
+| 40 | **Every in-memory state that affects disconnect MUST be persisted** -- `_feeGranter` was in-memory only; crash recovery restored the tunnel but disconnect failed (0 P2P, no fee grant). Persist to `credentials.enc.json`, restore in `tryFastReconnect()`. | wallet | Agent crash → tunnel restored but cannot end session on-chain |
+| 41 | **Reconnect must use same connection mode as original connect** -- `autoReconnect()` was hardcoded to `connectAuto()`, ignoring `opts.subscriptionId`/`opts.planId`. Fee-granted agents reconnected with direct payment and failed with INSUFFICIENT_BALANCE. | wallet | Agent drops → reconnect fails → permanent disconnect |
+| 42 | **Fee grant pre-check must validate spend limit, not just existence** -- grant can exist and not be expired but have < 20,000 udvpn remaining (insufficient for one TX). Check `spend_limit` array before connecting. | wallet | Agent passes pre-check but fails at broadcast time with opaque chain error |
 
 ---
 
@@ -124,6 +127,10 @@
 | W1 | Fee grant auto-detection silently applied | Direct-connect app uses random stranger's fee grant without consent | SDK auto-detects fee grants and picks `grants[0]` on every transaction | Made fee grant opt-in via explicit `FeeGranter` option | Never auto-apply fee grants; make it explicit opt-in |
 | W2 | Insufficient funds with no dry-run option | AI builds working code but first real run fails with "insufficient funds" | Blockchain requires funded wallet; AI cannot purchase tokens | Added dry-run mode that validates everything except payment | Provide `dryRun: true` option to validate without spending tokens |
 | W3 | Fast reconnect never sets `state._mnemonic` | Sessions never end on-chain after fast reconnect; session leak | `connectDirect()` called `tryFastReconnect()` which skips `connectInternal()` where `_mnemonic` was set | Set `state._mnemonic = opts.mnemonic` BEFORE calling `tryFastReconnect()` | Set authentication state before any early-return code path |
+| W4 | Fee granter lost on crash recovery | Agent crashes mid-session, restarts, `tryFastReconnect()` restores tunnel but `_feeGranter` is null — disconnect fails (0 P2P, no fee grant) | `_feeGranter` was in-memory only, not persisted to `credentials.enc.json` | Persist `feeGranter` in `saveCredentials()`, restore in `tryFastReconnect()` | Every in-memory state that affects disconnect MUST be persisted |
+| W5 | Fee grant exhausted mid-session | Agent connects fine but session TX or disconnect TX fails with "fee-grant not found or exhausted" | Operator set low `spend_limit` on fee grant; pre-check didn't verify remaining budget | Added `spend_limit` check in fee grant pre-check — warns if <20,000 udvpn remaining | Always validate spend budget before connecting, not just existence + expiration |
+| W6 | autoReconnect ignores subscription/plan mode | Agent connected via `connectViaSubscription`, drops, `autoReconnect` calls `connectAuto()` which tries direct payment — fails with INSUFFICIENT_BALANCE (0 P2P) | `autoReconnect()` hardcoded to `connectAuto()`, ignoring `opts.subscriptionId`/`opts.planId` | Dispatch based on `opts.subscriptionId` → `connectViaSubscription`, `opts.planId` → `connectViaPlan` | Reconnect must use same connection mode as original connect |
+| W7 | Fee grant pre-check used LCD instead of RPC | Fee grant validation took ~880ms via LCD REST. SDK standard is RPC (protobuf) first — balance check already used `rpcQueryBalance` but fee grant check was LCD-only | Missing `rpcQueryFeeGrant` function; no protobuf decoder for fee grant response | Built `rpcQueryFeeGrant()` in `chain/rpc.js` with full protobuf decoding (AllowedMsgAllowance → BasicAllowance → spend_limit + expiration). LCD fallback via `tryWithFallback` | All chain queries must use RPC first, LCD fallback — never LCD-only for critical path operations |
 
 ### TIMING
 

package/ai-path/GUIDE.md

@@ -306,6 +306,8 @@ await disconnect();
 // On-chain session end is fire-and-forget -- it may take a few seconds.
 ```
 
+**Fee-granted disconnect:** When the connection was established with `feeGranter`, the SDK remembers the granter address and uses it for the `MsgCancelSessionRequest` TX on disconnect. If the fee grant has expired or been exhausted by disconnect time, the session ends naturally when the subscription allocation expires. No tokens are lost.
+
 ### Session Recovery
 
 If a connection partially succeeds (payment TX broadcast but tunnel failed), the session exists on-chain and can be recovered without paying again. Use the SDK's `recoverSession`:
@@ -865,6 +867,102 @@ await disconnect();
 
 **Important:** Node.js native `fetch()` silently ignores SOCKS5 proxy configuration. Use `axios` with an explicit agent, not `fetch()`.
 
+### Pattern 6: Operator-Provisioned Mode (Zero P2P / Fee-Granted)
+
+When an operator has provisioned access for the agent (e.g., via x402 payment protocol), the agent connects with **zero P2P tokens**. The operator's fee grant covers all gas costs.
+
+This mode requires three things from the operator:
+1. **Subscription share** -- operator added agent's `sent1...` address to their plan subscription
+2. **Fee grant** -- operator created a fee allowance so agent pays 0 gas on Sentinel
+3. **Node address** -- a node linked to the operator's plan
+
+```js
+import { connect, disconnect } from 'sentinel-ai-connect';
+
+// Agent has 0 P2P — operator covers gas via fee grant
+const vpn = await connect({
+  mnemonic: process.env.MNEMONIC,
+
+  // Operator-provisioned fields (from provisioning response)
+  subscriptionId: 12345,                                        // Operator's subscription
+  feeGranter: 'sent1operatoraddress...', // Operator pays gas
+  nodeAddress: 'sentnode1abc...', // Plan node
+
+  onProgress: (step, detail) => console.log(`[${step}] ${detail}`),
+});
+
+console.log(`Connected: ${vpn.protocol} | IP: ${vpn.ip}`);
+await disconnect();
+```
+
+**How it works:**
+- Balance check is skipped when `feeGranter` is set (agent may have 0 P2P)
+- Fee grant is validated before connecting via RPC (protobuf, ~250ms) with LCD fallback
+- Session TX is broadcast via `broadcastWithFeeGrant` — chain deducts gas from granter
+- Disconnect also uses fee grant for the `MsgCancelSessionRequest` TX
+- If fee grant fails at any step, SDK falls back to agent's own balance (if available)
+
+#### Fee Grant Pre-Check (Step 3.5)
+
+Before attempting the session TX, the SDK validates the fee grant on-chain. This runs between the balance check (Step 3) and node selection (Step 4):
+
+1. **Query grant** — RPC first (`rpcQueryFeeGrant`, protobuf ABCI query, ~250ms), LCD fallback (`queryFeeGrant` via `tryWithFallback`, ~880ms). Matches the SDK standard: all chain queries use RPC with LCD as a safety net.
+2. **Existence check** — `FEE_GRANT_NOT_FOUND` if no grant exists from granter to grantee.
+3. **Expiration check** — `FEE_GRANT_EXPIRED` if the grant's expiration is in the past. Warns if < 1 hour remaining.
+4. **Spend limit check** — `FEE_GRANT_EXHAUSTED` if `spend_limit` has < 20,000 udvpn remaining (minimum for one session TX).
+5. **Allowed messages check** — Warns (non-blocking) if `MsgStartSession` / `MsgStartSessionRequest` is not in the grant's `allowed_messages` list.
+
+The grant structure on-chain is `AllowedMsgAllowance` wrapping a `BasicAllowance`. The SDK uses robust `@type`-based detection to handle both wrapped and unwrapped grant formats.
+
+**Fee grant pre-check errors:**
+
+| Error Code | Meaning | `nextAction` | Action |
+|---|---|---|---|
+| `FEE_GRANT_NOT_FOUND` | No grant from granter to grantee on-chain | `request_fee_grant` | Request provisioning from operator |
+| `FEE_GRANT_EXPIRED` | Grant existed but expiration is past | `request_fee_grant_renewal` | Request grant renewal from operator |
+| `FEE_GRANT_EXHAUSTED` | Grant spend limit < 20,000 udvpn | `request_fee_grant_renewal` | Request operator to top up grant |
+
+All errors include `err.code`, `err.nextAction`, and `err.details` (with `granter`, `grantee`, and context-specific fields) for programmatic handling by agents.
+
+#### Crash Recovery
+
+The `feeGranter` is persisted to `credentials.enc.json` (AES-256-GCM encrypted) alongside session credentials. If the agent process crashes and restarts:
+
+1. `tryFastReconnect()` loads credentials from disk
+2. Restores `state._feeGranter` from `saved.feeGranter`
+3. Tunnel is restored (WireGuard adapter or V2Ray process)
+4. Disconnect correctly uses fee grant — no tokens needed
+
+Without this persistence, a crashed agent with 0 P2P would be unable to end its session on-chain after recovery.
+
+#### Auto-Reconnect
+
+`autoReconnect()` dispatches based on the original connection mode:
+
+- `opts.subscriptionId` → `connectViaSubscription(opts)` — fee grant preserved
+- `opts.planId` → `connectViaPlan(opts)` — fee grant preserved
+- Neither → `connectAuto(opts)` — self-pay mode
+
+This ensures fee-granted agents don't fall back to direct payment (which would fail with 0 P2P).
+
+#### Fee-Granted Disconnect
+
+When connected with `feeGranter`, the SDK stores the granter address in `state._feeGranter`. On `disconnect()`, `_endSessionOnChain` uses `broadcastWithFeeGrant()` for the `MsgCancelSessionRequest` TX. All 9 disconnect call sites (graceful, abort, error cleanup, crash handler, etc.) pass through `state._feeGranter`.
+
+If the fee grant has expired or been exhausted by disconnect time, the session ends naturally when the subscription allocation expires. No tokens are lost.
+
+**Alternative: Plan mode** -- if the agent doesn't have a specific subscription ID but knows the plan:
+
+```js
+const vpn = await connect({
+  mnemonic: process.env.MNEMONIC,
+  planId: 42,                                                  // Subscribe + connect
+  feeGranter: 'sent1operatoraddress...',  // Operator pays gas
+});
+```
+
+Plan mode subscribes to the plan AND starts a session in one flow. Use `subscriptionId` when the operator already provisioned a subscription; use `planId` when the agent subscribes itself.
+
 ---
 
 ## 9. Autonomous Agent Pattern

package/ai-path/README.md

@@ -191,6 +191,47 @@ const vpn = await connect({
 | `signal` | `AbortSignal` | `null` | AbortController signal for cancellation |
 | `v2rayExePath` | `string` | `auto` | Path to V2Ray binary. Auto-detected from `bin/` |
 
+### Operator-Provisioned Mode (Zero P2P / Fee-Granted)
+
+When an operator (like x402) provisions VPN access for your agent, you don't need P2P tokens. The operator shares their subscription and grants a fee allowance — your agent pays zero gas. Pass `subscriptionId` and `feeGranter` to connect:
+
+```js
+const vpn = await connect({
+  mnemonic: process.env.MNEMONIC,
+  subscriptionId: '12345',                            // Operator's subscription ID
+  feeGranter: 'sent1operatoraddress...',              // Operator's address
+  nodeAddress: 'sentnode1abc...',                     // Plan node
+  fullTunnel: false,  // Recommended for agents
+});
+```
+
+This mode:
+- **Skips balance check** — agent wallet can have 0 P2P
+- **Validates fee grant via RPC** — checks existence, expiration, spend limit, and allowed messages before connecting (~250ms)
+- **Uses fee grant for gas** — operator pays transaction fees (connect AND disconnect)
+- **Connects via existing subscription** — no on-chain subscription creation needed
+- **Crash-safe** — `feeGranter` is persisted to encrypted credentials; crash recovery restores it so disconnect still works
+- **Auto-reconnect aware** — reconnects using same connection mode (subscription/plan), preserving fee grant
+
+| Option | Type | Description |
+|---|---|---|
+| `subscriptionId` | `string\|number` | Operator-provisioned subscription ID |
+| `feeGranter` | `string` | Operator's `sent1...` address (pays gas) |
+| `planId` | `string\|number` | Alternative: subscribe to a plan (creates new subscription) |
+
+**Fee grant pre-check errors** (thrown before connection attempt):
+
+| Error Code | Meaning |
+|---|---|
+| `FEE_GRANT_NOT_FOUND` | No grant from operator to agent on-chain |
+| `FEE_GRANT_EXPIRED` | Grant exists but has expired |
+| `FEE_GRANT_EXHAUSTED` | Grant spend limit too low (< 20,000 udvpn) |
+
+**When to use which:**
+- `subscriptionId` — operator already added you to their subscription (x402 flow)
+- `planId` — operator's plan is open; you subscribe yourself (operator grants gas via feeGranter)
+- Neither — direct pay-per-use with your own P2P tokens (default mode)
+
 ### WARNING: `fullTunnel` and AI Agents
 
 When `fullTunnel: true` (the default), **ALL traffic** routes through the VPN tunnel — including the SDK's own chain queries (LCD, RPC), balance checks, and reconnect logic. On nodes with median speeds (~3 Mbps), this makes chain operations significantly slower and can cause timeouts.