Class Reticulum

The primary entry point and orchestrator for the Reticulum Network System.

Description

The Reticulum class orchestrates the transport and local destinations.

Constructors

constructor

new Reticulum(
    config?: {
        compressionProvider?: Bzip2;
        defaultGravity?: number;
        discovery?: Object;
        enableDiscovery?: boolean;
        ingressControl?: IngressControlConfig;
        logLevel?: string | number;
        stamps?: {
            alwaysStampLinkRequests?: boolean;
            destinationCost?: number;
            destinationValue?: number;
            enableStamping?: boolean;
            enforceStamps?: boolean;
            lrCost?: number;
            prCost?: number;
            prValue?: number;
            stampDestinations?: boolean;
            stampPathRequests?: boolean;
        };
        storageAdapter?: StorageAdapter;
        useImplicitProof?: boolean;
    },
): Reticulum
Initializes the Reticulum engine.
Parameters
- config: {
      compressionProvider?: Bzip2;
      defaultGravity?: number;
      discovery?: Object;
      enableDiscovery?: boolean;
      ingressControl?: IngressControlConfig;
      logLevel?: string | number;
      stamps?: {
          alwaysStampLinkRequests?: boolean;
          destinationCost?: number;
          destinationValue?: number;
          enableStamping?: boolean;
          enforceStamps?: boolean;
          lrCost?: number;
          prCost?: number;
          prValue?: number;
          stampDestinations?: boolean;
          stampPathRequests?: boolean;
      };
      storageAdapter?: StorageAdapter;
      useImplicitProof?: boolean;
  } = {}
  Configuration options for the node.
  - OptionalcompressionProvider?: Bzip2
    
    Engine for handling bz2 Resources (e.g., for rngit).
  - OptionaldefaultGravity?: number
    
    Default interface gravity applied to any interface that doesn't specify one. Higher gravity = preferred for paths. Defaults to Reticulum.DEFAULT_GRAVITY (0).
  - Optionaldiscovery?: Object
    
    Extra options forwarded to the InterfaceDiscovery constructor when enableDiscovery is true (requiredValue, discoverySources, networkIdentity, backboneSupport).
  - OptionalenableDiscovery?: boolean
    
    When true, start an InterfaceDiscovery listener on the transport "announce" event so a leaf can discover connectable transport-node interfaces on the rnstransport.discovery.interface aspect. v1 is surface-only — no auto-connect.
  - OptionalingressControl?: IngressControlConfig
    
    Node-global ingress burst-control overrides applied to every interface at addInterface time (node-level ic_* options — there is no per-interface form). Absent keys keep the defaults. Per-interface programmatic control (including iface.ingressControl = false to opt out) always remains available.
  - OptionallogLevel?: string | number
    
    Initial log threshold. Accepts a LogLevel value or a level name ("DEBUG", "NOTICE", …). Takes precedence over the RETICULUM_LOG_LEVEL environment variable. See src/utils/log.js.
  - Optionalstamps?: {
        alwaysStampLinkRequests?: boolean;
        destinationCost?: number;
        destinationValue?: number;
        enableStamping?: boolean;
        enforceStamps?: boolean;
        lrCost?: number;
        prCost?: number;
        prValue?: number;
        stampDestinations?: boolean;
        stampPathRequests?: boolean;
    }
    
    RNS 1.6.0 network-stamp configuration, mirroring the Python reference's [stamps] config section. The knobs are process-wide (they map onto the Python Transport class attributes). Upstream rollout defaults: everything verified, nothing emitted, nothing enforced in 1.6.0; emission on in 1.6.1; enforcement on in 1.6.2.
    
    OptionalalwaysStampLinkRequests?: boolean
    
    Stamp link requests even when the destination announced no cost (Python always_stamp_lrs).
    
    OptionaldestinationCost?: number
    
    Required announce stamp cost (Python destination_cost, default 23.5).
    
    OptionaldestinationValue?: number
    
    Target announce stamp value (Python destination_value, default 25.0).
    
    OptionalenableStamping?: boolean
    
    Turn on emission of destination announce stamps, path request stamps and link request stamps in one go (Python enable_stamping = yes).
    
    OptionalenforceStamps?: boolean
    
    Drop announces, path requests and link requests that fail their stamp requirements (Python enforce_stamps = yes).
    
    OptionallrCost?: number
    
    Required link request cost when a destination announced none (Python lr_cost, default 12.5).
    
    OptionalprCost?: number
    
    Required path request stamp cost (Python pr_cost, default 15.8).
    
    OptionalprValue?: number
    
    Target path request stamp value (Python pr_value, default 15.8).
    
    OptionalstampDestinations?: boolean
    
    Emit destination announce stamps (Python stamp_destinations).
    
    OptionalstampPathRequests?: boolean
    
    Emit path request stamps (Python stamp_prs).
  - OptionalstorageAdapter?: StorageAdapter
    
    Interface for persisting identities and caches.
  - OptionaluseImplicitProof?: boolean
    
    §6.5.2 PROOF form for opportunistic DATA: true (default, upstream) emits the 64-byte implicit body; false emits the 96-byte explicit body.
Returns Reticulum
- Defined in packages/core/src/core/reticulum.js:107

Properties

_stopped

_stopped: boolean

Whether stop has run.

compressionProvider

compressionProvider: Bzip2 | null

coreInstanceToken

coreInstanceToken: object

Module-instance identity of this copy of @reticulum/core (work doc #37). Dependent packages (@reticulum/lxmf, @reticulum/rfed, ...) compare it against their own CORE_INSTANCE_TOKEN import via warnIfFragmented to detect a fragmented install (two physical core copies in one process) at first boot.

defaultGravity

defaultGravity: number

discovery

discovery: InterfaceDiscovery | null

ingressControl

ingressControl: IngressControlConfig

localDestinations

localDestinations: Map<any, any>

persistor

persistor: Persistor

persistorLoadPromise

persistorLoadPromise: Promise<void>

storage

storage: StorageAdapter | null

transport

transport: TransportCore

useImplicitProof

useImplicitProof: boolean

`Static`DEFAULT_GRAVITY

DEFAULT_GRAVITY: number = 0

The default interface gravity applied when an interface doesn't specify one (RNS.Interfaces.Interface.Interface.DEFAULT_GRAVITY). Higher gravity = preferred for paths when the same announce is heard on multiple interfaces.

`Static`DEFAULT_PER_HOP_TIMEOUT_SECS

DEFAULT_PER_HOP_TIMEOUT_SECS: number = 6

The base per-hop timeout in seconds (RNS.Reticulum.DEFAULT_PER_HOP_TIMEOUT), added on top of the bitrate-derived term in TransportCore.firstHopTimeout / TransportCore.establishmentTimeout.

`Static`IFAC_MIN_SIZE

IFAC_MIN_SIZE: number = IFAC_MIN_SIZE

Minimum IFAC size in bytes (RNS.Reticulum.IFAC_MIN_SIZE). Re-exported from import("./ifac.js").IFAC_MIN_SIZE for upstream API parity.

`Static`IFAC_SALT

IFAC_SALT: Uint8Array<ArrayBuffer> = IFAC_SALT

Fixed IFAC salt (RNS.Reticulum.IFAC_SALT). Re-exported from import("./ifac.js").IFAC_SALT for upstream API parity.

`Static`MINIMUM_BITRATE

MINIMUM_BITRATE: number = 5

Minimum acceptable interface bitrate in bits/s. A configured bitrate below this is ignored so the interface keeps its default — used for config-time validation only. It does not cause interfaces to be skipped in routing; the reference implementations behave the same.

`Static`MTU

MTU: number = 500

The network MTU in bytes (RNS.Reticulum.MTU). The largest packet the network will carry; feeds the bitrate-adaptive timeout math (TransportCore.firstHopTimeout).

Methods

addInterface

addInterface(rnsInterface: Interface, isDefault?: boolean): void
Attaches a physical or virtual network interface to the router.

Connecting to a local shared instance is now the caller's job — use the LocalClientInterface.connectToSharedInstance() static factory (from @reticulum/node/src/interfaces/local_client.js) and pass the resulting interface here. Keeping shared-instance discovery out of the core keeps Reticulum free of Node.js builtins and browser-safe.
Parameters
- rnsInterface: Interface
  An instantiated interface (TCP, WebSocket, RNode, shared-instance client, ...)
- isDefault: boolean = false
  If true, unroutable packets fallback to this interface
Returns void
- Defined in packages/core/src/core/reticulum.js:226

broadcast

broadcast(packet: Packet): void
Broadcasts a packet from a specific destination to the mesh.
Parameters
- packet: Packet
Returns void
- Defined in packages/core/src/core/reticulum.js:306

deregisterDestination

deregisterDestination(destination: Destination): void
Removes a local destination, ceasing all incoming traffic to that application endpoint.
Parameters
- destination: Destination
Returns void
- Defined in packages/core/src/core/reticulum.js:291

getFirstHopTimeout

getFirstHopTimeout(destinationHash: Uint8Array<ArrayBufferLike>): number
The bitrate-adaptive proof timeout for a single hop toward the destination, in seconds (RNS.Reticulum.get_first_hop_timeout). Delegates to TransportCore.firstHopTimeout; falls back to Reticulum.DEFAULT_PER_HOP_TIMEOUT_SECS when no route / bitrate is known.
Parameters
- destinationHash: Uint8Array<ArrayBufferLike>
Returns number
seconds
- Defined in packages/core/src/core/reticulum.js:319

getLowestInterfaceBitrate

getLowestInterfaceBitrate(): number | null
The bitrate of the slowest currently-online interface, in bits/s, or null when no online interface reports a usable bitrate. Delegates to TransportCore.lowestInterfaceBitrate. (The Python reference also has a shared-instance RPC branch; reticulum-js has no shared-instance model yet, so only the local delegation is exposed.)

Returns number | null
- Defined in packages/core/src/core/reticulum.js:332

getMediumPathTimeout

getMediumPathTimeout(): number
A full round trip for an MTU on the slowest currently-online interface, plus per-hop grace, in seconds (RNS.Reticulum.get_medium_path_timeout). Delegates to TransportCore.mediumPathTimeout; returns 0 when no online interface bitrate is known. (No shared-instance RPC branch — see getLowestInterfaceBitrate.)

Returns number
seconds
- Defined in packages/core/src/core/reticulum.js:344

ready

ready(): Promise<void>
Waits for the Reticulum node to be ready. Resolves when the initial persistence hydration has finished and any background initialization (such as interface discovery) has completed.

Returns Promise<void>
- Defined in packages/core/src/core/reticulum.js:354

registerDestination

registerDestination(destination: Destination): void
Binds an application-level Destination to the network. When your web components spin up and instantiate a Yjs provider, this is where they register their collaborative endpoints to receive traffic.
Parameters
- destination: Destination
Returns void
- Defined in packages/core/src/core/reticulum.js:257

removeInterface

removeInterface(rnsInterface: Interface): void
Removes an interface and purges its routes from the TransportCore.
Parameters
- rnsInterface: Interface
  An instantiated interface (TCP, WebSocket, RNode)
Returns void
- Defined in packages/core/src/core/reticulum.js:246

stop

stop(): Promise<void>
Graceful shutdown: stops interface discovery, disconnects every attached interface, and flushes the persistence layer so the final debounced batch isn't lost. A per-interface disconnect failure is logged and the rest still proceed. Idempotent.

Links and their channels are not torn down here (they are owned by the application's destinations); they terminate when their interfaces close.

Returns Promise<void>
- Defined in packages/core/src/core/reticulum.js:371

Class Reticulum

Description

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

OptionalcompressionProvider?: Bzip2

OptionaldefaultGravity?: number

Optionaldiscovery?: Object

OptionalenableDiscovery?: boolean

OptionalingressControl?: IngressControlConfig

OptionallogLevel?: string | number

Optionalstamps?: { alwaysStampLinkRequests?: boolean; destinationCost?: number; destinationValue?: number; enableStamping?: boolean; enforceStamps?: boolean; lrCost?: number; prCost?: number; prValue?: number; stampDestinations?: boolean; stampPathRequests?: boolean;}

OptionalalwaysStampLinkRequests?: boolean

OptionaldestinationCost?: number

OptionaldestinationValue?: number

OptionalenableStamping?: boolean

OptionalenforceStamps?: boolean

OptionallrCost?: number

OptionalprCost?: number

OptionalprValue?: number

OptionalstampDestinations?: boolean

OptionalstampPathRequests?: boolean

OptionalstorageAdapter?: StorageAdapter

OptionaluseImplicitProof?: boolean

Returns Reticulum

Properties

_stopped

compressionProvider

coreInstanceToken

defaultGravity

discovery

ingressControl

localDestinations

persistor

persistorLoadPromise

storage

transport

useImplicitProof

StaticDEFAULT_GRAVITY

StaticDEFAULT_PER_HOP_TIMEOUT_SECS

StaticIFAC_MIN_SIZE

StaticIFAC_SALT

StaticMINIMUM_BITRATE

StaticMTU

Methods

addInterface

Parameters

Returns void

broadcast

Parameters

Returns void

deregisterDestination

Parameters

Returns void

getFirstHopTimeout

Parameters

Returns number

getLowestInterfaceBitrate

Returns number | null

getMediumPathTimeout

Returns number

ready

Returns Promise<void>

registerDestination

Parameters

Returns void

removeInterface

Parameters

Returns void

stop

Returns Promise<void>

Settings

On This Page

`Optional`compressionProvider?: Bzip2

`Optional`defaultGravity?: number

`Optional`discovery?: Object

`Optional`enableDiscovery?: boolean

`Optional`ingressControl?: IngressControlConfig

`Optional`logLevel?: string | number

`Optional`stamps?: {
alwaysStampLinkRequests?: boolean;
destinationCost?: number;
destinationValue?: number;
enableStamping?: boolean;
enforceStamps?: boolean;
lrCost?: number;
prCost?: number;
prValue?: number;
stampDestinations?: boolean;
stampPathRequests?: boolean;
}

`Optional`alwaysStampLinkRequests?: boolean

`Optional`destinationCost?: number

`Optional`destinationValue?: number

`Optional`enableStamping?: boolean

`Optional`enforceStamps?: boolean

`Optional`lrCost?: number

`Optional`prCost?: number

`Optional`prValue?: number

`Optional`stampDestinations?: boolean

`Optional`stampPathRequests?: boolean

`Optional`storageAdapter?: StorageAdapter

`Optional`useImplicitProof?: boolean

`Static`DEFAULT_GRAVITY

`Static`DEFAULT_PER_HOP_TIMEOUT_SECS

`Static`IFAC_MIN_SIZE

`Static`IFAC_SALT

`Static`MINIMUM_BITRATE

`Static`MTU