VOT

Verified Object Transfer: a protocol and Rust implementation for transferring immutable objects with cryptographic receiver assurance.

Status: early development. Specifications are in spec/.

cargo test --workspace --locked

• vot-sdk is the pure Rust facade for verified coverage, package ingest, proof catalogs, and receipts. It has no native filesystem or network dependency.
• vot-wasm exposes the pure facade through generated WebAssembly bindings.
• vot-sdk-file adds native file staging and publication on Linux, macOS, and Windows. It never overwrites an existing destination and reports an unsupported assurance requirement instead of silently downgrading it.

Applications can use the pure facade directly and add the native adapter only where filesystem publication is required.

Build and run with cargo run -p vot-cli -- <command>.

# Build a deterministic transfer bundle from a directory.
vot send [SUITE] SOURCE_DIR BUNDLE_DIR
# Prints: ROOT LENGTH

# Verify, publish, and write a receipt.
vot receive BUNDLE_DIR DESTINATION_DIR RECEIPT.cbor KEY_SOURCE OBSERVED_AT
# Prints: ROOT LENGTH PUBLISHED

# Check a receipt without the bundle.
vot verify-receipt RECEIPT.cbor KEY_SOURCE
# Prints: ROOT LENGTH ASSURANCE (THIRD-PARTY-VERIFIABLE or SHARED-SECRET)

SUITE is blake3 or sha256 (default: sha256).

OBSERVED_AT is an RFC 3339 timestamp.

Wire commands need the wire feature (builds BoringSSL via cmake):

# Serve a bundle. Supports concurrent sessions.
vot serve BUNDLE_DIR LISTEN_ADDR [CERT.pem KEY.pem]

# Fetch a bundle from a server. The root is what says which package to accept.
vot fetch CONNECT_ADDR BUNDLE_DIR PACKAGE_ROOT

# Fetch and receive in one step.
vot pull CONNECT_ADDR BUNDLE_DIR DESTINATION_DIR RECEIPT.cbor KEY_SOURCE \
  OBSERVED_AT PACKAGE_ROOT

# Run a rendezvous service (ADR-0033).
vot rendezvous LISTEN_ADDR

# Run a relay, for two ends that cannot punch (ADR-0034).
vot relay LISTEN_ADDR

A relay forwards ciphertext between two endpoints. It observes addresses and byte counts, not package roots or plaintext. Slots are keyed by a root hash and bounded by operator-configured lifetimes and byte limits.

With VOT_RENDEZVOUS, the serve registers a package-root hash, the fetch resolves it, and both peers attempt NAT traversal. Symmetric and carrier-grade NAT may require a relay.

export VOT_RENDEZVOUS=rendezvous.example:9999
vot serve BUNDLE_DIR 0.0.0.0:0            # registers under the bundle's root
vot fetch ROOT BUNDLE_DIR                 # resolves that root, no address

Transport certificates are ephemeral and are not verified. Content is instead authenticated against the requested package root: ranges prove to object roots, and the manifest proves those roots to the package seal. Address-based fetches therefore require PACKAGE_ROOT. Set VOT_FETCH_UNPINNED=1 only when the remote package is intentionally accepted without a trusted root.

Both ends ask the kernel for a 16 MiB UDP receive buffer and an 8 MiB send buffer. On Linux without CAP_NET_ADMIN the kernel clamps those to net.core.rmem_max and net.core.wmem_max, 208 KiB on a stock system, which dropped around a tenth of the packets at 12 to 15 Gbit/s over loopback. macOS refuses a request above kern.ipc.maxsockbuf (about 7.4 MB by default) outright and the socket keeps its much smaller default. The CLI prints one warning line to stderr naming the knob when it got less than it asked for; raise it (64 MiB is ample) to clear the warning.

A serve behind Linux's default fq_codel root qdisc loses packets on long paths for a different reason: CoDel drops on queue sojourn time against a 5 ms target, and a sender whose round trip is 100 ms keeps its queue above that permanently, so on one measured 107 ms path 6.5% of the serve's packets were dropped by its own qdisc as whole segmentation bursts. Raising the qdisc's limit does nothing; replacing it (tc qdisc replace dev eth0 root pfifo limit 100000) took that to 0.001% and cut the serve's CPU by a quarter, while the wall moved only 6% because eight rails are not loss bound there.

A virtio guest with a single transmit queue commonly boots with tx-udp-segmentation off, and then the serve's UDP_SEGMENT writes are taken apart by the guest kernel and reach the queue as one 1.5 KB descriptor per packet, about 150,000 a second. That caps the serve near 1.6 Gbit/s at every rail count with no drop counter moving and no thread busy, which is 98% of what plain UDP gets on the same box and 17% of eight TCP streams at 3 ms, TCP keeping its own segmentation offload. ethtool -K eth0 tx-udp-segmentation on (check with ethtool -k eth0 | grep tx-udp-segmentation) put 30 KB in each descriptor and took the same binary to 6.1 Gbit/s at four rails and 6.0 at eight at 3 ms, 71% and 69% of eight TCP streams, and to 3.9 at 83 ms, 189% of TCP. With it on, the fetch host's single receive queue is the next limit: one core saturates in softirq near 380,000 packets a second and the eighth rail adds loss rather than rate, so multiple receive queues (RSS) or receive-side UDP GRO on the fetch host is the lever. VOT prints no warning for this, because unlike the buffer clamp nothing socket-local reveals it.

A serve answers anyone by default. Give it an issuer key and it requires a capability: a signed token naming one package, one holder key, and a validity window. ADR-0036.

Every key below is a KEY_SOURCE, so it names where to read a key from and not the key itself: env:NAME, - for stdin, or a file path. What it reads is the labelled key, ed25519-secret:HEX or ed25519-public:HEX.

# The recipient makes a key and sends you the public half.
vot capability keygen                      # prints the secret, then the public

# You mint a token for your package under your own issuer key.
export ISSUER_SECRET=ed25519-secret:...    # your key, however you store it
export HOLDER_PUBLIC=ed25519-public:...    # theirs
vot capability issue env:ISSUER_SECRET you.example them.example \
  env:HOLDER_PUBLIC PACKAGE_ROOT 86400 token.cbor

# Your serve requires one.
export ISSUER_PUBLIC=ed25519-public:...    # the public half of yours
export VOT_SERVE_ISSUER=env:ISSUER_PUBLIC
export VOT_SERVE_ISSUER_NAME=you.example
export VOT_SERVE_AUDIENCE=them.example
vot serve BUNDLE_DIR 0.0.0.0:9000

# Their fetch presents it.
export HOLDER_SECRET=ed25519-secret:...
export VOT_FETCH_CAPABILITY=token.cbor
export VOT_FETCH_HOLDER_KEY=env:HOLDER_SECRET
vot fetch ADDR BUNDLE_DIR PACKAGE_ROOT

Authentication completes before transfer. Token validation failures use the same refusal to avoid exposing token state.

The capability proof binds the holder key to the session challenge and TLS exporter. Authentication fails closed when the carrier cannot provide that binding. The exporter does not authenticate the server; the package root authenticates received content. See ADR-0037.

Push authenticates both ends. The receiver requires the same issuer triple as an authenticated serve and prints the certificate identity the holder must pin. Issue a publish token for the exact package root and logical length, then push with that token and its holder key. The receive portal currently requires Unix directory-containment guarantees; the dialing push command remains available on every supported platform.

export VOT_SERVE_ISSUER=env:ISSUER_PUBLIC
export VOT_SERVE_ISSUER_NAME=you.example
export VOT_SERVE_AUDIENCE=them.example
vot receive-push 0.0.0.0:9000 RECEIVED_BUNDLES CERT.pem KEY.pem
# Prints: identity HEX (pin with VOT_PUSH_IDENTITY)

vot capability issue-push env:ISSUER_SECRET you.example them.example \
  env:HOLDER_PUBLIC PACKAGE_ROOT PACKAGE_LENGTH 86400 push-token.cbor
export VOT_PUSH_IDENTITY=HEX
vot push BUNDLE_DIR ADDR push-token.cbor env:HOLDER_SECRET

KEY_SOURCE is env:NAME, - (stdin), or a file path.

Ed25519 receipts are third-party verifiable: anyone with the public key can check them. Shared-secret receipts cannot be verified without the ability to forge them.

Linux, macOS, and Windows. receive-push is Unix-only until guarded directory operations exist on Windows; all other commands, including push, retain the three-platform support. Platform-specific code is isolated in vot-platform-fs, vot-platform-net, and vot-platform-proc.

• Validation - every check and how to run it
• Sessions and negotiation - handshake, readiness, lane identity
• Specifications - protocol specs (wire, security, proofs, registries)
• Architecture - crate layering and invariants
• ADRs - decision records with reasoning

• vot-bench-driver - benchmark carrier (simulator, quiche, msquic)
• vot-transport-sim - deterministic network simulator
• fuzz/ - libFuzzer targets for codec and manifest
• tools/ - Python validators for conformance vectors
• test-vectors/ - committed test vectors and mutation test records

Rust implementation and project files: AGPL-3.0-only. Specifications, test vectors, and formal models: Apache-2.0. See LICENSE, LICENSE-APACHE, and permissive-directory markers.