logos-delivery-module

Wrap LogosMessaging API (liblogosdelivery) and make it available as a Logos Core module.

This module provides high-level message delivery capabilities through the liblogosdelivery interface from logos-delivery, packaged as a Logos module plugin compatible with logos-core.

Full API documentation is in src/delivery_module_plugin.h (DeliveryModulePlugin).

How to Build

Using Nix (Recommended)

Build Complete Module (Library + Headers)

# Build everything (default)
nix build

The result will include:

• /lib/delivery_module_plugin.dylib (or .so on Linux) - The Delivery module plugin
• /lib/liblogosdelivery.dylib (or .so on linux) - The logos-delivery library
• /lib/librln.dylib (or .so in linux) - Zerokit's RLN library
• /lib/libpq.dylib (or .so on Linux) - PostgreSQL runtime library
• /lib/libpq.5.dylib (or .so.5 on Linux)

Build Individual Components

# Build only the library (plugin + liblogosdelivery reference)
nix build '.#lib'

# Build only the generated headers
nix build '.#include'

# build module in local and in protable logos_core format
nix build .#lgx / .#lgx-portable

Development Shell

# Enter development shell with all dependencies
nix develop

Note: In zsh, you need to quote the target (e.g., '.#default') to prevent glob expansion.

If you don't have flakes enabled globally, add experimental flags:

nix build --extra-experimental-features 'nix-command flakes'

The compiled artifacts can be found at result/

Output Structure

When built with Nix, the module produces:

result/
└── lib/
    ├── delivery_module_plugin.dylib  # or .so on Linux — Logos module plugin
    ├── liblogosdelivery.dylib
    ├── librln.dylib
    ├── libpq.dylib                   # or .so on Linux — PostgreSQL runtime
    └── libpq.5.dylib                 # or .so.5 on Linux

Requirements

Build Tools

• CMake (3.14 or later)
• Ninja build system
• pkg-config

Dependencies

• Qt6 (qtbase)
• Qt6 Remote Objects (qtremoteobjects)
• logos-liblogos (provided via Nix)
• logos-cpp-sdk (provided via Nix)
• logos-delivery / liblogosdelivery — target (provided via Nix)
• PostgreSQL (libpq) — runtime dependency bundled by the Nix build

All dependencies are automatically handled by the Nix flake configuration.

Module Interface

The delivery module provides the following API methods (all synchronous, all return LogosResult):

• createNode(cfg: QString) - Initialize the delivery node with a JSON configuration (call once)
• start() - Start the delivery node
• stop() - Stop the delivery node
• send(contentTopic: QString, payload: QString) - Send a message (returns a request id)
• subscribe(contentTopic: QString) - Subscribe to receive messages on a topic
• unsubscribe(contentTopic: QString) - Unsubscribe from a topic
• getAvailableNodeInfoIDs() - List queryable node info identifiers
• getNodeInfo(nodeInfoId: QString) - Retrieve node info by identifier
• getAvailableConfigs() - Retrieve available configuration parameter descriptions
• collectOpenMetricsText() - Node metrics as OpenMetrics/Prometheus text for the openmetrics module (see docs/run-node.md → Metrics)

Node Configuration (createNode)

createNode accepts a flat JSON object whose keys correspond to WakuNodeConf field names (camelCase) from logos-delivery. Unknown keys are silently ignored. Every field has a built-in default, so only values that differ from defaults need to be supplied.

Commonly used keys

Key	Type	Default	Description
mode	string	"noMode"	"Core", "Edge", or "noMode"
preset	string	""	Network preset ("logos.test", "logos.dev", "twn")
clusterId	number (uint16)	0	Cluster identifier
entryNodes	array of string	[]	Bootstrap peers (enrtree / multiaddress)
relay	boolean	false	Enable relay protocol
rlnRelay	boolean	false	Enable RLN rate-limit nullifier
tcpPort	number (uint16)	60000	P2P TCP listen port
numShardsInNetwork	number (uint16)	1	Auto-sharding shard count
logLevel	string	"INFO"	"TRACE", "DEBUG", "INFO", "WARN"
logFormat	string	"TEXT"	"TEXT" or "JSON"
maxMessageSize	string	"150KiB"	Maximum message payload size

logLevel reaches the node but does not change how much it logs. The bundled liblogosdelivery resolves each log statement's level when it is compiled, so the ceiling is a build-time property; this module pins it to WARN in flake.nix to keep the node's peer-discovery and subscription-upkeep chatter out of an embedding host's console. Lower it there and rebuild the library to get those diagnostics back.

Presets

Using a preset populates cluster ID, entry nodes, sharding, RLN, and other network-specific defaults automatically. Individual keys supplied alongside a preset override the preset values.

• "logos.test" – Logos Test fleet (the default for running a node; mix enabled, p2pReliability on, auto-shards, built-in bootstrap nodes).
• "logos.dev" – Logos Dev Network (cluster 2, mix enabled, p2pReliability on, 8 auto-shards, built-in bootstrap nodes).
• "twn" – The RLN-protected Waku Network (cluster 1).

Minimal example using the default logos.test preset:

{
  "logLevel": "INFO",
  "mode": "Core",
  "preset": "logos.test"
}

Content Topics

Content topics identify message channels for publishing and subscribing. Use a properly structured content topic for your application following the format specified in LIP-23: Topics.

Example: "/myapp/1/chat/proto"

Sending Messages (send)

send(contentTopic, payload) accepts a content topic and a raw payload string. The plugin converts the payload to UTF-8 bytes, base64-encodes it, and wraps it in a JSON envelope before crossing the FFI boundary:

{ "contentTopic": "<topic>", "payload": "<base64>", "ephemeral": false }

The call is synchronous and returns a request id on success. The actual network delivery is asynchronous — track results via the emitted events:

• messageError – the module could not send the message.
• messagePropagated – the message reached the network but is not yet validated.
• messageSent – the message has been confirmed by the network.

Events

Asynchronous events are emitted off-thread as Logos Plugin events. Each event carries a QVariantList data with positional values:

• messageSent – message confirmed by the network
  • data[0] (QString): request id
  • data[1] (QString): message hash
  • data[2] (QString): local timestamp (ISO-8601)
• messageError – send failure
  • data[0] (QString): request id
  • data[1] (QString): message hash
  • data[2] (QString): error message
  • data[3] (QString): local timestamp (ISO-8601)
• messagePropagated – message reached the network but not yet validated
  • data[0] (QString): request id
  • data[1] (QString): message hash
  • data[2] (QString): local timestamp (ISO-8601)
• messageReceived – a message arrived on a subscribed topic
  • data[0] (QString): message hash
  • data[1] (QString): content topic
  • data[2] (QString): payload (base64-encoded)
  • data[3] (QString): timestamp (nanoseconds since epoch)
• connectionStateChanged – node connectivity change
  • data[0] (QString): connection status
  • data[1] (QString): local timestamp (ISO-8601)

Metrics

collectOpenMetricsText() returns the node's internal Prometheus metrics as OpenMetrics/Prometheus exposition text for the openmetrics module to scrape. For how to wire up openmetrics and scrape a running node, see Running a node → Metrics.

Architecture

┌─────────────────────────────────────┐
│  Logos Core (Qt Application)        │
└──────────────┬──────────────────────┘
               │
               │ Plugin Interface
               ▼
┌─────────────────────────────────────┐
│  delivery_module_plugin             │
│  (Qt Plugin - this repository)      │
└──────────────┬──────────────────────┘
               │
               │ C FFI
               ▼
┌─────────────────────────────────────┐
│  liblogosdelivery                   │
│  (from logos-delivery)              │
│  High-level Message-delivery API    │
└──────────────┬──────────────────────┘
               │
               │ Nim API
               ▼
┌─────────────────────────────────────┐
│ logos-delivery                      │
│ Core message-delivery implementation│
└─────────────────────────────────────┘

Development

Local Development

# Enter development shell (exports LOGOS_MODULE_BUILDER_ROOT and all other deps)
nix develop

# Configure — env vars are exported automatically by the dev shell
cmake -B build -S . -GNinja

# Build
ninja -C build