Every Stellar protocol upgrade, from the introduction of Soroban in Protocol 20 to subsequent cost model and state archival changes, directly alters the data structures that Horizon indexes and serves. These changes are not cosmetic; they introduce new transaction meta formats, new ledger entry types, and new resource fields that exchanges, wallets, and data indexers must parse correctly to avoid integration breakage. The Horizon API is the primary interface for reading Stellar network state, and its response schemas are tightly coupled to the XDR definitions that evolve with each protocol version bump.
Protocols
Horizon API Changes from Protocol Upgrades
Documents how new protocol features manifest in the Horizon data API. Covers new endpoints, new fields in existing resources like Soroban transaction meta, and deprecated response formats. Exchanges, wallets, and data indexers must handle these changes to avoid integration breakage.
introduction
API SURFACE EVOLUTION
Introduction
How Stellar protocol upgrades manifest as new endpoints, modified fields, and deprecated response formats in the Horizon data API.
The most significant recent shift was the addition of Soroban transaction meta in Protocol 20, which introduced a new tx.result.meta structure for smart contract invocations. This required Horizon to serve new resource types like soroban_transaction_data and expose fields such as diagnostic_events, return_value, and footprint within the standard transaction response. Subsequent upgrades, such as Protocol 21, refined these structures and added new host functions, which in turn altered the cost and resource models reflected in the API. Operators who do not update their parsing logic risk silent data corruption or rejected transactions.
Beyond new fields, protocol upgrades can deprecate entire response formats. Horizon's API versioning strategy, which uses a X-Client-Version header and a latest pointer, means that teams must actively track the deprecation window for old response schemas. A mandatory Stellar Core upgrade that bumps the protocol version will eventually force a corresponding Horizon release that drops support for deprecated fields. Infrastructure providers should treat each protocol upgrade as a trigger for a full integration review, including re-validation of all Horizon queries, event stream parsing, and SDK compatibility.
PROTOCOL-TO-API IMPACT MODEL
Quick Facts: Horizon API Change Lifecycle
How protocol upgrades propagate into Horizon API changes and what integration teams must do to avoid breakage.
| Area | What changes | Who is affected | Action |
|---|---|---|---|
New Endpoints | Protocol features like new Soroban host functions or operations may introduce entirely new Horizon endpoints to query the resulting ledger state. | Exchanges, wallets, data indexers | Review Horizon release notes for new paths. Plan integration and parsing logic before the protocol upgrade activates. |
Resource Representation | Existing resources (e.g., transactions, operations, effects) can gain new fields in their JSON response to expose new protocol metadata, such as Soroban diagnostic events or extended result codes. | Wallets, block explorers, analytics platforms | Test response parsing against all expected transaction types on Testnet. Update deserialization logic to be forward-compatible with unknown fields. |
Deprecated Fields | Fields tied to pre-Soroban transaction meta or legacy operations may be deprecated and eventually removed, breaking strict parsers. | All API consumers | Monitor Horizon changelogs for deprecation notices. Migrate to replacement fields during the announced grace period. |
Streaming Behavior | New ledger entry types or state changes can alter the volume and ordering of events in Horizon's streaming endpoints, affecting real-time consumers. | Market makers, real-time alerting systems | Load-test streaming ingestion against Testnet under protocol upgrade conditions. Adjust reconnect and backpressure logic. |
Ingestion Lag | Horizon's internal ingestion pipeline must be updated to parse new XDR schemas. A lag in Horizon release can cause API unavailability or stale data post-upgrade. | Node operators, infrastructure providers | Verify that the Horizon version you run is compatible with the target protocol version before the upgrade ledger. Plan a coordinated Core and Horizon upgrade. |
Soroban-Specific Meta | Soroban transaction meta includes new structures like contract events, return values, and diagnostic info that Horizon must decode and expose. | Soroban dapp frontends, indexers, auditors | Update event filtering and decoding logic to handle new meta formats. Re-verify contract monitoring dashboards. |
Rate Limiting | New endpoints or increased query complexity from richer data can trigger stricter rate limiting, impacting high-frequency consumers. | High-frequency trading desks, large-scale indexers | Re-evaluate query patterns and cache strategies. Engage with infrastructure providers about rate limit adjustments. |
technical-context
THE PROTOCOL-TO-API PIPELINE
How Protocol Changes Become API Changes
A protocol upgrade is not complete until downstream APIs, SDKs, and indexers correctly expose the new ledger state. This section explains how Stellar protocol changes propagate into the Horizon API.
When a Stellar protocol version is upgraded via validator consensus, the new rules immediately govern what is valid inside a transaction envelope and how the ledger state is mutated. However, the Horizon API—the primary data interface for most exchanges, wallets, and applications—does not automatically reflect these changes. The Stellar Development Foundation must explicitly map new protocol primitives into Horizon's resource representations, which creates a critical time gap between protocol activation and API readiness that integration teams must plan for.
The most significant recent example is the introduction of Soroban smart contracts in Protocol 20. The protocol began producing a new transaction meta format (TransactionMetaV3) containing Soroban-specific host function traces, contract events, and resource consumption data. Horizon had to introduce new endpoints (/transactions/{hash}/effects, new fields on the transaction resource) and deprecate older response shapes. A wallet querying a Soroban transaction before its Horizon instance was updated would receive a 500 Internal Server Error because the API could not parse the new meta format—a breaking change that required coordinated SDK and backend upgrades.
For operators and integration engineers, the operational rule is straightforward: a protocol version bump that introduces new ledger entry types, operation result codes, or transaction meta versions will require a corresponding Horizon major version release. Teams should monitor the stellar/horizon and stellar/go repositories for release candidates that coincide with protocol upgrade dates. Chainscore Labs can assist with integration impact assessments, staging environment validation, and regression testing to ensure that wallets, indexers, and trading engines handle new response schemas without data loss or downtime.
INTEGRATION IMPACT BY ACTOR
Affected Systems and Teams
Exchange & Custodian Impact
Horizon API changes from protocol upgrades directly affect deposit/withdrawal pipelines, balance reconciliation, and transaction monitoring.
Immediate actions:
- Audit ingestion logic for new fields in transaction meta, especially for Soroban operations that may alter balance-change semantics.
- Update internal ledgers to handle new operation types and effects without rejecting them as unknown.
- Test against the new Horizon version in a staging environment before mainnet activation.
Risks:
- Unrecognized operation types can halt processing pipelines.
- Deprecated fields may return null or disappear, breaking reconciliation scripts.
Chainscore can review your Horizon integration code and test suites to ensure compatibility before the protocol upgrade activates.
implementation-impact
HORIZON INTEGRATION IMPACT
Common API Change Patterns
Protocol upgrades introduce predictable categories of change to the Horizon API. Recognizing these patterns helps exchanges, wallets, and data indexers scope integration work before a release reaches Mainnet.
02
New Fields in Existing Resources
Existing resources like transactions, operations, and effects often gain new fields to expose richer protocol data. For example, Soroban transaction meta adds fields for contract events, return values, and diagnostic information. Downstream systems with strict schema validation will reject these responses unless their models are updated. Test against Testnet responses early to catch parsing failures.
05
Soroban-Specific Meta Changes
Soroban upgrades frequently alter the structure of transaction meta for smart contract invocations. This includes changes to host function footprints, event payloads, and resource consumption diagnostics. Indexers that extract Soroban data for analytics or compliance must adapt their parsing logic. A contract call that succeeds on Testnet may produce meta that an older Horizon client cannot deserialize.
06
Ingestion Filtering and Pagination
New resource types or fields can break ingestion filters that rely on specific operation or effect types. A filter designed for classic payment operations will miss new Soroban transfer semantics. Additionally, pagination behavior may shift if default limits or cursor formats change. Teams should run a full historical re-ingestion against a Testnet archive to validate their filtering and pagination logic before Mainnet activation.
HORIZON API BREAKING CHANGE SURFACE
Integration Risk Matrix
Map of integration points that break or change behavior when new protocol features are exposed through Horizon. Use this to prioritize testing and remediation before a network upgrade activates.
| Area | What changes | Who is affected | Action |
|---|---|---|---|
New endpoints | Horizon may expose new resource collections or sub-resources for novel protocol features (e.g., Soroban contract events, state archival queries). | Data indexers, block explorers, analytics platforms | Audit new endpoint schemas against your ingestion pipeline. Verify pagination, rate limits, and field completeness before production reliance. |
New fields in existing resources | Existing resources like transactions, operations, or effects gain additional fields to represent new protocol metadata (e.g., Soroban diagnostic events, extended result codes). | Wallets, exchanges, custody platforms | Test deserialization of enriched responses. Ensure your parser does not reject unknown fields and that display logic handles new data types correctly. |
Deprecated response formats | Horizon may drop legacy fields, change HAL link structures, or remove previously optional attributes when a protocol version becomes mandatory. | All API consumers | Run integration tests against the target Horizon version with deprecated fields explicitly removed. Update any code that relies on removed attributes or link relations. |
Soroban transaction meta structure | The transaction envelope and result meta for Soroban invocations can change structure across protocol versions, adding new diagnostic or fee components. | Contract developers, block explorers, auditors | Re-parse historical Soroban transactions against the new meta schema. Confirm that fee calculation, event extraction, and error decoding remain accurate. |
Streaming and cursor behavior | Protocol upgrades that alter ledger close timing or transaction ordering can cause cursor gaps or duplicate events in Horizon's streaming endpoints. | Real-time data consumers, market makers, alerting systems | Monitor streaming connections during testnet upgrades for gaps or replays. Implement idempotency and cursor checkpointing to handle potential resets. |
Ingestion and history archive changes | Horizon's ingestion pipeline may require updated history archive access patterns or new bucket list formats introduced by the protocol. | Self-hosted Horizon operators, data warehouse pipelines | Verify that your Horizon instance can ingest the new protocol's history archives. Test catchup from a fresh state to confirm no schema migration failures. |
SDK compatibility | XDR schema changes in the protocol propagate to Horizon responses and force major version bumps in Stellar SDKs. | Application developers, integration engineers | Audit SDK release notes for the Horizon version you target. Plan SDK upgrade work alongside Horizon upgrade to avoid type mismatches and deserialization errors. |
Rate limiting and resource usage | New protocol features may generate larger or more frequent Horizon responses, changing effective rate limit consumption for existing query patterns. | High-frequency traders, data indexers, analytics platforms | Profile response sizes and query rates against the upgraded Horizon. Adjust pagination strategies and caching layers to stay within rate limits. |
HORIZON API READINESS
Pre-Upgrade Integration Checklist
A structured checklist for exchanges, wallets, and data indexers to validate their Horizon integration against a new Stellar protocol version before it activates on Mainnet. Each item identifies a specific change vector, why it matters, and the signal that confirms readiness.
What to check: Confirm that your Stellar SDK version supports the new XDR schema introduced by the protocol upgrade. New operations, result codes, or envelope types will cause deserialization failures if the SDK is out of date.
Why it matters: An incompatible SDK will fail to parse new transaction meta or submit new operation types, leading to stalled withdrawals, failed deposits, or broken history ingestion.
Readiness signal: Your integration tests pass against Testnet using the target SDK version, and you can successfully deserialize all new transaction and ledger structures without XDR parsing error logs.
resource-links
OFFICIAL REFERENCES
Canonical Resources
Use these sources to verify how Stellar protocol upgrades propagate into Horizon responses, XDR decoding, SDK behavior, and indexer compatibility. Teams should compare documentation with release notes and implementation changes before upgrading production integrations.
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.
HORIZON INTEGRATION IMPACT
Frequently Asked Questions
Common questions from exchanges, wallets, and data indexers about how protocol upgrades change the Horizon API surface and what steps are required to maintain integration integrity.
Review the Stellar Core release notes and the corresponding CAP for the protocol version bump. Look for changes to XDR schemas, new operation types, or new fields in transaction meta. The key signals are:
- New XDR union arms: A new
OperationTypeorAssetTypewill appear in Horizon responses. If your parser rejects unknown enum values, it will break. - New meta fields: Soroban upgrades often add fields to
TransactionMeta. If you deserialize transaction history, new optional fields may cause strict parsers to fail. - Deprecated endpoints or fields: Horizon may remove or change the shape of fields that were previously marked as deprecated.
Test against the Horizon instance on Testnet before the Mainnet upgrade date. If you maintain an internal indexer, verify that it can ingest and serve the new ledger format.
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.