doc: `createEncoder` and `createDecoder`

packages/core/src/lib/waku_message/version_0.ts

@@ -92,6 +92,18 @@ export class Encoder implements IEncoder {
   }
 }
 
+/**
+ * Creates an encoder that encode messages without Waku level encryption or signature.
+ *
+ * An encoder is used to encode messages in the [`14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/)
+ * format to be sent over the Waku network. The resulting encoder can then be
+ * pass to { @link @waku/interfaces.LightPush.push } or
+ * { @link @waku/interfaces.Relay.send } to automatically encode outgoing
+ * messages.
+ *
+ * @param contentTopic The content topic to set on outgoing messages.
+ * @param ephemeral An optional flag to mark message as ephemeral, ie, not to be stored by Waku Store nodes.
+ */
 export function createEncoder(
   contentTopic: string,
   ephemeral = false
@@ -135,6 +147,17 @@ export class Decoder implements IDecoder<DecodedMessage> {
   }
 }
 
+/**
+ * Creates an decoder that decode messages without Waku level encryption.
+ *
+ * A decoder is used to decode messages from the [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/)
+ * format when received from the Waku network. The resulting decoder can then be
+ * pass to { @link @waku/interfaces.Filter.subscribe } or
+ * { @link @waku/interfaces.Relay.subscribe } to automatically decode incoming
+ * messages.
+ *
+ * @param contentTopic The resulting decoder will only decode messages with this content topic.
+ */
 export function createDecoder(contentTopic: string): Decoder {
   return new Decoder(contentTopic);
 }

packages/message-encryption/src/ecies.ts

@@ -65,6 +65,24 @@ class Encoder implements IEncoder {
   }
 }
 
+/**
+ * Creates an encoder that encrypts messages using ECIES for the given public,
+ * as defined in [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26/).
+ *
+ * An encoder is used to encode messages in the [`14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/)
+ * format to be sent over the Waku network. The resulting encoder can then be
+ * pass to { @link @waku/interfaces.LightPush.push } or
+ * { @link @waku/interfaces.Relay.send } to automatically encrypt
+ * and encode outgoing messages.
+ *
+ * The payload can optionally be signed with the given private key as defined
+ * in [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26/).
+ *
+ * @param contentTopic The content topic to set on outgoing messages.
+ * @param publicKey The public key to encrypt the payload for.
+ * @param sigPrivKey An optional private key to used to sign the payload before encryption.
+ * @param ephemeral An optional flag to mark message as ephemeral, ie, not to be stored by Waku Store nodes.
+ */
 export function createEncoder(
   contentTopic: string,
   publicKey: Uint8Array,
@@ -132,6 +150,19 @@ class Decoder extends DecoderV0 implements IDecoder<DecodedMessage> {
   }
 }
 
+/**
+ * Creates a decoder that decrypts messages using ECIES, using the given private
+ * key as defined in [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26/).
+ *
+ * A decoder is used to decode messages from the [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/)
+ * format when received from the Waku network. The resulting decoder can then be
+ * pass to { @link @waku/interfaces.Filter.subscribe } or
+ * { @link @waku/interfaces.Relay.subscribe } to automatically decrypt and
+ * decode incoming messages.
+ *
+ * @param contentTopic The resulting decoder will only decode messages with this content topic.
+ * @param privateKey The private key used to decrypt the message.
+ */
 export function createDecoder(
   contentTopic: string,
   privateKey: Uint8Array

packages/message-encryption/src/index.ts

@@ -14,6 +14,9 @@ export const OneMillion = BigInt(1_000_000);
 
 export { generatePrivateKey, generateSymmetricKey, getPublicKey };
 
+export * as ecies from "./ecies.js";
+export * as symmetric from "./symmetric.js";
+
 export const Version = 1;
 
 export type Signature = {

packages/message-encryption/src/symmetric.ts

@@ -63,6 +63,24 @@ class Encoder implements IEncoder {
   }
 }
 
+/**
+ * Creates an encoder that encrypts messages using symmetric encryption for the
+ * given key, as defined in [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26/).
+ *
+ * An encoder is used to encode messages in the [`14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/)
+ * format to be sent over the Waku network. The resulting encoder can then be
+ * pass to { @link @waku/interfaces.LightPush.push } or
+ * { @link @waku/interfaces.Relay.send } to automatically encrypt
+ * and encode outgoing messages.
+ *
+ * The payload can optionally be signed with the given private key as defined
+ * in [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26/).
+ *
+ * @param contentTopic The content topic to set on outgoing messages.
+ * @param symKey The symmetric key to encrypt the payload with.
+ * @param sigPrivKey An optional private key to used to sign the payload before encryption.
+ * @param ephemeral An optional flag to mark message as ephemeral, ie, not to be stored by Waku Store nodes.
+ */
 export function createEncoder(
   contentTopic: string,
   symKey: Uint8Array,
@@ -130,6 +148,19 @@ class Decoder extends DecoderV0 implements IDecoder<DecodedMessage> {
   }
 }
 
+/**
+ * Creates a decoder that decrypts messages using symmetric encryption, using
+ * the given key as defined in [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26/).
+ *
+ * A decoder is used to decode messages from the [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/)
+ * format when received from the Waku network. The resulting decoder can then be
+ * pass to { @link @waku/interfaces.Filter.subscribe } or
+ * { @link @waku/interfaces.Relay.subscribe } to automatically decrypt and
+ * decode incoming messages.
+ *
+ * @param contentTopic The resulting decoder will only decode messages with this content topic.
+ * @param symKey The symmetric key used to decrypt the message.
+ */
 export function createDecoder(
   contentTopic: string,
   symKey: Uint8Array