Bundle Lifecycle¶

Bundles transition through multiple states from creation to delivery or expiration.

State Machine¶

stateDiagram-v2
    [*] --> NEW : enqueue()
    [*] --> RECEIVED : from peer

    NEW --> FWD : markForwarded()
    NEW --> EXP : TTL expired

    RECEIVED --> RECEIVED_FORWARDABLE : destination nearby
    RECEIVED --> DEL : local delivery
    RECEIVED --> CANCELLED : cancel()

    RECEIVED_FORWARDABLE --> FWD : markForwarded()

    FWD --> DEL : delivered to destination
    FWD --> EXP : TTL expired
    FWD --> CANCELLED : cancel()

    DEL --> CANCELLED : cleanup after ACK

    note right of NEW : Created locally
    note right of RECEIVED : From peer, for local user
    note right of RECEIVED_FORWARDABLE : Promoted for relay
    note left of DEL : Successfully delivered
    note left of EXP : TTL exceeded
    note left of CANCELLED : Explicitly removed

State Descriptions¶

NEW¶

Entry: When locally-created bundles are enqueued
Meaning: Bundle created by this device, queued for forwarding
Next States: FWD (forwarding), EXP (expired)

RECEIVED¶

Entry: When bundle arrives from peer
Meaning: Bundle accepted from network, stored locally
Next States:
DEL if this device is the destination
RECEIVED_FORWARDABLE if destination is nearby
CANCELLED if explicitly removed

RECEIVED_FORWARDABLE¶

Entry: When destination peer is detected
Meaning: Received bundle promoted for relay toward destination
Next States: FWD (forwarding)

FWD (Forwarding)¶

Entry: When forwarding attempt begins
Meaning: Bundle currently being sent to peers
Next States: DEL (delivered), EXP (expired), CANCELLED

DEL (Delivered)¶

Entry: When delivery confirmed
Meaning: Successfully delivered to final destination
Terminal: Yes (but may transition to CANCELLED for cleanup)

EXP (Expired)¶

Entry: During periodic cleanup
Meaning: TTL exceeded, bundle no longer valid
Terminal: Yes

ERR (Error)¶

Entry: Processing failure
Meaning: Unrecoverable error during handling
Terminal: Yes
Note: Rarely used in practice

CANCELLED¶

Entry: On delivery cancel or operator action
Meaning: Explicitly removed from network
Terminal: Yes

Transition Triggers¶

Creation Path¶

sequenceDiagram
    participant App as Application
    participant Repo as BundleRepository
    participant DB as Database

    App->>Repo: createDM(recipient, text)
    Repo->>Repo: encrypt payload
    Repo->>Repo: build BundleHeader
    Repo->>DB: insert(status=NEW)
    Note over Repo: Bundle queued for forwarding

Reception Path¶

sequenceDiagram
    participant Peer as Remote Peer
    participant Transport as Transport Layer
    participant Repo as BundleRepository

    Peer->>Transport: bundle bytes
    Transport->>Repo: processReceived(bundle)
    Repo->>Repo: verify signature
    Repo->>Repo: check deduplication

    alt Is for local user
        Repo->>Repo: decrypt & deliver
        Note over Repo: status=DEL
    else Relay candidate
        Repo->>Repo: store for forwarding
        Note over Repo: status=RECEIVED
    end

Forwarding Path¶

sequenceDiagram
    participant Routing as RoutingFacade
    participant Repo as BundleRepository
    participant Transport as Transport Layer

    Routing->>Repo: getForwardable()
    Repo-->>Routing: bundles with NEW/RECEIVED_FORWARDABLE
    Routing->>Routing: selectBundlesForPeer()
    Routing->>Transport: send(selectedBundles)
    Transport->>Repo: markForwarded(bundleId)
    Note over Repo: status=FWD, attempts++

Delivery Confirmation¶

sequenceDiagram
    participant Dest as Destination
    participant Origin as Origin
    participant Repo as BundleRepository

    Dest->>Origin: DeliveryAck (signed)
    Origin->>Repo: markDelivered(bundleId)
    Note over Repo: status=DEL
    Origin->>Origin: Update routing (ACK learning)
    Origin->>Repo: cleanup (optional CANCELLED)

TTL and Expiration¶

Bundles have a time-to-live (TTL) after which they expire.

Default TTLs¶

Message Type	TTL	Rationale
DM (text)	7 days	Important, wait for delivery
DM (media)	3 days	Larger, less critical
Group message	4 hours	Time-sensitive context
Channel broadcast	4 hours	Ephemeral content
Control (ACK)	24 hours	Routing feedback

Expiration Check¶

Expiration runs periodically (every 5 minutes) to clean up stale bundles. Expired bundles have their payloads deleted and status set to EXP.

Copy Budget Lifecycle¶

Each bundle has a copy budget for Spray-and-Wait routing.

Initial Budget by Priority:

Priority	Copy Budget
CRITICAL	8
NORMAL	3
BULK	2

Each successful forward consumes one copy. The budget decrements with each forward, and the attempt counter increments.

Cleanup¶

ACK-Triggered Cleanup¶

When a DeliveryAck is received: 1. Mark bundle as DEL 2. Send DeliveryCancel to network 3. Other nodes receiving cancel → CANCELLED

Storage Cleanup¶

When a bundle is cleaned up, its status is set to CANCELLED and its payload file is deleted from storage.

Database Cleanup¶

Periodic cleanup removes old terminal-state bundles: - DEL older than 24 hours - EXP older than 1 hour - CANCELLED older than 1 hour

Next: Bundle Structure | Message Types