diff --git a/README.md b/README.md index 855b0ff3a4..41555f90a2 100644 --- a/README.md +++ b/README.md @@ -9,312 +9,38 @@ A JavaScript implementation of the [Waku v2 protocol](https://rfc.vac.dev/spec/1 ## Documentation -In the [section below](#usage) you can find explanations for the main API. +- [Quick start](https://docs.dappconnect.dev/docs/quick_start/) +- [Full documentation](https://docs.dappconnect.dev/) +- [API documentation (`main` branch)](https://status-im.github.io/js-waku/docs/) -We also have [guides](https://github.com/status-im/js-waku/blob/main/guides/menu.md) available -and [code examples](https://github.com/status-im/js-waku/blob/main/examples/examples.md). - -You can read the latest `main` branch documentation at [https://status-im.github.io/js-waku/docs/](https://status-im.github.io/js-waku/docs/). - -Docs can also be generated locally using: +API Documentation can also be generated locally: ```shell +git clone https://github.com/status-im/js-waku.git +cd js-waku npm install npm run doc ``` - -## Usage - -Install `js-waku` package: - -```shell -npm install js-waku -``` - -### Import js-waku - -To use js-waku in your application, you can: - -use `import`: - -```js -import { Waku } from 'js-waku'; - -const waku = await Waku.create(); -``` - -use `require`: - -```js -const jsWaku = require('js-waku'); - -jsWaku.Waku.create().then(waku => { - // ... -}); -``` - -Or directly import it in a ` - -``` - -### Start a waku node - -```ts -const waku = await Waku.create({ bootstrap: true }); -``` - -### Listen for messages - -The `contentTopic` is a metadata `string` that allows categorization of messages on the waku network. -Depending on your use case, you can either create one (or several) new `contentTopic`(s) or look at the [RFCs](https://rfc.vac.dev/) and use an existing `contentTopic`. -See [How to Choose a Content Topic](./guides/choose-content-topic.md) for more details. - -For example, if you were to use a new `contentTopic` such as `/my-cool-app/1/my-use-case/proto`, -here is how to listen to new messages received via [Waku v2 Relay](https://rfc.vac.dev/spec/11/): - -```ts -waku.relay.addObserver((msg) => { - console.log("Message received:", msg.payloadAsUtf8) -}, ["/my-cool-app/1/my-use-case/proto"]); -``` - -The examples chat apps currently use content topic `"/toy-chat/2/huilong/proto"`. - -### Send messages - -There are two ways to send messages: - -#### Waku Relay - -[Waku Relay](https://rfc.vac.dev/spec/11/) is the most decentralized option, -peer receiving your messages are unlikely to know whether you are the originator or simply forwarding them. -However, it does not give you any delivery information. - -```ts -import { WakuMessage } from 'js-waku'; - -const msg = await WakuMessage.fromUtf8String("Here is a message!", "/my-cool-app/1/my-use-case/proto") -await waku.relay.send(msg); -``` - -#### Waku Light Push - -[Waku Light Push](https://rfc.vac.dev/spec/19/) gives you confirmation that the light push server node has -received your message. -However, it means that said node knows you are the originator of the message. -It cannot guarantee that the node will forward the message. - -```ts -const ack = await waku.lightPush.push(message); -if (!ack?.isSuccess) { - // Message was not sent -} -``` - -### Retrieve archived messages - -The [Waku v2 Store protocol](https://rfc.vac.dev/spec/13/) enables more permanent nodes to store messages received via relay -and ephemeral clients to retrieve them (e.g. mobile phone resuming connectivity). -The protocol implements pagination meaning that it may take several queries to retrieve all messages. - -Query a waku store peer to check historical messages: - -```ts -// Process messages once they are all retrieved -const messages = await waku.store.queryHistory(['/my-cool-app/1/my-use-case/proto']); -messages.forEach((msg) => { - console.log('Message retrieved:', msg.payloadAsUtf8); -}); - -// Or, pass a callback function to be executed as pages are received: -waku.store.queryHistory(['/my-cool-app/1/my-use-case/proto'], { - callback: (messages) => { - messages.forEach((msg) => { - console.log('Message retrieved:', msg.payloadAsUtf8); - }); - } -}); -``` - -### Encryption & Signature - -With js-waku, you can: - -- Encrypt messages over the wire using public/private key pair (asymmetric encryption), -- Encrypt messages over the wire using a unique key to both encrypt and decrypt (symmetric encryption), -- Sign and verify your waku messages (must use encryption, compatible with both symmetric and asymmetric). - -#### Cryptographic Libraries - -A quick note on the cryptographic libraries used as it is a not a straightforward affair: -- Asymmetric encryption: - Uses [ecies-geth](https://github.com/cyrildever/ecies-geth/) - which in turns uses [SubtleCrypto](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto) Web API (browser), - [secp256k1](https://www.npmjs.com/package/secp256k1) (native binding for node) - or [elliptic](https://www.npmjs.com/package/elliptic) (pure JS if none of the other libraries are available). -- Symmetric encryption: - Uses [SubtleCrypto](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto) Web API (browser) - or [NodeJS' crypto](https://nodejs.org/api/crypto.html) module. - -### Create new keys - -Asymmetric private keys and symmetric keys are expected to be 32 bytes arrays. - -```ts -import { generatePrivateKey, generateSymmetricKey, getPublicKey } from 'js-waku'; - -// Asymmetric -const privateKey = generatePrivateKey(); -const publicKey = getPublicKey(privateKey); - -// Symmetric -const symKey = generateSymmetricKey(); -``` - -#### Encrypt Waku Messages - -To encrypt your waku messages, simply pass the encryption key when creating it: - -```ts -import { WakuMessage } from "js-waku"; - -// Asymmetric -const message1 = await WakuMessage.fromBytes(payload, myAppContentTopic, { - encPublicKey: publicKey, -}); - -// Symmetric -const message2 = await WakuMessage.fromBytes(payload, myAppContentTopic, { - symKey: symKey, -}); - -``` - -#### Decrypt Waku Messages - -##### Waku Relay - -If you expect to receive encrypted messages then simply add private decryption key(s) to `WakuRelay`. -Waku Relay will attempt to decrypt incoming messages with each keys, both for symmetric and asymmetric encryption. -Messages that are successfully decrypted (or received in clear) will be passed to the observers, other messages will be omitted. - -```ts -// Asymmetric -waku.relay.addDecryptionKey(privateKey); - -// Symmetric -waku.relay.addDecryptionKey(symKey); - -// Then add the observer -waku.relay.addObserver(callback, [contentTopic]); -``` - -Keys can be removed using `WakuMessage.deleteDecryptionKey`. - -##### Waku Store - -```ts -const messages = await waku.store.queryHistory([], { - decryptionKeys: [privateKey, symKey] -}); -``` - -Similarly to relay, only decrypted or clear messages will be returned. - -#### Sign Waku Messages - -As per version 1`s [specs](https://rfc.vac.dev/spec/26/), signatures are only included in encrypted messages. -In the case where your app does not need encryption then you could use symmetric encryption with a trivial key, I intend to dig [more on the subject](https://github.com/status-im/js-waku/issues/74#issuecomment-880440186) and come back with recommendation and examples. - -Signature keys can be generated the same way asymmetric keys for encryption are: - -```ts -import { generatePrivateKey, getPublicKey, WakuMessage } from 'js-waku'; - -const signPrivateKey = generatePrivateKey(); - -// Asymmetric Encryption -const message1 = await WakuMessage.fromBytes(payload, myAppContentTopic, { - encPublicKey: recipientPublicKey, - sigPrivKey: signPrivateKey -}); - -// Symmetric Encryption -const message2 = await WakuMessage.fromBytes(payload, myAppContentTopic, { - encPublicKey: symKey, - sigPrivKey: signPrivateKey -}); - -``` - -#### Verify Waku Message signatures - -Two fields are available on `WakuMessage` regarding signatures: - -- `signaturePublicKey`: If the message is signed, it holds the public key of the signature, -- `signature`: If the message is signed, it holds the actual signature. - -Thus, if you expect messages to be signed by Alice, -you can simply compare `WakuMessage.signaturePublicKey` with Alice's public key. -As comparing hex string can lead to issues (is the `0x` prefix present?), -simply use helper function `equalByteArrays`. - -```ts -import { equalByteArrays } from 'js-waku/lib/utils'; - -const sigPubKey = wakuMessage.signaturePublicKey; - -const isSignedByAlice = sigPubKey && equalByteArrays(sigPubKey, alicePublicKey); -``` - ## Changelog -Release changelog can be found [here](https://github.com/status-im/js-waku/blob/main/CHANGELOG.md). +Release changelog can be found in [CHANGELOG.md](https://github.com/status-im/js-waku/blob/main/CHANGELOG.md). ## Bugs, Questions & Features If you encounter any bug or would like to propose new features, feel free to [open an issue](https://github.com/status-im/js-waku/issues/new/). -To get help, join #dappconnect-support on [Vac Discord](https://discord.gg/j5pGbn7MHZ) or [Telegram](https://t.me/dappconnectsupport). +To get help, join **#dappconnect-support** on [Vac Discord](https://discord.gg/j5pGbn7MHZ) or [Telegram](https://t.me/dappconnectsupport). -For more general discussion and latest news, join #dappconnect on [Vac Discord](https://discord.gg/9DgykdmpZ6) or [Telegram](https://t.me/dappconnect). +For more general discussion and latest news, join **#dappconnect** on [Vac Discord](https://discord.gg/9DgykdmpZ6) or [Telegram](https://t.me/dappconnect). -## Waku Protocol Support +## Roadmap You can track progress on the [project board](https://github.com/status-im/js-waku/projects/1). -- ✔: Supported -- 🚧: Implementation in progress -- ⛔: Support is not planned - -| Spec | Implementation Status | -| ---- | -------------- | -|[6/WAKU1](https://rfc.vac.dev/spec/6)|⛔| -|[7/WAKU-DATA](https://rfc.vac.dev/spec/7)|⛔| -|[8/WAKU-MAIL](https://rfc.vac.dev/spec/8)|⛔| -|[9/WAKU-RPC](https://rfc.vac.dev/spec/9)|⛔| -|[10/WAKU2](https://rfc.vac.dev/spec/10)|🚧| -|[11/WAKU2-RELAY](https://rfc.vac.dev/spec/11)|✔| -|[12/WAKU2-FILTER](https://rfc.vac.dev/spec/12)|| -|[13/WAKU2-STORE](https://rfc.vac.dev/spec/13)|✔ (querying node only)| -|[14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14)|✔| -|[15/WAKU2-BRIDGE](https://rfc.vac.dev/spec/15)|| -|[16/WAKU2-RPC](https://rfc.vac.dev/spec/16)|⛔| -|[17/WAKU2-RLNRELAY](https://rfc.vac.dev/spec/17)|| -|[18/WAKU2-SWAP](https://rfc.vac.dev/spec/18)|| -|[19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/)|✔| - ## Contributing -See [CONTRIBUTING.md](./CONTRIBUTING.md). +See [CONTRIBUTING.md](https://github.com/status-im/js-waku/blob/main/CONTRIBUTING.md). ## License Licensed and distributed under either of