@t402/tron 2.3.1 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t402/tron",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
   "types": "./dist/cjs/index.d.ts",
@@ -19,12 +19,12 @@
   "description": "t402 Payment Protocol TRON Implementation",
   "devDependencies": {
     "@eslint/js": "^9.24.0",
-    "@types/node": "^22.13.4",
+    "@types/node": "^25.2.0",
     "@typescript-eslint/eslint-plugin": "^8.29.1",
     "@typescript-eslint/parser": "^8.29.1",
     "eslint": "^9.24.0",
     "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-jsdoc": "^50.6.9",
+    "eslint-plugin-jsdoc": "^62.5.0",
     "eslint-plugin-prettier": "^5.2.6",
     "glob": "^13.0.0",
     "prettier": "3.5.2",
@@ -36,7 +36,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@t402/core": "2.3.1"
+    "@t402/core": "2.4.0"
   },
   "exports": {
     ".": {
@@ -78,6 +78,16 @@
         "types": "./dist/cjs/exact/facilitator/index.d.ts",
         "default": "./dist/cjs/exact/facilitator/index.js"
       }
+    },
+    "./upto": {
+      "import": {
+        "types": "./dist/esm/upto/index.d.mts",
+        "default": "./dist/esm/upto/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/upto/index.d.ts",
+        "default": "./dist/cjs/upto/index.js"
+      }
     }
   },
   "files": [

package/dist/esm/chunk-MTL3FNSQ.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/constants.ts","../../src/utils.ts"],"sourcesContent":["/**\n * TRON Network Constants\n *\n * Network identifiers, endpoints, and configuration for TRON blockchain.\n */\n\n// =============================================================================\n// Network Identifiers (CAIP-2 Format)\n// =============================================================================\n\n/** TRON Mainnet CAIP-2 identifier */\nexport const TRON_MAINNET_CAIP2 = 'tron:mainnet'\n\n/** TRON Nile Testnet CAIP-2 identifier */\nexport const TRON_NILE_CAIP2 = 'tron:nile'\n\n/** TRON Shasta Testnet CAIP-2 identifier */\nexport const TRON_SHASTA_CAIP2 = 'tron:shasta'\n\n/** All supported TRON networks */\nexport const TRON_NETWORKS = [TRON_MAINNET_CAIP2, TRON_NILE_CAIP2, TRON_SHASTA_CAIP2] as const\n\n/** TRON network type */\nexport type TronNetwork = (typeof TRON_NETWORKS)[number]\n\n// =============================================================================\n// RPC Endpoints\n// =============================================================================\n\n/** TRON Mainnet API endpoint (TronGrid) */\nexport const TRON_MAINNET_ENDPOINT = 'https://api.trongrid.io'\n\n/** TRON Nile Testnet API endpoint */\nexport const TRON_NILE_ENDPOINT = 'https://api.nileex.io'\n\n/** TRON Shasta Testnet API endpoint */\nexport const TRON_SHASTA_ENDPOINT = 'https://api.shasta.trongrid.io'\n\n/** Network to endpoint mapping */\nexport const NETWORK_ENDPOINTS: Record<string, string> = {\n  [TRON_MAINNET_CAIP2]: TRON_MAINNET_ENDPOINT,\n  [TRON_NILE_CAIP2]: TRON_NILE_ENDPOINT,\n  [TRON_SHASTA_CAIP2]: TRON_SHASTA_ENDPOINT,\n}\n\n// =============================================================================\n// TRC20 Contract Operations\n// =============================================================================\n\n/** TRC20 transfer function selector (transfer(address,uint256)) */\nexport const TRC20_TRANSFER_SELECTOR = 'a9059cbb'\n\n/** TRC20 approve function selector (approve(address,uint256)) */\nexport const TRC20_APPROVE_SELECTOR = '095ea7b3'\n\n/** TRC20 balanceOf function selector (balanceOf(address)) */\nexport const TRC20_BALANCE_OF_SELECTOR = '70a08231'\n\n// =============================================================================\n// Gas and Fee Constants\n// =============================================================================\n\n/** Default fee limit for TRC20 transfers (in SUN, 1 TRX = 1,000,000 SUN) */\nexport const DEFAULT_FEE_LIMIT = 100_000_000 // 100 TRX\n\n/** Minimum fee limit for TRC20 transfers */\nexport const MIN_FEE_LIMIT = 10_000_000 // 10 TRX\n\n/** Maximum fee limit for TRC20 transfers */\nexport const MAX_FEE_LIMIT = 1_000_000_000 // 1000 TRX\n\n/** SUN per TRX (1 TRX = 1,000,000 SUN) */\nexport const SUN_PER_TRX = 1_000_000\n\n// =============================================================================\n// Scheme Constants\n// =============================================================================\n\n/** Payment scheme identifier */\nexport const SCHEME_EXACT = 'exact'\n\n/** Default transaction validity duration in seconds (1 hour) */\nexport const DEFAULT_VALIDITY_DURATION = 3600\n\n/** Minimum validity buffer for verification (30 seconds) */\nexport const MIN_VALIDITY_BUFFER = 30\n\n// =============================================================================\n// Address Constants\n// =============================================================================\n\n/** TRON address prefix (base58check) */\nexport const TRON_ADDRESS_PREFIX = 'T'\n\n/** TRON address length (base58check format) */\nexport const TRON_ADDRESS_LENGTH = 34\n\n/** TRON address hex prefix (0x41 in decimal = 65) */\nexport const TRON_ADDRESS_HEX_PREFIX = 0x41\n\n// =============================================================================\n// USDT Contract Addresses\n// =============================================================================\n\n/** USDT TRC20 contract addresses by network */\nexport const USDT_ADDRESSES: Record<string, string> = {\n  [TRON_MAINNET_CAIP2]: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',\n  [TRON_NILE_CAIP2]: 'TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf',\n  [TRON_SHASTA_CAIP2]: 'TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs',\n}\n\n// =============================================================================\n// Token Decimals\n// =============================================================================\n\n/** Default decimals for USDT */\nexport const DEFAULT_USDT_DECIMALS = 6\n\n/** Default decimals for TRX */\nexport const DEFAULT_TRX_DECIMALS = 6\n","/**\n * TRON Utility Functions\n *\n * Address validation, amount conversion, and network utilities.\n */\n\nimport {\n  TRON_NETWORKS,\n  TRON_ADDRESS_LENGTH,\n  TRON_ADDRESS_PREFIX,\n  NETWORK_ENDPOINTS,\n  DEFAULT_USDT_DECIMALS,\n} from './constants.js'\nimport type { TronNetwork } from './constants.js'\n\n// =============================================================================\n// Network Utilities\n// =============================================================================\n\n/**\n * Normalize network identifier to CAIP-2 format\n *\n * @param network - Network identifier (e.g., \"tron:mainnet\", \"mainnet\")\n * @returns Normalized CAIP-2 identifier\n * @throws Error if network is not supported\n */\nexport function normalizeNetwork(network: string): TronNetwork {\n  // Already in correct format\n  if (TRON_NETWORKS.includes(network as TronNetwork)) {\n    return network as TronNetwork\n  }\n\n  // Handle shorthand formats\n  const lower = network.toLowerCase()\n  if (lower === 'mainnet' || lower === 'tron') {\n    return 'tron:mainnet'\n  }\n  if (lower === 'nile' || lower === 'tron-nile') {\n    return 'tron:nile'\n  }\n  if (lower === 'shasta' || lower === 'tron-shasta') {\n    return 'tron:shasta'\n  }\n\n  throw new Error(`Unsupported TRON network: ${network}`)\n}\n\n/**\n * Get RPC endpoint for a network\n *\n * @param network - CAIP-2 network identifier\n * @returns RPC endpoint URL\n * @throws Error if network is not supported\n */\nexport function getEndpoint(network: string): string {\n  const normalized = normalizeNetwork(network)\n  const endpoint = NETWORK_ENDPOINTS[normalized]\n  if (!endpoint) {\n    throw new Error(`No endpoint configured for network: ${network}`)\n  }\n  return endpoint\n}\n\n/**\n * Check if a network identifier is a TRON network\n *\n * @param network - Network identifier\n * @returns true if TRON network\n */\nexport function isTronNetwork(network: string): boolean {\n  try {\n    normalizeNetwork(network)\n    return true\n  } catch {\n    return false\n  }\n}\n\n// =============================================================================\n// Address Utilities\n// =============================================================================\n\n/**\n * Base58 alphabet for TRON addresses\n */\nconst BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'\n\n/**\n * Validate a TRON address\n *\n * TRON addresses are:\n * - Base58check encoded\n * - 34 characters long\n * - Start with 'T' (mainnet) or 'A'/'4' (testnet - rare)\n *\n * @param address - Address to validate\n * @returns true if valid TRON address\n */\nexport function validateTronAddress(address: string): boolean {\n  // Check length\n  if (!address || address.length !== TRON_ADDRESS_LENGTH) {\n    return false\n  }\n\n  // Check prefix (mainnet addresses start with T)\n  if (!address.startsWith(TRON_ADDRESS_PREFIX)) {\n    return false\n  }\n\n  // Check base58 characters\n  for (const char of address) {\n    if (!BASE58_ALPHABET.includes(char)) {\n      return false\n    }\n  }\n\n  return true\n}\n\n/**\n * Compare two TRON addresses for equality\n *\n * Handles case-insensitivity and different formats.\n *\n * @param addr1 - First address\n * @param addr2 - Second address\n * @returns true if addresses are equal\n */\nexport function addressesEqual(addr1: string, addr2: string): boolean {\n  if (!addr1 || !addr2) return false\n\n  // TRON addresses are case-sensitive in base58, but we normalize for comparison\n  // This handles potential mixed-case issues from different sources\n  return addr1 === addr2\n}\n\n/**\n * Format a TRON address for display\n *\n * @param address - Address to format\n * @param options - Formatting options\n * @returns Formatted address\n */\nexport function formatAddress(\n  address: string,\n  options?: {\n    /** Truncate to first/last N characters */\n    truncate?: number\n  },\n): string {\n  if (!address) return ''\n\n  if (options?.truncate && address.length > options.truncate * 2 + 3) {\n    return `${address.slice(0, options.truncate)}...${address.slice(-options.truncate)}`\n  }\n\n  return address\n}\n\n// =============================================================================\n// Amount Utilities\n// =============================================================================\n\n/**\n * Convert decimal amount to smallest units\n *\n * @param decimalAmount - Amount as decimal string (e.g., \"1.50\")\n * @param decimals - Token decimals (default: 6 for USDT)\n * @returns Amount in smallest units as string\n */\nexport function convertToSmallestUnits(\n  decimalAmount: string,\n  decimals: number = DEFAULT_USDT_DECIMALS,\n): string {\n  const parts = decimalAmount.split('.')\n  const wholePart = parts[0] || '0'\n  let fractionalPart = parts[1] || ''\n\n  // Pad or truncate fractional part to match decimals\n  if (fractionalPart.length > decimals) {\n    fractionalPart = fractionalPart.slice(0, decimals)\n  } else {\n    fractionalPart = fractionalPart.padEnd(decimals, '0')\n  }\n\n  // Combine and remove leading zeros\n  const result = (wholePart + fractionalPart).replace(/^0+/, '') || '0'\n  return result\n}\n\n/**\n * Convert smallest units to decimal amount\n *\n * @param smallestUnits - Amount in smallest units as string\n * @param decimals - Token decimals (default: 6 for USDT)\n * @returns Amount as decimal string\n */\nexport function convertFromSmallestUnits(\n  smallestUnits: string,\n  decimals: number = DEFAULT_USDT_DECIMALS,\n): string {\n  const padded = smallestUnits.padStart(decimals + 1, '0')\n  const wholePart = padded.slice(0, -decimals) || '0'\n  const fractionalPart = padded.slice(-decimals)\n\n  // Remove trailing zeros from fractional part\n  let end = fractionalPart.length\n  while (end > 0 && fractionalPart[end - 1] === '0') end--\n  const trimmedFractional = fractionalPart.slice(0, end)\n\n  if (trimmedFractional) {\n    return `${wholePart}.${trimmedFractional}`\n  }\n  return wholePart\n}\n\n// =============================================================================\n// Transaction Utilities\n// =============================================================================\n\n/**\n * Generate a unique memo/reference for payment tracking\n *\n * @returns Unique reference string\n */\nexport function generatePaymentReference(): string {\n  const timestamp = Date.now()\n  const random = Math.floor(Math.random() * 1000000)\n  return `t402_${timestamp}_${random}`\n}\n\n/**\n * Calculate transaction expiration time\n *\n * @param validitySeconds - Validity duration in seconds\n * @returns Expiration timestamp in milliseconds\n */\nexport function calculateExpiration(validitySeconds: number): number {\n  return Date.now() + validitySeconds * 1000\n}\n\n/**\n * Validate a hex string\n *\n * @param hex - String to validate\n * @returns true if valid hex string\n */\nexport function isValidHex(hex: string): boolean {\n  if (!hex) return false\n  // Remove 0x prefix if present\n  const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex\n  return /^[0-9a-fA-F]+$/.test(cleanHex)\n}\n\n/**\n * Estimate transaction fee\n *\n * Note: Actual fees depend on energy/bandwidth consumption.\n * This provides a conservative estimate.\n *\n * @param isActivated - Whether recipient account is activated\n * @returns Estimated fee in SUN\n */\nexport function estimateTransactionFee(isActivated: boolean = true): number {\n  // TRC20 transfer typically costs ~15-30 TRX in energy\n  // New account activation adds ~1 TRX\n  const baseFee = 30_000_000 // 30 TRX\n  const activationFee = isActivated ? 0 : 1_000_000 // 1 TRX\n  return baseFee + activationFee\n}\n"],"mappings":"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","names":[]}