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.
Overview
Section titled “Overview”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.
Key Components
Section titled “Key Components”The Config Class
Section titled “The Config Class”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}The Option Type
Section titled “The Option Type”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 Factory Class
Section titled “The Libp2p Factory Class”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 connectionsawait 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 Configfinal config = Libp2p.newConfig();
// Step 2: Apply configuration options to the Configawait 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 specifiedawait applyDefaults(config);
// Step 4: Create a new Host from the Config (this consumes the Config)final host = await config.newNode();
// Start the hostawait host.start();Default Options
Section titled “Default Options”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
ConnectionManagerand aBasicBus. - Advertised addresses: An
AddrsFactorythat leaves loopback and unspecified (0.0.0.0,::) addresses out ofhost.addrs. Replace it withLibp2p.addrsFactory. - Resource limits: A
ConfigurableLimiterwith 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.
Extending the Configuration
Section titled “Extending the Configuration”You can add your own custom options by following the established pattern:
- Add a new field to the
Configclass. - Add a new extension method to the
ConfigOptionsextension. - Add a new factory function to the
Libp2pclass.