When is a coin allowed to move?

Evidence

Each numbered marker in the text points here, and the ↩ links lead back to every place that cites an entry. Quotes are verbatim from the BIP files at commit 3a10b5b, including their wiki markup; links open the exact lines; the quoted text sits under each entry. Labels say what kind of statement each is: a rule, the author’s rationale, history, a test vector, or our own inference.

1. ↩ History BIP 65 (OP_CHECKLOCKTIMEVERIFY) was assigned in 2014, BIPs 68, 112 and 113 in 2015; all four are consensus soft forks recorded as Deployed.

   BIP 65 L3–8 BIP 68 L3–11 BIP 68 L9–11 BIP 112 L3–10 BIP 112 L8–10 BIP 113 L3–9 BIP 113 L7–9

   Quoted source text (7)

   Layer: Consensus (soft fork) Title: OP_CHECKLOCKTIMEVERIFY Authors: Peter Todd <pete@petertodd.org> Status: Deployed Type: Specification Assigned: 2014-10-01

   Layer: Consensus (soft fork) Title: Relative lock-time using consensus-enforced sequence numbers

   Status: Deployed Type: Specification Assigned: 2015-05-28

   Layer: Consensus (soft fork) Title: CHECKSEQUENCEVERIFY

   Status: Deployed Type: Specification Assigned: 2015-08-10

   Layer: Consensus (soft fork) Title: Median time-past as endpoint for lock-time calculations

   Status: Deployed Type: Specification Assigned: 2015-08-10

2. ↩ a b Rule OP_CHECKLOCKTIMEVERIFY lets a transaction output be made unspendable until some point in the future; it redefines NOP2.

   BIP 65 L14–16 BIP 65 L21

   Quoted source text (2)

   This BIP describes a new opcode (OP_CHECKLOCKTIMEVERIFY) for the Bitcoin scripting system that allows a transaction output to be made unspendable until some point in the future.

   CHECKLOCKTIMEVERIFY redefines the existing NOP2 opcode.

3. ↩ a b Rule CHECKSEQUENCEVERIFY redefines NOP3 and, with BIP 68, lets a script branch require a minimum age of the output being spent.

   BIP 112 L16–19 BIP 112 L24

   Quoted source text (2)

   This BIP describes a new opcode (CHECKSEQUENCEVERIFY) for the Bitcoin scripting system that in combination with BIP 68 allows execution pathways of a script to be restricted based on the age of the output being spent.

   CHECKSEQUENCEVERIFY redefines the existing NOP3 opcode.

4. ↩ a b c Rule BIP 113 compares time locks against the median of the past 11 blocks' timestamps instead of the including block's own timestamp; that median advances monotonically.

   BIP 113 L16–19 BIP 113 L64–67

   Quoted source text (2)

   The median of the last 11 blocks is used instead of the block's timestamp, ensuring that it increases monotonically with each block.

   This BIP proposes that after activation calls to IsFinalTx() within consensus code use the return value of `GetMedianTimePast(pindexPrev)` instead.

5. ↩ a b Rule BIP 68 repurposes nSequence, whose only use in Bitcoin Core until then was disabling nLockTime checks (a use the BIP preserves).

   BIP 68 L22 BIP 68 L234

   Quoted source text (2)

   nSequence will be repurposed to prevent mining of a transaction until a certain age of the spent output in blocks or timespan.

   The only use of sequence numbers by the Bitcoin Core reference client software is to disable checking the nLockTime constraints in a transaction. The semantics of that application are preserved by this BIP.

6. ↩ a b c d Rule CHECKLOCKTIMEVERIFY fails if the stack is empty, the top item is negative, its lock-time type differs from nLockTime's, it is greater than nLockTime, or the input's nSequence is 0xffffffff; otherwise it acts as a NOP.

   BIP 65 L25–31

   Quoted source text (1)

   * the stack is empty; or * the top item on the stack is less than 0; or * the lock-time type (height vs. timestamp) of the top stack item and the nLockTime field are not the same; or * the top stack item is greater than the transaction's nLockTime field; or * the nSequence field of the txin is 0xffffffff; Otherwise, script execution will continue as if a NOP had been executed.

7. ↩ a b c d Rule CHECKSEQUENCEVERIFY fails on an empty stack or a negative argument; if the argument's disable flag is clear, it also fails when the transaction version is below 2, the input's disable flag is set, the units differ, or the masked argument exceeds the masked nSequence.

   BIP 112 L27–33

   Quoted source text (1)

   * the stack is empty; or * the top item on the stack is less than 0; or * the top item on the stack has the disable flag (1 << 31) unset; and ** the transaction version is less than 2; or ** the transaction input sequence number disable flag (1 << 31) is set; or ** the relative lock-time type is not the same; or ** the top stack item is greater than the transaction input sequence (when masked according to the BIP68);

8. ↩ a b c Test vector This chapter's opcode figure uses 12 of 51 one-input CLTV/CSV transactions from Bitcoin Core's own transaction tests (v29.0, pinned excerpt); for all 51 the site's model gives the same verdict Core's tests expect, and the build fails otherwise. The cases and their labels are in sources/external/core-locktime-cases-excerpt.json, pinned by commit and SHA-256; the BIP line cited is the reference implementation those tests accompany.

   BIP 112 L340–342

   Quoted source text (1)

   A reference implementation is provided by the following pull request: https://github.com/bitcoin/bitcoin/pull/7524

9. ↩ a b c Observed nLockTime is read either as a block height or as a time, depending on whether it is below LOCKTIME_THRESHOLD; Bitcoin Core's script.h (pinned excerpt, v29.0) defines that threshold as 500,000,000, a Unix time in November 1985. (The value rests on the pinned script.h lines in sources/external/core-locktime-cases-excerpt.json and a test that checks the model's constant against them.)

   BIP 65 L241–243

   Quoted source text (1)

   // There are two types of nLockTime: lock-by-blockheight // and lock-by-blocktime, distinguished by whether // nLockTime < LOCKTIME_THRESHOLD.

10. ↩ a b c Rule Bit 22 chooses the unit: set means 512-second units counted from the median time past of the coin's previous block, clear means blocks.

    BIP 68 L36

    Quoted source text (1)

    Bit (1 << 22) determines if the relative lock-time is time-based or block based: If the bit is set, the relative lock-time specifies a timespan in units of 512 seconds granularity. The timespan starts from the median-time-past of the output’s previous block, and ends at the MTP of the previous block. If the bit is not set, the relative lock-time specifies a number of blocks.

11. ↩ a b Rule BIP 68's encoding examples: up to 65,535 blocks (about 1.25 years), or a time under 33,554,431 seconds (about 1.06 years) encoded as (1 << 22) | (nTime >> 9).

    BIP 68 L243–249

    Quoted source text (1)

    0 <= nHeight <= 65,535 blocks (1.25 years) nSequence = nHeight; nHeight = nSequence & 0x0000ffff; // 0 <= nTime < 33,554,431 seconds (1.06 years) nSequence = (1 << 22) | (nTime >> 9);

12. ↩ Rule nLockTime keeps a transaction from being mined until a given block height or block time.

    BIP 65 L33–34

    Quoted source text (1)

    The nLockTime field in a transaction prevents the transaction from being mined until either a certain block height, or block time, has been reached.

13. ↩ Rule A transaction is excluded from a block while the height (or time) is less than or equal to its nLockTime, so nLockTime names the last height or time at which it may not be mined.

    BIP 113 L24–26

    Quoted source text (1)

    At present, transactions are excluded from inclusion in a block if the present time or block height is less than or equal to that specified in the locktime.

14. ↩ Author’s rationale BIP 65's motivation: nLockTime can show a spend is possible later, but cannot show the output is unspendable until then, because another valid signed transaction spending it may exist.

    BIP 65 L43–50 BIP 65 L47–50

    Quoted source text (2)

    The nLockTime field in transactions can be used to prove that it is ''possible'' to spend a transaction output in the future, by constructing a valid transaction spending that output with the nLockTime field set.

    However, the nLockTime field can't prove that it is ''impossible'' to spend a transaction output until some time in the future, as there is no way to know if a valid signature for a different transaction spending that output has been created.

15. ↩ a b c Rule If every input's nSequence is the maximum value (0xffffffff), nLockTime is not enforced.

    BIP 65 L259–263 BIP 68 L67–69

    Quoted source text (2)

    // Finally the nLockTime feature can be disabled and thus // CHECKLOCKTIMEVERIFY bypassed if every txin has been // finalized by setting nSequence to maxint.

    Setting nSequence to this value for every input in a transaction * disables nLockTime. */ static const uint32_t SEQUENCE_FINAL = 0xffffffff;

16. ↩ a b Test vector Read by this site's model, BIP 143's native P2WPKH example has version 1, nLockTime 17 and one non-final input, so no block below height 18 can include it; BIP 174's signed legacy transaction has version 2 and nLockTime 1,257,139 with a non-final input; BIP 174's final transaction has nLockTime 0 and only final inputs.

    BIP 143 L184 BIP 174 L619 BIP 174 L833

    Quoted source text (3)

    nLockTime: 11000000

    0200000001268171371edff285e937adeea4b37b78000c0566cbb3ad64641713ca42171bf6

    0200000000010258e87a21b56daf0c23be8e7070456c336f7cbaa5c8757924f545887bb2abdd75

17. ↩ a b c Rule BIP 68 gives nSequence meaning only in transactions with nVersion 2 or more.

    BIP 68 L26

    Quoted source text (1)

    This specification defines the meaning of sequence numbers for transactions with an nVersion greater than or equal to 2

18. ↩ a b c Rule If bit 31 is set, nSequence has no consensus meaning; if it is clear, the field is an encoded relative lock-time.

    BIP 68 L30–32

    Quoted source text (1)

    If bit (1 << 31) of the sequence number is set, then no consensus meaning is applied to the sequence number and can be included in any block under all currently possible circumstances. If bit (1 << 31) of the sequence number is not set, then the sequence number is interpreted as an encoded relative lock-time.

19. ↩ a b Author’s rationale By comparing its argument with nLockTime, the opcode indirectly verifies that the height or time has been reached; the BIP credits Gregory Maxwell with suggesting the comparison against nLockTime rather than the chain.

    BIP 65 L34–38 BIP 65 L306–308

    Quoted source text (2)

    By comparing the argument to CHECKLOCKTIMEVERIFY against the nLockTime field, we indirectly verify that the desired block height or block time has been reached; until that block height or block time has been reached the transaction output remains unspendable.

    Thanks goes to Gregory Maxwell for suggesting that the argument be compared against the per-transaction nLockTime, rather than the current block height and time.

20. ↩ a b c Rule An argument with the disable flag set makes CHECKSEQUENCEVERIFY behave as a NOP, kept for future soft-fork extensibility.

    BIP 112 L279–283

    Quoted source text (1)

    // To provide for future soft-fork extensibility, if the // operand has the disabled lock-time flag set, // CHECKSEQUENCEVERIFY behaves as a NOP.

21. ↩ Author’s rationale The argument may be a 5-byte number so that, like the 32-bit nLockTime field, it lasts until 2106 rather than hitting a year-2038 limit.

    BIP 65 L225–232

    Quoted source text (1)

    // If we kept to that limit we'd have a year 2038 problem, // even though the nLockTime field in transactions // themselves is uint32 which only becomes meaningless // after the year 2106.

22. ↩ Author’s rationale BIP 65's example of frozen funds: <expiry time> CHECKLOCKTIMEVERIFY DROP followed by an ordinary pay-to-public-key-hash check, which nobody can spend before the expiry.

    BIP 65 L183–187 BIP 65 L187

    Quoted source text (2)

    With the following scriptPubKey, nobody will be able to spend the encumbered output until the provided expiry time.

    <expiry time> CHECKLOCKTIMEVERIFY DROP DUP HASH160 <pubKeyHash> EQUALVERIFY CHECKSIG

23. ↩ a b Rule A relative lock n allows inclusion n blocks, or 512 × n seconds, after the output being spent was mined.

    BIP 68 L51 BIP 68 L46

    Quoted source text (2)

    More generally, a relative block lock-time n can be included n blocks after the mining date of the output it is spending, or any block thereafter.

    More generally, a relative time-based lock-time n can be included into any block produced 512 * n seconds after the mining date of the output it is spending

24. ↩ Rule Only 16 bits are interpreted: a 0x0000ffff mask MUST be applied, leaving the other bits for future expansion.

    BIP 68 L40 BIP 68 L236–238

    Quoted source text (2)

    This specification only interprets 16 bits of the sequence number as relative lock-time, so a mask of 0x0000ffff MUST be applied to the sequence field to extract the relative lock-time. The 16-bit specification allows for a year of relative lock-time and the remaining bits allow for future expansion.

    Additionally, this BIP specifies only 16 bits to actually encode relative lock-time meaning a further 6 are unused (1 << 16 through 1 << 21 inclusive).

25. ↩ Author’s rationale The authors chose 512-second granularity because blocks come every 600 seconds on average, so either unit covers about the same span with the same bits.

    BIP 68 L44

    Quoted source text (1)

    For time based relative lock-time, 512 second granularity was chosen because bitcoin blocks are generated every 600 seconds. So when using block-based or time-based, the same amount of time can be encoded with the available number of bits.

26. ↩ Rule The rules do not apply to the coinbase input's nSequence.

    BIP 68 L53

    Quoted source text (1)

    The new rules are not applied to the nSequence field of the input of the coinbase transaction.

27. ↩ Author’s rationale BIP 112's escrow example: a 2-of-3 branch any time, or Alice alone after 30 days; the clock starts only when the payment to the escrow confirms.

    BIP 112 L59–61 BIP 112 L70–76

    Quoted source text (2)

    An escrow that times out automatically 30 days after being funded can be established in the following way. Alice, Bob and Escrow create a 2-of-3 address with the following redeemscript.

    At any time funds can be spent using signatures from any two of Alice, Bob or the Escrow. After 30 days Alice can sign alone. The clock does not start ticking until the payment to the escrow address confirms.

28. ↩ Author’s rationale BIP 112 argues relative locks suit payment channels: the clock starts when a transaction confirms, giving a predictable time to respond, while an absolute deadline forces channels to close before it.

    BIP 112 L105–111

    Quoted source text (1)

    Scriptable relative locktime provides a predictable amount of time to respond in the event a counterparty broadcasts a revoked transaction: Absolute locktime necessitates closing the channel and reopen it when getting close to the timeout, whereas with relative locktime, the clock starts ticking the moment the transactions confirms in a block.

29. ↩ Author’s rationale The authors' reason: block timestamps are not strictly ordered, so miners had an incentive to lie about time to include not-yet-mature transactions and collect their fees.

    BIP 113 L24–30

    Quoted source text (1)

    At present, transactions are excluded from inclusion in a block if the present time or block height is less than or equal to that specified in the locktime. Since the consensus rules do not mandate strict ordering of block timestamps, this has the unfortunate outcome of creating a perverse incentive for miners to lie about the time of their blocks in order to collect more fees by including transactions that by wall clock determination have not yet matured.

30. ↩ Rule BIP 113's rule applies to all transactions, including the coinbase.

    BIP 113 L69

    Quoted source text (1)

    The new rule applies to all transactions, including the coinbase transaction.

31. ↩ Author’s rationale The authors expected transactions using time-based lock-time to confirm about an hour later than under the old rules.

    BIP 113 L101–103

    Quoted source text (1)

    Transactions generated using time-based lock-time will take approximately an hour longer to confirm than would be expected under the old rules.

32. ↩ History BIP 65 activated by the IsSuperMajority mechanism for version-4 blocks: enforced when 750 of the previous 1,000 blocks signalled, and lower versions rejected at 950.

    BIP 65 L281–287

    Quoted source text (1)

    The new rules are in effect for every block (at height H) with nVersion = 4 and at least 750 out of 1000 blocks preceding it (with heights H-1000..H-1) also have nVersion >= 4. Furthermore, when 950 out of the 1000 blocks preceding a block do have nVersion >= 4, nVersion < 4 blocks become invalid

33. ↩ History BIPs 68, 112 and 113 were to deploy together through BIP 9 using bit 0, with a mainnet start time of midnight 1 May 2016 UTC.

    BIP 68 L224–226 BIP 112 L353

    Quoted source text (2)

    This BIP is to be deployed by "versionbits" BIP9 using bit 0. For Bitcoin '''mainnet''', the BIP9 '''starttime''' will be midnight 1st May 2016 UTC

    This BIP must be deployed simultaneously with BIP68 and BIP113 using the same deployment mechanism.