libtokensv

libtokensv is a Dart package that teaches a libspiffy wallet about tokens. It is made up of three parts:

• PushDrop, the token format that BRC-100 overlay services use. A PushDrop token keeps its data fields inside a spendable Output which is locked to a key. Message box advertisements, as well as the SHIP and SLAP host advertisements, are PushDrop tokens.
• Lineage Tokens, a family of covenant tokens: an NFT, a fungible token, and the fuelled, voucher, note and listed variants of the NFT. Each transfer proves, in Script and on chain, that the token descends from an issuance which its Issuer signed. The token’s rules are enforced by the nodes, so a wallet needs no indexer or token server to check a token it is paid.
• OverlayClient, a client for BSV overlay services. It performs BRC-24 lookups and BRC-22 submissions, and discovers hosts through SLAP and SHIP.

Each kind of token comes with its own libspiffy plugin. This means the wallet funds, signs, records and broadcasts token Transactions in the same way that it handles ordinary payments.

This documentation covers libtokensv 0.2.0.

Who it is for

These pages are written for Dart and Flutter developers who are building a wallet app on libspiffy, and who would like that app to issue, hold, send or check tokens. We will assume that you know how a libspiffy wallet is set up and how it pays an invoice. libspiffy.dev covers that ground. You do not need to know the token scripts themselves, since libtokensv builds and checks them for you.

For the Bitcoin background (Scripts, Transactions, Signatures) the Developer Guide is the place to start, in particular the sections on Bitcoin Script and Transactions.

How it fits with dartsv and libspiffy

Package	What it does here
dartsv	Keys, Scripts, Transactions and the Script interpreter. libtokensv writes its Scripts and Transactions with it, and its tests run every token spend through dartsv’s interpreter.
libspiffy	The wallet: an actor-based SPV wallet that selects coins, signs, records Transactions, builds BEEF and talks to ARC. libtokensv plugs into it through libspiffy’s TransactionBuilderPlugin interface, and libspiffy itself is left unchanged.
libtokensv	The token formats, the builders that make token Transactions from raw bytes, the checks a payee runs on a token it receives, and the plugins that allow libspiffy to move tokens.

It should be noted that you can use the builders without a wallet at all. They take keys and coins, and hand back raw Transactions. Inside a libspiffy wallet, the plugins are the way to use them.

Which token do I want?

You want	Use	Page
To publish data that a BRC-100 overlay indexes (a message box host, a SHIP or SLAP advertisement)	PushDrop	PushDrop
One unique item: a ticket, a certificate, a collectible	Covenant NFT	NFT
Amounts that split and merge: points, credits, shares	Fungible token	Fungible token
A unique item that holders can move without owning any coins	Fuelled NFT	Fuelled NFT
A gift card, coupon, badge or licence that goes back to the Issuer	Voucher NFT	Voucher NFT
A claim on satoshis that pays out by rules: a deposit, a time-locked claim, a callable claim	Note NFT	Note NFT
An item that anyone may buy at a posted price, without the owner being online	Listed NFT	Listed NFT
To sell a token for satoshis in a single Transaction	The swap, or a fuelled sale version	Sales and swaps

Choosing a token compares them in more detail.

Installation

dependencies:
  libtokensv: 0.2.0

libtokensv depends on dartsv (^3.1.1) and libspiffy (^5.4.0). The examples on these pages run against dartsv 3.1.2 and libspiffy 5.11.0. Getting started shows how to set it up inside a wallet.

Every code example on these pages is a region of a test in the site’s examples/libtokensv package, which runs against libtokensv 0.2.0. The tests build each Transaction offline, and run every token spend through dartsv’s Script interpreter, as a node would.

The docs

Getting startedInstalling the package, and registering the plugins in a libspiffy wallet.

PushDropData fields locked to a key, the way BRC-100 overlays use them.

Overlay servicesLooking up and submitting to BSV overlay services.

Lineage tokensWhat a Lineage Token proves, and what the payee checks.

Wallet pluginsMoving tokens through a libspiffy wallet.

Host security rulesWhat every app that hosts the plugins must do.

SecurityFor researchers: the threat model, every attack the tests try, and the open questions.

Reference

• API reference: pub.dev/documentation/libtokensv
• Package: pub.dev/packages/libtokensv
• Source: github.com/twostack/libtokensv

Status

The Lineage Tokens have been tested through the Script interpreter and mined on a regtest node, but at the time of writing they have not been used on mainnet. Their transfer message format (i.e. how a sender hands a token to a payee) is not settled yet either. For now, each app defines its own.