WDK Utils API Reference

Package: @tetherto/wdk-utils

Address Validation Helpers

validateAddress(chainId, address)

Validate an address with the chain-specific validator selected by a CAIP-2 chain ID or a bare namespace accepted by WDK Utils. The supported namespaces are bip122, eip155, solana, spark, and tron.

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

const result = validateAddress(
  'bip122:000000000019d6689c085ae165831e93',
  '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa'
)
// { success: true, type: 'p2pkh', compatibleNetworks: ['bitcoin'] }

The function returns the selected chain validator's result. Failures specific to dispatch are:

• INVALID_CHAIN_ID: chainId is not a string or does not match the accepted input shape: a 3–8 character lowercase namespace, optionally followed by a 1–32 character reference. A bare namespace is a WDK Utils extension; standard CAIP-2 identifiers require <namespace>:<reference>.
• UNSUPPORTED_CHAIN: the namespace has no validator.
• NETWORK_MISMATCH: a bip122 or spark reference is missing, unknown, or incompatible with the address.

For bip122 and spark, the reference selects the expected network. Other supported namespaces validate the address but do not enforce their reference value. This is structural validation; it does not confirm that an account exists, belongs to the intended recipient, or can receive a particular asset.

validateBase58(address)

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

The current beta.11 type declaration 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. Beta.11 replaces the earlier singular network field with compatibleNetworks and names mainnet bitcoin:

• { success: true, type: 'p2pkh' | 'p2sh' | 'bech32' | 'bech32m', compatibleNetworks: Array<'bitcoin' | 'testnet' | 'regtest'> }
• { success: false, reason: string }

Legacy Base58 testnet formats are also valid on regtest, so those results contain both testnet and regtest.

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 }

validateSolanaAddress(address)

Validate a Solana address as a base58-encoded 32-byte public key. The validator trims surrounding whitespace and accepts off-curve program-derived addresses because they can be valid recipients.

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

const result = validateSolanaAddress(
  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
)

SolanaAddressValidationResult is one of these shapes:

• { success: true, type: 'solana' }
• { success: false, reason: 'EMPTY_ADDRESS' | 'INVALID_FORMAT' | 'INVALID_LENGTH' }

Solana addresses do not include a checksum. This helper verifies structure and decoded length, not whether an account exists, is on curve, or belongs to the intended recipient.

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', compatibleNetworks: Array<'mainnet' | 'testnet' | 'regtest' | 'signet' | 'local'> }
• { success: false, reason: string }

Bitcoin L1 deposit-address formats can be shared by Spark testnet/signet or regtest/local, so the compatibility array can contain two networks.

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')

Seed Encryption Helpers

encrypt(plaintext, password, scryptParams?)

Encrypt a plaintext string with AES-256-GCM. The helper generates a random 32-byte salt and 12-byte initialization vector, derives a 32-byte key with scrypt, and returns a versioned payload with hex-encoded binary fields.

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

const encrypted = encrypt(seedPhrase, passphrase)

EncryptedPayload contains:

• version: 1
• salt: string
• iv: string
• tag: string
• ciphertext: string
• scryptN?: number
• scryptR?: number
• scryptP?: number

Pass optional scrypt cost parameters as { N, r, p }. Defaults are N: 65536, r: 8, and p: 1.

decrypt(payload, password)

Decrypt a payload produced by encrypt(). The helper reads scryptN, scryptR, and scryptP from the payload when present, then clears the derived key from memory after decryption.

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

const seedPhrase = decrypt(encrypted, passphrase)

decrypt() throws if the payload version is unsupported, the password is wrong, or the authentication tag does not verify.

deriveKey(password, salt, scryptParams?)

Derive a 32-byte AES key from a passphrase and salt. Use this when your app needs to manage the derived key explicitly before calling decryptWithKey().

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

const key = deriveKey(passphrase, saltBytes)

decryptWithKey(payload, key)

Decrypt a payload with a pre-derived key. The key must be a 32-byte Uint8Array.

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

const plaintext = decryptWithKey(encrypted, key)

Seed Key Derivation Helpers

Derive deterministic, domain-separated key material from high-entropy seed bytes.

type SeedKeyOptions = {
  salt: string | Uint8Array
  info: string | Uint8Array
  length?: number
}

type KeyPair = {
  publicKey: Uint8Array
  secretKey: Uint8Array
}

deriveSeedKey(seed, options)

Derive a key using HKDF-SHA256. salt and info are required caller-controlled domain-separation values, and length defaults to 32 bytes.

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

const key = deriveSeedKey(seedBytes, {
  salt: 'com.example.wallet/v1',
  info: 'local-encryption',
  length: 32
})

The function throws salt is required or info is required when either field is absent. String inputs are consumed as raw UTF-8 bytes; a mnemonic string is not converted into BIP-39 seed bytes.

deriveSeedKeyPair(seed, options)

Derive a deterministic Ed25519 keypair from the same seed, salt, and info inputs. The function always uses a 32-byte derived seed, even if options.length is supplied, and returns a 32-byte public key plus a 64-byte secret key laid out as the derived seed followed by the public key.

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

const keyPair = deriveSeedKeyPair(seedBytes, {
  salt: 'com.example.wallet/v1',
  info: 'device-signing'
})

BIP-39 Mnemonic Sharing Helpers

splitMnemonic(mnemonic, options)

Decode a valid 12-, 15-, 18-, 21-, or 24-word English BIP-39 mnemonic to entropy and split it into Shamir shares.

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

const shares = await splitMnemonic(seedPhrase, {
  shares: 5,
  threshold: 3
})

• shares must be an integer from 2 through 255.
• threshold must be an integer from 2 through shares.
• The returned shares are unencrypted lowercase hex strings.
• Invalid BIP-39 words, word counts, and checksums are rejected.
• The runtime must provide secure crypto.getRandomValues; React Native apps may need to load react-native-get-random-values before importing WDK Utils.

combineMnemonic(shares)

Reconstruct a mnemonic from enough shares produced by splitMnemonic().

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

const restored = await combineMnemonic([
  shares[0],
  shares[2],
  shares[4]
])

The helper verifies the embedded four-byte integrity checksum and rejects malformed, corrupted, duplicate, mixed-length, or insufficient share sets.

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?