avp

Alt Vault Protocol, an open zero-knowledge spec for sharing alts across clients.

Conformance vectors

Test vectors an implementation can check itself against. Each file is JSON with a description and one or more cases. The conformance runner in ../examples/conformance loads and checks every file here with Node’s crypto.

index.json is a machine-readable index of these files: each entry gives the file, its kind (deterministic / rfc-primitive / composition / data / scenario / negative), the spec section, and the published anchors, so a harness can enumerate the vectors instead of hardcoding filenames.

AVP 0.5 construction vectors (generated)

These pin the 0.5 byte constructions. They are derived only from fixed seeds (listed in each file under seeds) by generate.ts, which owns them.

The CE constructions have no published anchor, so the runner also re-derives every case by a second, hand-written assembly of the SPEC layout (raw byte concatenation, independent of the encoder under test).

Merge vectors (hand-written)

Host acceptance scenarios (hand-written verdicts)

Cryptographic primitive vectors (RFC-anchored)

Each primitive AVP relies on is pinned to a published RFC test vector, so a conformant implementation reproduces a known-good output and cannot drift on the primitive itself:

Composition vectors (three-way cross-verified)

This exercises the default wrap scheme (SPEC §4.4). They embed fixed keys/IVs so they are reproducible, and their correctness is established by three independent sources agreeing byte-for-byte (see “Three-way verification” below):

Three-way verification

The composition vectors are public and must not contain mistakes, so each was confirmed by three independent sources agreeing byte-for-byte before being committed:

  1. Published RFC test vectors, every primitive carries at least one published anchor: HKDF-SHA256 from RFC 5869 (Test Cases 1 and 3), X25519 from RFC 7748 (§5.2 vectors and the §6.1 DH example), and Ed25519 from RFC 8032 (§7.1 TEST 2 and TEST 3). The composition vectors are anchored to RFC 7748 §6.1 via the wrap keypairs. The Node runner reproduces every published output exactly.
  2. The reference implementation (Java), the lol.trq.alts crypto primitives independently agree with every vector: its HKDF and X25519 reproduce the primitive outputs, it verifies (and reproduces) the Ed25519 signatures, and its X25519HkdfAesGcmKeyWrap unwraps the key-wrap vector and recovers the data key. This was verified with a throwaway harness against the library’s compiled primitives.
  3. The Node conformance runner, reproduces every primitive output and round-trips every composition vector (decrypt/unwrap and assert recovery) with Node’s crypto; see the runner’s README.md. bun run test must pass.

An implementation proves conformance by reproducing the deterministic and RFC-anchored vectors exactly, and by round-tripping the composition vectors (decrypting/unwrapping what a peer encrypted/wrapped, verifying what a peer signed).

The 0.5 construction vectors (bip39-owner.json, manifest.json, commit.json) are verified by the Trezor BIP39 reference vectors and the RFC-anchored primitives, by the Node runner, and by the runner’s second, hand-written assembly of every CE layout; the rebuilt Rust and Java references reproduce them byte-for-byte as their third source.

Negative vectors

gRPC encoding vectors (generated)

Regenerating the vectors

grpc.json is not owned by generate.ts. It is derived from the proto and the files above by ../examples/conformance/scripts/grpc-vectors.ts: --write regenerates it and --check asserts the committed file is current. The conformance runner’s grpc.test.ts asserts the same, so bun run test fails on drift.

generate.ts is the reproducible derivation of these files. It reuses the vector-tested reference crypto so it cannot drift from the runner.