Installation

This page shows you how to add libspiffy 5.0.0 to a Dart or Flutter project and which library to import.

Requirements

libspiffy 5.0.0 declares sdk: ^3.5.1 in its pubspec.yaml, so you need Dart 3.5.1 or later (any Flutter release that ships it).

Add the dependencies

Isar is part of libspiffy’s public API (LibSpiffyActorSystem.initialize(isar:) and LibSpiffySchemas), so your app depends on Isar as well. libspiffy uses the community fork, isar_community.

pubspec.yaml

dependencies:
  libspiffy: ^5.0.0
  isar_community: ^3.3.2
  isar_community_flutter_libs: ^3.3.2 # Flutter apps only

dev_dependencies: # only when your app has Isar collections of its own
  isar_community_generator: ^3.3.2
  build_runner: ^2.7.0

Import Isar as package:isar_community/isar.dart, not package:isar/isar.dart. libspiffy 4.0.0 moved from the unmaintained isar 3.1.0+1 to isar_community 3.3.2; databases written by Isar 3.1 open without migration (see the 4.0.0 entry in CHANGELOG.md).

Add dactor or eventador only if your own code imports them: dactor to run libspiffy inside your own actor system (Actor system integration), eventador to register your own event types (Event type registration). libspiffy 5.0.0 depends on dactor: ^1.3.0 and eventador: ^4.0.0; use compatible constraints.

macOS and iOS: override isar_community

The published isar_community 3.3.2 binary is built on libmdbx v0.13.8-temp-upstream-fix. On Apple platforms that version preallocates the whole new file size past the end of the database file every time the file grows, and never gives the space back: a 135 MiB header store holds 1.9 GiB on disk, and a full testnet header store about 59 GiB. Every Isar database is affected, not only libspiffy’s.

libmdbx fixed this in v0.13.9, but isar_community has not released the upgrade. Until it does, override both packages with the 3.3.2 build on libmdbx v0.13.12, as libspiffy’s own pubspec.yaml does:

pubspec.yaml

dependency_overrides:
  isar_community:
    git:
      url: https://github.com/stephanfeb/isar-community.git
      ref: 3.3.2-libmdbx-0.13.12
      path: packages/isar_community
  isar_community_flutter_libs: # Flutter apps only
    git:
      url: https://github.com/stephanfeb/isar-community.git
      ref: 3.3.2-libmdbx-0.13.12
      path: packages/isar_community_flutter_libs

dependency_overrides in a package do not reach the apps that depend on it, which is why your app must declare the override itself. The fixed binary does not reclaim space a database already holds past its end; Isar on iOS & macOS covers that.

Choose your imports

libspiffy has three public libraries.

Import	What it exports	Use it for
package:libspiffy/coordinator.dart	WalletCoordinator (the type of libspiffy.coordinator), the coordinator’s commands, queries and events (CreateWalletCommand, GetBalanceQuery, WalletCreatedEvent, ErrorEvent, …), CoordinatorRequest, CoordinatorReply, CoordinatorFailure, WalletCoordinatorActor, ForeignSpend, and the channel and proof P2P adapters	Talking to libspiffy. Almost every app needs it.
package:libspiffy/libspiffy.dart	LibSpiffyActorSystem, initializeLibSpiffy(), storage interfaces and backends (SecureStorage, InMemorySecureStorage, StorageBackend, PostgresConfig, LibSpiffySchemas), ArcServiceConfig, FeeRate, models and read models, projections, BEEF/BUMP utilities, plugin interfaces, CDN header sync, blockchain data sources, and the internal actors with their messages	Starting and configuring libspiffy, and the types its events carry.
package:libspiffy/internals.dart	The aggregates (BitcoinWalletAggregate, InvoiceAggregate, PaymentChannelAggregate), their domain commands and events, and the payment channel manager’s messages	Custom actors, extending aggregates, or tests against the event-sourcing layer.

A typical app file imports the first two:

import 'package:libspiffy/coordinator.dart';
import 'package:libspiffy/libspiffy.dart';

These two can be imported together without conflicts. internals.dart cannot: its domain types share names with coordinator types (WalletCreatedEvent, InvoiceCreatedEvent, CreateWalletCommand, ChannelOpenedEvent and others). If one file needs both, prefix one of them:

import 'package:libspiffy/coordinator.dart';
import 'package:libspiffy/internals.dart' as domain;

NodeRpcDataSource is removed in 5.0.0. It read proofs with gettxoutproof, which Teranode does not serve. To import wallet history, pass a WhatsOnChainDataSource or your own BlockchainDataSource to initialize().

Next

Start the library and create a wallet in the quick start. If you are upgrading an app from libspiffy 4.x, read its Upgrading from 4.x section first.