feat: add mint and call (#35)

* feat: move utilities and custom errors to a library * feat: add ERC1363Mintable contract * docs: update code analysis folder
vittominacori · Sep 4, 2024 · 39aaea5 · 39aaea5
1 parent a8a0e0a
commit 39aaea5
Show file tree

Hide file tree

Showing 24 changed files with 2,450 additions and 601 deletions.
diff --git a/README.md b/README.md
@@ -91,11 +91,11 @@ interface IERC1363Spender {
 }
 ```
 
-### IERC1363Errors
+### ERC1363Utils
 
-[IERC1363Errors.sol](https://github.com/vittominacori/erc1363-payable-token/blob/master/contracts/token/ERC1363/IERC1363Errors.sol)
+[ERC1363Utils.sol](https://github.com/vittominacori/erc1363-payable-token/blob/master/contracts/token/ERC1363/ERC1363Utils.sol)
 
-Interface of the ERC-1363 custom errors following the [ERC-6093](https://eips.ethereum.org/EIPS/eip-6093) rationale.
+Library that provides common ERC-1363 utility functions and custom errors.
 
 ### ERC1363
 
@@ -106,16 +106,52 @@ Implementation of the ERC-1363 interface.
 The reference implementation of ERC-1363 that extends ERC-20 and adds support for executing code after transfers and approvals on recipient contracts.
 
 > [!IMPORTANT]
-> `transferAndCall`, `transferFromAndCall` and `approveAndCall` revert if the recipient/spender is an EOA address. 
+> `transferAndCall`, `transferFromAndCall` and `approveAndCall` revert if the recipient/spender is an EOA (Externally Owned Account). 
 > 
 > To transfer tokens to an EOA or approve it to spend tokens, use the ERC-20 `transfer`, `transferFrom` or `approve` methods.
 
+## Extensions
+
+### ERC1363Mintable
+
+[ERC1363Mintable.sol](https://github.com/vittominacori/erc1363-payable-token/blob/master/contracts/token/ERC1363/extensions/ERC1363Mintable.sol)
+
+An extension of ERC-1363 that adds a `_mintAndCall` method. 
+
+This method allows to mint new tokens to a receiver contract and then call the `onTransferReceived` callback.
+
+> [!NOTE]
+> `_mintAndCall` is an internal method, and you should call it from your derived contract.
+>
+> For instance, you may choose to check if the receiver is a contract or an EOA and call the `_mint` method instead.
+>
+> ```solidity
+> pragma solidity ^0.8.20;
+> 
+> // other imports
+> import "erc-payable-token/contracts/token/ERC1363/extensions/ERC1363Mintable.sol";
+> 
+> contract MyToken is ERC1363Mintable, Ownable {
+>     // your stuff
+>
+>     function safeMint(address account, uint256 value, bytes memory data) public onlyOwner {
+>         if (account.code.length == 0) {
+>             _mint(account, value);
+>         } else {
+>             _mintAndCall(account, value, data);
+>         }
+>     }
+>
+>     // your stuff
+> }
+> ```
+
 ## Presets
 
 > [!WARNING]
 > The `presets` contracts are ideas and suggestions for using ERC-1363 tokens within your contracts. 
 > 
-> When inheriting and copying from these contracts, you must include a way to use the received tokens, otherwise they will be stuck into the contract.
+> When inheriting or copying from these contracts, you must include a way to use the received tokens, otherwise they will be stuck into the contract.
 > 
 > Always test your contracts before going live.
 
@@ -188,10 +224,18 @@ It executes the method passed via `data`. Methods emit a `MethodCall` event.
 
 ## Code Analysis
 
-* [Control Flow](https://raw.githubusercontent.com/vittominacori/erc1363-payable-token/master/analysis/control-flow/ERC1363.png)
-* [Description Table](https://github.com/vittominacori/erc1363-payable-token/blob/master/analysis/description-table/ERC1363.md)
-* [Inheritance Tree](https://raw.githubusercontent.com/vittominacori/erc1363-payable-token/master/analysis/inheritance-tree/ERC1363.png)
-* [UML](https://raw.githubusercontent.com/vittominacori/erc1363-payable-token/master/analysis/uml/ERC1363.svg)
+- Control Flow
+  - [ERC1363](https://raw.githubusercontent.com/vittominacori/erc1363-payable-token/master/analysis/control-flow/ERC1363.png)
+  - [ERC1363Mintable](https://raw.githubusercontent.com/vittominacori/erc1363-payable-token/master/analysis/control-flow/ERC1363Mintable.png)
+- Description Table
+  - [ERC1363](https://github.com/vittominacori/erc1363-payable-token/blob/master/analysis/description-table/ERC1363.md)
+  - [ERC1363Mintable](https://github.com/vittominacori/erc1363-payable-token/blob/master/analysis/description-table/ERC1363Mintable.md)
+- Inheritance Tree
+  - [ERC1363](https://raw.githubusercontent.com/vittominacori/erc1363-payable-token/master/analysis/inheritance-tree/ERC1363.png)
+  - [ERC1363Mintable](https://raw.githubusercontent.com/vittominacori/erc1363-payable-token/master/analysis/inheritance-tree/ERC1363Mintable.png)
+- UML
+  - [ERC1363](https://raw.githubusercontent.com/vittominacori/erc1363-payable-token/master/analysis/uml/ERC1363.svg)
+  - [ERC1363Mintable](https://raw.githubusercontent.com/vittominacori/erc1363-payable-token/master/analysis/uml/ERC1363Mintable.svg)
 
 ## Development
 

diff --git a/analysis/control-flow/ERC1363.png b/analysis/control-flow/ERC1363.png
diff --git a/analysis/control-flow/ERC1363Mintable.png b/analysis/control-flow/ERC1363Mintable.png
diff --git a/analysis/description-table/ERC1363.md b/analysis/description-table/ERC1363.md
@@ -64,6 +64,16 @@
 | **ERC165** | Implementation | IERC165 |||
 | └ | supportsInterface | Public ❗️ |   |NO❗️ |
 ||||||
+| **IERC1363Receiver** | Interface |  |||
+| └ | onTransferReceived | External ❗️ | 🛑  |NO❗️ |
+||||||
+| **IERC1363Spender** | Interface |  |||
+| └ | onApprovalReceived | External ❗️ | 🛑  |NO❗️ |
+||||||
+| **ERC1363Utils** | Library |  |||
+| └ | checkOnERC1363TransferReceived | Internal 🔒 | 🛑  | |
+| └ | checkOnERC1363ApprovalReceived | Internal 🔒 | 🛑  | |
+||||||
 | **IERC1363** | Interface | IERC20, IERC165 |||
 | └ | transferAndCall | External ❗️ | 🛑  |NO❗️ |
 | └ | transferAndCall | External ❗️ | 🛑  |NO❗️ |
@@ -72,24 +82,14 @@
 | └ | approveAndCall | External ❗️ | 🛑  |NO❗️ |
 | └ | approveAndCall | External ❗️ | 🛑  |NO❗️ |
 ||||||
-| **IERC1363Errors** | Interface |  |||
-||||||
-| **IERC1363Receiver** | Interface |  |||
-| └ | onTransferReceived | External ❗️ | 🛑  |NO❗️ |
-||||||
-| **IERC1363Spender** | Interface |  |||
-| └ | onApprovalReceived | External ❗️ | 🛑  |NO❗️ |
-||||||
-| **ERC1363** | Implementation | ERC20, ERC165, IERC1363, IERC1363Errors |||
+| **ERC1363** | Implementation | ERC20, ERC165, IERC1363 |||
 | └ | supportsInterface | Public ❗️ |   |NO❗️ |
 | └ | transferAndCall | Public ❗️ | 🛑  |NO❗️ |
 | └ | transferAndCall | Public ❗️ | 🛑  |NO❗️ |
 | └ | transferFromAndCall | Public ❗️ | 🛑  |NO❗️ |
 | └ | transferFromAndCall | Public ❗️ | 🛑  |NO❗️ |
 | └ | approveAndCall | Public ❗️ | 🛑  |NO❗️ |
 | └ | approveAndCall | Public ❗️ | 🛑  |NO❗️ |
-| └ | _checkOnERC1363TransferReceived | Private 🔐 | 🛑  | |
-| └ | _checkOnERC1363ApprovalReceived | Private 🔐 | 🛑  | |
 
 
 ### Legend

diff --git a/analysis/description-table/ERC1363Mintable.md b/analysis/description-table/ERC1363Mintable.md
@@ -0,0 +1,104 @@
+## Sūrya's Description Report
+
+### Files Description Table
+
+
+|  File Name  |  SHA-1 Hash  |
+|-------------|--------------|
+| dist/ERC1363Mintable.dist.sol | [object Promise] |
+
+
+### Contracts Description Table
+
+
+|  Contract  |         Type        |       Bases      |                  |                 |
+|:----------:|:-------------------:|:----------------:|:----------------:|:---------------:|
+|     └      |  **Function Name**  |  **Visibility**  |  **Mutability**  |  **Modifiers**  |
+||||||
+| **IERC20Errors** | Interface |  |||
+||||||
+| **IERC721Errors** | Interface |  |||
+||||||
+| **IERC1155Errors** | Interface |  |||
+||||||
+| **IERC20** | Interface |  |||
+| └ | totalSupply | External ❗️ |   |NO❗️ |
+| └ | balanceOf | External ❗️ |   |NO❗️ |
+| └ | transfer | External ❗️ | 🛑  |NO❗️ |
+| └ | allowance | External ❗️ |   |NO❗️ |
+| └ | approve | External ❗️ | 🛑  |NO❗️ |
+| └ | transferFrom | External ❗️ | 🛑  |NO❗️ |
+||||||
+| **IERC20Metadata** | Interface | IERC20 |||
+| └ | name | External ❗️ |   |NO❗️ |
+| └ | symbol | External ❗️ |   |NO❗️ |
+| └ | decimals | External ❗️ |   |NO❗️ |
+||||||
+| **Context** | Implementation |  |||
+| └ | _msgSender | Internal 🔒 |   | |
+| └ | _msgData | Internal 🔒 |   | |
+| └ | _contextSuffixLength | Internal 🔒 |   | |
+||||||
+| **ERC20** | Implementation | Context, IERC20, IERC20Metadata, IERC20Errors |||
+| └ | <Constructor> | Public ❗️ | 🛑  |NO❗️ |
+| └ | name | Public ❗️ |   |NO❗️ |
+| └ | symbol | Public ❗️ |   |NO❗️ |
+| └ | decimals | Public ❗️ |   |NO❗️ |
+| └ | totalSupply | Public ❗️ |   |NO❗️ |
+| └ | balanceOf | Public ❗️ |   |NO❗️ |
+| └ | transfer | Public ❗️ | 🛑  |NO❗️ |
+| └ | allowance | Public ❗️ |   |NO❗️ |
+| └ | approve | Public ❗️ | 🛑  |NO❗️ |
+| └ | transferFrom | Public ❗️ | 🛑  |NO❗️ |
+| └ | _transfer | Internal 🔒 | 🛑  | |
+| └ | _update | Internal 🔒 | 🛑  | |
+| └ | _mint | Internal 🔒 | 🛑  | |
+| └ | _burn | Internal 🔒 | 🛑  | |
+| └ | _approve | Internal 🔒 | 🛑  | |
+| └ | _approve | Internal 🔒 | 🛑  | |
+| └ | _spendAllowance | Internal 🔒 | 🛑  | |
+||||||
+| **IERC165** | Interface |  |||
+| └ | supportsInterface | External ❗️ |   |NO❗️ |
+||||||
+| **ERC165** | Implementation | IERC165 |||
+| └ | supportsInterface | Public ❗️ |   |NO❗️ |
+||||||
+| **IERC1363Receiver** | Interface |  |||
+| └ | onTransferReceived | External ❗️ | 🛑  |NO❗️ |
+||||||
+| **IERC1363Spender** | Interface |  |||
+| └ | onApprovalReceived | External ❗️ | 🛑  |NO❗️ |
+||||||
+| **ERC1363Utils** | Library |  |||
+| └ | checkOnERC1363TransferReceived | Internal 🔒 | 🛑  | |
+| └ | checkOnERC1363ApprovalReceived | Internal 🔒 | 🛑  | |
+||||||
+| **IERC1363** | Interface | IERC20, IERC165 |||
+| └ | transferAndCall | External ❗️ | 🛑  |NO❗️ |
+| └ | transferAndCall | External ❗️ | 🛑  |NO❗️ |
+| └ | transferFromAndCall | External ❗️ | 🛑  |NO❗️ |
+| └ | transferFromAndCall | External ❗️ | 🛑  |NO❗️ |
+| └ | approveAndCall | External ❗️ | 🛑  |NO❗️ |
+| └ | approveAndCall | External ❗️ | 🛑  |NO❗️ |
+||||||
+| **ERC1363** | Implementation | ERC20, ERC165, IERC1363 |||
+| └ | supportsInterface | Public ❗️ |   |NO❗️ |
+| └ | transferAndCall | Public ❗️ | 🛑  |NO❗️ |
+| └ | transferAndCall | Public ❗️ | 🛑  |NO❗️ |
+| └ | transferFromAndCall | Public ❗️ | 🛑  |NO❗️ |
+| └ | transferFromAndCall | Public ❗️ | 🛑  |NO❗️ |
+| └ | approveAndCall | Public ❗️ | 🛑  |NO❗️ |
+| └ | approveAndCall | Public ❗️ | 🛑  |NO❗️ |
+||||||
+| **ERC1363Mintable** | Implementation | ERC1363 |||
+| └ | _mintAndCall | Internal 🔒 | 🛑  | |
+| └ | _mintAndCall | Internal 🔒 | 🛑  | |
+
+
+### Legend
+
+|  Symbol  |  Meaning  |
+|:--------:|-----------|
+|    🛑    | Function can modify state |
+|    💵    | Function is payable |
diff --git a/analysis/inheritance-tree/ERC1363.png b/analysis/inheritance-tree/ERC1363.png
diff --git a/analysis/inheritance-tree/ERC1363Mintable.png b/analysis/inheritance-tree/ERC1363Mintable.png