@colibri

Documentation | Runnable examples | JSR packages

TypeScript packages for Stellar transactions, Soroban contracts, authorization, testing, data ingestion, and contract build verification.

Overview

Colibri is a Deno workspace of independently published packages built on the Stellar JavaScript SDK. It keeps Stellar SDK operations, transactions, XDR values, and RPC clients as the protocol boundary, and adds reusable structure for the application workflows around them.

The central package, @colibri/core, separates transaction work into plain processes, stable pipeline steps, typed connectors, and complete callable pipelines. The other packages cover testing, authentication standards, continuous RPC ingestion, contract build verification, transaction plugins, and address identicons.

Packages

Package	Primary responsibility	Main surfaces
@colibri/core	Stellar and Soroban application primitives and transaction orchestration	Network configuration, accounts, signers, classic and Soroban pipelines, contracts, assets, ledger entries, events, typed errors
@colibri/test-tooling	Integration testing against a real local Stellar network	StellarTestLedger, named Quickstart containers, service configuration, readiness, logs, reuse, and cleanup
@colibri/webauth	SEP-10 and SEP-45 Web Authentication	stellar.toml discovery, explicit or account-based protocol routing, challenge validation, signing, and JWT retrieval
@colibri/rpc-streamer	Checkpointed event, ledger, transaction, and operation ingestion	Live RPC polling, archive RPC backfill, native operation records, recovery, checkpoints, and custom ingestors
@colibri/build-verification	Reproducible Stellar contract build verification	SEP-58 and out-of-band targets, source and image resolution, bounded Docker builds, Wasm comparison, evidence, and CLI output
@colibri/plugin-fee-bump	Fee sponsorship for transaction pipelines	Fee-bump envelope construction and fee-source authorization at the send-transaction step
@colibri/plugin-channel-accounts	Reusable transaction source accounts for concurrent workloads	Sponsored channel-account lifecycle, allocation, signer injection, and release around supported pipelines
@colibri/plugin-sep29	Opt-in recipient memo requirements	Standalone RPC checks and a non-mutating submission guard for native and fee-bump transactions
@colibri/identicon	SEP-33 account visuals with a same-algorithm C-address extension	Local pattern generation and SVG, PNG, or data-URL rendering

Packages are versioned and published separately. Applications only need to install the packages used by their runtime or development workflow.

All packages except Build Verification have stable 1.x APIs. Compatible Core updates do not require new plugin releases when their existing dependency ranges remain sufficient. See compatibility and releases for the supported SDK/runtime matrix, extension-point guarantees, and independent versioning policy. Build Verification remains on 0.x.

Installation

Install Core with Deno:

deno add jsr:@colibri/core

Or add it to a Node.js project through JSR:

npx jsr add @colibri/core

Replace @colibri/core with another package name from the table above when only that package is required.

Core architecture

Colibri's transaction architecture is layered by responsibility. Each layer is publicly reusable; higher-level APIs compose the same lower-level functions rather than maintaining separate implementations.

Layer	Responsibility	Typical use
Primitives	Networks, accounts, signers, assets, identifiers, XDR helpers, ledger keys, events, and errors	Direct protocol and data handling
Processes	One plain TypeScript execution unit with typed input, output, and failures	Reuse one operation in application-owned orchestration
Steps	A process wrapped with a stable convee identifier	Observation, plugins, and pipeline composition
Connectors	Typed conversion from one step's output to the next step's input	Preserve explicit state transitions and access earlier run context
Pipelines	Ordered end-to-end transaction workflows	Execute a standard classic or Soroban lifecycle
Domain clients	APIs that configure and invoke one or more pipelines	Work with a contract, asset, or ledger domain object

Processes, steps, and pipelines are callable values. Their composition APIs remain available on the same values, so an application can attach a plugin or replace a lifecycle boundary without changing how the workflow is invoked.

Built-in transaction pipelines

Pipeline	Execution path
Classic transaction	Load a G-address or M-address source and sequence → build from Stellar SDK operations → resolve account and operation thresholds → apply matching envelope signers → submit, confirm, and expose typed runtime outcomes
Contract read	Build an ephemeral transaction → simulate → decode and return the contract result; no envelope is signed or submitted
Contract invocation	Build → recording simulation → authorize Soroban entries → assemble and enforce delegated credentials when present → assemble resources and fees → resolve envelope requirements → sign → submit and confirm

The simulation response remains the source of Soroban resource data and authorization entries. Assembly carries that response into the transaction; applications do not need to reconstruct the footprint or resource fee.

Minimal classic transaction

The following Testnet example uses a callable pipeline directly. See the complete quick start for setup notes and the examples repository for standalone projects.

import {
  createClassicTransactionPipeline,
  initializeWithFriendbot,
  LocalSigner,
  NetworkConfig,
} from "@colibri/core";
import { Asset, Operation } from "stellar-sdk";

const network = NetworkConfig.TestNet();
const sender = LocalSigner.generateRandom();
const recipient = LocalSigner.generateRandom();

for (const signer of [sender, recipient]) {
  await initializeWithFriendbot(network.friendbotUrl, signer.publicKey(), {
    rpcUrl: network.rpcUrl,
    allowHttp: network.allowHttp,
  });
}

const sendPayment = createClassicTransactionPipeline({
  networkConfig: network,
});

const result = await sendPayment({
  operations: [Operation.payment({
    destination: recipient.publicKey(),
    asset: Asset.native(),
    amount: "1",
  })],
  config: {
    source: sender.publicKey(),
    signers: [sender],
    fee: "100",
    timeout: 30,
  },
});

console.log(result.hash);
console.log(result.feeCharged);

const payment = result.operations[0];
if (payment.type === "payment") {
  console.log(payment.result.type); // paymentSuccess
}

Signers and authorization

Transaction-envelope authorization and Soroban authorization entries are separate capabilities. A signer may implement either capability or both, and the relevant process narrows the signer before invoking it.

Core includes implementations for:

Signer	Capability
LocalSigner	Ed25519 envelope signatures, Soroban authorization entries, and optional SEP-53 message signing
HashXSigner	Hash-X envelope authorization using a preimage
Ed25519SignedPayloadSigner	Ed25519 signed-payload envelope authorization
PreAuthorizedTransactionSigner	Validation of an exact pre-authorized transaction hash without adding a decorated signature
DelegatedSigner	Recursive delegated Soroban authorization entries

Applications can implement the same interfaces for wallets, remote signing services, hardware devices, or contract-specific authorization. The pipeline matches signers to requirements through signsFor(...); it does not assume that every signer owns an accessible secret key.

MessageSigner is an independent optional capability, narrowed with isMessageSigner. SEP-53 message signatures use the Stellar SDK's domain-separated format; they do not authorize a transaction or supply an application's replay-protection policy.

Contracts, assets, and ledger data

Core exposes domain-specific actions alongside lower-level protocol reads:

• StellarAsset owns a classic transaction pipeline for explicit trustline, transfer, issuance/redemption, authorization and clawback actions on a native SDK Asset. It reads balances and holder state, exposes identity/precision and exact amount conversion, and binds the SAC explicitly with toContract(). Transfers never silently add trustlines or switch to Soroban.

• SDEX manages known sell, buy, and passive offers. sell and buy variants express minimum receive or maximum spend per unit, while StellarPrice converts exact decimal limits or quantity ratios without silently rounding them. Equivalent unit names are available for updates and passive offers.

• NativeLiquidityPool binds a protocol-native pool, reads its reserves, and exposes explicit pool-share trustline, deposit, and withdrawal operations. Asset-labelled amounts and price bounds avoid requiring callers to remember A/B order. Position reads combine pool reserves and the holder's share trustline in one RPC observation.

• ClaimableBalancePredicates groups static time and boolean helpers that return native SDK predicates, including time windows and balanced all/any lists; claiming or refunding still needs an explicit transaction.

• Contract loads contract specifications, binds deployed contracts, deploys Wasm or external executable references, and routes reads and invocations through the standard pipelines. It can also extract SEP-46 metadata, parse SEP-47 claims, and compare SEP-48 specifications with versioned standard interface providers without treating a declaration as proof of a match.

• SEP41TokenContract provides the exact portable SEP-41 interface for custom token contracts, including muxed transfer destinations, while retaining its underlying Contract for implementation-specific methods.

• StellarAssetContract provides typed operations for Stellar Asset Contract administration, balances, allowances, authorization, minting, burning, and transfers.

• LedgerEntries reads typed current-state entries, including accounts, contract instances, contract code, data, and configuration.

• ledger parsing and event schemas turn closed-ledger XDR and contract events into typed application data.

Use RPC Streamer when event, ledger, transaction, or operation processing must continue over time. It owns pagination, checkpoints, archive backfill, the transition to live RPC, and waiting at the network head. It does not replace Core's typed parsing or current-state readers. Transaction/operation variants include failures with explicit transaction status; an operation present in an envelope is not proof that it executed successfully.

The native asset, exchange, and pool classes use the existing callable transactionPipe and its plugin boundaries. These are known-object workflows, not an order-book service, market indexer, or best-price discovery engine. See the SDEX guide, native pool guide, and asset guide.

SDEX, native liquidity pools, and their exact rational price helpers are grouped under core/markets/. They remain named exports of @colibri/core and accept native SDK assets and operation inputs. StellarAsset supplies asset-level balance and authorization queries, explicit mint/burn payments, issuer authorization control, and creation of claimable balances with native claimants.

Testing with Quickstart

@colibri/test-tooling manages Docker-backed Stellar Quickstart instances for tests that require ledger behavior. StellarTestLedger controls the container name, image, network, enabled services, ports, readiness, logs, reuse policy, and cleanup, then exposes network values that can be used by Core.

Use a local ledger for behavior that a mock cannot establish, including:

• account sequences and transaction submission;
• contract deployment, simulation, and authorization;
• Soroban resource assembly and fee handling;
• emitted events and persisted ledger state;
• fee-bump and channel-account lifecycle behavior.

Pure conversion, validation, and requirement logic should remain in unit tests.

Authentication and Stellar standards

@colibri/webauth implements two distinct Web Authentication flows:

• SEP-10 for classic or muxed accounts, including challenge structure, account and memo binding, domains, time bounds, and server-signature validation;
• SEP-45 for contract accounts, including application-provided authorization of the complete Soroban entry and enforcing simulation before the challenge is returned to the server.

The unified client can select the flow from the requested account type, or an application can select SEP-10 or SEP-45 explicitly. It does not retry one protocol as a fallback for the other.

Standard-oriented functionality across the workspace includes:

Standard	Implementation
SEP-1	stellar.toml retrieval and typed discovery in Core
SEP-10	Classic-account Web Authentication in WebAuth
SEP-29	Opt-in account memo requirements in the SEP-29 plugin
SEP-11	Canonical Stellar asset identifiers in Core
SEP-23	StrKey encoding and validation in Core
SEP-33	Reference-compatible Stellar identicons in Identicon
SEP-35	Operation identifiers and TOID helpers in Core
SEP-40	Versioned price-feed interface analysis in Core
SEP-41	Standard token client and version-compatible event schemas in Core
SEP-53	Optional message-signing capability and LocalSigner implementation in Core
SEP-44, SEP-50, SEP-56, SEP-57	Versioned contract-interface providers and structural analysis in Core
SEP-45	Contract-account Web Authentication in WebAuth
SEP-46	Ordered contract metadata extraction in Core
SEP-47	Contract-interface claim discovery in Core
SEP-48	Contract specification extraction and interface matching in Core
SEP-58	Contract build verification in Build Verification

Refer to each package's documentation for its exact version and support boundary.

Transaction operations and scaling

@colibri/plugin-sep29 adds opt-in memo-presence checks for payments, path payments, and account merges using RPC account-data reads. It respects muxed destinations and checks fee-bump inner transactions without changing either the memo or the envelope. Pass a native SDK Memo through TransactionConfig.memo. See SEP-29.

Core's wrapSponsorship composes native reserve-sponsorship blocks for account creation, trustlines, and other reserve-bearing entries. It preserves the operations you provide and uses the normal pipeline signer list. This pays reserves without transferring XLM to the sponsored account; it does not pay transaction fees. See Reserve sponsorship.

The transaction plugins attach policy at stable pipeline boundaries:

• @colibri/plugin-fee-bump targets the send-transaction step. It wraps the completed inner transaction in a fee-bump envelope and authorizes the fee source separately.
• @colibri/plugin-channel-accounts targets complete classic and contract invocation pipelines. It allocates a reusable source account before the transaction is built, injects its signer, and releases the account after success or failure.

Fee sponsorship and source-account allocation solve different problems and can be composed. Channel accounts isolate sequences across concurrent submissions; fee bumps let another account pay the network fee.

Contract build verification

@colibri/build-verification verifies that declared source and build inputs reproduce the exact Wasm deployed on Stellar or supplied directly. It supports contract IDs, Wasm hashes, external executable references, and direct Wasm, then resolves the source and OCI image, runs the build in a bounded Docker container, selects the declared artifact, and compares the bytes.

The library API and CLI return structured results, logs, and evidence. A successful comparison establishes build reproducibility and byte equality; it is not a source-code audit or a statement about contract safety.

Extension and error contracts

Stable pipeline and step identifiers are public extension points. Plugins can target a complete pipeline or a specific step without patching transaction objects at unrelated stages. Custom pipelines can reuse exported processes and connectors, while domain clients can configure those pipelines behind a contract- or asset-focused API.

Public workflows use typed error families with stable codes and structured metadata. Callers should narrow the error type or code for retry, observability, and user-facing decisions instead of parsing message strings. The generated error reference lists the declared errors by package and context.

Important boundaries

• stellar.toml provides discovery data; retrieving it does not establish trust in the domain or its services.
• An identicon is a visual cue, not proof of account ownership and not a replacement for checking the complete address.
• A successful transaction proves network acceptance, not application-level correctness.
• A successful build verification proves byte equality for the selected inputs, not contract safety.
• Secret management remains the responsibility of the signer implementation; transaction construction does not require direct access to secret keys.

Repository layout

core/                         Core package and transaction architecture
build-verification/           Contract build-verification library and CLI
webauth/                      SEP-10 and SEP-45 Web Authentication
rpc-streamer/                 Checkpointed ledger and event ingestion
identicon/                    SEP-33-compatible identicon generation
plugins/fee-bump/             Fee-bump pipeline plugin
plugins/channel-accounts/     Channel-account tools and pipeline plugin
test-tooling/                 Docker-backed Quickstart test infrastructure
docs/                         GitBook guides and generated error reference
_internal/                    Repository-only test fixtures and contracts
_tools/                       Documentation, lint, coverage, and build tooling

_internal/ and _tools/ are repository infrastructure and are not published as packages.

Development

This repository uses Deno workspace tasks from deno.json.

Tests

# Unit and integration tests
deno task test

# Unit tests only
deno task test:unit

# Integration tests only
deno task test:integration

Integration tests require the external services used by the selected package; Quickstart-backed tests also require Docker.

Package checks

deno lint
deno task check
deno task check:jsr
deno task check:slow-types
deno task check:package-versions
deno task check:crap

Documentation

Follow the documentation conventions: link documented concepts where they are mentioned, connect parent pages to their child guides, and keep shared explanations in one canonical place. Links belong beside code examples so the examples remain runnable.

GitBook content is under docs/, with navigation in docs/SUMMARY.md.

# Regenerate the error catalog after changing declared errors
deno task docs:errors

# Test documentation tooling and validate links, navigation, and examples
deno task test:docs
deno task check:docs

Complete TypeScript examples use a <!-- deno-check --> marker before the code fence so CI type-checks them without executing external effects.

License

MIT License. See LICENSE.

Contract bindings

Generate typed contract clients from Wasm, a Wasm hash, or a contract ID with @colibri/contract-bindings. The Deno CLI supports prompts and flags, source files or JSR/npm packages, embedded specs, constructor error maps, and typed Core event definitions.

React applications

@colibri/react adds headless React hooks for connections, queries, contracts, existing transaction pipelines, events and SEP integrations. See the React guide for setup and feature imports.