This page is the Simplified Technical English version of ZIP 68. The source ZIP is the normative text. Read the writing rules to understand the marked words.
ZIP 68: Relative lock-time using consensus-enforced sequence numbers
ZIP: 68
Title: Relative lock-time using consensus-enforced sequence numbers
Owners: Daira-Emma Hopwood <daira@jacaranda.org>
Credits: Mark Friedenbach
BtcDrak
Nicolas Dorier
kinoshitajona
Category: Consensus
Status: Draft
Created: 2016-06-06
Terminology
On this page, STE words are in the place of the BCP 14 key words of the source. Refer to the key word table.
In this document, the "Median Time Past" of a block has the meaning that is described in [zip-0113].
Abstract
This ZIP contains new consensus-enforced semantics of relative lock-time (RLT) for the sequence number field. With these semantics, a signed transaction input can stay invalid for a defined period of time after the confirmation of its corresponding outpoint.
Motivation
Zcash transactions have a sequence number field for each input. This field is from Bitcoin.
It seems that the original idea in Bitcoin was as follows. A transaction in the mempool was to be replaced by a transaction that uses the same input with a higher sequence value.
This idea was not correctly implemented. Also, the idea depends on an assumption: miners prefer the higher sequence numbers, even if the lower sequence numbers are more profitable to mine. But a miner that acts only for profit breaks that assumption completely.
With the change in this ZIP, the sequence number has new use cases. The existing functionality stays the same. With the change, there is also space for future expansion and for other use cases.
The transaction nLockTime is used to prevent the mining of a transaction until a certain date. nSequence will be used for a new purpose: to prevent the mining of a transaction until the spent output has a certain age. This age is a number of blocks or a timespan.
With this new purpose, among other uses, bi-directional payment channels are possible. These channels are used in [deployable-lightning] and [zip-0112].
Specification
This specification contains the meaning of sequence numbers for transactions in blocks after the activation of this ZIP.
If bit (1 << 31) of the sequence number is set, no consensus meaning applies to the sequence number. In this case, the input can be included in any block in all circumstances that are possible at this time.
If bit (1 << 31) of the sequence number is not set, the sequence number is interpreted as an encoded relative lock-time.
The sequence number encoding must be interpreted as follows:
The type of the relative lock-time depends on bit (1 << 22). The type is time-based or block-based.
- If the bit is set, the relative lock-time is a timespan in units of 32 seconds granularity. The timespan starts at the Median Time Past of the previous block of the output. The timespan ends at the Median Time Past of the previous block.
- If the bit is not set, the relative lock-time is a number of blocks.
Note: The time unit of 64 seconds is different from the time unit of Bitcoin's BIP 68. The time unit of BIP 68 is 512 seconds.
The flag (1 << 22) is the highest-order bit in a 3-byte signed integer. This integer is for use in Zcash scripts as a 3-byte PUSHDATA with OP_CHECKSEQUENCEVERIFY [zip-0112].
In this specification, only 22 bits of the sequence number are interpreted as relative lock-time. Thus, to get the relative lock-time, a mask of 0x003FFFFF must be applied to the sequence field. With the 22-bit specification, a relative lock-time can be more than 8.5 years.
For time-based relative lock-time, a granularity of 64 seconds was selected. The reason is that the target block spacing for Zcash after activation of the Blossom network upgrade is 75 seconds. Thus, with the available number of bits, approximately the same amount of time can be encoded with block-based or time-based lock-time. To convert a sequence number to seconds, multiply it by 64.
When the relative lock-time is time-based, it is interpreted as a minimum block-time constraint over the age of the input. If the relative time-based lock-time of an input is zero, the input can be included in any block. More generally, an input with a relative time-based lock-time n can be included in these blocks:
- Any block produced 64 * n seconds after the mining date of the output that the input spends.
- Any block after that block.
The mining date of the output is equal to the Median Time Past of the previous block of the block that includes the output.
The produced time of a block is equal to the Median Time Past of its previous block.
When the relative lock-time is block-based, it is interpreted as a minimum block-height constraint over the age of the input. If the relative block-based lock-time of an input is zero, the input can be included in any block. More generally, an input with a relative block lock-time n can be included in these blocks:
- A block n blocks after the mining date of the output that the input spends.
- Any block after that block.
The new rules do not apply to the nSequence field of the input of the coinbase transaction.
Reference Implementation
enum {
/* Interpret sequence numbers as relative lock-time constraints. */
LOCKTIME_VERIFY_SEQUENCE = (1 << 0),
};
/* Setting nSequence to this value for every input in a transaction
* disables nLockTime. */
static const uint32_t SEQUENCE_FINAL = 0xffffffff;
/* Below flags apply in the context of ZIP 68. */
/* If this flag set, CTxIn::nSequence is NOT interpreted as a
* relative lock-time. */
static const uint32_t SEQUENCE_LOCKTIME_DISABLE_FLAG = (1 << 31);
/* If CTxIn::nSequence encodes a relative lock-time and this flag
* is set, the relative lock-time has units of 512 seconds,
* otherwise it specifies blocks with a granularity of 1. */
static const uint32_t SEQUENCE_LOCKTIME_TYPE_FLAG = (1 << 22);
/* If CTxIn::nSequence encodes a relative lock-time, this mask is
* applied to extract that lock-time from the sequence field. */
static const uint32_t SEQUENCE_LOCKTIME_MASK = 0x003fffff;
/* In order to use the same number of bits to encode roughly the
* same wall-clock duration, and because blocks are naturally
* limited to occur every 75s on average after Blossom activation,
* the minimum granularity for time-based relative lock-time is
* fixed at 64 seconds.
* Converting from CTxIn::nSequence to seconds is performed by
* multiplying by 64, or equivalently shifting up by 6 bits. */
static const int SEQUENCE_LOCKTIME_GRANULARITY = 6;
/**
* Calculates the block height and previous block's Median Time Past at
* which the transaction will be considered final in the context of ZIP 68.
* Also removes from the vector of input heights any entries which did not
* correspond to sequence locked inputs as they do not affect the calculation.
*/
static std::pair<int, int64_t> CalculateSequenceLocks(const CTransaction &tx, int flags, std::vector<int>* prevHeights, const CBlockIndex& block)
{
assert(prevHeights->size() == tx.vin.size());
// Will be set to the equivalent height- and time-based nLockTime
// values that would be necessary to satisfy all relative lock-
// time constraints given our view of block chain history.
// The semantics of nLockTime are the last invalid height/time, so
// use -1 to have the effect of any height or time being valid.
int nMinHeight = -1;
int64_t nMinTime = -1;
// tx.nVersion is signed integer so requires cast to unsigned otherwise
// we would be doing a signed comparison and half the range of nVersion
// wouldn't support ZIP 68.
bool fEnforceZIP68 = static_cast<uint32_t>(tx.nVersion) >= 2
&& flags & LOCKTIME_VERIFY_SEQUENCE;
// Do not enforce sequence numbers as a relative lock time
// unless we have been instructed to
if (!fEnforceZIP68) {
return std::make_pair(nMinHeight, nMinTime);
}
for (size_t txinIndex = 0; txinIndex < tx.vin.size(); txinIndex++) {
const CTxIn& txin = tx.vin[txinIndex];
// Sequence numbers with the most significant bit set are not
// treated as relative lock-times, nor are they given any
// consensus-enforced meaning at this point.
if (txin.nSequence & CTxIn::SEQUENCE_LOCKTIME_DISABLE_FLAG) {
// The height of this input is not relevant for sequence locks
(*prevHeights)[txinIndex] = 0;
continue;
}
int nCoinHeight = (*prevHeights)[txinIndex];
if (txin.nSequence & CTxIn::SEQUENCE_LOCKTIME_TYPE_FLAG) {
int64_t nCoinTime = block.GetAncestor(std::max(nCoinHeight-1, 0))->GetMedianTimePast();
// NOTE: Subtract 1 to maintain nLockTime semantics
// ZIP 68 relative lock times have the semantics of calculating
// the first block or time at which the transaction would be
// valid. When calculating the effective block time or height
// for the entire transaction, we switch to using the
// semantics of nLockTime which is the last invalid block
// time or height. Thus we subtract 1 from the calculated
// time or height.
// Time-based relative lock-times are measured from the
// smallest allowed timestamp of the block containing the
// txout being spent, which is the Median Time Past of the
// block prior.
nMinTime = std::max(nMinTime, nCoinTime + (int64_t)((txin.nSequence & CTxIn::SEQUENCE_LOCKTIME_MASK) << CTxIn::SEQUENCE_LOCKTIME_GRANULARITY) - 1);
} else {
nMinHeight = std::max(nMinHeight, nCoinHeight + (int)(txin.nSequence & CTxIn::SEQUENCE_LOCKTIME_MASK) - 1);
}
}
return std::make_pair(nMinHeight, nMinTime);
}
static bool EvaluateSequenceLocks(const CBlockIndex& block, std::pair<int, int64_t> lockPair)
{
assert(block.pprev);
int64_t nBlockTime = block.pprev->GetMedianTimePast();
if (lockPair.first >= block.nHeight || lockPair.second >= nBlockTime)
return false;
return true;
}
bool SequenceLocks(const CTransaction &tx, int flags, std::vector<int>* prevHeights, const CBlockIndex& block)
{
return EvaluateSequenceLocks(block, CalculateSequenceLocks(tx, flags, prevHeights, block));
}
bool CheckSequenceLocks(const CTransaction &tx, int flags)
{
AssertLockHeld(cs_main);
AssertLockHeld(mempool.cs);
CBlockIndex* tip = chainActive.Tip();
CBlockIndex index;
index.pprev = tip;
// CheckSequenceLocks() uses chainActive.Height()+1 to evaluate
// height based locks because when SequenceLocks() is called within
// ConnectBlock(), the height of the block *being*
// evaluated is what is used.
// Thus if we want to know if a transaction can be part of the
// *next* block, we need to use one more than chainActive.Height()
index.nHeight = tip->nHeight + 1;
// pcoinsTip contains the UTXO set for chainActive.Tip()
CCoinsViewMemPool viewMemPool(pcoinsTip, mempool);
std::vector<int> prevheights;
prevheights.resize(tx.vin.size());
for (size_t txinIndex = 0; txinIndex < tx.vin.size(); txinIndex++) {
const CTxIn& txin = tx.vin[txinIndex];
CCoins coins;
if (!viewMemPool.GetCoins(txin.prevout.hash, coins)) {
return error("%s: Missing input", __func__);
}
if (coins.nHeight == MEMPOOL_HEIGHT) {
// Assume all mempool transaction confirm in the next block
prevheights[txinIndex] = tip->nHeight + 1;
} else {
prevheights[txinIndex] = coins.nHeight;
}
}
std::pair<int, int64_t> lockPair = CalculateSequenceLocks(tx, flags, &prevheights, index);
return EvaluateSequenceLocks(index, lockPair);
}
Acknowledgments
This ZIP is based on BIP 68. These persons are the authors of BIP 68:
- Mark Friedenbach
- BtcDrak
- Nicolas Dorier
- kinoshitajona
Gregory Maxwell gets credit because he gave a short and clear description of the behavior of this change. This description became the basis of the BIP text.
Deployment
At the time of writing, there was no decision about the network upgrade for this ZIP. It is possible that no network upgrade will include this ZIP.
This ZIP is designed for deployment at the same time as [zip-0112] and [zip-0113].
Compatibility
The zcashd reference implementation uses sequence numbers for only one purpose: to disable the check of the nLockTime constraints in a transaction. With this ZIP, the semantics of that use stay the same.
Refer to the Specification section. Some bits have no definition in this ZIP.
The purpose is to make other use cases possible when bit (1 << 31) is set. When bit (1 << 31) is set, the remaining 31 bits have no meaning in this ZIP.
Also, when bit (1 << 31) is not set, bits (1 << 23) through (1 << 30) inclusive have no meaning at all.
In this ZIP, all of the low 22 bits are used for the value. This is different from BIP 68 in Bitcoin. The reason is that blocks are more frequent (75 seconds instead of 600 seconds). Thus more bits are necessary to get approximately the same range of time.
To calculate the sequence number from the relative lock-time, the most efficient method is to use bit masks and shifts:
// 0 <= nHeight <= 4194303 blocks (~10 years at post-Blossom block target spacing) nSequence = nHeight; nHeight = nSequence & 0x003fffff; // 0 <= nTime <= 268435392 seconds (~8.5 years) nSequence = (1 << 22) | (nTime >> 6); nTime = (nSequence & 0x003fffff) << 6;
References
- [RFC2119]
- Key words for use in RFCs to Indicate Requirement Levels
- [mailing-list]
- Bitcoin mailing list discussion
- [zip-0112]
- ZIP 112: CHECKSEQUENCEVERIFY
- [zip-0113]
- ZIP 113: Median Time Past as endpoint for lock-time calculations
- [deployable-lightning]
- Reaching The Ground With Lightning (draft 0.2)