← Back to Home

SIP-1: Sparkle Metadata Schema (v1)

STATUS: DRAFT
Type: Standard
Created: 2025-10-02
Author: David Michael

Abstract

This specification defines the JSON metadata schema for Sparkle Protocol inscriptions (version 1). It establishes canonicalization rules, required/optional fields, and upgrade semantics to ensure indexer consensus across implementations.

Motivation

Without a normative schema and canonicalization rules, different indexers will disagree on:

This SIP provides deterministic rules so all indexers reach the same state.

Specification

JSON Schema (v1)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Sparkle Inscription Metadata v1",
  "type": "object",
  "required": ["p", "v"],
  "properties": {
    "p": {
      "const": "sparkle",
      "description": "Protocol identifier"
    },
    "v": {
      "type": "integer",
      "const": 1,
      "description": "Protocol version"
    },
    "op": {
      "enum": ["deploy", "config"],
      "description": "Operation type"
    },
    "layers": {
      "type": "array",
      "description": "Recursive parent inscription IDs",
      "items": {
        "type": "object",
        "required": ["id"],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}i[0-9]+$",
            "description": "Parent inscription ID"
          },
          "z": {
            "type": "integer",
            "minimum": 0,
            "description": "Layer z-index (0 = bottom)"
          }
        }
      }
    },
    "lightning": {
      "type": "object",
      "description": "Lightning Network configuration",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Enable Lightning trades"
        },
        "network": {
          "enum": ["mainnet", "testnet", "regtest"],
          "description": "Bitcoin network"
        },
        "htlc_timeout": {
          "type": "integer",
          "minimum": 18,
          "maximum": 1008,
          "description": "HTLC timeout in blocks"
        }
      }
    },
    "meta": {
      "type": "object",
      "description": "Optional metadata",
      "properties": {
        "name": { "type": "string" },
        "description": { "type": "string" },
        "attributes": { "type": "array" }
      }
    }
  },
  "additionalProperties": false
}

Canonicalization Rules

  1. Key Ordering: Alphabetical by key name
  2. Whitespace: No whitespace between tokens (compact JSON)
  3. Unicode: UTF-8 encoding, escaped control characters
  4. Numbers: No leading zeros, no trailing decimals

Example: Valid Sparkle v1 Inscription

{"layers":[{"id":"abc123...i0","z":0},{"id":"def456...i0","z":1}],"lightning":{"enabled":true,"network":"mainnet"},"meta":{"name":"NFT #1"},"op":"deploy","p":"sparkle","v":1}

Validation Rules

Backwards Compatibility

Version 1 is the initial specification. Future versions will be defined in separate SIPs and MUST NOT break v1 indexer implementations.

Security Considerations

See Also