lib/reticulum/src/packet/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! Four jobs govern what a node does with a packet once its bytes have been
 2 //! read: decide whether to act on it, remember it so it is acted on once,
 3 //! answer it with a signed reply that says it arrived, and keep track of the
 4 //! packets it sent that are still waiting to be answered. The 32-byte digest
 5 //! that names a packet is the key every one of those four jobs turns on.
 6 //!
 7 //! A mesh floods, so the same packet reaches a node over more than one route,
 8 //! and the node has to act on it once. A sender needs to learn that what it
 9 //! sent arrived, and to give up after a wait that grows with the distance. Both
10 //! jobs need memory fixed before the program starts.
11 //!
12 //! Remembering the digest of every packet a node ever saw grows without limit,
13 //! and forgetting them all at once would let an old packet act a second time. A
14 //! record of a sent packet that waits forever for its answer holds its slot
15 //! forever, and a node whose records fill their storage cannot record the
16 //! packet it is sending now. The answer to a packet has to name the packet
17 //! without carrying it back, because the answer travels over the same 500-byte
18 //! limit.
19 //!
20 //! The subtree follows Reticulum 1.5.0, the reference implementation, pinned to
21 //! one upstream commit by the package README and the generated conformance
22 //! corpus. What it takes is the admission rules of Reticulum@1.5.0
23 //! RNS/Transport.py:1571-1628, the two hash generations of Reticulum@1.5.0
24 //! RNS/Transport.py:803-805, the two proof forms of Reticulum@1.5.0
25 //! RNS/Packet.py:403-404, and the receipt states and timeout rule of
26 //! Reticulum@1.5.0 RNS/Packet.py:396-400,537-548. The package generates
27 //! reference vectors from that release and replays them in tests, so each of
28 //! those claims is checkable from this tree.
29 //!
30 //! The store of seen hashes keeps two generations of the 32-byte SHA-256 digest
31 //! that names a packet (*packet hash*) and drops the older one on rotation, so
32 //! a packet stays recognized for at least one rotation while the store stays
33 //! bounded. The store of seen hashes and the records of sent packets
34 //! (*receipts*) are both carved out of caller storage with an entry maximum the
35 //! caller fixes. The reference filters an arriving packet against its shared
36 //! instance before it reaches these rules, and this subtree leaves that to the
37 //! caller. The reference marks a receipt for culling with a negative timeout,
38 //! and seconds here are unsigned, so the largest value a timeout holds marks
39 //! it. The subtree names its pieces: the packet hash, admission, the store of
40 //! seen hashes, proofs, and receipts.
41 //!
42 //! - *proof*: a packet carrying a signature over an earlier packet's hash, sent
43 //!   back so the sender learns the packet arrived.
44 
45 pub const Hash = [32]u8;
46 
47 pub const filter = @import("filter.zig");
48 pub const hashlist = @import("hashlist.zig");
49 pub const proof = @import("proof.zig");
50 pub const receipt = @import("receipt.zig");