@tetherto/wdk-utils 1.0.0-beta.1

package/src/address-validation/bitcoin.js

@@ -0,0 +1,244 @@
+// Copyright 2026 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+'use strict'
+
+import { createBase58check, bech32, bech32m } from '@scure/base'
+import { sha256 } from '@noble/hashes/sha2'
+
+/**
+ * Bitcoin address validation.
+ * Validates format and checksum for mainnet and testnet addresses.
+ * Supports P2PKH, P2SH, SegWit v0 (Bech32), and SegWit v1+ (Bech32m).
+ */
+
+const base58check = createBase58check(sha256)
+
+const NETWORKS = {
+  mainnet: {
+    bech32: 'bc',
+    p2pkh: 0x00,
+    p2sh: 0x05
+  },
+  testnet: {
+    bech32: 'tb',
+    p2pkh: 0x6f,
+    p2sh: 0xc4
+  },
+  regtest: {
+    bech32: 'bcrt'
+    // Regtest uses testnet Base58 version bytes
+  }
+}
+
+const WITNESS_VERSION_BECH32 = 0
+
+/**
+ * @typedef {{ success: true, type: 'p2pkh' | 'p2sh' | 'bech32' | 'bech32m', network: 'mainnet' | 'testnet' | 'regtest' }} BtcAddressValidationSuccess
+ * @typedef {{ success: false, reason: string }} BtcAddressValidationFailure
+ * @typedef {BtcAddressValidationSuccess | BtcAddressValidationFailure} BtcAddressValidationResult
+ */
+
+/**
+ * Decodes a Base58Check address and validates its payload length.
+ * Returns decoded bytes or a failure result.
+ * @param {string} address
+ * @returns {{ decoded: Uint8Array } | BtcAddressValidationFailure}
+ */
+function _decodeBase58 (address) {
+  let decoded
+
+  try {
+    decoded = base58check.decode(address)
+  } catch (e) {
+    const msg = e && e.message ? e.message.toLowerCase() : ''
+
+    if (msg.includes('checksum')) {
+      return { success: false, reason: 'INVALID_CHECKSUM' }
+    }
+
+    return { success: false, reason: 'INVALID_FORMAT' }
+  }
+
+  if (decoded.length !== 21) {
+    return { success: false, reason: 'INVALID_LENGTH' }
+  }
+
+  return { decoded }
+}
+
+/**
+ * Validates a P2PKH address for any supported network.
+ * @param {Uint8Array} decoded - The decoded address
+ * @returns {BtcAddressValidationResult}
+ */
+function _validateP2PKH (decoded) {
+  const version = decoded[0]
+  if (version === NETWORKS.mainnet.p2pkh) {
+    return { success: true, type: 'p2pkh', network: 'mainnet' }
+  }
+  if (version === NETWORKS.testnet.p2pkh) {
+    return { success: true, type: 'p2pkh', network: 'testnet' }
+  }
+
+  return { success: false, reason: 'INVALID_VERSION_BYTE' }
+}
+
+/**
+ * Validates a P2SH address for any supported network.
+ * @param {Uint8Array} decoded - The decoded address
+ * @returns {BtcAddressValidationResult}
+ */
+function _validateP2SH (decoded) {
+  const version = decoded[0]
+
+  if (version === NETWORKS.mainnet.p2sh) {
+    return { success: true, type: 'p2sh', network: 'mainnet' }
+  }
+
+  if (version === NETWORKS.testnet.p2sh) {
+    return { success: true, type: 'p2sh', network: 'testnet' }
+  }
+
+  return { success: false, reason: 'INVALID_VERSION_BYTE' }
+}
+
+export function validateBase58 (address) {
+  const result = _decodeBase58(address)
+  if (!result.decoded) return result
+
+  const validateP2pkh = _validateP2PKH(result.decoded)
+  if (validateP2pkh.success) {
+    return validateP2pkh
+  }
+
+  const validateP2sh = _validateP2SH(result.decoded)
+  if (validateP2sh.success) {
+    return validateP2sh
+  }
+
+  return { success: false, reason: 'INVALID_VERSION_BYTE' }
+}
+
+/**
+ * Validates a Bech32 address for any supported network.
+ * @param {string} address - The address to validate.
+ * @returns {BtcAddressValidationResult}
+ */
+export function validateBech32 (address) {
+  try {
+    const decoded = bech32.decode(address)
+    const { words } = decoded
+
+    if (words[0] !== WITNESS_VERSION_BECH32) {
+      return { success: false, reason: 'INVALID_WITNESS_VERSION' }
+    }
+
+    const programBytes = bech32.fromWords(words.slice(1))
+    if (programBytes.length !== 20 && programBytes.length !== 32) {
+      return { success: false, reason: 'INVALID_LENGTH' }
+    }
+
+    const prefix = address.toLowerCase().substring(0, address.lastIndexOf('1'))
+    if (prefix === NETWORKS.mainnet.bech32) return { success: true, type: 'bech32', network: 'mainnet' }
+    if (prefix === NETWORKS.testnet.bech32) return { success: true, type: 'bech32', network: 'testnet' }
+    // Note: Regtest addresses are Bech32m, not Bech32. This validator will correctly fail them.
+
+    return { success: false, reason: 'INVALID_HRP' }
+  } catch (e) {
+    if (e && e.message && e.message.toLowerCase().includes('lowercase or uppercase')) {
+      return { success: false, reason: 'MIXED_CASE' }
+    }
+    return { success: false, reason: 'INVALID_BECH32_FORMAT' }
+  }
+}
+
+/**
+ * Validates a Bech32m address for any supported network.
+ * @param {string} address - The address to validate.
+ * @returns {BtcAddressValidationResult}
+ */
+export function validateBech32m (address) {
+  try {
+    const decoded = bech32m.decode(address)
+    const { words } = decoded
+
+    if (words[0] === WITNESS_VERSION_BECH32) {
+      return { success: false, reason: 'INVALID_WITNESS_VERSION' }
+    }
+
+    const programBytes = bech32m.fromWords(words.slice(1))
+    // As per BIP-173, valid witness programs are 2-40 bytes.
+    if (programBytes.length < 2 || programBytes.length > 40) {
+      return { success: false, reason: 'INVALID_LENGTH' }
+    }
+
+    const prefix = address.toLowerCase().substring(0, address.lastIndexOf('1'))
+    if (prefix === NETWORKS.mainnet.bech32) return { success: true, type: 'bech32m', network: 'mainnet' }
+    if (prefix === NETWORKS.testnet.bech32) return { success: true, type: 'bech32m', network: 'testnet' }
+    if (prefix === NETWORKS.regtest.bech32) return { success: true, type: 'bech32m', network: 'regtest' }
+
+    return { success: false, reason: 'INVALID_HRP' }
+  } catch (e) {
+    if (e && e.message && e.message.toLowerCase().includes('lowercase or uppercase')) {
+      return { success: false, reason: 'MIXED_CASE' }
+    }
+    return { success: false, reason: 'INVALID_BECH32M_FORMAT' }
+  }
+}
+
+/**
+ * Validates a Bitcoin address for mainnet or testnet.
+ *
+ * @param {string} address The address to validate.
+ * @returns {BtcAddressValidationResult}
+ */
+export function validateBitcoinAddress (address) {
+  if (address == null || typeof address !== 'string') {
+    return { success: false, reason: 'INVALID_FORMAT' }
+  }
+  const trimmed = address.trim()
+  if (trimmed.length === 0) {
+    return { success: false, reason: 'EMPTY_ADDRESS' }
+  }
+
+  const results = [
+    validateBase58(trimmed),
+    validateBech32(trimmed),
+    validateBech32m(trimmed)
+  ]
+
+  const successes = results.filter(r => r.success)
+
+  if (successes.length === 1) {
+    return successes[0]
+  }
+
+  if (successes.length > 1) {
+    return { success: false, reason: 'AMBIGUOUS_ADDRESS' }
+  }
+
+  const failures = results
+
+  const definitiveFailure = failures.find(f =>
+    f.reason !== 'INVALID_FORMAT' &&
+    f.reason !== 'INVALID_BECH32_FORMAT' &&
+    f.reason !== 'INVALID_BECH32M_FORMAT'
+  )
+
+  if (definitiveFailure) {
+    return definitiveFailure
+  }
+
+  return { success: false, reason: 'INVALID_FORMAT' }
+}

package/src/address-validation/evm.js

@@ -0,0 +1,90 @@
+// Copyright 2026 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+'use strict'
+
+/**
+ * EVM address validation.
+ * EIP-55 checksum: if all lowercase, valid; if mixed case, must match checksum.
+ * @see https://eips.ethereum.org/EIPS/eip-55
+ */
+
+// eslint-disable-next-line camelcase
+import { keccak_256 } from '@noble/hashes/sha3'
+
+function isValidEIP55Checksum (address) {
+  const hexPart = address.slice(2)
+  if (hexPart === hexPart.toLowerCase()) {
+    return true
+  }
+  const addressLower = address.toLowerCase()
+  const addressWithoutPrefix = addressLower.slice(2)
+  try {
+    const addressBytes = new TextEncoder().encode(addressWithoutPrefix)
+    const hashBytes = keccak_256(addressBytes)
+    const hash = Array.from(hashBytes)
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('')
+    let checksummed = '0x'
+    for (let i = 0; i < addressWithoutPrefix.length; i++) {
+      const char = addressWithoutPrefix[i]
+      const hashChar = hash[i]
+      if (parseInt(hashChar, 16) >= 8) {
+        checksummed += char.toUpperCase()
+      } else {
+        checksummed += char
+      }
+    }
+    return address === checksummed
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @typedef {{ success: true, type: 'evm' }} EvmAddressValidationSuccess
+ * @typedef {{ success: false, reason: string }} EvmAddressValidationFailure
+ * @typedef {EvmAddressValidationSuccess | EvmAddressValidationFailure} EvmAddressValidationResult
+ */
+
+/**
+ * Validates an EVM address (format + optional EIP-55 checksum).
+ * If mixed case, checksum must match; all lowercase or all uppercase is valid.
+ *
+ * @param {string} address The address to validate.
+ * @returns {EvmAddressValidationResult}
+ */
+export function validateEVMAddress (address) {
+  if (address == null || typeof address !== 'string') {
+    return { success: false, reason: 'INVALID_FORMAT' }
+  }
+  const trimmed = address.trim()
+  if (trimmed.length === 0) {
+    return { success: false, reason: 'EMPTY_ADDRESS' }
+  }
+
+  if (!trimmed.startsWith('0x') || trimmed.length !== 42) {
+    return { success: false, reason: 'INVALID_FORMAT' }
+  }
+  const hexPart = trimmed.slice(2)
+  if (!/^[0-9a-fA-F]{40}$/.test(hexPart)) {
+    return { success: false, reason: 'INVALID_FORMAT' }
+  }
+  const isAllLowercase = hexPart === hexPart.toLowerCase()
+  const isAllUppercase = hexPart === hexPart.toUpperCase()
+  const hasMixedCase = !isAllLowercase && !isAllUppercase
+  if (hasMixedCase && !isValidEIP55Checksum(trimmed)) {
+    return { success: false, reason: 'INVALID_CHECKSUM' }
+  }
+  return { success: true, type: 'evm' }
+}

package/src/address-validation/index.js

@@ -0,0 +1,20 @@
+// Copyright 2026 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+'use strict'
+
+export * from './bitcoin.js'
+export * from './evm.js'
+export * from './lightning.js'
+export * from './spark.js'
+export * from './uma.js'

package/src/address-validation/lightning.js

@@ -0,0 +1,153 @@
+// Copyright 2026 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+'use strict'
+
+/**
+ * Lightning validation.
+ * Invoice prefixes: lnbc, lntb, lnbcrt, lni.
+ * Lightning address: strict email (user@domain.tld).
+ */
+
+import { bech32 } from '@scure/base'
+
+const VALID_INVOICE_PREFIXES = ['lnbc', 'lntb', 'lnbcrt', 'lnsb']
+/** Lightning address: must have dot in domain (user@domain.tld) */
+const LIGHTNING_ADDRESS_EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+/**
+ * Strips "lightning:" URI prefix (case-insensitive). The input is trimmed first.
+ *
+ * @param {string} input
+ * @returns {string} Returns a string. Returns an empty string if input is not a string.
+ */
+export function stripLightningPrefix (input) {
+  if (typeof input !== 'string') {
+    return ''
+  }
+
+  const trimmed = input.trim()
+  if (trimmed.toLowerCase().startsWith('lightning:')) {
+    return trimmed.slice(10).trim()
+  }
+
+  return trimmed
+}
+
+/**
+ * @typedef {{ success: true, type: 'invoice' }} LightningInvoiceValidationSuccess
+ * @typedef {{ success: false, reason: string }} LightningInvoiceValidationFailure
+ * @typedef {LightningInvoiceValidationSuccess | LightningInvoiceValidationFailure} LightningInvoiceValidationResult
+ */
+
+/**
+ * Validates a Lightning Network invoice (lnbc, lntb, lnbcrt, lni; length >= 20).
+ *
+ * @param {string} address The invoice to validate.
+ * @returns {LightningInvoiceValidationResult}
+ */
+export function validateLightningInvoice (address) {
+  if (address == null || typeof address !== 'string') {
+    return { success: false, reason: 'INVALID_FORMAT' }
+  }
+
+  const invoice = stripLightningPrefix(address)
+  if (invoice.length === 0) {
+    return { success: false, reason: 'EMPTY_ADDRESS' }
+  }
+
+  const lowerInvoice = invoice.toLowerCase()
+
+  const hasValidPrefix = VALID_INVOICE_PREFIXES.some((prefix) =>
+    lowerInvoice.startsWith(prefix)
+  )
+  if (!hasValidPrefix) {
+    return { success: false, reason: 'INVALID_PREFIX' }
+  }
+  if (invoice.length < 20) {
+    return { success: false, reason: 'INVALID_LENGTH' }
+  }
+  try {
+    bech32.decode(invoice, false)
+    return { success: true, type: 'invoice' }
+  } catch (e) {
+    if (e && e.message && e.message.toLowerCase().includes('lowercase or uppercase')) {
+      return { success: false, reason: 'MIXED_CASE' }
+    }
+
+    return { success: false, reason: 'INVALID_BECH32_FORMAT' }
+  }
+}
+
+/**
+ * @typedef {{ success: true, type: 'lnurl' }} LnurlValidationSuccess
+ * @typedef {{ success: false, reason: string }} LnurlValidationFailure
+ * @typedef {LnurlValidationSuccess | LnurlValidationFailure} LnurlValidationResult
+ */
+
+/**
+ * Validates an LNURL address (lnurl1... bech32 encoded URL).
+ *
+ * @param {string} address The LNURL to validate.
+ * @returns {LnurlValidationResult}
+ */
+export function validateLnurl (address) {
+  if (address == null || typeof address !== 'string') {
+    return { success: false, reason: 'INVALID_FORMAT' }
+  }
+  const lnurl = address.trim()
+  if (lnurl.length === 0) {
+    return { success: false, reason: 'EMPTY_ADDRESS' }
+  }
+
+  if (!lnurl.toLowerCase().startsWith('lnurl1')) {
+    return { success: false, reason: 'INVALID_PREFIX' }
+  }
+
+  try {
+    bech32.decode(lnurl, false)
+    return { success: true, type: 'lnurl' }
+  } catch (e) {
+    if (e && e.message && e.message.toLowerCase().includes('lowercase or uppercase')) {
+      return { success: false, reason: 'MIXED_CASE' }
+    }
+    return { success: false, reason: 'INVALID_BECH32_FORMAT' }
+  }
+}
+
+/**
+ * @typedef {{ success: true, type: 'address' }} LightningAddressValidationSuccess
+ * @typedef {{ success: false, reason: string }} LightningAddressValidationFailure
+ * @typedef {LightningAddressValidationSuccess | LightningAddressValidationFailure} LightningAddressValidationResult
+ */
+
+/**
+ * Validates Lightning Address format (email: user@domain.tld).
+ *
+ * @param {string} address The address to validate.
+ * @returns {LightningAddressValidationResult}
+ */
+export function validateLightningAddress (address) {
+  if (address == null || typeof address !== 'string') {
+    return { success: false, reason: 'INVALID_FORMAT' }
+  }
+  const trimmed = address.trim()
+  if (trimmed.length === 0) {
+    return { success: false, reason: 'EMPTY_ADDRESS' }
+  }
+
+  if (LIGHTNING_ADDRESS_EMAIL_REGEX.test(trimmed.toLowerCase())) {
+    return { success: true, type: 'address' }
+  }
+  return { success: false, reason: 'INVALID_FORMAT' }
+}

package/src/address-validation/spark.js

@@ -0,0 +1,71 @@
+// Copyright 2026 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+'use strict'
+
+import { bech32m } from '@scure/base'
+import { validateBech32m } from './bitcoin.js'
+
+/**
+ * @typedef {{ success: true, type: 'spark' | 'btc' }} SparkAddressValidationSuccess
+ * @typedef {{ success: false, reason: string }} SparkAddressValidationFailure
+ * @typedef {SparkAddressValidationSuccess | SparkAddressValidationFailure} SparkAddressValidationResult
+ */
+
+const VALID_PREFIXES = ['spark', 'sparkrt', 'sparkt', 'sparks', 'sparkl']
+
+/**
+ * Validates a Spark address.
+ * A Spark address can be a native Bech32m encoded address or a standard
+ * Bitcoin address for L1 deposits.
+ *
+ * @param {string} address The address to validate.
+ * @returns {SparkAddressValidationResult}
+ */
+export function validateSparkAddress (address) {
+  if (address == null || typeof address !== 'string') {
+    return { success: false, reason: 'INVALID_FORMAT' }
+  }
+
+  const trimmed = address.trim()
+  if (trimmed.length === 0) {
+    return { success: false, reason: 'EMPTY_ADDRESS' }
+  }
+
+  const lower = trimmed.toLowerCase()
+  const upper = trimmed.toUpperCase()
+  if (trimmed !== lower && trimmed !== upper) {
+    return { success: false, reason: 'MIXED_CASE' }
+  }
+
+  let decoded
+  try {
+    decoded = bech32m.decode(lower)
+  } catch (e) {
+    if (validateBech32m(trimmed).success) {
+      return { success: true, type: 'btc' }
+    }
+
+    return { success: false, reason: 'INVALID_FORMAT' }
+  }
+
+  if (VALID_PREFIXES.includes(decoded.prefix)) {
+    return { success: true, type: 'spark' }
+  }
+
+  if (validateBech32m(trimmed).success) {
+    return { success: true, type: 'btc' }
+  }
+
+  return { success: false, reason: 'INVALID_FORMAT' }
+}

package/src/address-validation/uma.js

@@ -0,0 +1,71 @@
+// Copyright 2026 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+'use strict'
+
+/**
+ * Universal Money Address (UMA) validation.
+ * Format: $user@domain.tld (human-readable, like email for money; built on Lightning).
+ * Resolves UMA usernames into the underlying Lightning Address (user@domain).
+ */
+
+/** UMA format: leading $ then local@domain with dot in domain */
+const UMA_REGEX = /^\$([^\s@]+)@([^\s@]+\.[^\s@]+)$/
+
+/**
+ * @typedef {{ success: true, type: 'uma' }} UmaAddressValidationSuccess
+ * @typedef {{ success: false, reason: string }} UmaAddressValidationFailure
+ * @typedef {UmaAddressValidationSuccess | UmaAddressValidationFailure} UmaAddressValidationResult
+ */
+
+/**
+ * Validates a Universal Money Address (format: $user@domain.tld).
+ *
+ * @param {string} address The address to validate.
+ * @returns {UmaAddressValidationResult}
+ */
+export function validateUmaAddress (address) {
+  if (address == null || typeof address !== 'string') {
+    return { success: false, reason: 'INVALID_FORMAT' }
+  }
+  const trimmed = address.trim()
+  if (trimmed.length === 0) {
+    return { success: false, reason: 'EMPTY_ADDRESS' }
+  }
+
+  if (UMA_REGEX.test(trimmed.toLowerCase())) {
+    return { success: true, type: 'uma' }
+  }
+  return { success: false, reason: 'INVALID_FORMAT' }
+}
+
+/**
+ * Resolves UMA username into address components and the underlying Lightning Address.
+ * UMA is built on Lightning Addresses; this returns the user@domain form used for resolution.
+ *
+ * @param {string} uma - UMA string (e.g. $you@uma.money)
+ * @returns {{ localPart: string; domain: string; lightningAddress: string } | null} Parsed parts and lightningAddress (user@domain), or null if invalid
+ */
+export function resolveUmaUsername (uma) {
+  if (typeof uma !== 'string') {
+    return null
+  }
+  const trimmed = uma.trim()
+  const match = trimmed.toLowerCase().match(UMA_REGEX)
+  if (!match) {
+    return null
+  }
+  const [, localPart, domain] = match
+  const lightningAddress = `${localPart}@${domain}`
+  return { localPart, domain, lightningAddress }
+}