API reference#

Everything delivery_module exposes, generated from the doc comments in src/delivery_module_plugin.h: the methods you call, and the events they report back through.

Methods#

Every call returns as soon as its request is dispatched. Where the outcome only becomes known later, it is reported through the events below.

StdLogosResult createNode(const std::string &cfg)#

Creates a liblogosdelivery node from a JSON configuration.

The JSON passes through to logos-delivery verbatim; parseLogosDeliveryConf (logos-messaging/logos-delivery) owns the grammar. entryLayer selects how much of the stack is mounted:

  • "kernel" — transport node only

  • "messaging" — kernel + messaging client

  • "channels" — kernel + messaging + reliable channels (default)

Three typical shapes:

App developer — full stack (default entryLayer). preset picks the network ("logos.test", "logos.dev", "twn"), mode picks the protocol flags ("Core" = relay node, "Edge" = light node). Optional messagingOverrides / channelsOverrides objects override per-layer defaults: 

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

Node operator — kernel-only service node on a public network. mode is not applied on this layer, so protocol flags are set explicitly in kernelConf: 

{
  "entryLayer": "kernel",
  "kernelConf": { "preset": "logos.test", "relay": true }
}

Network hoster — kernel-only node on a self-hosted network; kernelConf is a raw WakuNodeConf used as-is: 

{
  "entryLayer": "kernel",
  "kernelConf": { "clusterId": 42, "relay": true, "entryNodes": ["/dns4/…"] }
}

On kernel-only nodes send / subscribe / channel*

fail with “node has

no messaging client” / “no reliable channel manager”;

getNodeInfo, storeQuery and metrics keep working.

The pre-layered flat shape (bare WakuNodeConf keys at top level) still parses and boots the full stack.

Parameters:

cfg – UTF-8 JSON payload string.

Returns:

true if context creation succeeds and callback returns RET_OK, otherwise false.

StdLogosResult start()#

Starts the delivery node.

Returns:

true once dispatched; completion is reported via nodeStarted.

StdLogosResult stop()#

Stops the delivery node.

Returns:

true once dispatched; completion is reported via nodeStopped.

StdLogosResult send(const std::string &contentTopic, const std::vector<uint8_t> &payload)#

Sends a message over the active node.

Builds a JSON envelope expected by logosdelivery_send: { "contentTopic": string, "payload": base64, "ephemeral": false }.

Returns a requestId on success. Async results come via typed events:

  • messageError emitted if the module can’t send the message

  • messagePropagated emitted if the message has hit the network

  • messageSent emitted after the message is validated by the network

Parameters:

  • contentTopic – Destination content topic.

  • payload – Raw message bytes; base64-encoded before crossing the FFI boundary.

Returns:

Success with request id, or error details.

StdLogosResult subscribe(const std::string &contentTopic)#

Subscribes to the supplied content topic.

Parameters:

contentTopic – Topic identifier.

Returns:

true when subscribed successfully, otherwise false.

StdLogosResult unsubscribe(const std::string &contentTopic)#

Unsubscribes from the supplied content topic.

Parameters:

contentTopic – Topic identifier.

Returns:

true when unsubscribed successfully, otherwise false.

StdLogosResult storeQuery(const std::string &jsonQuery, const std::string &peerAddr, int64_t timeoutMs)#

Runs a Store (historical message) query against a specific store service peer.

⚠️ USE AT YOUR OWN RISK: backed by the kernel API (waku_store_query, liblogosdelivery_kernel.h), which is subject to change at any point without a deprecation cycle. This method’s JSON contract follows it.

The query JSON maps to logos-delivery’s StoreQueryRequest (library/kernel_api/protocols/store_api.nim):

Key

Type

Required

Description

requestId

string

yes

Caller-chosen id, echoed in the response

includeData

boolean

yes

true returns full messages, false hashes only

paginationForward

boolean

yes

Paging direction

pubsubTopic

string

no

Pubsub topic filter

contentTopics

array of string

no

Content topic filters

timeStart

number/string

no

Range start, nanoseconds since Unix epoch

timeEnd

number/string

no

Range end, nanoseconds since Unix epoch

messageHashes

array of string

no

Hex message hashes for lookup-by-hash queries

paginationCursor

string

no

Hex cursor from a previous response

paginationLimit

number

no

Max messages per page

On success the result value is the response JSON (StoreQueryResponseHex): { "requestId", "statusCode", "statusDesc", "messages": [ { "messageHash", "message", "pubsubTopic" } ], "paginationCursor" } with hashes 0x-hex encoded.

Parameters:

  • jsonQuery – UTF-8 JSON query document, see above.

  • peerAddr – Multiaddress of the store service peer to query (e.g. /ip4/127.0.0.1/tcp/60000/p2p/16Uiu2...).

  • timeoutMs – Query timeout in milliseconds.

Returns:

Success with the response JSON, or error details.

StdLogosResult channelCreate(const std::string &channelId, const std::string &contentTopic, const std::string &senderId)#

Creates (or re-opens) a reliable channel.

Persisted channel state survives channelClose, so re-creating a channel with the same id restores it.

Parameters:

  • channelId – Application-chosen channel identifier.

  • contentTopic – Content topic the channel communicates on.

  • senderId – This participant’s SDS (Scalable Data Sync) sender identifier.

Returns:

Success with the channel id, or error details.

StdLogosResult channelExists(const std::string &channelId)#

Checks whether a reliable channel is currently open.

An unknown channel id is not an error.

Parameters:

channelId – Channel identifier.

Returns:

Success with "true" or "false" (verbatim FFI string), or error details.

StdLogosResult channelSend(const std::string &channelId, const std::vector<uint8_t> &payload)#

Sends a message on a reliable channel.

Builds the JSON envelope expected by logosdelivery_channel_send: { "payload": base64, "ephemeral": false }.

Returns a requestId on success. Async results come via typed events:

  • channelMessageSent once every segment of the send is confirmed

  • channelMessageError if the send finalises with a failed segment

Parameters:

  • channelId – Channel identifier.

  • payload – Raw message bytes; base64-encoded before crossing the FFI boundary.

Returns:

Success with request id, or error details.

StdLogosResult channelClose(const std::string &channelId)#

Closes a reliable channel: stops its SDS loops.

Persisted state survives, so channelCreate with the same id restores the channel.

Parameters:

channelId – Channel identifier.

Returns:

true when closed successfully, otherwise false.

StdLogosResult getAvailableNodeInfoIDs()#

Lists the node info items this node advertises, for use with getNodeInfo.

The list comes back as a JSON array of strings:

["Version", "Metrics", "MyMultiaddresses", "MyENR", "MyPeerId"]

Which items a node advertises depends on how it was built and configured, so treat the set as discovered rather than fixed. An advertised item may still return an empty value from getNodeInfo when the feature behind it is unconfigured.

Returns:

Success with the list above, or error details. Fails before createNode has run.

StdLogosResult getNodeInfo(const std::string &nodeInfoId)#

Returns information for the given node info item.

Parameters:

nodeInfoId – Identifier for the requested node info item.

Returns:

JSON data string on success, or error details.

StdLogosResult getAvailableConfigs()#

Information about the available configuration parameters for createNode.

std::string collectOpenMetricsText()#

Returns the node’s metrics as an OpenMetrics/Prometheus text document, so the openmetrics module can scrape this module.

liblogosdelivery already aggregates Prometheus metrics in its global registry and renders them as exposition text behind the "Metrics" node-info attribute. This method just hands that text back verbatim — no reshaping — which satisfies the openmetrics metrics_source interface’s collectOpenMetricsText() convention. The openmetrics scraper parses the text, injects a module="delivery_module" label on every series, and merges it with other modules. Select this method per-module in the openmetrics start config with {"name":"delivery_module","format":"text"}.

Returns an empty string before a node has been created, or when the underlying read fails, so a scrape never errors out on this module.

Returns:

OpenMetrics/Prometheus exposition text (possibly empty).

Events#

A caller never invokes these. Every method above returns as soon as its request is dispatched, and what actually happened on the network arrives here — so subscribe to these rather than reading a return value.

send and channelSend return a request id, and every event reporting the outcome of that call carries the same id, so several messages can be in flight at once.

Timestamps are int64 nanoseconds since the Unix epoch. messageReceived reports the timestamp carried by the message itself; every other event is stamped by the module host when the event is emitted.

void messageSent(const std::string &requestId, const std::string &messageHash, int64_t timestamp)#

Emitted when the network has validated a sent message.

The success terminal state for send, usually preceded by messagePropagated.

void messageError(const std::string &requestId, const std::string &messageHash, const std::string &error, int64_t timestamp)#

Emitted when the module could not send a message; error carries the reason.

void messagePropagated(const std::string &requestId, const std::string &messageHash, int64_t timestamp)#

Emitted when a message has reached the network but is not yet validated.

void messageReceived(const std::string &messageHash, const std::string &contentTopic, const std::vector<uint8_t> &payload, int64_t timestamp)#

Emitted when a message arrives on a subscribed content topic.

payload is delivered as raw bytes, already decoded from the wire encoding.

void connectionStateChanged(const std::string &connectionStatus, int64_t timestamp)#

Emitted when the node’s connectivity changes.

void channelMessageReceived(const std::string &channelId, const std::string &senderId, const std::vector<uint8_t> &payload, int64_t timestamp)#

Emitted when a message arrives on an open reliable channel.

senderId is the sending participant’s SDS identifier. payload is delivered as raw bytes, already decoded from the wire encoding.

void channelMessageSent(const std::string &channelId, const std::string &requestId, int64_t timestamp)#

Emitted once every segment of a channelSend is confirmed.

void channelMessageError(const std::string &channelId, const std::string &requestId, const std::string &error, int64_t timestamp)#

Emitted when a channelSend finalises with a failed segment.

void nodeStarted(bool success, const std::string &message, int64_t timestamp)#

Emitted when start finishes; message carries the reason when success is false.

void nodeStopped(bool success, const std::string &message, int64_t timestamp)#

Emitted when stop finishes; message carries the reason when success is false.