SuperRare Developer Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Auxiliary Contracts

Supporting Contracts

Overview

While not part of the core components of the network, these contracts play very pivotal parts in setting up certains values, control plane settings for the network to function. The power of this is that new core mechanics can be built on top of them due to Web3 composability by anyone and adopted into the core network.

Marketplace Settings

The marketplace settings provides SuperRare network with various information that influences the payment amounts such as: network fee (3%), primary sale fee (15%), and whether or not a token has previously sold (sale is a primary vs secondary sale).

Interface

interface IMarketplaceSettings {

	/**
	* @dev Get the max value to be used with the marketplace.
	* @return uint256 wei value.
	*/
	function getMarketplaceMaxValue() external view returns (uint256);
	
	/**
	* @dev Get the max value to be used with the marketplace.
	* @return uint256 wei value.
	*/
	function getMarketplaceMinValue() external view returns (uint256);

	/**
	* @dev Get the marketplace fee percentage.
	* @return uint8 wei fee.
	*/
	function getMarketplaceFeePercentage() external view returns (uint8);  

	/**
	* @dev Utility function for calculating the marketplace fee for given amount of wei.
	* @param _amount uint256 wei amount.
	* @return uint256 wei fee.
	*/
	function calculateMarketplaceFee(uint256 _amount)
		external
		view
		returns (uint256);

	/**
	* @dev Get the primary sale fee percentage for a specific ERC721 contract.
	* @param _contractAddress address ERC721Contract address.
	* @return uint8 wei primary sale fee.
	*/
	function getERC721ContractPrimarySaleFeePercentage(address _contractAddress)
		external
		view
		returns (uint8);

	/**
	* @dev Utility function for calculating the primary sale fee for given amount of wei
	* @param _contractAddress address ERC721Contract address.
	* @param _amount uint256 wei amount.
	* @return uint256 wei fee.
	*/
	function calculatePrimarySaleFee(address _contractAddress, uint256 _amount)
		external
		view
		returns (uint256);

	/**
	* @dev Check whether the ERC721 token has sold at least once.
	* @param _contractAddress address ERC721Contract address.
	* @param _tokenId uint256 token ID.
	* @return bool of whether the token has sold.
	*/
	function hasERC721TokenSold(address _contractAddress, uint256 _tokenId)
	external
	view
	returns (bool);

	/**
	* @dev Mark a token as sold.
	* Requirements:
	*
	* - `_contractAddress` cannot be the zero address.
	* @param _contractAddress address ERC721Contract address.
	* @param _tokenId uint256 token ID.
	* @param _hasSold bool of whether the token should be marked sold or not.
	*/
	function markERC721Token(
		address _contractAddress,
		uint256 _tokenId,
		bool _hasSold
	) external;
}

Approved Token Registry

This registry holds the list of ERC20 tokens that are approved by the network to be used in the SuperRare ecosystem. This is an important aspect as we can guarantee that only the tokens agreed upon by the network (through the SIP procedure) are able to be used by our supporting contracts.

Interface

interface IApprovedTokenRegistry {
	/// @notice Returns if a token has been approved or not.
	/// @param _tokenContract Contract of token being checked.
	/// @return True if the token is allowed, false otherwise.
	function isApprovedToken(address _tokenContract)
		external
		view
		returns (bool);

	/// @notice Adds a token to the list of approved tokens.
	/// @param _tokenContract Contract of token being approved.
	function addApprovedToken(address _tokenContract) external;
	
	/// @notice Removes a token from the approved tokens list.
	/// @param _tokenContract Contract of token being approved.
	function removeApprovedToken(address _tokenContract) external;

	/// @notice Sets whether all token contracts should be approved.
	/// @param _allTokensApproved Bool denoting if all tokens should be approved.
	function setAllTokensApproved(bool _allTokensApproved) external;
}

Space Operator Registry

The Space Operator Registry provides the network with a nice interface to determine whether or not an address is a SuperRare Network approved Operator and what the platform commission is for that Operator (this is in place of the 15% on primary sales of other pieces).

Interface

interface ISpaceOperatorRegistry {
	function getPlatformCommission(address _operator)
		external
		view
		returns (uint8);

function setPlatformCommission(address _operator, uint8 _commission)
	external;

function isApprovedSpaceOperator(address _operator)
	external
	view
	returns (bool);

function setSpaceOperatorApproved(address _operator, bool _approved)
	external;
}

Creator Registry

As the ERC721 is a minimal standard for what constitutes an NFT we came up with our own way of denoting who the creator of an individual token is and being able to override it in the event that a wallet gets compromised (for the purpose of royalties). This registry encompasses all of that and is used by SuperRare Royalty Registry and transitively by the global one as well.

Interface

interface ICreatorRegistry {
    function tokenCreator(address _contractAddress, uint256 _tokenId)
        external
        view
        returns (address payable);
}

Royalty Registry (SuperRare)

Before ERC-2981: The Royalty Standard existed, the SuperRare Network created a registry to store information on the royalty amount that needed to be paid for a given token and who it should be paid for. Currently we call the global roylaty registry directly which under the hood will use the 2981 standard or this registry (only for SuperRareV1 and SuperRareV2 tokens).

Interface

interface IRoyaltyRegistry {
    /**
     * @dev Get the royalty fee percentage for a specific ERC721 contract.
     * @param _contractAddress address ERC721Contract address.
     * @param _tokenId uint256 token ID.
     * @return uint8 wei royalty fee.
     */
    function getERC721TokenRoyaltyPercentage(
        address _contractAddress,
        uint256 _tokenId
    ) external view returns (uint8);

    /**
     * @dev Utililty function to calculate the royalty fee for a token.
     * @param _contractAddress address ERC721Contract address.
     * @param _tokenId uint256 token ID.
     * @param _amount uint256 wei amount.
     * @return uint256 wei fee.
     */
    function calculateRoyaltyFee(
        address _contractAddress,
        uint256 _tokenId,
        uint256 _amount
    ) external view returns (uint256);

    /**
     * @dev Utililty function to set the royalty percentage for a specific ERC721 contract.
     * @param _contractAddress address ERC721Contract address.
     * @param _percentage percentage for royalty
     */
    function setPercentageForSetERC721ContractRoyalty(
        address _contractAddress,
        uint8 _percentage
    ) external;

	function tokenCreator(address _contractAddress, uint256 _tokenId)
        external
        view
        returns (address payable);
}

Payments

Payments is, for the most part, a stateless contract whose only job is to facilitate the sending of eth from the market to an address. This utilizes the OpenZeppelin PullPayment contract in order to handle failed payments. If an eth transfer fails for whatever reason, the amount is escrowed within the contract allowing for a user to go in and claim their balance. This helps us mitigate against certain Denial of Service attacks.

Interface

interface IPayments {
	function refund(address _payee, uint256 _amount) 
		external 
		payable;

	function payout(address[] calldata _splits, uint256[] calldata _amounts)
		external
		payable;

	function withdrawPayments(address payable payee) public;

	function payments(address dest) 
		public 
		view 
		returns (uint256 balance);
}

Collector Royalties

Collector royalties is a program where previous owners from a token are able to partake in future sales of that token (starting once they are not involved in the sale). In order to have this done in an efficient manner, the total amounts are accumulated off-chain and bundled up into a single claim. This contract uses merkle proofs to keep both the cost down and the logic simple.

Interface

interface ICollectorRoyaltiesClaim {
	bytes32 public claimRoot;
	mapping(address => mapping(uint256 => bool)) public rewardClaimedForClaim;
	uint256 public currentClaimId;
	bool public paused;

	event RoyaltyClaimed(
		bytes32 indexed root,
		address indexed addr,
		uint256 indexed claimId,
		uint256 amt
	);

	event NewClaim(uint256 indexed claimId, bytes32 indexed root);

	function claim(uint256 amount, bytes32[] calldata proof) public;

	function verifyEntitled(
		address recipient,
		uint256 value,
		bytes32[] memory proof
	) public view returns (bool);

  
	function verifyProof(bytes32 leaf, bytes32[] memory proof)
		internal
		view
		returns (bool);
}

Addresses

Mainnet

Contract Name Contract Address
SuperRare Mint Allowlist 0xb932a70a57673d89f4acffbe830e8ed7f75fb9e0
MarketplaceSettings 0x33bAC43e4B5aF78fec2283CE719C0D2Eb9E79AEa
ApprovedTokenRegistry 0x16c9e9Bc7fD73F538e7dFc2eb1A21F429C3e0B8C
SpaceOperatorRegistry 0xa8752906162B734274f75C2F23C7A00f05D085c0
RoyaltyRegistry (SR) 0x17B0C8564E53f22364A6C8de6F7ca5CE9BEa4e5D
RoyaltyEngine (Global) 0xFf5A6F7f36764aAD301B7C9E85A5277614Df5E26
Payments 0xc033BBef0Af25Db7523FCe16BaB1C39df0bF2Ae3
CollectorRoyalties 0xb661241653B0174e3d758CeE01e320A1f4BcAeBF