Socket
Socket
Sign inDemoInstall

@limitbreak/creator-token-standards

Package Overview
Dependencies
2
Maintainers
1
Versions
2
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@limitbreak/creator-token-standards


Version published
Maintainers
1
Created

Readme

Source

Creator Token Standards

A backwards compatible library of NFT contract standards and mix-ins that power programmable royalty use cases and expand possible NFT use cases by introducing creator tokens.

Installation with Foundry

With an existing foundry project:

forge install OpenZeppelin/openzeppelin-contracts@v4.8.3
forge install chiru-labs/ERC721A@v4.2.3
forge install dmfxyz/murky
forge install limitbreakinc/creator-token-standards

Add a remappings.txt file to the root of your project and add the following contents to resolve imports.

@limitbreak/creator-token-standards/=lib/creator-token-standards/src/
@openzeppelin/=lib/openzeppelin-contracts/
ds-test/=lib/forge-std/lib/ds-test/src/
forge-std/=lib/forge-std/src/
murky/=lib/murky/src
erc721a/=lib/ERC721A/

Usage

Once installed, you can use the contracts in the library by importing them.

Note: This contract library contains Initializable variations of several contracts an mix-ins. The initialization functions are meant for use ONLY with EIP-1167 Minimal Proxies (Clones). The use of the term "Initializable" is not meant to imply that these contracts are suitable for use in Upgradeable Proxy contracts. This contract library should NOT be used in any upgradeable contract, as they do not provide storage-safety should additional contract variables be added in future versions. Limit Break has no intentions to make this library suitable for upgradeability and developers are solely responsible for adapting the code should they use it in an upgradeable contract.

Cloning The Source Code

git clone https://github.com/limitbreakinc/creator-token-standards.git

Build

forge build

Test

forge test

Code Coverage

./scripts/test/generate-coverage-report.sh

Documentation

forge doc -s
> Serving on: http://localhost:3000

Open a browser to http://localhost:3000 to view docs.

Deploying The Registry

./script/common/0-create2-transfer-validator-v2.sh
./script/common/1-deploy-transfer-validator-v2.sh --gas-price <gas-price> --priority-gas-price <priority-gas-price> --chain-id <chain-id>

Overview

  • Extended NFT Standards

    • AdventureERC721 - Limit Break's adventure token standard that provides flexible hard and soft staking mechanics to enable on-chain adventures and quests.
    • ERC721C - Extends OpenZeppelin's ERC721 implementation, adding creator-definable transfer security profiles that are the foundation for enforceable, programmable royalties.
    • ERC1155C - Extends OpenZeppelin's ERC1155 implementation, adding creator-definable transfer security profiles that are the foundation for enforceable, programmable royalties.
    • AdventureERC721C - Extends Limit Break's AdventureERC721 implementation, adding creator-definable transfer security profiles that are the foundation for enforceable, programmable royalties.
    • ERC721AC - Extends Azuki's ERC721-A implementation, adding creator-definable transfer security profiles that are the foundation for enforceable, programmable royalties.
  • Wrapper Standards

    • ERC721CW - Extends ERC721C and introduces opt-in staking/unstaking as a form of token wrapping/unwrapping. This is backwards compatible and enables any vanilla ERC721 token to be upgraded to an ERC721C with enhanced utility at the discretion of token holders who can choose whether to stake into the new state or not.
    • ERC1155CW - Extends ERC1155C and introduces opt-in staking/unstaking as a form of token wrapping/unwrapping. This is backwards compatible and enables any vanilla ERC1155 token to be upgraded to an ERC1155C with enhanced utility at the discretion of token holders who can choose whether to stake into the new state or not.
    • AdventureERC721CW - Extends AdventureERC721C and introduces opt-in staking/unstaking as a form of token wrapping/unwrapping. This is backwards compatible and enables any vanilla ERC721 token to be upgraded to an AdventureERC721C with enhanced utility at the discretion of token holders who can choose whether to stake into the new state or not.
  • Interfaces - for ease of integration, the following interfaces have been defined for 3rd party consumption

  • Infrastructure

    • EOARegistry - A deployable contract where users can sign a message to prove they are an EOA. A global community-use EOA registry will be deployed and made available as there is no real need for users to prove they are an EOA in more than one contract.
    • CreatorTokenTransferValidator - Extends EOA registry and enables creators to set transfer security levels, create and manage whitelists/contract receiver allow lists, and apply their creator-defined policies to one or more creator token collections they own. All the different implementations of creator token standards point to this registry for application of transfer security policies. [DEPRECATED]
    • CreatorTokenTransferValidatorV2 - Extends EOA registry and enables creators to set transfer security levels, create and manage whitelists/blacklists, and apply their creator-defined policies to one or more creator token collections they own. All the different implementations of creator token standards point to this registry for application of transfer security policies. [CURRENT VERSION]
  • Programmable Royalty Sample Mix-Ins for ERC-721

    • ImmutableMinterRoyalties - A mix-in that grants minters permanent royalty rights to the NFT token ID they minted. Royalty fee cannot be changed.
    • MutableMinterRoyalties - A mix-in that grants minters permanent royalty rights to the NFT token ID they minted. Royalty fee for each token ID can be changed by the minter of that token id.
    • MinterCreatorSharedRoyalties - A mix-in that grants minters a permanent share of royalty rights to the NFT token ID they minted. Royalty fees for each token ID are shared between the NFT creator and the minter according to a ratio of shares defined at contract creation. A payment splitter is created for each token ID to split funds between the minter and creator.
  • Miscellaneous

    • EOARegistryAccess - A mix-in that can be applied to any contract that has a need to verify an arbitrary address is a verified EOA.
    • TransferValidation - A mix-in that can be used to decompose _beforeTransferToken and _afterTransferToken into granular pre and post mint/burn/transfer validation hooks. These hooks provide finer grained controls over the lifecycle of an ERC721 token.
  • Presets

  • Examples

How To Guides

How To Build, Deploy, and Setup a Creator Token

  1. Choose a standard (ERC721-C, ERC721-AC, AdventureERC721-C, ERC1155-C, or ERC20-C)
  2. Inherit the selected standard and desired mix-ins. The following example is a basic ERC721-C with an open mint and basic royalties.
pragma solidity ^0.8.4;

import "@limitbreak/creator-token-standards/access/OwnableBasic.sol";
import "@limitbreak/creator-token-standards/erc721c/v2/ERC721C.sol";
import "@limitbreak/creator-token-standards/programmable-royalties/BasicRoyalties.sol";

contract ERC721CWithBasicRoyalties is OwnableBasic, ERC721C, BasicRoyalties {

    constructor(
        address royaltyReceiver_,
        uint96 royaltyFeeNumerator_,
        string memory name_,
        string memory symbol_) 
        ERC721OpenZeppelin(name_, symbol_) 
        BasicRoyalties(royaltyReceiver_, royaltyFeeNumerator_) {
    }

    function supportsInterface(bytes4 interfaceId) public view virtual override(ERC721C, ERC2981) returns (bool) {
        return super.supportsInterface(interfaceId);
    }

    function mint(address to, uint256 tokenId) external {
        _mint(to, tokenId);
    }

    function safeMint(address to, uint256 tokenId) external {
        _safeMint(to, tokenId);
    }

    function burn(uint256 tokenId) external {
        _burn(tokenId);
    }

    function setDefaultRoyalty(address receiver, uint96 feeNumerator) public {
        _requireCallerIsContractOwner();
        _setDefaultRoyalty(receiver, feeNumerator);
    }

    function setTokenRoyalty(uint256 tokenId, address receiver, uint96 feeNumerator) public {
        _requireCallerIsContractOwner();
        _setTokenRoyalty(tokenId, receiver, feeNumerator);
    }
}

  1. Deploy and verify contract. It is assumed developers already know how to do this, but instructions for Foundry can be found here.

  2. It is strongly encouraged to transfer ownership of your contracts to a multi-sig, such as Gnosis Safe and to require multiple keys to sign off on each transaction.

  3. To configure collection security and trading settings, use developers.freenft.com.

How To Use The Creator Token Transfer Validator To Manage Security Settings For Collections

The CreatorTokenTransferValidator is a smart contract used for managing and applying security policies to token transfers. It provides a comprehensive set of configurable security policies to help control token transfers, while also allowing external on-chain whitelisting and blacklisting of accounts and codehashes. The magic of creator tokens is applied in this infrastructure contract. Limit Break has deployed this contract on Ethereum Mainnet, Polygon Mainnet, as well as Sepolia and Mumbai testnets at the following addresses:

  • Version 1: 0x0000721C310194CcfC01E523fc93C9cCcFa2A0Ac.
  • Version 2: TBD

The CreatorTokenTransferValidator has the following features:

  • Create, manage, and apply security policies for token transfers
  • Manage whitelists/blacklists
  • Apply different security policies to different collections
  • Control token transfers based on the caller and receiver constraints
  • Use events to track changes in security policies and allowlists

Interact with the deployed contract using the provided functions to create, manage, and apply security policies. A multi-sig such as Gnosis safe is strongly encouraged, and the Gnosis Safe transaction builder can be used to securely manage collections using the following functions.

Security Policy Management
  • applyCollectionTransferPolicy(address caller, address from, address to): Validates a token transfer based on the security policy applied to the collection.
  • setTransferSecurityLevelOfCollection(address collection, TransferSecurityLevels level): Sets the security level of a collection.
  • function getCollectionSecurityPolicyV2(address collection) external view returns (CollectionSecurityPolicyV2 memory);
  • [DEPRECATED/V1] getCollectionSecurityPolicy(address collection): Retrieves the security policy for a given collection.
Whitelist Management
  • function applyListToCollection(address collection, uint120 id) external;

  • function createList(string calldata name) external returns (uint120);

  • function createListCopy(string calldata name, uint120 sourceListId) external returns (uint120);

  • function reassignOwnershipOfList(uint120 id, address newOwner) external;

  • function renounceOwnershipOfList(uint120 id) external;

  • function addAccountsToBlacklist(uint120 id, address[] calldata accounts) external;

  • function addAccountsToWhitelist(uint120 id, address[] calldata accounts) external;

  • function addCodeHashesToBlacklist(uint120 id, bytes32[] calldata codehashes) external;

  • function addCodeHashesToWhitelist(uint120 id, bytes32[] calldata codehashes) external;

  • function removeAccountsFromBlacklist(uint120 id, address[] calldata accounts) external;

  • function removeAccountsFromWhitelist(uint120 id, address[] calldata accounts) external;

  • function removeCodeHashesFromBlacklist(uint120 id, bytes32[] calldata codehashes) external;

  • function removeCodeHashesFromWhitelist(uint120 id, bytes32[] calldata codehashes) external;

  • function getBlacklistedAccounts(uint120 id) external view returns (address[] memory);

  • function getWhitelistedAccounts(uint120 id) external view returns (address[] memory);

  • function getBlacklistedCodeHashes(uint120 id) external view returns (bytes32[] memory);

  • function getWhitelistedCodeHashes(uint120 id) external view returns (bytes32[] memory);

  • function isAccountBlacklisted(uint120 id, address account) external view returns (bool);

  • function isAccountWhitelisted(uint120 id, address account) external view returns (bool);

  • function isCodeHashBlacklisted(uint120 id, bytes32 codehash) external view returns (bool);

  • function isCodeHashWhitelisted(uint120 id, bytes32 codehash) external view returns (bool);

  • function getBlacklistedAccountsByCollection(address collection) external view returns (address[] memory);

  • function getWhitelistedAccountsByCollection(address collection) external view returns (address[] memory);

  • function getBlacklistedCodeHashesByCollection(address collection) external view returns (bytes32[] memory);

  • function getWhitelistedCodeHashesByCollection(address collection) external view returns (bytes32[] memory);

  • function isAccountBlacklistedByCollection(address collection, address account) external view returns (bool);

  • function isAccountWhitelistedByCollection(address collection, address account) external view returns (bool);

  • function isCodeHashBlacklistedByCollection(address collection, bytes32 codehash) external view returns (bool);

  • function isCodeHashWhitelistedByCollection(address collection, bytes32 codehash) external view returns (bool);

  • [DEPRECATED/V1] createOperatorWhitelist(string calldata name): Creates a new operator whitelist.

  • [DEPRECATED/V1] reassignOwnershipOfOperatorWhitelist(uint120 id, address newOwner): Reassigns the ownership of an operator whitelist.

  • [DEPRECATED/V1] renounceOwnershipOfOperatorWhitelist(uint120 id): Renounces ownership of an operator whitelist.

  • [DEPRECATED/V1] setOperatorWhitelistOfCollection(address collection, uint120 id): Sets the operator whitelist for a collection.

  • [DEPRECATED/V1] addOperatorToWhitelist(uint120 id, address operator): Adds an operator to a whitelist.

  • [DEPRECATED/V1] removeOperatorFromWhitelist(uint120 id, address operator): Removes an operator from a whitelist.

  • [DEPRECATED/V1] isOperatorWhitelisted(uint120 id, address operator): Checks if an operator is whitelisted.

  • [DEPRECATED/V1] getWhitelistedOperators(uint120 id): Retrieves the whitelisted operators for a given id.

Events
  • event CreatedList(uint256 indexed id, string name);

  • event AppliedListToCollection(address indexed collection, uint120 indexed id);

  • event ReassignedListOwnership(uint256 indexed id, address indexed newOwner);

  • event AddedAccountToList(ListTypes indexed kind, uint256 indexed id, address indexed account);

  • event AddedCodeHashToList(ListTypes indexed kind, uint256 indexed id, bytes32 indexed codehash);

  • event RemovedAccountFromList(ListTypes indexed kind, uint256 indexed id, address indexed account);

  • event RemovedCodeHashFromList(ListTypes indexed kind, uint256 indexed id, bytes32 indexed codehash);

  • event SetTransferSecurityLevel(address indexed collection, TransferSecurityLevels level);

  • [DEPRECATED/V1] event AddedToAllowlist(AllowlistTypes indexed kind, uint256 indexed id, address indexed account);

  • [DEPRECATED/V1] event CreatedAllowlist(AllowlistTypes indexed kind, uint256 indexed id, string indexed name);

  • [DEPRECATED/V1] event ReassignedAllowlistOwnership(AllowlistTypes indexed kind, uint256 indexed id, address indexed newOwner);

  • [DEPRECATED/V1] event RemovedFromAllowlist(AllowlistTypes indexed kind, uint256 indexed id, address indexed account);

  • [DEPRECATED/V1] event SetAllowlist(AllowlistTypes indexed kind, address indexed collection, uint120 indexed id);

For more information, please refer to the contract code comments and the provided function descriptions.

The CreatorTokenTransferValidator contract defines 7 transfer security levels, each represented by a unique TransferSecurityPolicy. Each policy consists of a combination of caller and receiver constraints to define varying levels of security for token transfers.

Transfer Security Levels Description (V2)
  1. TransferSecurityLevels.Recommended:

    • Caller Constraints: OperatorWhitelistEnableOTC (Over-the-counter)
    • Receiver Constraints: None
    • In this level, the caller must be whitelisted as an operator or the owner of the token. There are no constraints on the receiver. (Default Equivalent To Level Two)
  2. TransferSecurityLevels.One:

    • Caller Constraints: None
    • Receiver Constraints: None
    • This is the most relaxed level of security, allowing any caller to initiate a token transfer to any receiver without any restrictions.
  3. TransferSecurityLevels.Two:

    • Caller Constraints: OperatorBlacklistEnableOTC (Over-the-counter)
    • Receiver Constraints: None
    • In this level, the caller must not be a blacklisted account or have a blacklisted code hash. There are no constraints on the receiver.
  4. TransferSecurityLevels.Three:

    • Caller Constraints: OperatorWhitelistEnableOTC (Over-the-counter)
    • Receiver Constraints: None
    • In this level, the caller must be whitelisted, or the owner of the token. There are no constraints on the receiver.
  5. TransferSecurityLevels.Four:

    • Caller Constraints: OperatorWhitelistDisableOTC
    • Receiver Constraints: None
    • The caller or owner must be whitelisted, and OTC transfers initiated by the token owner are not allowed, unless the token owner is a whitelisted account or has a whitelisted code hash. There are no constraints on the receiver.
  6. TransferSecurityLevels.Five:

    • Caller Constraints: OperatorWhitelistEnableOTC
    • Receiver Constraints: NoCode
    • The caller must be whitelisted, or the owner of the token. The receiver must not have deployed code, which means they cannot be a smart contract. If the receiver does have code, the receiver may receive the token only if the account or code hash is whitelisted.
  7. TransferSecurityLevels.Six:

    • Caller Constraints: OperatorWhitelistEnableOTC
    • Receiver Constraints: EOA (Externally Owned Account)
    • The caller must be whitelisted, or the owner of the token. The receiver must be an EOA, which means they cannot be a smart contract and must have performed a one-time signature verification in the CreatorTokenTransferValidator. If the receiver is not a proven EOA, the receiver may receive the token only if the account or code hash is whitelisted.
  8. TransferSecurityLevels.Seven:

    • Caller Constraints: OperatorWhitelistDisableOTC
    • Receiver Constraints: NoCode
    • The caller must be whitelisted, and OTC transfers initiated by the token owner are not allowed, unless the token owner is a whitelisted account or has a whitelisted code hash. The receiver must not have deployed code, which means they cannot be a smart contract. If the receiver does have code, the receiver may receive the token only if the account or code hash is whitelisted.
  9. TransferSecurityLevels.Eight:

    • Caller Constraints: OperatorWhitelistDisableOTC
    • Receiver Constraints: EOA
    • The caller must be whitelisted, and OTC transfers initiated by the token owner are not allowed, unless the token owner is a whitelisted account or has a whitelisted code hash. The receiver must be an EOA, which means they cannot be a smart contract and must have performed a one-time signature verification in the CreatorTokenTransferValidator. If the receiver is not a proven EOA, the receiver may receive the token only if the account or code hash is whitelisted.

These predefined transfer security levels can be applied to collections to implement varying levels of transfer security based on the collection's requirements.

Transfer Security Levels Description (DEPRECATED/V1)

The following levels only apply to the V1 Transfer Validator.

  1. TransferSecurityLevels.Zero:

    • Caller Constraints: None
    • Receiver Constraints: None
    • This is the most relaxed level of security, allowing any caller to initiate a token transfer to any receiver without any restrictions.
  2. TransferSecurityLevels.One:

    • Caller Constraints: OperatorWhitelistEnableOTC (Over-the-counter)
    • Receiver Constraints: None
    • In this level, the caller must be whitelisted as an operator or the owner of the token. There are no constraints on the receiver.
  3. TransferSecurityLevels.Two:

    • Caller Constraints: OperatorWhitelistDisableOTC
    • Receiver Constraints: None
    • The caller must be whitelisted as an operator, and OTC transfers initiated by the token owner are not allowed. There are no constraints on the receiver.
  4. TransferSecurityLevels.Three:

    • Caller Constraints: OperatorWhitelistEnableOTC
    • Receiver Constraints: NoCode
    • The caller must be whitelisted as an operator or the owner of the token. The receiver must not have deployed code, which means they cannot be a smart contract. Specific contract receivers can optionally be designated in a permitted contract receivers allowlist.
  5. TransferSecurityLevels.Four:

    • Caller Constraints: OperatorWhitelistEnableOTC
    • Receiver Constraints: EOA (Externally Owned Account)
    • The caller must be whitelisted as an operator or the owner of the token. The receiver must be an EOA, which means they cannot be a smart contract and must have performed a one-time signature verification in the CreatorTokenTransferValidator. Specific contract receivers can optionally be designated in a permitted contract receivers allowlist.
  6. TransferSecurityLevels.Five:

    • Caller Constraints: OperatorWhitelistDisableOTC
    • Receiver Constraints: NoCode
    • The caller must be whitelisted as an operator, and OTC transfers initiated by the token owner are not allowed. The receiver must not have deployed code, which means they cannot be a smart contract. Specific contract receivers can optionally be designated in a permitted contract receivers allowlist.
  7. TransferSecurityLevels.Six:

    • Caller Constraints: OperatorWhitelistDisableOTC
    • Receiver Constraints: EOA
    • The caller must be whitelisted as an operator, and OTC transfers initiated by the token owner are not allowed. The receiver must be an EOA, which means they cannot be a smart contract and must have performed a one-time signature verification in the CreatorTokenTransferValidator. Specific contract receivers can optionally be designated in a permitted contract receivers allowlist.

These predefined transfer security levels can be applied to collections to implement varying levels of transfer security based on the collection's requirements.

Disclaimer

It is crucial to thoroughly test the integration of this mixin with your specific marketplace implementation to ensure the security and proper functioning of your platform. This mixin provides a general-purpose solution but may require adjustments or customizations depending on your use case.

Limit Break Curated Whitelist / Blacklist

Limit Break curates the default whitelist that is applied unless a creator opts into a custom whitelist/blacklist. To be considered for the whitelist or to propose a new exchange, teams can reach out to blockchain@limitbreak.com.

Security and License

This project is made available by Limit Break in an effort to provide an open-source functional library of smart contract components to be used by other parties as precedent for individual user’s creation and deployment of smart contracts in the Etherium ecosystem (the “Limit Break Contracts”). Limit Break is committed to following, and has sought to apply, commercially reasonable best practices as it pertains to safety and security in making the Limit Break Contracts publicly available for use as precedent. Nevertheless, smart contracts are a new and emerging technology and carry a high level of technical risk and uncertainty. Despite Limit Break’s commitment and efforts to foster safety and security in their adoption, using the precedent contracts made available by this project is not a substitute for a security audit conducted by the end user. Please report any actual or suspected security vulnerabilities to our team at security@limitbreak.com.

The Limit Break Contracts are made available under the MIT License, which disclaims all warranties in relation to the project and which limits the liability of those that contribute and maintain the project, including Limit Break. As set out further in Limit Break’s Terms of Service, as may be amended and revised from time to time, you acknowledge that you are solely responsible for any use of the Limit Break Contracts and you assume all risks associated with any such use. For the avoidance of doubt, such assumption of risk by the user also implies all risks associated with the legality or related implications tied to the use of smart contracts in any given jurisdiction, whether now known or yet to be determined.

Limit Break's offering of the code in Creator Token Contracts has no bearing on Limit Break's own implementations of programmable royalties.

FAQs

Last updated on 06 Feb 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc