Waku API Spec: Node initialization by fryorcraken · Pull Request #65 · logos-messaging/specs

fryorcraken · 2025-06-17T09:48:11Z

This PR intends to introduce the customer Interface Definition Language, by proposing an initialization function and accompanying config for the Waku API.

The "Waku API" is a proposed renamed of "Waku Messaging API" because the term "messaging" is very generic and is going to also be used by Status to qualify the Waku Chat SDK API.

Also best to start generic for us with "Waku API", as this is the API we want developers to use. And we can refine at a later stage if there is a more specialized API we want to offer (aka "RLN API").

This PR is a suggestion to replace #19. I have already made comment in #19, but in short:

More succinct document and definition, we are here to define an API, behaviour should be inferred by protocols already defined
Focus on iterative delivery, the spec should match the code. eg we do not intend to implement Waku API in REST API in 2025H2, so the spec can be done later
Trying to avoid duplicate block of text, and keeping definitions close to introduction
Making it language agnostic, so it can truly define the API across all languages.

#68

Ivansete-status

This is really superb so far! Congrats for it 🙌
I'm just suggesting minor tweaks

standards/application/waku-api.md

NagyZoltanPeter

Added some recomendation.

standards/application/waku-api.md

NagyZoltanPeter · 2025-06-18T11:41:09Z

standards/application/waku-api.md

+- No `default` means that the value is mandatory
+- Primitive types are `string`, `int`, `bool` and `uint`
+- Complex pre-define types are `struct`, `option` and `array`
+- Primitive types are preferred to describe the API for simplicity, the implementator may prefer a native type (e.g. `string` vs `Multiaddr` object/struct)


I would argue with it, as such API has reduntant use of complex types (structs like WakuMessage or even very specific named types like Multiaddr). I think IDL shall support references to such types to allow reuse them over native types.- much like OpenAPI syntax.
This is even beneficial if we think it is harder to read as it leads more comprehensive api definition.

I am not convinced Waku Message needs to leak out of the API.

In terms of Multiaddr, I don't want to prescribe the API to have to only accept an object Multiaddr because in some language like JS, a string is often used and expected.

Hence not entirely sure the best way to express that. I gave it a go in adaba54 (#65)

IMHO , Multiaddr type doesn't seem as generic as option, array, struct. I wouldn't add it adaba54

I think we cna expect it to be a string in most languages. so will do that.

fryorcraken · 2025-06-26T05:32:05Z

standards/application/waku-api.md

+      active_relay_shards:
+        type: array<uint>
+        constraints: mode == "relay"
+        default: []
+        description: "The shards for relay to subscribe to and participate in."


I am actually not convinced this should be available when initializing a node.

The action here is that "subscribe" will be called on those shards. "subscribe" is a live action to be done on a running node.

While it is fine for wakunode2 to have a way to specify shards to subscribe to on the CLI, it should be seen separately for node instantiation.

Hence I think I would recommend removing it.

weboko · 2025-06-27T11:58:18Z

standards/application/waku-api.md

@@ -0,0 +1,224 @@
+---
+title: MESSAGING-API


It seems we aligned on new naming.

Suggested change

title: MESSAGING-API

title: WAKU-API

weboko · 2025-06-27T12:03:20Z

standards/application/waku-api.md

+  - `option`: a value that can be set or left null
+  - `array`: iterable object containing values of all the same type
+  - `multiaddr`: a libp2p multiaddress; may be an object or a string, most idiomatic approach depending on the language
+  - `result`: an enum type that either contain a return value (success), or an error (failure). The error is left to the implementor


we can specify somewhere that result is recommended way of communicating errors rather than throw but it can be left to implementations

weboko · 2025-06-27T12:04:04Z

standards/application/waku-api.md

+The accessibility of Waku protocols is capped by the accessibility of their implementations, and hence API.
+This RFC enables a concerted effort to draft an API that is simple and accessible, and provides an opinion on sane defaults.
+
+This effort is best done in an RFC, allowing all current implementors to review and agree on it. 


nit: we can omit this line, seems it doesn't bring much value

weboko · 2025-06-27T12:05:47Z

standards/application/waku-api.md

+  - `multiaddr`: a libp2p multiaddress; may be an object or a string, most idiomatic approach depending on the language
+  - `result`: an enum type that either contain a return value (success), or an error (failure). The error is left to the implementor
+  - `error`: Left to the implementor on whether `error` types are `string` or `object` in the given language.
+- The first parameter of a function MAY be considered as the object on which a method is called. It is left to the implementor on whether an objective programming approach is idiomatic to the language.


this line seems to be too specific even though it is true for nim and rust

we can re-introduce it when we define function that needs a reference to some exiting Waku node instance.

standards/application/waku-api.md

weboko · 2025-06-27T12:08:41Z

standards/application/waku-api.md

+## The Waku API
+
+```yaml
+api_version: "0.0.1"


just general question: why not start with 1.0.0?

As usual, let's mature things before we decide to crystallize and make it a 1.0.0

Being able to set what shard to subscribe too when initialising a Waku node is a biased towards service nodes. Indeed, subscribing to shard should be done with the `subscribe` API (yet to be defined). Which can be used with a content topic, and pubsub topic (only if static sharding). A service node such as the `wakunode2` binary can still accept "shards to subscribe to" via CLI, but this is unrelated to the Waku node conf, and the `wakunode2` software should simply call `subscribe` when ready.

fryorcraken · 2025-06-30T04:24:37Z

Only comment node configuration and initialization part of this PR.

The work here is highly controversial, so let's focus on one bit at a time. Discussions related to other functions such as subscribe, etc, should wait for their own PR.

Reducing the scope, we can review Rust, Golang and C in a separate PR.

fryorcraken · 2025-07-03T06:35:40Z

standards/application/waku-api.md

+    fields:
+      mode: 
+        type: string
+        constraints: ["edge", "relay"]


core or standard are good alternatives to relay.

I wouldn't change relay. It sounds correct to me.

tough to get right, convo ongoing here: https://discord.com/channels/1110799176264056863/1389431080012087306/1421097560113942549

fryorcraken · 2025-07-07T08:39:14Z

standards/application/waku-api.md

+
+If the `mode` set is `edge`, the initialised `WakuNode` MUST mount:
+
+- [LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) as client 


Metadata should be loaded too.

@osmaczko

After feedback from @osmaczko

fryorcraken · 2025-09-25T04:02:09Z

@jimstir I think it's going to be hard to maintain a spell check dictionary.

Ivansete-status

LGTM! Thanks so much for it! 🥳
Just added another nitpick one ;P

Ivansete-status · 2025-09-25T08:24:25Z

standards/application/waku-api.md

+        constraints: [ "store", "filter" ]
+        # Until further dogfooding, assuming default false, usage of SDS should be preferred
+        default: [ "none" ]


EDITED:

I think we don't need that message_confirmation parameter. That can be considered internally as per the given operation mode (edge, relay.)

EDITED: disregard the following comment. I was confused.

Maybe :)?

Suggested change

constraints: [ "store", "filter" ]

# Until further dogfooding, assuming default false, usage of SDS should be preferred

default: [ "none" ]

constraints: [ "none", "store", "sds" ]

# Until further dogfooding, assuming default none, usage of SDS should be preferred

default: [ "none" ]

Besides, I can't quite get why an array<string> is needed

Besides, I can't quite get why an array is needed

@Ivansete-status as I understand it is because we can have multiple confirmation mechanisms working at the same time filter + store

What @weboko said: the p2p reliability strategies are not mutually exclusive.

weboko · 2025-09-25T09:25:53Z

standards/application/waku-api.md

+The accessibility of Waku protocols is capped by the accessibility of their implementations, and hence API.
+This RFC enables a concerted effort to draft an API that is simple and accessible, and provides an opinion on sane defaults.
+
+The API defined in this document is an opinionated-by-purpose method to use the more agnostic [WAKU2]() protocols.


Suggested change

The API defined in this document is an opinionated-by-purpose method to use the more agnostic [WAKU2]() protocols.

The API defined in this document is an opinionated-by-purpose method to use the more agnostic [WAKU2](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/10/waku2.md) protocols.

weboko · 2025-09-25T09:30:17Z

standards/application/waku-api.md

+- No `default` means that the value is mandatory, meaning a `default` value implies an optional parameter.
+- Primitive types are `string`, `int`, `bool`, `enum` and `uint`
+- Complex pre-defined types are:
+  - `struct`: object and other nested types.


nit: by being biased by high level languages I would prefer object instead of struct

weboko · 2025-09-25T09:39:57Z

standards/application/waku-api.md

+      message_confirmation:
+        type: array<string>
+        constraints: [ "store", "filter" ]
+        # Until further dogfooding, assuming default false, usage of SDS should be preferred


I don't understand why we mention SDS here as it is in dogfooding / experimental stage too

I removed, what I mean is that I expect we change the default in the future.

weboko · 2025-09-25T09:51:24Z

standards/application/waku-api.md

+        type: array<string>
+        # Default means the node does not bootstrap, e.g. for local development
+        default: []
+        description: "Nodes to connect to; used for discovery bootstrapping and quick connectivity. entree and multiaddr formats are accepted."


nit: and we can remove the comment above

Suggested change

description: "Nodes to connect to; used for discovery bootstrapping and quick connectivity. entree and multiaddr formats are accepted."

description: "Nodes to connect to; used for discovery bootstrapping and quick connectivity. entree and multiaddr formats are accepted. If not provided, node does not bootstrap (e.g for local development)"

if we ever add mDNS the comment will be false. But will add in the mean time.

weboko · 2025-09-25T09:54:56Z

standards/application/waku-api.md

+      static_store_nodes:
+        type: array<string>
+        default: []
+        description: "Only the passed nodes are used for store queries, discovered store nodes are discarded."


sorry if you mentioned it somewhere and I didn't see

question: why discarded? previously we were discussing it in the way that discovered nodes will be de-prioritized and used only if static store nodes are not available

I think we can re-adjust at implementation time. Will correct and add todo.

weboko · 2025-09-25T09:55:17Z

standards/application/waku-api.md

+        description: "The auto-sharding config, if sharding mode is `auto`"
+      message_validation:
+        type: MessageValidation
+        # If the default config for TWN is not used, then we still provide a message validation default 


Suggested change

# If the default config for TWN is not used, then we still provide a message validation default

description: If the default config for TWN is not used, then we still provide a message validation default

weboko · 2025-09-25T09:58:24Z

standards/application/waku-api.md

+    type: string
+    fields:
+      listen_ipv4:
+        # Is not applicable in some environments such as browser.


nit: should we include comments into description? I think this gives needed context and doesn't over bloat them

yes all done

weboko · 2025-09-25T10:01:19Z

standards/application/waku-api.md

+  TheWakuNetworkPreset:
+    type: WakuConfig
+    fields:
+      remote_nodes: [ "enrtree://AIRVQ5DDA4FFWLRBCHJWUWOO6X6S4ZTZ5B667LQ6AJU6PEYDLRD5O@sandbox.waku.nodes.status.im" ]


I am not sure it worth mentioning remote nodes and contract address as they can get outdated rather fast: unpredicted contract changes like we did recently etc.

I see your point. I think it's fine to have it and forces us to update it as the intent is to ensure that all implementations are interoperable by default.

weboko

left some comments, lgtm otherwise

amazing to see progress on Waku API init

jimstir · 2025-09-26T13:47:58Z

@jimstir I think it's going to be hard to maintain a spell check dictionary.

Yea, the nature of specifications, new terms will always be introduced which will require constant updates to the dictionary.

Propose custom IDL for Waku API definition

93bd790

fryorcraken force-pushed the f/waku-api-custom-idl branch from 6e40863 to 93bd790 Compare June 18, 2025 00:13

fryorcraken changed the title ~~F/waku api custom idl~~ Waku API Spec Jun 18, 2025

add language translation

e013c15

Ivansete-status reviewed Jun 18, 2025

View reviewed changes

standards/application/waku-api.md Outdated Show resolved Hide resolved

standards/application/waku-api.md Outdated Show resolved Hide resolved

standards/application/waku-api.md Outdated Show resolved Hide resolved

standards/application/waku-api.md Outdated Show resolved Hide resolved

NagyZoltanPeter reviewed Jun 18, 2025

View reviewed changes

Ivansete-status mentioned this pull request Jun 18, 2025

Add "Messaging API" spec #19

Open

fryorcraken added 3 commits June 24, 2025 12:23

typos and types

adaba54

set default value

d5c688a

Reducing prescription re language mapping

95ebcd9

fryorcraken commented Jun 26, 2025

View reviewed changes

fryorcraken mentioned this pull request Jun 26, 2025

chore!: make sharding configuration explicit logos-messaging/logos-delivery#3468

Merged

7 tasks

weboko reviewed Jun 27, 2025

View reviewed changes

standards/application/waku-api.md Show resolved Hide resolved

weboko reviewed Jun 27, 2025

View reviewed changes

fryorcraken added 4 commits June 30, 2025 14:26

Only specify nim and TS naming convention

73354fd

Reducing the scope, we can review Rust, Golang and C in a separate PR.

remove extra

2096211

rename RFC

b20f5fd

rework structure, include feedback

4ca0e08

fryorcraken linked an issue Jul 1, 2025 that may be closed by this pull request

Define Waku API #68

Closed

fryorcraken commented Jul 3, 2025

View reviewed changes

fryorcraken mentioned this pull request Jul 3, 2025

feat!: Use Waku API for libwaku logos-messaging/logos-delivery#3490

Closed

2 tasks

fryorcraken changed the title ~~Waku API Spec~~ Waku API Spec: Node initialization Jul 4, 2025

fryorcraken mentioned this pull request Jul 4, 2025

feat: Implement Init API logos-messaging/logos-delivery#3493

Closed

1 task

fryorcraken commented Jul 7, 2025

View reviewed changes

Mention trait approach for ETH RPC

616306e

After feedback from @osmaczko

fryorcraken mentioned this pull request Sep 25, 2025

feat: Waku API create node logos-messaging/logos-delivery#3580

Merged

add toc

388c257

Ivansete-status approved these changes Sep 25, 2025

View reviewed changes

weboko reviewed Sep 25, 2025

View reviewed changes

weboko approved these changes Sep 25, 2025

View reviewed changes

fryorcraken added 9 commits September 26, 2025 11:32

prefer entry_nodes

ad4fb96

integrate feedback

0c64eaa

fix inconsistencies

82181bf

clarify scope

09e3ade

raw spec

34b9443

note on errors

214ee73

add metadata

7748d6a

change "relay" to "sovereign"

b9454e3

change "sovereign" to "core"

6a421f5

fryorcraken marked this pull request as ready for review September 26, 2025 13:44

remove message confirmation

5cd0080

Ivansete-status mentioned this pull request Sep 30, 2025

Waku api create node logos-messaging/logos-delivery#3590

Closed

1 task

fryorcraken merged commit 71ad70a into master Oct 1, 2025
1 check failed

fryorcraken deleted the f/waku-api-custom-idl branch October 1, 2025 06:32

weboko mentioned this pull request Oct 28, 2025

chore: add Health Status to Waku API #92

Merged


		If the `mode` set is `edge`, the initialised `WakuNode` MUST mount:

		- [LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) as client

	The API defined in this document is an opinionated-by-purpose method to use the more agnostic [WAKU2]() protocols.
	The API defined in this document is an opinionated-by-purpose method to use the more agnostic [WAKU2](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/10/waku2.md) protocols.

	description: "Nodes to connect to; used for discovery bootstrapping and quick connectivity. entree and multiaddr formats are accepted."
	description: "Nodes to connect to; used for discovery bootstrapping and quick connectivity. entree and multiaddr formats are accepted. If not provided, node does not bootstrap (e.g for local development)"

	# If the default config for TWN is not used, then we still provide a message validation default
	description: If the default config for TWN is not used, then we still provide a message validation default

Conversation

fryorcraken commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Ivansete-status left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

NagyZoltanPeter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fryorcraken commented Jun 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fryorcraken commented Sep 25, 2025

Uh oh!

Ivansete-status left a comment

Choose a reason for hiding this comment

Uh oh!

Ivansete-status Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

fryorcraken commented Jun 17, 2025 •

edited

Loading

Ivansete-status Sep 25, 2025 •

edited

Loading