From a raw log to a typed event

You already know that every event log starts with topic0 — the keccak256 hash of the event's signature. That single fact is the decoder path. The indexer keeps a hash-map from topic0 → a small object that knows how to parse that one event into a typed struct. This lesson shows you the real map, the real parser, and the 3-step recipe to add your own.

1 · topic0 is the routing key

In pkg/decoder/topics.go, every supported event's topic0 is computed exactly the way you'd compute it by hand — there's no magic:

// pkg/decoder/topics.go
var (
  TopicTransfer = crypto.Keccak256Hash([]byte("Transfer(address,address,uint256)"))
  TopicApproval = crypto.Keccak256Hash([]byte("Approval(address,address,uint256)"))
  TopicRoleGranted = crypto.Keccak256Hash([]byte("RoleGranted(bytes32,address,address)"))
  // …~90 of these, across ERC-20, Aave, Compound, Uniswap, Morpho, Safe, Chainlink…
)

Source: risk-graph-indexer/pkg/decoder/topics.go. This is the cast keccak "Transfer(address,address,uint256)" you've run a hundred times — just in Go.

2 · The registry: a map, not a giant switch

The system avoids a 90-case switch. Instead, a Registry holds a Go map from each topic0 to a decoder object:

// pkg/decoder/decoder.go
type Registry struct {
    decoders map[common.Hash]LogDecoder   // topic0 → decoder
    chainID  types.ChainID
}

func NewRegistry(chainID types.ChainID) *Registry {
    r := ...
    r.Register(TopicTransfer,    &transferDecoder{})    // wire each topic…
    r.Register(TopicApproval,    &approvalDecoder{})
    r.Register(TopicRoleGranted, &roleGrantedDecoder{})
    // …one Register call per event type
    return r
}

And the dispatch loop — for every log in the block, look up topic0, and if there's a decoder for it, run it:

// pkg/decoder/decoder.go — DecodeBlock (simplified)
for _, l := range tx.Logs {
    dec, ok := r.decoders[l.Topics[0]]   // ← the whole routing decision
    if !ok {
        continue                          // no decoder for this event → ignore it
    }
    ev, err := dec.Decode(l, tx)          // parse into a typed event
    ...
}

type LogDecoder interface {
    Decode(log ethtypes.Log, tx *types.RawTransaction) (*types.DecodedEvent, error)
}

Source: pkg/decoder/decoder.go — LogDecoder interface, Registry, NewRegistry, DecodeBlock.

3 · A real decoder, line by line

Here's the actual transferDecoder — the whole thing. You'll recognise every byte of it:

// pkg/decoder/decoder.go
type transferDecoder struct{}   // no state — just a method holder

func (d *transferDecoder) Decode(l ethtypes.Log, tx *types.RawTransaction) (*types.DecodedEvent, error) {
    // ERC-721 transfers share this topic0 but put tokenId in topics[3] and carry no data.
    // We only want ERC-20 → skip anything that doesn't look like one.
    if len(l.Topics) < 3 || len(l.Data) < 32 {
        return nil, errSkipEvent
    }
    return &types.DecodedEvent{
        Type:     types.EventTransfer,
        TxHash:   tx.Hash,
        LogIndex: l.Index,
        Contract: l.Address,                 // the token contract that emitted it
        Payload: &types.TransferEvent{
            Token: l.Address,
            From:  common.BytesToAddress(l.Topics[1].Bytes()),  // indexed arg #1
            To:    common.BytesToAddress(l.Topics[2].Bytes()),  // indexed arg #2
            Value: new(big.Int).SetBytes(l.Data[:32]),         // non-indexed → from data
        },
    }, nil
}

Map it to what you know about ERC-20 Transfer(address indexed from, address indexed to, uint256 value):

4 · The skill: add a decoder (3 steps)

Adding support for a new event is one of the most common first contributions, and now it's just a recipe. Say you want to decode some FooBar(address indexed who, uint256 amount) event:

TopicFooBar = crypto.Keccak256Hash([]byte("FooBar(address,uint256)"))

type fooBarDecoder struct{}
func (d *fooBarDecoder) Decode(l ethtypes.Log, tx *types.RawTransaction) (*types.DecodedEvent, error) {
    if len(l.Topics) < 2 || len(l.Data) < 32 { return nil, errSkipEvent }
    return &types.DecodedEvent{ /* Type, Contract, Payload… */ }, nil
}

r.Register(TopicFooBar, &fooBarDecoder{})

The decoder pattern + this recipe are distilled in the Adding-a-Decoder recipe card. Real registrations to copy: pkg/decoder/decoder.go NewRegistry (20+ examples).

Check yourself

What you can now do

• Explain the decoder path: topic0 → registry map → a LogDecoder → a typed DecodedEvent.
• Read any concrete decoder and map its Topics[]/Data[] reads to indexed vs non-indexed args.
• Recognise the Go interface pattern that lets one map hold every decoder.
• Add a decoder via the 3-step recipe — and know the decoder/handler boundary.