ISC - Restructure (#1458)

* ISC - Restructure - Learn and Build (#1415) * Fix broken links * Isc Restructure - EVM how tos - basic contract, ERC20 , ERC721 and deploy (#1454) * saving working state * re-merge EVM and WASM * apply suggestions by @jlvandenhout * add simplified explanations in Learn * add and update get funds add tabs to tools delete magic contract how tos for the time being add introduction * first draft deploy a smart contract using remix or hardhat @todo add images and merge with tools section. * normalized how we call the ShimmerEVM testnet * fix links fix numbering * rebased on ISC/restructure saving working state @todo add dummy value to images @todo review ERC721 texts and update images * add how to mint the nft. create admonition for priorknowledge and remix ide\ delete unnecessary images align images in ERC20 update sample ERC721 contract * Add 'Create Foundry' how-to * Mint token * Register token * Allowance how tos * Custom erc20 * added article on testing (#1471) * Format * Get balance * Fix structure * Add Randomness how-to (#1484) * Add Randomness how-to * Apply suggestions from code review Co-authored-by: Lucas Tortora <[email protected]> --------- Co-authored-by: Lucas Tortora <[email protected]> * Add how to withdraw assets to L1 * Format * Resolve TODOs * Use tabs (#1492) * Remove Truffle (#1493) * Remove Wasp CLI mentions from build (#1494) * Small fixes * fix link * Small Fixes * On... Off... On... * Restructure how tos (#1500) * Restructure how-tos * Update core contract introduction * Add decimals * Update docs/build/isc/v1.0.0-rc.6/docs/how-tos/core-contracts/basics/send-assets-to-l1.mdx * expand gas and allowance explanations (#1503) * expand gas and allowance explanations * revert unwanted autoformat change * Update docs/build/isc/v1.0.0-rc.6/docs/explanations/invocation.md Co-authored-by: Lucas Tortora <[email protected]> --------- Co-authored-by: Dr-Electron <[email protected]> * Update docs/build/isc/v1.0.0-rc.6/docs/explanations/invocation.md * Apply suggestions from code review Co-authored-by: Jorge Silva <[email protected]> * removed glossary tooltip in sandbox.md removed glossary tooltip in smart-contract-anatomy.md clarify that hname identification is only for core and WASM contracts in smart-contract-anatomy.md removed confusing statement about SC logical structure in smart-contract-anatomy.md removed video tutorial from tools.mdx changed serious for production in tools.mdx rephrased gas/fees statement in tools.mdx move explanations below how tos in the sidebar rephrase validator explanation introduction.md removed link to isc-architecture in introduction.md removed isc-architecture.md and included what the relevant info in introduction.md changed md ordered list to html ordered list in tools.mdx to fix the display of the ChainID component changed Shimmer Public Testnet to Public Testnet on _network_warning.md removed all video tutorials * fix typo * Rebase on main to sort out conflicts * HTML be gone * Update docs/build/isc/v1.0.0-rc.6/docs/how-tos/core-contracts/basics/get-balance.md Co-authored-by: Dr-Electron <[email protected]> --------- Co-authored-by: Dr-Electron <[email protected]> Co-authored-by: Jeroen van den Hout <[email protected]> Co-authored-by: Jorge Silva <[email protected]>
iotaledger · Mar 19, 2024 · 010438b · 010438b
1 parent 40b20a9
commit 010438b
Show file tree

Hide file tree

Showing 173 changed files with 3,042 additions and 3,777 deletions.
diff --git a/articleRedirects.js b/articleRedirects.js
@@ -398,10 +398,6 @@ exports.articleRedirects = [
     from: '/shimmer/learn/role-of-token',
     to: '/get-started/introduction/shimmer/shimmer-token',
   },
-  {
-    from: '/shimmer/learn/smart-contracts/smart-contracts-chains',
-    to: '/learn/smart-contracts/isc-architecture',
-  },
   {
     from: '/shimmer/learn/smart-contracts/smart-contracts-community-tutorials',
     to: '/learn/smart-contracts/introduction',
@@ -460,15 +456,15 @@ exports.articleRedirects = [
   },
   {
     from: '/shimmer/smart-contracts/configuration',
-    to: '/wasp/configuration',
+    to: '/wasp/reference/configuration',
   },
   {
     from: '/shimmer/smart-contracts/contribute',
     to: '/learn/smart-contracts/introduction',
   },
   {
     from: '/shimmer/smart-contracts/metrics',
-    to: '/wasp/metrics',
+    to: '/wasp/reference/metrics',
   },
   {
     from: '/shimmer/learn/smart-contracts/introduction',

diff --git a/docs/build/getting-started/networks-endpoints.mdx b/docs/build/getting-started/networks-endpoints.mdx
@@ -77,14 +77,13 @@ This network is subject to occasional resets (no data retention) which are usual
 | ------------------------- | -------- | ----------------------------------- | ------------------------------------------------------------ | ----------------------------------------- | -------------------------------------- |
 | Testnet Tokens (no value) | Stardust | `https://api.testnet.shimmer.network` | wss://api.testnet.shimmer.network:443/api/mqtt/v1 (MQTT 3.1) | https://chronicle.testnet.shimmer.network | https://faucet.testnet.shimmer.network |
 
-### Testnet EVM
+### ShimmerEVM Testnet
 
 <AddToMetaMaskButton cfg={EVMNetworks['shimmerevm-testnet']} />
 
-[The Testnet EVM](https://explorer.evm.testnet.shimmer.network/) (also called ShimmerEVM Beta) runs as a layer 2 on top
-of the Public Testnet. This network does not run
-any IOTA protocol but instead uses ISC to facilitate an Ethereum Virtual Machine and has an enshrined bridge from to
-layer 1.
+[The ShimmerEVM Testnet](https://explorer.evm.testnet.shimmer.network/) runs as a layer 2 on top
+of the Public Testnet. This network uses ISC to facilitate an Ethereum Virtual Machine and has an
+enshrined bridge to layer 1.
 
 :::info
 

diff --git a/docs/build/getting-started/sidebars.ts b/docs/build/getting-started/sidebars.ts
@@ -28,12 +28,12 @@ module.exports = {
         {
           type: 'link',
           label: 'WASP CLI',
-          href: '/wasp-cli/how-tos/wasp-cli',
+          href: '/wasp/how-tos/wasp-cli',
         },
         {
           label: 'Schema Tool',
           type: 'link',
-          href: '/wasp-wasm/how-tos/schema-tool/introduction',
+          href: '/isc/schema/introduction',
         },
         {
           label: 'Explorer',

diff --git a/docs/build/getting-started/welcome.md b/docs/build/getting-started/welcome.md
@@ -50,5 +50,5 @@ The [IOTA Smart Contracts (ISC)](/learn/smart-contracts/introduction) bring scal
 contract functionality to the IOTA ecosystem. By anchoring multiple chains to the IOTA Tangle, ISC enables
 higher _throughput_ and lower fees than traditional single-chain solutions. Users have the freedom to create custom
 chains with control over gas fees and privacy settings, and the platform is virtual machine-agnostic, supporting both
-[Rust/Wasm](/wasp-wasm/introduction) and [Solidity/EVM](/wasp-evm/introduction)
+[Rust/Wasm](/isc/introduction) and [Solidity/EVM](/isc/introduction)
 smart contracts.
diff --git a/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_EVM-required-prior-knowledge.md b/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_EVM-required-prior-knowledge.md
@@ -0,0 +1,14 @@
+:::note Required Prior Knowledge
+
+This guide assumes you are familiar with the concept
+of [tokens](https://en.wikipedia.org/wiki/Cryptocurrency#Crypto_token)
+in [blockchain](https://en.wikipedia.org/wiki/Blockchain),
+[Ethereum Request for Comments (ERCs)](https://eips.ethereum.org/erc)(also known as Ethereum Improvement Proposals (
+EIP))
+, [NFTs](/learn/protocols/stardust/core-concepts/multi-asset-ledger#non-fungible-tokens-nfts), [Smart Contracts](/learn/smart-contracts/introduction)
+and have already tinkered with [Solidity](https://docs.soliditylang.org/en/v0.8.16/).
+
+You should also have basic knowledge on how to [create](../how-tos/create-a-basic-contract.md) and [deploy](../how-tos/deploy-a-smart-contract.mdx)
+a smart contract.
+
+:::
diff --git a/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_EVM_compatibility.md b/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_EVM_compatibility.md
@@ -0,0 +1,7 @@
+:::info EVM Compatibility
+
+The ISC EVM layer is also designed to be as compatible as possible with existing Ethereum
+[tools](../getting-started/tools.mdx) and functionalities. However, please make sure you have checked out the current
+[properties and limitations](../getting-started/compatibility.md).
+
+:::
diff --git a/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_about-accounts.md b/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_about-accounts.md
@@ -0,0 +1,5 @@
+:::info Accounts in ISC
+
+Learn more about the [different types of accounts](../explanations/how-accounts-work.md).
+
+:::
diff --git a/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_deploy_a_smart_contract.md b/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_deploy_a_smart_contract.md
@@ -0,0 +1,5 @@
+:::tip Deploy a Smart Contract 
+
+Deploy a Solidity Smart Contract following our [how to Deploy a Smart Contract guide](/isc/how-tos/deploy-a-smart-contract#remix).
+
+:::
diff --git a/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_network_warning.md b/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_network_warning.md
@@ -0,0 +1,6 @@
+:::caution Only Available on Shimmer
+
+At the moment, Smart Contracts are only available on [Shimmer](/build/networks-endpoints/#shimmer) and
+its [Public Testnet](/build/networks-endpoints/#public-testnet) network.
+
+:::
diff --git a/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_ownership.md b/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_ownership.md
@@ -0,0 +1,7 @@
+:::info Ownership
+
+You might want to look into making the function ownable with, for example,
+[OpenZeppelin](https://docs.openzeppelin.com/contracts/5.x/access-control#ownership-and-ownable)
+so only owners of the contract can call certain functionalities of your contract.
+
+:::
diff --git a/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_payable.md b/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_payable.md
@@ -0,0 +1,10 @@
+:::info Payable
+
+Instead of making the function payable, you could let the contract pay for the storage deposit. 
+If so, you will need to change the `require` statement to check if the contract's balance has enough funds:
+
+```solidity
+require(address(this).balance > _storageDeposit);
+```
+
+:::
diff --git a/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_remix-IDE.md b/docs/build/isc/v1.0.0-rc.6/docs/_admonitions/_remix-IDE.md
@@ -0,0 +1,6 @@
+:::tip Remix
+
+This guide will use the [Remix IDE](https://remix.ethereum.org/), but you can use this contract with any IDE you are
+familiar with.
+
+:::
diff --git a/docs/build/isc/v1.0.0-rc.6/docs/_partials/_on_off_ledger_request.md b/docs/build/isc/v1.0.0-rc.6/docs/_partials/_on_off_ledger_request.md
@@ -0,0 +1,13 @@
+### On-Ledger Requests
+
+An on-ledger request is a Layer 1 transaction that validator nodes retrieve from the Tangle. The Tangle acts as an
+arbiter between users and chains and guarantees that the transaction is valid, making it the only way to transfer assets
+to a chain or between chains.
+
+### Off-Ledger Requests
+
+If all necessary assets are in the chain already, it is possible to send a request directly to that chain's validator
+nodes.
+This way, you don’t have to wait for the Tangle to process the message, significantly reducing the overall confirmation
+time.
+Due to the shorter delay, off-ledger requests are preferred over on-ledger requests unless you need to deposit assets to the chain.
diff --git a/docs/build/isc/v1.0.0-rc.6/docs/_partials/how-tos/token/_check_storage_deposit.md b/docs/build/isc/v1.0.0-rc.6/docs/_partials/how-tos/token/_check_storage_deposit.md
@@ -0,0 +1,10 @@
+### 1. Check the Storage Deposit
+
+Check if the amount paid to the contract is the same as the required [storage deposit](/learn/protocols/stardust/core-concepts/storage-deposit)
+   and set the allowance.
+
+```solidity
+require(msg.value == _storageDeposit*(10**12), "Please send exact funds to pay for storage deposit");
+ISCAssets memory allowance;
+allowance.baseTokens = _storageDeposit;
+```
diff --git a/docs/build/isc/v1.0.0-rc.6/docs/_partials/how-tos/token/_example_code_intro.md b/docs/build/isc/v1.0.0-rc.6/docs/_partials/how-tos/token/_example_code_intro.md
@@ -0,0 +1,9 @@
+import Ownership from '../../../_admonitions/_ownership.md';
+import Payable from '../../../_admonitions/_payable.md';
+import CheckStorageDeposit from './_check_storage_deposit.md'
+
+<Ownership/>
+
+<CheckStorageDeposit/>
+
+<Payable/>
diff --git a/docs/build/isc/v1.0.0-rc.6/docs/explanations/consensus.md b/docs/build/isc/v1.0.0-rc.6/docs/explanations/consensus.md
@@ -0,0 +1,53 @@
+---
+description: IOTA Smart Contracts consensus is how Layer 2 validators agree to change the chain state in the same way.
+image: /img/logo/WASP_logo_dark.png
+tags:
+  - smart contracts
+  - consensus
+  - validator committee
+  - validators
+  - validator nodes
+  - explanation
+---
+
+# Consensus
+
+To update the chain, its committee must reach a _consensus_, meaning that more than two thirds of its validators have to
+agree to change the state in the exact same way.
+This prevents a single malicious node from wreaking havoc over the chain, but there are also more mundane reasons for
+individual nodes to act up.
+
+Smart contracts are deterministic. All honest nodes will produce the same output — but only if they have received the
+same input. Each validator node has its point of access to the Tangle, so it may look different to different nodes, as
+new transactions take time to propagate through the network. Validator nodes will receive smart contract requests with
+random delays in a random order, and, finally, all computers run on their own always slightly skewed clocks.
+
+## Batch Proposals
+
+As the first step, each node provides its vision, a _batch proposal_. The proposal contains a local timestamp, a list of
+unprocessed requests, and the node's partial signature of the commitment to the current state.
+
+Then the nodes must agree on which batch proposals they want to work on. In short, nodes A, B, and C have to confirm
+that they plan to work on proposals from A, B, and C, and from no one else. As long as there are more than two thirds of
+honest nodes, they will be able to find an _asynchronous common subset_ of the batch proposals. From that point, nodes
+have the same input and will produce the same result independently.
+
+## The Batch
+
+The next step is to convert the raw list of batch proposals into an actual batch. All requests from all proposals are
+counted and filtered to produce the same list of requests in the same order.
+The partial signatures of all nodes are combined into a full signature that is then fed to a pseudo-random function that
+sorts the smart contract requests.
+Validator nodes can neither affect nor predict the final order of requests in the batch. (This protects ISC
+from [MEV attacks](https://ethereum.org/en/developers/docs/mev/)).
+
+## State Anchor
+
+After agreeing on the input, each node executes every smart contract request in order, independently producing the same
+new block. Each node then crafts a state anchor, a Layer 1 transaction that proves the commitment to this new chain
+state. The timestamp for this transaction is derived from the timestamps of all batch proposals.
+
+All nodes then sign the state anchor with their partial keys and exchange these signatures. This way, every node obtains
+the same valid combined signature and the same valid anchor transaction, which means that any node can publish this
+transaction to Layer 1. In theory, nodes could publish these state anchors every time they update the state; in
+practice, they do it only every approximately ten seconds to reduce the load on the Tangle.
diff --git a/...v1.0.0-rc.6/docs/explanations/context.mdx → ...v1.0.0-rc.6/docs/explanations/context.mdx b/...v1.0.0-rc.6/docs/explanations/context.mdx → ...v1.0.0-rc.6/docs/explanations/context.mdx
diff --git a/docs/build/isc/v1.0.0-rc.6/docs/explanations/core-contracts.md b/docs/build/isc/v1.0.0-rc.6/docs/explanations/core-contracts.md
@@ -0,0 +1,37 @@
+---
+description: There currently are 6 core smart contracts that are always deployed on each  chain, root, _default, accounts, blob, blocklog, and governance.
+image: /img/banner/banner_wasp_core_contracts_overview.png
+tags:
+  - smart contracts
+  - core
+  - initialization
+  - request handling
+  - on-chain ledger
+  - accounts
+  - data
+  - receipts
+  - reference
+---
+
+# Core Contracts
+
+![Wasp Node Core Contracts Overview](/img/banner/banner_wasp_core_contracts_overview.png)
+
+There are currently 7 core smart contracts that are always deployed on each
+chain. These are responsible for the vital functions of the chain and
+provide infrastructure for all other smart contracts:
+
+- [`root`](../reference/core-contracts/root.md): Responsible for the initialization of the chain, maintains registry of deployed contracts.
+
+- [`accounts`](../reference/core-contracts/accounts.md): Manages the on-chain ledger of accounts.
+
+- [`blob`](../reference/core-contracts/blob.md): Responsible for the registry of binary objects of arbitrary size.
+
+- [`blocklog`](../reference/core-contracts/blocklog.md): Keeps track of the blocks and receipts of requests that were processed by the chain.
+
+- [`governance`](../reference/core-contracts/governance.md): Handles the administrative functions of the chain. For example: rotation of the committee of validators of the chain, fees and other chain-specific configurations.
+
+- [`errors`](../reference/core-contracts/errors.md): Keeps a map of error codes to error messages templates. These error codes are used in request receipts.
+
+- [`evm`](../reference/core-contracts/evm.md): Provides the necessary infrastructure to accept Ethereum
+  transactions and execute EVM code.
diff --git a/....6/docs/explanations/how-accounts-work.md → ....6/docs/explanations/how-accounts-work.md b/....6/docs/explanations/how-accounts-work.md → ....6/docs/explanations/how-accounts-work.md
@@ -1,5 +1,5 @@
 ---
-description: 'IOTA Smart Contracts chains keeps a ledger of on-chain account balances. On-chain accounts are identified
+description: 'IOTA Smart Contracts chains keep a ledger of on-chain account balances. On-chain accounts are identified
 by an AgentID.'
 image: /img/tutorial/accounts.png
 tags:
@@ -11,7 +11,6 @@ tags:
 - explanation
 
 ---
-
 # How Accounts Work
 
 On the L1 Ledger, like with any _DLT_, we have **trustless** and **atomic** transfers of assets between addresses on the
@@ -20,10 +19,14 @@ ledger.
 Tokens controlled by an address can be moved to another address by providing a valid signature using the private key
 that controls the source address.
 
-In IOTA Smart Contracts, [each chain has a L1 address](/learn/smart-contracts/states#digital-assets-on-the-chain) (also known as the _Chain
+## L1 Addresses
+
+In IOTA Smart Contracts, [each chain has a L1 address](../explanations/states.md#digital-assets-on-the-chain) (also known as the _Chain
 ID_) which enables it to control L1 assets (base tokens, native tokens and NFTs).
 The chain acts as a custodian of the L1 assets on behalf of different entities, thus providing a _L2 Ledger_.
 
+## L2 Accounts
+
 The L2 ledger is a collection of _on-chain accounts_ (sometimes called just _accounts_).
 L2 accounts can be owned by different entities, identified by a unique _Agent ID_.
 The L2 ledger is a mapping of Agent ID => balances of L2 assets.
@@ -42,11 +45,11 @@ Tokens in an address account can only be moved through a request signed by the p
 ### Smart Contract
 
 Any _smart contract_ can be the owner of a L2 account. Recall that a smart
-contract is uniquely identified in a chain by a [_hname_](/learn/smart-contracts/smart-contract-anatomy#identifying-a-smart-contract).
+contract is uniquely identified in a chain by a [_hname_](smart-contract-anatomy.md#identifying-a-smart-contract).
 However, the hname is not enough to identify the account since a smart contract on another chain could own it.
 
 Thus, the Agent ID of a smart contract is composed as the contract hname plus the [_chain
-ID_](/learn/smart-contracts/states#digital-assets-on-the-chain), with syntax `<hname>@<chain-id>`. For
+ID_](states.md#digital-assets-on-the-chain), with syntax `<hname>@<chain-id>`. For
 example: `cebf5908@tgl1pzehtgythywhnhnz26s2vtpe2wy4y64pfcwkp9qvzhpwghzxhwkps2tk0nd`.
 
 Note that this allows trustless transfers of assets between smart contracts on the same or different chains.
@@ -74,14 +77,14 @@ Tokens in an Ethereum account can only be moved by sending an Ethereum transacti
 The [`accounts` core contract](../reference/core-contracts/accounts.md) is responsible for managing the L2 ledger.
 By calling this contract, it is possible to:
 
-- [View current account balances](../how-tos/view-account-balances.mdx)
-- [Deposit funds to the chain](../how-tos/deposit-to-a-chain.mdx)
-- [Withdraw funds from the chain](../how-tos/withdraw-from-a-chain.mdx)
+- [View current account balances](../how-tos/core-contracts/basics/get-balance.md)
+- [Deposit funds to the chain](../how-tos/send-funds-from-L1-to-L2.mdx)
+- [Withdraw funds from the chain](../how-tos/core-contracts/basics/send-assets-to-l1.mdx)
 
 ## Example
 
 The following diagram illustrates an example situation.
-The the IDs and hnames are shortened for simplicity.
+The IDs and hnames are shortened for simplicity.
 
 [![Example situation. Two chains are deployed, with three smart contracts and one address.](/img/tutorial/accounts.png)](/img/tutorial/accounts.png)