AVP, the Alt Vault Protocol

An open, vendor-neutral protocol for sharing Minecraft alt accounts across clients through a zero-knowledge sync server.

License no-leak spec

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 the server stores only ciphertext, wrapped keys, public keys, and version counters. 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 is addressed avp://host/repoId, and one portable identity reaches repositories on any conformant server. Different clients, and different communities running their own servers, 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 server. A conformant client and server exist as separate reference implementations.

How it works in one paragraph

A repository has one symmetric data key that encrypts the alt payload (AES-256-GCM, with the repository id, payload version, and key epoch bound in as additional authenticated data). That data key is wrapped to each member’s X25519 public key, so only members can decrypt it, and the server never sees it unwrapped. A member’s stable identity is an Ed25519 public key. Removing a member rotates the data key to a new epoch, so the departed member’s old wrapped copy becomes useless. Writes use optimistic concurrency on a monotonic payload version. No plaintext (passphrases, identity seeds, the data key, or the alts themselves) ever reaches the server.

Two transport profiles

The same messages are defined for two interchangeable encodings, so you can pick whichever fits your stack:

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 (HTTP/JSON profile).
vectors/ Conformance test vectors.
examples/ A worked end-to-end flow, representative message bodies, and a runnable reference server.
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:

  1. Read SPEC.md. It is short and self-contained.
  2. Generate types from proto/avp.proto, or work straight from schema/avp.schema.json if you prefer JSON.
  3. 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, pull, push, rotate) with representative message bodies, which is the fastest way to see how the pieces fit together.

Your client and ours can then share the same repositories. The protocol does not care which client a member runs.

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:

  1. Field names are normative. Use the exact names in proto/avp.proto (and their camelCase form for JSON). Do not rename or renumber fields.
  2. Two fixed byte constructions. The additional-authenticated-data layout (SPEC section 4) and the canonical key-binding message (SPEC section 9) are exact. Reproduce the deterministic vectors/ before trusting your encoder.
  3. Zero-knowledge is the whole point. Never send the server a plaintext alt, a passphrase, an identity seed, or the data key. The server sees only ciphertext, wrapped keys, public keys, counters, and opaque signatures.
  4. Provenance values are runtime data. sourceClient and sourceUser are 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 (see CONTRIBUTING.md).
  5. 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:

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:

Status

Draft v0.2 of the protocol. The wire contract is stable. Open items are tracked in SPEC.md §Security considerations.

Activity

Repobeats analytics image