Developer SDK Reference

STATUS: PROPOSED API ONLY
This SDK is not yet implemented. The code below shows the intended API design. No npm package exists. Integration requires using ord CLI + Spark SDK separately until this is built.

Installation

# PROPOSED (not yet published):
# npm install @sparkle-protocol/sdk

# CURRENT REALITY:
# No npm package exists. Use ord CLI directly for inscriptions.
# Use @buildonspark/spark-sdk separately for Lightning payments.

Core Classes

SparkleClient

Main client for interacting with Sparkle Protocol

Constructor

import { SparkleClient } from '@sparkle-protocol/sdk';

const client = new SparkleClient({
    network: 'mainnet', // or 'testnet', 'regtest'
    ordEndpoint: 'http://localhost:8080',
    sparkEndpoint: 'https://spark.money',
    bitcoinRPC: {
        host: '127.0.0.1',
        port: 8332,
        username: 'user',
        password: 'pass'
    }
});

Methods

Method	Parameters	Returns	Description
`inscribeLayer`	file: Buffer, feeRate: number	Promise<InscriptionResult>	Inscribe a single layer file
`createNFT`	layers: string[], metadata: object	Promise<NFTResult>	Create recursive NFT from layers
`enableLightning`	inscriptionId: string	Promise<LightningResult>	Add Lightning capability to NFT
`tradeLightning`	nftId: string, price: number	Promise<TradeResult>	Execute Lightning trade

SparkleIndexer

Service for indexing Sparkle Protocol NFTs

Constructor

import { SparkleIndexer } from '@sparkle-protocol/sdk';

const indexer = new SparkleIndexer({
    database: {
        type: 'postgres',
        host: 'localhost',
        port: 5432,
        database: 'sparkle',
        username: 'sparkle',
        password: 'sparkle'
    },
    ordEndpoint: 'http://localhost:8080',
    scanInterval: 60000 // 1 minute
});

// Start indexing
await indexer.start();

Methods

Method	Parameters	Returns
`scanBlock`	blockHeight: number	Promise<ScanResult>
`getSparkleNFTs`	filter: FilterOptions	Promise<NFT[]>
`verifyProtocol`	inscriptionId: string	Promise<boolean>

Complete Example: Inscribe Collection

// PROPOSED API DESIGN - NOT YET IMPLEMENTED
// @sparkle-protocol/sdk does not exist yet
// @buildonspark/spark-sdk is real (separate project for Lightning payments)

import { SparkleClient } from '@sparkle-protocol/sdk'; // DOES NOT EXIST
import { SparkWallet } from '@buildonspark/spark-sdk'; // EXISTS (Spark SDK only)
import fs from 'fs';

async function inscribeCollection() {
    // Initialize clients
    const sparkle = new SparkleClient({
        network: 'testnet',
        ordEndpoint: 'http://localhost:8080'
    });

    const spark = await SparkWallet.initialize({
        options: { network: 'TESTNET' }
    });

    // Step 1: Inscribe base layers
    const layers = {
        backgrounds: [],
        bodies: [],
        eyes: []
    };

    // Inscribe backgrounds
    for (let i = 1; i <= 20; i++) {
        const file = fs.readFileSync(`./layers/bg_${i}.svg`);
        const result = await sparkle.inscribeLayer(file, 10);
        layers.backgrounds.push(result.inscriptionId);
        console.log(`Inscribed background ${i}: ${result.inscriptionId}`);
    }

    // Step 2: Create NFTs with recursive references
    const nfts = [];
    for (let i = 0; i < 100; i++) {
        const nft = await sparkle.createNFT({
            layers: [
                layers.backgrounds[i % 20],
                layers.bodies[i % 20],
                layers.eyes[i % 30]
            ],
            metadata: {
                name: `Sparkle #${i}`,
                lightning: true
            }
        });
        nfts.push(nft);
    }

    // Step 3: Enable Lightning trading
    for (const nft of nfts) {
        await sparkle.enableLightning(nft.inscriptionId);
    }

    return nfts;
}

Trading Flow Example

// Example of Lightning-enabled NFT trade

async function tradeNFT(nftId, sellerClient, buyerClient) {
    // Seller creates Lightning invoice
    const invoice = await sellerClient.createTradeInvoice({
        nftId: nftId,
        price: 100000, // satoshis
        timeout: 3600 // 1 hour
    });

    // Buyer pays via Lightning
    const payment = await buyerClient.payInvoice({
        invoice: invoice.paymentRequest,
        maxFee: 100 // max routing fee
    });

    if (payment.status === 'SUCCESS') {
        // Atomic swap triggered
        // NFT ownership transfers on-chain
        const transfer = await sellerClient.completeTransfer({
            nftId: nftId,
            paymentPreimage: payment.preimage,
            buyerAddress: buyerClient.address
        });

        return {
            success: true,
            txid: transfer.txid,
            lightningPayment: payment.paymentHash
        };
    }
}

Event System

WebSocket Events

// Subscribe to real-time updates
const ws = sparkle.subscribe();

ws.on('inscription:new', (data) => {
    if (data.protocol === 'sparkle') {
        console.log('New Sparkle NFT:', data.inscriptionId);
    }
});

ws.on('trade:initiated', (data) => {
    console.log('Trade started:', data.nftId, data.invoice);
});

ws.on('trade:completed', (data) => {
    console.log('Trade completed:', data.nftId, data.txid);
});

ws.on('lightning:payment', (data) => {
    console.log('Lightning payment:', data.paymentHash);
});

Error Handling

try {
    const nft = await sparkle.createNFT({...});
} catch (error) {
    if (error.code === 'INSUFFICIENT_FUNDS') {
        console.error('Not enough BTC for inscription');
    } else if (error.code === 'INVALID_LAYER') {
        console.error('Layer inscription not found');
    } else if (error.code === 'LIGHTNING_OFFLINE') {
        console.error('Lightning node not reachable');
    }
}

Database Schema

-- Required tables for indexer
CREATE TABLE sparkle_nfts (
    id SERIAL PRIMARY KEY,
    inscription_id VARCHAR(66) UNIQUE NOT NULL,
    block_height INTEGER NOT NULL,
    metadata JSONB NOT NULL,
    lightning_enabled BOOLEAN DEFAULT false,
    owner_address VARCHAR(62),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE sparkle_layers (
    id SERIAL PRIMARY KEY,
    inscription_id VARCHAR(66) UNIQUE NOT NULL,
    layer_type VARCHAR(50) NOT NULL,
    file_hash VARCHAR(64) NOT NULL,
    file_size INTEGER NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE sparkle_trades (
    id SERIAL PRIMARY KEY,
    nft_id VARCHAR(66) NOT NULL,
    seller_address VARCHAR(62) NOT NULL,
    buyer_address VARCHAR(62) NOT NULL,
    price_sats BIGINT NOT NULL,
    lightning_invoice TEXT,
    payment_hash VARCHAR(64),
    status VARCHAR(20) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW(),
    completed_at TIMESTAMP
);

CREATE INDEX idx_sparkle_owner ON sparkle_nfts(owner_address);
CREATE INDEX idx_sparkle_lightning ON sparkle_nfts(lightning_enabled);
CREATE INDEX idx_trade_status ON sparkle_trades(status);

Configuration File

// sparkle.config.json
{
    "network": "mainnet",
    "endpoints": {
        "ord": "http://localhost:8080",
        "bitcoin": "http://localhost:8332",
        "spark": "https://spark.money"
    },
    "inscription": {
        "defaultFeeRate": 10,
        "batchSize": 20,
        "maxRetries": 3
    },
    "lightning": {
        "channelCapacity": 10000000,
        "routingFeeLimit": 1000,
        "invoiceExpiry": 3600
    },
    "indexer": {
        "scanInterval": 60000,
        "confirmations": 6,
        "database": {
            "type": "postgres",
            "connectionString": "postgresql://sparkle:sparkle@localhost/sparkle"
        }
    }
}

What Actually Exists vs What's Needed

Component	Exists Today	Needs Building
ord inscriptions	[OK] Working	Integration wrapper
spark.money SDK	[OK] Available	NFT-specific methods
SparkleClient class	✗ Not built	Complete implementation
SparkleIndexer	✗ Not built	Full indexer service
WebSocket events	✗ Not built	Event system
Database schema	Designed	Implementation
Error handling	✗ Not built	Error classes
npm package	✗ Not published	Build & publish

Reality Check

To use this SDK, someone needs to:

Implement all the classes shown above (~2000 lines of code)
Test with real Bitcoin/Lightning transactions
Deploy indexer infrastructure
Create npm package and publish
Write real documentation with working examples
Maintain and update as ord protocol evolves

Estimated effort: 400-600 hours of development