helia-coord

February 16, 2026 · View on GitHub

A JavaScript npm library built on top of Helia, the JS implementation of IPFS. It provides the following high-level features:

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 pubsub channels (via gossipsub) for communication
Circuit Relays for censorship resistance and tunneling through firewalls
Bitcoin Cash 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.

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.

Install

Install the npm library:

npm install --save helia-coord

This library requires a peer dependency of 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:

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 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 IPFS node.
`wallet`	Yes	An instance of 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 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:

git clone https://github.com/Permissionless-Software-Foundation/helia-coord
cd helia-coord
npm install

Running Tests

This project uses Mocha for testing, Chai for assertions, Sinon for mocks, and nyc for code coverage.

Run the unit test suite:

npm test

This runs the linter (Standard.js) followed by the unit tests.

Generate a coverage report:

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:

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 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.

License

MIT