TYPE 0x0404 · RECURSION FAMILY

RECURSE_COUNT

Countdown covenant. Each spend decrements the count parameter by one. When count reaches zero the covenant terminates and the UTXO is free. Provides a finite-hop covenant chain with deterministic termination. No Tapscript equivalent.

Recursion Invertible

Ladder Diagram

Fields

Field	Data Type	Size	Side	Description
count	NUMERIC	1-4 B	Conditions	Remaining hop count (≥ 0). Decremented by 1 on each spend. Covenant terminates when count reaches 0.

Wire Format Breakdown

0x0404 0 1 NUMERIC · count Conditions = 9 bytes

0x0404 0 0 Witness = 4 bytes

Total 15 bytes

Evaluation Logic

1.Locate the conditions NUMERIC field. Missing → ERROR. ReadNumeric → count; undecodable → ERROR

2.If count == 0 → SATISFIED immediately (countdown done; covenant terminates, output is free).

3.If count < 0 → ERROR (malformed; also guards cur - 1 against signed overflow on INT64_MIN).

4.No spending context (no input_conditions or spending_output): structural pass → SATISFIED

5.Build a copy of the revealed rung (input_conditions.rungs[0]). Walk its blocks, find the first RECURSE_COUNT block, and within it find the first NUMERIC field; verify cur > 0 (else ERROR) and write cur - 1. If no RECURSE_COUNT block carrying a NUMERIC was found in the rung → UNSATISFIED

6.Recompute the expected MLSC root using the mutated rung: leaf-centric (BuildCPRung + ComputeTxMLSCLeaf + ComputeExpectedRoot) when verified_leaves is set, otherwise full-conditions fallback (ComputeConditionsRootMLSC).

7.Extract the spending output's MLSC root via GetMLSCRoot; non-MLSC output → UNSATISFIED. Compare against the expected root: equal → SATISFIED; differs → UNSATISFIED

Worked Example

3-hop payment channel: count = 3

Spend 1: count=3 > 0, output must have RECURSE_COUNT(2) → SATISFIED

Spend 2: count=2 > 0, output must have RECURSE_COUNT(1) → SATISFIED

Spend 3: count=1 > 0, output must have RECURSE_COUNT(0) → SATISFIED

Spend 4: count=0 → SATISFIED (covenant done, output is free)

JSON Wire Format

{
  "type": "RECURSE_COUNT",
  "fields": [
    { "type": "NUMERIC", "value": 3 }
  ]
}

Count value determines the exact number of covenanted hops remaining. A count of 0 means the covenant is already satisfied.

Use Cases

N-Hop Payment Channels

A payment channel that allows exactly N intermediate hops before the funds become unencumbered. Each routing hop decrements the counter, ensuring the payment reaches its destination within a bounded number of steps.

Finite State Machines

Combined with other blocks, implements a state machine with a known maximum number of transitions. The count acts as a fuel meter, guaranteeing termination after N state changes.

Countdown Triggers

A multi-party protocol where N participants must each sign and forward the UTXO. After all N parties have acted (count reaches 0), the final output is free to be spent without restrictions.

← RECURSE_UNTIL RECURSE_SPLIT →