BA-14 · LESSON 02

Regtest workflows

KEY DEFINITIONS

Terms used in this lesson

Regtest: A private Bitcoin test network where the operator can create blocks instantly for repeatable experiments.
Coinbase transaction: The special first transaction in a Bitcoin block, which claims permitted subsidy and fees and has no ordinary prior-output input.
RPC: Remote procedure call: the command interface applications use to ask a Bitcoin node to perform operations or return state.
Outpoint: A transaction ID plus output number that identifies one exact prior output.
Transaction ID: The identifier produced by hashing a Bitcoin transaction’s non-witness serialization.
UTXO: Unspent transaction output: one discrete chunk of bitcoin that can be used as a transaction input.
Oracle: A system that reports outside information, such as a market price, for use by a protocol.

A private deterministic chain enables instant mining, reorgs, policy experiments, and repeatable failure tests.

45 min Difficulty 3/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 · state machineOne valid action transforms a known stateSelect any state to inspect its exact role.

RELATIONSHIP MAPOrdered mechanism flow

01
BEFOREKnown state
Identify the facts and objects that exist before the action.
02
ACTIONRegtest workflows
The Regtest workflows lesson isolates the event that proposes a change.
03
RULEDeterministic check
The enforcing rule accepts or rejects the proposed transition.
04
AFTERSuccessor state
Accepted work creates a new state without silently changing the prior facts.
05
FAILUREState unchanged
A failed condition must not produce a partially accepted successor.

Rule shown: A valid transition names the prior state, action, enforcing rule, and successor state.

STAGE 1 OF 5BEFORE: Known state

Identify the facts and objects that exist before the action.

Governing relationship: A valid transition names the prior state, action, enforcing rule, and successor state. Complete path: 1. BEFORE, Known state. Identify the facts and objects that exist before the action. 2. ACTION, Regtest workflows. The Regtest workflows lesson isolates the event that proposes a change. 3. RULE, Deterministic check. The enforcing rule accepts or rejects the proposed transition. 4. AFTER, Successor state. Accepted work creates a new state without silently changing the prior facts. 5. FAILURE, State unchanged. A failed condition must not produce a partially accepted successor.

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

BEFORE

A fresh Core v31.1 regtest node mines a signed payment T, then explicitly invalidates T's block.

MECHANISM

Start bitcoind with regtest and an explicit temporary directory so tests cannot touch mainnet wallets or another run's state.

AFTER

Each branch claim is tied to a distinct RPC observation; confirmation counts alone are not a UTXO rollback oracle.

Text equivalent: Starting from A fresh Core v31.1 regtest node mines a signed payment T, then explicitly invalidates T's block. The mechanism begins when Start bitcoind with regtest and an explicit temporary directory so tests cannot touch mainnet wallets or another run's state. The resulting lesson is Each branch claim is tied to a distinct RPC observation; confirmation counts alone are not a UTXO rollback oracle.

2. Mechanism pathSelect a stage to inspect its job

STAGE 1 OF 5

Create an isolated data directory

Start bitcoind with regtest and an explicit temporary directory so tests cannot touch mainnet wallets or another run's state.

Complete path: 1. Create an isolated data directory: Start bitcoind with regtest and an explicit temporary directory so tests cannot touch mainnet wallets or another run's state. 2. Create wallets and mature funds: Generate addresses, mine coinbase outputs, and mine enough additional blocks for the 100-block maturity rule before spending them. 3. Exercise the workflow: Construct, sign, test, broadcast, mine, and query transactions using RPC with exact assertions. 4. Force failure and reorg: Submit conflicts, invalid scripts, low fees, locks, or competing branches rather than testing only a successful confirmation. 5. Stop and remove state: Terminate the node, capture needed logs, and delete only the validated temporary directory so the next run is independent.

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

ACCEPTED PATH

Predictions are sealed before a fresh Core run, and every awarded assertion is recomputed from raw RPC observations covering maturity, admission, confirmation, invalidation, rollback, competing blocks, reconfirmation, and cleanup.

CHANGED CONDITION

A schema contradiction, policy or consensus rejection, conflict, nonfinal lock, missing rollback observation, changed txid, or incomplete cleanup invalidates the corresponding evidence fingerprint.

Important distinction: Regtest behavior proves a transaction will relay and confirm identically on mainnet. Consensus logic can be exercised, but public peer topology, miner policy, fees, timing, adversaries, and software versions differ.

Text equivalent: The accepted path is enforced by Predictions are sealed before a fresh Core run, and every awarded assertion is recomputed from raw RPC observations covering maturity, admission, confirmation, invalidation, rollback, competing blocks, reconfirmation, and cleanup. If the required condition changes, A schema contradiction, policy or consensus rejection, conflict, nonfinal lock, missing rollback observation, changed txid, or incomplete cleanup invalidates the corresponding evidence fingerprint.

Loading lesson visuals...

Learn the idea

Regtest is a private Bitcoin network mode where the operator controls block production and can create deterministic test chains without public funds. It uses separate network parameters, addresses, ports, and data directories. Tests can mine blocks instantly, create reorgs, set policy conditions, and reset all state.

GUIDED EXPLANATION1/5 ideas inspected

Create an isolated data directory

Start bitcoind with regtest and an explicit temporary directory so tests cannot touch mainnet wallets or another run's state.

The worked example follows the explanation

Inspect every idea above to open it.

Important distinction“Regtest behavior proves a transaction will relay and confirm identically on mainnet.”

Consensus logic can be exercised, but public peer topology, miner policy, fees, timing, adversaries, and software versions differ.

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.