Merge branch 'main' into oz-n01

Author: operatorfilterer

README.md

@@ -2,40 +2,40 @@
 
 ## **Note on Grace Period for Non-Ethereum Chains**
 
-Currently, OpenSea only requires creator fee enforcement on Ethereum Mainnet and Goerli for collections to be eligible for creator fees. However, starting **January 2nd, 2023**, Opensea will begin validating creator fee enforcement on all supported EVM chains.
+Currently, OpenSea only requires creator earnings enforcement on Ethereum Mainnet and Goerli for collections to be eligible for creator earnings. However, starting **January 2nd, 2023**, Opensea will begin validating creator earnings enforcement on all supported EVM chains.
 
 ## Introduction
 
-This repository contains a number of tools to help token contracts manage the operators allowed to transfer tokens on behalf of users - including the smart contracts and delegates of marketplaces that do not respect creator fees.
+This repository contains a number of tools to help token contracts manage the operators allowed to transfer tokens on behalf of users - including the smart contracts and delegates of marketplaces that do not respect creator earnings.
 
-This is not a foolproof approach - but it makes bypassing creator fees less liquid and easy at scale.
+This is not a foolproof approach - but it makes bypassing creator earnings less liquid and easy at scale.
 
 ## How it works
 
 Token smart contracts may register themselves (or be registered by their "owner") with the `OperatorFilterRegistry`. Token contracts or their "owner"s may then curate lists of operators (specific account addresses) and codehashes (smart contracts deployed with the same code) that should not be allowed to transfer tokens on behalf of users.
 
-## Creator Fee Enforcement
+## Creator Earnings Enforcement
 
-OpenSea will enforce creator fees for smart contracts that make best efforts to filter transfers from operators known to not respect creator fees.
+OpenSea will enforce creator earnings for smart contracts that make best efforts to filter transfers from operators known to not respect creator earnings.
 
 This repository facilitates that process by providing smart contracts that interface with the registry automatically, including automatically subscribing to OpenSea's list of filtered operators.
 
 When filtering operators, use of this registry is not required, nor is it required for a token contract to "subscribe" to OpenSea's list within this registry. Subscriptions can be changed or removed at any time. Filtered operators and codehashes may likewise be added or removed at any time.
 
-Contract owners may implement their own filtering outside of this registry, or they may use this registry to curate their own lists of filtered operators. However, there are certain contracts that are filtered by the default subscription, and must be filtered in order to be eligible for creator fee enforcement on OpenSea.
+Contract owners may implement their own filtering outside of this registry, or they may use this registry to curate their own lists of filtered operators. However, there are certain contracts that are filtered by the default subscription, and must be filtered in order to be eligible for creator earnings enforcement on OpenSea.
 
 ## Note on [EIP-2981](https://eips.ethereum.org/EIPS/eip-2981)
 
-Implementing EIP-2981 is not sufficient for a token to be eligible for creator fees on OpenSea.
+Implementing EIP-2981 is not sufficient for a token to be eligible for creator earnings on OpenSea.
 
-While sometimes described as "on-chain," EIP-2981 only provides a method to determine what the appropriate creator fee should be for a sale. EIP-2981 does not provide any mechanism of on-chain enforcement of those fees.
+While sometimes described as "on-chain," EIP-2981 only provides a method to determine what the appropriate creator earnings should be for a sale. EIP-2981 does not provide any mechanism of on-chain enforcement of those earnings.
 
 ## Filtered addresses
 
 Entries in this list are added according to the following criteria:
 
--   If the application most commonly used to interface with the contract gives buyers and sellers the ability to bypass creator fees when a similar transaction for the same item would require creator fee payment on OpenSea.io
--   If the contract is facilitating the evasion of on-chain creator fee enforcement measures. For example, the contract uses a wrapper contract to bypass fee enforcement.
+-   If the application most commonly used to interface with the contract gives buyers and sellers the ability to bypass creator earnings when a similar transaction for the same item would require creator earnings payment on OpenSea.io
+-   If the contract is facilitating the evasion of on-chain creator earnings enforcement measures. For example, the contract uses a wrapper contract to bypass earnings enforcement.
 
 <table>
 <tr>
@@ -79,11 +79,18 @@ Ethereum Mainnet
 <table>
 <tr>
 <th>Network</th>
+<th>CORI Subscription TimelockController</th>
 <th>OperatorFilterRegistry</th>
-<th>OpenSea Curated Subscription Address</th>
+<th>CORI Curated Subscription Address</th>
 </tr>
 
-<tr><td>Ethereum</td><td rowspan="20">
+<tr><td>Ethereum</td>
+<td>
+
+0x178AD648e66815E1B01791eBBdbF7b2D7C5B1626
+
+</td>
+<td rowspan="20">
 
 [0x000000000000AAeB6D7670E522A718067333cd4E](https://etherscan.io/address/0x000000000000AAeB6D7670E522A718067333cd4E#code)
 
@@ -93,8 +100,17 @@ Ethereum Mainnet
 
 </td></tr>
 
-<tr><td>Goerli</td></tr>
-<tr><td>Polygon</td></tr>
+<tr>
+<td>Polygon</td>
+
+<td>
+0x87bCD4735CbCF9CE98ea2822fBf3F05F2ce10f96
+</td>
+<td></td>
+<td></td>
+</tr>
+
+<tr><td>Goerli</td><td rowspan="20">0xe3A6CD067a1193b903143C36dA00557c9d95C41e</td></tr>
 <tr><td>Mumbai</td></tr>
 <tr><td>Optimism</td></tr>
 <tr><td>Optimism Goerli</td></tr>
@@ -111,6 +127,8 @@ Ethereum Mainnet
 
 </table>
 
+To mitigate abuse of the CORI curated subscription of filtered operators and codehashes, the CORI curated subscription is owned by a `TimelockController`, which is in turn owned by a multi-signature wallet. Any update to CORI's list of filtered operators must be approved by at least two members of the Creator Ownership Research Institute, and is then subject to a minimum 24-hour delay before being executed. During this time, updates may be reviewed and revoked. 
+
 ## Usage
 
 Token contracts that wish to manage lists of filtered operators and restrict transfers from them may integrate with the registry easily with tokens using the [`OperatorFilterer`](src/OperatorFilterer.sol) and [`DefaultOperatorFilterer`](src/DefaultOperatorFilterer.sol) contracts. These contracts provide modifiers (`onlyAllowedOperator` and `onlyAllowedOperatorApproval`) which can be used on the token's transfer methods to restrict transfers from or approvals of filtered operators.
@@ -210,7 +228,7 @@ This method will toggle filtering for an operator for a given registrant. If `fi
 
 ### updateCodeHash(address registrant, bytes32 codeHash, bool filtered)
 
-This method will toggle filtering on code hashes of operators given registrant. If an operator's `EXTCODEHASH` matches a filtered code hash, `isOperatorAllowed` will return `true`. Otherwise, `isOperatorAllowed` will return `false`. This can filter smart contract operators with different addresess but the same code.
+This method will toggle filtering on code hashes of operators given registrant. If an operator's `EXTCODEHASH` matches a filtered code hash, `isOperatorAllowed` will return `true`. Otherwise, `isOperatorAllowed` will return `false`. This can filter smart contract operators with different addresses but the same code.
 
 ## `OperatorFilterer`
 
@@ -225,6 +243,8 @@ On construction, it takes three parameters:
 -   `address subscriptionOrRegistrantToCopy`: the address of the registrant the contract will either subscribe to, or do a one-time copy of that registrant's filters. If the zero address is provided, no subscription or copies will be made.
 -   `bool subscribe`: if true, subscribes to the previous address if it was not the zero address. If false, copies existing filtered addresses and codeHashes without subscribing to future updates.
 
+Please note that if your token contract does not provide an owner with [EIP-173](https://eips.ethereum.org/EIPS/eip-173), it must provide administration methods on the contract itself to interact with the registry otherwise the subscription will be locked to the options set during construction.
+
 ### `onlyAllowedOperator(address operator)`
 
 This modifier will revert if the `operator` or its code hash is filtered by the `OperatorFilterRegistry` contract.
@@ -233,15 +253,17 @@ This modifier will revert if the `operator` or its code hash is filtered by the
 
 This smart contract extends `OperatorFilterer` and automatically configures the token contract that inherits it to subscribe to OpenSea's list of filtered operators and code hashes. This subscription can be updated at any time by the owner by calling `updateSubscription` on the `OperatorFilterRegistry` contract.
 
+Please note that if your token contract does not provide an owner with [EIP-173](https://eips.ethereum.org/EIPS/eip-173), it must provide administration methods on the contract itself to interact with the registry otherwise the subscription will be locked to the options set during construction.
+
 ## `OwnedRegistrant`
 
 This `Ownable` smart contract is meant as a simple utility to enable subscription addresses that can easily be transferred to a new owner for administration. For example: an EOA curates a list of filtered operators and code hashes, and then transfers ownership of the `OwnedRegistrant` to a multisig wallet.
 
 # Validation
 
-When the first token is minted on an NFT smart contract, OpenSea checks if the filtered operators on that network (Ethereum Mainnet, Goerli, Polygon, etc.) are allowed to transfer the token. If they are, OpenSea will mark the collection as ineligible for creator fees. Otherwise, OpenSea will enforce creator fees on the collection.
+When the first token is minted on an NFT smart contract, OpenSea checks if the filtered operators on that network (Ethereum Mainnet, Goerli, Polygon, etc.) are allowed to transfer the token. If they are, OpenSea will mark the collection as ineligible for creator earnings. Otherwise, OpenSea will enforce creator earnings on the collection.
 
-If at a later point, OpenSea detects orders being fulfilled by filtered operators, OpenSea will mark the collection as ineligible for creator fees going forward.
+If at a later point, OpenSea detects orders being fulfilled by filtered operators, OpenSea will mark the collection as ineligible for creator earnings going forward.
 
 The included [validation test](test/validation/Validation.t.sol) runs the same checks that OpenSea does when first creating a collection page, and can be extended with custom setup for your token contract.
 

src/DefaultOperatorFilterer.sol

@@ -6,9 +6,14 @@ import {OperatorFilterer} from "./OperatorFilterer.sol";
 /**
  * @title  DefaultOperatorFilterer
  * @notice Inherits from OperatorFilterer and automatically subscribes to the default OpenSea subscription.
+ * @dev    Please note that if your token contract does not provide an owner with EIP-173, it must provide
+ *         administration methods on the contract itself to interact with the registry otherwise the subscription
+ *         will be locked to the options set during construction.
  */
 abstract contract DefaultOperatorFilterer is OperatorFilterer {
+    /// @dev The default OpenSea subscription address
     address constant DEFAULT_SUBSCRIPTION = address(0x3cc6CddA760b79bAfa08dF41ECFA224f810dCeB6);
 
+    /// @dev The constructor that is called when the contract is being deployed.
     constructor() OperatorFilterer(DEFAULT_SUBSCRIPTION, true) {}
 }

src/IOperatorFilterRegistry.sol

@@ -2,28 +2,138 @@
 pragma solidity ^0.8.13;
 
 interface IOperatorFilterRegistry {
+    /**
+     * @notice Returns true if operator is not filtered for a given token, either by address or codeHash. Also returns
+     *         true if supplied registrant address is not registered.
+     */
     function isOperatorAllowed(address registrant, address operator) external view returns (bool);
+
+    /**
+     * @notice Registers an address with the registry. May be called by address itself or by EIP-173 owner.
+     */
     function register(address registrant) external;
+
+    /**
+     * @notice Registers an address with the registry and "subscribes" to another address's filtered operators and codeHashes.
+     */
     function registerAndSubscribe(address registrant, address subscription) external;
+
+    /**
+     * @notice Registers an address with the registry and copies the filtered operators and codeHashes from another
+     *         address without subscribing.
+     */
     function registerAndCopyEntries(address registrant, address registrantToCopy) external;
+
+    /**
+     * @notice Unregisters an address with the registry and removes its subscription. May be called by address itself or by EIP-173 owner.
+     *         Note that this does not remove any filtered addresses or codeHashes.
+     *         Also note that any subscriptions to this registrant will still be active and follow the existing filtered addresses and codehashes.
+     */
     function unregister(address addr) external;
+
+    /**
+     * @notice Update an operator address for a registered address - when filtered is true, the operator is filtered.
+     */
     function updateOperator(address registrant, address operator, bool filtered) external;
+
+    /**
+     * @notice Update multiple operators for a registered address - when filtered is true, the operators will be filtered. Reverts on duplicates.
+     */
     function updateOperators(address registrant, address[] calldata operators, bool filtered) external;
+
+    /**
+     * @notice Update a codeHash for a registered address - when filtered is true, the codeHash is filtered.
+     */
     function updateCodeHash(address registrant, bytes32 codehash, bool filtered) external;
+
+    /**
+     * @notice Update multiple codeHashes for a registered address - when filtered is true, the codeHashes will be filtered. Reverts on duplicates.
+     */
     function updateCodeHashes(address registrant, bytes32[] calldata codeHashes, bool filtered) external;
+
+    /**
+     * @notice Subscribe an address to another registrant's filtered operators and codeHashes. Will remove previous
+     *         subscription if present.
+     *         Note that accounts with subscriptions may go on to subscribe to other accounts - in this case,
+     *         subscriptions will not be forwarded. Instead the former subscription's existing entries will still be
+     *         used.
+     */
     function subscribe(address registrant, address registrantToSubscribe) external;
+
+    /**
+     * @notice Unsubscribe an address from its current subscribed registrant, and optionally copy its filtered operators and codeHashes.
+     */
     function unsubscribe(address registrant, bool copyExistingEntries) external;
+
+    /**
+     * @notice Get the subscription address of a given registrant, if any.
+     */
     function subscriptionOf(address addr) external returns (address registrant);
+
+    /**
+     * @notice Get the set of addresses subscribed to a given registrant.
+     *         Note that order is not guaranteed as updates are made.
+     */
     function subscribers(address registrant) external returns (address[] memory);
+
+    /**
+     * @notice Get the subscriber at a given index in the set of addresses subscribed to a given registrant.
+     *         Note that order is not guaranteed as updates are made.
+     */
     function subscriberAt(address registrant, uint256 index) external returns (address);
+
+    /**
+     * @notice Copy filtered operators and codeHashes from a different registrantToCopy to addr.
+     */
     function copyEntriesOf(address registrant, address registrantToCopy) external;
+
+    /**
+     * @notice Returns true if operator is filtered by a given address or its subscription.
+     */
     function isOperatorFiltered(address registrant, address operator) external returns (bool);
+
+    /**
+     * @notice Returns true if the hash of an address's code is filtered by a given address or its subscription.
+     */
     function isCodeHashOfFiltered(address registrant, address operatorWithCode) external returns (bool);
+
+    /**
+     * @notice Returns true if a codeHash is filtered by a given address or its subscription.
+     */
     function isCodeHashFiltered(address registrant, bytes32 codeHash) external returns (bool);
+
+    /**
+     * @notice Returns a list of filtered operators for a given address or its subscription.
+     */
     function filteredOperators(address addr) external returns (address[] memory);
+
+    /**
+     * @notice Returns the set of filtered codeHashes for a given address or its subscription.
+     *         Note that order is not guaranteed as updates are made.
+     */
     function filteredCodeHashes(address addr) external returns (bytes32[] memory);
+
+    /**
+     * @notice Returns the filtered operator at the given index of the set of filtered operators for a given address or
+     *         its subscription.
+     *         Note that order is not guaranteed as updates are made.
+     */
     function filteredOperatorAt(address registrant, uint256 index) external returns (address);
+
+    /**
+     * @notice Returns the filtered codeHash at the given index of the list of filtered codeHashes for a given address or
+     *         its subscription.
+     *         Note that order is not guaranteed as updates are made.
+     */
     function filteredCodeHashAt(address registrant, uint256 index) external returns (bytes32);
+
+    /**
+     * @notice Returns true if an address has registered
+     */
     function isRegistered(address addr) external returns (bool);
+
+    /**
+     * @dev Convenience method to compute the code hash of an arbitrary contract
+     */
     function codeHashOf(address addr) external returns (bytes32);
 }