DA-07 · LESSON 06

Upgrade and compatibility

KEY DEFINITIONS

Terms used in this lesson

Taptree: The Merkle tree of alternative scripts committed inside a Taproot output.
Oracle: A system that reports outside information, such as a market price, for use by a protocol.
Vault: A set of Bitcoin outputs and spending rules that holds collateral and represents the current loan state.
Validator: Software or a participant that independently checks state transitions under a system's rules. The exact role depends on the protocol being discussed.
Guardian: A Ducat policy-checking signer that can authorize or reject defined protocol transactions.
Runestone: Transaction data interpreted by the Runes protocol to describe token creation or allocation.
API: Application programming interface: a defined way for one program to request data or actions from another.
Taproot: A Bitcoin output and spending design that can combine a public-key path with privately committed alternative scripts.

Protocol versions, taptree layout, oracle event formats, key packages, indexer rules, and client compatibility require coordinated migration.

45 min Difficulty 5/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
REQUESTUpgrade and compatibility
The Upgrade and compatibility 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, Upgrade and compatibility. The Upgrade and compatibility 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

Version one clients expect threshold events with an h commitment tag and a 30-minute expiry. Version two proposes a required snapshot_id field and a different liquidation lea…

MECHANISM

List transaction layouts, sequence tags, runestone parsing, taptrees, oracle event fields, request schemas, policy digests, key packages, and APIs.

AFTER

Data-format support can overlap across versions, but an existing Taproot commitment cannot be edited. New readers must preserve old parsing and old spend paths until every af…

Text equivalent: Starting from Version one clients expect threshold events with an h commitment tag and a 30-minute expiry. Version two proposes a required snapshot_id field and a different liquidation leaf committed only in newly created vaults. Act… The mechanism begins when List transaction layouts, sequence tags, runestone parsing, taptrees, oracle event fields, request schemas, policy digests, key packages, and APIs. The resulting lesson is Data-format support can overlap across versions, but an existing Taproot commitment cannot be edited. New readers must preserve old parsing and old spend paths until every affected output is migrated or naturally closed.

2. Mechanism pathSelect a stage to inspect its job

STAGE 1 OF 4

Inventory versioned interfaces

List transaction layouts, sequence tags, runestone parsing, taptrees, oracle event fields, request schemas, policy digests, key packages, and APIs.

Complete path: 1. Inventory versioned interfaces: List transaction layouts, sequence tags, runestone parsing, taptrees, oracle event fields, request schemas, policy digests, key packages, and APIs. 2. Define activation: State the block, time, profile version, deployment wave, or explicit migration that determines old and new behavior. 3. Test mixed versions: Run old-client/new-validator, new-client/old-Guardian, reorg, rollback, and existing-vault cases before rollout. 4. Respect irreversible commitments: Existing Bitcoin outputs keep their committed keys and scripts; rollback may require forward migration rather than restoring old code.

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. Existing Bitcoin outputs keep their committed keys and scripts; rollback may require forward migration rather than restoring old code.

CHANGED CONDITION

A missing, malformed, stale, unauthorized, or inconsistent required input stops at its first named boundary. Confirmed Bitcoin commitments and migrated keys or data remain. Operational rollback cannot rewrite already created outputs.

Important distinction: Rolling back application code restores the previous protocol state. Confirmed Bitcoin commitments and migrated keys or data remain. Operational rollback cannot rewrite already created outputs.

Text equivalent: The accepted path is enforced by The worked case executes the named inputs and checks in the displayed order. Existing Bitcoin outputs keep their committed keys and scripts; rollback may require forward migration rather than restoring old code. If the required condition changes, A missing, malformed, stale, unauthorized, or inconsistent required input stops at its first named boundary. Confirmed Bitcoin commitments and migrated keys or data remain. Operational rollback cannot rewrite already created outputs.

Loading lesson visuals...

Learn the idea

A compatible upgrade preserves one shared interpretation of old and new state across clients, validators, Guardians, oracle events, key packages, profiles, and Bitcoin scripts. An activation boundary is the declared block height, time, or profile change at which new rules begin. Mixed-version operation means old and new components run at the same time. Existing Bitcoin outputs keep the keys and scripts committed when they were created, so some changes require an authorized migration spend.

GUIDED EXPLANATION1/4 ideas inspected

Inventory versioned interfaces

List transaction layouts, sequence tags, runestone parsing, taptrees, oracle event fields, request schemas, policy digests, key packages, and APIs.

The worked example follows the explanation

Inspect every idea above to open it.

Important distinction“Rolling back application code restores the previous protocol state.”

Confirmed Bitcoin commitments and migrated keys or data remain. Operational rollback cannot rewrite already created outputs.

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.