diff --git a/packages/docusaurus-playground/docs/Advanced/pages/pages.md b/packages/docusaurus-playground/docs/Advanced/pages/pages.md deleted file mode 100644 index 300a090..0000000 --- a/packages/docusaurus-playground/docs/Advanced/pages/pages.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Subtitle -sidebar_position: 4 ---- - -## Hello World - -```python -print("hello world!") -``` diff --git a/packages/docusaurus-playground/docs/architect.md b/packages/docusaurus-playground/docs/architect.md deleted file mode 100644 index 3a075d4..0000000 --- a/packages/docusaurus-playground/docs/architect.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Description and architecture -sidebar_position: 2 ---- - -Waku is a family of protocols that enable private, censorship-resistant communications; a suite of open-source software; and the name of the public, permissionless and decentralized network facilitating generalized messaging. By communications, we mean the exchange of data or messages between two or more entities, whether they are users, devices or nodes. - -Waku was built as open-source public goods infrastructure to serve as the communications layer of the decentralized web. As such, its development focuses on the following: - -- Generalized: Waku's focus on generalized and ephemeral messaging facilitates communication between users, subsystems or nodes according to developers' needs. - -- Peer-to-peer: Waku is implemented via a decentralized p2p network, yielding the advantages of censorship resistance while remaining adaptive and scalable. - -- Runs anywhere: Waku was designed to run in resource-restricted environments—like phones and browsers—enabling users operating lower-spec hardware or with intermittent bandwidth to participate as peers. - -- Privacy first: Waku's strong privacy guarantees strengthen its resistance to censorship and external attack. Waku empowers developers to build apps that cannot harvest users' metadata, removing the need for users to trust that their data is not used without their permission. - -- Modular: Waku's modularity enables developers to make tradeoffs according to their users' privacy expectations and performance demands by implementing only those protocols that are relevant to their applications. While one app might value privacy above all else, another may be willing to make compromises to deliver a more frictionless UX. - -- Platform agnostic: Waku can run on any platform or in any environment making it a suitable messaging solution for decentralized applications regardless of the network on which they're deployed. - -
- -### Network architecture - -The Waku team has developed three clients to run in different environments along with a range of SDKs in Rust, React Native, Kotlin and Swift: - -- nwaku: Waku's reference implementation written in Nim. -- go-waku: An implementation for native integration with Golang applications. -- js-waku: Waku's JavaScript implementation for browser environments. - -Waku is best thought of as a cohesive whole in terms of its capabilities. However, under the hood are three distinct network interaction domains: gossip, discovery and request/response. - -Waku compromises multiple protocols, including but not limited to the following: - -**Waku Relay**: The heart of Waku v2, the relay protocol specifies a pub/sub approach to p2p messaging with a focus on privacy, censorship resistance, security and privacy, and is currently implemented as a minor extension of the libp2p GossipSub protocol. - -**Waku Filter**: A lighter-weight version of the relay protocol for resource-restricted devices, Waku Filter enables light nodes to only receive the messages they want from full nodes. - -**Waku Store**: Enables querying of messages stored by other nodes through Waku Relay. - -**Waku Light Push**: A request/response protocol that enables nodes with short connection windows or limited bandwidth to publish messages to the Waku network - -
- -[Dive into the docs](https://vac.dev/research) - -[Continue reading](/team) diff --git a/packages/docusaurus-playground/docs/clients/js-waku/build-chat-app.mdx b/packages/docusaurus-playground/docs/clients/js-waku/build-chat-app.mdx new file mode 100644 index 0000000..720e90e --- /dev/null +++ b/packages/docusaurus-playground/docs/clients/js-waku/build-chat-app.mdx @@ -0,0 +1,282 @@ +--- +title: Build a Chat App +--- + +# Build a Chat App + +In this guide, you will learn how to receive and send messages using Waku by building an app from scratch. +If you want to learn how to add Waku to an existing app, check the [Quick Start](./quick-start) guide. + +## Pre-Requisites + +### 1. Set up Project + +Setup a new npm package: + +```shell +mkdir waku-app +cd waku-app +npm init -y +``` + +### 2. Set up Web Server + +Use the `serve` package as a web server + +```shell +npm i -D serve +``` + +Add a `start` script to the `package.json` file: + +```json +{ + "scripts": { + "start": "serve ." + } +} +``` + +### 3. Create Files + +Finally, create empty files for your project: + +```shell +touch index.html index.js +``` + +## Write Your App + +## 1. Add HTML Elements + +In `index.html`, add a button, text box and `div` for messages to have a basic chat app. +Also, import the `index.js` file. + +```html title=index.html + + + + + + Waku Chat App + + + + + +
+
+ + + +``` + +## 2. Access HTML Elements + +::: note + +From now on, all changes need to be done in the `index.js` file. + +::: + +Initialize variables to easily modify the HTML content: + +```js +const sendButton = document.getElementById('send') +const messagesDiv = document.getElementById('messages') +const textInput = document.getElementById('textInput') +``` + +## 3. Start a Waku Node + +Create and start a Waku Node: + +```js +import { createLightNode } from 'https://unpkg.com/@waku/create@0.0.12/bundle/index.js' + +const wakuNode = await createLightNode({ defaultBootstrap: true }) +await wakuNode.start() +``` + +:::info + +Setting the `defaultBootstrap` option to true allows your Waku node to connect to a set of pre-defined nodes. + +::: + +## 4. Wait for Connection to be Established + +Your Waku node needs to connect to a remote node in order to access the network. +To wait for this, use the `waitForRemotePeer` function: + +```js +import * as waku from 'https://unpkg.com/@waku/core@0.0.16/bundle/index.js' + +await waku.waitForRemotePeer(wakuNode) +``` + +## 5. Define a Content Topic + +The `contentTopic` is a metadata `string` used for categorizing messages on the Waku network. +Depending on your use case, you can create one or more new `contentTopic`(s). +Refer to our [How to Choose a Content Topic](/) guide more details. + +For this guide, we'll use `/chat-app-guide/1/message/utf8`. +Note that our payload will be encoded using `utf-8`. +We recommended using Protobuf for production purposes. + +```js +const contentTopic = `/chat-app-guide/1/message/utf8` +``` + +## 6. Render Incoming Messages + +Let's store incoming messages in an array and create a function to render them in the `messages` div: + +```js +const updateMessages = (msgs, div) => { + div.innerHTML = '' +} + +const messages = [] +``` + +## 7. Create a Decoder + +Waku supports various encryption protocols. +A decoder allows you to specify the content topic to use and how to decrypt messages. +For the chosen content topic, create a plain text decoder (without encryption): + +```js +const decoder = waku.createDecoder(contentTopic) +``` + +## 8. Listen for Incoming Messages + +Messages sent over the network are `Waku Message`s, +as defined in the [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/#wire-format) RFC. + +Messages returned by the plain text decoder implement the [`DecodedMessage`](https://js.waku.org/classes/_waku_core.DecodedMessage.html) interface. + +For now, we will just use the `payload` field. +It is a byte array field that can be used to encode any data. +We will store messages as a `utf-8` string. + +Listen to messages using the decoder and add them to the `messages` div upon reception: + +```ts +import * as utils from 'https://unpkg.com/@waku/utils@0.0.4/bundle/bytes.js' + +wakuNode.filter.subscribe([decoder], (message) => { + const str = utils.bytesToUtf8(message.payload) + messages.push(str) + updateMessages(messages, messagesDiv) +}) +``` + +## 9. Send Messages + +Finally, create a plain text encoder and set up the `send` button to send messages. +Users will be able to enter the message using the `textInput` div. + +Once done, we can enable the `send` button. + +```ts +const encoder = waku.createEncoder({ contentTopic }) + +sendButton.onclick = async () => { + const text = textInput.value + + await wakuNode.lightPush.send(encoder, { + payload: utils.utf8ToBytes(text), + }) + textInput.value = null +} +sendButton.disabled = false +``` + +### 10. Run the App + +You can now start a local web server to run the app: + +```shell +npm start +``` + +Click on the link in the console (http://localhost:3000/) and send a message! +You can open your app in several tabs to see messages being sent around. + +## Conclusion + +Congratulations on building your first Waku chat app. You can find the complete files below: + +```html title=index.html + + + + + + JS-Waku Quick Start App + + + + + +
+
+ + + +``` + +```js title=index.js +import { createLightNode } from 'https://unpkg.com/@waku/create@0.0.12/bundle/index.js' +import * as waku from 'https://unpkg.com/@waku/core@0.0.16/bundle/index.js' +import * as utils from 'https://unpkg.com/@waku/utils@0.0.4/bundle/bytes.js' + +const sendButton = document.getElementById('send') +const messagesDiv = document.getElementById('messages') +const textInput = document.getElementById('textInput') + +const wakuNode = await createLightNode({ defaultBootstrap: true }) +await wakuNode.start() + +await waku.waitForRemotePeer(wakuNode) + +const contentTopic = `/chat-app-guide/1/message/utf8` + +const updateMessages = (msgs, div) => { + div.innerHTML = '' +} + +const messages = [] + +const decoder = waku.createDecoder(contentTopic) + +wakuNode.filter.subscribe([decoder], (message) => { + console.log('message received', message) + const str = utils.bytesToUtf8(message.payload) + messages.push(str) + updateMessages(messages, messagesDiv) +}) + +const encoder = waku.createEncoder({ contentTopic }) + +sendButton.onclick = async () => { + const text = textInput.value + + await wakuNode.lightPush.send(encoder, { + payload: utils.utf8ToBytes(text), + }) + textInput.value = null +} +sendButton.disabled = false +``` diff --git a/packages/docusaurus-playground/docs/clients/js-waku/index.md b/packages/docusaurus-playground/docs/clients/js-waku/index.md new file mode 100644 index 0000000..4ca98ee --- /dev/null +++ b/packages/docusaurus-playground/docs/clients/js-waku/index.md @@ -0,0 +1,41 @@ +--- +title: Introduction +slug: /clients/js-waku +--- + +# JS-Waku Documentation + +[JS-Waku](https://github.com/waku-org/js-waku) is the TypeScript implementation of the Waku protocol, +specifically designed for the browser environment. +This powerful, easy-to-use library enables you to integrate Waku into your web applications seamlessly. + +:::info + +If you wish to use Waku with a NodeJS application, you can either: + +- Use [nwaku](https://github.com/status-im/nwaku)'s [JSON RPC API](https://rfc.vac.dev/spec/16/) +- Or, attempt to use go-waku's [c-bindings](https://github.com/waku-org/go-waku/tree/master/examples/c-bindings) in NodeJS + +::: + +To get started, the [Quick Start](/) guide offers a simple way to integrate Waku into your web app. +For a more comprehensive tutorial, follow the [Build a Chat App](/) guide, +which demonstrates how to create a chat app from scratch. + +Explore the [js-waku-examples repository](https://github.com/waku-org/js-waku-examples) to find various working Proof-of-Concepts that showcase how to use JS-Waku effectively. +You can also interact with these examples live: + +- [web-chat](https://examples.waku.org/web-chat): A simple public chat. +- [eth-pm](https://examples.waku.org/eth-pm): End-to-end encrypted private messages. +- [rln-js](https://examples.waku.org/rln-js): Demonstration of [RLN](https://rfc.vac.dev/spec/32/), + an economic spam protection protocol that rate limit using zero-knowledge for privacy preserving purposes. + +To gain a deeper understanding of Waku, visit the [overview documentation](/). +If you're interested in learning how Waku works under the hood, check out the specs at [rfc.vac.dev](https://rfc.vac.dev/). + +## Bugs, Questions & Support + +If you encounter any bug or would like to propose new features, feel free to [open an issue](https://github.com/waku-org/js-waku/issues/new/). + +For general discussion, get help or latest news, +join **#js-waku** on [Vac Discord](https://discord.gg/Nrac59MfSX) or the [Waku Telegram Group](https://t.me/waku_org). diff --git a/packages/docusaurus-playground/docs/clients/js-waku/quick-start.mdx b/packages/docusaurus-playground/docs/clients/js-waku/quick-start.mdx new file mode 100644 index 0000000..3e45ecf --- /dev/null +++ b/packages/docusaurus-playground/docs/clients/js-waku/quick-start.mdx @@ -0,0 +1,114 @@ +--- +title: Quick Start +date: 2021-12-09T14:00:00+01:00 +weight: 20 +--- + +# Quick Start + +In this guide, you will learn how to integrate Waku into an **existing** JavaScript project. +If you're looking to build a Waku app from scratch, check out our [Build a Chat App](./build-chat-app) guide. + +## 1. Install Waku Libraries + +To begin, install the required Waku libraries with the following command: + +```shell +npm i @waku/core @waku/create @waku/utils +``` + +## 2. Start a Waku Node + +Next, create and start a Waku Node: + +```js +import { createLightNode } from '@waku/create' + +const waku = await createLightNode({ defaultBootstrap: true }) +await waku.start() +``` + +:::info + +Setting the `defaultBootstrap` option to true allows your Waku node to connect to a set of pre-defined nodes. + +::: + +## 3. Wait for Connection to be Established + +Your Waku node needs to connect to a remote node in order to access the network. +To wait for this, use the `waitForRemotePeer` function: + +```js +import * as waku from '@waku/core' + +await waku.waitForRemotePeer(wakuNode) +``` + +## 4. Define a Content Topic + +The `contentTopic` is a metadata `string` used for categorizing messages on the Waku network. +Depending on your use case, you can create one or more new `contentTopic`(s). +Refer to our [How to Choose a Content Topic](/) guide more details. + +For this guide, we'll use `/quick-start/1/message/utf8`. +Note that our payload will be encoded using `utf-8`. +We recommended using Protobuf for production purposes. + +```js +const contentTopic = `/quick-start/1/message/utf8` +``` + +## 5. Create a Decoder + +Waku supports various encryption protocols. +A decoder allows you to specify the content topic to use and how to decrypt messages. +For the chosen content topic, create a plain text decoder (without encryption): + +```js +const decoder = waku.createDecoder(contentTopic) +``` + +## 6. Listen for Incoming Messages + +Messages sent over the network are `Waku Message`s, +as defined in the [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/#wire-format) RFC. + +Messages returned by the plain text decoder implement the [`DecodedMessage`](https://js.waku.org/classes/_waku_core.DecodedMessage.html) interface. + +For now, we will just use the `payload` field. +It is a byte array field that can be used to encode any data. +We will store messages as a `utf-8` string. + +To listen for messages using the decoder, use the following code: + +```js +wakuNode.filter.subscribe([decoder], (message) => { + const str = utils.bytesToUtf8(message.payload) + // str is a string, render it in your app as desired +}) +``` + +## 7. Send Messages + +Finally, create a `sendMessage` function that sends messages over Waku: + +```js +import * as utils from '@waku/utils' + +const encoder = waku.createEncoder(contentTopic) + +const sendMessage = async (textMsg) => { + await wakuNode.lightPush.push(encoder, { + payload: utils.utf8ToBytes(textMsg), + }) +} +``` + +Now, you can use the `sendMessage` function in your app to send messages. + +## Conclusion + +Congratulations! You've successfully added decentralized communication features to your app. + +Continue learning by exploring how to [build a chat app](./build-chat-app) from scratch using Waku. diff --git a/packages/docusaurus-playground/docs/community.md b/packages/docusaurus-playground/docs/community.md new file mode 100644 index 0000000..44e65cd --- /dev/null +++ b/packages/docusaurus-playground/docs/community.md @@ -0,0 +1,21 @@ +--- +title: Join Our Community +--- + +Welcome to the Waku Community! Whether you're interested in building with Waku, contributing to the network, expanding your knowledge, or staying up-to-date with our progress, we have something for everyone. + +## [Discord](https://discord.waku.org/) + +Connect with like-minded individuals in the Waku ecosystem! Introduce yourself, join developer conversations, or seek assistance. Join the [Waku Discord](https://discord.waku.org/) today! + +## [Twitter](https://twitter.com/waku_org) + +Stay informed and updated with the latest news and insights from Waku. [Follow us on Twitter](https://twitter.com/waku_org) now for all the exciting updates! + +## [Telegram](https://t.me/waku_org) + +Join the [Waku Telegram Group](https://t.me/waku_org) now and become part of the thriving community! Stay informed, share ideas, and connect with fellow enthusiasts. + +## [Vac Forum](https://forum.vac.dev/) + +Are you seeking answers or looking forward to engaging in in-depth discussions about Waku? Join the conversation on the [Vac Forum](https://forum.vac.dev/), where you can participate in research-related and other insightful talks. diff --git a/packages/docusaurus-playground/docs/configuration.md b/packages/docusaurus-playground/docs/configuration.md deleted file mode 100644 index d4ccc38..0000000 --- a/packages/docusaurus-playground/docs/configuration.md +++ /dev/null @@ -1,264 +0,0 @@ ---- -title: Configuration -sidebar_position: 2 ---- - -# Configuration - -import TOCInline from '@theme/TOCInline'; - -:::info - -Check the [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.mdx) for an exhaustive list of options. - -::: - -Docusaurus has a unique take on configurations. We encourage you to congregate information about your site into one place. We guard the fields of this file and facilitate making this data object accessible across your site. - -Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors to be able to focus on documentation while still being able to customize the site. - -## Syntax to declare `docusaurus.config.js` {#syntax-to-declare-docusaurus-config} - -The `docusaurus.config.js` file is run in Node.js and should export either: - -- a **config object** -- a **function** that creates the config object - -:::info - -The `docusaurus.config.js` file only supports the [**CommonJS**](https://flaviocopes.com/commonjs/) module system: - -- **Required:** use `module.exports = /* your config*/` to export your Docusaurus config -- **Optional:** use `require("lib")` to import Node.js packages -- **Optional:** use `await import("lib")` (dynamic import) in an async function to import ESM-Only Node.js packages - -::: - -Node.js gives us the ability to declare our Docusaurus configuration in various **equivalent ways**, and all the following config examples lead to the exact same result: - -```js title="docusaurus.config.js" -module.exports = { - title: 'Docusaurus', - url: 'https://docusaurus.io', - // your site config ... -} -``` - -```js title="docusaurus.config.js" -const config = { - title: 'Docusaurus', - url: 'https://docusaurus.io', - // your site config ... -} - -module.exports = config -``` - -```js title="docusaurus.config.js" -module.exports = function configCreator() { - return { - title: 'Docusaurus', - url: 'https://docusaurus.io', - // your site config ... - } -} -``` - -```js title="docusaurus.config.js" -module.exports = async function createConfigAsync() { - return { - title: 'Docusaurus', - url: 'https://docusaurus.io', - // your site config ... - } -} -``` - -:::tip Using ESM-only packages - -Using an async config creator can be useful to import ESM-only modules (notably most Remark plugins). It is possible to import such modules thanks to dynamic imports: - -```js title="docusaurus.config.js" -module.exports = async function createConfigAsync() { - // Use a dynamic import instead of require('esm-lib') - // highlight-next-line - const lib = await import('lib') - - return { - title: 'Docusaurus', - url: 'https://docusaurus.io', - // rest of your site config... - } -} -``` - -::: - -## What goes into a `docusaurus.config.js`? {#what-goes-into-a-docusaurusconfigjs} - -You should not have to write your `docusaurus.config.js` from scratch even if you are developing your site. All templates come with a `docusaurus.config.js` that includes defaults for the common options. - -However, it can be helpful if you have a high-level understanding of how the configurations are designed and implemented. - -The high-level overview of Docusaurus configuration can be categorized into: - - - -### Site metadata {#site-metadata} - -Site metadata contains the essential global metadata such as `title`, `url`, `baseUrl`, and `favicon`. - -They are used in several places such as your site's title and headings, browser tab icon, social sharing (Facebook, Twitter) information or even to generate the correct path to serve your static files. - -### Deployment configurations {#deployment-configurations} - -Deployment configurations such as `projectName`, `organizationName`, and optionally `deploymentBranch` are used when you deploy your site with the `deploy` command. - -It is recommended to check the [deployment docs](deployment.mdx) for more information. - -### Theme, plugin, and preset configurations {#theme-plugin-and-preset-configurations} - -List the [themes](./using-plugins.mdx#using-themes), [plugins](./using-plugins.mdx), and [presets](./using-plugins.mdx#using-presets) for your site in the `themes`, `plugins`, and `presets` fields, respectively. These are typically npm packages: - -```js title="docusaurus.config.js" -module.exports = { - // ... - plugins: [ - '@docusaurus/plugin-content-blog', - '@docusaurus/plugin-content-pages', - ], - themes: ['@docusaurus/theme-classic'], -} -``` - -:::tip - -Docusaurus supports [**module shorthands**](./using-plugins.mdx#module-shorthands), allowing you to simplify the above configuration as: - -```js title="docusaurus.config.js" -module.exports = { - // ... - plugins: ['content-blog', 'content-pages'], - themes: ['classic'], -} -``` - -::: - -They can also be loaded from local directories: - -```js title="docusaurus.config.js" -const path = require('path') - -module.exports = { - // ... - themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')], -} -``` - -To specify options for a plugin or theme, replace the name of the plugin or theme in the config file with an array containing the name and an options object: - -```js title="docusaurus.config.js" -module.exports = { - // ... - plugins: [ - [ - 'content-blog', - { - path: 'blog', - routeBasePath: 'blog', - include: ['*.md', '*.mdx'], - // ... - }, - ], - 'content-pages', - ], -} -``` - -To specify options for a plugin or theme that is bundled in a preset, pass the options through the `presets` field. In this example, `docs` refers to `@docusaurus/plugin-content-docs` and `theme` refers to `@docusaurus/theme-classic`. - -```js title="docusaurus.config.js" -module.exports = { - // ... - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - sidebarPath: require.resolve('./sidebars.js'), - }, - theme: { - customCss: [require.resolve('./src/css/custom.css')], - }, - }, - ], - ], -} -``` - -:::tip - -The `presets: [['classic', {...}]]` shorthand works as well. - -::: - -For further help configuring themes, plugins, and presets, see [Using Plugins](./using-plugins.mdx). - -### Custom configurations {#custom-configurations} - -Docusaurus guards `docusaurus.config.js` from unknown fields. To add custom fields, define them in `customFields`. - -Example: - -```js title="docusaurus.config.js" -module.exports = { - // ... - // highlight-start - customFields: { - image: '', - keywords: [], - }, - // highlight-end - // ... -} -``` - -## Accessing configuration from components {#accessing-configuration-from-components} - -Your configuration object will be made available to all the components of your site. And you may access them via React context as `siteConfig`. - -Basic example: - -```jsx -import React from 'react' -// highlight-next-line -import useDocusaurusContext from '@docusaurus/useDocusaurusContext' - -const Hello = () => { - // highlight-start - const { siteConfig } = useDocusaurusContext() - // highlight-end - const { title, tagline } = siteConfig - - return
{`${title} · ${tagline}`}
-} -``` - -:::tip - -If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in `docusaurus.config.js`. - -::: - -## Customizing Babel Configuration {#customizing-babel-configuration} - -For new Docusaurus projects, we automatically generated a `babel.config.js` in the project root. - -```js title="babel.config.js" -module.exports = { - presets: [require.resolve('@docusaurus/core/lib/babel/preset')], -} -``` - -Most of the time, this configuration will work just fine. If you want to customize your Babel configuration (e.g. to add support for Flow), you can directly edit this file. For your changes to take effect, you need to restart the Docusaurus dev server. diff --git a/packages/docusaurus-playground/docs/contribute.md b/packages/docusaurus-playground/docs/contribute.md new file mode 100644 index 0000000..f9c1303 --- /dev/null +++ b/packages/docusaurus-playground/docs/contribute.md @@ -0,0 +1,27 @@ +--- +title: Contribute to Waku +--- + +Get involved in Waku's open-source initiatives to improve the protocols, SDKs, developer tools and examples, and documentation. You can contribute by: + +- [Operating a node](/guides/sdks-and-nodes#operate-a-waku-node) within your application. +- [Reporting bugs](#report-a-bug) and [suggesting missing features](#suggest-a-feature) to the development team. +- Inspiring other developers to explore and use Waku for [various use cases](/getting-started/use-cases). + +Begin your journey by visiting the [SDKs and Nodes](/guides/sdks-and-nodes) guide and start building on Waku today! + +## Report a Bug + +To report a bug, create an issue in the appropriate [GitHub repository](https://github.com/waku-org). Ensure no issue exists about the bug and include detailed steps to reproduce the bug. + +## Suggest a Feature + +To suggest a new feature, create an issue in the appropriate [GitHub repository](https://github.com/waku-org). Ensure no issue exists about the feature and specify the use cases the feature can enable, allowing us to investigate and prioritize accordingly. + +## Make Pull Requests + +Community pull requests (PRs) are highly encouraged, but we recommend [suggesting a feature](#suggest-a-feature) first to gauge interest and gather feedback before proceeding with a PR. + +## Contribute to Waku Research + +Waku Research is an innovative R&D project dedicated to developing modular peer-to-peer protocols for communication that prioritize privacy, security, and censorship resistance. Explore Waku's ongoing challenges and experimental code at . diff --git a/packages/docusaurus-playground/docs/getting-started.md b/packages/docusaurus-playground/docs/getting-started.md deleted file mode 100644 index 72f67bf..0000000 --- a/packages/docusaurus-playground/docs/getting-started.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Getting Started -sidebar_position: 3 ---- - -# Tutorial Intro - -Let's discover **Docusaurus in less than 5 minutes**. - -```mermaid -graph TD; - A-->B; - A-->C; - B-->D; - C-->D; -``` - -## Getting Started - -Get started by **creating a new site**. - -Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. - -### What you'll need - -- [Node.js](https://nodejs.org/en/download/) version 16.14 or above: - - When installing Node.js, you are recommended to check all checkboxes related to dependencies. diff --git a/packages/docusaurus-playground/docs/getting-started/concepts/content-topics.md b/packages/docusaurus-playground/docs/getting-started/concepts/content-topics.md new file mode 100644 index 0000000..0ce935e --- /dev/null +++ b/packages/docusaurus-playground/docs/getting-started/concepts/content-topics.md @@ -0,0 +1,37 @@ +--- +title: Content Topics +--- + +`Content Topics` are metadata strings set by developers on outgoing messages to facilitate protocol-level features like selectively processing incoming messages ([Relay](/getting-started/concepts/protocols#relay) or [Filter](/getting-started/concepts/protocols#filter)) and retrieving historical messages ([Store](/getting-started/concepts/protocols#store)) that meet specific filtering criteria. Please refer to the [WAKU2-TOPICS](https://rfc.vac.dev/spec/23/#content-topics) specification to learn more. + +## Content Topic Format + +Here is the recommended format for content topics: + +`/{application-name}/{version}/{content-topic-name}/{encoding}` + +- `application-name`: This is the unique name of your decentralized application (dApp) to prevent conflicts with other dApps. +- `version`: Typically starting at `1`, this field helps track breaking changes in your messages. +- `content-topic-name`: The specific name of the content topic used for filtering. +- `encoding`: The message serialization/encoding format, with [Protocol Buffers](https://protobuf.dev/) (`proto`) being the recommended choice. + +For instance, if your dApp is called `SuperCrypto` and it allows users to receive notifications and send private messages, you can consider using the following content topics: + +- `/supercrypto/1/notification/proto` +- `/supercrypto/1/private-message/proto` + +:::info +While you can choose any encoding format for your `Content Topic`, we highly recommend using Protocol Buffers (`proto`) because of its efficiency. Choosing a lightweight format ensures optimal performance of your dApp. +::: + +## Naming Considerations + +When choosing a content topic, it is crucial to consider privacy implications. The `Filter` protocol discloses content topics to peers, and the `Store` protocol can link them with a light node, allowing nodes providing these services to access message content topics, posing potential privacy risks. + +:::info +Waku is developing privacy-preserving features like [Anonymous Filter Subscription](https://rfc.vac.dev/spec/12/#future-work) for the `Filter` protocol and [Anonymous Query](https://rfc.vac.dev/spec/13/#future-work) for the `Store` protocol to hide content topics from potential adversaries. +::: + +You can preserve the anonymity of individual identities by increasing [k-anonymity](https://www.privitar.com/blog/k-anonymity-an-introduction/), where k is proportional to the network size (number of subscribers). This involves using a single content topic across the entire application or specific features such as notifications or private messages, allowing multiple users to share it. + +However, maintaining functionality with a single content topic can introduce complexity. We recommend switching functionality using the Protocol Buffer message format or the [Waku Message](/getting-started/concepts/protocols#waku-message) `meta` attribute. By doing so, applications can retain a high granularity and functionality while using a single content topic, preserving user privacy. diff --git a/packages/docusaurus-playground/docs/getting-started/concepts/network-domains.md b/packages/docusaurus-playground/docs/getting-started/concepts/network-domains.md new file mode 100644 index 0000000..160aa2a --- /dev/null +++ b/packages/docusaurus-playground/docs/getting-started/concepts/network-domains.md @@ -0,0 +1,58 @@ +--- +title: Network Domains +--- + +Waku is a unified and cohesive entity that offers a rich ecosystem with three distinct network interaction domains. These domains serve specialized purposes and contribute to the robust functionality of Waku, forming its foundation. + +## Discovery Domain + +Peer discovery in Waku facilitates locating other nodes within the network. As a modular protocol, Waku incorporates various discovery mechanisms, such as [Discv5](/getting-started/concepts/peer-discovery#discv5) and [Peer Exchange](/getting-started/concepts/peer-discovery#peer-exchange). These mechanisms allow developers to choose the most suitable option(s) for their specific use cases and user environments, including mobile phones, desktop browsers, servers, and more. + +## Gossip Domain + +GossipSub derives its name from the practice within Pub/Sub networks where peers gossip about the messages they have encountered, thus establishing a message delivery network. + +Waku employs gossiping through [Relay](/getting-started/concepts/protocols#relay) to distribute messages across the network. Additionally, Waku introduces [RLN Relay](/getting-started/concepts/protocols#rln-relay), an experimental mechanism that combines privacy preservation and economic spam protection. + +## Request/Response Domain + +Waku provides a set of protocols to optimize its performance in resource-limited environments like low bandwidth or mostly offline scenarios for multiple purposes. + +- [Store](/getting-started/concepts/protocols#store) enables the retrieval of historical messages. +- [Filter](/getting-started/concepts/protocols#filter) efficiently retrieves a subset of messages to conserve bandwidth. +- [Light Push](/getting-started/concepts/protocols#light-push) facilitates message publication for nodes with limited bandwidth and short connection windows. + +## Overview of Protocol Interaction + +Here's a diagram illustrating the interaction between different protocols within the Waku network. + +```mermaid +sequenceDiagram +participant A as A relay +participant B as B relay(pubtopic1) +participant C as C relay(pubtopic1) +participant D as D relay(pubtopic1), store(pubtopic1), filter +participant E as E relay, store +participant F as F filter + +A ->> A: msg1=WakuMessage(contentTopic1, data) (1) +F ->> D: FilterRequest(pubtopic1, contentTopic1) (2) +D ->> D: Subscribe F to filter (2) +A ->> B: Publish msg1 on pubtopic1 (3) +B ->> D: relay msg1 on pubtopic1 (3) +D ->> D: store: saves msg1 (4) +D ->> C: relay msg1 on pubtopic1 (4) +D ->> F: MessagePush(msg1) (5) +E ->> E: E comes online (6) +E ->> D: HistoryQuery(pubtopic1, contentTopic1) (6) +D ->> E: HistoryResponse(msg1, ...) (6) +``` + +The Pub/Sub topic `pubtopic1` serves as a means of routing messages (the network employs a default Pub/Sub topic) and indicates that it is subscribed to messages on that topic for a relay. Node D serves as a `Store` and is responsible for persisting messages. + +1. Node A creates a WakuMessage `msg1` with [Content Topic](/getting-started/concepts/content-topics) `contentTopic1`. +2. Node F requests to get messages filtered by Pub/Sub topic `pubtopic1` and Content Topic `contentTopic1`. Node D subscribes F to this filter and will forward messages that match that filter in the future. +3. Node A publishes `msg1` on `pubtopic1`. The message is sent from Node A to Node B and then forwarded to Node D. +4. Node D, upon receiving `msg1` both stores the message for future retrieval by other nodes and forwards it to Node C. +5. Node D also pushes `msg1` to Node F, informing it about the arrival of a new message. +6. At a later time, Node E comes online and requests messages matching `pubtopic1` and `contentTopic1` from Node D. Node D responds with `msg1` and potentially other messages that match the query. diff --git a/packages/docusaurus-playground/docs/getting-started/concepts/peer-discovery.md b/packages/docusaurus-playground/docs/getting-started/concepts/peer-discovery.md new file mode 100644 index 0000000..ccf48bf --- /dev/null +++ b/packages/docusaurus-playground/docs/getting-started/concepts/peer-discovery.md @@ -0,0 +1,71 @@ +--- +title: Peer Discovery +--- + +When initializing a Waku node, it must connect with other peers to enable message sending, receiving, and retrieval. To achieve this, a discovery mechanism is employed to locate and connect with other peers. This process is known as bootstrapping. + +Once a connection is established, the node must actively seek out additional peers to have: + +- Sufficient peers in the [Relay](/getting-started/concepts/protocols#relay) mesh: The goal is to have at least 6 peers in the mesh. This ensures a robust network where messages can be efficiently relayed. +- Reserve peers for backup: It is essential to have a surplus of peers available as reserves. These reserves are backups when the current peers become overloaded or experience unexpected disconnections. +- Peers with specific capabilities: The node seeks out peers with specific capabilities, such as [Store](/getting-started/concepts/protocols#store), [Light Push](/getting-started/concepts/protocols#light-push), or [Filter](/getting-started/concepts/protocols#filter). This allows for targeted interactions and enhanced functionality based on the desired capabilities. + +## Predefined Nodes + +Waku applications have the flexibility to embed bootstrap node addresses directly into their codebase. Developers can opt to use either the [predefined nodes by Status](https://github.com/waku-org/js-waku/blob/master/packages/core/src/lib/predefined_bootstrap_nodes.ts#L45) or [operate a node](/guides/sdks-and-nodes#operate-a-waku-node) per their preference. + +#### Pros + +- Low latency. +- Low resource requirements. + +#### Cons + +- Vulnerable to censorship: Node IPs can be blocked or restricted. +- Limited scalability: The number of nodes is fixed and cannot easily be expanded. +- Maintenance challenges: Updating the node list requires modifying the code, which can be cumbersome and involves releasing and deploying. + +## [DNS Discovery](https://rfc.vac.dev/spec/31/) + +Built upon the foundation of [EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459), DNS Discovery allows the retrieval of an `ENR` tree from the `TXT` field of a domain name. This innovative approach enables the storage of essential node connection details, including IP, port, and multiaddr, using the standardized [ENR format](https://rfc.vac.dev/spec/31/). + +This bootstrapping method allows anyone to register and publish a domain name for the network, fostering increased decentralization. + +#### Pros + +- Low latency, low resource requirements. +- Easy bootstrap list updates by modifying the domain name, eliminating the need for code changes. +- Ability to reference a larger list of nodes by including other domain names in the code or ENR tree. + +#### Cons + +- Vulnerable to censorship: Domain names can be blocked or restricted. +- Limited scalability: The listed nodes are at risk of being overwhelmed by receiving all queries. Also, operators must provide their `ENR` to the domain owner for listing. + +## [Discv5](https://rfc.vac.dev/spec/33/) + +`Discv5` is a decentralized and efficient peer discovery method for the Waku network. It uses a [Distributed Hash Table (DHT)](https://en.wikipedia.org/wiki/Distributed_hash_table) for storing `ENR` records, providing resistance to censorship. `Discv5` offers a global view of participating nodes, enabling random sampling for load distribution. It uses bootstrap nodes as an entry point to the network, providing randomized sets of nodes for mesh expansion. This enhances resilience, load balancing, and security in the Waku network. + +#### Pros + +- Decentralized with random sampling from a global view. +- Continuously researched and improved. + +#### Cons + +- Requires lots of connections and involves frequent churn. +- Relies on User Datagram Protocol (UDP), which is not supported in web browsers. + +## [Peer Exchange](https://rfc.vac.dev/spec/34/) + +The primary objective of this protocol is to facilitate peer connectivity for resource-limited devices. The peer exchange protocol enables lightweight nodes to request peers from other nodes within the network. Light nodes can bootstrap and expand their mesh independently without relying on `Discv5`. + +#### Pros + +- Low resource requirements. +- Decentralized with random sampling of nodes from a global view using `Discv5`. + +#### Cons + +- Decreased anonymity. +- Imposes additional load on responder nodes. diff --git a/packages/docusaurus-playground/docs/getting-started/concepts/protocols.md b/packages/docusaurus-playground/docs/getting-started/concepts/protocols.md new file mode 100644 index 0000000..86e4cf4 --- /dev/null +++ b/packages/docusaurus-playground/docs/getting-started/concepts/protocols.md @@ -0,0 +1,47 @@ +--- +title: Protocols +--- + +Waku takes a modular approach, providing a range of protocols that enable applications to control the trade-offs involved in the [Anonymity Trilemma](https://eprint.iacr.org/2017/954.pdf). This flexibility empowers applications to make informed choices regarding the desired balance between anonymity, scalability, and latency. Here are the main protocols provided by Waku: + +## [Relay](https://rfc.vac.dev/spec/11/) + +`Relay` protocol employs a Pub/Sub architecture to facilitate message routing among peers. It extends the [libp2p GossipSub protocol](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md) to create a privacy-focused peer-to-peer messaging protocol that enables secure communication channels, encryption, and protection against censorship. + +## [RLN Relay](https://rfc.vac.dev/spec/17/) + +`RLN Relay` protocol extends the `Relay` protocol by using [Rate Limit Nullifiers (RLN)](https://rfc.vac.dev/spec/32/) to provide efficient and economic spam prevention. It caps the bandwidth usage for all peers on the network, effectively preventing spam, and imposes financial penalties and network removal for spammers. You can find more details in the [RLN Relay blog post](https://vac.dev/rln-relay). + +## [Filter](https://rfc.vac.dev/spec/12/) + +`Filter` protocol allows light nodes to selectively subscribe to specific messages transmitted by other peers using [content topics](/getting-started/concepts/content-topics). It is designed to be a lightweight alternative for accessing the `Relay` network, particularly tailored for devices with limited bandwidth. + +:::info +`Filter` protocol helps optimize bandwidth usage, but it has fewer privacy guarantees as it must disclose the content topic to its peers to retrieve messages. +::: + +## [Store](https://rfc.vac.dev/spec/13/) + +`Store` protocol is responsible for storing messages relayed on the network, making it possible to query and retrieve them later. This functionality benefits offline peers by enabling them to retrieve missed messages upon reconnection. + +:::info +Using `Relay` and `Filter` protocols is recommended when a node is online, as `Store` does not guarantee data availability. The `Store` protocol is suitable for retrieving messages when connecting to the network, like when a dApp starts. +::: + +## [Light Push](https://rfc.vac.dev/spec/19/) + +`Light Push` is a [Request/Response](/getting-started/concepts/network-domains#requestresponse-domain) protocol for nodes with limited bandwidth and short connection windows. It allows a client to receive an acknowledgment when sending messages, indicating that at least one peer has received them. Subsequently, the remote peer forwards these messages to the `Relay` network. + +:::info +While the `Light Push` protocol acknowledges the receipt by the remote peer, it does not guarantee network-wide propagation. +::: + +## [Waku Message](https://rfc.vac.dev/spec/14) + +`Waku Message` specifies the message structure used in the Waku network. It defines the attributes and metadata fields that accompany a message, including the following: + +- `content_topic` attribute for [content-based filtering](/getting-started/concepts/content-topics). +- `payload` attribute containing the message data payload to be sent. +- `meta` attribute for conveying additional details to various protocols for application-specific processing. +- `timestamp` attribute signifying the time at which the message was generated by its sender. +- `ephemeral` attribute specifying whether the network should not persist the message. diff --git a/packages/docusaurus-playground/docs/getting-started/concepts/transports.md b/packages/docusaurus-playground/docs/getting-started/concepts/transports.md new file mode 100644 index 0000000..87c7203 --- /dev/null +++ b/packages/docusaurus-playground/docs/getting-started/concepts/transports.md @@ -0,0 +1,15 @@ +--- +title: Transports +--- + +Transports help move data packets across a network by establishing connections between peers. They define the rules and protocols to ensure efficient network transmission, routing, and data delivery. + +Waku is a transport-agnostic framework that allows developers to choose and support multiple protocols according to their requirements. For Waku nodes, the following transports are recommended: + +- **TCP:** By default, Waku nodes use TCP for communication. Service nodes should employ TCP for listening to and connecting with other nodes. +- **Secure WebSocket:** In browser environments, secure WebSocket is used. Service nodes are encouraged to set up SSL certificates to enable incoming connections from browsers and serve them securely. +- Other protocols like [WebRTC](https://github.com/waku-org/js-waku/issues/20), [WebTransport](https://github.com/waku-org/js-waku/issues/697), and QUIC have been researched and studied for potential integration. + +:::info +Waku ensures compatibility and improved communication capabilities by following these recommended transports. +::: diff --git a/packages/docusaurus-playground/docs/getting-started/history.md b/packages/docusaurus-playground/docs/getting-started/history.md new file mode 100644 index 0000000..72eb5bb --- /dev/null +++ b/packages/docusaurus-playground/docs/getting-started/history.md @@ -0,0 +1,57 @@ +--- +title: History of Waku +--- + +`Waku v1` was a fork of Whisper with some added tweaks for efficiency. `Waku v2` introduces a fully revamped suite of protocols designed to address the goals set out [previously](/#motivation-and-goals). + +```mermaid +%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchName': 'HISTORY'}} }%% +gitGraph + commit id:"2013" + commit id:"2015" tag:"R&D" + commit id:"2018" tag:"R&D" type: HIGHLIGHT + branch v1 + checkout v1 + commit id:"2020" tag:"release" + checkout HISTORY + merge v1 + branch v2 + checkout v2 + commit id:"2021" tag:"release" + checkout HISTORY + merge v2 + commit id:"🔥" +``` + +### 2013 + +The Ethereum White Paper was published, unveiling the holy trinity of Web3, comprising: + +- Ethereum for consensus. +- Swarm for decentralized storage. +- Whisper for peer-to-peer messaging. + +### 2015-2018 + +The development of the Whisper protocol lagged behind the advancements made by the Ethereum EVM and Swarm, primarily because there was no dedicated team working on building the protocol. + +### 2018 + +Due to the lack of progress made on Whisper and growing concerns around scalability, [Vac](https://vac.dev/) was established to focus on researching and developing more scalable peer-to-peer messaging solutions. + +### 2020 + +`Waku v1` replaces Whisper as the messaging protocol in Status, resulting in the following: + +- Enhanced performance. +- Better scalability. +- Ability to work in resource-limited environments. +- And many more. + +### 2021 + +`Waku v2` releases with a fully revamped suite of protocols that not only supersedes but also surpasses the performance of `Waku v1`. + +### Present Day + +Waku has continued to evolve and enhance itself, solidifying its position as the standard for Web3 communication. diff --git a/packages/docusaurus-playground/docs/getting-started/index.md b/packages/docusaurus-playground/docs/getting-started/index.md new file mode 100644 index 0000000..bb852a7 --- /dev/null +++ b/packages/docusaurus-playground/docs/getting-started/index.md @@ -0,0 +1,72 @@ +--- +title: What is Waku? +slug: / +--- + +:::caution +Waku has risks and limitations as it is still developing and preparing for extensive adoption. However, it is already demonstrating its capabilities by [powering various applications](/powered-by-waku). [Join our community](/community) to stay updated on our progress. +::: + +Waku, the standard of Web3 communication, is a family of protocols that offer secure, private, and peer-to-peer communication in a decentralized environment. It is designed to operate in resource-limited environments but can also be used as a node or desktop application. + +Waku protocols ensure that users communication remains censorship-resistant and privacy-preserving, giving them complete control over their data. By integrating Waku into your dApp, you can add decentralized communication features to your application without compromising security or privacy. + +## Motivation and Goals + +The Waku family of protocols is designed for diverse applications due to their properties, such as: + +### Generalized Messaging + +Waku aims to solve the problem of ephemeral messaging between subsystems and nodes through a flexible, secure, and private protocol. It supports human-to-human and machine-to-machine messaging scenarios but is not designed for data storage. + +### Peer-to-Peer + +Waku is suitable for applications that require a peer-to-peer approach, offering the following advantages: + +- Censorship resistance with no single point of failure. +- Adaptive and scalable network. +- Shared infrastructure, leveraging the capabilities of Waku as a service network. + +### Platform Agnostic + +Waku can run on any platform or environment, even settings with limited resources like bandwidth, CPU, memory, disk, battery, etc. It can also function when the nodes are not publicly connected or are mostly offline. + +### Privacy-Preserving + +Waku can cater to applications that require privacy guarantees, such as: + +- Pseudonymity and not being tied to any Personally Identifiable Information (PII). +- Metadata protection in transit. +- Various forms of [unlinkability](/getting-started/reference/security-features#anonymityunlinkability). + +### Modular Design + +Waku nodes are adaptive and can be customized based on the application's requirements and environment. Users can adjust several parameters, including: + +- Low privacy/low resource usage vs. high privacy/increased latency + bandwidth usage. +- Providing resources to the network vs. consuming resources. +- Stronger guarantees for spam protection vs. economic registration cost. + +These options are part of the [Anonymity Trilemma](https://eprint.iacr.org/2017/954.pdf), which Waku addresses through its adjustable protocol. + +### Service Network + +Waku provides developers with a convenient solution for building decentralized communication systems, eliminating the need to start from scratch or depend on centralized systems. Node operators can offer several services, such as: + +- Storing messages for offline devices. +- Enabling bandwidth-saving access to the [Relay](/getting-started/concepts/protocols#relay) network through [Light Push](/getting-started/concepts/protocols#light-push) and [Filter](/getting-started/concepts/protocols#filter) protocols. +- Implementing spam prevention and DoS mitigation features. +- Providing a resilient and shared [Relay](/getting-started/concepts/protocols#relay) infrastructure that applications can leverage to enhance reliability and efficiency. + +## How Does Waku Work? + +The [Relay](/getting-started/concepts/protocols#relay) protocol is the foundation of the Waku network, which employs a Pub/Sub architecture built on the [libp2p GossipSub protocol](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md). Additionally, various other Waku protocols have been created to facilitate specific functionalities, including but not limited to: + +1. Facilitating the retrieval of historical messages for mostly offline devices. +2. Providing solutions for encrypted communication, such as symmetric encryption, ECIES/asymmetric encryption, and noise handshake-based key turns. +3. Preserving bandwidth usage for resource-limited environments. +4. Implementing economic spam protection (rate limits) while ensuring privacy. +5. Developing methods to protect against mass deanonymization (currently being researched). +6. Designing strategies to scale `Relay/GossipSub` securely. + +If you want to learn more about how Waku operates, the [WAKU2 RFC](https://rfc.vac.dev/spec/10/) provides an in-depth look under the hood. diff --git a/packages/docusaurus-playground/docs/getting-started/reference/glossary.md b/packages/docusaurus-playground/docs/getting-started/reference/glossary.md new file mode 100644 index 0000000..eb774a8 --- /dev/null +++ b/packages/docusaurus-playground/docs/getting-started/reference/glossary.md @@ -0,0 +1,127 @@ +--- +title: Glossary +--- + +# Waku Docs Glossary + +Definitions and usage of the terminology used in the Waku ecosystem. + +### Bootstrapping + +Bootstrapping is the initial entry point of a [node](#node) to the [Waku network](#waku). Once connected, other [peer discovery](#peer-discovery) methods can be employed to establish connections with fellow peers. + +### [Content Topic](/getting-started/concepts/content-topics) + +A content topic is a string attached to [messages](#waku-message) to enable [protocol-level](#protocol) features like selective message processing and retrieval based on specific criteria. + +### [Dappnode](https://dappnode.com/) + +Dappnode is an open-source platform that simplifies the hosting and management of decentralized applications and blockchain nodes, including [Waku](#waku). + +### [Discv5](/getting-started/concepts/peer-discovery#discv5) + +Discv5 is a [peer discovery](#peer-discovery) mechanism using a Distributed Hash Table (DHT) to store [ENR](#enr) records, providing censorship resistance, load distribution, and enhanced network resilience. + +### [DNS Discovery](/getting-started/concepts/peer-discovery#dns-discovery) + +DNS discovery is a [peer discovery](#peer-discovery) mechanism that allows the retrieval of an [ENR](#enr) tree from the TXT field of a domain name, enabling the storage of [node](#node) connection details and promoting decentralization. + +### [ENR](https://rfc.vac.dev/spec/31/) + +Ethereum Node Record (ENR) is a specification used to represent and identify [nodes](#node), facilitating [discovery](#peer-discovery) and communication within the network. Besides connection details, `Waku ENR` also includes node configuration information like enabled protocol and shards. + +### [Filter](/getting-started/concepts/protocols#filter) + +Filter is a [protocol](#protocol) that enables [light nodes](#light-node) to selectively subscribe to specific [messages](#waku-message) transmitted by [peers](#peer) using [content topics](#content-topic). It is designed to be a lightweight alternative for accessing the [Relay](#relay) network. + +### [GossipSub](/getting-started/concepts/network-domains#gossip-domain) + +GossipSub is a [protocol](#protocol) for efficient and scalable information dissemination in decentralized networks commonly used in blockchain systems. + +### Light Node + +A light node is a [resource-limited](#resource-limited) device or client that leverages service nodes to access the [Relay](#relay) network. + +### [Light Push](/getting-started/concepts/protocols#light-push) + +Light push is a protocol enabling [light nodes](#light-node) to send [messages](#waku-message) to the [Relay](#relay) network and receive acknowledgments confirming that a [peer](#peer) has received them. + +### Mostly Offline + +Mostly offline devices refer to clients who spend most of their time offline or disconnected from the network but occasionally connect for certain reasons. Examples include browsers and mobile phones. + +### Node + +A node is a device or client that implements Waku [protocols](#protocol) and leverages the [Waku network](#waku) to enable secure and private peer-to-peer Web3 communication. + +### Payload + +The payload field in a [Waku Message](#waku-message) contains the application data, serving as the business logic message transmitted between clients over Waku. Applications can encrypt the payload or employ encryption methods specified in [Waku Message Payload Encryption](#waku-message-payload-encryption). + +### Peer + +A peer refers to other [nodes](#node) and participants of the [Waku network](#waku) with whom communication and interaction are possible. + +### [Peer Discovery](/getting-started/concepts/peer-discovery) + +Peer discovery is the process where a [node](#node) locates and connects with [peers](#peer) to establish communication and exchange information. + +### [Peer Exchange](/getting-started/concepts/peer-discovery#peer-exchange) + +Peer exchange is a [peer discovery](#peer-discovery) mechanism that enables [light nodes](#light-node) to request and receive peers from other nodes in the network, allowing them to bootstrap and expand their connections without depending on [Discv5](#discv5). + +### [Protocol](/getting-started/concepts/protocols) + +A protocol is a set of rules that enables [nodes](#node) within the [Waku network](#waku) to perform various functionalities such as message sending, relaying, filtering, storing, retrieving, and more. + +### Pub/Sub + +Publish/Subscribe (Pub/Sub) is an asynchronous messaging pattern where publishers send messages to topics, and subscribers receive messages from topics of interest, allowing efficient one-to-many communication. + +### Pub/Sub Topic + +A Pub/Sub topic is a string that serves as an identifier for the topic of interest among [GossipSub](#gossipsub) peers. Peers interested in the same topic are likely to maintain a connection and forward messages received on that topic. + +### [Rate Limit Nullifiers](https://rfc.vac.dev/spec/32/) + +Rate Limit Nullifiers (RLN) are a construct based on zero-knowledge proofs that provide an anonymous rate-limited messaging framework, preserving message owner anonymity while preventing spam or DoS attacks. + +### [Relay](/getting-started/concepts/protocols#relay) + +Relay is a [protocol](#protocol) that extends the [GossipSub protocol](#gossipsub) to enable secure and censorship-resistant [message](#waku-message) dissemination among [peers](#peer) while preserving privacy. + +### Resource-Limited + +Resource-limited refers to environments or devices restricting available resources, including bandwidth, CPU, memory, disk, and battery power. + +### [RLN Relay](/getting-started/concepts/protocols#rln-relay) + +RLN Relay is an extension of the [Relay protocol](#relay) that uses [Rate Limit Nullifiers (RLN)](#rate-limit-nullifiers) to prevent spam economically by enforcing bandwidth caps, imposing penalties, and facilitating network removal for spammers. + +### [SDK](/guides/sdks-and-nodes) + +SDKs are tools, libraries, and resources to integrate Waku's private, secure, and censorship-free communication features into various applications. + +### [Store](/getting-started/concepts/protocols#store) + +Store is a [protocol](#protocol) that enables the storage of relayed [messages](#waku-message) in the network, allowing offline peers to retrieve missed messages upon reconnecting to the network. + +### [Transport](/getting-started/concepts/transports) + +A transport is a network mechanism that establishes connections between [peers](#peer) and enables efficient transmission, routing, and delivery of data packets. + +### Waku + +Waku is a family of private, secure, decentralized, and peer-to-peer Web3 communication [protocols](#protocol) designed to operate in [resource-limited](#resource-limited) environments and suitable for [node](#node) or desktop application use. Additionally, these protocols collectively form the Waku network. + +### [Waku Message](/getting-started/concepts/protocols#waku-message) + +Waku Message defines the structure of messages in the [Waku network](#waku), including the [content topic](#content-topic), [payload](#payload), and metadata for application-specific processing. + +### [Waku Message Payload Encryption](https://rfc.vac.dev/spec/26/) + +Waku Message Payload Encryption provides guidelines for implementing secure and private communication in the [Waku network](#waku). It covers encryption, decryption, and signing methods for message [payloads](#payload), focusing on confidentiality, authenticity, integrity, and unlinkability. + +### [Waku Noise](https://rfc.vac.dev/spec/35/) + +Waku Noise is a specified way to use the [Noise Protocol Framework](http://noiseprotocol.org/) to build protocols that enable secure key-exchange mechanisms for encrypted communication with confidentiality, authenticity, integrity, strong forward secrecy, and identity-hiding properties. diff --git a/packages/docusaurus-playground/docs/getting-started/reference/research-in-progress.md b/packages/docusaurus-playground/docs/getting-started/reference/research-in-progress.md new file mode 100644 index 0000000..fc3ba41 --- /dev/null +++ b/packages/docusaurus-playground/docs/getting-started/reference/research-in-progress.md @@ -0,0 +1,21 @@ +--- +title: Research in Progress +--- + +The following features are currently experimental and under research and initial implementation: + +## Economic Spam Resistance + +We aim to enable an incentivized spam protection technique to enhance `Relay` by using [Rate Limit Nullifiers (RLN)](https://rfc.vac.dev/spec/32/). In this advanced method, peers are limited to a certain messaging rate per epoch, and an immediate financial penalty is enforced for spammers who break this rate. You can find more details in the [RLN Relay blog post](https://vac.dev/rln-relay). + +We have prepared a PoC implementation of this method in JS: + +## Prevention of Denial of Service (DoS) and Node Incentivization + +Denial of service signifies the case where an adversarial peer exhausts another node's service capacity (e.g., by making a large number of requests) and makes it unavailable to the rest of the system. RnD on DoS attack mitigation can tracked from here: . + +In a nutshell, peers have to pay for the service they obtain from each other. In addition to incentivizing the service provider, accounting also makes DoS attacks costly for malicious peers. The accounting model can be used in `Store` and `Filter` to protect against DoS attacks. + +Additionally, along with RLN, this gives node operators who provide a useful service to the network an incentive to perform that service. Read more here: + +You can also read more about the ongoing challenges the Waku team is working on here: diff --git a/packages/docusaurus-playground/docs/getting-started/reference/security-features.md b/packages/docusaurus-playground/docs/getting-started/reference/security-features.md new file mode 100644 index 0000000..c7164cc --- /dev/null +++ b/packages/docusaurus-playground/docs/getting-started/reference/security-features.md @@ -0,0 +1,32 @@ +--- +title: Security Features +--- + +Waku's protocol layers offer different services and security considerations, shaping the overall security of Waku. We document the security models in the [RFCs of the protocols](https://rfc.vac.dev/), aiming to provide transparent and open-source references. This empowers Waku users to understand each protocol's security guarantees and limitations. + +Some of the Waku's security features include the following: + +## [Pseudonymity](https://rfc.vac.dev/spec/10/#pseudonymity) + +Waku ensures pseudonymity across its protocol layers, using libp2p `PeerID` as identifiers instead of disclosing true identities. However, it's important to note that pseudonymity doesn't provide complete anonymity. Actions performed under the same pseudonym (`PeerID`) can be linked, leading to the potential re-identification of the actual actor. + +## [Anonymity/Unlinkability](https://rfc.vac.dev/spec/10/#anonymity--unlinkability) + +Anonymity means an adversary cannot connect an actor to their actions or data. To achieve anonymity, avoiding linking activities with actors or their Personally Identifiable Information (PII) is crucial. In Waku, the following anonymity features are provided: + +- [Publisher-Message Unlinkability](https://rfc.vac.dev/spec/11/#security-analysis): Ensures that the publisher of messages in the `Relay` protocol cannot be linked to their published messages. +- [Subscriber-Topic Unlinkability](https://rfc.vac.dev/spec/11/#security-analysis): Ensures that the subscriber of topics in the `Relay` protocol cannot be linked to the topics they have subscribed to. + +## [Spam Protection](https://rfc.vac.dev/spec/10/#spam-protection) + +The spam protection feature in `Relay` ensures that no adversary can flood the system with many messages, intentionally or not, regardless of the content's validity or usefulness. This protection is achieved through the [scoring mechanism](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#spam-protection-measures) of `GossipSub v1.1`. Peers assign scores to their connections based on their behavior and remove peers with low scores. + +Ongoing research is being conducted, including developing [Rate Limit Nullifiers (RLN)](/getting-started/concepts/protocols#rln-relay), which can be explored further at: . + +## [Data Confidentiality, Integrity, and Authenticity](https://rfc.vac.dev/spec/10/#data-confidentiality-integrity-and-authenticity) + +Confidentiality in Waku is ensured through data encryption, while integrity and authenticity are achieved through digital signatures. These security measures are available in [Waku Message (version 1)](https://rfc.vac.dev/spec/14#version-1) and [Noise](https://rfc.vac.dev/spec/35/) protocols, which offer payload encryption and encrypted signatures. [Noise](https://rfc.vac.dev/spec/35/) protocols also facilitate secure channel negotiation within the Waku network. + +## [Security Considerations](https://rfc.vac.dev/spec/10/#security-considerations) + +In protocols like `Store` and `Filter`, where direct connections are required for the designated service, anonymity or unlinkability is not guaranteed. This is because nodes use their `PeerID` to identify each other during direct connections, making the service obtained in these protocols linkable to the beneficiary's `PeerID`, considered Personally Identifiable Information (PII). In `Store`, the queried node can link the querying node's `PeerID` to the topics being queried. Similarly, in `Filter`, a node can link the `PeerID` of a light node to its content filter. diff --git a/packages/docusaurus-playground/docs/getting-started/reference/waku-vs-libp2p.md b/packages/docusaurus-playground/docs/getting-started/reference/waku-vs-libp2p.md new file mode 100644 index 0000000..cede5a9 --- /dev/null +++ b/packages/docusaurus-playground/docs/getting-started/reference/waku-vs-libp2p.md @@ -0,0 +1,19 @@ +--- +title: Comparing Waku and libp2p +--- + +Since Waku is built on top of libp2p, they share a lot of concepts and terminologies between them. However, there are key differences between them that are worth noting. + +## Waku as a Service Network + +Waku intends to incentivize mechanisms to run nodes, but it's not part of libp2p's scope. Additionally, users or developers do not have to deploy their infra as a prerequisite to use Waku. It is a service network. However, you are encouraged to [operate a node](/guides/sdks-and-nodes#operate-a-waku-node) to support and decentralize the network. + +## Waku as a Keyturn Solution + +Waku includes various protocols covering the following domains: privacy preservation, censorship resistance, and platform agnosticism, allowing it to run on any platform or environment. + +libp2p does not provide out-of-the-box protocols to enable mostly offline/resource-limited devices, [Store](/getting-started/concepts/protocols#store)/[Light Push](/getting-started/concepts/protocols#light-push)/[Filter](/getting-started/concepts/protocols#filter) caters to those use cases. + +## Economic Spam Protection + +libp2p does not have strong spam protection guarantees, [RLN Relay](/getting-started/concepts/protocols#rln-relay) is a protocol being developed by the Waku team towards this goal. diff --git a/packages/docusaurus-playground/docs/getting-started/use-cases.md b/packages/docusaurus-playground/docs/getting-started/use-cases.md new file mode 100644 index 0000000..c03f600 --- /dev/null +++ b/packages/docusaurus-playground/docs/getting-started/use-cases.md @@ -0,0 +1,78 @@ +--- +title: Use Cases +--- + +Waku is a decentralized communication network, facilitating secure and private person-to-person and machine-to-machine communication without a central authority. It supports various use cases, including but not limited to: + +### Chat Messengers + +Waku can be used as the communication layer when building a private, decentralized, and censorship-resistant messenger. + +#### Demos + +- [Status Web](https://github.com/status-im/status-web) + +### Polls + +With Waku, you can create, answer, and view censorship-resistant polls, fostering a democratic and transparent voting environment immune to manipulation and censorship. + +#### Demos + +- [Waku Connect Poll SDK](https://github.com/status-im/wakuconnect-vote-poll-sdk) + +### NFT Marketplaces + +Waku can be used to take NFT bids and offers off-chain, enabling gas savings. Additionally, it allows for adding a social media layer, enabling NFT owners to like, comment, and perform other social actions. + +#### Demos + +- [SmolPuddle Marketplace](https://github.com/Agusx1211/smolpuddle-web) + +### State Channels + +Waku can enable two parties to establish and sustain a state channel effortlessly, facilitating message exchange and seamless updates to their shared agreement without direct blockchain involvement. + +### Voting and Proposals + +To save on gas fees, votes for proposals submitted on the blockchain can be exchanged over Waku. These votes can then be aggregated and submitted to the blockchain to commit the result. + +#### Demos + +- [Waku Connect Poll SDK](https://github.com/status-im/wakuconnect-vote-poll-sdk) + +### Signature Exchange for Multi-Signature Wallets + +Waku can enable multiple owners of a given multi-signature wallet to exchange signatures in a decentralized, private, and censorship-resistant manner, allowing for the approval of transactions. + +### Game Mechanics Communication + +Waku can be used as the communication layer for a peer-to-peer, decentralized game, eliminating the need for a centralized infrastructure for gameplay communications. + +#### Demos + +- [Super Card Game](https://github.com/fjij/ethonline-2021) + +### dApp to Wallet Communication + +dApp operators can use communication between a user's wallet and their dApp to notify users (e.g., governance token holders can be notified to vote on a proposal) or to request transaction signatures from the wallet. + +#### Demos + +- [WalletConnect 2.0](https://walletconnect.com/) +- [HashPack](https://www.hashpack.app/hashconnect) + +### Layer 2 Coordination (Open Market, Spam Protected Mempool) + +Waku can broadcast and aggregate Layer 2 transactions to enhance privacy, anonymity, and resilience. Aggregating transactions reduces network load and improves scalability, ensuring a more robust Layer 2 ecosystem. + +### Generalized Marketplaces + +Waku can enable users to offer, bid, accept, and trade goods and services, making it possible to create ride-sharing or trading apps. + +#### Demos + +- [Waku-Uber](https://github.com/TheBojda/waku-uber) + +### Social Media Platforms + +While chat messengers are a type of social media that can be decentralized and made censorship-resistant through Waku, other forms of social media, such as news feeds, blog posts, and audio or video sharing, can also benefit from using Waku. diff --git a/packages/docusaurus-playground/docs/getting-started/why-waku.md b/packages/docusaurus-playground/docs/getting-started/why-waku.md new file mode 100644 index 0000000..03b949f --- /dev/null +++ b/packages/docusaurus-playground/docs/getting-started/why-waku.md @@ -0,0 +1,24 @@ +--- +title: Why Waku? +--- + +Communication in the present day is heavily influenced by third-party intervention, ranging from censorship and deplatforming to intermediaries that seek to profit from rent and the misuse of data in the surveillance economy. + +Waku is intended to empower individuals by returning control of communication to them. It is the go-to standard for Web3 communication, offering a scalable decentralized communication solution. + +- Waku improves upon Whisper's capabilities by overcoming limitations and addressing functional gaps. +- It provides a public infrastructure for the Ethereum and multi-chain ecosystem, serving as a common good. +- It is not confined to a particular blockchain. +- It is modular, adaptable, and can cater to various use cases. +- It allows developers to decentralize communication in their dApps or move actions off-chain while maintaining decentralization. +- It can run on various platforms, including mobile devices, cloud environments, web browsers, desktop apps, or even a [Dappnode](https://dappnode.com/)! + +## Why Waku is Necessary + +| | Whisper | Waku | +| -------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Scalability** | Whisper doesn't scale very well, specifically when it comes to bandwidth usage on mobile devices. | Uses GossipSub and Content Topics. | +| **Spam Resistance** | Proof of work requires too much battery and compute power making it a poor mechanism for heterogeneous nodes. | Uses innovative p2p economic spam protection mechanism RLN Relay. | +| **Incentivization Infrastructure** | There is no incentive to run a Whisper node. | Research in progress to design incentivization for node operators. | +| **Formal Specification/Documentation** | Lack of formal and unambiguous specification. | The specs and docs are open-source and licensed under CC0, making them freely available for anyone to read, modify and improve without restrictions. | +| **Portability** | Runs over devp2p which limits where Whisper can run and how. | Waku is built using libp2p, making it easy to run Waku anywhere. | diff --git a/packages/docusaurus-playground/docs/guides/sdks-and-nodes.md b/packages/docusaurus-playground/docs/guides/sdks-and-nodes.md new file mode 100644 index 0000000..ba98a1c --- /dev/null +++ b/packages/docusaurus-playground/docs/guides/sdks-and-nodes.md @@ -0,0 +1,42 @@ +--- +title: SDKs and Nodes +--- + +:::caution +Waku has risks and limitations as it is still developing and preparing for extensive adoption. However, it is already demonstrating its capabilities by [powering various applications](/powered-by-waku). [Join our community](/community) to stay updated on our progress. +::: + +Ready to integrate Waku into your application for private, secure, censorship-free communication? Explore the available SDKs and contribute by operating a node. + +## Operate a Waku Node + +The Waku network is permissionless and decentralized, consisting of nodes. It is open for anyone to run a node, use the network, and contribute to its support. Please visit the [nwaku guide](https://github.com/waku-org/nwaku/tree/master/docs/operators) (recommended) or [go-waku guide](https://github.com/waku-org/go-waku/tree/master/docs/operators) for operators to learn more. + +## Integrate Using SDKs + +Waku is implemented in multiple SDKs, allowing it to easily integrate with different languages and address various use cases. + +| SDK | Description | Documentation | +| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| [js-waku](https://github.com/waku-org/js-waku) | JavaScript/TypeScript SDK designed for browser environments | | +| [nwaku](https://github.com/waku-org/nwaku) | Nim SDK for running a standalone node and accessing the Waku network | | +| [go-waku](https://github.com/waku-org/go-waku) | Golang SDK designed for integration with Golang applications, includes C bindings for usage in C/C++, C#/Unity, Swift, and Kotlin | | +| [waku-rust-bindings](https://github.com/waku-org/waku-rust-bindings) | Rust wrapper using `go-waku` bindings designed for integration in Rust applications | | + +## Run on Mobile Devices + +Waku provides integrations tailored for mobile applications, enabling Waku to operate efficiently on mobile devices. + +| Language | Description | Documentation | +| ------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------- | +| [React Native](https://github.com/waku-org/waku-react-native) | React Native wrapper using `go-waku` bindings designed for native mobile integration | | +| Swift (iOS) | `go-waku` bindings for Swift applications to seamlessly integrate Waku | | +| Kotlin (Android) | `go-waku` bindings for Kotlin applications to seamlessly integrate Waku | | + +## More Integrations + +| Implementation | Description | Documentation | +| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | ------------- | +| [@waku/react](https://www.npmjs.com/package/@waku/react) | React components and UI adapters designed for seamless integration with `js-waku` | | +| [@waku/create-app](https://www.npmjs.com/package/@waku/create-app) | Starter kit to bootstrap your next `js-waku` project from various example templates | | +| JSON-RPC API | `JSON-RPC` API interface provided by `nwaku` and `go-waku` to access the Waku network | | diff --git a/packages/docusaurus-playground/docs/index.md b/packages/docusaurus-playground/docs/index.md deleted file mode 100644 index 1944abb..0000000 --- a/packages/docusaurus-playground/docs/index.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Introduction -sidebar_position: 1 ---- - -## Generate a new site - -Generate a new Docusaurus site using the **classic template**. - -The classic template will automatically be added to your project after you run the command: - -```bash -npm init docusaurus@latest my-website classic -``` - -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. - -The command also installs all necessary dependencies you need to run Docusaurus. - -```tsx title="docusaurus.config.js" -module.exports = { - // ... - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - sidebarPath: require.resolve('./sidebars.js'), - }, - theme: { - customCss: [require.resolve('./src/css/custom.css')], - }, - }, - ], - ], -} -``` - -```tsx -import React from 'react' -import useDocusaurusContext from '@docusaurus/useDocusaurusContext' - -const Hello = () => { - const { siteConfig } = useDocusaurusContext() - const { title, tagline } = siteConfig - - return
{`${title} · ${tagline}`}
-} -``` - -:::note - -The presets: **_ [['classic', {...}]] _** shorthand works as well. - -::: - -:::tip - -Some **content** with _Markdown_ `syntax`. Check [this `api`](#). - -::: - -:::info - -The presets: **_ [['classic', {...}]] _** shorthand works as well. - -::: - -:::caution - -Some **content** with _Markdown_ `syntax`. Check [this `api`](#). - -::: - -:::danger - -The presets: **_ [['classic', {...}]] _** shorthand works as well. - -::: - -## Start your site - -Run the development server: - -```bash -cd my-website -npm run start -``` - -The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. - -The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. - -Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. - -
CLICK ME - -#### yes, even hidden code blocks! - -
- -```python -print("hello world!") -``` - -
diff --git a/packages/docusaurus-playground/docs/powered-by-waku.mdx b/packages/docusaurus-playground/docs/powered-by-waku.mdx new file mode 100644 index 0000000..c6a49d7 --- /dev/null +++ b/packages/docusaurus-playground/docs/powered-by-waku.mdx @@ -0,0 +1,44 @@ +--- +title: Powered by Waku +--- + +Leap into the future with Waku! Revolutionize communication, collaboration, and connectivity. Join us and create something extraordinary! + +import { PoweredBy } from '@site/src/components/mdx' + + diff --git a/packages/docusaurus-playground/docs/presentations.md b/packages/docusaurus-playground/docs/presentations.md new file mode 100644 index 0000000..75d1712 --- /dev/null +++ b/packages/docusaurus-playground/docs/presentations.md @@ -0,0 +1,39 @@ +--- +title: Watch Our Presentations +--- + +## Using ZKP for Better p2p Messaging With Waku + + + +## How to Ethically Build Public Good Infrastructure + + + +## Building Privacy-Protecting Infrastructure + + + +## Secureum TrustX - Waku: Enabling a New Dimension for dApps + + + +## Waku: Enabling a New Dimension for dApps + + + +## The Next Level of Decentralization Messaging in Web3 + + + +## Build with Waku & DappConnect + + + +## DappConnect: Enabling Decentralized Communications Using Waku + + + +## DappConnect: Decentralized Communication Using Waku + + diff --git a/packages/docusaurus-playground/docs/test.mdx b/packages/docusaurus-playground/docs/test.mdx deleted file mode 100644 index ca6a720..0000000 --- a/packages/docusaurus-playground/docs/test.mdx +++ /dev/null @@ -1,40 +0,0 @@ -import { PoweredBy } from '../src/components/mdx' - -test - - diff --git a/packages/docusaurus-playground/docusaurus.config.js b/packages/docusaurus-playground/docusaurus.config.js index 4a801e5..8608068 100644 --- a/packages/docusaurus-playground/docusaurus.config.js +++ b/packages/docusaurus-playground/docusaurus.config.js @@ -2,16 +2,13 @@ // Note: type annotations allow type checking and IDEs autocompletion require('dotenv').config() -/** @type {import('@docusaurus/types').Config} */ +/** @type {import("@docusaurus/types").Config} */ const config = { - title: 'TITLE', - url: 'https://url', + title: 'Waku Docs Portal', + url: 'https://waku.guide/', baseUrl: '/', - - customFields: {}, - markdown: { - mermaid: true, - }, + onBrokenLinks: 'throw', + onBrokenMarkdownLinks: 'warn', // Even if you don't use internalization, you can use this field to set useful // metadata like html lang. For example, if your site is Chinese, you may want @@ -20,116 +17,162 @@ const config = { defaultLocale: 'en', locales: ['en'], }, - presets: [ [ '@acid-info/logos-docusaurus-preset', - /** @type {import('@acid-info/logos-docusaurus-preset').PluginOptions} */ - ({ - businessUnit: 'Nomos', + { + businessUnit: 'Waku', + customSiteConfig: true, + docs: { + routeBasePath: '/', + sidebarPath: require.resolve('./sidebars.js'), + editUrl: 'https://github.com/waku-org/waku.guide/tree/develop/', + }, theme: { name: 'default', options: { customCss: [require.resolve('./src/css/custom.scss')], - docs: { - default: { - sidebar: { - hide: false, - }, - }, - }, }, }, - docs: { - routeBasePath: '/about', - versions: { - current: { - label: 'current', - }, - }, - lastVersion: 'current', - }, - }), + }, ], ], + staticDirectories: ['static'], + themeConfig: { + docs: { + sidebar: { + hideable: false, + }, + }, + navbar: { + hideOnScroll: true, + items: [ + { + type: 'search', + }, + { + type: 'docSidebar', + position: 'left', + sidebarId: 'main', + label: 'Getting Started', + }, + { + type: 'dropdown', + label: 'Guides', + position: 'right', + items: [ + { + label: 'SDKs and Nodes', + to: '/guides/sdks-and-nodes', + }, + ], + }, + { + to: '/powered-by-waku', + label: 'Powered by Waku', + position: 'left', + }, + { + type: 'dropdown', + label: 'Community', + position: 'right', + items: [ + { + label: 'Join Our Community', + to: '/community', + }, + { + label: 'Contribute to Waku', + to: '/contribute', + }, + { + label: 'Watch Our Presentations', + to: '/presentations', + }, + ], + }, + { + href: 'https://github.com/waku-org', + position: 'right', + className: 'header-github-link', + title: 'Waku GitHub repository', + }, + ], + }, + footer: { + links: [ + { + title: 'Guides', + items: [ + { + to: '/guides/sdks-and-nodes', + label: 'SDKs and Nodes', + }, + ], + }, + { + title: 'Community', + items: [ + { + href: 'https://discord.waku.org/', + label: 'Discord', + }, + { + href: 'https://twitter.com/waku_org', + label: 'Twitter', + }, + { + href: 'https://t.me/waku_org', + label: 'Telegram', + }, + { + href: 'https://forum.vac.dev/', + label: 'Vac Forum', + }, + ], + }, + { + title: 'Resources', + items: [ + { + href: 'https://github.com/waku-org', + label: 'GitHub', + }, + { + href: 'https://vac.dev/research', + label: 'Blog', + }, + { + href: 'https://rfc.vac.dev/', + label: 'Vac RFCs', + }, + ], + }, + { + title: 'Legal', + items: [ + { + href: 'https://waku.org/terms-of-use', + label: 'Terms of Use', + }, + { + href: 'https://waku.org/privacy-policy', + label: 'Privacy Policy', + }, + ], + }, + ], + }, + // colorMode: { + // defaultMode: "dark", + // disableSwitch: false, + // respectPrefersColorScheme: false + // } + }, themes: ['@docusaurus/theme-mermaid'], - - themeConfig: - /** @type {import('@acid-info/logos-docusaurus-preset').ThemeConfig} */ - ({ - navbar: { - items: [ - { - type: 'search', - }, - { - label: 'About', - to: '/about', - }, - { - label: 'Features', - href: '/#features', - }, - { - label: 'Usecases', - href: '/#usecases', - }, - { - label: 'Github', - href: 'https://github.com/status-im', - }, - { - type: 'localeDropdown', - position: 'right', - }, - ], - }, - footer: { - copyright: 'Nimbus @2023
All Rights Reserved.', - links: [ - { - items: [ - { - href: 'https://twitter.com/ethnimbus', - label: 'Twitter', - }, - { - href: 'https://discord.gg/EP8DZnXu9y', - label: 'Discord', - }, - { - href: '/', - label: 'Docs', - }, - { - href: '/', - label: 'Github', - }, - ], - }, - { - items: [ - { - href: '/', - label: 'Contact us', - }, - { - href: 'https://jobs.status.im/', - label: 'Work with us', - }, - { - href: '/', - label: 'Privacy policy', - }, - { - href: '/', - label: 'Terms & conditions', - }, - ], - }, - ], - }, - }), + markdown: { + mermaid: true, + }, } module.exports = config diff --git a/packages/docusaurus-playground/sidebars.js b/packages/docusaurus-playground/sidebars.js new file mode 100644 index 0000000..d953b7f --- /dev/null +++ b/packages/docusaurus-playground/sidebars.js @@ -0,0 +1,50 @@ +// @ts-check + +/** @type {import("@docusaurus/plugin-content-docs").SidebarsConfig} */ +const sidebars = { + main: [ + 'getting-started/index', + 'getting-started/history', + 'getting-started/why-waku', + 'getting-started/use-cases', + { + type: 'html', + value: + 'SDKs and Nodes', + }, + { + type: 'html', + value: + 'Presentations', + }, + { + type: 'category', + label: 'Concepts', + collapsed: false, + collapsible: true, + items: [ + 'getting-started/concepts/protocols', + 'getting-started/concepts/content-topics', + 'getting-started/concepts/network-domains', + 'getting-started/concepts/peer-discovery', + 'getting-started/concepts/transports', + ], + }, + { + type: 'category', + label: 'Reference', + collapsed: false, + collapsible: true, + items: [ + 'getting-started/reference/glossary', + 'getting-started/reference/security-features', + 'getting-started/reference/research-in-progress', + 'getting-started/reference/waku-vs-libp2p', + ], + }, + ], + guides: ['guides/sdks-and-nodes'], + community: ['powered-by-waku', 'community', 'contribute', 'presentations'], +} + +module.exports = sidebars diff --git a/packages/docusaurus-playground/src/components/PoweredByCard.js b/packages/docusaurus-playground/src/components/PoweredByCard.js new file mode 100644 index 0000000..9d0efa4 --- /dev/null +++ b/packages/docusaurus-playground/src/components/PoweredByCard.js @@ -0,0 +1,57 @@ +import React from 'react' + +const PoweredByCard = ({ appLink, logoSrc, appName, children }) => ( + +) + +export default PoweredByCard diff --git a/packages/docusaurus-playground/src/pages/index.mdx b/packages/docusaurus-playground/src/pages/index.mdx deleted file mode 100644 index f3862a3..0000000 --- a/packages/docusaurus-playground/src/pages/index.mdx +++ /dev/null @@ -1,154 +0,0 @@ -import { - Hero, - HeroTitle, - HeroDescription, - HeroActions, - HeroAction, - CallToActionSection, - CallToActionButton, - FeatureList, - Showcase, - HeroModel, - HeroInfo, - Box, -} from '../components/mdx' - - - - - THE STANDARD
- FOR WEB3 COMMUNICATIONS - - {/* - - Waku is a decentralized communications network that enables private, censorship-resistant messaging for web3 - applications. - - * */} - - Waku is a decentralized communications network, built for generalized - private and censorship-resistant messaging, supporting resource-restricted - environments like phones and browsers - - - - Learn more - - - Run Waku - - - - - - - - - Decentralize your DApp - - - - - - - - - - - - - - - - - - - - - - diff --git a/packages/docusaurus-playground/versioned_docs/version-1.1.0/Advanced/pages/pages.md b/packages/docusaurus-playground/versioned_docs/version-1.1.0/Advanced/pages/pages.md deleted file mode 100644 index ac58641..0000000 --- a/packages/docusaurus-playground/versioned_docs/version-1.1.0/Advanced/pages/pages.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Pages -sidebar_position: 4 ---- - -## Hello World - -```python -print("hello world!") -``` diff --git a/packages/docusaurus-playground/versioned_docs/version-1.1.0/configuration.md b/packages/docusaurus-playground/versioned_docs/version-1.1.0/configuration.md deleted file mode 100644 index d4ccc38..0000000 --- a/packages/docusaurus-playground/versioned_docs/version-1.1.0/configuration.md +++ /dev/null @@ -1,264 +0,0 @@ ---- -title: Configuration -sidebar_position: 2 ---- - -# Configuration - -import TOCInline from '@theme/TOCInline'; - -:::info - -Check the [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.mdx) for an exhaustive list of options. - -::: - -Docusaurus has a unique take on configurations. We encourage you to congregate information about your site into one place. We guard the fields of this file and facilitate making this data object accessible across your site. - -Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors to be able to focus on documentation while still being able to customize the site. - -## Syntax to declare `docusaurus.config.js` {#syntax-to-declare-docusaurus-config} - -The `docusaurus.config.js` file is run in Node.js and should export either: - -- a **config object** -- a **function** that creates the config object - -:::info - -The `docusaurus.config.js` file only supports the [**CommonJS**](https://flaviocopes.com/commonjs/) module system: - -- **Required:** use `module.exports = /* your config*/` to export your Docusaurus config -- **Optional:** use `require("lib")` to import Node.js packages -- **Optional:** use `await import("lib")` (dynamic import) in an async function to import ESM-Only Node.js packages - -::: - -Node.js gives us the ability to declare our Docusaurus configuration in various **equivalent ways**, and all the following config examples lead to the exact same result: - -```js title="docusaurus.config.js" -module.exports = { - title: 'Docusaurus', - url: 'https://docusaurus.io', - // your site config ... -} -``` - -```js title="docusaurus.config.js" -const config = { - title: 'Docusaurus', - url: 'https://docusaurus.io', - // your site config ... -} - -module.exports = config -``` - -```js title="docusaurus.config.js" -module.exports = function configCreator() { - return { - title: 'Docusaurus', - url: 'https://docusaurus.io', - // your site config ... - } -} -``` - -```js title="docusaurus.config.js" -module.exports = async function createConfigAsync() { - return { - title: 'Docusaurus', - url: 'https://docusaurus.io', - // your site config ... - } -} -``` - -:::tip Using ESM-only packages - -Using an async config creator can be useful to import ESM-only modules (notably most Remark plugins). It is possible to import such modules thanks to dynamic imports: - -```js title="docusaurus.config.js" -module.exports = async function createConfigAsync() { - // Use a dynamic import instead of require('esm-lib') - // highlight-next-line - const lib = await import('lib') - - return { - title: 'Docusaurus', - url: 'https://docusaurus.io', - // rest of your site config... - } -} -``` - -::: - -## What goes into a `docusaurus.config.js`? {#what-goes-into-a-docusaurusconfigjs} - -You should not have to write your `docusaurus.config.js` from scratch even if you are developing your site. All templates come with a `docusaurus.config.js` that includes defaults for the common options. - -However, it can be helpful if you have a high-level understanding of how the configurations are designed and implemented. - -The high-level overview of Docusaurus configuration can be categorized into: - - - -### Site metadata {#site-metadata} - -Site metadata contains the essential global metadata such as `title`, `url`, `baseUrl`, and `favicon`. - -They are used in several places such as your site's title and headings, browser tab icon, social sharing (Facebook, Twitter) information or even to generate the correct path to serve your static files. - -### Deployment configurations {#deployment-configurations} - -Deployment configurations such as `projectName`, `organizationName`, and optionally `deploymentBranch` are used when you deploy your site with the `deploy` command. - -It is recommended to check the [deployment docs](deployment.mdx) for more information. - -### Theme, plugin, and preset configurations {#theme-plugin-and-preset-configurations} - -List the [themes](./using-plugins.mdx#using-themes), [plugins](./using-plugins.mdx), and [presets](./using-plugins.mdx#using-presets) for your site in the `themes`, `plugins`, and `presets` fields, respectively. These are typically npm packages: - -```js title="docusaurus.config.js" -module.exports = { - // ... - plugins: [ - '@docusaurus/plugin-content-blog', - '@docusaurus/plugin-content-pages', - ], - themes: ['@docusaurus/theme-classic'], -} -``` - -:::tip - -Docusaurus supports [**module shorthands**](./using-plugins.mdx#module-shorthands), allowing you to simplify the above configuration as: - -```js title="docusaurus.config.js" -module.exports = { - // ... - plugins: ['content-blog', 'content-pages'], - themes: ['classic'], -} -``` - -::: - -They can also be loaded from local directories: - -```js title="docusaurus.config.js" -const path = require('path') - -module.exports = { - // ... - themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')], -} -``` - -To specify options for a plugin or theme, replace the name of the plugin or theme in the config file with an array containing the name and an options object: - -```js title="docusaurus.config.js" -module.exports = { - // ... - plugins: [ - [ - 'content-blog', - { - path: 'blog', - routeBasePath: 'blog', - include: ['*.md', '*.mdx'], - // ... - }, - ], - 'content-pages', - ], -} -``` - -To specify options for a plugin or theme that is bundled in a preset, pass the options through the `presets` field. In this example, `docs` refers to `@docusaurus/plugin-content-docs` and `theme` refers to `@docusaurus/theme-classic`. - -```js title="docusaurus.config.js" -module.exports = { - // ... - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - sidebarPath: require.resolve('./sidebars.js'), - }, - theme: { - customCss: [require.resolve('./src/css/custom.css')], - }, - }, - ], - ], -} -``` - -:::tip - -The `presets: [['classic', {...}]]` shorthand works as well. - -::: - -For further help configuring themes, plugins, and presets, see [Using Plugins](./using-plugins.mdx). - -### Custom configurations {#custom-configurations} - -Docusaurus guards `docusaurus.config.js` from unknown fields. To add custom fields, define them in `customFields`. - -Example: - -```js title="docusaurus.config.js" -module.exports = { - // ... - // highlight-start - customFields: { - image: '', - keywords: [], - }, - // highlight-end - // ... -} -``` - -## Accessing configuration from components {#accessing-configuration-from-components} - -Your configuration object will be made available to all the components of your site. And you may access them via React context as `siteConfig`. - -Basic example: - -```jsx -import React from 'react' -// highlight-next-line -import useDocusaurusContext from '@docusaurus/useDocusaurusContext' - -const Hello = () => { - // highlight-start - const { siteConfig } = useDocusaurusContext() - // highlight-end - const { title, tagline } = siteConfig - - return
{`${title} · ${tagline}`}
-} -``` - -:::tip - -If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in `docusaurus.config.js`. - -::: - -## Customizing Babel Configuration {#customizing-babel-configuration} - -For new Docusaurus projects, we automatically generated a `babel.config.js` in the project root. - -```js title="babel.config.js" -module.exports = { - presets: [require.resolve('@docusaurus/core/lib/babel/preset')], -} -``` - -Most of the time, this configuration will work just fine. If you want to customize your Babel configuration (e.g. to add support for Flow), you can directly edit this file. For your changes to take effect, you need to restart the Docusaurus dev server. diff --git a/packages/docusaurus-playground/versioned_docs/version-1.1.0/getting-started.md b/packages/docusaurus-playground/versioned_docs/version-1.1.0/getting-started.md deleted file mode 100644 index 72f67bf..0000000 --- a/packages/docusaurus-playground/versioned_docs/version-1.1.0/getting-started.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Getting Started -sidebar_position: 3 ---- - -# Tutorial Intro - -Let's discover **Docusaurus in less than 5 minutes**. - -```mermaid -graph TD; - A-->B; - A-->C; - B-->D; - C-->D; -``` - -## Getting Started - -Get started by **creating a new site**. - -Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. - -### What you'll need - -- [Node.js](https://nodejs.org/en/download/) version 16.14 or above: - - When installing Node.js, you are recommended to check all checkboxes related to dependencies. diff --git a/packages/docusaurus-playground/versioned_docs/version-1.1.0/index.md b/packages/docusaurus-playground/versioned_docs/version-1.1.0/index.md deleted file mode 100644 index 5a6d368..0000000 --- a/packages/docusaurus-playground/versioned_docs/version-1.1.0/index.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -id: version-1.1.0-Introduction -title: Introduction -sidebar_position: 1 ---- - -## Generate a new site - -Generate a new Docusaurus site using the **classic template**. - -The classic template will automatically be added to your project after you run the command: - -```bash -npm init docusaurus@latest my-website classic -``` - -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. - -The command also installs all necessary dependencies you need to run Docusaurus. - -```tsx title="docusaurus.config.js" -module.exports = { - // ... - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - sidebarPath: require.resolve('./sidebars.js'), - }, - theme: { - customCss: [require.resolve('./src/css/custom.css')], - }, - }, - ], - ], -} -``` - -```tsx -import React from 'react' -import useDocusaurusContext from '@docusaurus/useDocusaurusContext' - -const Hello = () => { - const { siteConfig } = useDocusaurusContext() - const { title, tagline } = siteConfig - - return
{`${title} · ${tagline}`}
-} -``` - -:::note - -The presets: **_ [['classic', {...}]] _** shorthand works as well. - -::: - -:::tip - -Some **content** with _Markdown_ `syntax`. Check [this `api`](#). - -::: - -:::info - -The presets: **_ [['classic', {...}]] _** shorthand works as well. - -::: - -:::caution - -Some **content** with _Markdown_ `syntax`. Check [this `api`](#). - -::: - -:::danger - -The presets: **_ [['classic', {...}]] _** shorthand works as well. - -::: - -## Start your site - -Run the development server: - -```bash -cd my-website -npm run start -``` - -The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. - -The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. - -Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. - -
CLICK ME - -#### yes, even hidden code blocks! - -
- -```python -print("hello world!") -``` - -
diff --git a/packages/docusaurus-playground/versioned_sidebars/version-1.1.0-sidebars.json b/packages/docusaurus-playground/versioned_sidebars/version-1.1.0-sidebars.json deleted file mode 100644 index cff0c94..0000000 --- a/packages/docusaurus-playground/versioned_sidebars/version-1.1.0-sidebars.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "defaultSidebar": [ - { - "type": "autogenerated", - "dirName": "." - } - ] -} diff --git a/packages/docusaurus-playground/versions.json b/packages/docusaurus-playground/versions.json deleted file mode 100644 index 6c0c4be..0000000 --- a/packages/docusaurus-playground/versions.json +++ /dev/null @@ -1 +0,0 @@ -["1.1.0"] diff --git a/packages/logos-docusaurus-theme/src/client/components/Icon/Icon.tsx b/packages/logos-docusaurus-theme/src/client/components/Icon/Icon.tsx index 6636a7c..3f703f7 100644 --- a/packages/logos-docusaurus-theme/src/client/components/Icon/Icon.tsx +++ b/packages/logos-docusaurus-theme/src/client/components/Icon/Icon.tsx @@ -23,6 +23,7 @@ import SearchSvg from '../../static/icons/search.svg' import StatusSvg from '../../static/icons/status.svg' import TelegramSvg from '../../static/icons/telegram.svg' import TwitterSvg from '../../static/icons/twitter.svg' +import EditSvg from '../../static/icons/edit.svg' type TIconProps = { size?: 's' | 'm' | 'l' @@ -171,3 +172,9 @@ export const IconClose = (props: TIconProps): JSX.Element => ( ) + +export const IconEdit = (props: TIconProps): JSX.Element => ( + + + +) diff --git a/packages/logos-docusaurus-theme/src/client/css/custom.scss b/packages/logos-docusaurus-theme/src/client/css/custom.scss index e86532a..665ad83 100644 --- a/packages/logos-docusaurus-theme/src/client/css/custom.scss +++ b/packages/logos-docusaurus-theme/src/client/css/custom.scss @@ -86,12 +86,12 @@ --ifm-font-weight-bold: 600; --ifm-font-weight-base: var(--ifm-font-weight-normal); - --ifm-h1-font-size: 4rem; - --ifm-h2-font-size: 2rem; - --ifm-h3-font-size: 1.25rem; - --ifm-h4-font-size: 1.15rem; - --ifm-h5-font-size: 1rem; - --ifm-h6-font-size: 0.85rem; + --ifm-h1-font-size: var(--lsd-h1-fontSize); + --ifm-h2-font-size: var(--lsd-h2-fontSize); + --ifm-h3-font-size: var(--lsd-h3-fontSize); + --ifm-h4-font-size: var(--lsd-h4-fontSize); + --ifm-h5-font-size: var(--lsd-h5-fontSize); + --ifm-h6-font-size: var(--lsd-h6-fontSize); /* Spacing. */ --ifm-global-spacing: 0.67rem; @@ -283,7 +283,24 @@ svg * { color: rgb(var(--lsd-text-secondary)) !important; } +h1 { + @include lsd.typography('h1'); +} + +h2 { + @include lsd.typography('h2'); +} + +h3 { + @include lsd.typography('h3'); +} + +h4 { + @include lsd.typography('h4'); +} + code { + @include lsd.typography('body1'); color: rgb(var(--lsd-text-primary)); border-radius: 0; background: rgba(255, 255, 255, 0.15); @@ -374,6 +391,16 @@ small { align-items: center; } +.theme-edit-this-page { + display: flex; + align-items: center; + gap: 12px; +} + +.external-link { + @include lsd.typography('body2'); +} + .dropdown__link:hover { color: rgb(var(--lsd-text-secondary)); } @@ -449,6 +476,10 @@ small { .menu__list-item-collapsible > a { border: none !important; + + span { + color: rgb(var(--lsd-text-primary), 0.6); + } } .table-of-contents__link--active code { @@ -777,6 +808,7 @@ a[class^='sidebarLogo_'] { text-align: unset; grid-column: 1 / 12; grid-row: 1 / 1; + @include lsd.typography('body2'); & > div:first-of-type { display: none; diff --git a/packages/logos-docusaurus-theme/src/client/static/icons/edit.svg b/packages/logos-docusaurus-theme/src/client/static/icons/edit.svg new file mode 100644 index 0000000..b444489 --- /dev/null +++ b/packages/logos-docusaurus-theme/src/client/static/icons/edit.svg @@ -0,0 +1,3 @@ + + + diff --git a/packages/logos-docusaurus-theme/src/client/theme/EditThisPage/index.tsx b/packages/logos-docusaurus-theme/src/client/theme/EditThisPage/index.tsx new file mode 100644 index 0000000..af7e89b --- /dev/null +++ b/packages/logos-docusaurus-theme/src/client/theme/EditThisPage/index.tsx @@ -0,0 +1,26 @@ +import React from 'react' +import Translate from '@docusaurus/Translate' +import { ThemeClassNames } from '@docusaurus/theme-common' +import { IconEdit } from '@logos-theme/components/Icon' +import { Typography } from '@acid-info/lsd-react' + +export default function EditThisPage({ editUrl }) { + return ( + + + + + Edit this page + + + + ) +}