multichain-address-validator 0.7.8 → 0.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "multichain-address-validator",
     "description": "Multichain address validator for Bitcoin and other blockchains.",
-    "version": "0.7.8",
+    "version": "0.8.0",
     "keywords": [
         "0x",
         "zrx",

package/src/chain-validators.ts

@@ -4,6 +4,7 @@ import { NetworkType } from './types.js'
 import {
     AlgorandValidator,
     BCHValidator,
+    BittensorValidator,
     BTCValidator,
     CardanoValidator,
     EOSValidator,
@@ -20,7 +21,9 @@ import {
     TezosValidator,
     TronValidator,
     XLMValidator,
+    ZcashValidator,
 } from './validators/index.js'
+import {SegwitVersion} from './validators/bitcoin_validator'
 
 
 type ChainValidators = Record<string, {
@@ -40,10 +43,12 @@ const chainValidators: ChainValidators = {
             mainnet: BTCValidator({
                 addressTypes: ['00', '05'],
                 bech32Hrp: ['bc'],
+                allowedSegwitVersions: [SegwitVersion.NativeSegwit],
             }),
             testnet: BTCValidator({
                 addressTypes: ['6f', 'c4', '3c', '26'],
                 bech32Hrp: ['tb'],
+                allowedSegwitVersions: [SegwitVersion.NativeSegwit],
             }),
         },
     },
@@ -62,6 +67,10 @@ const chainValidators: ChainValidators = {
             }),
         }
     },
+    bittensor: {
+        alternatives: ['tao'],
+        validator: BittensorValidator,
+    },
     cardano: {
         alternatives: ['ada'],
         validator: CardanoValidator,
@@ -106,10 +115,12 @@ const chainValidators: ChainValidators = {
             mainnet: BTCValidator({
                 addressTypes: ['30', '32'],
                 bech32Hrp: ['ltc'],
+                allowedSegwitVersions: [SegwitVersion.NativeSegwit],
             }),
             testnet: BTCValidator({
                 addressTypes: ['6f', 'c4', '3a'],
-                bech32Hrp: ['tltc']
+                bech32Hrp: ['tltc'],
+                allowedSegwitVersions: [SegwitVersion.NativeSegwit],
             })
         }
     },
@@ -119,6 +130,10 @@ const chainValidators: ChainValidators = {
             testnet: MoneroValidator(NetworkType.TestNet),
         }
     },
+    monad: {
+        alternatives: ['mon'],
+        validator: ETHValidator,
+    },
     nem: {validator: NemValidator},
     nano: {validator: NanoValidator},
     polkadot: {validator: PolkadotValidator},
@@ -144,6 +159,13 @@ const chainValidators: ChainValidators = {
         alternatives: ['stellar', 'stellarlumens'],
         validator: XLMValidator,
     },
+    zcash: {
+        alternatives: ['zec'],
+        validator: {
+            mainnet: ZcashValidator(NetworkType.MainNet),
+            testnet: ZcashValidator(NetworkType.TestNet),
+        }
+    },
 }
 
 export function getValidatorForChain(chain: Chain): Validator | undefined {

package/src/crypto/segwit_addr.js

@@ -93,12 +93,18 @@ function isValidAddress(address, opts = {}) {
         return false;
     }
 
+    if (!opts.allowedSegwitVersions?.length) {
+        return false;
+    }
+
     const correctBech32Hrps = opts.bech32Hrp;
 
-    for(var chrp of correctBech32Hrps) {
-        var ret = decode(chrp, address);
+    for(const chrp of correctBech32Hrps) {
+        const ret = decode(chrp, address);
         if(ret) {
-            return encode(chrp, ret.version, ret.program) === address.toLowerCase();
+            if (opts.allowedSegwitVersions.includes(ret.version)) {
+                return encode(chrp, ret.version, ret.program) === address.toLowerCase();
+            }
         }
     }
 

package/src/index.ts

@@ -23,5 +23,6 @@ export type { Address, Chain }
 export { NetworkType }
 
 export default {
-    validate
+    validate,
+    validateMemo
 }

package/src/validators/bitcoin_validator.ts

@@ -71,24 +71,23 @@ function isValidP2PKHandP2SHAddress(address: string, opts: BTCValidatorOpts) {
     return false;
 }
 
+export enum SegwitVersion {
+    NativeSegwit = 0,
+    TapRoot = 1,
+}
 
 interface BTCValidatorOpts {
     addressTypes: string[],
     expectedLength?: number,
     bech32Hrp?: [string],
+    allowedSegwitVersions?: [number],
     hashFunction?: 'blake256' | 'blake256keccak256' | 'keccak256' | 'sha256',
     regex?: RegExp,
 }
 
-// const DefaultBTCValidatorOpts: BTCValidatorOpts = {
-//     addressTypes: {mainnet: ['00', '05'], testnet: ['6f', 'c4', '3c', '26']},
-//     bech32Hrp: {mainnet: ['bc'], testnet: ['tb']},
-// }
-
 export default (opts: BTCValidatorOpts) => ({
     isValidAddress(address: Address): boolean {
         const addr = getAddress(address)
-        // const _opts = {...DefaultBTCValidatorOpts, ...opts}
         return isValidP2PKHandP2SHAddress(addr, opts) || segwit.isValidAddress(addr, opts);
     }
 })

package/src/validators/bittensor_validator.ts

@@ -0,0 +1,8 @@
+import createSS58Validator from './ss58_validator.js'
+
+// Bittensor uses SS58 address format (Substrate-based) with network prefix 42
+// Reference: https://docs.learnbittensor.org/evm-tutorials/convert-h160-to-ss58
+// SS58 Registry: https://github.com/paritytech/ss58-registry
+
+// Network prefix 42 (0x2A in hex) is used by Bittensor
+export default createSS58Validator({ networkPrefix: 42 })

package/src/validators/index.ts

@@ -1,5 +1,6 @@
 export {default as AlgorandValidator} from "./algorand_validator.js"
 export {default as BCHValidator} from "./bch_validator.js"
+export {default as BittensorValidator} from "./bittensor_validator.js"
 export {default as BTCValidator} from "./bitcoin_validator.js"
 export {default as CardanoValidator} from "./cardano_validator.js"
 export {default as EOSValidator} from "./eos_validator.js"
@@ -16,3 +17,4 @@ export {default as SolanaValidator} from "./solana_validator.js"
 export {default as TezosValidator} from "./tezos_validator.js"
 export {default as TronValidator} from "./tron_validator.js"
 export {default as XLMValidator} from "./xlm_validator.js"
+export {default as ZcashValidator} from "./zcash_validator.js"

package/src/validators/polkadot_validator.ts

@@ -1,57 +1,7 @@
-import cryptoUtils from '../crypto/utils.js'
-import {Address} from '../types.js'
-import {getAddress} from '../helpers.js'
+import createSS58Validator from './ss58_validator.js'
 
-// from https://github.com/paritytech/substrate/wiki/External-Address-Format-(SS58)
-const addressFormats = [
-    {addressLength: 3, accountIndexLength: 1, checkSumLength: 1},
-    {addressLength: 4, accountIndexLength: 2, checkSumLength: 1},
-    {addressLength: 5, accountIndexLength: 2, checkSumLength: 2},
-    {addressLength: 6, accountIndexLength: 4, checkSumLength: 1},
-    {addressLength: 7, accountIndexLength: 4, checkSumLength: 2},
-    {addressLength: 8, accountIndexLength: 4, checkSumLength: 3},
-    {addressLength: 9, accountIndexLength: 4, checkSumLength: 4},
-    {addressLength: 10, accountIndexLength: 8, checkSumLength: 1},
-    {addressLength: 11, accountIndexLength: 8, checkSumLength: 2},
-    {addressLength: 12, accountIndexLength: 8, checkSumLength: 3},
-    {addressLength: 13, accountIndexLength: 8, checkSumLength: 4},
-    {addressLength: 14, accountIndexLength: 8, checkSumLength: 5},
-    {addressLength: 15, accountIndexLength: 8, checkSumLength: 6},
-    {addressLength: 16, accountIndexLength: 8, checkSumLength: 7},
-    {addressLength: 17, accountIndexLength: 8, checkSumLength: 8},
-    {addressLength: 34, accountIndexLength: 32, checkSumLength: 2},
-];
+// Polkadot uses SS58 address format (Substrate-based)
+// SS58 Registry: https://github.com/paritytech/ss58-registry
+// Accepts any valid SS58 address (no network prefix restriction)
 
-function verifyChecksum(address: string) {
-    try {
-        const preImage = '53533538505245'
-        const decoded = cryptoUtils.base58(address);
-        const addressType = cryptoUtils.byteArray2hexStr(decoded.slice(0, 1));
-        const addressAndChecksum = decoded.slice(1)
-
-        // get the address format
-        const addressFormat = addressFormats.find(af => af.addressLength === addressAndChecksum.length);
-
-        if (!addressFormat) {
-            throw new Error('Invalid address length');
-        }
-
-        const decodedAddress = cryptoUtils.byteArray2hexStr(addressAndChecksum.slice(0, addressFormat.accountIndexLength));
-        const checksum = cryptoUtils.byteArray2hexStr(addressAndChecksum.slice(-addressFormat.checkSumLength));
-
-        const calculatedHash = cryptoUtils
-            .blake2b(preImage + addressType + decodedAddress, 64)
-            .substr(0, addressFormat.checkSumLength * 2)
-            .toUpperCase();
-
-        return calculatedHash == checksum;
-    } catch (err) {
-        return false;
-    }
-}
-
-export default {
-    isValidAddress(address: Address) {
-        return verifyChecksum(getAddress(address))
-    },
-}
+export default createSS58Validator()

package/src/validators/ss58_validator.ts

@@ -0,0 +1,80 @@
+import cryptoUtils from '../crypto/utils.js'
+import {Address, Validator} from '../types.js'
+import {getAddress} from '../helpers.js'
+
+// SS58 address format (Substrate-based)
+// SS58 Registry: https://github.com/paritytech/ss58-registry
+const addressFormats = [
+    {addressLength: 3, accountIndexLength: 1, checkSumLength: 1},
+    {addressLength: 4, accountIndexLength: 2, checkSumLength: 1},
+    {addressLength: 5, accountIndexLength: 2, checkSumLength: 2},
+    {addressLength: 6, accountIndexLength: 4, checkSumLength: 1},
+    {addressLength: 7, accountIndexLength: 4, checkSumLength: 2},
+    {addressLength: 8, accountIndexLength: 4, checkSumLength: 3},
+    {addressLength: 9, accountIndexLength: 4, checkSumLength: 4},
+    {addressLength: 10, accountIndexLength: 8, checkSumLength: 1},
+    {addressLength: 11, accountIndexLength: 8, checkSumLength: 2},
+    {addressLength: 12, accountIndexLength: 8, checkSumLength: 3},
+    {addressLength: 13, accountIndexLength: 8, checkSumLength: 4},
+    {addressLength: 14, accountIndexLength: 8, checkSumLength: 5},
+    {addressLength: 15, accountIndexLength: 8, checkSumLength: 6},
+    {addressLength: 16, accountIndexLength: 8, checkSumLength: 7},
+    {addressLength: 17, accountIndexLength: 8, checkSumLength: 8},
+    {addressLength: 34, accountIndexLength: 32, checkSumLength: 2},
+];
+
+interface SS58ValidatorOptions {
+    // Network prefix to validate (in decimal). If provided, only addresses with this prefix are valid.
+    // Examples: 0 = Polkadot, 2 = Kusama, 42 = Substrate/Bittensor
+    networkPrefix?: number;
+}
+
+/**
+ * Creates an SS58 validator with optional network prefix filtering
+ * @param options Configuration options including optional network prefix
+ * @returns Validator instance for SS58 addresses
+ */
+export default function createSS58Validator(options: SS58ValidatorOptions = {}): Validator {
+    function verifyChecksum(address: string): boolean {
+        try {
+            const preImage = '53533538505245'
+            const decoded = cryptoUtils.base58(address);
+            const addressType = cryptoUtils.byteArray2hexStr(decoded.slice(0, 1));
+
+            // If a specific network prefix is required, validate it
+            if (options.networkPrefix !== undefined) {
+                const expectedPrefix = options.networkPrefix.toString(16).padStart(2, '0').toUpperCase();
+                if (addressType.toUpperCase() !== expectedPrefix) {
+                    return false;
+                }
+            }
+
+            const addressAndChecksum = decoded.slice(1)
+
+            // get the address format
+            const addressFormat = addressFormats.find(af => af.addressLength === addressAndChecksum.length);
+
+            if (!addressFormat) {
+                throw new Error('Invalid address length');
+            }
+
+            const decodedAddress = cryptoUtils.byteArray2hexStr(addressAndChecksum.slice(0, addressFormat.accountIndexLength));
+            const checksum = cryptoUtils.byteArray2hexStr(addressAndChecksum.slice(-addressFormat.checkSumLength));
+
+            const calculatedHash = cryptoUtils
+                .blake2b(preImage + addressType + decodedAddress, 64)
+                .substr(0, addressFormat.checkSumLength * 2)
+                .toUpperCase();
+
+            return calculatedHash == checksum;
+        } catch (err) {
+            return false;
+        }
+    }
+
+    return {
+        isValidAddress(address: Address) {
+            return verifyChecksum(getAddress(address))
+        },
+    }
+}

package/src/validators/zcash_validator.ts

@@ -0,0 +1,57 @@
+import base58 from '../crypto/base58.js'
+import cryptoUtils from '../crypto/utils.js'
+import {Address, NetworkType} from '../types.js'
+import {getAddress} from '../helpers.js'
+
+function getDecoded(address: string) {
+    try {
+        return base58.decode(address);
+    } catch (e) {
+        // if decoding fails, assume invalid address
+        return null;
+    }
+}
+
+function getChecksum(payload: any) {
+    return cryptoUtils.sha256Checksum(payload);
+}
+
+function isValidTransparentAddress(address: string, networkType: NetworkType) {
+    // Zcash transparent addresses use 2-byte version prefixes
+    // Expected length: 26 bytes (2 bytes version + 20 bytes payload + 4 bytes checksum)
+    const expectedLength = 26;
+    const decoded = getDecoded(address);
+
+    if (!decoded || decoded.length !== expectedLength) {
+        return false;
+    }
+
+    const checksum = cryptoUtils.toHex(decoded.slice(expectedLength - 4, expectedLength));
+    const body = cryptoUtils.toHex(decoded.slice(0, expectedLength - 4));
+    const goodChecksum = getChecksum(body);
+
+    if (checksum !== goodChecksum) {
+        return false;
+    }
+
+    // Get the 2-byte version prefix
+    const versionPrefix = cryptoUtils.toHex(decoded.slice(0, 2));
+
+    // Define valid version prefixes for each network
+    // Only supporting transparent addresses (t1/t3 for mainnet, tm/t2 for testnet)
+    const validPrefixes = networkType === NetworkType.MainNet
+        ? ['1cb8', '1cbd'] // t1 (P2PKH) and t3 (P2SH) for mainnet
+        : ['1d25', '1cba']; // tm (P2PKH) and t2 (P2SH) for testnet
+
+    return validPrefixes.includes(versionPrefix);
+}
+
+export default (networkType: NetworkType) => ({
+    isValidAddress(address: Address): boolean {
+        const addr = getAddress(address);
+
+        // Only validate transparent addresses (t1/t3 for mainnet, tm/t2 for testnet)
+        // Sapling (zs) and Unified (u) addresses are NOT supported
+        return isValidTransparentAddress(addr, networkType);
+    }
+})

package/test/addresses/addresses.ts

@@ -2,6 +2,7 @@ import algorand from './algorand.json'
 import aptos from './aptos.json'
 import bch from './bch.json'
 import bchTestnet from './bch-testnet.json'
+import bittensor from './bittensor.json'
 import btc from './btc.json'
 import btcTestnet from './btc-testnet.json'
 import cardano from './cardano.json'
@@ -24,6 +25,7 @@ import sui from './sui.json'
 import tezos from './tezos.json'
 import tron from './tron.json'
 import xlm from './xlm.json'
+import zcash from './zcash.json'
 
 export type TestAddress = string | { address: string, memo?: string } & { invalid?: boolean, invalidMemo?: boolean }
 
@@ -32,6 +34,7 @@ const testAddresses: Record<string, TestAddress[]> = {
     algorand,
     bch,
     'bch-testnet': bchTestnet,
+    bittensor,
     btc,
     'btc-testnet': btcTestnet,
     cardano,
@@ -54,6 +57,7 @@ const testAddresses: Record<string, TestAddress[]> = {
     tezos,
     tron,
     xlm,
+    zcash,
 } as const;
 
 export default testAddresses

package/test/addresses/bittensor.json

@@ -0,0 +1,27 @@
+[
+    "5CS9x5NsPHpb2THeS92zBYCSSk4MFoQjjx76DB8bEzeJTTSt",
+    "5CZmB94iEG4Ld7JkejAWToAw7NKEfV3YZHX7FYaqPGh7isXe",
+    "5DA7UsaYbk1UnhhtTxqpwdqjuxhQ2rW7D6GTN1S1S5tC2NRV",
+    "5HGjWAeFDfFCWPsjFQdVV2Msvz2XtMktvgocEZcCj68kUMaw",
+    "5DAAnrj7VHTznn2AWBemMuyBwZWs6FNFjdyVXUeYum3PTXFy",
+    "5HpG9w8EBLe5XCrbczpwq5TSXvedjrBGCwqxK1iQ7qUsSWFc",
+    "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL",
+    "5GNJqTPyNqANBkUVMN1LPPrxXnFouWXoe2wNSmmEoLctxiZY",
+    "5Gs5ung9YhbXjrEx469w5V9C6V8nEVM6XS9CzMMq1tq16cMt",
+    {
+        "address": "1iQPKJmghHbrRhUiMt2cNEuxYbR6S9vYtJKqYvE4PNR9WDB",
+        "invalid": true
+    },
+    {
+        "address": "invalid_ss58_address",
+        "invalid": true
+    },
+    {
+        "address": "0x1234567890abcdef",
+        "invalid": true
+    },
+    {
+        "address": "123",
+        "invalid": true
+    }
+]

package/test/addresses/btc-testnet.json

@@ -8,6 +8,7 @@
     "GSa5espVLNseXEfKt46zEdS6jrPkmFghBU",
     "tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3q0sl5k7",
     "tb1qqqqqp399et2xygdj5xreqhjjvcmzhxw4aywxecjdzew6hylgvsesrxh6hy",
+    "2My6YWQy9Umh52TFwhRA5CXHZQVLFoB39vJ",
     "mxHzYDeCZD8qzvfVzTqPS65p23inGkRvXT",
     "2N3ATmqPqnHR243HiwtqpCFwSsNdTiCvmmv"
 ]

package/test/addresses/btc.json

@@ -10,5 +10,9 @@
     "1SQHtwR5oJRKLfiWQ2APsAd9miUc4k2ez",
     "116CGDLddrZhMrTwhCVJXtXQpxygTT1kHd",
     "3NJZLcZEEYBpxYEUGewU4knsQRn1WM5Fkt",
-    "bc1q2t63ewm3mvh0ztmnmezxm7s0tefknenxlrlwrk"
+    "bc1q2t63ewm3mvh0ztmnmezxm7s0tefknenxlrlwrk",
+    {
+        "address": "bc1pmr3w69uk09zqez3vy4l0jjws7uwa9fmljag2mwumfx9rr6045g8scr7nn3",
+        "invalid": true
+    }
 ]

package/test/addresses/ltc.json

@@ -4,5 +4,6 @@
     "Lb6wDP2kHGyWC7vrZuZAgV7V4ECyDdH7a6",
     "ltc1qg42tkwuuxefutzxezdkdel39gfstuap288mfea",
     "ltc1qg42tkwuuxefutzxezdkdel39gfstuap288mfea",
+    "ltc1qhxka8d59lylj76rpsflhagp76nvckggd8x0tt7jtnphpkmfv3snsk6suq0",
     "LLUvRjeoNCa1gRuoVzFAzr3pWdu21JJESa"
 ]

package/test/addresses/zcash.json

@@ -0,0 +1,8 @@
+[
+    "t1NN6mnj4gaMX4aL4C2B29ekFgLttT9B1jM",
+    "t1ZVi2YGk98tEGYcNpXYnJFWCoLG2oYwv3J",
+    "t3cFfPt1Bcvgez9ZbMBFWeZsskxTkPzGCow",
+    "t1at7nVNsv6taLRrNRvnQdtfLNRDfsGc3Ak",
+    "t1MYWFMnMbazMP3U8ZCASfdamy6JY5inevP",
+    "t1a7EMsA9HxrBgPmLYUUq3iBijnDvfgptGJ"
+]

package/test/multichain-address-validator.test.ts

@@ -84,6 +84,11 @@ const TestCases: Record<string, TestCase> = {
             testAddresses: 'bch-testnet',
         }
     },
+    'bittensor': {
+        alternatives: ['tao'],
+        testAddresses: 'bittensor',
+        exclude: ['polkadot'],
+    },
     'cardano': {
         alternatives: ['ada'],
         testAddresses: 'cardano',
@@ -112,6 +117,7 @@ const TestCases: Record<string, TestCase> = {
             'bsc',
             'eth',
             'flare',
+            'monad',
             'optimism',
             'sonic',
             'story',
@@ -137,6 +143,11 @@ const TestCases: Record<string, TestCase> = {
             testAddresses: 'monero-testnet',
         }
     },
+    'monad': {
+        alternatives: ['mon'],
+        testAddresses: 'evm',
+        exclude: ['evm'],
+    },
     'nano': {
         alternatives: [],
         testAddresses: 'nano',
@@ -148,6 +159,7 @@ const TestCases: Record<string, TestCase> = {
     'polkadot': {
         alternatives: [],
         testAddresses: 'polkadot',
+        exclude: ['bittensor'],
     },
     'ripple': {
         alternatives: ['xrp'],
@@ -169,7 +181,7 @@ const TestCases: Record<string, TestCase> = {
     'tezos': {
         alternatives: [],
         testAddresses: 'tezos',
-        exclude: ['btc', 'bch', 'btc-testnet', 'ltc-testnet', 'bch-testnet', 'doge', 'doge-testnet', 'ltc', 'tron'],
+        exclude: ['btc', 'bch', 'btc-testnet', 'ltc-testnet', 'bch-testnet', 'doge', 'doge-testnet', 'ltc', 'tron', 'zcash'],
     },
     'tron': {
         alternatives: ['trc20'],
@@ -178,6 +190,11 @@ const TestCases: Record<string, TestCase> = {
     'xlm': {
         alternatives: ['stellar', 'stellarlumens'],
         testAddresses: 'xlm',
+    },
+    'zcash': {
+        alternatives: ['zec'],
+        testAddresses: 'zcash',
+        exclude: ['tezos'],
     }
 }