Data Structures

The following subsections detail the data structures needed for the creation of and filling of orders in Payment Processor. Note that maker signature formats vary by order-type.

SignatureECDSA

V	R	S
uint8	bytes32	bytes32

• V: The v component of an ECDSA signature.
• R: The r component of an ECDSA signature.
• S: The s component of an ECDSA signature.

Note: For a detailed explanation of ECDSA signatures read this article.

Cosignature

Signer	Taker	Expiration	V	R	S
address	address	uint256	uint8	bytes32	bytes32

• Signer: The co-signer designated and acknowledged in the order maker's signature approving the order. MUST be an EOA, or address(0) when the co-signature is empty. It is expected that marketplaces implementing co-signing MUST expose an API enabling the taker to retrieve a co-signature approving the fill of co-signed orders.
• Taker: The address of the account filling the co-signed order. May be an EOA or Smart Contract account, or address(0) when the co-signature is empty. A marketplace's co-signing API service MUST acknowledge the taker address in the co-signature.
• Expiration: The unix timestamp (in seconds) when the co-signature expires, or 0 when the co-signature is empty. A marketplace's co-signing API should use the current unix timestamp and add a validity time that is acknowledged in the co-signature. If the validity time is too short, there might not be sufficient time for the fill transaction to be confirmed on-chain, possibly resulting in failed fill transactions. However, the validity time should also not be too long, as a taker could sit on a fill transaction for quite a while. It is left up to the marketplace to determine an appropriate validity time.
• V: The v component of the co-signer's signature.
• R: The r component of the co-signer's signature.
• S: The s component of the co-signer's signature.

Note: The co-signature is generated when the co-signer creates an ECDSA signature of the Cosignature typed data message.

FeeOnTop

A fee on top is typically reserved for a marketplace or specialized wallet that found the order filled by the taker. This taker marketplace fee is an optional fee paid by the taker in excess of the items' prices in one or more orders. When the maker and taker marketplace is the same, it is strongly encouraged not to apply this fee, as the fee can already be assessed in the maker fee. Note that the fee on top is paid in the same currency as the order's payment method.

Recipient	Amount
address	uint256

• Recipient: The address to which the fee is paid, or address(0) when the fee is empty.
• Amount: The absolute amount of the fee, in wei, or 0 when the fee is empty. Note that the fee amount is not permitted to exceed the item sale price of any given order.

TokenSetProof

Token set proofs are required to fill token set offers on a collection. A token set offer is a merkle tree where the leaf data is the keccak256 hash of the collection address and token id.

leafHash = keccak256(abi.encode(collectionAddress, tokenId));

Root Hash	Proof
bytes32	bytes32[]

• Root Hash: The root hash of the merkle tree containing 2 or more collection/token id leaf nodes, or bytes32(0) when the order being filled is not a token set offer.
• Proof: The merkle proof for the specific collection/token id leaf node being filled, , or bytes32[](0) when the order being filled is not a token set offer.

Order

This data structure is used to fill all single and bulk orders that are not sweep orders.

Protocol	Maker	Beneficiary	Marketplace	Fallback Royalty Recipient	Payment Method	Token Address	Token Id	Amount	Item Price	Nonce	Expiration	Marketplace Fee Numerator	Max Royalty Fee Numerator	Requested Fill Amount	Minimum Fill Amount
uint8	address	address	address	address	address	address	uint256	uint248	uint256	uint256	uint256	uint256	uint256	uint248	uint248

• Protocol: 0 for ERC721_FILL_OR_KILL, 1 for ERC1155_FILL_OR_KILL, or 2 for ERC1155_FILL_PARTIAL collections. FILL_PARTIAL means an order is partially fillable across multiple trades, while FILL_OR_KILL means the entire amount specified in the order must be filled in a single transaction.
• Maker: The address of the account the created the order. May be an EOA or Smart Contract account. When the order was a listing, the maker is the seller of the item. When the order was an offer, the maker is the buyer of the item.
• Beneficiary: The address of the account that receives the item when the order is filled. When the order was a listing, the taker (msg.sender) can either buy with themselves as the beneficiary, or another account. When the order was an offer, the maker would be the buyer, and the beneficiary address can either be the maker's account or another account. For example, the buyer could be a user's hot wallet, and the beneficiary could be the user's cold storage wallet.
• Marketplace: The address to which the primary (maker) marketplace fee should be paid, or address(0) if the maker marketplace charges no platform fees. Note that for collections that offer non-exclusive royalty bounties, the maker marketplace also receives a royalty bounty paid out of creator royalties. For collections that offer exclusive royalty bounties, the maker marketplace receives a royalty bounty only if it matches the exclusive royalty bounty recipient designated by the collection creator.
• Fallback Royalty Recipient: Used to allow marketplaces to support royalties for collections that do not implement ERC-2981, do not have a contract owner and do not have a user with default admin role. Fallback royalties are calculated using the Max Royalty Fee Numerator for the order.
• Payment Method: The address of the ERC-20 coin used to fill the trade, or address(0) for the native currency of the chain the trade executed on. For example, address(0) denotes ETH on ETH Mainnet, and Matic on Polygon Mainnet.
• Token Address: The address of the collection.
• Token Id: The id of the token (if collection is ERC721), or the token type id of the token (if collection is ERC1155).
• Amount: The number of tokens. MUST be 1 if collection is ERC721, and MUST be greater than or equal to 1 if collection is ERC1155.
• Item Price: The price of the token(s) in the order.
• Nonce: A unique identifier to the order that prevents replay attacks. Nonce applies only to standard signed orders and may not be re-used. For co-signed order, nonce should be set to 0. Note: It is easier to generate a random nonce than attempt to keep track of nonces that have been used. However, be aware that a gas optimization is in place such that filled or cancelled nonces are tracked in a bitmap. Nonces 0-255, 256-511, 512-767, etc are stored in the same slot. Each maker address has its own set of nonces generated for gasless listings such that nonce 1234 is stored separately for makers address(5678) and address(abcd) but storage of the same nonce for the same maker is common across all marketplaces. It is possible that marketplaces will have no knowledge of nonces used in outstanding order signatures. Marketplaces should employ a nonce sequencing methodology that reduces the probability of overlapping nonce usage with other marketplaces. Examples of this could be a fixed set of upper bits for all orders placed through that marketplace where nonces 0x12340000...0000 to 0x1234FFFF...FFFF relate to a specific marketplace or the development of a common nonce issuance service that tracks all nonces used by a maker.
• Expiration: The unix timestamp (in seconds) when the maker's order signature expires. A marketplace's order making API should use the current unix timestamp and add a user-defined validity time that is acknowledged in the maker's signature.
• Marketplace Fee Numerator: Marketplace fee percentage in bips. Should be in range 0-10,000, as denominator is 10,000. 0.5% fee numerator is 50, 1% fee numerator is 100, 10% fee numerator is 1,000 and so on.
• Max Royalty Fee Numerator: Maximum approved royalty fee percentage in bips. Should be in range 0-10,000, as denominator is 10,000. 0.5% fee numerator is 50, 1% fee numerator is 100, 10% fee numerator is 1,000 and so on. When requesting the order signature from the order maker, the marketplace MUST first attempt to read the royalties for the individual token using the EIP-2981 royaltyInfo function call on the collection. If royaltyInfo raises an exception (likely because it is unimplemented), the marketplace MUST attempt to determine if royalties have been backfilled by calling the collectionRoyaltyBackfillSettings function on Payment Processor. If no on-chain royalties are present, this may be set to 0.
• Requested/Minimum Fill Amount: When a fill transaction is submitted, this is the number of items the taker wishes to fill. If insufficient items remain from the partially filled order, the remaining number of items is filled instead, provided the number of remaining items its greater than or equal to the Minimum Fill Amount.

Sweep Order

This data structure is used to fill sweep orders, and represents the shared values that apply to all order in the sweep.

Protocol	Token Address	Payment Method	Beneficiary
uint8	address	address	address

• Protocol: 0 for ERC721 or 1 for ERC1155 collections.
• Token Address: The address of the collection.
• Payment Method: The address of the ERC-20 coin used to fill the trade, or address(0) for the native currency of the chain the trade executed on. For example, address(0) denotes ETH on ETH Mainnet, and Matic on Polygon Mainnet.
• Beneficiary: The address of the account that receives the item when the order is filled.

Sweep Item

This data structure is used to fill sweep orders, and represents the values that apply to individual orders in the sweep.

Maker	Marketplace	Fallback Royalty Recipient	Token Id	Amount	Item Price	Nonce	Expiration	Marketplace Fee Numerator	Max Royalty Fee Numerator
address	address	address	uint256	uint248	uint256	uint256	uint256	uint256	uint256

• Maker: The address of the account the created the order. May be an EOA or Smart Contract account. When the order was a listing, the maker is the seller of the item. When the order was an offer, the maker is the buyer of the item.
• Marketplace: The address to which the primary (maker) marketplace fee should be paid, or address(0) if the maker marketplace charges no platform fees. Note that for collections that offer non-exclusive royalty bounties, the maker marketplace also receives a royalty bounty paid out of creator royalties. For collections that offer exclusive royalty bounties, the maker marketplace receives a royalty bounty only if it matches the exclusive royalty bounty recipient designated by the collection creator.
• Fallback Royalty Recipient: Used to allow marketplaces to support royalties for collections that do not implement ERC-2981, do not have a contract owner and do not have a user with default admin role. Fallback royalties are calculated using the Max Royalty Fee Numerator for the sweep item.
• Token Id: The id of the token (if collection is ERC721), or the token type id of the token (if collection is ERC1155).
• Amount: The number of tokens. MUST be 1 if collection is ERC721, and MUST be greater than or equal to 1 if collection is ERC1155.
• Item Price: The price of the token(s) in the order.
• Nonce: A unique identifier to the order that prevents replay attacks. Nonce applies only to standard signed orders and may not be re-used. For co-signed order, nonce should be set to 0. Note: It is easier to generate a random nonce than attempt to keep track of nonces that have been used. However, be aware that a gas optimization is in place such that filled or cancelled nonces are tracked in a bitmap. Nonces 0-255, 256-511, 512-767, etc are stored in the same slot. Each maker address has its own set of nonces generated for gasless listings such that nonce 1234 is stored separately for makers address(5678) and address(abcd) but storage of the same nonce for the same maker is common across all marketplaces. It is possible that marketplaces will have no knowledge of nonces used in outstanding order signatures. Marketplaces should employ a nonce sequencing methodology that reduces the probability of overlapping nonce usage with other marketplaces. Examples of this could be a fixed set of upper bits for all orders placed through that marketplace where nonces 0x12340000...0000 to 0x1234FFFF...FFFF relate to a specific marketplace or the development of a common nonce issuance service that tracks all nonces used by a maker.
• Expiration: The unix timestamp (in seconds) when the maker's order signature expires. A marketplace's order making API should use the current unix timestamp and add a user-defined validity time that is acknowledged in the maker's signature.
• Marketplace Fee Numerator: Marketplace fee percentage in bips. Should be in range 0-10,000, as denominator is 10,000. 0.5% fee numerator is 50, 1% fee numerator is 100, 10% fee numerator is 1,000 and so on.
• Max Royalty Fee Numerator: Maximum approved royalty fee percentage in bips. Should be in range 0-10,000, as denominator is 10,000. 0.5% fee numerator is 50, 1% fee numerator is 100, 10% fee numerator is 1,000 and so on. When requesting the order signature from the order maker, the marketplace MUST first attempt to read the royalties for the individual token using the EIP-2981 royaltyInfo function call on the collection. If royaltyInfo raises an exception (likely because it is unimplemented), the marketplace MUST attempt to determine if royalties have been backfilled by calling the collectionRoyaltyBackfillSettings function on Payment Processor. If no on-chain royalties are present, this may be set to 0.