dart_ipfs library

Production-ready IPFS (InterPlanetary File System) implementation in Dart.

This library provides a complete IPFS implementation with support for:

Full IPFS protocol compliance (CID, UnixFS, DAG-PB, Bitswap, DHT)
P2P networking with production-grade cryptography
Multiple deployment modes (offline, gateway, full P2P)
HTTP Gateway and RPC API
Mobile (Flutter) and web platform support

Quick Start

Offline Mode (Local Storage)

import 'package:dart_ipfs/dart_ipfs.dart';

void main() async {
  final node = await IPFSNode.create(
    IPFSConfig(offline: true),
  );
  await node.start();

  // Add content
  final cid = await node.addFile(data);
  // print('Added: $cid');

  // Retrieve content
  final content = await node.get(cid);

  await node.stop();
}

Gateway Mode (HTTP Server)

final node = await IPFSNode.create(
  IPFSConfig(
    offline: true,
    gateway: GatewayConfig(
      enabled: true,
      port: 8080,
    ),
  ),
);
await node.start();
// Access at `http://localhost:8080/ipfs/<CID>`

Full P2P Mode

final node = await IPFSNode.create(
  IPFSConfig(offline: false),
);
await node.start();
// print('Peer ID: ${node.peerId}');

Features

Core IPFS

CID v0/v1: Content identifier support
UnixFS: File system with chunking
DAG-PB: MerkleDAG operations
Pinning: Content persistence
CAR Files: Import/export

Networking

Bitswap 1.2.0: Block exchange protocol
Kademlia DHT: Distributed routing
PubSub: Real-time messaging
MDNS: Local peer discovery
Circuit Relay: NAT traversal

Services

HTTP Gateway: Content serving
RPC API: go-ipfs compatible
IPNS: Mutable naming
DNSLink: Domain resolution
Metrics: Prometheus compatible

Architecture

The library is organized into layers:

Core: CID, blocks, data structures
Protocols: Bitswap, DHT, PubSub
Services: Gateway, RPC, IPNS
Transport: P2P networking
Storage: Local datastore

Security

Production-grade cryptography:

secp256k1: Elliptic curve (128-bit security)
ChaCha20-Poly1305: AEAD encryption
SHA-256: Content hashing

Platform Support

✅ Mobile (Flutter iOS/Android)
✅ Web (Dart Web)
✅ Desktop (Windows/macOS/Linux)
✅ Server (Dart VM)

Examples

See the example/ directory for:

Offline content publishing
P2P networking
HTTP gateway
Full node operation

Learn More

Classes

AndCondition: Matches when every member condition matches.
BitswapConfig: Configuration for the Bitswap protocol, including the optional HTTP gateway fallback used when P2P block exchange fails.
Block: Represents an IPFS block.
BlockStore: Persistent storage for content-addressed blocks in IPFS.
BlockStoreResult<T>: A generic result returned by block store operations.
CarHeader: Immutable CAR file header.
CarReader: Streaming/iterable reader for CAR v1 and v2 archives.
CarSection: A single CID/block section within a CAR archive.
CarWriter: Append-only writer for CAR v1 and v2 archives.
CID: A Content Identifier (CID) for content-addressed data in IPFS.
CircuitRelayConfig: Configuration for the circuit relay client.
Condition: A predicate over a data-model node, used by Matcher.onlyIf, ExploreRecursive.stopAt, and ExploreConditional.condition.
CryptoUtils: Cryptographic utilities for secure key management.
DagCborCodec: Codec for DAG-CBOR.
DagJsonCodec: Codec for DAG-JSON.
Datastore: Abstract interface for a key-value datastore.
DenylistAuditEvent: A single audit event recorded when content is matched by the denylist.
DenylistService: Operator-controlled content denylist service.
DenylistStats: Statistics describing the current state of a denylist refresh.
DepthRecursionLimit: Depth-based recursion limit ({"depth": n}).
DHTConfig: Configuration options for the DHT (Distributed Hash Table)
Ed25519Signer: Unified Ed25519 signing service.
EncryptedData: Result of AES-GCM encryption containing ciphertext and nonce.
ExploreAll: ExploreAll: traverse every key/value pair of a map or every index of a list, applying next to each reached node.
ExploreConditional: ExploreConditional: when condition matches the current node, continue exploration with next.
ExploreFields: ExploreFields: traverse only the named fields of a map.
ExploreIndex: ExploreIndex: traverse a single list index.
ExploreInterpretAs: ExploreInterpretAs (spec name InterpretAs, union key ~): reify the current node through the ADL named adl, then apply next to the reified view.
ExploreRange: ExploreRange: traverse the half-open range of list indices [start, end).
ExploreRecursive: ExploreRecursive: recursive descent with a limit and a sequence.
ExploreRecursiveEdge: ExploreRecursiveEdge: sentinel marking the recursion point inside an ExploreRecursive sequence. Invalid outside one.
ExploreUnion: ExploreUnion: apply a list of selectors to the same node. Serializes as {"|": [<selector>...]}.
FullAddress: Represents a network address (IP + Port). Replaces p2plib.FullAddress.
GatewayConfig: Configuration for the IPFS HTTP Gateway.
GraphsyncConfig: Configuration for the Graphsync protocol handler.
GreaterThanCondition: Matches when node is a number strictly greater than value.
HasFieldCondition: Matches when node is a map containing field.
HasKindCondition: Matches when node's kind equals kindName (one of map, list, string, bytes, int, float, bool, null, link).
HasValueCondition: Matches when node is data-model-equal to value.
IBlock: Interface for content-addressed data blocks.
IBlockStore: Interface for block storage operations.
ImmutableBytes: An immutable wrapper around a Uint8List with value-based equality.
IndexBuilder: Builder for CAR v2 index payloads.
InMemoryBlockStore: A simple in-memory block store implementation.
IPFS: Main entry point for the IPFS (InterPlanetary File System) implementation.
IPFSConfig: Configuration for an IPFS node.
IPFSNode: The main IPFS node implementation.
IpfsPlatform: Abstract class representing platform-specific operations.
IPFSWebNode: A minimal IPFS node for web browsers.
IPLDCodec: Interface for all IPLD codecs in dart_ipfs_core.
IPLDLink: Represents a CID link
IPLDList: Represents an ordered sequence of IPLD values
IPLDMap: Represents key-value associations
IPLDNode: Main message wrapping all IPLD value types
IPLDSchema: IPLD schema validator for structured data validation.
IPLDSelector: IPLD Selector for querying and traversing DAG structures.
IsLinkCondition: Matches when node is a link. If target is set, the link must point at that CID.
Key: Represents a key in the datastore. Keys are hierarchical path-like strings, e.g., /local/peers/Qm...
Kind: Enumeration of all possible IPLD kinds
LessThanCondition: Matches when node is a number strictly less than value.
Link: A directed link between nodes in the IPFS Merkle DAG.
ManualMobileLifecycleAdapter: A controllable, stream-backed MobileLifecycleAdapter useful for testing, CLI simulations, or custom platform integrations.
Matcher: Matcher selector: marks the node it is applied to as part of the result set. With subset only the sliced span of a string/bytes node is matched; onlyIf gates the match on a Condition; label and index annotate the match for result labelling.
MerkleDAGNode: A node in the IPFS Merkle DAG (Directed Acyclic Graph).
MetricsConfig: Configuration options for telemetry and metrics collection.
MFSListEntry: Kubo-compatible entry in an MFS directory listing.
MFSManager: Manages the Mutable File System (MFS) for an IPFS node.
MFSStat: Kubo-compatible stat result for an MFS path.
MobileLifecycleAdapter: Abstract interface for bridging platform-specific lifecycle and battery events into the IPFS node without binding the core engine to a specific UI framework.
MobileLifecycleCoordinator: Coordinates node resource utilization, background connection scaling, and persistent cache safety in mobile application environments.
MultibaseUtils: Helpers for multibase encoding/decoding used by CID and other multiformats.
Multicodec: Multicodec registry helpers for core IPLD and IPFS codecs.
MultihashUtils: Helpers for computing and decoding multihashes.
NetworkConfig: Network configuration for the IPFS node.
OrCondition: Matches when at least one member condition matches.
OTelExporter: Exports metrics to an OpenTelemetry collector over OTLP/HTTP.
Peer: Represents a peer node in the IPFS network.
PeerKeyRegistry: Registry for caching and verifying bindings between PeerId strings and their corresponding Ed25519 public keys.
PubSubMessage: Represents a message published on a PubSub topic.
Query: A Query object for the datastore.
QueryEntry: The entry returned by a query.
QueryFilter: Interface for filtering query results.
QueryOrder: Interface for ordering query results.
QuicConnection: Adapter implementing libp2p.TransportConn around a quic_lib Libp2pQuicConnection.
QuicListener: libp2p Listener implementation that wraps a quic_lib incoming connection stream.
QuicTransport: libp2p Transport implementation backed by the pure-Dart quic_lib package.
RawCodec: Codec for raw binary data.
RecursionLimit: Recursion limit for ExploreRecursive. The spec union has two members: {"depth": int} and {"none": {}}.
RecursionLimitNone: Unbounded recursion limit ({"none": {}}).
Reprovider: Periodic service that re-announces local content to the DHT.
ReproviderResult: Result of a single reprovide run.
ReproviderStatus: Status snapshot of the Reprovider service.
SchemaValidationError: A single schema validation failure.
SchemaValidationResult: Result of a detailed schema validation run.
SecurityConfig: Security-related configuration options for IPFS node
SelectedNode: Result of a selector execution.
Selector: Base class for all official IPLD selectors.
SelectorExecutor: Executes a Selector against an IPLD block store.
SelectorResult: Result of a selector execution.
Slice: A Slice selects the [from, to) subset of a string, bytes, or reified node inside a Matcher.
StorageConfig: Configuration options for IPFS storage.
TurnServer: Configuration for a TURN server used by WebRTC ICE.
TypedMap: An immutable, type-safe wrapper around a plain Map<String, dynamic>.

Enums

GatewayMode: Modes for retrieving content via the IPFSNode.
IpfsPowerMode: Operational power tiers governing IPFS connection density and network activity.
NodeLifecycleState: Represents the platform lifecycle states of an application embedding IPFS.
NodeState: Represents the possible states of an IPFSNode.
SelectorType: Types of IPLD selectors for DAG traversal.

Extensions

KeyPairExtensions on SimpleKeyPair: Extension to help with key pair management and cleanup.

Constants

defaultSelectorMaxDepth → const int: Default safe depth budget for selector execution.
defaultSelectorMaxNodes → const int: Default safe node budget for selector execution.

Functions

decodeSelectorBytes(Uint8List bytes) → Future<Selector>: Decode a selector from either DAG-CBOR or DAG-JSON bytes.
decodeSelectorDagCbor(Uint8List bytes) → Future<Selector>: Decode a selector from DAG-CBOR bytes. A bare selector or a {"selector": ...} envelope are both accepted.
decodeSelectorDagJson(Uint8List bytes) → Future<Selector>: Decode a selector from DAG-JSON bytes. A bare selector or a {"selector": ...} envelope are both accepted.
encodeSelectorDagCbor(Selector selector) → Future<Uint8List>: Encode a Selector to canonical DAG-CBOR bytes.
encodeSelectorDagJson(Selector selector) → Future<Uint8List>: Encode a Selector to canonical DAG-JSON bytes.
encodeSelectorEnvelopeDagCbor(Selector selector) → Future<Uint8List>: Encode a Selector wrapped in the SelectorEnvelope ({"selector": ...}) to canonical DAG-CBOR bytes.
ipldKindName(Kind kind) → String: The lowercase data-model kind name for kind, as used by HasKindCondition.
ipldNodeEquals(IPLDNode a, IPLDNode b) → bool: Structural equality for IPLDNode values.
ipldNodeHash(IPLDNode node) → int: Order-independent hash for ipldNodeEquals-comparable nodes.
multiaddrFromBytes(Uint8List bytes) → FullAddress?: Helper to decode binary multiaddr to FullAddress
multiaddrToBytes(FullAddress address) → Uint8List: Helper to encode FullAddress to binary multiaddr
parseCondition(IPLDNode node) → Condition: Parse a Condition from its data-model node.
parseMultiaddrString(String multiaddrString) → FullAddress?: Helper function to parse a multiaddr string into a FullAddress.
parseSelector(IPLDNode node) → Selector: Parse an IPLDNode (decoded from DAG-CBOR or DAG-JSON) into a typed Selector.
parseSelectorEnvelope(IPLDNode node) → Selector: Parse a SelectorEnvelope node ({"selector": <selector>}).

Typedefs

IPLDLinkResolver = Future<IPLDNode?> Function(IPLDLink link): Resolves the node an IPLDLink points at.
MultihashInfo = MultihashInfo: Re-export of the underlying multihash info type from dart_multihash.

Exceptions / Errors

CarException: Base class for CAR parsing errors.
CarHeaderException: Thrown when a CAR header is malformed or violates the CAR specification.
CarIndexException: Thrown when a CAR index is malformed or inconsistent with the data payload.
CarSectionException: Thrown when a CAR section is malformed or truncated.
CarV2Exception: Thrown when a CAR v2 pragma or header is invalid.
DatastoreError: Error thrown when a datastore operation fails.
DenylistBlockedException: Thrown when content cannot be served because a CID (or path) matched the operator denylist.
IPLDDecodingError: Error during IPLD decoding (e.g., parsing failures).
IPLDEncodingError: Error during IPLD encoding (e.g., serialization failures).
IPLDError: Base class for IPLD (InterPlanetary Linked Data) errors.
IPLDLinkError: Error resolving IPLD links (e.g., broken DAG references).
IPLDResolutionError: Error during IPLD path resolution.
IPLDSchemaError: Error during IPLD schema validation.
IPLDStorageError: Error during IPLD storage operations.
IPLDValidationError: Error during IPLD content validation.
MFSPathError: Error thrown when a path argument is invalid or escapes the MFS root.
OTelExportException: Thrown when an OTLP export request fails or is rejected by the collector.
SelectorBudgetExceeded: Error when a selector execution exceeds its configured budget.
SelectorParseError: Error when a selector cannot be parsed or is malformed.
TransportUnavailableException: Exception thrown when a transport is enabled but has no working backend on the current platform.

dart_ipfs library

Quick Start

Offline Mode (Local Storage)

Gateway Mode (HTTP Server)

Full P2P Mode

Features

Core IPFS

Networking

Services

Architecture

Security

Platform Support

Examples

Learn More

Classes

Enums

Extensions

Constants

Functions

Typedefs

Exceptions / Errors

dart_ipfs package

dart_ipfs library