Bitcoin SPV Integration Map

Bitcoin SPV Integration Map

Phase: 0 - Reference Model & Threat Formalization Status: Exploratory / Research Draft

1. Overview

This document maps how Bitcoin SPV verification integrates with Zenon’s existing architectural primitives. It identifies touchpoints, data flows, and the responsibilities of each network component.

2. Architectural Components

2.1 Zenon Primitives Involved

2.2 Bitcoin Primitives Required

3. Data Flow

3.1 Verification Flow

1. External: Bitcoin transaction is confirmed
2. Header Source: Provides Bitcoin headers to Zenon
3. Account: Receives SPV proof (headers + Merkle branch)
4. Account: Executes local verification
5. Account: Updates local state with verified fact
6. Momentum: Includes account-block in next Momentum
7. Network: Verified fact is now globally visible

3.2 Query Flow

1. Querier: Requests Bitcoin fact from account state
2. Sentry/Sentinel: Retrieves account state (or state proof)
3. Querier: Receives verified fact with Zenon state proof
4. Querier: Can verify fact is checkpointed without re-verifying SPV

4. Component Responsibilities

4.1 Header Providers

What they do:

• Connect to Bitcoin network (P2P or API)
• Maintain Bitcoin header chain
• Serve headers to requesting accounts
• May announce new tips to the network

Trust model:

• Multiple independent sources reduce eclipse risk
• Threshold agreement on chain tip recommended
• Invalid headers are detectable (PoW verification)

4.2 Verifying Accounts

What they do:

• Receive SPV proofs from users or other sources
• Execute full SPV verification locally
• Record verified facts in account state
• Pay verification cost (Plasma)

Trust model:

• Account is responsible for verification correctness
• Account chooses confirmation depth requirements
• Other accounts can rely on verified facts (trusting the verifier)

4.3 Momentum Producers (Pillars)

What they do:

• Include valid account-blocks in Momentum
• Do NOT re-execute SPV verification
• Checkpoint the resulting state

Trust model:

• Pillars trust that account verification was performed correctly
• Invalid account states would require fraud proof mechanism
• Pillar consensus provides finality for checkpointed facts

4.4 Proof Servers (Sentinels/Sentries)

What they do:

• Serve state proofs to light clients
• May bundle Bitcoin facts with account state
• Cache frequently requested data

Trust model:

• Serving valid proofs is verifiable
• Light clients verify Momentum anchors
• No trust required if proofs are verified

5. State Storage

5.1 Per-Account State

Each account maintains:

btc_facts: []BtcFact {
    tx_hash:      [32]byte
    block_hash:   [32]byte
    depth:        uint16
    verified_at:  uint64  // Momentum height
}

5.2 Network-Wide State

Momentum includes:

• Hash of all account states (including Bitcoin facts)
• No explicit Bitcoin header storage in consensus

5.3 Optional Infrastructure State

Header providers may maintain:

• Full Bitcoin header chain (~70 MB)
• Recent headers only (configurable)
• Chainwork calculations

6. Integration Points

6.1 ACI Integration

New ACI methods:

VerifyBitcoinSPV(proof) -> fact_id
GetBitcoinFact(tx_hash) -> BtcFact
ListBitcoinFacts(offset, limit) -> []BtcFact

6.2 SDK Integration

New SDK functions:

// Verification
account.verifyBitcoinSPV(proof: SPVProof): Promise<FactId>
 
// Queries
account.getBitcoinFact(txHash: string): Promise<BtcFact>
account.listBitcoinFacts(): Promise<BtcFact[]>

6.3 RPC Integration

New RPC endpoints:

btc.verifySpv(account, proof) -> fact_id
btc.getFact(account, tx_hash) -> fact
btc.listFacts(account) -> [fact]

7. Cross-Component Interactions

7.1 Account ↔ Header Provider

Account requests: GetHeaders(start_height, count)
Provider responds: [BitcoinHeader]
Account verifies: PoW and chain linkage

7.2 Account ↔ Momentum

Account submits: Account-block with Bitcoin fact
Momentum includes: Account-block in Momentum
Momentum commits: State hash including fact

7.3 Light Client ↔ Sentinel

Client requests: StatefulAccount(account_id)
Sentinel responds: Account state + Momentum proof
Client verifies: Momentum signature chain
Client reads: Bitcoin facts from state

8. Failure Modes

8.1 Header Unavailability

Symptom: Cannot obtain Bitcoin headers Impact: Cannot verify new proofs Mitigation: Multiple header sources, caching

8.2 Stale Headers

Symptom: Header sources behind Bitcoin tip Impact: Recent transactions not verifiable Mitigation: Source monitoring, freshness requirements

8.3 Verification Failure

Symptom: Valid-looking proof fails verification Impact: Transaction not recorded as verified Mitigation: Error reporting, proof debugging

8.4 State Inconsistency

Symptom: Account state doesn’t match expected Impact: Downstream applications fail Mitigation: State proof verification, reconciliation

9. Upgrade Considerations

9.1 Adding New Verification Features

• New ACI methods can be added without breaking existing
• Version field in proof structure for format evolution
• Backward compatibility for stored facts

9.2 Changing Verification Rules

• Requires careful migration
• Old facts remain valid under old rules
• New proofs use new rules

9.3 Protocol-Level Integration

• Would require Zenon protocol upgrade
• Assessment criteria defined in Phase 5 docs
• Not required for Phases 1-4

10. Summary

Bitcoin SPV integrates with Zenon through:

1. Account-chains: Store verified facts locally
2. Momentum: Checkpoints facts without re-verification
3. Header providers: Supply Bitcoin chain data
4. Proof servers: Distribute verified facts to light clients

The integration is designed to be:

• Minimal: Doesn’t change Zenon’s core consensus
• Optional: Only involved accounts pay costs
• Composable: Works with existing Zenon primitives
• Upgradeable: Can evolve without breaking changes

Document Type: Architecture Map Status: Draft