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"
}

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.

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. 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. 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. Cardano's Byron form is the one exception, its network hides in an attribute the check doesn't open.

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.

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.