CAIP Chain-Agnostic Identifiers

A receipt that names a chain, an account or an asset carries a CAIP identifier. CAIP-2 names the chain (eip155:1), CAIP-10 names an account on that chain (eip155:1:0xAb16a9...), and CAIP-19 names an asset (eip155:1/slip44:60). When such an identifier is folded into a canonicalised, content-addressed record, it stops being a display string and becomes part of the hash preimage. Two verifiers must agree on its exact bytes or their digests diverge and the record stops recomputing. So the question is not merely whether an identifier is valid. It must be byte-canonical. That makes identifier validation a substrate concern rather than an application concern, and it is why it sits next to JCS canonicalisation in the same package.

The trailing-newline anchor trap

This is the failure that motivates the module, and it is a genuine cross-language divergence rather than a quirk of one runtime. Consider validating a CAIP-2 chain id with a regex anchored as ^...$, then hashing the string:

"eip155:1\n"

Whether that input is accepted depends on the language the verifier is written in:

Behaviour of `$` (no multiline flag)	Languages
Also matches just before a trailing newline, so `"eip155:1\n"` is accepted	Python, Java, PHP (PCRE), Ruby (line-anchored)
Matches only at end of input, so `"eip155:1\n"` is rejected	Go (RE2), Rust, JavaScript

A producer in one language accepts the trailing newline and hashes the identifier with the newline. A verifier in another language rejects it, or accepts the clean identifier and hashes without it. Both parties believe they validated correctly, yet the digests differ by one byte and the record fails to recompute. This table is measured, not reasoned. The caip_edge_v1 conformance set runs 102 adversarial identifiers through eight implementations across the seven languages above. All eight validate 102/102 under the correct anchors; under a naive ^...$ the over-acceptance counts are Python 3, Java 8, PHP 3, Ruby 5, and Go, Rust and JavaScript 0. Opting into line anchors reverts the last three to the same defect, so the fault is the anchor rather than the language. Full matrix with engine versions: seven-engine attestation. The substrate therefore anchors with \A and \Z (Python) and without the multiline flag (TypeScript), which have no trailing-newline exception in any of the above:

Anchor discipline is load-bearing. require_caip2("eip155:1\n") raises rather than returning a value that would silently produce a non-reproducible digest. The strict require_* forms are the pre-hash gate: they fail closed before a non-canonical identifier ever reaches the digest.

Three validation tiers

The tiers are additive and opt-in. Chain-agnostic by default, strict where you ask for it.

1. Grammar

is_caip2 / isCaip2The CAIP grammar only. A future or not-yet-registered chain still validates, so the substrate does not become a gatekeeper on which chains may exist.

2. Registered namespace

is_registered_caip2 / isRegisteredCaip2Additionally requires a namespace registered in ChainAgnostic/namespaces, such as eip155, solana, cosmos, xrpl.

3. Reference format

is_valid_caip2 / isValidCaip2Strictest. Additionally requires the chain reference to be well formed for its namespace, so eip155:abc is rejected because eip155 references are decimal.

Each tier has a require_* counterpart (require_caip*, require_registered_caip*, require_valid_caip*) that returns the identifier unchanged or raises CaipError.

The namespace registry is vendored, not fetched at runtime, so validation stays offline and deterministic. Note that a registry directory name is not always the namespace it declares: the avalanche directory registers the namespace avax.

Install

pip install algovoi-substrate

npm install @algovoi/substrate

Usage

from algovoi_substrate import (
    is_caip2, is_caip10, is_caip19,
    require_caip2, caip10_of, caip19_slip44,
    is_registered_caip2, is_valid_caip2, CaipError,
)

is_caip2("eip155:1")                  # True
is_caip2("eip155:1\n")                # False  (anchor discipline)
is_caip10("eip155:1:0xAb16a9...")     # True
is_caip19("eip155:1/slip44:60")       # True

# constructors are gated on the way in and on the way out
caip10_of("eip155:1", "0xAb16a9...")  # "eip155:1:0xAb16a9..."
caip19_slip44("eip155:1", 60)         # "eip155:1/slip44:60"

# tier 2 and tier 3
is_registered_caip2("zzz:1")          # False (namespace not registered)
is_valid_caip2("eip155:abc")          # False (eip155 references are decimal)

require_caip2("eip155:1\n")           # raises CaipError

import {
  isCaip2, isCaip10, isCaip19,
  requireCaip2, caip10Of, caip19Slip44,
  isRegisteredCaip2, isValidCaip2, CaipError,
} from '@algovoi/substrate';

isCaip2('eip155:1');                  // true
isCaip2('eip155:1\n');                // false  (anchor discipline)
isCaip10('eip155:1:0xAb16a9...');     // true
isCaip19('eip155:1/slip44:60');       // true

// constructors are gated on the way in and on the way out
caip10Of('eip155:1', '0xAb16a9...');  // 'eip155:1:0xAb16a9...'
caip19Slip44('eip155:1', 60);         // 'eip155:1/slip44:60'

// tier 2 and tier 3
isRegisteredCaip2('zzz:1');           // false (namespace not registered)
isValidCaip2('eip155:abc');           // false (eip155 references are decimal)

requireCaip2('eip155:1\n');           // throws CaipError

Grammar

Verbatim from CAIP-2, CAIP-10 and CAIP-19:

chain_id    = namespace ":" reference    namespace [-a-z0-9]{3,8}   reference [-_a-zA-Z0-9]{1,32}
account_id  = chain_id ":" address       address   [-.%a-zA-Z0-9]{1,128}
asset_type  = chain_id "/" ns ":" ref    asset ns  [-a-z0-9]{3,8}   asset ref [-.%a-zA-Z0-9]{1,128}
asset_id    = asset_type "/" token_id    token_id  [-.%a-zA-Z0-9]{1,78}

The Python implementation uses only the standard library, so the tier adds no dependency to the substrate.

What is validated

The identifier validators ship with the substrate test suite. Every claim below is reproducible from the tagged source:

git clone https://github.com/chopmob-cloud/algovoi-substrate
cd algovoi-substrate/python && git checkout v0.5.0
pip install -e ".[test]" && pytest

Cross-runtime

Full suite green on Python 3.10, 3.11, 3.12 and 3.13 and on Node 18, 20 and 22, run against the installed package rather than the source tree.

Differential

The regexes are checked against an independent regex-free oracle over a large fuzz corpus, so an anchor or character-class error surfaces as a disagreement rather than a silent pass.

Property-based

Structural generators build grammar-valid identifiers that must validate, and shrink any counterexample to a minimal failing input.

Non-catastrophic

Pathological inputs are checked for catastrophic backtracking, so a hostile identifier cannot stall a verifier.

The Python and TypeScript implementations hand-maintain the same grammar and the same namespace registry in separate files. A parity test parses the TypeScript source and asserts its constants match Python’s, so copy drift fails the suite rather than shipping as a silent cross-language disagreement.

Reproducible builds

The published artefacts are reproducible from the tagged source. An independent checkout of v0.5.0 rebuilds the wheel, source distribution and npm tarball byte for byte:

git clone https://github.com/chopmob-cloud/algovoi-substrate
cd algovoi-substrate && git checkout v0.5.0
SOURCE_DATE_EPOCH=1735689600 python -m build   # from python/
npm install && npm run build && npm pack        # from typescript/

Line endings are pinned to LF in .gitattributes, so the build does not depend on the checkout platform.

Licence and attribution

Apache-2.0. Every module carries an SPDX-License-Identifier: Apache-2.0 header, and the NOTICE file ships inside the wheel, the source distribution and the npm tarball. When redistributing this work or derivative works, retain the NOTICE per Apache License, Version 2.0, Section 4(d). See Substrate licensing and attribution.

JCS Canonicalisation Substrate

The canonicalisation discipline these identifiers are hashed under.

Adopt the substrate

Anchor your own service or specification and be recorded in the registry.

Get started

Platform

Concepts

Keystone

Substrate 2

Commercial

Open substrate

Payment protocols

Chains

Integrations

Help

Company

CAIP Chain-Agnostic Identifiers

The trailing-newline anchor trap

Three validation tiers

1. Grammar

2. Registered namespace

3. Reference format

Install

Usage

Grammar

What is validated

Cross-runtime

Differential

Property-based

Non-catastrophic

Reproducible builds

Licence and attribution

JCS Canonicalisation Substrate

Adopt the substrate

​The trailing-newline anchor trap

​Three validation tiers

1. Grammar

2. Registered namespace

3. Reference format

​Install

​Usage

​Grammar

​What is validated

Cross-runtime

Differential

Property-based

Non-catastrophic

​Reproducible builds

​Licence and attribution

JCS Canonicalisation Substrate

Adopt the substrate

The trailing-newline anchor trap

Three validation tiers

Install

Usage

Grammar

What is validated

Reproducible builds

Licence and attribution