Transient Labs Creator Contracts

A repository for Transient Labs Creator Contracts

Deployments

See https://docs.transientlabs.xyz/tl-creator-contracts/implementation for latest deployments

Core Features

Ownership & Access

We have implemented the OwnableAccessControlUpgradeable contract from tl-sol-tools and have created custom admin and mint contract priviledges. Admins are able to perform actions on behalf of the creator (contract owner). Approved mint contracts are allowed to mint NFTs or metadata (ERC7160TL).

Creator Royalties

EIP-2981 is used as it is the on-chain royalty specification used to return a royalty payout address and the royalty amount to pay based on the sale price.

For each contract, there is a default royalty specification set that can be altered if needed. There are also individual token overrides in case of collaboration or anything like that.

BlockList

A feature that allows creators to block operators, such as marketplaces, from getting approved on the contract. setApprovalForAll and approve will fail for any blocked addresses.

Story Inscriptions

The ability to add human provenance to the blockchain to fully tell the story behind a token. See more here

NFT Delegation Integration

There are NFT delegation protocols in use today, such as delegate.xyz, and more coming. Our creator contrats (ERC-721 based) have the ability to integrate with a delegation registry that aggregates and checks against popular delegation protocols. Right now, that is just delegate.xyz, but can expand to include others as well.

We only use NFT delegation for NFT ownership utility that does not affect ownership. So this means that NFT delegation is not used for transfers and approvals. It is used for features like

• story inscriptions
• multi-metadata pinning & unpinning
• Synergy metadata updates

ERC721TL

Our core ERC-721 creator contract.

Synergy

This mechanism protects collectors from having token metadata changed on them unexpectedly. Artists need to be able to update metadata in certain situations, but collectors should have a right to review these changes after they have bought the piece. This is what Synergy allows; the collector must sign a transaction allowing the metadata to be updated.

Airdrops

Allows creators to airdrop tokens to a list of addresses.

Batch Minting

Allows creators to cheaply batch mint tokens to their wallet.

Testing shows our implementation is market leading: view here

ERC7160TL

Our implementation of ERC-7160. This brings multiple pieces of metadata to NFTs and allows token holders to pin or unpin metadata as they please. Only the contract owner/admin have the ability to add metadata for a token.

Airdrops

Allows creators to airdrop tokens to a list of addresses.

Batch Minting

Allows creators to cheaply batch mint tokens to their wallet.

Testing shows our implementation is market leading: view here

Doppelganger

An implementation of ERC-7160 but with a focus on editions. Rather than have multiple pieces of metadata per token, like in ERC7160TL, there is a contract-wide metadata array from which token holders can choose to pin. This allows for immense flexibility and gas efficiency for ERC-721 editions.

It shares similar features with ERC7160TL.

Collector's Choice

A variant of Doppelganger that allows the creator to set a cutoff time, after which, all pinning and unpinning actions by token holders are blocked. This essentially freezes the metadata and can be use for interesting gameification.

Shatter

Allows a 1/1 token to be shattered into many tokens, that can either be an edition or more 1/1 tokens. Later, all the tokens can be fused back into the 1/1 if the tokens are all owned by the same address.

Shares many similar features to ERC721TL.

Proxy Deployments

We use immutable ERC-1167 proxies for creators to deploy contracts in a cheap and immutable way. ERC-1967 proxies can also be used.

Running Tests

1. Install foundry
2. Run make install or make update
3. Run forge test (optionally can adjust the fuzz runs via the flag --fuzz-runs <number>)

Building InitCode for the TL Universal Deployer

1. Navigate the the contract type you want to deploy
2. Look at the initialize function to see the function signature
3. Run cast calldata "<function-signature-here>" <constructor-args-here>

Example: cast calldata "initialize(string,string,string,address,uint256,address,address[],bool,address)" "The Enchanted Hour" "RK" "" 0x77B35947d508012589a91CA4c9d168824376Cc7D 1000 0x77B35947d508012589a91CA4c9d168824376Cc7D "[]" true 0x77B35947d508012589a91CA4c9d168824376Cc7D

See more about cast calldata here.

Disclaimer

This codebase is provided on an "as is" and "as available" basis.

We do not give any warranties and will not be liable for any loss incurred through any use of this codebase.

License

This code is copyright Transient Labs, Inc 2023 and is licensed under the MIT license.

Contents

• ERC1155TL
• IERC1155TL

ERC1155TL

Git Source

Inherits: ERC1155Upgradeable, EIP2981TLUpgradeable, OwnableAccessControlUpgradeable, ICreatorBase, IERC1155TL, IStory

Author: transientlabs.xyz

Sovereign ERC-1155 Creator Contract with Story Inscriptions

State Variables

VERSION

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;

name

string public name;

symbol

string public symbol;

storyEnabled

bool public storyEnabled;

blocklistRegistry

IBlockListRegistry public blocklistRegistry;

_tokens

mapping(uint256 => Token) private _tokens;

Functions

constructor

constructor(bool disable);

Parameters

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
) external initializer;

Parameters

totalSupply

Function to get total supply minted so far

function totalSupply() external view returns (uint256);

getTokenDetails

Function to get token creation details

function getTokenDetails(uint256 tokenId) external view returns (Token memory);

Parameters

setApprovedMintContracts

Function to set approved mint contracts

Access to owner or admin

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

Parameters

createToken

Function to create a token that can be minted to creator or airdropped

Requires owner or admin

function createToken(string calldata newUri, address[] calldata addresses, uint256[] calldata amounts)
    external
    onlyRoleOrOwner(ADMIN_ROLE);

Parameters

createToken

Function to create a token that can be minted to creator or airdropped

Requires owner or admin

function createToken(
    string calldata newUri,
    address[] calldata addresses,
    uint256[] calldata amounts,
    address royaltyAddress,
    uint256 royaltyPercent
) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

batchCreateToken

function to batch create tokens that can be minted to creator or airdropped

requires owner or admin

function batchCreateToken(string[] calldata newUris, address[][] calldata addresses, uint256[][] calldata amounts)
    external
    onlyRoleOrOwner(ADMIN_ROLE);

Parameters

batchCreateToken

function to batch create tokens that can be minted to creator or airdropped

requires owner or admin

function batchCreateToken(
    string[] calldata newUris,
    address[][] calldata addresses,
    uint256[][] calldata amounts,
    address[] calldata royaltyAddresses,
    uint256[] calldata royaltyPercents
) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

mintToken

Function to mint existing token to recipients

Requires owner or admin

function mintToken(uint256 tokenId, address[] calldata addresses, uint256[] calldata amounts)
    external
    onlyRoleOrOwner(ADMIN_ROLE);

Parameters

externalMint

External mint function

Requires caller to be an approved mint contract

function externalMint(uint256 tokenId, address[] calldata addresses, uint256[] calldata amounts)
    external
    onlyRole(APPROVED_MINT_CONTRACT);

Parameters

burn

Function to burn tokens from an account

Msg.sender must be token owner or operator

function burn(address from, uint256[] calldata tokenIds, uint256[] calldata amounts) external;

Parameters

setDefaultRoyalty

Function to set the default royalty specification

Requires owner or admin

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

Parameters

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

setTokenUri

Function to set a token uri

Requires owner or admin

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

Parameters

uri

function uri(uint256 tokenId) public view override(ERC1155Upgradeable) 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

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

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

setStoryStatus

Function to enable or disable collector story inscriptions

Requires owner or admin

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

Parameters

setBlockListRegistry

Function to change the blocklist registry

Access to owner or admin

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

Parameters

setApprovalForAll

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

tlNftDelegationRegistry

Function to get the delegation registry

function tlNftDelegationRegistry() external pure returns (ITLNftDelegationRegistry);

setNftDelegationRegistry

Function to change the TL NFT delegation registry

Access to owner or admin

function setNftDelegationRegistry(address) external pure;

Parameters

supportsInterface

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

_exists

Private helper function to verify a token exists

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

Parameters

_createToken

Private helper function to create a new token

function _createToken(string memory newUri, address[] memory addresses, uint256[] memory amounts)
    private
    returns (uint256);

Parameters

Returns

_mintToken

Private helper function

function _mintToken(uint256 tokenId, address[] calldata addresses, uint256[] calldata amounts) private;

Parameters

_isOperatorBlocked

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

Errors

EmptyTokenURI

Token uri is an empty string

error EmptyTokenURI();

BatchSizeTooSmall

Batch size too small

error BatchSizeTooSmall();

MintToZeroAddresses

Mint to zero addresses

error MintToZeroAddresses();

ArrayLengthMismatch

Array length mismatch

error ArrayLengthMismatch();

CallerNotTokenOwner

Token not owned by the owner of the contract

error CallerNotTokenOwner();

CallerNotApprovedOrOwner

Caller is not approved or owner

error CallerNotApprovedOrOwner();

TokenDoesntExist

Token does not exist

error TokenDoesntExist();

BurnZeroTokens

Burning zero tokens

error BurnZeroTokens();

OperatorBlocked

Operator for token approvals blocked

error OperatorBlocked();

StoryNotEnabled

Story not enabled for collectors

error StoryNotEnabled();

IERC1155TL

Git Source

Author: transientlabs.xyz

Interface for ERC1155TL

Interface id = 0x452d5a4a

Functions

getTokenDetails

Function to get token creation details

function getTokenDetails(uint256 tokenId) external view returns (Token memory);

Parameters

createToken

Function to create a token that can be minted to creator or airdropped

Requires owner or admin

function createToken(string calldata newUri, address[] calldata addresses, uint256[] calldata amounts) external;

Parameters

createToken

Function to create a token that can be minted to creator or airdropped

Overloaded function where you can set the token royalty config in this tx

Requires owner or admin

function createToken(
    string calldata newUri,
    address[] calldata addresses,
    uint256[] calldata amounts,
    address royaltyAddress,
    uint256 royaltyPercent
) external;

Parameters

batchCreateToken

function to batch create tokens that can be minted to creator or airdropped

requires owner or admin

function batchCreateToken(string[] calldata newUris, address[][] calldata addresses, uint256[][] calldata amounts)
    external;

Parameters

batchCreateToken

Function to batch create tokens that can be minted to creator or airdropped

Overloaded function where you can set the token royalty config in this tx

Requires owner or admin

function batchCreateToken(
    string[] calldata newUris,
    address[][] calldata addresses,
    uint256[][] calldata amounts,
    address[] calldata royaltyAddresses,
    uint256[] calldata royaltyPercents
) external;

Parameters

mintToken

Function to mint existing token to recipients

Requires owner or admin

function mintToken(uint256 tokenId, address[] calldata addresses, uint256[] calldata amounts) external;

Parameters

externalMint

External mint function

Requires caller to be an approved mint contract

function externalMint(uint256 tokenId, address[] calldata addresses, uint256[] calldata amounts) external;

Parameters

burn

Function to burn tokens from an account

Msg.sender must be token owner or operator

If this function is called from another contract as part of a burn/redeem, the contract must ensure that no amount is '0' or if it is, that it isn't a vulnerability.

function burn(address from, uint256[] calldata tokenIds, uint256[] calldata amounts) external;

Parameters

setTokenUri

Function to set a token uri

Requires owner or admin

function setTokenUri(uint256 tokenId, string calldata newUri) external;

Parameters

Structs

Token

Struct defining a token

struct Token {
    bool created;
    string uri;
}

Contents

• multi-metadata
• shatter
• trace
• ERC721TL
• IERC721TL

Contents

• CollectorsChoice
• Doppelganger
• ERC7160TL

CollectorsChoice

Git Source

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

Author: transientlabs.xyz

Sovereign ERC-7160 Editions with a metadata lock timer (Collectors Choice) 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;

cutoffTime

uint256 public cutoffTime;

_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

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

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

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

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

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

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

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

burn

Function to burn a token

Caller must be approved or owner of the token

function burn(uint256 tokenId) external;

Parameters

setDefaultRoyalty

Function to set the default royalty specification

Requires owner or admin

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

Parameters

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

setCutoffTime

Function to set the cutoff time for the contract

Must be called by the contract owner oor admin

function setCutoffTime(uint256 time) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

addTokenUris

Function to add token uris

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

function addTokenUris(string[] calldata tokenUris) external;

Parameters

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

Returns

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

unpinTokenURI

Unpin metadata for a particular token

This call MUST revert if the token does not exist

function unpinTokenURI(uint256 tokenId) external;

Parameters

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

Returns

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

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

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

setStoryStatus

Function to enable or disable collector story inscriptions

Requires owner or admin

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

Parameters

setBlockListRegistry

Function to change the blocklist registry

Access to owner or admin

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

Parameters

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

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

Returns

_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

_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);

Events

CutoffTimeSet

Cutoff Time Set

event CutoffTimeSet(address indexed sender, uint256 indexed time);

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();

CutoffTimeAlreadySet

Cutoff time set and can't set again

error CutoffTimeAlreadySet();

PastCutoffTime

Past cutoff time

error PastCutoffTime();

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

Doppelganger

Git Source

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

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

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

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

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

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

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

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

burn

Function to burn a token

Caller must be approved or owner of the token

function burn(uint256 tokenId) external;

Parameters

setDefaultRoyalty

Function to set the default royalty specification

Requires owner or admin

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

Parameters

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

addTokenUris

Function to add token uris

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

function addTokenUris(string[] calldata tokenUris) external;

Parameters

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

Returns

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

unpinTokenURI

Unpin metadata for a particular token

This call MUST revert if the token does not exist

function unpinTokenURI(uint256 tokenId) external;

Parameters

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

Returns

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

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

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

setStoryStatus

Function to enable or disable collector story inscriptions

Requires owner or admin

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

Parameters

setBlockListRegistry

Function to change the blocklist registry

Access to owner or admin

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

Parameters

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

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

Returns

_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

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

ERC7160TL

Git Source

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

Author: transientlabs.xyz

Sovereign ERC-7160 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;

_tokenUris

mapping(uint256 => string) private _tokenUris;

_multiMetadatas

mapping(uint256 => MultiMetadata) private _multiMetadatas;

_multiMetadataBaseUris

string[] private _multiMetadataBaseUris;

_batchMints

BatchMint[] private _batchMints;

Functions

constructor

constructor(bool disable);

Parameters

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

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

mint

Function to mint a single token

Requires owner or admin

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

Parameters

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

batchMint

Function to batch mint tokens

Requires owner or admin

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

Parameters

airdrop

Function to airdrop tokens to addresses

Requires owner or admin

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

Parameters

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

burn

Function to burn a token

Caller must be approved or owner of the token

function burn(uint256 tokenId) external;

Parameters

setDefaultRoyalty

Function to set the default royalty specification

Requires owner or admin

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

Parameters

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

addTokenUris

Function to add token uris

Written to take in many token ids and a base uri that contains metadata files with file names matching the index of each token id in the tokenIds array (aka folderIndex)

No trailing slash on the base uri

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

function addTokenUris(uint256[] calldata tokenIds, string calldata baseUri) external;

Parameters

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

Returns

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

unpinTokenURI

Unpin metadata for a particular token

This call MUST revert if the token does not exist

function unpinTokenURI(uint256 tokenId) external;

Parameters

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

Returns

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

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

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

setStoryStatus

Function to enable or disable collector story inscriptions

Requires owner or admin

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

Parameters

setBlockListRegistry

Function to change the blocklist registry

Access to owner or admin

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

Parameters

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

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, string memory);

Parameters

Returns

_ownerOf

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

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

_getMintedMetadataUri

internal function to get original metadata uri from mint

function _getMintedMetadataUri(uint256 tokenId) internal view returns (string memory uri);

_getMultiMetadataUri

internal function to help get metadata from multi-metadata struct

function _getMultiMetadataUri(MultiMetadata memory multiMetadata, uint256 index)
    internal
    view
    returns (string memory uri);

Parameters

_exists

Function to check if a token exists

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

Parameters

_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();

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();

NoTokensSpecified

No tokens in tokenIds array

error NoTokensSpecified();

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

MetadataLoc

Struct for specifying base uri index and folder index

struct MetadataLoc {
    uint128 baseUriIndex;
    uint128 folderIndex;
}

MultiMetadata

Struct for holding additional metadata used in ERC-7160

struct MultiMetadata {
    bool pinned;
    uint256 index;
    MetadataLoc[] metadataLocs;
}

Contents

• IShatter
• Shatter

IShatter

Git Source

Author: transientlabs.xyz

interface defining the Shatter standard Interface id = 0xf2528cbb

Functions

mint

Function for minting the 1/1

Requires contract owner or admin

Requires that shatters is equal to 0 -> meaning no piece has been minted

function mint(address recipient, string memory uri, uint128 min, uint128 max, uint256 time) external;

Parameters

shatter

function to shatter the 1/1 token

*care should be taken to ensure that the following conditions are met

• this function can only be called once
• msg.sender actually owns the 1/1 token
• the token has not been shattered yet
• block.timestamp is past the shatter time (if applicable)
• numShatters is an allowed value as set by the creator*

function shatter(uint128 numShatters) external;

Parameters

fuse

function to fuse shatters back into a 1/1

*care should be taken to ensure that the following conditions are met

• this function can only be called once
• the 1/1 is actually shattered
• msg.sender actually owns all of the shatters*

function fuse() external;

Events

Shattered

event Shattered(address indexed user, uint256 indexed numShatters, uint256 indexed shatteredTime);

Fused

event Fused(address indexed user, uint256 indexed fuseTime);

Shatter

Git Source

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

Author: transientlabs.xyz

Sovereign Shatter Creator Contract with Synergy and Story Inscriptions

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");

isShattered

bool public isShattered;

isFused

bool public isFused;

storyEnabled

bool public storyEnabled;

tlNftDelegationRegistry

ITLNftDelegationRegistry public tlNftDelegationRegistry;

blocklistRegistry

IBlockListRegistry public blocklistRegistry;

minShatters

uint128 public minShatters;

maxShatters

uint128 public maxShatters;

shatters

uint128 public shatters;

shatterTime

uint256 public shatterTime;

_shatterAddress

address private _shatterAddress;

_baseUri

string private _baseUri;

_proposedTokenUris

mapping(uint256 => string) private _proposedTokenUris;

_tokenUris

mapping(uint256 => string) private _tokenUris;

Functions

constructor

constructor(bool disable);

Parameters

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

totalSupply

function to get total supply of tokens on the contract

function totalSupply() external view returns (uint256);

setApprovedMintContracts

Function to set approved mint contracts

Access to owner or admin

function setApprovedMintContracts(address[] calldata, bool) external pure;

Parameters

mint

Function for minting the 1/1

Requires contract owner or admin

function mint(address recipient, string memory uri, uint128 min, uint128 max, uint256 time)
    external
    onlyRoleOrOwner(ADMIN_ROLE);

Parameters

shatter

function to shatter the 1/1 token

*care should be taken to ensure that the following conditions are met

• this function can only be called once
• msg.sender actually owns the 1/1 token
• the token has not been shattered yet
• block.timestamp is past the shatter time (if applicable)
• numShatters is an allowed value as set by the creator*

function shatter(uint128 numShatters) external;

Parameters

fuse

function to fuse shatters back into a 1/1

*care should be taken to ensure that the following conditions are met

• this function can only be called once
• the 1/1 is actually shattered
• msg.sender actually owns all of the shatters*

function fuse() external;

setDefaultRoyalty

function to set the default royalty specification

requires owner

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

Parameters

setTokenRoyalty

function to override a token's royalty info

requires owner

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

Parameters

proposeNewTokenUri

function to propose a token uri update for a specific token

requires owner

if the owner of the contract is the owner of the token, the change takes hold right away

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

Parameters

acceptTokenUriUpdate

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

requires owner of the token to call the function

function acceptTokenUriUpdate(uint256 tokenId) external;

Parameters

rejectTokenUriUpdate

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

requires owner of the token to call the function

function rejectTokenUriUpdate(uint256 tokenId) external;

Parameters

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

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

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

setStoryStatus

Function to enable or disable collector story inscriptions

Requires owner or admin

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

Parameters

setBlockListRegistry

Function to change the blocklist registry

Access to owner or admin

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

Parameters

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

supportsInterface

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

_ownerOf

function to override { ERC721Upgradeable._ownerOf } to allow for batch minting/shatter

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

_exists

Function to check if a token exists

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

Parameters

_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();

AlreadyMinted

already minted the first token and can't mint another token to this contract

error AlreadyMinted();

NotShattered

not shattered

error NotShattered();

IsShattered

token is shattered

error IsShattered();

IsFused

token is fused

error IsFused();

CallerNotTokenOwner

caller is not the owner of the specific token

error CallerNotTokenOwner();

CallerDoesNotOwnAllTokens

caller does not own all shatters for fusing

error CallerDoesNotOwnAllTokens();

InvalidNumShatters

number shatters requested is invalid

error InvalidNumShatters();

CallPriorToShatterTime

calling shatter prior to shatter time

error CallPriorToShatterTime();

NoTokenUriUpdateAvailable

no proposed token uri to change to

error NoTokenUriUpdateAvailable();

TokenDoesntExist

token does not exist

error TokenDoesntExist();

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();

Contents

• ITRACE
• TRACE

ITRACE

Git Source

Author: transientlabs.xyz

Interface for TRACE

Interface id = 0xcfec4f64

Functions

mint

Function to mint a single token

Requires owner or admin

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

Parameters

mint

Function to mint a single token with specific token royalty

Requires owner or admin

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

Parameters

airdrop

Function to airdrop tokens to addresses

Requires owner or admin

Utilizes batch mint token uri values to save some gas but still ultimately mints individual tokens to people

The baseUri folder should have the same number of json files in it as addresses in addresses

The baseUri folder should have files named without any file extension

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

Parameters

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;

Parameters

transferToken

Function to transfer token to another wallet

Callable only by owner or admin

Useful if a chip fails or an alteration damages a chip in some way

function transferToken(address from, address to, uint256 tokenId) external;

Parameters

setTracersRegistry

Function to set a new TRACERS registry

Callable only by owner or admin

function setTracersRegistry(address newTracersRegistry) external;

Parameters

addVerifiedStory

Function to write stories for tokens

Requires that the passed signature is signed by the token owner, which is the ARX Halo Chip (physical)

Uses EIP-712 for the signature

function addVerifiedStory(uint256[] calldata tokenIds, string[] calldata stories, bytes[] calldata signatures)
    external;

Parameters

setTokenUri

Function to update a token uri for a specific token

Requires owner or admin

function setTokenUri(uint256 tokenId, string calldata newUri) external;

Parameters

Events

TRACERSRegistryUpdated

event TRACERSRegistryUpdated(
    address indexed sender, address indexed oldTracersRegistry, address indexed newTracersRegistry
);

TRACE

Git Source

Inherits: ERC721Upgradeable, OwnableAccessControlUpgradeable, EIP2981TLUpgradeable, EIP712Upgradeable, ICreatorBase, ITRACE, IStory, IERC4906

Author: transientlabs.xyz

Sovereign T.R.A.C.E. Creator Contract allowing for digital Certificates of Authenticity backed by the blockchain

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");

tracersRegistry

ITRACERSRegistry public tracersRegistry;

_counter

uint256 private _counter;

_tokenUris

mapping(uint256 => string) private _tokenUris;

_verifiedStoryHashUsed

mapping(bytes32 => bool) private _verifiedStoryHashUsed;

_batchMints

BatchMint[] private _batchMints;

Functions

constructor

constructor(bool disable);

Parameters

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,
    address defaultTracersRegistry
) external initializer;

Parameters

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

mint

Function to mint a single token

Requires owner or admin

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

Parameters

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

airdrop

Function to airdrop tokens to addresses

Requires owner or admin

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

Parameters

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

transferToken

Function to transfer token to another wallet

Callable only by owner or admin

function transferToken(address from, address to, uint256 tokenId) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

setTracersRegistry

Function to set a new TRACERS registry

Callable only by owner or admin

function setTracersRegistry(address newTracersRegistry) external onlyRoleOrOwner(ADMIN_ROLE);

Parameters

addVerifiedStory

Function to write stories for tokens

Requires that the passed signature is signed by the token owner, which is the ARX Halo Chip (physical)

function addVerifiedStory(uint256[] calldata tokenIds, string[] calldata stories, bytes[] calldata signatures)
    external;

Parameters

setDefaultRoyalty

Function to set the default royalty specification

Requires owner or admin

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

Parameters

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

setTokenUri

Function to update a token uri for a specific token

Requires owner or admin

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

Parameters

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

ignores the creator name to avoid sybil

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

Parameters

addCreatorStory

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

ignores the creator name to avoid sybil

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

Parameters

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, string calldata, string calldata) external pure;

Parameters

setStoryStatus

Function to enable or disable collector story inscriptions

Requires owner or admin

function setStoryStatus(bool) external pure;

Parameters

storyEnabled

Function to get the status of collector stories

function storyEnabled() external pure returns (bool);

Returns

setBlockListRegistry

Function to change the blocklist registry

Access to owner or admin

function setBlockListRegistry(address) external pure;

Parameters

blocklistRegistry

Function to get the blocklist registry

function blocklistRegistry() external pure returns (IBlockListRegistry);

setNftDelegationRegistry

Function to change the TL NFT delegation registry

Access to owner or admin

function setNftDelegationRegistry(address) external pure;

Parameters

tlNftDelegationRegistry

Function to get the delegation registry

function tlNftDelegationRegistry() external pure returns (ITLNftDelegationRegistry);

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 (string memory);

Parameters

Returns

_exists

Function to check if a token exists

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

Parameters

_addVerifiedStory

Function to add a verified story in a reusable way

function _addVerifiedStory(uint256 tokenId, string memory story, bytes memory signature) internal;

_hashVerifiedStory

Function to hash the typed data

function _hashVerifiedStory(address nftContract, uint256 tokenId, string memory story)
    internal
    pure
    returns (bytes32);

Errors

EmptyTokenURI

Token uri is an empty string

error EmptyTokenURI();

AirdropTooFewAddresses

Airdrop to too few addresses

error AirdropTooFewAddresses();

TokenDoesntExist

Token does not exist

error TokenDoesntExist();

VerifiedStoryAlreadyWritten

Verified story already written for token

error VerifiedStoryAlreadyWritten();

ArrayLengthMismatch

Array length mismatch

error ArrayLengthMismatch();

InvalidSignature

Invalid signature

error InvalidSignature();

Unauthorized

Unauthorized to add a verified story

error Unauthorized();

Structs

BatchMint

Struct defining a batch mint - used for airdrops

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

VerifiedStory

Struct for verified story & signed EIP-712 message

struct VerifiedStory {
    address nftContract;
    uint256 tokenId;
    string story;
}

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

_proposedTokenUris

mapping(uint256 => string) private _proposedTokenUris;

_tokenUris

mapping(uint256 => string) private _tokenUris;

_batchMints

BatchMint[] private _batchMints;

Functions

constructor

constructor(bool disable);

Parameters

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

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

mint

Function to mint a single token

Requires owner or admin

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

Parameters

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

batchMint

Function to batch mint tokens

Requires owner or admin

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

Parameters

airdrop

Function to airdrop tokens to addresses

Requires owner or admin

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

Parameters

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

burn

Function to burn a token

Caller must be approved or owner of the token

function burn(uint256 tokenId) external;

Parameters

setDefaultRoyalty

Function to set the default royalty specification

Requires owner or admin

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

Parameters

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

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

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

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

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

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

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

setStoryStatus

Function to enable or disable collector story inscriptions

Requires owner or admin

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

Parameters

setBlockListRegistry

Function to change the blocklist registry

Access to owner or admin

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

Parameters

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

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, string memory);

Parameters

Returns

_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

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

IERC721TL

Git Source

Author: transientlabs.xyz

Interface for ERC721TL

Interface id = 0xc74089ae

Functions

mint

Function to mint a single token

Requires owner or admin

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

Parameters

mint

Function to mint a single token with specific token royalty

Requires owner or admin

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

Parameters

batchMint

Function to batch mint tokens

Requires owner or admin

The baseUri folder should have the same number of json files in it as numTokens

The baseUri folder should have files named without any file extension

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

Parameters

airdrop

Function to airdrop tokens to addresses

Requires owner or admin

Utilizes batch mint token uri values to save some gas but still ultimately mints individual tokens to people

The baseUri folder should have the same number of json files in it as addresses in addresses

The baseUri folder should have files named without any file extension

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

Parameters

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;

Parameters

burn

Function to burn a token

Caller must be approved or owner of the token

function burn(uint256 tokenId) external;

Parameters

Contents

• IBlockListRegistry
• ICreatorBase
• IERC7160
• IStory
• ISynergy
• ITLNftDelegationRegistry
• ITRACERSRegistry

IBlockListRegistry

Git Source

Author: transientlabs.xyz

Interface for the BlockListRegistry Contract

Functions

getBlockListStatus

Function to get blocklist status with True meaning that the operator is blocked

function getBlockListStatus(address operator) external view returns (bool);

Parameters

setBlockListStatus

Function to set the block list status for multiple operators

Must be called by the blockList owner

function setBlockListStatus(address[] calldata operators, bool status) external;

Parameters

clearBlockList

Function to clear the block list status

Must be called by the blockList owner

function clearBlockList() external;

Events

BlockListStatusChange

event BlockListStatusChange(address indexed user, address indexed operator, bool indexed status);

BlockListCleared

event BlockListCleared(address indexed user);

ICreatorBase

Git Source

Author: transientlabs.xyz

Base interface for creator contracts

Interface id = 0x1c8e024d

Functions

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;

Parameters

setBlockListRegistry

Function to change the blocklist registry

Access to owner or admin

function setBlockListRegistry(address newBlockListRegistry) external;

Parameters

blocklistRegistry

Function to get the blocklist registry

function blocklistRegistry() external view returns (IBlockListRegistry);

setNftDelegationRegistry

Function to change the TL NFT delegation registry

Access to owner or admin

function setNftDelegationRegistry(address newNftDelegationRegistry) external;

Parameters

tlNftDelegationRegistry

Function to get the delegation registry

function tlNftDelegationRegistry() external view returns (ITLNftDelegationRegistry);

setDefaultRoyalty

Function to set the default royalty specification

Requires owner or admin

function setDefaultRoyalty(address newRecipient, uint256 newPercentage) external;

Parameters

setTokenRoyalty

Function to override a token's royalty info

Requires owner or admin

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

Parameters

setStoryStatus

Function to enable or disable collector story inscriptions

Requires owner or admin

function setStoryStatus(bool status) external;

Parameters

storyEnabled

Function to get the status of collector stories

function storyEnabled() external view returns (bool);

Returns

Events

StoryStatusUpdate

Event for changing the story status

event StoryStatusUpdate(address indexed sender, bool indexed status);

BlockListRegistryUpdate

Event for changing the BlockList registry

event BlockListRegistryUpdate(
    address indexed sender, address indexed prevBlockListRegistry, address indexed newBlockListRegistry
);

NftDelegationRegistryUpdate

Event for changing the NFT Delegation registry

event NftDelegationRegistryUpdate(
    address indexed sender, address indexed prevNftDelegationRegistry, address indexed newNftDelegationRegistry
);

IERC7160

Git Source

The ERC-165 identifier for this interface is 0x06e1bc5b.

Functions

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

This call MUST revert if the token does not exist

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

Parameters

Returns

pinTokenURI

Pin a specific token uri for a particular token

This call MUST revert if the token does not exist

This call MUST emit a TokenUriPinned event

This call MAY emit a MetadataUpdate event from ERC-4096

function pinTokenURI(uint256 tokenId, uint256 index) external;

Parameters

unpinTokenURI

Unpin metadata for a particular token

This call MUST revert if the token does not exist

This call MUST emit a TokenUriUnpinned event

This call MAY emit a MetadataUpdate event from ERC-4096

It is up to the developer to define what this function does and is intentionally left open-ended

function unpinTokenURI(uint256 tokenId) external;

Parameters

hasPinnedTokenURI

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

This call MUST revert if the token does not exist

Useful for on-chain mechanics that don't require the tokenURIs themselves

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

Parameters

Returns

Events

TokenUriPinned

This event emits when a token uri is pinned and is useful for indexing purposes.

event TokenUriPinned(uint256 indexed tokenId, uint256 indexed index);

TokenUriUnpinned

This event emits when a token uri is unpinned and is useful for indexing purposes.

event TokenUriUnpinned(uint256 indexed tokenId);

IStory

Git Source

Author: transientlabs.xyz

Interface id: 0x2464f17b

Previous interface id that is still supported: 0x0d23ecb9

Functions

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.

This function MUST emit the CollectionStory event each time it is called

This function MUST implement logic to restrict access to only the creator

function addCollectionStory(string calldata creatorName, string calldata story) external;

Parameters

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.

This function MUST emit the CreatorStory event each time it is called

This function MUST implement logic to restrict access to only the creator

This function MUST revert if a story is written to a non-existent token

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

Parameters