Tokenator

Tokenator is a flexible and lightweight TypeScript library for creating, updating, redeeming, and querying simple text-based tokens on the Bitcoin SV (BSV) blockchain.

Tokens are embedded using PushDrop scripts, can optionally be encrypted using the BSV SDK's BRC-2 encryption system, and support either local or overlay tracking modes.

Features

• Optional encryption and decryption of token data
• Local token tracking via wallet baskets
• Overlay tracking via broadcast and lookup services
• Simple API for creating, updating, redeeming, and listing tokens
• Built on @bsv/sdk

Installation

npm install @bsv/sdk

Then copy Tokenator.ts into your project.

Usage

Initialization

import { WalletClient } from '@bsv/sdk'
import { Tokenator } from './Tokenator'

const wallet = new WalletClient()

const tokenator = new Tokenator({
  protocol: [2, 'MyApp'],
  keyID: '1',
  tracking: 'local',          // or 'overlay'
  basket: 'my-basket',        // required for local mode
  encryptByDefault: true      // optional
}, wallet)

Create Token

await tokenator.createToken('My secure message')

This creates and broadcasts a token using the configured tracking mode (local basket or overlay topic). If encryptByDefault is set, the message will be encrypted automatically.

List Tokens

const tokens = await tokenator.listTokens()
// tokens: Array<{ message, token: { txid, outputIndex, lockingScript, satoshis, beef? } }>

By default:

• Includes beef, which is required to redeem or update tokens
• Decrypts messages if in local mode and encryption was used

Update Token

await tokenator.updateToken(tokens[0].token, 'Updated message')

Updates the given token output with a new message. Encryption is applied based on constructor settings (or can be overridden per call).

Redeem Token

await tokenator.redeemToken(tokens[0].token)

Spends (removes) the token by creating and signing a transaction that consumes it.

Tracking Modes

| Mode | Description | |----------|-----------------------------------------------------------------------------| | local | Tokens are stored in a wallet basket. No overlay broadcast is performed. | | overlay| Tokens are broadcast to a topic and queryable via a lookup overlay service.|

API Reference

Constructor

new Tokenator(options: TokenatorOptions, wallet?: WalletInterface)

TokenatorOptions

| Name | Type | Description | |-------------------|----------------------|--------------------------------------------| | protocol | [number, string] | Protocol ID and name | | keyId | string | Identifier for key derivation | | tracking | 'local' | 'overlay' | Token tracking mode | | basket | string? | Required if using local mode | | overlayTopic | string? | Topic name for overlay broadcast | | overlayService | string? | Lookup service name for overlay query | | encryptByDefault| boolean? | Automatically encrypt all messages |

Example: Public Notes with Overlay

const notes = new Tokenator({
  protocol: [99, 'Notes'],
  keyId: '1',
  tracking: 'overlay',
  overlayTopic: 'public_notes',
  overlayService: 'ls_notes'
}, wallet)

await notes.createToken('Hello, world!')
const results = await notes.listTokens({ limit: 5 })
console.log(results.map(n => n.message))

License

This library is licensed under the Open BSV License.