lib/reticulum/src/wire/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! The byte layouts of one datagram on a mesh network, with a reader and a
 2 //! writer for each: the header and its flag bits, the byte that says what the
 3 //! payload is for, the digest that names the packet, the two shapes of the
 4 //! signed reply that says a packet arrived, and the payloads that open an
 5 //! encrypted session. That network is Reticulum, in which nodes find each other
 6 //! by broadcasting signed announcements and reach each other over any medium
 7 //! that moves bytes.
 8 //!
 9 //! Two programs that have never met have to agree on every byte of a 500-byte
10 //! datagram, down to the order of the bits inside its first byte. The code that
11 //! reads those bytes runs where memory is fixed before the program starts, so
12 //! it works in buffers its caller owns and hands back slices of them. One
13 //! packet needs one name that both ends and every node between them compute the
14 //! same way, because a signed reply travels back naming the packet it answers.
15 //!
16 //! The bytes a device hands over are whatever the wire delivered, so a reader
17 //! settles every length question before it indexes into them. A packet changes
18 //! as it travels, because the hop count rises at every node and a node carrying
19 //! it for someone else inserts sixteen bytes of its own ahead of the address. A
20 //! field can arrive holding a value this release has no name for, and
21 //! discarding it would break a peer running a newer build.
22 //!
23 //! The subtree follows Reticulum 1.5.0, the reference implementation, pinned to
24 //! one upstream commit by the package README and the generated conformance
25 //! corpus. What it takes from the reference is the field order, the bit
26 //! positions, and the length rule of each layout, and each declaration names
27 //! the reference file and line range it follows. The package generates byte
28 //! vectors from that release and replays them in tests, so each of those claims
29 //! is checkable from this tree.
30 //!
31 //! Reading and writing both work in a slice the caller supplies and return a
32 //! slice of it, so this code calls no allocator. The 32-byte SHA-256 digest
33 //! that names a packet (*packet hash*) covers the low four bits of the first
34 //! byte and everything from the address onward, which leaves out the hop count
35 //! and the sixteen bytes a carrying node inserts, so the name holds still as
36 //! the packet crosses the mesh. Each enum here names every bit pattern its
37 //! field can hold, and the header's last byte, which says what the payload is
38 //! for (*context byte*), carries an unnamed value through a decode and an
39 //! encode unchanged. The subtree names its pieces: the flag bits, the context
40 //! byte, the packet hash, the header, the proof payloads, and the link
41 //! payloads.
42 //!
43 //! - *proof*: a packet carrying a signature over an earlier packet's hash, sent
44 //!   back so the sender learns the packet arrived.
45 //! - *link*: an encrypted session between two endpoints, named by a 16-byte
46 //!   link id that both ends derive from the request packet.
47 
48 pub const context = @import("context.zig");
49 pub const flags = @import("flags.zig");
50 pub const hash = @import("hash.zig");
51 pub const header = @import("header.zig");
52 pub const link = @import("link.zig");
53 pub const proof = @import("proof.zig");
54 
55 pub const Context = context.Context;
56 pub const Flags = flags.Flags;
57 pub const HeaderType = flags.HeaderType;
58 pub const TransportType = flags.TransportType;
59 pub const DestinationType = flags.DestinationType;
60 pub const PacketType = flags.PacketType;
61 
62 pub const Packet = header.Packet;
63 pub const DecodeError = header.DecodeError;
64 pub const EncodeError = header.EncodeError;
65 pub const decode = header.decode;
66 pub const encode = header.encode;
67 pub const encodedLength = header.encodedLength;
68 pub const headerLength = header.headerLength;
69 pub const header_one_bytes = header.header_one_bytes;
70 pub const header_two_bytes = header.header_two_bytes;
71 pub const mtu = header.mtu;
72 pub const pathfinder_hops = header.pathfinder_hops;
73 pub const truncated_hash_bytes = header.truncated_hash_bytes;