Contracts

Below is a clear overview of each major CryptoLegacy smart contract: its purpose, inheritance, key methods, events, and external interactions.

Table of Contents

1. BeneficiaryRegistry

2. BuildManagerOwnable

3. CryptoLegacy

4. CryptoLegacyBuildManager

5. CryptoLegacyDiamondBase

6. CryptoLegacyExternalLens

7. CryptoLegacyFactory

8. CryptoLegacyOwnable

9. FeeRegistry

10. LegacyMessenger

11. LifetimeNft

12. LockChainGate

13. MultiPermit

14. PluginsRegistry

15. ProxyBuilder

16. ProxyBuilderAdmin

17. SignatureRoleTimelock

18. Flags (Library)

19. IBeneficiaryRegistry (Interface)

20. IBuildManagerOwnable (Interface)

21. ICallProxy (Interface)

22. ICryptoLegacy (Interface)

23. ICryptoLegacyBuildManager (Interface)

24. ICryptoLegacyDiamondBase (Interface)

25. ICryptoLegacyFactory (Interface)

26. ICryptoLegacyLens (Interface)

27. ICryptoLegacyOwnable (Interface)

28. ICryptoLegacyPlugin (Interface)

29. ICryptoLegacyUpdaterPlugin (Interface)

30. IDeBridgeGate (Interface)

31. IDiamondCut (Interface)

32. IDiamondLoupe (Interface)

33. IFeeRegistry (Interface)

34. ILockChainGate (Interface)

35. ILegacyMessenger (Interface)

36. ILido (Interface)

37. ILifetimeNft (Interface)

38. IPluginsRegistry (Interface)

39. ISafeMinimalMultisig (Interface)

40. ISignatureRoleTimelock (Interface)

41. ITrustedGuardiansPlugin (Interface)

42. DiamondLoupeFacet

43. LibCreate2Deploy (Library)

44. LibCryptoLegacy (Library)

45. LibCryptoLegacyPlugins (Library)

46. LibDiamond (Library)

47. LibSafeMinimalBeneficiaryMultisig (Library)

48. LibSafeMinimalMultisig (Library)

49. LibTrustedGuardiansPlugin (Library)

50. BeneficiaryPluginAddRights

51. LegacyRecoveryPlugin

52. CryptoLegacyBasePlugin

53. LensPlugin

54. NftLegacyPlugin

55. TrustedGuardiansPlugin

56. UpdateRolePlugin

---

1. BeneficiaryRegistry

Purpose

• Maintains mappings between role-based hashes (beneficiary, owner, guardian, recovery) and contract addresses (referred to as “CryptoLegacy” contracts).

• Records the block numbers at which changes are made.

• Ensures only valid “CryptoLegacy” contracts (as checked by BuildManagerOwnable) can register or remove themselves.

Inheritance

• Inherits from IBeneficiaryRegistry (interface)

• Inherits from BuildManagerOwnable (for ownership and validation logic)

Key Methods

• Registration / Removal: setCryptoLegacyBeneficiary, setCryptoLegacyGuardian, setCryptoLegacyOwner, setCryptoLegacyRecoveryAddresses.

• Lookup: getCryptoLegacyListBy* functions to retrieve contract lists by hash.

• Block Tracking: _setBlockNumberChange stores the block number each time a contract updates its registration.

All Functions

• constructor(address _owner) (public)

  • Sets the initial owner of the contract via _transferOwnership.

• _setBlockNumberChange(address _cryptoLegacy) (internal)

  • Appends the current block number to blockNumberChangesByCryptoLegacy[_cryptoLegacy] if not already appended in this block.

• setCryptoLegacyBeneficiary(bytes32 _beneficiary, bool _isAdd) (external)

  • Adds or removes the calling contract (msg.sender) under the specified _beneficiary hash.

  • Emits AddCryptoLegacyForBeneficiary or RemoveCryptoLegacyForBeneficiary.

• setCryptoLegacyGuardian(bytes32 _guardian, bool _isAdd) (external)

  • Adds or removes the calling contract under the _guardian hash.

  • Emits AddCryptoLegacyForGuardian or RemoveCryptoLegacyForGuardian.

• setCryptoLegacyOwner(bytes32 _owner, bool _isAdd) (external)

  • Adds or removes the calling contract under the _owner hash.

  • Emits AddCryptoLegacyForOwner or RemoveCryptoLegacyForOwner.

• setCryptoLegacyRecoveryAddresses(bytes32[] memory _oldRecoveryHashes, bytes32[] memory _newRecoveryHashes) (external)

  • Removes the calling contract from old recovery hashes and adds it under new recovery hashes.

  • Emits AddCryptoLegacyForRecovery and RemoveCryptoLegacyForRecovery events.

• getCryptoLegacyListByBeneficiary(bytes32 _hash) (public view)

  • Returns an array of registered contract addresses under the _hash for a beneficiary.

• getCryptoLegacyListByOwner(bytes32 _hash) (public view)

  • Returns an array of registered contract addresses under the _hash for an owner.

• getCryptoLegacyListByGuardian(bytes32 _hash) (public view)

  • Returns an array of registered contract addresses under the _hash for a guardian.

• getCryptoLegacyListByRecovery(bytes32 _hash) (public view)

  • Returns an array of registered contract addresses under the _hash for recovery.

• getCryptoLegacyBlockNumberChanges(address _cryptoLegacy) (public view)

  • Returns the list of recorded block numbers for a specific CryptoLegacy contract address.

• getAllCryptoLegacyListByRoles(bytes32 _hash) (public view)

  • Returns four arrays of addresses associated with the provided _hash for beneficiary, owner, guardian, and recovery.

Events

(Emitted within this contract, though declared in IBeneficiaryRegistry.)

• AddCryptoLegacyForBeneficiary(bytes32, address)

• RemoveCryptoLegacyForBeneficiary(bytes32, address)

• AddCryptoLegacyForGuardian(bytes32, address)

• RemoveCryptoLegacyForGuardian(bytes32, address)

• AddCryptoLegacyForOwner(bytes32, address)

• RemoveCryptoLegacyForOwner(bytes32, address)

• AddCryptoLegacyForRecovery(bytes32, address)

• RemoveCryptoLegacyForRecovery(bytes32, address)

Interacts With

• BuildManagerOwnable: _checkBuildManagerValid enforces that only valid contracts can call registry functions.

• IBeneficiaryRegistry: Implements interface functions/events.

• OpenZeppelin’s EnumerableSet library for storing and managing sets of addresses.

• “CryptoLegacy” contracts that register themselves under various hashes.

---

2. BuildManagerOwnable

Purpose

• Manages a list of valid build managers for CryptoLegacy contracts.

• Ensures only registered build managers can build or register new CryptoLegacy instances.

• Extends OpenZeppelin’s Ownable to restrict administrative functions to the contract owner.

Inheritance

• Inherits from:

  • IBuildManagerOwnable

  • Ownable

Key Methods

• setBuildManager(...): Allows the owner to add or remove build manager addresses.

• _checkBuildManagerValid(...): Validates a CryptoLegacy contract’s build manager.

All Functions

• constructor()

  • Calls Ownable() constructor to set the initial owner of this contract.

• setBuildManager(address _buildManager, bool _isAdd) external onlyOwner

  • Adds or removes _buildManager from the set of valid build managers.

  • Emits AddBuildManager(_buildManager) if _isAdd is true.

  • Emits RemoveBuildManager(_buildManager) if _isAdd is false.

• _checkBuildManagerValid(address _cryptoLegacy, address _clOwner) internal view

  • Internal function to ensure _cryptoLegacy was built by a valid build manager.

  • Checks:

    • If _clOwner != address(0), verifies _cryptoLegacy owner is _clOwner.

    • Verifies _cryptoLegacy is registered in its own build manager.

    • Confirms that this build manager is in the local buildManagerAdded set.

  • Reverts on failure with relevant errors.

• getBuildManagerAdded() external view returns (address[] memory)

  • Returns an array of all currently valid build managers.

Events

• AddBuildManager(address indexed buildManager)

  • Emitted when a build manager is added.

• RemoveBuildManager(address indexed buildManager)

  • Emitted when a build manager is removed.

Errors

• NotTheOwnerOfCryptoLegacy()

  • Reverts if the specified _cryptoLegacy is not owned by the expected owner.

• CryptoLegacyNotRegistered()

  • Reverts if _cryptoLegacy is not registered with its own build manager.

• BuildManagerNotAdded()

  • Reverts if the build manager for _cryptoLegacy is not found in buildManagerAdded.

Interacts With

• ICryptoLegacy: Used to check ownership and build manager of the CryptoLegacy contract.

• ICryptoLegacyBuildManager: Invoked to confirm a CryptoLegacy contract is registered.

• OpenZeppelin’s Ownable: Provides ownership control for administrative functions.

• OpenZeppelin’s EnumerableSet: Tracks valid build managers in a set.

---

3. CryptoLegacy

Purpose

• Main contract orchestrating Diamond Standard capabilities and ownership logic.

• Implements a decentralized inheritance/asset recovery system with plugin architecture.

Inheritance

• CryptoLegacyDiamondBase (base contract for diamond functionality).

• CryptoLegacyOwnable (for owner-based access control).

Key Methods

• Constructor: Initializes build manager, sets ownership, and adds initial plugins.

• replacePlugin: Removes old plugins and adds new ones.

• addPluginList: Adds new plugins.

• removePluginList: Removes specified plugins.

• externalLens: Retrieves external lens address from the build manager.

All Functions

• Constructor

  • Signature: constructor(address _buildManager, address _owner, address[] memory _plugins)

  • Description:

    • Sets the build manager.

    • Records the lastUpdateAt timestamp.

    • Establishes contract ownership.

    • Adds initial plugin addresses.

• replacePlugin(address[] memory _oldPlugins, address[] memory _newPlugins)

  • Visibility: external

  • Description:

    • Removes a list of old plugins.

    • Adds a list of new plugins.

    • Restricted by onlyOwner.

• addPluginList(address[] memory _plugins)

  • Visibility: external

  • Description:

    • Adds multiple plugin addresses to the contract.

    • Restricted by onlyOwner.

• removePluginList(address[] memory _plugins)

  • Visibility: external

  • Description:

    • Removes multiple plugin addresses from the contract.

    • Restricted by onlyOwner.

• externalLens()

  • Visibility: external view

  • Description:

    • Returns the address of the external lens from the build manager.

• Fallback/Receive:

  • (No fallback or receive function explicitly defined.)

Events

• (No custom events are declared within this contract. Ownership events might be inherited from CryptoLegacyOwnable.)

Interacts With

• CryptoLegacyDiamondBase for diamond functionality.

• CryptoLegacyOwnable for ownership restrictions.

• LibDiamond, LibCryptoLegacy, LibCryptoLegacyPlugins for internal logic.

• ICryptoLegacyBuildManager to fetch configuration details (e.g., externalLens).

• ICryptoLegacyPlugin references when adding/removing plugins.

---

4. CryptoLegacyBuildManager

Purpose

• Main contract to manage building and deploying new CryptoLegacy instances.

• Manages fees, referral codes, lifetime NFTs, and registry interactions.

Inheritance

• Inherits Ownable.

• Implements ICryptoLegacyBuildManager (as indicated by override).

• Uses EnumerableSet.

Key Methods

• Building new CryptoLegacy contracts (buildCryptoLegacy).

• Paying fees, creating or updating referral codes (payFee, createRef, createCustomRef, etc.).

• Minting and locking Lifetime NFTs (_mintAndLockLifetimeNft).

• Setting or updating various registries.

All Functions

Below is every function in CryptoLegacyBuildManager (including constructor, internal, external, public, and receive):

1. Constructor

   • Initializes registry contracts, factory, NFT contract, and ownership.

2. receive() (external, payable)

   • Special function to accept Ether transfers without data.

3. setRegistries(IFeeRegistry _feeRegistry, IPluginsRegistry _pluginsRegistry, IBeneficiaryRegistry _beneficiaryRegistry) (external, onlyOwner)

   • Updates the registry contracts.

4. _setRegistries(IFeeRegistry _feeRegistry, IPluginsRegistry _pluginsRegistry, IBeneficiaryRegistry _beneficiaryRegistry) (internal)

   • Internal logic for updating registry references. Emits SetRegistries.

5. setFactory(ICryptoLegacyFactory _factory) (external, onlyOwner)

   • Sets the factory contract address.

6. _setFactory(ICryptoLegacyFactory _factory) (internal)

   • Internal logic for updating the factory. Emits SetFactory.

7. setSupplyLimit(uint256 _newVal) (external, onlyOwner)

   • Sets the minimum supply limit for Lifetime NFT mass mint. Emits SetSupplyLimit.

8. setExternalLens(address _externalLens) (external, onlyOwner)

   • Updates external lens address. Emits SetExternalLens.

9. withdrawFee(address payable _recipient, uint256 _amount) (external, onlyOwner)

   • Withdraws fee balance from contract. Emits WithdrawFee.

10. payFee(bytes8 _code, address _toHolder, uint256 _mul, uint256[] memory _lockToChainIds, uint256[] memory _crossChainFees) (external, payable)

    • Public method to pay fee for updates or other use-cases. Internally calls _payFee.

11. _payFee(bytes8 _code, address _toHolder, uint8 _feeCase, uint256 _mul, uint256 _subValue, uint256[] memory _chainIds, uint256[] memory _crossChainFees) (internal)

    • Internal function to calculate and collect fee. Might switch to lifetime fee case if enough Ether is provided.

12. _checkFee(uint256 _value, uint256 _fee) (internal, pure)

    • Ensures the sent Ether is not below the required fee. Reverts with IncorrectFee.

13. _mintAndLockLifetimeNft(address _tokenOwner, uint256[] memory _chainIds, uint256[] memory _crossChainFees, uint256 _valueToSend) (internal)

    • Mints a Lifetime NFT and locks it for cross-chain usage.

14. payInitialFee(bytes8 _code, address _toHolder, uint256[] memory _lockToChainIds, uint256[] memory _crossChainFees) (public, payable)

    • Pays the initial build fee (or lifetime fee if sufficient Ether) for a new CryptoLegacy contract.

15. payForMultipleLifetimeNft(bytes8 _code, LifetimeNftMint[] memory _lifetimeNftMints) (public, payable)

    • Mints multiple Lifetime NFTs if total supply is above minMassMintSupply. Checks and takes lifetime fee in bulk. Emits PaidForMint for each NFT and PaidForMultipleNft.

16. createCustomRef(bytes8 _customRefCode, address _recipient, uint256[] memory _chainIds, uint256[] memory _crossChainFees) returns (bytes8 refCode, uint256 crossChainFee) (public, payable)

    • Creates a custom referral code. Calculates cross-chain fee, checks payment, calls feeRegistry.createCustomCode. Emits CreateCustomRef.

17. createRef(address _recipient, uint256[] memory _chainIds, uint256[] memory _crossChainFees) returns (bytes8 refCode, uint256 crossChainFee) (public, payable)

    • Creates a referral code (short, generated style). Similar logic to createCustomRef. Emits CreateRef.

18. updateCrossChainsRef(uint256[] memory _chainIds, uint256[] memory _crossChainFees) returns(uint256 crossChainFee) (external, payable)

    • Updates cross-chain referral parameters. Checks fee. Calls feeRegistry.updateCrossChainsRef. Emits SetCrossChainsRef.

19. _createRefAndPayForBuild(BuildArgs memory _buildArgs, RefArgs memory _refArgs) internal returns(uint256 initialFeeToPay, uint256 updateFee)

    • Internal helper. Optionally creates referral code and then retrieves/pays the build fee.

20. buildCryptoLegacy(BuildArgs memory _buildArgs, RefArgs memory _refArgs, ICryptoLegacyFactory.Create2Args memory _create2Args) public payable returns(address payable)

    • Main function to create a new CryptoLegacy contract.

    • Pays fees, validates build arguments, deploys via factory, initializes the new contract. Emits Build.

21. _checkBuildArgs(BuildArgs memory _buildArgs) internal virtual

    • Validates timeouts (e.g., must be 180 days and 90 days). Reverts with NotValidTimeout.

22. _getAndPayBuildFee(bytes8 _invitedByRefCode, uint256 _subValue, uint256[] memory _chainIds, uint256[] memory _crossChainFees) internal returns(uint256 initialFeeToPay, uint256 updateFee)

    • Internal logic to determine the build fee, possibly zero if the caller’s lifetime NFT is locked.

23. getUpdateFee(bytes8 _refCode) external view returns(uint256)

    • Returns the update fee for a given referral code from the fee registry.

24. getAndPayBuildFee(bytes8 _invitedByRefCode) public payable returns(uint256 initialFeeToPay, uint256 updateFee)

    • Public wrapper for _getAndPayBuildFee with no subValue and default arrays.

25. calculateCrossChainCreateRefFee(uint256[] memory _chainIds, uint256[] memory _crossChainFees) public view returns(uint256 totalFee)

    • Calculates total native fee for cross-chain referral creation. Calls into ILockChainGate if needed.

26. getFactoryAddress() external override view returns(address)

    • Returns address of the current factory contract.

27. isLifetimeNftLocked(address _owner) public view returns(bool)

    • Checks if a lifetime NFT is locked for a specific owner.

28. isLifetimeNftLockedAndUpdate(address _owner) public returns(bool)

    • Similar to isLifetimeNftLocked, but updates state if needed.

29. isPluginRegistered(address _plugin) external view returns(bool)

    • Queries pluginsRegistry to check if a plugin is registered.

30. isCryptoLegacyBuilt(address _cryptoLegacy) external view returns(bool)

    • Checks if a given CryptoLegacy contract was built by this build manager.

Events

• SetRegistries(address _feeRegistry, address _pluginsRegistry, address _beneficiaryRegistry) Emitted when registry addresses are updated.

• SetFactory(address _factory) Emitted when the factory address is updated.

• SetSupplyLimit(uint256 _newVal) Emitted when the minimum supply limit for Lifetime NFT mass mint is changed.

• SetExternalLens(address _newVal) Emitted when the external lens address is changed.

• WithdrawFee(address recipient, uint256 amount) Emitted when fees are withdrawn from the contract.

• PaidForMint(address indexed payer, uint256 tokenId, address indexed toHolder) Emitted each time a single Lifetime NFT is minted through payForMultipleLifetimeNft.

• PaidForMultipleNft(address indexed payer, bytes8 refCode, uint256 amountPaid, uint256 totalMinted) Emitted after multiple Lifetime NFTs are minted in one transaction.

• CreateCustomRef(address indexed from, bytes8 refCode, address indexed recipient, uint256[] chainIds) Emitted when a custom referral code is created.

• CreateRef(address indexed from, bytes8 refCode, address indexed recipient, uint256[] chainIds) Emitted when a standard referral code is created.

• SetCrossChainsRef(address indexed from, uint256[] chainIds) Emitted when cross-chain referral parameters are updated.

• Build(address indexed from, address indexed deployedAt, address[] plugins, bytes32[] beneficiaryHashes, bytes32[] beneficiaryConfig, bool usedLifetime, uint256 updateInterval, uint256 challengeTimeout) Emitted when a new CryptoLegacy contract is successfully deployed.

Errors

• IncorrectFee(uint256 expected) Thrown if the provided fee is insufficient compared to the expected fee.

• BellowMinimumSupply(uint256 requiredMinSupply) Thrown if payForMultipleLifetimeNft is attempted while total supply is below the minimum allowed.

• NotValidTimeout() Thrown if the specified timeouts in build arguments do not match expected values.

Interacts With

• feeRegistry (IFeeRegistry) for fee calculations and referrals.

• pluginsRegistry (IPluginsRegistry) to check plugin registration status.

• beneficiaryRegistry (IBeneficiaryRegistry) to record or update beneficiary data.

• lifetimeNft (ILifetimeNft) for minting and managing Lifetime NFTs.

• factory (ICryptoLegacyFactory) to deploy new CryptoLegacy contracts.

• ILockChainGate (acquired via feeRegistry) for locking Lifetime NFTs cross-chain.

---

5. CryptoLegacyDiamondBase

Purpose

• A base contract that implements a fallback function to delegate calls to various facets in accordance with the Diamond Standard (EIP-2535).

• Provides dynamic resolution of function selectors, including caching the facet address once discovered, and handles static call checks.

Inheritance

• Implements ICryptoLegacyDiamondBase

• Inherits DiamondLoupeFacet

Key Methods

• Fallback Delegation: Forwards calls to the appropriate facet using a delegatecall.

• Static Call Checker: Detects static calls vs. normal transactions and reverts if needed.

All Functions

• constructor: (Implicit, not explicitly declared in snippet)

  • Default constructor behavior (since not shown, typically uses Solidity defaults).

• staticCallChecker() (external)

  • Checks if the current call originates from the contract itself.

  • Reverts with NotSelfCall if msg.sender is not this contract.

  • Emits StaticCallCheck on success.

• fallback() (external payable)

  • Retrieves the facet address from Diamond Storage based on the function selector (msg.sig).

  • If no facet is found, tries a low-gas call to staticCallChecker() to detect if the call is static.

  • If a facet is subsequently found via LibCryptoLegacyPlugins._findFacetBySelector and the call is not static, it caches the discovered facet.

  • Reverts with FunctionNotExists if no facet is found for the selector.

  • Uses inline assembly to delegate the call and bubble up any revert messages.

Events

• StaticCallCheck()

  • Emitted when a static call check passes successfully (called from staticCallChecker).

Errors

• NotSelfCall()

  • Thrown if staticCallChecker is not invoked by the contract itself.

• FunctionNotExists(bytes4 selector)

  • Thrown if the fallback cannot find a suitable facet for the given function selector.

Interacts With

• LibDiamond for retrieving and storing facet addresses.

• LibCryptoLegacyPlugins for additional plugin-based facet lookups.

• DiamondLoupeFacet for standard DiamondLoupe features.

• Implements the ICryptoLegacyDiamondBase interface.

---

6. CryptoLegacyExternalLens

Purpose

• Forwards various “getter” calls to a designated CryptoLegacy diamond contract or its plugins.

• Avoids duplicating logic by calling into existing contracts and interfaces.

Inheritance

• Inherits directly from contract (no explicit parent contract in the snippet).

• No additional interfaces are implemented within this file.

Key Methods

• Provides external view functions that retrieve or aggregate data from the target _cryptoLegacy address.

• Offers utility functions to fetch both basic contract state (owner, paused status, etc.) and more complex data (beneficiaries, tokens distribution, vested/claimed information).

All Functions

External/Public

1. isLifetimeActive(address _cryptoLegacy) external view returns (bool)

   • Checks whether the lifetime of the _cryptoLegacy instance is still active.

2. isPaused(address _cryptoLegacy) external view returns (bool)

   • Determines if the _cryptoLegacy instance is paused.

3. buildManager(address _cryptoLegacy) external view returns (address)

   • Retrieves the address of the buildManager from the _cryptoLegacy contract.

4. owner(address _cryptoLegacy) external view returns (address)

   • Returns the owner address of the _cryptoLegacy contract.

5. updateInterval(address _cryptoLegacy) external view returns (uint64)

   • Gets the update interval from the _cryptoLegacy plugin (LensPlugin).

6. challengeTimeout(address _cryptoLegacy) external view returns (uint64)

   • Retrieves the challenge timeout value from the LensPlugin.

7. distributionStartAt(address _cryptoLegacy) external view returns (uint64)

   • Returns the timestamp at which distribution starts.

8. lastFeePaidAt(address _cryptoLegacy) external view returns (uint64)

   • Fetches the timestamp when the last fee was paid.

9. lastUpdateAt(address _cryptoLegacy) external view returns (uint64)

   • Gets the timestamp of the last update made to the _cryptoLegacy instance.

10. initialFeeToPay(address _cryptoLegacy) external view returns (uint128)

    • Retrieves the initial fee required.

11. updateFee(address _cryptoLegacy) external view returns (uint128)

    • Returns the current update fee.

12. invitedByRefCode(address _cryptoLegacy) external view returns (bytes8)

    • Fetches the referral code that was used to invite the owner to the _cryptoLegacy instance.

13. getBeneficiaries(address _cryptoLegacy) external view returns (bytes32[] memory hashes, bytes32[] memory originalHashes, ICryptoLegacy.BeneficiaryConfig[] memory configs)

    • Retrieves the beneficiaries’ hashes and configuration data.

14. getTokensDistribution(address _cryptoLegacy, address[] calldata _tokens) external view returns (ICryptoLegacy.TokenDistribution[] memory list)

    • Provides distribution details for specific _tokens in the _cryptoLegacy contract.

15. getCryptoLegacyBaseData(address _cryptoLegacy) external view returns (ICryptoLegacyLens.CryptoLegacyBaseData memory data)

    • Retrieves base data via an internal helper _baseData.

16. getCryptoLegacyListData(address _cryptoLegacy, address[] memory _tokens) external view returns (ICryptoLegacyLens.CryptoLegacyListData memory data)

    • Retrieves a list of token data via an internal helper _listTokensData.

17. getMessagesBlockNumbersByRecipient(address _cryptoLegacy, bytes32 _recipient) external view returns (uint64[] memory blockNumbers)

    • Returns the block numbers for messages sent to a specific _recipient.

18. getTransferBlockNumbers(address _cryptoLegacy) external view returns (uint64[] memory blockNumbers)

    • Fetches the block numbers where token transfers occurred.

19. getVestedAndClaimedData(address _cryptoLegacy, bytes32 _beneficiary, address[] calldata _tokens) external view returns (ICryptoLegacyLens.BeneficiaryTokenData[] memory result, uint64 startDate, uint64 endDate)

    • Provides both vested and claimed token data for a specific _beneficiary.

20. getPluginInfoList(address _cryptoLegacy) external view returns (ICryptoLegacyLens.PluginInfo[] memory)

    • Retrieves plugin information from the _cryptoLegacy instance.

21. getCryptoLegacyListWithStatuses(IBeneficiaryRegistry _beneficiaryRegistry, bytes32 _hash) external view returns (address[] memory listByBeneficiary, bool[] memory beneficiaryDefaultGuardian, address[] memory listByOwner, address[] memory listByGuardian, address[] memory listByRecovery)

    • Aggregates a set of CryptoLegacy addresses associated with multiple roles, also checking if guardians are initialized.

Internal/Private

1. _baseData(address _cryptoLegacy) internal view returns (ICryptoLegacyLens.CryptoLegacyBaseData memory)

   • Internal helper to fetch base data from the _cryptoLegacy contract via the ICryptoLegacyLens interface.

2. _listTokensData(address _cryptoLegacy, address[] memory _tokens) internal view returns (ICryptoLegacyLens.CryptoLegacyListData memory)

   • Internal helper to fetch token distribution data from the _cryptoLegacy contract via the ICryptoLegacyLens interface.

Constructor

• No explicit constructor is defined; uses the default.

Fallback / Receive

• No fallback or receive function is defined.

Events

• None declared in this contract.

Interacts With

• CryptoLegacyBasePlugin (for isLifetimeActive(), isPaused()).

• LensPlugin (for updateInterval(), challengeTimeout(), distributionStartAt(), etc.).

• ICryptoLegacy (for buildManager(), owner()).

• ICryptoLegacyLens (for fetching data structures like getCryptoLegacyBaseData(), getCryptoLegacyListData(), etc.).

• ITrustedGuardiansPlugin (checked in a try/catch within getCryptoLegacyListWithStatuses()).

• IBeneficiaryRegistry (queried in getCryptoLegacyListWithStatuses()).

---

7. CryptoLegacyFactory

Purpose

• Serves as a factory to deploy new CryptoLegacy contracts using CREATE2.

• Maintains a registry of authorized "build operators" who can trigger deployments.

Inheritance

• ICryptoLegacyFactory (interface contract implementation).

• Ownable (from OpenZeppelin for ownership management).

Key Methods

• Deployment: createCryptoLegacy uses CREATE2 for deterministic contract addresses.

• Access Control: setBuildOperator for managing which addresses can deploy new contracts.

All Functions

• Constructor

  • constructor(address _owner): Transfers ownership of the factory to _owner.

• setBuildOperator(address _operator, bool _isAdd) (public)

  • Adds or removes _operator in/from the set of build operators.

  • Emitted events: AddBuildOperator, RemoveBuildOperator.

• createCryptoLegacy(address _owner, address[] memory _plugins, Create2Args memory _create2Args) (external)

  • Deploys a new CryptoLegacy contract via CREATE2.

  • Reverts with NotBuildOperator() error if caller is unauthorized.

• cryptoLegacyBytecode(address _buildManager, address _owner, address[] memory _plugins) (public, pure, virtual)

  • Returns the combined creation bytecode (init code + constructor params) for a new CryptoLegacy deployment.

• computeAddress(bytes32 _salt, bytes32 _bytecodeHash) (public, view)

  • Computes the address of a contract if deployed using CREATE2 with the given _salt and _bytecodeHash.

Events

• AddBuildOperator(address operator)

  • Emitted when a build operator is added.

• RemoveBuildOperator(address operator)

  • Emitted when a build operator is removed.

Errors

• NotBuildOperator()

  • Thrown (revert) if the caller is not an authorized build operator.

Interacts With

• CryptoLegacy: The contract being deployed by this factory.

• LibCreate2Deploy: Library used for the CREATE2 deployment logic.

• ICryptoLegacyFactory: Interface implemented by this contract.

• Ownable: Used for ownership and access control.

---

8. CryptoLegacyOwnable

Purpose

• Provides ownership control and the ability to pause the CryptoLegacy contract.

Inheritance

• Inherits from the ICryptoLegacyOwnable interface.

Key Methods

• Owner-Only Functions: Ensures only the contract owner can execute specific operations.

• Pausable Mechanism: Enables or disables critical contract functions via a pause state.

All Functions

• onlyOwner() (modifier):

  • Internal check that uses LibCryptoLegacy._checkOwner() to confirm the caller is the contract owner.

• notPaused() (modifier):

  • Internal check that uses LibCryptoLegacy._checkPause() to ensure the contract is not paused.

• _transferOwnership(address _owner) (internal):

  • Transfers ownership by updating the owner in the diamond storage.

  • Emits the OwnershipTransferred event.

• setPause(bool _isPaused) (public):

  • Only callable by the owner.

  • Sets or unsets the paused state using LibCryptoLegacy._setPause().

(No constructor, fallback, or receive function is explicitly defined.)

Events

• OwnershipTransferred(address indexed previousOwner, address indexed newOwner):

  • Emitted when the contract owner is changed.

Interacts With

• LibDiamond for managing and setting the contract owner.

• LibCryptoLegacy for pause and owner-check functionality.

• ICryptoLegacyOwnable for interface definitions (ownership, events, etc.).

---

9. FeeRegistry

Purpose

Manages fee settings, referral codes, and fee collection for CryptoLegacy contracts.

• Central place for storing and calculating referral discounts and shares.

• Handles both single-chain and cross-chain referral code creation/updates.

Inheritance

• LockChainGate: Enables cross-chain functionality (not shown in full here).

• IFeeRegistry: Interface defining expected functions/events for fee management.

Key Methods

• Initialization: initialize(...) sets up default percentages, lock period, and ownership.

• Referral Handling: createCode(...), createCustomCode(...), updateCrossChainsRef(...) for cross-chain referral management.

• Fee Collection: takeFee(...) calculates, applies discounts/shares, and accumulates fees.

All Functions

Constructor

• constructor()

  • Empty constructor.

Public / External Functions

• initialize(address _owner, uint32 _defaultDiscountPct, uint32 _defaultSharePct, ILifetimeNft _lifetimeNft, uint256 _lockPeriod) Initializes the registry with default discount/share percentages, lock period, and owner.

• setCodeOperator(address _operator, bool _isAdd) Adds or removes an address authorized to manage referral codes.

• setSupportedRefCodeInChains(uint256[] memory _chains, bool _isAdd) Adds or removes chain IDs where referral codes are recognized.

• setFeeBeneficiaries(FeeBeneficiary[] memory _beneficiaries) Defines how accumulated fees are split among multiple beneficiaries.

• setDefaultPct(uint32 _defaultDiscountPct, uint32 _defaultSharePct) Updates the global default discount and share percentages.

• setRefererSpecificPct(address _referrer, uint32 _discountPct, uint32 _sharePct) Adjusts discount/share percentages specifically for a given referrer.

• setContractCaseFee(address _contract, uint8 _case, uint128 _fee) Sets the base fee for a particular contract-case combination.

• takeFee(address _contract, uint8 _case, bytes8 _code, uint256 _mul) Collects and distributes a fee, applying any referral discount/share.

• withdrawAccumulatedFee() Pays out the total accumulated (non-referral) fees to all configured beneficiaries.

• withdrawReferralAccumulatedFee(bytes8 _code) Pays out the accumulated referral fee for a specific code.

• createCustomCode(address _referrer, address _recipient, bytes8 _shortCode, uint256[] memory _chainIds, uint256[] memory _crossChainFees) Creates a custom referral code and optionally propagates it to multiple chains.

• createCode(address _referrer, address _recipient, uint256[] memory _chainIds, uint256[] memory _crossChainFees) Generates a new referral code on the current chain and optionally on additional chains.

• updateCrossChainsRef(address _referrer, uint256[] memory _chainIds, uint256[] memory _crossChainFees) payable Updates referral parameters across multiple chains.

• crossCreateCustomCode(uint256 _fromChainId, address _referrer, address _recipient, bytes8 _shortCode, uint32 _discountPct, uint32 _sharePct) Cross-chain function to create a referral code from a source chain.

• crossUpdateCustomCode(uint256 _fromChainId, address _referrer, address _recipient, bytes8 _shortCode, uint32 _discountPct, uint32 _sharePct) Cross-chain function to update a referral code from a source chain.

• changeCodeReferrer(bytes8 _code, address _newReferer, address _newRecipient, uint256[] memory _chainIds, uint256[] memory _crossChainFees) Changes ownership of a referral code to a new referrer (and updates on specified chains).

• changeRecipientReferrer(bytes8 _code, address _newRecipient, uint256[] memory _chainIds, uint256[] memory _crossChainFees) Updates the recipient of a referral code (and syncs across specified chains).

• getCodeOperatorsList() Returns the current list of authorized referral code operators.

• isCodeOperator(address _addr) Checks if an address is authorized to manage referral codes.

• getSupportedRefInChainsList() Retrieves a list of chain IDs that support referral codes.

• isSupportedRefInChain(uint256 _chainId) Checks if a specific chain ID is enabled for referrals.

• getFeeBeneficiaries() Lists all configured fee beneficiaries and their share percentages.

• getCodePct(bytes8 _code) Returns the effective discount and share percentages for a referral code.

• calculateFee(bytes8 _code, uint256 _fee) Calculates discount, share, and final fee based on referral code.

• getContractCaseFee(address _contract, uint8 _case) Retrieves the base fee for a given contract-case pair.

• getContractCaseFeeForCode(address _contract, uint8 _case, bytes8 _code) Retrieves the fee after applying the code’s discount.

• getReferrerByAddress(address _referrer) Fetches the referrer data associated with a particular address.

• getReferrerByCode(bytes8 _code) Fetches detailed information for a specific referral code.

• defaultSharePct() Returns the global default share percentage.

• defaultDiscountPct() Returns the global default discount percentage.

• refererByCode(bytes8 _code) Direct getter for the refererByCode mapping (raw data).

• codeByReferrer(address _referrer) Direct getter for the codeByReferrer mapping (raw data).

• accumulatedFee() Returns the total non-referral fees accumulated in the contract.

Internal / Private Functions

• lockFeeRegistryStorage() internal pure Returns the FeeRegistry storage pointer (via assembly).

• _setDefaultPct(FRStorage storage fs, uint32 _defaultDiscountPct, uint32 _defaultSharePct) internal Sets the default discount/share percentages.

• _checkFee(uint256 totalFee) [inherited or internal check from LockChainGate context] Ensures correct fee payment (not fully shown in snippet).

• _checkSource(...) / _onlyCrossChain(...) [from LockChainGate context] Validates cross-chain message authenticity (not fully shown).

• _setCustomCode(...) Internal utility to assign or update a referral code’s ownership and parameters.

• _createCustomCode(...) Handles creation of a brand-new code, ensuring it doesn’t already exist.

• _checkCodeNotZero(bytes8 _shortCode) Verifies a code is not the zero value.

• _checkSenderIsOperator(...) Ensures the caller is recognized as an operator.

• _checkSenderIsReferrer(...) Ensures the caller is the owner of a specific referral code.

• _checkNewOwnerIsNotReferrer(...) Prevents transferring code ownership to an address that already owns a code.

• _setCrossChainsRef(...) Internal logic for propagating referral changes to multiple chains.

• _encodeCrossCreateCustomCodeCommand(...) / _encodeCrossUpdateCustomCodeCommand(...) Pack data for cross-chain creation/update calls.

• _getCodePct(...) Derives effective discount/share (either custom or default).

• _calculateFee(...) Applies discount/share logic to produce final fee numbers.

• _getReferrerByAddress(...) / _getReferrerByCode(...) Internal retrieval methods for referrer info.

Events

• AddCodeOperator(address operator) Emitted when a new code operator is added.

• RemoveCodeOperator(address operator) Emitted when a code operator is removed.

• AddSupportedRefCodeInChain(uint256 chainId) Emitted when a chain ID is added as supported for referrals.

• RemoveSupportedRefCodeInChain(uint256 chainId) Emitted when a chain ID is removed from referral support.

• SetFeeBeneficiaries(FeeBeneficiary[] beneficiaries) Emitted when fee beneficiaries are updated.

• SetDefaultPct(uint32 defaultDiscount, uint32 defaultShare) Emitted when global default percentages are updated.

• SetRefererSpecificPct(address referrer, bytes8 code, uint32 discount, uint32 share) Emitted when custom discount/share is set for a referrer.

• SetContractCaseFee(address contract, uint8 caseId, uint128 fee) Emitted when a fee is assigned to a contract-case pair.

• SentFee(address owner, bytes8 code, address recipient, uint256 share) Emitted when a referral share is successfully sent.

• AccumulateFee(address owner, bytes8 code, address recipient, uint256 share) Emitted when a referral share cannot be sent and is stored.

• TakeFee(address contract, uint8 caseId, bytes8 code, uint256 discount, uint256 share, uint256 fee, uint256 value) Emitted when fees are taken, detailing discount, share, and final fees.

• WithdrawFee(address recipient, uint256 share) Emitted when a beneficiary withdraws from the accumulated pool.

• WithdrawRefFee(address recipient, uint256 share) Emitted when a referrer withdraws referral-specific accumulated fees.

• CreateCode(address caller, address referrer, bytes8 code, address recipient, uint256 fromChain) Emitted when a new referral code is created (multi-chain context).

• UpdateCode(address caller, address referrer, bytes8 code, address recipient, uint256 fromChain) Emitted when a referral code is updated (multi-chain context).

• SetCrossChainsRef(bytes8 code, bool isCreate, uint256[] chainIds, uint256[] fees) Emitted when referral info is propagated to multiple chains.

• ChangeCode(address oldReferrer, address newReferrer, bytes8 code) Emitted when a referral code’s owner is changed.

• ChangeRecipient(address oldReferrer, address newRecipient, bytes8 code) Emitted when a referral code’s beneficiary is changed.

Errors (Reverts)

• PctSumDoesntMatchBase() Thrown if sum of share percentages does not match the base (10000).

• TooBigPct() Thrown if discount/share percentages exceed the allowable base.

• RefAlreadyCreated() Thrown if attempting to create a referral code that already exists.

• ZeroCode() Thrown if a zero-value referral code is used.

• NotOperator() Thrown if caller is not an authorized code operator.

• CodeNotCreated() Thrown if a code does not exist for the provided referrer.

• NotReferrer() Thrown if the caller is not the referrer for a specified code.

• AlreadyReferrer() Thrown if attempting to assign code ownership to an address that already owns a code.

Interacts With

• LockChainGate (parent): Provides cross-chain message verification and fee checks.

• ILifetimeNft: Used during initialization to lock certain NFTs.

• IFeeRegistry (interface): Defines the function signatures and events for this registry.

• External: Potential cross-chain calls to other deployments of FeeRegistry.

---

10. LegacyMessenger

Purpose

Forwards messages to designated recipients and logs the block numbers when messages are received. Useful for on-chain “legacy” or inheritance message handling.

Inheritance

• ILegacyMessenger: Implements the interface methods for sending legacy messages.

• BuildManagerOwnable: Ensures ownership and build-manager validation.

Key Methods

• sendMessagesTo(...): Main entry point for distributing messages.

• getMessagesBlockNumbersByRecipient(...): Retrieves the logged block numbers for each recipient.

All Functions

• Constructor

  • constructor(address _owner)

    • Sets the initial owner of the contract.

• sendMessagesTo(address _cryptoLegacy, bytes32[] memory _recipientList, bytes32[] memory _messageHashList, bytes[] memory _messageList, bytes[] memory _messageCheckList, uint256 _messageType) (public)

  • Forwards the given message data to the specified recipients.

  • Emits LegacyMessage and LegacyMessageCheck events.

  • Calls _checkBuildManagerValid(_cryptoLegacy, msg.sender) internally.

• getMessagesBlockNumbersByRecipient(bytes32 _recipient) (external, view)

  • Returns an array of block numbers indicating when messages were received for a given recipient.

• Auto-Generated Getter

  • messagesGotByBlockNumber(bytes32) -> uint64[] (public mapping)

    • Returns stored block numbers for a specific recipient.

• (No fallback or receive function declared.)

Events

• LegacyMessage(bytes32 indexed, bytes32 indexed, bytes, uint256): Logs the main message parameters.

• LegacyMessageCheck(bytes32 indexed, bytes32 indexed, bytes, uint256): Logs an associated check message.

Interacts With

• BuildManagerOwnable for ownership and validation logic.

• ILegacyMessenger interface definitions.

• External _cryptoLegacy contract for message validation context.

---

11. LifetimeNft

Purpose

• An ERC721 token representing lifetime access with tier determination.

• Manages minting permissions via minterOperator.

• Uses the Tier system to classify tokens.

Inheritance

• ILifetimeNft (interface)

• ERC721Enumerable (OpenZeppelin)

• Ownable (OpenZeppelin)

Key Methods

• Minting: Authorized minter operators can mint new tokens.

• Tier Retrieval: Provides a tier for each token ID.

• Access Control: Owner can set base URIs and manage authorized minters.

All Functions

1. Constructor

   • constructor(string memory name_, string memory symbol_, string memory baseURI_, address _owner) Initializes the ERC721 token (name and symbol), sets the base URI, and transfers ownership.

2. Owner Functions

   • setBaseUri(string memory baseURI_) external onlyOwner Updates the base URI for the token metadata.

   • _setBaseUri(string memory baseURI_) internal Internal helper to set and emit the updated base URI.

   • setMinterOperator(address _minter, bool _isActive) external onlyOwner Adds or removes a minter operator address.

3. Minter Operator Function

   • mint(address _tokenOwner) external returns (uint256) Mints a new NFT to _tokenOwner. Requires caller to be an active minter operator; reverts with NotTheMinter otherwise.

4. View/Pure Functions

   • _baseURI() internal view override returns (string memory) Returns the current base URI for token metadata (overrides OpenZeppelin’s internal _baseURI).

   • tokensOfOwner(address _owner) external view returns (uint256[] memory tokens) Enumerates and returns all token IDs owned by a given address.

   • getTier(uint256 _tokenId) external pure returns (Tier) Determines the tier of the specified _tokenId.

5. Fallback / Receive

   • (None present in this contract.)

Events

• SetBaseURI(string baseURI): Emitted when the base URI is updated.

• SetMinterOperator(address indexed minter, bool indexed isActive): Emitted when a minter operator is added or removed.

Errors

• NotTheMinter(): Thrown when a non-minter operator attempts to mint.

Interacts With

• ILifetimeNft: Implements the interface and its definitions.

• OpenZeppelin Contracts: Uses ERC721Enumerable and Ownable.

---

12. LockChainGate

Purpose

• Primary cross-chain locking and unlocking mechanism for a special “lifetime NFT.”

• Allows NFT holders to lock their NFTs, preventing transfer until certain conditions are met (e.g., time-based lock period, multi-chain synchronization, or cross-chain calls).

Inheritance

• Ownable (OpenZeppelin): Restricts certain functions (like setters) to the contract owner.

• ILockChainGate: Interface (not shown) presumably matching this contract’s main external API.

• Initializable: Used to manage an initialization routine suitable for upgradeable or proxy-based deployment.

Key Methods

• NFT Locking/Unlocking: lockLifetimeNft, unlockLifetimeNft, lockLifetimeNftToChains, etc.

• Cross-Chain Operations: _send, _encodeCrossLockCommand, _encodeCrossUnlockCommand, _encodeCrossUpdateOwnerCommand.

• Configuration: setDebridgeGate, setDebridgeNativeFee, setDestinationChainContract, setSourceChainContract, etc.

All Functions

(Includes public, external, internal, private, constructor, fallback, receive if any. Fallback/receive are not present in this code.)

1. Constructor

   • constructor()

     • Disables contract initializers (from Initializable) to prevent misuse.

2. Internal Storage Getter

   • lockChainGateStorage() (internal, pure)

     • Returns a pointer to the LCGStorage struct in the designated storage slot.

3. Internal Initializer

   • _initializeLockChainGate(ILifetimeNft _lifetimeNft, uint256 _lockPeriod, address _owner) (internal)

     • Sets NFT address, lock period, and transfers contract ownership.

4. Public Function: Set Lock Operator

   • setLockOperator(address _operator, bool _isAdd)

     • Allows owner to add/remove an approved operator for lock-related actions.

5. External Function: Set deBridgeGate

   • setDebridgeGate(address _deBridgeGate)

     • Owner sets the IDeBridgeGate contract address.

6. External Function: Set deBridge Native Fee

   • setDebridgeNativeFee(uint256 _chainId, uint256 _nativeFee)

     • Owner configures a chain-specific native fee for cross-chain operations.

7. Internal Function: Set Destination Chain Contract

   • _setDestinationChainContract(uint256 _chainId, address _chainContract)

     • Updates mapping for a destination chain → contract address.

8. External Function: Set Destination Chain Contract

   • setDestinationChainContract(uint256 _chainId, address _chainContract)

     • Public wrapper for _setDestinationChainContract.

9. Internal Function: Set Source Chain Contract

   • _setSourceChainContract(uint256 _chainId, address _chainContract)

     • Updates mapping for a source chain → contract address.

10. External Function: Set Source Chain Contract

    • setSourceChainContract(uint256 _chainId, address _chainContract)

      • Public wrapper for _setSourceChainContract.

11. External Function: Set Both Source & Destination Contract

    • setSourceAndDestinationChainContract(uint256 _chainId, address _chainContract)

      • Sets the same address for source and destination of a given chain.

12. External Function: Set Lock Period

    • setLockPeriod(uint256 _lockPeriod)

      • Owner updates how long an NFT remains locked.

13. External Function: Set Referral Code

    • setReferralCode(uint32 _referralCode)

      • Owner sets the referral code used in cross-chain messaging.

14. External Function: Set Custom Chain ID

    • setCustomChainId(uint256 _customChainId)

      • Overrides the blockchain chainid() for specialized environments.

15. Internal Function: Record NFT Lock

    • _writeLockLifetimeNft(address _holder, uint256 _tokenId)

      • Updates internal storage to record an NFT as locked for a holder.

16. External Function: Lock Lifetime NFT

    • lockLifetimeNft(uint256 _tokenId, address _holder, uint256[] memory _lockToChainIds, uint256[] memory _crossChainFees)

      • Transfers NFT from caller to contract, locks it, and optionally triggers cross-chain locks.

17. External Function: Cross-Lock Lifetime NFT

    • crossLockLifetimeNft(uint256 _fromChainID, uint256 _tokenId, address _holder)

      • Invoked via cross-chain message to register an NFT as locked from another chain.

18. Internal Function: Lock NFT to Multiple Chains

    • _lockLifetimeNftToChains(LCGStorage storage ls, address _holder, uint256[] memory _toChainIDs, uint256[] memory _crossChainFees)

      • Iterates over chain IDs, calls _lockLifetimeNftToChain for each, and checks fees.

19. Internal Function: Check Fee

    • _checkFee(uint256 _fee)

      • Validates that msg.value matches required fee (with a small tolerance).

20. External Function: Lock NFT to Multiple Chains (Caller)

    • lockLifetimeNftToChains(uint256[] memory _toChainIDs, uint256[] memory _crossChainFees)

      • A convenience method letting the caller lock their NFT to multiple chains.

21. Internal Function: Lock NFT to One Chain

    • _lockLifetimeNftToChain(LCGStorage storage ls, uint256 _toChainID, address _holder, uint256 _sendFee)

      • Checks if already locked to that chain, encodes cross-lock command, sends message.

22. External Function: Unlock Lifetime NFT

    • unlockLifetimeNft(uint256 _tokenId)

      • Unlocks NFT if conditions are met (time-based, no cross-chain locks, correct holder).

23. External Function: Unlock Lifetime NFT From Chain

    • unlockLifetimeNftFromChain(uint256 _tokenId)

      • Unlocks an NFT originally locked from a different chain, sends cross-chain message back.

24. External Function: Cross-Unlock Lifetime NFT

    • crossUnlockLifetimeNft(uint256 _fromChainID, uint256 _tokenId, address _holder)

      • Invoked cross-chain to remove a chain ID from the locked set.

25. External Function: Cross-Update NFT Owner

    • crossUpdateNftOwner(uint256 _fromChainID, uint256 _tokenId, address _transferTo)

      • Transfers ownership from old holder to new holder in cross-chain context.

26. Internal Function: Delete NFT Lock Data

    • _deleteTokenData(address _holder, uint256 _tokenId)

      • Cleans up tracking info upon unlock or cross-chain release.

27. Internal Function: Cross-Chain Access Check

    • _onlyCrossChain(LCGStorage storage ls, uint256 _fromChainID)

      • Ensures the caller is the ICallProxy and chain/sender match expected source.

28. Internal Function: Send Cross-Chain Message

    • _send(LCGStorage storage ls, bytes memory _dstTransactionCall, uint256 _toChainId, uint256 _value)

      • Encodes flags, referral code, calls deBridgeGate.sendMessage.

29. External Function: Approve NFT

    • approveLifetimeNftTo(uint256 _tokenId, address _approveTo)

      • Approves an address to unlock or transfer the locked NFT.

30. Internal Function: Transfer NFT Ownership

    • _transferLifetimeNftTo(LCGStorage storage ls, uint256 _tokenId, address _holder, address _transferTo, uint256 _fromChain)

      • Moves lock data to new holder, resets approvals, emits event.

31. External Function: Transfer NFT & Lock to Chains

    • transferLifetimeNftTo(uint256 _tokenId, address _transferTo, uint256[] memory _toChainIDs, uint256[] memory _crossChainFees)

      • Transfers locked NFT ownership to another user and optionally updates cross-chain locks.

32. External Function: Update NFT Owner on Chain List

    • updateNftOwnerOnChainList(uint256 _tokenId, uint256[] memory _toChainIDs, uint256[] memory _crossChainFees)

      • Similar to above, but only updates cross-chain owner references.

33. Internal Function: Update NFT Owner on Single Chain

    • _updateLifetimeNftOwnerOnChain(...)

      • Encodes cross-update command, sends message, and records chain lock.

34. Internal Function: Encode Cross-Lock Command

    • _encodeCrossLockCommand(...)

      • Encodes LockChainGate.crossLockLifetimeNft.selector with chain/time data.

35. Internal Function: Encode Cross-Unlock Command

    • _encodeCrossUnlockCommand(...)

      • Encodes LockChainGate.crossUnlockLifetimeNft.selector with chain/time data.

36. Internal Function: Encode Cross-Update Owner Command

    • _encodeCrossUpdateOwnerCommand(...)

      • Encodes LockChainGate.crossUpdateNftOwner.selector.

37. Internal Function: Check Destination Configuration

    • _checkDestinationLockedChain(...)

      • Verifies the chain contract is set and the token is locked for the holder.

38. Internal Function: Check for Cross-Chain Lock

    • _checkCrossChainLock(...)

      • Reverts if the NFT is locked from another chain.

39. Internal Function: Check Lock Too Early

    • _checkTooEarly(address _holder)

      • Ensures the lock period has elapsed.

40. Internal Function: Check Valid Source Chain

    • _checkSource(...)

      • Reverts if no source contract is set for _fromChainID.

41. Internal Function: Check Holder Owns Correct Token

    • _checkHolderTokenLock(...)

      • Reverts if the stored locked token ID for a holder doesn’t match the requested token.

42. External View: Get Locked Chains for Account

    • getLockedToChainsIdsOfAccount(address _holder)

      • Returns the chain IDs to which _holder’s NFT is locked.

43. Internal View: _getLockedToChainsIdsOfAccount(...)

    • Same as above, but library-internal.

44. External View: Get Locked Until

    • getLockedUntil(address _holder)

      • Returns the timestamp after which the holder’s NFT can unlock.

45. Internal View: _getLockedUntil(...)

    • Calculates lockedAt + lockPeriod.

46. External View: Get Locked Chains for Token

    • getLockedToChainsIds(uint256 _tokenId)

      • Returns chain IDs for a specific token.

47. External View: lockPeriod

    • lockPeriod()

      • Returns the configured lock duration in seconds.

48. External View: referralCode

    • referralCode()

      • Returns the set referral code for cross-chain calls.

49. External View: ownerOfTokenId

    • ownerOfTokenId(uint256 _tokenId)

      • Returns the stored “owner” address for a locked token.

50. External View: lockedNftFromChainId

    • lockedNftFromChainId(uint256 _tokenId)

      • Returns the chain ID from which an NFT was cross-locked.

51. External View: lockedNftApprovedTo

    • lockedNftApprovedTo(uint256 _tokenId)

      • Returns the address approved to manage a locked token.

52. External View: lockedNft

    • lockedNft(address _holder)

      • Returns the LockedNft data struct for a holder.

53. External Payable: getDeBridgeChainNativeFeeAndCheck

    • getDeBridgeChainNativeFeeAndCheck(uint256 _chainId, uint256 _userValue)

      • Returns the required cross-chain fee and verifies payment.

54. Internal Function: _getDeBridgeChainNativeFeeAndCheck

    • Similar to above, with internal logic for verifying fees.

55. External View: getDeBridgeChainNativeFee

    • getDeBridgeChainNativeFee(uint256 _chainId, uint256 _userValue)

      • Returns the chain-specific or global fallback fee, whichever is higher.

56. Internal View: _getDeBridgeChainNativeFee

    • Implements the logic for retrieving a chain’s fee (from stored mapping or global fallback).

57. External View: deBridgeGate

    • deBridgeGate()

      • Returns the address of the IDeBridgeGate contract in use.

58. External View: lifetimeNft

    • lifetimeNft()

      • Returns the associated ILifetimeNft contract.

59. External View: deBridgeChainConfig

    • deBridgeChainConfig(uint256 _chainId)

      • Returns (nativeFee, destinationChain, sourceChain) for a given _chainId.

60. External View: getLockOperatorsList

    • getLockOperatorsList()

      • Returns an array of all authorized lock operators.

61. Public View: isLockOperator

    • isLockOperator(address _addr)

      • Checks if _addr is in the set of lock operators.

62. Public View: calculateCrossChainCreateRefNativeFee

    • calculateCrossChainCreateRefNativeFee(uint256[] memory _chainIds, uint256[] memory _crossChainFees)

      • Summation utility for multi-chain fees.

63. External View: isNftLocked

    • isNftLocked(address _holder)

      • Returns true if _holder has a locked NFT.

64. External: isNftLockedAndUpdate

    • isNftLockedAndUpdate(address _holder)

      • If lock is expired and called by operator or approved, refreshes lockedAt to current time, returns whether NFT is locked.

65. External View: getChainId

    • getChainId()

      • Returns the current chain ID, or a custom one if set.

66. Internal View: _getChainId

    • Retrieves chainid() or the stored custom chain ID.

(No fallback or receive function exists in the contract.)

Events

• AddLockOperator(address operator) Emitted when a lock operator is added.

• RemoveLockOperator(address operator) Emitted when a lock operator is removed.

• SetDeBridgeGate(address deBridgeGate) Emitted when the deBridgeGate contract is updated.

• SetDeBridgeNativeFee(uint256 chainId, uint256 nativeFee) Emitted when a chain-specific native fee is configured.

• SetDestinationChainContract(uint256 chainId, address chainContract) Emitted when the destination contract for a chain is set.

• SetSourceChainContract(uint256 chainId, address chainContract) Emitted when the source contract for a chain is set.

• SetLockPeriod(uint256 lockPeriod) Emitted when the lock period changes.

• SetReferralCode(uint32 referralCode) Emitted when the referral code changes.

• SetCustomChainId(uint256 customChainId) Emitted when a custom chain ID is set.

• LockNft(uint256 lockedAt, uint256 tokenId, address holder) Emitted when an NFT is locked.

• CrossLockNft(uint256 lockedAt, uint256 tokenId, address holder, uint256 fromChainID) Emitted when an NFT is locked cross-chain.

• LockToChain(address holder, uint256 tokenId, uint256 toChainID, bytes32 submissionId) Emitted when an NFT is locked to a specific chain.

• UnlockNft(uint256 lockedAt, uint256 tokenId, address holder, address receiver) Emitted when an NFT is unlocked.

• UnlockFromChain(address holder, uint256 tokenId, uint256 fromChainID, bytes32 submissionId) Emitted when an NFT is unlocked from a cross-chain lock.

• CrossUnlockNft(uint256 lockedAt, uint256 tokenId, address holder, uint256 fromChainID) Emitted when a cross-chain NFT unlock is finalized.

• CrossUpdateNftOwner(uint256 fromChainID, uint256 tokenId, address transferTo) Emitted when ownership is updated cross-chain.

• TransferNft(uint256 tokenId, address from, address to, uint256 fromChainID) Emitted on local NFT transfer with cross-chain context.

• ApproveNft(uint256 tokenId, address holder, address approved) Emitted when an address is approved for unlocking or transferring an NFT.

• SendToChain(uint256 chainId, bytes32 submissionId, uint256 value, bytes dstTxCall) Emitted before sending a cross-chain message.

• UpdateLockToChain(address holder, uint256 tokenId, uint256 toChainID, bytes32 submissionId) Emitted when updating NFT ownership or lock state on a remote chain.

Errors

• AlreadyLocked() Thrown when attempting to lock an NFT that is already locked.

• AlreadyLockedToChain() Thrown if attempting to lock an NFT to a chain where it’s already locked.

• NotAvailable() Thrown if a caller lacks permission to unlock or manage the NFT.

• LockedToChains() Thrown if the NFT is locked to one or more chains, preventing unlock.

• NotLockedByChain() Thrown if attempting to unlock from a chain when the NFT is not cross-locked.

• DestinationChainNotSpecified() Thrown if no contract is set for the target chain.

• SameAddress() Thrown if transferring an NFT to the same owner.

• RecipientLocked() Thrown if the recipient address already has a locked NFT.

• NotCallProxy() Thrown if a cross-chain function is not called by the ICallProxy.

• ChainIdMismatch() Thrown if the chain ID from the cross-chain call doesn’t match the expected value.

• NotValidSender() Thrown if the cross-chain caller is not the expected contract address.

• CrossChainLock() Thrown if the NFT is locked by another chain.

• TooEarly() Thrown if trying to unlock before the lock period has elapsed.

• SourceNotSpecified() Thrown if the source chain is not configured.

• TokenNotLocked() Thrown if no NFT is locked or if the token ID is incorrect.

• TokenIdMismatch(uint256 tokenId) Thrown if attempting a cross-chain update for a different token ID than expected.

• NotAllowed() Thrown if an unauthorized address tries to modify the lock state.

• IncorrectFee(uint256 requiredFee) Thrown if the caller does not provide the correct native fee.

Interacts With

• IDeBridgeGate: For cross-chain messaging and fee retrieval.

• ICallProxy (via deBridgeGate.callProxy()): To validate calls from other chains.

• ILifetimeNft: The ERC721-like NFT being locked.

• OpenZeppelin: Ownable, Initializable, and EnumerableSet libraries.

---

13. MultiPermit

Purpose

• A contract allowing batch execution of ERC20 permit approvals in a single transaction.

• Optimizes gas usage by aggregating multiple permit calls into one.

Inheritance

• Does not inherit from other contracts within this code snippet.

Key Methods

• approveTreasuryTokensToLegacy(...): Main method to batch permit approvals across multiple tokens.

All Functions

• Constructor: Initializes the MultiPermit contract. (No parameters or special logic.)

• approveTreasuryTokensToLegacy(PermitData[] memory _permits) (external):

  • Iterates through an array of PermitData structures.

  • Calls IERC20Permit(p.token).permit(...) for each entry, executing off-chain approvals on multiple tokens in one transaction.

No fallback or receive functions are declared in this contract.

Events

• No events are declared in this contract.

Interacts With

• IERC20Permit interface from OpenZeppelin:

  • Uses the permit function to authorize ERC20 allowances without requiring on-chain approvals.

---

14. PluginsRegistry

Purpose

Manages the registration of plugins, stores metadata about them, and provides retrieval methods. Inherits ownership capabilities from OpenZeppelin’s Ownable contract.

Inheritance

• IPluginsRegistry

• Ownable (from OpenZeppelin)

Key Methods

• addPlugin / removePlugin: Enables the owner to manage which plugins are registered.

• getPluginMetadata / getPluginInfoList: Provides comprehensive information about registered plugins.

All Functions

• Constructor

  • constructor(address _owner) Sets the initial owner of the contract.

• addPlugin(address _plugin, string memory _description) public onlyOwner Registers a new plugin in the internal list and logs a description with its block number.

• addPluginDescription(address _plugin, string memory _description) public onlyOwner Appends a new description entry (recorded by current block number) for an already registered plugin.

• removePlugin(address _plugin) public onlyOwner Removes a plugin from the registry.

• isPluginRegistered(address _plugin) public view returns(bool) Checks if a plugin address is currently registered.

• getPluginMetadata(address _plugin) public view returns(string memory name, uint16 version, uint64[] memory descriptionBlockNumbers) Retrieves the plugin’s name, version, and a list of description block numbers by calling the plugin’s interface.

• getPluginDescriptionBlockNumbers(address _plugin) external view returns(uint64[] memory) Returns the entire array of block numbers where plugin descriptions were added.

• getPluginAddressList() public view returns(address[] memory) Returns all currently registered plugin addresses.

• getPluginInfoList() public view returns(PluginInfo[] memory) Returns a comprehensive list of registered plugins, including their addresses, names, versions, and description timestamps.

Events

(These events are declared in IPluginsRegistry and emitted by this contract.)

• AddPlugin(address indexed plugin, string description) Emitted when a new plugin is added.

• AddPluginDescription(address indexed plugin, string description) Emitted when an additional description is appended for an existing plugin.

• RemovePlugin(address indexed plugin) Emitted when a plugin is removed.

Interacts With

• ICryptoLegacyPlugin (to query plugin name and version).

• EnumerableSet (OpenZeppelin library for managing a set of plugin addresses).

• Ownable (OpenZeppelin contract providing role-based ownership control).

---

15. ProxyBuilder

Purpose

• Facilitates the creation and management of upgradeable proxies using a ProxyAdmin.

• Provides functionality to set or update the ProxyAdmin and deploy new proxies via Create2.

Inheritance

• Inherits from Ownable (OpenZeppelin).

Key Methods

• build(...): Deploys a new proxy using Create2 and returns its address.

• setProxyAdmin(...): Updates the ProxyAdmin address.

All Functions

• constructor(address _owner, address _proxyAdmin) (public):

  • Initializes the contract, optionally setting an existing ProxyAdmin if _proxyAdmin is non-zero.

  • Transfers ownership to _owner.

• setProxyAdmin(address _proxyAdmin) (external, onlyOwner):

  • Updates the stored proxyAdmin address and emits SetProxyAdmin.

• build(address _create2Address, bytes32 _create2Salt, address _implementation, bytes calldata _initData) (external, onlyOwner) returns (address):

  • Uses LibCreate2Deploy._deployByCreate2 to deploy a proxy via Create2.

  • The deployed proxy points to _implementation.

  • Emits Build event upon successful deployment.

• proxyBytecode(address _implementation, bytes memory _data) (public, view) returns (bytes memory):

  • Generates the bytecode used for deploying a TransparentUpgradeableProxy with _implementation and _data.

• computeAddress(bytes32 _salt, bytes32 _bytecodeHash) (public, view) returns (address):

  • Computes the future address of a Create2 deployment by leveraging LibCreate2Deploy._computeAddress.

• No fallback or receive functions are declared.

Events

• Build(address proxy, address implementation):

  • Emitted when a new proxy is successfully deployed.

• SetProxyAdmin(address proxyAdmin):

  • Emitted when the ProxyAdmin address is updated.

Errors

• AdminAlreadyCreated():

  • Defined but not invoked in the provided snippet. Likely used for scenarios where an admin is re-initialized.

Interacts With

• LibCreate2Deploy:

  • Used to perform Create2 deployments and compute potential addresses.

• ProxyAdmin:

  • Managed by this contract (initially set during construction and updatable via setProxyAdmin).

• TransparentUpgradeableProxy:

  • Deployed through the generated proxy bytecode.

---

16. ProxyBuilderAdmin

Purpose

• Extends OpenZeppelin’s ProxyAdmin to allow setting a custom owner during construction.

Inheritance

• Inherits from ProxyAdmin (OpenZeppelin).

Key Methods

• Constructor: Transfers ownership to a specified address.

All Functions

• constructor(address _owner) (public):

  • Initializes the contract by calling _transferOwnership(_owner) from the inherited ProxyAdmin.

No other functions, fallback, or receive are defined in this contract.

Events

• No custom events are declared in this contract.

Interacts With

• ProxyAdmin: Inherited from OpenZeppelin, used for managing upgradeable proxies.

---

17. SignatureRoleTimelock

Purpose

Implements a timelocked mechanism where calls can only be executed by accounts holding specific roles after a certain delay.

• Allows scheduling, executing, and canceling calls.

• Uses role-based permissions to restrict who can schedule and manage calls.

• Timelock periods ensure that calls cannot be executed immediately, providing security and oversight.

Inheritance

• ISignatureRoleTimelock (interface implemented)

• AccessControl (from OpenZeppelin) for role management

• ReentrancyGuard (from OpenZeppelin) for non-reentrant function calls

Key Methods

• Scheduling Calls (scheduleCallList)

• Executing Calls (executeCallList)

• Canceling Calls (cancelCallList)

• Role Management (setRoleAccounts, _addRoleAccount, _removeRoleAccount)

• Signature Role Management (addSignatureRoleList, removeSignatureRoleList)

All Functions

Public / External Functions

1. Constructor

   • constructor(...):

     • Assigns the deployer as ADMIN_ROLE.

     • Adds the contract itself (address(this)) to ADMIN_ROLE.

     • Adds initial signature roles for managing signatures within this contract.

     • Accepts arrays of role assignments (_roles) and signature roles (_sigs) to set up upon deployment.

2. setMaxExecutionPeriod(uint128 _maxExecutionPeriod) external onlyRole(ADMIN_ROLE)

   • Sets the maximum period during which a scheduled call can be valid for execution.

   • Reverts if _maxExecutionPeriod is outside the allowed bounds (7 to 21 days).

3. setRoleAccounts(AddressRoleInput[] memory _list) external onlyRole(ADMIN_ROLE)

   • Batch operation to add or remove accounts from roles.

   • Depending on the provided prevAccount and newAccount, it adds or removes accounts accordingly.

4. addSignatureRoleList(SignatureToAdd[] memory _sigs) external onlyCurrentAddress

   • Adds multiple new signature roles in batch.

   • Restricted to calls originating from this contract (onlyCurrentAddress).

5. removeSignatureRoleList(SignatureToRemove[] memory _sigsToRemove) external onlyCurrentAddress

   • Removes multiple signature roles in batch.

   • Also restricted to calls originating from this contract.

6. scheduleCallList(CallToAdd[] calldata _calls) external nonReentrant returns (bytes32[] memory callIds)

   • Schedules a list of calls for future execution, each with a timelock.

   • Returns an array of identifiers (callIds) for the scheduled calls.

7. executeCallList(bytes32[] memory _callIds) external nonReentrant

   • Executes a list of scheduled calls by their IDs, provided their timelocks have passed.

   • Uses a low-level call to forward data to the target contract.

8. cancelCallList(bytes32[] memory _callIds) external onlyRole(ADMIN_ROLE) nonReentrant

   • Cancels a list of scheduled calls by their IDs, only if still pending.

   • Only callable by admins.

9. getRoleAccounts(bytes32 _role) external view returns(address[] memory)

   • Retrieves the list of addresses currently assigned to the given role.

10. getTargets() external view returns(address[] memory)

    • Returns all contract addresses (targets) that have assigned signature roles.

11. getTargetSigs(address _target) external view returns(TargetSigRes[] memory result)

    • Returns details (role, timelock) of each function selector associated with _target.

12. getCallId(address target, bytes calldata data, address caller, uint256 executeAfter) public pure returns (bytes32)

    • Helper to compute a call ID off-chain or on-chain, matching the ID used internally.

13. getCall(bytes32 _callId) external view returns(CallRequest memory)

    • Fetches the details of a specific scheduled call by its ID.

14. getCallsList(uint256 _offset, uint256 _limit) external view returns(bytes32[] memory ids, CallRequest[] memory resCalls)

    • Returns a paginated subset of scheduled call IDs and their details.

15. getCallIds() external view returns(bytes32[] memory)

    • Returns an array of all scheduled call IDs.

16. getCallsLength() external view returns(uint256)

    • Returns the total number of scheduled calls.

Internal / Private Functions

1. _addRoleAccount(bytes32 _role, address _account)

   • Internal function that grants _account a specific _role.

   • Emits an event and updates internal mappings.

2. _removeRoleAccount(bytes32 _role, address _account)

   • Internal function that revokes _account from a specific _role.

   • Emits an event and updates internal mappings.

3. _addSignatureRole(address _target, bytes4 _signature, bytes32 _role, uint128 _timelock)

   • Internal function to add a new signature role for _signature on _target.

   • Ensures role exists and timelock is within bounds.

4. _removeSignatureRole(address _target, bytes4 _signature)

   • Internal function to remove a signature role from _target.

   • Updates arrays, possibly removing _target from the list of tracked targets.

5. _scheduleCall(address _target, bytes4 _sig, bytes memory _data) internal returns(bytes32 callId)

   • Core scheduling logic that sets the timelock and stores call details.

   • Ensures the caller has the required role.

6. _executeCall(bytes32 callId) internal

   • Core execution logic that verifies timelock constraints before calling the target.

   • Bubbles up any revert reason from the low-level call.

7. _cancelCall(bytes32 callId) internal

   • Cancels a previously scheduled call if still pending.

8. _getAddressIndex(address[] memory _list, address _addr) internal pure returns (uint index)

   • Utility to find an address index in an array, or type(uint256).max if not found.

9. _getBytes4Index(bytes4[] memory _list, bytes4 _hash) internal pure returns (uint index)

   • Utility to find a function selector index in an array, or type(uint256).max if not found.

10. _checkRole(bytes32 _role) internal view override

    • Overrides the inherited _checkRole method to revert with a custom error if msg.sender lacks _role.

Fallback / Receive Functions

• None (No explicit fallback or receive function defined).

Events

• SetMaxExecutionPeriod(uint128 _maxExecutionPeriod): Emitted when the maximum execution period is updated.

• AddRoleAccount(bytes32 indexed role, address indexed account): Emitted when a role is granted to an account.

• RemoveRoleAccount(bytes32 indexed role, address indexed account): Emitted when a role is revoked from an account.

• AddTarget(address indexed target): Emitted when a new target is added to track signature roles.

• RemoveTarget(address indexed target): Emitted when a target is removed from tracking.

• AddSignatureRole(address indexed target, bytes4 signature, bytes32 indexed role, uint128 timelock): Emitted when a signature role is created.

• RemoveSignatureRole(address indexed target, bytes4 signature): Emitted when a signature role is removed.

• CallScheduled(bytes32 indexed callId, address indexed caller, address indexed target, bytes4 signature, uint128 executeAfter): Emitted when a call is scheduled.

• CallExecuted(bytes32 indexed callId, address indexed executor, bytes returnData): Emitted when a call is successfully executed.

• CallCanceled(bytes32 indexed callId, address indexed executor): Emitted when a scheduled call is canceled.

Errors

• CallerNotCurrentAddress(): Thrown when a function restricted to address(this) is called by an external account.

• OutOfMaxExecutionPeriodBounds(uint128 minPeriod, uint128 maxPeriod): Thrown if the new max execution period is out of 7–21 day bounds.

• AlreadyHaveRole(): Thrown when attempting to grant a role to an account that already has it.

• DoesntHaveRole(): Thrown when attempting to remove a role from an account that does not hold it.

• IncorrectRoleIndex(): Thrown if the address to remove from a role does not match the expected index in the array.

• RoleDontExist(): Thrown if a role is referenced that has no assigned accounts.

• SignatureAlreadyExists(): Thrown if attempting to create a signature role that is already defined.

• OutOfTimelockBounds(uint128 maxDuration): Thrown when a specified timelock exceeds MAX_TIMELOCK_DURATION.

• SignatureTimeLockNotSet(bytes4 signature): Thrown if a function signature has no timelock configured when scheduling a call.

• CallerHaveNoRequiredRole(bytes32 role): Thrown if the caller does not have the required role to schedule a call.

• CallAlreadyScheduled(): Thrown if an identical call is already scheduled.

• CallNotScheduled(): Thrown if trying to execute or cancel a call that is not scheduled.

• NotPending(): Thrown if a call is not in a pending state.

• TimelockActive(): Thrown if attempting to execute a call before its timelock has passed.

• TimelockExpired(): Thrown if attempting to execute a call after it has expired.

• CallFailed(bytes returnData): Thrown when a low-level call fails. Revert reasons from the target are included in returnData.

• IncorrectSignatureIndex(): Thrown if the signature to remove does not match the expected index in the array.

Interacts With

• Other Contracts: Any target contract for scheduled calls.

• ISignatureRoleTimelock: Implements the interface structures.

• OpenZeppelin: Uses AccessControl for role management and ReentrancyGuard for preventing reentrancy attacks.

---

18. Flags (Library)

Purpose

• The Flags library is designed to manage a set of flags within a packed uint256.

• It provides bitwise operations for setting and retrieving specific flags, enabling efficient handling of multiple boolean conditions in a single storage slot.

Inheritance

• This library does not inherit from any other contract or library.

Key Methods

• getFlag: Retrieves the boolean status of a specific flag within a packed set of flags.

• setFlag: Sets or unsets a specific flag within a packed set of flags.

All Functions

Public Constants (Auto-generated getters)

• UNWRAP_ETH(): Returns the constant value 0. Represents a flag to unwrap ETH.

• REVERT_IF_EXTERNAL_FAIL(): Returns the constant value 1. Represents a flag to revert if an external call fails.

• PROXY_WITH_SENDER(): Returns the constant value 2. Represents a flag to call a proxy with a sender contract.

• SEND_HASHED_DATA(): Returns the constant value 3. Represents a flag indicating data is hashed in DeBridgeGate send method.

• SEND_EXTERNAL_CALL_GAS_LIMIT(): Returns the constant value 4. Represents a flag indicating the first 24 bytes from data is the gas limit for an external call.

• MULTI_SEND(): Returns the constant value 5. Represents a flag supporting multiple sends for external calls.

Internal Functions

• getFlag(uint256 _packedFlags, uint256 _flag) returns (bool):

  • Checks if a particular bit (flag) is set in _packedFlags.

• setFlag(uint256 _packedFlags, uint256 _flag, bool _value) returns (uint256):

  • Sets or clears a particular bit (flag) in _packedFlags based on _value.

Events

• None.

Interacts With

• This library does not directly interact with external contracts.

---

19. IBeneficiaryRegistry (Interface)

Purpose

• Manages and tracks crypto legacy addresses associated with different entity roles (e.g., beneficiary, owner, guardian, recovery).

• Provides mechanisms to add or remove crypto legacy addresses under these roles.

Inheritance

• None (This is a standalone interface.)

Key Methods

• Role Management: Add or remove crypto legacy addresses for specific roles.

• Recovery Addresses Update: Allows bulk update of old and new recovery addresses.

• Retrieval Function: Fetches all crypto legacy addresses categorized by role.

All Functions

1. setCryptoLegacyBeneficiary(bytes32 _beneficiary, bool _isAdd) external

   • Adds or removes a crypto legacy address associated with a specific beneficiary identifier.

2. setCryptoLegacyOwner(bytes32 _owner, bool _isAdd) external

   • Adds or removes a crypto legacy address for an owner identifier.

3. setCryptoLegacyGuardian(bytes32 _guardian, bool _isAdd) external

   • Adds or removes a crypto legacy address for a guardian identifier.

4. setCryptoLegacyRecoveryAddresses(bytes32[] memory _oldRecoveryAddresses, bytes32[] memory _newRecoveryAddresses) external

   • Replaces outdated or old recovery address identifiers with new ones, ensuring continuity of recovery options.

5. getAllCryptoLegacyListByRoles(bytes32 _hash) external view returns ( address[] memory listByBeneficiary, address[] memory listByOwner, address[] memory listByGuardian, address[] memory listByRecovery )

   • Retrieves all associated crypto legacy addresses sorted by entity role for a given identifier hash.

Events

• AddCryptoLegacyForBeneficiary(bytes32 indexed beneficiary, address indexed cryptoLegacy) Emitted when a crypto legacy address is added for a beneficiary.

• RemoveCryptoLegacyForBeneficiary(bytes32 indexed beneficiary, address indexed cryptoLegacy) Emitted when a crypto legacy address is removed from a beneficiary.

• AddCryptoLegacyForGuardian(bytes32 indexed guardian, address indexed cryptoLegacy) Emitted when a crypto legacy address is added for a guardian.

• RemoveCryptoLegacyForGuardian(bytes32 indexed guardian, address indexed cryptoLegacy) Emitted when a crypto legacy address is removed from a guardian.

• AddCryptoLegacyForRecovery(bytes32 indexed recovery, address indexed cryptoLegacy) Emitted when a crypto legacy address is added for a recovery role.

• RemoveCryptoLegacyForRecovery(bytes32 indexed recovery, address indexed cryptoLegacy) Emitted when a crypto legacy address is removed from a recovery role.

• AddCryptoLegacyForOwner(bytes32 indexed owner, address indexed cryptoLegacy) Emitted when a crypto legacy address is added for an owner.

• RemoveCryptoLegacyForOwner(bytes32 indexed owner, address indexed cryptoLegacy) Emitted when a crypto legacy address is removed from an owner.

Enum

• EntityType { NONE, OWNER, BENEFICIARY, GUARDIAN, RECOVERY } Used to categorize entity roles within the registry.

Interacts With

• None (As an interface, it defines the functions and events that other contracts must implement, but does not directly interact with any external contracts on its own.)

---

20. IBuildManagerOwnable (Interface)

Purpose

• Defines a set of events and custom errors related to build manager ownership.

• Serves as an interface to standardize the addition and removal of build managers.

Inheritance

• No inherited contracts or interfaces.

Key Methods

• No explicit functions are defined in this interface (it only declares events and errors).

All Functions

• None (no public/external/internal/private functions).

Events

• AddBuildManager(address indexed buildManager): Emitted when a build manager is successfully added.

• RemoveBuildManager(address indexed buildManager): Emitted when a build manager is removed.

Errors

• NotTheOwnerOfCryptoLegacy(): Indicates that the caller is not recognized as the owner of CryptoLegacy.

• CryptoLegacyNotRegistered(): Signifies that CryptoLegacy is not registered in the system.

• BuildManagerNotAdded(): Thrown if a specified build manager is not found in the records.

Interacts With

• Designed to be implemented by contracts that manage build manager ownership.

• No direct interactions with external contracts within this interface.

---

21. ICallProxy (Interface)

Purpose

• Defines a standard interface for cross-chain or multi-chain call execution.

• Facilitates calls that may transfer native assets or ERC20 tokens across chain boundaries.

Inheritance

• None (this is a standalone interface).

Key Methods

• call: Executes a call involving native asset transfer.

• callERC20: Executes a call involving ERC20 token transfer.

All Functions

• submissionChainIdFrom() (external): Returns the chain ID from which the current submission originated.

• submissionNativeSender() (external): Returns the native sender address (in bytes) of the current submission.

• call( address _reserveAddress, address _receiver, bytes memory _data, uint256 _flags, bytes memory _nativeSender, uint256 _chainIdFrom ) (external, payable): Executes a call with the possibility of transferring native assets.

  • _reserveAddress: Fallback recipient if the main call fails.

  • _receiver: Address of the contract to be called.

  • _data: Encoded function call data.

  • _flags: Configuration for special handling.

  • _nativeSender: The original sender in byte format.

  • _chainIdFrom: ID of the originating chain.

• callERC20( address _token, address _reserveAddress, address _receiver, bytes memory _data, uint256 _flags, bytes memory _nativeSender, uint256 _chainIdFrom ) (external): Executes a call with the possibility of transferring ERC20 tokens.

  • _token: The ERC20 token address.

  • _reserveAddress: Fallback recipient if the main call fails.

  • _receiver: Address of the contract to be called.

  • _data: Encoded function call data.

  • _flags: Configuration for special handling.

  • _nativeSender: The original sender in byte format.

  • _chainIdFrom: ID of the originating chain.

Events

• None in this interface.

Interacts With

• Implementing contracts or external systems that handle cross-chain bridging and call execution.

---

22. ICryptoLegacy (Interface)

Purpose

• Primary interface defining the core functionality for a “Crypto Legacy” system.

• Manages fees, beneficiary configurations, token distributions, and plugin/facet updates.

Inheritance

• None declared in the snippet (it’s a standalone interface).

Key Methods

• buildManager(): Returns the address of the build manager (ICryptoLegacyBuildManager).

• owner(): Returns the owner’s address.

All Functions

• buildManager() (external, view):

  • Retrieves the ICryptoLegacyBuildManager instance managing build operations.

• owner() (external, view):

  • Returns the owner address of this contract/implementation.

(No constructors, fallback, or receive functions are present in this interface.)

Events

• PauseSet(bool indexed isPaused) Emitted whenever the contract’s pause state is toggled.

• Update(uint256 updateFee, bytes32 indexed byPlugin) Emitted when an update occurs, detailing the fee and an associated plugin identifier.

• FeePaidByLifetime(bytes8 indexed refCode, bool indexed initial, address factory, uint64 lastFeePaidAt) Logs a lifetime fee payment event, including reference code and factory details.

• FeePaidByDefault(bytes8 indexed refCode, bool indexed initial, uint256 value, address factory, uint64 lastFeePaidAt) Logs a standard fee payment event with the ref code, payment value, and timestamp.

• FeePaidByTransfer(bytes8 indexed refCode, bool indexed initial, uint256 value, address factory, uint64 lastFeePaidAt) Emitted when fees are paid through a token transfer, including relevant metadata.

• FeeSentToRefByTransfer(bytes8 indexed refCode, uint256 value, address referral) Logs the portion of fees sent to a referral address.

• BeneficiaryClaim(address indexed token, uint256 amount, bytes32 indexed beneficiary) Emitted when a beneficiary successfully claims tokens.

• TransferTreasuryTokensToLegacy(address[] holders, address[] tokens) Emitted during a treasury token transfer into this legacy contract.

• TransferTokensFromLegacy(ICryptoLegacy.TokenTransferTo[] transfers) Logs token transfers executed from the legacy contract to specified recipients.

• AddFunctions(address _facetAddress, bytes4[] _functionSelectors, uint16 selectorPosition) Emitted when new function selectors are added to a facet in this contract’s architecture.

• RemoveFunctions(address _facetAddress, bytes4[] _functionSelectors) Emitted when existing function selectors are removed from a facet.

Errors

• DisabledFunc(): Thrown when a function has been disabled.

• NotTheOwner(): Caller is not the owner.

• NotTheBeneficiary(): Caller is not the designated beneficiary.

• TooEarly(): A call or claim is made before the allowed time.

• IncorrectFee(uint256 requiredFee): Fee provided does not match the required fee.

• ZeroAddress(): An invalid zero address was encountered.

• ZeroTokens(): Token amount is zero (invalid).

• InitialFeeNotPaid(): The initial fee required has not been paid.

• InitialFeeAlreadyPaid(): The initial fee is already paid; a duplicate payment is not allowed.

• NotBuildManager(): The caller is not the recognized build manager.

• AlreadyInit(): A function or process was called after initialization was already completed.

• LengthMismatch(): Arrays or input lengths do not match.

• ShareSumDoesntMatchBase(): Sum of shares does not align with expected base values.

• DistributionStarted(): An action was attempted after the distribution process had begun.

• DistributionStartAlreadySet(): Distribution start time was already established and cannot be reset.

• DistributionDelay(): A required delay for distribution has not yet passed.

• AlreadySet(): A value has already been set and cannot be changed.

• BeneficiaryNotSet(): A beneficiary address or configuration is missing.

• Pause(): The contract is paused, preventing this action.

• IncorrectFacetCutAction(): A facet cut action was invalid (e.g., add, replace, remove not properly specified).

• NotContractOwner(): A function requiring contract ownership was called by a non-owner.

• FacetNotFound(): Attempt to reference a facet that does not exist.

• FacetHasNoCode(): A facet address provided contains no code.

• NoSelectorsInFacetToCut(): Attempted to cut a facet with no function selectors.

• FacetCantBeZero(): Provided a zero address for a facet.

• CantRemoveImmutableFunctions(): Attempt to remove an immutable function that cannot be changed.

• CantAddFunctionThatAlreadyExists(): Tried adding a function selector already present.

• CantReplaceFunctionWithSameFunction(): Attempted to replace a function with itself.

• InitFunctionReverted(): An initialization function call reverted during a facet update.

• InitAddressZeroButCalldataIsNot(): The init function address is zero, but calldata is non-zero.

• InitCalldataZeroButAddressIsNot(): The init function address is non-zero, but calldata is zero.

• PluginNotRegistered(): A plugin used is not registered or recognized.

Interacts With

• ICryptoLegacyBuildManager: Provides build management or upgrade information.

• EnumerableSet: Used internally for managing sets of beneficiary data (via EnumerableSet.Bytes32Set).

---

23. ICryptoLegacyBuildManager (Interface)

ICryptoLegacyBuildManager

Purpose

• Main interface to build and manage a “CryptoLegacy.”

• Handles referral codes, cross-chain fees, plugin registrations, beneficiary registries, and various fee payment actions.

Inheritance

• It is an interface; no explicit parent contracts or interfaces are mentioned as inherited by ICryptoLegacyBuildManager.

Key Methods

• payInitialFee(...) and payFee(...): Allow users to pay fees associated with building or updating a “CryptoLegacy.”

• isLifetimeNftLocked(...) / isLifetimeNftLockedAndUpdate(...): Check if an NFT is locked (lifetime access or subscription), potentially updating state.

• isPluginRegistered(...): Verify if a plugin is recognized by the registry.

• isCryptoLegacyBuilt(...): Check if a particular “CryptoLegacy” instance is fully set up.

All Functions

• payInitialFee(bytes8 _code, address _toHolder, uint256[] memory _lockToChainIds, uint256[] memory _crossChainFees) external payable

  • Allows payment of an initial fee for setting up or initializing a “CryptoLegacy,” possibly referencing a referral code (_code) and distributing the fee across multiple chains.

• payFee(bytes8 _code, address _toHolder, uint256 _mul, uint256[] memory _lockToChainIds, uint256[] memory _crossChainFees) external payable

  • Allows payment of subsequent fees, possibly using a multiplier _mul and fee distribution across chains. Also references a referral code.

• getUpdateFee(bytes8 _refCode) external returns (uint256)

  • Retrieves the fee required to update a “CryptoLegacy” associated with a particular referral code _refCode.

• isLifetimeNftLocked(address _owner) external view returns (bool)

  • Checks if the _owner has a locked lifetime NFT, indicating no further fees may be needed.

• isLifetimeNftLockedAndUpdate(address _owner) external returns (bool)

  • Similar to the above but potentially updates internal state upon query.

• isPluginRegistered(address _plugin) external view returns (bool)

  • Verifies if a plugin address is registered in the system.

• isCryptoLegacyBuilt(address _cryptoLegacy) external view returns (bool)

  • Checks if the specified _cryptoLegacy contract has been successfully built or initialized.

• pluginsRegistry() external view returns (IPluginsRegistry)

  • Returns the address of the associated plugins registry contract.

• getFactoryAddress() external view returns (address)

  • Retrieves the address of the factory used to create new “CryptoLegacy” instances.

• beneficiaryRegistry() external view returns (IBeneficiaryRegistry)

  • Returns the address of the associated beneficiary registry contract.

• externalLens() external view returns (address)

  • Returns the address of an external lens contract used for extended views or data retrieval.

(No constructor, fallback, or receive function, as this is an interface.)

Events

• CreateRef(address indexed sender, bytes8 indexed refCode, address indexed recipient, uint256[] chainIds)

  • Emitted when a new referral is created.

• CreateCustomRef(address indexed sender, bytes8 indexed refCode, address indexed recipient, uint256[] chainIds)

  • Emitted when a custom referral code is created.

• SetCrossChainsRef(address indexed sender, uint256[] chainIds)

  • Emitted when cross-chain references or fees are updated.

• WithdrawFee(address indexed recipient, uint256 indexed amount)

  • Emitted when fees are withdrawn to a specified recipient.

• SetRegistries(address indexed feeRegistry, address indexed pluginsRegistry, address indexed beneficiaryRegistry)

  • Emitted when registry addresses are set or updated.

• SetFactory(address indexed factory)

  • Emitted when the factory address is updated.

• SetSupplyLimit(uint256 supplyLimit)

  • Emitted when a supply limit is defined or updated.

• SetExternalLens(address indexed externalLens)

  • Emitted when the external lens contract address is updated.

• PaidForMint(address indexed sender, uint256 indexed tokenId, address indexed toHolder)

  • Emitted when a payment is made specifically for minting an NFT.

• PaidForMultipleNft(address indexed sender, bytes8 indexed code, uint256 value, uint256 totalAmount)

  • Emitted when payment is made for multiple NFTs, possibly referencing a referral code.

• Build(address indexed sender, address indexed cryptoLegacy, address[] plugins, bytes32[] beneficiaryHashes, ICryptoLegacy.BeneficiaryConfig[] beneficiaryConfig, bool isPaid, uint64 updateInterval, uint64 challengeTimeout)

  • Emitted when a complete “CryptoLegacy” is built or deployed, with beneficiary and plugin details.

Errors

• AlreadyLifetime()

  • Thrown if an attempt is made to acquire a lifetime NFT or benefit when already in that state.

• NotValidTimeout()

  • Thrown if a provided timeout or waiting period is invalid.

• IncorrectFee(uint256 feeToTake)

  • Thrown if the fee provided in a payment function does not match the expected fee.

• BellowMinimumSupply(uint256 supplyLimit)

  • Thrown if a supply limit is set below the minimum allowable threshold.

Interacts With

• IBeneficiaryRegistry: For managing or retrieving beneficiary-related data.

• IPluginsRegistry: For registering or verifying plugins that can be attached to a “CryptoLegacy.”

• ICryptoLegacy: For checking and configuring “CryptoLegacy” instances.

---

24. ICryptoLegacyDiamondBase (Interface)

Purpose

• Defines core events and error types that may be used throughout a diamond-based architecture (a style of upgradeable contract system).

Inheritance

• None. This interface does not inherit from other contracts or interfaces.

Key Methods

• No explicit function definitions are declared.

  • This interface primarily declares events and errors, which are foundational for implementing diamond functionality or handling specific conditions.

All Functions

• No functions (no constructors, fallback, or receive functions).

Events

• StaticCallCheck Emitted to indicate a static call check has occurred, possibly used for security validation or upgrade checks.

Errors

• FunctionNotExists(bytes4 selector) Thrown when a function corresponding to the given function selector does not exist in the diamond.

• NotSelfCall() Thrown when a function is called by a contract other than itself, enforcing a self-call requirement.

Interacts With

• No direct interactions specified.

  • As an interface, it simply defines the blueprint (events and errors) that implementing contracts or facets can utilize.

---

25. ICryptoLegacyFactory (Interface)

Purpose

An interface responsible for creating new CryptoLegacy contracts and managing build operators. It encapsulates factory creation logic using create2 parameters for deterministic contract deployment.

Inheritance

• No direct inheritance is shown.

• Imports:

  • ICryptoLegacy for referencing CryptoLegacy-related functionality.

  • stdMath for potential math operations (though not used directly in the snippet).

Key Methods

• createCryptoLegacy(...): Main method to deploy a new CryptoLegacy contract with specified parameters.

• setBuildOperator(...): Manage permissions for build operators who can create or modify build logic.

All Functions

1. createCryptoLegacy(address _owner, address[] memory _plugins, Create2Args memory _create2Args) external returns (address payable)

   • Deploys a new CryptoLegacy contract owned by _owner, optionally loading _plugins.

   • Accepts a create2Salt and create2Address for deterministic deployment (Create2Args).

2. setBuildOperator(address _operator, bool _isAdd) external

   • Adds or removes a build operator.

   • If _isAdd is true, _operator is designated as a build operator; otherwise, it is removed.

Events

• AddBuildOperator(address indexed buildOperator) Emitted when a new build operator is added.

• RemoveBuildOperator(address indexed buildOperator) Emitted when an existing build operator is removed.

Errors

• NotBuildOperator() Thrown when an unauthorized address attempts to perform an action reserved for a build operator.

Interacts With

• ICryptoLegacy: The interface for deployed CryptoLegacy contracts.

• Potentially other contracts or systems needing deterministic deployment via create2.

---

26. ICryptoLegacyLens (Interface)

Purpose

• Provides read-only or "view" utility functions to inspect various data within a CryptoLegacy ecosystem.

• Retrieves block numbers associated with messages, vesting and claimed data, and other detailed legacy-related configurations.

Inheritance

• Imports: ICryptoLegacy (though not inherited, it is directly referenced).

Key Methods

• Data Retrieval Functions: Simplify viewing of beneficiary and plugin-related data without modifying state.

All Functions

1. getMessagesBlockNumbersByRecipient(bytes32 _recipient) (external view)

   • Returns an array of block numbers associated with messages for the specified _recipient.

2. getVestedAndClaimedData(bytes32 _beneficiary, address[] memory _tokens) (external view)

   • Returns:

     • An array of BeneficiaryTokenData (containing vested, claimed, and total amounts).

     • The startDate and endDate for the vesting period.

   • Useful for tracking how much a beneficiary has vested and claimed across multiple token addresses.

3. getCryptoLegacyBaseData() (external view)

   • Returns a CryptoLegacyBaseData struct with various configuration details (fees, intervals, timestamps, and default function toggles).

4. getCryptoLegacyListData(address[] memory _tokens) (external view)

   • Returns a CryptoLegacyListData struct, including:

     • Arrays of beneficiaries and original hashes,

     • Lists of plugin info,

     • Beneficiary configuration arrays,

     • Token distribution details.

   • Consolidates high-level snapshot data relevant to a CryptoLegacy contract setup.

Events

• None.

  • No events are declared within ICryptoLegacyLens.

Interacts With

• ICryptoLegacy: Utilizes structures (BeneficiaryConfig, TokenDistribution) defined in the ICryptoLegacy interface.

---

27. ICryptoLegacyOwnable (Interface)

Purpose

• This interface defines the event structure for an ownership transfer mechanism.

• Typically used by contracts that implement ownership-based access control.

Inheritance

• Not applicable (this is an interface; it does not inherit other contracts or interfaces in the provided code).

Key Methods

• None. This interface only declares an event.

All Functions

• No functions defined in this interface.

  • There are no public, external, internal, private, fallback, or receive functions declared.

Events

• OwnershipTransferred(address indexed previousOwner, address indexed newOwner)

  • Emitted when the contract ownership changes from previousOwner to newOwner.

Interacts With

• Not applicable. As an interface, it is designed to be inherited by other contracts rather than directly interacting with external components.

---

28. ICryptoLegacyPlugin (Interface)

Purpose

• This interface defines the essential functions for a “CryptoLegacy” plugin, which can be used to interact with and retrieve plugin-specific metadata or signatures.

Inheritance

• None. This is a standalone interface.

Key Methods

• Metadata Retrieval: Methods like getPluginName() and getPluginVer() provide plugin identification.

• Function Signature Discovery: Methods like getSigs() and getSetupSigs() reveal function signatures required by external systems.

All Functions

• getSigs() (external view): Returns an array of function signatures supported by this plugin.

• getSetupSigs() (external view): Returns an array of setup or initialization-related function signatures for this plugin.

• getPluginName() (external view): Provides the human-readable name of the plugin.

• getPluginVer() (external view): Returns the plugin’s version number as a 16-bit integer.

Events

• None. This interface does not define or emit any events.

Interacts With

• Designed to integrate with a larger “CryptoLegacy” system or contracts that call these methods to dynamically discover function signatures and metadata.

---

29. ICryptoLegacyUpdaterPlugin (Interface)

Purpose

Defines the structure for managing updaters in a crypto legacy context. This interface specifies events and an error to be implemented in inheriting contracts.

Inheritance

• None (this is a standalone interface).

Key Methods

• No callable functions are defined in this interface.

All Functions

• No functions exist in this interface.

Events

• AddUpdater(address indexed owner, address indexed updater): Emitted when a new updater is added by an owner.

• RemoveUpdater(address indexed owner, address indexed updater): Emitted when an updater is removed by an owner.

Errors

• NotTheUpdater(): Reverts when a caller who is not an authorized updater attempts an updater-only action.

Interacts With

• No direct contract interactions. This interface is intended to be implemented by other contracts.

---

30. IDeBridgeGate (Interface)

Purpose

• IDeBridgeGate is an interface defining a cross-chain bridging protocol, enabling the locking, minting, and transferring of assets across different blockchain networks.

• It also defines methods to send arbitrary messages and execute external calls on a destination chain.

Inheritance

• No direct inheritance since this is an interface. Contracts that implement this interface will provide the actual logic.

Key Methods

• Asset Transfer: send(), claim(), withdrawFee() to lock, mint/unlock, and withdraw fees for bridged assets.

• Message Passing: Overloaded sendMessage() functions enable cross-chain call execution instructions.

• Fee Management: Provides consistent fee parameters (globalFixedNativeFee(), globalTransferFeeBps()) for bridging logic.

• Utility: Functions for checking submissions (isSubmissionUsed()) and retrieving token/native chain information (getNativeInfo()).

All Functions

Note: There are no constructors, fallback, or receive functions in this interface.

1. isSubmissionUsed(bytes32 submissionId) external view returns (bool)

   • Checks if a transfer submission has been utilized (claimed) already.

2. getNativeInfo(address token) external view returns (uint256 nativeChainId, bytes memory nativeAddress)

   • Returns the original chain ID and native address of a wrapped token.

3. callProxy() external view returns (address)

   • Provides the address of the proxy contract used for executing external calls on the destination chain.

4. globalFixedNativeFee() external view returns (uint256)

   • Returns the fallback fixed fee (in native tokens) applied if a specific chain fee is not set.

5. globalTransferFeeBps() external view returns (uint16)

   • Returns the fallback transfer fee in basis points, applied if a specific chain transfer fee is not set.

6. sendMessage(uint256 _dstChainId, bytes memory _targetContractAddress, bytes memory _targetContractCalldata) external payable returns (bytes32 submissionId)

   • Submits a message to another chain to call a target contract with provided calldata; uses default flags.

7. sendMessage(uint256 _dstChainId, bytes memory _targetContractAddress, bytes memory _targetContractCalldata, uint256 _flags, uint32 _referralCode) external payable returns (bytes32 submissionId)

   • Similar to the above but accepts custom flags and a referral code for flexible execution settings.

8. send(address _tokenAddress, uint256 _amount, uint256 _chainIdTo, bytes memory _receiver, bytes memory _permitEnvelope, bool _useAssetFee, uint32 _referralCode, bytes calldata _autoParams) external payable returns (bytes32 submissionId)

   • Locks/mints an asset on the native chain and transfers it to another chain. Allows setting auto-execution parameters and referral code.

9. claim(bytes32 _debridgeId, uint256 _amount, uint256 _chainIdFrom, address _receiver, uint256 _nonce, bytes calldata _signatures, bytes calldata _autoParams) external

   • Unlocks an asset on its native chain for a specified receiver, if properly signed by validators.

10. withdrawFee(bytes32 _debridgeId) external

    • Withdraws collected protocol fees for a given bridged asset identifier.

11. getDebridgeChainAssetFixedFee(bytes32 _debridgeId, uint256 _chainId) external view returns (uint256)

    • Retrieves the asset-specific fixed fee for a given chain.

Events

1. Sent(bytes32 submissionId, bytes32 indexed debridgeId, uint256 amount, bytes receiver, uint256 nonce, uint256 indexed chainIdTo, uint32 referralCode, FeeParams feeParams, bytes autoParams, address nativeSender)

   • Emitted when tokens are sent from the native chain to another chain.

2. Claimed(bytes32 submissionId, bytes32 indexed debridgeId, uint256 amount, address indexed receiver, uint256 nonce, uint256 indexed chainIdFrom, bytes autoParams, bool isNativeToken)

   • Emitted when tokens are claimed and withdrawn on the destination chain.

3. PairAdded(bytes32 debridgeId, address tokenAddress, bytes nativeAddress, uint256 indexed nativeChainId, uint256 maxAmount, uint16 minReservesBps)

   • Emitted when a new token pair is added for bridging.

4. MonitoringSendEvent(bytes32 submissionId, uint256 nonce, uint256 lockedOrMintedAmount, uint256 totalSupply)

   • Emitted for monitoring purposes when tokens are sent.

5. MonitoringClaimEvent(bytes32 submissionId, uint256 lockedOrMintedAmount, uint256 totalSupply)

   • Emitted for monitoring purposes when tokens are claimed.

6. ChainSupportUpdated(uint256 chainId, bool isSupported, bool isChainFrom)

   • Emitted when support for a specific chain is enabled or disabled.

7. ChainsSupportUpdated(uint256 chainIds, ChainSupportInfo chainSupportInfo, bool isChainFrom)

   • Emitted when multiple chains’ support status and details are updated.

8. CallProxyUpdated(address callProxy)

   • Emitted when the call proxy address is updated.

9. AutoRequestExecuted(bytes32 submissionId, bool indexed success, address callProxy)

   • Emitted when an auto-request call is executed on the destination chain.

10. Blocked(bytes32 submissionId)

    • Emitted when a submission is blocked.

11. Unblocked(bytes32 submissionId)

    • Emitted when a submission is unblocked.

12. WithdrawnFee(bytes32 debridgeId, uint256 fee)

    • Emitted when protocol fees are withdrawn.

13. FixedNativeFeeUpdated(uint256 globalFixedNativeFee, uint256 globalTransferFeeBps)

    • Emitted when the fallback fixed and transfer fees are updated.

14. FixedNativeFeeAutoUpdated(uint256 globalFixedNativeFee)

    • Emitted when the fallback native fee is automatically updated by the fee contract updater.

Interacts With

• This interface is typically implemented by a bridging contract interacting with:

  • Various chain environments (locking/unlocking assets, verifying signatures, paying fees).

  • External call proxy (via callProxy).

---

31. IDiamondCut (Interface)

Purpose

• Defines the standard interface for adding, replacing, or removing functions from a “Diamond” contract as per EIP-2535.

Inheritance

• This is a standalone interface with no inherited contracts or interfaces.

Key Methods

• diamondCut(...): The primary function for updating the diamond facets (adding, replacing, or removing function selectors).

All Functions

• diamondCut(FacetCut[] calldata _diamondCut, address _init, bytes calldata _calldata) external

  • Initiates modifications to the diamond by adding, replacing, or removing facets.

  • Optionally executes a delegatecall on _init with the provided _calldata.

Events

• DiamondCut(FacetCut[] _diamondCut, address _init, bytes _calldata)

  • Emitted whenever a successful facet cut operation occurs, detailing changes and the optional function call data.

Additional Structures

• Enum FacetCutAction:

  • Add (0): Insert new function selectors.

  • Replace (1): Swap out existing function selectors.

  • Remove (2): Eliminate specified function selectors.

• Struct FacetCut:

  • facetAddress: The address of the facet contract.

  • action: The type of operation to perform (Add, Replace, or Remove).

  • functionSelectors: A list of function selectors to modify.

Interacts With

• Designed for Diamond (EIP-2535) contracts that implement multiple facets.

• No direct interactions with other contracts are defined within this interface itself, but implementing contracts will rely on it for diamond operations.

---

32. IDiamondLoupe (Interface)

Purpose

• This interface defines the standard loupe methods for EIP-2535 (Diamond Standard).

• Designed to enable external tools and consumers to query facet information of a Diamond contract.

Inheritance

• No explicit inheritance. This is a standalone interface defining Diamond loupe functions.

Key Methods

• Querying and retrieving facet data such as addresses and selectors.

All Functions

• facets() (external, view): Returns an array of Facet structs, each containing a facet address and its associated function selectors.

• facetFunctionSelectors(address _facet) (external, view): Given a facet address, returns the list of function selectors supported by that facet.

• facetAddresses() (external, view): Retrieves a list of all unique facet addresses used by the Diamond.

• facetAddress(bytes4 _functionSelector) (external, view): Returns the facet address that supports a given function selector. If none is found, returns address(0).

Events

• No events are declared in this interface.

Interacts With

• Diamond (EIP-2535): The methods in this interface are typically called by external contracts, libraries, or tools to examine facets within a Diamond-compliant contract.

---

33. IFeeRegistry (Interface)

Purpose

• Provides a structured way to define and manage fees, discount rates, referral codes, and accumulated fees.

• Facilitates fee collection (takeFee) and creation of referral codes across different chains.

Inheritance

• This is an interface and does not inherit from any parent contract.

• Utilizes OpenZeppelin’s EnumerableSet library indirectly through its storage struct definitions.

Key Methods

• takeFee(): Central function to deduct fees based on contract cases and referral codes.

• createCustomCode() / createCode(): Allows creation of new referral codes with optional cross-chain support.

All Functions

• getContractCaseFee(address _contract, uint8 _case) external view returns(uint256) Returns the fee amount associated with a given contract and case index.

• getContractCaseFeeForCode(address _contract, uint8 _case, bytes8 _code) external view returns(uint256 fee) Retrieves the fee for a specific contract, case, and referral code combination.

• takeFee(address _contract, uint8 _case, bytes8 _code, uint256 _mul) external payable Deducts fees for a given contract, case, and referral code. The _mul parameter can be used for scaled calculations.

• createCustomCode(address _referrer, address _recipient, bytes8 _shortCode, uint256[] memory _chainIds, uint256[] memory _crossChainFees) external payable returns(bytes8 code, uint256 totalFee) Creates a custom referral code _shortCode and optionally sets up cross-chain fees.

• createCode(address _referrer, address _recipient, uint256[] memory _chainIds, uint256[] memory _crossChainFees) external payable returns(bytes8 code, uint256 totalFee) Generates a referral code (automatically assigned) with optional cross-chain fee data.

• updateCrossChainsRef(address _referrer, uint256[] memory _chainIds, uint256[] memory _crossChainFees) external payable returns(uint256 totalFee) Updates existing cross-chain fee settings for a given referrer.

• accumulatedFee() external view returns(uint128) Returns the total accumulated fees in the system.

• getSupportedRefInChainsList() external view returns(uint256[] memory) Lists all chain IDs where referral codes are supported.

Events

• AddCodeOperator(address indexed codeOperator) Emitted when a new code operator is added.

• RemoveCodeOperator(address indexed codeOperator) Emitted when a code operator is removed.

• SetDefaultPct(uint32 defaultDiscountPct, uint32 defaultSharePct) Emitted when default discount and share percentages are updated.

• SetRefererSpecificPct(address indexed referrer, bytes8 indexed code, uint32 discountPct, uint32 sharePct) Emitted when a referrer-specific discount/share percentage is set.

• SetContractCaseFee(address indexed sourceContract, uint8 indexed contractCase, uint256 fee) Emitted when fees are assigned to a specific contract and case.

• TakeFee(address indexed sourceContract, uint8 indexed contractCase, bytes8 indexed code, uint256 discount, uint256 share, uint256 fee, uint256 value) Emitted when a fee is taken (collected).

• SentFee(address indexed referrer, bytes8 indexed code, address indexed recipient, uint256 value) Emitted when fees are distributed to a recipient.

• AccumulateFee(address indexed referrer, bytes8 indexed code, address indexed recipient, uint256 value) Emitted when fees accumulate for a referrer and code.

• CreateCode(address indexed codeOperator, address indexed referrer, bytes8 indexed code, address recipient, uint256 fromChain) Emitted upon creation of a new referral code.

• UpdateCode(address indexed codeOperator, address indexed referrer, bytes8 indexed code, address recipient, uint256 fromChain) Emitted when a referral code is updated.

• ChangeCode(address indexed oldReferrer, address indexed newReferrer, bytes8 indexed code) Emitted when referral ownership changes from one referrer to another.

• ChangeRecipient(address indexed referrer, address indexed newRecipient, bytes8 indexed code) Emitted when the recipient of a referral code is changed.

• SetCrossChainsRef(bytes8 indexed shortCode, bool indexed isCreate, uint256[] toChainIDs, uint256[] crossChainFees) Emitted when cross-chain referral data is created or updated.

• SetFeeBeneficiaries(FeeBeneficiary[] beneficiaries) Emitted when global fee beneficiaries are set or updated.

• AddSupportedRefCodeInChain(uint256 indexed chainId) Emitted when a chain ID is added to the list of supported referral code chains.

• RemoveSupportedRefCodeInChain(uint256 indexed chainId) Emitted when a chain ID is removed from the supported referral code list.

• WithdrawFee(address indexed beneficiary, uint256 value) Emitted when a beneficiary withdraws accumulated fees.

• WithdrawRefFee(address indexed recipient, uint256 value) Emitted when a recipient withdraws referral fees.

Errors

• PctSumDoesntMatchBase() Thrown when discount/share percentages do not sum up correctly.

• TooBigPct() Thrown when a percentage exceeds allowable limits.

• RefAlreadyCreated() Thrown when attempting to create a referral code that already exists.

• ZeroCode() Thrown when a referral code is zero.

• NotOperator() Thrown when a caller is not recognized as an operator.

• NotReferrer() Thrown when a caller does not match the expected referrer.

• AlreadyReferrer() Thrown when a caller is already assigned as a referrer.

• CodeNotCreated() Thrown when trying to update or manage a code that does not exist.

Interacts With

• EnumerableSet (OpenZeppelin) used for maintaining sets of chains, addresses.

• Other Contracts that call takeFee(), createCode(), etc., to manage fees.

---

34. ILockChainGate (Interface)

Purpose

• Manages cross-chain locking and unlocking of NFTs (referred to as “LifetimeNft”).

• Integrates with a bridge (DeBridge) to facilitate sending lock/unlock instructions across chains.

Inheritance

• This is an interface and does not inherit from any parent contract.

• Utilizes OpenZeppelin’s EnumerableSet library in its storage struct.

Key Methods

• lockLifetimeNft(): Locks an NFT to enable cross-chain functionality.

• isNftLocked(): Checks if an NFT is currently locked.

• calculateCrossChainCreateRefNativeFee(): Helps calculate native fees for cross-chain referral code creation (if integrated with fee registry).

All Functions

• lockLifetimeNft(uint256 _tokenId, address _owner, uint256[] memory _lockToChainIds, uint256[] memory _crossChainFees) external payable Locks an NFT for potential cross-chain actions; optionally includes cross-chain fees.

• isNftLocked(address _owner) external view returns(bool) Returns true if the NFT held by _owner is locked.

• isNftLockedAndUpdate(address _owner) external returns(bool) Checks if the NFT is locked, and updates internal state if necessary.

• calculateCrossChainCreateRefNativeFee(uint256[] memory _chainIds, uint256[] memory _crossChainFees) external view returns(uint256) Calculates the total native fee required to create cross-chain referral information.

Events

• AddLockOperator(address indexed lockOperator) Emitted when a lock operator is added.

• RemoveLockOperator(address indexed lockOperator) Emitted when a lock operator is removed.

• SetDestinationChainContract(uint256 indexed chainId, address indexed chainContract) Emitted when the contract address for a destination chain is updated.

• SetSourceChainContract(uint256 indexed chainId, address indexed chainContract) Emitted when the contract address for a source chain is updated.

• SetDeBridgeGate(address indexed deBridgeGate) Emitted when the DeBridgeGate address is set.

• SetDeBridgeNativeFee(uint256 indexed chainId, uint256 nativeFee) Emitted when the native fee for a specific chain is set.

• SetLockPeriod(uint256 lockPeriod) Emitted when the NFT lock period is set.

• SendToChain(uint256 indexed toChainId, bytes32 indexed submissionId, uint256 value, bytes dstTransactionCall) Emitted when a value is sent to another chain.

• LockNft(uint256 lockedAt, uint256 indexed tokenId, address indexed holder) Emitted when an NFT is locked.

• UnlockNft(uint256 lockedAt, uint256 indexed tokenId, address indexed holder, address indexed recipient) Emitted when an NFT is unlocked.

• ApproveNft(uint256 indexed tokenId, address indexed holder, address indexed approveTo) Emitted when an NFT is approved.

• TransferNft(uint256 indexed tokenId, address indexed holder, address indexed transferTo, uint256 fromChainID) Emitted when an NFT is transferred on-chain or cross-chain.

• LockToChain(address indexed sender, uint256 indexed tokenId, uint256 indexed toChainID, bytes32 submissionId) Emitted when an NFT is locked for bridging to a specific chain.

• UpdateLockToChain(address indexed sender, uint256 indexed tokenId, uint256 indexed toChainID, bytes32 submissionId) Emitted when lock data to a specific chain is updated.

• Update(address indexed sender, uint256 indexed tokenId, uint256 indexed toChainID, bytes32 submissionId) Emitted when an NFT lock or bridging data is updated.

• UnlockFromChain(address indexed sender, uint256 indexed tokenId, uint256 indexed toChainID, bytes32 submissionId) Emitted when an NFT is unlocked from another chain.

• CrossLockNft(uint256 lockedAt, uint256 indexed tokenId, address indexed holder, uint256 indexed fromChainID) Emitted when an NFT is cross-locked from another chain.

• CrossUnlockNft(uint256 lockedAt, uint256 indexed tokenId, address indexed holder, uint256 indexed fromChainID) Emitted when an NFT is cross-unlocked back to this chain.

• CrossUpdateNftOwner(uint256 indexed fromChainID, uint256 indexed tokenId, address indexed transferTo) Emitted when an NFT’s ownership is updated cross-chain.

• SetReferralCode(uint32 indexed referralCode) Emitted when a referral code is set.

• SetCustomChainId(uint256 indexed customChainId) Emitted when a custom chain ID is set for additional chain logic.

Errors

• AlreadyLocked() Thrown when attempting to lock an NFT that is already locked.

• LockedToChains() Thrown when an NFT is locked to multiple chains and cannot be operated on freely.

• CrossChainLock() Thrown when an action is attempted that conflicts with an existing cross-chain lock.

• TooEarly() Thrown when attempting an unlock or transfer before the lock period expires.

• DestinationChainNotSpecified() Thrown when a destination chain is not provided.

• TokenNotLocked() Thrown when an action requires the NFT to be locked, but it is not.

• TokenIdMismatch(uint256 checkTokenId) Thrown when provided token ID does not match locked token data.

• AlreadyLockedToChain() Thrown when an NFT is already locked to a specific chain.

• SourceNotSpecified() Thrown when a source chain is not provided.

• NotLockedByChain() Thrown when unlocking or updating an NFT that was not locked by a particular chain.

• DestinationNotSpecified() Thrown when an NFT transfer destination is not provided.

• NotAvailable() Thrown when the requested operation is not currently available.

• IncorrectFee(uint256 requiredFee) Thrown when the wrong fee amount is provided.

• SameAddress() Thrown when an operation is attempted with an identical address.

• RecipientLocked() Thrown when the recipient of an NFT is locked or otherwise unavailable.

• NotCallProxy() Thrown when a function is called by an entity that is not the designated call proxy.

• ChainIdMismatch() Thrown when the chain ID does not match the expected value.

• NotValidSender() Thrown when a function is called by an address that is not valid for the current context.

• NotAllowed() Thrown when attempting to perform an action that is not permitted.

Interacts With

• IDeBridgeGate for cross-chain bridging operations.

• ILifetimeNft for NFT lock/unlock functionalities.

• EnumerableSet (OpenZeppelin) for managing lock operators and chain sets.

---

35. ILegacyMessenger (Interface)

Purpose

• Defines a standard interface for legacy message handling and checking within a system.

Inheritance

• None (this interface does not inherit from other interfaces or contracts).

Key Methods

• No callable functions are defined in this interface; it strictly declares events.

All Functions

• None (no functions, constructors, fallback, or receive functions are declared).

Events

• LegacyMessage:

  • Emitted when a legacy message is transmitted.

  • Parameters:

    • toRecipient: The recipient’s identifier.

    • messageHash: Hash of the message content.

    • message: The actual message payload.

    • messageType: An integer specifying the type of the message.

• LegacyMessageCheck:

  • Emitted when a legacy message check is performed.

  • Parameters:

    • toBeneficiary: The beneficiary’s identifier.

    • messageHash: Hash of the message content.

    • message: The actual message payload.

    • messageType: An integer specifying the type of the message.

Interacts With

• No direct interactions with other contracts are specified in this interface.

---

36. ILido (Interface)

Purpose

• An interface for interacting with Lido staking functionality.

• Allows submitting Ether to Lido, transferring shares, and querying share balances.

Inheritance

• None (This is a standalone interface.)

Key Methods

• Staking and Share Transfer: Methods to submit Ether and transfer share ownership.

All Functions

• submit(address _referral) external payable returns (uint256) Allows submitting Ether to Lido, with an optional referral address.

  • Visibility: External (payable)

  • Returns: Amount of minted shares (as uint256)

• transferShares(address _recipient, uint256 _sharesAmount) external returns (uint256) Transfers a specified amount of shares to a recipient.

  • Visibility: External

  • Returns: Number of transferred shares (as uint256)

• transferSharesFrom(address _sender, address _recipient, uint256 _sharesAmount) external returns (uint256) Transfers a specified amount of shares from a sender to a recipient, typically requiring allowance or permissions.

  • Visibility: External

  • Returns: Number of transferred shares (as uint256)

• sharesOf(address _account) external view returns (uint256) Fetches the number of shares held by a specific account.

  • Visibility: External (view)

  • Returns: Balance of shares (as uint256)

Events

• None (No events defined in this interface.)

Interacts With

• Expected to be implemented by Lido contracts that handle staking and share accounting.

---

37. ILifetimeNft (Interface)

Purpose

• Defines a specialized NFT interface intended for “lifetime” tokens or memberships.

• Extends OpenZeppelin’s IERC721Enumerable interface to support enumerability of tokens.

• Introduces an additional enum Tier for categorizing tokens under different tiers.

Inheritance

• IERC721Enumerable (from OpenZeppelin)

  • Inherits from IERC721, which in turn inherits from IERC165.

Key Methods

• mint(address _tokenOwner): Allows minting a new token to a specified address.

• setMinterOperator(address _minter, bool _isActive): Grants or revokes minting permission for a particular address.

• enum Tier: Defines various membership or token tiers (None, Silicon, Gallium, Indium, Based, Tantalum).

All Functions

From IERC165:

• supportsInterface(bytes4 interfaceId) external view returns (bool)

  • Checks if a contract implements a specific interface.

From IERC721:

• balanceOf(address owner) external view returns (uint256 balance)

  • Returns the number of tokens owned by an address.

• ownerOf(uint256 tokenId) external view returns (address owner)

  • Returns the address that owns a specific token.

• safeTransferFrom(address from, address to, uint256 tokenId) external

  • Safely transfers a token, checking first that the recipient can handle ERC721 tokens.

• transferFrom(address from, address to, uint256 tokenId) external

  • Transfers a token without safety checks.

• approve(address to, uint256 tokenId) external

  • Approves another address to manage a specific token.

• setApprovalForAll(address operator, bool _approved) external

  • Approves or removes an operator to manage all of the caller’s tokens.

• getApproved(uint256 tokenId) external view returns (address operator)

  • Returns the address approved for a specific token.

• isApprovedForAll(address owner, address operator) external view returns (bool)

  • Returns whether an operator is approved to manage all tokens of an owner.

From IERC721Enumerable:

• totalSupply() external view returns (uint256)

  • Returns the total amount of tokens in circulation.

• tokenOfOwnerByIndex(address owner, uint256 index) external view returns (uint256 tokenId)

  • Returns a token ID owned by owner at a specific index.

• tokenByIndex(uint256 index) external view returns (uint256)

  • Returns a token ID at a given index of all tokens.

Declared in ILifetimeNft:

• mint(address _tokenOwner) external returns (uint256 tokenId)

  • Mints a new token for _tokenOwner; returns the newly assigned token ID.

• setMinterOperator(address _minter, bool _isActive) external

  • Enables or disables _minter to call mint.

Events

Inherited from IERC721:

• Transfer(address indexed from, address indexed to, uint256 indexed tokenId)

  • Emitted when a token is transferred from one owner to another.

• Approval(address indexed owner, address indexed approved, uint256 indexed tokenId)

  • Emitted when the owner of a token approves another address to manage the token.

• ApprovalForAll(address indexed owner, address indexed operator, bool approved)

  • Emitted when the owner enables or disables an operator to manage all tokens.

(No additional custom events are defined in ILifetimeNft.)

Errors

• NotTheMinter()

  • Thrown when a function requiring minter permission is called by an unauthorized address.

Interacts With

• Relies on OpenZeppelin’s IERC721Enumerable and its underlying ERC721 functionality.

---

38. IPluginsRegistry (Interface)

Purpose

• Defines the interface for a plugin registry system, allowing the addition, removal, and description of plugins.

Inheritance

• None. This is a standalone interface without any inherited contracts or interfaces.

Key Methods

• Registration & Lookup: Functions to check if a plugin is registered and retrieve related block numbers.

All Functions

• getPluginDescriptionBlockNumbers(address _plugin) -> uint64[] (external view)

  • Returns an array of block numbers at which descriptions were added for a specific plugin.

• isPluginRegistered(address _plugin) -> bool (external view)

  • Checks whether a given plugin is registered in the system.

Events

• AddPlugin(address indexed plugin, string description)

  • Emitted when a new plugin is added with its initial description.

• AddPluginDescription(address indexed plugin, string description)

  • Emitted when an additional description is added for an existing plugin.

• RemovePlugin(address indexed plugin)

  • Emitted when a plugin is removed from the registry.

Interacts With

• No direct interaction details are provided within this interface. Typically, implementing contracts will manage plugin storage and interactions.

---

39. ISafeMinimalMultisig (Interface)

Purpose

• Defines the interface for a minimal multi-signature scheme, including proposal creation, confirmation, and execution mechanics.

Inheritance

• None (this is a standalone interface in the snippet).

Key Methods

• As an interface, it declares behavior for multi-signature proposals but no function signatures are exposed in the snippet.

All Functions

• No explicit functions (public, external, internal, private, constructor, fallback, or receive) are declared within this interface snippet.

Events

• CreateSafeMinimalMultisigProposal(uint256 proposalId, bytes32 voter, uint256 reqConfirmations) Emitted when a new proposal is created, detailing the proposal ID, the voter who initiated it, and the required confirmations.

• ConfirmSafeMinimalMultisigProposal(uint256 proposalId, bytes32 voter, uint256 reqConfirmations, uint256 confirms) Emitted when a proposal is confirmed by a voter, providing the proposal ID, the voter, the required confirmations, and the current confirmation count.

• ExecuteSafeMinimalMultisigProposal(uint256 proposalId, bytes32 voter, bool executed, bytes returnData) Emitted upon execution of a proposal, indicating whether it succeeded and including any return data.

Errors

• MultisigAlreadyExecuted() Thrown when attempting to execute a proposal that has already been executed.

• MultisigAlreadyConfirmed() Thrown if a voter attempts to confirm a proposal they have already confirmed.

• MultisigExecutionFailed() Thrown when execution of the proposal fails for any reason.

• MultisigMethodNotAllowed() Thrown when a method is not permitted by the multi-signature scheme.

• MultisigVoterNotAllowed() Thrown if a caller is not recognized as a valid voter.

• MultisigOnlyExecutor() Thrown when a function is restricted to the designated executor only.

• MultisigIncorrectRequiredConfirmations() Thrown when the required confirmations parameter is invalid or improperly set.

Structs and Enums

• Storage Holds requiredConfirmations, an array of voters, the proposals, and a mapping to track who has confirmed each proposal.

• Proposal Contains the function selector, function parameters (params), the count of confirmations (confirms), and an execution flag (executed).

• ProposalWithStatus Extends Proposal with an array of booleans indicating which voters have confirmed it.

• InitializationStatus An enum indicating whether the multi-signature storage is initialized or not.

Interacts With

• Potentially interacts with the contract or module implementing the multi-signature logic.

• References ICryptoLegacyBuildManager (imported but not utilized in this snippet).

• Imports @openzeppelin/contracts/utils/structs/EnumerableSet.sol, although no explicit usage is shown here.

---

40. ISignatureRoleTimelock (Interface)

Purpose

• This interface defines a role-based timelock mechanism for executing scheduled calls.

• It includes events, errors, and data structures that implementers can use to manage roles, set timelocks for function signatures, and schedule or cancel calls.

Inheritance

• None (this is a standalone interface; it does not explicitly inherit from other interfaces).

Key Methods

• No callable functions are declared. Instead, the interface specifies events, custom errors, and data structures to be used by implementing contracts.

All Functions

• None. As an interface, it only provides event and error definitions, plus data structures. There are no public, external, internal, private, constructor, fallback, or receive functions declared.

Events

• SetMaxExecutionPeriod(uint128 indexed maxExecutionPeriod) Emitted when the maximum execution period for scheduled calls is updated.

• AddRoleAccount(bytes32 indexed role, address indexed account) Emitted when an address is granted a specified role.

• RemoveRoleAccount(bytes32 indexed role, address indexed account) Emitted when an address is removed from a specified role.

• AddSignatureRole(address indexed target, bytes4 indexed signature, bytes32 indexed role, uint256 timelock) Emitted when a function signature is bound to a role and assigned a timelock requirement.

• RemoveSignatureRole(address indexed target, bytes4 indexed signature) Emitted when a function signature is unbound from any role and timelock configuration.

• AddTarget(address indexed target) Emitted when a new contract address is authorized as a valid target for scheduled calls.

• RemoveTarget(address indexed target) Emitted when a contract address is removed from the set of valid targets for scheduled calls.

• CallScheduled(bytes32 indexed callId, address indexed caller, address indexed target, bytes4 signature, uint256 executeAfter) Emitted when a call is scheduled for execution after a certain time.

• CallExecuted(bytes32 indexed callId, address indexed msgSender, bytes returnData) Emitted upon successful execution of a scheduled call, along with its return data.

• CallCanceled(bytes32 indexed callId, address indexed msgSender) Emitted when a scheduled call is canceled before execution.

Custom Errors

• AlreadyHaveRole() Thrown if an address already possesses the specified role.

• DoesntHaveRole() Thrown if an address does not have the required role.

• RoleDontExist() Thrown if an operation references a role that is not defined.

• CallerNotCurrentAddress() Thrown if the caller is not the expected (current) address for a particular operation.

• IncorrectSignatureIndex() Thrown when an invalid signature index is encountered.

• IncorrectRoleIndex() Thrown when an invalid role index is encountered.

• CallFailed(bytes errorMessage) Thrown if a scheduled call fails during execution, returning an error message.

• CallNotScheduled() Thrown if an operation references a call that is not scheduled.

• NotPending() Thrown if an operation references a call that is no longer pending.

• TimelockActive() Thrown if a call is attempted before the timelock period expires.

• TimelockExpired() Thrown if a call is attempted after the timelock period has expired.

• CallerHaveNoRequiredRole(bytes32 requiredRole) Thrown if the caller does not have the required role to perform an action.

• CallAlreadyScheduled() Thrown if a duplicate schedule is attempted for the same call.

• SignatureAlreadyExists() Thrown if attempting to add a signature configuration that already exists.

• SignatureTimeLockNotSet(bytes4 signature) Thrown if attempting to execute a signature whose timelock configuration is missing.

• OutOfTimelockBounds(uint256 maxTimelock) Thrown if the requested timelock value is not within acceptable bounds.

• OutOfMaxExecutionPeriodBounds(uint256 minPeriod, uint256 maxPeriod) Thrown if the execution period set is out of the allowable range.

Structs

• CallRequest

  • caller: Address that scheduled the call.

  • target: Target contract to be called.

  • data: Encoded function call data.

  • executeAfter: Earliest timestamp the call can be executed.

  • executeBefore: Latest timestamp the call can be executed.

  • pending: Indicates if the call is still pending or has been executed/canceled.

• AddressRoleInput

  • role: Role identifier.

  • newAccount: Address to be added or assigned to the role.

  • prevAccount: Address previously assigned to the role.

• SignatureAttr

  • role: Role required to execute the signature.

  • timelock: Timelock duration for scheduled calls on this signature.

• SignatureToAdd

  • target: Contract address whose function signature requires a role-based timelock.

  • signature: Function signature to protect.

  • role: Required role for executing that function.

  • timelock: Timelock duration to be applied.

• SignatureToRemove

  • target: Contract address whose function signature configuration will be removed.

  • signature: Function signature to remove from timelock protection.

• CallToAdd

  • target: Contract address for the scheduled call.

  • data: Encoded function call data to be executed.

• TargetSigRes

  • signature: Function signature associated with the target.

  • role: Role required to execute the signature.

  • timelock: Timelock duration assigned to that signature.

Interacts With

• Implementation Contracts

  • Any contract implementing this interface can enforce role-based and timelock-based access control for function calls, but the interface itself does not interact directly with external contracts.

---

41. ITrustedGuardiansPlugin (Interface)

Purpose

• Defines an interface for managing a set of guardians with voting functionality for certain critical actions.

• Allows configuration of threshold and challenge timeout parameters for guardians.

Inheritance

• This is an interface; it does not inherit from other contracts or interfaces directly.

Key Methods

• Guardian Management: Control the addition or removal of guardians.

• Voting: Guardians can vote for certain operations (e.g., distribution).

• Configuration: Allows setting threshold and challenge timeout for guardians.

All Functions

• isGuardiansInitialized() external view returns (bool)

  • Checks if the guardians have been initialized.

Events

• SetGuardian(bytes32 indexed guardian, bool indexed _isAdd)

  • Emitted when a guardian is added or removed.

• GuardiansVoteForDistribution(bytes32 indexed guardian, uint256 votedCount)

  • Emitted when a guardian votes for distribution, carrying the updated vote count.

• GuardiansDistributionStartSet(bytes32 indexed guardian, uint256 distributionStartAt)

  • Emitted when a guardian initiates a distribution start time.

• SetGuardiansConfig(uint8 guardiansThreshold, uint64 guardiansChallengeTimeout)

  • Emitted when the guardians’ configuration (threshold, challenge timeout) is updated.

• ResetGuardiansVoting()

  • Emitted when the guardian voting process is reset.

Errors

• NotGuardian()

  • Thrown if an unauthorized entity attempts to perform guardian-only actions.

• ThresholdDontMet()

  • Thrown if a required threshold is not met for an action.

• GuardianAlreadyVoted()

  • Thrown if a guardian attempts to vote more than once.

• MaxGuardiansTimeout(uint64 guardiansThreshold)

  • Thrown if the specified challenge timeout exceeds maximum allowed constraints.

Structs

• PluginStorage

  • Holds:

    • guardians: Set of guardian identifiers.

    • guardiansVoted: Array of guardians who have voted.

    • guardiansThreshold: Minimum number of guardian votes needed.

    • guardiansChallengeTimeout: Time window for guardian challenges.

• GuardianToChange

  • Holds:

    • hash: Identifier for the guardian.

    • isAdd: Indicates whether the guardian is being added or removed.

Interacts With

• Uses EnumerableSet from OpenZeppelin for guardian set management.

---

42. DiamondLoupeFacet

Purpose

• Implements the “loupe” functions for an EIP-2535 Diamond.

• Provides a way to query facets and function selectors from a diamond.

Inheritance

• IDiamondLoupe: Provides the standard interface for diamond loupe functions.

• IERC165: Enables interface support detection.

Key Methods

• Loupe Functions (e.g., facets(), facetFunctionSelectors(), facetAddresses(), facetAddress()):

  • Frequently called by tools to inspect which facets and selectors are supported.

All Functions

• facets() (external, view) Returns an array of all facets and their selectors.

• facetFunctionSelectors(address _facet) (external, view) Retrieves an array of function selectors supported by a specific facet address.

• facetAddresses() (external, view) Lists all facet addresses used by the diamond.

• facetAddress(bytes4 _functionSelector) (external, view) Provides the facet address that supports a particular function selector. Returns address(0) if not found.

• storageFacetAddress(bytes4 _functionSelector) (external, view) Gives the facet address from the contract’s storage mapping for a particular function selector.

• supportsInterface(bytes4 _interfaceId) (external, view) Implements ERC-165 interface checks. Returns true if the interface ID is supported.

Events

• None defined in this facet.

Interacts With

• LibCryptoLegacyPlugins: Used to find a facet if the address is not stored locally.

• LibDiamond: Accesses and manages the diamond’s storage (e.g., diamondStorage()).

• ICryptoLegacyPlugin: Used to call getSigs() for retrieving function selectors from a facet.

---

43. LibCreate2Deploy (Library)

Purpose

A library that provides functionality to deterministically deploy smart contracts using the CREATE2 opcode. It ensures predictable addresses, emits an event upon successful deployment, and reverts under specific error conditions.

Inheritance

• None

Key Methods

• _deployByCreate2(...): Core function enabling deterministic contract deployment.

All Functions

• _deployByCreate2(address _contractAddress, bytes32 _factorySalt, bytes memory _contractBytecode) internal returns (address)

  • Deploys a contract using CREATE2 if it does not already exist.

  • Emits CryptoLegacyCreation event upon success.

  • Reverts with an error if deployment fails or certain conditions are not met.

• _computeAddress(bytes32 _salt, bytes32 _bytecodeHash) internal view returns (address)

  • Computes the address for a CREATE2-based deployment.

  • Used internally to determine the resulting contract address before actual deployment.

Events

• CryptoLegacyCreation(address addr, bytes32 salt)

  • Emitted after successfully deploying a contract with CREATE2.

  • Provides the deployed contract’s address and the salt used for deployment.

Errors

• BytecodeEmpty()

  • Thrown if the _contractBytecode passed to _deployByCreate2 is empty.

• AlreadyExists()

  • Thrown if a contract already exists at the predicted address.

• AddressMismatch()

  • Thrown if the computed address does not match the expected _contractAddress.

• Create2Failed()

  • Thrown if the CREATE2 deployment fails, resulting in a zero address.

Interacts With

• None (No direct interactions with external contracts, though it relies on the EVM's CREATE2 opcode.)

---

44. LibCryptoLegacy (Library)

Purpose

LibCryptoLegacy is a core library that manages the logic for distributing tokens, verifying beneficiaries, enforcing access controls, and handling fee payments within the CryptoLegacy system. It encapsulates internal checks, storage retrieval, fee logic, and distribution preparation.

Inheritance

• None directly.

• Uses internal references to:

  • ICryptoLegacy for shared data structures, events, and errors.

  • LibDiamond for ownership checks.

  • SafeERC20 for secure ERC20 transfers.

  • EnumerableSet for managing beneficiary sets.

Key Methods

• Fee Management: _takeFee, _checkFee, _sendFeeByTransfer — handle fee logic, distribution checks, and referral splits.

• Beneficiary Checks: _checkAddressIsBeneficiary, _checkDistributionReadyForBeneficiary — confirm if callers/addresses can interact with distributions.

• Distribution Control: _tokenPrepareToDistribute, _getVestedAndClaimedAmount — prepare tokens for distribution and calculate each beneficiary’s vested amounts.

All Functions

Note: All functions listed below are marked internal. They are only callable from other facets/libraries within the system.

1. getCryptoLegacyStorage()

   • Returns the storage struct (CryptoLegacyStorage) from a predefined storage slot.

2. _checkDisabledFunc(ICryptoLegacy.CryptoLegacyStorage storage cls, uint8 _funcFlag)

   • Ensures a specific function is not disabled by checking a bitwise flag.

3. _checkDistributionStart(ICryptoLegacy.CryptoLegacyStorage storage cls)

   • Reverts if distribution has already started.

4. _isDistributionStarted(ICryptoLegacy.CryptoLegacyStorage storage cls) -> bool

   • Returns true if distribution start time is set and has passed.

5. _checkOwner()

   • Reverts unless the caller is the contract owner and initial fee has been paid.

6. _checkSenderOwner()

   • Verifies msg.sender is the owner via LibDiamond.contractOwner().

7. _checkPause(ICryptoLegacy.CryptoLegacyStorage storage cls)

   • Reverts if the contract is currently paused.

8. _setPause(ICryptoLegacy.CryptoLegacyStorage storage cls, bool _isPaused)

   • Toggles or sets the paused state and emits ICryptoLegacy.PauseSet.

9. _getPause(ICryptoLegacy.CryptoLegacyStorage storage cls) -> bool

   • Returns whether the contract is paused.

10. _checkAddressIsBeneficiary(ICryptoLegacy.CryptoLegacyStorage storage cls, address _addr) -> bytes32

    • Reverts if the _addr is not recognized as a beneficiary.

11. _checkDistributionReadyForBeneficiary(ICryptoLegacy.CryptoLegacyStorage storage cls) -> bytes32

    • Checks that the caller is a valid beneficiary and distribution is active.

12. _checkDistributionReady(ICryptoLegacy.CryptoLegacyStorage storage cls)

    • Ensures distribution has officially started (time-based check).

13. _getBeneficiariesCount(ICryptoLegacy.CryptoLegacyStorage storage cls) -> uint256

    • Returns the total count of registered beneficiaries.

14. _isLifetimeActiveAndUpdate(ICryptoLegacy.CryptoLegacyStorage storage cls, address _owner) -> bool

    • Checks (and potentially updates) whether a lifetime NFT is locked for _owner.

15. _takeFee(...)

    • Orchestrates fee payment logic, handling lifetime NFT checks, referral splits, cross-chain fees, and more.

16. _checkFee(uint256 _fee)

    • Validates msg.value against the required fee, allowing minimal overpayment tolerance.

17. _sendFeeByTransfer(...)

    • Directly transfers fee to the builder/manager and optionally to a referrer.

18. _tokenPrepareToDistribute(ICryptoLegacy.CryptoLegacyStorage storage cls, address _token) -> TokenDistribution storage

    • Adjusts amountToDistribute for a token based on the contract’s current balance and prior distribution data.

19. _getStartAndEndDate(...) -> (uint64, uint64)

    • Computes a beneficiary’s vesting start/end timestamps.

20. _getVestedAndClaimedAmount(...) -> (uint256 vestedAmount, uint256 claimedAmount, uint256 totalAmount)

    • Calculates how much of the beneficiary’s allocation is vested and how much is already claimed.

21. _getBeneficiaryVesting(ICryptoLegacy.CryptoLegacyStorage storage cls, bytes32 _beneficiary) -> BeneficiaryVesting storage

    • Retrieves the vesting record for a hashed beneficiary address.

22. _setCryptoLegacyToBeneficiaryRegistry(...)

    • Registers or unregisters individuals (owner, beneficiary, guardian) in an external beneficiary registry, if available.

23. _setCryptoLegacyListToBeneficiaryRegistry(...)

    • Updates lists of addresses (e.g. recovery addresses) in the external beneficiary registry.

24. _updateOwnerInBeneficiaryRegistry(ICryptoLegacy.CryptoLegacyStorage storage cls, address _newOwner)

    • Unregisters the old owner and registers the new owner in the beneficiary registry.

25. _transferTreasuryTokensToLegacy(...)

    • Transfers tokens from specified holders to this legacy contract and updates distribution info.

26. _transferTokensFromLegacy(...)

    • Transfers tokens from this legacy contract to specified recipients and logs distribution.

27. _addressToHash(address _addr) -> bytes32

    • Computes the keccak256 hash of an address.

Events

• Emitted from LibCryptoLegacy via ICryptoLegacy (all event definitions belong to the ICryptoLegacy interface; see ICryptoLegacy (Interface)).

Interacts With

• ICryptoLegacy (via struct references, events, errors)

• LibDiamond (for ownership checks)

• IBeneficiaryRegistry (for beneficiary data registration)

• IERC20 & SafeERC20 (for token transfers)

• EnumerableSet (for beneficiary sets)

---

45. LibCryptoLegacyPlugins (Library)

Purpose

• LibCryptoLegacyPlugins is a library managing plugin registration and function selectors within the CryptoLegacy diamond.

• It validates plugins, adds/removes them to/from the diamond, and finds facets by selector.

Inheritance

• This library does not explicitly inherit from another contract or library; it uses functionality from LibDiamond, ICryptoLegacy, and ICryptoLegacyPlugin.

Key Methods

• Internal logic to register plugins, remove plugins, and manage function selectors within a diamond/facet architecture.

All Functions

1. _validatePlugin(ICryptoLegacy.CryptoLegacyStorage storage _cls, address _plugin) internal view

   • Checks if a plugin is registered via _cls.buildManager.isPluginRegistered(_plugin).

   • Reverts with ICryptoLegacy.PluginNotRegistered if not found.

2. _addPluginList(ICryptoLegacy.CryptoLegacyStorage storage _cls, address[] memory _plugins) internal

   • Iterates over an array of plugin addresses.

   • Validates each plugin.

   • Retrieves setup function selectors using getSetupSigs() from each plugin.

   • Calls addFunctions() to register each selector.

3. _removePlugin(ICryptoLegacyPlugin _plugin) internal

   • Removes all function selectors associated with a plugin by calling removeFunctions(...).

4. _getFacetAddressPosition(LibDiamond.DiamondStorage storage ds, address _facetAddress) private view returns (uint256)

   • Finds the index of _facetAddress in the ds.facetAddresses array.

   • Reverts with ICryptoLegacy.FacetNotFound if not found.

5. _addFacetAddressIfNotExists(LibDiamond.DiamondStorage storage ds, address _facetAddress) private

   • Ensures _facetAddress is added to the diamond storage if it does not already exist.

   • Calls LibDiamond.enforceHasContractCode(...) to confirm _facetAddress contains code.

6. _removeFacetAddress(LibDiamond.DiamondStorage storage ds, address _facetAddress) private

   • Removes _facetAddress from ds.facetAddresses by swapping with the last entry and popping the array.

7. addFunctions(address _facetAddress, bytes4[] memory _functionSelectors) internal

   • Validates _facetAddress is not zero.

   • Calls _addFacetAddressIfNotExists(...).

   • Registers each function selector in diamond storage.

   • Emits ICryptoLegacy.AddFunctions upon success.

8. removeFunctions(address _facetAddress, bytes4[] memory _functionSelectors) internal

   • Validates _facetAddress is not zero and not address(this).

   • Removes _facetAddress from diamond storage if needed.

   • Deletes each function selector mapping.

   • Emits ICryptoLegacy.RemoveFunctions upon success.

9. _findFacetBySelector(LibDiamond.DiamondStorage storage ds, bytes4 _selector) internal view returns (address facetAddress)

   • Searches all facet addresses in ds.facetAddresses.

   • Compares _selector against the array returned by getSigs() in each plugin.

   • Returns the facet address if found, otherwise returns the zero address.

Events

• No new events are declared in this library. However, two events from ICryptoLegacy are emitted:

  • ICryptoLegacy.AddFunctions

  • ICryptoLegacy.RemoveFunctions

Interacts With

• LibDiamond for Diamond Storage structure and code validation.

• ICryptoLegacy for errors and events.

• ICryptoLegacyPlugin to fetch function selectors (getSigs() and getSetupSigs()).

---

46. LibDiamond (Library)

Purpose

The LibDiamond library implements the core logic of the Diamond Standard (EIP-2535). It maintains and manages diamond storage, handles ownership, and facilitates adding, replacing, or removing facets.

Inheritance

• No direct inheritance (this is a library).

Key Methods

• diamondCut: Core logic to add, replace, or remove function selectors in the Diamond.

• setContractOwner: Assigns a new owner to the Diamond.

• contractOwner: Retrieves the current owner.

All Functions

1. diamondStorage() -> (DiamondStorage storage ds) (internal, pure)

   • Returns the library’s dedicated storage struct reference for Diamond-related data.

2. setContractOwner(address _newOwner) (internal)

   • Transfers Diamond ownership from the current owner to _newOwner.

3. contractOwner() -> (address contractOwner_) (internal, view)

   • Retrieves the current contract owner from Diamond storage.

4. enforceIsContractOwner() (internal, view)

   • Throws an exception if msg.sender is not the Diamond’s current owner.

5. diamondCut(IDiamondCut.FacetCut[] memory _diamondCut, address _init, bytes memory _calldata) (internal)

   • Main function to add, replace, or remove facet addresses and their selectors.

   • Emits the DiamondCut event and calls initializeDiamondCut for optional setup.

6. addFunctions(address _facetAddress, bytes4[] memory _functionSelectors) (internal)

   • Appends new function selectors to a specified facet address.

7. replaceFunctions(address _facetAddress, bytes4[] memory _functionSelectors) (internal)

   • Replaces existing function selectors with those from a specified facet address.

8. removeFunctions(address _facetAddress, bytes4[] memory _functionSelectors) (internal)

   • Removes function selectors from the Diamond, optionally cleaning up facet addresses no longer needed.

9. addFacet(DiamondStorage storage ds, address _facetAddress) (internal)

   • Ensures the facet address has contract code, then stores it in Diamond storage.

10. addFunction(DiamondStorage storage ds, bytes4 _selector, uint96 _selectorPosition, address _facetAddress) (internal)

    • Inserts a new selector into the facet’s function selector array.

11. removeFunction(DiamondStorage storage ds, address _facetAddress, bytes4 _selector) (internal)

    • Deletes a selector from a facet’s function list; updates the address array if needed.

12. initializeDiamondCut(address _init, bytes memory _calldata) (internal)

    • Optional initialization logic: calls _init with _calldata via delegatecall if _init is non-zero.

13. enforceHasContractCode(address _contract, string memory _errorMessage) (internal, view)

    • Reverts if _contract has no code (i.e., it’s not a valid deployed contract).

Events

1. OwnershipTransferred(address indexed previousOwner, address indexed newOwner)

   • Emitted whenever ownership is changed via setContractOwner.

2. DiamondCut(IDiamondCut.FacetCut[] _diamondCut, address _init, bytes _calldata)

   • Emitted during every diamondCut operation to signal facet changes.

Errors

• InitializationFunctionReverted(address _initializationContractAddress, bytes _calldata)

  • Thrown if the optional _init delegatecall in diamondCut fails.

Interacts With

• IDiamondCut (imported interface): Uses FacetCut struct and FacetCutAction enum.

• Any contract passed to initializeDiamondCut for delegatecall-based setup.

---

48. LibSafeMinimalMultisig (Library)

Purpose

• This library provides internal logic for creating, confirming, and executing multisig proposals.

• It manages the core storage structure (ISafeMinimalMultisig.Storage) and enforces multisig rules (like who can vote, how many confirmations are needed, and which methods are allowed).

Inheritance

• None (library).

• Depends on:

  • ISafeMinimalMultisig for data structures, errors, and events.

  • LibCryptoLegacy for address hashing utility.

Key Methods

• _propose(...): Creates a new proposal.

• _confirm(...): Confirms an existing proposal.

• _execute(...): Executes a proposal once enough confirmations are reached.

All Functions

Internal/Private Functions

1. _checkIsMultisigExecutor() (internal, view)

   • Ensures that only the contract itself can perform certain actions.

   • Reverts with MultisigOnlyExecutor if msg.sender is not the contract.

2. _checkIsVoterAllowed(bytes32[] memory _allVoters, bytes32 _voter) (internal, pure)

   • Verifies that _voter is in _allVoters.

   • Reverts with MultisigVoterNotAllowed if not found.

3. _setVotersAndConfirmations(ISafeMinimalMultisig.Storage storage s, bytes32[] memory _voters, uint256 _requiredConfirmations) (internal)

   • Updates the list of voters and the required confirmations in storage.

   • Reverts with MultisigIncorrectRequiredConfirmations if _requiredConfirmations is invalid.

4. _initializationStatus(ISafeMinimalMultisig.Storage storage s) internal view returns (ISafeMinimalMultisig.InitializationStatus)

   • Checks if the multisig is initialized by looking at s.requiredConfirmations.

   • Returns INITIALIZED or NOT_INITIALIZED_BUT_NEED.

5. _calcDefaultConfirmations(uint256 _voterCount) internal pure returns (uint256)

   • Calculates a default threshold: (voterCount / 2) + 1.

6. _isMethodAllowed(bytes4[] memory _allowedMethods, bytes4 _selector) internal pure returns (bool)

   • Checks if a given function selector _selector is in _allowedMethods.

   • Returns true if found, false otherwise.

7. _isVoterAllowed(bytes32[] memory _allVoters, bytes32 _voter) internal pure returns (bool)

   • Helper that scans _allVoters to see if _voter is included.

   • Returns true if allowed, false otherwise.

8. _getConfirmedCount(ISafeMinimalMultisig.Storage storage s, bytes32[] memory _allVoters, uint256 _proposalId) internal view returns (uint256)

   • Counts how many voters have confirmed a proposal by checking s.confirmedBy.

9. _getStorageVotersAndConfirmations(ISafeMinimalMultisig.Storage storage s) internal view returns (bytes32[] memory, uint256)

   • Returns the current list of voters and the required number of confirmations from storage.

10. _getProposal(ISafeMinimalMultisig.Storage storage s, uint256 _proposalId) internal view returns (ISafeMinimalMultisig.Proposal memory)

    • Retrieves a single proposal by ID from s.proposals.

11. _getProposalList(ISafeMinimalMultisig.Storage storage s) internal view returns (ISafeMinimalMultisig.Proposal[] memory)

    • Returns the entire array of proposals in storage.

12. _getProposalListWithStatusesAndStorageVoters(ISafeMinimalMultisig.Storage storage s) internal view returns (bytes32[] memory voters, uint256 requiredConfirmations, ISafeMinimalMultisig.ProposalWithStatus[] memory proposalsWithStatuses)

    • Returns all proposals, their per-voter confirmation statuses, plus the current list of voters and confirmations threshold.

13. _getProposalWithStatus(ISafeMinimalMultisig.Storage storage s, bytes32[] memory voters, uint256 _proposalId) internal view returns (ISafeMinimalMultisig.ProposalWithStatus memory)

    • Retrieves a single proposal and compiles a boolean array indicating which voters have confirmed it.

14. _propose(ISafeMinimalMultisig.Storage storage s, bytes32[] memory _allVoters, bytes4[] memory _allowedMethods, bytes4 _selector, bytes memory _params) (internal)

    • Creates a new proposal, checking that _selector is allowed and that msg.sender is an authorized voter.

    • Emits CreateSafeMinimalMultisigProposal.

    • Automatically confirms the proposal by the creator; executes immediately if requiredConfirmations == 1.

15. _confirm(ISafeMinimalMultisig.Storage storage s, bytes32[] memory _allVoters, uint256 _proposalId) (internal)

    • Allows a voter to confirm a proposal.

    • Increments the proposal’s confirmation count.

    • Emits ConfirmSafeMinimalMultisigProposal.

    • Executes the proposal if confirmations meet or exceed the required threshold.

16. _execute(ISafeMinimalMultisig.Storage storage s, bytes32 _voter, uint256 _proposalId) (private)

    • Marks a proposal as executed and performs a low-level call to address(this).

    • Reverts with MultisigExecutionFailed if the call fails.

    • Emits ExecuteSafeMinimalMultisigProposal.

Events

• No new events are declared directly in this library.

• The library emits events declared in ISafeMinimalMultisig:

  • CreateSafeMinimalMultisigProposal

  • ConfirmSafeMinimalMultisigProposal

  • ExecuteSafeMinimalMultisigProposal

Errors

• This library references and reverts with errors declared in ISafeMinimalMultisig (see ISafeMinimalMultisig Errors section).

Interacts With

• ISafeMinimalMultisig: Uses the interface’s storage structure, errors, and events.

• LibCryptoLegacy: Converts addresses to bytes32 identifiers within _propose().

---

49. LibTrustedGuardiansPlugin (Library)

Purpose

Utility for resetting guardian votes and interacting with the plugin storage of trusted guardians.

Functions

• _resetGuardianVoting(...): Clears guardian votes, resets distribution start.

---

50. BeneficiaryPluginAddRights

Purpose

• Extends ICryptoLegacyPlugin to enable beneficiaries to manage additional rights, specifically through a multisig setup that controls plugin functionality.

• Allows new plugins to be added, proposes and confirms actions via a beneficiary-specific multisig mechanism, and integrates with the overall CryptoLegacy distribution logic.

Inheritance

• Implements ICryptoLegacyPlugin.

• Inherits from ReentrancyGuard.

Key Methods

• Multisig Setup: Allows setting and proposing actions that beneficiaries must collectively confirm.

• Plugin Addition: Enables adding more plugins to extend functionality.

All Functions

1. Constructor, Fallback, Receive

   • No explicit constructor, fallback, or receive function.

2. External/Public Functions

   • getSigs(): Returns the function selectors provided by this plugin.

   • getSetupSigs(): Returns setup function selectors (empty for this plugin).

   • getMultisigAllowedMethods(): Returns function selectors allowed to be executed via multisig proposals.

   • getPluginVer(): Returns the plugin version.

   • barSetMultisigConfig(uint256 _requiredConfirmations): Updates multisig confirmation requirements (can be called by owner or internally if distribution is ready).

   • barPropose(bytes4 _selector, bytes memory _params): Submits a new proposal. Uses nonReentrant and onlyDistributionReady.

   • barConfirm(uint256 _proposalId): Confirms an existing proposal. Uses nonReentrant and onlyDistributionReady.

   • barAddPluginList(address[] memory _plugins): Adds a list of plugins to the CryptoLegacy system. Uses onlyDistributionReady and requires multisig execution.

   • barGetInitializationStatus(): Retrieves the multisig initialization status.

   • barGetVotersAndConfirmations(): Returns the list of multisig voters and the required confirmations.

   • barGetProposalWithStatus(uint256 _proposalId): Returns details of a specific proposal, including confirmations.

   • barGetProposalListWithStatuses(): Returns an array of proposals, each with its status.

3. Internal/Private Functions

   • getPluginMultisigStorage(): Internal function retrieving the multisig storage slot.

4. Modifiers

   • onlyOwner(): Restricts access to the contract owner (checked via LibCryptoLegacy._checkOwner()).

   • onlyDistributionReady(): Ensures token distribution is ready (checked via LibCryptoLegacy._checkDistributionReady()).

Events

• No events are declared directly in this contract.

Interacts With

• LibCryptoLegacy: Checks ownership and distribution readiness.

• LibSafeMinimalBeneficiaryMultisig: Proposes, confirms, and manages multisig-based actions.

• LibCryptoLegacyPlugins: Adds new plugin addresses to the system.

• ICryptoLegacy / ICryptoLegacyPlugin: Conforms to the plugin interface for the CryptoLegacy ecosystem.

• ReentrancyGuard: Protects state-changing functions from reentrancy attacks.

---

51. LegacyRecoveryPlugin

Purpose

• Enables secure recovery operations within the CryptoLegacy ecosystem by leveraging a minimal multisig scheme.

• Provides functions for configuring and managing recovery-specific proposals (e.g., transferring treasury tokens, resetting guardian voting).

Inheritance

• ICryptoLegacyPlugin: Implements plugin-specific signatures for the CryptoLegacy ecosystem.

• ReentrancyGuard (from OpenZeppelin): Protects functions from reentrancy attacks.

Key Methods

• lrSetMultisigConfig(...): Configures voters and required confirmations for the plugin’s internal multisig.

• lrPropose(...) and lrConfirm(...): Core multisig proposal lifecycle management (creation and confirmation).

• lrTransferTreasuryTokensToLegacy(...) and lrWithdrawTokensFromLegacy(...): Manage treasury token flows relevant to the legacy contract.

• lrResetGuardianVoting(): Resets guardian voting to a clean state.

All Functions

1. getSigs() external view

   • Returns an array of function selectors provided by this plugin.

2. getSetupSigs() external pure

   • Returns setup function selectors for this plugin; here, it returns an empty array.

3. getMultisigAllowedMethods() public view

   • Lists the function selectors that can be executed via multisig proposals (e.g., token transfers and guardian reset).

4. getPluginName() public pure

   • Returns the plugin’s unique name ("legacy_recover").

5. getPluginVer() external pure

   • Returns the version number (encoded as a uint16).

6. modifier onlyOwner()

   • Restricts access to the contract owner by checking ownership via LibCryptoLegacy._checkOwner(). (Not a function, but a modifier.)

7. getPluginMultisigStorage() internal pure

   • Retrieves the dedicated multisig storage for this plugin from a fixed storage slot.

8. lrSetMultisigConfig(bytes32[] memory _voters, uint256 _requiredConfirmations) external onlyOwner

   • Allows the owner to set or update the multisig configuration (voters and confirmations).

   • Also updates references in the beneficiary registry.

9. lrPropose(bytes4 _selector, bytes memory _params) external

   • Creates a new multisig proposal for approved methods.

   • Checks if the proposer is an allowed voter and if the _selector is permitted.

10. lrConfirm(uint256 _proposalId) external

    • Confirms an existing proposal.

    • Executes the proposal automatically once enough confirmations are collected.

11. lrTransferTreasuryTokensToLegacy(address[] memory _holders, address[] memory _tokens) external nonReentrant

    • Transfers treasury tokens from specified holders to the legacy contract, executed by the multisig.

12. lrWithdrawTokensFromLegacy(ICryptoLegacy.TokenTransferTo[] memory _transfers) external nonReentrant

    • Withdraws tokens from the legacy contract to designated recipients, executed by the multisig.

13. lrResetGuardianVoting() external nonReentrant

    • Resets the guardian-based voting process, preventing distribution if it has already started.

    • Executed by the multisig.

14. lrGetInitializationStatus() external view returns (ISafeMinimalMultisig.InitializationStatus)

    • Returns the multisig’s initialization status.

15. lrGetProposalWithStatus(uint256 _proposalId) external view returns (...)

    • Fetches detailed proposal information along with its confirmation status.

16. lrGetProposalListWithStatuses() external view returns (...)

    • Returns the entire proposal list and statuses stored in the multisig plugin.

Events

• None explicitly declared in this contract.

Interacts With

• LibCryptoLegacy (for ownership checks, token transfers).

• LibSafeMinimalMultisig (for multisig lifecycle and storage).

• LibTrustedGuardiansPlugin (for guardian voting reset).

• ICryptoLegacy (struct definitions and legacy state).

• ISafeMinimalMultisig (for proposal data structures and execution logic).

• IBeneficiaryRegistry (for updating beneficiary registry data).

---

52. CryptoLegacyBasePlugin

Purpose

• CryptoLegacyBasePlugin provides the core functionalities for the CryptoLegacy system, including:

  • Fee management (initial and periodic).

  • Beneficiary configuration (adding, removing, switching).

  • Periodic update logic and challenge initiation.

  • Secure distribution of tokens to beneficiaries upon challenge maturity.

  • Messaging system for beneficiaries.

  • Integration with a “Build Manager” for advanced setup (e.g., cross-chain fees, lifetime NFT checks).

Inheritance

• Inherits:

  • ICryptoLegacy (interface for core CryptoLegacy actions/errors).

  • CryptoLegacyOwnable (custom ownership management).

  • ReentrancyGuard (OpenZeppelin’s contract for preventing re-entrancy).

Key Methods

• initializeByBuildManager(...): One-time initialization by the Build Manager with fees, beneficiaries, intervals, etc.

• payInitialFee(...): Handles the initial required fee payment or checks for lifetime NFT coverage.

• setBeneficiaries(...): Owner-only function to configure beneficiaries and their vesting parameters.

• update(...): Periodic function to pay/update fee and reset certain time counters.

• initiateChallenge(): Allows a beneficiary to initiate a challenge if the owner fails to update on time.

• beneficiaryClaim(...): Core function enabling beneficiaries to claim their vested tokens.

• beneficiarySwitch(...): Enables a beneficiary to switch to a new beneficiary identifier.

• sendMessagesToBeneficiary(...): Owner can send messages (and checks) to beneficiaries.

All Functions

1. getSigs() external view

   • Returns an array of function selectors (bytes4) representing the externally callable methods from this plugin.

   • Visibility: external view

2. getSetupSigs() external view

   • Returns an array of function selectors used during plugin setup.

   • Visibility: external view

3. getPluginName() public pure

   • Returns the unique plugin name, "base".

   • Visibility: public pure

4. getPluginVer() external pure

   • Returns the plugin version as a uint16.

   • Visibility: external pure

5. getCryptoLegacyVer() external pure

   • Returns the underlying CryptoLegacy version.

   • Visibility: external pure

6. constructor()

   • Empty constructor.

   • Visibility: public (default)

7. initializeByBuildManager(...) external

   • Initializes the contract with initial fees, beneficiary hashes/configs, reference code, update/challenge intervals.

   • Only callable by the recognized Build Manager.

   • Visibility: external

8. owner() public view

   • Returns the contract owner (inherited from LibDiamond).

   • Visibility: public view

9. isPaused() external view

   • Checks whether the contract is paused (managed via internal library logic).

   • Visibility: external view

10. buildManager() external view

    • Returns the ICryptoLegacyBuildManager instance associated with this contract.

    • Visibility: external view

11. renounceOwnership() public virtual onlyOwner

    • Renounces ownership by setting the owner to the zero address.

    • Visibility: public

12. transferOwnership(address newOwner) public virtual onlyOwner

    • Transfers ownership to a new, non-zero address and updates beneficiary registry.

    • Visibility: public

13. payInitialFee(uint256[] memory _lockToChainIds, uint256[] memory _crossChainFees) external payable nonReentrant

    • Pays the initial fee if not already paid; can also handle cross-chain fee locking or uses a lifetime NFT check.

    • Unpauses the contract upon successful payment.

    • Visibility: external payable

14. setBeneficiaries(bytes32[] memory _beneficiaryHashes, BeneficiaryConfig[] memory _beneficiaryConfig) external onlyOwner

    • Public method for the owner to configure (add/remove) beneficiaries and their parameters.

    • Visibility: external

15. _setBeneficiaries(...) internal

    • Internal function that performs the actual beneficiary list/config updates.

    • Validates the sum of shareBps equals 10000.

    • Visibility: internal

16. update(uint256[] memory _lockToChainIds, uint256[] memory _crossChainFees) external payable onlyOwner nonReentrant

    • Periodic update to pay the update fee and reset distributionStartAt/time counters.

    • Visibility: external payable

17. initiateChallenge() external

    • Allows a beneficiary to start the challenge process if the owner fails to make timely updates.

    • Sets the distribution start time.

    • Visibility: external

18. transferTreasuryTokensToLegacy(address[] memory _holders, address[] memory _tokens) external nonReentrant

    • Instructs certain holder addresses to transfer tokens into this contract for eventual distribution.

    • Must be called by a valid beneficiary after distribution window is opened.

    • Visibility: external

19. beneficiaryClaim(address[] memory _tokens, address _ref, uint256 _refShare) external payable nonReentrant

    • A beneficiary claims its vested tokens.

    • Performs fee checks and calculations for vesting vs. claimed amounts, then transfers tokens.

    • Visibility: external payable

20. _claimTokenWithVesting(...) internal returns(uint256 amountToClaim)

    • Internal helper: calculates how many tokens are vested and unclaimed, then transfers them.

    • Updates claimed amounts in storage.

    • Visibility: internal

21. beneficiarySwitch(bytes32 _newBeneficiary) external

    • A beneficiary can switch to a new beneficiary identifier if it’s not already registered.

    • Preserves all prior configuration and vesting data.

    • Visibility: external

22. sendMessagesToBeneficiary(...) external onlyOwner

    • Owner can send messages and corresponding “check” messages to listed beneficiaries.

    • Visibility: external

23. isLifetimeActive() public view returns(bool isNftLocked)

    • Checks if the owner’s lifetime NFT is locked (active), via the Build Manager.

    • Visibility: public view

Events

The following events are declared in this contract:

• SetBeneficiary(bytes32 indexed beneficiary, uint64 indexed vestingPeriod, uint64 shareBps, uint64 claimDelay) Emitted when a beneficiary is added or updated.

• SwitchBeneficiary(bytes32 indexed oldBeneficiary, bytes32 indexed newBeneficiary) Emitted when a beneficiary switches to a new identifier.

• ChallengeInitiate(bytes32 indexed beneficiary) Emitted when a beneficiary initiates the challenge period.

• BeneficiaryMessage(bytes32 indexed toBeneficiary, bytes32 messageHash, bytes message, uint256 indexed messageType) Emitted when the owner sends a message to a beneficiary.

• BeneficiaryMessageCheck(bytes32 indexed toBeneficiary, bytes32 messageHash, bytes message, uint256 indexed messageType) Emitted as a verification or check for the above message.

The following events are emitted but defined elsewhere (inherited or in external interfaces/libraries):

• FeePaidByLifetime(...) Emitted when the initial fee is marked paid due to an active lifetime NFT.

• FeePaidByDefault(...) Emitted when the initial fee is successfully paid via the Build Manager call.

• FeePaidByTransfer(...) Emitted when the initial fee is paid by direct transfer (fallback scenario).

• BeneficiaryClaim(address token, uint256 amount, bytes32 beneficiary) Emitted each time a beneficiary claims vested tokens.

• Update(uint256 value, bytes32 data) Emitted during the periodic update() call to log updated fee payments.

Errors

All custom errors used by this contract are defined in ICryptoLegacy or inherited code. These include (but may not be limited to):

• ICryptoLegacy.NotBuildManager()

• ICryptoLegacy.AlreadyInit()

• ICryptoLegacy.ZeroAddress()

• ICryptoLegacy.InitialFeeAlreadyPaid()

• ICryptoLegacy.ShareSumDoesntMatchBase()

• ICryptoLegacy.TooEarly()

• ICryptoLegacy.DistributionStartAlreadySet()

• ICryptoLegacy.AlreadySet()

• ICryptoLegacy.LengthMismatch()

Interacts With

• ICryptoLegacyBuildManager (for fee payment logic, lifetime NFT checks).

• LibDiamond and LibCryptoLegacy (for internal storage management, ownership, pause checks, and distribution logic).

• CryptoLegacyOwnable (modifiers and ownership management).

• Pausable (OpenZeppelin, used indirectly for pause functionality).

• SafeERC20 / IERC20 (OpenZeppelin, for safe token transfers).

• EnumerableSet (OpenZeppelin, for storing beneficiary hashes).

• IBeneficiaryRegistry (for registering or unregistering a beneficiary’s relationship with this contract).

---

53. LensPlugin

Purpose

• LensPlugin provides a comprehensive, read-only view of the internal state of the CryptoLegacy contract.

• It exposes details such as fee parameters, update intervals, beneficiary configurations, and distribution data for easy integration with dashboards and explorers.

Inheritance

• Inherits from ICryptoLegacyPlugin and ICryptoLegacyLens.

  • Both interfaces define functions related to plugin management and lens functionality for CryptoLegacy.

Key Methods

• View/Read-Only Methods such as updateInterval(), challengeTimeout(), and getCryptoLegacyBaseData() provide external callers with the contract’s core configuration and distribution data.

All Functions

Below is a complete list of every function within LensPlugin, including their visibility and a brief description of each.

1. getSigs() → bytes4[] (public, view)

   • Returns an array of function selectors (bytes4) that LensPlugin provides.

2. getSetupSigs() → bytes4[] (external, pure)

   • Returns an empty array of setup function selectors. (This plugin has no setup-specific functions.)

3. getPluginName() → string (external, pure)

   • Returns the name of the plugin ("lens").

4. getPluginVer() → uint16 (external, pure)

   • Returns the version number of the plugin (1).

5. updateInterval() → uint64 (external, view)

   • Retrieves how frequently the CryptoLegacy contract expects an update call.

6. challengeTimeout() → uint64 (external, view)

   • Retrieves the timeout duration for beneficiary challenges.

7. distributionStartAt() → uint64 (external, view)

   • Returns the timestamp when distribution of assets is scheduled to start.

8. lastFeePaidAt() → uint64 (external, view)

   • Returns the timestamp of the last fee payment.

9. lastUpdateAt() → uint64 (external, view)

   • Returns the timestamp of the last update call to the core CryptoLegacy contract.

10. initialFeeToPay() → uint128 (external, view)

    • Retrieves the initial fee that must be paid by a user.

11. updateFee() → uint128 (external, view)

    • Retrieves the periodic update fee.

12. invitedByRefCode() → bytes8 (external, view)

    • Returns the reference code, if any, that invited the current user/contract owner.

13. getBeneficiaryVesting(bytes32 _beneficiary, address _token) → uint256 (external, view)

    • Returns the total amount of tokens already claimed by a given beneficiary for a specified token.

14. getOriginalBeneficiaryHash(bytes32 _beneficiary) → bytes32 (external, view)

    • Retrieves the original beneficiary hash mapped to the given beneficiary identifier.

15. getBeneficiaryConfig(bytes32 _beneficiary) → ICryptoLegacy.BeneficiaryConfig (external, view)

    • Retrieves the configuration (claimDelay, vestingPeriod, shareBps) for a given beneficiary.

16. getBeneficiaries() → (bytes32[] hashes, bytes32[] originalHashes, ICryptoLegacy.BeneficiaryConfig[] configs) (external, view)

    • Returns arrays of beneficiary identifiers, their original hashes, and the associated configuration structs.

17. _getBeneficiaries(ICryptoLegacy.CryptoLegacyStorage storage cls) → (bytes32[] hashes, bytes32[] originalHashes, ICryptoLegacy.BeneficiaryConfig[] configs) (internal, view)

    • Internal helper function used by getBeneficiaries() to assemble and return beneficiary data.

18. getTransferBlockNumbers() → uint64[] (external, view)

    • Returns an array of block numbers at which asset transfers occurred.

19. getTokensDistribution(address[] memory _tokens) → ICryptoLegacy.TokenDistribution[] (external, view)

    • Fetches distribution details (amount to distribute, total claimed, etc.) for an array of tokens.

20. _getTokensDistribution(address[] memory _tokens) → ICryptoLegacy.TokenDistribution[] (internal, view)

    • Internal helper function used by getTokensDistribution() to retrieve token distribution data.

21. getCryptoLegacyBaseData() → (CryptoLegacyBaseData memory) (external, view)

    • Retrieves a struct containing core contract data (fees, intervals, reference codes, etc.).

22. getCryptoLegacyListData(address[] memory _tokens) → (CryptoLegacyListData memory) (external, view)

    • Retrieves a struct containing arrays of beneficiaries, plugin info, and token distribution details.

23. getMessagesBlockNumbersByRecipient(bytes32 _recipient) → uint64[] (external, view)

    • Returns block numbers when messages were received for the specified beneficiary.

24. getVestedAndClaimedData(bytes32 _beneficiary, address[] memory _tokens) → (BeneficiaryTokenData[] memory result, uint64 startDate, uint64 endDate) (external, view)

    • Calculates and returns the vested, claimed, and total distributable token amounts for a beneficiary, including vesting start and end dates.

25. getPluginInfoList() → PluginInfo[] (external, view)

    • Returns a list of plugin information (address, name, version) currently attached to the CryptoLegacy contract.

26. getPluginMetadata(address _plugin) → (string memory name, uint16 version, uint64[] memory descriptionBlockNumbers) (external, view)

    • Retrieves plugin metadata (name, version, block numbers for descriptions) for a specific plugin.

27. _getPluginInfoList(ICryptoLegacy.CryptoLegacyStorage storage cls) → PluginInfo[] (internal, view)

    • Internal helper for assembling the array of all plugins attached to the CryptoLegacy contract.

28. _getPluginMetadata(ICryptoLegacy.CryptoLegacyStorage storage cls, address _plugin) → (string memory name, uint16 version, uint64[] memory descriptionBlockNumbers) (internal, view)

    • Internal helper for retrieving plugin metadata.

Events

• No events are declared or emitted in LensPlugin.

Interacts With

• ICryptoLegacy for accessing and interpreting the main CryptoLegacy storage and structs.

• ICryptoLegacyLens (direct inheritance) for lens-specific functionality.

• ICryptoLegacyPlugin (direct inheritance) for plugin identification and versioning.

• LibCryptoLegacy for internal storage retrieval (getCryptoLegacyStorage()) and calculations (vesting, distribution).

• LibDiamond for retrieving and iterating plugin/facet addresses (ds.facetAddresses).

• EnumerableSet (OpenZeppelin library) for managing sets of bytes32 (used with beneficiary hashes).

---

54. NftLegacyPlugin

Purpose

• Extends CryptoLegacy to Support NFTs:

  • Allows setting an NFT beneficiary.

  • Facilitates transferring NFT assets into the legacy contract.

  • Enables beneficiaries to claim NFTs after a specified delay.

Inheritance

• ICryptoLegacyPlugin: For plugin interface compliance.

• ReentrancyGuard: For preventing reentrancy on critical functions.

Key Methods

• NFT Beneficiary Management: setNftBeneficiary

• NFT Transfers to Legacy: transferNftTokensToLegacy

• NFT Claiming: beneficiaryClaimNft

All Functions

1. Constructor / Fallback / Receive

   • No explicit constructor

   • No fallback or receive function

2. getSigs() external view returns (bytes4[] memory)

   • Returns an array of function selectors for this plugin.

3. getSetupSigs() external pure returns (bytes4[] memory)

   • Returns an empty array, indicating no setup functions are required.

4. getPluginName() external pure returns (string memory)

   • Returns the unique plugin name, "nft_legacy".

5. getPluginVer() external pure returns (uint16)

   • Returns the plugin version as a uint16 (here, 1).

6. getPluginStorage() internal pure returns (PluginStorage storage)

   • Internal function providing access to the plugin’s specific NFT beneficiary mapping storage.

7. onlyOwner() (modifier)

   • Restricts access to contract owner by calling LibCryptoLegacy._checkOwner().

8. setNftBeneficiary(bytes32 _beneficiary, address _nftContract, uint256[] memory _tokenIds, uint32 _delay) public onlyOwner

   • Allows the owner to set or update an NFT beneficiary and claim delay for multiple token IDs.

9. transferNftTokensToLegacy(address _nftContract, uint256[] memory _tokenIds) public nonReentrant

   • Transfers the specified NFTs from their current owners to the contract, validating distribution readiness and beneficiary settings.

10. beneficiaryClaimNft(address _nftContract, uint256[] memory _tokenIds) public nonReentrant

    • Enables the designated beneficiary to claim NFTs after the claim delay has passed.

Events

• SetNftBeneficiary(address indexed nftContract, uint256 indexed tokenId, bytes32 indexed beneficiaryHash) Emitted when an NFT beneficiary is set or updated.

• BeneficiaryClaimNft(address indexed nftContract, uint256 indexed tokenId, bytes32 indexed beneficiaryHash, address beneficiaryAddress) Emitted when a beneficiary successfully claims an NFT.

• TransferNftToCryptoLegacy(address indexed nftContract, uint256 indexed tokenId) Emitted when an NFT is transferred into the CryptoLegacy contract.

Interacts With

• ICryptoLegacy and LibCryptoLegacy for distribution checks and owner validation.

• IERC721 to transfer NFTs.

• ReentrancyGuard to protect functions from reentry attacks.

---

55. TrustedGuardiansPlugin

Purpose

• A plugin for the CryptoLegacy system that manages guardian-based approvals for distribution, token transfers, and guardian configuration.

• Implements ICryptoLegacyPlugin and ITrustedGuardiansPlugin.

• Provides multi-guardian voting logic.

Inheritance

• Implements:

  • ICryptoLegacyPlugin

  • ITrustedGuardiansPlugin

• Inherits:

  • ReentrancyGuard (OpenZeppelin)

Key Methods

• Guardian management and voting:

  • initializeGuardians(...) sets initial guardians and configuration.

  • guardiansVoteForDistribution() triggers votes and can schedule distribution.

  • guardiansTransferTreasuryTokensToLegacy(...) facilitates token movement upon successful guardian voting.

All Functions

External / Public Functions

1. getSigs() (external, view)

   • Returns an array of function selectors provided by this plugin.

2. getSetupSigs() (external, view)

   • Returns an array of setup function selectors for this plugin.

3. getPluginName() (external, pure)

   • Returns the unique plugin name, "trusted_guardians".

4. getPluginVer() (external, pure)

   • Returns the plugin version as a uint16.

5. initializeGuardians(GuardianToChange[] memory _guardians, uint8 _guardiansThreshold, uint64 _guardiansChallengeTimeout) (external, nonReentrant)

   • Owner-only. Sets initial guardian list, vote threshold, and challenge timeout.

6. setGuardians(GuardianToChange[] memory _guardians) (external, nonReentrant)

   • Owner-only. Adds or removes guardians based on the provided array.

7. setGuardiansConfig(uint8 _guardiansThreshold, uint64 _guardiansChallengeTimeout) (external, nonReentrant)

   • Owner-only. Resets guardian votes and updates threshold and challenge timeout (max 30 days).

8. guardiansVoteForDistribution() (external, nonReentrant)

   • A guardian-only function to cast a vote for distribution.

   • Sets or updates distributionStartAt if the vote threshold is reached.

9. guardiansTransferTreasuryTokensToLegacy(address[] memory _holders, address[] memory _tokens) (external, nonReentrant)

   • A guardian-only function to move tokens from specified holders to the legacy contract, only if distribution is ready.

10. resetGuardianVoting() (external, nonReentrant)

• Owner-only. Clears all guardian votes and resets distribution timing.

1. isGuardiansInitialized() (external, view)

• Returns true if the guardian set in plugin storage is non-empty.

1. getGuardiansData() (external, view)

• Retrieves all guardians, voted guardians, vote threshold, and challenge timeout.

Internal / Private Functions

1. _isGuardianVoted(...) (internal)

   • Checks if a given guardian has already voted; removes invalid entries from the vote list.

2. _checkGuardian() (internal, view)

   • Ensures the caller is a valid guardian. Reverts if not.

3. _checkGuardianNotVoted() (internal)

   • Combines _checkGuardian() with a vote check. Reverts if guardian has already voted.

4. _getGuardians(...) (internal, view)

   • Retrieves the current guardian set from either plugin storage or the core beneficiaries.

5. _getGuardiansThreshold(...) (internal, view)

   • Fetches the required vote threshold. Defaults to a value computed by LibSafeMinimalMultisig if not set.

6. _getGuardiansChallengeTimeout(...) (internal, view)

   • Returns the challenge timeout. Defaults to 30 days if not explicitly configured.

7. _setGuardians(...) (internal)

   • Internal logic to add or remove guardians and update the beneficiary registry.

8. _setGuardiansConfig(...) (internal)

   • Validates and updates threshold and timeout settings; clears any active votes.

9. _isGuardiansInitialized(...) (internal, view)

   • Checks if the plugin storage contains any guardians.

Modifier

• onlyOwner()

  • Restricts access to the contract owner (calls LibCryptoLegacy._checkOwner()).

No Constructor, Fallback, or Receive

• The contract does not define a custom constructor, fallback, or receive function.

Events

• SetGuardian(bytes32 indexed hash, bool isAdd) Emitted when a guardian is added or removed.

• SetGuardiansConfig(uint8 guardiansThreshold, uint64 guardiansChallengeTimeout) Emitted when the threshold or challenge timeout is changed.

• GuardiansVoteForDistribution(bytes32 indexed hash, uint256 currentVoteCount) Emitted when a guardian votes for distribution.

• GuardiansDistributionStartSet(bytes32 indexed hash, uint64 newDistributionStartAt) Emitted when the distribution start time is updated due to reaching the vote threshold.

Errors

• NotGuardian() Reverts if the caller is not a recognized guardian.

• GuardianAlreadyVoted() Reverts if a guardian attempts to vote more than once.

• MaxGuardiansTimeout(uint64 maxTimeout) Reverts if _guardiansChallengeTimeout exceeds 30 days.

Interacts With

• ICryptoLegacy and LibCryptoLegacy for core CryptoLegacy storage and ownership checks.

• ITrustedGuardiansPlugin for plugin-specific storage structures.

• LibTrustedGuardiansPlugin for resetting votes and internal plugin storage operations.

• LibSafeMinimalMultisig for default vote threshold calculations.

• ReentrancyGuard from OpenZeppelin to prevent reentrant calls.

• External token contracts when transferring treasury tokens (via LibCryptoLegacy._transferTreasuryTokensToLegacy).

---

56. UpdateRolePlugin

Purpose

• UpdateRolePlugin provides decentralized update management, allowing designated "updater" addresses (beyond the contract owner) to trigger updates in the CryptoLegacy system. This ensures continuous and distributed operational control.

Inheritance

• Implements ICryptoLegacyPlugin

• Inherits ReentrancyGuard

Key Methods

• Role Management: Adds and removes authorized updater addresses.

• Update Execution: Allows approved updaters to execute contract updates, including fee handling.

All Functions

1. Constructor / Fallback / Receive

   • (No explicit constructor, fallback, or receive function is defined in the snippet.)

2. getSigs() external view returns (bytes4[] memory)

   • Returns an array of function selectors for the externally callable plugin functions.

3. getSetupSigs() external view returns (bytes4[] memory)

   • Returns an array of setup function selectors for configuring the plugin.

4. getPluginName() public pure returns (string memory)

   • Returns a unique string identifier for this plugin: "update_role".

5. getPluginVer() external pure returns (uint16)

   • Returns the plugin version (hardcoded as 1).

6. getPluginStorage() internal pure returns (PluginStorage storage storageStruct) (Internal)

   • Retrieves the internal storage struct used to maintain updater addresses.

7. owner() public view returns (address)

   • Returns the contract owner address, retrieved via LibDiamond.contractOwner().

8. Modifiers

   • onlyOwner(): Restricts function access to the contract owner.

   • onlyUpdater(): Ensures the caller is a valid updater and that distributions are started before allowing certain actions.

9. getUpdaterList() public view returns(address[] memory)

   • Returns an array of all addresses currently authorized as updaters.

10. isUpdater(address _acc) public view returns(bool)

    • Checks if _acc is in the set of authorized updaters.

11. setUpdater(address _updater, bool _toAdd) external payable onlyOwner nonReentrant

    • Adds or removes an address from the updater set.

    • Emits AddUpdater or RemoveUpdater from ICryptoLegacyUpdaterPlugin.

12. updateByUpdater(uint256[] memory _lockToChainIds, uint256[] memory _crossChainFees) external payable onlyUpdater nonReentrant

    • Allows an authorized updater to trigger a contract update, handle fee distribution, and reset certain system timestamps.

    • Emits an Update event from ICryptoLegacy indicating the plugin update details.

Events

• AddUpdater(address indexed caller, address indexed newUpdater): Emitted when an updater is added.

• RemoveUpdater(address indexed caller, address indexed removedUpdater): Emitted when an updater is removed.

• Update(uint256 msgValue, bytes32 pluginNameHash): Emitted (via ICryptoLegacy) when an updater triggers a contract update.

Interacts With

• ICryptoLegacyUpdaterPlugin: Uses events and errors for updater management.

• ICryptoLegacy: Emits the Update event to signal an update in the system.

• LibCryptoLegacy: For ownership checks, distribution checks, and fee handling.

• LibDiamond: For retrieving the contract owner.

• ReentrancyGuard: Ensures update functions are not susceptible to reentrancy attacks.

• EnumerableSet (from OpenZeppelin): Manages the set of updater addresses internally.