AVP, the Alt Vault Protocol
An open, vendor-neutral protocol for sharing Minecraft alt accounts across clients through zero-knowledge hosts that replicate each repository between them.
Read it online at avp.trq.lol, or jump straight to the specification, the proto schema, or the worked examples.
Members of a shared alt repository are identified by a keypair. The alt payload is encrypted on the client before it ever leaves the machine, so a host stores only ciphertext, wrapped keys, public keys, counters, ids, and signatures. It can decrypt nothing. Any client or mod can implement either side and interoperate, the same way any mail client talks to any IMAP server.
AVP is federated. A repository lives on several hosts at once: each member talks to its own home host, and the hosts replicate with each other, so a member keeps working while another member’s host is down. Different clients, and different communities running their own hosts, can share alts without a central authority.
This repository is the specification, not an implementation. It defines the wire contract so anyone can build a conformant client or host. Illustrative Rust and Java reference clients and hosts live in
examples/.
How it works in one paragraph
The repository owner holds a 24-word recovery phrase that derives the owner signing key. Only the owner signs manifest states: a hash-linked chain holding the members, the data key wrapped to each member’s X25519 key, the key epoch, the refresh-token policy, and the hosts. Every write is a commit signed by its member author, carrying the full payload encrypted with AES-256-GCM under the epoch’s data key, with the repository, epoch, author, and parent commits bound in as additional authenticated data. Concurrent writes on different hosts fork the commit graph; every field carries its own timestamp, so clients merge the heads per field without losing a write. Removing a member rotates the data key to a new epoch and signs a cutoff that rejects anything the removed member backdates. Hosts verify every signature and validate every item, but no phrase, seed, data key, or plaintext alt ever reaches one.
Two transport profiles
The same messages are defined for two interchangeable encodings, so you can pick whichever fits your stack:
- gRPC profile.
proto/avp.protois canonical. Field numbers and names are stable. TheVaultservice carries every client operation, discovery and authentication included (SPEC section 10.3), with the bearer token inauthorizationmetadata. It also defines theReplicationservice for host-to-host sync over gRPC. - HTTP/JSON profile. One HTTP path per operation, JSON bodies whose field names are the proto field
names in
camelCase, and a Bearer token inAuthorization. Message shapes areschema/avp.schema.json; the full route surface (paths, status codes, error bodies) isopenapi.yaml. The reference hosts replicate with each other over signed HTTP/JSON (SPEC section 9.3).
A browser or Node client can implement AVP with no gRPC toolchain at all.
Repository layout
| Path | Contents |
|---|---|
SPEC.md |
The normative protocol specification. |
proto/avp.proto |
Canonical Protocol Buffers schema (gRPC profile). |
schema/avp.schema.json |
JSON Schema message shapes (HTTP/JSON profile). |
openapi.yaml |
OpenAPI 3.1 route description for the HTTP/JSON profile. |
vectors/ |
Conformance test vectors (indexed by vectors/index.json). |
examples/ |
A worked end-to-end flow, representative message bodies, and runnable reference implementations. |
harness/ |
Black-box conformance suite: run it against any host, or several replicating hosts, to assert the wire-contract MUSTs. |
Taskfile.yml |
One-command local runner: task test runs the conformance suite and every example. |
THREATMODEL.md |
What AVP defends against, what it does not, and the residual risks. |
CONTRIBUTING.md |
How to help. |
SECURITY.md |
How to report a vulnerability. |
llms.txt |
Structured entry point for LLMs and AI agents. |
Implement it in your client
If you build a Minecraft client, mod, or launcher, you can add cross-client alt sharing by implementing the side you need:
- Read
SPEC.md. It is short and self-contained. - Generate types from
proto/avp.proto, or work straight fromschema/avp.schema.jsonif you prefer JSON. - Check your build against
vectors/, then cross-test against another implementation: if it decrypts what you encrypt and verifies what you sign, you interoperate.
The examples/ directory walks the full flow (create, invite, join, write, merge, remove,
replicate) with representative message bodies and holds the Rust and Java reference clients and hosts.
IMPLEMENTING.md is the implementer’s guide.
Your client and ours can then share the same repositories. The protocol does not care which client a member runs.
Check yourself against the vectors
The reference conformance runner reproduces every vector in vectors/ with Node’s crypto:
cd examples/conformance
bun install
bun run test
It reproduces the RFC-anchored and construction vectors exactly, round-trips the composition vectors (decrypting and unwrapping what a peer produced), replays the host acceptance scenarios, and rejects every negative case. Reproduce the same in your language and your crypto and rules are conformant.
Check your host
The vectors prove your crypto; the black-box harness in harness/ proves your host.
Point it at any running AVP host and it drives the full wire contract, asserting the normative MUSTs:
the auth failure modes, the manifest chain, forks and merges, the head bound, the removal cutoff, leave,
prepareJoin, and zero-knowledge. A second suite drives replication between two or three hosts:
bun harness/conformance.ts --server http://127.0.0.1:8787
bun harness/multihost.ts --a http://127.0.0.1:19201 --b http://127.0.0.1:19202 --c http://127.0.0.1:19203
Each prints PASS/FAIL per check and exits non-zero on any failure. CI
(.github/workflows/conformance.yml) runs both against the Rust and
Java reference hosts, the multi-host suite in every language pairing, lints openapi.yaml,
and checks that the schema, example bodies, and vector index stay consistent.
For AI agents
If you are an AI coding agent asked to implement, review, or extend AVP, start from
llms.txt. It is a structured index of every document here with direct links to the raw
files, in the llmstxt.org format.
Before generating an implementation, load SPEC.md in full. The points most often gotten
wrong:
- Field names are normative. Use the exact names in
proto/avp.proto(and theircamelCaseform for JSON). Do not rename or renumber fields. - Fixed byte constructions. Every signed or hashed structure (manifest state, commit header, AAD,
acceptance, leave request) is built by the canonical encoding of SPEC section 4 and is exact.
Reproduce the
vectors/before trusting your encoder. - Zero-knowledge is the whole point. Never send a host a plaintext alt, the owner phrase or seed, a private key, or a data key. A host sees only ciphertext, wrapped keys, public keys, counters, ids, and signatures.
- Provenance values are runtime data.
sourceClientandsourceUserare filled in by the implementer at runtime. Never hardcode a real client, user, or server name into spec text or examples; a CI gate rejects vendor-internal names (seeCONTRIBUTING.md). - Pick a profile. gRPC from the proto, or HTTP/JSON from the schema. Both carry the same messages.
Verify against another conformant implementation: if it decrypts what you encrypt and verifies what you sign, you interoperate.
Want to help?
Contributions from other client developers are very welcome. Good ways to lock in:
- Implement a client or host in a new language and report back on anything ambiguous in the spec.
- Add conformance vectors, especially host acceptance scenarios and negative cases.
- Write a reference HTTP/JSON host skeleton so newcomers can stand one up quickly.
- Review the cryptography and the manifest chain, removal cutoff, and replication design, and open issues for weaknesses.
- Help design the open items in
SPEC.md§15 (algorithm negotiation, ownership transfer, deletion-marker GC and retention, host freshness).
Start by opening an issue to discuss, then send a pull request. See CONTRIBUTING.md.
Disclaimer
AVP is an independent, community specification. It is not affiliated with, endorsed by, or associated with Mojang or Microsoft. “Minecraft” and related marks belong to their respective owners and are used here only to describe interoperability. The specification is provided as is, without warranty of any kind. How an implementation obtains and uses accounts, and whether that complies with any service’s terms or with applicable law, is the implementer’s responsibility.
License
This repository is dual-licensed:
- Machine-readable artifacts (
proto/,schema/,vectors/) and the example code underexamples/are licensed MIT, seeLICENSE. - Specification prose (
SPEC.mdand this README) is licensed CC-BY-4.0, seeLICENSE-docs.
Status
Stable v0.5 of the protocol: multi-host repositories with an owner-signed manifest chain, a signed commit
graph, per-field merge, host-issued authentication, and a BIP39 owner identity. 0.5 is a breaking version,
not wire compatible with 0.4. Open items are tracked in SPEC.md §15.