Skip to content

#16 /advances and /transactions, from Horizon and the contract's own record - #66

Merged
Lexirieru merged 1 commit into
mainfrom
feat/16-backend-api
Oct 20, 2026
Merged

Lexirieru merged 1 commit into
mainfrom
feat/16-backend-api

Conversation

@Lin1er

@Lin1er Lin1er commented Oct 19, 2026

Copy link
Copy Markdown
Collaborator

Refs #16. These are the two chain-state routes @Nabil-Aufa asked for on #16, for #21 (repayment and history). Full reference: docs/api.md.

Answers to the five questions on #16

# Asked Answer
1 GET /advances?borrower=<G…> as AdvanceSummary Done. Newest first, and the field names match fe/src/lib/api/types.ts. Amounts and timestamps are strings.
2 nullifier and the disbursement txHash on each advance Done. The nullifier is computed exactly the way the contract's nullifier_for computes it. It matches the value Axel checked with is_spent on chain (#61).
3 GET /transactions?borrower=<G…> as LedgerTransaction Done. Newest first.
4 A trustline kind Done. amount is "0" and nullifier is "".
5 What status: "failed" means The transaction reached the ledger and failed. The fee (a fraction of an XLM) was spent, and no USDC moved. A transaction that never reached a ledger is not listed, because nothing about it is on chain. So "not charged" is right for the USDC but not for the fee.

Where the data comes from

Horizon provides the borrower's history. It keeps every operation, failed ones included, with the contract call's arguments and the USDC that moved. RPC getEvents was not usable: it only reaches back about a week, and the contract has no index by borrower.

The contract provides the figures, read with advance(nullifier) (simulated, nothing signed). So principal and repaid are the contract's own numbers, never totals added up from history.

Also in this PR

  • RECORDED.contracts.advance was still null after Deploy the advance contract to testnet, with evidence #15. It now holds CCQFL2…I2HS, in network.ts and in the deployments record together, as network.test.ts requires.
  • horizonUrl was added to the record, and it can be overridden with HORIZON_URL.
  • A test checks that the USDC asset used to read Horizon (USDC:GBBD47…LFLA5) maps to the recorded SAC CBIELT…DAMA.
  • 502 is returned when Horizon or the RPC fails, so the front end can retry. 400 is returned for a borrower that is not a G… address.

Verified

For #21

Set NEXT_PUBLIC_API_URL, and set the front end's origin in the API's CORS_ORIGINS. Nothing in types.ts or client.ts has to change.

The two routes the front end's repayment view (#21) reads.

- /advances?borrower=G...: every advance the wallet took, newest
  first. The figures come from the contract's own record
  (advance(nullifier)), and the nullifier is computed from the call's
  arguments, as nullifier_for does on chain.
- /transactions?borrower=G...: advances, repayments and the USDC
  trustline, newest first. Transactions that failed on the ledger
  are listed as failed: the fee was spent, no USDC moved.

History comes from Horizon, not RPC getEvents. getEvents only reaches
back about a week, and an advance outlives that. Horizon keeps every
operation, failed ones included, with call arguments and USDC moved.

Also records the deployed advance contract (#15) and the Horizon URL
in network.ts and the deployments record. advance was still null. A
test checks that the USDC issuer used for Horizon maps to the
recorded SAC.

Tested against real Horizon output (fixture) and live on testnet
against the dev contract.
@Lin1er

Lin1er commented Oct 20, 2026

Copy link
Copy Markdown
Collaborator Author

@Lexirieru this is ready for review: CI is green, and /advances and /transactions were verified live against the dev contract (details in the description). It's the last open item in M2, which is due 23 Oct. #73 (the #17 relay) is stacked on it.

@Lexirieru Lexirieru left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. I checked this out and ran it rather than reading it, because the claims in the PR body are the kind that are only worth anything if someone reproduces them. Everything you said holds. Notes below are notes, not blockers.

Reproduced

  • 75/75 tests pass on a clean npm install. (My first run showed 6 failures; that was my own stale node_modules, not this branch.)
  • The nullifier derivation is right. I ran your nullifierFor("pub-h1792084434", "2026-07-01", "2026-09-30") and got d0cd01df330362b23508edf7e386950549da634b756d1c29aa242cfc9c88c839 — the exact value is_spent answers true for on the dev contract. Independent of your fixture, and independent of my Python.
  • Live, with ADVANCE_CONTRACT_ID on the dev contract: /advances returned 4 advances newest first with the contract's own principal/repaid; /transactions returned 13 rows (4 advances, 8 repayments, 1 trustline); a bad borrower gave 400; an account with no history gave []; CORS echoed http://localhost:3000 and sent no header at all for an unknown origin. The ⚠ contract addresses differ warning fires correctly on the override.
  • Horizon over getEvents — your rationale is verified, not just plausible. I pulled the demo account's full operation list: the oldest record is its own create_account on 2026-10-09. Horizon is keeping everything from account creation, so the week-long getEvents window really is the constraint and Horizon really does solve it.

That last one matters more than it looks. If Horizon testnet had been trimming too, this design would have had the same hole you rejected getEvents for, and nothing in the test suite would have shown it.

1. status: "failed" has no real-data coverage, and is rarer than it reads

All 39 operations on that account succeeded, and horizon-ops.json is a verbatim capture of them — so the fixture contains zero failed rows. history.test.ts covers the parsing with synthesised ones, which is the right call.

The part worth writing down: in Forepay a contract refusal does not produce a failed ledger transaction. Every negative case in the rehearsal was refused at simulation and never reached the ledger (docs/deployments.md, #24/#25/#26 — "the refusal never reached the ledger"). So failed is only reachable through the narrow race where simulation passes and inclusion fails. That is exactly what @AncungAulia flagged as item 4 on #58, and the front end will handle it badly if it treats failed as the ordinary refusal path.

One or two sentences in docs/api.md would prevent that reading.

2. amount's doc comment contradicts amount's behaviour

LedgerTransaction.amount says "0 when nothing moved". A failed repayment carries the attempted amount; a failed advance carries 0. Your test states the asymmetry deliberately (// what was attempted; no USDC moved) and it matches what fe/src/lib/api/types.ts wants — a failed repayment "shown, struck through". So the behaviour is right and the comment is wrong. Please fix the comment and say the asymmetry in docs/api.md.

Cross-PR, for @Nabil-Aufa on #58: a failed advance arrives as amount: 0, so 3b would render a struck-through "0.00 USDC", which says nothing. That row probably wants different words, not a struck-through zero.

3. Pagination truncates silently

maxPages: 5 × 200 = 1,000 operations, newest first. Past that the loop just stops: the oldest advances disappear from /advances, and an advance missing from /advances is one #21 cannot offer a repayment for — even while it is outstanding.

I measured it rather than guessing: that account has 39 operations today, 4% of the ceiling. So this is not close to binding and I am not asking you to change the limit. But a ceiling that is crossed in silence is the kind that is discovered at a demo. Either throw when page === maxPages - 1 and _links.next still exists, or put the number in docs/api.md.

4. Minor

  • Promise.all over readAdvance is unbounded: N advances means N simultaneous simulations, and one failure 502s the whole list. Fine at demo scale, worth a comment saying so.
  • READ_SOURCE being an all-zero key works (I exercised it), but a line explaining why a non-existent account is acceptable for a read-only simulation would save the next person the lookup.

Two things from my side you should know

The contract was upgraded since you tested. #63 added sizing(); both the dev and production contracts now run wasm e5626890…, still StellarExpert-verified against commit 2b545287. The Advance struct is unchanged, so nothing here breaks — and I re-ran your routes against the upgraded dev contract an hour ago, which is where the numbers above come from. Your work is already post-upgrade-verified.

advance now defaults to the production contract, which still has no claim template pinned (#61, blocked on #5), so out of the box both routes correctly return [] for everyone. Anyone demoing before #61 lands has to set ADVANCE_CONTRACT_ID to the dev contract. Worth one line in docs/api.md so it is not rediscovered live.

Nice piece of work — the decision to read figures from advance(nullifier) instead of summing Horizon is the right one, and the reason you give for it is the real reason.

@Lexirieru
Lexirieru merged commit e1a70a8 into main Oct 20, 2026
6 checks passed
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.

2 participants