Expand description
The normative wa-wire boundary format and negotiation types.
Every WhatsApp Web client library speaks the same wire protocol and exposes
a different API. wa-wire makes the thing they already share — the wire
itself — the interface, so an integration written once runs on any
conforming engine.
§The layer model
- L0-wire — the stanza as it arrived, payload still encrypted.
- L0-plain — that frame plus the plaintexts the engine decrypted.
- L1 — typed canonical events, derived from L0-plain.
L0 is normative and L1 is a derived view: nothing may appear in L1 that is
not derivable from L0-plain. L0-plain → L1 is a pure function — protobuf
parsing and mapping, no keys and no accumulated state — which is why it runs
host-side, once, instead of being reimplemented per engine.
§What crosses the boundary
The frame bytes already exist inside every engine at the moment it decodes,
and the frame never contained the plaintext anyway — <enc> carries
ciphertext, and the plaintext arrives later from Signal. So an envelope is
the frame verbatim plus a side table of plaintexts, each addressed by
the path of the node it belongs to.
Nothing is re-encoded, so there is no encoding to choose. The frame is parsed exactly once, host-side, and only if something subscribed to L1.
use wa_wire_contract::{EnvelopeBuilder, EnvelopeRef, Flags, NodePath,
PlaintextEntry, PlaintextStatus};
// A <message> whose single <enc> child decrypted successfully.
let frame = b"\xf8\x03..."; // unpacked binary-node bytes
let path = 0u16.to_le_bytes(); // child 0 of the root
let entries = [PlaintextEntry {
path: NodePath::from_le_bytes(&path),
status: PlaintextStatus::Ok,
payload: b"decrypted protobuf",
}];
let bytes = EnvelopeBuilder::new(Flags::inbound(), frame)
.with_entries(entries.iter().copied())
.encode_to_vec()?;
let envelope = EnvelopeRef::decode(&bytes)?;
assert_eq!(envelope.frame(), frame);
let entry = envelope.entries().next().expect("one plaintext");
assert!(entry.status.is_ok());
assert_eq!(entry.payload, b"decrypted protobuf");§What publication froze
Contract version 1 is fixed as of 0.1.0: the envelope layout, the ten capability identifiers, and the meaning of every field an envelope carries. An adapter written against this can be linked by a host built against it and neither has to ask the other’s version.
Fixed rather than final. What may still happen inside version 1:
- new capability identifiers, which an older reader keeps as unknown text rather than refusing — a recording declares them by name and preserves the ones it cannot resolve;
- new reserved-flag bits and new metadata tags, the latter carrying a critical bit that says whether skipping one is safe;
- anything additive that an existing reader can ignore without being wrong.
What would need version 2: moving a field, changing what one means, or
removing anything. ContractVersion::check compares by equality for that
reason — a differing major means the layout may differ, and guessing is how
silent corruption starts.
A WhatsApp-side protocol change never bumps this. L0 is total: the frame
crosses verbatim, so at L0 there is nothing for a protocol change to break.
Which WhatsApp build a derivation came from is Provenance, tracked
separately and expected to move often.
§Two version axes
ContractVersion versions this boundary; Provenance records which
whatspec build an L1 derivation came from. A WhatsApp protocol change
moves provenance and leaves the contract version alone — otherwise every
deployed adapter would break whenever the protocol shifted. L0 totality is
what makes that safe: the frame crosses verbatim, so there is nothing at L0
for a protocol change to break.
§Cost
Decoding never allocates and never copies: an EnvelopeRef borrows from
the buffer it was decoded from. Encoding writes once into a caller-supplied
slice, or allocates exactly once with encode_to_vec.
Re-exports§
pub use capability::Capability;pub use capability::CapabilitySet;pub use capability::UnmetCapabilities;pub use envelope::EnvelopeBuilder;pub use envelope::EnvelopeRef;pub use envelope::HEADER_LEN;pub use envelope::PlaintextEntry;pub use error::DecodeError;pub use error::EncodeError;pub use error::Field;pub use flags::Direction;pub use flags::Flags;pub use flags::FrameOrigin;pub use path::NodePath;pub use provenance::Provenance;pub use provenance::ProvenanceCheck;pub use status::PlaintextStatus;pub use version::ContractVersion;pub use version::VersionMismatch;
Modules§
- capability
- What an adapter can and cannot do, declared rather than discovered.
- envelope
- The L0-plain envelope: frame bytes verbatim plus a plaintext side table.
- error
- Decode failures.
- flags
- The envelope flag word.
- path
- Addressing a node inside a frame.
- provenance
- Which
whatspecbuild an L1 derivation came from. - status
- Outcome of one decryption attempt.
- version
- Contract versioning.