SIP-2: Upgrade and Reinscription Semantics

Abstract

This specification defines how Sparkle Protocol handles upgrades, reinscriptions, and conflicting metadata. It establishes deterministic rules for ownership verification, parent/child ordering, and replay protection.

Motivation

NFT owners need the ability to upgrade Lightning configuration or metadata without re-inscribing the entire NFT. Without clear upgrade rules, indexers will disagree on which metadata is authoritative.

Specification

Upgrade Operation

An upgrade inscription MUST:

1. Reference the parent inscription ID in a "parent" field
2. Be inscribed to the same address that owned the parent at upgrade block height
3. Include "op": "config" to signal an upgrade

Example Upgrade Inscription

{
  "p": "sparkle",
  "v": 1,
  "op": "config",
  "parent": "abc123...i0",
  "lightning": {
    "enabled": false
  }
}

Conflict Resolution Rules

When multiple upgrades exist for the same parent:

1. Higher block height wins: Later upgrades override earlier ones
2. Owner-at-height check: Only valid if inscriber owned parent at that block
3. Tie-breaker: If same block, lower transaction index wins

Ownership Verification Algorithm

function isValidUpgrade(upgrade, parent, blockHeight) {
  // 1. Check parent reference
  if (upgrade.parent !== parent.inscriptionId) {
    return false;
  }

  // 2. Get parent owner at upgrade block
  const parentOwner = getOwnerAtBlock(parent, blockHeight);

  // 3. Check upgrade inscriber matches parent owner
  const upgradeInscriber = getInscriptionAddress(upgrade);

  return upgradeInscriber === parentOwner;
}

Replay Protection

To prevent cross-network replay attacks:

• Upgrades MUST include "network" field matching parent network
• Indexers MUST reject upgrades with mismatched networks
• Genesis inscriptions SHOULD specify network explicitly

State Merging

When applying an upgrade:

• Specified fields override parent values
• Unspecified fields inherit from parent
• Arrays are replaced entirely (no merging)
• Objects are shallow-merged (top-level keys only)

Example State Evolution

// Genesis inscription (block 100)
{
  "p": "sparkle",
  "v": 1,
  "op": "deploy",
  "layers": [{"id": "layer1...i0", "z": 0}],
  "lightning": {"enabled": true, "network": "mainnet"},
  "meta": {"name": "NFT #1"}
}

// Upgrade inscription (block 200)
{
  "p": "sparkle",
  "v": 1,
  "op": "config",
  "parent": "genesis...i0",
  "lightning": {"enabled": false}
}

// Effective state after block 200
{
  "p": "sparkle",
  "v": 1,
  "layers": [{"id": "layer1...i0", "z": 0}],  // inherited
  "lightning": {"enabled": false, "network": "mainnet"},  // merged
  "meta": {"name": "NFT #1"}  // inherited
}

Indexer Requirements

1. MUST track ownership history for each inscription
2. MUST validate owner-at-height for all upgrades
3. MUST apply upgrades in chronological order
4. MUST reject upgrades from non-owners

Security Considerations

• Reorg Handling: Indexers MUST recompute state after reorgs deeper than 6 blocks
• DoS Prevention: Limit to 100 upgrades per parent inscription
• Spam Protection: Indexers MAY require minimum fee rate for upgrade inscriptions

Backwards Compatibility

This upgrade mechanism is forwards-compatible. Indexers that don't implement SIP-2 will treat upgrades as independent inscriptions, which degrades gracefully.