> For the complete documentation index, see [llms.txt](https://fifo-docs.gitbook.io/colibri/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fifo-docs.gitbook.io/colibri/getting-started/compatibility.md).

# Compatibility and releases

[Core](/colibri/colibri-core/overview.md), [WebAuth](/colibri/colibri-webauth/webauth.md), [RPC Streamer](/colibri/colibri-rpc-streamer/rpc-streamer.md), [Identicon](/colibri/colibri-identicon/identicon.md), [Test Tooling](/colibri/colibri-test-tooling/test-tooling.md), and the [channel-account](/colibri/plugins/channel-accounts.md), [fee-bump](/colibri/plugins/fee-bump.md), and [SEP-29](/colibri/plugins/sep29.md) plugins start their stable release lines at **1.0.0**. Build Verification remains on **0.x** while its API continues to mature. Packages have independent versions; matching version numbers are not a requirement for using them together.

## Stable API contract

The compatibility contract covers documented public exports, accepted inputs, return types, error codes and documented programmatic error fields. It also covers the extension points used to integrate Colibri into an application:

* Consumer-defined signers and optional signer capabilities.
* Supported class subclassing and public configuration types.
* Callable processes, steps, and pipelines, their stable IDs, and plugin targets.
* Documented lifecycle/hook ordering, cleanup, units, defaults, and transaction semantics, including fees, memos, sources, and authorization.
* Interoperability with native Stellar SDK operations, transactions, XDR values, specs, keys, and RPC clients within the supported dependency range.

An auxiliary type used in a public signature is part of that signature's compatibility boundary, even if it is marked `@internal` to reduce generated documentation noise. Private implementation files and undocumented deep imports are not additional entrypoints. Human-readable error wording can improve without changing an error's stable code or documented structured fields.

## Choosing a version change

| Change                                                                                                       | Release                        |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------ |
| Compatible correction to documented behavior                                                                 | Patch, such as 1.0.1           |
| New optional method, standalone helper, standard, or capability                                              | Minor, such as 1.1.0           |
| Removed method/input, changed fee units/defaults, required signer method, or incompatible result/error shape | Major, such as 2.0.0           |
| Dropped supported runtime or broken native SDK/plugin interoperability                                       | Major for the affected package |

Adding a new member to a promised closed union can break exhaustive TypeScript consumers. Protocol fields explicitly documented as extensible are different: callers must continue to handle their documented unknown values. Compatibility is reviewed from the consumer's perspective, not just from the number of changed lines or the dependency's own version number.

Deprecations can be introduced in a minor release while the existing API keeps working. Removal belongs to a later major. A Stellar SDK or Convee major update requires an interoperability review; its version number alone does not determine Colibri's bump. Colibri does not hide an incompatible SDK change behind a new wrapper solely to avoid a major release.

## Core 3.0 and SDK 17.2.1 migration

This release requires Stellar JavaScript SDK **17.2.1 or later within 17.x**. Use one compatible resolved SDK throughout the application. Core, WebAuth, RPC Streamer, Identicon and the three plugins move to **3.0.0** because their native SDK or Core interoperability boundary changes. Test Tooling moves from 1.1.0 to **2.0.0** because its recorder directly decodes SDK transactions, events and ledger changes; Quickstart still has no Core dependency. Preview packages move to Build Verification **0.6.0**, Contract Bindings **0.5.0** and React **0.6.0**. Each dependency floor is recorded in the package manifest.

Review these observable corrections when upgrading:

* [Named structs](/colibri/colibri-core/contract/values.md#named-record-evolution) decode by field name, normalize omitted optional fields and ignore unknown fields by default. Required fields and wire types remain validated. Inputs encode dense records, and [typed maps](/colibri/colibri-core/contract/values.md#compose-types-and-values) sort without mutating inputs and reject duplicate encoded keys.
* [ABI events](/colibri/colibri-core/contract/events.md#sparse-map-data-and-ambiguity) accept sparse optional data fields. Choose an explicit declaration when multiple event shapes match. [SEP-41 events](/colibri/colibri-core/overview-1/standardized-events/sep-41.md) validate wire types and match topic prefixes; generic templates retain exact topic matching by default. [RPC filters](/colibri/colibri-core/overview-1/event-filter.md) support four constraints followed by `**`, independently of event topic count.
* [Interface catalogs](/colibri/colibri-core/contract/metadata-and-interfaces.md) expose SEP-41 0.5.2 and SEP-57 0.4.0, preserving historical providers. SEP-57 minimum profiles are opt-in and do not weaken existing reference checks.
* Use [SEP-35 operation IDs](/colibri/colibri-core/toid.md#sep-0035-structure) for new standard operation identifiers. Existing Colibri event IDs and RPC cursors keep their historical encoding; do not rewrite stored cursors.
* Recompute [liquidity-pool IDs](/colibri/colibri-core/liquidity-pool.md#sdk-1721-asset-ordering) cached from same-code, different-issuer assets under older SDKs. This is local derivation; no on-chain pool or balance changes.
* [TOML discovery](/colibri/colibri-core/sep1.md#fromdomaindomain-options) rejects malformed hosts before transport. [SEP-58 metadata](/colibri/colibri-build-verification/sources.md#sep-58-field-grammar) now validates complete ASCII field grammar before retrieval/build policy.

The [lossless map helper](/colibri/colibri-core/helpers.md) is opt-in. Existing `parseScVal` results, event output properties, method signatures and stored identifiers retain their documented shapes. Regenerate [bindings](/colibri/colibri-contract-bindings/contract-bindings.md) to pick up the current dependency floor and optional named input fields.

## Core 2.0 SAC identity migration

[StellarAssetContract](/colibri/colibri-core/asset/stellar-asset-contract.md) now guarantees a complete public readonly `code` and `issuer` for every client. The issuer is the original Classic asset issuer, independent of the mutable SAC administrator; XLM uses `"native"` as its issuer marker.

* Await [fromContractId](/colibri/colibri-core/asset/stellar-asset-contract.md#from-a-known-contract-id), which now resolves and validates the instance through one RPC read.
* Replace contract-id-only constructor calls with that asynchronous factory.
* Keep [fromAsset and full-identity construction](/colibri/colibri-core/asset/stellar-asset-contract.md#from-a-classic-asset) synchronous. These paths derive identity locally and do not check deployment.
* Handle resolution failures at construction time, including unavailable instances, non-SAC executables, malformed metadata and wrong-network ids. See the [SAC error reference](/colibri/reference/errors/core-asset-sac.md).

This is a major Core release because the return type and constructor inputs change. The accompanying packages adopt Core 2.0: stable packages move to 2.0 and preview packages increment their minor version. Existing Core 1.x applications should keep their previous compatible package versions. The exact migration examples are in the [SAC guide](/colibri/colibri-core/asset/stellar-asset-contract.md#migrating-from-core-1x).

## Dependency floors

A plugin using `@colibri/core@^1.0.0` can keep that dependency and its own version when Core publishes a compatible 1.0.1 or 1.1.0. It does not need a release merely to repeat Core's new version number.

If the plugin starts using a method introduced in Core 1.2.0, its next release must require at least that version. A higher minimum can also be necessary to guarantee a Core bug fix. Adopting Core 2.x requires a separate compatibility decision for each dependent package.

Keep the native Stellar SDK version compatible throughout the application's dependency graph. For npm consumers, avoid loading duplicate Core or Convee instances when passing errors or runtime contexts across package boundaries. JSR documents npm alias/deduplication limitations and recommends pnpm where duplicate installations are a concern. See [JSR npm compatibility](https://jsr.io/docs/npm-compatibility).

[Contract Bindings](/colibri/colibri-contract-bindings/contract-bindings.md) starts at 0.1 as a preview. Its portable root API supports Deno/Node tooling; its `/cli` entrypoint is Deno-only. Generated JSR and npm clients use Core 3.0 or later within 3.x.

[React](/colibri/colibri-react/react.md) starts at **0.1** as a headless preview. The current release requires Core 3.0+, React 19.1+ within 19.x and TanStack Query 5.87+ within 5.x. Apps own their React, QueryClient and wallet integrations; keep one resolved React instance. The consumer matrix covers SSR, hydration, connection updates, shared bigint query data and SVG rendering. The local Stellar integration suite also executes contract read/invoke, Classic payment, Soroban simulation/submission and events. Freighter is tested through its injected API boundary, without claiming live extension coverage for every supported wallet/version.

## Supported and tested integrations

| Surface                           | Compatibility boundary and CI checks                                                               |
| --------------------------------- | -------------------------------------------------------------------------------------------------- |
| Stellar JavaScript SDK            | `>=17.2.1 <18`; exact 17.2.1 and freshly resolved compatible 17.x                                  |
| Convee                            | Exact [2.4.1](https://jsr.io/@fifo/convee/2.4.1); public composition and plugin lifecycle fixtures |
| Deno                              | Minimum 2.7.11 and 2.9.6; each runtime's bundled TypeScript compiler                               |
| Node.js                           | Minimum 22.12.0, current patched 22.x, and 24.x LTS                                                |
| TypeScript in npm consumers       | 5.9.3 and 6.0.3                                                                                    |
| Browsers                          | Playwright-pinned Chromium, Firefox, and WebKit; actual engine versions appear in CI logs          |
| Quickstart and Build Verification | Deno and Docker integration                                                                        |
| Test execution recorder           | Deno BDD and Node native test runner; shared capture, aggregation, CLI and offline HTML reports    |

Use current patched supported runtimes in applications. The oldest runtime in the matrix is a compatibility fixture, not a security recommendation. Browser tests execute real SDK signing/binary operations, identicon rendering, and callable pipeline/plugin composition. WebKit coverage is not a claim that every Safari version or operating system was tested. Network operations still depend on the provider's availability, protocol support, and browser CORS policy.

## How compatibility is checked

CI validates a reviewed release plan and normalized public declaration changes early. Preserved 1.0 consumers compile and execute against candidate packages, including native SDK objects, custom signers, subclassing, plugins, and typed errors. A single `compatibility` check groups the Deno, installed npm, browser and released-Core scenarios into named steps, with individual logs and a complete results table. Minimum and latest-compatible SDK selections are resolved once; identical resolved versions share one matrix, while distinct versions both run all supported combinations. Failed or missing results fail the check.

Dependent packages are also checked against the oldest available Core release accepted by their range. Conversely, the earliest still-compatible dependent release is checked against candidate Core. These use immutable Git release trees in isolated import maps, without workspace substitution. During the first 1.0 release there is no prior compatible 1.x artifact: CI reports that bootstrap explicitly, and historical checks begin once those release tags exist.

The normal package suites, integration tests, coverage aggregation, architecture rules, and CRAP threshold remain in place. Consumer fixtures are additional compatibility evidence, not coverage padding. After publication, another check installs the actual JSR modules and JSR-generated npm distributions; pre-release test artifacts are not presented as equivalent to the published artifacts.

No declaration tool can determine whether a changed default or runtime behavior is compatible. The release diff and compatibility evidence still require review.

## Maintenance policy

Maintenance focuses on the current release line. There is no standing LTS duration, automatic backport commitment, or set of older-major adapters. If a concrete need for an older major arises, its scope and support approach will be discussed separately. This does not relax the compatibility commitment within the current stable major.