blue-js-sdk 2.7.1 → 2.7.2

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 Every fix made during SDK creation, why it matters, and what happens if you use upstream Sentinel code directly without these fixes.
 
+## v2.7.2 — Packaging Fix: include `auth/` and `operator/` in tarball (2026-05-02)
+
+**2.7.1 shipped without `auth/` and `operator/` directories.** `index.js` imports
+from both (`./auth/adr36.js`, `./operator/auto-lease.js`, etc.), but they were
+absent from the `files` array in `package.json`. Local CI passed because every
+relative import resolved on disk — but `npm install blue-js-sdk@2.7.1` threw
+`ERR_MODULE_NOT_FOUND: ...auth/adr36.js` for every consumer. Plan Manager's
+attempt to upgrade to 2.7.1 surfaced the regression.
+
+### Fix
+- `package.json` `files`: added `auth/` and `operator/` so they ship in the tarball.
+- `.github/workflows/ci.yml`: added a "Verify published tarball imports cleanly"
+  step that runs `npm pack`, installs the resulting tarball into a temp directory,
+  and imports `blue-js-sdk` — the only test that exercises the actual published
+  surface. Local-import checks (which 2.7.1's CI relied on) cannot catch
+  packaging drift; only a tarball install can.
+
+### Rule
+**Every directory imported by `index.js` MUST appear in `package.json` "files".**
+The tarball-install CI step is now the gate that enforces this. Adding a new
+top-level directory? It must also be added to `files` in the same diff.
+
+---
+
 ## 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.

package/auth/adr36.js

@@ -0,0 +1,81 @@
+/**
+ * Sentinel SDK — ADR-36 Signature Verification
+ *
+ * Verifies Keplr/Leap/Cosmostation `signArbitrary` signatures server-side.
+ * Includes address-vs-pubkey derivation check (the part most consumers skip).
+ *
+ * Usage:
+ *   import { verifyAdr36Signature } from './auth/adr36.js';
+ *   const { ok, reason } = await verifyAdr36Signature({ addr, pubkeyB64, signatureB64, message });
+ */
+
+import { Secp256k1, sha256, ripemd160 } from '@cosmjs/crypto';
+import { toBech32 } from '@cosmjs/encoding';
+
+// ─── Canonical JSON ──────────────────────────────────────────────────────────
+
+/**
+ * Amino-compatible canonical JSON serialization (sorted keys, no whitespace).
+ * Required for ADR-36 sign-doc hashing — standard JSON.stringify produces
+ * non-deterministic key order, which breaks signature verification.
+ */
+export function sortedJsonStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(sortedJsonStringify).join(',') + ']';
+  const keys = Object.keys(value).sort();
+  return '{' + keys.map(k => JSON.stringify(k) + ':' + sortedJsonStringify(value[k])).join(',') + '}';
+}
+
+// ─── ADR-36 Verifier ─────────────────────────────────────────────────────────
+
+/**
+ * Verify an ADR-36 `signArbitrary` signature produced by Keplr, Leap, or Cosmostation.
+ *
+ * Checks BOTH:
+ *   1. That the pubkey derives to the claimed address (addr-pubkey-mismatch attack vector).
+ *   2. That the secp256k1 signature over the canonical sign-doc is valid.
+ *
+ * @param {object} opts
+ * @param {string} opts.addr        - Bech32 signer address (e.g. sent1abc...)
+ * @param {string} opts.pubkeyB64   - Base64-encoded compressed secp256k1 pubkey (33 bytes)
+ * @param {string} opts.signatureB64 - Base64-encoded 64-byte signature (r||s)
+ * @param {string} opts.message     - The original UTF-8 message that was signed
+ * @param {string} [opts.prefix]    - Bech32 prefix (default: 'sent')
+ * @returns {Promise<{ ok: boolean, reason: string|null }>}
+ */
+export async function verifyAdr36Signature({ addr, pubkeyB64, signatureB64, message, prefix = 'sent' }) {
+  const pubkey = Buffer.from(pubkeyB64, 'base64');
+
+  // Step 1: derive bech32 address from pubkey and compare to claimed addr.
+  // Skipping this check allows an attacker to substitute their own pubkey for
+  // a victim's address and produce a valid-looking signature for any message.
+  const derived = toBech32(prefix, ripemd160(sha256(pubkey)));
+  if (derived !== addr) return { ok: false, reason: 'addr-pubkey-mismatch' };
+
+  // Step 2: rebuild the canonical ADR-36 amino sign-doc and verify the signature.
+  const signDoc = {
+    chain_id: '',
+    account_number: '0',
+    sequence: '0',
+    fee: { gas: '0', amount: [] },
+    msgs: [{
+      type: 'sign/MsgSignData',
+      value: {
+        signer: addr,
+        data: Buffer.from(message, 'utf8').toString('base64'),
+      },
+    }],
+    memo: '',
+  };
+
+  const hash = sha256(Buffer.from(sortedJsonStringify(signDoc), 'utf8'));
+  const sig = Buffer.from(signatureB64, 'base64');
+
+  const ok = await Secp256k1.verifySignature(
+    { r: sig.slice(0, 32), s: sig.slice(32) },
+    hash,
+    pubkey,
+  );
+
+  return { ok, reason: ok ? null : 'sig-invalid' };
+}

package/auth/keplr-signdoc.js

@@ -0,0 +1,97 @@
+/**
+ * Sentinel SDK — Keplr Broadcast-Back Helpers
+ *
+ * Builds a SIGN_MODE_DIRECT signDoc for Keplr/Leap `signDirect`, then
+ * reassembles the signed TxRaw for RPC broadcast. This is the only pattern
+ * that works without leaking mnemonics or maintaining a long-lived signing
+ * client in the browser.
+ *
+ * Flow:
+ *   server: buildKeplrSignDoc(msgs, account, fee) → { bodyBytes, authInfoBytes, chainId, accountNumber }
+ *   browser: keplr.signDirect(chainId, addr, signDoc) → { signed, signature }
+ *   server: broadcastSignedKeplrTx(tmClient, signed, signature) → txHash
+ *
+ * Usage:
+ *   import { buildKeplrSignDoc, broadcastSignedKeplrTx } from './auth/keplr-signdoc.js';
+ */
+
+import { TxBody, TxRaw } from 'cosmjs-types/cosmos/tx/v1beta1/tx.js';
+import { makeAuthInfoBytes } from '@cosmjs/proto-signing';
+import Long from 'long';
+
+// ─── SignDoc Builder ─────────────────────────────────────────────────────────
+
+/**
+ * Build a Direct-mode signDoc for Keplr's `signDirect`.
+ *
+ * Common traps avoided here:
+ *   - `accountNumber` must be Long.toString(), not a JS Number — Keplr silently fails otherwise.
+ *   - `SIGN_MODE_DIRECT` = 1 (not a named export in older cosmjs-types).
+ *   - `pubkey.value` must be the raw 33-byte compressed pubkey bytes, NOT a protobuf wrapper.
+ *
+ * @param {object} opts
+ * @param {Array}  opts.msgs           - Array of { typeUrl, value } EncodeObjects
+ * @param {string} [opts.memo]         - TX memo (default: '')
+ * @param {string} opts.pubkeyB64      - Base64-encoded compressed secp256k1 pubkey (33 bytes)
+ * @param {number} opts.accountNumber  - Chain account number
+ * @param {number} opts.sequence       - Account sequence
+ * @param {number} opts.gasLimit       - Gas limit
+ * @param {Array}  opts.feeAmount      - Array of { denom, amount } Coin objects
+ * @param {string} opts.chainId        - Chain ID (e.g. 'sentinelhub-2')
+ * @param {object} opts.registry       - CosmJS TypeRegistry (from buildRegistry())
+ * @returns {{ bodyBytes: string, authInfoBytes: string, chainId: string, accountNumber: string }}
+ *   All byte fields are base64-encoded for JSON transport to the browser.
+ */
+export function buildKeplrSignDoc({ msgs, memo = '', pubkeyB64, accountNumber, sequence, gasLimit, feeAmount, chainId, registry }) {
+  const bodyBytes = TxBody.encode({
+    messages: msgs.map(m => registry.encodeAsAny(m)),
+    memo,
+    timeoutHeight: Long.UZERO,
+    extensionOptions: [],
+    nonCriticalExtensionOptions: [],
+  }).finish();
+
+  const pubkeyBytes = Buffer.from(pubkeyB64, 'base64');
+  const authInfoBytes = makeAuthInfoBytes(
+    [{ pubkey: { typeUrl: '/cosmos.crypto.secp256k1.PubKey', value: pubkeyBytes }, sequence }],
+    feeAmount,
+    gasLimit,
+    undefined,
+    undefined,
+    1, // SIGN_MODE_DIRECT
+  );
+
+  return {
+    bodyBytes: Buffer.from(bodyBytes).toString('base64'),
+    authInfoBytes: Buffer.from(authInfoBytes).toString('base64'),
+    chainId,
+    accountNumber: Long.fromNumber(accountNumber).toString(),
+  };
+}
+
+// ─── Broadcast Reconstructor ─────────────────────────────────────────────────
+
+/**
+ * Reconstruct TxRaw from Keplr's `signDirect` response and broadcast via RPC.
+ *
+ * @param {object} opts
+ * @param {object} opts.tmClient        - Tendermint37Client (from createRpcQueryClient)
+ * @param {string} opts.bodyBytesB64    - `signed.bodyBytes` from Keplr (base64)
+ * @param {string} opts.authInfoBytesB64 - `signed.authInfoBytes` from Keplr (base64)
+ * @param {string} opts.signatureB64    - `signature.signature` from Keplr (base64)
+ * @returns {Promise<{ transactionHash: string, code: number }>}
+ */
+export async function broadcastSignedKeplrTx({ tmClient, bodyBytesB64, authInfoBytesB64, signatureB64 }) {
+  const txRaw = TxRaw.encode({
+    bodyBytes: Buffer.from(bodyBytesB64, 'base64'),
+    authInfoBytes: Buffer.from(authInfoBytesB64, 'base64'),
+    signatures: [Buffer.from(signatureB64, 'base64')],
+  }).finish();
+
+  const result = await tmClient.broadcastTxSync({ tx: txRaw });
+  return {
+    transactionHash: Buffer.from(result.hash).toString('hex').toUpperCase(),
+    code: result.code ?? 0,
+    rawLog: result.log ?? '',
+  };
+}

package/auth/privy-cosmos-signer.js

@@ -0,0 +1,298 @@
+/**
+ * Sentinel SDK — Privy → Cosmos Signer Adapter
+ *
+ * Bridges a Privy embedded wallet (EVM/Solana-native) to a Sentinel Cosmos
+ * signer. The result satisfies cosmjs `OfflineDirectSigner`, so it can be
+ * passed straight to `SigningStargateClient.connectWithSigner` and to every
+ * Sentinel SDK helper that takes a `wallet`.
+ *
+ * Two strategies are supported, picked by the `mode` field on the input.
+ *
+ * ─── Mode A: 'mnemonic' (seed-import) ──────────────────────────────────────
+ * The consumer triggers Privy's `exportWallet()` once, captures the seed
+ * phrase the user reveals, and hands it to this adapter. The adapter derives
+ * a Cosmos secp256k1 key on Sentinel's HD path (cosmoshub-style, coinType
+ * 118) and wraps it in `DirectSecp256k1HdWallet`. Same trust model as a
+ * normal mnemonic wallet — the seed leaves Privy's secure enclave.
+ *
+ * Use this when you need full broadcast capability (sessions, payments,
+ * fee-grants) and your UX can prompt the user to export once.
+ *
+ * ─── Mode B: 'rawSign' (custody-preserving) ────────────────────────────────
+ * The seed never leaves Privy. The consumer supplies:
+ *   - `pubkey`: the compressed secp256k1 pubkey (33 bytes) Privy derived for
+ *     this user on the Cosmos `m/44'/118'/0'/0/0` path. Privy exposes raw
+ *     signing for embedded wallets; deriving the pubkey from the same path
+ *     yields the same `sent1...` address Mode A would produce.
+ *   - `signRawSecp256k1(digest32)`: an async function that asks Privy to
+ *     produce a 64-byte (r||s) signature over the supplied 32-byte digest,
+ *     using the same key the pubkey came from. The adapter computes the
+ *     digest of the cosmjs `SignDoc` itself, so Privy only sees a hash.
+ *
+ * Use this when you must keep custody inside Privy. Note that
+ * `signRawSecp256k1` MUST return a *normalized low-S* signature — cosmjs
+ * rejects high-S sigs. The adapter normalizes defensively.
+ *
+ * ─── Usage ─────────────────────────────────────────────────────────────────
+ *
+ *   // Mode A
+ *   const signer = await PrivyCosmosSigner.fromMnemonic({
+ *     mnemonic: privyExportedSeed,
+ *     prefix: 'sent',
+ *   });
+ *
+ *   // Mode B
+ *   const signer = await PrivyCosmosSigner.fromRawSign({
+ *     pubkey: privyDerivedCompressedPubkey,   // Uint8Array(33)
+ *     signRawSecp256k1: async (digest32) => {
+ *       const sig = await privy.signRawHash({ hash: digest32, curve: 'secp256k1' });
+ *       return sig; // Uint8Array(64), r||s
+ *     },
+ *     prefix: 'sent',
+ *   });
+ *
+ *   const [account] = await signer.getAccounts();
+ *   // account.address === 'sent1...'
+ *   const client = await SigningStargateClient.connectWithSigner(rpc, signer, ...);
+ */
+
+import {
+  Bip39,
+  EnglishMnemonic,
+  Slip10,
+  Slip10Curve,
+  Secp256k1,
+  sha256,
+  ripemd160,
+} from '@cosmjs/crypto';
+import { makeCosmoshubPath } from '@cosmjs/amino';
+import { DirectSecp256k1HdWallet, makeSignDoc } from '@cosmjs/proto-signing';
+import { fromBech32, toBech32 } from '@cosmjs/encoding';
+import { ValidationError, ErrorCodes } from '../errors/index.js';
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+function assertPrefix(prefix) {
+  if (typeof prefix !== 'string' || prefix.length === 0) {
+    throw new ValidationError(ErrorCodes.INVALID_OPTIONS,
+      'PrivyCosmosSigner: prefix must be a non-empty string (e.g. "sent")',
+      { prefix });
+  }
+}
+
+// secp256k1 group order n. Signatures with s > n/2 are non-canonical and
+// rejected by Cosmos chains since cosmos-sdk v0.42. Privy's raw-sign path is
+// not guaranteed to return low-S form, so we normalize defensively.
+const SECP256K1_N = BigInt('0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141');
+const SECP256K1_HALF_N = SECP256K1_N >> 1n;
+
+function bytesToBigInt(bytes) {
+  let n = 0n;
+  for (const b of bytes) n = (n << 8n) | BigInt(b);
+  return n;
+}
+
+function bigIntTo32Bytes(n) {
+  const out = new Uint8Array(32);
+  for (let i = 31; i >= 0; i--) {
+    out[i] = Number(n & 0xffn);
+    n >>= 8n;
+  }
+  return out;
+}
+
+function normalizeLowS(rawSig) {
+  const r = rawSig.slice(0, 32);
+  const sBytes = rawSig.slice(32, 64);
+  const s = bytesToBigInt(sBytes);
+  if (s <= SECP256K1_HALF_N) return rawSig;
+  const flipped = SECP256K1_N - s;
+  const out = new Uint8Array(64);
+  out.set(r, 0);
+  out.set(bigIntTo32Bytes(flipped), 32);
+  return out;
+}
+
+function pubkeyToBech32Address(compressedPubkey, prefix) {
+  if (!(compressedPubkey instanceof Uint8Array) || compressedPubkey.length !== 33) {
+    throw new ValidationError(ErrorCodes.INVALID_OPTIONS,
+      'PrivyCosmosSigner: pubkey must be a 33-byte compressed secp256k1 Uint8Array',
+      { length: compressedPubkey?.length });
+  }
+  const data = ripemd160(sha256(compressedPubkey));
+  return toBech32(prefix, data);
+}
+
+// ─── Mode A: seed-import via Privy exportWallet ─────────────────────────────
+
+/**
+ * Build a signer from a mnemonic the user just exported from Privy.
+ *
+ * Internally this is `DirectSecp256k1HdWallet` with Sentinel's prefix — i.e.
+ * the same key + address the consumer would get from `createWallet()` if
+ * they typed the mnemonic in directly. The wrapper exists so a consumer can
+ * write the same code path regardless of which Privy mode they're in.
+ *
+ * @param {object} opts
+ * @param {string} opts.mnemonic
+ * @param {string} [opts.prefix='sent']
+ * @returns {Promise<DirectSecp256k1HdWallet>} A cosmjs OfflineDirectSigner
+ */
+export async function privyCosmosSignerFromMnemonic({ mnemonic, prefix = 'sent' } = {}) {
+  assertPrefix(prefix);
+  if (typeof mnemonic !== 'string' || mnemonic.trim().split(/\s+/).length < 12) {
+    throw new ValidationError(ErrorCodes.INVALID_MNEMONIC,
+      'privyCosmosSignerFromMnemonic: mnemonic must be a 12+ word BIP39 string',
+      { wordCount: typeof mnemonic === 'string' ? mnemonic.trim().split(/\s+/).length : 0 });
+  }
+  return DirectSecp256k1HdWallet.fromMnemonic(mnemonic, { prefix });
+}
+
+/**
+ * Convenience: derive the compressed secp256k1 pubkey + address from a
+ * mnemonic on Sentinel's HD path. Useful for pre-computing what the
+ * `sent1...` address WILL be in Mode B before plumbing the raw-sign callback.
+ *
+ * @param {string} mnemonic
+ * @param {string} [prefix='sent']
+ * @returns {Promise<{ pubkey: Uint8Array, address: string }>}
+ */
+export async function deriveCosmosPubkeyFromMnemonic(mnemonic, prefix = 'sent') {
+  assertPrefix(prefix);
+  const seed = await Bip39.mnemonicToSeed(new EnglishMnemonic(mnemonic));
+  const { privkey } = Slip10.derivePath(Slip10Curve.Secp256k1, seed, makeCosmoshubPath(0));
+  const { pubkey } = await Secp256k1.makeKeypair(privkey);
+  const compressed = Secp256k1.compressPubkey(pubkey);
+  return { pubkey: compressed, address: pubkeyToBech32Address(compressed, prefix) };
+}
+
+// ─── Mode B: raw-sign (Privy keeps custody) ─────────────────────────────────
+
+/**
+ * `OfflineDirectSigner` that delegates the actual ECDSA op to Privy. The
+ * private key never leaves Privy's enclave; we hash the SignDoc locally and
+ * ship the 32-byte digest to the supplied callback.
+ *
+ * Conforms to cosmjs `OfflineDirectSigner`:
+ *   - `getAccounts()` → `[{ address, algo: 'secp256k1', pubkey }]`
+ *   - `signDirect(signerAddress, signDoc)` → `{ signed, signature }`
+ */
+export class PrivyRawSignDirectSigner {
+  /**
+   * @param {object} opts
+   * @param {Uint8Array} opts.pubkey - 33-byte compressed secp256k1 pubkey
+   * @param {(digest: Uint8Array) => Promise<Uint8Array>} opts.signRawSecp256k1
+   *        Returns a 64-byte (r||s) signature over `digest`. MUST be low-S
+   *        normalized; the adapter re-normalizes defensively.
+   * @param {string} [opts.prefix='sent']
+   */
+  constructor({ pubkey, signRawSecp256k1, prefix = 'sent' }) {
+    assertPrefix(prefix);
+    if (typeof signRawSecp256k1 !== 'function') {
+      throw new ValidationError(ErrorCodes.INVALID_OPTIONS,
+        'PrivyRawSignDirectSigner: signRawSecp256k1 must be a function',
+        {});
+    }
+    this._pubkey = pubkey;
+    this._sign = signRawSecp256k1;
+    this._prefix = prefix;
+    this._address = pubkeyToBech32Address(pubkey, prefix);
+  }
+
+  async getAccounts() {
+    return [{
+      address: this._address,
+      algo: 'secp256k1',
+      pubkey: this._pubkey,
+    }];
+  }
+
+  /**
+   * @param {string} signerAddress
+   * @param {import('@cosmjs/proto-signing').SignDoc} signDoc
+   */
+  async signDirect(signerAddress, signDoc) {
+    if (signerAddress !== this._address) {
+      throw new ValidationError(ErrorCodes.INVALID_OPTIONS,
+        `PrivyRawSignDirectSigner: signerAddress mismatch (got ${signerAddress}, signer holds ${this._address})`,
+        { expected: this._address, got: signerAddress });
+    }
+    // Re-encode the SignDoc the same way cosmjs does, then SHA-256 it.
+    // Importing the raw protobuf encoder via makeSignDoc → makeSignBytes
+    // would also work, but doing it inline keeps the dep surface tight.
+    const { makeSignBytes } = await import('@cosmjs/proto-signing');
+    const signBytes = makeSignBytes(signDoc);
+    const digest = sha256(signBytes);
+
+    const rawSig = await this._sign(digest);
+    if (!(rawSig instanceof Uint8Array) || rawSig.length !== 64) {
+      throw new ValidationError(ErrorCodes.INVALID_OPTIONS,
+        'PrivyRawSignDirectSigner: signRawSecp256k1 must return a 64-byte (r||s) Uint8Array',
+        { length: rawSig?.length });
+    }
+
+    // Normalize to low-S so chain validators accept it. cosmjs's
+    // Secp256k1Signature.fromFixedLength + Secp256k1.trimRecoveryByte path
+    // is internal; instead we parse r/s as bigints and flip s if it sits in
+    // the upper half of the curve order.
+    const normalized = normalizeLowS(rawSig);
+
+    return {
+      signed: signDoc,
+      signature: {
+        pub_key: {
+          type: 'tendermint/PubKeySecp256k1',
+          value: Buffer.from(this._pubkey).toString('base64'),
+        },
+        signature: Buffer.from(normalized).toString('base64'),
+      },
+    };
+  }
+}
+
+/**
+ * Build a Mode B signer.
+ *
+ * @param {object} opts
+ * @param {Uint8Array} opts.pubkey
+ * @param {(digest: Uint8Array) => Promise<Uint8Array>} opts.signRawSecp256k1
+ * @param {string} [opts.prefix='sent']
+ * @returns {Promise<PrivyRawSignDirectSigner>}
+ */
+export async function privyCosmosSignerFromRawSign(opts) {
+  return new PrivyRawSignDirectSigner(opts);
+}
+
+// ─── Unified factory ────────────────────────────────────────────────────────
+
+/**
+ * Single entry point picking the right strategy by `mode`.
+ *
+ * @param {{ mode: 'mnemonic', mnemonic: string, prefix?: string }
+ *        | { mode: 'rawSign', pubkey: Uint8Array,
+ *            signRawSecp256k1: (digest: Uint8Array) => Promise<Uint8Array>,
+ *            prefix?: string }} opts
+ * @returns {Promise<DirectSecp256k1HdWallet | PrivyRawSignDirectSigner>}
+ */
+export async function createPrivyCosmosSigner(opts = {}) {
+  if (opts.mode === 'mnemonic') {
+    return privyCosmosSignerFromMnemonic(opts);
+  }
+  if (opts.mode === 'rawSign') {
+    return privyCosmosSignerFromRawSign(opts);
+  }
+  throw new ValidationError(ErrorCodes.INVALID_OPTIONS,
+    `createPrivyCosmosSigner: unknown mode "${opts.mode}" — expected "mnemonic" or "rawSign"`,
+    { mode: opts.mode });
+}
+
+// ─── Static facade ──────────────────────────────────────────────────────────
+
+export class PrivyCosmosSigner {
+  static fromMnemonic(opts) { return privyCosmosSignerFromMnemonic(opts); }
+  static fromRawSign(opts) { return privyCosmosSignerFromRawSign(opts); }
+  static create(opts) { return createPrivyCosmosSigner(opts); }
+  static derivePubkeyFromMnemonic(mnemonic, prefix) {
+    return deriveCosmosPubkeyFromMnemonic(mnemonic, prefix);
+  }
+}

package/operator/auto-lease.js

@@ -0,0 +1,157 @@
+/**
+ * Sentinel SDK — Operator / Auto Lease
+ *
+ * Lease multiple nodes onto a plan in optimistic batches.
+ * The chain rejects more than ~20 MsgStartLeaseRequest messages per TX —
+ * perTxLimit=20 is the empirically validated safe cap.
+ *
+ * Usage:
+ *   import { batchLeaseNodes } from 'sentinel-dvpn-sdk/operator';
+ *   const results = await batchLeaseNodes({
+ *     client, providerAddress: 'sentprov1...', planId: 42,
+ *     nodes: [{ nodeAddress: 'sentnode1...', hours: 720, maxPrice: { denom: 'udvpn', base_value: '...', quote_value: '...' } }],
+ *     onProgress: (info) => console.log(info),
+ *   });
+ */
+
+import { encodeMsgStartLease } from '../plan-operations.js';
+import { broadcast } from '../chain/broadcast.js';
+import { ValidationError, ErrorCodes } from '../errors.js';
+
+const PER_TX_LIMIT = 20; // empirically validated chain cap for MsgStartLeaseRequest batch
+const SLEEP_MS = 7000;   // 7s between TX batches (chain rate-limit safe)
+const GAS_PER_MSG = 120_000;
+
+function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms));
+}
+
+/**
+ * Lease a single node onto a plan.
+ *
+ * @param {object} opts
+ * @param {import('@cosmjs/stargate').SigningStargateClient} opts.client - Signed with provider's wallet
+ * @param {string} opts.providerAddress - sentprov1... prefix (plan owner)
+ * @param {{ nodeAddress: string, hours: number, maxPrice: { denom: string, base_value: string, quote_value: string } }} opts.node
+ * @param {number} [opts.gasPerMsg] - Gas per MsgStartLeaseRequest (default: 120000)
+ * @returns {Promise<{ ok: boolean, txHash?: string, error?: string }>}
+ */
+export async function autoLeaseNode(opts = {}) {
+  const { client, providerAddress, node, gasPerMsg = GAS_PER_MSG } = opts;
+  if (!client) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'client is required');
+  if (!providerAddress) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'providerAddress is required');
+  if (!node?.nodeAddress) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'node.nodeAddress is required');
+  if (!node?.hours || node.hours < 1) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'node.hours must be >= 1');
+  if (!node?.maxPrice) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'node.maxPrice is required');
+
+  const msg = {
+    typeUrl: '/sentinel.lease.v1.MsgStartLeaseRequest',
+    value: encodeMsgStartLease({
+      from: providerAddress,
+      nodeAddress: node.nodeAddress,
+      hours: node.hours,
+      maxPrice: node.maxPrice,
+    }),
+  };
+  const fee = {
+    amount: [{ denom: 'udvpn', amount: String(gasPerMsg) }],
+    gas: String(gasPerMsg),
+  };
+
+  try {
+    const result = await broadcast(client, providerAddress, [msg], fee);
+    if (result.code === 0) {
+      return { ok: true, txHash: result.transactionHash };
+    }
+    return { ok: false, error: result.rawLog || `code=${result.code}` };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/**
+ * Lease multiple nodes onto a plan in batches.
+ *
+ * Splits nodes into chunks of `perTxLimit` (default: 20, the empirical
+ * chain cap for MsgStartLeaseRequest per TX). Sleeps 7s between each
+ * chunk broadcast to avoid sequence errors.
+ *
+ * @param {object} opts
+ * @param {import('@cosmjs/stargate').SigningStargateClient} opts.client - Signed with provider's wallet
+ * @param {string} opts.providerAddress - sentprov1... prefix (plan owner)
+ * @param {Array<{ nodeAddress: string, hours: number, maxPrice: { denom: string, base_value: string, quote_value: string } }>} opts.nodes
+ * @param {number} [opts.perTxLimit=20] - Max MsgStartLeaseRequest per TX
+ * @param {number} [opts.gasPerMsg=120000] - Gas per message
+ * @param {(info: { stage: string, batch: number, totalBatches: number, done: number, total: number, txHash?: string, error?: string }) => void} [opts.onProgress]
+ * @returns {Promise<Array<{ nodeAddress: string, ok: boolean, txHash?: string, error?: string }>>}
+ */
+export async function batchLeaseNodes(opts = {}) {
+  const {
+    client,
+    providerAddress,
+    nodes,
+    perTxLimit = PER_TX_LIMIT,
+    gasPerMsg = GAS_PER_MSG,
+    onProgress,
+  } = opts;
+
+  if (!client) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'client is required');
+  if (!providerAddress) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'providerAddress is required');
+  if (!Array.isArray(nodes) || nodes.length === 0) {
+    throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'nodes must be a non-empty array');
+  }
+
+  const total = nodes.length;
+  const totalBatches = Math.ceil(total / perTxLimit);
+  const results = [];
+  const report = (info) => { if (onProgress) onProgress({ done: results.length, total, totalBatches, ...info }); };
+
+  for (let batchIdx = 0; batchIdx < totalBatches; batchIdx++) {
+    const chunk = nodes.slice(batchIdx * perTxLimit, (batchIdx + 1) * perTxLimit);
+    const batch = batchIdx + 1;
+
+    report({ stage: 'batch_start', batch });
+
+    const msgs = chunk.map(n => ({
+      typeUrl: '/sentinel.lease.v1.MsgStartLeaseRequest',
+      value: encodeMsgStartLease({
+        from: providerAddress,
+        nodeAddress: n.nodeAddress,
+        hours: n.hours,
+        maxPrice: n.maxPrice,
+      }),
+    }));
+
+    const fee = {
+      amount: [{ denom: 'udvpn', amount: String(gasPerMsg * chunk.length) }],
+      gas: String(gasPerMsg * chunk.length),
+    };
+
+    try {
+      const result = await broadcast(client, providerAddress, msgs, fee);
+      if (result.code === 0) {
+        for (const n of chunk) {
+          results.push({ nodeAddress: n.nodeAddress, ok: true, txHash: result.transactionHash });
+        }
+        report({ stage: 'batch_ok', batch, txHash: result.transactionHash });
+      } else {
+        // Batch failed — record all in chunk as failed
+        const error = result.rawLog || `code=${result.code}`;
+        for (const n of chunk) {
+          results.push({ nodeAddress: n.nodeAddress, ok: false, error });
+        }
+        report({ stage: 'batch_failed', batch, error });
+      }
+    } catch (e) {
+      for (const n of chunk) {
+        results.push({ nodeAddress: n.nodeAddress, ok: false, error: e.message });
+      }
+      report({ stage: 'batch_failed', batch, error: e.message });
+    }
+
+    // Sleep 7s between batches (not after last batch)
+    if (batchIdx < totalBatches - 1) await sleep(SLEEP_MS);
+  }
+
+  return results;
+}

package/operator/batch-revoke.js

@@ -0,0 +1,112 @@
+/**
+ * Sentinel SDK — Operator / Batch Fee Grant Revoke
+ *
+ * Revoke fee grants from multiple grantees in optimistic batches.
+ * Tries all grantees in a single TX first; falls back to per-grantee
+ * TXs if the batch fails (e.g. one grantee has no active grant).
+ *
+ * Usage:
+ *   import { batchRevokeFeeGrants } from 'sentinel-dvpn-sdk/operator';
+ *   const results = await batchRevokeFeeGrants({
+ *     client, granter: 'sent1...', grantees: ['sent1...', 'sent1...'],
+ *     onProgress: (info) => console.log(info),
+ *   });
+ */
+
+import { buildRevokeFeeGrantMsg } from '../chain/fee-grants.js';
+import { broadcast } from '../chain/broadcast.js';
+import { ValidationError, ErrorCodes } from '../errors.js';
+
+const SLEEP_MS = 7000;
+
+function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms));
+}
+
+/**
+ * Batch-revoke fee grants from a list of grantees.
+ *
+ * Attempts to revoke all grantees in a single TX (optimistic batch).
+ * If the batch TX fails, falls back to one TX per grantee with 7s
+ * sleep between each (chain rate-limit safe).
+ *
+ * @param {object} opts
+ * @param {import('@cosmjs/stargate').SigningStargateClient} opts.client - Signed with granter's wallet
+ * @param {string} opts.granter - Address revoking grants (sent1...)
+ * @param {string[]} opts.grantees - Addresses to revoke
+ * @param {number} [opts.gasPerMsg=80000] - Gas estimate per revoke message
+ * @param {(info: {stage: string, grantee?: string, txHash?: string, error?: string, done: number, total: number}) => void} [opts.onProgress]
+ * @returns {Promise<Array<{ grantee: string, ok: boolean, txHash?: string, error?: string }>>}
+ */
+export async function batchRevokeFeeGrants(opts = {}) {
+  const { client, granter, grantees, gasPerMsg = 80_000, onProgress } = opts;
+
+  if (!client) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'client is required');
+  if (!granter) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'granter is required');
+  if (!Array.isArray(grantees) || grantees.length === 0) {
+    throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'grantees must be a non-empty array');
+  }
+
+  const unique = [...new Set(grantees.filter(g => g && g !== granter))];
+  if (unique.length === 0) return [];
+
+  const total = unique.length;
+  const results = [];
+  const report = (info) => { if (onProgress) onProgress({ done: results.length, total, ...info }); };
+
+  // ── Optimistic batch attempt ────────────────────────────────────────────────
+  const batchMsgs = unique.map(g => buildRevokeFeeGrantMsg(granter, g));
+  report({ stage: 'batch_attempt' });
+
+  try {
+    const fee = {
+      amount: [{ denom: 'udvpn', amount: String(gasPerMsg * unique.length) }],
+      gas: String(gasPerMsg * unique.length),
+    };
+    const result = await broadcast(client, granter, batchMsgs, fee);
+    if (result.code === 0) {
+      // All succeeded in one TX
+      for (const grantee of unique) {
+        results.push({ grantee, ok: true, txHash: result.transactionHash });
+        report({ stage: 'revoked', grantee, txHash: result.transactionHash });
+      }
+      return results;
+    }
+    // Non-zero code — fall through to per-grantee
+    report({ stage: 'batch_failed', error: result.rawLog || `code=${result.code}` });
+  } catch (batchErr) {
+    report({ stage: 'batch_failed', error: batchErr.message });
+  }
+
+  // ── Per-grantee fallback ────────────────────────────────────────────────────
+  report({ stage: 'fallback_start' });
+
+  for (let i = 0; i < unique.length; i++) {
+    const grantee = unique[i];
+    const msg = buildRevokeFeeGrantMsg(granter, grantee);
+    const fee = {
+      amount: [{ denom: 'udvpn', amount: String(gasPerMsg) }],
+      gas: String(gasPerMsg),
+    };
+
+    try {
+      const result = await broadcast(client, granter, [msg], fee);
+      if (result.code === 0) {
+        results.push({ grantee, ok: true, txHash: result.transactionHash });
+        report({ stage: 'revoked', grantee, txHash: result.transactionHash });
+      } else {
+        const error = result.rawLog || `code=${result.code}`;
+        results.push({ grantee, ok: false, error });
+        report({ stage: 'revoke_failed', grantee, error });
+      }
+    } catch (e) {
+      results.push({ grantee, ok: false, error: e.message });
+      report({ stage: 'revoke_failed', grantee, error: e.message });
+    }
+
+    // 7s gap between TXs (not needed after last one)
+    if (i < unique.length - 1) await sleep(SLEEP_MS);
+  }
+
+  return results;
+}

package/operator/feegrant-history.js

@@ -0,0 +1,133 @@
+/**
+ * Sentinel SDK — Operator / Fee Grant History
+ *
+ * Query the historical record of MsgGrantAllowance and MsgRevokeAllowance
+ * transactions for an address. Uses tmClient.txSearchAll() (RPC) for
+ * reliable historical lookup without LCD indexer dependencies.
+ *
+ * Usage:
+ *   import { queryFeeGrantHistory } from 'sentinel-dvpn-sdk/operator';
+ *   const history = await queryFeeGrantHistory(tmClient, 'sent1...');
+ */
+
+import { ValidationError, ErrorCodes } from '../errors.js';
+
+// ─── Attribute Decoder ───────────────────────────────────────────────────────
+// Cosmos SDK v0.47+ sometimes JSON-quotes string attribute values: `"sent1..."`.
+// We strip those quotes so callers always get plain strings.
+
+/**
+ * Read an event attribute value by key. Handles JSON-quoted values from v0.47+.
+ * @param {ReadonlyArray<{key:string, value:string}>} attrs
+ * @param {string} key
+ * @returns {string|null}
+ */
+export function attr(attrs, key) {
+  const found = attrs.find(a => a.key === key);
+  if (!found) return null;
+  const v = found.value;
+  // Strip surrounding JSON quotes if present
+  if (v.startsWith('"') && v.endsWith('"')) {
+    try { return JSON.parse(v); } catch { /* fall through */ }
+  }
+  return v;
+}
+
+// ─── Event Decoder ───────────────────────────────────────────────────────────
+
+/**
+ * Decode a fee-grant event from a TX event list.
+ * Returns null if the event doesn't match a grant or revoke action.
+ *
+ * @param {{ type: string, attributes: ReadonlyArray<{key:string, value:string}> }} ev
+ * @param {string} hash - TX hash (hex)
+ * @param {number} height - Block height
+ * @returns {{ action: 'grant'|'revoke', granter: string, grantee: string, txHash: string, height: number }|null}
+ */
+export function decodeFeeGrantEvent(ev, hash, height) {
+  // cosmos.feegrant events emit under 'cosmos.feegrant.v1beta1.EventGrantAllowance'
+  // or 'cosmos.feegrant.v1beta1.EventRevokeAllowance', or under 'message' with
+  // action='/cosmos.feegrant.v1beta1.MsgGrantAllowance'
+  const type = ev.type;
+  const attrs = ev.attributes;
+
+  let action = null;
+  if (type === 'cosmos.feegrant.v1beta1.EventGrantAllowance' ||
+      type === 'grant_allowance') {
+    action = 'grant';
+  } else if (type === 'cosmos.feegrant.v1beta1.EventRevokeAllowance' ||
+             type === 'revoke_allowance') {
+    action = 'revoke';
+  } else if (type === 'message') {
+    const msgAction = attr(attrs, 'action');
+    if (msgAction === '/cosmos.feegrant.v1beta1.MsgGrantAllowance') action = 'grant';
+    else if (msgAction === '/cosmos.feegrant.v1beta1.MsgRevokeAllowance') action = 'revoke';
+  }
+
+  if (!action) return null;
+
+  const granter = attr(attrs, 'granter');
+  const grantee = attr(attrs, 'grantee');
+  if (!granter || !grantee) return null;
+
+  return { action, granter, grantee, txHash: hash, height };
+}
+
+// ─── Main Query ──────────────────────────────────────────────────────────────
+
+/**
+ * Query fee grant history (grants and revokes) for an address.
+ *
+ * Searches both as granter and grantee by default. Set opts.role to
+ * 'granter' or 'grantee' to narrow the search.
+ *
+ * @param {import('@cosmjs/tendermint-rpc').Tendermint37Client} tmClient - From createRpcQueryClient().tmClient
+ * @param {string} address - Address to search (sent1...)
+ * @param {object} [opts]
+ * @param {'granter'|'grantee'|'both'} [opts.role='both'] - Which role to search
+ * @param {number} [opts.perPage=50] - Results per page
+ * @param {'asc'|'desc'} [opts.order='desc'] - Sort order (newest first by default)
+ * @returns {Promise<Array<{ action: 'grant'|'revoke', granter: string, grantee: string, txHash: string, height: number }>>}
+ */
+export async function queryFeeGrantHistory(tmClient, address, opts = {}) {
+  if (!tmClient) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'tmClient is required');
+  if (!address) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'address is required');
+
+  const { role = 'both', perPage = 50, order = 'desc' } = opts;
+
+  const queries = [];
+  if (role === 'both' || role === 'granter') {
+    queries.push(`message.action='/cosmos.feegrant.v1beta1.MsgGrantAllowance' AND message.sender='${address}'`);
+    queries.push(`message.action='/cosmos.feegrant.v1beta1.MsgRevokeAllowance' AND message.sender='${address}'`);
+  }
+  if (role === 'both' || role === 'grantee') {
+    queries.push(`message.action='/cosmos.feegrant.v1beta1.MsgGrantAllowance' AND cosmos.feegrant.v1beta1.EventGrantAllowance.grantee='${address}'`);
+    queries.push(`message.action='/cosmos.feegrant.v1beta1.MsgRevokeAllowance' AND cosmos.feegrant.v1beta1.EventRevokeAllowance.grantee='${address}'`);
+  }
+
+  const seen = new Set();
+  const results = [];
+
+  for (const query of queries) {
+    try {
+      const resp = await tmClient.txSearchAll({ query, per_page: perPage, order_by: order });
+      for (const tx of resp.txs) {
+        const hash = Buffer.from(tx.hash).toString('hex').toUpperCase();
+        if (seen.has(hash)) continue;
+
+        for (const ev of tx.result.events) {
+          const decoded = decodeFeeGrantEvent(ev, hash, tx.height);
+          if (decoded) {
+            results.push(decoded);
+          }
+        }
+        seen.add(hash);
+      }
+    } catch { /* query may fail if node doesn't index — skip silently */ }
+  }
+
+  // Sort by height descending (newest first)
+  results.sort((a, b) => b.height - a.height);
+
+  return results;
+}

package/operator/plan-ownership.js

@@ -0,0 +1,89 @@
+/**
+ * Sentinel SDK — Plan Ownership Pre-Flight
+ *
+ * Verifies the calling wallet owns a plan before broadcasting any mutating TX.
+ * Saves ~0.005 P2P per rejected broadcast and gives a clean error instead of
+ * a chain rejection.
+ *
+ * The sent <-> sentprov bech32 conversion is a footgun every plan-manager
+ * consumer hits independently. This module is the single source of truth.
+ *
+ * Usage:
+ *   import { assertPlanOwnership, PlanOwnershipError } from './operator/plan-ownership.js';
+ *   const plan = await assertPlanOwnership({ planId, walletAddr, client });
+ *   // throws PlanOwnershipError if not owner; returns plan object if ok
+ */
+
+import { fromBech32, toBech32 } from '@cosmjs/encoding';
+import { rpcQueryPlan } from '../chain/rpc.js';
+import { lcdQuery } from '../chain/lcd.js';
+
+// ─── Error Type ──────────────────────────────────────────────────────────────
+
+export class PlanOwnershipError extends Error {
+  constructor({ planId, expected, actual }) {
+    super(`Plan ${planId} is owned by ${expected}, not ${actual}`);
+    this.code = 'PLAN_OWNERSHIP_ERROR';
+    this.planId = planId;
+    this.expected = expected;
+    this.actual = actual;
+  }
+}
+
+// ─── Address Conversion ──────────────────────────────────────────────────────
+
+/**
+ * Convert a sent1... wallet address to its sentprov... equivalent.
+ * Plan `provider_address` fields use sentprov prefix; wallet addresses use sent.
+ * The raw bytes are identical — only the prefix differs.
+ */
+export function walletToProviderAddr(sentAddr) {
+  return toBech32('sentprov', fromBech32(sentAddr).data);
+}
+
+// ─── Plan Fetcher (RPC-first) ────────────────────────────────────────────────
+
+async function fetchPlan(planId, client, preferRpc) {
+  if (preferRpc && client?.tmClient) {
+    try {
+      return await rpcQueryPlan(client.tmClient, planId);
+    } catch (_) {
+      // fall through to LCD
+    }
+  }
+  // LCD fallback
+  const res = await lcdQuery(`/sentinel/plan/v3/plans/${planId}`);
+  return res?.plan ?? null;
+}
+
+// ─── assertPlanOwnership ─────────────────────────────────────────────────────
+
+/**
+ * Assert that `walletAddr` owns plan `planId`. Throws `PlanOwnershipError`
+ * if the plan exists but belongs to a different provider. Throws a generic
+ * Error if the plan does not exist.
+ *
+ * @param {object} opts
+ * @param {number|string} opts.planId    - Plan ID to check
+ * @param {string}  opts.walletAddr      - Caller's sent1... wallet address
+ * @param {object}  opts.client          - SentinelClient (needs .tmClient for RPC)
+ * @param {boolean} [opts.preferRpc=true] - Try RPC first, fall back to LCD
+ * @returns {Promise<object>} Plan object if ownership confirmed
+ * @throws {PlanOwnershipError} If a different provider owns the plan
+ * @throws {Error} If the plan is not found
+ */
+export async function assertPlanOwnership({ planId, walletAddr, client, preferRpc = true }) {
+  const plan = await fetchPlan(planId, client, preferRpc);
+  if (!plan) throw new Error(`Plan ${planId} not found`);
+
+  const walletAsProv = walletToProviderAddr(walletAddr);
+  if (plan.provider_address !== walletAsProv) {
+    throw new PlanOwnershipError({
+      planId,
+      expected: plan.provider_address,
+      actual: walletAsProv,
+    });
+  }
+
+  return plan;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blue-js-sdk",
-  "version": "2.7.1",
+  "version": "2.7.2",
   "description": "Decentralized VPN SDK for the Sentinel P2P bandwidth network. WireGuard + V2Ray tunnels, Cosmos blockchain, 900+ nodes. Tested on Windows. macOS/Linux support included but untested.",
   "type": "module",
   "main": "index.js",
@@ -33,6 +33,7 @@
   "files": [
     "*.js",
     "types/",
+    "auth/",
     "chain/",
     "connection/",
     "protocol/",
@@ -42,6 +43,7 @@
     "speedtest/",
     "state/",
     "client/",
+    "operator/",
     "cli/",
     "config/",
     "errors/",