Skip to content

fix: dashboard screenshot, referrer-pool tutorial, indexer reorg safety (#80 #85 #86)#307

Open
k-deejah wants to merge 1 commit into
tributary-protocol:mainfrom
k-deejah:fix/issues-80-85-86
Open

fix: dashboard screenshot, referrer-pool tutorial, indexer reorg safety (#80 #85 #86)#307
k-deejah wants to merge 1 commit into
tributary-protocol:mainfrom
k-deejah:fix/issues-80-85-86

Conversation

@k-deejah

@k-deejah k-deejah commented Jul 18, 2026

Copy link
Copy Markdown

Summary

Resolves three open issues in a single focused PR.


Issue closes #85 — Add dashboard screenshot to README

  • Added : an SVG illustration that faithfully matches the app's visual design (dark #0b1220 background, #4cc3ff cyan accent, sticky header, tabbed action panel with Create/Pay/Escrow tabs, recipient input rows, and the split-list card grid).
  • Inserted the screenshot in README.md immediately after the live-site link, before the prose description, so newcomers see the UI at a glance.

Issue closes #86 — Tutorial: build a referrer pool with nested splits

  • Added docs/tutorial-referrer-pool.md: a full end-to-end walkthrough covering:
    • Why children must be created before parents
    • preview_payout to sanity-check amounts before sending
    • pay to settle a sale in one transaction
    • distribute to flush pool escrow to referrers
    • update_split to swap the referrer roster without touching the marketplace split
    • A plain-text flow diagram tying it all together
    • "What to do next" pointers (deeper trees, pay_many, deposit-then-distribute, locking)
  • Cross-linked from the README Docs section and from docs/integrations.md at the existing referrer-pools heading.

Issue closes #80 — Handle RPC reorgs and make re-scans idempotent

New file: indexer/state.mjs
Pure helpers with zero external dependencies (no @stellar/stellar-sdk):

  • validateConfig — moved here from index.mjs so tests can import it without the SDK
  • loadState / saveStatestate.json now persists cursor and seenIds (sorted array of event ids). Tolerates missing files, corrupt JSON, and legacy files that only have cursor (backwards compatible).
  • cursorLedger — decodes the ledger sequence from a cursor string
  • isCursorSafeToCommit — returns false when the cursor's ledger is within REORG_DEPTH (default 2, configurable via env) ledgers of the chain tip, holding the cursor back so those ledgers are re-fetched next poll
  • deduplicateEvents — skips any event whose id is already in seenIds, making overlapping re-scans fully idempotent

Updated indexer/index.mjs

  • Imports all pure helpers from state.mjs
  • Poll loop guarded by isMain check so the file can be imported by tests without triggering RPC calls or process.exit
  • Cursor only advanced when isCursorSafeToCommit returns true; events within the reorg window are re-fetched and deduplicated automatically

Updated indexer/index.test.mjs

  • 20 new tests covering validateConfig, cursorLedger, isCursorSafeToCommit, deduplicateEvents (including a reorg simulation), loadState/saveState round-trips, legacy state compatibility, and large seenIds sets
  • All 23 tests (20 new + 3 existing rpc-backoff tests) pass: node --test index.test.mjs rpc-backoff.test.mjs

CI checklist

  • No Rust files changed — cargo fmt, cargo clippy, cargo test unaffected
  • No SDK/app TypeScript files changed — npm run build unaffected
  • No behaviour changes to contract code — no no_std / typed-error concern
  • New indexer behaviour covered by tests per CONTRIBUTING.md

…ty (tributary-protocol#80 tributary-protocol#85 tributary-protocol#86)

Issue tributary-protocol#85 - add dashboard screenshot to README
- Add assets/dashboard.svg: SVG illustration matching the app's dark theme,
  tabbed action panel (Create/Pay/Escrow), recipient inputs, and split-list grid.
- Reference it in README.md immediately after the live-site link.

Issue tributary-protocol#86 - tutorial: build a referrer pool with nested splits
- Add docs/tutorial-referrer-pool.md: step-by-step walkthrough covering
  create order, preview_payout, pay, distribute, update_split roster, and
  a plain-text flow diagram.
- Cross-link from README.md Docs section and docs/integrations.md.

Issue tributary-protocol#80 - handle RPC reorgs and make re-scans idempotent
- Extract indexer/state.mjs: pure helpers (validateConfig, loadState,
  saveState, cursorLedger, isCursorSafeToCommit, deduplicateEvents) with
  no external dependencies, importable by tests without stellar-sdk.
- state.json now persists cursor + seenIds (sorted array of event ids).
  loadState() tolerates missing files, corrupt JSON, and legacy files that
  lack seenIds (backwards compatible).
- deduplicateEvents() skips any event whose id is already in seenIds,
  making overlapping re-scans fully idempotent.
- isCursorSafeToCommit() holds the cursor back when its ledger is within
  REORG_DEPTH (default 2) of the chain tip; those ledgers are re-fetched
  next poll and the dedup absorbs any duplicates.
- index.mjs: poll loop only runs when the file is the entry point (isMain
  guard), so tests can import from state.mjs without triggering RPC calls.
- indexer/index.test.mjs: 20 new tests covering all pure helpers; combined
  with the 3 existing rpc-backoff tests the suite is 23/23 passing.
@k-deejah
k-deejah requested a review from Spagero763 as a code owner July 18, 2026 18:53
@Spagero763

Copy link
Copy Markdown
Contributor

This PR's contract check is failing on markdown-link-check / cspell, but not because of anything in your diff — your branch was forked before a docs fix landed on main (the flagged word/link doesn't exist in your changes, and main passes this check cleanly). Since "Update branch" is enabled on this repo, click it on this PR and CI should go green without any code changes on your end.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Tutorial: build a referrer pool with nested splits Add a dashboard screenshot to the readme Handle RPC reorgs and make re-scans idempotent

2 participants