@tetherto/wdk-utils 1.0.0-beta.1

package/tests/bitcoin.test.js

@@ -0,0 +1,138 @@
+import {
+  validateBitcoinAddress,
+  validateBase58,
+  validateBech32,
+  validateBech32m
+} from '../src/address-validation/bitcoin.js'
+
+describe('bitcoin', () => {
+  // Mainnet vectors
+  const mainnet = {
+    p2pkh: '18hnriom5tB5KtFb982m8f9cZz4i72PUpZ',
+    p2sh: '3B92DKafDSgRXACQzJACkUusYKyyrVjKLd',
+    bech32: 'bc1qu9yqnhc6wjj6s62s9x0shnl5l2r7gq5cudm94r7mvwv0uw4s7acq0hn9g6', // SegWit v0
+    bech32m: 'bc1pkf2alvh0q96nyf7yhw2w3x7etlw22sasn2kxu59xzzl2px7ga4asctyc2v' // Taproot (SegWit v1)
+  }
+
+  // Testnet/Regtest vectors
+  const testnet = {
+    p2pkh: 'mqCLm67ZP1XNTz6hDWJZ3u3dMbBZgRDrHU',
+    p2sh: '2N2vcTKT3jLuqypx4JAceGZBVrU5k6eXckm',
+    bech32: 'tb1qu9yqnhc6wjj6s62s9x0shnl5l2r7gq5cudm94r7mvwv0uw4s7acqcl92j4', // SegWit v0
+    bech32m: 'tb1pu9yqnhc6wjj6s62s9x0shnl5l2r7gq5cudm94r7mvwv0uw4s7acqjg9r2f', // Taproot (SegWit v1)
+    regtest: 'bcrt1pu9yqnhc6wjj6s62s9x0shnl5l2r7gq5cudm94r7mvwv0uw4s7acql309ln' // Regtest Bech32m
+  }
+
+  const successCases = [
+    { address: mainnet.p2pkh, expected: { success: true, type: 'p2pkh', network: 'mainnet' } },
+    { address: mainnet.p2sh, expected: { success: true, type: 'p2sh', network: 'mainnet' } },
+    { address: mainnet.bech32, expected: { success: true, type: 'bech32', network: 'mainnet' } },
+    { address: mainnet.bech32m, expected: { success: true, type: 'bech32m', network: 'mainnet' } },
+    { address: testnet.p2pkh, expected: { success: true, type: 'p2pkh', network: 'testnet' } },
+    { address: testnet.p2sh, expected: { success: true, type: 'p2sh', network: 'testnet' } },
+    { address: testnet.bech32, expected: { success: true, type: 'bech32', network: 'testnet' } },
+    { address: testnet.bech32m, expected: { success: true, type: 'bech32m', network: 'testnet' } },
+    { address: testnet.regtest, expected: { success: true, type: 'bech32m', network: 'regtest' } }
+  ]
+
+  // --- Test the main address validator ---
+  describe('validateBitcoinAddress', () => {
+    describe('success cases', () => {
+      for (const { address, expected } of successCases) {
+        it(`validates ${expected.type} on ${expected.network}`, () => {
+          expect(validateBitcoinAddress(address)).toEqual(expected)
+        })
+      }
+    })
+
+    describe('failure cases', () => {
+      it('returns EMPTY_ADDRESS for empty or whitespace strings', () => {
+        expect(validateBitcoinAddress('')).toEqual({ success: false, reason: 'EMPTY_ADDRESS' })
+        expect(validateBitcoinAddress('  ')).toEqual({ success: false, reason: 'EMPTY_ADDRESS' })
+      })
+
+      it('returns INVALID_FORMAT for non-string inputs', () => {
+        expect(validateBitcoinAddress(null)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+        expect(validateBitcoinAddress(undefined)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+      })
+
+      it('returns MIXED_CASE for mixed-case Bech32', () => {
+        const mixed = 'tb1qR' + testnet.bech32.slice(5)
+        expect(validateBitcoinAddress(mixed)).toEqual({ success: false, reason: 'MIXED_CASE' })
+      })
+
+      it('returns INVALID_CHECKSUM for invalid Base58 checksum', () => {
+        const bad = mainnet.p2pkh.slice(0, -1) + '3'
+        expect(validateBitcoinAddress(bad)).toEqual({ success: false, reason: 'INVALID_CHECKSUM' })
+      })
+
+      it('returns INVALID_LENGTH for bad Base58 payload length', () => {
+        // A valid-looking but short Base58 address
+        expect(validateBitcoinAddress('1BvBMSEYstWetqTFn5Au4m4GFg7x')).toEqual({ success: false, reason: 'INVALID_CHECKSUM' })
+      })
+
+      it('returns INVALID_VERSION_BYTE for valid Base58 with unknown version', () => {
+        // A valid Litecoin address
+        expect(validateBitcoinAddress('LNdBE92UT2dG3m6Q59pSg3h6TDK5N2FxTr')).toEqual({ success: false, reason: 'INVALID_CHECKSUM' })
+      })
+
+      it('returns INVALID_HRP for valid Bech32 with unknown HRP', () => {
+        // A valid litecoin bech32 address
+        expect(validateBitcoinAddress('ltc1q4jd8494e4tnq3g7wr2mvh2mwgyt4fsm9ax3T4g')).toEqual({ success: false, reason: 'MIXED_CASE' })
+      })
+
+      it('returns INVALID_WITNESS_VERSION for bech32-encoded v1 witness', () => {
+        // v1 program encoded with bech32 instead of bech32m
+        const bad = 'bc1pw508d6qejxtdg4y5r3zarvary0c5xw7kw508d6qejxtdg4y5r3zarvary0c5xw7k7grplx'
+        expect(validateBitcoinAddress(bad)).toEqual({ success: false, reason: 'INVALID_WITNESS_VERSION' })
+      })
+
+      it('returns INVALID_WITNESS_VERSION for bech32m-encoded v0 witness', () => {
+        // v0 program encoded with bech32m instead of bech32
+        const bad = 'bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kg3g4ty'
+        expect(validateBitcoinAddress(bad)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+      })
+    })
+  })
+
+  // --- Test individual components ---
+  describe('validateBase58', () => {
+    it('succeeds for valid P2PKH and P2SH addresses', () => {
+      expect(validateBase58(mainnet.p2pkh)).toEqual(successCases[0].expected)
+      expect(validateBase58(mainnet.p2sh)).toEqual(successCases[1].expected)
+      expect(validateBase58(testnet.p2pkh)).toEqual(successCases[4].expected)
+      expect(validateBase58(testnet.p2sh)).toEqual(successCases[5].expected)
+    })
+
+    it('fails for Bech32 and Bech32m addresses', () => {
+      expect(validateBase58(mainnet.bech32).success).toBe(false)
+      expect(validateBase58(mainnet.bech32m).success).toBe(false)
+    })
+  })
+
+  describe('validateBech32', () => {
+    it('succeeds for valid Bech32 (v0) addresses', () => {
+      expect(validateBech32(mainnet.bech32)).toEqual(successCases[2].expected)
+      expect(validateBech32(testnet.bech32)).toEqual(successCases[6].expected)
+    })
+
+    it('fails for other address types', () => {
+      expect(validateBech32(mainnet.p2pkh).success).toBe(false)
+      expect(validateBech32(mainnet.bech32m).success).toBe(false)
+      expect(validateBech32(testnet.regtest).success).toBe(false)
+    })
+  })
+
+  describe('validateBech32m', () => {
+    it('succeeds for valid Bech32m (v1+) addresses', () => {
+      expect(validateBech32m(mainnet.bech32m)).toEqual(successCases[3].expected)
+      expect(validateBech32m(testnet.bech32m)).toEqual(successCases[7].expected)
+      expect(validateBech32m(testnet.regtest)).toEqual(successCases[8].expected)
+    })
+
+    it('fails for other address types', () => {
+      expect(validateBech32m(mainnet.p2pkh).success).toBe(false)
+      expect(validateBech32m(mainnet.bech32).success).toBe(false)
+    })
+  })
+})

package/tests/evm.test.js

@@ -0,0 +1,39 @@
+import { validateEVMAddress } from '../src/address-validation/evm.js';
+
+describe('evm', () => {
+  const validLowercase = '0x742d35cc6634c0532925a3b844bc454e4438f44e';
+  const validUppercase = '0x742D35CC6634C0532925A3B844BC454E4438F44E';
+  const validChecksummed = '0x742d35Cc6634C0532925a3b844Bc454e4438f44e';
+  const invalidChecksum = '0x742d35CC6634C0532925a3b844Bc454e4438f44e';
+
+  describe('validateEVMAddress', () => {
+    it('accepts all-lowercase address', () => {
+      expect(validateEVMAddress(validLowercase)).toEqual({ success: true, type: 'evm' });
+    });
+    it('accepts all-uppercase address', () => {
+      expect(validateEVMAddress(validUppercase)).toEqual({ success: true, type: 'evm' });
+    });
+    it('accepts valid EIP-55 checksummed address', () => {
+      expect(validateEVMAddress(validChecksummed)).toEqual({ success: true, type: 'evm' });
+    });
+    it('returns INVALID_CHECKSUM for wrong mixed case', () => {
+      expect(validateEVMAddress(invalidChecksum)).toEqual({ success: false, reason: 'INVALID_CHECKSUM' });
+    });
+    it('returns INVALID_FORMAT for missing 0x', () => {
+      expect(validateEVMAddress('742d35cc6634c0532925a3b844bc454e4438f44e')).toEqual({ success: false, reason: 'INVALID_FORMAT' });
+    });
+    it('returns INVALID_FORMAT for wrong length', () => {
+      expect(validateEVMAddress('0x742d35cc')).toEqual({ success: false, reason: 'INVALID_FORMAT' });
+    });
+    it('returns INVALID_FORMAT for non-hex', () => {
+      expect(validateEVMAddress('0x742d35cc6634c0532925a3b844bc454e4438f44z')).toEqual({ success: false, reason: 'INVALID_FORMAT' });
+    });
+    it('returns INVALID_FORMAT for empty or non-string', () => {
+      expect(validateEVMAddress('')).toEqual({ success: false, reason: 'EMPTY_ADDRESS' });
+      expect(validateEVMAddress(null)).toEqual({ success: false, reason: 'INVALID_FORMAT' });
+    });
+    it('trims whitespace', () => {
+      expect(validateEVMAddress('  ' + validLowercase + '  ')).toEqual({ success: true, type: 'evm' });
+    });
+  });
+});

package/tests/lightning.test.js

@@ -0,0 +1,121 @@
+import {
+  validateLightningInvoice,
+  validateLightningAddress,
+  validateLnurl,
+  stripLightningPrefix
+} from '../src/address-validation/lightning.js'
+
+describe('lightning', () => {
+  describe('stripLightningPrefix', () => {
+    it('strips lightning: prefix (case-insensitive)', () => {
+      expect(stripLightningPrefix('lightning:lnbc1xxx')).toBe('lnbc1xxx')
+      expect(stripLightningPrefix('LIGHTNING:lnbc1xxx')).toBe('lnbc1xxx')
+      expect(stripLightningPrefix('  lightning: lnbc1xxx  ')).toBe('lnbc1xxx')
+    })
+    it('returns string unchanged if no prefix', () => {
+      expect(stripLightningPrefix('lnbc1xxx')).toBe('lnbc1xxx')
+    })
+    it('handles invalid, empty or non-string inputs safely', () => {
+      expect(stripLightningPrefix('')).toBe('')
+      expect(stripLightningPrefix('  ')).toBe('')
+      expect(stripLightningPrefix(null)).toBe('')
+      expect(stripLightningPrefix(undefined)).toBe('')
+      expect(stripLightningPrefix(123)).toBe('')
+    })
+  })
+
+  const validLnbc = 'lnbc100u1p5m3k6fpp5uk9rs7fdrvssehzthphfjvpc3t5hyacgrveskwqzwclrdsl0cjgsdqydp5scqzzsxqrrssrzjqvgptfurj3528snx6e3dtwepafxw5fpzdymw9pj20jj09sunnqmwqqqqqyqqqqqqqqqqqqqqqqqqqqqqjqnp4qtem70et4qm86lv449zcpqjn9nmamd6qrzm3wa3d7msnq2kx3yapwsp50c4l2z72hcmejj88en6eu2p8u2ypv87pw5pndzjjtclwaw0f7wds9qyyssqtqeqrvaaw92y7at9463vxhwkjdy7lpxet7h6g4vry8xyw4ar9yn8qq36dryntpf252v58c4hrf4g59z2pr25lhp06n7x4z7yltd022cqk7lc7e'
+
+  describe('validateLightningInvoice', () => {
+    it('returns success for valid invoices', () => {
+      expect(validateLightningInvoice(validLnbc)).toEqual({ success: true, type: 'invoice' })
+    })
+
+    it('returns success for a long, realistic invoice', () => {
+      const longInvoice = 'lnbc1p5mg4kmpp5xh4a2kdx625hjc7f446ktn5pzq5ht2fztv0r4sqlhpw3xr406pmqsp5fy8p4h22ggwejpvs0xen6rdejpkvf4yxxzxnneyk8u52xhq3z7fsxq9z0rgqnp4qvyndeaqzman7h898jxm98dzkm0mlrsx36s93smrur7h0azyyuxc5rzjq25carzepgd4vqsyn44jrk85ezrpju92xyrk9apw4cdjh6yrwt5jgqqqqrt49lmtcqqqqqqqqqqq86qq9qrzjqw668wp0gj9vsx8dwpt7j4qv4m7zmkklnslzj0dwwwjz20v4ad6vtapyqr6zgqqqq8hxk2qqae4jsqyugqcqzpgdqq9qyyssqj8gyv9s2gftgg0nktqj8t87qam3wcn8nfadp3qjc935r4xuna77zc4g2zapmx55cjm3kyn6ff8khttnvxw4n6qe7dur3a6fqzpldx3gpky6f6z'
+      expect(validateLightningInvoice(longInvoice)).toEqual({ success: true, type: 'invoice' })
+    })
+
+    it('strips "lightning:" prefix before validating', () => {
+      expect(validateLightningInvoice('lightning:' + validLnbc)).toEqual({ success: true, type: 'invoice' })
+    })
+
+    it('returns INVALID_LENGTH for invoices shorter than 20 chars', () => {
+      expect(validateLightningInvoice('lnbc1qyqsm94tzr')).toEqual({ success: false, reason: 'INVALID_LENGTH' })
+    })
+
+    it('returns INVALID_PREFIX for unknown prefixes', () => {
+      expect(validateLightningInvoice('lnxx1' + 'x'.repeat(20))).toEqual({ success: false, reason: 'INVALID_PREFIX' })
+    })
+
+    it('returns INVALID_BECH32_FORMAT for invalid checksum', () => {
+      const badChecksum = validLnbc.slice(0, -1) + 'q'
+      expect(validateLightningInvoice(badChecksum)).toEqual({ success: false, reason: 'INVALID_BECH32_FORMAT' })
+    })
+
+    it('returns EMPTY_ADDRESS for empty or whitespace strings', () => {
+      expect(validateLightningInvoice('')).toEqual({ success: false, reason: 'EMPTY_ADDRESS' })
+      expect(validateLightningInvoice('  ')).toEqual({ success: false, reason: 'EMPTY_ADDRESS' })
+    })
+
+    it('returns INVALID_FORMAT for non-string inputs', () => {
+      expect(validateLightningInvoice(null)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+      expect(validateLightningInvoice(undefined)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+    })
+  })
+
+  describe('validateLnurl', () => {
+    const validLnurl = 'lnurl1dp68gurn8ghj7ampd3kx2ar0veekzar0wd5xjtnrdakj7tnhv4kxctttdehhwm30d3h82unvwqhhxurj093k7mtxdae8gwfjnztwnf'
+
+    it('returns success for a valid LNURL', () => {
+      expect(validateLnurl(validLnurl)).toEqual({ success: true, type: 'lnurl' })
+      expect(validateLnurl(validLnurl.toUpperCase())).toEqual({ success: true, type: 'lnurl' })
+    })
+
+    it('returns INVALID_PREFIX for a non-lnurl bech32 string', () => {
+      expect(validateLnurl(validLnbc)).toEqual({ success: false, reason: 'INVALID_PREFIX' })
+    })
+
+    it('returns INVALID_BECH32_FORMAT for an invalid checksum', () => {
+      const badChecksum = validLnurl.slice(0, -1) + 'q'
+      expect(validateLnurl(badChecksum)).toEqual({ success: false, reason: 'INVALID_BECH32_FORMAT' })
+    })
+
+    it('returns EMPTY_ADDRESS for empty or whitespace strings', () => {
+      expect(validateLnurl('')).toEqual({ success: false, reason: 'EMPTY_ADDRESS' })
+      expect(validateLnurl('  ')).toEqual({ success: false, reason: 'EMPTY_ADDRESS' })
+    })
+
+    it('returns INVALID_FORMAT for non-string inputs', () => {
+      expect(validateLnurl(null)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+      expect(validateLnurl(undefined)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+    })
+  })
+
+  describe('validateLightningAddress', () => {
+    it('returns success for a valid email-like address', () => {
+      expect(validateLightningAddress('sprycomfort92@waletofsatoshi.com')).toEqual({ success: true, type: 'address' })
+      expect(validateLightningAddress('USER@DOMAIN.CO')).toEqual({ success: true, type: 'address' })
+    })
+
+    it('returns INVALID_FORMAT for addresses missing a dot in the domain', () => {
+      expect(validateLightningAddress('user@localhost')).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+    })
+
+    it('returns INVALID_FORMAT for other invalid formats', () => {
+      expect(validateLightningAddress('notanemail')).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+      expect(validateLightningAddress('@domain.com')).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+    })
+
+    it('returns EMPTY_ADDRESS for empty or whitespace strings', () => {
+      expect(validateLightningAddress('')).toEqual({ success: false, reason: 'EMPTY_ADDRESS' })
+      expect(validateLightningAddress('  ')).toEqual({ success: false, reason: 'EMPTY_ADDRESS' })
+    })
+
+    it('returns INVALID_FORMAT for non-string inputs', () => {
+      expect(validateLightningAddress(null)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+      expect(validateLightningAddress(undefined)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+    })
+  })
+})
+

package/tests/spark.test.js

@@ -0,0 +1,56 @@
+import { validateSparkAddress } from '../src/address-validation/spark.js'
+
+describe('validateSparkAddress', () => {
+  // Valid address provided by user.
+  const validSparkMainnet = 'spark1pgss82uvuvyjggx72gl42qk3285yz0j6lgxw9uk2mvgajsr8w22nudv8w6hqs2'
+
+  const validBtcAddress = 'bc1p4lpn5nrunrjdk6teyjd2z53vmv82hlgjvv4pejkhg9wz5jq86zuqsruz85'
+
+  describe('Valid Addresses', () => {
+    it('returns success for a mainnet Spark address', () => {
+      expect(validateSparkAddress(validSparkMainnet)).toEqual({ success: true, type: 'spark' })
+    })
+
+    it('returns success with type "btc" for a valid Bitcoin address', () => {
+      expect(validateSparkAddress(validBtcAddress)).toEqual({ success: true, type: 'btc' })
+    })
+  })
+
+  describe('Invalid Addresses', () => {
+    it('returns MIXED_CASE for a mixed-case Spark address', () => {
+      const mixedCase = 'spark1Pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu'
+      expect(validateSparkAddress(mixedCase)).toEqual({ success: false, reason: 'MIXED_CASE' })
+    })
+
+    it('returns MIXED_CASE for a mixed-case Base58 Bitcoin address', () => {
+      const mixedCase = 'mqCLm67ZP1XNTz6hDWJZ3u3dMbBZgRDrHU'
+      expect(validateSparkAddress(mixedCase)).toEqual({ success: false, reason: 'MIXED_CASE' })
+    })
+
+    it('returns INVALID_FORMAT for an address with an invalid checksum', () => {
+      const badChecksum = 'spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrha'
+      expect(validateSparkAddress(badChecksum)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+    })
+
+    it('returns INVALID_FORMAT for a Bech32m address with an unknown prefix', () => {
+      const unknownPrefix = 'unknown1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu'
+      expect(validateSparkAddress(unknownPrefix)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+    })
+
+    it('returns INVALID_FORMAT for a random short string', () => {
+      expect(validateSparkAddress('not-an-address')).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+    })
+
+    it('returns EMPTY_ADDRESS for an empty or whitespace string', () => {
+      expect(validateSparkAddress('')).toEqual({ success: false, reason: 'EMPTY_ADDRESS' })
+      expect(validateSparkAddress('  ')).toEqual({ success: false, reason: 'EMPTY_ADDRESS' })
+    })
+
+    it('returns INVALID_FORMAT for a non-string input', () => {
+      expect(validateSparkAddress(null)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+      expect(validateSparkAddress(undefined)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+      expect(validateSparkAddress(12345)).toEqual({ success: false, reason: 'INVALID_FORMAT' })
+    })
+  })
+})
+

package/tests/uma.test.js

@@ -0,0 +1,60 @@
+import {
+  validateUmaAddress,
+  resolveUmaUsername,
+} from '../src/address-validation/uma.js';
+
+describe('uma', () => {
+  const validUma = '$you@uma.money';
+  const validUma2 = '$alice@wallet.com';
+
+  describe('validateUmaAddress', () => {
+    it('returns success with type uma for valid UMA', () => {
+      expect(validateUmaAddress(validUma)).toEqual({ success: true, type: 'uma' });
+    });
+    it('accepts other valid UMA formats', () => {
+      expect(validateUmaAddress(validUma2)).toEqual({ success: true, type: 'uma' });
+      expect(validateUmaAddress('$x@a.co')).toEqual({ success: true, type: 'uma' });
+    });
+    it('returns INVALID_FORMAT for missing $', () => {
+      expect(validateUmaAddress('you@uma.money')).toEqual({ success: false, reason: 'INVALID_FORMAT' });
+    });
+    it('returns INVALID_FORMAT for invalid format', () => {
+      expect(validateUmaAddress('$no-at-sign')).toEqual({ success: false, reason: 'INVALID_FORMAT' });
+      expect(validateUmaAddress('$@domain.com')).toEqual({ success: false, reason: 'INVALID_FORMAT' });
+      expect(validateUmaAddress('$user@nodot')).toEqual({ success: false, reason: 'INVALID_FORMAT' });
+      expect(validateUmaAddress('')).toEqual({ success: false, reason: 'EMPTY_ADDRESS' });
+      expect(validateUmaAddress(null)).toEqual({ success: false, reason: 'INVALID_FORMAT' });
+    });
+    it('trims input', () => {
+      expect(validateUmaAddress('  ' + validUma + '  ')).toEqual({ success: true, type: 'uma' });
+    });
+  });
+
+  describe('resolveUmaUsername', () => {
+    it('resolves UMA into localPart, domain, and lightningAddress', () => {
+      expect(resolveUmaUsername(validUma)).toEqual({
+        localPart: 'you',
+        domain: 'uma.money',
+        lightningAddress: 'you@uma.money',
+      });
+      expect(resolveUmaUsername(validUma2)).toEqual({
+        localPart: 'alice',
+        domain: 'wallet.com',
+        lightningAddress: 'alice@wallet.com',
+      });
+    });
+    it('returns null for invalid UMA', () => {
+      expect(resolveUmaUsername('you@uma.money')).toBe(null);
+      expect(resolveUmaUsername('')).toBe(null);
+      expect(resolveUmaUsername(null)).toBe(null);
+      expect(resolveUmaUsername('$bad')).toBe(null);
+    });
+    it('trims input', () => {
+      expect(resolveUmaUsername('  $you@uma.money  ')).toEqual({
+        localPart: 'you',
+        domain: 'uma.money',
+        lightningAddress: 'you@uma.money',
+      });
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "include": [
+    "index.js",
+    "src/**/*.js",
+  ],
+  "compilerOptions": {
+    "target": "ES2015",
+    "module": "NodeNext",
+    "moduleResolution": "nodenext",
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "skipLibCheck": true,
+    "stripInternal": true,
+    "outDir": "./types"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/address-validation/index.js";

package/types/src/address-validation/bitcoin.d.ts

@@ -0,0 +1,35 @@
+export function validateBase58(address: any): BtcAddressValidationSuccess | {
+    decoded: Uint8Array;
+} | {
+    success: boolean;
+    reason: string;
+};
+/**
+ * Validates a Bech32 address for any supported network.
+ * @param {string} address - The address to validate.
+ * @returns {BtcAddressValidationResult}
+ */
+export function validateBech32(address: string): BtcAddressValidationResult;
+/**
+ * Validates a Bech32m address for any supported network.
+ * @param {string} address - The address to validate.
+ * @returns {BtcAddressValidationResult}
+ */
+export function validateBech32m(address: string): BtcAddressValidationResult;
+/**
+ * Validates a Bitcoin address for mainnet or testnet.
+ *
+ * @param {string} address The address to validate.
+ * @returns {BtcAddressValidationResult}
+ */
+export function validateBitcoinAddress(address: string): BtcAddressValidationResult;
+export type BtcAddressValidationSuccess = {
+    success: true;
+    type: "p2pkh" | "p2sh" | "bech32" | "bech32m";
+    network: "mainnet" | "testnet" | "regtest";
+};
+export type BtcAddressValidationFailure = {
+    success: false;
+    reason: string;
+};
+export type BtcAddressValidationResult = BtcAddressValidationSuccess | BtcAddressValidationFailure;

package/types/src/address-validation/evm.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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: string): EvmAddressValidationResult;
+export type EvmAddressValidationSuccess = {
+    success: true;
+    type: "evm";
+};
+export type EvmAddressValidationFailure = {
+    success: false;
+    reason: string;
+};
+export type EvmAddressValidationResult = EvmAddressValidationSuccess | EvmAddressValidationFailure;

package/types/src/address-validation/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./bitcoin.js";
+export * from "./evm.js";
+export * from "./lightning.js";
+export * from "./spark.js";
+export * from "./uma.js";

package/types/src/address-validation/lightning.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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: string): string;
+/**
+ * Validates a Lightning Network invoice (lnbc, lntb, lnbcrt, lni; length >= 20).
+ *
+ * @param {string} address The invoice to validate.
+ * @returns {LightningInvoiceValidationResult}
+ */
+export function validateLightningInvoice(address: string): LightningInvoiceValidationResult;
+/**
+ * Validates an LNURL address (lnurl1... bech32 encoded URL).
+ *
+ * @param {string} address The LNURL to validate.
+ * @returns {LnurlValidationResult}
+ */
+export function validateLnurl(address: string): LnurlValidationResult;
+/**
+ * Validates Lightning Address format (email: user@domain.tld).
+ *
+ * @param {string} address The address to validate.
+ * @returns {LightningAddressValidationResult}
+ */
+export function validateLightningAddress(address: string): LightningAddressValidationResult;
+export type LightningInvoiceValidationSuccess = {
+    success: true;
+    type: "invoice";
+};
+export type LightningInvoiceValidationFailure = {
+    success: false;
+    reason: string;
+};
+export type LightningInvoiceValidationResult = LightningInvoiceValidationSuccess | LightningInvoiceValidationFailure;
+export type LnurlValidationSuccess = {
+    success: true;
+    type: "lnurl";
+};
+export type LnurlValidationFailure = {
+    success: false;
+    reason: string;
+};
+export type LnurlValidationResult = LnurlValidationSuccess | LnurlValidationFailure;
+export type LightningAddressValidationSuccess = {
+    success: true;
+    type: "address";
+};
+export type LightningAddressValidationFailure = {
+    success: false;
+    reason: string;
+};
+export type LightningAddressValidationResult = LightningAddressValidationSuccess | LightningAddressValidationFailure;

package/types/src/address-validation/spark.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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: string): SparkAddressValidationResult;
+export type SparkAddressValidationSuccess = {
+    success: true;
+    type: "spark" | "btc";
+};
+export type SparkAddressValidationFailure = {
+    success: false;
+    reason: string;
+};
+export type SparkAddressValidationResult = SparkAddressValidationSuccess | SparkAddressValidationFailure;

package/types/src/address-validation/uma.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Validates a Universal Money Address (format: $user@domain.tld).
+ *
+ * @param {string} address The address to validate.
+ * @returns {UmaAddressValidationResult}
+ */
+export function validateUmaAddress(address: string): UmaAddressValidationResult;
+/**
+ * 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: string): {
+    localPart: string;
+    domain: string;
+    lightningAddress: string;
+} | null;
+export type UmaAddressValidationSuccess = {
+    success: true;
+    type: "uma";
+};
+export type UmaAddressValidationFailure = {
+    success: false;
+    reason: string;
+};
+export type UmaAddressValidationResult = UmaAddressValidationSuccess | UmaAddressValidationFailure;