Carbonby SevenLabs
Esc
↑↓ to move ↵ to openAgents: llms.txt
  1. Get started

Introduction

What Carbon is, how a pipeline moves Solana data from datasources through decoders to your processors, what you can build and when to use something else.

On this page

Carbon is an open-source Rust framework for building Solana indexers and data pipelines. You choose where the data comes from, Carbon decodes it into typed Rust values, and your code decides what to do with them. Carbon is maintained by SevenLabs with the Solana Foundation and released under the MIT license.

How a pipeline works#

A Carbon program builds one Pipeline from three kinds of parts:

  • Datasources read updates from Solana: account writes, transactions, account closures and block metadata. A datasource can be a Geyser gRPC stream, a Solana RPC subscription, a crawler over history, a validator snapshot or a provider API.
  • Decoders turn raw bytes into Rust types. Carbon publishes decoders for 60+ programs, and the Carbon CLI generates one from any Anchor or Codama IDL.
  • Processors are your code. Each one receives decoded data together with its metadata: slot, signature, the instruction's position in the transaction and so on.
How a Carbon pipeline moves data Datasources such as Yellowstone gRPC, an RPC crawler or a snapshot each send updates into one channel. The pipeline takes updates off the channel one at a time and offers each one to the pipes for its type: account pipes and instruction pipes filter and decode, transaction pipes filter and decode every instruction with a decoder set, and account-deletion and block-details pipes only filter. Every pipe then calls its processor, which is your code. DATASOURCES PIPELINE YOUR CODE Each update goes to the pipes for its type Accounts filters decode Instructions filters decode Transactions filters decode set Deletions & blocks filters channel one queue Yellowstone gRPC RPC crawler Snapshot, RPC, … Processor Processor Processor Processor How a Carbon pipeline moves data Datasources such as Yellowstone gRPC, an RPC crawler or a snapshot each send updates into one channel. The pipeline takes updates off the channel one at a time and offers each one to the pipes for its type: account pipes and instruction pipes filter and decode, transaction pipes filter and decode every instruction with a decoder set, and account-deletion and block-details pipes only filter. Every pipe then calls its processor, which is your code. DATASOURCES Yellowstone gRPC RPC crawler Snapshot, RPC, … channel PIPELINE Each update goes to the pipes for its type Accounts decode filters Instructions decode filters Transactions decode set filters Deletions & blocks filters Your processor, one per pipe

Every datasource runs in its own task and sends updates into one channel. The pipeline takes updates off the channel one at a time and offers each one to the pipes that match its type. A pipe applies its filters, decodes the update and calls its processor. Architecture explains the exact order and guarantees.

The same processor works with any datasource. You can develop against the free public RPC endpoint and switch to a Geyser stream in production without changing your processing code.

What you can build#

  • Real-time indexers that write decoded instructions and account state to Postgres or another store as blocks land, from a Geyser gRPC stream such as Yellowstone or Helius LaserStream.
  • Backfills that walk a program's transaction history with the transaction crawler or a block range with the block crawler.
  • State loaders that read every account of a program at once from getProgramAccounts or a validator snapshot, then keep it current with a stream.
  • Bots and alerting that react to swaps, liquidations or account changes within the same slot.
  • Analytics pipelines that aggregate trades, fees or balances across several programs, using transaction processors to see every instruction of a transaction together.

Carbon also ships optional Postgres and GraphQL layers, Prometheus metrics and test utilities.

When not to use Carbon#

  • You need ad-hoc queries over all of Solana's history. Carbon processes the updates you subscribe to; it isn't a hosted warehouse. Use a data warehouse or a provider's historical API, and use Carbon when you want your own tables for specific programs.
  • You only need a few RPC calls. Reading one account or sending transactions is simpler with solana-client directly.
  • You can't use Rust. Carbon is a Rust library. The Carbon CLI is a Node.js tool, but it only generates Rust code.
  • You need a datasource that isn't on the Carbon 2 line yet. Jito Shredstream and Jetstreamer have no 2.0 crates. See Datasources for what's available, or write your own.

Map of the docs#

SectionRead it when you want to
QuickstartRun a working indexer against mainnet in five minutes.
InstallationAdd Carbon to a project and pick crates and features.
Concepts, starting with ArchitectureUnderstand updates, datasources, decoders, processors, filters, metrics, shutdown and errors.
Guides, such as Generate a decoderFollow a task end to end: streaming, backfills, Postgres, GraphQL, testing, production.
Reference, starting with PipelineBuilderLook up a builder method, trait, filter, metric, error, feature flag or CLI flag.
Datasources and DecodersConfigure a specific datasource or decoder crate.
Examples, Troubleshooting, ChangelogCopy a full project, fix an error, or upgrade.

Using a coding agent? Every page is available as Markdown; see For AI agents.

Next steps#

Quickstart

Decode live Meteora swaps from mainnet. No account needed.

Installation

Requirements, crates and feature flags.

Architecture

How Pipeline::run moves an update from datasource to processor.

Updated
Page history (2 revisions)
  1. Replace ASCII art with drawn diagrams and file trees
  2. Contributing: describe the feedback paths available while the docs repo is private
Suggest an edit (opens in a new tab)Report an issue (opens in a new tab)

Your endpoints

Code samples use these instead of the placeholders, so you can copy and run them as they are. They’re stored only in this browser and never sent anywhere.