dart_ipfs 1.11.6

A comprehensive IPFS implementation in Dart, supporting CID, Bitswap, UnixFS, and DHT.

dart_ipfs

A complete, production-ready IPFS (InterPlanetary File System) implementation in Dart, supporting offline, gateway, and full P2P modes. Built for a seamless multi-platform experience.

A pure-Dart IPFS node supporting Dart VM (Windows, macOS, Linux) and Web (Chrome, Firefox, Safari). The IpfsPlatform abstraction automatically handles storage (File System vs. IndexedDB) and networking based on the target platform.

---

Multi-Platform Support

Platform	Runtime	Storage	Networking
Windows	Dart VM	File System	TCP / UDP / QUIC
macOS	Dart VM	File System	TCP / UDP / QUIC
Linux	Dart VM	File System	TCP / UDP / QUIC
Web	JS / Wasm	IndexedDB	WebSocket / WebRTC

---

Documentation

• Architecture Guide — Deep dive into the Manager-Handler pattern
• ACME Certificate Issuance — Automatic TLS certificate management
• API Reference — Auto-generated Dart docs

---

Table of Contents

• What's New in v1.11
• Features
• Quick Start
• Configuration
• Use Cases
• Architecture
• Security
• Performance
• Troubleshooting
• Examples
• Contributing
• Roadmap
• License

---

What's New in v1.11

Major Features

Feature	Description
WebRTC Multiplexing	Native p2p connectivity for browsers with standard libp2p stream support.
Bitswap 1.2.0	Smart routing via provider tracking and HAVE message support.
Advanced IPLD	Native support for DagCbor, DagJson, and DagJose codecs.
90% Coverage	Industrial-grade stability with >90% code coverage.
Security Parity	Enterprise security features now unified across IO and Web.

---

What's New in v1.10

Major Features

Feature	Description
IpfsPlatform	Unified abstraction shielding core logic from platform differences.
IndexedDB Storage	Production-ready persistent storage for Web browsers.
SecurityManager	Multi-platform encrypted keystore for secure identity management.
Standardization	100% compliance with Kubo (go-ipfs) protocol standards.
Browser Testing	Full CI/CD integration for Chrome and Firefox.

---

Features

Core IPFS Functionality

• Content-Addressable Storage: CID v0 and v1 support
• UnixFS: Full file system implementation with chunking
• DAG-PB: MerkleDAG operations and IPLD traversal
• CAR Files: Import/export support
• Pinning: Content persistence management

Networking & NAT Traversal

• Bitswap 1.2.0: Efficient block exchange with wantlist management
• Kademlia DHT: Distributed hash table for peer/content routing
• AutoNAT: Automatic NAT type detection
  • Direct connectivity testing
  • Symmetric NAT detection
  • Periodic dialback verification
• UPnP/NAT-PMP: Automatic port mapping via NatTraversalService
• Circuit Relay v2: Hole-punching via relay peers
  • HOP protocol (relay serving)
  • STOP protocol (connection handling)
  • RESERVE protocol (relay reservations)
• libp2p Core: Native TCP/Noise transport for standard P2P networking
• PubSub: Real-time messaging (Gossipsub)
• mDNS: Local peer discovery
• Bootstrap Peers: Network connectivity initialization

Services

• HTTP Gateway: Read-only and writable modes
• RPC API: Compatible with go-ipfs API
• IPNS: Mutable naming system with Ed25519 signatures
• DNSLink: Domain-based content resolution
• GraphSync: Efficient graph synchronization protocol
• Metrics: Prometheus-compatible monitoring

Security

• Production Cryptography
  • secp256k1 key exchange (128-bit security)
  • ChaCha20-Poly1305 AEAD encryption
  • SHA-256 content hashing
  • Ed25519 IPNS signatures
• Encrypted Keystore (SEC-008)
  • AES-256-GCM encryption
  • PBKDF2 key derivation
  • Automatic key rotation
  • Memory zeroing on lock
• Sybil Protection (SEC-005)
  • S/Kademlia Proof-of-Work for PeerId verification
  • Configurable difficulty via SecurityConfig.dhtDifficulty
• Rate Limiting
  • Per-client authentication throttling
  • DHT provider announcement limits
• Content Verification
  • Automatic CID validation
  • Merkle tree verification
  • Block integrity checks

Web Platform

• IPFSWebNode: Browser-compatible implementation
• IndexedDB Storage: Persistent local storage
• WebSocket Transport: Networking via secure relays
• Bitswap & PubSub: Full protocol support in browsers

---

Quick Start

Installation

Add to your pubspec.yaml:

dependencies:
  dart_ipfs: ^1.11.5

Or from Git for latest development:

dependencies:
  dart_ipfs:
    git:
      url: https://github.com/jxoesneon/IPFS.git

Then run:

dart pub get

Windows Setup

Important: On Windows, P2P networking requires libsodium for cryptography.

Automatic Setup: dart_ipfs automatically detects and installs libsodium via winget on first run.

Manual Installation (if auto-install fails):

# Via winget (recommended)
winget install jedisct1.libsodium

# Or use offline mode (no P2P)
IPFSConfig(offline: true)

Basic Usage

Offline Mode (Local Storage)

import 'package:dart_ipfs/dart_ipfs.dart';

void main() async {
  final node = await IPFSNode.create(
    IPFSConfig(
      dataPath: './ipfs_data',
      offline: true,  // No P2P networking
    ),
  );

  await node.start();

  // Add content
  import 'dart:convert';
  final cid = await node.addFile(
    Uint8List.fromList(utf8.encode('Hello, IPFS!')),
  );
  print('Added with CID: $cid');

  // Retrieve content
  final retrieved = await node.cat(cid);
  if (retrieved != null) {
    print('Retrieved: ${utf8.decode(retrieved)}');
  }

  await node.stop();
}

Gateway Mode (HTTP Server)

final node = await IPFSNode.create(
  IPFSConfig(
    dataPath: './gateway_data',
    offline: true,
    gateway: GatewayConfig(
      enabled: true,
      port: 8080,
    ),
  ),
);

await node.start();
print('Gateway running at http://localhost:8080');
// Access content at: `http://localhost:8080/ipfs/<CID>`

Automatic TLS with ACME: The gateway supports automatic certificate issuance via Let's Encrypt/ZeroSSL. See ACME Certificate Issuance for configuration details.

P2P Network Mode (Full Node)

final node = await IPFSNode.create(
  IPFSConfig(
    dataPath: './p2p_data',
    offline: false,  // Enable P2P networking
    network: NetworkConfig(
      bootstrapPeers: [
        '/dnsaddr/bootstrap.libp2p.io/p2p/...',
      ],
      enableNatTraversal: true,  // UPnP/NAT-PMP
    ),
  ),
);

await node.start();
print('P2P Node ID: ${node.peerID}');
// Node participates in DHT, Bitswap, PubSub

Web Platform (Browser)

import 'package:dart_ipfs/dart_ipfs.dart';

void main() async {
  final node = IPFSWebNode(
    bootstrapPeers: ['wss://relay.node.address/p2p/...'],
  );
  await node.start();

  final cid = await node.add(Uint8List.fromList('Hello Web!'.codeUnits));
  print('Added: $cid');

  final data = await node.get(cid.toString());
  print('Retrieved: ${String.fromCharCodes(data!)}');
}

---

Configuration

Full Configuration Reference

IPFSConfig(
  // Storage
  dataPath: './ipfs_data',

  // Networking
  offline: false,
  network: NetworkConfig(
    bootstrapPeers: [...],
    listenAddresses: ['/ip4/0.0.0.0/tcp/4001'],
    enableNatTraversal: true,  // UPnP/NAT-PMP port mapping
  ),

  // Gateway
  gateway: GatewayConfig(
    enabled: true,
    port: 8080,
    writable: false,
    cacheSize: 1024 * 1024 * 1024,  // 1GB
  ),

  // RPC API
  rpc: RPCConfig(
    enabled: true,
    port: 5001,
  ),

  // DHT
  dht: DHTConfig(
    mode: DHTMode.server,  // client, server, or auto
    bucketSize: 20,
  ),

  // Security
  security: SecurityConfig(
    dhtDifficulty: 16,              // S/Kademlia PoW difficulty
    rateLimitWindow: Duration(minutes: 1),
    maxAuthAttempts: 5,
    keyRotationInterval: Duration(days: 30),
  ),

  // Logging
  debug: false,
  verboseLogging: false,
)

---

Use Cases

1. Decentralized Storage

final file = File('document.pdf');
final bytes = await file.readAsBytes();
final cid = await node.addFile(bytes);
print('Document CID: $cid');
// Content is permanently addressable

2. Content Distribution Network

final config = IPFSConfig(
  gateway: GatewayConfig(
    enabled: true,
    port: 8080,
    cacheSize: 1024 * 1024 * 1024,
  ),
);

3. Peer-to-Peer Applications

// PubSub messaging
await node.pubsub.subscribe('my-topic', (message) {
  print('Received: $message');
});

await node.pubsub.publish('my-topic', 'Hello, peers!');

4. Decentralized Websites

final websiteDir = Directory('./my-website');
final rootCID = await node.addDirectory(websiteDir);
// Access via: `http://gateway/ipfs/<rootCID>/index.html`

---

Architecture

dart_ipfs follows a Manager-Handler pattern, coordinated by a LifecycleManager. This architecture ensures modularity, where each major responsibility (Content, Network, Protocol, Security, Storage) is handled by a specialized manager.

The IpfsPlatform abstraction layer shields the core logic from platform-specific differences, automatically switching between dart:io (for Desktop/Server) and dart:html/idb_shim (for Web) implementations.

┌─────────────────────────────────────┐
│         Application Layer            │
│   (Your Dart/Flutter Application)    │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         dart_ipfs Public API         │
│  (IPFSNode Facade & IpfsPlatform)    │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         Service Layer                │
│ (Managers: Content, Network, etc.)  │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│        Protocol Layer                │
│  Bitswap │ DHT │ GraphSync │ Relay  │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│        Transport Layer               │
│        P2P (Native libp2p)           │
│  AutoNAT │ Circuit Relay v2           │
│  Crypto (Ed25519 + Noise)            │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         Storage Layer                │
│ (Providers: FileStore vs IndexedDB) │
└─────────────────────────────────────┘

For more details, see the Architecture Guide.

---

Security

IMPORTANT: Production use requires strict sandboxing. See docker-compose.yml for a secure reference implementation.

Recommended Deployment

1. Immutable Filesystem: Run with a read-only root
2. Non-Root Execution: Use UID > 1000 (e.g., 10001)
3. Network Isolation: Bind ports to localhost (127.0.0.1) only
4. IP Diversity Limits: Max 5 peers/IP to prevent routing table poisoning

Encrypted Keystore

// Unlock keystore with password
await node.securityManager.unlockKeystore('your-password');

// Keys are encrypted at rest with AES-256-GCM
// Master key derived via PBKDF2
// Automatic memory zeroing on lock

S/Kademlia PoW

// Enable Sybil protection in DHT
SecurityConfig(
  dhtDifficulty: 16,  // Require 16-bit PoW prefix
)
// Peers with insufficient PoW are rejected from routing table

---

Performance

Metric	Value
Content Hashing	~50 MB/s (SHA-256)
Block Storage	~1000 ops/sec (Hive)
Gateway Latency	<10ms (local cache hit)
P2P Handshake	<100ms (secp256k1 ECDH)
Memory Baseline	~50MB + content cache

---

Known Limitations

• Web Platform: Browser-to-browser P2P requires WebRTC signaling or a relay; direct TCP/UDP listening is not available in browsers.
• Mobile: Not yet optimized for iOS/Android battery and background execution.
• QUIC Transport: Available via configuration but still stabilizing for production workloads.
• MFS: Basic operations are implemented; advanced filesystem semantics are planned for v2.0.

---

Troubleshooting

Node Won't Start (Windows)

Symptom: Hangs during startup

Solution: Install libsodium:

winget install jedisct1.libsodium

Bonjour "Blocked from Local Security Authority" Popup (Windows 11)

Symptom: A popup appears stating mdnsNSP.dll is blocked from loading into the Local Security Authority.

Reason: This is a known compatibility issue between older versions of Apple Bonjour and Windows 11's "LSA Protection" security feature. It happens when the IPFS node attempts local peer discovery via mDNS.

Solution:

1. Update Bonjour: Ensure you have the latest version of Bonjour installed.
2. Uninstall Bonjour: If you don't need it (it's often installed with iTunes or older Apple software), you can uninstall it.
3. Disable mDNS: If you don't need local peer discovery, disable it in your configuration:

   IPFSConfig(
     network: NetworkConfig(enableMDNS: false),
   )
   

AutoNAT Reports "Symmetric"

Symptom: Peers can't connect to you

Solution: Enable port mapping:

NetworkConfig(enableNatTraversal: true)

DHT Queries Slow

Symptom: findProviders takes >30s

Solution: Ensure bootstrap peers are reachable and check dhtDifficulty isn't too high.

Gateway Returns 404

Symptom: Content not found even though added

Solution: Check if content is pinned:

await node.pin(cid);

---

Examples

See the example/ directory for full applications:

• Premium Dashboard: Flutter desktop app with glassmorphism UI
• CLI Dashboard: Matrix-style terminal interface

Other examples:

• Basic Usage
• Offline Blog
• P2P Networking
• HTTP Gateway
• Full Node
• Keystore Unlock
• libp2p Bridge Verification

Run examples:

dart run example/blog_use_case.dart
dart run example/online_test.dart

---

Testing

# Run all tests (VM)
dart test

# Run tests in Chrome (Web)
dart test -p chrome

# Run with verbose output
dart test -r expanded

# Static analysis
dart analyze

Expected results:

• 0 errors
• 0 warnings
• 2326 tests pass

---

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Ensure dart analyze and dart test pass
5. Submit a pull request

---

Roadmap

Completed

• Core IPFS protocols (Bitswap, DHT, PubSub)
• Offline, Gateway, and P2P modes
• Production cryptography
• Web platform support
  • WebSocket, WebRTC, and WebTransport
  • WebRTC-Direct for browser-to-browser P2P
• libp2p core migration
• Circuit Relay v2
• AutoNAT
• Encrypted keystore
• S/Kademlia PoW
• 95%+ Router Coverage

In Progress

• Mobile optimization (Flutter performance)
• Native QUIC transport (Desktop/Server)

Planned

• Filecoin integration
• IPFS Pinning Service API (Remote Pinning)

---

Comparison with go-ipfs

Feature	dart_ipfs	go-ipfs (Kubo)
Content Storage	Yes	Yes
UnixFS	Yes	Yes
CID v0/v1	Yes	Yes
Bitswap 1.2.0	Yes	Yes
Kademlia DHT	Yes	Yes
HTTP Gateway	Yes	Yes
RPC API	Yes	Yes
PubSub	Yes	Yes
IPNS	Yes	Yes
GraphSync	Yes	Yes
Circuit Relay v2	Yes	Yes
AutoNAT	Yes	Yes
Language	Dart	Go
Mobile Support	Yes (Flutter)	No
Web Support	Yes (Dart Web)	No

---

License

MIT License — see LICENSE file for details

---

Credits

Built with:

• dart_libp2p — Native P2P networking
• pointycastle — Cryptography
• hive — Storage
• protobuf — Protocol buffers

Inspired by:

• go-ipfs (Kubo) — Reference implementation
• js-ipfs — JavaScript implementation

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• IPFS Docs: docs.ipfs.tech

---

For more information, see the GitHub repository.