@neus/sdk 1.0.0 → 1.0.1

package/cjs/utils.cjs

@@ -0,0 +1,620 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// utils.js
+var utils_exports = {};
+__export(utils_exports, {
+  NEUS_CONSTANTS: () => NEUS_CONSTANTS,
+  StatusPoller: () => StatusPoller,
+  buildVerificationRequest: () => buildVerificationRequest,
+  computeContentHash: () => computeContentHash,
+  constructVerificationMessage: () => constructVerificationMessage,
+  createVerificationData: () => createVerificationData,
+  delay: () => delay,
+  deriveDid: () => deriveDid,
+  formatTimestamp: () => formatTimestamp,
+  formatVerificationStatus: () => formatVerificationStatus,
+  isFailureStatus: () => isFailureStatus,
+  isSuccessStatus: () => isSuccessStatus,
+  isSupportedChain: () => isSupportedChain,
+  isTerminalStatus: () => isTerminalStatus,
+  normalizeAddress: () => normalizeAddress,
+  validateQHash: () => validateQHash,
+  validateSignatureComponents: () => validateSignatureComponents,
+  validateTimestamp: () => validateTimestamp,
+  validateVerifierPayload: () => validateVerifierPayload,
+  validateWalletAddress: () => validateWalletAddress,
+  withRetry: () => withRetry
+});
+module.exports = __toCommonJS(utils_exports);
+
+// errors.js
+var SDKError = class _SDKError extends Error {
+  constructor(message, code = "SDK_ERROR", details = {}) {
+    super(message);
+    this.name = "SDKError";
+    this.code = code;
+    this.details = details;
+    this.timestamp = Date.now();
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _SDKError);
+    }
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      details: this.details,
+      timestamp: this.timestamp
+    };
+  }
+};
+
+// utils.js
+function deterministicStringify(obj) {
+  if (obj === null || obj === void 0) {
+    return JSON.stringify(obj);
+  }
+  if (typeof obj !== "object") {
+    return JSON.stringify(obj);
+  }
+  if (Array.isArray(obj)) {
+    return "[" + obj.map((item) => deterministicStringify(item)).join(",") + "]";
+  }
+  const sortedKeys = Object.keys(obj).sort();
+  const pairs = sortedKeys.map(
+    (key) => JSON.stringify(key) + ":" + deterministicStringify(obj[key])
+  );
+  return "{" + pairs.join(",") + "}";
+}
+function constructVerificationMessage({ walletAddress, signedTimestamp, data, verifierIds, chainId, chain }) {
+  if (!walletAddress || typeof walletAddress !== "string") {
+    throw new SDKError("walletAddress is required and must be a string", "INVALID_WALLET_ADDRESS");
+  }
+  if (!signedTimestamp || typeof signedTimestamp !== "number") {
+    throw new SDKError("signedTimestamp is required and must be a number", "INVALID_TIMESTAMP");
+  }
+  if (!data || typeof data !== "object") {
+    throw new SDKError("data is required and must be an object", "INVALID_DATA");
+  }
+  if (!Array.isArray(verifierIds) || verifierIds.length === 0) {
+    throw new SDKError("verifierIds is required and must be a non-empty array", "INVALID_VERIFIER_IDS");
+  }
+  const chainContext = typeof chain === "string" && chain.length > 0 ? chain : chainId;
+  if (!chainContext) {
+    throw new SDKError("chainId is required (or provide chain for preview mode)", "INVALID_CHAIN_CONTEXT");
+  }
+  if (chainContext === chainId && typeof chainId !== "number") {
+    throw new SDKError("chainId must be a number when provided", "INVALID_CHAIN_ID");
+  }
+  if (chainContext === chain && (typeof chain !== "string" || !chain.includes(":"))) {
+    throw new SDKError('chain must be a "namespace:reference" string', "INVALID_CHAIN");
+  }
+  const namespace = typeof chain === "string" && chain.includes(":") ? chain.split(":")[0] : "eip155";
+  const normalizedWalletAddress = namespace === "eip155" ? walletAddress.toLowerCase() : walletAddress;
+  const dataString = deterministicStringify(data);
+  const messageComponents = [
+    "NEUS Verification Request",
+    `Wallet: ${normalizedWalletAddress}`,
+    `Chain: ${chainContext}`,
+    `Verifiers: ${verifierIds.join(",")}`,
+    `Data: ${dataString}`,
+    `Timestamp: ${signedTimestamp}`
+  ];
+  return messageComponents.join("\n");
+}
+function validateWalletAddress(address) {
+  if (!address || typeof address !== "string") {
+    return false;
+  }
+  return /^0x[a-fA-F0-9]{40}$/.test(address);
+}
+function validateTimestamp(timestamp, maxAgeMs = 5 * 60 * 1e3) {
+  if (!timestamp || typeof timestamp !== "number") {
+    return false;
+  }
+  const now = Date.now();
+  const age = now - timestamp;
+  return age >= 0 && age <= maxAgeMs;
+}
+function createVerificationData(content, owner, reference = null) {
+  const stableRefId = (value) => {
+    const str = typeof value === "string" ? value : JSON.stringify(value);
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      hash = (hash << 5) - hash + str.charCodeAt(i);
+      hash |= 0;
+    }
+    const hex = Math.abs(hash).toString(16).padStart(8, "0");
+    return `ref-id:${hex}:${str.length}`;
+  };
+  return {
+    content,
+    owner: owner.toLowerCase(),
+    reference: reference || {
+      // Must be a valid backend enum value; 'content' is not supported.
+      type: "other",
+      id: stableRefId(content)
+    }
+  };
+}
+function deriveDid(address, chainIdOrChain) {
+  if (!address || typeof address !== "string") {
+    throw new SDKError("deriveDid: address is required", "INVALID_ARGUMENT");
+  }
+  const chainContext = chainIdOrChain || NEUS_CONSTANTS.HUB_CHAIN_ID;
+  const isCAIP = typeof chainContext === "string" && chainContext.includes(":");
+  if (isCAIP) {
+    const [namespace, segment] = chainContext.split(":");
+    const normalized = namespace === "eip155" ? address.toLowerCase() : address;
+    return `did:pkh:${namespace}:${segment}:${normalized}`;
+  } else {
+    if (typeof chainContext !== "number") {
+      throw new SDKError("deriveDid: chainId (number) or chain (namespace:reference string) is required", "INVALID_ARGUMENT");
+    }
+    return `did:pkh:eip155:${chainContext}:${address.toLowerCase()}`;
+  }
+}
+function isTerminalStatus(status) {
+  if (!status || typeof status !== "string")
+    return false;
+  const successStates = [
+    "verified",
+    "verified_no_verifiers",
+    "verified_crosschain_propagated",
+    "partially_verified",
+    "verified_propagation_failed"
+  ];
+  const failureStates = [
+    "rejected",
+    "rejected_verifier_failure",
+    "rejected_zk_initiation_failure",
+    "error_processing_exception",
+    "error_initialization",
+    "error_storage_unavailable",
+    "error_storage_query",
+    "not_found"
+  ];
+  return successStates.includes(status) || failureStates.includes(status);
+}
+function isSuccessStatus(status) {
+  if (!status || typeof status !== "string")
+    return false;
+  const successStates = [
+    "verified",
+    "verified_no_verifiers",
+    "verified_crosschain_propagated",
+    "partially_verified",
+    "verified_propagation_failed"
+  ];
+  return successStates.includes(status);
+}
+function isFailureStatus(status) {
+  if (!status || typeof status !== "string")
+    return false;
+  const failureStates = [
+    "rejected",
+    "rejected_verifier_failure",
+    "rejected_zk_initiation_failure",
+    "error_processing_exception",
+    "error_initialization",
+    "error_storage_unavailable",
+    "error_storage_query",
+    "not_found"
+  ];
+  return failureStates.includes(status);
+}
+function formatVerificationStatus(status) {
+  const statusMap = {
+    "processing_verifiers": {
+      label: "Processing",
+      description: "Verifiers are being executed",
+      category: "processing",
+      color: "blue"
+    },
+    "processing_zk_proofs": {
+      label: "Generating ZK Proofs",
+      description: "Zero-knowledge proofs are being generated",
+      category: "processing",
+      color: "blue"
+    },
+    "verified": {
+      label: "Verified",
+      description: "Verification completed successfully",
+      category: "success",
+      color: "green"
+    },
+    "verified_crosschain_initiated": {
+      label: "Cross-chain Initiated",
+      description: "Verification successful, cross-chain propagation started",
+      category: "processing",
+      color: "blue"
+    },
+    "verified_crosschain_propagating": {
+      label: "Cross-chain Propagating",
+      description: "Verification successful, transactions propagating to spoke chains",
+      category: "processing",
+      color: "blue"
+    },
+    "verified_crosschain_propagated": {
+      label: "Fully Propagated",
+      description: "Verification completed and propagated to all target chains",
+      category: "success",
+      color: "green"
+    },
+    "verified_no_verifiers": {
+      label: "Verified (No Verifiers)",
+      description: "Verification completed without specific verifiers",
+      category: "success",
+      color: "green"
+    },
+    "verified_propagation_failed": {
+      label: "Propagation Failed",
+      description: "Verification successful but cross-chain propagation failed",
+      category: "warning",
+      color: "orange"
+    },
+    "partially_verified": {
+      label: "Partially Verified",
+      description: "Some verifiers succeeded, others failed",
+      category: "warning",
+      color: "orange"
+    },
+    "rejected": {
+      label: "Rejected",
+      description: "Verification failed",
+      category: "error",
+      color: "red"
+    },
+    "rejected_verifier_failure": {
+      label: "Verifier Failed",
+      description: "One or more verifiers failed",
+      category: "error",
+      color: "red"
+    },
+    "rejected_zk_initiation_failure": {
+      label: "ZK Initiation Failed",
+      description: "Zero-knowledge proof generation failed to start",
+      category: "error",
+      color: "red"
+    },
+    "error_processing_exception": {
+      label: "Processing Error",
+      description: "An error occurred during verification processing",
+      category: "error",
+      color: "red"
+    },
+    "error_initialization": {
+      label: "Initialization Error",
+      description: "Failed to initialize verification",
+      category: "error",
+      color: "red"
+    },
+    "not_found": {
+      label: "Not Found",
+      description: "Verification record not found",
+      category: "error",
+      color: "red"
+    }
+  };
+  return statusMap[status] || {
+    label: status?.replace(/_/g, " ").replace(/\b\w/g, (l) => l.toUpperCase()) || "Unknown",
+    description: "Unknown status",
+    category: "unknown",
+    color: "gray"
+  };
+}
+async function computeContentHash(input) {
+  try {
+    const ethers = await import("ethers");
+    const toBytes = typeof input === "string" ? ethers.toUtf8Bytes(input) : input;
+    return ethers.keccak256(toBytes);
+  } catch {
+    throw new SDKError('computeContentHash requires peer dependency "ethers" >= 6.0.0', "MISSING_PEER_DEP");
+  }
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var StatusPoller = class {
+  constructor(client, qHash, options = {}) {
+    this.client = client;
+    this.qHash = qHash;
+    this.options = {
+      interval: 2e3,
+      // 2 seconds
+      maxAttempts: 150,
+      // 5 minutes total
+      exponentialBackoff: true,
+      maxInterval: 1e4,
+      // 10 seconds max
+      ...options
+    };
+    this.attempt = 0;
+    this.currentInterval = this.options.interval;
+  }
+  async poll() {
+    return new Promise((resolve, reject) => {
+      const pollAttempt = async () => {
+        try {
+          this.attempt++;
+          const response = await this.client.getStatus(this.qHash);
+          if (isTerminalStatus(response.status)) {
+            resolve(response);
+            return;
+          }
+          if (this.attempt >= this.options.maxAttempts) {
+            reject(new SDKError(
+              "Verification polling timeout",
+              "POLLING_TIMEOUT"
+            ));
+            return;
+          }
+          if (this.options.exponentialBackoff) {
+            this.currentInterval = Math.min(
+              this.currentInterval * 1.5,
+              this.options.maxInterval
+            );
+          }
+          setTimeout(pollAttempt, this.currentInterval);
+        } catch (error) {
+          reject(new SDKError(
+            `Polling failed: ${error.message}`,
+            "POLLING_ERROR"
+          ));
+        }
+      };
+      pollAttempt();
+    });
+  }
+};
+var NEUS_CONSTANTS = {
+  // Hub chain (where all verifications occur)
+  HUB_CHAIN_ID: 84532,
+  // Supported target chains for cross-chain propagation
+  TESTNET_CHAINS: [
+    11155111,
+    // Ethereum Sepolia
+    11155420,
+    // Optimism Sepolia
+    421614,
+    // Arbitrum Sepolia
+    80002
+    // Polygon Amoy
+  ],
+  // API endpoints
+  API_BASE_URL: "https://api.neus.network",
+  API_VERSION: "v1",
+  // Timeouts and limits
+  SIGNATURE_MAX_AGE_MS: 5 * 60 * 1e3,
+  // 5 minutes
+  REQUEST_TIMEOUT_MS: 30 * 1e3,
+  // 30 seconds
+  // Default verifier set for quick starts
+  DEFAULT_VERIFIERS: [
+    "ownership-basic",
+    "nft-ownership",
+    "token-holding"
+  ]
+};
+function validateQHash(qHash) {
+  return typeof qHash === "string" && /^0x[a-fA-F0-9]{64}$/.test(qHash);
+}
+function formatTimestamp(timestamp) {
+  return new Date(timestamp).toLocaleString();
+}
+function isSupportedChain(chainId) {
+  return NEUS_CONSTANTS.TESTNET_CHAINS.includes(chainId) || chainId === NEUS_CONSTANTS.HUB_CHAIN_ID;
+}
+function normalizeAddress(address) {
+  if (!validateWalletAddress(address)) {
+    throw new SDKError("Invalid wallet address format", "INVALID_ADDRESS");
+  }
+  return address.toLowerCase();
+}
+function validateVerifierPayload(verifierId, data) {
+  const result = { valid: true, missing: [], warnings: [] };
+  if (!verifierId || typeof verifierId !== "string") {
+    return { valid: false, error: "verifierId is required and must be a string" };
+  }
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    return { valid: false, error: "data must be a non-null object" };
+  }
+  const id = verifierId.replace(/@\d+$/, "");
+  if (id === "nft-ownership") {
+    ["contractAddress", "tokenId", "chainId"].forEach((key) => {
+      if (!(key in data))
+        result.missing.push(key);
+    });
+    if (!("ownerAddress" in data)) {
+      result.warnings.push("ownerAddress omitted (most deployments default to the signed walletAddress)");
+    }
+  } else if (id === "token-holding") {
+    ["contractAddress", "minBalance", "chainId"].forEach((key) => {
+      if (!(key in data))
+        result.missing.push(key);
+    });
+    if (!("ownerAddress" in data)) {
+      result.warnings.push("ownerAddress omitted (most deployments default to the signed walletAddress)");
+    }
+  } else if (id === "ownership-basic") {
+    ["content"].forEach((key) => {
+      if (!(key in data))
+        result.missing.push(key);
+    });
+  }
+  if (result.missing.length > 0) {
+    result.valid = false;
+    result.error = `Missing required fields: ${result.missing.join(", ")}`;
+  }
+  return result;
+}
+function buildVerificationRequest({
+  verifierIds,
+  data,
+  walletAddress,
+  chainId = NEUS_CONSTANTS.HUB_CHAIN_ID,
+  options = void 0,
+  signedTimestamp = Date.now()
+}) {
+  if (!Array.isArray(verifierIds) || verifierIds.length === 0) {
+    throw new SDKError("verifierIds must be a non-empty array", "INVALID_ARGUMENT");
+  }
+  if (!validateWalletAddress(walletAddress)) {
+    throw new SDKError("walletAddress must be a valid 0x address", "INVALID_ARGUMENT");
+  }
+  if (!data || typeof data !== "object") {
+    throw new SDKError("data must be a non-null object", "INVALID_ARGUMENT");
+  }
+  if (typeof chainId !== "number") {
+    throw new SDKError("chainId must be a number", "INVALID_ARGUMENT");
+  }
+  const message = constructVerificationMessage({
+    walletAddress,
+    signedTimestamp,
+    data,
+    verifierIds,
+    chainId
+  });
+  const request = {
+    verifierIds,
+    data,
+    walletAddress,
+    signedTimestamp,
+    chainId,
+    ...options ? { options } : {}
+  };
+  return { message, request };
+}
+async function withRetry(fn, options = {}) {
+  const {
+    maxAttempts = 3,
+    baseDelay = 1e3,
+    maxDelay = 1e4,
+    backoffFactor = 2
+  } = options;
+  let lastError;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt === maxAttempts)
+        break;
+      const delayMs = Math.min(
+        baseDelay * Math.pow(backoffFactor, attempt - 1),
+        maxDelay
+      );
+      await delay(delayMs);
+    }
+  }
+  throw lastError;
+}
+function validateSignatureComponents({ walletAddress, signature, signedTimestamp, data, verifierIds, chainId }) {
+  const result = {
+    valid: true,
+    errors: [],
+    warnings: [],
+    debugInfo: {}
+  };
+  if (!validateWalletAddress(walletAddress)) {
+    result.valid = false;
+    result.errors.push("Invalid wallet address format - must be 0x + 40 hex characters");
+  } else {
+    result.debugInfo.normalizedAddress = walletAddress.toLowerCase();
+    if (walletAddress !== walletAddress.toLowerCase()) {
+      result.warnings.push("Wallet address should be lowercase for consistency");
+    }
+  }
+  if (!signature || typeof signature !== "string") {
+    result.valid = false;
+    result.errors.push("Signature is required and must be a string");
+  } else if (!/^0x[a-fA-F0-9]{130}$/.test(signature)) {
+    result.valid = false;
+    result.errors.push("Invalid signature format - must be 0x + 130 hex characters (65 bytes)");
+  }
+  if (!validateTimestamp(signedTimestamp)) {
+    result.valid = false;
+    result.errors.push("Invalid or expired timestamp - must be within 5 minutes");
+  } else {
+    result.debugInfo.timestampAge = Date.now() - signedTimestamp;
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    result.valid = false;
+    result.errors.push("Data must be a non-null object");
+  } else {
+    result.debugInfo.dataString = deterministicStringify(data);
+  }
+  if (!Array.isArray(verifierIds) || verifierIds.length === 0) {
+    result.valid = false;
+    result.errors.push("VerifierIds must be a non-empty array");
+  }
+  if (typeof chainId !== "number") {
+    result.valid = false;
+    result.errors.push("ChainId must be a number");
+  }
+  if (result.valid || result.errors.length < 3) {
+    try {
+      result.debugInfo.messageToSign = constructVerificationMessage({
+        walletAddress: walletAddress?.toLowerCase() || walletAddress,
+        signedTimestamp,
+        data,
+        verifierIds,
+        chainId
+      });
+    } catch (error) {
+      result.errors.push(`Failed to construct message: ${error.message}`);
+    }
+  }
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NEUS_CONSTANTS,
+  StatusPoller,
+  buildVerificationRequest,
+  computeContentHash,
+  constructVerificationMessage,
+  createVerificationData,
+  delay,
+  deriveDid,
+  formatTimestamp,
+  formatVerificationStatus,
+  isFailureStatus,
+  isSuccessStatus,
+  isSupportedChain,
+  isTerminalStatus,
+  normalizeAddress,
+  validateQHash,
+  validateSignatureComponents,
+  validateTimestamp,
+  validateVerifierPayload,
+  validateWalletAddress,
+  withRetry
+});