Merge pull request #614 from lukso-network/contracts-overview

Add more content in contracts overview section

docs/contracts/introduction.md

@@ -5,12 +5,13 @@ sidebar_position: 1
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import {ContractCardsGallery} from '@site/src/components/ContractCardsGallery';
 
 # Smart Contracts
 
 > The smart contracts are public and open source on [GitHub](https://github.com/lukso-network/lsp-smart-contracts). <a href="https://github.com/lukso-network/lsp-smart-contracts" target="_blank" rel="noopener noreferrer"><img style={{verticalAlign: 'middle'}} alt="github badge" src="https://img.shields.io/github/v/release/lukso-network/lsp-smart-contracts?logo=github&label=Github"/></a>
 >
-> They are available as an npm package [`@lukso/lsp-smart-contracts`](https://www.npmjs.com/package/@lukso/lsp-smart-contracts). <a href="https://www.npmjs.com/package/@lukso/lsp-smart-contracts" target="_blank" rel="noopener noreferrer"><img style={{verticalAlign: 'middle'}} alt="npm badge" src="https://img.shields.io/npm/v/@lukso/lsp-smart-contracts.svg?style=flat&label=NPM&logo=npm"/></a>
+> They are available as a npm package [`@lukso/lsp-smart-contracts`](https://www.npmjs.com/package/@lukso/lsp-smart-contracts). <a href="https://www.npmjs.com/package/@lukso/lsp-smart-contracts" target="_blank" rel="noopener noreferrer"><img style={{verticalAlign: 'middle'}} alt="npm badge" src="https://img.shields.io/npm/v/@lukso/lsp-smart-contracts.svg?style=flat&label=NPM&logo=npm"/></a>
 
 <br/>
 
@@ -51,40 +52,37 @@ pnpm add @lukso/lsp-smart-contracts
 
 ## Overview
 
-Overall, the contracts can be divided by their usage, related to:
+Overall the contracts can be divided by their usage.
 
-- **Universal Profiles**
-- **Digital Assets and NFT 2.0**
-- **General use cases**.
+<ContractCardsGallery />
 
-Some of the LSP standards do not have a contract implementation as they represent **Metadata-Standards** to be used in the implementation contracts.
 
-### Universal Profile
+## Types of contracts
+
+:::info
+
+If you are using base contracts and are deploying proxies for your application, it is recommended to use a factory pattern to deploy and initialize the proxies to avoid potential front-running issues. 
 
-The **Universal Profile** contracts allow a better representation of the identity on the blockchain and better control over it.
+The **LSP16 Universal Factory** or **LSP23 Linked Contract Deployment** can help you achieve this.
 
-- **[LSP0ERC725Account](../contracts/contracts/LSP0ERC725Account)**: a contract that can be used as an account and represents an **identity on-chain**.
-- **[LSP1UniversalReceiverDelegateUP](./contracts/LSP1UniversalReceiver/LSP1UniversalReceiverDelegateUP/LSP1UniversalReceiverDelegateUP.md)**: a contract that allows the account to react to the calls that it receives (Normal transaction, Token transfer, Vaults transfer, etc.).
-- **[LSP6KeyManager](../contracts/contracts/LSP6KeyManager/LSP6KeyManager.md)**: a contract that allows **multi-control** over the account using different permissions.
-- **LSP11BasicSocialRecovery**
+:::
 
-### Digital Assets
+The `@lukso/lsp-smart-contracts` repository contains two types of contracts:
 
-The **Digital Asset (Token and NFT 2.0)** contracts are the newest advanced version of the existing token standards. They come with many features that enhance the security and the overall user experience and compatibility with [ERC725Accounts](../standards/universal-profile/lsp0-erc725account.md) and [Universal Receivers](../standards/generic-standards/lsp1-universal-receiver.md).
+| Type                   | Description                                                                                                                 | Example                     |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| **Standard contracts** | One contract deployed per user. Deployed and initialized via a `constructor`.                                               | `LSP0ERC725Account.sol`     |
+| **Base contracts**     | Deploy one contract for all users. To be used as base contract behind proxies. Initialized via a `initalize(...)` function. | `LSP0ERC725AccountInit.sol` |
 
-- **[LSP4DigitalAssetMetadata](./contracts/LSP4DigitalAssetMetadata/LSP4DigitalAssetMetadata.md)**: a contract that sets the **metadata** of the **Digital Asset**.
-- **[LSP7DigitalAsset](./contracts/LSP7DigitalAsset/LSP7DigitalAsset.md)**: a contract that either represents a fungible or non-fungible token (NFT).
-- **[LSP8IdentifiableDigitalAsset](./contracts/LSP8IdentifiableDigitalAsset/LSP8IdentifiableDigitalAsset.md)**: a contract that represents a non-fungible token (NFT). It uses a bytes32 tokenId to allow many uses of token identification, including numbers, contract addresses, and hashed values (e.g., serial numbers).
 
-### Generic Standards
+## LSP Recipes
+
+Some of the LSP standards do not have a contract implementation as they represent **Metadata-Standards** to be used in the implementation contracts.
+
+Each contracts are not just related to one specific section. They could be used in different fashion and combination, with the **Universal Profile**, **Digital Asset**, and **NFT 2.0** contracts.
 
-These contracts are not just related to one specific section and could be used with the **Universal Profile**, **Digital Asset**, and **NFT 2.0** contracts.
+For instance, the **Universal Profile Browser extension** comprises a set of contracts allow a better representation of the identity on the blockchain and better control over it.
 
-- **[LSP9Vault](../contracts/contracts/LSP9Vault/LSP9Vault.md)**: a contract representing a **Vault** able to execute and hold assets could be owned by an LSP0ERC725Account contract.
-- **[LSP1UniversalReceiverDelegateVault](./contracts/LSP1UniversalReceiver/LSP1UniversalReceiverDelegateVault/LSP1UniversalReceiverDelegateVault.md)**: a contract that allows the vault to react to the calls it receives (Normal transaction, Token transfer, etc.).
-- **LSP14Ownable2Step**
-- **LSP17ContractExtension**
-- **LSP20CallVerification**
 
 ## Further Information
 

docs/contracts/overview/DigitalAssets.md

@@ -1,13 +1,66 @@
-# Digital Assets
-
-:::caution Warning
-
-`LSP7DigitalAsset.sol` and `LSP8IdentifiableDigitalAsset.sol` are `abstract` contracts that are not deployable as they are, because they do not contain any public functions by default to manage token supply (_e.g: no public `mint(...)` or `burn(...)` functions_). You can either:
+---
+title: Digital Assets (Token & NFT)
+sidebar_position: 4
+---
 
-- use `LSP7Mintable` or `LSP8Mintable`, a preset contract that contains a public `mint(...)` function callable only by the contract's owner.
-- or extend the `LSP7DigitalAsset` / `LSP8IdentifiableDigitalAsset` contract and create your own supply mechanism by defining public methods that use the internal `_mint(...)` and `_burn(...)` functions.
+# Digital Assets
 
-:::
+The **Digital Asset (Token and NFT 2.0)** contracts are the newest advanced version of the existing token standards. They come with many features that enhance the security and the overall user experience and compatibility with [ERC725Accounts](../../standards/universal-profile/lsp0-erc725account.md) and [Universal Receivers](../../standards/generic-standards/lsp1-universal-receiver.md).
+
+## Comparisons with ERC20 / ERC721
+
+The interfaces of LSP7 and LSP8 have some differences compared to ERC20 and ERC721. Their functions are simpler, more straight forward and unified.
+
+**Similar function names**
+
+Both functions in LSP7 and LSP8 have the same name (`transfer`) to transfer assets. This is easier compared to ERC20 and ERC721 that use different naming (`transfer` for ERC20 vs `transferFrom` in ERC721 to transfer tokens as the token owner).
+
+The table below highlights these differences:
+
+
+<table>
+  <tr>
+    <th>Description</th>
+    <th>ERC20</th>
+    <th>LSP7</th>
+  </tr>
+  <tr>
+    <td>Transferring tokens as an owner.</td>
+    <td><code>transfer(address,uint256)</code></td>
+    <td rowspan="2"><code>transfer(address,address,uint256,bool,bytes)</code></td>
+  </tr>
+  <tr>
+    <td>Transferring tokens as an operator.</td>
+    <td><code>transferFrom(address,address,uint256)</code></td>
+  </tr>
+  <tr>
+    <td>Approving an operator to spend tokens on behalf of the owner.</td>
+    <td><code>approve(address,uint256)</code></td>
+    <td><code>authorizeOperator(address,uint256)</code></td>
+  </tr>
+  <tr>
+    <th>Description</th>
+    <th>ERC721</th>
+    <th>LSP8</th>
+  </tr>
+  <tr>
+    <td>Transferring tokens as an owner.</td>
+    <td rowspan="2">
+        <code>transferFrom(address,address,uint256)</code><br/>
+        <code>safeTransferFrom(address,address,uint256)</code><br/>
+        <code>safeTransferFrom(address,address,uint256,bytes)</code>
+    </td>
+    <td rowspan="2"><code>transfer(address,address,bytes32,bool,bytes)</code></td>
+  </tr>
+  <tr>
+    <td>Transferring tokens as an operator.</td>
+  </tr>
+  <tr>
+    <td>Approving an operator to spend tokens on behalf of the owner.</td>
+    <td><code>approve(address,uint256)</code></td>
+    <td><code>authorizeOperator(address,bytes32)</code></td>
+  </tr>
+</table>
 
 ## LSP4 Digital Asset Metadata
 
@@ -17,9 +70,13 @@ Since it uses **[ERC725Y General Data Key/Value Store](https://eips.ethereum.org
 
 ## LSP7 Digital Asset
 
-The **LSP7DigitalAsset** contract represents digital assets for either fungible or non-fungible tokens where minting and transferring are specified with an amount of tokens. It has some functions from **[ERC20](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/ERC20.sol)** and **[ERC777](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC777/ERC777.sol)** with more upgraded features.
+The **LSP7DigitalAsset** contract represents digital assets for fungible tokens where minting and transferring are specified with an amount of tokens. Their functions were inspired from **[ERC20](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/ERC20.sol)** and **[ERC1155](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC1155/ERC1155.sol)** with more upgraded features.
 
-This contract serves as a **Fungible Token Contract** when `isNonDivisible` bool is set to `false` in the [`constructor(...)`](#constructor) and otherwise serves as a **Non-Fungible Token Contract**.
+An LSP7 can serves as:
+- a **Divisible Token Contract** when `isNonDivisible` bool is set to `false` in the [`constructor(...)`](#constructor)
+- otherwise serves as a **Non-Divisible Token Contract**.
+
+This can be useful to set `isNonDivisible` to `true`, rather than deploying a LSP8 contract to achieve the same goal.
 
 ### Create a Fungible Token
 
@@ -48,3 +105,10 @@ The **LSP8IdentifiableDigitalAsset** contract represents identifiable digital as
 Each NFT is identified with a tokenId, based on **[ERC721](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC721/ERC721.sol)**.
 
 A **bytes32** value is used for tokenId to allow many uses of token identification, including numbers, contract addresses, and hashed values (i.e., serial numbers).
+
+## Note on LSP7 and LSP8 implementations
+
+`LSP7DigitalAsset.sol` and `LSP8IdentifiableDigitalAsset.sol` are `abstract` contracts that are not deployable as they are, because they do not contain any public functions by default to manage token supply (_e.g: no public `mint(...)` or `burn(...)` functions_). You can either:
+
+- use `LSP7Mintable` or `LSP8Mintable`, a preset contract that contains a public `mint(...)` function callable only by the contract's owner.
+- or extend the `LSP7DigitalAsset` / `LSP8IdentifiableDigitalAsset` contract and create your own supply mechanism by defining public methods that use the internal `_mint(...)` and `_burn(...)` functions.

docs/contracts/overview/KeyManager.md

@@ -0,0 +1,23 @@
+---
+sidebar_position: 2
+---
+
+# Key Manager
+
+The Key Manager uses the concept of permissions to _authorize_ any addresses (dApps, protocols, devices, etc…) to do certain specific actions on the contract it is linked to.
+
+But why should you give anybody access to your smart contract? What is the intention behind doing this? How does the Key Manager enables that?
+
+As we will see, the Key Manager brings a different insight into the concept of ownership and permissions. 
+
+Let's illustrate with some examples. A Key Manager can be used with different setups. For intance:
+
+- to control a LSP0ERC725Account like a Universal Profile.
+- to control a Token contract.
+
+## Example with a Universal Profile
+
+To illustrate, in the case of Universal Profile and the browser extension, you can define your EOA / private keys (hold within your device, like in the Browser Extension) to be **the address with all the permissions** to do anything (the main admin account). 
+
+Afterwards, you can grant partial access to dApp and protocol (more specifically the smart contract addresses behind them), so that they can use your Universal Profile to interact on your behalf. This catalyze interactions on the blockchain, where your Universal Profile can do more and operate automatically in controlled manner, without requiring the main profile owner to have to do everything.
+

docs/contracts/overview/LSP1Delegate.md

@@ -0,0 +1,12 @@
+---
+sidebar_position: 3
+---
+
+# Universal Receiver Delegate
+
+There are two default implementations of the LSP1 Delegate contracts available, each for different use cases.
+
+| Contract                                                                                                                                                    | Description                                                                                                           |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| **[`LSP1UniversalReceiverDelegateUP.sol`](../contracts/LSP1UniversalReceiver/LSP1UniversalReceiverDelegateUP/LSP1UniversalReceiverDelegateUP.md)**          | Add feature to a `LSP0ERC725Account` to registered and un-register tokens (LSP7 and LSP8) and vaults (LSP9) received. |
+| **[`LSP1UniversalReceiverDelegateVault.sol`](../contracts/LSP1UniversalReceiver/LSP1UniversalReceiverDelegateVault/LSP1UniversalReceiverDelegateVault.md)** | Add feature to a `LSP9Vault` to register and un-register tokens (LSP7 and LSP8).                                      |