The path of an amendment from introduction through majority to activation.
What you'll learn
≈45 min · Intermediate · builds on Amendments — overview & architecture
Let's follow one amendment from idea to activation. In this module you'll trace its states through the 80%-for-two-weeks rule, the tfGotMajority / tfLostMajority flags and the EnableAmendment pseudo-transaction, and learn what 'amendment-blocked' means for a node that falls behind. Governance as a state machine.
In brief: the phases an amendment moves through from idea to enabled.
The lifecycle of an amendment can be represented by the following phases:
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.
Note. "Subscriptions" is used across these amendment modules purely as a hypothetical running example, to make the process concrete. It is not a real, shipped XRPL amendment; its transactors and fields are illustrative, not code you will find in rippled.
The first phase begins with the development of code that implements the new functionality. For Subscriptions (XLS-0078), this includes:
New data structures:
ltSUBSCRIPTION (0x0055) to store recurring payment authorizationssfAccount: Subscription owner accountsfDestination: Subscription receiver accountsfDestinationTag (optional): Tag to categorize paymentssfAmount: Maximum amount that can be withdrawn per periodsfFrequency: Interval in seconds between periodssfNextPaymentTime: Timestamp of next possible claimsfExpiration (optional): Timestamp of last possible periodNew transactions:
ttSUBSCRIPTION_SET: Create or modify a subscription (creation requires Destination, Amount, Frequency)ttSUBSCRIPTION_CLAIM: Claim a payment within available balance limitsttSUBSCRIPTION_CANCEL: Cancel an existing subscription (owner or destination can initiate)Validation logic:
preflight, preclaim, and doApplyReference: XLS-0078 Subscriptions
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 nameSupported::Yes: The code is included and supportedVoteBehavior::DefaultNo: By default, nodes do not vote for (requires explicit activation)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.
The code containing the new amendment is distributed via:
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.
In brief: validators include their support in the validation issued just before each flag ledger.
Validators must explicitly activate their vote for the amendment. This is typically done via the RPC command feature:
# Vote for the amendment
xrpld feature 7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8 accept
Or by modifying the configuration file:
[amendments]
7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8
Once a validator has activated their vote, the vote is not attached to every validation. It is attached only to the validation of a voting ledger — the ledger immediately before a flag ledger. In RCLConsensus.cpp, the validation-building code checks ledger.ledger->isVotingLedger() before setting sfAmendments; Ledger::isVotingLedger() returns true when the next sequence is a multiple of kFlagLedgerInterval (256), i.e. for ledgers with seq ≡ 255 mod 256. So amendment votes travel once per 256-ledger cycle (roughly every 15 minutes), not each ledger. 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
// (present only when the validated ledger is a voting ledger)
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.
Each node on the network collects validations received from trusted validators and extracts their amendment votes. The system maintains:
TrustedVotes: Structure that records the most recent votes seen from each trusted validator
class TrustedVotes {
private:
// Associates each trusted validator with the last votes we saw
// from them and an expiration for that record.
struct UpvotesAndTimeout {
std::vector<uint256> upVotes;
std::optional<NetClock::time_point> timeout;
};
hash_map<PublicKey, UpvotesAndTimeout> recordedVotes_;
public:
// Record the newest votes; expired records are cleared here.
void recordVotes(
Rules const& rules,
std::vector<std::shared_ptr<STValidation>> const& valSet,
NetClock::time_point const closeTime,
beast::Journal j,
std::scoped_lock<std::mutex> const& lock);
// Aggregate: number of validators with live records, and
// per-amendment vote counts.
[[nodiscard]] std::pair<int, hash_map<uint256, int>>
getVotes(Rules const& rules,
std::scoped_lock<std::mutex> const& lock) const;
};
Note that the record is per validator, not a simple per-amendment counter: getVotes() produces the amendment → count aggregation on demand from the per-validator records.
Vote retention: A recorded vote stays live for 24 hours (kExpiresAfter = 24h in AmendmentTable.cpp). The purpose of retaining the last vote from each trusted validator is to avoid "flapping": if a validator loses synchronization near a flag ledger, its validations (and therefore its votes) may be missing for that round, which would otherwise make an amendment appear to repeatedly gain and lose support. By holding on to the last vote seen, the node assumes an offline validator did not change its position. Only after 24 hours with no validation from a validator does the node clear that validator's recorded upVotes (there is no separate expire() call — the cleanup happens inside recordVotes()).
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:
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.
Note on connection role: The count, validations, and threshold fields (and vetoed) are only returned on admin connections — in AmendmentTableImpl::injectJson they are gated on isAdmin. Querying a public server returns only name, enabled, and supported, plus majority when present (the majority field comes from the validated ledger's Majorities and is not admin-gated).
In brief: crossing 80% support starts a two-week stability countdown.
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 recorded
"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) recorded as sfCloseTime when the tfGotMajority pseudo-transaction was applied. In Change::applyAmendment, the value written is view().parentCloseTime() — and since the pseudo-transaction lands in the ledger right after the flag ledger, this is the flag ledger's close time. Because votes are only tallied at flag-ledger boundaries, this is the moment the majority was first observed. In our example: 805385181 corresponds approximately to a date in 2025.
Support calculation: 21/25 = 84% > 80%
Vote tallying and pseudo-transaction injection happen once per flag-ledger cycle: in RCLConsensus.cpp, when the previous ledger was a flag ledger (prevLedger->isFlagLedger()), AmendmentTable::doVoting runs and injects the amendment pseudo-transactions into the consensus transaction set. They therefore land in the ledger after the flag ledger (seq ≡ 1 mod 256) — the flag ledger itself contains no amendment pseudo-transactions. At the first such voting round where the tally exceeds the threshold, an EnableAmendment pseudo-transaction with the tfGotMajority flag is injected:
{
"TransactionType": "EnableAmendment",
"Account": "rrrrrrrrrrrrrrrrrrrrrhoLvTp", // Special network account
"Amendment": "7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8",
"Flags": 65536, // tfGotMajority = 0x00010000
"LedgerSequence": 85432065,
"TransactionIndex": 0
}
Impact on ledger: This pseudo-transaction adds an entry to the sfMajorities field of the Amendments singleton ledger entry (ltAMENDMENTS, addressed by keylet::amendments()):
{
"Majorities": [
{
"Amendment": "7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8",
"CloseTime": 805385181
}
]
}
From this moment, the amendment enters a mandatory stability period. The hold is purely time-based: kDefaultAmendmentMajorityTime = weeks{2} in SystemParameters.h.
How the duration is enforced:
AmendmentTableImpl::doVoting compares the CloseTime recorded in sfMajorities plus the majority time against the ledger close time: the enable action fires when hasLedgerMajority && ((*majorityTime + majorityTime_) <= closeTime)kFlagLedgerInterval = 256 ledgers, roughly every 15 minutes) only sets where the check happens, not the duration[amendment_majority_time] in the config file (minimum 15 minutes); on mainnet it is the default 2 weeksReason for the period: This window allows:
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": 85434881
}
The majority field disappears from the amendment status, and the countdown restarts from zero if the threshold is reached again.
Key idea. The 80%-for-two-weeks rule is deliberate friction: it gives operators time to upgrade before a change goes live, so nobody is caught out.
In brief: an EnableAmendment pseudo-transaction turns the amendment on.
After two weeks of uninterrupted majority, the amendment is ready to be activated. The network detects this at the flag-ledger voting rounds: the amendment is enabled at the first round whose close time satisfies CloseTime (from sfMajorities) + amendmentMajorityTime ≤ close time.
At the first flag-ledger voting round after the period expires, an EnableAmendment pseudo-transaction without flags is injected into the ledger following the flag ledger (seq ≡ 1 mod 256):
{
"TransactionType": "EnableAmendment",
"Account": "rrrrrrrrrrrrrrrrrrrrrhoLvTp",
"Amendment": "7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8",
"Flags": 0, // No flag = activation
"LedgerSequence": 85987585,
"TransactionIndex": 0,
"hash": "491378DA1BAAE870A6C247B3E42193E80E507A50858A4E51217685E2765E6CE8"
}
Processing by Change::applyAmendment: This pseudo-transaction is processed by the Change::applyAmendment() function in src/libxrpl/tx/transactors/system/Change.cpp:
TER
Change::applyAmendment()
{
// Extract the amendment hash from the transaction
uint256 const amendment(ctx_.tx.getFieldH256(sfAmendment));
// Retrieve the key of the Amendments singleton ledger entry
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::ranges::find(amendments, amendment) != amendments.end())
return tefALREADY; // Already enabled, do nothing
// Read the flags from the transaction
bool const gotMajority = ctx_.tx.isFlag(tfGotMajority);
bool const lostMajority = ctx_.tx.isFlag(tfLostMajority);
// 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)
{
if (gotMajority)
return tefALREADY; // Already recorded as majority
found = true; // Found, don't copy it (lost majority)
}
else
{
// pass through
newMajorities.pushBack(majority);
}
}
}
// If lostMajority but not in list, error
if (!found && lostMajority)
return tefALREADY;
if (gotMajority)
{
// This amendment now has a majority
newMajorities.pushBack(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_.registry.get().getAmendmentTable().isSupported(amendment))
{
JLOG(j_.warn()) << "Unsupported amendment " << amendment
<< " received a majority.";
}
}
else if (!lostMajority)
{
// No flags, enable amendment
amendments.pushBack(amendment);
amendmentObject->setFieldV256(sfAmendments, amendments);
// Enable locally in AmendmentTable
ctx_.registry.get().getAmendmentTable().enable(amendment);
// Check if supported - block node if not supported
if (!ctx_.registry.get().getAmendmentTable().isSupported(amendment))
{
JLOG(j_.error()) << "Unsupported amendment " << amendment
<< " activated: server blocked.";
ctx_.registry.get().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;
}
The amendment is added to the sfAmendments field of the Amendments singleton ledger entry:
{
"Amendments": [
"...", // Other already enabled amendments
"7B73B9E8D8E6E8E8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8A8B8C8D8E8F8"
]
}
The corresponding entry is removed from the sfMajorities field since the amendment is no longer pending.
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 subscriptionsttSUBSCRIPTION_CLAIM transactions can claim payments within available balance limitsttSUBSCRIPTION_CANCEL transactions can cancel existing subscriptionsltSUBSCRIPTION objects (type 0x0055)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
}
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.
Here is a realistic timeline for Subscriptions on mainnet:
2025-03-01: Release of rippled 2.3.0 including Subscriptions (XLS-0078)
2025-03-15: First validators activate their vote
2025-04-01: Growing momentum
2025-04-20 14:32:15 UTC: Threshold exceeded
majority field appears with timestamp 806021535tfGotMajority pseudo-transaction injected at ledger 86245633 (the ledger after the flag ledger)2025-04-20 → 2025-05-04: Stability period
2025-05-04 14:41:02 UTC: Activation
EnableAmendment pseudo-transaction (without flag) injected at ledger 86652161sfAmendments field2025-05-04 14:41:05 UTC: Enablement
ttSUBSCRIPTION_SET transactions processedAfter each validated ledger, the amendment table synchronizes its local state with the ledger state. The interface (include/xrpl/ledger/AmendmentTable.h) provides a wrapper that takes the validated ledger, skips the work unless a flag-ledger boundary was crossed (needValidatedLedger()), and extracts the ledger's data with the free functions getEnabledAmendments() and getMajorityAmendments():
/** Called when a new fully-validated ledger is accepted. */
void
doValidatedLedger(std::shared_ptr<ReadView const> const& lastValidatedLedger)
{
if (needValidatedLedger(lastValidatedLedger->seq()))
{
doValidatedLedger(
lastValidatedLedger->seq(),
getEnabledAmendments(*lastValidatedLedger),
getMajorityAmendments(*lastValidatedLedger));
}
}
The implementation (src/xrpld/app/misc/detail/AmendmentTable.cpp) enables locally everything the ledger says is enabled, then scans the pending majorities to compute firstUnsupportedExpected_ — the earliest time an amendment this node does not support could become enabled, which drives the "amendment warned" state:
void
AmendmentTableImpl::doValidatedLedger(
LedgerIndex ledgerSeq,
std::set<uint256> const& enabled,
majorityAmendments_t const& majority)
{
for (auto& e : enabled)
enable(e);
std::scoped_lock const lock(mutex_);
// Remember the ledger sequence of this update.
lastUpdateSeq_ = ledgerSeq;
// Since we have the whole list in `majority`, reset the time flag, even
// if it's currently set. If it's not set when the loop is done, then any
// prior unknown amendments have lost majority.
firstUnsupportedExpected_.reset();
for (auto const& [hash, time] : majority)
{
AmendmentState const& s = add(hash, lock);
if (s.enabled)
continue;
if (!s.supported)
{
JLOG(j_.info()) << "Unsupported amendment " << hash
<< " reached majority at " << to_string(time);
if (!firstUnsupportedExpected_ || firstUnsupportedExpected_ > time)
firstUnsupportedExpected_ = time;
}
}
if (firstUnsupportedExpected_)
firstUnsupportedExpected_ = *firstUnsupportedExpected_ + majorityTime_;
}
This synchronization ensures that the node's internal state always reflects the validated ledger state.
If an amendment is enabled but the local node does not support it, the node enters "amendment blocked" mode. This happens in two places. First, when the pseudo-transaction is applied, Change::applyAmendment blocks the node directly (see the listing above):
if (!ctx_.registry.get().getAmendmentTable().isSupported(amendment))
{
JLOG(j_.error()) << "Unsupported amendment " << amendment
<< " activated: server blocked.";
ctx_.registry.get().getOPs().setAmendmentBlocked();
}
Second, LedgerMaster::setValidLedger re-checks after every call to doValidatedLedger — this catches a node that acquired an already-enabled ledger rather than applying the pseudo-transaction itself:
app_.getAmendmentTable().doValidatedLedger(l);
if (!app_.getOPs().isBlocked())
{
if (app_.getAmendmentTable().hasUnsupportedEnabled())
{
JLOG(journal_.error()) << "One or more unsupported amendments "
"activated: server blocked.";
app_.getOPs().setAmendmentBlocked();
}
// ...
}
This protects network integrity by preventing an outdated node from applying incorrect rules.
If the list of trusted validators (UNL) changes during the voting or majority phase, the threshold calculation adapts dynamically:
There is no mechanism to disable an amendment once enabled. If a critical problem is discovered after activation:
This is why the two-week stability period is crucial: it offers a last opportunity to detect problems before irreversible activation.
This module followed one amendment from proposal to activation. You traced its states through the rule that 80% of trusted validators must support it continuously for two weeks, the tfGotMajority / tfLostMajority flags, and the EnableAmendment pseudo-transaction that finally turns it on. You also learned what amendment-blocked means for a node that falls behind: it stops processing to avoid diverging from the network.
To remember:
kDefaultAmendmentMajorityTime)tfGotMajority marks the threshold crossing (timer starts); tfLostMajority marks a drop (timer resets)EnableAmendment pseudo-transactions (processed by the Change transactor) record it on-ledger; the flagless EnableAmendment finally switches it onfeature <hash> shows count vs threshold and the majority timestamp (count/threshold/validations require an admin connection)Next up. Activation is not just protocol, it is people. Next: voting and network coordination, how the ecosystem actually rolls a change out.
Resources
Assignments
0 of 2 complete