Overview

Sparkle Protocol enables trustless atomic swaps for Bitcoin Ordinals using Lightning Network payments. Trade inscriptions securely without intermediaries, custodial accounts, or private key exposure.

TL;DR: Pay Lightning, get Ordinal. Trustless. No custody risk.

Quick Start

Installation

npm install @sparkleprotocol/core

Basic Usage

import {
  createSparkleSwapAddress,
  generatePreimage,
  computePaymentHash,
} from '@sparkleprotocol/core';

// 1. Generate preimage and payment hash
const { preimage, preimageHex } = generatePreimage();
const paymentHash = computePaymentHash(preimage);

// 2. Create swap address
const swapAddress = createSparkleSwapAddress({
  sellerPubkey: SELLER_PUBKEY,
  buyerPubkey: BUYER_PUBKEY,
  paymentHash: paymentHashHex,
  timelockHeight: currentBlock + 144,
  network: 'mainnet',
});

// 3. Seller locks inscription to swapAddress.address
// 4. Buyer pays Lightning invoice
// 5. Buyer claims with preimage

Run Coordinator Server

git clone https://github.com/ProtocolSparkle/Sparkle-Protocol
cd Sparkle-Protocol && npm install
npx tsx src/coordinator/server.ts

Mainnet Proof

The protocol has been validated on Bitcoin mainnet:

| Component | Transaction ID | |-----------|---------------| | Lock TX | a3c6b08ed820194ee... | | Sweep TX | 9422e6cb358295d86... |

See proofs/ for full verification details.

How It Works

1. Seller creates Lightning hold invoice
2. Seller locks inscription in Taproot address with:
   - Claim path: requires preimage (revealed when buyer pays)
   - Refund path: available after timelock (if buyer abandons)
3. Buyer pays Lightning invoice
4. Payment reveals preimage
5. Buyer uses preimage to claim inscription
6. Seller receives Lightning payment

Result: Atomic exchange - both succeed or neither does

Security Properties

| Property | Guarantee | |----------|-----------| | Atomicity | Payment and transfer occur together or not at all | | Non-custodial | No third party holds funds or inscriptions | | Trustless | No trust required between buyer and seller | | Recoverable | Seller can always reclaim via timelock refund |

Coordinator API

| Endpoint | Method | Description | |----------|--------|-------------| | /health | GET | Health check and stats | | /api/swaps | GET | List active swaps | | /api/swaps/:id | GET | Get swap details | | /api/swaps | POST | Create new swap | | /api/stats | GET | Coordinator statistics |

Repository Structure

Sparkle-Protocol/
├── docs/               # Protocol documentation
├── proofs/             # Mainnet validation evidence
├── src/                # TypeScript SDK source
│   ├── core/          # Core swap primitives
│   ├── coordinator/   # Coordinator server
│   └── adapters/      # Wallet integrations
├── examples/           # Usage examples
├── tests/              # Test suite
└── LICENSE             # MIT License

Technical Specification

• Taproot (BIP-341) for script-path spending
• SHA256 hashlocks bound to Lightning payment hashes
• CLTV timelocks for seller refund protection
• Hold invoices for atomic settlement

Full specification: docs/SPECIFICATION.md

License

MIT License - see LICENSE

Links

• Website: https://sparkleprotocol.com
• NPM: https://www.npmjs.com/package/@sparkleprotocol/core
• Specification: docs/SPECIFICATION.md