Skip to content

cap-0083.md

Latest commit

 

History

History
232 lines (180 loc) · 9.74 KB

cap-0083.md

File metadata and controls

232 lines (180 loc) · 9.74 KB

Preamble

CAP: 0083
Title: Allow validators to vote to skip the current ledger
Working Group:
    Owner: Brett Boston <@bboston7>
    Authors: Brett Boston <@bboston7>
    Consulted: Nicolas Barry <@MonsieurNicolas>, Giuliano Losa <@nano-o>, Marta Lokhova <@marta-lokhova>
Status: Awaiting Decision
Created: 2026-03-31
Discussion: https://github.com/orgs/stellar/discussions/1865 and https://github.com/orgs/stellar/discussions/1907
Protocol version: TBD

Simple Summary

This CAP introduces a new StellarValue type to allow validators to explicitly skip the ledger that is being voted on. It also relaxes validation criteria on PREPARE messages.

Working Group

As specified in the preamble.

Motivation

Providing a mechanism for validators to explicitly vote to skip ledgers allows them to conduct some SCP voting prior to receiving a transaction set. This will improve SCP performance, as transaction set dissemination is costly and validators can safely make initial progress on consensus while waiting for transaction sets.

If, during the PREPARE phase of balloting, a validator has not received the transaction set being voted on within a reasonable amount of time, or the transaction set is invalid, they may vote to skip the current ledger. This prevents consensus from getting stuck waiting for a transaction set that may never arrive, as a valid transaction set is required before moving on to the CONFIRM phase of balloting.

Relaxing validity checks on PREPARE messages is necessary to enable early balloting without requiring that all network participants have the transaction set being voted on.

Goals Alignment

This CAP is aligned with the following Stellar Network Goal:

  • The Stellar Network should run at scale and at low cost to all participants of the network.

Abstract

This CAP introduces a new StellarValue extension type STELLAR_VALUE_SKIP. With this change, validators may switch their ballot to a STELLAR_VALUE_SKIP during the PREPARE phase of balloting prior to setting c1. STELLAR_VALUE_SKIP includes information about the value that a validator was considering before switching to voting to skip the ledger.

This CAP also relaxes the validation of PREPARE messages to permit invalid transaction sets. This change ensures the network does not drop ballots from honest network participants that may unknowingly vote for invalid values in early balloting stages.

Specification

XDR changes

To enable ledger skipping, this CAP proposes the following change to Stellar-ledger.x:

diff --git a/Stellar-ledger.x b/Stellar-ledger.x
index a17036b..667f8e7 100644
--- a/Stellar-ledger.x
+++ b/Stellar-ledger.x
@@ -13,7 +13,8 @@ typedef opaque UpgradeType<128>;
 enum StellarValueType
 {
     STELLAR_VALUE_BASIC = 0,
-    STELLAR_VALUE_SIGNED = 1
+    STELLAR_VALUE_SIGNED = 1,
+    STELLAR_VALUE_SKIP = 2
 };

 struct LedgerCloseValueSignature
@@ -43,6 +44,14 @@ struct StellarValue
         void;
     case STELLAR_VALUE_SIGNED:
         LedgerCloseValueSignature lcValueSignature;
+    case STELLAR_VALUE_SKIP:
+        struct
+        {
+            Hash txSetHash;
+            Hash previousLedgerHash;
+            uint32 previousLedgerVersion;
+            LedgerCloseValueSignature lcValueSignature;
+        } proposedValue;
     }
     ext;
 };

With this change, the full StellarValue struct becomes:

/* StellarValue is the value used by SCP to reach consensus on a given ledger
 */
struct StellarValue
{
    Hash txSetHash;      // transaction set to apply to previous ledger
    TimePoint closeTime; // network close time

    // upgrades to apply to the previous ledger (usually empty)
    // this is a vector of encoded 'LedgerUpgrade' so that nodes can drop
    // unknown steps during consensus if needed.
    // see notes below on 'LedgerUpgrade' for more detail
    // max size is dictated by number of upgrade types (+ room for future)
    UpgradeType upgrades<6>;

    // reserved for future use
    union switch (StellarValueType v)
    {
    case STELLAR_VALUE_BASIC:
        void;
    case STELLAR_VALUE_SIGNED:
        LedgerCloseValueSignature lcValueSignature;
    case STELLAR_VALUE_SKIP:
        struct
        {
            Hash txSetHash;
            Hash previousLedgerHash;
            uint32 previousLedgerVersion;
            LedgerCloseValueSignature lcValueSignature;
        } proposedValue;
    }
    ext;
};

XDR Example

TBD

Skip Value Semantics

Skip Value Representation

When the network votes to skip the ledger, validators will externalize a StellarValue with fields set as follows:

  • txSetHash : Set to 0x0
  • closeTime : Set as usual
  • upgrades : Set as usual
  • ext : Set to STELLAR_VALUE_SKIP
    • proposedValue : Details about the original StellarValue that a quorum of validators decided to skip.
      • proposedValue.txSetHash : The hash of the transaction set that was insufficiently disseminated or invalid.
      • proposedValue.previousLedgerHash : The hash of the ledger prior to this one. Used to construct an empty transaction set corresponding to this skip value.
      • proposedValue.previousLedgerVersion : The ledger version of the previous ledger. Used to construct an empty transaction set corresponding to this skip value.
      • proposedValue.lcValueSignature : The signature from the original StellarValue. Can be used to determine which validator proposed the original StellarValue.

Skip Value Application

At apply time, ledgers containing a skip value should be treated as ledgers with empty transaction sets. In every other way, they should be treated as normal STELLAR_VALUE_SIGNED ledgers.

PREPARE Message Validation

Validators must not drop incoming PREPARE messages on the basis of an invalid or missing transaction set. This ensures that the network can make progress when a transaction set is determined to be invalid during the PREPARE phase of balloting.

Validators must continue to drop any CONFIRM or EXTERNALIZE messages containing ballots for STELLAR_VALUE_SIGNED values with invalid transaction sets.

Design Rationale

We considered a few alternative methods to achieve parallel downloading of transaction sets before landing on this protocol change:

  • Rather than skipping a ledger on failure to download a transaction set, we looked into rolling back SCP to an earlier phase. However, this would be a large change to SCP, which was not designed to ever step backwards. We decided it was cleaner, and easier to verify the change if validators instead voted to skip the current ledger.
  • We analyzed how far along consensus a validator could safely proceed without a transaction set if there was no skip or rollback mechanism, and decided that the lack of such a mechanism was too limiting. Without some method for validators to agree that a transaction set is unavailable, it is only safe to proceed with early nomination voting.

Protocol Upgrade Transition

STELLAR_VALUE_SKIP values will become valid on the network at the protocol boundary. However, validators will not generate them unless they have enabled parallel transaction set downloading. Parallel transaction set downloading will initially be disabled by default, and we would like to gradually enable it across the validator network.

Validation of PREPARE messages will be relaxed at the protocol boundary.

Downstream Impact

Downstream consumers of StellarValues may require modification. Specifically, those that reason about txSetHash will need to handle the new 0x0 value, and those that reason about ext will need to handle the new STELLAR_VALUE_SKIP extension.

To help determine if you depend on something that contains a StellarValue, transitive dependencies on StellarValue are as follows:

StellarValue
    │
    ├──► LedgerHeader.scpValue
    │    │
    │    └──► LedgerHeaderHistoryEntry.header
    │         │
    │         ├──► LedgerCloseMetaV0.ledgerHeader
    │         ├──► LedgerCloseMetaV1.ledgerHeader
    │         └──► LedgerCloseMetaV2.ledgerHeader
    │              │
    │              └──► LedgerCloseMeta (union)
    │                   │
    │                   └──► LedgerCloseMetaBatch.ledgerCloseMetas
    │
    └──► StoredDebugTransactionSet.scpValue

Downstream consumers of StellarValues should treat skipped ledgers as empty ledgers.

Backwards Incompatibilities

As detailed in the previous section, downstream consumers of StellarValues may require modification.

Resource Utilization

We expect this change to increase throughput on validators by expediting consensus. Simulation has shown this to be manageable. However, we will rollout the parallel downloading portion of this change slowly to ensure that real-world performance data matches simulation.

Security Concerns

This CAP introduces a new method by which malicious validators could negatively impact the network. A malicious validator could introduce bad transaction set hashes, which then force the network to skip a ledger after some delay. However, this attack is mitigated by the following factors:

  • The attacker would have to win leader election to propose the bad value. This limits the frequency with which this attack can be pulled off.
  • By design, we include the original value that was skipped in the STELLAR_VALUE_SKIP struct, including the signature for the value. This enables node operators to easily determine which validators are misbehaving and remove them from their quorum sets.

Test Cases

TBD

Implementation

Draft implementation: stellar/stellar-core#5209

Footnotes

  1. See the SCP IETF draft for a complete semantics of c ↩