ERC721TL

Git Source

Inherits: ERC721Upgradeable, OwnableAccessControlUpgradeable, EIP2981TLUpgradeable, ICreatorBase, IERC721TL, ISynergy, IStory, IERC4906

Author: transientlabs.xyz

Sovereign ERC-721 Creator Contract with Synergy and Story Inscriptions

State Variables

VERSION

String representation of uint256

String representation for address

string public constant VERSION = "3.1.0";

ADMIN_ROLE

bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");

APPROVED_MINT_CONTRACT

bytes32 public constant APPROVED_MINT_CONTRACT = keccak256("APPROVED_MINT_CONTRACT");

_counter

uint256 private _counter;

storyEnabled

bool public storyEnabled;

tlNftDelegationRegistry

ITLNftDelegationRegistry public tlNftDelegationRegistry;

blocklistRegistry

IBlockListRegistry public blocklistRegistry;

_burned

mapping(uint256 => bool) private _burned;

_proposedTokenUris

mapping(uint256 => string) private _proposedTokenUris;

_tokenUris

mapping(uint256 => string) private _tokenUris;

_batchMints

BatchMint[] private _batchMints;

Functions

constructor

constructor(bool disable);

Parameters

Name	Type	Description
`disable`	`bool`	Boolean to disable initialization for the implementation contract

initialize

function initialize(
    string memory name,
    string memory symbol,
    string memory personalization,
    address defaultRoyaltyRecipient,
    uint256 defaultRoyaltyPercentage,
    address initOwner,
    address[] memory admins,
    bool enableStory,
    address initBlockListRegistry,
    address initNftDelegationRegistry
) external initializer;

Parameters

Name	Type	Description
`name`	`string`	The name of the 721 contract
`symbol`	`string`	The symbol of the 721 contract
`personalization`	`string`	A string to emit as a collection story. Can be ASCII art or something else that is a personalization of the contract.
`defaultRoyaltyRecipient`	`address`	The default address for royalty payments
`defaultRoyaltyPercentage`	`uint256`	The default royalty percentage of basis points (out of 10,000)
`initOwner`	`address`	The owner of the contract
`admins`	`address[]`	Array of admin addresses to add to the contract
`enableStory`	`bool`	A bool deciding whether to add story fuctionality or not
`initBlockListRegistry`	`address`	Address of the blocklist registry to use
`initNftDelegationRegistry`	`address`	Address of the TL nft delegation registry to use

totalSupply

Function to get total supply minted so far

function totalSupply() external view returns (uint256);

setApprovedMintContracts

Function to set approved mint contracts

Access to owner or admin

function setApprovedMintContracts(address[] calldata minters, bool status) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

Name	Type	Description
`minters`	`address[]`	Array of minters to grant approval to
`status`	`bool`	Status for the minters

mint

Function to mint a single token

Requires owner or admin

function mint(address recipient, string calldata uri) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

Name	Type	Description
`recipient`	`address`	The recipient of the token - assumed as able to receive 721 tokens
`uri`	`string`	The token uri to mint

mint

Function to mint a single token

Requires owner or admin

function mint(address recipient, string calldata uri, address royaltyAddress, uint256 royaltyPercent)
    external
    onlyRoleOrOwner(ADMIN_ROLE);

Parameters

Name	Type	Description
`recipient`	`address`	The recipient of the token - assumed as able to receive 721 tokens
`uri`	`string`	The token uri to mint
`royaltyAddress`	`address`
`royaltyPercent`	`uint256`

batchMint

Function to batch mint tokens

Requires owner or admin

function batchMint(address recipient, uint128 numTokens, string calldata baseUri)
    external
    onlyRoleOrOwner(ADMIN_ROLE);

Parameters

Name	Type	Description
`recipient`	`address`	The recipient of the token - assumed as able to receive 721 tokens
`numTokens`	`uint128`	Number of tokens in the batch mint
`baseUri`	`string`	The base uri for the batch, expecting json to be in order, starting at file name 0, and SHOULD NOT have a trailing `/`

airdrop

Function to airdrop tokens to addresses

Requires owner or admin

function airdrop(address[] calldata addresses, string calldata baseUri) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

Name	Type	Description
`addresses`	`address[]`	Dynamic array of addresses to mint to
`baseUri`	`string`	The base uri for the batch, expecting json to be in order, starting at file name 0, and SHOULD NOT have a trailing `/`

externalMint

Function to allow an approved mint contract to mint

Requires the caller to be an approved mint contract

function externalMint(address recipient, string calldata uri) external onlyRole(APPROVED_MINT_CONTRACT);

Parameters

Name	Type	Description
`recipient`	`address`	The recipient of the token - assumed as able to receive 721 tokens
`uri`	`string`	The token uri to mint

burn

Function to burn a token

Caller must be approved or owner of the token

function burn(uint256 tokenId) external;

Parameters

Name	Type	Description
`tokenId`	`uint256`	The token to burn

setDefaultRoyalty

Function to set the default royalty specification

Requires owner or admin

function setDefaultRoyalty(address newRecipient, uint256 newPercentage) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

Name	Type	Description
`newRecipient`	`address`	The new royalty payout address
`newPercentage`	`uint256`	The new royalty percentage in basis (out of 10,000)

setTokenRoyalty

Function to override a token's royalty info

Requires owner or admin

function setTokenRoyalty(uint256 tokenId, address newRecipient, uint256 newPercentage)
    external
    onlyRoleOrOwner(ADMIN_ROLE);

Parameters

Name	Type	Description
`tokenId`	`uint256`	The token to override royalty for
`newRecipient`	`address`	The new royalty payout address for the token id
`newPercentage`	`uint256`	The new royalty percentage in basis (out of 10,000) for the token id

proposeNewTokenUri

Function to propose a token uri update for a specific token

Requires owner or admin

function proposeNewTokenUri(uint256 tokenId, string calldata newUri) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

Name	Type	Description
`tokenId`	`uint256`	The token to propose new metadata for
`newUri`	`string`	The new token uri proposed

acceptTokenUriUpdate

Function to accept a proposed token uri update for a specific token

Requires owner of the token or delegate to call the function

function acceptTokenUriUpdate(uint256 tokenId) external;

Parameters

Name	Type	Description
`tokenId`	`uint256`	The token to accept the metadata update for

rejectTokenUriUpdate

Function to reject a proposed token uri update for a specific token

Requires owner of the token or delegate to call the function

function rejectTokenUriUpdate(uint256 tokenId) external;

Parameters

Name	Type	Description
`tokenId`	`uint256`	The token to reject the metadata update for

tokenURI

See {IERC721Metadata-tokenURI}.

function tokenURI(uint256 tokenId) public view override(ERC721Upgradeable) returns (string memory);

addCollectionStory

Function to let the creator add a story to the collection they have created

Depending on the implementation, this function may be restricted in various ways, such as limiting the number of times the creator may write a story.

function addCollectionStory(string calldata, string calldata story) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

Name	Type	Description
`<none>`	`string`
`story`	`string`	The story written and attached to the token id

addCreatorStory

Function to let the creator add a story to any token they have created

Depending on the implementation, this function may be restricted in various ways, such as limiting the number of times the creator may write a story.

function addCreatorStory(uint256 tokenId, string calldata, string calldata story)
    external
    onlyRoleOrOwner(ADMIN_ROLE);

Parameters

Name	Type	Description
`tokenId`	`uint256`	The token id to which the story is attached
`<none>`	`string`
`story`	`string`	The story written and attached to the token id

addStory

Function to let collectors add a story to any token they own

Depending on the implementation, this function may be restricted in various ways, such as limiting the number of times a collector may write a story.

function addStory(uint256 tokenId, string calldata, string calldata story) external;

Parameters

Name	Type	Description
`tokenId`	`uint256`	The token id to which the story is attached
`<none>`	`string`
`story`	`string`	The story written and attached to the token id

setStoryStatus

Function to enable or disable collector story inscriptions

Requires owner or admin

function setStoryStatus(bool status) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

Name	Type	Description
`status`	`bool`	The status to set for collector story inscriptions

setBlockListRegistry

Function to change the blocklist registry

Access to owner or admin

function setBlockListRegistry(address newBlockListRegistry) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

Name	Type	Description
`newBlockListRegistry`	`address`	The new blocklist registry

approve

See {IERC721-approve}.

function approve(address to, uint256 tokenId) public override(ERC721Upgradeable, IERC721);

setApprovalForAll

See {IERC721-setApprovalForAll}.

function setApprovalForAll(address operator, bool approved) public override(ERC721Upgradeable, IERC721);

setNftDelegationRegistry

Function to change the TL NFT delegation registry

Access to owner or admin

function setNftDelegationRegistry(address newNftDelegationRegistry) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

Name	Type	Description
`newNftDelegationRegistry`	`address`	The new blocklist registry

supportsInterface

Query if a contract implements an interface

Interface identification is specified in ERC-165. This function uses less than 30,000 gas.

function supportsInterface(bytes4 interfaceId)
    public
    view
    override(ERC721Upgradeable, EIP2981TLUpgradeable, IERC165)
    returns (bool);

Parameters

Name	Type	Description
`interfaceId`	`bytes4`

Returns

Name	Type	Description
`<none>`	`bool`	`true` if the contract implements `interfaceID` and `interfaceID` is not 0xffffffff, `false` otherwise

_getBatchInfo

Function to get batch mint info

function _getBatchInfo(uint256 tokenId) internal view returns (address, string memory);

Parameters

Name	Type	Description
`tokenId`	`uint256`	Token id to look up for batch mint info

Returns

Name	Type	Description
`<none>`	`address`	adress The token owner
`<none>`	`string`	string The uri for the tokenId

_ownerOf

Function to override { ERC721Upgradeable._ownerOf } to allow for batch minting

Returns the owner of the tokenId. Does NOT revert if token doesn't exist IMPORTANT: Any overrides to this function that add ownership of tokens not tracked by the core ERC721 logic MUST be matched with the use of {_increaseBalance} to keep balances consistent with ownership. The invariant to preserve is that for any address a the value returned by balanceOf(a) must be equal to the number of tokens such that _ownerOf(tokenId) is a.

function _ownerOf(uint256 tokenId) internal view override(ERC721Upgradeable) returns (address);

_exists

Function to check if a token exists

function _exists(uint256 tokenId) internal view returns (bool);

Parameters

Name	Type	Description
`tokenId`	`uint256`	The token id to check

_isTokenOwnerOrDelegate

Function to get if msg.sender is the token owner or delegated owner

function _isTokenOwnerOrDelegate(uint256 tokenId) internal view returns (bool);

_isOperatorBlocked

function _isOperatorBlocked(address operator) internal view returns (bool);

Errors

EmptyTokenURI

Token uri is an empty string

error EmptyTokenURI();

MintToZeroAddress

Mint to zero address

error MintToZeroAddress();

BatchSizeTooSmall

Batch size too small

error BatchSizeTooSmall();

AirdropTooFewAddresses

Airdrop to too few addresses

error AirdropTooFewAddresses();

CallerNotTokenOwnerOrDelegate

Caller is not the owner or delegate of the owner of the specific token

error CallerNotTokenOwnerOrDelegate();

CallerNotApprovedOrOwner

Caller is not approved or owner

error CallerNotApprovedOrOwner();

TokenDoesntExist

Token does not exist

error TokenDoesntExist();

NoTokenUriUpdateAvailable

No proposed token uri to change to

error NoTokenUriUpdateAvailable();

OperatorBlocked

Operator for token approvals blocked

error OperatorBlocked();

StoryNotEnabled

Story not enabled for collectors

error StoryNotEnabled();

Structs

BatchMint

Struct defining a batch mint

struct BatchMint {
    address creator;
    uint256 fromTokenId;
    uint256 toTokenId;
    string baseUri;
}