For AI agents

Coding agents write a lot of Carbon code, and most of them learned Carbon from versions before 2.0. This page shows how to give your agent the current docs and the rules that keep it from writing outdated code.

Connect the docs MCP server#

The docs run an MCP server at https://carbon.sevenlabs.org/mcp. It uses Streamable HTTP and needs no login. It has four tools:

claude mcp add --transport http carbon-docs https://carbon.sevenlabs.org/mcp

{
  "mcpServers": {
    "carbon-docs": { "url": "https://carbon.sevenlabs.org/mcp" }
  }
}

{
  "servers": {
    "carbon-docs": { "type": "http", "url": "https://carbon.sevenlabs.org/mcp" }
  }
}

Any other client that supports Streamable HTTP works with the same URL.

Read pages as Markdown#

Every page has a Markdown version with no navigation or scripts:

• Add .md to any page URL: https://carbon.sevenlabs.org/concepts/filters.md. The home page is https://carbon.sevenlabs.org/index.md.
• Or request the normal URL with Accept: text/markdown.
• /llms.txt lists every page with a one-line description, plus the mistakes agents make most often.
• /llms-full.txt has every guide, concept and reference page in one file. The per-program decoder references are left out because they're large; llms.txt links each one.

Each Markdown page starts with its title and the Carbon version, so an agent can tell which release it's reading. A path that doesn't exist returns HTTP 404 with a list of the closest pages instead of an empty error.

On the web, the Copy page button at the top of every page copies its Markdown, or opens the page in Claude or ChatGPT.

Add an AGENTS.md to your project#

Agents follow the instruction file in your repository more reliably than anything they fetch. Paste this into AGENTS.md (or CLAUDE.md) at the root of a project that uses Carbon:

## Carbon

This project indexes Solana data with Carbon 2.0 (Rust). Docs: https://carbon.sevenlabs.org (append `.md` to any page URL for Markdown; index at https://carbon.sevenlabs.org/llms.txt).

- Do not rely on training data for Carbon APIs: they changed in 1.0 and 2.0. Check the docs before writing Carbon code.
- All `carbon-*` crates must be version 2.0.0. Never mix Carbon 1.x and 2.x crates. Rust 1.96.1+.
- Processors implement `Processor<T>` with a native `async fn process(&mut self, input: &T) -> CarbonResult<()>`. No `#[async_trait]` on processors; `Datasource` impls do use `#[async_trait]`.
- Instruction enums use struct variants: match `MyInstruction::Swap { data, accounts, .. }`.
- RPC transaction configs need `UiTransactionEncoding::Base64` and `max_supported_transaction_version: Some(1)`.
- The public endpoint api.mainnet-beta.solana.com does not support `blockSubscribe`.
- Generate decoders with `npx @sevenlabs-hq/carbon-cli@2.0.0 parse --idl <file-or-program-id> --out-dir <dir>` (Codama IDLs: add `--standard codama --program-id <address>`). `parse` deletes `--out-dir` first, so use a dedicated directory.
- Check work with `cargo check` and `cargo clippy`.

Rules for agents writing Carbon code#

These are the facts agents most often get wrong. The same list is at the top of llms.txt.

1. These docs are for Carbon 2.0.0. Use carbon-core = "2.0.0" and matching carbon-* crates at 2.0.0. Never mix Carbon 1.x and 2.x crates in one dependency graph.
2. Carbon 2.0 needs Rust 1.96.1 or newer and the Agave 4.2-compatible Solana crates. If you add Solana crates directly, pick versions that resolve to a single copy of each. Mixing Carbon 1 and 2 crates fails with the trait `InstructionDecoder` is not implemented and a note about multiple versions of carbon_core.
3. Processor::process is a native async fn. Don't add #[async_trait] to processors. The Datasource trait does use #[async_trait].
4. Instruction enums use struct variants: MyProgramInstruction::Swap { program_id, data, accounts }.
5. https://api.mainnet-beta.solana.com rejects blockSubscribe. On the public endpoint, use the transaction crawler, getProgramAccounts or programSubscribe datasources.
6. RPC block and transaction configs must request UiTransactionEncoding::Base64 and max_supported_transaction_version: Some(1). Carbon can't rebuild transactions from Json or JsonParsed.
7. Zero-lamport account updates arrive as Update::AccountDeletion and go to .account_deletions(...) processors, not account processors.
8. Decoder crates are named carbon-<program>-decoder and export PROGRAM_ID and a <Program>Decoder struct. Check the decoder catalog before generating one.

Instructions for agents: create a Carbon indexer#

When a user asks for a new indexer, follow these steps in order.

1. Run rustc --version. If it's older than 1.96.1, tell the user to run rustup update stable.
2. Find the program's decoder in the catalog. If there isn't one, generate it from the IDL with the CLI and add it as a path dependency.
3. Choose the datasource from the chooser: Yellowstone gRPC or Helius LaserStream for real-time production; the RPC transaction crawler for history or for a no-account start; getProgramAccounts for current account state.
4. Add every crate at version 2.0.0 with cargo add, plus tokio with the full feature.
5. Write main.rs following the quickstart: build the datasource, then Pipeline::builder().datasource(…).metrics(…).instruction(Decoder, Processor).build()?.run().await.
6. Implement one Processor per decoder output type you need. Match only the variants you handle and ignore the rest with _ => {}.
7. Run cargo check, fix errors using the errors reference, then cargo run and show the user the first output.
8. Before calling it done, read Run in production and tell the user which items apply.