@lukso/lsp8-contracts 0.16.5 → 0.17.3

package/contracts/extensions/LSP8Revokable/LSP8RevokableInitAbstract.sol

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.27;
+
+// modules
+import {
+    OwnableUpgradeable
+} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
+import {
+    LSP8IdentifiableDigitalAssetInitAbstract
+} from "../../LSP8IdentifiableDigitalAssetInitAbstract.sol";
+import {
+    AccessControlExtendedInitAbstract
+} from "../AccessControlExtended/AccessControlExtendedInitAbstract.sol";
+
+// interfaces
+import {ILSP8Revokable} from "./ILSP8Revokable.sol";
+
+// errors
+import {
+    AccessControlUnauthorizedAccount
+} from "../AccessControlExtended/AccessControlExtendedErrors.sol";
+import {LSP8RevokableFeatureDisabled} from "./LSP8RevokableErrors.sol";
+
+/// @title LSP8RevokableInitAbstract
+/// @dev Abstract contract implementing revokable functionality for LSP8 tokens (initializer version).
+/// Allows addresses with the `REVOKER_ROLE` to revoke NFTs from any holder
+/// back to the contract owner or any other address that also has revoke rights.
+///
+/// This version is for proxy deployments using the initializer pattern.
+///
+/// Use cases include:
+/// - Memberships: Revoke membership NFTs when they expire or are terminated
+/// - Role badges: Remove role badge NFTs from community members
+/// - Compliance: Freeze or reverse NFTs for regulatory requirements
+/// - Ticketing: Reclaim tickets or access NFTs when conditions are no longer met
+abstract contract LSP8RevokableInitAbstract is
+    ILSP8Revokable,
+    LSP8IdentifiableDigitalAssetInitAbstract,
+    AccessControlExtendedInitAbstract
+{
+    bool internal _isRevokable;
+
+    /// @dev keccak256("REVOKER_ROLE")
+    bytes32 public constant REVOKER_ROLE =
+        0xce3f34913921da558f105cefb578d87278debbbd073a8d552b5de0d168deee30;
+
+    /// @notice Initializes the LSP8Revokable contract with base token params.
+    /// @dev Initializes the LSP8IdentifiableDigitalAsset base contract.
+    /// @param name_ The name of the token.
+    /// @param symbol_ The symbol of the token.
+    /// @param newOwner_ The owner of the contract (implicitly a revoker).
+    /// @param lsp4TokenType_ The token type (see LSP4).
+    /// @param lsp8TokenIdFormat_ The format of tokenIds (= NFTs) that this contract will create.
+    /// @param isRevokable_ Whether token revocation is enabled.
+    function __LSP8Revokable_init(
+        string memory name_,
+        string memory symbol_,
+        address newOwner_,
+        uint256 lsp4TokenType_,
+        uint256 lsp8TokenIdFormat_,
+        bool isRevokable_
+    ) internal virtual onlyInitializing {
+        LSP8IdentifiableDigitalAssetInitAbstract._initialize(
+            name_,
+            symbol_,
+            newOwner_,
+            lsp4TokenType_,
+            lsp8TokenIdFormat_
+        );
+        __AccessControlExtended_init();
+        __LSP8Revokable_init_unchained(isRevokable_);
+    }
+
+    /// @notice Unchained initializer for LSP8Revokable.
+    function __LSP8Revokable_init_unchained(
+        bool isRevokable_
+    ) internal virtual onlyInitializing {
+        _isRevokable = isRevokable_;
+
+        if (isRevokable_) {
+            _grantRole(REVOKER_ROLE, owner());
+        }
+    }
+
+    /// @inheritdoc ILSP8Revokable
+    function isRevokable() public view virtual override returns (bool) {
+        return _isRevokable;
+    }
+
+    /// @inheritdoc ILSP8Revokable
+    /// @custom:warning Once this function is called, any address holding the `REVOKER_ROLE` will be inoperable.
+    /// @custom:info The list of addresses holding the `REVOKER_ROLE` remains populated after the revokable feature is switched off.
+    function disableRevokable() public virtual override onlyOwner {
+        require(isRevokable(), LSP8RevokableFeatureDisabled());
+        _isRevokable = false;
+        emit RevokableStatusChanged({enabled: false});
+    }
+
+    /// @inheritdoc ILSP8Revokable
+    function revoke(
+        address from,
+        address to,
+        bytes32 tokenId,
+        bytes memory data
+    ) public virtual override onlyRole(REVOKER_ROLE) {
+        require(isRevokable(), LSP8RevokableFeatureDisabled());
+        require(
+            to == owner() || hasRole(REVOKER_ROLE, to),
+            AccessControlUnauthorizedAccount(to, REVOKER_ROLE)
+        );
+
+        // We assume revokers are trusted when specifying revocation destinations.
+        // Therefore, we bypass LSP1 receiver checks.
+        _transfer(from, to, tokenId, true, data);
+    }
+
+    function supportsInterface(
+        bytes4 interfaceId
+    )
+        public
+        view
+        virtual
+        override(
+            AccessControlExtendedInitAbstract,
+            LSP8IdentifiableDigitalAssetInitAbstract
+        )
+        returns (bool)
+    {
+        return
+            AccessControlExtendedInitAbstract.supportsInterface(interfaceId) ||
+            LSP8IdentifiableDigitalAssetInitAbstract.supportsInterface(
+                interfaceId
+            );
+    }
+
+    /// @dev Overridden function to ensure previous revokers do not persist after contract ownership has been transferred.
+    /// The only exception is if the old contract owner had the `REVOKER_ROLE`. This role will be given to the new owner.
+    ///
+    /// @custom:warning This function clears the entire `REVOKER_ROLE` member set.
+    /// - Gas cost scales linearly with the number of addresses with the `REVOKER_ROLE`.
+    /// - If the number of addresses with the `REVOKER_ROLE` is large, it might consume a lot of gas,
+    /// leading the transaction to approach or exceed the block gas limit and fail.
+    /// Consider revoking addresses with the `REVOKER_ROLE` in batches in separate transactions to mitigate this.
+    function _transferOwnership(
+        address newOwner
+    )
+        internal
+        virtual
+        override(AccessControlExtendedInitAbstract, OwnableUpgradeable)
+    {
+        // restore default admin hierarchy so a previously-installed custom admin
+        // cannot grant REVOKER_ROLE to new accounts post-transfer
+        _setRoleAdmin(REVOKER_ROLE, DEFAULT_ADMIN_ROLE);
+
+        // Transfer all roles from old owner to new owner first (including the `REVOKER_ROLE`)
+        // before clearing the list of revokers.
+        super._transferOwnership(newOwner);
+
+        address[] memory revokers = getRoleMembers(REVOKER_ROLE);
+
+        // Exclude the new owner from the list of revokers to delete.
+        for (uint256 ii = 0; ii < revokers.length; ++ii) {
+            address revoker = revokers[ii];
+            if (revoker == newOwner) continue;
+            _revokeRole(REVOKER_ROLE, revoker);
+        }
+    }
+
+    /**
+     * @dev This empty reserved space is put in place to allow future versions to add new
+     * variables without shifting down storage in the inheritance chain.
+     * See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps
+     *
+     * @custom:info The size of the `__gap` array is calculated so that the amount of storage used by the contract
+     * always adds up to the same number (in this case 50 storage slots).
+     */
+    uint256[49] private __gap;
+}

package/contracts/extensions/{LSP8Votes.sol → LSP8Votes/LSP8Votes.sol}

@@ -1,10 +1,9 @@
-// SPDX-License-Identifier: MIT
-
-pragma solidity ^0.8.0;
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.27;
 
 import {
     LSP8IdentifiableDigitalAsset
-} from "../LSP8IdentifiableDigitalAsset.sol";
+} from "../../LSP8IdentifiableDigitalAsset.sol";
 import {Votes} from "@openzeppelin/contracts/governance/utils/Votes.sol";
 import {
     _TYPEID_LSP8_VOTESDELEGATOR,

package/contracts/extensions/{LSP8VotesConstants.sol → LSP8Votes/LSP8VotesConstants.sol}

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0
-pragma solidity ^0.8.4;
+pragma solidity ^0.8.27;
 
 // keccak256('LSP8Tokens_VotesDelegatorNotification')
 bytes32 constant _TYPEID_LSP8_VOTESDELEGATOR = 0x2f6d3f668c2e57dbae4c255f2d9e0b69d47a8848d69a2251cce137529e34743e;

package/contracts/extensions/{LSP8VotesInitAbstract.sol → LSP8Votes/LSP8VotesInitAbstract.sol}

@@ -1,9 +1,9 @@
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.0;
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.27;
 
 import {
     LSP8IdentifiableDigitalAssetInitAbstract
-} from "../LSP8IdentifiableDigitalAssetInitAbstract.sol";
+} from "../../LSP8IdentifiableDigitalAssetInitAbstract.sol";
 import {
     VotesUpgradeable
 } from "@openzeppelin/contracts-upgradeable/governance/utils/VotesUpgradeable.sol";

package/contracts/presets/LSP8CustomizableToken.sol

@@ -0,0 +1,277 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.27;
+
+// modules
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+import {
+    AccessControlExtendedAbstract
+} from "../extensions/AccessControlExtended/AccessControlExtendedAbstract.sol";
+import {
+    LSP8IdentifiableDigitalAsset
+} from "../LSP8IdentifiableDigitalAsset.sol";
+
+// extensions
+import {LSP8Burnable} from "../extensions/LSP8Burnable/LSP8Burnable.sol";
+import {
+    LSP8MintableAbstract
+} from "../extensions/LSP8Mintable/LSP8MintableAbstract.sol";
+import {
+    LSP8CappedSupplyAbstract
+} from "../extensions/LSP8CappedSupply/LSP8CappedSupplyAbstract.sol";
+import {
+    LSP8CappedBalanceAbstract
+} from "../extensions/LSP8CappedBalance/LSP8CappedBalanceAbstract.sol";
+import {
+    LSP8NonTransferableAbstract
+} from "../extensions/LSP8NonTransferable/LSP8NonTransferableAbstract.sol";
+import {
+    LSP8RevokableAbstract
+} from "../extensions/LSP8Revokable/LSP8RevokableAbstract.sol";
+
+// constants
+import {
+    LSP8MintableParams,
+    LSP8NonTransferableParams,
+    LSP8CappedParams,
+    LSP8RevokableParams
+} from "./LSP8CustomizableTokenConstants.sol";
+
+// errors
+import {
+    LSP8MintDisabled
+} from "../extensions/LSP8Mintable/LSP8MintableErrors.sol";
+import {
+    LSP8CappedSupplyCannotMintOverCap
+} from "../extensions/LSP8CappedSupply/LSP8CappedSupplyErrors.sol";
+
+/// @title LSP8CustomizableToken
+/// @dev A customizable LSP8 token that implements multiple features and uses role-based exemptions.
+/// Implements {LSP8Burnable} to allow burning.
+/// Implements {LSP8Mintable} to allow minting.
+/// Implements {LSP8CappedSupply} to set total supply cap.
+/// Implements {LSP8CappedBalance} to set balance caps.
+/// Implements {LSP8NonTransferable} to restrict transfers.
+/// Implements {LSP8Revokable} to allow revoking tokens.
+contract LSP8CustomizableToken is
+    LSP8Burnable,
+    LSP8MintableAbstract,
+    LSP8CappedSupplyAbstract,
+    LSP8CappedBalanceAbstract,
+    LSP8NonTransferableAbstract,
+    LSP8RevokableAbstract
+{
+    /// @notice Initializes the token with name, symbol, owner, and customizable features.
+    /// @dev Sets up minting, balance cap, transfer restrictions and supply cap. Mints initial tokens if specified. Reverts if initialMintTokenIds length exceeds tokenSupplyCap. Inherits constructor logic from parent contracts.
+    /// @param name_ The name of the token.
+    /// @param symbol_ The symbol of the token.
+    /// @param newOwner_ The initial owner of the token.
+    /// @param lsp4TokenType_ The LSP4 token type (e.g., 1 for NFT, 2 for Collection).
+    /// @param lsp8TokenIdFormat_ The format of tokenIds (= NFTs) that this contract will create.
+    /// @param mintableParams Deployment configuration for minting feature (see above).
+    /// @param cappedParams Deployment configuration for capped balance and capped supply features (see above).
+    /// @param nonTransferableParams Deployment configuration for non-transferable feature (see above).
+    /// @param revokableParams Deployment configuration for revokable feature (see above).
+    constructor(
+        string memory name_,
+        string memory symbol_,
+        address newOwner_,
+        uint256 lsp4TokenType_,
+        uint256 lsp8TokenIdFormat_,
+        LSP8MintableParams memory mintableParams,
+        LSP8CappedParams memory cappedParams,
+        LSP8NonTransferableParams memory nonTransferableParams,
+        LSP8RevokableParams memory revokableParams
+    )
+        LSP8IdentifiableDigitalAsset(
+            name_,
+            symbol_,
+            newOwner_,
+            lsp4TokenType_,
+            lsp8TokenIdFormat_
+        )
+        AccessControlExtendedAbstract()
+        LSP8MintableAbstract(mintableParams.isMintable)
+        LSP8CappedSupplyAbstract(cappedParams.tokenSupplyCap)
+        LSP8CappedBalanceAbstract(cappedParams.tokenBalanceCap)
+        LSP8NonTransferableAbstract(
+            nonTransferableParams.transferLockStart,
+            nonTransferableParams.transferLockEnd
+        )
+        LSP8RevokableAbstract(revokableParams.isRevokable)
+    {
+        _initialMint({
+            to: newOwner_,
+            initialMintTokenIds: mintableParams.initialMintTokenIds
+        });
+    }
+
+    /// @inheritdoc LSP8CappedSupplyAbstract
+    /// @notice Returns the token supply cap.
+    /// @dev If minting is enabled, returns the configured supply cap defining the maximum number of NFTs that can be minted.
+    /// If minting is disabled, returns the current total supply as the effective cap (no more NFTs can be created).
+    function tokenSupplyCap() public view virtual override returns (uint256) {
+        return isMintable ? super.tokenSupplyCap() : totalSupply();
+    }
+
+    /// @dev Required override to resolve multiple inheritance. Calls every parent {supportsInterface} functions
+    /// via `super` to aggregate the interface IDs supported across all inherited modules.
+    function supportsInterface(
+        bytes4 interfaceId
+    )
+        public
+        view
+        virtual
+        override(
+            LSP8IdentifiableDigitalAsset,
+            LSP8CappedBalanceAbstract,
+            LSP8MintableAbstract,
+            LSP8NonTransferableAbstract,
+            LSP8RevokableAbstract
+        )
+        returns (bool)
+    {
+        return super.supportsInterface(interfaceId);
+    }
+
+    /// @dev Override to bypass the non transferable check when revokers revoke users' tokens.
+    function _nonTransferableCheck(
+        address from,
+        address to,
+        bytes32 tokenId,
+        bool force,
+        bytes memory data
+    ) internal virtual override {
+        if (_isRevocationBypass(to)) return;
+        super._nonTransferableCheck(from, to, tokenId, force, data);
+    }
+
+    /// @dev Override to bypass the token balance cap check when revokers revoke users' tokens.
+    function _tokenBalanceCapCheck(
+        address from,
+        address to,
+        bytes32 tokenId,
+        bool force,
+        bytes memory data
+    ) internal virtual override {
+        if (_isRevocationBypass(to)) return;
+        super._tokenBalanceCapCheck(from, to, tokenId, force, data);
+    }
+
+    /// @inheritdoc LSP8MintableAbstract
+    /// @dev Overridden function to allow minting only if:
+    /// - the minting feature is enabled, from {LSP8MintableAbstract}
+    /// - the total number of NFTs does not exceed the capped supply after minting, from {LSP8CappedSupplyAbstract}
+    function _mint(
+        address to,
+        bytes32 tokenId,
+        bool force,
+        bytes memory data
+    )
+        internal
+        virtual
+        override(
+            LSP8IdentifiableDigitalAsset,
+            LSP8MintableAbstract,
+            LSP8CappedSupplyAbstract
+        )
+    {
+        require(isMintable, LSP8MintDisabled());
+        LSP8CappedSupplyAbstract._mint(to, tokenId, force, data);
+    }
+
+    /// @notice Hook called before a token transfer to enforce restrictions.
+    /// @dev Combines checks from {LSP8CappedBalance} and {LSP8NonTransferable}.
+    /// - Bypasses {LSP8NonTransferable} checks for senders (`from`) holding the `NON_TRANSFERABLE_BYPASS_ROLE` role.
+    /// - Bypasses {LSP8CappedBalance} checks for recipients (`to`) holding the `UNCAPPED_BALANCE_ROLE` role.
+    /// - Allows minting (from address(0)) and burning to address(0) regardless of restrictions.
+    /// @param from The address sending the token.
+    /// @param to The address receiving the token.
+    /// @param tokenId The unique identifier of the token being transferred.
+    /// @param force Whether to force the transfer.
+    /// @param data Additional data for the transfer.
+    function _beforeTokenTransfer(
+        address from,
+        address to,
+        bytes32 tokenId,
+        bool force,
+        bytes memory data
+    )
+        internal
+        virtual
+        override(
+            LSP8IdentifiableDigitalAsset,
+            LSP8CappedBalanceAbstract,
+            LSP8NonTransferableAbstract
+        )
+    {
+        super._beforeTokenTransfer(from, to, tokenId, force, data);
+    }
+
+    /// @dev Required override to resolve multiple inheritance. Calls every parent {_transferOwnership} function
+    /// via `super` so that each inherited module updates its ownership-dependent state.
+    ///
+    /// When contract ownership changes, this will:
+    /// - clear the admin role for: `MINTER_ROLE`, `REVOKER_ROLE`, `NON_TRANSFERABLE_BYPASS_ROLE`, `UNCAPPED_BALANCE_ROLE`
+    /// - clear the list of addresses holding the `REVOKER_ROLE`
+    function _transferOwnership(
+        address newOwner
+    )
+        internal
+        virtual
+        override(
+            Ownable,
+            LSP8CappedBalanceAbstract,
+            LSP8MintableAbstract,
+            LSP8NonTransferableAbstract,
+            LSP8RevokableAbstract
+        )
+    {
+        super._transferOwnership(newOwner);
+    }
+
+    /// @dev Mint initial NFTs without enforcing check if the token contract is mintable or not.
+    /// Enforces the configured capped-supply value directly (not {tokenSupplyCap} when minting is disabled).
+    function _initialMint(
+        address to,
+        bytes32[] memory initialMintTokenIds
+    ) private {
+        uint256 configuredTokenSupplyCap = LSP8CappedSupplyAbstract
+            .tokenSupplyCap();
+        bool isCappedSupplyConfigured = configuredTokenSupplyCap > 0;
+
+        if (isCappedSupplyConfigured) {
+            bool mintingExceedsSupplyCap = initialMintTokenIds.length >
+                configuredTokenSupplyCap;
+
+            require(
+                !mintingExceedsSupplyCap,
+                LSP8CappedSupplyCannotMintOverCap()
+            );
+        }
+
+        for (uint256 ii = 0; ii < initialMintTokenIds.length; ++ii) {
+            LSP8IdentifiableDigitalAsset._mint(
+                to,
+                initialMintTokenIds[ii],
+                true,
+                ""
+            );
+        }
+    }
+
+    /// @dev Returns whether the current call is a legitimate revocation that should bypass the
+    /// {LSP8NonTransferable} and {LSP8CappedBalance} restrictions when revoking tokens from a token holder.
+    ///
+    /// Returns `true` only when all of the following conditions are met:
+    /// - the function being called is {revoke}.
+    /// - the revoking feature is enabled.
+    /// - the caller (`msg.sender`) holds the `REVOKER_ROLE`.
+    /// - the recipient (`to`) is either the contract `owner()` or a revoker (an address holding the `REVOKER_ROLE`).
+    function _isRevocationBypass(address to) private view returns (bool) {
+        return
+            msg.sig == this.revoke.selector &&
+            isRevokable() &&
+            hasRole(REVOKER_ROLE, msg.sender) &&
+            (to == owner() || hasRole(REVOKER_ROLE, to));
+    }
+}

package/contracts/presets/LSP8CustomizableTokenConstants.sol

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.27;
+
+/// @dev Deployment configuration for minting feature.
+/// @param isMintable True to enable minting after deployment, false to disable it forever.
+/// @param initialMintTokenIds Array of tokenIds to mint to `newOwner_` on deployment.
+struct LSP8MintableParams {
+    bool isMintable;
+    bytes32[] initialMintTokenIds;
+}
+
+/// @dev Deployment configuration for capped balance and capped supply features.
+/// @param tokenBalanceCap The maximum number of NFTs per address, 0 to disable.
+/// @param tokenSupplyCap The maximum total supply of NFTs, 0 to disable.
+struct LSP8CappedParams {
+    uint256 tokenBalanceCap;
+    uint256 tokenSupplyCap;
+}
+
+/// @dev Deployment configuration for non-transferable feature.
+/// @param transferLockStart The start timestamp of the transfer lock period, 0 to disable.
+/// @param transferLockEnd The end timestamp of the transfer lock period, 0 to disable.
+struct LSP8NonTransferableParams {
+    uint256 transferLockStart;
+    uint256 transferLockEnd;
+}
+
+/// @dev Deployment configuration for revokable feature.
+/// @param isRevokable True to enable token revocation after deployment, false to disable it.
+struct LSP8RevokableParams {
+    bool isRevokable;
+}