Bytes to a typed event

L3 showed the dispatch: topic0 → registry → the right decoder. This lesson opens what a decoder actually does — turn a raw log's bytes into a typed event. It's pure EVM, your strongest ground, and the whole skill is "know which bytes hold which parameter." We'll learn it on the Gnosis Safe events you already know feed multisig expansion (L22) and admin discovery (L25) — from the trivial case to the gnarly one, plus the guard that keeps a malicious log from OOM-ing the indexer.

1 · Shape A — indexed param from a topic (trivial)

AddedOwner(address owner) has its one param indexed, so it's in topics[1] (decoder_protocol.go):

func (d *safeAddedOwnerDecoder) Decode(l Log, tx *RawTransaction) (*DecodedEvent, error) {
    if len(l.Topics) < 2 { return nil, errInvalidLog }   // validate first
    return &DecodedEvent{ Type: EventSafeAddedOwner, …,
        Payload: &SafeAddedOwnerEvent{ Safe: l.Address, Owner: common.BytesToAddress(l.Topics[1].Bytes()) }}
}

An address is 20 bytes but a topic word is 32, so BytesToAddress takes the low 20 bytes. l.Address — the contract that emitted the log — is itself a value here: it's the Safe. The decoder validates len(Topics) before touching Topics[1] — bad logs get errInvalidLog, never a panic.

2 · Shape B — fixed param from data (a step up)

ProxyCreation(address proxy, address singleton) has no indexed params (Safe v1.3.0+), so both addresses sit in data at fixed 32-byte offsets:

Proxy:     common.BytesToAddress(l.Data[:32]),    // first word
Singleton: common.BytesToAddress(l.Data[32:64]),  // second word

3 · Shape C — a dynamic array from data (the head/tail scheme)

SafeSetup(address indexed initiator, address[] owners, uint256 threshold, …) is the gnarly one — it carries the Safe's initial owner set, invisible anywhere else (the gap L22's expansion needs filled at creation). The owners are a dynamic array, and that's where ABI's head/tail encoding shows up:

// data layout: head = 4 fixed words, then the array tail.
// head[0] = byte OFFSET of the owners array (a pointer into the tail)
// head[1] = threshold   head[2] = initializer   head[3] = fallbackHandler
threshold := new(big.Int).SetBytes(l.Data[32:64])      // head[1], a fixed word, read inline
off := new(big.Int).SetBytes(l.Data[0:32]).Int64()     // head[0] → where the array lives
n   := new(big.Int).SetBytes(l.Data[off : off+32]).Int64()  // the array's first tail word = its length
owners := make([]Address, n)
for i := 0; i < n; i++ {
    base := off + 32 + i*32                            // length word, then n entries
    owners[i] = common.BytesToAddress(l.Data[base : base+32])
}

4 · The guard — log data is adversarial

Here's the line that separates a toy decoder from a production one. The array length n comes from untrusted log bytes. A naive make([]Address, n) on a malicious length word is an attack:

maxOwners := (int64(len(l.Data)) - ao - 32) / 32   // how many addresses could POSSIBLY fit
if n < 0 || n > maxOwners { return nil, errInvalidLog }   // bound BEFORE you allocate

5 · The uniform output — every decoder ends the same

However it reads the bytes, a decoder returns the same shape: a *DecodedEvent with a Type (the event enum), the TxHash / LogIndex / Contract provenance, and a typed Payload struct (SafeSetupEvent, etc.). That uniformity is what lets the indexer's write path (L4) switch on Type and route each event to its handler without caring how it was decoded. Decoders normalize chaos into one envelope.

What you can now do

• Explain a log's two regions — topics (signature + ≤3 indexed words) and data (everything else, ABI-encoded).
• Read the three decode shapes: indexed-from-topic, fixed-from-data, dynamic-via-head/tail offset.
• Decode a dynamic array (read offset → seek → length → entries) and explain the ABI head/tail scheme.
• Spot the bound-before-allocate guard and explain the alloc-bomb it defuses — the adversarial-input mindset.
• Explain the uniform DecodedEvent output and how it lets the write path route by Type.