Address validation

The call

import { getChain, InvalidAddressError } from "@agntn/chains";

const bitcoin = getChain("btc");

bitcoin.validatesAddress; // true
bitcoin.assertAddress("bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"); // returns the address

try {
  bitcoin.assertAddress("bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t5");
} catch (error) {
  error instanceof InvalidAddressError; // true, the checksum caught the last digit
  (error as InvalidAddressError).chain; // "bitcoin"
  (error as InvalidAddressError).reason; // "the Bech32 checksum does not hold, so a character is wrong"
}

chain.assertAddress(address) returns the address when it fits the chain's format and throws InvalidAddressError when it doesn't. Chains without a validator throw AddressValidationUnsupportedError instead of quietly saying yes, and chain.validatesAddress tells you which ones those are before you ask. Right now every built-in chain validates. A false green light costs more than a false alarm when the caller is about to send funds.

An EVM rejection also says why, in .reason and at the end of the message. 39 hex digits after 0x, not 40 is a digit lost in the copy. the mixed case does not match the EIP-55 checksum means the digits are there but one of them, or one letter's case, is wrong. The CLI and the agent tools print the reason too, so a model knows what to fix instead of sending the string again. Bitcoin and the chains on its encodings say why as well. the Base58Check checksum does not hold, so a character is wrong is a typo. version byte 0x00, where this chain writes 0x1e or 0x16 is a Bitcoin address pasted where Dogecoin was asked for. a Bech32 checksum under witness version 1, where BIP-350 wants Bech32m is an encoder still on the old checksum. Every rule the address breaks goes into one answer, so a string cut short on the wrong chain hears about its length, its version byte and its checksum at once. That covers Litecoin, Bitcoin Gold, Dogecoin, Pepecoin, Dash, Bitcoin SV, TRON and Decred. The other families still decode to a plain yes or no, so their errors carry no .reason yet.

The library doesn't trim. assertAddress(" bc1q…") fails on the space. The CLI's validate passes the argument through as typed too. The agent tools do trim, because an address lifted out of a log line keeps its trailing newline and one invisible byte should not turn a good address into a bad one.

Why decode

Character counts aren't enough. A 34-character window takes a Bitcoin legacy address and a TRON address, both 25 bytes of Base58Check under different version bytes. Solana's System Program is 32 characters and 32 bytes, a Bitcoin address is 34 characters and 25 bytes. So the base58 validators decode and look at the bytes, and the Base58Check ones hash the last four against the rest. The Bech32 validators run the polymod. And Octra is the one base58 chain where decoding would be wrong: a contract address there is cut out of a base58 string rather than encoded from a payload, so the width is the whole format.

What each family checks

Mixed case fails on every Bech32 and CashAddr chain, all upper or all lower passes, as the specs say. On an EVM chain mixed case is the checksum, so it has to match, and one case throughout is the unchecksummed form every wallet accepts. Testnet forms are rejected everywhere the format can tell: Bitcoin's version bytes, TON's testnet flag, Monero's network byte, XRP's testnet X-address prefix, the network magic a Byron address carries only on a test network.

What it pays to

The validator takes the address apart to check it. Then it says yes and throws the parts away. Bit of a waste, right? decodeAddress runs the same check and keeps them:

import { getChain } from "@agntn/chains";

getChain("btc").decodeAddress("1Fo65aKq8s8iquMt6weF1rku1moWVEd5Ua");
// { kind: "p2pkh", payload: "a24922852051a9002ebf4c864a55acb75bb4cf75", hash: "hash160" }
getChain("bch").decodeAddress("bitcoincash:qz3yjg59ypg6jqpwhaxgvjj44jm4hdx0w5wsxw2qez");
// { kind: "p2pkh", payload: "a24922852051a9002ebf4c864a55acb75bb4cf75", hash: "hash160" }
getChain("dcr").decodeAddress("DeeUhrRoTp4DftsqddVW96yMGMW4sgQFYUE");
// { kind: "p2pkh", payload: "456d8ee57a4b9121987b4ecab8c3bcb5797e8a53", hash: "ripemd160-blake256", signature: "ed25519" }
getChain("eth").decodeAddress("0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984");
// { kind: "account" }

Same hash twice. That's one key, paid on two chains, and no block explorer was needed to see it.

A bad address throws the same InvalidAddressError as assertAddress, same .reason too. Nothing new to catch. payload is lowercase hex of whatever the address pays to. hash names the digest behind it. That matters on Decred, where the hash is RIPEMD-160 of BLAKE-256 and only looks like a HASH160.

A Unified Address and a Byron address get no payload. A Unified Address bundles several receivers, and picking one would be a guess. A Byron root hashes the spending data together with its attributes, so it isn't a key or script hash at all. A base address carries a stake credential too, but the coins sit behind the payment one, so that's the one you get. A custom chain on UTXO won't guess either. Until you override decodeAddress, it throws AddressDecodingUnsupportedError. The agent tools and chains validate print the kind and payload after a valid address.

Move addresses and EVM addresses

Aptos and Sui want all 32 bytes of hex written out, or the single digit short form AIP-40 defines for the special addresses, which is how the framework address 0x1 is actually written. Anything in between stays rejected. Accepting dropped leading zeros would make every EVM address a valid Move address too, and identify would report a family nobody asked about.

Transaction ids

import { getChain } from "@agntn/chains";

getChain("btc").assertTxid("4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b"); // the genesis coinbase, returned
getChain("sol").assertTxid("4AwYqQ8RbD6yhTbE9h38YiYufC7UHJfxzhP3BZsEoJRp4cY6TzphNFEsUWMjkrKNjE5dFMbBoxVwvr9m8vJukavE"); // a signature, 64 bytes of base58
getChain("xlm").validatesTxid; // true, on every chain that ships

assertTxid is the same contract for a transaction id: the string back when it fits, InvalidTxidError with .chain, .txid and .reason when it doesn't. Every built-in chain fills in the reason. A Bitcoin txid pasted with 0x comes back with 0x in front, which this chain's txids never carry, an uppercase Stellar hash with uppercase hex digits, and this chain reads lowercase only. It's a shape check and nothing else, there's no transaction to hash. Each rule is what the chain's own node writes and reads, so the case rules differ where the readers do.

A custom chain that never overrides assertTxid throws TxidValidationUnsupportedError, and validatesTxid says false there before you ask. chains_txid_validate and chains validate --txid are the same check for a model and for the terminal.

Where this stops

None of this touches a network. Not existence, not balances, not whether a contract sits at the address. That belongs in @agntn/nodes, and the Playground says the same thing under every green result.