Technical Specification

Table of Contents

1. sparkle_genesis - Collection Metadata
2. sparkle_child - Per-Inscription Metadata
3. sparkle_checkout - Lightning Checkout
4. Validation Rules
5. Sparkle Swap - Trustless Atomic Swaps
6. Implementation Guidelines

1. sparkle_genesis

Collection-level metadata inscribed once per collection. This inscription acts as the canonical source for collection information.

1.1 JSON Schema

{
  "p": "sparkle",
  "op": "genesis",
  "version": 1,
  "collection": {
    "name": "Darkita",
    "symbol": "DARKITA",
    "description": "10K PFP collection with Lightning-ready checkout.",
    "supply": 10000,
    "creator": {
      "name": "Creator Name",
      "website": "https://example.com",
      "pubkey": "optional-hex-or-nostr-pubkey"
    }
  },
  "spark": {
    "enabled": true,
    "networks": ["spark", "ln-mainnet"]
  },
  "royalties": {
    "bps": 500,
    "recipients": [
      {
        "label": "creator",
        "lightning_address": "creator@example.com",
        "ln_node_pubkey": "optional-ln-node-pubkey"
      }
    ]
  }
}

1.2 Field Definitions

1.3 Usage Notes

• Inscribe this JSON as the first inscription for your collection
• The resulting inscription ID becomes the collection reference for all child NFTs
• Indexers scan for p: "sparkle", op: "genesis" to discover collections
• Supply is a soft commitment; enforcement is social, not consensus-level

2. sparkle_child

Per-inscription metadata attached to each NFT in the collection.

2.1 JSON Schema

{
  "p": "sparkle",
  "op": "child",
  "version": 1,
  "collection_ref": "<GENESIS_INSCRIPTION_ID>",
  "token": {
    "id": 123,
    "name": "Darkita #123"
  },
  "media": {
    "type": "image/png",
    "recursive_parents": [
      "<PARENT_INSCRIPTION_ID_1>",
      "<PARENT_INSCRIPTION_ID_2>"
    ]
  },
  "traits": {
    "Background": "Yellow",
    "Eyes": "Glowing",
    "Accessory": "None"
  }
}

2.2 Field Definitions

2.3 Usage Notes

• Minimal valid child requires only collection_ref and token.id
• Recursive parents enable cost-efficient collections through trait inscription reuse
• Traits are optional but improve marketplace discovery

3. sparkle_checkout

Lightning/Spark checkout object agreed upon by wallets, markets, and coordinators before payment.

3.1 JSON Schema

{
  "p": "sparkle",
  "op": "checkout",
  "version": 1,
  "inscription_id": "<INSCRIPTION_ID_BEING_BOUGHT>",
  "collection_ref": "<GENESIS_INSCRIPTION_ID>",
  "buyer": {
    "ord_address": "bc1p...buyer...",
    "lightning_address": "buyer@example.com",
    "ln_node_pubkey": "optional-ln-node-pubkey"
  },
  "network": "spark",
  "max_total_sats": 1500000,
  "pricing": {
    "seller_sats": 1400000,
    "creator_royalty_sats": 20000,
    "market_fee_sats": 30000,
    "estimated_l1_fee_sats": 50000
  },
  "market": {
    "id": "example.market",
    "name": "Example Market"
  },
  "expiry_block": 900000,
  "buyer_sig": "<optional-signature>"
}

3.2 Field Definitions

4. Validation Rules

4.1 Rule 1: Sum Check

max_total_sats MUST equal the sum of all fields in pricing:

max_total_sats = seller_sats + creator_royalty_sats + market_fee_sats + estimated_l1_fee_sats

4.2 Rule 2: Royalty Check

creator_royalty_sats SHOULD be calculated based on the genesis bps value. Markets SHOULD warn if royalty exceeds genesis declaration.

4.3 Rule 3: Display Requirement

Wallets MUST display complete pricing breakdown before payment confirmation.

4.4 Rule 4: Network Match

Payment must be processed on the network specified in the network field.

5. Sparkle Swap - Trustless Atomic Swaps

Sparkle Swap enables trustless ordinal trading using Taproot hashlock scripts. The atomic swap guarantees that either both parties get what they want, or nothing happens.

5.1 Security Model

• Non-custodial: Coordinator never holds keys or funds
• Delta-safe timelocks: Refund timeout = 2x claim window to prevent race conditions
• Buyer deposit: 1% non-refundable deposit prevents free option exploit
• Atomic: Lightning payment reveals preimage that unlocks on-chain ordinal

5.2 Taproot Script Structure

// Buyer Claim Path (hashlock)
OP_SHA256 <payment_hash> OP_EQUALVERIFY <buyer_pubkey> OP_CHECKSIG

// Seller Refund Path (timelock)
<locktime> OP_CHECKLOCKTIMEVERIFY OP_DROP <seller_pubkey> OP_CHECKSIG

5.3 Trade Flow

5.4 Delta-Safety Guarantee

To prevent race conditions during blockchain reorgs:

• Buyer has claimWindowBlocks (default: 144 blocks / ~24 hours) to claim after paying Lightning
• Seller refund only available after 2 × claimWindowBlocks (default: 288 blocks / ~48 hours)
• This 2x safety margin ensures buyer can survive mempool congestion and minor reorgs

5.5 Lightning Compatibility

Sparkle Swap is Lightning-agnostic and works with:

• LND (Lightning Labs)
• Core Lightning / CLN (Blockstream)
• Eclair (ACINQ)
• LDK (Lightning Dev Kit)
• Any BOLT-compliant Lightning implementation

6. Implementation Guidelines

6.1 For Creators

1. Inscribe sparkle_genesis JSON as first collection inscription
2. Record the genesis inscription ID
3. Reference genesis ID in all sparkle_child inscriptions
4. Set spark.enabled: true if supporting Lightning checkout

6.2 For Marketplaces

1. Index inscriptions containing p: "sparkle"
2. Build collection structures from genesis references
3. Generate sparkle_checkout objects for listings
4. Integrate with Sparkle Swap coordinator for trustless trades

6.3 For Wallets

1. Parse and validate sparkle_checkout objects
2. Display complete fee breakdown to users
3. Warn if fees exceed genesis royalty declaration
4. Process Lightning payments per network field

6.4 For Indexers

1. Scan for inscriptions with p: "sparkle"
2. Build collection graphs from collection_ref references
3. Track child counts against declared supply
4. Identify Lightning-enabled collections

References

• Coordinator API Documentation
• Example Collection Implementation
• Ordinals Protocol Documentation