Repository navigation
feat: Index refunds issued on foreclosed applications #812
Description
The node records foreclosures but nothing about the refunds IApplication.issueRefund pays out afterwards, so a UI that wants to list refundable deposits and their state has to rebuild that view from portal inputs and on-chain reads.
What a client needs
On a foreclosed application a UI has to answer, per deposit input:
- Is this input a portal deposit, and of which asset (Ether, ERC-20, ERC-721, ERC-1155 single or batch), amount and depositor?
- Is it refundable, which is the case for every input of an epoch after the last accepted one?
- Was its refund already issued, by which transaction and at which block?
- How many refunds has the application issued in total?
The contract side has all of it: issueRefund(uint256 inputIndex, bytes input) is permissionless, emits RefundIssued, and wasRefundForInputIssued(uint256) and getNumberOfIssuedRefunds() expose the state.
What the node offers today
The node indexes the foreclosure (foreclose_block, foreclose_transaction on the application) and the accepted epochs, but no refund data: RefundIssued is not indexed, inputs carry no refund flag, and there is no refund counter.
A client can only rebuild the view itself, as the explorer does since cartesi/rollups-explorer#484, shipped in v2.0.0-alpha.5:
| need | workaround | limitation |
|---|---|---|
| find the deposits | cartesi_listInputs once per portal sender (five calls), from the last accepted epoch's input_index_upper_bound on, then decode each payload with the codec |
one query per portal, newest N only, payload decoding on the client |
| refund issued? | eth_call wasRefundForInputIssued per input (batched where possible) |
a chain read per input; the refund's transaction hash and block are not available |
| refund count | eth_call getNumberOfIssuedRefunds |
a chain read |
| refund history | not possible | no record of issued refunds, so nothing to list or link to |
A possible shape
One way to expose it, following how withdrawals are indexed. The names are only a suggestion:
cartesi_listRefunds(application, limit, offset, descending): one record per issued refund withinput_index,epoch_index,block_number,transaction_hash,log_index,created_at.cartesi_getRefund(application, input_index): the record for one input, or not found.- A
refundfield onInput(or on thecartesi_listInputsrow),nulluntil a refund is issued, so a client listing inputs of a foreclosed application sees the state without a second call. - An issued-refund counter on the application, next to
processed_inputs, so summary pages do not need a chain read.
None of this needs new contract data: everything comes from RefundIssued and the foreclosure the node already tracks.
Optional, and a bigger step: a cartesi_listInputs filter for portal deposits (deposits_only or a sender_in list), so a client does not need one call per portal to find them.
Acceptance criteria
- A client can list the refunds an application has issued, each with input index, block, transaction hash and log index.
- A client can tell whether a given input was refunded without a chain read.
- A client can read how many refunds an application has issued without a chain read.
Activity
brunomenezes commentedon Oct 29, 2026
@vfusco I posting for the record and to clarify how explorer is providing the feature so it gives some direction on "needs". Not sure whether the refunds is in your future list.