Zcash in Simplified Technical English

This page is the Simplified Technical English version of ZIP 203. The source ZIP is the normative text. Read the writing rules to understand the marked words.

ZIP 203: Transaction Expiry

ZIP: 203
Title: Transaction Expiry
Owners: Daira-Emma Hopwood <daira@jacaranda.org>
Original-Authors: Jay Graber
Status: Final
Category: Consensus
Created: 2018-01-09
License: MIT

Abstract

This Standards ZIP contains a new consensus rule for an expiry height. A sender can set an expiry height for a transaction. After the expiry height, miners cannot mine the transaction. If the transaction is not in a block at that time, nodes remove it from their mempools.

Motivation

Miners often do not mine transactions that have fees that are too small. The result of such a transaction is uncertain. This uncertainty is a source of confusion for users and wallets. With an expiry height, the time limit for the confirmation of a transaction is certain. After that limit, nodes reject the transaction, and the transaction must be sent again.

The advantages of transaction expiry include:

If the expiry height is \(N\!\), the transaction must be in block \(N\) or an earlier block. Block \(N+1\) is too late, and nodes remove the transaction from the mempool.

The new consensus rule has two effects. The transaction is invalid in a block of height greater than \(N\!\). A block that includes an expired transaction is invalid.

Specification

Transactions have a new field, nExpiryHeight. The value of this field is the expiry height. After the expiry height, nodes remove a transaction from the mempool if it is not in a block.

The data type of nExpiryHeight is uint32_t. An nLockTime value can be a UNIX timestamp. An nExpiryHeight value is never a UNIX timestamp. Thus the maximum expiry height is 499999999. (Coinbase transactions have an exception. Refer to Changes for NU5.)

Note: A previous version of this ZIP had an incorrect specification of an interaction between nExpiryHeight and nLockTime. That interaction was never implemented.

In the example that follows, block 3539 is the last block that can include the transaction. After that block, nodes remove the transaction from the mempool.

"txid": "17561b98cc77cd5a984bb959203e073b5f33cf14cbce90eb32b95ae2c796723f",
"version": 3,
"locktime": 2089,
"expiryheight": 3539,
Default
Before Blossom, the default is 20 blocks from the current height. This is approximately 50 minutes at a target block spacing of 2.5 minutes. The user can set a different default with a configuration option.
Minimum
There is no minimum.
Maximum
499999999. The wall-clock time of this height depends on the target block spacing that applies before the chain is at that height.
No limit
To set no limit on a transaction, set nExpiryHeight to 0. Such a transaction does not expire.
Coinbase
nExpiryHeight on coinbase transactions is ignored. By convention, its value is 0.

When a transaction expires, we recommend that nodes remove it from the mempool. In that case, we recommend that nodes also remove all the transactions that depend on it.

Changes for Blossom

At Blossom activation [zip-0206], the default changes to 40 blocks from the current height. This is still approximately 50 minutes at the new target block spacing of 75 seconds.

Changes for NU5

As stated above, nExpiryHeight is ignored for coinbase transactions. But from NU5 activation [zip-0252], the nExpiryHeight field of a coinbase transaction must be equal to the block height. Also, for coinbase transactions only, the limit of 499999999 on nExpiryHeight is removed. The purpose of these changes is to make sure that transaction IDs stay unique. More detail is in a note in Section 7.1 of the protocol specification [protocol-txnencoding].

Changes for NU7

ZIP 218 [zip-0218] has a recommendation for implementations that create transactions. The recommendation is that, at NU7 activation, these implementations change the default expiry delta from 40 blocks to 120 blocks. This stays approximately 50 minutes at the target block spacing of 25 seconds. A -txexpirydelta value that is set explicitly in the configuration continues to apply before and after activation. The expiry consensus rule and the maximum expiry height stay the same.

Wallet behavior and UI

With this feature, a zero-confirmation transaction that has an expiry height has an even smaller guarantee of inclusion. Thus UIs and services must never depend on zero-confirmation transactions in Zcash.

We recommend that a wallet tells the user about expired transactions. These transactions must be sent again.

RPC

For Overwinter, transaction expiry has a default value. The user can replace the default with the txexpirydelta flag in the config file.

The value of -txexpirydelta= is a number of blocks. After that number of blocks, a transaction that is not in a block becomes invalid.

To see expired transactions, use the new filter attribute of listtransactions. With this attribute, listtransactions shows only expired transactions:

listtransactions "*" 10 0 "expired"

WalletTxToJSON shows a boolean, expired, that is true or false.

Config

The user can set the default with the txexpirydelta option.

--txexpirydelta=100

Deployment

This feature is deployed with Overwinter. The proposal for the activation height is in [zip-0201].

Reference Implementation

https://github.com/zcash/zcash/pull/2874

References

[zip-0201]
ZIP 201: Network Peer Management for Overwinter
[zip-0206]
ZIP 206: Deployment of the Blossom Network Upgrade
[zip-0218]
ZIP 218: 25-second Block Target Spacing
[zip-0252]
ZIP 252: Deployment of the NU5 Network Upgrade
[protocol-txnencoding]
Zcash Protocol Specification, Version 2021.2.16. Section 7.1: Transaction Encoding and Consensus