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: 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 | uint256 | 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));
- 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 | Protocol Fee Version |
|---|
| uint256 | address | address | address | address | address | address | uint256 | uint256 | uint256 | uint256 | uint256 | uint256 | uint256 | uint256 | uint256 | uint256 |
- 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. Item price may not exceed type(uint240).max.
- 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.
- Protocol Fee Version: The protocol fee version to use when applying protocol fees.
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 |
|---|
| uint256 | 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 | Protocol Fee Version |
|---|
| address | address | address | uint256 | uint256 | uint256 | 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. May not exceed type(uint240).max.
- 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.
- Protocol Fee Version: The protocol fee version to use when applying protocol fees.
Bulk Order Proof
| orderIndex | proof |
|---|
| uint256 | bytes32[] |
- Order Index: The index of the order within the structure of the merkle tree. This is used to determine what side of the merkle tree the order falls on and used in conjunction with the provided merkle proof to recreate the root.
- Proof: An array of bytes32 hashes which are used to complete the merkle tree and generate the root along with the order digest.
Permit Context
| permitProcessor | permitNonce |
|---|
| address | uint256 |
- Permit Processor: The address of the Permit Processor contract. In order to be compatible with the Payment Processor, the provided contract must implement the
_permitTransferFromWithAdditionalData variants in PermitC as well as the fillPermittedOrderERC1155 function.
- Permit Nonce: The nonce of the permit processor to use to ensure that the transaction is only executed once. After a nonce is invalidated, the transaction cannot be replayed.
Advanced Order
This struct defines the items required to execute an advanced order.
| saleDetails | signature | cosignature | permitContext |
|---|
| Order | SignatureECDSA | Cosignature | PermitContext |
- saleDetails: The order execution parameters.
- signature: The signature of the maker authorizing order execution.
- cosignature: The cosignature of the maker authorizing the order execution (when cosigning enabled for an order).
- permitContext: Contains the address of the permit processor and the permit nonce to be used.
Advanced Bid Order
This struct defines the items required to execute an advanced bid order.
| offerType | advancedOrder | sellerPermitSignature |
|---|
| uint256 | AdvancedOrder | SignatureECDSA |
- offerType: The type of offer to execute [(0) Offer for any item in a collection. (1) Offer for a specific item in a collection. (2) Offer for a set of tokens in a collection.]
- advancedOrder: The order execution parameters.
- sellerPermitSignature: The signature of the seller to be used for the permit.
Advanced Sweep
This struct defines the items required to execute an advanced sweep order.
| feeOnTop | sweepOrder | items |
|---|
| FeeOnTop | SweepOrder | AdvancedSweepItem[] |
- feeOnTop: The additional fee to be paid by the taker.
- sweepOrder: The order execution parameters.
- items: An array of items to be executed as part of the sweep order.
Advanced Sweep Item
This struct is a wrapper for a sweep order item that includes the permit context, bulk order information, signature and cosignature.
| sweepItem | signature | cosignature | permitContext | bulkOrderProof |
|---|
| SweepItem | SignatureECDSA | Cosignature | PermitContext | BulkOrderProof |
- sweepItem: The sweep order item to be executed.
- signature: The signature of the maker authorizing the order execution.
- cosignature: The cosignature of the maker authorizing the order execution.
- permitContext: Contains the address of the permit processor and the permit nonce to be used.
- bulkOrderProof: The proof data for the bulk order.
