diff --git a/standards/application/waku-api.md b/standards/application/waku-api.md new file mode 100644 index 0000000..03d4bf6 --- /dev/null +++ b/standards/application/waku-api.md @@ -0,0 +1,322 @@ +--- +title: WAKU-API +name: Waku API definition +category: Standards Track +status: raw +tags: [reliability, application, api, protocol composition] +editor: Oleksandr Kozlov +contributors: +- Oleksandr Kozlov +- Prem Chaitanya Prathi +- Franck Royer +--- + +## Table of contents + + + * [Table of contents](#table-of-contents) + * [Abstract](#abstract) + * [Motivation](#motivation) + * [Syntax](#syntax) + * [API design](#api-design) + * [IDL](#idl) + * [Primitive types and general guidelines](#primitive-types-and-general-guidelines) + * [Language mappings](#language-mappings) + * [Application](#application) + * [The Waku API](#the-waku-api) + * [Initialise Waku node](#initialise-waku-node) + * [Type definitions](#type-definitions) + * [Function definitions](#function-definitions) + * [Predefined values](#predefined-values) + * [Extended definitions](#extended-definitions) + * [The Validation API](#the-validation-api) + * [Security/Privacy Considerations](#securityprivacy-considerations) + * [Copyright](#copyright) + + +## Abstract + +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, +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. + +TODO: This spec must be further extended to include connection health inspection, message sending, subscription and store hash queries. + +## 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 provides an opinion on sane defaults. + +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/main/waku/standards/core/10/waku2.md) 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](https://www.ietf.org/rfc/rfc2119.txt). + +## 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. + +### Primitive types and general guidelines + +- 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: + - `object`: object and other nested types. + - `array`: iterable object containing values of all the same type. + - `result`: an enum type that either contains a value or void (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. +- Usage of `result` is RECOMMENDED, usage of exceptions is NOT RECOMMENDED, no matter the language. + +TODO: Review whether to specify categories of errors. + +### Language mappings + +How the API definition should be translated to specific languages. + +```yaml +language_mappings: + typescript: + naming_convention: + - functions: "camelCase" + - variables: "camelCase" + - types: "PascalCase" + nim: + naming_convention: + - functions: "camelCase" + - variables: "camelCase" + - types: "PascalCase" +``` + +### Application + +This API is designed for generic use and ease across all programming languages, for `edge` and `core` type nodes. + +## The Waku API + +```yaml +api_version: "0.0.1" +library_name: "waku" +description: "Waku: a private and censorship-resistant message routing library." +``` + +### Initialise Waku node + +#### Type definitions + +```yaml +types: + WakuNode: + type: object + description: "A Waku node instance." + + NodeConfig: + type: object + fields: + mode: + type: string + constraints: [ "edge", "core" ] + default: "core" # "edge" for mobile and browser devices. + description: "The mode of operation of the Waku node; 'edge' of the network: relies on other nodes for message routing; 'core' of the network: fully participate to message routing." + protocols_config: + type: ProtocolsConfig + default: TheWakuNetworkPreset + networking_config: + type: NetworkConfig + default: DefaultNetworkingConfig + eth_rpc_endpoints: + type: array + description: "Eth/Web3 RPC endpoint URLs, only required when RLN is used for message validation; fail-over available by passing multiple URLs. Accepting an object for ETH RPC will be added at a later stage." + + ProtocolsConfig: + type: object + fields: + entry_nodes: + type: array + default: [] + description: "Nodes to connect to; used for discovery bootstrapping and quick connectivity. enrtree and multiaddr formats are accepted. If not provided, node does not bootstrap to the network (local dev)." + static_store_nodes: + type: array + default: [] + # TODO: confirm behaviour at implementation time. + description: "The passed nodes are prioritised for store queries." + cluster_id: + type: uint + auto_sharding_config: + type: AutoShardingConfig + default: DefaultAutoShardingConfig + description: "The auto-sharding config, if sharding mode is `auto`" + message_validation: + type: MessageValidation + description: "If the default config for TWN is not used, then we still provide default configuration for message validation." + default: DefaultMessageValidation + + NetworkingConfig: + type: object + fields: + listen_ipv4: + type: string + default: "0.0.0.0" + description: "The network IP address on which libp2p and discv5 listen for inbound connections. Not applicable for some environments such as the browser." + p2p_tcp_port: + type: uint + default: 60000 + description: "The TCP port used for libp2p, relay, etc aka, general p2p message routing. Not applicable for some environments such as the browser." + discv5_udp_port: + type: uint + default: 9000 + description: "The UDP port used for discv5. Not applicable for some environments such as the browser." + + AutoShardingConfig: + type: object + fields: + num_shards_in_cluster: + type: uint + description: "The number of shards in the configured cluster; this is a globally agreed value for each cluster." + + MessageValidation: + type: object + fields: + max_message_size: + type: string + default: "150 KiB" + description: "Maximum message size. Accepted units: KiB, KB, and B. e.g. 1024KiB; 1500 B; etc." + # For now, RLN is the only message validation available + rln_config: + type: RlnConfig + # If the default config for TWN is not used, then we do not apply RLN + default: none + + RlnConfig: + type: object + fields: + contract_address: + type: string + description: "The address of the RLN contract exposes `root` and `getMerkleRoot` ABIs" + chain_id: + type: uint + description: "The chain id on which the RLN contract is deployed" + epoch_size_sec: + type: uint + description: "The epoch size to use for RLN, in seconds" +``` + +#### Function definitions + +```yaml +functions: + createNode: + description: "Initialise a Waku node instance" + parameters: + - name: nodeConfig + type: NodeConfig + description: "The Waku node configuration." + returns: + type: result +``` + +#### Predefined values + +```yaml +values: + + DefaultNetworkingConfig: + type: NetworkConfig + fields: + listen_ipv4: "0.0.0.0" + p2p_tcp_port: 60000 + discv5_udp_port: 9000 + + TheWakuNetworkPreset: + type: ProtocolsConfig + fields: + entry_nodes: [ "enrtree://AIRVQ5DDA4FFWLRBCHJWUWOO6X6S4ZTZ5B667LQ6AJU6PEYDLRD5O@sandbox.waku.nodes.status.im" ] + # On TWN, we encourage the usage of discovered store nodes + static_store_nodes: [] + cluster_id: 1 + auto_sharding_config: + fields: + num_shards_in_cluster: 8 + message_validation: TheWakuNetworkMessageValidation + + TheWakuNetworkMessageValidation: + type: MessageValidation + fields: + max_message_size: "150 KiB" + rln_config: + fields: + contract_address: "0xB9cd878C90E49F797B4431fBF4fb333108CB90e6" + chain_id: 59141 + epoch_size_sec: 600 # 10 minutes + + # If not preset is used, autosharding on one cluster is applied by default + # This is a safe default that abstract shards (content topic shard derivation), and it enables scaling at a later stage + DefaultAutoShardingConfig: + type: AutoShardingConfig + fields: + num_shards_in_cluster: 1 + + # If no preset is used, we only apply a max size limit to messages + DefaultMessageValidation: + type: MessageValidation + fields: + max_message_size: "150 KiB" + rln_config: none +``` + +#### Extended definitions + +**`mode`**: + +If the `mode` set is `edge`, the initialised `WakuNode` SHOULD use: + +- [LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) as client +- [FILTER](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/12/filter.md) as client +- [STORE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/13/store.md) as client +- [METADATA](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/66/metadata.md) as client +- [PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md) as client +- [P2P-RELIABILITY](/standards/application/p2p-reliability.md) + +If the `mode` set is `core`, the initialised `WakuNode` SHOULD use: + +- [RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/11/relay.md) +- [LIGHTPUSH](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/19/lightpush.md) as service node +- [FILTER](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/12/filter.md) as service node +- [PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md) as service node +- [STORE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/13/store.md) as client +- [METADATA](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/66/metadata.md) as client and service node +- [P2P-RELIABILITY](/standards/application/p2p-reliability.md) +- [DISCV5](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/33/discv5.md) +- [PEER-EXCHANGE](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/34/peer-exchange.md) as client and service node +- [RENDEZVOUS](https://github.com/waku-org/specs/blob/master/standards/core/rendezvous.md) as client and service node + +`edge` mode SHOULD be used if node functions in resource restricted environment, +whereas `core` SHOULD be used if node has no strong hardware or bandwidth restrictions. + +## The Validation API + +[WAKU2-RLN-RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md) is currently the primary message validation mechanism in place. + +Work is scheduled to specify a validate API to enable plug-in validation. +As part of this API, it will be expected that a validation object can be passed, +that would contain all validation parameters including RLN. + +In the time being, parameters specific to RLN are accepted for the message validation. +RLN can also be disabled. + +## Security/Privacy Considerations + +See [WAKU2-ADVERSARIAL-MODELS](https://github.com/waku-org/specs/blob/master/informational/adversarial-models.md). + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).