Skip to content

Commit 93bd790

Browse files
fryorcrakenfryorcraken
committed
Propose custom IDL for Waku API definition
1 parent 48479c7 commit 93bd790

File tree

1 file changed

+174
-0
lines changed

1 file changed

+174
-0
lines changed

‎standards/application/waku-api.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
---
2+
title: MESSAGING-API
3+
name: Messaging API definition
4+
category: Standards Track
5+
tags: [reliability, application, api, protocol composition]
6+
editor: Oleksandr Kozlov <oleksandr@status.im>
7+
contributors:
8+
- Oleksandr Kozlov <oleksandr@status.im>
9+
- Prem Chaitanya Prathi <prem@status.im>
10+
- Franck Royer <franck@status.im>
11+
---
12+
13+
## Table of contents
14+
15+
- [Abstract](#abstract)
16+
- [Design Requirements](#design-requirements)
17+
- [API design](#api-design)
18+
- [Requirements](#requirements)
19+
- [Initial configuration](#initial-configuration)
20+
- [Send](#send)
21+
- [Subscribe](#subscribe)
22+
- [Message Storage](#message-storage)
23+
- [Health Indicator](#health-indicator)
24+
- [Event Source](#event-source)
25+
26+
## Abstract
27+
28+
This document specifies an Application Programming Interface (API) that is RECOMMENDED for developers of the [WAKU2](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/10/waku2.md) clients to implement,
29+
and for consumers to use as a single entry point to its functionalities.
30+
31+
This API defines the RECOMMENDED interface for leveraging Waku protocols to send and receive messages.
32+
Application developers SHOULD use it to access capabilities for peer discovery, message routing, and peer-to-peer reliability.
33+
34+
## Motivation
35+
36+
The accessibility of Waku protocols is capped by the accessibility of their implementations, and hence API.
37+
This RFC enables a concerted effort to draft an API that is simple and accessible, and opiniate on sane defaults.
38+
39+
This effort is best done in an RFC, allowing all current implementors to review and agree on it.
40+
41+
The API defined in this document is an opiniated-by-purpose method to use the more agnostic [WAKU2]() protocols.
42+
43+
## Syntax
44+
45+
The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”,
46+
“RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119.txt).
47+
48+
### Definitions
49+
50+
This section defines key terms and concepts used throughout this document.
51+
Each term is detailed in dedicated subsections to ensure clarity and consistency in interpretation.
52+
53+
`Multiaddr` - a self-describing format for encoding network address of a remote peer as per [libp2p addressing](https://github.com/libp2p/specs/blob/6d38f88f7b2d16b0e4489298bcd0737a6d704f7e/addressing/README.md) specification.
54+
55+
## API design
56+
57+
### IDL
58+
59+
A custom Interface Definition Language (IDL) in YAML is used to define the Waku API.
60+
Existing IDL Such as OpenAPI, AsyncAPI or WIT do not exactly fit the requirements for this API.
61+
Hence, instead of having the reader learn a new IDL, we propose to use a simple IDL with self-describing syntax.
62+
63+
An alternative would be to choose a programming language. However, such choice may express unintended opinions on the API.
64+
65+
#### Guidelines
66+
67+
- No `default` means that the value is mandatory
68+
- Primitive types are `string`, `int`, `bool` and `uint`
69+
- Complex pre-define types are `struct`, `option` and `array`
70+
- Primitive types are preferred to describe the API for simplicity, the implementator may prefer a native type (e.g. `string` vs `Multiaddr` object/struct)
71+
72+
### Application
73+
74+
This API is designed for generic use and ease across all programming languages and traditional `REST` architectures.
75+
76+
## The Waku API
77+
78+
```yaml
79+
api_version: "0.0.1"
80+
library_name: "waku"
81+
description: "Waku: a private and censorship-resistant message routing library."
82+
```
83+
84+
### Type definitions
85+
86+
```yaml
87+
types:
88+
Config:
89+
type: struct
90+
fields:
91+
operating_mode:
92+
type: string
93+
constraints: ["edge", "relay"]
94+
description: "The mode of operation of the Waku node. Core protocols used by the node are inferred from this mode."
95+
network_config:
96+
type: struct
97+
default: TheWakuNetworkPreset
98+
fields:
99+
boostrap_nodes:
100+
type: array<string>
101+
default: ""
102+
description: "Bootstrap nodes, entree and multiaddr formats are accepted."
103+
static_store_nodes:
104+
type: array<string>
105+
default: []
106+
description: "Only the passed nodes are used for store queries, discovered store nodes are discarded."
107+
clusterId:
108+
type: uint
109+
default: 1
110+
sharding_mode:
111+
constraints: ["auto", "static"]
112+
auto_sharding_config:
113+
type: optionAutoShardingConfig
114+
default: none
115+
description: "The auto-sharding config, if sharding mode is `auto`"
116+
active_relay_shards:
117+
type: array<uint>
118+
constraints: operating_mode == "relay"
119+
default: []
120+
description: "The shards for relay to subscribe to and participate in."
121+
store_confirmation:
122+
type: bool
123+
default: false
124+
description: "No-payload store hash queries are made to confirm whether outbound messages where received by remote store node."
125+
126+
AutoShardingConfig:
127+
type: struct
128+
fields:
129+
numShardsInCluster:
130+
type: uint
131+
description: "The number of shards in the configured cluster; this is a globally agreed value for each cluster."
132+
```
133+
134+
### Initialise Waku Node
135+
136+
TODO: define WakuNode?
137+
138+
```yaml
139+
functions:
140+
init:
141+
description: "Initialise the waku node"
142+
parameters:
143+
- name: config
144+
type: Config
145+
description: "The Waku node configuration."
146+
returns:
147+
type: result<void, string>
148+
```
149+
150+
#### Functionality / Additional Information / Specific Behaviours
151+
152+
If the node is operating in `edge` mode, it MUST:
153+
154+
- Use [LIGHTPUSH](../standards/core/lightpush.md) to send messages
155+
- Use [FILTER](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/12/filter.md) to receive messages
156+
- Use [PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/f08de108457eed828dadbd36339433c586701267/waku/standards/core/34/peer-exchange.md#abstract) to discover peers
157+
- Use [STORE](../standards/core/store.md) as per [WAKU-P2P-RELIABILITY]()
158+
159+
If the node is configured in `relay` mode, it MUST:
160+
161+
- Use [RELAY](https://github.com/vacp2p/rfc-index/blob/0277fd0c4dbd907dfb2f0c28b6cde94a335e1fae/waku/standards/core/11/relay.md) protocol.
162+
- Host endpoints for [LIGHTPUSH](../standards/core/lightpush.md) and [FILTER](https://github.com/vacp2p/rfc-index/blob/7b443c1aab627894e3f22f5adfbb93f4c4eac4f6/waku/standards/core/12/filter.md).
163+
- Serve the [PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/f08de108457eed828dadbd36339433c586701267/waku/standards/core/34/peer-exchange.md#abstract) protocol.
164+
165+
`edge` mode SHOULD be used if node functions in resource restricted environment,
166+
whereas `relay` SHOULD be used if node has no hard restrictions.
167+
168+
## Security/Privacy Considerations
169+
170+
See [WAKU2-ADVERSARIAL-MODELS](https://github.com/waku-org/specs/blob/master/informational/adversarial-models.md).
171+
172+
## Copyright
173+
174+
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

0 commit comments

Comments
 (0)