Quorum

#Overview

The QuorumManager determines when a conflict has been resolved. After each vote is stored, it retallies the conflict to check if any competing block has reached the required 67% of total delegated weight. When quorum is reached, the winning block is confirmed, losers are rejected, and all conflict state is cleaned up.

#Quorum Threshold

A block reaches quorum when its accumulated vote weight meets or exceeds 67% of the total delegated XE weight:

blockWeight * 100 >= totalWeight * 67

Both sides of the comparison use big.Int arithmetic to prevent overflow:

1const (2    quorumNumerator   = 673    quorumDenominator = 1004)5 6bigThreshold := new(big.Int).Mul(bigTotal, big.NewInt(quorumNumerator))7bigBlock := new(big.Int).Mul(blockWeight, big.NewInt(quorumDenominator))8if bigBlock.Cmp(bigThreshold) >= 0 {9    // quorum reached10}

The totalWeight used as the denominator comes from the weight snapshot taken at conflict detection time. If no snapshot is available, the current total delegated weight is used as a fallback.

#Tallying: OnVote()

OnVote is called by the VoteManager after each successfully stored vote. It triggers a retally of the referenced conflict.

#Process

1. Look up the conflict record from the ConflictStore
2. Verify the voted block is part of this conflict's BlockHashes
3. Acquire the quorum mutex (serializes tallying)
4. Call tallyConflict() to check for quorum
5. If quorum reached, call confirmConflict() to finalize

#tallyConflict()

Groups all votes for the conflict by BlockHash, summing weights with big.Int:

1weightByBlock := make(map[string]*big.Int)2for _, v := range votes {3    weightByBlock[v.BlockHash].Add(weightByBlock[v.BlockHash],4        new(big.Int).SetUint64(v.Weight))5}

Then checks each block against the 67% threshold. Returns a quorumResult if any block qualifies, or nil if quorum has not been reached.

#Fallback Resolution

In some cases, the 67% threshold is unreachable because non-voting representatives inflate the total weight. For example, if 40% of weight belongs to offline or non-participating representatives, the remaining 60% can never reach 67%.

The fallback mechanism resolves this:

const fallbackDelay = 10 * time.Second

if len(weightByBlock) == 1 &&   !conflict.DetectedAt.IsZero() &&   Now().Sub(conflict.DetectedAt) >= fallbackDelay {    // resolve with unanimous agreement}

This ensures that conflicts are eventually resolved even when total participation is low, while still giving sufficient time for all active representatives to vote.

#Conflict Confirmation

confirmConflict() finalizes a resolved conflict. This is a multi-step process that modifies the main chain.

#Steps

#Block Swap

If the winning block is in staging (it was the second block seen, not the one on the main chain), a swap is required:

Before:  Main chain: ... ← Block 2 ← Block 3a (loser, on main)  Staging:    Block 3b (winner, staged) After:  Main chain: ... ← Block 2 ← Block 3b (winner, promoted)  Staging:    Block 3a (loser, demoted)

The swap is performed by swapBlockLocked() on the ledger, which replaces the block at the conflict position in the account chain. The demoted block is saved to staging before the swap to prevent data loss if a later step fails.

#Block Status

Every block has a status that tracks its confirmation state:

type BlockStatus uint8const (    StatusPending   BlockStatus = 0  // default — not yet involved in a conflict    StatusConfirmed BlockStatus = 1  // won a conflict vote    StatusRejected  BlockStatus = 2  // lost a conflict vote)

#Stale Conflict Sweep

The StartStaleConflictSweep method launches a background goroutine that periodically retallies unresolved conflicts:

func (qm *QuorumManager) StartStaleConflictSweep(stop <-chan struct{})

#Behavior

• Runs every 15 seconds
• Iterates all conflicts via GetAllConflicts()
• Skips conflicts younger than fallbackDelay (10 seconds)
• Retallies each stale conflict via tallyConflict()
• If quorum or fallback conditions are met, calls confirmConflict()
• Stops when the stop channel is closed

┌─────────────────────────────────────────────────┐│                 Sweep Loop                       ││                                                  ││  Every 15s:                                      ││    for each conflict:                            ││      if age < 10s: skip                          ││      tallyConflict() → result?                   ││        yes → confirmConflict(result)             ││        no  → continue                            │└─────────────────────────────────────────────────┘

#QuorumManager Construction

1func NewQuorumManager(2    store QuorumStore,3    conflictStore ConflictStore,4    voteStore VoteStore,5    ledger *Ledger,6) *QuorumManager

#QuorumStore Interface

1type QuorumStore interface {2    SetBlockStatus(hash string, status BlockStatus) error3    GetBlockStatus(hash string) (BlockStatus, error)4    SetConfirmationHeight(account string, height uint64) error5    GetConfirmationHeight(account string) (uint64, error)6    DeleteVotesForConflict(account, previous string) error7}

#Concurrency

The QuorumManager uses a single sync.Mutex to serialize all tallying and confirmation operations. This prevents race conditions when multiple votes for the same conflict arrive simultaneously, which could otherwise cause double-confirmation or inconsistent state.

During confirmConflict(), the per-account lock is also acquired to prevent AddBlock from processing new blocks on the affected account while the chain is being modified.

#Related Pages

• Consensus Overview — the full consensus lifecycle
• Delegation — weight calculation and snapshots
• Conflict Detection — how conflicts are discovered and staged
• Voting — how votes are cast and validated
• Storage — QuorumStore and ConflictStore implementations