From 23938d424843c4b53fc63d16327293a6cafb854f Mon Sep 17 00:00:00 2001 From: Leslie Fung Date: Tue, 9 Apr 2024 16:48:49 +1000 Subject: [PATCH] Clarify SIP-7 substandard encodings --- SIPS/sip-7.md | 427 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 416 insertions(+), 11 deletions(-) diff --git a/SIPS/sip-7.md b/SIPS/sip-7.md index 24fd9ef..a94d257 100644 --- a/SIPS/sip-7.md +++ b/SIPS/sip-7.md @@ -108,17 +108,422 @@ If substandards are being used, each encoded data segment as part of the context Note that zones or contract offerers MUST validate substandard ID data if provided, but it is at the discretion of the zone or contract offerer to determine which substandards MUST be provided and which substandards MAY be provided. Initial substandards include: -| substandard ID | description | decoding scheme | substandard request data supplied to API | substandard response data returned from API | -| -------------- | --------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| 1 | required identifier for first returned received item | `(uint256)` | `{"requestedIdentifier": "123..."}` | `{"requiredIdentifier": "123..."}` | -| 2 | required initial "tip" | `(uint8, address, uint256, uint256, address)` | `{"requestedTip": null OR {"itemType": "1", "token": "abc", ...}}` | `{"requiredTip": {"itemType": "1", "token": "abc", ...}}` | -| 3 | required hash of full ReceivedItem array | `(bytes32)` | `{"requestedReceivedItems": null OR [{"itemType": "1", "token": "abc", ...}, ...]}` | `{"requiredReceivedItems": [{"itemType": "1", ...}, ...], "requiredReceivedItemsHash": "0xabc..."}` | -| 4 | required order hashes included as part of fulfillment | `(bytes32[])` | `{"requestedIncludedOrderHashes": null OR ["0xabc...", ...]}` | `{"requiredIncludedOrderHashes": ["0xabc...", ...]}` | -| 5 | required order hashes NOT included as part of fulfillment | `(bytes32[])` | `{"requestedExcludedOrderHashes": null OR ["0xabc...", ...]}` | `{"requiredExcludedOrderHashes": ["0xabc...", ...]}` | -| 6 | full amount of order's first offer item, and required hash of full ReceivedItem array at total fulfillment of order | `(uint256, bytes32)` | `{"requestedReceivedItems": null OR [{"itemType": "1", "token": "abc", ...}, ...]}` | `{"originalFirstOfferItemAmount": "123...", "requiredReceivedItems": [{"itemType": "1", ...}, ...], "requiredReceivedItemsHash": "0xabc..."}` | -| 7 | required identifier for first returned received item, and trigger call to `beforeAuthorizedTransfer(address operator, address token)` and `afterAuthorizedTransfer(address token)` on the specified registry, supplying a specified operator and token from first 721 or 1155 item | `abi.encodePacked(uint256 identifer, address registry, address operator)` | `{"requestedIdentifier": "123...", "requestedRegistry": "0xabc...", "requestedOperator": "0xdef..."}` | `{"requiredIdentifier": "123...", "requiredRegistry": "0xabc...", "requiredOperator": "0xdef..."}` | -| 8 | required identifier for first returned received item, and trigger call to `beforeAuthorizedTransfer(address token, uint256 tokenId)` and `afterAuthorizedTransfer(address token, uint256 tokenId)` on the specified registry, using token and tokenId from first 721 or 1155 item | `abi.encodePacked(uint256 identifer, address registry)` | `{"requestedIdentifier": "123...", "requestedRegistry": "0xabc..."}` | `{"requiredIdentifier": "123...", "requiredRegistry": "0xabc..."}` | -| 9 | required identifier for first returned received item, and trigger call to `beforeAuthorizedTransferWithAmount(address token, uint256 tokenId, uint256 amount)` and `afterAuthorizedTransferWithAmount(address token, uint256 tokenId)` on the specified registry, using token, tokenId & amount from first 721 or 1155 item | `abi.encodePacked(uint256 identifer, address registry)` | `{"requestedIdentifier": "123...", "requestedRegistry": "0xabc..."}` | `{"requiredIdentifier": "123...", "requiredRegistry": "0xabc..."}` | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
substandard IDdescriptiondecoding schemesubstandard request data supplied to APIsubstandard response data returned from API
1required identifier for first returned received item + + ```solidity + abi.encodePacked(uint256 identifier) + ``` + + + + ```json + { + "requestedIdentifier": "123..." + } + ``` + + + + ```json + { + "requiredIdentifier": "123..." + } + ``` + +
2required initial "tip" + + ```solidity + abi.encodePacked( + uint8 itemType, + address token, + uint256 identifier, + uint256 amount, + address recipient + ) + ``` + + + + ```json + { + "requestedTip": null + } + + OR + + { + "requestedTip" { + "itemType": "1", + "token": "abc", + ... + } + } + ``` + + + + ```json + { + "requiredTip": { + "itemType": "1", + "token": "abc", + ... + } + } + ``` + +
3 + + required hash of full `ReceivedItem` array + + + + ```solidity + keccak256( + abi.encodePacked( + uint8 item1ItemType, + address item1Token, + uint256 item1Identifier, + uint256 item1Amount, + address item1Recipient, + uint8 item2ItemType, + ... + ) + ) + ``` + + + + ```json + { + "requestedReceivedItems": null + } + + OR + + { + "requestedReceivedItems": [ + { + "itemType": "1", + "token": "abc", + ... + }, + ... + ] + } + ``` + + + + ```json + { + "requiredReceivedItems": [ + { + "itemType": "1", + ... + }, + ... + ], + "requiredReceivedItemsHash": "0xabc..." + } + ``` + +
4required order hashes included as part of fulfillment + + ```solidity + abi.encode(bytes32[] orderHashes) + ``` + + + + ```json + { + "requestedIncludedOrderHashes": null + } + + OR + + { + "requestedIncludedOrderHashes": [ + "0xabc...", + ... + ] + } + ``` + + + + ```json + { + "requiredIncludedOrderHashes": [ + "0xabc...", + ... + ] + } + ``` + +
5required order hashes NOT included as part of fulfillment + + ```solidity + abi.encode(bytes32[] orderHashes) + ``` + + + + ```json + { + "requestedExcludedOrderHashes": null + } + + OR + + { + "requestedExcludedOrderHashes": [ + "0xabc...", + ... + ] + } + ``` + + + + ```json + { + "requiredExcludedOrderHashes": [ + "0xabc...", + ... + ] + } + ``` + +
6 + + full amount of order's first offer item, and required hash of full `ReceivedItem` array at total fulfillment of order + + + + ```solidity + abi.encodePacked( + uint256 originalFirstOfferItemAmount, + keccak256( + abi.encodePacked( + uint8 item1ItemType, + address item1Token, + uint256 item1Identifier, + uint256 item1Amount, + address item1Recipient, + uint8 item2ItemType, + ... + ) + ) + ) + ``` + + + + ```json + { + "requestedReceivedItems": null + } + + OR + + { + "requestedReceivedItems": [ + { + "itemType": "1", + "token": "abc", + ... + }, + ... + ] + } + ``` + + + + ```json + { + "originalFirstOfferItemAmount": "123...", + "requiredReceivedItems": [ + { + "itemType": "1", + ... + }, + ... + ], + "requiredReceivedItemsHash": "0xabc..." + } + ``` + +
7 + + required identifier for first returned received item, and trigger call to `beforeAuthorizedTransfer(address operator, address token)` and `afterAuthorizedTransfer(address token)` on the specified registry, supplying a specified operator and token from first 721 or 1155 item + + + + ```solidity + abi.encodePacked( + uint256 identifer, + address registry, + address operator + ) + ``` + + + + ```json + { + "requestedIdentifier": "123...", + "requestedRegistry": "0xabc...", + "requestedOperator": "0xdef..." + } + ``` + + + + ```json + { + "requiredIdentifier": "123...", + "requiredRegistry": "0xabc...", + "requiredOperator": "0xdef..." + } + ``` + +
8 + + required identifier for first returned received item, and trigger call to `beforeAuthorizedTransfer(address token, uint256 tokenId)` and `afterAuthorizedTransfer(address token, uint256 tokenId)` on the specified registry, using token and tokenId from first 721 or 1155 item + + + + ```solidity + abi.encodePacked( + uint256 identifer, + address registry + ) + ``` + + + + ```json + { + "requestedIdentifier": "123...", + "requestedRegistry": "0xabc..." + } + ``` + + + + ```json + { + "requiredIdentifier": "123...", + "requiredRegistry": "0xabc..." + } + ``` + +
9 + + required identifier for first returned received item, and trigger call to `beforeAuthorizedTransferWithAmount(address token, uint256 tokenId, uint256 amount)` and `afterAuthorizedTransferWithAmount(address token, uint256 tokenId)` on the specified registry, using token, tokenId & amount from first 721 or 1155 item + + + + ```solidity + abi.encodePacked( + uint256 identifer, + address registry + ) + ``` + + + + ```json + { + "requestedIdentifier": "123...", + "requestedRegistry": "0xabc..." + } + ``` + + + + ```json + { + "requiredIdentifier": "123...", + "requiredRegistry": "0xabc..." + } + ``` + +
Additional substandards MAY be specified in subsequent SIPs that inherit SIP-7.