specs/standards/application/waku-api.md

title	name	category	tags	editor	contributors
MESSAGING-API	Messaging API definition	Standards Track	reliability application api protocol composition	Oleksandr Kozlov <oleksandr@status.im>	Oleksandr Kozlov <oleksandr@status.im> Prem Chaitanya Prathi <prem@status.im> Franck Royer <franck@status.im>

Table of contents

• Abstract
• Design Requirements
• API design
  • Requirements
  • Initial configuration
  • Send
  • Subscribe
  • Message Storage
  • Health Indicator
  • Event Source

Abstract

This document specifies an Application Programming Interface (API) that is RECOMMENDED for developers of the WAKU2 clients to implement, and for consumers to use as a single entry point to its functionalities.

This API defines the RECOMMENDED interface for leveraging Waku protocols to send and receive messages. Application developers SHOULD use it to access capabilities for peer discovery, message routing, and peer-to-peer reliability.

Motivation

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 opiniate on sane defaults.

This effort is best done in an RFC, allowing all current implementors to review and agree on it.

The API defined in this document is an opiniated-by-purpose method to use the more agnostic WAKU2 protocols.

Syntax

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119.

Definitions

This section defines key terms and concepts used throughout this document. Each term is detailed in dedicated subsections to ensure clarity and consistency in interpretation.

Multiaddr - a self-describing format for encoding network address of a remote peer as per libp2p addressing specification.

API design

IDL

A custom Interface Definition Language (IDL) in YAML is used to define the Waku API. Existing IDL Such as OpenAPI, AsyncAPI or WIT do not exactly fit the requirements for this API. Hence, instead of having the reader learn a new IDL, we propose to use a simple IDL with self-describing syntax.

An alternative would be to choose a programming language. However, such choice may express unintended opinions on the API.

Guidelines

• 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)

Application

This API is designed for generic use and ease across all programming languages and traditional REST architectures.

The Waku API

api_version: "0.0.1"
library_name: "waku"
description: "Waku: a private and censorship-resistant message routing library."

Type definitions

types:
  Config:
    type: struct
    fields:
      operating_mode: 
        type: string
        constraints: ["edge", "relay"]
        description: "The mode of operation of the Waku node. Core protocols used by the node are inferred from this mode."
      network_config:
        type: struct
        default: TheWakuNetworkPreset
        fields:
          boostrap_nodes:
            type: array<string>
            default: ""
            description: "Bootstrap nodes, entree and multiaddr formats are accepted."
          static_store_nodes:
            type: array<string>
            default: []
            description: "Only the passed nodes are used for store queries, discovered store nodes are discarded."
          clusterId:
            type: uint
            default: 1
          sharding_mode:
            constraints: ["auto", "static"]
          auto_sharding_config:
            type: optionAutoShardingConfig
            default: none
            description: "The auto-sharding config, if sharding mode is `auto`"
          active_relay_shards:
            type: array<uint>
            constraints: operating_mode == "relay"
            default: []
            description: "The shards for relay to subscribe to and participate in." 
      store_confirmation:
        type: bool
        default: false
        description: "No-payload store hash queries are made to confirm whether outbound messages where received by remote store node."
          
  AutoShardingConfig:
    type: struct
    fields:
      numShardsInCluster:
        type: uint
        description: "The number of shards in the configured cluster; this is a globally agreed value for each cluster."

Initialise Waku Node

TODO: define WakuNode?

functions:
  init:
    description: "Initialise the waku node"
    parameters:
        - name: config
          type: Config
          description: "The Waku node configuration."
    returns:
        type: result<void, string>

Functionality / Additional Information / Specific Behaviours

If the node is operating in edge mode, it MUST:

• Use LIGHTPUSH to send messages
• Use FILTER to receive messages
• Use PEER-EXCHANGE to discover peers
• Use STORE as per WAKU-P2P-RELIABILITY

If the node is configured in relay mode, it MUST:

• Use RELAY protocol.
• Host endpoints for LIGHTPUSH and FILTER.
• Serve the PEER-EXCHANGE protocol.

edge mode SHOULD be used if node functions in resource restricted environment, whereas relay SHOULD be used if node has no hard restrictions.

Security/Privacy Considerations

See WAKU2-ADVERSARIAL-MODELS.

Copyright

Copyright and related rights waived via CC0.