Nonces

Payment Processor uses two types of nonces to manage orders - master nonces and order nonces. Every order maker on Payment Processor has their own master nonce and set of order nonces.

The master nonce defaults to zero for an order maker and allows the maker to cancel all open orders that were signed using that master nonce by calling revokeMasterNonce on Payment Processor. revokeMasterNonce will increment the maker's master nonce by one and emit a MasterNonceInvalidated event with the order maker's address and the master nonce that was revoked, the maker's new master nonce will be the revoked nonce plus one. Master nonce is part of an order signature and will result in all previously signed orders with that nonce to recover as a different signer and revert.

An order nonce is a 32 byte integer that is used to prevent the replay of orders on Payment Processor and allow for orders to be explicitly cancelled prior to fulfillment by the order maker. When a nonce is consumed by fulfillment or cancellation it cannot be used again.

How are nonces stored?

Order nonces are stored in a bitmap data structure for each order maker where each storage slot is a "bucket" of 256 nonces where nonces 0-255 are in the first bucket, 256-511 are in the second bucket, and so forth. Nonces are packed this way for efficient use of storage within the EVM and to reduce gas costs on transaction execution. At a high level - consuming the first nonce in a bucket costs 20,000 gas units, each additional nonce consumed from the same bucket in the same transaction costs 100 gas units (a 99.5% savings over one slot per nonce or using nonces from different buckets), and an additional nonce consumed from a bucket that previously had a nonce consumed but in a different transaction costs 5,000 gas units (75% saving over one slot per nonce or using nonces from different buckets). Payment Processor does not account for the order book/marketplace in nonce validation - order books must generate nonces for users that will not overlap with nonces created by another order book to prevent fulfilled orders on one order book from interfering with open orders on the other.

What is an ideal nonce?

An ideal nonce for a Payment Processor order will include as many zero bytes in the 32 byte nonce as possible to save calldata gas cost (a zero byte in calldata costs 4 gas units while a non-zero byte costs 16 gas units), pack as many fillable order nonces into a 256 nonce "bucket" as possible, and not overlap with nonces used by other order books. To meet these objectives of an ideal nonce we recommend using the upper 4 bytes of the 32 byte nonce value as a marketplace differentiator and incrementing the nonce used for order signing by one for each marketplace as a user signs an order as a simple method for generating an order nonce.

Example

maker = "0x1234...FFFF"
orderbookDifferentiator = keccak256("YOUR_ORDER_BOOK") << 224 // 0x3cd2fd820000...0000
orderMakerNextOrderbookNonce = getNextNonce(orderbookDifferentiator, maker) // query database for next nonce, for example assume this value is 123
orderNonce = orderbookDifferentiator | orderMakerNextOrderbookNonce // 0x3cd2fd820000..007B

A more advanced solution could track prior nonces used for order signing where another factor on the order, such as expiration time or master nonce revocation, has made a prior order unfillable and re-use those nonces to better pack fulfilled nonces.