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.

[Miracle656]

Approved and merging — I rebased this to doc-only myself (8cbe9d8) now that #155 and #156 have landed, since the wave has closed.

I verified the document against the code rather than reading it, which is the only review a reference doc deserves:

• KNOWN_EVENT_TYPES in the doc matches src/decoder.ts:7 exactly — transfer, mint, burn, clawback.
• Every base64 ScVal in the worked examples decodes to precisely what the doc claims. I ran them:

topic0: transfer
addr1 : GDWCO35QUYQLGO6P7OLW4BZWNMMGGUWNPLRVPLCBVG7YNVDZKUDIW4KN
addr2 : GCXOO7OIJZ2HEOZODLOEISNVO6CBPK4PISRJCZYRFT37H7XGHDLB3C7O
value : 1000000000

Identical to the "Decoded" block, down to the 100.0000000 stroop annotation. Using the same XDR as the test fixtures is the detail that makes this doc trustworthy over time — a reference with hand-written examples drifts silently the first time a decoder changes, and nobody notices because docs have no CI. These are the strings the decoder tests already assert on, so they cannot rot without a test going red.

Documenting that unrecognised topics[0] symbols are silently skipped is also worth having written down. That is exactly the behaviour someone hits when their event does not appear in the index, and there is no log line to lead them to it.

The .gitignore change is quietly the most useful line in the PR. docs/ was ignored wholesale, which is why every document in this repo — DUAL_NETWORK.md, backup-restore.md — had to be force-added, and why anyone writing a new one would find git add silently doing nothing. I kept the removal and replaced it with a targeted ignore for docs/openapi.json, which npm run docs:openapi generates alongside the tracked root copy.

On the rebase: this branch was the top of the #155 → #156 → #157 stack and carried both of their code changes. All of it now exists on main in a later form (network-scoped schema, gated LP dialect, wired tombstone detector), so I took main's version of db.ts, indexer.ts, lp-shares.ts, tombstones.ts, schema.prisma and both test files, and dropped the two superseded June migrations. What is left is the document and the .gitignore line — which is what the PR was always about.

Verified: tsc --noEmit clean, full suite 382 passed.

That is the whole stack merged. Thanks for all four.