WDK Utils API Reference

Package: @tetherto/wdk-utils

Address Validation Helpers

validateBase58(address)

Validate a Base58Check Bitcoin address and identify whether it matches a supported P2PKH or P2SH network version byte.

The published beta.2 type declaration currently includes an internal { decoded: Uint8Array } branch in this return type. The shipped runtime returns validation results rather than exposing that intermediate decode object.

import { validateBase58 } from '@tetherto/wdk-utils'

const result = validateBase58('18hnriom5tB5KtFb982m8f9cZz4i72PUpZ')

validateBech32(address)

Validate a SegWit v0 Bech32 Bitcoin address for supported network prefixes.

import { validateBech32 } from '@tetherto/wdk-utils'

const result = validateBech32('bc1qu9yqnhc6wjj6s62s9x0shnl5l2r7gq5cudm94r7mvwv0uw4s7acq0hn9g6')

validateBech32m(address)

Validate a SegWit v1+ Bech32m Bitcoin address for mainnet, testnet, or regtest.

import { validateBech32m } from '@tetherto/wdk-utils'

const result = validateBech32m('bc1pkf2alvh0q96nyf7yhw2w3x7etlw22sasn2kxu59xzzl2px7ga4asctyc2v')

validateBitcoinAddress(address)

Run the combined Bitcoin validator across Base58Check, Bech32, and Bech32m inputs.

import { validateBitcoinAddress } from '@tetherto/wdk-utils'

const result = validateBitcoinAddress('tb1pu9yqnhc6wjj6s62s9x0shnl5l2r7gq5cudm94r7mvwv0uw4s7acqjg9r2f')

BtcAddressValidationResult is one of these shapes:

• { success: true, type: 'p2pkh' | 'p2sh' | 'bech32' | 'bech32m', network: 'mainnet' | 'testnet' | 'regtest' }
• { success: false, reason: string }

validateEVMAddress(address)

Validate an EVM address. Mixed-case inputs must satisfy EIP-55 checksum casing, while all-lowercase and all-uppercase inputs remain valid.

import { validateEVMAddress } from '@tetherto/wdk-utils'

const result = validateEVMAddress('0x742d35Cc6634C0532925a3b844Bc454e4438f44e')

EvmAddressValidationResult is one of these shapes:

• { success: true, type: 'evm' }
• { success: false, reason: string }

stripLightningPrefix(input)

Remove a lightning: URI prefix before validating or parsing Lightning inputs.

import { stripLightningPrefix } from '@tetherto/wdk-utils'

const invoice = stripLightningPrefix(
  'lightning:lnbc100u1p5m3k6fpp5uk9rs7fdrvssehzthphfjvpc3t5hyacgrveskwqzwclrdsl0cjgsdqydp5scqzzsxqrrssrzjqvgptfurj3528snx6e3dtwepafxw5fpzdymw9pj20jj09sunnqmwqqqqqyqqqqqqqqqqqqqqqqqqqqqqjqnp4qtem70et4qm86lv449zcpqjn9nmamd6qrzm3wa3d7msnq2kx3yapwsp50c4l2z72hcmejj88en6eu2p8u2ypv87pw5pndzjjtclwaw0f7wds9qyyssqtqeqrvaaw92y7at9463vxhwkjdy7lpxet7h6g4vry8xyw4ar9yn8qq36dryntpf252v58c4hrf4g59z2pr25lhp06n7x4z7yltd022cqk7lc7e'
)

validateLightningInvoice(address)

Validate a Lightning invoice string after trimming input and removing any lightning: URI prefix.

import { validateLightningInvoice } from '@tetherto/wdk-utils'

const result = validateLightningInvoice(
  'lnbc100u1p5m3k6fpp5uk9rs7fdrvssehzthphfjvpc3t5hyacgrveskwqzwclrdsl0cjgsdqydp5scqzzsxqrrssrzjqvgptfurj3528snx6e3dtwepafxw5fpzdymw9pj20jj09sunnqmwqqqqqyqqqqqqqqqqqqqqqqqqqqqqjqnp4qtem70et4qm86lv449zcpqjn9nmamd6qrzm3wa3d7msnq2kx3yapwsp50c4l2z72hcmejj88en6eu2p8u2ypv87pw5pndzjjtclwaw0f7wds9qyyssqtqeqrvaaw92y7at9463vxhwkjdy7lpxet7h6g4vry8xyw4ar9yn8qq36dryntpf252v58c4hrf4g59z2pr25lhp06n7x4z7yltd022cqk7lc7e'
)

LightningInvoiceValidationResult is one of these shapes:

• { success: true, type: 'invoice' }
• { success: false, reason: string }

decode(invoice)

Decode a BOLT11 Lightning invoice into structured invoice data. The exported function name is decode, so alias it at import sites when your code also decodes other payloads.

Payment descriptions are user-defined. Sanitize description tag values before rendering them in HTML or storing them.

import { decode as decodeBolt11 } from '@tetherto/wdk-utils'

const result = decodeBolt11(
  'lnbc1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdpl2pkx2ctnv5sxxmmwwd5kgetjypeh2ursdae8g6twvus8g6rfwvs8qun0dfjkxaq8rkx3yf5tcsyz3d73gafnh3cax9rn449d9p5uxz9ezhhypd0elx87sjle52x86fux2ypatgddc6k63n7erqz25le42c4u4ecky03ylcqca784w'
)

LightningInvoiceDecodingResult is one of these shapes:

• { success: true, type: 'invoice', data: DecodedLightningInvoice }
• { success: false, reason: string }

DecodedLightningInvoice includes the invoice network (bitcoin, testnet, regtest, or signet), optional millisatoshis, optional timestamp, optional timeExpireDate, optional payeeNodeKey, optional signature, optional recoveryFlag, required tags, and optional paymentRequest.

getHashToSign(invoiceData)

Return the SHA-256 hash that must be signed for a BOLT11 invoice.

import { getHashToSign } from '@tetherto/wdk-utils'

const hash = getHashToSign(invoiceData)

LightningInvoiceHashingResult is one of these shapes:

• { success: true, type: 'hash', data: Uint8Array }
• { success: false, reason: string }

sign(invoiceData, privateKey)

Sign BOLT11 invoice data. The private key can be a hex string or Uint8Array.

import { sign as signBolt11 } from '@tetherto/wdk-utils'

const signed = signBolt11(invoiceData, privateKey)

LightningInvoiceSigningResult is one of these shapes:

• { success: true, type: 'invoice', data: DecodedLightningInvoice }
• { success: false, reason: string }

encode(invoiceData)

Encode BOLT11 invoice data into an invoice string.

import { encode as encodeBolt11 } from '@tetherto/wdk-utils'

const encoded = encodeBolt11(signed.data)

LightningInvoiceEncodingResult is one of these shapes:

• { success: true, type: 'invoice', data: string }
• { success: false, reason: string }

validateLnurl(address)

Validate an LNURL string that begins with lnurl1.

import { validateLnurl } from '@tetherto/wdk-utils'

const result = validateLnurl(
  'lnurl1dp68gurn8ghj7ampd3kx2ar0veekzar0wd5xjtnrdakj7tnhv4kxctttdehhwm30d3h82unvwqhhxurj093k7mtxdae8gwfjnztwnf'
)

LnurlValidationResult is one of these shapes:

• { success: true, type: 'lnurl' }
• { success: false, reason: string }

decodeLnurl(address)

Decode an LNURL string into its original URL. The helper also accepts a leading lightning: URI prefix.

import { decodeLnurl } from '@tetherto/wdk-utils'

const result = decodeLnurl(
  'lnurl1dp68gurn8ghj7ampd3kx2ar0veekzar0wd5xjtnrdakj7tnhv4kxctttdehhwm30d3h82unvwqhhxurj093k7mtxdae8gwfjnztwnf'
)

LnurlDecodingResult is one of these shapes:

• { success: true, type: 'lnurl', data: string }
• { success: false, reason: string }

validateLightningAddress(address)

Validate a Lightning Address in user@domain.tld form.

import { validateLightningAddress } from '@tetherto/wdk-utils'

const result = validateLightningAddress('sprycomfort92@waletofsatoshi.com')

LightningAddressValidationResult is one of these shapes:

• { success: true, type: 'address' }
• { success: false, reason: string }

validateSparkAddress(address)

Validate a Spark address or a Bitcoin Bech32m deposit address accepted by Spark flows.

import { validateSparkAddress } from '@tetherto/wdk-utils'

const spark = validateSparkAddress(
  'spark1pgss82uvuvyjggx72gl42qk3285yz0j6lgxw9uk2mvgajsr8w22nudv8w6hqs2'
)
const l1Deposit = validateSparkAddress(
  'bc1p4lpn5nrunrjdk6teyjd2z53vmv82hlgjvv4pejkhg9wz5jq86zuqsruz85'
)

SparkAddressValidationResult is one of these shapes:

• { success: true, type: 'spark' | 'btc' }
• { success: false, reason: string }

validateTronAddress(address)

Validate a Tron Base58Check address. The helper checks the T prefix, the 34-character address length, the Tron prefix byte, and the checksum.

import { validateTronAddress } from '@tetherto/wdk-utils'

const result = validateTronAddress('TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH')

TronAddressValidationResult is one of these shapes:

• { success: true, type: 'tron' }
• { success: false, reason: string }

validateUmaAddress(address)

Validate a Universal Money Address in $user@domain.tld form.

import { validateUmaAddress } from '@tetherto/wdk-utils'

const result = validateUmaAddress('$you@uma.money')

UmaAddressValidationResult is one of these shapes:

• { success: true, type: 'uma' }
• { success: false, reason: string }

resolveUmaUsername(uma)

Resolve a valid UMA string into the local part, domain, and underlying Lightning Address.

import { resolveUmaUsername } from '@tetherto/wdk-utils'

const result = resolveUmaUsername('$alice@wallet.com')

BIP-21 Bitcoin Payment URI Helpers

isBip21Request(input)

Detect whether a string looks like a BIP-21 Bitcoin payment URI before attempting a full parse. This is a syntactic check only; use parseBip21Request() when you need address and parameter validation.

import { isBip21Request } from '@tetherto/wdk-utils'

const looksLikeRequest = isBip21Request(
  'bitcoin:1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH?amount=0.001&label=Coffee'
)

parseBip21Request(input)

Parse a BIP-21 Bitcoin payment URI. The helper validates the Bitcoin address, accepts optional amount, label, and message parameters, rejects unsupported req- parameters, and returns machine-readable failure reasons.

import { parseBip21Request } from '@tetherto/wdk-utils'

const result = parseBip21Request(
  'bitcoin:1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH?amount=0.001&label=Coffee&message=Thanks'
)

Bip21ParseResult is one of these shapes:

• { success: true, type: 'bip21', value: Bip21Request }
• { success: false, reason: 'INVALID_FORMAT' | 'INVALID_ADDRESS' | 'INVALID_AMOUNT' | 'UNSUPPORTED_REQUIRED_PARAM' }

Bip21Request contains:

• address: string
• amount?: string
• label?: string
• message?: string

amount is a decimal BTC string with up to eight decimal places and a maximum value of 21000000.

encodeBip21Request(request)

Encode a BIP-21 Bitcoin payment URI from a request object. The helper validates the Bitcoin address and amount before returning the URI.

import { encodeBip21Request } from '@tetherto/wdk-utils'

const uri = encodeBip21Request({
  address: '1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH',
  amount: '0.001',
  label: 'Coffee',
  message: 'Thanks'
})

encodeBip21Request() throws INVALID_REQUEST, INVALID_ADDRESS, or INVALID_AMOUNT when the request object cannot be encoded.

EIP-681 Request Parsing Helpers

isEip681Request(input)

Detect whether a string looks like a supported EIP-681 transfer request before you attempt a full parse.

import { isEip681Request } from '@tetherto/wdk-utils'

const looksLikeRequest = isEip681Request(
  'polygon:0xc2132D05D31c914a87C6611C10748AEb04B58e8F@137/transfer?address=0xA9e338082A061d657014c08e652D96B38639F22a&value=1000000'
)

parseEip681Request(input)

Parse a supported EIP-681 transfer request. The published runtime supports transfer requests, accepts value as an alias for uint256, and normalizes scientific-notation amounts into integer amountSmallest strings.

import { parseEip681Request } from '@tetherto/wdk-utils'

const result = parseEip681Request(
  'pol:0xc2132D05D31c914a87C6611C10748AEb04B58e8F@137/transfer?address=0xA9e338082A061d657014c08e652D96B38639F22a&uint256=0.175309000e6'
)

Eip681ParseResult is one of these shapes:

• { success: true, type: 'eip681-transfer', value: Eip681TransferRequest }
• { success: false, reason: 'INVALID_FORMAT' | 'UNSUPPORTED_METHOD' | 'MISSING_REQUIRED_PARAM' | 'INVALID_RECIPIENT' | 'INVALID_AMOUNT' }

Eip681TransferRequest contains:

• recipient: string
• tokenAddress: string
• chainId: number
• amountSmallest: string

Need Help?