helia-coord 2.0.0 → 2.0.2

package/README.md

@@ -1,5 +1,172 @@
 # helia-coord
 
-This is a fork of [ipfs-coord-esm](https://github.com/Permissionless-Software-Foundation/ipfs-coord-esm), adpted for use with [Helia](https://github.com/ipfs/helia) instead of Kubo.
+A JavaScript npm library built on top of [Helia](https://github.com/ipfs/helia), the JS implementation of IPFS. It provides the following high-level features:
 
-Read the [dev-docs](./dev-docs) for more information.
+- **Subnets** - Helps IPFS nodes create an on-the-fly subnetwork, using pubsub channels.
+- **Peer Discovery** - Allows new peers entering the subnetwork to find the other subnetwork peers.
+- **E2EE** - Creates end-to-end encrypted (e2ee) communication channels between peers.
+- **Censorship Resistance** - Allows automatic networking between peers, even if they are behind a firewall.
+- **Payments** - Allows peers to easily pay one another in cryptocurrency for access to web services.
+
+This library helps IPFS peers discover one another, coordinate around a common interest, and then stay connected around that interest. Its main sub-components are:
+
+- [libp2p](https://libp2p.io/) pubsub channels (via [gossipsub](https://github.com/ChainSafe/js-libp2p-gossipsub)) for communication
+- [Circuit Relays](https://docs.libp2p.io/concepts/nat/circuit-relay/) for censorship resistance and tunneling through firewalls
+- [Bitcoin Cash](https://bitcoincash.org/) for end-to-end encryption and payments
+
+helia-coord will automatically track peers, connect to them through circuit relays, and end-to-end encrypt all communication with each node. Interval timers continually maintain these connections, creating a self-healing mesh network. For more details, read the [dev-docs](./dev-docs).
+
+Here are some use cases where IPFS node coordination is needed:
+
+- e2e encrypted chat
+- Circuit-relay as-a-service
+- Creating CoinJoin transactions
+- Decentralized exchange of currencies
+- Compute-as-a-service
+- Storage-as-a-service
+
+The ultimate goal of this library is to be a building block for replacing conventional REST APIs. An IPFS-based API, in a fully distributed network like IPFS, must have sophisticated coordination in order to function properly. helia-coord is that coordination library. It is consumed by higher-level applications like [ipfs-service-provider](https://github.com/Permissionless-Software-Foundation/ipfs-service-provider).
+
+## Install
+
+Install the npm library:
+
+```bash
+npm install --save helia-coord
+```
+
+This library requires a peer dependency of [minimal-slp-wallet](https://www.npmjs.com/package/minimal-slp-wallet).
+
+## Quick Start
+
+helia-coord exports two things:
+
+- **`IpfsCoord`** (default export) - The coordination library that wraps a Helia IPFS node.
+- **`CreateHeliaNode`** (via `helia-coord/create-helia-node`) - A factory class for creating a properly configured Helia IPFS node.
+
+### Example in a node.js app
+
+Here is an example of adding helia-coord to your own node.js app:
+
+```javascript
+import SlpWallet from 'minimal-slp-wallet'
+import IpfsCoord from 'helia-coord'
+import CreateHeliaNode from 'helia-coord/create-helia-node'
+
+async function start () {
+  // Create an instance of the BCH wallet.
+  const wallet = new SlpWallet()
+  await wallet.walletInfoPromise
+
+  // Create a Helia IPFS node.
+  const createHeliaNode = new CreateHeliaNode()
+  const ipfs = await createHeliaNode.start()
+
+  // Pass the wallet and IPFS node to helia-coord when instantiating it.
+  const ipfsCoord = new IpfsCoord({
+    ipfs,
+    wallet,
+    type: 'node.js',
+    debugLevel: 1
+  })
+
+  await ipfsCoord.start()
+  console.log('IPFS and the coordination library is ready.')
+}
+start()
+```
+
+See [`examples/start-node.js`](./examples/start-node.js) for a working example.
+
+## Configuration
+
+When instantiating `IpfsCoord`, the following configuration properties can be passed to its constructor:
+
+| Property | Required | Description |
+|---|---|---|
+| `ipfs` | Yes | An instance of a [Helia](https://github.com/ipfs/helia) IPFS node. |
+| `wallet` | Yes | An instance of [minimal-slp-wallet](https://www.npmjs.com/package/minimal-slp-wallet). Used for BCH payments and generating encryption keys. |
+| `type` | Yes | `'node.js'` or `'browser'` - the type of environment the app is running in. |
+| `debugLevel` | No | Integer from 0-3. `0` = no debug output (default), `1` = status logs, `2` = verbose connection errors, `3` = everything. |
+| `statusLog` | No | A function for handling status log messages. Defaults to `console.log`. |
+| `privateLog` | No | A function for handling incoming e2e encrypted private messages from other peers. Defaults to `console.log`. |
+| `nodeType` | No | `'embedded'` (default) or `'external'`. |
+| `isCircuitRelay` | No | Boolean. Set to `true` if this node should act as a Circuit Relay. Defaults to `false`. |
+| `circuitRelayInfo` | No | Object with additional info for circuit relay nodes (e.g. `{ ip4, tcpPort, crDomain }`). |
+| `announceJsonLd` | No | A custom [JSON-LD](https://json-ld.org/) object for the node's announcement. Overrides the default. |
+| `tcpPort` | No | TCP port number. Used for auto-detecting the node's public multiaddr. |
+| `apiInfo` | No | A string (URL or IPFS hash) pointing to API documentation for the service this node provides. |
+
+When instantiating `CreateHeliaNode`, the following configuration properties can be passed:
+
+| Property | Default | Description |
+|---|---|---|
+| `ipfsDir` | `'./.ipfsdata/ipfs'` | Directory for IPFS block and data stores. |
+| `tcpPort` | `4001` | TCP port for libp2p to listen on. |
+| `wsPort` | `4003` | WebSocket port for libp2p to listen on. |
+| `isCircuitRelay` | `false` | Whether to enable the circuit relay server. |
+| `bootstrapPeers` | PSF defaults | Array of multiaddr strings for bootstrap peer discovery. |
+| `getSeed` | Random | An async function returning a seed string for the libp2p keychain. Provide this to get a persistent IPFS peer ID across restarts. |
+
+## Development Environment
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/Permissionless-Software-Foundation/helia-coord
+cd helia-coord
+npm install
+```
+
+### Running Tests
+
+This project uses [Mocha](https://mochajs.org/) for testing, [Chai](https://www.chaijs.com/) for assertions, [Sinon](https://sinonjs.org/) for mocks, and [nyc](https://github.com/istanbuljs/nyc) for code coverage.
+
+Run the unit test suite:
+
+```bash
+npm test
+```
+
+This runs the linter ([Standard.js](https://standardjs.com/)) followed by the unit tests.
+
+Generate a coverage report:
+
+```bash
+npm run coverage:report
+```
+
+### Running the Example App
+
+The `examples/` directory contains a working example that starts a Helia IPFS node with helia-coord attached:
+
+```bash
+cd examples
+node start-node.js
+```
+
+This will create a Helia IPFS node, connect to the PSF coordination network, discover peers, and begin announcing itself on the pubsub coordination channel. IPFS data is stored in `examples/.ipfsdata/`.
+
+## Architecture
+
+helia-coord follows the [Clean Architecture](https://troutsblog.com/blog/clean-architecture) design pattern, organized into four layers:
+
+- **Entities** - Core business objects: `thisNode` (the local IPFS node), `peers` (other nodes on the subnet), `relays` (circuit relay nodes), and `pubsub` channels.
+- **Use Cases** - Actions performed on entities: creating the node identity, managing peer connections, handling relay connections, and initializing pubsub.
+- **Controllers** - Inputs to the system, primarily interval timers that periodically maintain connections, announce the node, and manage peer/relay state.
+- **Adapters** - Interfaces to external systems: IPFS (Helia/libp2p), BCH (minimal-slp-wallet), encryption (Elliptic Curve), pubsub messaging, and a GitHub Gist adapter for discovering circuit relays.
+
+After instantiation, the library exposes `useCases`, `controllers`, and `adapters` properties for programmatic access to its features.
+
+## Further Reading
+
+- [dev-docs/theory-of-operation.md](./dev-docs/theory-of-operation.md) - High-level overview of entities, pubsub channels, and interval timers.
+- [dev-docs/usage-and-code.md](./dev-docs/usage-and-code.md) - Detailed specifications for the Clean Architecture layers.
+- [Helia](https://github.com/ipfs/helia) - The JavaScript IPFS implementation that helia-coord wraps.
+- [ipfs-service-provider](https://github.com/Permissionless-Software-Foundation/ipfs-service-provider) - A higher-level application that consumes helia-coord.
+- [The Cash Stack](https://cashstack.info) - The full software stack that helia-coord is a part of.
+- [PSFoundation.cash](https://PSFoundation.cash) - The Permissionless Software Foundation.
+
+## License
+
+[MIT](LICENSE.md)

package/dev-docs/pubsub.md

@@ -1,3 +1,27 @@
 # Pubsub
 
-One of the primary functions of the helia-coord library is 
+One of the primary functions of the helia-coord library is managing pubsub channels for communication between IPFS nodes. See [theory-of-operation.md](./theory-of-operation.md) for a high-level overview of the channel types.
+
+## Coordination Channel
+
+All nodes on the subnet subscribe to a shared coordination channel (configured in `config/global-config.js` as `DEFAULT_COORDINATION_ROOM`). Nodes periodically broadcast an announcement object on this channel containing their IPFS ID, multiaddrs, public encryption key, BCH/SLP addresses, and JSON-LD metadata. When a node receives an announcement, it is routed to `addSubnetPeer()` in `peer-use-cases.js` to be processed.
+
+## Private Channels
+
+Each node subscribes to a pubsub channel named after its own IPFS peer ID. This channel is used exclusively for **receiving** encrypted messages from other peers. The node never broadcasts on its own private channel.
+
+When a new peer is discovered via the coordination channel, the node subscribes to that peer's private channel in order to **send** encrypted messages to it. Messages are encrypted with the recipient's public key using Elliptic Curve cryptography (via `encryption-adapter.js`) before being published.
+
+Incoming encrypted messages on the private channel are decrypted and then passed up to the consuming application via the `privateLog` callback. Low-level messages such as ACK and metric commands are handled internally by helia-coord and are not passed up.
+
+## Message Routing
+
+The pubsub adapter (`lib/adapters/pubsub-adapter/`) handles message routing:
+
+- `messaging.js` - Publishes messages to pubsub channels.
+- `msg-router.js` - Routes incoming messages to the appropriate handler based on the channel and message type.
+- `resend-msg.js` - Handles retrying failed message deliveries.
+
+## CoinJoin Channel
+
+A separate pubsub channel (`BCH_COINJOIN_ROOM` in the global config) exists for coordinating CoinJoin transactions for financial privacy. This channel is not fully developed and can be ignored for now.

package/dev-docs/startup.md

@@ -1,6 +1,12 @@
 # Startup
 
-Outline of startup procedure:
+Outline of the startup procedure for helia-coord. See [theory-of-operation.md](./theory-of-operation.md) for a high-level overview and [usage-and-code.md](./usage-and-code.md) for details on each architectural layer.
 
-- Instantiate the library by passing in a configuration object.
-- 
+1. The consuming application creates a Helia IPFS node (e.g. via `CreateHeliaNode`) and an instance of `minimal-slp-wallet`.
+2. The consuming application instantiates `IpfsCoord`, passing in the Helia node, wallet, and configuration options.
+3. The consuming application calls `ipfsCoord.start()`, which triggers the following sequence:
+   - The IPFS adapter starts and retrieves the node's peer ID and multiaddrs.
+   - `createSelf()` builds the `thisNode` entity by aggregating IPFS info, generating BCH/SLP addresses and a public encryption key from the wallet, initializing the Schema library, and subscribing to the node's own private pubsub channel.
+   - `initializePubsub()` subscribes the node to the general coordination pubsub channel.
+   - `startTimers()` initializes the interval timers that maintain connections to relays, announce the node, and manage peer connections.
+   - `_initializeConnections()` downloads the Circuit Relay list from the GitHub Gist and attempts initial connections to relays and subnet peers. This runs without blocking so it does not delay startup of the consuming application.

package/dev-docs/temp.md

@@ -15,9 +15,9 @@ Peers are other IPFS nodes that the application wants to keep track of. These ar
 
 ### Relays
 
-Some nodes using ipfs-coord can elect to become [Circuit Relays](https://docs.libp2p.io/concepts/circuit-relay/). Circuit Relays are critical for keeping the network censorship resistant. They allow nodes that otherwise would not be able to communicate with one another, do so. They assist in punching through network firewalls that would otherwise block communication. They allow the subnet to route around damage and dynamically adjust as nodes enter and leave the subnet.
+Some nodes using helia-coord can elect to become [Circuit Relays](https://docs.libp2p.io/concepts/circuit-relay/). Circuit Relays are critical for keeping the network censorship resistant. They allow nodes that otherwise would not be able to communicate with one another, do so. They assist in punching through network firewalls that would otherwise block communication. They allow the subnet to route around damage and dynamically adjust as nodes enter and leave the subnet.
 
-ipfs-coord will start by connecting to a small set of pre-configured Relays. As it discovers new peers in the subnetwork that have their `isCircuitRelay` flag set, it will expand its connections to as many Relays as it can find.
+helia-coord will start by connecting to a small set of pre-configured Relays. As it discovers new peers in the subnetwork that have their `isCircuitRelay` flag set, it will expand its connections to as many Relays as it can find.
 
 - `relayList` - An array of IPFS IDs (strings), identifying each Relay this node knows about.
 - `relayData` - An object with root properties that match the relay IPFS ID. Each root property represents a relay and contains the data about that relay.

package/dev-docs/theory-of-operation.md

@@ -49,4 +49,4 @@ There are some low-level messages that are not passed up to the consuming softwa
 When a new node is discovered via its announcement on the *Coordination Channel*, the node will subscribe to that nodes private channel. The node will use this channel to send encrypted RPC commands to other nodes. This channel is only used for broadcasting. It is never used for receiving messages.
 
 ## Interval Timers
-A series of interval timers are defined in the `lib/controllser/timer-controller.js` file. These timers are periodically triggered in order to maintain the nodes state. They renew broken connections to other nodes, track latency between the node and Circuit Relays that it knows about, and other operations. These time-based function calls are what allow the node to create the mesh network on-the-fly and the self-heal the network as nodes come online or drop off the network.
+A series of interval timers are defined in the `lib/controllers/timer-controller.js` file. These timers are periodically triggered in order to maintain the nodes state. They renew broken connections to other nodes, track latency between the node and Circuit Relays that it knows about, and other operations. These time-based function calls are what allow the node to create the mesh network on-the-fly and the self-heal the network as nodes come online or drop off the network.

package/dev-docs/usage-and-code.md

@@ -1,10 +1,10 @@
-# ipfs-coord Specifications
+# helia-coord Specifications
 
 ## Overview
 
-ipfs-coord is a shortening of the word 'coordination'. It is a JavaScript npm library that helps applications using [js-ipfs](https://github.com/ipfs/js-ipfs) coordinate with other peers running related applications.
+helia-coord is a shortening of the word 'coordination'. It is a JavaScript npm library that helps applications using [Helia](https://github.com/ipfs/helia) coordinate with other peers running related applications.
 
-This document contains a high-level, human-readable specification for the four major architectural areas of the ipfs-coord library:
+This document contains a high-level, human-readable specification for the four major architectural areas of the helia-coord library:
 
 - Entities
 - Use Cases
@@ -13,17 +13,23 @@ This document contains a high-level, human-readable specification for the four m
 
 This reflects the [Clean Architecture](https://troutsblog.com/blog/clean-architecture) design pattern.
 
-After the ipfs-coord library is instantiated, it will have properties `useCases`, `controllers`, and `adapters` that have methods corresponding to the descriptions in this document. Apps can exercise the features of the ipfs-coord library through this object-oriented structure.
+After the helia-coord library is instantiated, it will have properties `useCases`, `controllers`, and `adapters` that have methods corresponding to the descriptions in this document. Apps can exercise the features of the helia-coord library through this object-oriented structure.
 
 ## Configuration
 
-When instantiating the ipfs-coord library, the following configuration inputs can be passed to its constructor via an object with the properties indicated below. Be sure to check out the [examples directory](../examples) for examples on how to instantiate the library with different configurations.
+When instantiating the helia-coord library, the following configuration inputs can be passed to its constructor via an object with the properties indicated below. Be sure to check out the [examples directory](../examples) for examples on how to instantiate the library with different configurations.
 
-- `ipfs`: (required) An instance of [js-ipfs](https://www.npmjs.com/package/ipfs). IPFS must be instantiated outside of ipfs-coord and passed into it when instantiating the ipfs-coord library.
-- `bchjs`: (required) An instance of [bch-js](https://www.npmjs.com/package/@psf/bch-js). bch-js must be instantiated outside of ipfs-coord and passed into it when instantiating the ipfs-coord library.
+- `ipfs`: (required) An instance of [Helia](https://github.com/ipfs/helia). The Helia IPFS node must be instantiated outside of helia-coord and passed into it when instantiating the library.
+- `wallet`: (required) An instance of [minimal-slp-wallet](https://www.npmjs.com/package/minimal-slp-wallet). The wallet must be instantiated outside of helia-coord and passed into it when instantiating the library. It provides BCH address generation and encryption key management.
 - `type`: (required) A string with the value of 'browser' or 'node.js', to indicate what type of app is instantiating the library. This will determine the types of Circuit Relays the library can connect to.
-- `statusLog`: A function for handling status output strings on the status of ipfs-coord. This defaults to `console.log` if not specified.
+- `statusLog`: A function for handling status output strings on the status of helia-coord. This defaults to `console.log` if not specified.
 - `privateLog`: A function for handling private messages passed to this node from peer nodes. This defaults to `console.log` if not specified.
+- `debugLevel`: An integer from 0-3 controlling the verbosity of log output. `0` = no debug output (default), `1` = status logs, `2` = verbose connection errors, `3` = everything.
+- `isCircuitRelay`: A boolean indicating whether this node should act as a Circuit Relay. Defaults to `false`.
+- `circuitRelayInfo`: An object with additional info for circuit relay nodes (e.g. `{ ip4, tcpPort, crDomain }`).
+- `announceJsonLd`: A custom JSON-LD object for the node's announcement on the coordination channel. Overrides the default.
+- `tcpPort`: TCP port number. Used for auto-detecting the node's public multiaddr.
+- `apiInfo`: A string (URL or IPFS hash) pointing to API documentation for the service this node provides.
 
 ## Entities
 
@@ -31,7 +37,7 @@ Entities make up the core business concepts. If these entities change, they fund
 
 ### thisNode
 
-`thisNode` is the IPFS node consuming the ipfs-coord library. The thisNode Entity creates a representation the 'self' and maintains the state of the IPFS node, BCH wallet, peers, relays, and pubsub channels that the node is tracking.
+`thisNode` is the IPFS node consuming the helia-coord library. The thisNode Entity creates a representation of the 'self' and maintains the state of the IPFS node, BCH wallet, peers, relays, and pubsub channels that the node is tracking.
 
 ## Use Cases
 
@@ -44,19 +50,27 @@ The `this-node-use-cases.js` library contains the following Use Cases:
 - `createSelf()` - initializes the `thisNode` Entity. It takes the following actions:
 
   - It retrieves basic information about the IPFS node like the ID and multiaddresses.
-  - It creates a BCH wallet and generates addresses for payments and a public key used for end-to-end encryption (e2ee).
-  - It creates an OrbitDB used to receive private e2ee messages.
+  - It generates BCH and SLP addresses (via the wallet) for payments and a public key used for end-to-end encryption (e2ee).
+  - It subscribes to its own private pubsub channel for receiving encrypted messages from other peers.
   - It initializes the Schema library for passing standardized messages.
 
-- `addSubnetPeer()` - This is an event handler that is triggered when an 'announcement object' is recieved on the general coordination pubsub channel. That object is passed to `addSubnetPeer()` to be processed. It will analyze the announcement object and add the peer to the array of peers tracked by the thisNode Entity. If the peer is already known, its data will be updated.
+### Peers
+
+The `peer-use-cases.js` library contains the following Use Cases:
+
+- `addSubnetPeer()` - This is an event handler that is triggered when an 'announcement object' is received on the general coordination pubsub channel. That object is passed to `addSubnetPeer()` to be processed. It will analyze the announcement object and add the peer to the array of peers tracked by the thisNode Entity. If the peer is already known, its data will be updated.
 
 - `refreshPeerConnections()` - is periodically called by the Timer Controller. It checks to see if thisNode is still connected to all the subnet peers. It will refresh the connection if they have been disconnected. Circuit Relays are used to connect to other subnet peers, and each known circuit relay will be cycled through until a connection can be established between thisNode and the subnet peer.
 
+- `sendPrivateMessage()` - sends an encrypted message to another peer on the subnet via their private pubsub channel.
+
 ### Relays
 
 The `relay-use-cases.js` library controls the interactions between thisNode and the Circuit Relays that it knows about.
 
-- `initializeRelays()` - The ipfs-coord library comes with a pre-programmed list of Circuit Relay nodes. This list is stored in `config/bootstrap-circuit-relays.js`. The `initializeRelays()` method is called once at startup to connect to these relays. This is what 'bootstraps' thisNode to the IPFS sub-network and allows it to find subnetwork peers. After that initial bootstrap connection, thisNode will automatically learn about and connect to other peers and circuit relays.
+- `getCRGist()` - At startup, helia-coord downloads a list of Circuit Relay nodes from a GitHub Gist (via the Gist adapter). It then attempts to connect to each relay in the list. This is what 'bootstraps' thisNode to the IPFS sub-network and allows it to find subnetwork peers. After that initial bootstrap connection, thisNode will automatically learn about and connect to other peers and circuit relays.
+
+- `connectToBootstrapRelays()` - Connects to the bootstrap peers configured in the libp2p setup. These are peers that are known to run as v2 Circuit Relays and can facilitate connections between other peers.
 
 - `connectToCRs()` - This method is called periodically by the Timer Controller. It checks the connection between thisNode and each Circuit Relay node. If thisNode has lost its connection, the connection is restored.
 
@@ -64,7 +78,7 @@ The `relay-use-cases.js` library controls the interactions between thisNode and
 
 The `pubsub-use-cases.js` has a single method:
 
-- `initializePubsub()` is called at startup to connect the node to the general coordination pubsub channel. This is the channel where other apps running the ipfs-coord library announce themselves to other peers in the subnet.
+- `initializePubsub()` is called at startup to connect the node to the general coordination pubsub channel. This is the channel where other apps running the helia-coord library announce themselves to other peers in the subnet.
 
 ## Controllers
 
@@ -82,34 +96,34 @@ The controllers listed in this section are activated periodically by a timer. Th
 
 - `managePeers()` checks the list of known subnet peers tracked by thisNode Entity. It will restore the connection to each peer if they get disconnected.
 
+- `getWebRtcMultiaddr()` extracts any webRTC multiaddrs from the node's list of multiaddrs and adds them to the announcement object.
+
 ## Adapters
 
 Adapters are the 'outputs' of the system. They are the interfaces that this library manipulates in order to maintain the state of the Entities. Adapters ensure that the business logic doesn't need to know any specific information about the outputs.
 
 ### bch-adapter.js
 
-[bch-js](https://github.com/Permissionless-Software-Foundation/bch-js) is the Bitcoin Cash (BCH) library used to handle payments and end-to-end encryption in peer communication. When the IPFS node is started, it generates a BCH address to receive payments in BCH, and an SLP address to receive payments in SLP tokens. The same private key used to generate these addresses is used to decrypt incoming pubsub messages, and the public key is passed on to other peers so that they can encrypt messages they want to send thisNode.
+The BCH adapter uses [minimal-slp-wallet](https://www.npmjs.com/package/minimal-slp-wallet) (via its embedded bch-js library) to handle payments and end-to-end encryption in peer communication. When the IPFS node is started, it generates a BCH address to receive payments in BCH, and an SLP address to receive payments in SLP tokens. The same private key used to generate these addresses is used to decrypt incoming pubsub messages, and the public key is passed on to other peers so that they can encrypt messages they want to send thisNode.
 
 ### ipfs-adapter.js
 
-This library is designed primarily to control an IPFS node. However, it does not load IPFS directly. It expects the developer to inject an instance of js-ipfs when instantiating this library.
-
-### orbitdb-adapter.js
-
-[OrbitDB](https://orbitdb.org/) is a database that runs on top of IPFS. It's used in this library to prevent 'dropped calls'. As nodes are constantly adjusting their network connections, they can sometimes miss pubsub messages. Other peers in the subnet maintain short-lived logs of the encrypted messages directed at the peers they are connected to. This allows them to pass the message on when the peer reconnects to them, preventing 'dropped calls'. These logs are abandoned after an hour and a new log is created, to prevent them from growing too large.
+This library is designed primarily to control an IPFS node. However, it does not load IPFS directly. It expects the developer to inject an instance of Helia when instantiating this library. It uses the Helia node's underlying libp2p layer for peer management, including connecting, disconnecting, and listing peers.
 
 ### encryption-adapter.js
 
-The encryption adapter is responsible for encryption and decryption of pubsub messages. It uses the same Eliptic Curve cryptography used by the Bitcoin protocol. The same private key that is used to generate the BCH address assigned to thisNode is the same private key used to decrypt incoming messages.
+The encryption adapter is responsible for encryption and decryption of pubsub messages. It uses the same Elliptic Curve cryptography used by the Bitcoin protocol. The same private key that is used to generate the BCH address assigned to thisNode is the same private key used to decrypt incoming messages.
 
-Other subnet peers that thisNode tracks will pass on their public key. All messages sent between nodes is encrypted with the receivers public key. Any unencrypted messages are ignored.
+Other subnet peers that thisNode tracks will pass on their public key. All messages sent between nodes are encrypted with the receiver's public key. Any unencrypted messages are ignored.
 
 ### pubsub-adapter.js
 
-The pubsub adapter can publish a message to a pubsub channel, and route incoming messages to an appropriate handler. There are (public) coordination channels that many peers subscribe to, and messages are published unencrypted.
+The pubsub adapter can publish a message to a pubsub channel, and route incoming messages to an appropriate handler. There are (public) coordination channels that many peers subscribe to, and messages are published unencrypted. Private messages between peers are sent as encrypted payloads published to the recipient's private pubsub channel.
+
+### gist.js
 
-Private messages between peers are _not_ controlled by this library. Those messages are published to OrbitDB and use pubsub messages indirectly, rather than being directly published to a pubsub channel by this library.
+The Gist adapter interfaces with the GitHub Gist API and the PSF bootstrap server. It is used to download a maintained list of Circuit Relays operated by members of the PSF, providing an up-to-date set of relay nodes that the library can connect to at startup.
 
 ### schema.js
 
-The schema library contain formatted JSON objects that are used to generate a standardized messages for communication between peers. The schema.js library is instantiated at startup and appended to the thisNode Entity.
+The schema library contains formatted JSON objects that are used to generate standardized messages for communication between peers. The schema.js library is instantiated at startup and appended to the thisNode Entity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helia-coord",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "A JS library for helping IPFS peers coordinate, find a common interest, and stay connected around that interest.",
   "main": "./index.js",
   "type": "module",
@@ -59,6 +59,7 @@
     "@libp2p/webrtc": "5.2.2",
     "@libp2p/websockets": "9.2.2",
     "@multiformats/multiaddr": "12.3.5",
+    "@multiformats/multiaddr-matcher": "1.6.0",
     "bch-encrypt-lib": "2.1.1",
     "blockstore-fs": "2.0.2",
     "datastore-fs": "10.0.2",