Architecture Overview

Colibri is built around core principles: composable pipelines, robust processes, extensible plugins, and type-safe abstractions.

Pipeline Architecture

Colibri uses the convee library to compose workflows as pipelines of discrete processes.

What is a Pipeline?

A pipeline chains multiple processes together, where each process:

• Receives input from the previous process

• Performs a specific task (build, simulate, sign, submit)

• Passes output to the next process

┌─────────┐     ┌──────────┐     ┌──────────┐     ┌────────┐     ┌────────┐
│  Build  │ ──→ │ Simulate │ ──→ │ SignAuth │ ──→ │  Sign  │ ──→ │ Submit │
└─────────┘     └──────────┘     └──────────┘     └────────┘     └────────┘

Colibri provides ready-to-use pipelines for common use cases like contract invocation, read-only calls, and classic transactions. You can use them directly or compose custom pipelines from individual processes.

See Pipelines for the full list and detailed documentation.

Processes

Processes are the atomic building blocks of Colibri. Each process handles a single task with predictable behavior, typed input/output, and specific error codes. They can be used standalone or composed into pipelines.

See Processes for the full list and detailed documentation.

Plugins

Plugins extend pipeline and process behavior without modifying core logic. They wrap around steps to add functionality like fee sponsorship, custom signing strategies, or logging.

See Plugins for available plugins and how to use them.

Type Safety

Colibri leverages TypeScript's type system extensively to ensure consistency across all components. Validation guards like StrKey help validate and narrow types at runtime:

import { StrKey } from "@colibri/core";

const input = "G...";

if (StrKey.isEd25519PublicKey(input)) {
  // TypeScript now knows input is Ed25519PublicKey
  await loadAccount(input);
}

Type checkers are available for public keys, secret keys, contract IDs, muxed addresses, and more—keeping consistency across the core components and tools.

Core Types

Colibri uses well-defined interfaces and types throughout the library. This enables custom implementations that integrate seamlessly—you're never locked into built-in tools. For example, Signer defines the signing interface so any custom signer works with all pipelines, NetworkConfig standardizes network settings across all tools, and TransactionConfig provides consistent transaction parameters.

Error Handling

Colibri uses typed errors with unique, standardized error codes across the entire library. Every error includes:

• A unique error code (e.g., BTX_003, SIM_001)

• A human-readable message

• Optional diagnostic information with suggestions

Network failures and external errors are wrapped and enriched with context, making debugging straightforward.

import { ColibriError } from "@colibri/core";

try {
  const result = await pipeline.run({...});
} catch (error) {
  if (ColibriError.is(error)) {
    console.log("Error Code:", error.code);
    console.log("Message:", error.message);

    if (error.diagnostic) {
      console.log("Suggestion:", error.diagnostic.suggestion);
    }
  }
}

See Error Handling for the full error system documentation.

Next Steps

• Pipelines — Build custom transaction workflows

• Processes — Learn about each process in detail

• Plugins — Extend behavior with plugins

• Error Handling — Deep dive into the error system