From 7d4f9e3d8ac8009d95ac8b3de4575b0d2ab3758e Mon Sep 17 00:00:00 2001 From: CJ42 Date: Tue, 11 Jul 2023 15:42:52 +0100 Subject: [PATCH 1/2] docs: update Natspec comments for LSP7 preset + extensions --- .../extensions/ILSP7CompatibleERC20.sol | 40 ++++++++++------ .../extensions/LSP7Burnable.sol | 6 +-- .../extensions/LSP7BurnableInitAbstract.sol | 6 +-- .../extensions/LSP7CappedSupply.sol | 39 ++++++++++----- .../LSP7CappedSupplyInitAbstract.sol | 39 +++++++++++---- .../extensions/LSP7CompatibleERC20.sol | 48 ++++++++++++++----- .../LSP7CompatibleERC20InitAbstract.sol | 43 +++++++++++++---- .../presets/LSP7CompatibleERC20Mintable.sol | 14 ++++++ .../LSP7CompatibleERC20MintableInit.sol | 13 +++-- ...SP7CompatibleERC20MintableInitAbstract.sol | 8 +++- .../LSP7DigitalAsset/presets/LSP7Mintable.sol | 16 +++---- .../presets/LSP7MintableInit.sol | 13 ++--- .../presets/LSP7MintableInitAbstract.sol | 10 +++- 13 files changed, 213 insertions(+), 82 deletions(-) diff --git a/contracts/LSP7DigitalAsset/extensions/ILSP7CompatibleERC20.sol b/contracts/LSP7DigitalAsset/extensions/ILSP7CompatibleERC20.sol index 6fb35cb42..64b3bd287 100644 --- a/contracts/LSP7DigitalAsset/extensions/ILSP7CompatibleERC20.sol +++ b/contracts/LSP7DigitalAsset/extensions/ILSP7CompatibleERC20.sol @@ -10,8 +10,9 @@ import {ILSP7DigitalAsset} from "../ILSP7DigitalAsset.sol"; */ interface ILSP7CompatibleERC20 is ILSP7DigitalAsset { /** - * @notice To provide compatibility with indexing ERC20 events. - * @dev Emitted when `amount` tokens is transferred from `from` to `to`. + * @dev ERC20 `Transfer` event emitted when `amount` tokens is transferred from `from` to `to`. + * To provide compatibility with indexing ERC20 events. + * * @param from The sending address * @param to The receiving address * @param value The amount of tokens transfered. @@ -19,8 +20,9 @@ interface ILSP7CompatibleERC20 is ILSP7DigitalAsset { event Transfer(address indexed from, address indexed to, uint256 value); /** - * @notice To provide compatibility with indexing ERC20 events. - * @dev Emitted when `owner` enables `spender` for `value` tokens. + * @dev ERC20 `Approval` event emitted when `owner` enables `spender` for `value` tokens. + * To provide compatibility with indexing ERC20 events. + * * @param owner The account giving approval * @param spender The account receiving approval * @param value The amount of tokens `spender` has access to from `owner` @@ -32,17 +34,22 @@ interface ILSP7CompatibleERC20 is ILSP7DigitalAsset { ); /* - * @dev Compatible with ERC20 transfer - * @param to The receiving address - * @param amount The amount of tokens to transfer + * @dev Transfer function from the ERC20 standard interface. + + * @param to The address receiving tokens. + * @param amount The amount of tokens to transfer. + * @return `true` on successful transfer. */ function transfer(address to, uint256 amount) external returns (bool); /* - * @dev Compatible with ERC20 transferFrom - * @param from The sending address - * @param to The receiving address - * @param amount The amount of tokens to transfer + * @dev Transfer functions for operators from the ERC20 standard interface. + + * @param from The address sending tokens. + * @param to The address receiving tokens. + * @param amount The amount of tokens to transfer. + * + * @return `true` on successful transfer. */ function transferFrom( address from, @@ -51,16 +58,21 @@ interface ILSP7CompatibleERC20 is ILSP7DigitalAsset { ) external returns (bool); /* - * @dev Compatible with ERC20 approve + * @dev Approval function from th ERC20 standard interface. + * @param operator The address to approve for `amount` - * @param amount The amount to approve + * @param amount The amount to approve. + * + * @return `true` on successful approval. */ function approve(address operator, uint256 amount) external returns (bool); /* - * @dev Compatible with ERC20 allowance + * @dev Function to get operator allowance allowed to spend on behalf of `tokenOwner` from the ERC20 standard interface. + * @param tokenOwner The address of the token owner * @param operator The address approved by the `tokenOwner` + * * @return The amount `operator` is approved by `tokenOwner` */ function allowance( diff --git a/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol b/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol index 99ef9d0e1..f28967ccf 100644 --- a/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol +++ b/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol @@ -5,14 +5,12 @@ pragma solidity ^0.8.4; import {LSP7DigitalAsset} from "../LSP7DigitalAsset.sol"; /** - * @dev LSP7 extension that allows token holders to destroy both + * @title LSP7 token extension that allows token holders to destroy both * their own tokens and those that they have an allowance for as an operator. */ abstract contract LSP7Burnable is LSP7DigitalAsset { /** - * @dev Destroys `amount` tokens from the `from` address. - * - * See internal _burn function for more details + * @dev See internal {_burn} function for details. */ function burn( address from, diff --git a/contracts/LSP7DigitalAsset/extensions/LSP7BurnableInitAbstract.sol b/contracts/LSP7DigitalAsset/extensions/LSP7BurnableInitAbstract.sol index 76d58d00e..7b542d189 100644 --- a/contracts/LSP7DigitalAsset/extensions/LSP7BurnableInitAbstract.sol +++ b/contracts/LSP7DigitalAsset/extensions/LSP7BurnableInitAbstract.sol @@ -7,14 +7,12 @@ import { } from "../LSP7DigitalAssetInitAbstract.sol"; /** - * @dev LSP7 extension that allows token holders to destroy both + * @title LSP7 token extension that allows token holders to destroy both * their own tokens and those that they have an allowance for as an operator. */ abstract contract LSP7BurnableInitAbstract is LSP7DigitalAssetInitAbstract { /** - * @dev Destroys `amount` tokens from the `from` address. - * - * See internal _burn function for more details + * @dev See internal {_burn} function for details. */ function burn( address from, diff --git a/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol b/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol index 18c8b5afb..ee9525d77 100644 --- a/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol +++ b/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol @@ -6,19 +6,35 @@ pragma solidity ^0.8.4; import {LSP7DigitalAsset} from "../LSP7DigitalAsset.sol"; /** - * @dev LSP7 extension, adds token supply cap. + * @dev LSP7 token extension to add a max token supply cap. */ abstract contract LSP7CappedSupply is LSP7DigitalAsset { // --- Errors + + /** + * @notice The `tokenSupplyCap` must be set and cannot be `0`. + * @dev Reverts when setting `0` for the {tokenSupplyCap}. The max token supply MUST be set to a number greater than 0. + */ error LSP7CappedSupplyRequired(); + + /** + * @notice Cannot mint anymore as total supply reached the maximum cap. + * @dev Reverts when trying to mint tokens but the {totalSupply} has reached the maximum {tokenSupplyCap}. + */ error LSP7CappedSupplyCannotMintOverCap(); // --- Storage uint256 private immutable _tokenSupplyCap; /** - * @notice Sets the token max supply - * @param tokenSupplyCap_ The Token max supply + * @notice Deploying a `LSP7CappedSupply` token contract with max token supply cap set to `tokenSupplyCap_`. + * @dev Deploy a `LSP7CappedSupply` token contract and set the maximum token supply token cap up to which + * it is not possible to mint more tokens. + * + * @param tokenSupplyCap_ The maximum token supply. + * + * @custom:requirements + * - `tokenSupplyCap_` MUST NOT be 0. */ constructor(uint256 tokenSupplyCap_) { if (tokenSupplyCap_ == 0) { @@ -31,8 +47,11 @@ abstract contract LSP7CappedSupply is LSP7DigitalAsset { // --- Token queries /** - * @dev Returns the number of tokens that can be minted - * @return The number of tokens that can be minted + * @notice The maximum supply amount of tokens allowed to exist is `_tokenSupplyCap`. + * @dev Get the maximum number of tokens that can exist to circulate. Once {totalSupply} reaches + * reaches {totalSuuplyCap}, it is not possible to mint more tokens. + * + * @return The maximum number of tokens that can exist in the contract. */ function tokenSupplyCap() public view virtual returns (uint256) { return _tokenSupplyCap; @@ -41,14 +60,12 @@ abstract contract LSP7CappedSupply is LSP7DigitalAsset { // --- Transfer functionality /** - * @dev Mints `amount` and transfers it to `to`. + * @dev Same as {_mint} but allows to mint only if the {totalSupply} does not exceed the {tokenSupplyCap} + * after `amount` of tokens have been minted. * - * Requirements: - * - * - `tokenSupplyCap() - totalSupply()` must be greater than zero. + * @custom:requirements + * - {tokenSupplyCap} - {totalSupply} must be greater than zero. * - `to` cannot be the zero address. - * - * Emits a {Transfer} event. */ function _mint( address to, diff --git a/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupplyInitAbstract.sol b/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupplyInitAbstract.sol index 6a4d18812..66d0c8686 100644 --- a/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupplyInitAbstract.sol +++ b/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupplyInitAbstract.sol @@ -8,16 +8,36 @@ import { } from "../LSP7DigitalAssetInitAbstract.sol"; /** - * @dev LSP7 extension, adds token supply cap. + * @dev LSP7 token extension to add a max token supply cap (proxy version). */ abstract contract LSP7CappedSupplyInitAbstract is LSP7DigitalAssetInitAbstract { // --- Errors + + /** + * @notice The `tokenSupplyCap` must be set and cannot be `0`. + * @dev Reverts when setting `0` for the {tokenSupplyCap}. The max token supply MUST be set to a number greater than 0. + */ error LSP7CappedSupplyRequired(); + + /** + * @notice Cannot mint anymore as total supply reached the maximum cap. + * @dev Reverts when trying to mint tokens but the {totalSupply} has reached the maximum {tokenSupplyCap}. + */ error LSP7CappedSupplyCannotMintOverCap(); // --- Storage uint256 private _tokenSupplyCap; + /** + * @notice Deploying a `LSP7CappedSupply` token contract with max token supply cap set to `tokenSupplyCap_`. + * @dev Deploy a `LSP7CappedSupply` token contract and set the maximum token supply token cap up to which + * it is not possible to mint more tokens. + * + * @param tokenSupplyCap_ The maximum token supply. + * + * @custom:requirements + * - `tokenSupplyCap_` MUST NOT be 0. + */ function _initialize( uint256 tokenSupplyCap_ ) internal virtual onlyInitializing { @@ -31,8 +51,11 @@ abstract contract LSP7CappedSupplyInitAbstract is LSP7DigitalAssetInitAbstract { // --- Token queries /** - * @dev Returns the number of tokens that can be minted - * @return The number of tokens that can be minted + * @notice The maximum supply amount of tokens allowed to exist is `_tokenSupplyCap`. + * @dev Get the maximum number of tokens that can exist to circulate. Once {totalSupply} reaches + * reaches {totalSuuplyCap}, it is not possible to mint more tokens. + * + * @return The maximum number of tokens that can exist in the contract. */ function tokenSupplyCap() public view virtual returns (uint256) { return _tokenSupplyCap; @@ -41,14 +64,12 @@ abstract contract LSP7CappedSupplyInitAbstract is LSP7DigitalAssetInitAbstract { // --- Transfer functionality /** - * @dev Mints `amount` and transfers it to `to`. - * - * Requirements: + * @dev Same as {_mint} but allows to mint only if the {totalSupply} does not exceed the {tokenSupplyCap} + * after `amount` of tokens have been minted. * - * - `tokenSupplyCap() - totalSupply()` must be greater than zero. + * @custom:requirements + * - {tokenSupplyCap} - {totalSupply} must be greater than zero. * - `to` cannot be the zero address. - * - * Emits a {Transfer} event. */ function _mint( address to, diff --git a/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol b/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol index 77140d4c0..1f8344ab8 100644 --- a/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol +++ b/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol @@ -11,6 +11,7 @@ import { } from "../../LSP4DigitalAssetMetadata/LSP4Compatibility.sol"; import { LSP7DigitalAsset, + LSP7DigitalAssetCore, LSP4DigitalAssetMetadata, ERC725YCore } from "../LSP7DigitalAsset.sol"; @@ -24,10 +25,12 @@ abstract contract LSP7CompatibleERC20 is LSP7DigitalAsset { /** - * @notice Sets the name, the symbol and the owner of the token - * @param name_ The name of the token - * @param symbol_ The symbol of the token - * @param newOwner_ The owner of the token + * @notice Deploying a `LSP7CompatibleERC20` token contract with: token name = `name_`, token symbol = `symbol_`, and + * address `newOwner_` as the token contract owner. + * + * @param name_ The name of the token. + * @param symbol_ The symbol of the token. + * @param newOwner_ The owner of the token contract. */ constructor( string memory name_, @@ -36,7 +39,7 @@ abstract contract LSP7CompatibleERC20 is ) LSP7DigitalAsset(name_, symbol_, newOwner_, false) {} /** - * @dev See {IERC165-supportsInterface}. + * @inheritdoc LSP7DigitalAsset */ function supportsInterface( bytes4 interfaceId @@ -73,8 +76,8 @@ abstract contract LSP7CompatibleERC20 is /** * @inheritdoc ILSP7CompatibleERC20 - * @dev Compatible with ERC20 transferFrom. - * Using allowNonLSP1Recipient=true so that EOA and any contract may receive the tokens. + * + * @custom:info This function uses the `allowNonLSP1Recipient` parameter as `true` so that EOA and any contract can receive tokens. */ function transferFrom( address from, @@ -89,8 +92,8 @@ abstract contract LSP7CompatibleERC20 is /** * @inheritdoc ILSP7CompatibleERC20 - * @dev Compatible with ERC20 transfer. - * Using allowNonLSP1Recipient=true so that EOA and any contract may receive the tokens. + * + * @custom:info This function uses the `allowNonLSP1Recipient` parameter as `true` so that EOA and any contract can receive tokens. */ function transfer( address to, @@ -101,8 +104,7 @@ abstract contract LSP7CompatibleERC20 is } /** - * @dev same behaviour as LSP7DigitalAssetCore - * with the addition of emitting ERC20 Approval event. + * @inheritdoc LSP7DigitalAssetCore */ function _updateOperator( address tokenOwner, @@ -113,6 +115,13 @@ abstract contract LSP7CompatibleERC20 is emit Approval(tokenOwner, operator, amount); } + /** + * @inheritdoc LSP7DigitalAssetCore + * + * @custom:events + * - LSP7 {Transfer} event. + * - ERC20 {Transfer} event. + */ function _transfer( address from, address to, @@ -124,6 +133,13 @@ abstract contract LSP7CompatibleERC20 is super._transfer(from, to, amount, allowNonLSP1Recipient, data); } + /** + * @inheritdoc LSP7DigitalAssetCore + * + * @custom:events + * - LSP7 {Transfer} event with `address(0)` as `from`. + * - ERC20 {Transfer} event with `address(0)` as `from`. + */ function _mint( address to, uint256 amount, @@ -134,6 +150,13 @@ abstract contract LSP7CompatibleERC20 is super._mint(to, amount, allowNonLSP1Recipient, data); } + /** + * @inheritdoc LSP7DigitalAssetCore + * + * @custom:events + * - LSP7 {Transfer} event with `address(0)` as the `to` address. + * - ERC20 {Transfer} event with `address(0)` as the `to` address. + */ function _burn( address from, uint256 amount, @@ -143,6 +166,9 @@ abstract contract LSP7CompatibleERC20 is super._burn(from, amount, data); } + /** + * @inheritdoc LSP4DigitalAssetMetadata + */ function _setData( bytes32 key, bytes memory value diff --git a/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20InitAbstract.sol b/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20InitAbstract.sol index 5d41c4271..4340e2e63 100644 --- a/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20InitAbstract.sol +++ b/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20InitAbstract.sol @@ -10,6 +10,7 @@ import { LSP4Compatibility } from "../../LSP4DigitalAssetMetadata/LSP4Compatibility.sol"; import { + LSP7DigitalAssetCore, LSP7DigitalAssetInitAbstract, LSP4DigitalAssetMetadataInitAbstract, ERC725YCore @@ -24,12 +25,13 @@ abstract contract LSP7CompatibleERC20InitAbstract is LSP7DigitalAssetInitAbstract { /** - * @notice Sets the name, the symbol and the owner of the token + * @notice Initializing a `LSP7CompatibleERC20` token contract with: token name = `name_`, token symbol = `symbol_`, and + * address `newOwner_` as the token contract owner. + * * @param name_ The name of the token * @param symbol_ The symbol of the token * @param newOwner_ The owner of the token */ - function _initialize( string memory name_, string memory symbol_, @@ -44,7 +46,7 @@ abstract contract LSP7CompatibleERC20InitAbstract is } /** - * @dev See {IERC165-supportsInterface}. + * @inheritdoc LSP7DigitalAssetInitAbstract */ function supportsInterface( bytes4 interfaceId @@ -81,8 +83,8 @@ abstract contract LSP7CompatibleERC20InitAbstract is /** * @inheritdoc ILSP7CompatibleERC20 - * @dev Compatible with ERC20 transferFrom. - * Using allowNonLSP1Recipient=true so that EOA and any contract may receive the tokens. + * + * @custom:info This function uses the `allowNonLSP1Recipient` parameter as `true` so that EOA and any contract can receive tokens. */ function transferFrom( address from, @@ -97,8 +99,8 @@ abstract contract LSP7CompatibleERC20InitAbstract is /** * @inheritdoc ILSP7CompatibleERC20 - * @dev Compatible with ERC20 transfer. - * Using allowNonLSP1Recipient=true so that EOA and any contract may receive the tokens. + * + * @custom:info This function uses the `allowNonLSP1Recipient` parameter as `true` so that EOA and any contract can receive tokens. */ function transfer( address to, @@ -109,8 +111,7 @@ abstract contract LSP7CompatibleERC20InitAbstract is } /** - * @dev same behaviour as LSP7DigitalAssetCore - * with the addition of emitting ERC20 Approval event. + * @inheritdoc LSP7DigitalAssetCore */ function _updateOperator( address tokenOwner, @@ -121,6 +122,13 @@ abstract contract LSP7CompatibleERC20InitAbstract is emit Approval(tokenOwner, operator, amount); } + /** + * @inheritdoc LSP7DigitalAssetCore + * + * @custom:events + * - LSP7 {Transfer} event. + * - ERC20 {Transfer} event. + */ function _transfer( address from, address to, @@ -132,6 +140,13 @@ abstract contract LSP7CompatibleERC20InitAbstract is super._transfer(from, to, amount, allowNonLSP1Recipient, data); } + /** + * @inheritdoc LSP7DigitalAssetCore + * + * @custom:events + * - LSP7 {Transfer} event with `address(0)` as `from`. + * - ERC20 {Transfer} event with `address(0)` as `from`. + */ function _mint( address to, uint256 amount, @@ -142,6 +157,13 @@ abstract contract LSP7CompatibleERC20InitAbstract is super._mint(to, amount, allowNonLSP1Recipient, data); } + /** + * @inheritdoc LSP7DigitalAssetCore + * + * @custom:events + * - LSP7 {Transfer} event with `address(0)` as the `to` address. + * - ERC20 {Transfer} event with `address(0)` as the `to` address. + */ function _burn( address from, uint256 amount, @@ -151,6 +173,9 @@ abstract contract LSP7CompatibleERC20InitAbstract is super._burn(from, amount, data); } + /** + * @inheritdoc LSP4DigitalAssetMetadataInitAbstract + */ function _setData( bytes32 key, bytes memory value diff --git a/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol b/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol index 270c9eb28..dc25a81c3 100644 --- a/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol +++ b/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol @@ -3,13 +3,27 @@ pragma solidity ^0.8.12; import {LSP7CompatibleERC20} from "../extensions/LSP7CompatibleERC20.sol"; +/** + * @title LSP7CompatibleERC20 deployable preset contract with a public {mint} function callable only by the contract {owner}. + */ contract LSP7CompatibleERC20Mintable is LSP7CompatibleERC20 { + /** + * @notice Deploying a `LSP7CompatibleERC20Mintable` token contract with: token name = `name_`, token symbol = `symbol_`, and + * address `newOwner_` as the token contract owner. + * + * @param name_ The name of the token. + * @param symbol_ The symbol of the token. + * @param newOwner_ The owner of the token contract. + */ constructor( string memory name_, string memory symbol_, address newOwner_ ) LSP7CompatibleERC20(name_, symbol_, newOwner_) {} + /** + * @dev Public {_mint} function only callable by the {owner}. + */ function mint( address to, uint256 amount, diff --git a/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20MintableInit.sol b/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20MintableInit.sol index c6e42355d..7bf424ce6 100644 --- a/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20MintableInit.sol +++ b/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20MintableInit.sol @@ -6,6 +6,9 @@ import { LSP7CompatibleERC20MintableInitAbstract } from "./LSP7CompatibleERC20MintableInitAbstract.sol"; +/** + * @title LSP7 deployable preset contract (proxy version) with a public mint function callable only by the contract {owner} + */ contract LSP7CompatibleERC20MintableInit is LSP7CompatibleERC20MintableInitAbstract { @@ -17,10 +20,12 @@ contract LSP7CompatibleERC20MintableInit is } /** - * @notice Sets the name, the symbol and the owner of the token - * @param name_ The name of the token - * @param symbol_ The symbol of the token - * @param newOwner_ The owner of the token + * @notice Initializing a `LSP7CompatibleERC20MintableInit` token contract with: token name = `name_`, token symbol = `symbol_`, and + * address `newOwner_` as the token contract owner. + * + * @param name_ The name of the token. + * @param symbol_ The symbol of the token. + * @param newOwner_ The owner of the token contract. */ function initialize( string memory name_, diff --git a/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20MintableInitAbstract.sol b/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20MintableInitAbstract.sol index 112a7d2ca..fe5b69b88 100644 --- a/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20MintableInitAbstract.sol +++ b/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20MintableInitAbstract.sol @@ -6,7 +6,10 @@ import { LSP7CompatibleERC20InitAbstract } from "../extensions/LSP7CompatibleERC20InitAbstract.sol"; -contract LSP7CompatibleERC20MintableInitAbstract is +/** + * @title LSP7 preset contract (inheritable proxy version) with a public mint function callable only by the contract {owner} + */ +abstract contract LSP7CompatibleERC20MintableInitAbstract is LSP7CompatibleERC20InitAbstract { /** @@ -20,6 +23,9 @@ contract LSP7CompatibleERC20MintableInitAbstract is LSP7CompatibleERC20InitAbstract._initialize(name_, symbol_, newOwner_); } + /** + * @dev Public {_mint} function only callable by the {owner}. + */ function mint( address to, uint256 amount, diff --git a/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol b/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol index d64d0eb3e..a11d44804 100644 --- a/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol +++ b/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol @@ -9,17 +9,17 @@ import {ILSP7Mintable} from "./ILSP7Mintable.sol"; import {LSP7DigitalAsset} from "../LSP7DigitalAsset.sol"; /** - * @title LSP7Mintable + * @title LSP7DigitalAsset deployable preset contract with a public {mint} function callable only by the contract {owner}. * @author Jean Cavallera, Yamen Merhi - * @dev LSP7 extension, mintable. */ contract LSP7Mintable is LSP7DigitalAsset, ILSP7Mintable { /** - * @notice Sets the token-Metadata and register LSP7InterfaceId - * @param name_ The name of the token - * @param symbol_ The symbol of the token - * @param newOwner_ The owner of the the token-Metadata - * @param isNonDivisible_ Specify if the LSP7 token is a fungible or non-fungible token + * @notice Deploying a `LSP7Mintable` token contract with: token name = `name_`, token symbol = `symbol_`, and + * address `newOwner_` as the token contract owner. + * + * @param name_ The name of the token. + * @param symbol_ The symbol of the token. + * @param newOwner_ The owner of the token contract. */ constructor( string memory name_, @@ -29,7 +29,7 @@ contract LSP7Mintable is LSP7DigitalAsset, ILSP7Mintable { ) LSP7DigitalAsset(name_, symbol_, newOwner_, isNonDivisible_) {} /** - * @inheritdoc ILSP7Mintable + * @dev Public {_mint} function only callable by the {owner}. */ function mint( address to, diff --git a/contracts/LSP7DigitalAsset/presets/LSP7MintableInit.sol b/contracts/LSP7DigitalAsset/presets/LSP7MintableInit.sol index aaad551ba..21bb6e87e 100644 --- a/contracts/LSP7DigitalAsset/presets/LSP7MintableInit.sol +++ b/contracts/LSP7DigitalAsset/presets/LSP7MintableInit.sol @@ -6,7 +6,7 @@ pragma solidity ^0.8.4; import {LSP7MintableInitAbstract} from "./LSP7MintableInitAbstract.sol"; /** - * @dev LSP7 extension, mintable. + * @dev LSP7DigitalAsset deployable preset contract (proxy version) with a public {mint} function callable only by the contract {owner}. */ contract LSP7MintableInit is LSP7MintableInitAbstract { /** @@ -17,11 +17,12 @@ contract LSP7MintableInit is LSP7MintableInitAbstract { } /** - * @notice Sets the token-Metadata and register LSP7InterfaceId - * @param name_ The name of the token - * @param symbol_ The symbol of the token - * @param newOwner_ The owner of the the token-Metadata - * @param isNonDivisible_ Specify if the LSP7 token is a fungible or non-fungible token + * @notice Initializing a `LSP7MintableInit` token contract with: token name = `name_`, token symbol = `symbol_`, and + * address `newOwner_` as the token contract owner. + * + * @param name_ The name of the token. + * @param symbol_ The symbol of the token. + * @param newOwner_ The owner of the token contract. */ function initialize( string memory name_, diff --git a/contracts/LSP7DigitalAsset/presets/LSP7MintableInitAbstract.sol b/contracts/LSP7DigitalAsset/presets/LSP7MintableInitAbstract.sol index 7cfc4a6cf..93767a32a 100644 --- a/contracts/LSP7DigitalAsset/presets/LSP7MintableInitAbstract.sol +++ b/contracts/LSP7DigitalAsset/presets/LSP7MintableInitAbstract.sol @@ -17,6 +17,14 @@ abstract contract LSP7MintableInitAbstract is LSP7DigitalAssetInitAbstract, ILSP7Mintable { + /** + * @notice Initialize a `LSP7MintableInitAbstract` token contract with: token name = `name_`, token symbol = `symbol_`, and + * address `newOwner_` as the token contract owner. + * + * @param name_ The name of the token. + * @param symbol_ The symbol of the token. + * @param newOwner_ The owner of the token contract. + */ function _initialize( string memory name_, string memory symbol_, @@ -32,7 +40,7 @@ abstract contract LSP7MintableInitAbstract is } /** - * @inheritdoc ILSP7Mintable + * @dev Public {_mint} function only callable by the {owner}. */ function mint( address to, From 7bd2d586e0ccadbb96b8dfafcc9f2984d3cf6004 Mon Sep 17 00:00:00 2001 From: CJ42 Date: Tue, 11 Jul 2023 15:43:14 +0100 Subject: [PATCH 2/2] docs: add auto-generated docs for LSP7 presets + extensions --- .../extensions/LSP7Burnable.md | 1327 +++++++++++++++ .../extensions/LSP7CappedSupply.md | 1353 +++++++++++++++ .../extensions/LSP7CompatibleERC20.md | 1446 ++++++++++++++++ .../presets/LSP7CompatibleERC20Mintable.md | 1504 +++++++++++++++++ .../LSP7DigitalAsset/presets/LSP7Mintable.md | 1364 +++++++++++++++ 5 files changed, 6994 insertions(+) create mode 100644 docs/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.md create mode 100644 docs/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.md create mode 100644 docs/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.md create mode 100644 docs/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.md create mode 100644 docs/contracts/LSP7DigitalAsset/presets/LSP7Mintable.md diff --git a/docs/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.md b/docs/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.md new file mode 100644 index 000000000..ce0b20055 --- /dev/null +++ b/docs/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.md @@ -0,0 +1,1327 @@ + + + +# LSP7Burnable + +:::info Standard Specifications + +[`LSP-7-DigitalAsset`](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md) + +::: +:::info Solidity implementation + +[`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) + +::: + +> LSP7 token extension that allows token holders to destroy both their own tokens and those that they have an allowance for as an operator. + +## Public Methods + +Public methods are accessible externally from users, allowing interaction with this function from dApps or other smart contracts. +When marked as 'public', a method can be called both externally and internally, on the other hand, when marked as 'external', a method can only be called externally. + +### authorizeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizeoperator) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `authorizeOperator(address,uint256)` +- Function selector: `0x47980aa3` + +::: + +:::danger + +To avoid front-running and Allowance Double-Spend Exploit when increasing or decreasing the authorized amount of an operator, it is advised to: 1. either call {revokeOperator} first, and then re-call {authorizeOperator} with the new amount. 2. or use the non-standard functions {increaseAllowance} or {decreaseAllowance}. For more information, see: https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/ + +::: + +```solidity +function authorizeOperator( + address operator, + uint256 amount +) external nonpayable; +``` + +Sets an `amount` of tokens that an `operator` has access from the caller's balance (allowance). See [`authorizedAmountFor`](#authorizedamountfor). + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ------------------------------------------------------ | +| `operator` | `address` | The address to authorize as an operator. | +| `amount` | `uint256` | The allowance amount of tokens operator has access to. | + +
+ +### authorizedAmountFor + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizedamountfor) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `authorizedAmountFor(address,address)` +- Function selector: `0x65aeaa95` + +::: + +```solidity +function authorizedAmountFor( + address operator, + address tokenOwner +) external view returns (uint256); +``` + +Get the amount of tokens `operator` address has access to from `tokenOwner`. Operators can send and burn tokens on behalf of their owners. + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | ---------------------------------------------------------- | +| `operator` | `address` | The operator's address to query the authorized amount for. | +| `tokenOwner` | `address` | The token owner that `operator` has allowance on. | + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | --------------------------------------------------------------------------------------- | +| `0` | `uint256` | The amount of tokens the `operator`'s address has access on the `tokenOwner`'s balance. | + +
+ +### balanceOf + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#balanceof) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `balanceOf(address)` +- Function selector: `0x70a08231` + +::: + +```solidity +function balanceOf(address tokenOwner) external view returns (uint256); +``` + +Get the number of tokens owned by `tokenOwner`. If the token is divisible (the [`decimals`](#decimals) function returns `18`), the amount returned should be divided by 1e18 to get a better picture of the actual balance of the `tokenOwner`. _Example:_ `balanceOf(someAddress) -> 42_000_000_000_000_000_000 / 1e18 = 42 tokens` + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | --------------------------------------------------------- | +| `tokenOwner` | `address` | The address of the token holder to query the balance for. | + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ------------------------------------------- | +| `0` | `uint256` | The amount of tokens owned by `tokenOwner`. | + +
+ +### burn + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#burn) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `burn(address,uint256,bytes)` +- Function selector: `0x44d17187` + +::: + +```solidity +function burn(address from, uint256 amount, bytes data) external nonpayable; +``` + +See internal [`_burn`](#_burn) function for details. + +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ----------- | +| `from` | `address` | - | +| `amount` | `uint256` | - | +| `data` | `bytes` | - | + +
+ +### decimals + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#decimals) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `decimals()` +- Function selector: `0x313ce567` + +::: + +```solidity +function decimals() external view returns (uint8); +``` + +Returns the number of decimals used to get its user representation. If the asset contract has been set to be non-divisible via the `isNonDivisible_` parameter in the `constructor`, the decimals returned wiil be `0`. Otherwise `18` is the common value. + +#### Returns + +| Name | Type | Description | +| ---- | :-----: | ----------------------------------------------------------------------- | +| `0` | `uint8` | the number of decimals. If `0` is returned, the asset is non-divisible. | + +
+ +### decreaseAllowance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#decreaseallowance) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `decreaseAllowance(address,uint256)` +- Function selector: `0xa457c2d7` + +::: + +:::info + +This is a non-standard function, not part of the LSP7 standard interface. It has been added in the LSP7 contract implementation so that it can be used as a prevention mechanism against the double spending allowance vulnerability. + +::: + +```solidity +function decreaseAllowance( + address operator, + uint256 substractedAmount +) external nonpayable; +``` + +_Decrease the allowance of `operator` by -`substractedAmount`_ + +Atomically decreases the allowance granted to `operator` by the caller. This is an alternative approach to [`authorizeOperator`](#authorizeoperator) that can be used as a mitigation for the double spending allowance problem. + +
+ +**Requirements:** + +- `operator` cannot be the zero address. +- `operator` must have allowance for the caller of at least `substractedAmount`. + +
+ +
+ +**Emitted events:** + +- [`AuthorizedOperator`](#authorizedoperator) event indicating the updated allowance after decreasing it. +- [`RevokeOperator`](#revokeoperator) event if `substractedAmount` is the full allowance, indicating `operator` does not have any alauthorizedAmountForlowance left for `msg.sender`. + +
+ +#### Parameters + +| Name | Type | Description | +| ------------------- | :-------: | ------------------------------------------------------ | +| `operator` | `address` | the operator to decrease allowance for `msg.sender` | +| `substractedAmount` | `uint256` | the amount to decrease by in the operator's allowance. | + +
+ +### getData + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#getdata) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `getData(bytes32)` +- Function selector: `0x54f6127f` + +::: + +```solidity +function getData(bytes32 dataKey) external view returns (bytes dataValue); +``` + +_Gets singular data at a given `dataKey`_ + +#### Parameters + +| Name | Type | Description | +| --------- | :-------: | ------------------------------- | +| `dataKey` | `bytes32` | The key which value to retrieve | + +#### Returns + +| Name | Type | Description | +| ----------- | :-----: | -------------------------- | +| `dataValue` | `bytes` | The data stored at the key | + +
+ +### getDataBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#getdatabatch) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `getDataBatch(bytes32[])` +- Function selector: `0xdedff9c6` + +::: + +```solidity +function getDataBatch( + bytes32[] dataKeys +) external view returns (bytes[] dataValues); +``` + +_Gets array of data for multiple given keys_ + +#### Parameters + +| Name | Type | Description | +| ---------- | :---------: | ------------------------------------------ | +| `dataKeys` | `bytes32[]` | The array of keys which values to retrieve | + +#### Returns + +| Name | Type | Description | +| ------------ | :-------: | ----------------------------------------- | +| `dataValues` | `bytes[]` | The array of data stored at multiple keys | + +
+ +### increaseAllowance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#increaseallowance) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `increaseAllowance(address,uint256)` +- Function selector: `0x39509351` + +::: + +:::info + +This is a non-standard function, not part of the LSP7 standard interface. It has been added in the LSP7 contract implementation so that it can be used as a prevention mechanism against double spending allowance vulnerability. + +::: + +```solidity +function increaseAllowance( + address operator, + uint256 addedAmount +) external nonpayable; +``` + +_Increase the allowance of `operator` by +`addedAmount`_ + +Atomically increases the allowance granted to `operator` by the caller. This is an alternative approach to [`authorizeOperator`](#authorizeoperator) that can be used as a mitigation for the double spending allowance problem. + +
+ +**Requirements:** + +- `operator` cannot be the same address as `msg.sender` +- `operator` cannot be the zero address. + +
+ +
+ +**Emitted events:** + +- [`AuthorizedOperator`](#authorizedoperator) indicating the updated allowance + +
+ +#### Parameters + +| Name | Type | Description | +| ------------- | :-------: | ----------------------------------------------------------------------- | +| `operator` | `address` | the operator to increase the allowance for `msg.sender` | +| `addedAmount` | `uint256` | the additional amount to add on top of the current operator's allowance | + +
+ +### owner + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#owner) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `owner()` +- Function selector: `0x8da5cb5b` + +::: + +```solidity +function owner() external view returns (address); +``` + +Returns the address of the current owner. + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ----------- | +| `0` | `address` | - | + +
+ +### renounceOwnership + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#renounceownership) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `renounceOwnership()` +- Function selector: `0x715018a6` + +::: + +```solidity +function renounceOwnership() external nonpayable; +``` + +Leaves the contract without owner. It will not be possible to call `onlyOwner` functions anymore. Can only be called by the current owner. NOTE: Renouncing ownership will leave the contract without an owner, thereby removing any functionality that is only available to the owner. + +
+ +### revokeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#revokeoperator) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `revokeOperator(address)` +- Function selector: `0xfad8b32a` + +::: + +```solidity +function revokeOperator(address operator) external nonpayable; +``` + +Removes the `operator` address as an operator of callers tokens, disallowing it to send any amount of tokens on behalf of the token owner (the caller of the function `msg.sender`). See also [`authorizedAmountFor`](#authorizedamountfor). + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ------------------------------------- | +| `operator` | `address` | The address to revoke as an operator. | + +
+ +### setData + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#setdata) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `setData(bytes32,bytes)` +- Function selector: `0x7f23690c` + +::: + +```solidity +function setData(bytes32 dataKey, bytes dataValue) external payable; +``` + +_Sets singular data for a given `dataKey`_ + +#### Parameters + +| Name | Type | Description | +| ----------- | :-------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dataKey` | `bytes32` | The key to retrieve stored value | +| `dataValue` | `bytes` | The value to set SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal 0. Emits a {DataChanged} event. | + +
+ +### setDataBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#setdatabatch) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `setDataBatch(bytes32[],bytes[])` +- Function selector: `0x97902421` + +::: + +```solidity +function setDataBatch(bytes32[] dataKeys, bytes[] dataValues) external payable; +``` + +Sets array of data for multiple given `dataKeys` SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal + +0. Emits a [`DataChanged`](#datachanged) event. + +#### Parameters + +| Name | Type | Description | +| ------------ | :---------: | ---------------------------------------- | +| `dataKeys` | `bytes32[]` | The array of data keys for values to set | +| `dataValues` | `bytes[]` | The array of values to set | + +
+ +### supportsInterface + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#supportsinterface) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `supportsInterface(bytes4)` +- Function selector: `0x01ffc9a7` + +::: + +```solidity +function supportsInterface(bytes4 interfaceId) external view returns (bool); +``` + +Returns true if this contract implements the interface defined by `interfaceId`. See the corresponding https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section] to learn more about how these ids are created. This function call must use less than 30 000 gas. + +#### Parameters + +| Name | Type | Description | +| ------------- | :------: | ----------- | +| `interfaceId` | `bytes4` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :----: | ----------- | +| `0` | `bool` | - | + +
+ +### totalSupply + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#totalsupply) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `totalSupply()` +- Function selector: `0x18160ddd` + +::: + +```solidity +function totalSupply() external view returns (uint256); +``` + +Returns the number of existing tokens that have been minted in this contract. + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ------------------------------ | +| `0` | `uint256` | The number of existing tokens. | + +
+ +### transfer + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transfer) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `transfer(address,address,uint256,bool,bytes)` +- Function selector: `0x760d9bba` + +::: + +```solidity +function transfer( + address from, + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) external nonpayable; +``` + +Transfers an `amount` of tokens from the `from` address to the `to` address and notify both sender and recipients via the LSP1 [`universalReceiver(...)`](#`universalreceiver) function. If the tokens are transferred by an operator on behalf of a token holder, the allowance for the operator will be decreased by `amount` once the token transfer has been completed (See [`authorizedAmountFor`](#authorizedamountfor)). + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address` | The sender address. | +| `to` | `address` | The recipient address. | +| `amount` | `uint256` | The amount of tokens to transfer. | +| `allowNonLSP1Recipient` | `bool` | When set to `true`, the `to` address CAN be any address. When set to `false`, the `to` address MUST be a contract that supports the LSP1 UniversalReceiver standard. | +| `data` | `bytes` | Any additional data the caller wants included in the emitted event, and sent in the hooks of the `from` and `to` addresses. | + +
+ +### transferBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transferbatch) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `transferBatch(address[],address[],uint256[],bool[],bytes[])` +- Function selector: `0x2d7667c9` + +::: + +```solidity +function transferBatch( + address[] from, + address[] to, + uint256[] amount, + bool[] allowNonLSP1Recipient, + bytes[] data +) external nonpayable; +``` + +Same as [`transfer(...)`](#`transfer) but transfer multiple tokens based on the arrays of `from`, `to`, `amount`. + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :---------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address[]` | An array of sending addresses. | +| `to` | `address[]` | An array of receiving addresses. | +| `amount` | `uint256[]` | An array of amount of tokens to transfer for each `from -> to` transfer. | +| `allowNonLSP1Recipient` | `bool[]` | For each transfer, when set to `true`, the `to` address CAN be any address. When set to `false`, the `to` address MUST be a contract that supports the LSP1 UniversalReceiver standard. | +| `data` | `bytes[]` | An array of additional data the caller wants included in the emitted event, and sent in the hooks to `from` and `to` addresses. | + +
+ +### transferOwnership + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transferownership) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Function signature: `transferOwnership(address)` +- Function selector: `0xf2fde38b` + +::: + +```solidity +function transferOwnership(address newOwner) external nonpayable; +``` + +Transfers ownership of the contract to a new account (`newOwner`). Can only be called by the current owner. + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ----------- | +| `newOwner` | `address` | - | + +
+ +## Internal Methods + +Any method labeled as `internal` serves as utility function within the contract. They can be used when writing solidity contracts that inherit from this contract. These methods can be extended or modified by overriding their internal behavior to suit specific needs. + +Internal functions cannot be called externally, whether from other smart contracts, dApp interfaces, or backend services. Their restricted accessibility ensures that they remain exclusively available within the context of the current contract, promoting controlled and encapsulated usage of these internal utilities. + +### \_checkOwner + +```solidity +function _checkOwner() internal view; +``` + +Throws if the sender is not the owner. + +
+ +### \_setOwner + +```solidity +function _setOwner(address newOwner) internal nonpayable; +``` + +Changes the owner if `newOwner` and oldOwner are different +This pattern is useful in inheritance. + +
+ +### \_getData + +```solidity +function _getData(bytes32 dataKey) internal view returns (bytes dataValue); +``` + +
+ +### \_setData + +```solidity +function _setData(bytes32 dataKey, bytes dataValue) internal nonpayable; +``` + +Save gas by emitting the [`DataChanged`](#datachanged) event with only the first 256 bytes of dataValue + +
+ +### \_updateOperator + +```solidity +function _updateOperator( + address tokenOwner, + address operator, + uint256 amount +) internal nonpayable; +``` + +Changes token `amount` the `operator` has access to from `tokenOwner` tokens. +If the amount is zero then the operator is being revoked, otherwise the operator amount is being modified. + +
+ +### \_mint + +```solidity +function _mint( + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) internal nonpayable; +``` + +Mints `amount` of tokens and transfers it to `to`. + +
+ +**Emitted events:** + +- [`Transfer`](#transfer) event with `address(0)` as `from`. + +
+ +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ------------------------------------------------------------------------------------------------------------------------- | +| `to` | `address` | the address to mint tokens for. | +| `amount` | `uint256` | the amount of tokens to mint. | +| `allowNonLSP1Recipient` | `bool` | a boolean that describe if transfer to a `to` address that does not support LSP1 is allowed or not. | +| `data` | `bytes` | Additional data the caller wants included in the emitted {Transfer} event, and sent in the LSP1 hook to the `to` address. | + +
+ +### \_burn + +:::tip Hint + +In dApps, you can know which address is burning tokens by listening for the `Transfer` event and filter with the zero address as `to`. + +::: + +```solidity +function _burn(address from, uint256 amount, bytes data) internal nonpayable; +``` + +Burns (= destroys) `amount` of tokens, decrease the `from` balance. This is done by sending them to the zero address. +Both the sender and recipient will be notified of the token transfer through the LSP1 [`universalReceiver`](#universalreceiver) +function, if they are contracts that support the LSP1 interface. Their `universalReceiver` function will receive +all the parameters in the calldata packed encoded. +Any logic in the [`_beforeTokenTransfer`](#_beforetokentransfer) function will run before updating the balances. + +
+ +**Emitted events:** + +- [`Transfer`](#transfer) event with `address(0)` as the `to` address + +
+ +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address` | the address to burn tokens from its balance. | +| `amount` | `uint256` | the amount of tokens to burn. | +| `data` | `bytes` | Additional data the caller wants included in the emitted event, and sent in the LSP1 hook to the `from` and `to` address. | + +
+ +### \_transfer + +```solidity +function _transfer( + address from, + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) internal nonpayable; +``` + +Transfer tokens from `from` to `to` by decreasing the balance of `from` by `-amount` and increasing the balance +of `to` by `+amount`. +Both the sender and recipient will be notified of the token transfer through the LSP1 [`universalReceiver`](#universalreceiver) +function, if they are contracts that support the LSP1 interface. Their `universalReceiver` function will receive +all the parameters in the calldata packed encoded. +Any logic in the [`_beforeTokenTransfer`](#_beforetokentransfer) function will run before updating the balances. + +
+ +**Emitted events:** + +- [`Transfer`](#transfer) event. + +
+ +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address` | the address to decrease the balance. | +| `to` | `address` | the address to increase the balance. | +| `amount` | `uint256` | the amount of tokens to transfer from `from` to `to`. | +| `allowNonLSP1Recipient` | `bool` | a boolean that describe if transfer to a `to` address that does not support LSP1 is allowed or not. | +| `data` | `bytes` | Additional data the caller wants included in the emitted event, and sent in the LSP1 hook to the `from` and `to` address. | + +
+ +### \_beforeTokenTransfer + +```solidity +function _beforeTokenTransfer( + address from, + address to, + uint256 amount +) internal nonpayable; +``` + +Hook that is called before any token transfer, including minting and burning. +Allows to run custom logic before updating balances and notifiying sender/recipient by overriding this function. + +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ------------------------------- | +| `from` | `address` | The sender address | +| `to` | `address` | The recipient address | +| `amount` | `uint256` | The amount of token to transfer | + +
+ +### \_notifyTokenSender + +```solidity +function _notifyTokenSender(address from, bytes lsp1Data) internal nonpayable; +``` + +Attempt to notify the token sender `from` about the `amount` of tokens being transferred. +This is done by calling its [`universalReceiver`](#universalreceiver) function with the `_TYPEID_LSP7_TOKENSSENDER` as typeId, if `from` is a contract that supports the LSP1 interface. +If `from` is an EOA or a contract that does not support the LSP1 interface, nothing will happen and no notification will be sent. + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | -------------------------------------------------------------------------- | +| `from` | `address` | The address to call the {universalReceiver} function on. | +| `lsp1Data` | `bytes` | the data to be sent to the `from` address in the `universalReceiver` call. | + +
+ +### \_notifyTokenReceiver + +```solidity +function _notifyTokenReceiver( + address to, + bool allowNonLSP1Recipient, + bytes lsp1Data +) internal nonpayable; +``` + +Attempt to notify the token receiver `to` about the `amount` tokens being received. +This is done by calling its [`universalReceiver`](#universalreceiver) function with the `_TYPEID_LSP7_TOKENSRECIPIENT` as typeId, if `to` is a contract that supports the LSP1 interface. +If `to` is is an EOA or a contract that does not support the LSP1 interface, the behaviour will depend on the `allowNonLSP1Recipient` boolean flag. + +- if `allowNonLSP1Recipient` is set to `true`, nothing will happen and no notification will be sent. + +- if `allowNonLSP1Recipient` is set to `false, the transaction will revert. + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | --------------------------------------------------------------------------------------------------- | +| `to` | `address` | The address to call the {universalReceiver} function on. | +| `allowNonLSP1Recipient` | `bool` | a boolean that describe if transfer to a `to` address that does not support LSP1 is allowed or not. | +| `lsp1Data` | `bytes` | the data to be sent to the `to` address in the `universalReceiver(...)` call. | + +
+ +## Events + +### AuthorizedOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizedoperator) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Event signature: `AuthorizedOperator(address,address,uint256)` +- Event topic hash: `0xd66aff874162a96578e919097b6f6d153dfd89a5cec41bb331fdb0c4aec16e2c` + +::: + +```solidity +event AuthorizedOperator(address indexed operator, address indexed tokenOwner, uint256 indexed amount); +``` + +Emitted when `tokenOwner` enables `operator` for `tokenId`. + +#### Parameters + +| Name | Type | Description | +| -------------------------- | :-------: | ----------------------------------------------------------------------- | +| `operator` **`indexed`** | `address` | The address authorized as an operator | +| `tokenOwner` **`indexed`** | `address` | The token owner | +| `amount` **`indexed`** | `uint256` | The amount of tokens `operator` address has access to from `tokenOwner` | + +
+ +### DataChanged + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#datachanged) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Event signature: `DataChanged(bytes32,bytes)` +- Event topic hash: `0xece574603820d07bc9b91f2a932baadf4628aabcb8afba49776529c14a6104b2` + +::: + +```solidity +event DataChanged(bytes32 indexed dataKey, bytes dataValue); +``` + +_Emitted when data at a key is changed_ + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ------------------------------------ | +| `dataKey` **`indexed`** | `bytes32` | The data key which data value is set | +| `dataValue` | `bytes` | The data value to set | + +
+ +### OwnershipTransferred + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#ownershiptransferred) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Event signature: `OwnershipTransferred(address,address)` +- Event topic hash: `0x8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0` + +::: + +```solidity +event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); +``` + +#### Parameters + +| Name | Type | Description | +| ----------------------------- | :-------: | ----------- | +| `previousOwner` **`indexed`** | `address` | - | +| `newOwner` **`indexed`** | `address` | - | + +
+ +### RevokedOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#revokedoperator) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Event signature: `RevokedOperator(address,address)` +- Event topic hash: `0x50546e66e5f44d728365dc3908c63bc5cfeeab470722c1677e3073a6ac294aa1` + +::: + +```solidity +event RevokedOperator(address indexed operator, address indexed tokenOwner); +``` + +Emitted when `tokenOwner` disables `operator` for `tokenId`. + +#### Parameters + +| Name | Type | Description | +| -------------------------- | :-------: | ---------------------------------- | +| `operator` **`indexed`** | `address` | The address revoked from operating | +| `tokenOwner` **`indexed`** | `address` | The token owner | + +
+ +### Transfer + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transfer) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Event signature: `Transfer(address,address,address,uint256,bool,bytes)` +- Event topic hash: `0x3997e418d2cef0b3b0e907b1e39605c3f7d32dbd061e82ea5b4a770d46a160a6` + +::: + +```solidity +event Transfer(address indexed operator, address indexed from, address indexed to, uint256 amount, bool allowNonLSP1Recipient, bytes data); +``` + +Emitted when `tokenId` token is transferred from `from` to `to`. + +#### Parameters + +| Name | Type | Description | +| ------------------------ | :-------: | ---------------------------------------------------------------------------------------------------------------------------- | +| `operator` **`indexed`** | `address` | The address of operator sending tokens | +| `from` **`indexed`** | `address` | The address which tokens are sent | +| `to` **`indexed`** | `address` | The receiving address | +| `amount` | `uint256` | The amount of tokens transferred. | +| `allowNonLSP1Recipient` | `bool` | When set to TRUE, `to` may be any address but when set to FALSE `to` must be a contract that supports LSP1 UniversalReceiver | +| `data` | `bytes` | Additional data the caller wants included in the emitted event, and sent in the hooks to `from` and `to` addresses | + +
+ +## Errors + +### ERC725Y_DataKeysValuesEmptyArray + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_datakeysvaluesemptyarray) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `ERC725Y_DataKeysValuesEmptyArray()` +- Error hash: `0x97da5f95` + +::: + +```solidity +error ERC725Y_DataKeysValuesEmptyArray(); +``` + +reverts when one of the array parameter provided to `setDataBatch` is an empty array + +
+ +### ERC725Y_DataKeysValuesLengthMismatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_datakeysvalueslengthmismatch) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `ERC725Y_DataKeysValuesLengthMismatch()` +- Error hash: `0x3bcc8979` + +::: + +```solidity +error ERC725Y_DataKeysValuesLengthMismatch(); +``` + +reverts when there is not the same number of elements in the lists of data keys and data values when calling setDataBatch. + +
+ +### ERC725Y_MsgValueDisallowed + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_msgvaluedisallowed) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `ERC725Y_MsgValueDisallowed()` +- Error hash: `0xf36ba737` + +::: + +```solidity +error ERC725Y_MsgValueDisallowed(); +``` + +reverts when sending value to the `setData(..)` functions + +
+ +### LSP4TokenNameNotEditable + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp4tokennamenoteditable) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `LSP4TokenNameNotEditable()` +- Error hash: `0x85c169bd` + +::: + +```solidity +error LSP4TokenNameNotEditable(); +``` + +Reverts when trying to edit the data key `LSP4TokenName` after the digital asset contract has been deployed. The `LSP4TokenName` data key is located inside the ERC725Y Data key-value store of the digital asset contract. It can be set only once inside the constructor/initializer when the digital asset contract is being deployed. + +
+ +### LSP4TokenSymbolNotEditable + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp4tokensymbolnoteditable) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `LSP4TokenSymbolNotEditable()` +- Error hash: `0x76755b38` + +::: + +```solidity +error LSP4TokenSymbolNotEditable(); +``` + +Reverts when trying to edit the data key `LSP4TokenSymbol` after the digital asset contract has been deployed. The `LSP4TokenSymbol` data key is located inside the ERC725Y Data key-value store of the digital asset contract. It can be set only once inside the constructor/initializer when the digital asset contract is being deployed. + +
+ +### LSP7AmountExceedsAuthorizedAmount + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7amountexceedsauthorizedamount) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `LSP7AmountExceedsAuthorizedAmount(address,uint256,address,uint256)` +- Error hash: `0xf3a6b691` + +::: + +```solidity +error LSP7AmountExceedsAuthorizedAmount( + address tokenOwner, + uint256 authorizedAmount, + address operator, + uint256 amount +); +``` + +reverts when `operator` of `tokenOwner` send an `amount` of tokens larger than the `authorizedAmount`. + +#### Parameters + +| Name | Type | Description | +| ------------------ | :-------: | ----------- | +| `tokenOwner` | `address` | - | +| `authorizedAmount` | `uint256` | - | +| `operator` | `address` | - | +| `amount` | `uint256` | - | + +
+ +### LSP7AmountExceedsBalance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7amountexceedsbalance) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `LSP7AmountExceedsBalance(uint256,address,uint256)` +- Error hash: `0x08d47949` + +::: + +```solidity +error LSP7AmountExceedsBalance( + uint256 balance, + address tokenOwner, + uint256 amount +); +``` + +reverts when sending an `amount` of tokens larger than the current `balance` of the `tokenOwner`. + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | ----------- | +| `balance` | `uint256` | - | +| `tokenOwner` | `address` | - | +| `amount` | `uint256` | - | + +
+ +### LSP7CannotSendToSelf + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotsendtoself) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `LSP7CannotSendToSelf()` +- Error hash: `0xb9afb000` + +::: + +```solidity +error LSP7CannotSendToSelf(); +``` + +reverts when specifying the same address for `from` or `to` in a token transfer. + +
+ +### LSP7CannotSendWithAddressZero + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotsendwithaddresszero) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `LSP7CannotSendWithAddressZero()` +- Error hash: `0xd2d5ec30` + +::: + +```solidity +error LSP7CannotSendWithAddressZero(); +``` + +reverts when trying to: + +- mint tokens to the zero address. + +- burn tokens from the zero address. + +- transfer tokens from or to the zero address. + +
+ +### LSP7CannotUseAddressZeroAsOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotuseaddresszeroasoperator) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `LSP7CannotUseAddressZeroAsOperator()` +- Error hash: `0x6355e766` + +::: + +```solidity +error LSP7CannotUseAddressZeroAsOperator(); +``` + +reverts when trying to set the zero address as an operator. + +
+ +### LSP7DecreasedAllowanceBelowZero + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7decreasedallowancebelowzero) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `LSP7DecreasedAllowanceBelowZero()` +- Error hash: `0x0ef76c35` + +::: + +```solidity +error LSP7DecreasedAllowanceBelowZero(); +``` + +Reverts when trying to decrease an operator's allowance to more than its current allowance. + +
+ +### LSP7InvalidTransferBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7invalidtransferbatch) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `LSP7InvalidTransferBatch()` +- Error hash: `0x263eee8d` + +::: + +```solidity +error LSP7InvalidTransferBatch(); +``` + +reverts when the array parameters used in [`transferBatch`](#transferbatch) have different lengths. + +
+ +### LSP7NotifyTokenReceiverContractMissingLSP1Interface + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7notifytokenreceivercontractmissinglsp1interface) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `LSP7NotifyTokenReceiverContractMissingLSP1Interface(address)` +- Error hash: `0xa608fbb6` + +::: + +```solidity +error LSP7NotifyTokenReceiverContractMissingLSP1Interface( + address tokenReceiver +); +``` + +reverts if the `tokenReceiver` does not implement LSP1 when minting or transferring tokens with `bool allowNonLSP1Recipient` set as `false`. + +#### Parameters + +| Name | Type | Description | +| --------------- | :-------: | ----------- | +| `tokenReceiver` | `address` | - | + +
+ +### LSP7NotifyTokenReceiverIsEOA + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7notifytokenreceiveriseoa) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `LSP7NotifyTokenReceiverIsEOA(address)` +- Error hash: `0x26c247f4` + +::: + +```solidity +error LSP7NotifyTokenReceiverIsEOA(address tokenReceiver); +``` + +reverts if the `tokenReceiver` is an EOA when minting or transferring tokens with `bool allowNonLSP1Recipient` set as `false`. + +#### Parameters + +| Name | Type | Description | +| --------------- | :-------: | ----------- | +| `tokenReceiver` | `address` | - | + +
+ +### LSP7TokenOwnerCannotBeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7tokenownercannotbeoperator) +- Solidity implementation: [`LSP7Burnable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol) +- Error signature: `LSP7TokenOwnerCannotBeOperator()` +- Error hash: `0xdab75047` + +::: + +```solidity +error LSP7TokenOwnerCannotBeOperator(); +``` + +reverts when trying to authorize or revoke the token's owner as an operator. + +
diff --git a/docs/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.md b/docs/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.md new file mode 100644 index 000000000..398e0acf2 --- /dev/null +++ b/docs/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.md @@ -0,0 +1,1353 @@ + + + +# LSP7CappedSupply + +:::info Standard Specifications + +[`LSP-7-DigitalAsset`](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md) + +::: +:::info Solidity implementation + +[`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) + +::: + +LSP7 token extension to add a max token supply cap. + +## Public Methods + +Public methods are accessible externally from users, allowing interaction with this function from dApps or other smart contracts. +When marked as 'public', a method can be called both externally and internally, on the other hand, when marked as 'external', a method can only be called externally. + +### authorizeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizeoperator) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `authorizeOperator(address,uint256)` +- Function selector: `0x47980aa3` + +::: + +:::danger + +To avoid front-running and Allowance Double-Spend Exploit when increasing or decreasing the authorized amount of an operator, it is advised to: 1. either call {revokeOperator} first, and then re-call {authorizeOperator} with the new amount. 2. or use the non-standard functions {increaseAllowance} or {decreaseAllowance}. For more information, see: https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/ + +::: + +```solidity +function authorizeOperator( + address operator, + uint256 amount +) external nonpayable; +``` + +Sets an `amount` of tokens that an `operator` has access from the caller's balance (allowance). See [`authorizedAmountFor`](#authorizedamountfor). + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ------------------------------------------------------ | +| `operator` | `address` | The address to authorize as an operator. | +| `amount` | `uint256` | The allowance amount of tokens operator has access to. | + +
+ +### authorizedAmountFor + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizedamountfor) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `authorizedAmountFor(address,address)` +- Function selector: `0x65aeaa95` + +::: + +```solidity +function authorizedAmountFor( + address operator, + address tokenOwner +) external view returns (uint256); +``` + +Get the amount of tokens `operator` address has access to from `tokenOwner`. Operators can send and burn tokens on behalf of their owners. + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | ---------------------------------------------------------- | +| `operator` | `address` | The operator's address to query the authorized amount for. | +| `tokenOwner` | `address` | The token owner that `operator` has allowance on. | + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | --------------------------------------------------------------------------------------- | +| `0` | `uint256` | The amount of tokens the `operator`'s address has access on the `tokenOwner`'s balance. | + +
+ +### balanceOf + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#balanceof) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `balanceOf(address)` +- Function selector: `0x70a08231` + +::: + +```solidity +function balanceOf(address tokenOwner) external view returns (uint256); +``` + +Get the number of tokens owned by `tokenOwner`. If the token is divisible (the [`decimals`](#decimals) function returns `18`), the amount returned should be divided by 1e18 to get a better picture of the actual balance of the `tokenOwner`. _Example:_ `balanceOf(someAddress) -> 42_000_000_000_000_000_000 / 1e18 = 42 tokens` + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | --------------------------------------------------------- | +| `tokenOwner` | `address` | The address of the token holder to query the balance for. | + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ------------------------------------------- | +| `0` | `uint256` | The amount of tokens owned by `tokenOwner`. | + +
+ +### decimals + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#decimals) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `decimals()` +- Function selector: `0x313ce567` + +::: + +```solidity +function decimals() external view returns (uint8); +``` + +Returns the number of decimals used to get its user representation. If the asset contract has been set to be non-divisible via the `isNonDivisible_` parameter in the `constructor`, the decimals returned wiil be `0`. Otherwise `18` is the common value. + +#### Returns + +| Name | Type | Description | +| ---- | :-----: | ----------------------------------------------------------------------- | +| `0` | `uint8` | the number of decimals. If `0` is returned, the asset is non-divisible. | + +
+ +### decreaseAllowance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#decreaseallowance) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `decreaseAllowance(address,uint256)` +- Function selector: `0xa457c2d7` + +::: + +:::info + +This is a non-standard function, not part of the LSP7 standard interface. It has been added in the LSP7 contract implementation so that it can be used as a prevention mechanism against the double spending allowance vulnerability. + +::: + +```solidity +function decreaseAllowance( + address operator, + uint256 substractedAmount +) external nonpayable; +``` + +_Decrease the allowance of `operator` by -`substractedAmount`_ + +Atomically decreases the allowance granted to `operator` by the caller. This is an alternative approach to [`authorizeOperator`](#authorizeoperator) that can be used as a mitigation for the double spending allowance problem. + +
+ +**Requirements:** + +- `operator` cannot be the zero address. +- `operator` must have allowance for the caller of at least `substractedAmount`. + +
+ +
+ +**Emitted events:** + +- [`AuthorizedOperator`](#authorizedoperator) event indicating the updated allowance after decreasing it. +- [`RevokeOperator`](#revokeoperator) event if `substractedAmount` is the full allowance, indicating `operator` does not have any alauthorizedAmountForlowance left for `msg.sender`. + +
+ +#### Parameters + +| Name | Type | Description | +| ------------------- | :-------: | ------------------------------------------------------ | +| `operator` | `address` | the operator to decrease allowance for `msg.sender` | +| `substractedAmount` | `uint256` | the amount to decrease by in the operator's allowance. | + +
+ +### getData + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#getdata) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `getData(bytes32)` +- Function selector: `0x54f6127f` + +::: + +```solidity +function getData(bytes32 dataKey) external view returns (bytes dataValue); +``` + +_Gets singular data at a given `dataKey`_ + +#### Parameters + +| Name | Type | Description | +| --------- | :-------: | ------------------------------- | +| `dataKey` | `bytes32` | The key which value to retrieve | + +#### Returns + +| Name | Type | Description | +| ----------- | :-----: | -------------------------- | +| `dataValue` | `bytes` | The data stored at the key | + +
+ +### getDataBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#getdatabatch) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `getDataBatch(bytes32[])` +- Function selector: `0xdedff9c6` + +::: + +```solidity +function getDataBatch( + bytes32[] dataKeys +) external view returns (bytes[] dataValues); +``` + +_Gets array of data for multiple given keys_ + +#### Parameters + +| Name | Type | Description | +| ---------- | :---------: | ------------------------------------------ | +| `dataKeys` | `bytes32[]` | The array of keys which values to retrieve | + +#### Returns + +| Name | Type | Description | +| ------------ | :-------: | ----------------------------------------- | +| `dataValues` | `bytes[]` | The array of data stored at multiple keys | + +
+ +### increaseAllowance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#increaseallowance) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `increaseAllowance(address,uint256)` +- Function selector: `0x39509351` + +::: + +:::info + +This is a non-standard function, not part of the LSP7 standard interface. It has been added in the LSP7 contract implementation so that it can be used as a prevention mechanism against double spending allowance vulnerability. + +::: + +```solidity +function increaseAllowance( + address operator, + uint256 addedAmount +) external nonpayable; +``` + +_Increase the allowance of `operator` by +`addedAmount`_ + +Atomically increases the allowance granted to `operator` by the caller. This is an alternative approach to [`authorizeOperator`](#authorizeoperator) that can be used as a mitigation for the double spending allowance problem. + +
+ +**Requirements:** + +- `operator` cannot be the same address as `msg.sender` +- `operator` cannot be the zero address. + +
+ +
+ +**Emitted events:** + +- [`AuthorizedOperator`](#authorizedoperator) indicating the updated allowance + +
+ +#### Parameters + +| Name | Type | Description | +| ------------- | :-------: | ----------------------------------------------------------------------- | +| `operator` | `address` | the operator to increase the allowance for `msg.sender` | +| `addedAmount` | `uint256` | the additional amount to add on top of the current operator's allowance | + +
+ +### owner + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#owner) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `owner()` +- Function selector: `0x8da5cb5b` + +::: + +```solidity +function owner() external view returns (address); +``` + +Returns the address of the current owner. + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ----------- | +| `0` | `address` | - | + +
+ +### renounceOwnership + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#renounceownership) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `renounceOwnership()` +- Function selector: `0x715018a6` + +::: + +```solidity +function renounceOwnership() external nonpayable; +``` + +Leaves the contract without owner. It will not be possible to call `onlyOwner` functions anymore. Can only be called by the current owner. NOTE: Renouncing ownership will leave the contract without an owner, thereby removing any functionality that is only available to the owner. + +
+ +### revokeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#revokeoperator) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `revokeOperator(address)` +- Function selector: `0xfad8b32a` + +::: + +```solidity +function revokeOperator(address operator) external nonpayable; +``` + +Removes the `operator` address as an operator of callers tokens, disallowing it to send any amount of tokens on behalf of the token owner (the caller of the function `msg.sender`). See also [`authorizedAmountFor`](#authorizedamountfor). + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ------------------------------------- | +| `operator` | `address` | The address to revoke as an operator. | + +
+ +### setData + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#setdata) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `setData(bytes32,bytes)` +- Function selector: `0x7f23690c` + +::: + +```solidity +function setData(bytes32 dataKey, bytes dataValue) external payable; +``` + +_Sets singular data for a given `dataKey`_ + +#### Parameters + +| Name | Type | Description | +| ----------- | :-------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dataKey` | `bytes32` | The key to retrieve stored value | +| `dataValue` | `bytes` | The value to set SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal 0. Emits a {DataChanged} event. | + +
+ +### setDataBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#setdatabatch) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `setDataBatch(bytes32[],bytes[])` +- Function selector: `0x97902421` + +::: + +```solidity +function setDataBatch(bytes32[] dataKeys, bytes[] dataValues) external payable; +``` + +Sets array of data for multiple given `dataKeys` SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal + +0. Emits a [`DataChanged`](#datachanged) event. + +#### Parameters + +| Name | Type | Description | +| ------------ | :---------: | ---------------------------------------- | +| `dataKeys` | `bytes32[]` | The array of data keys for values to set | +| `dataValues` | `bytes[]` | The array of values to set | + +
+ +### supportsInterface + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#supportsinterface) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `supportsInterface(bytes4)` +- Function selector: `0x01ffc9a7` + +::: + +```solidity +function supportsInterface(bytes4 interfaceId) external view returns (bool); +``` + +Returns true if this contract implements the interface defined by `interfaceId`. See the corresponding https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section] to learn more about how these ids are created. This function call must use less than 30 000 gas. + +#### Parameters + +| Name | Type | Description | +| ------------- | :------: | ----------- | +| `interfaceId` | `bytes4` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :----: | ----------- | +| `0` | `bool` | - | + +
+ +### tokenSupplyCap + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#tokensupplycap) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `tokenSupplyCap()` +- Function selector: `0x52058d8a` + +::: + +```solidity +function tokenSupplyCap() external view returns (uint256); +``` + +_The maximum supply amount of tokens allowed to exist is `_tokenSupplyCap`._ + +Get the maximum number of tokens that can exist to circulate. Once [`totalSupply`](#totalsupply) reaches reaches [`totalSuuplyCap`](#totalsuuplycap), it is not possible to mint more tokens. + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ------------------------------------------------------------ | +| `0` | `uint256` | The maximum number of tokens that can exist in the contract. | + +
+ +### totalSupply + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#totalsupply) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `totalSupply()` +- Function selector: `0x18160ddd` + +::: + +```solidity +function totalSupply() external view returns (uint256); +``` + +Returns the number of existing tokens that have been minted in this contract. + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ------------------------------ | +| `0` | `uint256` | The number of existing tokens. | + +
+ +### transfer + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transfer) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `transfer(address,address,uint256,bool,bytes)` +- Function selector: `0x760d9bba` + +::: + +```solidity +function transfer( + address from, + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) external nonpayable; +``` + +Transfers an `amount` of tokens from the `from` address to the `to` address and notify both sender and recipients via the LSP1 [`universalReceiver(...)`](#`universalreceiver) function. If the tokens are transferred by an operator on behalf of a token holder, the allowance for the operator will be decreased by `amount` once the token transfer has been completed (See [`authorizedAmountFor`](#authorizedamountfor)). + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address` | The sender address. | +| `to` | `address` | The recipient address. | +| `amount` | `uint256` | The amount of tokens to transfer. | +| `allowNonLSP1Recipient` | `bool` | When set to `true`, the `to` address CAN be any address. When set to `false`, the `to` address MUST be a contract that supports the LSP1 UniversalReceiver standard. | +| `data` | `bytes` | Any additional data the caller wants included in the emitted event, and sent in the hooks of the `from` and `to` addresses. | + +
+ +### transferBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transferbatch) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `transferBatch(address[],address[],uint256[],bool[],bytes[])` +- Function selector: `0x2d7667c9` + +::: + +```solidity +function transferBatch( + address[] from, + address[] to, + uint256[] amount, + bool[] allowNonLSP1Recipient, + bytes[] data +) external nonpayable; +``` + +Same as [`transfer(...)`](#`transfer) but transfer multiple tokens based on the arrays of `from`, `to`, `amount`. + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :---------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address[]` | An array of sending addresses. | +| `to` | `address[]` | An array of receiving addresses. | +| `amount` | `uint256[]` | An array of amount of tokens to transfer for each `from -> to` transfer. | +| `allowNonLSP1Recipient` | `bool[]` | For each transfer, when set to `true`, the `to` address CAN be any address. When set to `false`, the `to` address MUST be a contract that supports the LSP1 UniversalReceiver standard. | +| `data` | `bytes[]` | An array of additional data the caller wants included in the emitted event, and sent in the hooks to `from` and `to` addresses. | + +
+ +### transferOwnership + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transferownership) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Function signature: `transferOwnership(address)` +- Function selector: `0xf2fde38b` + +::: + +```solidity +function transferOwnership(address newOwner) external nonpayable; +``` + +Transfers ownership of the contract to a new account (`newOwner`). Can only be called by the current owner. + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ----------- | +| `newOwner` | `address` | - | + +
+ +## Internal Methods + +Any method labeled as `internal` serves as utility function within the contract. They can be used when writing solidity contracts that inherit from this contract. These methods can be extended or modified by overriding their internal behavior to suit specific needs. + +Internal functions cannot be called externally, whether from other smart contracts, dApp interfaces, or backend services. Their restricted accessibility ensures that they remain exclusively available within the context of the current contract, promoting controlled and encapsulated usage of these internal utilities. + +### \_checkOwner + +```solidity +function _checkOwner() internal view; +``` + +Throws if the sender is not the owner. + +
+ +### \_setOwner + +```solidity +function _setOwner(address newOwner) internal nonpayable; +``` + +Changes the owner if `newOwner` and oldOwner are different +This pattern is useful in inheritance. + +
+ +### \_getData + +```solidity +function _getData(bytes32 dataKey) internal view returns (bytes dataValue); +``` + +
+ +### \_setData + +```solidity +function _setData(bytes32 dataKey, bytes dataValue) internal nonpayable; +``` + +Save gas by emitting the [`DataChanged`](#datachanged) event with only the first 256 bytes of dataValue + +
+ +### \_updateOperator + +```solidity +function _updateOperator( + address tokenOwner, + address operator, + uint256 amount +) internal nonpayable; +``` + +Changes token `amount` the `operator` has access to from `tokenOwner` tokens. +If the amount is zero then the operator is being revoked, otherwise the operator amount is being modified. + +
+ +### \_mint + +```solidity +function _mint( + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) internal nonpayable; +``` + +Same as [`_mint`](#_mint) but allows to mint only if the [`totalSupply`](#totalsupply) does not exceed the [`tokenSupplyCap`](#tokensupplycap) +after `amount` of tokens have been minted. + +
+ +### \_burn + +:::tip Hint + +In dApps, you can know which address is burning tokens by listening for the `Transfer` event and filter with the zero address as `to`. + +::: + +```solidity +function _burn(address from, uint256 amount, bytes data) internal nonpayable; +``` + +Burns (= destroys) `amount` of tokens, decrease the `from` balance. This is done by sending them to the zero address. +Both the sender and recipient will be notified of the token transfer through the LSP1 [`universalReceiver`](#universalreceiver) +function, if they are contracts that support the LSP1 interface. Their `universalReceiver` function will receive +all the parameters in the calldata packed encoded. +Any logic in the [`_beforeTokenTransfer`](#_beforetokentransfer) function will run before updating the balances. + +
+ +**Emitted events:** + +- [`Transfer`](#transfer) event with `address(0)` as the `to` address + +
+ +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address` | the address to burn tokens from its balance. | +| `amount` | `uint256` | the amount of tokens to burn. | +| `data` | `bytes` | Additional data the caller wants included in the emitted event, and sent in the LSP1 hook to the `from` and `to` address. | + +
+ +### \_transfer + +```solidity +function _transfer( + address from, + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) internal nonpayable; +``` + +Transfer tokens from `from` to `to` by decreasing the balance of `from` by `-amount` and increasing the balance +of `to` by `+amount`. +Both the sender and recipient will be notified of the token transfer through the LSP1 [`universalReceiver`](#universalreceiver) +function, if they are contracts that support the LSP1 interface. Their `universalReceiver` function will receive +all the parameters in the calldata packed encoded. +Any logic in the [`_beforeTokenTransfer`](#_beforetokentransfer) function will run before updating the balances. + +
+ +**Emitted events:** + +- [`Transfer`](#transfer) event. + +
+ +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address` | the address to decrease the balance. | +| `to` | `address` | the address to increase the balance. | +| `amount` | `uint256` | the amount of tokens to transfer from `from` to `to`. | +| `allowNonLSP1Recipient` | `bool` | a boolean that describe if transfer to a `to` address that does not support LSP1 is allowed or not. | +| `data` | `bytes` | Additional data the caller wants included in the emitted event, and sent in the LSP1 hook to the `from` and `to` address. | + +
+ +### \_beforeTokenTransfer + +```solidity +function _beforeTokenTransfer( + address from, + address to, + uint256 amount +) internal nonpayable; +``` + +Hook that is called before any token transfer, including minting and burning. +Allows to run custom logic before updating balances and notifiying sender/recipient by overriding this function. + +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ------------------------------- | +| `from` | `address` | The sender address | +| `to` | `address` | The recipient address | +| `amount` | `uint256` | The amount of token to transfer | + +
+ +### \_notifyTokenSender + +```solidity +function _notifyTokenSender(address from, bytes lsp1Data) internal nonpayable; +``` + +Attempt to notify the token sender `from` about the `amount` of tokens being transferred. +This is done by calling its [`universalReceiver`](#universalreceiver) function with the `_TYPEID_LSP7_TOKENSSENDER` as typeId, if `from` is a contract that supports the LSP1 interface. +If `from` is an EOA or a contract that does not support the LSP1 interface, nothing will happen and no notification will be sent. + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | -------------------------------------------------------------------------- | +| `from` | `address` | The address to call the {universalReceiver} function on. | +| `lsp1Data` | `bytes` | the data to be sent to the `from` address in the `universalReceiver` call. | + +
+ +### \_notifyTokenReceiver + +```solidity +function _notifyTokenReceiver( + address to, + bool allowNonLSP1Recipient, + bytes lsp1Data +) internal nonpayable; +``` + +Attempt to notify the token receiver `to` about the `amount` tokens being received. +This is done by calling its [`universalReceiver`](#universalreceiver) function with the `_TYPEID_LSP7_TOKENSRECIPIENT` as typeId, if `to` is a contract that supports the LSP1 interface. +If `to` is is an EOA or a contract that does not support the LSP1 interface, the behaviour will depend on the `allowNonLSP1Recipient` boolean flag. + +- if `allowNonLSP1Recipient` is set to `true`, nothing will happen and no notification will be sent. + +- if `allowNonLSP1Recipient` is set to `false, the transaction will revert. + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | --------------------------------------------------------------------------------------------------- | +| `to` | `address` | The address to call the {universalReceiver} function on. | +| `allowNonLSP1Recipient` | `bool` | a boolean that describe if transfer to a `to` address that does not support LSP1 is allowed or not. | +| `lsp1Data` | `bytes` | the data to be sent to the `to` address in the `universalReceiver(...)` call. | + +
+ +## Events + +### AuthorizedOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizedoperator) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Event signature: `AuthorizedOperator(address,address,uint256)` +- Event topic hash: `0xd66aff874162a96578e919097b6f6d153dfd89a5cec41bb331fdb0c4aec16e2c` + +::: + +```solidity +event AuthorizedOperator(address indexed operator, address indexed tokenOwner, uint256 indexed amount); +``` + +Emitted when `tokenOwner` enables `operator` for `tokenId`. + +#### Parameters + +| Name | Type | Description | +| -------------------------- | :-------: | ----------------------------------------------------------------------- | +| `operator` **`indexed`** | `address` | The address authorized as an operator | +| `tokenOwner` **`indexed`** | `address` | The token owner | +| `amount` **`indexed`** | `uint256` | The amount of tokens `operator` address has access to from `tokenOwner` | + +
+ +### DataChanged + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#datachanged) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Event signature: `DataChanged(bytes32,bytes)` +- Event topic hash: `0xece574603820d07bc9b91f2a932baadf4628aabcb8afba49776529c14a6104b2` + +::: + +```solidity +event DataChanged(bytes32 indexed dataKey, bytes dataValue); +``` + +_Emitted when data at a key is changed_ + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ------------------------------------ | +| `dataKey` **`indexed`** | `bytes32` | The data key which data value is set | +| `dataValue` | `bytes` | The data value to set | + +
+ +### OwnershipTransferred + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#ownershiptransferred) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Event signature: `OwnershipTransferred(address,address)` +- Event topic hash: `0x8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0` + +::: + +```solidity +event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); +``` + +#### Parameters + +| Name | Type | Description | +| ----------------------------- | :-------: | ----------- | +| `previousOwner` **`indexed`** | `address` | - | +| `newOwner` **`indexed`** | `address` | - | + +
+ +### RevokedOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#revokedoperator) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Event signature: `RevokedOperator(address,address)` +- Event topic hash: `0x50546e66e5f44d728365dc3908c63bc5cfeeab470722c1677e3073a6ac294aa1` + +::: + +```solidity +event RevokedOperator(address indexed operator, address indexed tokenOwner); +``` + +Emitted when `tokenOwner` disables `operator` for `tokenId`. + +#### Parameters + +| Name | Type | Description | +| -------------------------- | :-------: | ---------------------------------- | +| `operator` **`indexed`** | `address` | The address revoked from operating | +| `tokenOwner` **`indexed`** | `address` | The token owner | + +
+ +### Transfer + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transfer) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Event signature: `Transfer(address,address,address,uint256,bool,bytes)` +- Event topic hash: `0x3997e418d2cef0b3b0e907b1e39605c3f7d32dbd061e82ea5b4a770d46a160a6` + +::: + +```solidity +event Transfer(address indexed operator, address indexed from, address indexed to, uint256 amount, bool allowNonLSP1Recipient, bytes data); +``` + +Emitted when `tokenId` token is transferred from `from` to `to`. + +#### Parameters + +| Name | Type | Description | +| ------------------------ | :-------: | ---------------------------------------------------------------------------------------------------------------------------- | +| `operator` **`indexed`** | `address` | The address of operator sending tokens | +| `from` **`indexed`** | `address` | The address which tokens are sent | +| `to` **`indexed`** | `address` | The receiving address | +| `amount` | `uint256` | The amount of tokens transferred. | +| `allowNonLSP1Recipient` | `bool` | When set to TRUE, `to` may be any address but when set to FALSE `to` must be a contract that supports LSP1 UniversalReceiver | +| `data` | `bytes` | Additional data the caller wants included in the emitted event, and sent in the hooks to `from` and `to` addresses | + +
+ +## Errors + +### ERC725Y_DataKeysValuesEmptyArray + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_datakeysvaluesemptyarray) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `ERC725Y_DataKeysValuesEmptyArray()` +- Error hash: `0x97da5f95` + +::: + +```solidity +error ERC725Y_DataKeysValuesEmptyArray(); +``` + +reverts when one of the array parameter provided to `setDataBatch` is an empty array + +
+ +### ERC725Y_DataKeysValuesLengthMismatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_datakeysvalueslengthmismatch) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `ERC725Y_DataKeysValuesLengthMismatch()` +- Error hash: `0x3bcc8979` + +::: + +```solidity +error ERC725Y_DataKeysValuesLengthMismatch(); +``` + +reverts when there is not the same number of elements in the lists of data keys and data values when calling setDataBatch. + +
+ +### ERC725Y_MsgValueDisallowed + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_msgvaluedisallowed) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `ERC725Y_MsgValueDisallowed()` +- Error hash: `0xf36ba737` + +::: + +```solidity +error ERC725Y_MsgValueDisallowed(); +``` + +reverts when sending value to the `setData(..)` functions + +
+ +### LSP4TokenNameNotEditable + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp4tokennamenoteditable) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP4TokenNameNotEditable()` +- Error hash: `0x85c169bd` + +::: + +```solidity +error LSP4TokenNameNotEditable(); +``` + +Reverts when trying to edit the data key `LSP4TokenName` after the digital asset contract has been deployed. The `LSP4TokenName` data key is located inside the ERC725Y Data key-value store of the digital asset contract. It can be set only once inside the constructor/initializer when the digital asset contract is being deployed. + +
+ +### LSP4TokenSymbolNotEditable + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp4tokensymbolnoteditable) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP4TokenSymbolNotEditable()` +- Error hash: `0x76755b38` + +::: + +```solidity +error LSP4TokenSymbolNotEditable(); +``` + +Reverts when trying to edit the data key `LSP4TokenSymbol` after the digital asset contract has been deployed. The `LSP4TokenSymbol` data key is located inside the ERC725Y Data key-value store of the digital asset contract. It can be set only once inside the constructor/initializer when the digital asset contract is being deployed. + +
+ +### LSP7AmountExceedsAuthorizedAmount + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7amountexceedsauthorizedamount) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP7AmountExceedsAuthorizedAmount(address,uint256,address,uint256)` +- Error hash: `0xf3a6b691` + +::: + +```solidity +error LSP7AmountExceedsAuthorizedAmount( + address tokenOwner, + uint256 authorizedAmount, + address operator, + uint256 amount +); +``` + +reverts when `operator` of `tokenOwner` send an `amount` of tokens larger than the `authorizedAmount`. + +#### Parameters + +| Name | Type | Description | +| ------------------ | :-------: | ----------- | +| `tokenOwner` | `address` | - | +| `authorizedAmount` | `uint256` | - | +| `operator` | `address` | - | +| `amount` | `uint256` | - | + +
+ +### LSP7AmountExceedsBalance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7amountexceedsbalance) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP7AmountExceedsBalance(uint256,address,uint256)` +- Error hash: `0x08d47949` + +::: + +```solidity +error LSP7AmountExceedsBalance( + uint256 balance, + address tokenOwner, + uint256 amount +); +``` + +reverts when sending an `amount` of tokens larger than the current `balance` of the `tokenOwner`. + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | ----------- | +| `balance` | `uint256` | - | +| `tokenOwner` | `address` | - | +| `amount` | `uint256` | - | + +
+ +### LSP7CannotSendToSelf + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotsendtoself) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP7CannotSendToSelf()` +- Error hash: `0xb9afb000` + +::: + +```solidity +error LSP7CannotSendToSelf(); +``` + +reverts when specifying the same address for `from` or `to` in a token transfer. + +
+ +### LSP7CannotSendWithAddressZero + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotsendwithaddresszero) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP7CannotSendWithAddressZero()` +- Error hash: `0xd2d5ec30` + +::: + +```solidity +error LSP7CannotSendWithAddressZero(); +``` + +reverts when trying to: + +- mint tokens to the zero address. + +- burn tokens from the zero address. + +- transfer tokens from or to the zero address. + +
+ +### LSP7CannotUseAddressZeroAsOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotuseaddresszeroasoperator) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP7CannotUseAddressZeroAsOperator()` +- Error hash: `0x6355e766` + +::: + +```solidity +error LSP7CannotUseAddressZeroAsOperator(); +``` + +reverts when trying to set the zero address as an operator. + +
+ +### LSP7CappedSupplyCannotMintOverCap + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cappedsupplycannotmintovercap) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP7CappedSupplyCannotMintOverCap()` +- Error hash: `0xeacbf0d1` + +::: + +```solidity +error LSP7CappedSupplyCannotMintOverCap(); +``` + +_Cannot mint anymore as total supply reached the maximum cap._ + +Reverts when trying to mint tokens but the [`totalSupply`](#totalsupply) has reached the maximum [`tokenSupplyCap`](#tokensupplycap). + +
+ +### LSP7CappedSupplyRequired + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cappedsupplyrequired) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP7CappedSupplyRequired()` +- Error hash: `0xacf1d8c5` + +::: + +```solidity +error LSP7CappedSupplyRequired(); +``` + +_The `tokenSupplyCap` must be set and cannot be `0`._ + +Reverts when setting `0` for the [`tokenSupplyCap`](#tokensupplycap). The max token supply MUST be set to a number greater than 0. + +
+ +### LSP7DecreasedAllowanceBelowZero + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7decreasedallowancebelowzero) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP7DecreasedAllowanceBelowZero()` +- Error hash: `0x0ef76c35` + +::: + +```solidity +error LSP7DecreasedAllowanceBelowZero(); +``` + +Reverts when trying to decrease an operator's allowance to more than its current allowance. + +
+ +### LSP7InvalidTransferBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7invalidtransferbatch) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP7InvalidTransferBatch()` +- Error hash: `0x263eee8d` + +::: + +```solidity +error LSP7InvalidTransferBatch(); +``` + +reverts when the array parameters used in [`transferBatch`](#transferbatch) have different lengths. + +
+ +### LSP7NotifyTokenReceiverContractMissingLSP1Interface + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7notifytokenreceivercontractmissinglsp1interface) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP7NotifyTokenReceiverContractMissingLSP1Interface(address)` +- Error hash: `0xa608fbb6` + +::: + +```solidity +error LSP7NotifyTokenReceiverContractMissingLSP1Interface( + address tokenReceiver +); +``` + +reverts if the `tokenReceiver` does not implement LSP1 when minting or transferring tokens with `bool allowNonLSP1Recipient` set as `false`. + +#### Parameters + +| Name | Type | Description | +| --------------- | :-------: | ----------- | +| `tokenReceiver` | `address` | - | + +
+ +### LSP7NotifyTokenReceiverIsEOA + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7notifytokenreceiveriseoa) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP7NotifyTokenReceiverIsEOA(address)` +- Error hash: `0x26c247f4` + +::: + +```solidity +error LSP7NotifyTokenReceiverIsEOA(address tokenReceiver); +``` + +reverts if the `tokenReceiver` is an EOA when minting or transferring tokens with `bool allowNonLSP1Recipient` set as `false`. + +#### Parameters + +| Name | Type | Description | +| --------------- | :-------: | ----------- | +| `tokenReceiver` | `address` | - | + +
+ +### LSP7TokenOwnerCannotBeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7tokenownercannotbeoperator) +- Solidity implementation: [`LSP7CappedSupply.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol) +- Error signature: `LSP7TokenOwnerCannotBeOperator()` +- Error hash: `0xdab75047` + +::: + +```solidity +error LSP7TokenOwnerCannotBeOperator(); +``` + +reverts when trying to authorize or revoke the token's owner as an operator. + +
diff --git a/docs/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.md b/docs/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.md new file mode 100644 index 000000000..fbb443eb1 --- /dev/null +++ b/docs/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.md @@ -0,0 +1,1446 @@ + + + +# LSP7CompatibleERC20 + +:::info Standard Specifications + +[`LSP-7-DigitalAsset`](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md) + +::: +:::info Solidity implementation + +[`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) + +::: + +LSP7 extension, for compatibility for clients / tools that expect ERC20. + +## Public Methods + +Public methods are accessible externally from users, allowing interaction with this function from dApps or other smart contracts. +When marked as 'public', a method can be called both externally and internally, on the other hand, when marked as 'external', a method can only be called externally. + +### allowance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#allowance) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `allowance(address,address)` +- Function selector: `0xdd62ed3e` + +::: + +```solidity +function allowance( + address tokenOwner, + address operator +) external view returns (uint256); +``` + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | ----------- | +| `tokenOwner` | `address` | - | +| `operator` | `address` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ----------- | +| `0` | `uint256` | - | + +
+ +### approve + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#approve) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `approve(address,uint256)` +- Function selector: `0x095ea7b3` + +::: + +```solidity +function approve( + address operator, + uint256 amount +) external nonpayable returns (bool); +``` + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ----------- | +| `operator` | `address` | - | +| `amount` | `uint256` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :----: | ----------- | +| `0` | `bool` | - | + +
+ +### authorizeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizeoperator) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `authorizeOperator(address,uint256)` +- Function selector: `0x47980aa3` + +::: + +:::danger + +To avoid front-running and Allowance Double-Spend Exploit when increasing or decreasing the authorized amount of an operator, it is advised to: 1. either call {revokeOperator} first, and then re-call {authorizeOperator} with the new amount. 2. or use the non-standard functions {increaseAllowance} or {decreaseAllowance}. For more information, see: https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/ + +::: + +```solidity +function authorizeOperator( + address operator, + uint256 amount +) external nonpayable; +``` + +Sets an `amount` of tokens that an `operator` has access from the caller's balance (allowance). See [`authorizedAmountFor`](#authorizedamountfor). + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ------------------------------------------------------ | +| `operator` | `address` | The address to authorize as an operator. | +| `amount` | `uint256` | The allowance amount of tokens operator has access to. | + +
+ +### authorizedAmountFor + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizedamountfor) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `authorizedAmountFor(address,address)` +- Function selector: `0x65aeaa95` + +::: + +```solidity +function authorizedAmountFor( + address operator, + address tokenOwner +) external view returns (uint256); +``` + +Get the amount of tokens `operator` address has access to from `tokenOwner`. Operators can send and burn tokens on behalf of their owners. + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | ---------------------------------------------------------- | +| `operator` | `address` | The operator's address to query the authorized amount for. | +| `tokenOwner` | `address` | The token owner that `operator` has allowance on. | + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | --------------------------------------------------------------------------------------- | +| `0` | `uint256` | The amount of tokens the `operator`'s address has access on the `tokenOwner`'s balance. | + +
+ +### balanceOf + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#balanceof) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `balanceOf(address)` +- Function selector: `0x70a08231` + +::: + +```solidity +function balanceOf(address tokenOwner) external view returns (uint256); +``` + +Get the number of tokens owned by `tokenOwner`. If the token is divisible (the [`decimals`](#decimals) function returns `18`), the amount returned should be divided by 1e18 to get a better picture of the actual balance of the `tokenOwner`. _Example:_ `balanceOf(someAddress) -> 42_000_000_000_000_000_000 / 1e18 = 42 tokens` + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | --------------------------------------------------------- | +| `tokenOwner` | `address` | The address of the token holder to query the balance for. | + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ------------------------------------------- | +| `0` | `uint256` | The amount of tokens owned by `tokenOwner`. | + +
+ +### decimals + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#decimals) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `decimals()` +- Function selector: `0x313ce567` + +::: + +```solidity +function decimals() external view returns (uint8); +``` + +Returns the number of decimals used to get its user representation. If the asset contract has been set to be non-divisible via the `isNonDivisible_` parameter in the `constructor`, the decimals returned wiil be `0`. Otherwise `18` is the common value. + +#### Returns + +| Name | Type | Description | +| ---- | :-----: | ----------------------------------------------------------------------- | +| `0` | `uint8` | the number of decimals. If `0` is returned, the asset is non-divisible. | + +
+ +### decreaseAllowance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#decreaseallowance) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `decreaseAllowance(address,uint256)` +- Function selector: `0xa457c2d7` + +::: + +:::info + +This is a non-standard function, not part of the LSP7 standard interface. It has been added in the LSP7 contract implementation so that it can be used as a prevention mechanism against the double spending allowance vulnerability. + +::: + +```solidity +function decreaseAllowance( + address operator, + uint256 substractedAmount +) external nonpayable; +``` + +_Decrease the allowance of `operator` by -`substractedAmount`_ + +Atomically decreases the allowance granted to `operator` by the caller. This is an alternative approach to [`authorizeOperator`](#authorizeoperator) that can be used as a mitigation for the double spending allowance problem. + +
+ +**Requirements:** + +- `operator` cannot be the zero address. +- `operator` must have allowance for the caller of at least `substractedAmount`. + +
+ +
+ +**Emitted events:** + +- [`AuthorizedOperator`](#authorizedoperator) event indicating the updated allowance after decreasing it. +- [`RevokeOperator`](#revokeoperator) event if `substractedAmount` is the full allowance, indicating `operator` does not have any alauthorizedAmountForlowance left for `msg.sender`. + +
+ +#### Parameters + +| Name | Type | Description | +| ------------------- | :-------: | ------------------------------------------------------ | +| `operator` | `address` | the operator to decrease allowance for `msg.sender` | +| `substractedAmount` | `uint256` | the amount to decrease by in the operator's allowance. | + +
+ +### getData + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#getdata) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `getData(bytes32)` +- Function selector: `0x54f6127f` + +::: + +```solidity +function getData(bytes32 dataKey) external view returns (bytes dataValue); +``` + +_Gets singular data at a given `dataKey`_ + +#### Parameters + +| Name | Type | Description | +| --------- | :-------: | ------------------------------- | +| `dataKey` | `bytes32` | The key which value to retrieve | + +#### Returns + +| Name | Type | Description | +| ----------- | :-----: | -------------------------- | +| `dataValue` | `bytes` | The data stored at the key | + +
+ +### getDataBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#getdatabatch) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `getDataBatch(bytes32[])` +- Function selector: `0xdedff9c6` + +::: + +```solidity +function getDataBatch( + bytes32[] dataKeys +) external view returns (bytes[] dataValues); +``` + +_Gets array of data for multiple given keys_ + +#### Parameters + +| Name | Type | Description | +| ---------- | :---------: | ------------------------------------------ | +| `dataKeys` | `bytes32[]` | The array of keys which values to retrieve | + +#### Returns + +| Name | Type | Description | +| ------------ | :-------: | ----------------------------------------- | +| `dataValues` | `bytes[]` | The array of data stored at multiple keys | + +
+ +### increaseAllowance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#increaseallowance) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `increaseAllowance(address,uint256)` +- Function selector: `0x39509351` + +::: + +:::info + +This is a non-standard function, not part of the LSP7 standard interface. It has been added in the LSP7 contract implementation so that it can be used as a prevention mechanism against double spending allowance vulnerability. + +::: + +```solidity +function increaseAllowance( + address operator, + uint256 addedAmount +) external nonpayable; +``` + +_Increase the allowance of `operator` by +`addedAmount`_ + +Atomically increases the allowance granted to `operator` by the caller. This is an alternative approach to [`authorizeOperator`](#authorizeoperator) that can be used as a mitigation for the double spending allowance problem. + +
+ +**Requirements:** + +- `operator` cannot be the same address as `msg.sender` +- `operator` cannot be the zero address. + +
+ +
+ +**Emitted events:** + +- [`AuthorizedOperator`](#authorizedoperator) indicating the updated allowance + +
+ +#### Parameters + +| Name | Type | Description | +| ------------- | :-------: | ----------------------------------------------------------------------- | +| `operator` | `address` | the operator to increase the allowance for `msg.sender` | +| `addedAmount` | `uint256` | the additional amount to add on top of the current operator's allowance | + +
+ +### name + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#name) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `name()` +- Function selector: `0x06fdde03` + +::: + +```solidity +function name() external view returns (string); +``` + +Returns the name of the token. + +#### Returns + +| Name | Type | Description | +| ---- | :------: | --------------------- | +| `0` | `string` | The name of the token | + +
+ +### owner + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#owner) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `owner()` +- Function selector: `0x8da5cb5b` + +::: + +```solidity +function owner() external view returns (address); +``` + +Returns the address of the current owner. + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ----------- | +| `0` | `address` | - | + +
+ +### renounceOwnership + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#renounceownership) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `renounceOwnership()` +- Function selector: `0x715018a6` + +::: + +```solidity +function renounceOwnership() external nonpayable; +``` + +Leaves the contract without owner. It will not be possible to call `onlyOwner` functions anymore. Can only be called by the current owner. NOTE: Renouncing ownership will leave the contract without an owner, thereby removing any functionality that is only available to the owner. + +
+ +### revokeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#revokeoperator) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `revokeOperator(address)` +- Function selector: `0xfad8b32a` + +::: + +```solidity +function revokeOperator(address operator) external nonpayable; +``` + +Removes the `operator` address as an operator of callers tokens, disallowing it to send any amount of tokens on behalf of the token owner (the caller of the function `msg.sender`). See also [`authorizedAmountFor`](#authorizedamountfor). + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ------------------------------------- | +| `operator` | `address` | The address to revoke as an operator. | + +
+ +### setData + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#setdata) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `setData(bytes32,bytes)` +- Function selector: `0x7f23690c` + +::: + +```solidity +function setData(bytes32 dataKey, bytes dataValue) external payable; +``` + +_Sets singular data for a given `dataKey`_ + +#### Parameters + +| Name | Type | Description | +| ----------- | :-------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dataKey` | `bytes32` | The key to retrieve stored value | +| `dataValue` | `bytes` | The value to set SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal 0. Emits a {DataChanged} event. | + +
+ +### setDataBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#setdatabatch) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `setDataBatch(bytes32[],bytes[])` +- Function selector: `0x97902421` + +::: + +```solidity +function setDataBatch(bytes32[] dataKeys, bytes[] dataValues) external payable; +``` + +Sets array of data for multiple given `dataKeys` SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal + +0. Emits a [`DataChanged`](#datachanged) event. + +#### Parameters + +| Name | Type | Description | +| ------------ | :---------: | ---------------------------------------- | +| `dataKeys` | `bytes32[]` | The array of data keys for values to set | +| `dataValues` | `bytes[]` | The array of values to set | + +
+ +### supportsInterface + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#supportsinterface) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `supportsInterface(bytes4)` +- Function selector: `0x01ffc9a7` + +::: + +```solidity +function supportsInterface(bytes4 interfaceId) external view returns (bool); +``` + +Returns true if this contract implements the interface defined by `interfaceId`. See the corresponding https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section] to learn more about how these ids are created. This function call must use less than 30 000 gas. + +#### Parameters + +| Name | Type | Description | +| ------------- | :------: | ----------- | +| `interfaceId` | `bytes4` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :----: | ----------- | +| `0` | `bool` | - | + +
+ +### symbol + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#symbol) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `symbol()` +- Function selector: `0x95d89b41` + +::: + +```solidity +function symbol() external view returns (string); +``` + +Returns the symbol of the token, usually a shorter version of the name. + +#### Returns + +| Name | Type | Description | +| ---- | :------: | ----------------------- | +| `0` | `string` | The symbol of the token | + +
+ +### totalSupply + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#totalsupply) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `totalSupply()` +- Function selector: `0x18160ddd` + +::: + +```solidity +function totalSupply() external view returns (uint256); +``` + +Returns the number of existing tokens that have been minted in this contract. + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ------------------------------ | +| `0` | `uint256` | The number of existing tokens. | + +
+ +### transfer + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transfer) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `transfer(address,address,uint256,bool,bytes)` +- Function selector: `0x760d9bba` + +::: + +```solidity +function transfer( + address from, + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) external nonpayable; +``` + +Transfers an `amount` of tokens from the `from` address to the `to` address and notify both sender and recipients via the LSP1 [`universalReceiver(...)`](#`universalreceiver) function. If the tokens are transferred by an operator on behalf of a token holder, the allowance for the operator will be decreased by `amount` once the token transfer has been completed (See [`authorizedAmountFor`](#authorizedamountfor)). + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address` | The sender address. | +| `to` | `address` | The recipient address. | +| `amount` | `uint256` | The amount of tokens to transfer. | +| `allowNonLSP1Recipient` | `bool` | When set to `true`, the `to` address CAN be any address. When set to `false`, the `to` address MUST be a contract that supports the LSP1 UniversalReceiver standard. | +| `data` | `bytes` | Any additional data the caller wants included in the emitted event, and sent in the hooks of the `from` and `to` addresses. | + +
+ +### transfer + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transfer) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `transfer(address,uint256)` +- Function selector: `0xa9059cbb` + +::: + +:::info + +This function uses the `allowNonLSP1Recipient` parameter as `true` so that EOA and any contract can receive tokens. + +::: + +```solidity +function transfer( + address to, + uint256 amount +) external nonpayable returns (bool); +``` + +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ----------- | +| `to` | `address` | - | +| `amount` | `uint256` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :----: | ----------- | +| `0` | `bool` | - | + +
+ +### transferBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transferbatch) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `transferBatch(address[],address[],uint256[],bool[],bytes[])` +- Function selector: `0x2d7667c9` + +::: + +```solidity +function transferBatch( + address[] from, + address[] to, + uint256[] amount, + bool[] allowNonLSP1Recipient, + bytes[] data +) external nonpayable; +``` + +Same as [`transfer(...)`](#`transfer) but transfer multiple tokens based on the arrays of `from`, `to`, `amount`. + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :---------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address[]` | An array of sending addresses. | +| `to` | `address[]` | An array of receiving addresses. | +| `amount` | `uint256[]` | An array of amount of tokens to transfer for each `from -> to` transfer. | +| `allowNonLSP1Recipient` | `bool[]` | For each transfer, when set to `true`, the `to` address CAN be any address. When set to `false`, the `to` address MUST be a contract that supports the LSP1 UniversalReceiver standard. | +| `data` | `bytes[]` | An array of additional data the caller wants included in the emitted event, and sent in the hooks to `from` and `to` addresses. | + +
+ +### transferFrom + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transferfrom) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `transferFrom(address,address,uint256)` +- Function selector: `0x23b872dd` + +::: + +:::info + +This function uses the `allowNonLSP1Recipient` parameter as `true` so that EOA and any contract can receive tokens. + +::: + +```solidity +function transferFrom( + address from, + address to, + uint256 amount +) external nonpayable returns (bool); +``` + +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ----------- | +| `from` | `address` | - | +| `to` | `address` | - | +| `amount` | `uint256` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :----: | ----------- | +| `0` | `bool` | - | + +
+ +### transferOwnership + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transferownership) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Function signature: `transferOwnership(address)` +- Function selector: `0xf2fde38b` + +::: + +```solidity +function transferOwnership(address newOwner) external nonpayable; +``` + +Transfers ownership of the contract to a new account (`newOwner`). Can only be called by the current owner. + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ----------- | +| `newOwner` | `address` | - | + +
+ +## Internal Methods + +Any method labeled as `internal` serves as utility function within the contract. They can be used when writing solidity contracts that inherit from this contract. These methods can be extended or modified by overriding their internal behavior to suit specific needs. + +Internal functions cannot be called externally, whether from other smart contracts, dApp interfaces, or backend services. Their restricted accessibility ensures that they remain exclusively available within the context of the current contract, promoting controlled and encapsulated usage of these internal utilities. + +### \_checkOwner + +```solidity +function _checkOwner() internal view; +``` + +Throws if the sender is not the owner. + +
+ +### \_setOwner + +```solidity +function _setOwner(address newOwner) internal nonpayable; +``` + +Changes the owner if `newOwner` and oldOwner are different +This pattern is useful in inheritance. + +
+ +### \_getData + +```solidity +function _getData(bytes32 dataKey) internal view returns (bytes dataValue); +``` + +
+ +### \_setData + +```solidity +function _setData(bytes32 key, bytes value) internal nonpayable; +``` + +
+ +### \_updateOperator + +```solidity +function _updateOperator( + address tokenOwner, + address operator, + uint256 amount +) internal nonpayable; +``` + +
+ +### \_mint + +```solidity +function _mint( + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) internal nonpayable; +``` + +
+ +### \_burn + +```solidity +function _burn(address from, uint256 amount, bytes data) internal nonpayable; +``` + +
+ +### \_transfer + +```solidity +function _transfer( + address from, + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) internal nonpayable; +``` + +
+ +### \_beforeTokenTransfer + +```solidity +function _beforeTokenTransfer( + address from, + address to, + uint256 amount +) internal nonpayable; +``` + +Hook that is called before any token transfer, including minting and burning. +Allows to run custom logic before updating balances and notifiying sender/recipient by overriding this function. + +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ------------------------------- | +| `from` | `address` | The sender address | +| `to` | `address` | The recipient address | +| `amount` | `uint256` | The amount of token to transfer | + +
+ +### \_notifyTokenSender + +```solidity +function _notifyTokenSender(address from, bytes lsp1Data) internal nonpayable; +``` + +Attempt to notify the token sender `from` about the `amount` of tokens being transferred. +This is done by calling its [`universalReceiver`](#universalreceiver) function with the `_TYPEID_LSP7_TOKENSSENDER` as typeId, if `from` is a contract that supports the LSP1 interface. +If `from` is an EOA or a contract that does not support the LSP1 interface, nothing will happen and no notification will be sent. + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | -------------------------------------------------------------------------- | +| `from` | `address` | The address to call the {universalReceiver} function on. | +| `lsp1Data` | `bytes` | the data to be sent to the `from` address in the `universalReceiver` call. | + +
+ +### \_notifyTokenReceiver + +```solidity +function _notifyTokenReceiver( + address to, + bool allowNonLSP1Recipient, + bytes lsp1Data +) internal nonpayable; +``` + +Attempt to notify the token receiver `to` about the `amount` tokens being received. +This is done by calling its [`universalReceiver`](#universalreceiver) function with the `_TYPEID_LSP7_TOKENSRECIPIENT` as typeId, if `to` is a contract that supports the LSP1 interface. +If `to` is is an EOA or a contract that does not support the LSP1 interface, the behaviour will depend on the `allowNonLSP1Recipient` boolean flag. + +- if `allowNonLSP1Recipient` is set to `true`, nothing will happen and no notification will be sent. + +- if `allowNonLSP1Recipient` is set to `false, the transaction will revert. + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | --------------------------------------------------------------------------------------------------- | +| `to` | `address` | The address to call the {universalReceiver} function on. | +| `allowNonLSP1Recipient` | `bool` | a boolean that describe if transfer to a `to` address that does not support LSP1 is allowed or not. | +| `lsp1Data` | `bytes` | the data to be sent to the `to` address in the `universalReceiver(...)` call. | + +
+ +## Events + +### Approval + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#approval) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Event signature: `Approval(address,address,uint256)` +- Event topic hash: `0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925` + +::: + +```solidity +event Approval(address indexed owner, address indexed spender, uint256 value); +``` + +Emitted when `owner` enables `approved` for `tokenId`. + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ----------------------------------------- | +| `owner` **`indexed`** | `address` | The address of the owner of the `tokenId` | +| `spender` **`indexed`** | `address` | - | +| `value` | `uint256` | - | + +
+ +### AuthorizedOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizedoperator) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Event signature: `AuthorizedOperator(address,address,uint256)` +- Event topic hash: `0xd66aff874162a96578e919097b6f6d153dfd89a5cec41bb331fdb0c4aec16e2c` + +::: + +```solidity +event AuthorizedOperator(address indexed operator, address indexed tokenOwner, uint256 indexed amount); +``` + +Emitted when `tokenOwner` enables `operator` for `tokenId`. + +#### Parameters + +| Name | Type | Description | +| -------------------------- | :-------: | ----------------------------------------------------------------------- | +| `operator` **`indexed`** | `address` | The address authorized as an operator | +| `tokenOwner` **`indexed`** | `address` | The token owner | +| `amount` **`indexed`** | `uint256` | The amount of tokens `operator` address has access to from `tokenOwner` | + +
+ +### DataChanged + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#datachanged) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Event signature: `DataChanged(bytes32,bytes)` +- Event topic hash: `0xece574603820d07bc9b91f2a932baadf4628aabcb8afba49776529c14a6104b2` + +::: + +```solidity +event DataChanged(bytes32 indexed dataKey, bytes dataValue); +``` + +_Emitted when data at a key is changed_ + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ------------------------------------ | +| `dataKey` **`indexed`** | `bytes32` | The data key which data value is set | +| `dataValue` | `bytes` | The data value to set | + +
+ +### OwnershipTransferred + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#ownershiptransferred) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Event signature: `OwnershipTransferred(address,address)` +- Event topic hash: `0x8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0` + +::: + +```solidity +event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); +``` + +#### Parameters + +| Name | Type | Description | +| ----------------------------- | :-------: | ----------- | +| `previousOwner` **`indexed`** | `address` | - | +| `newOwner` **`indexed`** | `address` | - | + +
+ +### RevokedOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#revokedoperator) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Event signature: `RevokedOperator(address,address)` +- Event topic hash: `0x50546e66e5f44d728365dc3908c63bc5cfeeab470722c1677e3073a6ac294aa1` + +::: + +```solidity +event RevokedOperator(address indexed operator, address indexed tokenOwner); +``` + +Emitted when `tokenOwner` disables `operator` for `tokenId`. + +#### Parameters + +| Name | Type | Description | +| -------------------------- | :-------: | ---------------------------------- | +| `operator` **`indexed`** | `address` | The address revoked from operating | +| `tokenOwner` **`indexed`** | `address` | The token owner | + +
+ +### Transfer + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transfer) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Event signature: `Transfer(address,address,address,uint256,bool,bytes)` +- Event topic hash: `0x3997e418d2cef0b3b0e907b1e39605c3f7d32dbd061e82ea5b4a770d46a160a6` + +::: + +```solidity +event Transfer(address indexed operator, address indexed from, address indexed to, uint256 amount, bool allowNonLSP1Recipient, bytes data); +``` + +Emitted when `tokenId` token is transferred from `from` to `to`. + +#### Parameters + +| Name | Type | Description | +| ------------------------ | :-------: | ---------------------------------------------------------------------------------------------------------------------------- | +| `operator` **`indexed`** | `address` | The address of operator sending tokens | +| `from` **`indexed`** | `address` | The address which tokens are sent | +| `to` **`indexed`** | `address` | The receiving address | +| `amount` | `uint256` | The amount of tokens transferred. | +| `allowNonLSP1Recipient` | `bool` | When set to TRUE, `to` may be any address but when set to FALSE `to` must be a contract that supports LSP1 UniversalReceiver | +| `data` | `bytes` | Additional data the caller wants included in the emitted event, and sent in the hooks to `from` and `to` addresses | + +
+ +## Errors + +### ERC725Y_DataKeysValuesEmptyArray + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_datakeysvaluesemptyarray) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `ERC725Y_DataKeysValuesEmptyArray()` +- Error hash: `0x97da5f95` + +::: + +```solidity +error ERC725Y_DataKeysValuesEmptyArray(); +``` + +reverts when one of the array parameter provided to `setDataBatch` is an empty array + +
+ +### ERC725Y_DataKeysValuesLengthMismatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_datakeysvalueslengthmismatch) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `ERC725Y_DataKeysValuesLengthMismatch()` +- Error hash: `0x3bcc8979` + +::: + +```solidity +error ERC725Y_DataKeysValuesLengthMismatch(); +``` + +reverts when there is not the same number of elements in the lists of data keys and data values when calling setDataBatch. + +
+ +### ERC725Y_MsgValueDisallowed + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_msgvaluedisallowed) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `ERC725Y_MsgValueDisallowed()` +- Error hash: `0xf36ba737` + +::: + +```solidity +error ERC725Y_MsgValueDisallowed(); +``` + +reverts when sending value to the `setData(..)` functions + +
+ +### LSP4TokenNameNotEditable + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp4tokennamenoteditable) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `LSP4TokenNameNotEditable()` +- Error hash: `0x85c169bd` + +::: + +```solidity +error LSP4TokenNameNotEditable(); +``` + +Reverts when trying to edit the data key `LSP4TokenName` after the digital asset contract has been deployed. The `LSP4TokenName` data key is located inside the ERC725Y Data key-value store of the digital asset contract. It can be set only once inside the constructor/initializer when the digital asset contract is being deployed. + +
+ +### LSP4TokenSymbolNotEditable + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp4tokensymbolnoteditable) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `LSP4TokenSymbolNotEditable()` +- Error hash: `0x76755b38` + +::: + +```solidity +error LSP4TokenSymbolNotEditable(); +``` + +Reverts when trying to edit the data key `LSP4TokenSymbol` after the digital asset contract has been deployed. The `LSP4TokenSymbol` data key is located inside the ERC725Y Data key-value store of the digital asset contract. It can be set only once inside the constructor/initializer when the digital asset contract is being deployed. + +
+ +### LSP7AmountExceedsAuthorizedAmount + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7amountexceedsauthorizedamount) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `LSP7AmountExceedsAuthorizedAmount(address,uint256,address,uint256)` +- Error hash: `0xf3a6b691` + +::: + +```solidity +error LSP7AmountExceedsAuthorizedAmount( + address tokenOwner, + uint256 authorizedAmount, + address operator, + uint256 amount +); +``` + +reverts when `operator` of `tokenOwner` send an `amount` of tokens larger than the `authorizedAmount`. + +#### Parameters + +| Name | Type | Description | +| ------------------ | :-------: | ----------- | +| `tokenOwner` | `address` | - | +| `authorizedAmount` | `uint256` | - | +| `operator` | `address` | - | +| `amount` | `uint256` | - | + +
+ +### LSP7AmountExceedsBalance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7amountexceedsbalance) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `LSP7AmountExceedsBalance(uint256,address,uint256)` +- Error hash: `0x08d47949` + +::: + +```solidity +error LSP7AmountExceedsBalance( + uint256 balance, + address tokenOwner, + uint256 amount +); +``` + +reverts when sending an `amount` of tokens larger than the current `balance` of the `tokenOwner`. + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | ----------- | +| `balance` | `uint256` | - | +| `tokenOwner` | `address` | - | +| `amount` | `uint256` | - | + +
+ +### LSP7CannotSendToSelf + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotsendtoself) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `LSP7CannotSendToSelf()` +- Error hash: `0xb9afb000` + +::: + +```solidity +error LSP7CannotSendToSelf(); +``` + +reverts when specifying the same address for `from` or `to` in a token transfer. + +
+ +### LSP7CannotSendWithAddressZero + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotsendwithaddresszero) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `LSP7CannotSendWithAddressZero()` +- Error hash: `0xd2d5ec30` + +::: + +```solidity +error LSP7CannotSendWithAddressZero(); +``` + +reverts when trying to: + +- mint tokens to the zero address. + +- burn tokens from the zero address. + +- transfer tokens from or to the zero address. + +
+ +### LSP7CannotUseAddressZeroAsOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotuseaddresszeroasoperator) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `LSP7CannotUseAddressZeroAsOperator()` +- Error hash: `0x6355e766` + +::: + +```solidity +error LSP7CannotUseAddressZeroAsOperator(); +``` + +reverts when trying to set the zero address as an operator. + +
+ +### LSP7DecreasedAllowanceBelowZero + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7decreasedallowancebelowzero) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `LSP7DecreasedAllowanceBelowZero()` +- Error hash: `0x0ef76c35` + +::: + +```solidity +error LSP7DecreasedAllowanceBelowZero(); +``` + +Reverts when trying to decrease an operator's allowance to more than its current allowance. + +
+ +### LSP7InvalidTransferBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7invalidtransferbatch) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `LSP7InvalidTransferBatch()` +- Error hash: `0x263eee8d` + +::: + +```solidity +error LSP7InvalidTransferBatch(); +``` + +reverts when the array parameters used in [`transferBatch`](#transferbatch) have different lengths. + +
+ +### LSP7NotifyTokenReceiverContractMissingLSP1Interface + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7notifytokenreceivercontractmissinglsp1interface) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `LSP7NotifyTokenReceiverContractMissingLSP1Interface(address)` +- Error hash: `0xa608fbb6` + +::: + +```solidity +error LSP7NotifyTokenReceiverContractMissingLSP1Interface( + address tokenReceiver +); +``` + +reverts if the `tokenReceiver` does not implement LSP1 when minting or transferring tokens with `bool allowNonLSP1Recipient` set as `false`. + +#### Parameters + +| Name | Type | Description | +| --------------- | :-------: | ----------- | +| `tokenReceiver` | `address` | - | + +
+ +### LSP7NotifyTokenReceiverIsEOA + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7notifytokenreceiveriseoa) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `LSP7NotifyTokenReceiverIsEOA(address)` +- Error hash: `0x26c247f4` + +::: + +```solidity +error LSP7NotifyTokenReceiverIsEOA(address tokenReceiver); +``` + +reverts if the `tokenReceiver` is an EOA when minting or transferring tokens with `bool allowNonLSP1Recipient` set as `false`. + +#### Parameters + +| Name | Type | Description | +| --------------- | :-------: | ----------- | +| `tokenReceiver` | `address` | - | + +
+ +### LSP7TokenOwnerCannotBeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7tokenownercannotbeoperator) +- Solidity implementation: [`LSP7CompatibleERC20.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol) +- Error signature: `LSP7TokenOwnerCannotBeOperator()` +- Error hash: `0xdab75047` + +::: + +```solidity +error LSP7TokenOwnerCannotBeOperator(); +``` + +reverts when trying to authorize or revoke the token's owner as an operator. + +
diff --git a/docs/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.md b/docs/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.md new file mode 100644 index 000000000..aba7d617e --- /dev/null +++ b/docs/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.md @@ -0,0 +1,1504 @@ + + + +# LSP7CompatibleERC20Mintable + +:::info Standard Specifications + +[`LSP-7-DigitalAsset`](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md) + +::: +:::info Solidity implementation + +[`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) + +::: + +> LSP7CompatibleERC20 deployable preset contract with a public {mint} function callable only by the contract {owner}. + +## Public Methods + +Public methods are accessible externally from users, allowing interaction with this function from dApps or other smart contracts. +When marked as 'public', a method can be called both externally and internally, on the other hand, when marked as 'external', a method can only be called externally. + +### constructor + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#constructor) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) + +::: + +```solidity +constructor(string name_, string symbol_, address newOwner_); +``` + +_Deploying a `LSP7CompatibleERC20Mintable` token contract with: token name = `name_`, token symbol = `symbol_`, and address `newOwner_` as the token contract owner._ + +#### Parameters + +| Name | Type | Description | +| ----------- | :-------: | -------------------------------- | +| `name_` | `string` | The name of the token. | +| `symbol_` | `string` | The symbol of the token. | +| `newOwner_` | `address` | The owner of the token contract. | + +
+ +### allowance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#allowance) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `allowance(address,address)` +- Function selector: `0xdd62ed3e` + +::: + +```solidity +function allowance( + address tokenOwner, + address operator +) external view returns (uint256); +``` + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | ----------- | +| `tokenOwner` | `address` | - | +| `operator` | `address` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ----------- | +| `0` | `uint256` | - | + +
+ +### approve + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#approve) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `approve(address,uint256)` +- Function selector: `0x095ea7b3` + +::: + +```solidity +function approve( + address operator, + uint256 amount +) external nonpayable returns (bool); +``` + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ----------- | +| `operator` | `address` | - | +| `amount` | `uint256` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :----: | ----------- | +| `0` | `bool` | - | + +
+ +### authorizeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizeoperator) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `authorizeOperator(address,uint256)` +- Function selector: `0x47980aa3` + +::: + +:::danger + +To avoid front-running and Allowance Double-Spend Exploit when increasing or decreasing the authorized amount of an operator, it is advised to: 1. either call {revokeOperator} first, and then re-call {authorizeOperator} with the new amount. 2. or use the non-standard functions {increaseAllowance} or {decreaseAllowance}. For more information, see: https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/ + +::: + +```solidity +function authorizeOperator( + address operator, + uint256 amount +) external nonpayable; +``` + +Sets an `amount` of tokens that an `operator` has access from the caller's balance (allowance). See [`authorizedAmountFor`](#authorizedamountfor). + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ------------------------------------------------------ | +| `operator` | `address` | The address to authorize as an operator. | +| `amount` | `uint256` | The allowance amount of tokens operator has access to. | + +
+ +### authorizedAmountFor + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizedamountfor) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `authorizedAmountFor(address,address)` +- Function selector: `0x65aeaa95` + +::: + +```solidity +function authorizedAmountFor( + address operator, + address tokenOwner +) external view returns (uint256); +``` + +Get the amount of tokens `operator` address has access to from `tokenOwner`. Operators can send and burn tokens on behalf of their owners. + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | ---------------------------------------------------------- | +| `operator` | `address` | The operator's address to query the authorized amount for. | +| `tokenOwner` | `address` | The token owner that `operator` has allowance on. | + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | --------------------------------------------------------------------------------------- | +| `0` | `uint256` | The amount of tokens the `operator`'s address has access on the `tokenOwner`'s balance. | + +
+ +### balanceOf + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#balanceof) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `balanceOf(address)` +- Function selector: `0x70a08231` + +::: + +```solidity +function balanceOf(address tokenOwner) external view returns (uint256); +``` + +Get the number of tokens owned by `tokenOwner`. If the token is divisible (the [`decimals`](#decimals) function returns `18`), the amount returned should be divided by 1e18 to get a better picture of the actual balance of the `tokenOwner`. _Example:_ `balanceOf(someAddress) -> 42_000_000_000_000_000_000 / 1e18 = 42 tokens` + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | --------------------------------------------------------- | +| `tokenOwner` | `address` | The address of the token holder to query the balance for. | + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ------------------------------------------- | +| `0` | `uint256` | The amount of tokens owned by `tokenOwner`. | + +
+ +### decimals + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#decimals) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `decimals()` +- Function selector: `0x313ce567` + +::: + +```solidity +function decimals() external view returns (uint8); +``` + +Returns the number of decimals used to get its user representation. If the asset contract has been set to be non-divisible via the `isNonDivisible_` parameter in the `constructor`, the decimals returned wiil be `0`. Otherwise `18` is the common value. + +#### Returns + +| Name | Type | Description | +| ---- | :-----: | ----------------------------------------------------------------------- | +| `0` | `uint8` | the number of decimals. If `0` is returned, the asset is non-divisible. | + +
+ +### decreaseAllowance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#decreaseallowance) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `decreaseAllowance(address,uint256)` +- Function selector: `0xa457c2d7` + +::: + +:::info + +This is a non-standard function, not part of the LSP7 standard interface. It has been added in the LSP7 contract implementation so that it can be used as a prevention mechanism against the double spending allowance vulnerability. + +::: + +```solidity +function decreaseAllowance( + address operator, + uint256 substractedAmount +) external nonpayable; +``` + +_Decrease the allowance of `operator` by -`substractedAmount`_ + +Atomically decreases the allowance granted to `operator` by the caller. This is an alternative approach to [`authorizeOperator`](#authorizeoperator) that can be used as a mitigation for the double spending allowance problem. + +
+ +**Requirements:** + +- `operator` cannot be the zero address. +- `operator` must have allowance for the caller of at least `substractedAmount`. + +
+ +
+ +**Emitted events:** + +- [`AuthorizedOperator`](#authorizedoperator) event indicating the updated allowance after decreasing it. +- [`RevokeOperator`](#revokeoperator) event if `substractedAmount` is the full allowance, indicating `operator` does not have any alauthorizedAmountForlowance left for `msg.sender`. + +
+ +#### Parameters + +| Name | Type | Description | +| ------------------- | :-------: | ------------------------------------------------------ | +| `operator` | `address` | the operator to decrease allowance for `msg.sender` | +| `substractedAmount` | `uint256` | the amount to decrease by in the operator's allowance. | + +
+ +### getData + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#getdata) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `getData(bytes32)` +- Function selector: `0x54f6127f` + +::: + +```solidity +function getData(bytes32 dataKey) external view returns (bytes dataValue); +``` + +_Gets singular data at a given `dataKey`_ + +#### Parameters + +| Name | Type | Description | +| --------- | :-------: | ------------------------------- | +| `dataKey` | `bytes32` | The key which value to retrieve | + +#### Returns + +| Name | Type | Description | +| ----------- | :-----: | -------------------------- | +| `dataValue` | `bytes` | The data stored at the key | + +
+ +### getDataBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#getdatabatch) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `getDataBatch(bytes32[])` +- Function selector: `0xdedff9c6` + +::: + +```solidity +function getDataBatch( + bytes32[] dataKeys +) external view returns (bytes[] dataValues); +``` + +_Gets array of data for multiple given keys_ + +#### Parameters + +| Name | Type | Description | +| ---------- | :---------: | ------------------------------------------ | +| `dataKeys` | `bytes32[]` | The array of keys which values to retrieve | + +#### Returns + +| Name | Type | Description | +| ------------ | :-------: | ----------------------------------------- | +| `dataValues` | `bytes[]` | The array of data stored at multiple keys | + +
+ +### increaseAllowance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#increaseallowance) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `increaseAllowance(address,uint256)` +- Function selector: `0x39509351` + +::: + +:::info + +This is a non-standard function, not part of the LSP7 standard interface. It has been added in the LSP7 contract implementation so that it can be used as a prevention mechanism against double spending allowance vulnerability. + +::: + +```solidity +function increaseAllowance( + address operator, + uint256 addedAmount +) external nonpayable; +``` + +_Increase the allowance of `operator` by +`addedAmount`_ + +Atomically increases the allowance granted to `operator` by the caller. This is an alternative approach to [`authorizeOperator`](#authorizeoperator) that can be used as a mitigation for the double spending allowance problem. + +
+ +**Requirements:** + +- `operator` cannot be the same address as `msg.sender` +- `operator` cannot be the zero address. + +
+ +
+ +**Emitted events:** + +- [`AuthorizedOperator`](#authorizedoperator) indicating the updated allowance + +
+ +#### Parameters + +| Name | Type | Description | +| ------------- | :-------: | ----------------------------------------------------------------------- | +| `operator` | `address` | the operator to increase the allowance for `msg.sender` | +| `addedAmount` | `uint256` | the additional amount to add on top of the current operator's allowance | + +
+ +### mint + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#mint) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `mint(address,uint256,bool,bytes)` +- Function selector: `0x7580d920` + +::: + +```solidity +function mint( + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) external nonpayable; +``` + +Public [`_mint`](#_mint) function only callable by the [`owner`](#owner). + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ----------- | +| `to` | `address` | - | +| `amount` | `uint256` | - | +| `allowNonLSP1Recipient` | `bool` | - | +| `data` | `bytes` | - | + +
+ +### name + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#name) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `name()` +- Function selector: `0x06fdde03` + +::: + +```solidity +function name() external view returns (string); +``` + +Returns the name of the token. + +#### Returns + +| Name | Type | Description | +| ---- | :------: | --------------------- | +| `0` | `string` | The name of the token | + +
+ +### owner + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#owner) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `owner()` +- Function selector: `0x8da5cb5b` + +::: + +```solidity +function owner() external view returns (address); +``` + +Returns the address of the current owner. + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ----------- | +| `0` | `address` | - | + +
+ +### renounceOwnership + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#renounceownership) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `renounceOwnership()` +- Function selector: `0x715018a6` + +::: + +```solidity +function renounceOwnership() external nonpayable; +``` + +Leaves the contract without owner. It will not be possible to call `onlyOwner` functions anymore. Can only be called by the current owner. NOTE: Renouncing ownership will leave the contract without an owner, thereby removing any functionality that is only available to the owner. + +
+ +### revokeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#revokeoperator) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `revokeOperator(address)` +- Function selector: `0xfad8b32a` + +::: + +```solidity +function revokeOperator(address operator) external nonpayable; +``` + +Removes the `operator` address as an operator of callers tokens, disallowing it to send any amount of tokens on behalf of the token owner (the caller of the function `msg.sender`). See also [`authorizedAmountFor`](#authorizedamountfor). + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ------------------------------------- | +| `operator` | `address` | The address to revoke as an operator. | + +
+ +### setData + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#setdata) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `setData(bytes32,bytes)` +- Function selector: `0x7f23690c` + +::: + +```solidity +function setData(bytes32 dataKey, bytes dataValue) external payable; +``` + +_Sets singular data for a given `dataKey`_ + +#### Parameters + +| Name | Type | Description | +| ----------- | :-------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dataKey` | `bytes32` | The key to retrieve stored value | +| `dataValue` | `bytes` | The value to set SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal 0. Emits a {DataChanged} event. | + +
+ +### setDataBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#setdatabatch) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `setDataBatch(bytes32[],bytes[])` +- Function selector: `0x97902421` + +::: + +```solidity +function setDataBatch(bytes32[] dataKeys, bytes[] dataValues) external payable; +``` + +Sets array of data for multiple given `dataKeys` SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal + +0. Emits a [`DataChanged`](#datachanged) event. + +#### Parameters + +| Name | Type | Description | +| ------------ | :---------: | ---------------------------------------- | +| `dataKeys` | `bytes32[]` | The array of data keys for values to set | +| `dataValues` | `bytes[]` | The array of values to set | + +
+ +### supportsInterface + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#supportsinterface) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `supportsInterface(bytes4)` +- Function selector: `0x01ffc9a7` + +::: + +```solidity +function supportsInterface(bytes4 interfaceId) external view returns (bool); +``` + +Returns true if this contract implements the interface defined by `interfaceId`. See the corresponding https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section] to learn more about how these ids are created. This function call must use less than 30 000 gas. + +#### Parameters + +| Name | Type | Description | +| ------------- | :------: | ----------- | +| `interfaceId` | `bytes4` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :----: | ----------- | +| `0` | `bool` | - | + +
+ +### symbol + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#symbol) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `symbol()` +- Function selector: `0x95d89b41` + +::: + +```solidity +function symbol() external view returns (string); +``` + +Returns the symbol of the token, usually a shorter version of the name. + +#### Returns + +| Name | Type | Description | +| ---- | :------: | ----------------------- | +| `0` | `string` | The symbol of the token | + +
+ +### totalSupply + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#totalsupply) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `totalSupply()` +- Function selector: `0x18160ddd` + +::: + +```solidity +function totalSupply() external view returns (uint256); +``` + +Returns the number of existing tokens that have been minted in this contract. + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ------------------------------ | +| `0` | `uint256` | The number of existing tokens. | + +
+ +### transfer + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transfer) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `transfer(address,address,uint256,bool,bytes)` +- Function selector: `0x760d9bba` + +::: + +```solidity +function transfer( + address from, + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) external nonpayable; +``` + +Transfers an `amount` of tokens from the `from` address to the `to` address and notify both sender and recipients via the LSP1 [`universalReceiver(...)`](#`universalreceiver) function. If the tokens are transferred by an operator on behalf of a token holder, the allowance for the operator will be decreased by `amount` once the token transfer has been completed (See [`authorizedAmountFor`](#authorizedamountfor)). + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address` | The sender address. | +| `to` | `address` | The recipient address. | +| `amount` | `uint256` | The amount of tokens to transfer. | +| `allowNonLSP1Recipient` | `bool` | When set to `true`, the `to` address CAN be any address. When set to `false`, the `to` address MUST be a contract that supports the LSP1 UniversalReceiver standard. | +| `data` | `bytes` | Any additional data the caller wants included in the emitted event, and sent in the hooks of the `from` and `to` addresses. | + +
+ +### transfer + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transfer) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `transfer(address,uint256)` +- Function selector: `0xa9059cbb` + +::: + +:::info + +This function uses the `allowNonLSP1Recipient` parameter as `true` so that EOA and any contract can receive tokens. + +::: + +```solidity +function transfer( + address to, + uint256 amount +) external nonpayable returns (bool); +``` + +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ----------- | +| `to` | `address` | - | +| `amount` | `uint256` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :----: | ----------- | +| `0` | `bool` | - | + +
+ +### transferBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transferbatch) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `transferBatch(address[],address[],uint256[],bool[],bytes[])` +- Function selector: `0x2d7667c9` + +::: + +```solidity +function transferBatch( + address[] from, + address[] to, + uint256[] amount, + bool[] allowNonLSP1Recipient, + bytes[] data +) external nonpayable; +``` + +Same as [`transfer(...)`](#`transfer) but transfer multiple tokens based on the arrays of `from`, `to`, `amount`. + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :---------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address[]` | An array of sending addresses. | +| `to` | `address[]` | An array of receiving addresses. | +| `amount` | `uint256[]` | An array of amount of tokens to transfer for each `from -> to` transfer. | +| `allowNonLSP1Recipient` | `bool[]` | For each transfer, when set to `true`, the `to` address CAN be any address. When set to `false`, the `to` address MUST be a contract that supports the LSP1 UniversalReceiver standard. | +| `data` | `bytes[]` | An array of additional data the caller wants included in the emitted event, and sent in the hooks to `from` and `to` addresses. | + +
+ +### transferFrom + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transferfrom) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `transferFrom(address,address,uint256)` +- Function selector: `0x23b872dd` + +::: + +:::info + +This function uses the `allowNonLSP1Recipient` parameter as `true` so that EOA and any contract can receive tokens. + +::: + +```solidity +function transferFrom( + address from, + address to, + uint256 amount +) external nonpayable returns (bool); +``` + +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ----------- | +| `from` | `address` | - | +| `to` | `address` | - | +| `amount` | `uint256` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :----: | ----------- | +| `0` | `bool` | - | + +
+ +### transferOwnership + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transferownership) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Function signature: `transferOwnership(address)` +- Function selector: `0xf2fde38b` + +::: + +```solidity +function transferOwnership(address newOwner) external nonpayable; +``` + +Transfers ownership of the contract to a new account (`newOwner`). Can only be called by the current owner. + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ----------- | +| `newOwner` | `address` | - | + +
+ +## Internal Methods + +Any method labeled as `internal` serves as utility function within the contract. They can be used when writing solidity contracts that inherit from this contract. These methods can be extended or modified by overriding their internal behavior to suit specific needs. + +Internal functions cannot be called externally, whether from other smart contracts, dApp interfaces, or backend services. Their restricted accessibility ensures that they remain exclusively available within the context of the current contract, promoting controlled and encapsulated usage of these internal utilities. + +### \_checkOwner + +```solidity +function _checkOwner() internal view; +``` + +Throws if the sender is not the owner. + +
+ +### \_setOwner + +```solidity +function _setOwner(address newOwner) internal nonpayable; +``` + +Changes the owner if `newOwner` and oldOwner are different +This pattern is useful in inheritance. + +
+ +### \_getData + +```solidity +function _getData(bytes32 dataKey) internal view returns (bytes dataValue); +``` + +
+ +### \_setData + +```solidity +function _setData(bytes32 key, bytes value) internal nonpayable; +``` + +
+ +### \_updateOperator + +```solidity +function _updateOperator( + address tokenOwner, + address operator, + uint256 amount +) internal nonpayable; +``` + +
+ +### \_mint + +```solidity +function _mint( + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) internal nonpayable; +``` + +
+ +### \_burn + +```solidity +function _burn(address from, uint256 amount, bytes data) internal nonpayable; +``` + +
+ +### \_transfer + +```solidity +function _transfer( + address from, + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) internal nonpayable; +``` + +
+ +### \_beforeTokenTransfer + +```solidity +function _beforeTokenTransfer( + address from, + address to, + uint256 amount +) internal nonpayable; +``` + +Hook that is called before any token transfer, including minting and burning. +Allows to run custom logic before updating balances and notifiying sender/recipient by overriding this function. + +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ------------------------------- | +| `from` | `address` | The sender address | +| `to` | `address` | The recipient address | +| `amount` | `uint256` | The amount of token to transfer | + +
+ +### \_notifyTokenSender + +```solidity +function _notifyTokenSender(address from, bytes lsp1Data) internal nonpayable; +``` + +Attempt to notify the token sender `from` about the `amount` of tokens being transferred. +This is done by calling its [`universalReceiver`](#universalreceiver) function with the `_TYPEID_LSP7_TOKENSSENDER` as typeId, if `from` is a contract that supports the LSP1 interface. +If `from` is an EOA or a contract that does not support the LSP1 interface, nothing will happen and no notification will be sent. + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | -------------------------------------------------------------------------- | +| `from` | `address` | The address to call the {universalReceiver} function on. | +| `lsp1Data` | `bytes` | the data to be sent to the `from` address in the `universalReceiver` call. | + +
+ +### \_notifyTokenReceiver + +```solidity +function _notifyTokenReceiver( + address to, + bool allowNonLSP1Recipient, + bytes lsp1Data +) internal nonpayable; +``` + +Attempt to notify the token receiver `to` about the `amount` tokens being received. +This is done by calling its [`universalReceiver`](#universalreceiver) function with the `_TYPEID_LSP7_TOKENSRECIPIENT` as typeId, if `to` is a contract that supports the LSP1 interface. +If `to` is is an EOA or a contract that does not support the LSP1 interface, the behaviour will depend on the `allowNonLSP1Recipient` boolean flag. + +- if `allowNonLSP1Recipient` is set to `true`, nothing will happen and no notification will be sent. + +- if `allowNonLSP1Recipient` is set to `false, the transaction will revert. + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | --------------------------------------------------------------------------------------------------- | +| `to` | `address` | The address to call the {universalReceiver} function on. | +| `allowNonLSP1Recipient` | `bool` | a boolean that describe if transfer to a `to` address that does not support LSP1 is allowed or not. | +| `lsp1Data` | `bytes` | the data to be sent to the `to` address in the `universalReceiver(...)` call. | + +
+ +## Events + +### Approval + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#approval) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Event signature: `Approval(address,address,uint256)` +- Event topic hash: `0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925` + +::: + +```solidity +event Approval(address indexed owner, address indexed spender, uint256 value); +``` + +Emitted when `owner` enables `approved` for `tokenId`. + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ----------------------------------------- | +| `owner` **`indexed`** | `address` | The address of the owner of the `tokenId` | +| `spender` **`indexed`** | `address` | - | +| `value` | `uint256` | - | + +
+ +### AuthorizedOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizedoperator) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Event signature: `AuthorizedOperator(address,address,uint256)` +- Event topic hash: `0xd66aff874162a96578e919097b6f6d153dfd89a5cec41bb331fdb0c4aec16e2c` + +::: + +```solidity +event AuthorizedOperator(address indexed operator, address indexed tokenOwner, uint256 indexed amount); +``` + +Emitted when `tokenOwner` enables `operator` for `tokenId`. + +#### Parameters + +| Name | Type | Description | +| -------------------------- | :-------: | ----------------------------------------------------------------------- | +| `operator` **`indexed`** | `address` | The address authorized as an operator | +| `tokenOwner` **`indexed`** | `address` | The token owner | +| `amount` **`indexed`** | `uint256` | The amount of tokens `operator` address has access to from `tokenOwner` | + +
+ +### DataChanged + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#datachanged) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Event signature: `DataChanged(bytes32,bytes)` +- Event topic hash: `0xece574603820d07bc9b91f2a932baadf4628aabcb8afba49776529c14a6104b2` + +::: + +```solidity +event DataChanged(bytes32 indexed dataKey, bytes dataValue); +``` + +_Emitted when data at a key is changed_ + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ------------------------------------ | +| `dataKey` **`indexed`** | `bytes32` | The data key which data value is set | +| `dataValue` | `bytes` | The data value to set | + +
+ +### OwnershipTransferred + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#ownershiptransferred) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Event signature: `OwnershipTransferred(address,address)` +- Event topic hash: `0x8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0` + +::: + +```solidity +event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); +``` + +#### Parameters + +| Name | Type | Description | +| ----------------------------- | :-------: | ----------- | +| `previousOwner` **`indexed`** | `address` | - | +| `newOwner` **`indexed`** | `address` | - | + +
+ +### RevokedOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#revokedoperator) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Event signature: `RevokedOperator(address,address)` +- Event topic hash: `0x50546e66e5f44d728365dc3908c63bc5cfeeab470722c1677e3073a6ac294aa1` + +::: + +```solidity +event RevokedOperator(address indexed operator, address indexed tokenOwner); +``` + +Emitted when `tokenOwner` disables `operator` for `tokenId`. + +#### Parameters + +| Name | Type | Description | +| -------------------------- | :-------: | ---------------------------------- | +| `operator` **`indexed`** | `address` | The address revoked from operating | +| `tokenOwner` **`indexed`** | `address` | The token owner | + +
+ +### Transfer + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transfer) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Event signature: `Transfer(address,address,address,uint256,bool,bytes)` +- Event topic hash: `0x3997e418d2cef0b3b0e907b1e39605c3f7d32dbd061e82ea5b4a770d46a160a6` + +::: + +```solidity +event Transfer(address indexed operator, address indexed from, address indexed to, uint256 amount, bool allowNonLSP1Recipient, bytes data); +``` + +Emitted when `tokenId` token is transferred from `from` to `to`. + +#### Parameters + +| Name | Type | Description | +| ------------------------ | :-------: | ---------------------------------------------------------------------------------------------------------------------------- | +| `operator` **`indexed`** | `address` | The address of operator sending tokens | +| `from` **`indexed`** | `address` | The address which tokens are sent | +| `to` **`indexed`** | `address` | The receiving address | +| `amount` | `uint256` | The amount of tokens transferred. | +| `allowNonLSP1Recipient` | `bool` | When set to TRUE, `to` may be any address but when set to FALSE `to` must be a contract that supports LSP1 UniversalReceiver | +| `data` | `bytes` | Additional data the caller wants included in the emitted event, and sent in the hooks to `from` and `to` addresses | + +
+ +## Errors + +### ERC725Y_DataKeysValuesEmptyArray + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_datakeysvaluesemptyarray) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `ERC725Y_DataKeysValuesEmptyArray()` +- Error hash: `0x97da5f95` + +::: + +```solidity +error ERC725Y_DataKeysValuesEmptyArray(); +``` + +reverts when one of the array parameter provided to `setDataBatch` is an empty array + +
+ +### ERC725Y_DataKeysValuesLengthMismatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_datakeysvalueslengthmismatch) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `ERC725Y_DataKeysValuesLengthMismatch()` +- Error hash: `0x3bcc8979` + +::: + +```solidity +error ERC725Y_DataKeysValuesLengthMismatch(); +``` + +reverts when there is not the same number of elements in the lists of data keys and data values when calling setDataBatch. + +
+ +### ERC725Y_MsgValueDisallowed + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_msgvaluedisallowed) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `ERC725Y_MsgValueDisallowed()` +- Error hash: `0xf36ba737` + +::: + +```solidity +error ERC725Y_MsgValueDisallowed(); +``` + +reverts when sending value to the `setData(..)` functions + +
+ +### LSP4TokenNameNotEditable + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp4tokennamenoteditable) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `LSP4TokenNameNotEditable()` +- Error hash: `0x85c169bd` + +::: + +```solidity +error LSP4TokenNameNotEditable(); +``` + +Reverts when trying to edit the data key `LSP4TokenName` after the digital asset contract has been deployed. The `LSP4TokenName` data key is located inside the ERC725Y Data key-value store of the digital asset contract. It can be set only once inside the constructor/initializer when the digital asset contract is being deployed. + +
+ +### LSP4TokenSymbolNotEditable + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp4tokensymbolnoteditable) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `LSP4TokenSymbolNotEditable()` +- Error hash: `0x76755b38` + +::: + +```solidity +error LSP4TokenSymbolNotEditable(); +``` + +Reverts when trying to edit the data key `LSP4TokenSymbol` after the digital asset contract has been deployed. The `LSP4TokenSymbol` data key is located inside the ERC725Y Data key-value store of the digital asset contract. It can be set only once inside the constructor/initializer when the digital asset contract is being deployed. + +
+ +### LSP7AmountExceedsAuthorizedAmount + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7amountexceedsauthorizedamount) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `LSP7AmountExceedsAuthorizedAmount(address,uint256,address,uint256)` +- Error hash: `0xf3a6b691` + +::: + +```solidity +error LSP7AmountExceedsAuthorizedAmount( + address tokenOwner, + uint256 authorizedAmount, + address operator, + uint256 amount +); +``` + +reverts when `operator` of `tokenOwner` send an `amount` of tokens larger than the `authorizedAmount`. + +#### Parameters + +| Name | Type | Description | +| ------------------ | :-------: | ----------- | +| `tokenOwner` | `address` | - | +| `authorizedAmount` | `uint256` | - | +| `operator` | `address` | - | +| `amount` | `uint256` | - | + +
+ +### LSP7AmountExceedsBalance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7amountexceedsbalance) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `LSP7AmountExceedsBalance(uint256,address,uint256)` +- Error hash: `0x08d47949` + +::: + +```solidity +error LSP7AmountExceedsBalance( + uint256 balance, + address tokenOwner, + uint256 amount +); +``` + +reverts when sending an `amount` of tokens larger than the current `balance` of the `tokenOwner`. + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | ----------- | +| `balance` | `uint256` | - | +| `tokenOwner` | `address` | - | +| `amount` | `uint256` | - | + +
+ +### LSP7CannotSendToSelf + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotsendtoself) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `LSP7CannotSendToSelf()` +- Error hash: `0xb9afb000` + +::: + +```solidity +error LSP7CannotSendToSelf(); +``` + +reverts when specifying the same address for `from` or `to` in a token transfer. + +
+ +### LSP7CannotSendWithAddressZero + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotsendwithaddresszero) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `LSP7CannotSendWithAddressZero()` +- Error hash: `0xd2d5ec30` + +::: + +```solidity +error LSP7CannotSendWithAddressZero(); +``` + +reverts when trying to: + +- mint tokens to the zero address. + +- burn tokens from the zero address. + +- transfer tokens from or to the zero address. + +
+ +### LSP7CannotUseAddressZeroAsOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotuseaddresszeroasoperator) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `LSP7CannotUseAddressZeroAsOperator()` +- Error hash: `0x6355e766` + +::: + +```solidity +error LSP7CannotUseAddressZeroAsOperator(); +``` + +reverts when trying to set the zero address as an operator. + +
+ +### LSP7DecreasedAllowanceBelowZero + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7decreasedallowancebelowzero) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `LSP7DecreasedAllowanceBelowZero()` +- Error hash: `0x0ef76c35` + +::: + +```solidity +error LSP7DecreasedAllowanceBelowZero(); +``` + +Reverts when trying to decrease an operator's allowance to more than its current allowance. + +
+ +### LSP7InvalidTransferBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7invalidtransferbatch) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `LSP7InvalidTransferBatch()` +- Error hash: `0x263eee8d` + +::: + +```solidity +error LSP7InvalidTransferBatch(); +``` + +reverts when the array parameters used in [`transferBatch`](#transferbatch) have different lengths. + +
+ +### LSP7NotifyTokenReceiverContractMissingLSP1Interface + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7notifytokenreceivercontractmissinglsp1interface) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `LSP7NotifyTokenReceiverContractMissingLSP1Interface(address)` +- Error hash: `0xa608fbb6` + +::: + +```solidity +error LSP7NotifyTokenReceiverContractMissingLSP1Interface( + address tokenReceiver +); +``` + +reverts if the `tokenReceiver` does not implement LSP1 when minting or transferring tokens with `bool allowNonLSP1Recipient` set as `false`. + +#### Parameters + +| Name | Type | Description | +| --------------- | :-------: | ----------- | +| `tokenReceiver` | `address` | - | + +
+ +### LSP7NotifyTokenReceiverIsEOA + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7notifytokenreceiveriseoa) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `LSP7NotifyTokenReceiverIsEOA(address)` +- Error hash: `0x26c247f4` + +::: + +```solidity +error LSP7NotifyTokenReceiverIsEOA(address tokenReceiver); +``` + +reverts if the `tokenReceiver` is an EOA when minting or transferring tokens with `bool allowNonLSP1Recipient` set as `false`. + +#### Parameters + +| Name | Type | Description | +| --------------- | :-------: | ----------- | +| `tokenReceiver` | `address` | - | + +
+ +### LSP7TokenOwnerCannotBeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7tokenownercannotbeoperator) +- Solidity implementation: [`LSP7CompatibleERC20Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7CompatibleERC20Mintable.sol) +- Error signature: `LSP7TokenOwnerCannotBeOperator()` +- Error hash: `0xdab75047` + +::: + +```solidity +error LSP7TokenOwnerCannotBeOperator(); +``` + +reverts when trying to authorize or revoke the token's owner as an operator. + +
diff --git a/docs/contracts/LSP7DigitalAsset/presets/LSP7Mintable.md b/docs/contracts/LSP7DigitalAsset/presets/LSP7Mintable.md new file mode 100644 index 000000000..5a3aaaaee --- /dev/null +++ b/docs/contracts/LSP7DigitalAsset/presets/LSP7Mintable.md @@ -0,0 +1,1364 @@ + + + +# LSP7Mintable + +:::info Standard Specifications + +[`LSP-7-DigitalAsset`](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md) + +::: +:::info Solidity implementation + +[`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) + +::: + +> LSP7DigitalAsset deployable preset contract with a public {mint} function callable only by the contract {owner}. + +## Public Methods + +Public methods are accessible externally from users, allowing interaction with this function from dApps or other smart contracts. +When marked as 'public', a method can be called both externally and internally, on the other hand, when marked as 'external', a method can only be called externally. + +### constructor + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#constructor) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) + +::: + +```solidity +constructor( + string name_, + string symbol_, + address newOwner_, + bool isNonDivisible_ +); +``` + +_Deploying a `LSP7Mintable` token contract with: token name = `name_`, token symbol = `symbol_`, and address `newOwner_` as the token contract owner._ + +#### Parameters + +| Name | Type | Description | +| ----------------- | :-------: | -------------------------------- | +| `name_` | `string` | The name of the token. | +| `symbol_` | `string` | The symbol of the token. | +| `newOwner_` | `address` | The owner of the token contract. | +| `isNonDivisible_` | `bool` | - | + +
+ +### authorizeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizeoperator) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `authorizeOperator(address,uint256)` +- Function selector: `0x47980aa3` + +::: + +:::danger + +To avoid front-running and Allowance Double-Spend Exploit when increasing or decreasing the authorized amount of an operator, it is advised to: 1. either call {revokeOperator} first, and then re-call {authorizeOperator} with the new amount. 2. or use the non-standard functions {increaseAllowance} or {decreaseAllowance}. For more information, see: https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/ + +::: + +```solidity +function authorizeOperator( + address operator, + uint256 amount +) external nonpayable; +``` + +Sets an `amount` of tokens that an `operator` has access from the caller's balance (allowance). See [`authorizedAmountFor`](#authorizedamountfor). + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ------------------------------------------------------ | +| `operator` | `address` | The address to authorize as an operator. | +| `amount` | `uint256` | The allowance amount of tokens operator has access to. | + +
+ +### authorizedAmountFor + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizedamountfor) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `authorizedAmountFor(address,address)` +- Function selector: `0x65aeaa95` + +::: + +```solidity +function authorizedAmountFor( + address operator, + address tokenOwner +) external view returns (uint256); +``` + +Get the amount of tokens `operator` address has access to from `tokenOwner`. Operators can send and burn tokens on behalf of their owners. + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | ---------------------------------------------------------- | +| `operator` | `address` | The operator's address to query the authorized amount for. | +| `tokenOwner` | `address` | The token owner that `operator` has allowance on. | + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | --------------------------------------------------------------------------------------- | +| `0` | `uint256` | The amount of tokens the `operator`'s address has access on the `tokenOwner`'s balance. | + +
+ +### balanceOf + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#balanceof) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `balanceOf(address)` +- Function selector: `0x70a08231` + +::: + +```solidity +function balanceOf(address tokenOwner) external view returns (uint256); +``` + +Get the number of tokens owned by `tokenOwner`. If the token is divisible (the [`decimals`](#decimals) function returns `18`), the amount returned should be divided by 1e18 to get a better picture of the actual balance of the `tokenOwner`. _Example:_ `balanceOf(someAddress) -> 42_000_000_000_000_000_000 / 1e18 = 42 tokens` + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | --------------------------------------------------------- | +| `tokenOwner` | `address` | The address of the token holder to query the balance for. | + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ------------------------------------------- | +| `0` | `uint256` | The amount of tokens owned by `tokenOwner`. | + +
+ +### decimals + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#decimals) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `decimals()` +- Function selector: `0x313ce567` + +::: + +```solidity +function decimals() external view returns (uint8); +``` + +Returns the number of decimals used to get its user representation. If the asset contract has been set to be non-divisible via the `isNonDivisible_` parameter in the `constructor`, the decimals returned wiil be `0`. Otherwise `18` is the common value. + +#### Returns + +| Name | Type | Description | +| ---- | :-----: | ----------------------------------------------------------------------- | +| `0` | `uint8` | the number of decimals. If `0` is returned, the asset is non-divisible. | + +
+ +### decreaseAllowance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#decreaseallowance) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `decreaseAllowance(address,uint256)` +- Function selector: `0xa457c2d7` + +::: + +:::info + +This is a non-standard function, not part of the LSP7 standard interface. It has been added in the LSP7 contract implementation so that it can be used as a prevention mechanism against the double spending allowance vulnerability. + +::: + +```solidity +function decreaseAllowance( + address operator, + uint256 substractedAmount +) external nonpayable; +``` + +_Decrease the allowance of `operator` by -`substractedAmount`_ + +Atomically decreases the allowance granted to `operator` by the caller. This is an alternative approach to [`authorizeOperator`](#authorizeoperator) that can be used as a mitigation for the double spending allowance problem. + +
+ +**Requirements:** + +- `operator` cannot be the zero address. +- `operator` must have allowance for the caller of at least `substractedAmount`. + +
+ +
+ +**Emitted events:** + +- [`AuthorizedOperator`](#authorizedoperator) event indicating the updated allowance after decreasing it. +- [`RevokeOperator`](#revokeoperator) event if `substractedAmount` is the full allowance, indicating `operator` does not have any alauthorizedAmountForlowance left for `msg.sender`. + +
+ +#### Parameters + +| Name | Type | Description | +| ------------------- | :-------: | ------------------------------------------------------ | +| `operator` | `address` | the operator to decrease allowance for `msg.sender` | +| `substractedAmount` | `uint256` | the amount to decrease by in the operator's allowance. | + +
+ +### getData + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#getdata) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `getData(bytes32)` +- Function selector: `0x54f6127f` + +::: + +```solidity +function getData(bytes32 dataKey) external view returns (bytes dataValue); +``` + +_Gets singular data at a given `dataKey`_ + +#### Parameters + +| Name | Type | Description | +| --------- | :-------: | ------------------------------- | +| `dataKey` | `bytes32` | The key which value to retrieve | + +#### Returns + +| Name | Type | Description | +| ----------- | :-----: | -------------------------- | +| `dataValue` | `bytes` | The data stored at the key | + +
+ +### getDataBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#getdatabatch) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `getDataBatch(bytes32[])` +- Function selector: `0xdedff9c6` + +::: + +```solidity +function getDataBatch( + bytes32[] dataKeys +) external view returns (bytes[] dataValues); +``` + +_Gets array of data for multiple given keys_ + +#### Parameters + +| Name | Type | Description | +| ---------- | :---------: | ------------------------------------------ | +| `dataKeys` | `bytes32[]` | The array of keys which values to retrieve | + +#### Returns + +| Name | Type | Description | +| ------------ | :-------: | ----------------------------------------- | +| `dataValues` | `bytes[]` | The array of data stored at multiple keys | + +
+ +### increaseAllowance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#increaseallowance) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `increaseAllowance(address,uint256)` +- Function selector: `0x39509351` + +::: + +:::info + +This is a non-standard function, not part of the LSP7 standard interface. It has been added in the LSP7 contract implementation so that it can be used as a prevention mechanism against double spending allowance vulnerability. + +::: + +```solidity +function increaseAllowance( + address operator, + uint256 addedAmount +) external nonpayable; +``` + +_Increase the allowance of `operator` by +`addedAmount`_ + +Atomically increases the allowance granted to `operator` by the caller. This is an alternative approach to [`authorizeOperator`](#authorizeoperator) that can be used as a mitigation for the double spending allowance problem. + +
+ +**Requirements:** + +- `operator` cannot be the same address as `msg.sender` +- `operator` cannot be the zero address. + +
+ +
+ +**Emitted events:** + +- [`AuthorizedOperator`](#authorizedoperator) indicating the updated allowance + +
+ +#### Parameters + +| Name | Type | Description | +| ------------- | :-------: | ----------------------------------------------------------------------- | +| `operator` | `address` | the operator to increase the allowance for `msg.sender` | +| `addedAmount` | `uint256` | the additional amount to add on top of the current operator's allowance | + +
+ +### mint + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#mint) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `mint(address,uint256,bool,bytes)` +- Function selector: `0x7580d920` + +::: + +```solidity +function mint( + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) external nonpayable; +``` + +Public [`_mint`](#_mint) function only callable by the [`owner`](#owner). + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ----------- | +| `to` | `address` | - | +| `amount` | `uint256` | - | +| `allowNonLSP1Recipient` | `bool` | - | +| `data` | `bytes` | - | + +
+ +### owner + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#owner) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `owner()` +- Function selector: `0x8da5cb5b` + +::: + +```solidity +function owner() external view returns (address); +``` + +Returns the address of the current owner. + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ----------- | +| `0` | `address` | - | + +
+ +### renounceOwnership + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#renounceownership) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `renounceOwnership()` +- Function selector: `0x715018a6` + +::: + +```solidity +function renounceOwnership() external nonpayable; +``` + +Leaves the contract without owner. It will not be possible to call `onlyOwner` functions anymore. Can only be called by the current owner. NOTE: Renouncing ownership will leave the contract without an owner, thereby removing any functionality that is only available to the owner. + +
+ +### revokeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#revokeoperator) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `revokeOperator(address)` +- Function selector: `0xfad8b32a` + +::: + +```solidity +function revokeOperator(address operator) external nonpayable; +``` + +Removes the `operator` address as an operator of callers tokens, disallowing it to send any amount of tokens on behalf of the token owner (the caller of the function `msg.sender`). See also [`authorizedAmountFor`](#authorizedamountfor). + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ------------------------------------- | +| `operator` | `address` | The address to revoke as an operator. | + +
+ +### setData + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#setdata) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `setData(bytes32,bytes)` +- Function selector: `0x7f23690c` + +::: + +```solidity +function setData(bytes32 dataKey, bytes dataValue) external payable; +``` + +_Sets singular data for a given `dataKey`_ + +#### Parameters + +| Name | Type | Description | +| ----------- | :-------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dataKey` | `bytes32` | The key to retrieve stored value | +| `dataValue` | `bytes` | The value to set SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal 0. Emits a {DataChanged} event. | + +
+ +### setDataBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#setdatabatch) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `setDataBatch(bytes32[],bytes[])` +- Function selector: `0x97902421` + +::: + +```solidity +function setDataBatch(bytes32[] dataKeys, bytes[] dataValues) external payable; +``` + +Sets array of data for multiple given `dataKeys` SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal + +0. Emits a [`DataChanged`](#datachanged) event. + +#### Parameters + +| Name | Type | Description | +| ------------ | :---------: | ---------------------------------------- | +| `dataKeys` | `bytes32[]` | The array of data keys for values to set | +| `dataValues` | `bytes[]` | The array of values to set | + +
+ +### supportsInterface + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#supportsinterface) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `supportsInterface(bytes4)` +- Function selector: `0x01ffc9a7` + +::: + +```solidity +function supportsInterface(bytes4 interfaceId) external view returns (bool); +``` + +Returns true if this contract implements the interface defined by `interfaceId`. See the corresponding https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section] to learn more about how these ids are created. This function call must use less than 30 000 gas. + +#### Parameters + +| Name | Type | Description | +| ------------- | :------: | ----------- | +| `interfaceId` | `bytes4` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :----: | ----------- | +| `0` | `bool` | - | + +
+ +### totalSupply + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#totalsupply) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `totalSupply()` +- Function selector: `0x18160ddd` + +::: + +```solidity +function totalSupply() external view returns (uint256); +``` + +Returns the number of existing tokens that have been minted in this contract. + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ------------------------------ | +| `0` | `uint256` | The number of existing tokens. | + +
+ +### transfer + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transfer) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `transfer(address,address,uint256,bool,bytes)` +- Function selector: `0x760d9bba` + +::: + +```solidity +function transfer( + address from, + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) external nonpayable; +``` + +Transfers an `amount` of tokens from the `from` address to the `to` address and notify both sender and recipients via the LSP1 [`universalReceiver(...)`](#`universalreceiver) function. If the tokens are transferred by an operator on behalf of a token holder, the allowance for the operator will be decreased by `amount` once the token transfer has been completed (See [`authorizedAmountFor`](#authorizedamountfor)). + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address` | The sender address. | +| `to` | `address` | The recipient address. | +| `amount` | `uint256` | The amount of tokens to transfer. | +| `allowNonLSP1Recipient` | `bool` | When set to `true`, the `to` address CAN be any address. When set to `false`, the `to` address MUST be a contract that supports the LSP1 UniversalReceiver standard. | +| `data` | `bytes` | Any additional data the caller wants included in the emitted event, and sent in the hooks of the `from` and `to` addresses. | + +
+ +### transferBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transferbatch) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `transferBatch(address[],address[],uint256[],bool[],bytes[])` +- Function selector: `0x2d7667c9` + +::: + +```solidity +function transferBatch( + address[] from, + address[] to, + uint256[] amount, + bool[] allowNonLSP1Recipient, + bytes[] data +) external nonpayable; +``` + +Same as [`transfer(...)`](#`transfer) but transfer multiple tokens based on the arrays of `from`, `to`, `amount`. + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :---------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address[]` | An array of sending addresses. | +| `to` | `address[]` | An array of receiving addresses. | +| `amount` | `uint256[]` | An array of amount of tokens to transfer for each `from -> to` transfer. | +| `allowNonLSP1Recipient` | `bool[]` | For each transfer, when set to `true`, the `to` address CAN be any address. When set to `false`, the `to` address MUST be a contract that supports the LSP1 UniversalReceiver standard. | +| `data` | `bytes[]` | An array of additional data the caller wants included in the emitted event, and sent in the hooks to `from` and `to` addresses. | + +
+ +### transferOwnership + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transferownership) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Function signature: `transferOwnership(address)` +- Function selector: `0xf2fde38b` + +::: + +```solidity +function transferOwnership(address newOwner) external nonpayable; +``` + +Transfers ownership of the contract to a new account (`newOwner`). Can only be called by the current owner. + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ----------- | +| `newOwner` | `address` | - | + +
+ +## Internal Methods + +Any method labeled as `internal` serves as utility function within the contract. They can be used when writing solidity contracts that inherit from this contract. These methods can be extended or modified by overriding their internal behavior to suit specific needs. + +Internal functions cannot be called externally, whether from other smart contracts, dApp interfaces, or backend services. Their restricted accessibility ensures that they remain exclusively available within the context of the current contract, promoting controlled and encapsulated usage of these internal utilities. + +### \_checkOwner + +```solidity +function _checkOwner() internal view; +``` + +Throws if the sender is not the owner. + +
+ +### \_setOwner + +```solidity +function _setOwner(address newOwner) internal nonpayable; +``` + +Changes the owner if `newOwner` and oldOwner are different +This pattern is useful in inheritance. + +
+ +### \_getData + +```solidity +function _getData(bytes32 dataKey) internal view returns (bytes dataValue); +``` + +
+ +### \_setData + +```solidity +function _setData(bytes32 dataKey, bytes dataValue) internal nonpayable; +``` + +Save gas by emitting the [`DataChanged`](#datachanged) event with only the first 256 bytes of dataValue + +
+ +### \_updateOperator + +```solidity +function _updateOperator( + address tokenOwner, + address operator, + uint256 amount +) internal nonpayable; +``` + +Changes token `amount` the `operator` has access to from `tokenOwner` tokens. +If the amount is zero then the operator is being revoked, otherwise the operator amount is being modified. + +
+ +### \_mint + +```solidity +function _mint( + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) internal nonpayable; +``` + +Mints `amount` of tokens and transfers it to `to`. + +
+ +**Emitted events:** + +- [`Transfer`](#transfer) event with `address(0)` as `from`. + +
+ +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ------------------------------------------------------------------------------------------------------------------------- | +| `to` | `address` | the address to mint tokens for. | +| `amount` | `uint256` | the amount of tokens to mint. | +| `allowNonLSP1Recipient` | `bool` | a boolean that describe if transfer to a `to` address that does not support LSP1 is allowed or not. | +| `data` | `bytes` | Additional data the caller wants included in the emitted {Transfer} event, and sent in the LSP1 hook to the `to` address. | + +
+ +### \_burn + +:::tip Hint + +In dApps, you can know which address is burning tokens by listening for the `Transfer` event and filter with the zero address as `to`. + +::: + +```solidity +function _burn(address from, uint256 amount, bytes data) internal nonpayable; +``` + +Burns (= destroys) `amount` of tokens, decrease the `from` balance. This is done by sending them to the zero address. +Both the sender and recipient will be notified of the token transfer through the LSP1 [`universalReceiver`](#universalreceiver) +function, if they are contracts that support the LSP1 interface. Their `universalReceiver` function will receive +all the parameters in the calldata packed encoded. +Any logic in the [`_beforeTokenTransfer`](#_beforetokentransfer) function will run before updating the balances. + +
+ +**Emitted events:** + +- [`Transfer`](#transfer) event with `address(0)` as the `to` address + +
+ +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address` | the address to burn tokens from its balance. | +| `amount` | `uint256` | the amount of tokens to burn. | +| `data` | `bytes` | Additional data the caller wants included in the emitted event, and sent in the LSP1 hook to the `from` and `to` address. | + +
+ +### \_transfer + +```solidity +function _transfer( + address from, + address to, + uint256 amount, + bool allowNonLSP1Recipient, + bytes data +) internal nonpayable; +``` + +Transfer tokens from `from` to `to` by decreasing the balance of `from` by `-amount` and increasing the balance +of `to` by `+amount`. +Both the sender and recipient will be notified of the token transfer through the LSP1 [`universalReceiver`](#universalreceiver) +function, if they are contracts that support the LSP1 interface. Their `universalReceiver` function will receive +all the parameters in the calldata packed encoded. +Any logic in the [`_beforeTokenTransfer`](#_beforetokentransfer) function will run before updating the balances. + +
+ +**Emitted events:** + +- [`Transfer`](#transfer) event. + +
+ +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ------------------------------------------------------------------------------------------------------------------------- | +| `from` | `address` | the address to decrease the balance. | +| `to` | `address` | the address to increase the balance. | +| `amount` | `uint256` | the amount of tokens to transfer from `from` to `to`. | +| `allowNonLSP1Recipient` | `bool` | a boolean that describe if transfer to a `to` address that does not support LSP1 is allowed or not. | +| `data` | `bytes` | Additional data the caller wants included in the emitted event, and sent in the LSP1 hook to the `from` and `to` address. | + +
+ +### \_beforeTokenTransfer + +```solidity +function _beforeTokenTransfer( + address from, + address to, + uint256 amount +) internal nonpayable; +``` + +Hook that is called before any token transfer, including minting and burning. +Allows to run custom logic before updating balances and notifiying sender/recipient by overriding this function. + +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ------------------------------- | +| `from` | `address` | The sender address | +| `to` | `address` | The recipient address | +| `amount` | `uint256` | The amount of token to transfer | + +
+ +### \_notifyTokenSender + +```solidity +function _notifyTokenSender(address from, bytes lsp1Data) internal nonpayable; +``` + +Attempt to notify the token sender `from` about the `amount` of tokens being transferred. +This is done by calling its [`universalReceiver`](#universalreceiver) function with the `_TYPEID_LSP7_TOKENSSENDER` as typeId, if `from` is a contract that supports the LSP1 interface. +If `from` is an EOA or a contract that does not support the LSP1 interface, nothing will happen and no notification will be sent. + +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | -------------------------------------------------------------------------- | +| `from` | `address` | The address to call the {universalReceiver} function on. | +| `lsp1Data` | `bytes` | the data to be sent to the `from` address in the `universalReceiver` call. | + +
+ +### \_notifyTokenReceiver + +```solidity +function _notifyTokenReceiver( + address to, + bool allowNonLSP1Recipient, + bytes lsp1Data +) internal nonpayable; +``` + +Attempt to notify the token receiver `to` about the `amount` tokens being received. +This is done by calling its [`universalReceiver`](#universalreceiver) function with the `_TYPEID_LSP7_TOKENSRECIPIENT` as typeId, if `to` is a contract that supports the LSP1 interface. +If `to` is is an EOA or a contract that does not support the LSP1 interface, the behaviour will depend on the `allowNonLSP1Recipient` boolean flag. + +- if `allowNonLSP1Recipient` is set to `true`, nothing will happen and no notification will be sent. + +- if `allowNonLSP1Recipient` is set to `false, the transaction will revert. + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | --------------------------------------------------------------------------------------------------- | +| `to` | `address` | The address to call the {universalReceiver} function on. | +| `allowNonLSP1Recipient` | `bool` | a boolean that describe if transfer to a `to` address that does not support LSP1 is allowed or not. | +| `lsp1Data` | `bytes` | the data to be sent to the `to` address in the `universalReceiver(...)` call. | + +
+ +## Events + +### AuthorizedOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#authorizedoperator) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Event signature: `AuthorizedOperator(address,address,uint256)` +- Event topic hash: `0xd66aff874162a96578e919097b6f6d153dfd89a5cec41bb331fdb0c4aec16e2c` + +::: + +```solidity +event AuthorizedOperator(address indexed operator, address indexed tokenOwner, uint256 indexed amount); +``` + +Emitted when `tokenOwner` enables `operator` for `tokenId`. + +#### Parameters + +| Name | Type | Description | +| -------------------------- | :-------: | ----------------------------------------------------------------------- | +| `operator` **`indexed`** | `address` | The address authorized as an operator | +| `tokenOwner` **`indexed`** | `address` | The token owner | +| `amount` **`indexed`** | `uint256` | The amount of tokens `operator` address has access to from `tokenOwner` | + +
+ +### DataChanged + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#datachanged) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Event signature: `DataChanged(bytes32,bytes)` +- Event topic hash: `0xece574603820d07bc9b91f2a932baadf4628aabcb8afba49776529c14a6104b2` + +::: + +```solidity +event DataChanged(bytes32 indexed dataKey, bytes dataValue); +``` + +_Emitted when data at a key is changed_ + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ------------------------------------ | +| `dataKey` **`indexed`** | `bytes32` | The data key which data value is set | +| `dataValue` | `bytes` | The data value to set | + +
+ +### OwnershipTransferred + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#ownershiptransferred) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Event signature: `OwnershipTransferred(address,address)` +- Event topic hash: `0x8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0` + +::: + +```solidity +event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); +``` + +#### Parameters + +| Name | Type | Description | +| ----------------------------- | :-------: | ----------- | +| `previousOwner` **`indexed`** | `address` | - | +| `newOwner` **`indexed`** | `address` | - | + +
+ +### RevokedOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#revokedoperator) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Event signature: `RevokedOperator(address,address)` +- Event topic hash: `0x50546e66e5f44d728365dc3908c63bc5cfeeab470722c1677e3073a6ac294aa1` + +::: + +```solidity +event RevokedOperator(address indexed operator, address indexed tokenOwner); +``` + +Emitted when `tokenOwner` disables `operator` for `tokenId`. + +#### Parameters + +| Name | Type | Description | +| -------------------------- | :-------: | ---------------------------------- | +| `operator` **`indexed`** | `address` | The address revoked from operating | +| `tokenOwner` **`indexed`** | `address` | The token owner | + +
+ +### Transfer + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#transfer) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Event signature: `Transfer(address,address,address,uint256,bool,bytes)` +- Event topic hash: `0x3997e418d2cef0b3b0e907b1e39605c3f7d32dbd061e82ea5b4a770d46a160a6` + +::: + +```solidity +event Transfer(address indexed operator, address indexed from, address indexed to, uint256 amount, bool allowNonLSP1Recipient, bytes data); +``` + +Emitted when `tokenId` token is transferred from `from` to `to`. + +#### Parameters + +| Name | Type | Description | +| ------------------------ | :-------: | ---------------------------------------------------------------------------------------------------------------------------- | +| `operator` **`indexed`** | `address` | The address of operator sending tokens | +| `from` **`indexed`** | `address` | The address which tokens are sent | +| `to` **`indexed`** | `address` | The receiving address | +| `amount` | `uint256` | The amount of tokens transferred. | +| `allowNonLSP1Recipient` | `bool` | When set to TRUE, `to` may be any address but when set to FALSE `to` must be a contract that supports LSP1 UniversalReceiver | +| `data` | `bytes` | Additional data the caller wants included in the emitted event, and sent in the hooks to `from` and `to` addresses | + +
+ +## Errors + +### ERC725Y_DataKeysValuesEmptyArray + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_datakeysvaluesemptyarray) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `ERC725Y_DataKeysValuesEmptyArray()` +- Error hash: `0x97da5f95` + +::: + +```solidity +error ERC725Y_DataKeysValuesEmptyArray(); +``` + +reverts when one of the array parameter provided to `setDataBatch` is an empty array + +
+ +### ERC725Y_DataKeysValuesLengthMismatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_datakeysvalueslengthmismatch) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `ERC725Y_DataKeysValuesLengthMismatch()` +- Error hash: `0x3bcc8979` + +::: + +```solidity +error ERC725Y_DataKeysValuesLengthMismatch(); +``` + +reverts when there is not the same number of elements in the lists of data keys and data values when calling setDataBatch. + +
+ +### ERC725Y_MsgValueDisallowed + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#erc725y_msgvaluedisallowed) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `ERC725Y_MsgValueDisallowed()` +- Error hash: `0xf36ba737` + +::: + +```solidity +error ERC725Y_MsgValueDisallowed(); +``` + +reverts when sending value to the `setData(..)` functions + +
+ +### LSP4TokenNameNotEditable + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp4tokennamenoteditable) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `LSP4TokenNameNotEditable()` +- Error hash: `0x85c169bd` + +::: + +```solidity +error LSP4TokenNameNotEditable(); +``` + +Reverts when trying to edit the data key `LSP4TokenName` after the digital asset contract has been deployed. The `LSP4TokenName` data key is located inside the ERC725Y Data key-value store of the digital asset contract. It can be set only once inside the constructor/initializer when the digital asset contract is being deployed. + +
+ +### LSP4TokenSymbolNotEditable + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp4tokensymbolnoteditable) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `LSP4TokenSymbolNotEditable()` +- Error hash: `0x76755b38` + +::: + +```solidity +error LSP4TokenSymbolNotEditable(); +``` + +Reverts when trying to edit the data key `LSP4TokenSymbol` after the digital asset contract has been deployed. The `LSP4TokenSymbol` data key is located inside the ERC725Y Data key-value store of the digital asset contract. It can be set only once inside the constructor/initializer when the digital asset contract is being deployed. + +
+ +### LSP7AmountExceedsAuthorizedAmount + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7amountexceedsauthorizedamount) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `LSP7AmountExceedsAuthorizedAmount(address,uint256,address,uint256)` +- Error hash: `0xf3a6b691` + +::: + +```solidity +error LSP7AmountExceedsAuthorizedAmount( + address tokenOwner, + uint256 authorizedAmount, + address operator, + uint256 amount +); +``` + +reverts when `operator` of `tokenOwner` send an `amount` of tokens larger than the `authorizedAmount`. + +#### Parameters + +| Name | Type | Description | +| ------------------ | :-------: | ----------- | +| `tokenOwner` | `address` | - | +| `authorizedAmount` | `uint256` | - | +| `operator` | `address` | - | +| `amount` | `uint256` | - | + +
+ +### LSP7AmountExceedsBalance + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7amountexceedsbalance) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `LSP7AmountExceedsBalance(uint256,address,uint256)` +- Error hash: `0x08d47949` + +::: + +```solidity +error LSP7AmountExceedsBalance( + uint256 balance, + address tokenOwner, + uint256 amount +); +``` + +reverts when sending an `amount` of tokens larger than the current `balance` of the `tokenOwner`. + +#### Parameters + +| Name | Type | Description | +| ------------ | :-------: | ----------- | +| `balance` | `uint256` | - | +| `tokenOwner` | `address` | - | +| `amount` | `uint256` | - | + +
+ +### LSP7CannotSendToSelf + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotsendtoself) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `LSP7CannotSendToSelf()` +- Error hash: `0xb9afb000` + +::: + +```solidity +error LSP7CannotSendToSelf(); +``` + +reverts when specifying the same address for `from` or `to` in a token transfer. + +
+ +### LSP7CannotSendWithAddressZero + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotsendwithaddresszero) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `LSP7CannotSendWithAddressZero()` +- Error hash: `0xd2d5ec30` + +::: + +```solidity +error LSP7CannotSendWithAddressZero(); +``` + +reverts when trying to: + +- mint tokens to the zero address. + +- burn tokens from the zero address. + +- transfer tokens from or to the zero address. + +
+ +### LSP7CannotUseAddressZeroAsOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7cannotuseaddresszeroasoperator) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `LSP7CannotUseAddressZeroAsOperator()` +- Error hash: `0x6355e766` + +::: + +```solidity +error LSP7CannotUseAddressZeroAsOperator(); +``` + +reverts when trying to set the zero address as an operator. + +
+ +### LSP7DecreasedAllowanceBelowZero + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7decreasedallowancebelowzero) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `LSP7DecreasedAllowanceBelowZero()` +- Error hash: `0x0ef76c35` + +::: + +```solidity +error LSP7DecreasedAllowanceBelowZero(); +``` + +Reverts when trying to decrease an operator's allowance to more than its current allowance. + +
+ +### LSP7InvalidTransferBatch + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7invalidtransferbatch) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `LSP7InvalidTransferBatch()` +- Error hash: `0x263eee8d` + +::: + +```solidity +error LSP7InvalidTransferBatch(); +``` + +reverts when the array parameters used in [`transferBatch`](#transferbatch) have different lengths. + +
+ +### LSP7NotifyTokenReceiverContractMissingLSP1Interface + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7notifytokenreceivercontractmissinglsp1interface) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `LSP7NotifyTokenReceiverContractMissingLSP1Interface(address)` +- Error hash: `0xa608fbb6` + +::: + +```solidity +error LSP7NotifyTokenReceiverContractMissingLSP1Interface( + address tokenReceiver +); +``` + +reverts if the `tokenReceiver` does not implement LSP1 when minting or transferring tokens with `bool allowNonLSP1Recipient` set as `false`. + +#### Parameters + +| Name | Type | Description | +| --------------- | :-------: | ----------- | +| `tokenReceiver` | `address` | - | + +
+ +### LSP7NotifyTokenReceiverIsEOA + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7notifytokenreceiveriseoa) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `LSP7NotifyTokenReceiverIsEOA(address)` +- Error hash: `0x26c247f4` + +::: + +```solidity +error LSP7NotifyTokenReceiverIsEOA(address tokenReceiver); +``` + +reverts if the `tokenReceiver` is an EOA when minting or transferring tokens with `bool allowNonLSP1Recipient` set as `false`. + +#### Parameters + +| Name | Type | Description | +| --------------- | :-------: | ----------- | +| `tokenReceiver` | `address` | - | + +
+ +### LSP7TokenOwnerCannotBeOperator + +:::note References + +- Specification details: [**LSP-7-DigitalAsset**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-7-DigitalAsset.md#lsp7tokenownercannotbeoperator) +- Solidity implementation: [`LSP7Mintable.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP7DigitalAsset/presets/LSP7Mintable.sol) +- Error signature: `LSP7TokenOwnerCannotBeOperator()` +- Error hash: `0xdab75047` + +::: + +```solidity +error LSP7TokenOwnerCannotBeOperator(); +``` + +reverts when trying to authorize or revoke the token's owner as an operator. + +