blue-js-sdk 2.0.0

package/chain/client.js

@@ -0,0 +1,160 @@
+/**
+ * Sentinel SDK — Chain / Client Module
+ *
+ * CosmJS Registry building, SigningStargateClient creation,
+ * and all MSG_TYPES constants.
+ *
+ * Usage:
+ *   import { createClient, buildRegistry, MSG_TYPES } from './chain/client.js';
+ *   const client = await createClient(rpcUrl, wallet);
+ */
+
+import { Registry } from '@cosmjs/proto-signing';
+import { SigningStargateClient, GasPrice, defaultRegistryTypes } from '@cosmjs/stargate';
+
+// Protobuf encoders from v3protocol.js
+import {
+  encodeMsgStartSession,
+  encodeMsgEndSession,
+  encodeMsgStartSubscription,
+  encodeMsgSubStartSession,
+  encodeMsgCancelSubscription,
+  encodeMsgRenewSubscription,
+  encodeMsgShareSubscription,
+  encodeMsgUpdateSubscription,
+  encodeMsgUpdateSession,
+  encodeMsgRegisterNode,
+  encodeMsgUpdateNodeDetails,
+  encodeMsgUpdateNodeStatus,
+  encodeMsgUpdatePlanDetails,
+} from '../v3protocol.js';
+
+// Plan/provider/lease encoders from plan-operations.js
+import {
+  encodeMsgRegisterProvider,
+  encodeMsgUpdateProviderDetails,
+  encodeMsgUpdateProviderStatus,
+  encodeMsgCreatePlan,
+  encodeMsgUpdatePlanStatus,
+  encodeMsgLinkNode,
+  encodeMsgUnlinkNode,
+  encodeMsgPlanStartSession,
+  encodeMsgStartLease,
+  encodeMsgEndLease,
+} from '../plan-operations.js';
+
+import { GAS_PRICE } from '../defaults.js';
+
+// ─── CosmJS Registry ─────────────────────────────────────────────────────────
+
+/**
+ * Adapter that wraps a manual protobuf encoder for CosmJS's Registry.
+ * CosmJS expects { fromPartial, encode, decode } — we only need encode.
+ */
+function makeMsgType(encodeFn) {
+  return {
+    fromPartial: (v) => v,
+    encode: (inst) => ({ finish: () => encodeFn(inst) }),
+    decode: () => ({}),
+  };
+}
+
+/**
+ * Build a CosmJS Registry with ALL 14 Sentinel message types registered.
+ * This is required for signAndBroadcast to encode Sentinel-specific messages.
+ */
+export function buildRegistry() {
+  return new Registry([
+    ...defaultRegistryTypes,
+    // Direct node session (v3protocol.js)
+    ['/sentinel.node.v3.MsgStartSessionRequest', makeMsgType(encodeMsgStartSession)],
+    // End session (v3protocol.js)
+    ['/sentinel.session.v3.MsgCancelSessionRequest', makeMsgType(encodeMsgEndSession)],
+    // Subscription (v3protocol.js)
+    ['/sentinel.subscription.v3.MsgStartSubscriptionRequest', makeMsgType(encodeMsgStartSubscription)],
+    ['/sentinel.subscription.v3.MsgStartSessionRequest', makeMsgType(encodeMsgSubStartSession)],
+    // Plan (plan-operations.js)
+    ['/sentinel.plan.v3.MsgStartSessionRequest', makeMsgType(encodeMsgPlanStartSession)],
+    ['/sentinel.plan.v3.MsgCreatePlanRequest', makeMsgType(encodeMsgCreatePlan)],
+    ['/sentinel.plan.v3.MsgLinkNodeRequest', makeMsgType(encodeMsgLinkNode)],
+    ['/sentinel.plan.v3.MsgUnlinkNodeRequest', makeMsgType(encodeMsgUnlinkNode)],
+    ['/sentinel.plan.v3.MsgUpdatePlanStatusRequest', makeMsgType(encodeMsgUpdatePlanStatus)],
+    // Provider (plan-operations.js)
+    ['/sentinel.provider.v3.MsgRegisterProviderRequest', makeMsgType(encodeMsgRegisterProvider)],
+    ['/sentinel.provider.v3.MsgUpdateProviderDetailsRequest', makeMsgType(encodeMsgUpdateProviderDetails)],
+    ['/sentinel.provider.v3.MsgUpdateProviderStatusRequest', makeMsgType(encodeMsgUpdateProviderStatus)],
+    // Plan details update (v3 — NEW, from sentinel-go-sdk)
+    ['/sentinel.plan.v3.MsgUpdatePlanDetailsRequest', makeMsgType(encodeMsgUpdatePlanDetails)],
+    // Lease (plan-operations.js)
+    ['/sentinel.lease.v1.MsgStartLeaseRequest', makeMsgType(encodeMsgStartLease)],
+    ['/sentinel.lease.v1.MsgEndLeaseRequest', makeMsgType(encodeMsgEndLease)],
+    // Subscription management (v3 — from sentinel-go-sdk)
+    ['/sentinel.subscription.v3.MsgCancelSubscriptionRequest', makeMsgType(encodeMsgCancelSubscription)],
+    ['/sentinel.subscription.v3.MsgRenewSubscriptionRequest', makeMsgType(encodeMsgRenewSubscription)],
+    ['/sentinel.subscription.v3.MsgShareSubscriptionRequest', makeMsgType(encodeMsgShareSubscription)],
+    ['/sentinel.subscription.v3.MsgUpdateSubscriptionRequest', makeMsgType(encodeMsgUpdateSubscription)],
+    // Session management (v3)
+    ['/sentinel.session.v3.MsgUpdateSessionRequest', makeMsgType(encodeMsgUpdateSession)],
+    // Node operator (v3 — for node operators, NOT consumer apps)
+    ['/sentinel.node.v3.MsgRegisterNodeRequest', makeMsgType(encodeMsgRegisterNode)],
+    ['/sentinel.node.v3.MsgUpdateNodeDetailsRequest', makeMsgType(encodeMsgUpdateNodeDetails)],
+    ['/sentinel.node.v3.MsgUpdateNodeStatusRequest', makeMsgType(encodeMsgUpdateNodeStatus)],
+  ]);
+}
+
+// ─── Signing Client ──────────────────────────────────────────────────────────
+
+/**
+ * Create a SigningStargateClient connected to Sentinel RPC.
+ * Gas price: from defaults.js GAS_PRICE (chain minimum).
+ */
+export async function createClient(rpcUrl, wallet) {
+  return SigningStargateClient.connectWithSigner(rpcUrl, wallet, {
+    gasPrice: GasPrice.fromString(GAS_PRICE),
+    registry: buildRegistry(),
+  });
+}
+
+// ─── All Type URL Constants ──────────────────────────────────────────────────
+
+export const MSG_TYPES = {
+  // Direct node session
+  START_SESSION:          '/sentinel.node.v3.MsgStartSessionRequest',
+  END_SESSION:            '/sentinel.session.v3.MsgCancelSessionRequest',
+  // Subscription
+  START_SUBSCRIPTION:     '/sentinel.subscription.v3.MsgStartSubscriptionRequest',
+  SUB_START_SESSION:      '/sentinel.subscription.v3.MsgStartSessionRequest',
+  // Plan
+  PLAN_START_SESSION:     '/sentinel.plan.v3.MsgStartSessionRequest',
+  CREATE_PLAN:            '/sentinel.plan.v3.MsgCreatePlanRequest',
+  UPDATE_PLAN_STATUS:     '/sentinel.plan.v3.MsgUpdatePlanStatusRequest',
+  LINK_NODE:              '/sentinel.plan.v3.MsgLinkNodeRequest',
+  UNLINK_NODE:            '/sentinel.plan.v3.MsgUnlinkNodeRequest',
+  // Provider
+  REGISTER_PROVIDER:      '/sentinel.provider.v3.MsgRegisterProviderRequest',
+  UPDATE_PROVIDER:        '/sentinel.provider.v3.MsgUpdateProviderDetailsRequest',
+  UPDATE_PROVIDER_STATUS: '/sentinel.provider.v3.MsgUpdateProviderStatusRequest',
+  // Plan details update (v3 — NEW)
+  UPDATE_PLAN_DETAILS:    '/sentinel.plan.v3.MsgUpdatePlanDetailsRequest',
+  // Lease
+  START_LEASE:            '/sentinel.lease.v1.MsgStartLeaseRequest',
+  END_LEASE:              '/sentinel.lease.v1.MsgEndLeaseRequest',
+  // Subscription management (v3)
+  CANCEL_SUBSCRIPTION:    '/sentinel.subscription.v3.MsgCancelSubscriptionRequest',
+  RENEW_SUBSCRIPTION:     '/sentinel.subscription.v3.MsgRenewSubscriptionRequest',
+  SHARE_SUBSCRIPTION:     '/sentinel.subscription.v3.MsgShareSubscriptionRequest',
+  UPDATE_SUBSCRIPTION:    '/sentinel.subscription.v3.MsgUpdateSubscriptionRequest',
+  // Session management (v3)
+  UPDATE_SESSION:         '/sentinel.session.v3.MsgUpdateSessionRequest',
+  // Node operator (v3)
+  REGISTER_NODE:          '/sentinel.node.v3.MsgRegisterNodeRequest',
+  UPDATE_NODE_DETAILS:    '/sentinel.node.v3.MsgUpdateNodeDetailsRequest',
+  UPDATE_NODE_STATUS:     '/sentinel.node.v3.MsgUpdateNodeStatusRequest',
+  // Cosmos FeeGrant
+  GRANT_FEE_ALLOWANCE:    '/cosmos.feegrant.v1beta1.MsgGrantAllowance',
+  REVOKE_FEE_ALLOWANCE:   '/cosmos.feegrant.v1beta1.MsgRevokeAllowance',
+  // Cosmos Authz
+  AUTHZ_GRANT:            '/cosmos.authz.v1beta1.MsgGrant',
+  AUTHZ_REVOKE:           '/cosmos.authz.v1beta1.MsgRevoke',
+  AUTHZ_EXEC:             '/cosmos.authz.v1beta1.MsgExec',
+};

package/chain/fee-grants.js

@@ -0,0 +1,305 @@
+/**
+ * Sentinel SDK — Chain / Fee Grants Module
+ *
+ * FeeGrant message builders, queries, monitoring, and workflow helpers.
+ * Gas-free UX: granter pays fees for grantee's transactions.
+ *
+ * Usage:
+ *   import { buildFeeGrantMsg, queryFeeGrants, monitorFeeGrants } from './chain/fee-grants.js';
+ *   const msg = buildFeeGrantMsg(serviceAddr, userAddr, { spendLimit: 5000000 });
+ */
+
+import { EventEmitter } from 'events';
+import { protoString, protoInt64, protoEmbedded } from '../v3protocol.js';
+import { LCD_ENDPOINTS } from '../defaults.js';
+import { ValidationError, ErrorCodes } from '../errors.js';
+import { lcd, lcdPaginatedSafe, lcdQueryAll } from './lcd.js';
+import { isSameKey } from './wallet.js';
+import { queryPlanSubscribers } from './queries.js';
+
+// ─── Protobuf Helpers for FeeGrant ──────────────────────────────────────────
+// Uses the same manual protobuf encoding as Sentinel types — no codegen needed.
+
+function encodeCoin(denom, amount) {
+  return Buffer.concat([protoString(1, denom), protoString(2, String(amount))]);
+}
+
+function encodeTimestamp(date) {
+  const ms = date.getTime();
+  if (Number.isNaN(ms)) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'encodeTimestamp(): invalid date', { date });
+  const seconds = BigInt(Math.floor(ms / 1000));
+  return Buffer.concat([protoInt64(1, seconds)]);
+}
+
+function encodeBasicAllowance(spendLimit, expiration) {
+  const parts = [];
+  if (spendLimit != null && spendLimit !== false) {
+    const coins = Array.isArray(spendLimit) ? spendLimit : [{ denom: 'udvpn', amount: String(spendLimit) }];
+    for (const coin of coins) {
+      parts.push(protoEmbedded(1, encodeCoin(coin.denom || 'udvpn', coin.amount)));
+    }
+  }
+  if (expiration) {
+    parts.push(protoEmbedded(2, encodeTimestamp(expiration instanceof Date ? expiration : new Date(expiration))));
+  }
+  return Buffer.concat(parts);
+}
+
+function encodeAllowedMsgAllowance(innerTypeUrl, innerBytes, allowedMessages) {
+  const parts = [protoEmbedded(1, encodeAny(innerTypeUrl, innerBytes))];
+  for (const msg of allowedMessages) {
+    parts.push(protoString(2, msg));
+  }
+  return Buffer.concat(parts);
+}
+
+function encodeAny(typeUrl, valueBytes) {
+  return Buffer.concat([
+    protoString(1, typeUrl),
+    protoEmbedded(2, valueBytes),
+  ]);
+}
+
+// ─── FeeGrant (cosmos.feegrant.v1beta1) ─────────────────────────────────────
+
+/**
+ * Build a MsgGrantAllowance message.
+ * @param {string} granter - Address paying fees (sent1...)
+ * @param {string} grantee - Address receiving fee grant (sent1...)
+ * @param {object} opts
+ * @param {number|Array} opts.spendLimit - Max spend in udvpn (number) or [{denom, amount}]
+ * @param {Date|string} opts.expiration - Optional expiry date
+ * @param {string[]} opts.allowedMessages - Optional: restrict to specific msg types (uses AllowedMsgAllowance)
+ */
+export function buildFeeGrantMsg(granter, grantee, opts = {}) {
+  const { spendLimit, expiration, allowedMessages } = opts;
+  const basicBytes = encodeBasicAllowance(spendLimit, expiration);
+
+  let allowanceTypeUrl, allowanceBytes;
+  if (allowedMessages?.length) {
+    allowanceTypeUrl = '/cosmos.feegrant.v1beta1.AllowedMsgAllowance';
+    allowanceBytes = encodeAllowedMsgAllowance(
+      '/cosmos.feegrant.v1beta1.BasicAllowance', basicBytes, allowedMessages
+    );
+  } else {
+    allowanceTypeUrl = '/cosmos.feegrant.v1beta1.BasicAllowance';
+    allowanceBytes = basicBytes;
+  }
+
+  // MsgGrantAllowance: field 1=granter, field 2=grantee, field 3=allowance(Any)
+  return {
+    typeUrl: '/cosmos.feegrant.v1beta1.MsgGrantAllowance',
+    value: { granter, grantee, allowance: { typeUrl: allowanceTypeUrl, value: Uint8Array.from(allowanceBytes) } },
+  };
+}
+
+/**
+ * Build a MsgRevokeAllowance message.
+ */
+export function buildRevokeFeeGrantMsg(granter, grantee) {
+  return {
+    typeUrl: '/cosmos.feegrant.v1beta1.MsgRevokeAllowance',
+    value: { granter, grantee },
+  };
+}
+
+/**
+ * Query fee grants given to a grantee.
+ * @returns {Promise<Array>} Array of allowance objects
+ */
+export async function queryFeeGrants(lcdUrl, grantee) {
+  const { items } = await lcdPaginatedSafe(lcdUrl, `/cosmos/feegrant/v1beta1/allowances/${grantee}`, 'allowances');
+  return items;
+}
+
+/**
+ * Query fee grants issued BY an address (where addr is the granter).
+ * @param {string} lcdUrl
+ * @param {string} granter - Address that issued the grants
+ * @returns {Promise<Array>}
+ */
+export async function queryFeeGrantsIssued(lcdUrl, granter) {
+  const { items } = await lcdPaginatedSafe(lcdUrl, `/cosmos/feegrant/v1beta1/issued/${granter}`, 'allowances');
+  return items;
+}
+
+/**
+ * Query a specific fee grant between granter and grantee.
+ * @returns {Promise<object|null>} Allowance object or null
+ */
+export async function queryFeeGrant(lcdUrl, granter, grantee) {
+  try {
+    const data = await lcd(lcdUrl, `/cosmos/feegrant/v1beta1/allowance/${granter}/${grantee}`);
+    return data.allowance || null;
+  } catch { return null; } // 404 = no grant
+}
+
+// ─── Fee Grant Workflow Helpers (v25b) ────────────────────────────────────────
+
+/**
+ * Grant fee allowance to all plan subscribers who don't already have one.
+ * Filters out self-grants (granter === grantee) and already-granted addresses.
+ *
+ * @param {number|string} planId
+ * @param {object} opts
+ * @param {string} opts.granterAddress - Who pays fees (typically plan owner)
+ * @param {string} opts.lcdUrl - LCD endpoint
+ * @param {object} [opts.grantOpts] - Options for buildFeeGrantMsg (spendLimit, expiration, allowedMessages)
+ * @returns {Promise<{ msgs: Array, skipped: string[], newGrants: string[] }>} Messages ready for broadcast
+ */
+export async function grantPlanSubscribers(planId, opts = {}) {
+  const { granterAddress, lcdUrl, grantOpts = {} } = opts;
+  if (!granterAddress) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'granterAddress is required');
+
+  // Get subscribers
+  const { subscribers } = await queryPlanSubscribers(planId, { lcdUrl });
+
+  // Get existing grants ISSUED BY granter (not grants received)
+  const existingGrants = await queryFeeGrantsIssued(lcdUrl || LCD_ENDPOINTS[0].url, granterAddress);
+  const alreadyGranted = new Set(existingGrants.map(g => g.grantee));
+
+  const msgs = [];
+  const skipped = [];
+  const newGrants = [];
+
+  const now = new Date();
+  // Deduplicate by address and filter active+non-expired
+  const seen = new Set();
+  for (const sub of subscribers) {
+    const addr = sub.acc_address || sub.address;
+    if (!addr || seen.has(addr)) continue;
+    seen.add(addr);
+    // Skip self-grant (chain rejects granter === grantee)
+    if (addr === granterAddress || isSameKey(addr, granterAddress)) { skipped.push(addr); continue; }
+    // Skip inactive or expired
+    if (sub.status && sub.status !== 'active') { skipped.push(addr); continue; }
+    if (sub.inactive_at && new Date(sub.inactive_at) <= now) { skipped.push(addr); continue; }
+    // Skip already granted
+    if (alreadyGranted.has(addr)) { skipped.push(addr); continue; }
+    msgs.push(buildFeeGrantMsg(granterAddress, addr, grantOpts));
+    newGrants.push(addr);
+  }
+
+  return { msgs, skipped, newGrants };
+}
+
+/**
+ * Find fee grants expiring within N days.
+ *
+ * @param {string} lcdUrl - LCD endpoint
+ * @param {string} granteeOrGranter - Address to check grants for
+ * @param {number} withinDays - Check grants expiring within this many days (default: 7)
+ * @param {'grantee'|'granter'} [role='grantee'] - Whether to check as grantee or granter
+ * @returns {Promise<Array<{ granter: string, grantee: string, expiresAt: Date|null, daysLeft: number|null }>>}
+ */
+export async function getExpiringGrants(lcdUrl, granteeOrGranter, withinDays = 7, role = 'grantee') {
+  const grants = role === 'grantee'
+    ? await queryFeeGrants(lcdUrl, granteeOrGranter)
+    : await queryFeeGrantsIssued(lcdUrl, granteeOrGranter);
+
+  const now = Date.now();
+  const cutoff = now + withinDays * 24 * 60 * 60_000;
+  const expiring = [];
+
+  for (const g of grants) {
+    // Fee grant allowances have complex nested @type structures:
+    // BasicAllowance: { expiration }
+    // PeriodicAllowance: { basic: { expiration } }
+    // AllowedMsgAllowance: { allowance: { expiration } or allowance: { basic: { expiration } } }
+    const a = g.allowance || {};
+    const inner = a.allowance || a; // unwrap AllowedMsgAllowance
+    const expStr = inner.expiration || inner.basic?.expiration || a.expiration || a.basic?.expiration;
+    if (!expStr) continue; // no expiry set
+    const expiresAt = new Date(expStr);
+    if (expiresAt.getTime() <= cutoff) {
+      expiring.push({
+        granter: g.granter,
+        grantee: g.grantee,
+        expiresAt,
+        daysLeft: Math.max(0, Math.round((expiresAt.getTime() - now) / (24 * 60 * 60_000))),
+      });
+    }
+  }
+  return expiring;
+}
+
+/**
+ * Revoke and re-grant expiring fee grants.
+ *
+ * @param {string} lcdUrl
+ * @param {string} granterAddress
+ * @param {number} withinDays - Renew grants expiring within N days
+ * @param {object} [grantOpts] - Options for new grants (spendLimit, expiration, allowedMessages)
+ * @returns {Promise<{ msgs: Array, renewed: string[] }>} Messages ready for broadcast
+ */
+export async function renewExpiringGrants(lcdUrl, granterAddress, withinDays = 7, grantOpts = {}) {
+  const expiring = await getExpiringGrants(lcdUrl, granterAddress, withinDays, 'granter');
+  const msgs = [];
+  const renewed = [];
+
+  for (const g of expiring) {
+    if (g.grantee === granterAddress) continue; // skip self
+    msgs.push(buildRevokeFeeGrantMsg(granterAddress, g.grantee));
+    msgs.push(buildFeeGrantMsg(granterAddress, g.grantee, grantOpts));
+    renewed.push(g.grantee);
+  }
+
+  return { msgs, renewed };
+}
+
+// ─── Fee Grant Monitoring (v25b) ─────────────────────────────────────────────
+
+/**
+ * Monitor fee grants for expiry. Returns an EventEmitter that checks grants on interval.
+ *
+ * @param {object} opts
+ * @param {string} opts.lcdUrl - LCD endpoint
+ * @param {string} opts.address - Address to monitor (as granter)
+ * @param {number} [opts.checkIntervalMs] - Check interval (default: 6 hours)
+ * @param {number} [opts.warnDays] - Emit 'expiring' when grant expires within N days (default: 7)
+ * @param {boolean} [opts.autoRenew] - Auto-revoke+re-grant expiring grants (default: false)
+ * @param {object} [opts.grantOpts] - Options for renewed grants
+ * @returns {EventEmitter} Emits 'expiring' and 'expired' events. Call .stop() to stop monitoring.
+ */
+export function monitorFeeGrants(opts = {}) {
+  const { lcdUrl, address, checkIntervalMs = 6 * 60 * 60_000, warnDays = 7, autoRenew = false, grantOpts = {} } = opts;
+  if (!lcdUrl || !address) throw new ValidationError(ErrorCodes.INVALID_OPTIONS, 'monitorFeeGrants requires lcdUrl and address');
+
+  const emitter = new EventEmitter();
+  let timer = null;
+
+  const check = async () => {
+    try {
+      const expiring = await getExpiringGrants(lcdUrl, address, warnDays, 'granter');
+      const now = Date.now();
+
+      for (const g of expiring) {
+        if (g.expiresAt.getTime() <= now) {
+          emitter.emit('expired', g);
+        } else {
+          emitter.emit('expiring', g);
+        }
+      }
+
+      if (autoRenew && expiring.length > 0) {
+        const { msgs, renewed } = await renewExpiringGrants(lcdUrl, address, warnDays, grantOpts);
+        if (msgs.length > 0) {
+          emitter.emit('renew', { msgs, renewed });
+        }
+      }
+    } catch (err) {
+      emitter.emit('error', err);
+    }
+  };
+
+  // Start checking
+  check();
+  timer = setInterval(check, checkIntervalMs);
+  if (timer.unref) timer.unref(); // Don't prevent process exit
+
+  emitter.stop = () => {
+    if (timer) { clearInterval(timer); timer = null; }
+  };
+
+  return emitter;
+}