!5342itz/parity-c4a-refund-funding → itz/parity-c3-outbound-guardf5efe1e6a0

Hold refunds until their inbound is finalised and owned (parity C4a)

AI-generatedEverything on this page was written by an AI agent from the diff: the summaries, the narration, the diagrams, the flags and the glossary. It can be wrong or incomplete, so check it against the code before you rely on it.

5commits
14files
2.9klines changed
979lines to read
UTXOsources proven
2×checks per signing
+1 fieldsigner store

Where the diff is

Where the refund guard sits in the signer

Two checks wrap signing; a failed first check parks the item for a background worker.

newchanged

4-minute explainer

What changed

Why hold a refund

A reorged or reverted inbound must not fund a refund.

inboundvoterREFUNDvault pays

The funding check

Fresh voter: finalised, not reverted, owns this refund action.

  • finalised
  • not reverted
  • action owns refund
  • chain proof (UTXO)

Two checks per signing

Before the vault lock, and again before every broadcast.

checklock · signre-checkbroadcast

Hold and retry

A held item gets a retry height; one worker re-checks each block.

held h+1held h+2pass → 0

Store writes

One write mutex; Batch never replaces an existing key.

SetBatchRemoveDeferUpdateRetry

The UTXO proof

Rebuild the deposit's block and match what THORChain credited.

locateblockrebuildconfirmanchor

What is guarded

UTXO proven; EVM a no-op until C4b; others pass.

BTC BCH LTC DOGE ZECEVM no-opothers pass

State + upgrade

Constants

  • newrefundFundingTimeout30s
  • newrefundFundingRetryBlocks1
  • newrefundFundingMaxHeightHints16
  • newrefundFundingMaxParentBatchBytes32 MiB

Signer store fields added

TxOutStoreItem (signer LevelDB JSON)
+ RefundFundingRetryHeight int64 (json refund_funding_retry_height, omitempty)
SignerStorage interface
+ DeferRefundFunding(string, int64) error+ UpdateRefundFundingRetry(TxOutStoreItem, int64) error
SignerStore
+ writeMu sync.Mutex

Line by line · every changed logic line, narrated

14:28runtime
25code chapters
100%logic lines narrated (724/724)
7flagged spots
speed

Chapters

What to check

Ask an AI about this change

Chat assistantClaude, ChatGPT, … (reads a link)

Coding agentClaude Code, Cursor, … (reads the repo)

The context file is context.md. Use Copy with context for an AI that can't open links; it pastes the whole file in.

Glossary

Bifrost
The off-chain node process that watches external chains and signs outbounds. This change lives entirely in Bifrost; THORNode consensus is untouched. docs/bifrost-refund-funding.md ↗
C4b
The follow-up MR that brings the real EVM refund-funding proof after the EVM observation rework (C6).
Finalised height
The height at which a voter reached consensus on a confirmed observation. Zero means the inbound is not yet final.
Inbound voter
THORChain's record of an observed inbound: the votes, finalise height, reverted flag and the outbound actions it owns. Read fresh via /thorchain/tx/details. thorclient/refund_funding.go ↗
Keysign
The TSS signing round where vault members jointly sign an outbound. Nodes that hold while others sign can stall the round.
REFUND outbound
An outbound that returns an inbound's funds after THORChain could not complete it. Its memo is REFUND:<inbound hash>.
Retry marker
RefundFundingRetryHeight on the stored signer item. Non-zero keeps the item out of signing until the background worker's check passes. signer/storage.go ↗
txindex
A UTXO daemon option that indexes all transactions so getrawtransaction can find a mined transaction by hash.
Unexposed
A stored item with no signed bytes, checkpoint, terminal-round retry or saved observation. Only these may be held and parked. signer/refund_funding.go ↗
Zebra
The Zcash node implementation. The parent batch uses JSON-RPC 2.0 and numeric verbosity for it.