Contracts Data Structures

Below is a clear overview of each major CryptoLegacy contract data structure: purpose, fields, types, relationships, and usage within contracts.

Table of Contents

  1. BeneficiaryRegistry (C1)

    • cryptoLegacyByBeneficiary (C1-V1)

    • cryptoLegacyByOwner (C1-V2)

    • cryptoLegacyByGuardian (C1-V3)

    • cryptoLegacyByRecovery (C1-V4)

    • blockNumberChangesByCryptoLegacy (C1-V5)

  2. BuildManagerOwnable (C2)

    • buildManagerAdded (C2-V1)

  3. CryptoLegacy (C3)

    • (No permanent storage variables.)

  4. CryptoLegacyBuildManager (C4)

    • feeRegistry (C4-V1)

    • pluginsRegistry (C4-V2)

    • beneficiaryRegistry (C4-V3)

    • lifetimeNft (C4-V4)

    • factory (C4-V5)

    • externalLens (C4-V6)

    • minMassMintSupply (C4-V7)

    • REGISTRY_BUILD_CASE (C4-V8)

    • REGISTRY_UPDATE_CASE (C4-V9)

    • REGISTRY_LIFETIME_CASE (C4-V10)

    • cryptoLegacyBuilt (C4-V11)

  5. CryptoLegacyDiamondBase (C5)

    • (No permanent storage variables.)

  6. CryptoLegacyExternalLens (C6)

    • (No permanent storage variables.)

  7. CryptoLegacyFactory (C7)

    • buildOperators (C7-V1)

  8. CryptoLegacyOwnable (C8)

    • (No permanent storage variables.)

  9. FeeRegistry (C9)

    • PCT_BASE (C9-V1)

    • FR_STORAGE_POSITION (C9-V2)

    • (Uses internal struct FRStorage, see Data Types Used.)

  10. LegacyMessenger (C10)

    • messagesGotByBlockNumber (C10-V1)

  11. LifetimeNft (C11)

    • baseURI (C11-V1)

    • minterOperator (C11-V2)

  12. LockChainGate (C12)

    • LCG_STORAGE_POSITION (C12-V1)

    • (Uses internal struct LCGStorage and LockedNft, see Data Types Used.)

  13. MultiPermit (C13)

    • (No permanent storage variables.)

    • (Uses struct PermitData, see Data Types Used.)

  14. PluginsRegistry (C14)

    • pluginsList (C14-V1)

    • pluginDescriptionBlockNumbers (C14-V2)

  15. ProxyBuilder (C15)

    • proxyAdmin (C15-V1)

  16. ProxyBuilderAdmin (C16)

    • (No permanent storage variables.)

  17. SignatureRoleTimelock (C17)

    • maxExecutionPeriod (C17-V1)

    • roleAccounts (C17-V2)

    • signatureRoles (C17-V3)

    • targetSigs (C17-V4)

    • targets (C17-V5)

    • pendingCalls (C17-V6)

    • callsIds (C17-V7)

    • (Uses structs SignatureAttr and CallRequest, see Data Types Used.)

  18. DiamondLoupeFacet (C18)

    • (No permanent storage variables.)

  19. CryptoLegacyBasePlugin (C19)

    • (No permanent storage variables.)

  20. LensPlugin (C20)

    • (No permanent storage variables.)

  21. NftLegacyPlugin (C21)

    • PLUGIN_POSITION (C21-V1)

    • (Uses internal struct PluginStorage and NftBeneficiary, see Data Types Used.)

  22. TrustedGuardiansPlugin (C22)

    • (No permanent storage variables; references a library-based PluginStorage.)

  23. UpdateRolePlugin (C23)

    • PLUGIN_POSITION (C23-V1)

    • (Uses internal struct PluginStorage (UpdateRolePlugin), see Data Types Used.)

BeneficiaryRegistry (C1)

cryptoLegacyByBeneficiary (C1-V1)

Data Type: mapping(bytes32 => EnumerableSet.AddressSet) Description: Maps a beneficiary hash (bytes32) to a dynamic set of CryptoLegacy contract addresses for that beneficiary.

cryptoLegacyByOwner (C1-V2)

Data Type: mapping(bytes32 => EnumerableSet.AddressSet) Description: Tracks CryptoLegacy contract addresses by owner hash (bytes32), allowing quick lookups by the owner’s hashed identity.

cryptoLegacyByGuardian (C1-V3)

Data Type: mapping(bytes32 => EnumerableSet.AddressSet) Description: Maps a guardian hash (bytes32) to a set of CryptoLegacy contracts that reference them as a guardian.

cryptoLegacyByRecovery (C1-V4)

Data Type: mapping(bytes32 => EnumerableSet.AddressSet) Description: Maintains a set of CryptoLegacy contract addresses associated with each recovery hash (bytes32).

blockNumberChangesByCryptoLegacy (C1-V5)

Data Type: mapping(address => uint256[]) Description: Records a history of block numbers whenever a registered CryptoLegacy contract makes certain changes, enabling on-chain event tracing.

BuildManagerOwnable (C2)

buildManagerAdded (C2-V1)

Data Type: EnumerableSet.AddressSet Description: A set of valid “build manager” addresses. The owner controls which addresses get added or removed, indicating which managers can validate the CryptoLegacy contracts.

CryptoLegacy (C3)

(No permanent storage variables.)

CryptoLegacyBuildManager (C4)

feeRegistry (C4-V1)

Data Type: IFeeRegistry (public) Description: Points to the FeeRegistry contract that calculates and collects applicable fees for building or updating CryptoLegacy contracts.

pluginsRegistry (C4-V2)

Data Type: IPluginsRegistry (public) Description: References the PluginsRegistry contract that manages registered plugin addresses and their descriptions.

beneficiaryRegistry (C4-V3)

Data Type: IBeneficiaryRegistry (public) Description: References the BeneficiaryRegistry contract, used for storing and retrieving beneficiary associations to CryptoLegacy contracts.

lifetimeNft (C4-V4)

Data Type: ILifetimeNft (public) Description: The Lifetime NFT contract, which is minted to users to grant lifetime fee exemptions.

factory (C4-V5)

Data Type: ICryptoLegacyFactory (public) Description: A factory contract used to deploy new CryptoLegacy contracts using the CREATE2 pattern.

externalLens (C4-V6)

Data Type: address (public) Description: An external contract address (often a lens or forwarder) that can be utilized by explorers or dashboards to query read-only data.

minMassMintSupply (C4-V7)

Data Type: uint256 (public) Description: The minimum token supply limit required for a mass minting operation of the Lifetime NFT.

REGISTRY_BUILD_CASE (C4-V8)

Data Type: uint8 constant (public) Description: Denotes the case type for “build” fees within the FeeRegistry system.

REGISTRY_UPDATE_CASE (C4-V9)

Data Type: uint8 constant (public) Description: Specifies the case type for “update” fees in the FeeRegistry.

REGISTRY_LIFETIME_CASE (C4-V10)

Data Type: uint8 constant (public) Description: Identifies the case type for a “lifetime” fee scenario (buying the lifetime NFT) in the FeeRegistry.

cryptoLegacyBuilt (C4-V11)

Data Type: mapping(address => bool) (internal) Description: Tracks which CryptoLegacy contract addresses were successfully created (built). The mapping is set after each deployment.

CryptoLegacyDiamondBase (C5)

(No permanent storage variables.)

CryptoLegacyExternalLens (C6)

(No permanent storage variables.)

CryptoLegacyFactory (C7)

buildOperators (C7-V1)

Data Type: EnumerableSet.AddressSet (private) Description: Stores addresses allowed to build new CryptoLegacy contracts via this factory. Managed solely by the factory owner.

CryptoLegacyOwnable (C8)

(No permanent storage variables.)

FeeRegistry (C9)

PCT_BASE (C9-V1)

Data Type: uint32 constant (public) Description: A “percentage base” of 10,000 used for fee calculation denominators (BPS).

FR_STORAGE_POSITION (C9-V2)

Data Type: bytes32 constant (internal) Description: Storage slot identifier used internally to read/write the FRStorage struct data in the contract’s low-level storage.

(Uses internal FRStorage struct to maintain the actual registry data; see Data Types Used.)

LegacyMessenger (C10)

messagesGotByBlockNumber (C10-V1)

Data Type: mapping(bytes32 => uint64[]) (public) Description: Maps a recipient hash (bytes32) to an array of block numbers indicating when messages were logged for that recipient.

LifetimeNft (C11)

baseURI (C11-V1)

Data Type: string (internal) Description: Base URI used to construct token metadata URLs for all minted lifetime NFTs.

minterOperator (C11-V2)

Data Type: mapping(address => bool) (public) Description: Tracks addresses authorized to call mint(...). If set to true, that operator can mint new Lifetime NFT tokens.

LockChainGate (C12)

LCG_STORAGE_POSITION (C12-V1)

Data Type: bytes32 constant (internal) Description: Indicates the specific storage slot for reading and writing the LCGStorage struct used by LockChainGate.

(Relies on LCGStorage struct and LockedNft struct for all internal data; see Data Types Used.)

MultiPermit (C13)

(No permanent storage variables.)

(Uses the PermitData struct; see Data Types Used.)

PluginsRegistry (C14)

pluginsList (C14-V1)

Data Type: EnumerableSet.AddressSet (private) Description: The set of registered plugin addresses. Each plugin can be added/removed by the owner.

pluginDescriptionBlockNumbers (C14-V2)

Data Type: mapping(address => uint64[]) (public) Description: Records a timeline of block numbers at which new descriptions were appended for each plugin.

ProxyBuilder (C15)

proxyAdmin (C15-V1)

Data Type: ProxyAdmin (public) Description: Reference to a ProxyAdmin instance managing upgradeable proxies created by this builder.

ProxyBuilderAdmin (C16)

(No permanent storage variables.)

SignatureRoleTimelock (C17)

maxExecutionPeriod (C17-V1)

Data Type: uint128 (public) Description: Defines the maximum period (in seconds) during which a scheduled call remains valid after its timelock ends.

roleAccounts (C17-V2)

Data Type: mapping(bytes32 => address[]) (public) Description: Records which addresses hold a given role (indexed by the role’s bytes32 identifier).

signatureRoles (C17-V3)

Data Type: mapping(address => mapping(bytes4 => SignatureAttr)) (public) Description: Associates each target contract + function selector with a required role and a timelock duration.

targetSigs (C17-V4)

Data Type: mapping(address => bytes4[]) (public) Description: For each target address, stores the list of function selectors that have assigned signature roles.

targets (C17-V5)

Data Type: address[] (public) Description: Lists all distinct target contract addresses that have at least one assigned signature role.

pendingCalls (C17-V6)

Data Type: mapping(bytes32 => CallRequest) (public) Description: Scheduled calls keyed by a unique ID (keccak-based) storing call details such as target, data, timelock constraints, etc.

callsIds (C17-V7)

Data Type: bytes32[] (public) Description: The ordered list of all scheduled call IDs, allowing iteration over scheduled calls.

(Uses SignatureAttr and CallRequest structs; see Data Types Used.)

DiamondLoupeFacet (C18)

(No permanent storage variables.)

CryptoLegacyBasePlugin (C19)

(No permanent storage variables.)

LensPlugin (C20)

(No permanent storage variables.)

NftLegacyPlugin (C21)

PLUGIN_POSITION (C21-V1)

Data Type: bytes32 constant (public) Description: Indicates the storage slot key used to store the NFT-related plugin data (PluginStorage) in diamond-style or library-based storage.

(Relies on PluginStorage struct and NftBeneficiary struct; see Data Types Used.)

TrustedGuardiansPlugin (C22)

(No permanent storage variables; references a library-based PluginStorage under the hood.)

UpdateRolePlugin (C23)

PLUGIN_POSITION (C23-V1)

Data Type: bytes32 constant (public) Description: The storage slot key used to store the “update role” data (PluginStorage) in diamond-style or library-based storage.

(Relies on an internal PluginStorage struct for storing updaters; see Data Types Used.)

Data Types Used

Below are common or custom-defined data types used by the above contracts.

FRStorage (in FeeRegistry)

  • defaultDiscountPct (uint32) The default discount percentage (in BPS) for referral-based fees, used if no specific code’s discount is set.

  • defaultSharePct (uint32) The default share percentage (in BPS) paid out to referrers, used if no code-specific share is defined.

  • accumulatedFee (uint128) The total native fees collected and currently held by the registry, awaiting withdrawal.

  • supportedRefInChains (EnumerableSet.UintSet) A set of chain IDs where cross-chain referral code features are supported.

  • refererByCode (mapping(bytes8 => Referrer)) Maps a short referral code (bytes8) to a Referrer struct detailing discount/share logic.

  • codeByReferrer (mapping(address => bytes8)) Tracks which referral code belongs to a particular referrer address.

  • codeOperators (EnumerableSet.AddressSet) Addresses permitted to create or manage referral codes.

  • feeByContractCase (mapping(address => mapping(uint8 => uint128))) Multi-level mapping specifying fee amounts for a particular contract address + fee case.

  • feeBeneficiaries (FeeBeneficiary[]) An array listing multiple fee-receiving addresses and the share (in BPS) each should receive on withdrawals.

Referrer (used within FRStorage)

  • owner (address) The primary owner of the referral code.

  • recipient (address) Receives referral share distributions or minted NFTs.

  • discountPct (uint32) A discount percentage for the user when using this referral code (BPS-based).

  • sharePct (uint32) The portion of fees directed to this referrer (BPS-based).

  • accumulatedFee (uint128) The total fees accrued by this referral code that have not yet been withdrawn.

FeeBeneficiary (used within FRStorage)

  • recipient (address) Address that receives a portion of the overall collected fees.

  • sharePct (uint32) The percentage (in BPS) of the total fee allocated to this beneficiary.

LCGStorage (in LockChainGate)

  • deBridgeGate (IDeBridgeGate) Address of the deBridgeGate contract for cross-chain message or asset bridging.

  • deBridgeNativeFee (mapping(uint256 => uint256)) Per-chain mapping of required native fees for cross-chain operations.

  • destinationChainContracts (mapping(uint256 => address)) The LockChainGate contract addresses on each destination chain, keyed by chain ID.

  • sourceChainsContracts (mapping(uint256 => address)) The LockChainGate contract addresses on each source chain, keyed by chain ID.

  • lockOperators (EnumerableSet.AddressSet) Addresses authorized to lock or unlock NFTs cross-chain.

  • lifetimeNft (ILifetimeNft) Reference to the LifetimeNft contract for verifying locked NFTs.

  • lockPeriod (uint256) The required number of seconds an NFT remains locked before it can be unlocked.

  • lockedNft (mapping(address => LockedNft)) Tracks an NFT locked by an owner, referencing the LockedNft struct.

  • ownerOfTokenId (mapping(uint256 => address)) Records which address owns a specific token ID while locked.

  • lockedToChainsIds (mapping(uint256 => EnumerableSet.UintSet)) Lists chains to which a specific NFT token ID is further locked.

  • lockedNftFromChainId (mapping(uint256 => uint256)) For cross-chain locks, stores the originating chain ID where the NFT was first locked.

  • lockedNftApprovedTo (mapping(uint256 => address)) A designated address with permission to unlock or transfer the locked NFT token.

  • referralCode (uint32) A code used for cross-chain referral or fee-tracking in bridging calls.

  • customChainId (uint256) Allows overriding the current chain ID for cross-chain usage in certain environments.

LockedNft (used within LCGStorage)

  • lockedAt (uint256) The timestamp when the NFT was locked.

  • tokenId (uint256) The ID of the locked token.

PermitData (in MultiPermit)

  • token (address) The ERC20 token address to permit.

  • owner (address) Token owner who signed the permit.

  • spender (address) Address approved to spend the tokens.

  • value (uint256) The amount of tokens allowed by this permit.

  • deadline (uint256) The permit’s expiration timestamp.

  • v (uint8) ECDSA signature parameter (recovery byte).

  • r (bytes32) ECDSA signature parameter.

  • s (bytes32) ECDSA signature parameter.

SignatureAttr (in SignatureRoleTimelock)

  • role (bytes32) The role identifier that a caller must hold to execute the specified target + function.

  • timelock (uint128) The delay (in seconds) required after scheduling before the call may be executed.

CallRequest (in SignatureRoleTimelock)

  • caller (address) The address scheduling the call.

  • target (address) The contract address where the call will be executed.

  • data (bytes) Encoded function selector and parameters for the delegated call.

  • executeAfter (uint128) Earliest timestamp when the call can be executed (timelock end).

  • executeBefore (uint128) A deadline timestamp by which the call must be executed.

  • pending (bool) Tracks whether the call is still active or has been executed/canceled.

PluginStorage (in NftLegacyPlugin)

  • nftBeneficiary (mapping(address => mapping(uint256 => NftBeneficiary))) For each NFT contract + token ID, stores the designated NftBeneficiary details.

NftBeneficiary (in NftLegacyPlugin)

  • addressHash (bytes32) The hashed beneficiary address authorized to claim the NFT after distribution.

  • claimDelay (uint64) Time (in seconds) after distribution starts before the NFT can be claimed.

PluginStorage (for TrustedGuardiansPlugin, via LibTrustedGuardiansPlugin)

  • guardians (EnumerableSet.Bytes32Set) A set of addresses (hashed as bytes32) recognized as trusted guardians.

  • guardiansVoted (bytes32[]) List of guardian hashes that have cast a vote for distribution.

  • guardiansThreshold (uint8) Number of votes needed to finalize a distribution start.

  • guardiansChallengeTimeout (uint64) Additional delay (in seconds) appended to the current timestamp when the threshold is met.

PluginStorage (for UpdateRolePlugin)

  • updaters (EnumerableSet.AddressSet) Addresses permitted to perform “update” actions on behalf of the owner (subject to fee payment and time rules).

Other Structs or Types (from ICryptoLegacy or related libraries)

  1. ICryptoLegacy.BeneficiaryConfig Contains claimDelay, vestingPeriod, and shareBps for each beneficiary.

  2. ICryptoLegacy.CryptoLegacyStorage Diamond-style storage for the core CryptoLegacy, referencing many mappings for beneficiaries, tokens, etc.

  3. ICryptoLegacy.TokenDistribution Tracks how much of each token is allocated (amountToDistribute) and how much is already claimed (totalClaimedAmount).

PreviousContracts Functions. Part 2.NextContracts Events

Last updated