OneBitcoin Plugin SDK

A framework for creating payment method plugins for the OneBitcoin modular payment app.

Features

• 📦 Simple Interface - Easy-to-implement PaymentPlugin interface
• 🔧 Base Class - Start quickly with the BasePlugin abstract class
• 💰 Multi-Currency - Support Bitcoin, Lightning, eCash, fiat, and more
• 🌍 Multi-Network - Mainnet, Testnet, Signet, Regtest
• 📱 Cross-Platform - Works on web, mobile, and desktop

Installation

npm install @onebitcoin/plugin-sdk

Quick Start

1. Create Your Plugin

import { BasePlugin, types } from '@onebitcoin/plugin-sdk';

export class MyLightningPlugin extends BasePlugin {
  readonly id = 'lightning';
  readonly name = 'Lightning Network';

  getInfo() {
    return {
      id: this.id,
      name: this.name,
      version: '1.0.0',
      description: 'Lightning Network payments',
      icon: '⚡',
      capabilities: {
        canSend: true,
        canReceive: true,
        canCreateWallet: true,
        supportsInvoices: true,
        supportsBatching: false,
        supportedAddressTypes: ['ln', 'lnurl']
      }
    };
  }

  async createWallet(config: types.WalletConfig): Promise<types.Wallet> {
    // Your implementation
    const wallet = await super.createWallet(config);
    wallet.address = 'lnbc1...'; // Lightning invoice
    return wallet;
  }

  async sendPayment(walletId: string, req: types.PaymentRequest): Promise<types.Transaction> {
    // Your implementation - pay Lightning invoice
    return {
      id: crypto.randomUUID(),
      amount: -req.amount,
      fee: 1,
      direction: 'send',
      status: 'confirmed',
      timestamp: Date.now() / 1000,
      confirmations: 1
    };
  }

  async receivePayment(walletId: string, req: types.ReceiveRequest): Promise<types.Invoice> {
    // Your implementation - create Lightning invoice
    return {
      id: crypto.randomUUID(),
      invoice: 'lnbc1...',
      amount: req.amount,
      memo: req.memo,
      expiresAt: Date.now() + 3600000
    };
  }
}

2. Register Your Plugin

import { PluginRegistry } from '@onebitcoin/app';
import { MyLightningPlugin } from './my-plugin';

const registry = new PluginRegistry();
registry.register(new MyLightningPlugin());

API Reference

Core Interface: PaymentPlugin

| Method | Description | |--------|-------------| | id | Unique plugin identifier | | name | Human-readable name | | getInfo() | Returns plugin metadata | | setNetwork() | Switch between mainnet/testnet | | getNetwork() | Get current network | | createWallet() | Create a new wallet | | deleteWallet() | Delete a wallet | | listWallets() | List all wallets | | getWallet() | Get specific wallet | | getBalance() | Get wallet balance | | sendPayment() | Send a payment | | receivePayment() | Generate receive invoice/address | | getTransactions() | Get transaction history | | sync() | Sync with external service |

Data Types

See types.ts for complete type definitions.

BasePlugin Class

The BasePlugin class provides default implementations for all methods. Override only what you need:

class MyPlugin extends BasePlugin {
  // Only override these required methods
  readonly id = 'my-plugin';
  readonly name = 'My Plugin';

  getInfo() { /* ... */ }

  // Override specific methods as needed
  async sendPayment(walletId, req) { /* custom implementation */ }
}

Example Plugins

Bitcoin Onchain

import { BasePlugin, types } from '@onebitcoin/plugin-sdk';

export class OnchainPlugin extends BasePlugin {
  readonly id = 'onchain';
  readonly name = 'Bitcoin Onchain';

  // Implements BIP-44 wallet derivation
  // Connects to Electrum servers
}

eCash (Cashu)

import { BasePlugin, types } from '@onebitcoin/plugin-sdk';

export class EcashPlugin extends BasePlugin {
  readonly id = 'ecash';
  readonly name = 'eCash (Cashu)';

  // Implements Cashu tokens
}

Publishing Your Plugin

1. Build Your Plugin

npm run build

2. Publish to NPM

npm publish

3. Users Install

npm install @yourorg/your-plugin

Development

Building

npm run build

Testing

npm test

License

MIT