DA-02 · LESSON 06

Indexer reconstruction and reorgs

KEY DEFINITIONS

Terms used in this lesson

Validator: Software or a participant that independently checks state transitions under a system's rules. The exact role depends on the protocol being discussed.
Runes: A Bitcoin metaprotocol that assigns fungible-token meaning to transaction outputs through off-chain interpretation.
UNIT: Ducat’s dollar-pegged stablecoin, the asset a borrower can create against bitcoin collateral.
Proof-of-work target: The maximum header-hash value accepted for a block; lowering it makes valid hashes harder to find.
UTXO: Unspent transaction output: one discrete chunk of bitcoin that can be used as a transaction input.
Vault: A set of Bitcoin outputs and spending rules that holds collateral and represents the current loan state.
Outpoint: A transaction ID plus output number that identifies one exact prior output.
API: Application programming interface: a defined way for one program to request data or actions from another.

Validators and Rune-compatible indexers deterministically replay confirmed transactions and must reverse and reapply derived token state during Bitcoin reorganizations.

45 min Difficulty 4/5 Not started

VISUAL MODEL

See the whole mechanism before going step by step

Use the diagrams to orient yourself. Then the guided explanation below teaches every part in depth.

4 explanatory views

CONCEPT-SPECIFIC MAP · ducat vaultA Ducat action moves one Bitcoin-anchored vault state to a successorSelect any state to inspect its exact role.

RELATIONSHIP MAPInputs, rule, and outputs

01
PREDECESSORCurrent vault outpoint
The current Bitcoin output anchors collateral and identifies the state being spent.
02
REQUESTIndexer reconstruction and reorgs
The Indexer reconstruction and reorgs workflow proposes one exact action and successor state.
03
POLICYProfile, oracle, signatures
Applicable policy, price evidence, authorization, and transaction shape are checked.
04
BITCOIN SPENDScript-valid transaction
Bitcoin miners and nodes can include only a transaction that satisfies Bitcoin rules.
05
SUCCESSORNew outpoint and state
Ducat validators reconstruct debt, collateral, token, and account changes from the confirmed transaction.

Rule shown: Bitcoin checks the spend; Ducat components independently reconstruct and validate the additional protocol state.

STAGE 1 OF 5PREDECESSOR: Current vault outpoint

The current Bitcoin output anchors collateral and identifies the state being spent.

Governing relationship: Bitcoin checks the spend; Ducat components independently reconstruct and validate the additional protocol state. Complete path: 1. PREDECESSOR, Current vault outpoint. The current Bitcoin output anchors collateral and identifies the state being spent. 2. REQUEST, Indexer reconstruction and reorgs. The Indexer reconstruction and reorgs workflow proposes one exact action and successor state. 3. POLICY, Profile, oracle, signatures. Applicable policy, price evidence, authorization, and transaction shape are checked. 4. BITCOIN SPEND, Script-valid transaction. Bitcoin miners and nodes can include only a transaction that satisfies Bitcoin rules. 5. SUCCESSOR, New outpoint and state. Ducat validators reconstruct debt, collateral, token, and account changes from the confirmed transaction.

1. State transitionWhat exists, what changes, and what results

BEFORE

Block heights and outpoints are illustrative. The lesson teaches the required deterministic result, not a claim about a particular validator API.

MECHANISM

The validator parses confirmed transactions and updates UTXOs, UNIT allocations, accounts, and vault objects deterministically.

AFTER

Derived state must follow the selected Bitcoin chain. Disconnect reverses the old block before connect applies its replacement, so balances from both branches are never added…

Text equivalent: Starting from Block heights and outpoints are illustrative. The lesson teaches the required deterministic result, not a claim about a particular validator API. The mechanism begins when The validator parses confirmed transactions and updates UTXOs, UNIT allocations, accounts, and vault objects deterministically. The resulting lesson is Derived state must follow the selected Bitcoin chain. Disconnect reverses the old block before connect applies its replacement, so balances from both branches are never added together.

2. Mechanism pathSelect a stage to inspect its job

STAGE 1 OF 4

Apply blocks in order

The validator parses confirmed transactions and updates UTXOs, UNIT allocations, accounts, and vault objects deterministically.

Complete path: 1. Apply blocks in order: The validator parses confirmed transactions and updates UTXOs, UNIT allocations, accounts, and vault objects deterministically. 2. Record checkpoints and undo data: Each block's derived changes need enough history to restore the rollback target: the last recorded chain state still shared with the replacement branch. 3. Disconnect the old branch: On a reorg, transactions from removed blocks no longer define confirmed UNIT and vault state. 4. Apply the winning branch: The indexer replays replacement blocks and exposes only the state consistent with the selected Bitcoin chain.

3. Rule and failure boundaryWhat accepts the result and where it can stop

ACCEPTED PATH

The worked case executes the named inputs and checks in the displayed order. The indexer replays replacement blocks and exposes only the state consistent with the selected Bitcoin chain.

CHANGED CONDITION

A missing, malformed, stale, unauthorized, or inconsistent required input stops at its first named boundary. Confirmations reduce reorg risk but do not create absolute finality. An indexer must handle disconnected blocks correctly.

Important distinction: A confirmed UNIT balance can never change because Bitcoin blocks are final. Confirmations reduce reorg risk but do not create absolute finality. An indexer must handle disconnected blocks correctly.

Text equivalent: The accepted path is enforced by The worked case executes the named inputs and checks in the displayed order. The indexer replays replacement blocks and exposes only the state consistent with the selected Bitcoin chain. If the required condition changes, A missing, malformed, stale, unauthorized, or inconsistent required input stops at its first named boundary. Confirmations reduce reorg risk but do not create absolute finality. An indexer must handle disconnected blocks correctly.

Loading lesson visuals...

Learn the idea

An indexer scans Bitcoin history and derives Runes and Ducat state that Bitcoin Core does not store as native balances. A checkpoint is a recorded chain position, usually a block height and block hash, plus enough derived state or undo information to resume or verify replay. A rollback target is the most recent checkpoint or common ancestor that remains on the selected Bitcoin chain after a reorg. A reorg disconnects previously accepted blocks, so derived changes after that rollback target must be reversed before transactions on the replacement branch are applied.

GUIDED EXPLANATION1/4 ideas inspected

Apply blocks in order

The validator parses confirmed transactions and updates UTXOs, UNIT allocations, accounts, and vault objects deterministically.

The worked example follows the explanation

Inspect every idea above to open it.

Important distinction“A confirmed UNIT balance can never change because Bitcoin blocks are final.”

Confirmations reduce reorg risk but do not create absolute finality. An indexer must handle disconnected blocks correctly.

FINISH LEARNING FIRST

The questions unlock after every required learning activity

Inspect every guided idea, open the worked example, rebuild its mechanism, and complete the deterministic lesson tool. Your progress is saved automatically.