mirror of
https://github.com/bitcoin/bips.git
synced 2024-11-19 01:40:05 +01:00
266 lines
10 KiB
Plaintext
266 lines
10 KiB
Plaintext
<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 nSequence field of the transaction
|
|
input containing the scriptSig. If it is greater than or equal to (1 << 31),
|
|
or if the transaction version is greater than or equal to 2, the transaction
|
|
sequence is less than or equal to (1 << 31) and the top stack item is less than
|
|
the transaction sequence, script exection continues as if a NOP was executed,
|
|
otherwise the script fails.
|
|
|
|
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.
|
|
|
|
===Examples===
|
|
|
|
====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.
|
|
|
|
|
|
====Payment Channel Revokation====
|
|
|
|
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. It also provides a means to know exactly how
|
|
long to wait (in number of blocks) before funds can be pulled out of the channel
|
|
in the event of a noncooperative counterparty.
|
|
|
|
|
|
====Hash Time-Locked Contracts====
|
|
|
|
Hashed Timelock Contracts (HTLCs) can be used to create chains of payments which
|
|
is required for lightning network payment channels. The scheme requires both
|
|
CHECKSEQUENCEVERIFY and CHECKLOCKTIMEVERIFY to enforce HTLC timeouts and
|
|
revokation.
|
|
|
|
|
|
==Specification==
|
|
|
|
Refer to the reference implementation, reproduced below, for the precise
|
|
semantics and detailed rationale for those semantics.
|
|
|
|
|
|
/* Threshold for nSequence: below this value it is interpreted
|
|
* as a relative lock-time, otherwise ignored. */
|
|
static const uint32_t SEQUENCE_LOCKTIME_THRESHOLD = (1 << 31);
|
|
|
|
/* Threshold for nSequence when interpreted as a relative
|
|
* lock-time: below this value it has units of blocks, otherwise
|
|
* seconds. */
|
|
static const uint32_t SEQUENCE_UNITS_THRESHOLD = (1 << 30);
|
|
|
|
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 elsewhere numeric opcodes are limited to
|
|
// operands in the range -2**31+1 to 2**31-1, however it is
|
|
// legal for opcodes to produce results exceeding that
|
|
// range. This limitation is implemented by CScriptNum's
|
|
// default 4-byte limit.
|
|
//
|
|
// 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.
|
|
//
|
|
// Thus as a special case we tell CScriptNum to accept up
|
|
// to 5-byte bignums, which are good until 2**39-1, well
|
|
// beyond the 2**32-1 limit of the nLockTime field itself.
|
|
const CScriptNum nSequence(stacktop(-1), fRequireMinimal, 5);
|
|
|
|
// 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 (nSequence < 0)
|
|
return set_error(serror, SCRIPT_ERR_NEGATIVE_LOCKTIME);
|
|
|
|
// To provide for future soft-fork extensibility, if the
|
|
// operand is too large to be treated as a relative lock-
|
|
// time, CHECKSEQUENCEVERIFY behaves as a NOP.
|
|
if (nSequence >= SEQUENCE_LOCKTIME_THRESHOLD)
|
|
break;
|
|
|
|
// Actually compare the specified sequence number with the input.
|
|
if (!CheckSequence(nSequence))
|
|
return set_error(serror, SCRIPT_ERR_UNSATISFIED_LOCKTIME);
|
|
|
|
break;
|
|
}
|
|
|
|
bool CheckSequence(const CScriptNum& nSequence) const
|
|
{
|
|
// Relative lock times are supported by comparing the passed
|
|
// in operand to the sequence number of the input.
|
|
const int64_t txToSequence = (int64_t)txTo->vin[nIn].nSequence;
|
|
|
|
// Fail if the transaction's version number is not set high
|
|
// enough to trigger BIP 68 rules.
|
|
if (static_cast<uint32_t>(txTo->nVersion) < 2)
|
|
return false;
|
|
|
|
// Sequence numbers above SEQUENCE_LOCKTIME_THRESHOLD
|
|
// are not consensus constrained. Testing that the transaction's
|
|
// sequence number is not above this threshold prevents
|
|
// using this property to get around a CHECKSEQUENCEVERIFY
|
|
// check.
|
|
if (txToSequence >= SEQUENCE_LOCKTIME_THRESHOLD)
|
|
return false;
|
|
|
|
// There are two kinds of nSequence: lock-by-blockheight
|
|
// and lock-by-blocktime, distinguished by whether
|
|
// nSequence < SEQUENCE_UNITS_THRESHOLD.
|
|
//
|
|
// We want to compare apples to apples, so fail the script
|
|
// unless the type of nSequence being tested is the same as
|
|
// the nSequence in the transaction.
|
|
if (!(
|
|
(txToSequence < SEQUENCE_UNITS_THRESHOLD && nSequence < SEQUENCE_UNITS_THRESHOLD) ||
|
|
(txToSequence >= SEQUENCE_UNITS_THRESHOLD && nSequence >= SEQUENCE_UNITS_THRESHOLD)
|
|
))
|
|
return false;
|
|
|
|
// Now that we know we're comparing apples-to-apples, the
|
|
// comparison is a simple numeric one.
|
|
if (nSequence > txToSequence)
|
|
return false;
|
|
|
|
return true;
|
|
}
|
|
|
|
|
|
==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 = 4. 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 = 3 blocks become
|
|
invalid, and all further blocks enforce the new rules.
|
|
|
|
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==
|
|
|
|
[https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki BIP 68] Consensus-enforced transaction replacement signalled via sequence numbers
|
|
|
|
[https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki BIP 65] OP_CHECKLOCKTIMEVERIFY
|
|
|
|
[https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki BIP 113] Median past block time for time-lock constraints
|
|
|
|
[http://lists.linuxfoundation.org/pipermail/lightning-dev/2015-July/000021.html HTLCs using OP_CHECKSEQUENCEVERIFY/OP_LOCKTIMEVERIFY and revocation hashes]
|
|
|
|
[http://lightning.network/lightning-network-paper.pdf Lightning Network]
|
|
|
|
[http://diyhpl.us/diyhpluswiki/transcripts/sf-bitcoin-meetup/2015-02-23-scaling-bitcoin-to-billions-of-transactions-per-day/ Scaling Bitcoin to Billions of Transactions Per Day]
|
|
|
|
[http://lists.linuxfoundation.org/pipermail/bitcoin-dev/2015-August/010396.html Softfork deployment considerations]
|
|
|
|
[https://gist.github.com/sipa/bf69659f43e763540550 Version bits]
|
|
|
|
[https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2013-April/002433.html Jeremy Spilman Micropayment Channels]
|
|
|
|
|
|
==Copyright==
|
|
|
|
This document is placed in the public domain.
|
|
|