Stellar protocol upgrades are not activated by block height but by a validator quorum vote. When the Stellar Development Foundation (SDF) or another core developer proposes a new protocol version, it is shipped within a Stellar Core release. Node operators must first upgrade their software, but the network does not enforce the new protocol rules until a supermajority of validators explicitly vote to upgrade. This decouples software deployment from protocol activation, giving the network a coordination window.
Protocols
Protocol Version Upgrade Governance
Explains the quorum-based validator voting process for adopting new Stellar Core protocol versions. Maps the lifecycle from SDF proposal to validator ratification, detailing upgrade thresholds and coordination requirements.
introduction
THE VALIDATOR UPGRADE LIFECYCLE
How Stellar Protocol Versions Are Adopted
A quorum-based voting process governs how new Stellar Core protocol versions are proposed, ratified, and activated across the network.
The voting mechanism relies on the Stellar Consensus Protocol's (SCP) quorum set configuration. Validators cast votes for a specific protocol version by setting it in their configuration. Once a quorum threshold—typically a supermajority of the trusted nodes in a transitive quorum set—agrees on the new version, the network ratchets to it. The protocol version can only increase; downgrades are forbidden by consensus, making each upgrade a one-way migration that all operators must eventually follow to avoid being left on an incompatible fork.
This governance model places significant practical power in the hands of the SDF, which controls the reference implementation and publishes the recommended quorum set. While any validator can technically propose a version, the SDF's coordination role means its releases are the de facto upgrade path. Infrastructure teams should monitor the protocolversion field in the ledger header and the voting status of Tier-1 validators to anticipate activation. A failure to upgrade before the quorum tips results in a node that cannot interpret the new ledger state, effectively disconnecting it from the network.
VALIDATOR COORDINATION AND UPGRADE ACTIVATION
Protocol Version Upgrade Governance at a Glance
Operational impact and coordination requirements for validators, node operators, and infrastructure teams during a Stellar Core protocol version upgrade vote.
| Area | What changes | Who is affected | Action |
|---|---|---|---|
Upgrade Proposal | A new protocol version is proposed by the SDF for validator ratification. | All validators, node operators | Monitor the stellar-core repository and SDF communications for the new version proposal. |
Voting Mechanism | Validators signal readiness by upgrading their node software and updating their quorum set configuration. | Validator node operators | Upgrade to the specified stellar-core release and verify the upgrade is signaled in local node logs. |
Quorum Threshold | The network upgrades when a super-majority of validators, by quorum weight, adopt the new version. | Governance delegates, risk teams | Track validator signaling status on network dashboards to estimate time to activation. |
Activation | The ledger automatically closes and resumes with the new protocol version once the threshold is met. | Exchanges, custodians, wallets | Prepare for a brief network stall during the upgrade close. Halt deposits/withdrawals if necessary. |
Compatibility | New protocol versions are backwards-incompatible. Non-upgraded nodes diverge from the network. | All node operators, API providers | Test all SDKs, Horizon instances, and custom integrations against the new version in Testnet before mainnet activation. |
Soroban Runtime | A protocol version bump may include a new Soroban WASM runtime, altering smart contract execution. | Soroban smart contract developers | Re-test and re-deploy contracts against the new runtime environment. Verify gas cost changes. |
Rollback | There is no on-chain rollback mechanism. A faulty upgrade requires an out-of-band validator coordination event. | SDF, Tier-1 validators | Ensure a robust off-chain communication channel exists for emergency coordination. Verify against canonical source. |
technical-context
PROTOCOL VERSION GOVERNANCE
The Upgrade Lifecycle: From Core Release to Network Activation
How a Stellar Core release becomes the network's governing protocol version through a quorum-based validator voting process.
A Stellar protocol version upgrade is not complete when the Stellar Development Foundation (SDF) tags a new release of Stellar Core. The lifecycle extends from that software release through a socially coordinated, on-chain validator ratification process that ultimately determines the network's active protocol version. This governance mechanism is the critical path between a Core Advancement Proposal (CAP) being implemented in code and its rules becoming binding on the network. For node operators, the upgrade lifecycle defines a mandatory coordination window; missing it means your node will diverge from the network ledger.
The process begins when a new version of Stellar Core is released containing the logic for a protocol version bump. Validators must then independently upgrade their nodes to this new software. Once a quorum of validators—configured through the network's interdependent quorum set structure—is running the new version, they begin casting txSet and upgrade operations to signal readiness and nominate the new protocol version for the next ledger close. The network upgrades when a supermajority of the consensus quorum ratifies the version change, atomically activating all bundled CAPs. This is not a simple majority vote; it requires navigating the specific quorum slices of the Stellar network, where a failure to coordinate can lead to a network halt or a fork if a subset of the transitive quorum fails to upgrade.
The operational risk is concentrated in the ratification phase. A validator that upgrades its node but fails to coordinate its quorum set configuration may find itself on a minority fork, unable to externalize new ledgers. Infrastructure teams should monitor the upgrades field in ledger headers and the quorumset endpoint on Horizon to track signaling in real time. Chainscore Labs assists node operators and infrastructure providers by auditing quorum set configurations against the target validator set, simulating upgrade ratification scenarios, and reviewing operational runbooks to ensure a safe transition before the network-wide activation window closes.
IMPACT ANALYSIS
Who Is Affected by a Protocol Version Upgrade
Validators & Node Operators
This is the most directly affected group. A protocol version upgrade vote is a mandatory coordination event. Failure to upgrade Stellar Core before the upgrade ledger sequence results in the node diverging from the consensus ledger and effectively going offline.
Action Items:
- Monitor the
stellar-corereleases and the SDF's upgrade schedule for the target protocol version. - Test the new version in a staging or testnet environment, paying close attention to quorum set compatibility and any new configuration parameters.
- Ensure your quorum set is aligned with the rest of the network to avoid a split. A misconfigured quorum set can cause your node to accept a different ledger chain.
- Plan the binary replacement and restart process to minimize downtime. The upgrade is a "flag day" event, not a gradual rollout.
Chainscore Labs can review your node upgrade playbook and quorum configuration to ensure a safe transition.
implementation-impact
UPGRADE COORDINATION
Operational Impact and Coordination Requirements
A protocol version upgrade is a network-wide event that requires precise coordination from node operators, application developers, and infrastructure providers to prevent divergence and service disruption.
03
Horizon and API Consumer Impact
Protocol upgrades may introduce new ledger entry types, operations, or meta-data formats that Horizon must ingest and serve. API consumers—including wallets, exchanges, and analytics platforms—should test against the Horizon release that corresponds to the new protocol version. Breaking changes to resource representations or new ingestion lag during the upgrade window can cause transaction submission failures or balance display errors for end users.
04
Soroban Smart Contract Re-evaluation
If the protocol upgrade includes Soroban environment changes—such as WASM runtime bumps, host function modifications, or resource limit adjustments—existing smart contracts may behave differently. Developers must re-run test suites against the new protocol version to detect regressions. Contracts that rely on specific ledger entry rent economics or compute pricing may require re-deployment or parameter updates to remain economically viable.
05
Exchange and Custody Freeze Planning
Exchanges and custodians should plan a temporary suspension of deposits and withdrawals during the upgrade activation window. This prevents transaction submission to nodes that may be in a transient state. The freeze window should account for the time required for the quorum to ratify the upgrade and for the operator's own nodes to catch up and resync. Post-upgrade, teams must verify that transaction processing and balance reconciliation return to normal before resuming operations.
06
Monitoring and Alerting Adjustments
Operators should adjust their monitoring thresholds for the upgrade window. Metrics such as ledger close time, catchup latency, and quorum intersection health may fluctuate during the voting and activation phases. Alerting rules that trigger on normal operational variance should be temporarily widened to avoid false positives. Post-upgrade, teams should verify that all nodes are on the same protocol version and that no persistent fork has emerged.
PROTOCOL VERSION UPGRADE GOVERNANCE
Upgrade Governance Risk Matrix
Evaluates the operational, security, and coordination risks introduced by the validator voting process for Stellar Core protocol version upgrades.
| Risk Area | Failure Mode | Severity | Affected Actors | Mitigation and Action |
|---|---|---|---|---|
Validator Coordination | Insufficient validator adoption of the new protocol version before the upgrade deadline, leading to a network split or halt. | Critical | Node operators, SDF, exchanges, wallets | Monitor quorum set configuration and node version distribution. Node operators must schedule and test the upgrade well before the SDF-coordinated upgrade date. |
Quorum Centralization | A small set of validators, heavily influenced by SDF recommendations, controls the quorum threshold, allowing a unilateral protocol change. | High | Governance delegates, risk teams, protocol architects | Audit the quorum set configuration for centralization risks. Governance teams should verify the independence of Tier-1 validators and the diversity of the transitive quorum. |
SDF Proposal Authority | The SDF proposes a protocol version with breaking changes that benefit a specific ecosystem vertical, bypassing broad community consensus. | Medium | Application developers, asset issuers, DeFi protocols | Review all CAPs bundled in a protocol version upgrade. Impacted teams should participate in the governance discussion and test against release candidates to surface breaking changes early. |
Non-ratification Stalemate | Validators fail to reach the upgrade threshold, leaving the network on an old version with no clear path to resolve the deadlock. | High | All network participants | Establish a contingency plan for node operations. Infrastructure teams should model the cost of operating on a stale protocol version and engage in the governance process to break the deadlock. |
Soroban Environment Incompatibility | A protocol version upgrade changes the Soroban WASM runtime, host functions, or metering, silently breaking existing smart contracts. | High | Soroban smart contract developers, DeFi protocols | Test all deployed contracts against the new protocol version's Soroban environment in a testnet or local simulation. Monitor for changes in compute and storage resource pricing. |
API and SDK Deprecation | A protocol version upgrade deprecates Horizon API endpoints or changes the behavior of core SDK functions, breaking wallet and exchange integrations. | Medium | Wallets, exchanges, custodians, application developers | Track Stellar Core and Horizon release notes for deprecation warnings. Integration teams must run full regression tests against the upgraded network before the activation date. |
Uncoordinated Downtime | Exchanges and custodians fail to upgrade their nodes in time, leading to prolonged suspension of deposits and withdrawals. | High | Exchanges, custodians, end-users | Operations teams must align internal maintenance windows with the SDF's public upgrade schedule. Verify node readiness and block ingestion health immediately after the upgrade. |
PROTOCOL VERSION UPGRADE GOVERNANCE
Node Operator Upgrade Checklist
A practical checklist for Stellar node operators preparing for a mandatory protocol version upgrade. Each step verifies readiness for the quorum-based voting process and ensures a safe transition to the new protocol version without ledger divergence.
Confirm that the Stellar Core release you are running supports the proposed protocol version. The SDF publishes compatibility matrices with each new Core release. Running an incompatible version will cause your node to diverge from the network after the upgrade activates.
- Check the release notes for the specific Stellar Core version that introduces support for the target protocol version.
- Validate that your build includes the correct consensus and overlay protocol implementations.
- Signal of readiness:
stellar-core --versionreturns a build that lists the target protocol version as supported.
resource-links
STELLAR UPGRADE GOVERNANCE
Canonical Resources
Use these primary sources to verify Stellar protocol-version proposals, validator coordination requirements, Core release readiness, and network health during upgrade windows.
Chains We Build On
Looking to build on a specific blockchain?
We build smart contracts, DeFi applications, wallets, tokenization platforms, and blockchain infrastructure across the major ecosystems teams choose today. That includes Ethereum, Arbitrum, Optimism, Polygon, Avalanche, Solana, Sui, Aptos, Hedera, Stellar, and NEAR, with support for additional EVM and non-EVM networks based on your product requirements.
EVM ecosystems
- Ethereum
- Arbitrum
- Optimism
- Polygon
- Avalanche
- Cronos
Non-EVM ecosystems
- Solana
- Sui
- Aptos
- Hedera
- Stellar
- NEAR
Additional ecosystems
- Polkadot
- Cosmos
- TON
- Cardano
- Algorand
- Tempo
Also available for Base, appchains, custom EVM networks, and cross-chain product architecture.
UPGRADE GOVERNANCE FAQ
Frequently Asked Questions
Practical answers for node operators, infrastructure teams, and protocol architects navigating Stellar's quorum-based protocol version upgrade process.
A protocol version upgrade on Stellar requires a supermajority of the network's validators to vote for the upgrade. The specific threshold is defined by the network's consensus protocol and is typically set at a level that ensures no single entity can unilaterally force an upgrade. Node operators should verify the exact threshold against the current stellar-core configuration, as it is a function of the quorum set intersection logic. The upgrade is not activated by a simple block height; it requires a coordinated upgrades operation where validators explicitly signal their readiness. The network will only switch to the new protocol version once the required threshold of validator votes has been cast within the same ledger close window. Failure to reach quorum means the upgrade attempt times out and must be re-proposed.
Trusted by Industry Leaders
Delivering blockchain solutions for 5+ years.
We have partnered with 50+ leading DeFi protocols, NFT ecosystems, and fintech innovators to build secure, scalable, and capital-efficient blockchain products.
Selected Partners & Clients
“I've been working with Chainscore Labs for last 3+ years, they've consistently delivered with strong ownership across multiple projects. The team is reliable and detail-oriented.”
L
Lee Erswell
CEO, Telos Foundation
how to get started
How to get started?
If you're looking for blockchain integration, ChainScore Labs has 5+ years of experience helping teams build and integrate exchanges, wallets, smart contracts, tokenization solutions, and protocol-connected products, we can help you choose the right path, integrate securely, and get to production faster. Our team consists of experienced blockchain developers and architects who can help you with your blockchain integration needs.
01
Exploration & Strategy
Define your product goals and choose the right blockchain architecture for your use case.
02
Architecture & Design
Design the smart contracts, tokenomics, and security parameters of your system.
03
Development & Integration
Build and integrate with wallets, oracles, and front-end dApps for a seamless experience.
04
Security & Launch
Comprehensive audits followed by a risk-managed mainnet deployment to protect your users.
Explore More Solutions
Discover our
blockchain development services.
We build production-grade blockchain solutions for top-tier projects across DeFi and Web3.
Book a Call
Start a build
Need a blockchain engineering team?
Send the project context and we will respond with next steps, scope questions, and a practical path to delivery.