Skip to content

demo-example-scp.md

Latest commit

 

History

History
579 lines (445 loc) · 16.9 KB

demo-example-scp.md

File metadata and controls

579 lines (445 loc) · 16.9 KB

SCP Consensus - Comprehensive Learning Guide

This comprehensive guide walks you through Stellar Consensus Protocol (SCP), explaining the two-phase nomination and ballot process, quorum slices, and how flexible trust relationships enable consensus.

Understanding SCP Consensus

Core Principle

SCP uses Federated Byzantine Agreement (FBA) where each node defines its own quorum slice (set of trusted nodes). Consensus is reached when enough nodes in each quorum slice agree. Unlike BFT's fixed 2/3 threshold, SCP uses flexible, node-specific trust relationships.

Key Concepts

Quorum Slice:

  • Set of nodes that a particular node trusts
  • Each node defines its own quorum slice
  • In this implementation, quorum slice = self + all connected peers

Quorum:

  • Set of nodes that includes a quorum slice for each member
  • Consensus requires a quorum to be formed
  • Simplified: majority of quorum slice nodes must agree

Two-Phase Process:

  1. Nomination Phase: Node nominates a block for consideration
  2. Ballot Phase: Nodes vote (ballot) on the nominated block

Why Flexible Trust?

  • Nodes can have different trust relationships
  • Network can grow organically without reconfiguration
  • More realistic model of real-world trust
  • Allows asymmetric trust (A trusts B, but B might not trust A)

Complete Flow Example - 3 Node Network

Scenario Setup

  • Node 6001: Nominator (will nominate the block)
  • Node 6002: Voter (will ballot on the nomination)
  • Node 6003: Voter (will ballot on the nomination)
  • Quorum Slice Size: 3 nodes (self + 2 peers)
  • Required Votes: 2 out of 3 (majority of quorum slice = 50%)

Step 1: Node Nominates a Block

What happens: Node 6001 creates a new block, mines it, and nominates it to the network.

Terminal Output (Node 6001):

SCP-Node-6001> propose "Payment of $100 from Alice to Bob"

SCP-Node-6001 NOMINATING NEW BLOCK (SCP Nomination Phase):
   Data: "Payment of $100 from Alice to Bob"

MINING PHASE:
Mining block 1...
Target: Hash must start with 00
Mining attempt 10000: a7f3d2e1b5c8f9...
Mining attempt 20000: b2e8f4a9c1d7e3...
Block mined! Nonce: 23847, Hash: 00a7f3d2e1b5c8f9abc123def456...

NOMINATION PHASE:
   Nomination broadcast to 2 peers
   Waiting for quorum slice to accept nomination...

What to Observe:

  1. Nomination vs Proposal: In SCP, we "nominate" rather than "propose" - this is the first phase
  2. No Immediate Vote: Unlike BFT, the nominator doesn't immediately vote - it waits for others to accept the nomination
  3. Quorum Slice Reference: The system mentions "quorum slice" - this is SCP's trust model

Why This Matters:

  • Nomination is a suggestion, not a commitment
  • Other nodes must validate and accept the nomination
  • This two-phase approach allows for more flexible consensus

Key Difference from BFT:

  • BFT: Proposer immediately votes for its own block
  • SCP: Nominator waits for others to accept the nomination first

Step 2: Other Nodes Receive Nomination

What happens: Node 6002 and Node 6003 receive the nomination. They validate the block and create ballots (votes).

Terminal Output (Node 6002):

NOMINATION RECEIVED:
   From: SCP-Node-6001
   Block: 00a7f3d2e1b5c8f9...

BALLOT PHASE:
   Voted: ACCEPT for block 00a7f3d2e1b5c8f9...
   Current votes: 1/2 (need majority of quorum slice)

Terminal Output (Node 6003):

NOMINATION RECEIVED:
   From: SCP-Node-6001
   Block: 00a7f3d2e1b5c8f9...

BALLOT PHASE:
   Voted: ACCEPT for block 00a7f3d2e1b5c8f9...
   Current votes: 1/2 (need majority of quorum slice)

What to Observe:

  1. Validation First: Nodes validate the block before creating a ballot
  2. Ballot Creation: Each node creates its own ballot (vote) for the nomination
  3. Quorum Calculation: Each node calculates if it has a quorum (majority of its quorum slice)
  4. Vote Count: Initially 1 vote (self-vote), needs 2 for majority

Why This Matters:

  • Nodes independently validate before voting
  • Each node tracks votes based on its own quorum slice
  • The quorum slice determines how many votes are needed

Key Difference from BFT:

  • BFT: Fixed threshold (2/3 of all nodes)
  • SCP: Flexible threshold (majority of quorum slice, which varies per node)

Step 3: Ballots Are Broadcast and Received

What happens: Each node broadcasts its ballot to all peers. Nodes receive ballots and update their vote counts.

Terminal Output (Node 6001):

BALLOT RECEIVED:
   From: SCP-Node-6002
   Vote: ACCEPT
   Block: 00a7f3d2e1b5c8f9...
   Current votes: 2

Terminal Output (Node 6002):

BALLOT RECEIVED:
   From: SCP-Node-6003
   Vote: ACCEPT
   Block: 00a7f3d2e1b5c8f9...
   Current votes: 2

Terminal Output (Node 6003):

BALLOT RECEIVED:
   From: SCP-Node-6002
   Vote: ACCEPT
   Block: 00a7f3d2e1b5c8f9...
   Current votes: 2

What to Observe:

  1. Ballot Messages: These are the "votes" in SCP terminology
  2. Vote Aggregation: Each node tracks how many ballots it has received
  3. Quorum Check: When votes reach majority of quorum slice, quorum is reached
  4. Synchronization: All nodes see the same vote count as ballots are broadcast

Why This Matters:

  • Ballots are explicit votes on the nomination
  • Each node independently determines if quorum is reached
  • The quorum slice determines the threshold for each node

Key Learning:

  • In SCP, "ballot" = "vote"
  • Quorum is determined per node based on its quorum slice
  • Different nodes might have different quorum slices (in real SCP)

Step 4: Quorum Reached - Block Added to Blockchain

What happens: When a node determines that it has received a majority of votes from its quorum slice, it reaches quorum and adds the block.

Terminal Output (All Nodes):

QUORUM REACHED! (SCP Consensus):
   Block 1 has been accepted by the network!
   Final votes: 2 out of 3 quorum slice nodes
   Block added to blockchain (Total blocks: 2)

SUCCESS! NEW BLOCK OFFICIALLY ADDED TO BLOCKCHAIN!
   Block Index: 1
   Block Hash: 00a7f3d2e1b5c8f9abc123def456...
   Block Data: "Payment of $100 from Alice to Bob"
   Quorum Votes: 2 out of 3 quorum slice nodes
   Added at: 19/6/2025, 8:30:15 pm
   Blockchain Length: 2 blocks

All connected nodes now have this block in their blockchain!

BLOCK INFORMATION:
   Index: 1
   Previous Hash: 4702089da1945d07...
   Timestamp: 19/6/2025, 8:30:15 pm
   Data: "Payment of $100 from Alice to Bob"
   Nonce: 23847
   Hash: 00a7f3d2e1b5c8f9abc123def456...
   Votes: 0

CURRENT BLOCKCHAIN:
   Block 0: 4702089da194... | Data: "Genesis Block - The First Block"
   Block 1: 00a7f3d2e1b5... | Data: "Payment of $100 from Alice to Bob"
   Chain length: 2 blocks

What to Observe:

  1. Quorum Message: "QUORUM REACHED!" instead of "CONSENSUS REACHED!"
  2. Quorum Slice Reference: "2 out of 3 quorum slice nodes" - emphasizes the quorum slice model
  3. Finality: Once quorum is reached, block is permanent
  4. Synchronization: All nodes have the same blockchain

Why This Matters:

  • Quorum is the SCP equivalent of consensus
  • The quorum slice model allows flexible trust
  • All nodes reach quorum independently based on their own quorum slices

Key Difference from BFT:

  • BFT: "CONSENSUS REACHED! 2 out of 3 nodes"
  • SCP: "QUORUM REACHED! 2 out of 3 quorum slice nodes"
  • The terminology reflects the different trust models

Understanding Quorum Slices

How Quorum Slices Work

In This Implementation:

  • Each node's quorum slice = {self} + {all connected peers}
  • When Node 6001 connects to Node 6002, Node 6002 is added to Node 6001's quorum slice
  • Quorum slice size = 1 (self) + number of connected peers

Example:

Node 6001 connects to Node 6002:
   Quorum slice: {SCP-Node-6001, SCP-Node-6002}
   Size: 2
   Required votes: 2 (majority of 2 = 2)

Node 6001 connects to Node 6002 and Node 6003:
   Quorum slice: {SCP-Node-6001, SCP-Node-6002, SCP-Node-6003}
   Size: 3
   Required votes: 2 (majority of 3 = 2, rounded up)

What to Observe:

  • Use status command to see quorum slice:
SCP-Node-6001 STATUS:
   Status: IDLE
   Blockchain length: 2
   Quorum slice size: 3
   Quorum slice nodes: SCP-Node-6001, SCP-Node-6002, SCP-Node-6003

Key Learning:

  • Quorum slices are dynamic - they change as nodes connect/disconnect
  • Each node maintains its own quorum slice
  • The quorum slice determines how many votes are needed

Advanced Scenarios

Scenario 1: Asymmetric Quorum Slices

Setup:

  • Node 6001: Quorum slice = {6001, 6002}
  • Node 6002: Quorum slice = {6002, 6003}
  • Node 6003: Quorum slice = {6003, 6001}

What Happens: Each node has a different quorum slice, but they overlap. This is how real SCP works.

Key Learning:

  • Nodes can trust different sets of nodes
  • Quorum intersection ensures safety
  • More flexible than BFT's symmetric trust

Note: In this simplified implementation, all nodes have the same quorum slice (all connected nodes). Real SCP allows asymmetric quorum slices.

Scenario 2: Network Growth

Setup:

  • Start with 2 nodes (6001, 6002)
  • Add a 3rd node (6003)

What Happens:

Initial State (2 nodes):
   Quorum slice size: 2
   Required votes: 2 (majority of 2 = 2, which is 100%)

After Adding Node 6003:
   Quorum slice size: 3
   Required votes: 2 (majority of 3 = 2, which is 67%)

What to Observe:

  1. Quorum Slice Updates: When Node 6003 connects, all nodes update their quorum slices
  2. Threshold Changes: Required votes change from 2/2 (100%) to 2/3 (67%)
  3. No Reconfiguration: Network adapts automatically without manual threshold updates

Key Learning:

  • SCP adapts to network changes automatically
  • Quorum slices update as nodes join/leave
  • No need to manually recalculate thresholds

Key Difference from BFT:

  • BFT: Must manually recalculate 2/3 threshold when nodes join/leave
  • SCP: Quorum slices automatically adapt

Scenario 3: Nomination Before Connection

What happens if a node nominates before connecting to others?

Terminal Output:

SCP-Node-6001> propose "Transaction X"

SCP-Node-6001 NOMINATING NEW BLOCK:
   ...

NOMINATION PHASE:
   Nomination broadcast to 0 peers
   Waiting for quorum slice to accept nomination...

BALLOT PHASE:
   Voted: ACCEPT for block 00a7f3d2...
   Current votes: 1/1 (need majority of quorum slice)

What to Observe:

  • Quorum slice size = 1 (only self)
  • Required votes = 1 (majority of 1 = 1)
  • Consensus reached immediately (1/1 = 100%)

Key Learning:

  • Single node can reach consensus (100% of its quorum slice)
  • This is different from BFT, which needs multiple nodes
  • Shows the flexibility of SCP's quorum slice model

Scenario 4: Ballot Before Nomination

What happens if a ballot arrives before the nomination?

Terminal Output:

BALLOT RECEIVED:
   From: SCP-Node-6002
   Vote: ACCEPT
   Block: 00a7f3d2...

Received ballot for unknown nomination: 00a7f3d2...
   Note: Nomination must be received before ballots can be processed

What to Observe:

  • Ballots require nominations first
  • This ensures nodes know what they're voting on
  • Nominations provide the block data

Key Learning:

  • Two-phase process: Nomination → Ballot
  • Nominations must precede ballots
  • This prevents voting on unknown blocks

Understanding the Messages

Nomination Message

Structure:

{
  "type": "NOMINATION",
  "blockHash": "00a7f3d2e1b5c8f9...",
  "blockIndex": 1,
  "blockData": "Payment of $100...",
  "nominatorNodeId": "SCP-Node-6001",
  "block": {
    "index": 1,
    "previousHash": "4702089da194...",
    "data": "Payment of $100...",
    "hash": "00a7f3d2e1b5c8f9...",
    "nonce": 23847,
    "timestamp": 1234567890
  }
}

What Each Field Means:

  • type: Identifies this as a nomination message
  • blockHash: Unique identifier of the nominated block
  • nominatorNodeId: Which node is nominating
  • block: Complete block data (so recipients can validate)

Why Complete Block Data?

  • Recipients need to validate the block
  • They need all block information to create ballots
  • This is different from BFT, which only sends the hash

Ballot Message

Structure:

{
  "type": "BALLOT",
  "blockHash": "00a7f3d2e1b5c8f9...",
  "voterNodeId": "SCP-Node-6002",
  "vote": "ACCEPT"
}

What Each Field Means:

  • type: Identifies this as a ballot (vote) message
  • blockHash: Which block is being voted on
  • voterNodeId: Which node is casting the ballot
  • vote: "ACCEPT" or "REJECT" (in this implementation, always ACCEPT)

Why Simpler Than Nomination?

  • Ballots only need to reference the block (by hash)
  • The block data was already sent in the nomination
  • This reduces message size

Key Concepts Demonstrated

1. Federated Byzantine Agreement (FBA)

  • What it means: Each node defines its own trust relationships
  • How SCP achieves it: Quorum slices allow flexible trust
  • What you see: Nodes can have different quorum slices

2. Two-Phase Consensus

  • What it means: Nomination then Ballot, not immediate voting
  • How SCP achieves it: Separate nomination and ballot phases
  • What you see: Nomination received → Ballot created → Quorum reached

3. Flexible Trust

  • What it means: Nodes don't need to trust the same set
  • How SCP achieves it: Each node defines its quorum slice
  • What you see: Quorum slices can differ between nodes

4. Organic Network Growth

  • What it means: Network can grow without reconfiguration
  • How SCP achieves it: Quorum slices update automatically
  • What you see: Adding nodes updates quorum slices without manual changes

Experiments to Try

Experiment 1: Quorum Slice Observation

  1. Start Node 6001 alone
  2. Check status - observe quorum slice size = 1
  3. Connect to Node 6002
  4. Check status - observe quorum slice size = 2
  5. Connect to Node 6003
  6. Check status - observe quorum slice size = 3
  7. Question: How does quorum slice size affect required votes?

Experiment 2: Nomination vs Ballot Timing

  1. Start 3 nodes
  2. Have Node 6001 nominate a block
  3. Observe: Nomination received → Ballot created → Ballots exchanged
  4. Question: Why two phases instead of one?
  5. Answer: Allows nodes to validate before committing to vote

Experiment 3: Single Node Consensus

  1. Start Node 6001 alone
  2. Nominate a block
  3. Observe: Consensus reached immediately (1/1 = 100%)
  4. Question: Can BFT do this?
  5. Answer: No, BFT needs multiple nodes for 2/3 threshold

Experiment 4: Network Partition

  1. Start 3 nodes and connect them
  2. Nominate a block
  3. Disconnect one node
  4. Observe: Can remaining 2 nodes reach quorum?
  5. Answer: Yes, if their quorum slices still form a quorum

Comparison: SCP vs BFT

Trust Model

  • BFT: Symmetric - all nodes trust the same set
  • SCP: Asymmetric - each node defines its own quorum slice

Threshold

  • BFT: Fixed 2/3 of all nodes
  • SCP: Flexible - majority of each node's quorum slice

Network Growth

  • BFT: Requires threshold recalculation
  • SCP: Automatic quorum slice updates

Consensus Process

  • BFT: Propose → Vote → Consensus (single phase)
  • SCP: Nominate → Ballot → Quorum (two phases)

Single Node

  • BFT: Cannot reach consensus alone
  • SCP: Can reach consensus alone (100% of quorum slice)

Troubleshooting

Problem: Quorum Not Reaching

Symptoms:

BALLOT PHASE:
   Current votes: 1/2 (need majority of quorum slice)
   Need 1 more vote for quorum

Possible Causes:

  1. Not enough nodes in quorum slice: Need more connections
  2. Nodes not voting: Check if nominations are being received
  3. Network issues: Check connections with network command

Solution:

  • Connect more nodes to increase quorum slice size
  • Check that nominations are being received
  • Verify network connectivity

Problem: Nomination Not Received

Symptoms:

BALLOT RECEIVED:
   Received ballot for unknown nomination: 00a7f3d2...

Possible Causes:

  1. Nomination lost: Network issue prevented nomination delivery
  2. Timing issue: Ballot arrived before nomination
  3. Different blocks: Ballot is for a different block

Solution:

  • Nominations must arrive before ballots
  • Check network connectivity
  • Ensure all nodes are on the same network

Summary: What You've Learned

After going through these examples, you should understand:

  1. How SCP Works: Two-phase nomination and ballot process with quorum slices
  2. Why Quorum Slices: Allows flexible, asymmetric trust relationships
  3. Nomination Phase: Nodes suggest blocks for consideration
  4. Ballot Phase: Nodes vote on nominated blocks
  5. Quorum Calculation: Based on each node's quorum slice, not fixed threshold
  6. Network Adaptability: Quorum slices update automatically as network changes

Key Takeaway: SCP provides flexible consensus through quorum slices, making it ideal for networks where trust relationships are asymmetric and the network needs to grow organically without reconfiguration.