@colibri

A TypeScript-first toolkit for building robust Stellar and Soroban applications with deterministic error handling, composable workflows, and extensible plugin architecture.

📚 Documentation | 💡 Examples

Packages

@colibri/core

The foundation of the Colibri ecosystem. Provides pipelines, processes, and utilities for Stellar and Soroban workflows.

deno add jsr:@colibri/core
# or
npm install @colibri/core

View Documentation →

---

@colibri/sep10

A SEP-10 web authentication client for Stellar, with full-flow helpers, challenge validation, JWT handling, and flexible signer support.

deno add jsr:@colibri/sep10
# or
npm install @colibri/sep10

View Documentation →

---

@colibri/plugin-fee-bump

A plugin that enables fee sponsorship by wrapping transactions in Fee Bump Transactions.

deno add jsr:@colibri/plugin-fee-bump
# or
npm install @colibri/plugin-fee-bump

View Documentation →

---

@colibri/plugin-channel-accounts

A plugin and channel management helper for reusing sponsored Stellar channel accounts across classic and Soroban transaction pipelines.

deno add jsr:@colibri/plugin-channel-accounts
# or
npm install @colibri/plugin-channel-accounts

View Documentation →

---

@colibri/rpc-streamer

A real-time event streaming client for Stellar/Soroban that supports live streaming, historical ingestion, and automatic mode switching.

deno add jsr:@colibri/rpc-streamer
# or
npm install @colibri/rpc-streamer

View Documentation →

---

@colibri/test-tooling

Docker-backed test infrastructure helpers for Colibri packages, centered on StellarTestLedger for local Quickstart-based integration tests.

deno add jsr:@colibri/test-tooling

View Documentation →

---

Core Concepts & Standards

Colibri is designed around a specific mindset to ensure reliability and debuggability in blockchain applications. It is built on top of the Convee framework, leveraging its patterns for functional, railway-oriented programming.

1. Deterministic Error Handling

We do not throw generic errors. Every error in Colibri is a typed ColibriError containing:

• Domain: The logical area (e.g., Pipeline, Process, Account).
• Code: A stable, unique identifier (e.g., PIPE_INVC_002).
• Meta: Structured data relevant to the error context.
• Diagnostic: Human-readable suggestions for resolution.

2. Pipelines, Processes & Steps

The architecture separates orchestration from execution, promoting reusability and testability.

• Processes (The "How"): Atomic functions that do one thing well. They are plain reusable building blocks, independent from orchestration.

  • Example: signAuthEntries takes Soroban auth entries plus signers and returns signed authorization entries.
  • Example: simulateTransaction takes a transaction, sends it to the RPC, and returns simulation results.

• Steps (The orchestration boundary): Thin convee wrappers around processes. They attach stable step ids, plugin targets, and runtime context without polluting the process layer.

• Pipelines (The "What"): Orchestrators that chain processes together to achieve a high-level business goal.

  • Example: createInvokeContractPipeline(...) composes build, simulate, sign-auth, assemble, envelope-signing-requirements, sign-envelope, and send steps into one write flow.

This composition allows us to swap parts easily. For instance, the FeeBump plugin targets the SendTransaction step and wraps the outgoing transaction before submission, without rewriting the rest of the pipeline.

3. Type Safety

Everything is strictly typed. From network configurations to error metadata, TypeScript is used to enforce correctness at compile time.

---

Architecture

The system is built in layers, aiming to provide both high-level tools for specific use cases and highly specialized, bullet-proof building blocks.

• Layer 4: Plugins, Clients & Streamers
  • Extensions (Fee Bump), specialized clients (Contract, Signer), and event streaming.
• Layer 3: Pipelines
  • High-level workflows (createInvokeContractPipeline, createReadFromContractPipeline).
• Layer 2: Steps & Processes
  • Plain process functions plus convee step wrappers with stable ids.
• Layer 1: Core
  • Base types, Error primitives, Network configurations, account wrappers, and shared auth/address utilities.

---

Development

This workspace is a Deno monorepo. We use specific tasks defined in deno.json to maintain quality.

Testing

Run the test suite. You can run all tests or target specific types.

# Run all tests (Unit + Integration)
deno task test

# Run only unit tests
deno task test:unit

# Run only integration tests (requires network connection)
deno task test:integration

Linting

Ensure code style consistency.

deno lint

License

MIT License - see LICENSE for details.

Status: Beta (🪶)