tiny.reticulum.node

1/// The shared key and code length that authenticate every frame on one carrier, for a caller that2/// runs a closed network and hands one of these to `registerCarrier`. The node appends the code to3/// each frame it sends on that carrier and checks and strips it from each frame it receives. The4/// key is 64 bytes and the code runs from 1 to 64 bytes.5pub const Access = struct {6    key: ifac.Key,7    size: ifac.Size,8};

1/// What the node remembers about one carrier, so a caller reads one of these to see what the node2/// believes about a carrier it registered: that it is registered, whether the node may send on it,3/// whether it searches for paths it lacks, and its access code, if it has one. The node holds one4/// of these for every carrier index its limits allow, in storage the caller supplied. A carrier5/// with no access code carries its frames as they are.6pub const Registration = struct {7    registered: u1 = 0,8    outgoing: u1 = 0,9    /// Whether the node asks this carrier for a path it lacks, which Reticulum@1.5.010    /// RNS/Interfaces/Interface.py:55,121 leaves off, so a caller turns this on for the carrier it11    /// wants the node to search when it has no path to a destination. Registering the carrier again12    /// returns the setting to off.13    discover_paths: u1 = 0,14    access: ?Access = null,15};

1pub const Code = enum(u8) {2    unregistered_interface,3    frame_too_large,4    ifac_unexpected_flag,5    ifac_missing_flag,6    ifac_invalid_code,7    ifac_truncated,8    malformed_packet,9    duplicate_packet,10    packet_filtered,11    no_path,12    path_request_malformed,13    path_request_duplicate,14    path_request_batched,15    invalid_announce,16    own_announce,17    announce_key_changed,18    announce_table_full,19    discovery_table_full,20    announce_relay_too_large,21    unknown_destination,22    destination_type_mismatch,23    decryption_failed,24    proof_rejected,25    proof_relay_wrong_interface,26    links_unsupported,27    links_full,28    link_request_invalid,29    link_request_duplicate,30    unknown_link,31    link_state_mismatch,32    link_wrong_interface,33    link_close_invalid,34    link_entries_full,35    link_relay_early,36    link_relay_no_direction,37    unsupported_context,38    storage_failed,39};

1pub const Effect = union(enum) {2    carrier_send: struct {3        interface: carrier.Index,4        frame: []const u8,5    },6    application_delivery: struct {7        destination: [16]u8,8        packet_hash: [32]u8,9        plaintext: []const u8,10        ratchet_id: ?[10]u8,11        proof_requested: bool,12        interface: carrier.Index,13    },14    announce_received: AnnounceReceived,15    path_request: PathRequest,16    receipt_update: struct {17        packet_hash: packet.Hash,18        status: packet.receipt.Status,19        rtt: ?timer.Seconds,20    },21    persist: struct {22        kind: PersistKind,23        key: [16]u8,24        bytes: []const u8,25        token: event.PersistToken,26    },27    schedule_timer: struct {28        id: timer.TimerId,29        at: timer.Seconds,30    },31    diagnostic: struct {32        code: Code,33        packet_hash: ?[32]u8,34    },35    link_requested: LinkRequested,36    link_established: LinkEstablished,37    link_delivery: LinkDelivery,38    link_closed: LinkClosed,39};

1pub const Effects = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: Capacity,4    storage: Storage,5    entries: []Effect,6    frames: []carrier.Frame,7    len: usize = 0,8    frames_used: usize = 0,910    pub const storage_alignment: usize = 8;11    pub const Storage = []align(storage_alignment) u8;12    pub const Limits: type = EffectsLimits;13    pub const Capacity: type = EffectsCapacity;14    pub const Exhaustion = error{Full};15    pub const InitError = Capacity.DeriveError || error{StorageLengthMismatch};16    pub const work_limits: alloc_phase.capacity.WorkLimits = .{17        .transition_steps_max = 2,18        .cleanup_steps_per_call_max = 0,19        .cleanup_calls_at_capacity_max = 0,20    };21    pub const claim: alloc_phase.capacity.Declaration = .{22        .source = .{23            .id = "reticulum.effects",24            .kind = .phase_static,25            .limit_source = .caller,26            .storage = .{27                .covered = &.{28                    .{29                        .id = "caller_effect_entries",30                        .lifetime = .transferred,31                        .detail = "caller storage for bounded effect values",32                    },33                    .{34                        .id = "caller_effect_frames",35                        .lifetime = .transferred,36                        .detail = "caller storage for bounded inline effect frame copies",37                    },38                },39                .excluded = &.{40                    "event input slices",41                    "carrier devices, application callbacks, and persistence state",42                },43            },44            .capacity = .{45                .inputs = &.{46                    alloc_phase.capacity.bindInput(EffectsLimits, "effects_max", "effects_max"),47                    alloc_phase.capacity.bindInput(EffectsLimits, "frames_max", "frames_max"),48                },49                .type_selectors = &.{50                    alloc_phase.capacity.bindType(Effect, "effect"),51                    alloc_phase.capacity.bindType(carrier.Frame, "frame"),52                },53                .nodes = &.{54                    .{ .input = 0 },55                    .{ .scale = .{56                        .node = 0,57                        .coefficient = .{ .size_of_concrete_type = 0 },58                    } },59                    .{ .input = 1 },60                    .{ .scale = .{61                        .node = 2,62                        .coefficient = .{ .size_of_concrete_type = 1 },63                    } },64                    .{ .add = .{ .left = 1, .right = 3 } },65                },66                .assertions = &.{.{67                    .scope = .closure_total,68                    .measure = .retained,69                    .relation = .exact,70                    .expression = 4,71                }},72            },73            .overload = .{74                .kind = .reject_before_mutation,75                .detail = "full effect or frame admission preserves every retained effect",76            },77            .risks = .{78                .transitive = .{79                    .status = .excluded,80                    .detail = "effect copying calls no allocating owner",81                },82                .foreign = .{83                    .status = .excluded,84                    .detail = "the effect sink crosses no foreign boundary",85                },86            },87            .work = .{ .equation = "push copies at most one frame and one effect" },88            .obligations = &.{89                .{ .key = "reticulum_effects_capacity", .role = .capacity_model },90                .{ .key = "reticulum_effects_overload", .role = .overload },91                .{ .key = "reticulum_effects_work", .role = .work_bound },92            },93        },94        .bindings = .{95            .owner = @This(),96            .seal = .{97                .family = alloc_phase.capacity.selector(@This().activate),98                .premise = .{ .class = .checked_semantic_fact, .authority = .checker },99            },100            .teardown = .{101                .family = alloc_phase.capacity.selector(@This().deinit),102                .premise = .{ .class = .checked_semantic_fact, .authority = .checker },103            },104        },105    };106107    pub fn init(storage: Storage, limits: Limits) InitError!Effects {108        const capacity = try Capacity.derive(limits);109        if (storage.len != capacity.storage_bytes) return error.StorageLengthMismatch;110        const entries = std.mem.bytesAsSlice(Effect, storage[0..capacity.effect_bytes]);111        const frame_storage: []align(@alignOf(carrier.Frame)) u8 = @alignCast(112            storage[capacity.effect_bytes..],113        );114        const frames = std.mem.bytesAsSlice(carrier.Frame, frame_storage);115        for (frames) |*frame| frame.* = .{};116        return .{117            .phase = .initialization,118            .capacity = capacity,119            .storage = storage,120            .entries = entries,121            .frames = frames,122        };123    }124125    pub fn activate(self: *Effects) void {126        std.debug.assert(self.phase == .initialization);127        std.debug.assert(self.len == 0);128        std.debug.assert(self.frames_used == 0);129        self.phase = .steady;130    }131132    pub fn push(self: *Effects, value: Effect) Exhaustion!void {133        std.debug.assert(self.phase == .steady);134        if (self.len == self.capacity.effects_max) return error.Full;135        const retained: Effect = switch (value) {136            .carrier_send => |send| .{ .carrier_send = .{137                .interface = send.interface,138                .frame = try self.retain(send.frame),139            } },140            .application_delivery => |delivery| .{ .application_delivery = .{141                .destination = delivery.destination,142                .packet_hash = delivery.packet_hash,143                .plaintext = try self.retain(delivery.plaintext),144                .ratchet_id = delivery.ratchet_id,145                .proof_requested = delivery.proof_requested,146                .interface = delivery.interface,147            } },148            .announce_received => |announce| .{ .announce_received = .{149                .destination_hash = announce.destination_hash,150                .identity_hash = announce.identity_hash,151                .public_key = announce.public_key,152                .app_data = try self.retain(announce.app_data),153                .hops = announce.hops,154                .rotating_key_present = announce.rotating_key_present,155                .path_response = announce.path_response,156            } },157            .link_delivery => |delivery| .{ .link_delivery = .{158                .link_id = delivery.link_id,159                .packet_hash = delivery.packet_hash,160                .plaintext = try self.retain(delivery.plaintext),161                .proof_requested = delivery.proof_requested,162            } },163            .persist => |persist| .{ .persist = .{164                .kind = persist.kind,165                .key = persist.key,166                .bytes = try self.retain(persist.bytes),167                .token = persist.token,168            } },169            .receipt_update,170            .schedule_timer,171            .diagnostic,172            .path_request,173            .link_requested,174            .link_established,175            .link_closed,176            => value,177        };178        self.entries[self.len] = retained;179        self.len += 1;180    }181182    pub fn items(self: *const Effects) []const Effect {183        std.debug.assert(self.phase == .steady);184        return self.entries[0..self.len];185    }186187    pub fn reset(self: *Effects) void {188        std.debug.assert(self.phase == .steady);189        self.len = 0;190        self.frames_used = 0;191    }192193    pub fn deinit(self: *Effects) Storage {194        std.debug.assert(self.phase == .steady);195        self.phase = .teardown;196        const storage = self.storage;197        self.* = undefined;198        return storage;199    }200201    fn retain(self: *Effects, bytes: []const u8) Exhaustion![]const u8 {202        if (self.frames_used == self.capacity.frames_max) return error.Full;203        const frame = carrier.Frame.init(bytes) catch return error.Full;204        self.frames[self.frames_used] = frame;205        const retained = self.frames[self.frames_used].slice();206        self.frames_used += 1;207        return retained;208    }209};

1/// Records why a link closed: a deadline passed, the initiator closed it, or the responder closed2/// it. Reticulum@1.5.0 RNS/Link.py:116-118 names the same three teardown reasons `TIMEOUT`,3/// `INITIATOR_CLOSED`, and `DESTINATION_CLOSED`.4pub const LinkCloseReason = enum(u8) {5    timeout = 1,6    initiator_closed = 2,7    destination_closed = 3,8};

1pub const PersistKind = enum(u8) {2    known_identity,3    known_ratchet,4    ratchet_ring,5};

1pub const Error = error{2    EffectsFull,3    TimerFull,4    NoOutgoingCarrier,5    UnknownDestination,6    InvalidDestination,7    InvalidHops,8    PacketTooLarge,9    EncryptionFailed,10    AppDataTooLong,11    MissingEntropy,12    TimestampOutOfRange,13    ProofUnavailable,14    LinksFull,15    DuplicateLink,16    UnknownLink,17    LinkNotEstablished,18};

1pub const ApplicationAnnounce = struct {2    destination: [16]u8,3    app_data: []const u8,4    random: [5]u8,5    fresh_rotating_key: ?[32]u8,6    now: timer.Seconds,7    /// The carrier to answer a path request on, which a caller sets on an announce so8    /// Reticulum@1.5.0 RNS/Transport.py:3379-3382 answers on that carrier alone. Left null, the9    /// announce goes out on every outgoing carrier.10    path_response: ?carrier.Index = null,11};

1/// Asks the node to take down one link it holds open, so a caller can close a link once done with2/// it. An encrypted LINKCLOSE goes out, the link leaves the pool, and the caller hears that it3/// closed. A link that has yet to activate drops at once with no packet sent. The reason is4/// `initiator_closed` on an initiator and `destination_closed` on a responder, per Reticulum@1.5.05/// RNS/Link.py:657-672.6pub const ApplicationLinkClose = struct {7    link_id: [16]u8,8    iv: [16]u8,9    now: timer.Seconds,10};

1/// Asks the node to open a link toward a single destination it holds an identity for, learned from2/// an announce, for an encrypted session that outlives a single packet. `encryption_private` and3/// `signing_private` hold the X25519 and Ed25519 private keys the initiator uses for this session4/// alone, and Reticulum@1.5.0 RNS/Link.py:284-285 draws both at random.5pub const ApplicationLinkOpen = struct {6    destination: [16]u8,7    encryption_private: [32]u8,8    signing_private: [32]u8,9    now: timer.Seconds,10    /// What the node does with data delivered over this link, chosen here for an initiator link11    /// because it has no registered destination to read it from. Under `.none` the node proves12    /// nothing, under `.all` it proves every delivered packet at once, and under `.app` it reports13    /// each delivery with a proof request that a link proof event answers. By contrast, a responder14    /// reads this from its destination, per Reticulum@1.5.0 RNS/Link.py:958-968.15    proof_strategy: ProofStrategy = .none,16};

1/// Asks the node to answer one packet of link data it has handed up with a proof, so a caller under2/// the `.app` strategy can answer a delivery that asked to be proved. The application names the3/// packet hash from a delivery whose `proof_requested` was set, and the node sends that hash and a4/// signature over it as link plaintext. A packet the node has already forgotten returns5/// `error.ProofUnavailable`, per Reticulum@1.5.0 RNS/Link.py:378-389.6pub const ApplicationLinkProve = struct {7    link_id: [16]u8,8    packet_hash: [32]u8,9    now: timer.Seconds,10};

1/// Asks the node to put application plaintext across a link that has activated, so the caller can2/// send application bytes over the open link. Plaintext over 431 bytes returns3/// `error.PacketTooLarge` before the node changes anything, per Reticulum@1.5.0 RNS/Link.py:73.4/// With `create_receipt` set, the node tracks the delivery, fails a receipt that stays in the table5/// max(rtt * 6, 0.005) seconds after the send when no proof has arrived, per Reticulum@1.5.06/// RNS/Packet.py:419-420 and Reticulum@1.5.0 RNS/Transport.py:1307-1318, and culls the oldest7/// receipt and reports it as a `receipt_update` effect with status `culled` and no round trip time8/// when a later send that asks for a receipt finds the receipt table full.9pub const ApplicationLinkSend = struct {10    link_id: [16]u8,11    plaintext: []const u8,12    iv: [16]u8,13    now: timer.Seconds,14    create_receipt: bool = true,15};

1/// Asks any node that knows a path to the named destination to answer with one, carrying the2/// caller's own tag, for a caller that has yet to learn a route to that destination, as3/// Reticulum@1.5.0 RNS/Transport.py:3207-3220 requests it. Naming a carrier sends the request on4/// that carrier alone, and leaving it null sends it on every outgoing carrier.5pub const ApplicationPathRequest = struct {6    destination: [16]u8,7    tag: [16]u8,8    interface: ?carrier.Index,9    now: timer.Seconds,10};

1pub const ApplicationProve = struct {2    destination: [16]u8,3    packet_hash: [32]u8,4    interface: carrier.Index,5    now: timer.Seconds,6};

1pub const ApplicationSend = struct {2    destination: [16]u8,3    now: timer.Seconds,4    plaintext: []const u8,5    context: wire.Context = .none,6    hops: u8 = 0,7    ephemeral_private: [32]u8,8    iv: [16]u8,9    create_receipt: bool = true,10};

1pub const CarrierFrame = struct {2    interface: carrier.Index,3    now: timer.Seconds,4    bytes: []const u8,5    /// Thirty-two bytes of randomness that the caller renews for every frame it gives the node, so6    /// a link's keys on the receiving side come out of them. A step that needs a key or an7    /// initialization vector runs HKDF-SHA256 over those bytes, taking the link id as the salt and8    /// a label that names the use. A responder gets its X25519 private key from this expansion, and9    /// Reticulum@1.5.0 RNS/Link.py:276 draws one at random. An initiator's round trip packet and a10    /// responder's LINKCLOSE take their initialization vectors this way, and Reticulum@1.5.011    /// RNS/Cryptography/Token.py:89 draws a random one.12    entropy: [32]u8,13};

1pub const Event = union(enum) {2    carrier_frame: CarrierFrame,3    timer_expired: TimerExpired,4    application_send: ApplicationSend,5    application_announce: ApplicationAnnounce,6    application_prove: ApplicationProve,7    application_path_request: ApplicationPathRequest,8    application_link_open: ApplicationLinkOpen,9    application_link_send: ApplicationLinkSend,10    application_link_close: ApplicationLinkClose,11    application_link_prove: ApplicationLinkProve,12    storage_complete: StorageComplete,13};

1pub const StorageComplete = struct {2    token: PersistToken,3    now: timer.Seconds,4};

1pub const TimerExpired = struct {2    id: timer.TimerId,3    now: timer.Seconds,4    /// Thirty-two bytes of randomness that the caller renews for every timer it reports, so a timer5    /// that closes a link can encrypt. A step driven by a timer derives its keys and initialization6    /// vectors the same way, through HKDF-SHA256 with the link id as the salt and a label that7    /// names the use.8    entropy: [32]u8,9};

1pub const Capacity = struct {2    interface_storage_bytes: usize,3    identity_storage_bytes: usize,4    ratchet_binding_storage_bytes: usize,5    scratch_storage_bytes: usize,6    destinations: destination.registry.Table.Capacity,7    known_identities: identity.known.Identities.Capacity,8    known_ratchets: identity.known.Ratchets.Capacity,9    receipts: packet.receipt.Table.Capacity,10    duplicate_hashes: packet.hashlist.Table.Capacity,11    timers: timer.Table.Capacity,12    transport: transport.State.Capacity,13    effects: effect.Effects.Capacity,14    identities_offset: usize,15    ratchet_bindings_offset: usize,16    destinations_offset: usize,17    known_identities_offset: usize,18    known_ratchets_offset: usize,19    receipts_offset: usize,20    duplicate_hashes_offset: usize,21    timers_offset: usize,22    transport_offset: usize,23    effects_offset: usize,24    scratch_offset: usize,25    storage_bytes: usize,2627    pub const DeriveError = error{ InvalidLimit, CapacityOverflow };2829    pub fn derive(limits: Limits) DeriveError!Capacity {30        if (limits.interfaces_max == 0) return error.InvalidLimit;31        if (limits.interfaces_max > @as(usize, std.math.maxInt(carrier.Index)) + 1) {32            return error.InvalidLimit;33        }34        const subs = try deriveSubcapacities(limits);35        const interface_storage_bytes = try alloc_phase.capacity.mul(36            usize,37            limits.interfaces_max,38            @sizeOf(access.Registration),39        );40        var cursor = try alignForward(interface_storage_bytes, 8);41        const identities_offset = try advance(&cursor, try alloc_phase.capacity.mul(42            usize,43            limits.destinations_max,44            @sizeOf(identity.Private),45        ));46        const ratchet_bindings_offset = try advance(&cursor, try alloc_phase.capacity.mul(47            usize,48            limits.destinations_max,49            @sizeOf(RatchetBinding),50        ));51        const destinations_offset = try advance(&cursor, subs.destinations.storage_bytes);52        const known_identities_offset = try advance(&cursor, subs.known_identities.storage_bytes);53        const known_ratchets_offset = try advance(&cursor, subs.known_ratchets.storage_bytes);54        const receipts_offset = try advance(&cursor, subs.receipts.storage_bytes);55        const duplicate_hashes_offset = try advance(&cursor, subs.duplicate_hashes.storage_bytes);56        const timers_offset = try advance(&cursor, subs.timers.storage_bytes);57        const transport_offset = try advance(&cursor, subs.transport.storage_bytes);58        const effects_offset = try advance(&cursor, subs.effects.storage_bytes);59        const scratch_offset = try advance(&cursor, wire.mtu);60        return .{61            .interface_storage_bytes = interface_storage_bytes,62            .identity_storage_bytes = ratchet_bindings_offset - identities_offset,63            .ratchet_binding_storage_bytes = destinations_offset - ratchet_bindings_offset,64            .scratch_storage_bytes = wire.mtu,65            .destinations = subs.destinations,66            .known_identities = subs.known_identities,67            .known_ratchets = subs.known_ratchets,68            .receipts = subs.receipts,69            .duplicate_hashes = subs.duplicate_hashes,70            .timers = subs.timers,71            .transport = subs.transport,72            .effects = subs.effects,73            .identities_offset = identities_offset,74            .ratchet_bindings_offset = ratchet_bindings_offset,75            .destinations_offset = destinations_offset,76            .known_identities_offset = known_identities_offset,77            .known_ratchets_offset = known_ratchets_offset,78            .receipts_offset = receipts_offset,79            .duplicate_hashes_offset = duplicate_hashes_offset,80            .timers_offset = timers_offset,81            .transport_offset = transport_offset,82            .effects_offset = effects_offset,83            .scratch_offset = scratch_offset,84            .storage_bytes = cursor,85        };86    }87};

1pub const Limits = struct {2    interfaces_max: usize,3    destinations_max: usize,4    known_identities_max: usize,5    known_ratchets_max: usize,6    receipts_max: usize,7    duplicate_hashes_max: usize,8    timers_max: usize,9    effects_max: usize,10    effect_frames_max: usize,11    paths_max: usize,12    announces_max: usize,13    reverse_entries_max: usize,14    path_request_tags_max: usize,15    inflight_requests_max: usize,16    discoveries_max: usize,17    links_max: usize,18    link_entries_max: usize,1920    /// One set of limits that pairs the reference receipt, hash, and tag maxima above with a single21    /// entry in every other table. The tests derive a capacity from it to show that those maxima22    /// fit and that raising one past the range of its entry type is refused.23    pub const reference = Limits{24        .interfaces_max = 1,25        .destinations_max = 1,26        .known_identities_max = 1,27        .known_ratchets_max = 1,28        .receipts_max = reference_receipts_max,29        .duplicate_hashes_max = reference_duplicate_hashes_max,30        .timers_max = 1,31        .effects_max = effect.effects_per_event_max,32        .effect_frames_max = effect.effect_frames_per_event_max,33        .paths_max = 1,34        .announces_max = 1,35        .reverse_entries_max = 1,36        .path_request_tags_max = reference_path_request_tags_max,37        .inflight_requests_max = 1,38        .discoveries_max = 1,39        .links_max = 1,40        .link_entries_max = 1,41    };42};

1pub const RatchetBinding = struct {2    ring: ?*identity.Ring = null,3    enforce: bool = false,4};

1pub const Node = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: Capacity,4    storage: Storage,5    interfaces: []Interface,6    identities: []identity.Private,7    ratchet_bindings: []RatchetBinding,8    destinations: destination.registry.Table,9    known_identities: identity.known.Identities,10    known_ratchets: identity.known.Ratchets,11    receipts: packet.receipt.Table,12    duplicate_hashes: packet.hashlist.Table,13    timers: timer.Table,14    transport: transport.State,15    effects: effect.Effects,16    scratch: []u8,17    proof_mode: ProofMode = .implicit,1819    pub const storage_alignment: usize = 8;20    pub const Storage = []align(storage_alignment) u8;21    pub const Limits: type = limits.Limits;22    pub const Capacity: type = limits.Capacity;23    pub const InitError = Capacity.DeriveError || error{StorageLengthMismatch};24    pub const work_limits: alloc_phase.capacity.WorkLimits = .{25        .transition_steps_max = 8,26        .cleanup_steps_per_call_max = 0,27        .cleanup_calls_at_capacity_max = 0,28    };29    pub const claim: alloc_phase.capacity.Declaration = .{30        .source = .{31            .id = "reticulum.node",32            .kind = .phase_static,33            .limit_source = .caller,34            .storage = .{35                .covered = &.{36                    .{37                        .id = "caller_interface_slots",38                        .lifetime = .transferred,39                        .detail = "caller storage for bounded carrier access registrations",40                    },41                    .{42                        .id = "caller_node_subowners",43                        .lifetime = .transferred,44                        .detail = "caller storage for local identities and eight strict subowners",45                    },46                    .{47                        .id = "caller_node_work",48                        .lifetime = .transferred,49                        .detail = "caller storage for rotating-key bindings and one MTU scratch",50                    },51                },52                .excluded = &.{53                    "carrier memory and interface devices",54                    "bound rotating-key rings and application payload inputs",55                    "persistent storage and operating-system state",56                },57            },58            .capacity = .{59                .inputs = &.{60                    alloc_phase.capacity.bindInput(Limits, "interfaces", "interfaces_max"),61                    alloc_phase.capacity.bindInput(Limits, "destinations", "destinations_max"),62                    alloc_phase.capacity.bindInput(Limits, "identities", "known_identities_max"),63                    alloc_phase.capacity.bindInput(Limits, "ratchets", "known_ratchets_max"),64                    alloc_phase.capacity.bindInput(Limits, "receipts", "receipts_max"),65                    alloc_phase.capacity.bindInput(Limits, "hashes", "duplicate_hashes_max"),66                    alloc_phase.capacity.bindInput(Limits, "timers", "timers_max"),67                    alloc_phase.capacity.bindInput(Limits, "effects", "effects_max"),68                    alloc_phase.capacity.bindInput(Limits, "frames", "effect_frames_max"),69                    alloc_phase.capacity.bindInput(Limits, "paths", "paths_max"),70                    alloc_phase.capacity.bindInput(Limits, "announces", "announces_max"),71                    alloc_phase.capacity.bindInput(72                        Limits,73                        "reverse_entries",74                        "reverse_entries_max",75                    ),76                    alloc_phase.capacity.bindInput(77                        Limits,78                        "path_request_tags",79                        "path_request_tags_max",80                    ),81                    alloc_phase.capacity.bindInput(82                        Limits,83                        "inflight_requests",84                        "inflight_requests_max",85                    ),86                    alloc_phase.capacity.bindInput(Limits, "discoveries", "discoveries_max"),87                    alloc_phase.capacity.bindInput(Limits, "links", "links_max"),88                },89                .type_selectors = &.{90                    alloc_phase.capacity.bindType(identity.Private, "private_identity"),91                    alloc_phase.capacity.bindType(RatchetBinding, "ratchet_binding"),92                    alloc_phase.capacity.bindType(93                        destination.registry.Entry,94                        "destination",95                    ),96                    alloc_phase.capacity.bindType(97                        identity.known.IdentityEntry,98                        "identity",99                    ),100                    alloc_phase.capacity.bindType(101                        identity.known.RatchetEntry,102                        "ratchet",103                    ),104                    alloc_phase.capacity.bindType(packet.receipt.Receipt, "receipt"),105                    alloc_phase.capacity.bindType(packet.Hash, "hash"),106                    alloc_phase.capacity.bindType(timer.Timer, "timer"),107                    alloc_phase.capacity.bindType(effect.Effect, "effect"),108                    alloc_phase.capacity.bindType(carrier.Frame, "frame"),109                    alloc_phase.capacity.bindType(Interface, "interface"),110                    alloc_phase.capacity.bindType(transport.path.Entry, "path"),111                    alloc_phase.capacity.bindType(transport.announces.Entry, "announce"),112                    alloc_phase.capacity.bindType(transport.reverse.Entry, "reverse_entry"),113                    alloc_phase.capacity.bindType(transport.inflight.Entry, "inflight_request"),114                    alloc_phase.capacity.bindType(transport.discoveries.Entry, "discovery"),115                },116                .nodes = &.{117                    .{ .input = 0 },118                    .{ .scale = .{119                        .node = 0,120                        .coefficient = .{ .size_of_concrete_type = 10 },121                    } },122                    .{ .alignment = .{ .node = 1, .alignment = .{ .literal = 8 } } },123                    .{ .input = 1 },124                    .{ .scale = .{125                        .node = 3,126                        .coefficient = .{ .size_of_concrete_type = 0 },127                    } },128                    .{ .add = .{ .left = 2, .right = 4 } },129                    .{ .scale = .{130                        .node = 3,131                        .coefficient = .{ .size_of_concrete_type = 1 },132                    } },133                    .{ .add = .{ .left = 5, .right = 6 } },134                    .{ .scale = .{135                        .node = 3,136                        .coefficient = .{ .size_of_concrete_type = 2 },137                    } },138                    .{ .add = .{ .left = 7, .right = 8 } },139                    .{ .input = 2 },140                    .{ .scale = .{141                        .node = 10,142                        .coefficient = .{ .size_of_concrete_type = 3 },143                    } },144                    .{ .add = .{ .left = 9, .right = 11 } },145                    .{ .input = 3 },146                    .{ .scale = .{147                        .node = 13,148                        .coefficient = .{ .size_of_concrete_type = 4 },149                    } },150                    .{ .add = .{ .left = 12, .right = 14 } },151                    .{ .input = 4 },152                    .{ .scale = .{153                        .node = 16,154                        .coefficient = .{ .size_of_concrete_type = 5 },155                    } },156                    .{ .add = .{ .left = 15, .right = 17 } },157                    .{ .input = 5 },158                    .{ .scale = .{159                        .node = 19,160                        .coefficient = .{ .size_of_concrete_type = 6 },161                    } },162                    .{ .add = .{ .left = 18, .right = 20 } },163                    .{ .input = 6 },164                    .{ .scale = .{165                        .node = 22,166                        .coefficient = .{ .size_of_concrete_type = 7 },167                    } },168                    .{ .add = .{ .left = 21, .right = 23 } },169                    .{ .input = 7 },170                    .{ .scale = .{171                        .node = 25,172                        .coefficient = .{ .size_of_concrete_type = 8 },173                    } },174                    .{ .add = .{ .left = 24, .right = 26 } },175                    .{ .input = 8 },176                    .{ .scale = .{177                        .node = 28,178                        .coefficient = .{ .size_of_concrete_type = 9 },179                    } },180                    .{ .add = .{ .left = 27, .right = 29 } },181                    .{ .input = 9 },182                    .{ .scale = .{183                        .node = 31,184                        .coefficient = .{ .size_of_concrete_type = 11 },185                    } },186                    .{ .add = .{ .left = 30, .right = 32 } },187                    .{ .input = 10 },188                    .{ .scale = .{189                        .node = 34,190                        .coefficient = .{ .size_of_concrete_type = 12 },191                    } },192                    .{ .add = .{ .left = 33, .right = 35 } },193                    .{ .input = 11 },194                    .{ .scale = .{195                        .node = 37,196                        .coefficient = .{ .size_of_concrete_type = 13 },197                    } },198                    .{ .add = .{ .left = 36, .right = 38 } },199                    .{ .input = 12 },200                    .{ .scale = .{201                        .node = 40,202                        .coefficient = .{ .size_of_concrete_type = 6 },203                    } },204                    .{ .add = .{ .left = 39, .right = 41 } },205                    .{ .input = 13 },206                    .{ .scale = .{207                        .node = 43,208                        .coefficient = .{ .size_of_concrete_type = 14 },209                    } },210                    .{ .add = .{ .left = 42, .right = 44 } },211                    .{ .input = 14 },212                    .{ .scale = .{213                        .node = 46,214                        .coefficient = .{ .size_of_concrete_type = 15 },215                    } },216                    .{ .add = .{ .left = 45, .right = 47 } },217                    .{ .input = 15 },218                    .{ .scale = .{219                        .node = 49,220                        .coefficient = .{ .literal = @sizeOf(transport.links.Entry) },221                    } },222                    .{ .add = .{ .left = 48, .right = 50 } },223                    .{ .constant = 500 },224                    .{ .add = .{ .left = 51, .right = 52 } },225                },226                .assertions = &.{.{227                    .scope = .closure_total,228                    .measure = .retained,229                    .relation = .exact,230                    .expression = 53,231                }},232            },233            .overload = .{234                .kind = .reject_before_seal,235                .detail = "invalid limits and short caller storage reject before activation",236            },237            .risks = .{238                .transitive = .{239                    .status = .witnessed,240                    .detail = "all retained subowner storage is carved from the node region",241                },242                .foreign = .{243                    .status = .excluded,244                    .detail = "the node owner crosses no foreign boundary",245                },246            },247            .work = .{ .equation = "activation and teardown each visit eight subowners" },248            .dependencies = &.{249                "reticulum.destinations",250                "reticulum.known_identities",251                "reticulum.known_ratchets",252                "reticulum.receipts",253                "reticulum.hashlist",254                "reticulum.timers",255                "reticulum.effects",256                "reticulum.transport",257            },258            .obligations = &.{259                .{ .key = "reticulum_node_capacity", .role = .capacity_model },260                .{ .key = "reticulum_node_overload", .role = .overload },261                .{ .key = "reticulum_node_transitive", .role = .transitive_risk },262                .{ .key = "reticulum_node_work", .role = .work_bound },263            },264        },265        .bindings = .{266            .owner = @This(),267            .seal = .{268                .family = alloc_phase.capacity.selector(@This().activate),269                .premise = .{ .class = .checked_semantic_fact, .authority = .checker },270            },271            .teardown = .{272                .family = alloc_phase.capacity.selector(@This().deinit),273                .premise = .{ .class = .checked_semantic_fact, .authority = .checker },274            },275        },276    };277278    pub fn init(storage: Storage, selected: Limits) InitError!Node {279        const capacity = try Capacity.derive(selected);280        if (storage.len != capacity.storage_bytes) return error.StorageLengthMismatch;281        const interfaces = initializeInterfaces(storage, capacity);282        const identities = std.mem.bytesAsSlice(identity.Private, region(283            storage,284            capacity.identities_offset,285            capacity.identity_storage_bytes,286        ));287        for (identities) |*private| private.* = identity.Private.fromBytes(@splat(0));288        const ratchet_bindings = std.mem.bytesAsSlice(RatchetBinding, region(289            storage,290            capacity.ratchet_bindings_offset,291            capacity.ratchet_binding_storage_bytes,292        ));293        @memset(ratchet_bindings, .{});294        const subowners = try initSubowners(storage, capacity, selected);295        const scratch = storage[capacity.scratch_offset..][0..capacity.scratch_storage_bytes];296        @memset(scratch, 0);297        return .{298            .phase = .initialization,299            .capacity = capacity,300            .storage = storage,301            .interfaces = interfaces,302            .identities = identities,303            .ratchet_bindings = ratchet_bindings,304            .destinations = subowners.destinations,305            .known_identities = subowners.known_identities,306            .known_ratchets = subowners.known_ratchets,307            .receipts = subowners.receipts,308            .duplicate_hashes = subowners.duplicate_hashes,309            .timers = subowners.timers,310            .transport = subowners.transport,311            .effects = subowners.effects,312            .scratch = scratch,313        };314    }315316    pub fn activate(self: *Node) void {317        std.debug.assert(self.phase == .initialization);318        self.destinations.activate();319        self.known_identities.activate();320        self.known_ratchets.activate();321        self.receipts.activate();322        self.duplicate_hashes.activate();323        self.timers.activate();324        self.transport.activate();325        self.effects.activate();326        self.phase = .steady;327    }328329    pub fn identityAt(self: *Node, index: usize) ?*identity.Private {330        std.debug.assert(self.phase == .steady);331        if (index >= self.identities.len) return null;332        return &self.identities[index];333    }334335    /// Registers one carrier index, so the node accepts frames that arrive on it and, with336    /// `outgoing` set, sends on it as well. An access code given here authenticates every frame in337    /// both directions on that carrier. An index at or past the caller's carrier maximum returns338    /// `error.Index`. Registering the same index again zeroes what was there, so its path discovery339    /// returns to off.340    pub fn registerCarrier(341        self: *Node,342        index: carrier.Index,343        outgoing: bool,344        access_config: ?Access,345    ) error{Index}!void {346        std.debug.assert(self.phase == .steady);347        std.debug.assert(self.interfaces.len > 0);348        std.debug.assert(self.interfaces.len <= @as(usize, std.math.maxInt(carrier.Index)) + 1);349        if (access_config) |value| {350            std.debug.assert(value.size.byte() >= ifac.min_size_bytes);351            std.debug.assert(@as(usize, wire.mtu) + value.size.byte() <= carrier.frame_bytes_max);352        }353        const slot: usize = index;354        if (slot >= self.interfaces.len) return error.Index;355        std.crypto.secureZero(u8, std.mem.asBytes(&self.interfaces[slot]));356        self.interfaces[slot] = .{357            .registered = 1,358            .outgoing = @intFromBool(outgoing),359            .access = access_config,360        };361        std.debug.assert(self.interfaces[slot].registered == 1);362    }363364    /// Binds a rotating-key ring to one of the node's own identities, so announces from that365    /// identity carry a rotating public key and data addressed to it is decrypted with the ring's366    /// keys first. The ring stays the caller's and has to outlive the node, which holds only a367    /// pointer to it. With `enforce` set, the node decrypts only with the ring's keys, so a packet368    /// that none of them open fails. An identity index at or past the caller's destination maximum369    /// returns `error.Index`.370    pub fn bindRatchetRing(371        self: *Node,372        identity_index: usize,373        ring: *identity.Ring,374        enforce: bool,375    ) error{Index}!void {376        std.debug.assert(self.phase == .steady);377        if (identity_index >= self.ratchet_bindings.len) return error.Index;378        self.ratchet_bindings[identity_index] = .{ .ring = ring, .enforce = enforce };379    }380381    /// Chooses whether a proof this node sends carries the proved packet's hash beside the382    /// signature or the signature alone. The node starts in implicit mode, with the signature383    /// alone.384    pub fn setProofMode(self: *Node, mode: ProofMode) void {385        std.debug.assert(self.phase == .steady);386        self.proof_mode = mode;387    }388389    /// Turns the node into one that carries traffic for others and gives it the 16 bytes that name390    /// it to its neighbors, which Reticulum@1.5.0 RNS/Transport.py:1577-1580,1907 sets. An enabled391    /// transport node rebroadcasts the announces it accepts and relays the packets that name it as392    /// the next hop.393    pub fn setTransport(self: *Node, identity_hash: [16]u8, enabled: bool) void {394        std.debug.assert(self.phase == .steady);395        self.transport.configure(identity_hash, enabled);396    }397398    /// Lets the node ask one carrier for a path it lacks, which Reticulum@1.5.0399    /// RNS/Transport.py:3352-3355 searches. An index at or past the carrier maximum, or one the400    /// caller has yet to register, returns `error.Index`. Registering that carrier again returns401    /// the setting to off, per Reticulum@1.5.0 RNS/Interfaces/Interface.py:55,121.402    pub fn setPathDiscovery(self: *Node, index: carrier.Index, enabled: bool) error{Index}!void {403        std.debug.assert(self.phase == .steady);404        const slot: usize = index;405        if (slot >= self.interfaces.len) return error.Index;406        if (self.interfaces[slot].registered == 0) return error.Index;407        self.interfaces[slot].discover_paths = @intFromBool(enabled);408        std.debug.assert(self.interfaces[slot].discover_paths == @intFromBool(enabled));409    }410411    /// Applies one event and returns the effects it produced. The effects point into the node's own412    /// storage and stay valid until the next call.413    pub fn step(self: *Node, value: event.Event) errors.Error![]const effect.Effect {414        return @import("step.zig").run(self, value);415    }416417    pub fn deinit(self: *Node) Storage {418        std.debug.assert(self.phase == .steady);419        _ = self.effects.deinit();420        _ = self.transport.deinit();421        _ = self.timers.deinit();422        _ = self.duplicate_hashes.deinit();423        _ = self.receipts.deinit();424        _ = self.known_ratchets.deinit();425        _ = self.known_identities.deinit();426        _ = self.destinations.deinit();427        std.crypto.secureZero(u8, std.mem.sliceAsBytes(self.interfaces));428        @memset(self.ratchet_bindings, .{});429        for (self.identities) |*private| private.zero();430        std.crypto.secureZero(u8, self.scratch);431        self.phase = .teardown;432        const storage = self.storage;433        self.* = undefined;434        return storage;435    }436};

1pub const ProofMode = enum(u1) {2    implicit,3    explicit,4};

1/// Gives the most byte slices one event's effects retain, so a caller sizes the effect list's frame2/// storage from this bound. One delivery that also proves reaches that number, retaining the3/// plaintext and 256 carrier frames.4pub const effect_frames_per_event_max: u16 = 257;

1/// Gives the most effects one event can produce, so a caller sizes its effect storage from this2/// bound. An announce reaches that number: it reports the announce, arms one timer, and sends one3/// answer over every one of 256 carriers. A link open with no known path reaches it too: it reports4/// the request, arms one timer, and sends that request over every one of 256 carriers.5pub const effects_per_event_max: u16 = 258;

1pub const PersistToken = u64;

1//! A state machine for one node of a mesh network holds everything the node remembers and turns one2//! input at a time into a list of things for the program around it to do. That network is3//! Reticulum, in which nodes find each other by broadcasting signed announcements and reach each4//! other over any network interface that moves bytes.5//!6//! Someone writing such a node has to decide what to put on the wire, what to remember about who is7//! out there, and when a deadline has passed, and the program around the node keeps the sockets,8//! the clock, and the source of randomness. The node has to run on machines whose memory is fixed9//! before the program starts, so it takes the size of each store it keeps from the caller and10//! refuses work once a store is full. A port of an existing protocol has to be checkable against11//! the original, byte for byte.12//!13//! Code that reads the wall clock and draws its own randomness gives a different answer on every14//! run, which leaves nothing to compare against a reference. Sending from inside the protocol logic15//! also needs somewhere for the bytes to live. A transition can run out of room part way through,16//! and a half-applied transition would leave the node's stores disagreeing with what the caller was17//! told.18//!19//! The subtree follows *Reticulum 1.5.0*, the reference implementation this package is a port of.20//! The package README and the generated conformance material pin the upstream commit. What the21//! subtree takes from the reference is its order of handling an arriving packet, its state machines22//! for routes and for encrypted sessions, and its timeouts, and each declaration names the23//! reference file and line range it follows. The package generates reference bytes and clocks from24//! that release (a *conformance corpus*) and replays them in differential tests, so each of those25//! claims is checkable from this tree.26//!27//! A transition (a *step*) takes the instant and the 32 bytes of randomness it needs from its own28//! input, so replaying the same inputs gives the same results. The node sends nothing, arms no29//! timer, and writes no storage itself: it appends a record of each such request (an *effect*) to a30//! list, and the caller performs them. Every transition first reserves room (a *reserve*): it31//! checks that the list of effects and the storage for its bytes can hold what it is about to32//! append before it changes any store, so a transition that runs out of room leaves the node as it33//! was. Every store takes its entry maximum (its *limits*) from the caller and is carved out of one34//! block of caller storage whose length has to equal the derived byte count exactly. The node keeps35//! one packet-sized buffer (its *scratch*) where a transition builds the bytes it is about to hand36//! to one network interface.37//!38//! The file exports the subtree's pieces: `Node` and `Limits`, the `Event` a transition takes and39//! the `Effect` records it returns, `timer`, and the modules `inbound` for arriving frames,40//! `outbound` for sends, `announce`, `link`, `transport` for carrying traffic on behalf of other41//! nodes, and `fixture`, the three-node test world.42//!43//! - *node*: the state machine that holds one Reticulum node's tables, one packet of scratch space,44//!   and its effect list.45//! - *event*: the one input a step takes, either a frame that arrived on a carrier, a timer that46//!   came due, an application request, or the completion of a caller's storage write.47//! - *step entropy*: the 32 bytes the caller draws fresh for each carrier frame and each timer48//!   event, which the step expands with HKDF-SHA256 whenever it needs a key or an initialization49//!   vector.50//! - *table*: an owner over caller-supplied bytes with a fixed entry maximum, which carves the51//!   caller's storage once and hands it back at teardown.52//! - *packet*: one Reticulum datagram, at most 500 bytes, carrying a flags byte, a hop count, an53//!   optional transport id, a destination hash, a context byte, and a payload.54//! - *frame*: the bytes handed to one carrier, one packet plus at most a 64-byte signature.55//! - *carrier*: one network interface a node sends and receives frames over, named by a byte index.56//! - *announce*: a packet carrying a destination's public keys, a name hash, ten random bytes, and57//!   a signature, so any node that hears it learns that destination and how far away it sits.58//! - *path*: what a node learned from an announce about reaching one destination: the carrier to59//!   send on, the neighbor to name as the next hop, and how many hops away it sits.60//! - *link*: an encrypted session between two endpoints, named by a 16-byte link id that both ends61//!   derive from the request packet.62//! - *timer*: a deadline the node holds, naming what comes due and the whole second it comes due63//!   at.64//! - *transport node*: a node that carries traffic on behalf of other nodes, as well as sending and65//!   receiving its own.6667const effect = @import("effect.zig");68const errors = @import("error.zig");69const event = @import("event.zig");70const limits = @import("limits.zig");71const owner = @import("owner.zig");72pub const timer = @import("timer.zig");73pub const outbound = @import("outbound.zig");74pub const announce = @import("announce.zig");75pub const inbound = @import("inbound.zig");76pub const link = @import("link.zig");77pub const transition = @import("step.zig");78pub const transport = @import("transport/root.zig");79pub const fixture = @import("fixture/root.zig");8081pub const Seconds = timer.Seconds;82pub const TimerId = timer.TimerId;83pub const PersistToken = event.PersistToken;8485pub const Limits = limits.Limits;86pub const Capacity = limits.Capacity;87pub const Node = owner.Node;88pub const Access = owner.Access;89pub const Interface = owner.Interface;90pub const ProofMode = owner.ProofMode;91pub const RatchetBinding = owner.RatchetBinding;92pub const StepError = errors.Error;9394pub const Event = event.Event;95pub const CarrierFrame = event.CarrierFrame;96pub const TimerExpired = event.TimerExpired;97pub const ApplicationSend = event.ApplicationSend;98pub const ApplicationAnnounce = event.ApplicationAnnounce;99pub const ApplicationProve = event.ApplicationProve;100pub const ApplicationPathRequest = event.ApplicationPathRequest;101pub const ApplicationLinkOpen = event.ApplicationLinkOpen;102pub const ApplicationLinkSend = event.ApplicationLinkSend;103pub const ApplicationLinkClose = event.ApplicationLinkClose;104pub const ApplicationLinkProve = event.ApplicationLinkProve;105pub const StorageComplete = event.StorageComplete;106pub const Effect = effect.Effect;107pub const Effects = effect.Effects;108pub const Code = effect.Code;109pub const LinkCloseReason = effect.LinkCloseReason;110pub const LinkRole = transport.links.Role;111pub const PersistKind = effect.PersistKind;112pub const effects_per_event_max = effect.effects_per_event_max;113pub const effect_frames_per_event_max = effect.effect_frames_per_event_max;

1pub const node = @import("node/root.zig");