Doppelganger

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

Author: transientlabs.xyz

Sovereign ERC-7160 Editions (Doppelganger) Creator Contract with Story Inscriptions

When unpinned, the latest metadata added for a token is returned from tokenURI and tokenURIs

State Variables

VERSION

String representation of uint256

String representation for address

string public constant VERSION = "3.0.1";

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;

_multiMetadatas

mapping(uint256 => MultiMetadata) private _multiMetadatas;

_tokenUris

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

tx.origin is used in the events here as these can be deployed via contract factories and we want to capture the true sender

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

cannot mint unless at least one token uri has been added to the array

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

Parameters

Name	Type	Description
`recipient`	`address`	The recipient of the token - assumed as able to receive 721 tokens
`<none>`	`string`

mint

Function to mint a single token

cannot mint unless at least one token uri has been added to the array

function mint(address recipient, string calldata, 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
`<none>`	`string`
`royaltyAddress`	`address`
`royaltyPercent`	`uint256`

batchMint

Function to batch mint tokens

cannot mint unless at least one token uri has been added to the array

function batchMint(address recipient, uint128 numTokens, string calldata) 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
`<none>`	`string`

airdrop

Function to airdrop tokens to addresses

cannot mint unless at least one token uri has been added to the array

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

Parameters

Name	Type	Description
`addresses`	`address[]`	Dynamic array of addresses to mint to
`<none>`	`string`

externalMint

Function to allow an approved mint contract to mint

cannot mint unless at least one token uri has been added to the array

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

Parameters

Name	Type	Description
`recipient`	`address`	The recipient of the token - assumed as able to receive 721 tokens
`<none>`	`string`

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

addTokenUris

Function to add token uris

Must be called by contract owner, admin, or approved mint contract

function addTokenUris(string[] calldata tokenUris) external;

Parameters

Name	Type	Description
`tokenUris`	`string[]`	Array of token uris to add

tokenURIs

Get all token uris associated with a particular token

If a token uri is pinned, the index returned SHOULD be the index in the string array

function tokenURIs(uint256 tokenId) external view returns (uint256 index, string[] memory uris, bool pinned);

Parameters

Name	Type	Description
`tokenId`	`uint256`	The identifier for the nft

Returns

Name	Type	Description
`index`	`uint256`	An unisgned integer that specifies which uri is pinned for a token (or the default uri if unpinned)
`uris`	`string[]`	A string array of all uris associated with a token
`pinned`	`bool`	A boolean showing if the token has pinned metadata or not

pinTokenURI

Pin a specific token uri for a particular token

This call MUST revert if the token does not exist

function pinTokenURI(uint256 tokenId, uint256 index) external;

Parameters

Name	Type	Description
`tokenId`	`uint256`	The identifier of the nft
`index`	`uint256`	The index in the string array returned from the `tokenURIs` function that should be pinned for the token

unpinTokenURI

Unpin metadata for a particular token

This call MUST revert if the token does not exist

function unpinTokenURI(uint256 tokenId) external;

Parameters

Name	Type	Description
`tokenId`	`uint256`	The identifier of the nft

hasPinnedTokenURI

Check on-chain if a token id has a pinned uri or not

This call MUST revert if the token does not exist

function hasPinnedTokenURI(uint256 tokenId) external view returns (bool);

Parameters

Name	Type	Description
`tokenId`	`uint256`	The identifier of the nft

Returns

Name	Type	Description
`<none>`	`bool`	pinned A bool specifying if a token has metadata pinned or not

tokenURI

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

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

function approve(address to, uint256 tokenId) public override(ERC721Upgradeable, 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

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

_getBatchInfo

Function to get batch mint info

function _getBatchInfo(uint256 tokenId) internal view returns (address);

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

_ownerOf

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

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

EmptyTokenURIs

No token uris added yet

error EmptyTokenURIs();

MintToZeroAddress

Mint to zero address

error MintToZeroAddress();

BatchSizeTooSmall

Batch size too small

error BatchSizeTooSmall();

AirdropTooFewAddresses

Airdrop to too few addresses

error AirdropTooFewAddresses();

CallerNotApprovedOrOwner

Caller is not approved or owner

error CallerNotApprovedOrOwner();

TokenDoesntExist

Token does not exist

error TokenDoesntExist();

InvalidTokenURIIndex

Index given for ERC-7160 is invalid

error InvalidTokenURIIndex();

NotOwnerAdminOrMintContract

Not owner, admin, or mint contract

error NotOwnerAdminOrMintContract();

CallerNotTokenOwnerOrDelegate

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

error CallerNotTokenOwnerOrDelegate();

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;
}

MultiMetadata

Struct for holding values used in ERC-7160

struct MultiMetadata {
    bool pinned;
    uint256 index;
}