blue-js-sdk 2.0.0

package/protocol/events.js

@@ -0,0 +1,361 @@
+/**
+ * Sentinel SDK — Protocol / Typed Event Parsers
+ *
+ * Type-safe event parsers for Sentinel chain transaction events.
+ * Replaces regex string matching with structured parsers that
+ * guarantee field access and type correctness.
+ *
+ * Pattern matches TKD Alex's sentinel-js-sdk typed event approach.
+ *
+ * Usage:
+ *   import { NodeEventCreateSession, searchEvent } from './protocol/events.js';
+ *   const event = searchEvent(NodeEventCreateSession.type, txResult.events);
+ *   if (event) {
+ *     const parsed = NodeEventCreateSession.parse(event);
+ *     console.log(parsed.sessionId);  // bigint, guaranteed
+ *   }
+ */
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Decode an event attribute key or value.
+ * Chain events may be base64-encoded (older CosmJS) or plain strings.
+ */
+function decodeAttr(raw) {
+  if (typeof raw === 'string') return raw.replace(/^"|"$/g, '');
+  if (raw instanceof Uint8Array || Buffer.isBuffer(raw)) return Buffer.from(raw).toString('utf8').replace(/^"|"$/g, '');
+  try { return Buffer.from(String(raw), 'base64').toString('utf8').replace(/^"|"$/g, ''); } catch { return String(raw); }
+}
+
+/**
+ * Parse event attributes into a key-value object.
+ * Handles both base64-encoded and plain string attributes.
+ */
+function parseAttributes(attributes) {
+  const result = {};
+  for (const attr of (attributes || [])) {
+    const key = decodeAttr(attr.key);
+    const value = decodeAttr(attr.value);
+    result[key] = value;
+  }
+  return result;
+}
+
+/**
+ * Search transaction events for a specific event type.
+ * @param {string} eventType - The event type URL to search for
+ * @param {Array} events - Transaction result events array
+ * @returns {object|null} The matched event or null
+ */
+export function searchEvent(eventType, events) {
+  if (!events || !Array.isArray(events)) return null;
+  for (const event of events) {
+    if (event.type === eventType) return event;
+  }
+  return null;
+}
+
+/**
+ * Search for ALL events matching a type.
+ * @param {string} eventType - The event type URL
+ * @param {Array} events - Transaction result events array
+ * @returns {Array} All matching events
+ */
+export function searchEvents(eventType, events) {
+  if (!events || !Array.isArray(events)) return [];
+  return events.filter(e => e.type === eventType);
+}
+
+// ─── Node Events ────────────────────────────────────────────────────────────
+
+/**
+ * sentinel.node.v3.EventCreateSession — emitted when a direct node session starts.
+ * Fields: session_id, acc_address, node_address, price (denom, base_value, quote_value), max_bytes, max_duration
+ */
+export const NodeEventCreateSession = {
+  type: 'sentinel.node.v3.EventCreateSession',
+
+  /**
+   * @param {object} event - Raw chain event
+   * @returns {{ sessionId: bigint, accAddress: string, nodeAddress: string, maxBytes: string, maxDuration: string, price: { denom: string, baseValue: string, quoteValue: string } }}
+   */
+  parse(event) {
+    const attrs = parseAttributes(event.attributes);
+    return {
+      sessionId: BigInt(attrs.session_id || attrs.SessionID || attrs.id || '0'),
+      accAddress: attrs.acc_address || attrs.address || '',
+      nodeAddress: attrs.node_address || '',
+      maxBytes: attrs.max_bytes || '0',
+      maxDuration: attrs.max_duration || '0',
+      price: {
+        denom: attrs.price_denom || attrs.denom || '',
+        baseValue: attrs.price_base_value || attrs.base_value || '0',
+        quoteValue: attrs.price_quote_value || attrs.quote_value || '0',
+      },
+    };
+  },
+
+  /** Type guard. */
+  is(event) { return event?.type === NodeEventCreateSession.type; },
+};
+
+/**
+ * sentinel.node.v3.EventPay — emitted when session payment is settled.
+ * Fields: session_id, acc_address, node_address, payment, staking_reward
+ */
+export const NodeEventPay = {
+  type: 'sentinel.node.v3.EventPay',
+
+  parse(event) {
+    const attrs = parseAttributes(event.attributes);
+    return {
+      sessionId: BigInt(attrs.session_id || '0'),
+      accAddress: attrs.acc_address || '',
+      nodeAddress: attrs.node_address || '',
+      payment: attrs.payment || '0',
+      stakingReward: attrs.staking_reward || '0',
+    };
+  },
+
+  is(event) { return event?.type === NodeEventPay.type; },
+};
+
+/**
+ * sentinel.node.v3.EventRefund — emitted when unused session deposit is refunded.
+ */
+export const NodeEventRefund = {
+  type: 'sentinel.node.v3.EventRefund',
+
+  parse(event) {
+    const attrs = parseAttributes(event.attributes);
+    return {
+      sessionId: BigInt(attrs.session_id || '0'),
+      accAddress: attrs.acc_address || '',
+      amount: attrs.amount || attrs.value || '0',
+    };
+  },
+
+  is(event) { return event?.type === NodeEventRefund.type; },
+};
+
+/**
+ * sentinel.node.v3.EventUpdateStatus — emitted when node status changes.
+ */
+export const NodeEventUpdateStatus = {
+  type: 'sentinel.node.v3.EventUpdateStatus',
+
+  parse(event) {
+    const attrs = parseAttributes(event.attributes);
+    return {
+      address: attrs.address || '',
+      status: parseInt(attrs.status || '0', 10),
+    };
+  },
+
+  is(event) { return event?.type === NodeEventUpdateStatus.type; },
+};
+
+// ─── Session Events ─────────────────────────────────────────────────────────
+
+/**
+ * sentinel.session.v3.EventEnd — emitted when any session ends.
+ */
+export const SessionEventEnd = {
+  type: 'sentinel.session.v3.EventEnd',
+
+  parse(event) {
+    const attrs = parseAttributes(event.attributes);
+    return {
+      sessionId: BigInt(attrs.session_id || attrs.id || '0'),
+      accAddress: attrs.acc_address || '',
+      nodeAddress: attrs.node_address || '',
+    };
+  },
+
+  is(event) { return event?.type === SessionEventEnd.type; },
+};
+
+/**
+ * sentinel.session.v3.EventUpdateDetails — emitted when session bandwidth is updated.
+ */
+export const SessionEventUpdateDetails = {
+  type: 'sentinel.session.v3.EventUpdateDetails',
+
+  parse(event) {
+    const attrs = parseAttributes(event.attributes);
+    return {
+      sessionId: BigInt(attrs.session_id || attrs.id || '0'),
+      accAddress: attrs.acc_address || '',
+      nodeAddress: attrs.node_address || '',
+      downloadBytes: attrs.download_bytes || '0',
+      uploadBytes: attrs.upload_bytes || '0',
+      duration: attrs.duration || '0',
+    };
+  },
+
+  is(event) { return event?.type === SessionEventUpdateDetails.type; },
+};
+
+// ─── Subscription Events ────────────────────────────────────────────────────
+
+/**
+ * sentinel.subscription.v3.EventCreate — emitted when a subscription is created.
+ */
+export const SubscriptionEventCreate = {
+  type: 'sentinel.subscription.v3.EventCreate',
+
+  parse(event) {
+    const attrs = parseAttributes(event.attributes);
+    return {
+      subscriptionId: BigInt(attrs.subscription_id || attrs.id || '0'),
+      planId: BigInt(attrs.plan_id || '0'),
+      accAddress: attrs.acc_address || '',
+      price: {
+        denom: attrs.price_denom || attrs.denom || '',
+        baseValue: attrs.price_base_value || '0',
+        quoteValue: attrs.price_quote_value || '0',
+      },
+    };
+  },
+
+  is(event) { return event?.type === SubscriptionEventCreate.type; },
+};
+
+/**
+ * sentinel.subscription.v3.EventCreateSession — emitted when a session starts via subscription.
+ */
+export const SubscriptionEventCreateSession = {
+  type: 'sentinel.subscription.v3.EventCreateSession',
+
+  parse(event) {
+    const attrs = parseAttributes(event.attributes);
+    return {
+      sessionId: BigInt(attrs.session_id || attrs.id || '0'),
+      subscriptionId: BigInt(attrs.subscription_id || '0'),
+      accAddress: attrs.acc_address || '',
+      nodeAddress: attrs.node_address || '',
+    };
+  },
+
+  is(event) { return event?.type === SubscriptionEventCreateSession.type; },
+};
+
+/**
+ * sentinel.subscription.v3.EventPay — emitted when subscription payment processed.
+ */
+export const SubscriptionEventPay = {
+  type: 'sentinel.subscription.v3.EventPay',
+
+  parse(event) {
+    const attrs = parseAttributes(event.attributes);
+    return {
+      subscriptionId: BigInt(attrs.subscription_id || attrs.id || '0'),
+      planId: BigInt(attrs.plan_id || '0'),
+      accAddress: attrs.acc_address || '',
+      provAddress: attrs.prov_address || '',
+      payment: attrs.payment || '0',
+      stakingReward: attrs.staking_reward || '0',
+    };
+  },
+
+  is(event) { return event?.type === SubscriptionEventPay.type; },
+};
+
+/**
+ * sentinel.subscription.v3.EventEnd — emitted when subscription ends.
+ */
+export const SubscriptionEventEnd = {
+  type: 'sentinel.subscription.v3.EventEnd',
+
+  parse(event) {
+    const attrs = parseAttributes(event.attributes);
+    return {
+      subscriptionId: BigInt(attrs.subscription_id || attrs.id || '0'),
+      planId: BigInt(attrs.plan_id || '0'),
+      accAddress: attrs.acc_address || '',
+    };
+  },
+
+  is(event) { return event?.type === SubscriptionEventEnd.type; },
+};
+
+// ─── Lease Events ───────────────────────────────────────────────────────────
+
+/**
+ * sentinel.lease.v1.EventCreate — emitted when a lease starts.
+ */
+export const LeaseEventCreate = {
+  type: 'sentinel.lease.v1.EventCreate',
+
+  parse(event) {
+    const attrs = parseAttributes(event.attributes);
+    return {
+      leaseId: BigInt(attrs.lease_id || attrs.id || '0'),
+      nodeAddress: attrs.node_address || '',
+      provAddress: attrs.prov_address || '',
+      maxHours: parseInt(attrs.max_hours || '0', 10),
+    };
+  },
+
+  is(event) { return event?.type === LeaseEventCreate.type; },
+};
+
+/**
+ * sentinel.lease.v1.EventEnd — emitted when a lease ends.
+ */
+export const LeaseEventEnd = {
+  type: 'sentinel.lease.v1.EventEnd',
+
+  parse(event) {
+    const attrs = parseAttributes(event.attributes);
+    return {
+      leaseId: BigInt(attrs.lease_id || attrs.id || '0'),
+      nodeAddress: attrs.node_address || '',
+      provAddress: attrs.prov_address || '',
+    };
+  },
+
+  is(event) { return event?.type === LeaseEventEnd.type; },
+};
+
+// ─── Utility: Extract Session ID (typed replacement for old extractSessionId) ──
+
+/**
+ * Extract session ID from a transaction result using typed event parsers.
+ * Checks both node.v3.EventCreateSession and subscription.v3.EventCreateSession.
+ *
+ * @param {{ events?: Array }} txResult - Transaction broadcast result
+ * @returns {bigint|null} Session ID or null
+ */
+export function extractSessionIdTyped(txResult) {
+  const events = txResult?.events || [];
+
+  // Try node direct session event
+  const nodeEvent = searchEvent(NodeEventCreateSession.type, events);
+  if (nodeEvent) {
+    const parsed = NodeEventCreateSession.parse(nodeEvent);
+    if (parsed.sessionId > 0n) return parsed.sessionId;
+  }
+
+  // Try subscription session event
+  const subEvent = searchEvent(SubscriptionEventCreateSession.type, events);
+  if (subEvent) {
+    const parsed = SubscriptionEventCreateSession.parse(subEvent);
+    if (parsed.sessionId > 0n) return parsed.sessionId;
+  }
+
+  // Fallback: scan all events for session_id attribute (handles edge cases)
+  for (const event of events) {
+    if (/session/i.test(event.type)) {
+      const attrs = parseAttributes(event.attributes);
+      const id = attrs.session_id || attrs.SessionID || attrs.id;
+      if (id) {
+        const parsed = BigInt(String(id).replace(/"/g, ''));
+        if (parsed > 0n) return parsed;
+      }
+    }
+  }
+
+  return null;
+}

package/protocol/handshake.js

@@ -0,0 +1,297 @@
+/**
+ * Sentinel v3 Node Handshake
+ *
+ * Handles the v3 node handshake protocol for both WireGuard and V2Ray nodes.
+ *
+ * v3 handshake request body:
+ * - data:      base64(JSON.stringify({public_key: "<base64_wg_pubkey>"}))  [WG]
+ *              base64(JSON.stringify({uuid: [byte_array]}))                [V2Ray]
+ * - id:        session ID (uint64 number)
+ * - pub_key:   "secp256k1:<base64_cosmos_pubkey>"
+ * - signature: base64(secp256k1_sign(SHA256(BigEndian8(id) + data_bytes)))
+ *
+ * Sources verified from:
+ *   github.com/sentinel-official/dvpn-node development branch (Dec 2025, v8.3.1)
+ *   github.com/sentinel-official/sentinel-go-sdk main branch
+ */
+
+import https from 'https';
+import net from 'net';
+import axios from 'axios';
+import { Secp256k1, sha256 } from '@cosmjs/crypto';
+import { secp256k1 as nobleSecp } from '@noble/curves/secp256k1.js';
+import { NodeError, ErrorCodes } from '../errors.js';
+
+// Legacy fallback — node-connect.js passes TOFU agent; this only used for direct calls
+const httpsAgent = new https.Agent({ rejectUnauthorized: false });
+
+// ─── IP/CIDR Validation ─────────────────────────────────────────────────────
+
+/**
+ * Validate an IP/CIDR string (e.g. "10.8.0.2/24" or "fd1d::2/128").
+ * Returns true if valid IPv4 or IPv6 CIDR, false otherwise.
+ */
+export function validateCIDR(cidr) {
+  if (typeof cidr !== 'string') return false;
+  const parts = cidr.split('/');
+  if (parts.length !== 2) return false;
+  const [ip, prefix] = parts;
+  const prefixNum = parseInt(prefix, 10);
+  if (isNaN(prefixNum) || prefixNum < 0) return false;
+  // IPv4
+  if (net.isIPv4(ip)) return prefixNum <= 32;
+  // IPv6
+  if (net.isIPv6(ip)) return prefixNum <= 128;
+  return false;
+}
+
+// ─── Node Status (v3: GET /) ──────────────────────────────────────────────────
+
+/**
+ * Fetch node info from v3 node API.
+ * Returns a normalised object compatible with the rest of the codebase.
+ */
+export async function nodeStatusV3(remoteUrl, agent) {
+  const stripped = remoteUrl.replace(/\/+$/, '').trim();
+  const url = stripped.startsWith('http') ? stripped : `https://${stripped}`;
+  const before = Date.now();
+  const res = await axios.get(url + '/', { httpsAgent: agent || httpsAgent, timeout: 12_000 });
+  const after = Date.now();
+  const r = res.data?.result;
+  if (!r) throw new NodeError(ErrorCodes.NODE_OFFLINE, 'No result in node status response', { remoteUrl });
+
+  // Detect server clock drift from the HTTP Date header.
+  // VMess AEAD auth fails if |client_time - server_time| > 120 seconds.
+  let clockDriftSec = null;
+  const dateHeader = res.headers?.['date'];
+  if (dateHeader) {
+    const serverTime = new Date(dateHeader).getTime();
+    if (!isNaN(serverTime)) {
+      const localMidpoint = before + (after - before) / 2;
+      clockDriftSec = Math.round((serverTime - localMidpoint) / 1000);
+    }
+  }
+
+  // Normalise to match the shape the rest of server.js expects
+  return {
+    address: r.address || '',
+    type: r.service_type === 'wireguard' ? 'wireguard' : 'v2ray',
+    moniker: r.moniker || '',
+    peers: r.peers || 0,
+    bandwidth: {
+      // downlink/uplink are bytes/s (string in v3)
+      download: parseInt(r.downlink || '0', 10),
+      upload: parseInt(r.uplink || '0', 10),
+    },
+    location: {
+      city: r.location?.city || '',
+      country: r.location?.country || '',
+      country_code: r.location?.country_code || '',
+      latitude: r.location?.latitude || 0,
+      longitude: r.location?.longitude || 0,
+    },
+    qos: { max_peers: r.qos?.max_peers || null },
+    clockDriftSec,
+    gigabyte_prices: [],  // not in v3 status; fetched from LCD
+    _raw: r,
+  };
+}
+
+// ─── Handshake Signing (shared between WG and V2Ray) ────────────────────────
+
+/**
+ * Build signed handshake body for v3 node protocol.
+ * @param {Buffer} dataBytes   - Peer request JSON bytes
+ * @param {bigint} sessionId   - Session ID (uint64)
+ * @param {Buffer} cosmosPrivKey - Raw secp256k1 private key (32 bytes)
+ * @returns {{ body: object }} - Signed request body ready for POST
+ */
+async function buildSignedBody(dataBytes, sessionId, cosmosPrivKey) {
+  // Build message: BigEndian uint64 (8 bytes) ++ data
+  const idBuf = Buffer.alloc(8);
+  idBuf.writeBigUInt64BE(BigInt(sessionId));
+  const msg = Buffer.concat([idBuf, dataBytes]);
+
+  // Sign: SHA256(msg) → secp256k1 compact 64-byte sig (r+s, no recovery byte) → base64
+  // IMPORTANT: Go's VerifySignature requires EXACTLY 64 bytes (len != 64 → false)
+  const msgHash = sha256(msg);
+  const sig = await Secp256k1.createSignature(msgHash, cosmosPrivKey);
+  // toFixedLength() returns 65 bytes (r+s+recovery) — take only first 64 (r+s)
+  const sigBytes = Buffer.from(sig.toFixedLength()).slice(0, 64);
+  const signature = sigBytes.toString('base64');
+
+  // Encode Cosmos public key (compressed, 33 bytes): "secp256k1:<base64>"
+  const compressedPubKey = nobleSecp.getPublicKey(cosmosPrivKey, true);
+  const pubKeyEncoded = 'secp256k1:' + Buffer.from(compressedPubKey).toString('base64');
+
+  const idNum = Number(sessionId);
+  if (!Number.isSafeInteger(idNum)) {
+    throw new NodeError(ErrorCodes.INVALID_OPTIONS, `Session ID ${sessionId} exceeds safe integer range (max ${Number.MAX_SAFE_INTEGER})`, { sessionId });
+  }
+
+  return {
+    body: {
+      data: dataBytes.toString('base64'),
+      id: idNum,
+      pub_key: pubKeyEncoded,
+      signature,
+    },
+  };
+}
+
+// ─── Chain-Lag Retry POST ───────────────────────────────────────────────────
+
+/**
+ * POST to node with chain-lag retry logic.
+ * After MsgStartSession, the node may not see the session on-chain yet.
+ * If the node returns "does not exist" or HTTP 404 code 5, wait and retry once.
+ */
+async function postWithChainLagRetry(url, body, agent, label = 'Node') {
+  const doPost = async () => {
+    let res;
+    try {
+      res = await axios.post(url, body, {
+        httpsAgent: agent || httpsAgent,
+        timeout: 90_000,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    } catch (err) {
+      // 409 "session already exists" — node already has our session and peer data.
+      // Extract the config from the error response instead of wasting tokens on a new session.
+      if (err.response?.status === 409 && err.response?.data?.result?.data) {
+        return err.response; // Treat as success — node accepted our session
+      }
+      const errData = err.response?.data;
+      const code = err.code || '';
+      const status = err.response?.status;
+      const detail = errData ? JSON.stringify(errData) : err.message;
+      const bodyStr = typeof errData === 'string' ? errData : JSON.stringify(errData || '');
+      // Detect corrupted node database (HTTP 500 with sqlite errors)
+      if (status === 500 && (bodyStr.includes('no such table') || bodyStr.includes('database is locked') || bodyStr.includes('disk I/O error'))) {
+        throw new NodeError('NODE_DATABASE_CORRUPT', `Node ${url} has a corrupted database: ${bodyStr.substring(0, 200)}`, { remoteUrl: url, status });
+      }
+      const isChainLag = bodyStr.includes('does not exist') ||
+        (status === 404 && errData?.code === 5);
+      if (isChainLag) return { _chainLag: true, detail };
+      throw new NodeError(ErrorCodes.NODE_OFFLINE, `${label} handshake failed (HTTP ${status}${code ? ', ' + code : ''}): ${detail}`, { status, code });
+    }
+    return res;
+  };
+
+  let res = await doPost();
+
+  // Retry once on chain lag
+  if (res?._chainLag) {
+    console.log('Session not yet visible on node — waiting 10s for chain propagation...');
+    await new Promise(r => setTimeout(r, 10_000));
+    res = await doPost();
+    if (res?._chainLag) {
+      throw new NodeError(ErrorCodes.NODE_OFFLINE, `${label} handshake failed: session does not exist on node after retry (chain propagation delay). Detail: ${res.detail}`, { chainLag: true });
+    }
+  }
+
+  return res;
+}
+
+// ─── v3 WireGuard Handshake (POST /) ────────────────────────────────────────
+
+/**
+ * Perform v3 node handshake for WireGuard.
+ * @param {string}     remoteUrl     - Node's HTTPS base URL
+ * @param {bigint}     sessionId     - Session ID (uint64)
+ * @param {Buffer}     cosmosPrivKey - Raw secp256k1 private key bytes (32 bytes)
+ * @param {Buffer}     wgPublicKey   - WireGuard public key (32 bytes)
+ * @returns {{ assignedAddrs: string[], serverPubKey: string, serverEndpoints: string[] }}
+ */
+export async function initHandshakeV3(remoteUrl, sessionId, cosmosPrivKey, wgPublicKey, agent) {
+  // 1. Build peer request data
+  const peerRequest = { public_key: wgPublicKey.toString('base64') };
+  const dataBytes = Buffer.from(JSON.stringify(peerRequest));
+
+  // 2. Sign and build body
+  const { body } = await buildSignedBody(dataBytes, sessionId, cosmosPrivKey);
+
+  // 3. POST with chain-lag retry
+  const url = remoteUrl.replace(/\/+$/, '') + '/';
+  const res = await postWithChainLagRetry(url, body, agent, 'Node');
+
+  const result = res.data?.result;
+  if (!result) {
+    const errInfo = res.data?.error;
+    throw new NodeError(ErrorCodes.NODE_OFFLINE, `Node handshake error: ${JSON.stringify(errInfo || res.data)}`, { response: errInfo || res.data });
+  }
+
+  // 4. Parse AddPeerResponse from result.data (base64-encoded JSON bytes)
+  const addPeerData = Buffer.from(result.data, 'base64').toString('utf8');
+  const addPeerResp = JSON.parse(addPeerData);
+
+  // result.addrs = node's WireGuard listening addresses (["IP:PORT", ...])
+  // addPeerResp.addrs = our assigned IPs (["10.x.x.x/24", ...])
+  // addPeerResp.metadata = [{port, public_key}, ...]
+
+  const metadata = (addPeerResp.metadata || [])[0] || {};
+  const serverPubKeyBase64 = metadata.public_key || '';
+  const serverPort = parseInt(metadata.port, 10) || 51820;
+
+  // Validate handshake response — garbage data from node → clear error instead of opaque WG failure
+  if (!serverPubKeyBase64) throw new NodeError(ErrorCodes.NODE_OFFLINE, 'Handshake failed: node returned empty WireGuard public key');
+  if (serverPort < 1 || serverPort > 65535) throw new NodeError(ErrorCodes.NODE_OFFLINE, `Handshake failed: invalid port ${serverPort} from node`, { serverPort });
+
+  const assignedAddrs = addPeerResp.addrs || [];
+  if (assignedAddrs.length === 0) throw new NodeError(ErrorCodes.NODE_OFFLINE, 'Handshake failed: node returned no assigned addresses');
+  for (const addr of assignedAddrs) {
+    if (!validateCIDR(addr)) {
+      throw new NodeError(ErrorCodes.INVALID_ASSIGNED_IP, `Handshake failed: node returned invalid IP/CIDR "${addr}"`, { assignedAddrs });
+    }
+  }
+
+  // Node's WireGuard endpoint: use first entry of result.addrs
+  // If it doesn't include a port, append the metadata port
+  const rawEndpoint = (result.addrs || [])[0] || '';
+  if (!rawEndpoint) throw new NodeError(ErrorCodes.NODE_OFFLINE, 'Handshake failed: node returned no WireGuard endpoint addresses');
+  const serverEndpoint = rawEndpoint.includes(':')
+    ? rawEndpoint
+    : `${rawEndpoint}:${serverPort}`;
+
+  return {
+    assignedAddrs,                              // our IPs e.g. ["10.8.0.2/24"]
+    serverPubKey: serverPubKeyBase64,         // server WG pub key (base64)
+    serverEndpoint,                             // "IP:PORT" for WireGuard Endpoint
+    serverEndpoints: result.addrs || [],
+    rawAddPeerResp: addPeerResp,
+  };
+}
+
+// ─── v3 V2Ray Handshake (POST /) ────────────────────────────────────────────
+
+/**
+ * Perform v3 V2Ray handshake.
+ * Returns the V2Ray client config (JSON string in result.data).
+ */
+export async function initHandshakeV3V2Ray(remoteUrl, sessionId, cosmosPrivKey, uuid, agent) {
+  const hex = uuid.replace(/-/g, '');
+  const uuidBytes = [];
+  for (let i = 0; i < hex.length; i += 2) {
+    uuidBytes.push(parseInt(hex.substring(i, i + 2), 16));
+  }
+  const peerRequest = { uuid: uuidBytes };
+  const dataBytes = Buffer.from(JSON.stringify(peerRequest));
+
+  const { body } = await buildSignedBody(dataBytes, sessionId, cosmosPrivKey);
+
+  const url = remoteUrl.replace(/\/+$/, '') + '/';
+  const res = await postWithChainLagRetry(url, body, agent, 'V2Ray');
+
+  const result = res.data?.result;
+  if (!result) {
+    throw new NodeError(ErrorCodes.NODE_OFFLINE, `V2Ray handshake error: ${JSON.stringify(res.data?.error || res.data)}`, { response: res.data?.error || res.data });
+  }
+
+  // result.data is base64-encoded V2Ray client config JSON
+  const v2rayConfig = Buffer.from(result.data, 'base64').toString('utf8');
+
+  return {
+    config: v2rayConfig,
+    serverEndpoints: result.addrs || [],
+  };
+}

package/protocol/index.js

@@ -0,0 +1,15 @@
+// Protocol — Handshakes, Config Builders, Protobuf Encoders
+export {
+  nodeStatusV3, generateWgKeyPair, initHandshakeV3, initHandshakeV3V2Ray,
+  writeWgConfig, buildV2RayClientConfig,
+  generateV2RayUUID, extractSessionId, waitForPort,
+  encodePrice, encodeMsgStartSession, encodeMsgStartSubscription, encodeMsgSubStartSession,
+  encodeVarint, protoString, protoInt64, protoEmbedded, decToScaledInt,
+} from './v3.js';
+
+export {
+  encodeMsgRegisterProvider, encodeMsgUpdateProviderDetails, encodeMsgUpdateProviderStatus,
+  encodeMsgCreatePlan, encodeMsgUpdatePlanStatus, encodeMsgLinkNode, encodeMsgUnlinkNode,
+  encodeMsgPlanStartSession, encodeMsgStartLease, encodeMsgEndLease,
+  encodeDuration, protoUint64, protoBool,
+} from './plans.js';