IShareXKeysSeries

Inherits: IERC1155

Title: ShareX Keys Series Interface

Author: ShareX Team

ERC1155 interface for ShareX ecosystem NFT collection with whitelist-based minting The ShareX Keys Series consists of three token types representing different access levels:

ESSENTIA (ID: 0): Essential access keys for basic functionality
MAGNA (ID: 1): Enhanced access keys with additional privileges
NOVA (ID: 2): Premium access keys with full ecosystem access Key Features:
Whitelist-based minting with allocation limits per user
Batch operations for efficient gas usage across multiple accounts
Comprehensive mint status tracking for transparency
Role-based access control for administrative functions
Gas-optimized operations using RareSkills patterns Security Considerations:
All administrative functions require DEFAULT_ADMIN_ROLE
Whitelist allocations are immutable once set (must be reset to change)
Mint amounts are validated against remaining allocations
Zero address checks prevent accidental burns Usage Example:

// Set whitelist allocation for a user
keysSeries.setWhitelists(user, 5, 3, 1); // 5 ESSENTIA, 3 MAGNA, 1 NOVA
// User mints their allocation
keysSeries.mint(0, 2); // Mint 2 ESSENTIA tokens
keysSeries.mintAll();   // Mint all remaining tokens
// Check status
(MintStatus memory essentia,,) = keysSeries.getMintStatus(user);
// essentia.remaining == 3

Functions

setWhitelists

Set whitelist allocation for a single account across all token types

Only callable by DEFAULT_ADMIN_ROLE. Overwrites existing allocations.

function setWhitelists(
    address account,
    uint256 essentiaAmount,
    uint256 magnaAmount,
    uint256 novaAmount
) external;

Parameters

Name	Type	Description
`account`	`address`	The address to set allocations for
`essentiaAmount`	`uint256`	Number of ESSENTIA tokens to allocate
`magnaAmount`	`uint256`	Number of MAGNA tokens to allocate
`novaAmount`	`uint256`	Number of NOVA tokens to allocate Requirements: - Caller must have DEFAULT_ADMIN_ROLE - Account cannot be zero address Emits: ShareXKeysWhitelistsSet event

batchSetWhitelists

Set whitelist allocations for multiple accounts in a single transaction

Batch operation for gas efficiency. Only callable by DEFAULT_ADMIN_ROLE.

function batchSetWhitelists(
    address[] calldata accounts,
    uint256[] calldata essentiaAmounts,
    uint256[] calldata magnaAmounts,
    uint256[] calldata novaAmounts
) external;

Parameters

Name	Type	Description
`accounts`	`address[]`	Array of addresses to set allocations for
`essentiaAmounts`	`uint256[]`	Array of ESSENTIA allocations corresponding to accounts
`magnaAmounts`	`uint256[]`	Array of MAGNA allocations corresponding to accounts
`novaAmounts`	`uint256[]`	Array of NOVA allocations corresponding to accounts Requirements: - Caller must have DEFAULT_ADMIN_ROLE - All arrays must have equal length - No account can be zero address - Gas-optimized with unchecked arithmetic for large batches Emits: ShareXKeysBatchWhitelistsSet event

mint

Mint a specific amount of a specific token type

Gas-optimized minting with allocation validation

function mint(uint256 tokenId, uint256 amount) external;

Parameters

Name	Type	Description
`tokenId`	`uint256`	The token type to mint (0=ESSENTIA, 1=MAGNA, 2=NOVA)
`amount`	`uint256`	Number of tokens to mint Requirements: - tokenId must be valid (0, 1, or 2) - amount must be greater than 0 - Caller must have sufficient whitelist allocation - amount must not exceed remaining allocation Emits: ShareXKeysMinted event

mintAll

Mint all remaining tokens across all types for the caller

Batch mint operation that mints the complete remaining allocation Gas-optimized batch minting that:

Automatically detects which tokens have remaining allocation
Mints only tokens with remaining > 0
Uses efficient batch operations for multiple token types Requirements:
Caller must have at least one token with remaining allocation > 0 Emits: ShareXKeysBatchMinted event

function mintAll() external;

getMintStatus

Get detailed minting status for an account across all token types

View function that returns comprehensive allocation and minting statistics

function getMintStatus(address account)
    external
    view
    returns (MintStatus memory essentia, MintStatus memory magna, MintStatus memory nova);

Parameters

Name	Type	Description
`account`	`address`	The address to query status for

Returns

Name	Type	Description
`essentia`	`MintStatus`	Mint status for ESSENTIA tokens (ID: 0)
`magna`	`MintStatus`	Mint status for MAGNA tokens (ID: 1)
`nova`	`MintStatus`	Mint status for NOVA tokens (ID: 2) Each MintStatus contains: - whitelisted: Total allocation for this token type - minted: Already minted amount for this token type - remaining: Available to mint (whitelisted - minted)

getWhitelisted

Get whitelist allocations for an account across all token types

View function for checking total allocations without minting statistics

function getWhitelisted(address account)
    external
    view
    returns (uint256 essentiaAmount, uint256 magnaAmount, uint256 novaAmount);

Parameters

Name	Type	Description
`account`	`address`	The address to query allocations for

Returns

Name	Type	Description
`essentiaAmount`	`uint256`	Total ESSENTIA tokens allocated
`magnaAmount`	`uint256`	Total MAGNA tokens allocated
`novaAmount`	`uint256`	Total NOVA tokens allocated Note: This returns total allocations, not remaining amounts. Use getMintStatus() for remaining allocation information.

setTokenURI

Set the URI for a specific token type

Only callable by DEFAULT_ADMIN_ROLE. Updates token metadata URI.

function setTokenURI(uint256 tokenId, string calldata tokenURI) external;

Parameters

Name	Type	Description
`tokenId`	`uint256`	The token type to set URI for (0=ESSENTIA, 1=MAGNA, 2=NOVA)
`tokenURI`	`string`	The new URI string for the token Requirements: - Caller must have DEFAULT_ADMIN_ROLE - tokenId must be valid (0, 1, or 2) Emits: URI event from ERC1155 standard

Structs

MintStatus

Mint status information for a specific token type

Contains allocation and minting statistics for transparency

struct MintStatus {
    uint256 whitelisted;
    uint256 minted;
    uint256 remaining;
}

Properties

Name	Type	Description
`whitelisted`	`uint256`	Total tokens allocated to the account
`minted`	`uint256`	Total tokens already minted by the account
`remaining`	`uint256`	Tokens remaining to be minted (whitelisted - minted)

Keyboard shortcuts