Lesson 5 of 7

Understanding Adder

Adder is Blink Labs' Go tool for tailing the Cardano blockchain — following new blocks and transactions as they arrive, and turning them into events your application can react to. It sits in the same ecosystem as gOuroboros (the protocol library) and Apollo (the transaction builder), and together they form an all-Go stack for building Cardano backends.

This lesson explains why Adder exists, what it does (and deliberately doesn't) do, and how it fits alongside the other tools you'll use in this course.

Prerequisites

  • A general sense of what a blockchain is
  • Completed 100.2 — you know why "included in a block" and "settled" aren't the same
  • Completed 100.4 — you've seen Apollo build a transaction

No coding is required in this lesson.

The Problem Adder Solves

A Cardano node knows everything that's happening on the chain. It sees every new block, every transaction, every rollback. But a raw node doesn't push that information to your application — you have to pull it, one block at a time, over the Ouroboros protocol.

Writing that pull loop yourself is possible (you'll see it in gouroboros in Module 101). But every application that wants to react to chain events ends up writing the same infrastructure:

  • Connect to a node
  • Follow the chain tip
  • Decode each block into transactions
  • Handle rollbacks
  • Filter out everything you don't care about

Adder exists so you don't write that infrastructure twice. It is, fundamentally, opinionated plumbing: a pipeline that you plug an input into, an output into, and a set of filters between.

How Adder Works

Adder's core abstraction is a pipeline:

  ┌───────┐     ┌─────────┐     ┌────────┐
  │ Input │ ──> │ Filters │ ──> │ Output │
  └───────┘     └─────────┘     └────────┘
  • Input — where events come from. The default is chainsync, which connects to a Cardano node (or Dolos, or a remote relay) and follows the chain.
  • Filters — decide which events pass through. Filter by event type, address, asset policy, stake pool, and so on.
  • Output — where matching events go. Built-in outputs include a log, an HTTP webhook, push notifications, an embedded Go callback, Kafka, and more.

Events are a simple JSON shape with a type, timestamp, context, and payload. The chainsync input produces four event types:

  • input.block — a new block was added to the chain
  • input.transaction — a transaction was included in a block
  • input.rollback — the chain rolled back
  • input.governance — a Conway-era governance action

Each event has a specific payload structure. Your code handles the types you care about and ignores the rest.

Two Ways to Use Adder

Adder ships with two personas — two different workflows wearing the same name:

1. The CLI tool

Download the adder binary, point it at a node, and it prints events to stdout as JSON or human-readable text:

adder --input-chainsync-network preprod --output-log-format json | jq .

This is useful for quick inspection, for piping into jq or grep, or for building lightweight shell-driven workflows. You don't write any Go code.

2. The Go library

Import Adder into your own Go program and compose a pipeline in code:

p := pipeline.New()
p.AddInput(input_chainsync.New(...))
p.AddFilter(filter_event.New(
    filter_event.WithTypes([]string{"input.transaction"}),
))
p.AddOutput(output_embedded.New(
    output_embedded.WithCallbackFunc(myHandler),
))
p.Start()

This is what you'll use from Module 201 onwards. The library path lets you drop the event handling directly inside your Go service — no JSON serialisation to another process, no tooling glue.

Both modes share the same plugin architecture. A filter you'd use from the CLI is the same code that runs when you invoke it from the library.

What Adder Is Not

Knowing what Adder deliberately leaves out is as important as knowing what it does.

It is not a database

Events flow through the pipeline and are gone. If your handler crashes, you lose everything in-flight. Adder does not persist events anywhere by default.

This is a feature. Choosing a storage layer is opinionated — some applications want PostgreSQL, others want SQLite, others want to pipe into Kafka. Adder lets you decide. In Module 202 you'll add SQLite to an Adder pipeline.

It is not a query provider

You can't ask Adder "what UTxOs exist at this address right now?" It only sees events as they arrive. For point-in-time queries, you need something else — Dolos's gRPC endpoint, Blockfrost, Kupo, db-sync. Adder is the reacting layer, not the querying layer.

It is not a full node

Adder connects to a node — it doesn't validate blocks, produce blocks, or participate in consensus. If the node it connects to is wrong, Adder's events are wrong.

Where Adder Sits in the Stack

         ┌────────────────────────────────┐
         │  Your Go application           │
         │  (business logic, HTTP API)    │
         └──────────┬──────────────┬──────┘
                    │              │
                    │ live events  │ tx construction
                    ▼              ▼
         ┌──────────────────┐  ┌────────────┐
         │  Adder           │  │  Apollo    │
         │  (this lesson)   │  │  (100.4)   │
         └──────────┬───────┘  └──────┬─────┘
                    │ ChainSync      │ submit
                    │                │
                    ▼                ▼
         ┌───────────────────────────────────┐
         │  Cardano node (Dolos / relay)     │
         └───────────────────────────────────┘

In the course's preferred setup, both Adder and Apollo talk to a local Dolos instance. Adder reads the chain tip via ChainSync; Apollo submits via LocalTxSubmission (from Module 102.4). One node, two libraries, one all-Go stack.

Why "Adder"?

The name comes from the additive pipeline model: each stage adds something to the flow — an input adds events, a filter adds a gate, an output adds a destination. Every real-world indexer you'll build on Cardano has this shape, whether or not it uses Adder. Adder just gives you the shape out of the box.

When You'd Reach for Something Else

Adder is excellent for applications that need to react in real time to events on the chain tip going forward. It's less suited for:

  • Historical queries — "what happened at this address last month?" Use a full indexer (db-sync) or a hosted API (Blockfrost).
  • Aggregations across many events — "total locked value in this contract." Possible with Adder + your own DB, but not out of the box.
  • Point-in-time ledger state — "current UTxO set at this address." Use LocalStateQuery (gOuroboros) or a query service.

You'll see this trade-off explicitly in Module 202, where we pair Adder with Dolos's query endpoints to cover both needs.

Summary

  • Adder is a Go pipeline for following Cardano chain events in real time.
  • The pipeline is Input → Filters → Output, with pluggable components at every stage.
  • It comes in two forms: a CLI tool for quick inspection and a Go library for embedding in your own services.
  • It is deliberately not a database, not a query provider, and not a full node.
  • In this course, you'll use the library form (Module 201) with Dolos as the input source.

You now have the conceptual picture of Adder's role in the Cardano Go stack. Module 201 puts it to work.