Universal Node Specification

[gerardcolomerFV]

Introduction

This issue looks at settling the specification of the behaviour of Universal Node (uNode).

All RPC calls received that do not involve a universal ERC-721 (uERC721) contract in the ownership chain (e.g. on Ethereum, on Polygon) are simply bypassed, routed to an ownership chain node. This redirection also applies to the corresponding responses.

The RPC calls that do involve a uERC721 contract on the ownership chain are the main subject of this issue, as specified below.

Check this other issue for the spec related to processing of the events from both nodes

Definitions

"tokenId" - The tokenId uses as input to ALL ERC-721 QUERIES refers to the id of the ownership chain slot
"a tokenId exists" - This is a hybrid EVOCHAIN+OWNCHAIN concept. First of all, as said above, all queries about tokenId refer to an ownership slot. Second, it exists if { it points to an asset that was minted in the Evochain AND it has not been burned in the ownchain }
tokenId does not exist" - The NOT of the previous definition of "a tokenId exists"

ERC-721 Interface

The uERC-721 standard exposed by the universal node will be the same one as the standard ERC-721. The below table exposes what is expected to be exposed by the ownership node, the evolution node as well as the universal node.

Function / Event	Detail	Ownership node	Evolution node	Universal node
event	event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId)	As dictated by 721 standard	-	Maintains {ownership node events + one "adapted Transfer event" per each Mint on evochain}
event	event Approval(address indexed _owner, address indexed _approved, uint256 indexed _tokenId)	As dictated by 721 standard	-	queries the ownership node
event	event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved)	As dictated by 721 standard	-	queries the ownership node
function	balanceOf(address _owner) external view returns (uint256)	The ownership node alone cannot reply in the required way to this query, therefore It is recommended that the method returns a constant number (e.g. 2**96) always	-	Returns { number of "tokenId that exist" owned by "owner" }
function	ownerOf(uint256 _tokenId) external view returns (address)	Returns the owner of a given slot regardless of whether the "tokenId exists" or not	-	Reverts if "tokenId does not exist". Otherwise, return { owner of slot }
function	safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes data) external payable	As dictated by 721 standard	-	Reverts if "tokenId does not exist". Otherwise, Relay to Ownership
function	safeTransferFrom(address _from, address _to, uint256 _tokenId) external payable	As dictated by 721 standard	-	Reverts if "tokenId does not exist". Otherwise, Relay to Ownership
function	transferFrom(address _from, address _to, uint256 _tokenId) external payable	As dictated by 721 standard	-	Reverts if "tokenId does not exist". Otherwise, Relay to Ownership
function	approve(address _approved, uint256 _tokenId) external payable	As dictated by 721 standard	-	Reverts if "tokenId does not exist". Otherwise, Relay to Ownership
function	setApprovalForAll(address _operator, bool _approved) external	As dictated by 721 standard	-	Relay to ownership node
function	getApproved(uint256 _tokenId) external view returns (address)	As dictated by 721 standard	-	Reverts if "tokenId does not exist". Otherwise, Relay to Ownership
function	isApprovedForAll(address _owner, address _operator) external view returns (bool)	As dictated by 721 standard	-	Relay to ownership node

ERC-721 enumeration

The uERC-721 standard exposed by the universal node needs to support the ERC-721 enumeration standard so a developer can ask for the total supply and retrieve one by one all minted tokens or all tokens from a user.

Function / Event	Detail	ownership node	evolution node	Universal node
function	supportsInterface(bytes4 interfaceID) external view returns (bool)	Returns false on 0x780e9d63	-	Returns true on 0x780e9d63
function	totalSupply() external view returns (uint256)	-	-	Returns { number of "tokenId that exist" }. Warning: careful about "burns" (which force you to look at the ownchain too); review definition of "exists"
function	tokenByIndex(uint256 _index) external view returns (uint256)	-	-	Returns the tokenId in the ownership chain for the slot at the given index within the ordered list of all "tokenId that exist".
function	tokenOfOwnerByIndex(address _owner, uint256 _index) external view returns (uint256)	-	-	Returns the tokenId in the ownership chain for the slot at the given index within the ordered list of { all "tokenId that exist" and are owned by the owner }

Metadata extension

Function / Event	Detail	ownership node	evolution node	Universal node
function	name() external view returns (string _name)	As dictated by 721 standard	-	Relay to ownership node
function	symbol() external view returns (string _symbol)	As dictated by 721 standard	-	Relay to ownership node
function	tokenURI(uint256 _tokenId) external view returns (string)	Returns the universal location to the evolution chain of a given asset.	-	Reverts if "tokenId does not exist". Otherwise Returns { evochain.collectionAddr.tokenURI(tokenId) }, where [collectionAddress, tokenId] = parse{ ownchain.tokenURI( tokenID ) }

Evochain

These queries that are not part of the 721 standard. In all that follows: tokenId refers to a value interpreted in the EVOCHAIN inside a certain collection. Check the full spec for the interfaces exposed by the EvoChain.

Function / Event	Detail
event	NewCollection(address indexed owner, address collectionAddress)
event	MintedWithExternalURI(address indexed to, uint96 slot, uint256 indexed tokenId, string tokenURI)
event	EvolvedWithExternalURI(uint256 indexed tokenId, string tokenURI)
function	createCollection(address owner) external returns (address)
function	owner() external view returns (address)
function	tokenURI(uint256 tokenId) external view returns (string memory)
function	mintWithExternalURI(address to, uint96 slot, string calldata tokenURI) external returns (uint256)
function	evolveWithExternalURI(uint256 tokenId,string calldata tokenURI) external returns (uint256)

Additional resources

ERC721 experiment repo - This repo allows you to play with the default ERC721 implementation by OpenZeppelin, you can add a test and see how a function behaves, etc.
Evochain Solidity Interface - Check here the methods and events available in the Evochain