Skip to content
libspiffy

Introduction

This page tells you what libspiffy is, whether it fits your app, and where to go next.

libspiffy is a Dart library that puts a Bitcoin SV SPV wallet inside your application. It is built from actors (Dactor), keeps every wallet change as an event in an event store (Eventador), and validates the payments it receives with merkle proofs checked against block headers it keeps itself. These docs cover libspiffy 5.0.0 (pub.dev).

Who it is for

Section titled “Who it is for”

You are writing a Dart or Flutter app, or a Dart server, that holds keys and moves BSV: a mobile wallet, a point-of-sale app, a service that takes payments. You know what a UTXO, a transaction and a block header are. You do not want to write coin selection, BEEF handling and SPV checks yourself.

What it does

Section titled “What it does”
  • Creates and imports wallets: HD from a mnemonic, xpriv, WIF, or watch-only from an xpub.
  • Creates invoices, builds and signs payments as BEEF, and validates incoming BEEF against its own header chain before it credits the wallet.
  • Broadcasts through ARC (or Arcade, its Teranode-era successor) and pays ARC’s published policy fee rate.
  • Syncs block headers from the BSV P2P network, optionally starting from a header CDN.
  • Tracks UTXOs, reservations, deferred payments and payment channels, and answers balance and history queries from read models.
  • Lets plugins add script types and token protocols.

What it does not do

Section titled “What it does not do”
  • It is a library, not an app. There is no UI, no CLI and no server process. Your app starts it with LibSpiffyActorSystem.initialize() and talks to it through the coordinator: ask() sends a command and returns its reply.
  • It needs an ARC endpoint to broadcast. libspiffy does not relay transactions over P2P. It submits them to ARC or Arcade, and asks ARC for the fee rate every transaction pays. Plan for a reachable endpoint on every network you use (see Network, ARC & Arcade).
  • It uses P2P only for headers. Peers give it block headers. It never downloads blocks or scans the chain for your transactions; payments reach it as BEEF from the payer, or through an import from a blockchain data source.
  • It needs a database. Events and read models live in Isar (mobile and desktop) or PostgreSQL (servers). An in-memory backend exists for tests.
  • It does not create a wallet’s keys for you. Your app supplies a mnemonic (DartSVCryptoService().generateMnemonic() makes one), an xpriv, a WIF or an xpub, and backs it up.
  • It does not keep your keys safe by itself. Your app supplies a SecureStorage implementation backed by the platform keychain or similar. The default, InMemorySecureStorage, forgets every key on restart.

How these docs are organised

Section titled “How these docs are organised”