docs/generated/contracts.mdgenerated from code
Reference · 3 min read
envelope
Contracts: envelope.
Read as
Source: crates/lvcs-net/src/wire/envelope.rs.
1/// The envelope's version (discussion:owner/284).2///3/// `major` changes only with an incompatible layout: a node rejects an4/// envelope whose `major` is not `lvcs_vocab::ids::WIRE_MAJOR` with5/// [`WireError::UnknownMajor`]. A new message kind is a `minor` change:6/// nodes accept any `minor` and ignore kinds they don't know (discussion:owner/588).7/// Encoded as the map `{ major, minor }`. Owner: `M3.envelope`.8#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]9pub struct WireVersion {10 /// Changes only with an incompatible layout.11 pub major: u16,12 /// Changes when a message kind is added; nodes accept any.13 pub minor: u16,14}1516/// Who signed an envelope (discussion:owner/107).17///18/// Chosen at the M3 freeze: gossip messages are signed by the peer19/// who sent them, so capability checks and per-signer token buckets key on20/// the peer, while gossipsub's own message author (the forwarding21/// device) is what a repeat offense down-scores; sync-stream frames are22/// signed by the sending device, whose identity Noise already23/// authenticated. Peer and device keys are separate keys: a peer key is never a device key. Encoded as a one-entry map24/// `{ peer: <bytes> }` or `{ device: <bytes> }`. Owner:25/// `M3.envelope`.26#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]27pub enum Sender {28 /// A peer's Ed25519 public key: the bytes of an29 /// `lvcs_doc::PeerKey`.30 Peer([u8; 32]),31 /// A device's Ed25519 public key, from which its libp2p `PeerId`32 /// derives.33 Device([u8; 32]),34}3536/// One message between nodes (discussion:owner/20 and discussion:owner/67).37///38/// `payload` is the canonical CBOR encoding of the payload type `kind` names39/// (the `wire_kind` set in `docs/generated/vocabulary.md`, an open set: a40/// kind outside it is ignored, never rejected). `frontier` is the sender's41/// visible frontier id when the message is about project state (absent42/// otherwise; encoded as CBOR null, so the field set never varies). `sig`43/// is `sender`'s `SIGNATURE` over the canonical CBOR array44/// `[v, kind, sender, frontier, payload]` (an array of the signed fields,45/// chosen at the M3 freeze). Encoded as the map46/// `{ v, kind, sender, frontier, payload, sig }` in that order, digests and47/// `payload` as byte strings. A document's sync payload travels inside a48/// `sync` payload unchanged (discussion:owner/30). `trace` follows `sig`, outside49/// the signed array (discussion:owner/441). Owner: `M3.envelope`.50#[derive(Debug, Clone, PartialEq, Eq)]51#[expect(52 clippy::min_ident_chars,53 reason = "the field `v` is named for the encoded envelope's `v` map key (discussion:owner/107), \54 which this contract type tree_files field for field; Clippy checks a field's name \55 against the struct's lint level, so the struct is the narrowest item"56)]57pub struct Envelope {58 /// The envelope's version.59 pub v: WireVersion,60 /// The message kind: a `wire_kind` value, or one this node doesn't know.61 pub kind: String,62 /// Who signed the envelope.63 pub sender: Sender,64 /// The sender's visible frontier id, when the message is about project65 /// state.66 pub frontier: Option<[u8; 32]>,67 /// The canonical CBOR encoding of the payload type `kind` names.68 pub payload: Vec<u8>,69 /// `sender`'s signature over the signed fields.70 pub sig: [u8; 64],71 /// The sending step's trace context (discussion:owner/441), the binary W3C72 /// traceparent: telemetry only, unsigned, never branched on.73 pub trace: Option<Traceparent>,74}7576/// A binary W3C traceparent (discussion:owner/441): version, trace id, span id,77/// and flags. lvcs-net carries it as it is.78pub type Traceparent = [u8; TRACEPARENT_BYTES];7980/// The bytes of a [`Traceparent`]: 1 + 16 + 8 + 1.81pub const TRACEPARENT_BYTES: usize = 26;8283/// Why bytes are not an acceptable envelope (discussion:owner/107).84///85/// Each maps to one `rejection` value: `TooLarge` and `Malformed` to86/// `malformed`, `UnknownMajor` to `unknown_version`, `BadSignature` to87/// `bad_signature`. Owner: `M3.envelope`.88#[derive(Debug, Clone, PartialEq, Eq)]89pub enum WireError {90 /// Longer than `lvcs_vocab::limits::WIRE_MAX_BYTES`; not decoded.91 TooLarge {92 /// The length received, in bytes.93 len: usize,94 },95 /// Not a canonical CBOR envelope or payload.96 Malformed(String),97 /// The envelope's major version is not `WIRE_MAJOR`.98 UnknownMajor {99 /// The major version the envelope carried.100 major: u16,101 },102 /// `sig` is not `sender`'s signature over the signed fields.103 BadSignature,104}