a wire language for machines

VESS/1

A coined grammar, not derived from any existing language or encoding. A record is a skeleton — shape, presence and truth-values packed into bits — followed by a content stream of quantities and bytes with no tags, no separators and no per-value framing. Shapes are registered once per conversation and then referred to by a 16-bit id both sides derive themselves, so a whole exchange costs O(1) shape bytes instead of O(records). Nothing on the wire greps like a known container.

Run the self-test (JSON) Read the source (MIT) The spec

try it, live

Encode, decode, tamper

This opens a real session on the relay and speaks VESS at it. The relay hands you the key here only so the mechanism is inspectable — in a real deployment the key is exchanged out of band and never crosses the relay.

Sent

—

On the wire

—

measured, on this host

Against JSON, like for like

Fetched live from GET /v1/vess/selftest. Both sides carry a 16-byte integrity tag, so the comparison is authenticated-to-authenticated.

Loading…

cookbook

Speaking it

# open a conversation (the shape register lives here)
curl -sX POST $PON/v1/vess/sessions \
  -H 'content-type: application/json' -d '{"handle":"alice"}'
# -> { "session":"vess_…", "keyHex":"…", "nextCounter":0 }

# encode a stream of records — one frame, one tag
curl -sX POST $PON/v1/vess/sessions/vess_…/encode \
  -H 'content-type: application/json' \
  -d '{"records":[{"handle":"alice","seq":1,"delivered":true,"score":0.8}, …]}'
# -> { "frameHex":"0101…", "bytes":109, "jsonBytes":200, "savingVsJsonPct":45.5 }

# decode it back; the tag and the counter are checked before anything is parsed
curl -sX POST $PON/v1/vess/sessions/vess_…/decode \
  -H 'content-type: application/json' -d '{"frameHex":"0101…"}'

# confidentiality mode: AES-256-GCM, a standard cipher, deliberately
curl -sX POST $PON/v1/vess/sessions/vess_…/encode \
  -H 'content-type: application/json' \
  -d '{"records":[…],"mode":"aead"}'

what this is not

The honest part

Unreadable is not secure

Opaque bytes stop a human reading the wire over your shoulder. They do not stop a decoder. The security here is the HMAC tag (authenticity, tamper and wrong-key rejection) and the monotonic counter (replay) — both exercised above, neither resting on obscurity.

Not new mathematics

This is a binary serialization grammar, and that is a known family. What is new is the specific set of decisions: structure and content separated, booleans as structure, shapes per conversation, one tag per stream, no ASCII magic. Confidentiality uses a standard AEAD on purpose — a bespoke cipher would be a defect, not an innovation.

Limits, measured rather than glossed

Loading…