Repository navigation
#16 /advances and /transactions, from Horizon and the contract's own record - #66
Conversation
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.
|
@Lexirieru this is ready for review: CI is green, and |
Lexirieru
left a comment
There was a problem hiding this comment.
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 stalenode_modules, not this branch.) - The nullifier derivation is right. I ran your
nullifierFor("pub-h1792084434", "2026-07-01", "2026-09-30")and gotd0cd01df330362b23508edf7e386950549da634b756d1c29aa242cfc9c88c839— the exact valueis_spentanswerstruefor on the dev contract. Independent of your fixture, and independent of my Python. - Live, with
ADVANCE_CONTRACT_IDon the dev contract:/advancesreturned 4 advances newest first with the contract's own principal/repaid;/transactionsreturned 13 rows (4 advances, 8 repayments, 1 trustline); a bad borrower gave 400; an account with no history gave[]; CORS echoedhttp://localhost:3000and sent no header at all for an unknown origin. The⚠ contract addresses differwarning 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 owncreate_accounton 2026-10-09. Horizon is keeping everything from account creation, so the week-longgetEventswindow 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.alloverreadAdvanceis unbounded: N advances means N simultaneous simulations, and one failure 502s the whole list. Fine at demo scale, worth a comment saying so.READ_SOURCEbeing 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.
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
GET /advances?borrower=<G…>asAdvanceSummaryfe/src/lib/api/types.ts. Amounts and timestamps are strings.nullifierand the disbursementtxHashon each advancenullifieris computed exactly the way the contract'snullifier_forcomputes it. It matches the value Axel checked withis_spenton chain (#61).GET /transactions?borrower=<G…>asLedgerTransactiontrustlinekindamountis"0"andnullifieris"".status: "failed"meansWhere 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
getEventswas 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.advancewas stillnullafter Deploy the advance contract to testnet, with evidence #15. It now holdsCCQFL2…I2HS, innetwork.tsand in the deployments record together, asnetwork.test.tsrequires.horizonUrlwas added to the record, and it can be overridden withHORIZON_URL.USDC:GBBD47…LFLA5) maps to the recorded SACCBIELT…DAMA.G…address.Verified
ADVANCE_CONTRACT_IDset to the dev contractCD25Q4…HQN4:/advancesreturned the rehearsal account's 4 advances, with principal and repaid read from the contract;/transactionsreturned 13 rows: 4 advances, 8 repayments and 1 trustline;[];For #21
Set
NEXT_PUBLIC_API_URL, and set the front end's origin in the API'sCORS_ORIGINS. Nothing intypes.tsorclient.tshas to change.