docs: add event schema and Dune analytics guide

[ryzen-xp]

• Close Connect Dune Analytics to the escrow contract for on-chain analytics #66

Summary

Adds the event-emission documentation and Dune analytics guide called for in
the on-chain analytics task. No contract code is changed — this is docs-only.

---

What's in this PR

docs/dune-analytics.md (new, 560 lines)

Complete reference for anyone building analytics on the Boundless contract:

• §1 — How Dune indexes Soroban events. Relevant tables
  (stellar.history_contract_events, stellar.contract_data, etc.), column
  layout, ScVal auto-decoding rules.
• §2 — Complete event schema. Every one of the 27 emitted events documented
  with topic name, per-field ScVal type, and analytics notes:
  • Core lifecycle: EventCreated, EventCancelled, FundsAdded,
    ContributorRefunded, OwnerResidualRefunded
  • Participation: Applied, ApplicationWithdrawn, Submitted,
    SubmissionWithdrawn
  • Payouts: WinnersSelected, WinnerPaid, MilestoneClaimed
  • Admin/config: AdminUpdated, PendingAdminSet, FeeAccountUpdated,
    FeeBpsUpdated, ProfileContractUpdated, TokenRegistered,
    TokenDeregistered, Paused, Unpaused
  • Upgrade/migration: PendingUpgradeProposed, PendingUpgradeCancelled,
    UpgradeApplied, Upgraded (legacy alias), Migrated
• §3 — TVL accounting model. Exact inflow/outflow events, net-of-fee
  semantics, Crowdfunding vs other pillars distinction.
• §4 — 10 Dune SQL query skeletons (also in standalone .sql files).
• §5 — Dashboard layout. Suggested panel arrangement for the public
  Boundless On-chain Dune dashboard.
• §6 — Acceptance checklist.
• §7 — Maintenance notes (upgrades, new tokens, fee changes).

docs/dune-queries/ (new, 10 .sql files)

Each file is a standalone, paste-ready Dune query. All use {{CONTRACT_ADDRESS}}
as a Dune parameter so the same queries work on testnet and mainnet.

File	Panel	Type
01_tvl_current.sql	Current TVL	Counter
02_tvl_over_time.sql	TVL over time	Area chart
03_bounties_funded.sql	Events by pillar + budget	Bar chart
04_total_payouts.sql	Total payouts over time	Bar chart
05_unique_participants.sql	Unique builders + organizers	Counter
06_event_outcomes.sql	Funded / completed / cancelled funnel	Bar chart
07_avg_size_and_ttp.sql	Avg budget + time-to-payout	Table
08_payout_by_token.sql	Payout volume by token	Table
09_crowdfunding_contributions.sql	Crowdfunding daily inflows	Line chart
10_event_created_decode_test.sql	EventCreated decode verification	Table

---

Analytics correctness notes

Every analytics-relevant event carries decodable id / amount / asset /
address fields:

Requirement	Covered by
Event identifier	id on EventCreated; event_id on all subsequent events
Amount	total_budget (create), amount (FundsAdded, WinnerPaid, MilestoneClaimed, refunds)
Asset / token	token on EventCreated; join via event_id for payout events
Address	owner, contributor, recipient, applicant on relevant events

All amount fields in events are net-of-fee — the protocol fee is deducted
before remaining_escrow is credited. No fee adjustment is needed in SQL if the
rate changes.

Crowdfunding vs other pillars: EventCreated.total_budget is a funding goal
for Crowdfunding (escrow starts at 0). The TVL queries exclude it from creation
inflows and rely solely on FundsAdded for crowdfunding inflows.

---

Stale field removed from docs

The Applied event documentation previously listed a credit_cost: U32 field
carried over from the pre-1.1.0 schema. Credits moved off-chain in the 1.1.0
upgrade; the field was dropped from the Applied struct. This PR fixes the doc
to match the live contract: Applied carries only { event_id, applicant }.

---

Acceptance criteria status

• Event schema documented — every analytics-relevant event confirmed
  decodable (id, amount, asset, address, topic)
• 10_event_created_decode_test.sql decodes EventCreated filtered to the
  contract address and returns id, pillar, owner, token,
  total_budget, title
• Dune query skeletons cover TVL + total payouts + bounties funded
• Dashboard live at dune.com (pending manual creation — queries are ready
  to paste; dashboard URL will be added to dune-analytics.md once published)

---

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a955e5ae-cc5b-4d2f-b57b-50eaf747f907

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}