blue-js-sdk 2.0.0

package/protocol/messages.js

@@ -0,0 +1,346 @@
+/**
+ * Sentinel SDK — Protocol / Message Builders
+ *
+ * Returns proper EncodeObject ({ typeUrl, value }) for each Sentinel message type.
+ * These are ready for CosmJS signAndBroadcast() — no wrapping needed.
+ *
+ * The encodeMsg*() functions in encoding.js return raw Uint8Array (protobuf bytes).
+ * These buildMsg*() functions return { typeUrl, value: object } that CosmJS can encode
+ * via the Registry. Use these for all external/consumer usage.
+ *
+ * Usage:
+ *   import { buildMsgStartSession } from './protocol/messages.js';
+ *   const msg = buildMsgStartSession({ from, nodeAddress, gigabytes: 1, maxPrice });
+ *   const result = await client.signAndBroadcast(address, [msg], fee);
+ */
+
+// ─── Type URL Constants ────────────────────────────────────────────────────
+
+export const TYPE_URLS = {
+  // Node sessions
+  START_SESSION:          '/sentinel.node.v3.MsgStartSessionRequest',
+  CANCEL_SESSION:         '/sentinel.session.v3.MsgCancelSessionRequest',
+  UPDATE_SESSION:         '/sentinel.session.v3.MsgUpdateSessionRequest',
+  // Subscriptions
+  START_SUBSCRIPTION:     '/sentinel.subscription.v3.MsgStartSubscriptionRequest',
+  CANCEL_SUBSCRIPTION:    '/sentinel.subscription.v3.MsgCancelSubscriptionRequest',
+  RENEW_SUBSCRIPTION:     '/sentinel.subscription.v3.MsgRenewSubscriptionRequest',
+  SHARE_SUBSCRIPTION:     '/sentinel.subscription.v3.MsgShareSubscriptionRequest',
+  UPDATE_SUBSCRIPTION:    '/sentinel.subscription.v3.MsgUpdateSubscriptionRequest',
+  SUB_START_SESSION:      '/sentinel.subscription.v3.MsgStartSessionRequest',
+  // Plans
+  PLAN_START_SESSION:     '/sentinel.plan.v3.MsgStartSessionRequest',
+  CREATE_PLAN:            '/sentinel.plan.v3.MsgCreatePlanRequest',
+  UPDATE_PLAN_DETAILS:    '/sentinel.plan.v3.MsgUpdatePlanDetailsRequest',
+  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',
+  // Lease
+  START_LEASE:            '/sentinel.lease.v1.MsgStartLeaseRequest',
+  END_LEASE:              '/sentinel.lease.v1.MsgEndLeaseRequest',
+  // Node operator
+  REGISTER_NODE:          '/sentinel.node.v3.MsgRegisterNodeRequest',
+  UPDATE_NODE_DETAILS:    '/sentinel.node.v3.MsgUpdateNodeDetailsRequest',
+  UPDATE_NODE_STATUS:     '/sentinel.node.v3.MsgUpdateNodeStatusRequest',
+};
+
+// ─── Session Message Builders ──────────────────────────────────────────────
+
+/**
+ * Build MsgStartSessionRequest (direct node session).
+ * @param {{ from: string, nodeAddress: string, gigabytes?: number, hours?: number, maxPrice?: { denom: string, amount: string } }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgStartSession({ from, nodeAddress, gigabytes = 1, hours = 0, maxPrice }) {
+  return {
+    typeUrl: TYPE_URLS.START_SESSION,
+    value: {
+      from,
+      node_address: nodeAddress,
+      gigabytes: gigabytes || 0,
+      hours: hours || 0,
+      max_price: maxPrice || undefined,
+    },
+  };
+}
+
+/**
+ * Build MsgCancelSessionRequest (end/cancel a session).
+ * @param {{ from: string, id: number|bigint }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgCancelSession({ from, id }) {
+  return {
+    typeUrl: TYPE_URLS.CANCEL_SESSION,
+    value: { from, id: Number(id) },
+  };
+}
+
+/** Alias for backwards compatibility. */
+export const buildMsgEndSession = buildMsgCancelSession;
+
+/**
+ * Build MsgUpdateSessionRequest (node reports bandwidth).
+ * @param {{ from: string, id: number|bigint, downloadBytes: number, uploadBytes: number }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgUpdateSession({ from, id, downloadBytes, uploadBytes }) {
+  return {
+    typeUrl: TYPE_URLS.UPDATE_SESSION,
+    value: { from, id: Number(id), download_bytes: downloadBytes, upload_bytes: uploadBytes },
+  };
+}
+
+// ─── Subscription Message Builders ─────────────────────────────────────────
+
+/**
+ * Build MsgStartSubscriptionRequest (subscribe to a plan).
+ * @param {{ from: string, id: number|bigint, denom?: string, renewalPricePolicy?: number }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgStartSubscription({ from, id, denom = 'udvpn', renewalPricePolicy = 0 }) {
+  return {
+    typeUrl: TYPE_URLS.START_SUBSCRIPTION,
+    value: { from, id: Number(id), denom, renewal_price_policy: renewalPricePolicy },
+  };
+}
+
+/**
+ * Build MsgStartSessionRequest via subscription.
+ * @param {{ from: string, id: number|bigint, nodeAddress: string }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgSubStartSession({ from, id, nodeAddress }) {
+  return {
+    typeUrl: TYPE_URLS.SUB_START_SESSION,
+    value: { from, id: Number(id), node_address: nodeAddress },
+  };
+}
+
+/**
+ * Build MsgCancelSubscriptionRequest.
+ * @param {{ from: string, id: number|bigint }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgCancelSubscription({ from, id }) {
+  return {
+    typeUrl: TYPE_URLS.CANCEL_SUBSCRIPTION,
+    value: { from, id: Number(id) },
+  };
+}
+
+/**
+ * Build MsgRenewSubscriptionRequest.
+ * @param {{ from: string, id: number|bigint, denom?: string }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgRenewSubscription({ from, id, denom = 'udvpn' }) {
+  return {
+    typeUrl: TYPE_URLS.RENEW_SUBSCRIPTION,
+    value: { from, id: Number(id), denom },
+  };
+}
+
+/**
+ * Build MsgShareSubscriptionRequest.
+ * @param {{ from: string, id: number|bigint, accAddress: string, bytes: number }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgShareSubscription({ from, id, accAddress, bytes }) {
+  return {
+    typeUrl: TYPE_URLS.SHARE_SUBSCRIPTION,
+    value: { from, id: Number(id), acc_address: accAddress, bytes },
+  };
+}
+
+/**
+ * Build MsgUpdateSubscriptionRequest.
+ * @param {{ from: string, id: number|bigint, renewalPricePolicy: number }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgUpdateSubscription({ from, id, renewalPricePolicy }) {
+  return {
+    typeUrl: TYPE_URLS.UPDATE_SUBSCRIPTION,
+    value: { from, id: Number(id), renewal_price_policy: renewalPricePolicy },
+  };
+}
+
+// ─── Plan Message Builders ─────────────────────────────────────────────────
+
+/**
+ * Build MsgStartSessionRequest via plan (creates subscription + starts session).
+ * @param {{ from: string, id: number|bigint, denom?: string, renewalPricePolicy?: number, nodeAddress: string }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgPlanStartSession({ from, id, denom = 'udvpn', renewalPricePolicy = 0, nodeAddress }) {
+  return {
+    typeUrl: TYPE_URLS.PLAN_START_SESSION,
+    value: { from, id: Number(id), denom, renewal_price_policy: renewalPricePolicy, node_address: nodeAddress },
+  };
+}
+
+/**
+ * Build MsgCreatePlanRequest.
+ * @param {{ from: string, bytes: string|number, duration: { seconds: number }, prices?: Array, private?: boolean }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgCreatePlan({ from, bytes, duration, prices = [], isPrivate = false }) {
+  return {
+    typeUrl: TYPE_URLS.CREATE_PLAN,
+    value: { from, bytes: String(bytes), duration, prices, private: isPrivate },
+  };
+}
+
+/**
+ * Build MsgUpdatePlanDetailsRequest.
+ * @param {{ from: string, id: number|bigint, bytes?: string|number, duration?: object, prices?: Array }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgUpdatePlanDetails({ from, id, bytes, duration, prices = [] }) {
+  return {
+    typeUrl: TYPE_URLS.UPDATE_PLAN_DETAILS,
+    value: { from, id: Number(id), bytes: bytes ? String(bytes) : undefined, duration, prices },
+  };
+}
+
+/**
+ * Build MsgUpdatePlanStatusRequest.
+ * @param {{ from: string, id: number|bigint, status: number }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgUpdatePlanStatus({ from, id, status }) {
+  return {
+    typeUrl: TYPE_URLS.UPDATE_PLAN_STATUS,
+    value: { from, id: Number(id), status },
+  };
+}
+
+/**
+ * Build MsgLinkNodeRequest.
+ * @param {{ from: string, id: number|bigint, nodeAddress: string }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgLinkNode({ from, id, nodeAddress }) {
+  return {
+    typeUrl: TYPE_URLS.LINK_NODE,
+    value: { from, id: Number(id), node_address: nodeAddress },
+  };
+}
+
+/**
+ * Build MsgUnlinkNodeRequest.
+ * @param {{ from: string, id: number|bigint, nodeAddress: string }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgUnlinkNode({ from, id, nodeAddress }) {
+  return {
+    typeUrl: TYPE_URLS.UNLINK_NODE,
+    value: { from, id: Number(id), node_address: nodeAddress },
+  };
+}
+
+// ─── Provider Message Builders ─────────────────────────────────────────────
+
+/**
+ * Build MsgRegisterProviderRequest.
+ * @param {{ from: string, name: string, identity?: string, website?: string, description?: string }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgRegisterProvider({ from, name, identity = '', website = '', description = '' }) {
+  return {
+    typeUrl: TYPE_URLS.REGISTER_PROVIDER,
+    value: { from, name, identity, website, description },
+  };
+}
+
+/**
+ * Build MsgUpdateProviderDetailsRequest.
+ * @param {{ from: string, name?: string, identity?: string, website?: string, description?: string }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgUpdateProviderDetails({ from, name, identity, website, description }) {
+  return {
+    typeUrl: TYPE_URLS.UPDATE_PROVIDER,
+    value: { from, name, identity, website, description },
+  };
+}
+
+/**
+ * Build MsgUpdateProviderStatusRequest.
+ * @param {{ from: string, status: number }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgUpdateProviderStatus({ from, status }) {
+  return {
+    typeUrl: TYPE_URLS.UPDATE_PROVIDER_STATUS,
+    value: { from, status },
+  };
+}
+
+// ─── Lease Message Builders ────────────────────────────────────────────────
+
+/**
+ * Build MsgStartLeaseRequest.
+ * @param {{ from: string, nodeAddress: string, hours: number, maxPrice: object, renewalPricePolicy?: number }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgStartLease({ from, nodeAddress, hours, maxPrice, renewalPricePolicy = 0 }) {
+  return {
+    typeUrl: TYPE_URLS.START_LEASE,
+    value: { from, node_address: nodeAddress, hours, max_price: maxPrice, renewal_price_policy: renewalPricePolicy },
+  };
+}
+
+/**
+ * Build MsgEndLeaseRequest.
+ * @param {{ from: string, id: number|bigint }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgEndLease({ from, id }) {
+  return {
+    typeUrl: TYPE_URLS.END_LEASE,
+    value: { from, id: Number(id) },
+  };
+}
+
+// ─── Node Operator Message Builders ────────────────────────────────────────
+
+/**
+ * Build MsgRegisterNodeRequest.
+ * @param {{ from: string, gigabytePrices?: Array, hourlyPrices?: Array, remoteAddrs?: string[] }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgRegisterNode({ from, gigabytePrices = [], hourlyPrices = [], remoteAddrs = [] }) {
+  return {
+    typeUrl: TYPE_URLS.REGISTER_NODE,
+    value: { from, gigabyte_prices: gigabytePrices, hourly_prices: hourlyPrices, remote_addrs: remoteAddrs },
+  };
+}
+
+/**
+ * Build MsgUpdateNodeDetailsRequest.
+ * @param {{ from: string, gigabytePrices?: Array, hourlyPrices?: Array, remoteAddrs?: string[] }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgUpdateNodeDetails({ from, gigabytePrices = [], hourlyPrices = [], remoteAddrs = [] }) {
+  return {
+    typeUrl: TYPE_URLS.UPDATE_NODE_DETAILS,
+    value: { from, gigabyte_prices: gigabytePrices, hourly_prices: hourlyPrices, remote_addrs: remoteAddrs },
+  };
+}
+
+/**
+ * Build MsgUpdateNodeStatusRequest.
+ * @param {{ from: string, status: number }} opts
+ * @returns {{ typeUrl: string, value: object }}
+ */
+export function buildMsgUpdateNodeStatus({ from, status }) {
+  return {
+    typeUrl: TYPE_URLS.UPDATE_NODE_STATUS,
+    value: { from, status },
+  };
+}

package/protocol/plans.js

@@ -0,0 +1,199 @@
+/**
+ * Plan, Provider & Lease Operations for Sentinel dVPN
+ *
+ * Contains all encoder functions for plan management, provider registration,
+ * and node leasing. These are the 10 message types NOT in v3protocol.js.
+ *
+ * v3protocol.js handles: direct session, subscription, sub-session (3 types)
+ * This file handles: provider (3), plan (4), lease (2), plan-session (1) = 10 types
+ */
+
+// ─── Protobuf Encoding Primitives ────────────────────────────────────────────
+// Shared with v3.js — single source of truth for protobuf encoding.
+import { encodeVarint, protoString, protoInt64, protoEmbedded, decToScaledInt, encodePrice } from './v3.js';
+
+// protoUint64 is identical to protoInt64 — both use varint wire type 0
+function protoUint64(fieldNum, n) {
+  return protoInt64(fieldNum, n);
+}
+
+function protoBool(fieldNum, val) {
+  if (!val) return Buffer.alloc(0); // false = omit (protobuf default)
+  return Buffer.concat([encodeVarint((BigInt(fieldNum) << 3n) | 0n), encodeVarint(1)]);
+}
+
+// decToScaledInt and encodePrice imported from v3.js (single source of truth)
+
+/**
+ * Encode google.protobuf.Duration { seconds, nanos }
+ * Used by MsgCreatePlanRequest for plan duration.
+ */
+function encodeDuration({ seconds, nanos = 0 }) {
+  return Buffer.concat([
+    protoInt64(1, seconds),
+    nanos ? protoInt64(2, nanos) : Buffer.alloc(0),
+  ]);
+}
+
+// ─── Provider Messages ───────────────────────────────────────────────────────
+
+/**
+ * MsgRegisterProviderRequest (sentinel.provider.v3)
+ * Register a new provider. One wallet = one provider.
+ * from: sent prefix (account address)
+ */
+export function encodeMsgRegisterProvider({ from, name, identity, website, description }) {
+  return Uint8Array.from(Buffer.concat([
+    protoString(1, from),
+    protoString(2, name),
+    protoString(3, identity || ''),
+    protoString(4, website || ''),
+    protoString(5, description || ''),
+  ]));
+}
+
+/**
+ * MsgUpdateProviderDetailsRequest (sentinel.provider.v3)
+ * Update existing provider info.
+ * from: sentprov prefix (provider address)
+ */
+export function encodeMsgUpdateProviderDetails({ from, name, identity, website, description }) {
+  return Uint8Array.from(Buffer.concat([
+    protoString(1, from),
+    protoString(2, name || ''),
+    protoString(3, identity || ''),
+    protoString(4, website || ''),
+    protoString(5, description || ''),
+  ]));
+}
+
+/**
+ * MsgUpdateProviderStatusRequest (sentinel.provider.v3)
+ * Activate/deactivate provider. Status: 1=active, 2=inactive_pending, 3=inactive
+ * from: sent prefix (account address)
+ */
+export function encodeMsgUpdateProviderStatus({ from, status }) {
+  return Uint8Array.from(Buffer.concat([
+    protoString(1, from),
+    protoInt64(2, status),
+  ]));
+}
+
+// ─── Plan Messages ───────────────────────────────────────────────────────────
+
+/**
+ * MsgCreatePlanRequest (sentinel.plan.v3)
+ * Create a new subscription plan.
+ * from: sentprov prefix (provider address)
+ * bytes: total bandwidth as string (e.g. "10000000000" for 10GB)
+ * duration: { seconds: N } — plan validity period
+ * prices: [{ denom, base_value, quote_value }] — subscription cost
+ * isPrivate: boolean
+ *
+ * NOTE: Plans start INACTIVE by default — must send MsgUpdatePlanStatusRequest separately!
+ */
+export function encodeMsgCreatePlan({ from, bytes, duration, prices, isPrivate }) {
+  const parts = [protoString(1, from)];
+  if (bytes) parts.push(protoString(2, String(bytes)));
+  if (duration) parts.push(protoEmbedded(3, encodeDuration(
+    typeof duration === 'number' ? { seconds: duration } : duration
+  )));
+  for (const p of (prices || [])) {
+    parts.push(protoEmbedded(4, encodePrice(p)));
+  }
+  if (isPrivate) parts.push(protoBool(5, true));
+  return Uint8Array.from(Buffer.concat(parts));
+}
+
+/**
+ * MsgUpdatePlanStatusRequest (sentinel.plan.v3)
+ * Activate/deactivate a plan. Status: 1=active, 2=inactive_pending, 3=inactive
+ * from: sentprov prefix (provider address)
+ */
+export function encodeMsgUpdatePlanStatus({ from, id, status }) {
+  return Uint8Array.from(Buffer.concat([
+    protoString(1, from),
+    protoUint64(2, id),
+    protoInt64(3, status),
+  ]));
+}
+
+/**
+ * MsgLinkNodeRequest (sentinel.plan.v3)
+ * Link a leased node to a plan. Requires active lease for the node.
+ * from: sentprov prefix (provider address)
+ */
+export function encodeMsgLinkNode({ from, id, nodeAddress }) {
+  return Uint8Array.from(Buffer.concat([
+    protoString(1, from),
+    protoUint64(2, id),
+    protoString(3, nodeAddress),
+  ]));
+}
+
+/**
+ * MsgUnlinkNodeRequest (sentinel.plan.v3)
+ * Remove a node from a plan.
+ * from: sentprov prefix (provider address)
+ */
+export function encodeMsgUnlinkNode({ from, id, nodeAddress }) {
+  return Uint8Array.from(Buffer.concat([
+    protoString(1, from),
+    protoUint64(2, id),
+    protoString(3, nodeAddress),
+  ]));
+}
+
+/**
+ * MsgStartSessionRequest (sentinel.plan.v3) — COMBINED subscribe + session
+ * Subscribes to a plan AND starts a session in one TX.
+ * from: sent prefix (account address)
+ */
+export function encodeMsgPlanStartSession({ from, id, denom = 'udvpn', renewalPricePolicy = 0, nodeAddress }) {
+  const parts = [
+    protoString(1, from),
+    protoUint64(2, id),
+    protoString(3, denom),
+  ];
+  if (renewalPricePolicy) parts.push(protoInt64(4, renewalPricePolicy));
+  if (nodeAddress) parts.push(protoString(5, nodeAddress));
+  return Uint8Array.from(Buffer.concat(parts));
+}
+
+// ─── Lease Messages ──────────────────────────────────────────────────────────
+
+/**
+ * MsgStartLeaseRequest (sentinel.lease.v1)
+ * Lease a node from its operator. Provider pays node's hourly price.
+ * from: sentprov prefix (provider address)
+ *
+ * CRITICAL: maxPrice must EXACTLY match the node's hourly_prices from LCD.
+ * Any mismatch → "invalid price" error.
+ */
+export function encodeMsgStartLease({ from, nodeAddress, hours, maxPrice, renewalPricePolicy = 0 }) {
+  const parts = [
+    protoString(1, from),
+    protoString(2, nodeAddress),
+    protoInt64(3, hours),
+  ];
+  if (maxPrice) parts.push(protoEmbedded(4, encodePrice(maxPrice)));
+  if (renewalPricePolicy) parts.push(protoInt64(5, renewalPricePolicy));
+  return Uint8Array.from(Buffer.concat(parts));
+}
+
+/**
+ * MsgEndLeaseRequest (sentinel.lease.v1)
+ * End an active lease.
+ * from: sentprov prefix (provider address)
+ */
+export function encodeMsgEndLease({ from, id }) {
+  return Uint8Array.from(Buffer.concat([
+    protoString(1, from),
+    protoUint64(2, id),
+  ]));
+}
+
+// ─── Exported Helpers ────────────────────────────────────────────────────────
+
+export { encodePrice, encodeDuration, decToScaledInt };
+export { encodeVarint, protoString, protoInt64, protoUint64, protoBool, protoEmbedded };