Public ledger explorer v2: bond search, drill-down & pagination — full-stack EPIC

[grantfox-oss]

DESCRIPTION

ExplorerController.snapshot() (apps/api/src/explorer/explorer.controller.ts) is the only public explorer endpoint: it returns the latest 20 bonds and latest 10 Soroban/Trustless Work contracts, hardcoded, with no way to search for a specific bond or see its full on-chain history. Since this is VELAR's public transparency surface — "anyone can query it to verify on-chain state" — this is a meaningful gap. This epic builds a real explorer with search and drill-down.

GOAL

Anyone (no auth, matching the current @Public() explorer) can search for a bond by id/party/wallet and see its full transfer + on-chain contract history, and browse the full bond/transfer history with pagination instead of only the latest 20/10.

REQUIREMENTS

Backend

• GET /explorer/bonds/:bondId — full detail for one bond: party, current owner, face value/status, full transfer history, Soroban contract link, Trustless Work escrow contract link(s).
• GET /explorer/search?q= — search by bond_id, party name, or Stellar wallet address, returning matching bonds.
• Paginate the existing snapshot() lists (recent_bonds, soroban_nfts, trustless_work_contracts) using the shared parsePagination/paginatedResponse helpers (apps/api/src/common/pagination.ts) instead of the hardcoded limit(20)/limit(10).

Frontend

• Update apps/web/app/explorer/ with a real search bar and a per-bond detail view backed by the new endpoints, instead of only showing the latest snapshot.

ACCEPTANCE CRITERIA

• GET /explorer/bonds/:bondId returns full bond history for a real bond id, 404 for an unknown one.
• GET /explorer/search?q= matches on bond id, party name, and wallet address.
• GET /explorer/snapshot?page=2&limit=20 returns the correct next slice with an accurate total.
• All explorer endpoints remain public (@Public(), no auth required) since this is VELAR's public transparency surface.
• The frontend explorer page lets a visitor search and drill into a bond's full history.
• npm run build, npm run lint, npm run test pass in both apps/api and apps/web with NO VELAR credentials.

NOTES

Relevant files: apps/api/src/explorer/explorer.controller.ts, apps/api/src/escrow/stellar.config.ts (URL builders, reuse explorerAccountUrl/explorerAssetUrl/explorerContractUrl), apps/api/src/common/pagination.ts (reuse), apps/web/app/explorer/. This endpoint stays public/unauthenticated by design — do not add an AuthGuard here.

No VELAR credentials required: the explorer is public by design; verifiable locally against local/seed data, no real credentials.

Difficulty: Advanced (full-stack)
Priority: High

PR REQUIREMENTS

• Ship this as a single pull request — do not split into stacked/sequential PRs.
• Your PR description must include Closes #<this-issue-number> (this issue's GitHub number) so merging auto-closes it.

CAMPAIGN REQUIREMENTS (FWC26)

To be eligible for the reward on this issue, the contributor must:

• Follow Velar on X: https://x.com/VelarApp
• Star the repository: https://github.com/Velar-Bonds/Velar
• Follow the Velar-Bonds organization on GitHub: https://github.com/Velar-Bonds

[Naajih09]

Hi, I'd like to work on this issue. I've gone through the description and acceptance criteria and I'm confident I can deliver it. I'll make sure every acceptance criterion is met and submit a clean, tested PR. Please assign it to me.

[Peculiarr7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. I’ll prioritize this immediately and ensure a reliable solution is delivered as soon as possible. Thank you!

[shogun444]

Hey maintainer, I’d love to grab #79! Checked the repo and the explorer v2 requirement is crystal clear.

I work as a full-stack developer, so I'll handle both sides cleanly—building the bond search and drill-down endpoints on the backend, and delivering a clean, fast explorer UI on the frontend with smooth pagination and solid empty/loading states.

Portfolio: https://portfolio-amber-one-v8ggyhsjyr.vercel.app/

Ready to jump on this right away!

[SofGarro]

Hi, I'd like to work on this issue, the public explorer page currently only shows the latest 20 bonds and 10 contracts, with no way to search or see a specific bond's full history. I'd add a way to look up one bond in detail (its history, owner, and links to the on-chain contracts), a search by bond ID / party name / wallet address, and proper pagination instead of just showing the latest items. I'd also update the explorer page on the frontend so people can actually use the search and view a bond's details.

[grantfox-oss]

🦊 GrantFox — @SofGarro has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #79)
2. Your PR will be reviewed by the Velar-Bonds maintainers

Good luck! Track your progress on GrantFox.