Skip to content

Configuration

The configuration system for dart-libp2p provides a flexible and extensible way to configure your libp2p node. It is modeled after the Go implementation’s configuration system but uses Dart’s extension methods for a more idiomatic API.

The system uses a functional options pattern. You start with a Config object and apply various Option functions to it. An Option is simply a function that modifies the Config object.

The Config class is the central component that holds all configuration options for a libp2p node.

class Config {
String? userAgent;
String? protocolVersion;
KeyPair? peerKey;
List<Transport> transports = [];
List<SecurityProtocol> securityProtocols = [];
bool insecure = false;
List<MultiAddr> listenAddrs = [];
List<StreamMuxer> muxers = [];
// ... and many other options
}

An Option is a function that takes a Config object and applies a setting to it.

typedef Option = FutureOr<void> Function(Config config);

The Libp2p class provides a set of static factory methods for creating Option functions. This is the primary way you will specify your configuration.

class Libp2p {
static Option listenAddrs(List<MultiAddr> addrs) { ... }
static Option security(SecurityProtocol securityProtocol) { ... }
static Option transport(Transport transport) { ... }
static Option identity(KeyPair keyPair) { ... }
// ... and so on
}

There are two primary ways to configure and create a libp2p host.

Method 1: Using the Libp2p.new_ convenience method

Section titled “Method 1: Using the Libp2p.new_ convenience method”

This is the simplest way to get a host running. It creates a Config object, applies your options, adds sensible defaults for any unspecified options, and returns a new Host. The host does not listen until you call start().

import 'package:dart_libp2p/dart_libp2p.dart' hide Option;
import 'package:dart_libp2p/config/config.dart';
import 'package:dart_libp2p/p2p/security/noise/noise_protocol.dart';
import 'package:dart_libp2p/p2p/transport/connection_manager.dart';
import 'package:dart_libp2p/p2p/transport/multiplexing/multiplexer.dart';
import 'package:dart_libp2p/p2p/transport/multiplexing/yamux/session.dart';
import 'package:dart_libp2p/p2p/transport/tcp_transport.dart';
final keyPair = await generateEd25519KeyPair();
final connManager = ConnectionManager();
final host = await Libp2p.new_([
// Set the identity (private key)
Libp2p.identity(keyPair),
// Share one connection manager between the host and its transports
Libp2p.connManager(connManager),
// Set the transport
Libp2p.transport(TCPTransport(connManager: connManager)),
// Set the listen addresses
Libp2p.listenAddrs([MultiAddr('/ip4/0.0.0.0/tcp/9000')]),
// Set the security protocol (Noise is the default)
Libp2p.security(await NoiseSecurity.create(keyPair)),
// Set the stream multiplexer (Yamux is the default)
Libp2p.muxer(
'/yamux/1.0.0',
(conn, isClient) =>
YamuxSession(conn as TransportConn, const MultiplexerConfig(), isClient),
),
// Set the user agent
Libp2p.userAgent('my-libp2p-node/1.0.0'),
]);
// Start the host to begin listening for connections
await host.start();

The barrel dart_libp2p.dart also exports a routing Option type. Hide it, as above, or import config/config.dart with a prefix, so that Option means the configuration option.

Method 2: Manually creating and applying a Config

Section titled “Method 2: Manually creating and applying a Config”

This method gives you more control over the configuration process and follows the pattern used in go-libp2p.

import 'package:dart_libp2p/dart_libp2p.dart' hide Option;
import 'package:dart_libp2p/config/config.dart';
import 'package:dart_libp2p/config/defaults.dart';
import 'package:dart_libp2p/p2p/transport/connection_manager.dart';
import 'package:dart_libp2p/p2p/transport/tcp_transport.dart';
final keyPair = await generateEd25519KeyPair();
final connManager = ConnectionManager();
// Step 1: Create a new Config
final config = Libp2p.newConfig();
// Step 2: Apply configuration options to the Config
await config.apply([
Libp2p.identity(keyPair),
Libp2p.connManager(connManager),
Libp2p.transport(TCPTransport(connManager: connManager)),
Libp2p.listenAddrs([MultiAddr('/ip4/0.0.0.0/tcp/9000')]),
]);
// Step 3: Apply defaults for any options that weren't specified
await applyDefaults(config);
// Step 4: Create a new Host from the Config (this consumes the Config)
final host = await config.newNode();
// Start the host
await host.start();

If you don’t specify certain options, the library will apply sensible defaults. These are defined in the lib/config/defaults.dart file and include:

  • Identity: An Ed25519 key pair is generated if not provided.
  • Security: The Noise protocol is used by default.
  • Multiplexer: Yamux (/yamux/1.0.0) is used by default.
  • Connection manager and event bus: A ConnectionManager and a BasicBus.
  • Advertised addresses: An AddrsFactory that leaves loopback and unspecified (0.0.0.0, ::) addresses out of host.addrs. Replace it with Libp2p.addrsFactory.
  • Resource limits: A ConfigurableLimiter with go-libp2p’s default limits (see Resource Manager).
  • Services: Identify, Ping, AutoNAT and hole punching are enabled by default; relay and AutoRelay are not.

You must, however, specify at least one Transport; newNode() throws No transports specified without one. Listen addresses are optional: a host without them can still dial other peers, but no one can dial it.

You can add your own custom options by following the established pattern:

  1. Add a new field to the Config class.
  2. Add a new extension method to the ConfigOptions extension.
  3. Add a new factory function to the Libp2p class.

Built by Stephan Februarygithub.com/stephanfebLinkedIn