Amendment Lifecycle

← Back to Building an Amendments I: Lifecycle and Impact on Core Protocol

---

Introduction

The lifecycle of an amendment on XRPL is a carefully orchestrated process that ensures protocol changes are adopted in a coordinated and consensual manner across the decentralized network. This process involves several distinct phases, each with its own rules, timeouts, and transition mechanisms.

In this section, we will follow the complete journey of the Subscriptions amendment (XLS-0078) from its initial conception to its final activation on the ledger. This amendment introduces a subscription mechanism (recurring payments) on XRPL, allowing account owners to authorize automatic recurring payments with predefined parameters including amount, frequency, and destination - similar to bank direct debits.

Understanding this lifecycle is essential for anticipating when a protocol change will become effective, coordinating node updates, and managing risks associated with protocol transitions.

---

Lifecycle Overview

The lifecycle of an amendment can be represented by the following phases:

┌─────────────┐
│  Proposal   │  Code developed, amendment added to registry
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    Vote     │  Validators vote for/against the amendment
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Majority   │  More than 80% of validators vote for (2 weeks minimum)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Activation  │  EnableAmendment pseudo-transaction injected
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Enablement  │  Amendment active, new rules applied
└─────────────┘

Each phase has specific criteria that must be satisfied before moving to the next. Let's now explore each phase in detail following the Subscriptions example.

---

Phase 1: Proposal

Code Development

The first phase begins with the development of code that implements the new functionality. For Subscriptions (XLS-0078), this includes:

New data structures:

• Ledger entry type ltSUBSCRIPTION (0x0055) to store recurring payment authorizations

• New fields:

  • sfAccount: Subscription owner account

  • sfDestination: Subscription receiver account

  • sfDestinationTag (optional): Tag to categorize payments

  • sfAmount: Maximum amount that can be withdrawn per period

  • sfFrequency: Interval in seconds between periods

  • sfNextPaymentTime: Timestamp of next possible claim

  • sfExpiration (optional): Timestamp of last possible period

New transactions:

• ttSUBSCRIPTION_SET: Create or modify a subscription (creation requires Destination, Amount, Frequency)

• ttSUBSCRIPTION_CLAIM: Claim a payment within available balance limits

• ttSUBSCRIPTION_CANCEL: Cancel an existing subscription (owner or destination can initiate)

Validation logic:

• Checks in preflight, preclaim, and doApply

• Management of amounts per period (≤ Amount)

• Support for XRP, IOUs (with trustlines and transfer rates), and MPTs (Multi-Purpose Tokens)

• Arrears management: if a period passes without claim, the opportunity is lost and NextPaymentTime advances by one Frequency interval

• Single claim per period to avoid spam

• Respect freeze states (IOU) and lock (MPT)

• Auto-creation of trustlines and MPToken holdings if authorizations and reserves are sufficient

Reference: XLS-0078 Subscriptions

Amendment Registration

Once the code is ready, the amendment is registered in the system via features.macro:

XRPL_FEATURE(Subscriptions, Supported::yes, VoteBehavior::DefaultNo)

Parameters:

• Subscriptions: Amendment name

• Supported::yes: The code is included and supported

• VoteBehavior::DefaultNo: By default, nodes do not vote for (requires explicit activation)

Hash Calculation

The amendment hash is calculated automatically:

Name: "Subscriptions"
Method: SHA-512Half(name)
Hash: 7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8

This hash is the unique identifier that will be used in all network communications and data structures.

Code Distribution

The code containing the new amendment is distributed via:

• A new version of rippled (e.g., 2.3.0)

• Publication on GitHub with detailed release notes

• Announcements on community communication channels

• Documentation on XRPL.org and link to XLS-0078

At this stage, the amendment exists in the code but is not yet enabled. Nodes that update to this version recognize the amendment but do not apply it yet.

---

Phase 2: Vote

Vote Activation by Validators

Validators must explicitly activate their vote for the amendment. This is typically done via the RPC command feature:

# Vote for the amendment
rippled feature 7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8 accept

Or by modifying the configuration file:

[amendments]
7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8

Inclusion in Validations

Once a validator has activated their vote, this vote is included in each validation they publish. The validation contains:

// Simplified structure of a validation
struct STValidation {
    uint256 ledgerHash;           // Hash of validated ledger
    uint32 ledgerSeq;             // Sequence number
    NetClock::time_point signTime; // Signing moment
    PublicKey publicKey;          // Validator's public key

    // List of supported amendments
    std::vector<uint256> amendments;

    // Validation signature
    Buffer signature;
};

The amendments field contains the list of all amendments the validator wishes to see enabled, including Subscriptions.

Vote Collection

Each node on the network collects validations received from trusted validators and extracts their amendment votes. The system maintains:

TrustedVotes: Structure that aggregates votes over a time period

class TrustedVotes {
    // Map: Amendment hash -> Number of votes
    hash_map<uint256, int> votes_;

    // Total number of trusted validators
    int trustedValidations_;

    // Expire votes that are too old
    void expire(NetClock::time_point now);

    // Retrieve aggregated votes
    std::pair<int, hash_map<uint256, int>>
        getVotes(Rules const& rules);
};

Freshness period: Votes have a limited lifetime (typically 5 minutes). A vote expires if it is not reaffirmed by a new validation within this time. This ensures that vote counts reflect the current state of the network.

Status Monitoring

During the voting phase, the status of Subscriptions can be queried via the RPC command feature:

{
  "7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8": {
    "count": 15,              // 15 validators vote for
    "enabled": false,         // Not yet enabled
    "name": "Subscriptions",
    "supported": true,        // This node supports the amendment
    "threshold": 20,          // threshold = floor(25 * 0.8) = 20
    "validations": 25,        // 25 trusted validators in total
  }
}

Interpretation:

• 15 out of 25 validators vote for Subscriptions (60%)

• The 80% threshold is not yet exceeded (need more than 20 votes, so minimum 21)

• The amendment is supported but not enabled

Note on threshold: The threshold field displays floor(validations * 0.8) = 20, but the comparison in the code uses votes > threshold, so 21 votes minimum are needed to reach majority.

---

Phase 3: Majority

Exceeding the 80% Threshold

When enough validators activate their vote, the amendment exceeds the required threshold. Let's assume 6 additional validators activate their vote:

{
  "7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8": {
    "count": 21,              // 21 validators vote for (84%)
    "enabled": false,         // Still not enabled
    "majority": 805385181,    // ← NEW: XRPL timestamp when majority reached
    "name": "Subscriptions",
    "supported": true,
    "threshold": 20,          // floor(25 * 0.8) = 20
    "validations": 25,
  }
}

The majority field: This is the critical moment. This field contains the XRPL Time (seconds since 2000-01-01 00:00:00 UTC) when the 80% threshold was first exceeded (count > threshold). In our example: 805385181 corresponds approximately to a date in 2025.

Support calculation: 21/25 = 84% > 80% ✓

tfGotMajority Pseudo-transaction

When the threshold is reached, an EnableAmendment pseudo-transaction with the tfGotMajority flag is injected into the ledger:

{
  "TransactionType": "EnableAmendment",
  "Account": "rrrrrrrrrrrrrrrrrrrrrhoLvTp",  // Special network account
  "Amendment": "7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8",
  "Flags": 65536,  // tfGotMajority = 0x00010000
  "LedgerSequence": 85432190,
  "TransactionIndex": 0
}

Impact on ledger: This pseudo-transaction adds an entry to the sfMajorities field of the global ledger object:

{
  "Majorities": [
    {
      "Amendment": "7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8",
      "CloseTime": 805385181
    }
  ]
}

Two-Week Stability Period

From this moment, the amendment enters a mandatory two-week stability period (more precisely, two flag ledgers). Flag ledgers are special ledgers that occur approximately every 15 minutes (256 ledgers).

Duration calculation:

• 1 flag ledger ≈ 15 minutes (256 ledgers × 3.5 seconds/ledger)

• 2 flag ledgers ≈ 30 minutes in terms of ledgers

• But in practice, the minimum period is 2 weeks in real time

Reason for the period: This window allows:

• Node operators to prepare and update their systems

• The community to detect any potential problems

• Exchanges and wallets to adapt their integrations to support subscriptions

• A last opportunity for validators to withdraw their vote if necessary

Loss of Majority (Edge Case)

If during the stability period support falls below 80%, the amendment loses its majority. An EnableAmendment pseudo-transaction with the tfLostMajority flag is injected:

{
  "TransactionType": "EnableAmendment",
  "Account": "rrrrrrrrrrrrrrrrrrrrrhoLvTp",
  "Amendment": "7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8",
  "Flags": 131072,  // tfLostMajority = 0x00020000
  "LedgerSequence": 85435000
}

The majority field disappears from the amendment status, and the countdown restarts from zero if the threshold is reached again.

---

Phase 4: Activation

Expiration of Stability Period

After two weeks of uninterrupted majority, the amendment is ready to be activated. The network automatically calculates when this moment arrives based on the CloseTime recorded in sfMajorities.

EnableAmendment Pseudo-transaction

At the next flag ledger after the period expires, an EnableAmendment pseudo-transaction without flags is injected:

{
  "TransactionType": "EnableAmendment",
  "Account": "rrrrrrrrrrrrrrrrrrrrrhoLvTp",
  "Amendment": "7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8",
  "Flags": 0,  // No flag = activation
  "LedgerSequence": 85987654,
  "TransactionIndex": 0,
  "hash": "491378DA1BAAE870A6C247B3E42193E80E507A50858A4E51217685E2765E6CE8"
}

Processing by Change::applyAmendment: This pseudo-transaction is processed by the Change::applyAmendment() function in src/xrpld/app/tx/detail/Change.cpp:

TER Change::applyAmendment() {
    // Extract the amendment hash from the transaction
    uint256 amendment(ctx_.tx.getFieldH256(sfAmendment));

    // Retrieve the key of the ledger's global amendments object
    auto const k = keylet::amendments();

    // Read or create the amendments object
    SLE::pointer amendmentObject = view().peek(k);

    if (!amendmentObject)
    {
        // If the object doesn't exist yet, create it (rare)
        amendmentObject = std::make_shared<SLE>(k);
        view().insert(amendmentObject);
    }

    // Read the list of already enabled amendments
    STVector256 amendments = amendmentObject->getFieldV256(sfAmendments);

    // Check if this amendment is already enabled
    if (std::find(amendments.begin(), amendments.end(), amendment) !=
        amendments.end())
        return tefALREADY;  // Already enabled, do nothing

    // Extract flags from the transaction
    auto flags = ctx_.tx.getFlags();

    bool const gotMajority = (flags & tfGotMajority) != 0;
    bool const lostMajority = (flags & tfLostMajority) != 0;

    // Check flag consistency (can't have both)
    if (gotMajority && lostMajority)
        return temINVALID_FLAG;

    // Prepare a new majorities array
    STArray newMajorities(sfMajorities);

    // Iterate through existing majorities to update
    bool found = false;
    if (amendmentObject->isFieldPresent(sfMajorities))
    {
        STArray const& oldMajorities =
            amendmentObject->getFieldArray(sfMajorities);

        for (auto const& majority : oldMajorities)
        {
            if (majority.getFieldH256(sfAmendment) == amendment)
            {
                // This amendment is already in majorities
                if (gotMajority)
                    return tefALREADY;  // Already recorded as majority
                found = true;  // Found, don't copy it (lost majority)
            }
            else
            {
                // Copy other majorities
                newMajorities.push_back(majority);
            }
        }
    }

    // If lostMajority but not in list, error
    if (!found && lostMajority)
        return tefALREADY;

    if (gotMajority)
    {
        // Amendment just reached majority
        // Add a new entry to sfMajorities
        newMajorities.push_back(STObject::makeInnerObject(sfMajority));
        auto& entry = newMajorities.back();
        entry[sfAmendment] = amendment;
        entry[sfCloseTime] =
            view().parentCloseTime().time_since_epoch().count();

        // Warn if amendment is not supported by this node
        if (!ctx_.app.getAmendmentTable().isSupported(amendment))
        {
            JLOG(j_.warn()) << "Unsupported amendment " << amendment
                            << " received a majority.";
        }
    }
    else if (!lostMajority)
    {
        // No flags = ACTIVATION of the amendment
        // Add to list of enabled amendments
        amendments.push_back(amendment);
        amendmentObject->setFieldV256(sfAmendments, amendments);

        // Enable locally in AmendmentTable
        ctx_.app.getAmendmentTable().enable(amendment);

        // Check if supported - block node if not supported
        if (!ctx_.app.getAmendmentTable().isSupported(amendment))
        {
            JLOG(j_.error()) << "Unsupported amendment " << amendment
                             << " activated: server blocked.";
            ctx_.app.getOPs().setAmendmentBlocked();
        }
    }

    // Update the sfMajorities field
    if (newMajorities.empty())
        amendmentObject->makeFieldAbsent(sfMajorities);  // Remove if empty
    else
        amendmentObject->setFieldArray(sfMajorities, newMajorities);

    // Save changes to ledger
    view().update(amendmentObject);

    return tesSUCCESS;
}

Ledger Update

The amendment is added to the sfAmendments field of the global ledger object:

{
  "Amendments": [
    "...",  // Other already enabled amendments
    "7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8"
  ]
}

The corresponding entry is removed from the sfMajorities field since the amendment is no longer pending.

---

Phase 5: Enablement

Application of New Rules

As soon as the amendment is added to the sfAmendments field, all new transactions and all new ledgers must apply the Subscriptions rules.

For Subscriptions (XLS-0078), this means:

• ttSUBSCRIPTION_SET transactions are now valid and can be submitted to create/modify subscriptions

• ttSUBSCRIPTION_CLAIM transactions can claim payments within available balance limits

• ttSUBSCRIPTION_CANCEL transactions can cancel existing subscriptions

• The ledger can contain ltSUBSCRIPTION objects (type 0x0055)

• Logic for managing periods, balances, and arrears is activated

• Support for XRP, IOUs with trustlines, and MPTs with their specific rules

Rules Object Construction

The state of amendments is encapsulated in the Rules object which is constructed for each ledger:

class Rules {
private:
    std::set<uint256> enabledAmendments_;

public:
    bool enabled(uint256 const& amendment) const {
        return enabledAmendments_.count(amendment) > 0;
    }
};

Transactors and ledger logic consult this object to know which rules to apply:

// In SubscriptionSet::preflight()
NotTEC SubscriptionSet::preflight(PreflightContext const& ctx) {
    if (!ctx.rules.enabled(featureSubscriptions))
        return temDISABLED;

    // ... rest of validation
}

Final Status

The amendment status after activation simplifies:

{
  "7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8": {
    "enabled": true,          // ← Amendment active
    "name": "Subscriptions",
    "supported": true
  }
}

The fields count, threshold, validations, majority disappear because they are no longer relevant once the amendment is enabled.

---

Complete Timeline: Concrete Example

Here is a realistic timeline for Subscriptions on mainnet:

2025-03-01: Release of rippled 2.3.0 including Subscriptions (XLS-0078)

• Code distributed, nodes begin to update

• Publication of detailed documentation on XRPL.org

2025-03-15: First validators activate their vote

• 5 out of 35 validators vote for (14%)

2025-04-01: Growing momentum

• 20 out of 35 validators vote for (57%)

• Exchanges and wallets begin to prepare their integrations

2025-04-20 14:32:15 UTC: Threshold exceeded

• 29 out of 35 validators vote for (82.9% > 80%)

• majority field appears with timestamp 806021535

• tfGotMajority pseudo-transaction injected at ledger 86245789

2025-04-20 → 2025-05-04: Stability period

• 2 weeks mandatory waiting

• Support remains stable above 80%

• Final tests on staging environments

2025-05-04 14:32:15 UTC: Activation

• EnableAmendment pseudo-transaction (without flag) injected at ledger 86652345

• Subscriptions added to sfAmendments field

2025-05-04 14:32:18 UTC: Enablement

• First ledger with Subscriptions active

• First ttSUBSCRIPTION_SET transactions processed

• Users can now create subscriptions for recurring payments

---

State Transition Management

doValidatedLedger: Local Synchronization

After each validated ledger, the AmendmentTableImpl::doValidatedLedger() function synchronizes the local state of amendments with the ledger state:

void AmendmentTableImpl::doValidatedLedger(
    std::shared_ptr<ReadView const> const& ledger)
{
    std::lock_guard lock(mutex_);

    // Read enabled amendments from ledger
    auto const amendments = ledger->rules().prevalidate();

    // Enable locally all amendments from ledger
    for (auto const& amendment : amendments) {
        auto it = amendmentMap_.find(amendment);
        if (it != amendmentMap_.end()) {
            it->second.enabled = true;
        }
    }

    // Update majority status
    updateMajorities(ledger);

    // Check unsupported amendments
    checkUnsupported(ledger);
}

This synchronization ensures that the node's internal state always reflects the validated ledger state.

Detection of Unsupported Amendments

If an amendment is enabled but the local node does not support it, the node enters "amendment blocked" mode:

if (!isSupported(amendment)) {
    JLOG(j_.error())
        << "Unsupported amendment " << amendment << " activated!";
    app_.getOPs().setAmendmentBlocked();
    // Node ceases to participate in consensus
}

This protects network integrity by preventing an outdated node from applying incorrect rules.

---

Special Cases and Edge Cases

Changes in UNL List

If the list of trusted validators (UNL) changes during the voting or majority phase, the threshold calculation adapts dynamically:

• If validators are added to the UNL, the absolute threshold increases

• If validators are removed, the threshold decreases

• An amendment can lose its majority if enough validators supporting the amendment leave the UNL

Rollback and Contingency

There is no mechanism to disable an amendment once enabled. If a critical problem is discovered after activation:

1. A fix must be developed and deployed via a new amendment

2. Or a security patch must be distributed urgently

3. In extreme cases, out-of-band coordination may be necessary

This is why the two-week stability period is crucial: it offers a last opportunity to detect problems before irreversible activation.