diff options
Diffstat (limited to 'bip-0112.mediawiki')
| -rw-r--r-- | bip-0112.mediawiki | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/bip-0112.mediawiki b/bip-0112.mediawiki new file mode 100644 index 0000000..c06caf5 --- /dev/null +++ b/bip-0112.mediawiki @@ -0,0 +1,246 @@ +<pre> + BIP: 112 + Title: CHECKSEQUENCEVERIFY + Authors: BtcDrak <btcdrak@gmail.com> + Mark Friedenbach <mark@friedenbach.org> + Status: Draft + Type: Standards Track + Created: 2015-08-10 +</pre> + +==Abstract== + +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. + + +==Summary== + +CHECKSEQUENCEVERIFY redefines the existing NOP3 opcode. When executed +it compares the top item on the stack to the inverse of the nSequence +field of the transaction input containing the scriptSig. If the +inverse of nSequence is less than the sequence threshold (1 << 31), +the transaction version is greater than or equal to 2, and the top +item on the stack is less than or equal to the inverted nSequence, +script evaluation continues as though a NOP was executed. Otherwise +the script fails immediately. + +BIP 68's redefinition of nSequence prevents a non-final transaction +from being selected for inclusion in a block until the corresponding +input has reached the specified age, as measured in block height or +block time. By comparing the argument to CHECKSEQUENCEVERIFY against +the nSequence field, we indirectly verify a desired minimum age of the +the output being spent; until that relative age has been reached any +script execution pathway including the CHECKSEQUENCEVERIFY will fail +to validate, causing the transaction not to be selected for inclusion +in a block. + + +==Motivation== + +BIP 68 repurposes the transaction nSequence field meaning by giving +sequence numbers new consensus-enforced semantics as a relative +lock-time. However, there is no way to build Bitcoin scripts to make +decisions based on this field. + +By making the nSequence field accessible to script, it becomes +possible to construct code pathways that only become accessible some +minimum time after proof-of-publication. This enables a wide variety +of applications in phased protocols such as escrow, payment channels, +or bidirectional pegs. + + +==Specification== + +Refer to the reference implementation, reproduced below, for the precise +semantics and detailed rationale for those semantics. + + + // Threshold for nLockTime: below this value it is interpreted as block number, + // otherwise as UNIX timestamp (already defined in Bitcoin Core). + static const unsigned int LOCKTIME_THRESHOLD = 500000000; // Tue Nov 5 00:53:20 1985 UTC + + // Threshold for inverted nSequence: below this value it is interpreted + // as a relative lock-time, otherwise ignored. + static const uint32_t SEQUENCE_THRESHOLD = (1 << 31); + + case OP_NOP3: + { + if (!(flags & SCRIPT_VERIFY_CHECKSEQUENCEVERIFY)) { + // not enabled; treat as a NOP3 + if (flags & SCRIPT_VERIFY_DISCOURAGE_UPGRADABLE_NOPS) { + return set_error(serror, SCRIPT_ERR_DISCOURAGE_UPGRADABLE_NOPS); + } + break; + } + + if (stack.size() < 1) + return set_error(serror, SCRIPT_ERR_INVALID_STACK_OPERATION); + + // Note that unlike CHECKLOCKTIMEVERIFY we do not need to + // accept 5-byte bignums since any value greater than or + // equal to SEQUENCE_THRESHOLD (= 1 << 31) will be rejected + // anyway. This limitation just happens to coincide with + // CScriptNum's default 4-byte limit with an explicit sign + // bit. + // + // This means there is a maximum relative lock time of 52 + // years, even though the nSequence field in transactions + // themselves is uint32_t and could allow a relative lock + // time of up to 120 years. + const CScriptNum nInvSequence(stacktop(-1), fRequireMinimal); + + // In the rare event that the argument may be < 0 due to + // some arithmetic being done first, you can always use + // 0 MAX CHECKSEQUENCEVERIFY. + if (nInvSequence < 0) + return set_error(serror, SCRIPT_ERR_NEGATIVE_LOCKTIME); + + // Actually compare the specified inverse sequence number + // with the input. + if (!CheckSequence(nInvSequence)) + return set_error(serror, SCRIPT_ERR_UNSATISFIED_LOCKTIME); + + break; + } + + bool CheckSequence(const CScriptNum& nInvSequence) const + { + int64_t txToInvSequence; + + // Fail under all circumstances if the transaction's version + // number is not set high enough to enable enforced sequence + // number rules. + if (txTo->nVersion < 2) + return false; + + // Sequence number must be inverted to convert it into a + // relative lock-time. + txToInvSequence = (int64_t)~txTo->vin[nIn].nSequence; + + // Sequence numbers under SEQUENCE_THRESHOLD are not consensus + // constrained. + if (txToInvSequence >= SEQUENCE_THRESHOLD) + return false; + + // There are two types of relative lock-time: lock-by- + // blockheight and lock-by-blocktime, distinguished by + // whether txToInvSequence < LOCKTIME_THRESHOLD. + // + // We want to compare apples to apples, so fail the script + // unless the type of lock-time being tested is the same as + // the lock-time in the transaction input. + if (!( + (txToInvSequence < LOCKTIME_THRESHOLD && nInvSequence < LOCKTIME_THRESHOLD) || + (txToInvSequence >= LOCKTIME_THRESHOLD && nInvSequence >= LOCKTIME_THRESHOLD) + )) + return false; + + // Now that we know we're comparing apples-to-apples, the + // comparison is a simple numeric one. + if (nInvSequence > txToInvSequence) + return false; + + return true; + } + +https://github.com/maaku/bitcoin/commit/33be476a60fcc2afbe6be0ca7b93a84209173eb2 + + +==Example: Escrow with Timeout== + +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. + + IF + 2 <Alice's pubkey> <Bob's pubkey> <Escrow's pubkey> 3 CHECKMULTISIGVERIFY + ELSE + <LOCKTIME_THRESHOLD + 30*24*60*60> CHECKSEQUENCEVERIFY DROP + <Alice's pubkey> CHECKSIGVERIFY + ENDIF + +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. + + +==Reference Implementation== + +A reference implementation is provided in the following git repository: + +https://github.com/maaku/bitcoin/tree/checksequenceverify + + +==Deployment== + +We reuse the double-threshold switchover mechanism from BIPs 34 and +66, with the same thresholds, but for nVersion = 8. The new rules are +in effect for every block (at height H) with nVersion = 8 and at least +750 out of 1000 blocks preceding it (with heights H-1000..H-1) also +have nVersion = 8. Furthermore, when 950 out of the 1000 blocks +preceding a block do have nVersion = 8, nVersion = 3 blocks become +invalid, and all further blocks enforce the new rules. + +When assessing the block version as mask of ~0x20000007 must be applied +to work around the complications caused by +[http://lists.linuxfoundation.org/pipermail/bitcoin-dev/2015-August/010396.html BIP101's premature use] +of the [https://gist.github.com/sipa/bf69659f43e763540550 undecided version bits proposal]. + +By applying ~0x20000007 with nVersion = 8, the thresholds should be tested +comparing block nVersion >= 4 as this will save a bit for future use. + +It is recommended that this soft-fork deployment trigger include other +related proposals for improving Bitcoin's lock-time capabilities, including: + +[https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki BIP 65]: +OP_CHECKLOCKTIMEVERIFY, + +[https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki BIP 68]: +Consensus-enforced transaction replacement signalled via sequence numbers, + +and [https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki BIP 113]: +Median-Past-Time-Lock. + +==Credits== + +Mark Friedenbach invented the application of sequence numbers to +achieve relative lock-time, and wrote the reference implementation of +CHECKSEQUENCEVERIFY. + +The reference implementation and this BIP was based heavily on work +done by Peter Todd for the closely related BIP 65. + +BtcDrak authored this BIP document. + + +==References== + +BIP 68: Consensus-enforced transaction replacement signalled via +sequence numbers +https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki + +BIP 65: OP_CHECKLOCKTIMEVERIFY +https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki + +BIP 113: Median past block time for time-lock constraints +https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki + +HTLCs using OP_CHECKSEQUENCEVERIFY/OP_LOCKTIMEVERIFY and +revocation hashes +http://lists.linuxfoundation.org/pipermail/lightning-dev/2015-July/000021.html + +[http://lists.linuxfoundation.org/pipermail/bitcoin-dev/2015-August/010396.html Softfork deployment considerations] + +[https://gist.github.com/sipa/bf69659f43e763540550 Version bits] + + +==Copyright== + +This document is placed in the public domain. |