Soroban event reference doc

[githoboman]

Summary
Closes #144
Created docs/event-reference.md — a reference of every event the indexer recognizes, grounded in the actual code rather than the task title.

What it documents, one section per event, each with a real worked example:

transfer — from/to/amount (from topics[1], topics[2], value)
mint — to/amount; from is null, admin in topics[1] is intentionally ignored
burn — from/amount; to is null
clawback — same shape as burn
Each section has: the topic/value shape table, how the fields map into a TransferRecord, the base64 XDR (taken verbatim from the test fixtures), and the decoded form. The example XDR and decoded values are verified — I ran them through @stellar/stellar-sdk's scValToNative/Address to confirm the exact addresses and amounts, then removed the temp script.

One correction worth flagging: the task title lists transfer, mint, burn, approve, but the indexer actually recognizes transfer, mint, burn, clawback (src/decoder.ts:7 — KNOWN_EVENT_TYPES). There is no approve handling anywhere. I documented the four real events and added a dedicated "A note on approve" section explaining why it's not indexed (it sets an allowance, not a balance movement; its value is a struct, not an i128) and what it would take to add it.

Gitignore change: per your choice, I removed the docs/ line from .gitignore so the doc is trackable. Side effect: the existing docs/cookbook/ directory is now also no longer ignored — worth a glance before you commit if it contains anything you'd rather keep untracked.

Want me to commit these changes (on this Soroban-event-reference-doc branch), or open a PR?

[drips-wave]

@githoboman Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Miracle656]

The docs/event-reference.md doc itself is excellent — clear field-source tables, the KNOWN_EVENT_TYPES set, per-event topic/value shapes, and worked XDR examples. I'd merge the doc happily on its own.

The problem is PR hygiene: this branch is stacked on #155 and #156, so its diff also carries the tombstone and LP-share code — both of which I've just requested changes on (#156: mint/burn over-capture every token as an LP share; #155: tombstone detection is never wired into the indexer). Because those are bundled in here, #157 can't merge until they're resolved.

Two paths:

1. Preferred: rebase this branch so it contains only docs/event-reference.md on top of main, and let #155/#156 land (reworked) independently. Then #157 is a trivial docs merge.
2. Or fold everything into the reworked #155/#156 and close this as the doc rides along.

One content note for whichever way you go: your own doc quotes KNOWN_EVENT_TYPES = {"transfer","mint","burn","clawback"} — which is exactly why keying LP-shares off bare mint/burn in #156 over-captures. Once the LP-share and tombstone paths are finalized, it'd be great to add their event shapes to this reference too.

Rebase down to just the doc and I'll merge it right away.