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

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

Parameters

Name	Type	Description
`name`	`string`	The name of the contract
`symbol`	`string`	The symbol of the 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
`defaultTracersRegistry`	`address`	Address of the TRACERS 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`

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

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

Name	Type	Description
`from`	`address`	The current owner of the token
`to`	`address`	The recipient of the token
`tokenId`	`uint256`	The token to transfer

setTracersRegistry

Function to set a new TRACERS registry

Callable only by owner or admin

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

Parameters

Name	Type	Description
`newTracersRegistry`	`address`	The new TRACERS Registry

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

Name	Type	Description
`tokenIds`	`uint256[]`	The tokens to add a stories to
`stories`	`string[]`	The story text
`signatures`	`bytes[]`	The signtatures from the chip to verify physical presence

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

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

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

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

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

ignores the creator name to avoid sybil

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

Parameters

Name	Type	Description
`<none>`	`uint256`
`<none>`	`string`
`<none>`	`string`

setStoryStatus

Function to enable or disable collector story inscriptions

Requires owner or admin

function setStoryStatus(bool) external pure;

Parameters

Name	Type	Description
`<none>`	`bool`

storyEnabled

Function to get the status of collector stories

function storyEnabled() external pure returns (bool);

Returns

Name	Type	Description
`<none>`	`bool`	bool Status of collector stories being enabled

setBlockListRegistry

Function to change the blocklist registry

Access to owner or admin

function setBlockListRegistry(address) external pure;

Parameters

Name	Type	Description
`<none>`	`address`

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

Name	Type	Description
`<none>`	`address`

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

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

Returns

Name	Type	Description
`<none>`	`string`	string the uri for the tokenId

_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

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