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, 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.

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 and .txid when it doesn't. 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_validate_txid 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.