ISC restructure - Explanations - Learn

articleRedirects.js

@@ -428,7 +428,7 @@ exports.articleRedirects = [
   },
   {
     from: '/shimmer/learn/smart-contracts/smart-contracts-chains',
-    to: '/learn/smart-contracts/isc-architecture',
+    to: '/learn/smart-contracts/introduction',
   },
   {
     from: '/shimmer/learn/smart-contracts/smart-contracts-community-tutorials',

docs/build/wasp-evm/v1.0.0-rc.6/docs/explanations/how-accounts-work.md

@@ -20,7 +20,7 @@ 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
+In IOTA Smart Contracts, [each chain has a L1 address](/learn/smart-contracts/accounts-addresses-and-fees) (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_.
 
@@ -42,11 +42,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_.
 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_](/learn/smart-contracts/state-management-and-anchoring#digital-assets), 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.

docs/build/wasp-evm/v1.0.0-rc.6/docs/getting-started/compatibility.md

@@ -43,13 +43,12 @@ Here are some of the most important properties and limitations of EVM support in
 
 The Wasp node provides a JSON-RPC service, the standard protocol used by Ethereum tools. Upon receiving a signed
 Ethereum transaction via JSON-RPC, the transaction is wrapped into an ISC
-[off-ledger request](/learn/smart-contracts/invocation#off-ledger-requests). The sender of the request
+[off-ledger request](/learn/smart-contracts/smart-contract-execution#off-ledger-requests). The sender of the request
 is the Ethereum address that signed the original transaction (e.g., the Metamask account).
 
 ### Contract ID Source
 
-While ISC contracts are identified by an [hname](/learn/smart-contracts/smart-contract-anatomy), EVM contracts are
-identified by their Ethereum address.
+While ISC contracts are identified by an `hname`, EVM contracts are identified by their Ethereum address.
 
 ### WASM Root Contract List
 
@@ -58,7 +57,7 @@ EVM contracts are not listed in the chain's [contract registry](../reference/cor
 ### On-ledger Requests
 
 EVM contracts cannot be called via regular ISC requests; they can only be called through the JSON-RPC service.
-As a consequence, EVM contracts cannot receive [on-ledger requests](/learn/smart-contracts/invocation#on-ledger-requests).
+As a consequence, EVM contracts cannot receive [on-ledger requests](/learn/smart-contracts/smart-contract-execution#on-ledger-requests).
 
 ### Block Structure and Storage
 

docs/build/wasp-evm/v1.0.0-rc.6/docs/how-tos/magic-contract/call-a-function.md

@@ -3,7 +3,7 @@
 In the example above, `ISC.sandbox.getEntropy()` calls the
 [`getEntropy`](https://github.com/iotaledger/wasp/blob/develop/packages/vm/core/evm/iscmagic/ISCSandbox.sol#L20)
 method of the `ISCSandbox` interface, which, in turn,
-calls [ISC Sandbox's](/learn/smart-contracts/sandbox) `GetEntropy`.
+calls ISC Sandbox's `GetEntropy`.
 
 ```solidity
 pragma solidity >=0.8.5;

docs/build/wasp-wasm/v1.0.0-rc.6/docs/explanations/how-accounts-work.md

@@ -4,11 +4,11 @@ by an AgentID.'
 image: /img/tutorial/accounts.png
 keywords:
 
-- smart contracts
-- on-chain account
-- ownership
-- accounts Contract
-- explanation
+  - smart contracts
+  - on-chain account
+  - ownership
+  - accounts Contract
+  - explanation
 
 ---
 
@@ -20,7 +20,7 @@ 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
+In IOTA Smart Contracts, [each chain has a L1 address](/learn/smart-contracts/accounts-addresses-and-fees) (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_.
 
@@ -41,12 +41,12 @@ 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).
+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_.
 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_](/learn/smart-contracts/state-management-and-anchoring#digital-assets), 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.

docs/build/wasp-wasm/v1.0.0-rc.6/docs/how-tos/schema-tool/yaml.mdx

@@ -45,7 +45,7 @@ The schema definition file can have the following level 1 attributes:
 ## state
 
 - **Type**: Map of strings
-- **Usage**: Contains key/value pairs for use-case specific data ([details](/learn/smart-contracts/states))
+- **Usage**: Contains key/value pairs for use-case specific data ([details](/learn/smart-contracts/state-management-and-anchoring))
 - **Note**: To employ nested types, create a typedef alias for arrays or maps, but ensure map keys are primitive
 
 ## funcs & views

docs/learn/sidebars.ts

@@ -99,43 +99,33 @@ module.exports = {
         },
         {
           type: 'doc',
-          label: 'ISC Architecture',
-          id: 'smart-contracts/isc-architecture',
+          label: 'Protocol Overview',
+          id: 'smart-contracts/protocol-overview',
         },
         {
           type: 'doc',
-          label: 'Anatomy of a Smart Contract',
-          id: 'smart-contracts/smart-contract-anatomy',
+          label: 'Smart Contract Execution',
+          id: 'smart-contracts/smart-contract-execution',
         },
         {
           type: 'doc',
-          label: 'Sandbox Interface',
-          id: 'smart-contracts/sandbox',
+          label: 'Account, Addresses & Fees',
+          id: 'smart-contracts/accounts-addresses-and-fees',
         },
         {
           type: 'doc',
-          label: 'Calling a Smart Contract',
-          id: 'smart-contracts/invocation',
+          label: 'Chain Owners, Validators, & Access Nodes',
+          id: 'smart-contracts/chain-owners-validators-and-access-nodes',
         },
         {
           type: 'doc',
-          label: 'State, Transitions and State Anchoring',
-          id: 'smart-contracts/states',
-        },
-        {
-          type: 'doc',
-          label: 'State manager',
-          id: 'smart-contracts/state_manager',
-        },
-        {
-          type: 'doc',
-          label: 'Validators and Access Nodes',
-          id: 'smart-contracts/validators',
+          label: 'Consensus',
+          id: 'smart-contracts/consensus',
         },
         {
           type: 'doc',
-          label: 'Consensus',
-          id: 'smart-contracts/consensus',
+          label: 'State Management & Anchoring',
+          id: 'smart-contracts/state-management-and-anchoring',
         },
       ],
     },

docs/learn/smart-contracts/accounts-addresses-and-fees.md

@@ -0,0 +1,42 @@
+---
+description: An overview of account types, gas costs, and fees in IOTA Smart Contracts for efficient transaction management.
+image: /img/logo/WASP_logo_dark.png
+keywords:
+- IOTA Smart Contracts
+- Accounts and Addresses
+- Gas and Fees
+- Blockchain
+- Digital Assets
+---
+# Accounts, Addresses, and Fees
+
+## TL;DR;
+
+- [Types of Accounts](#types-of-accounts): IOTA Smart Contracts feature Layer 1 and Layer 2 accounts, each serving different roles and facilitating asset transfers across the blockchain.
+- [Gas](#gas): Running requests in IOTA Smart Contracts incurs a 'gas' cost, with users setting a `GasBudget` to manage their spending.
+- [Gas Budget](#gas-budget): The `GasBudget` allows users to define a spending limit for their requests, aligning with the chain’s fee policy.
+- [Allowance](#allowance): The `Allowance` system controls the fund usage in smart contracts, ensuring only authorized transactions are processed.
+
+## Types of Accounts
+
+In the world of IOTA Smart Contracts, accounts play a pivotal role. These accounts exist on two levels: Layer 1 (L1) and
+Layer 2 (L2). L1 addresses control assets on the IOTA ledger, and each smart contract chain has a unique L1 address,
+acting as a custodian for L1 assets. On the L2 ledger, accounts can be owned by various entities, each identified by a
+unique Agent ID. An L2 account can belong to a standard L1 address, a specific smart contract, or even an Ethereum
+address, enabling trustless asset transfers between different entities on the same or different chains.
+
+## Gas
+
+In the IOTA Smart Contract ecosystem, running a request in a chain incurs a cost known as 'gas'. Each operation within a
+smart contract, like arithmetic calculations or data storage, has an associated gas cost.
+
+### Gas Budget
+
+Users define a `GasBudget` for their requests, which represents the maximum cost they are willing to pay. This fee is
+charged based on the chain’s fee policy and is deducted from the user's on-chain account.
+
+### Allowance
+
+Additionally, the concept of `Allowance` is crucial as it defines the funds a smart contract can use on behalf of the
+caller. This mechanism ensures that only an authorized amount of funds can be utilized in transactions.
+

docs/learn/smart-contracts/chain-owners-validators-and-access-nodes.md

@@ -0,0 +1,48 @@
+---
+description: Explore the roles of chain owners, validator nodes, and access nodes in the governance and operation of IOTA Smart Contracts.
+image: /img/logo/WASP_logo_dark.png
+keywords:
+- IOTA Smart Contracts
+- Chain Owners
+- Validator Nodes
+- Access Nodes
+- Blockchain Governance
+---
+# Chain Owners, Validators, and Access Nodes
+
+## TL;DR;
+
+- [Chain Owners](#chain-owners): As the primary governors of a chain, chain owners control validator committees and dictate the chain's governance model.
+- [Validator Nodes](#validator-nodes): Validator nodes are crucial for block production and achieving consensus on state updates, with their composition managed by chain owners.
+- [Access Nodes](#access-nodes): Access nodes, having only read access, are key for querying the chain's state and managing external interactions with the blockchain.
+
+## Chain Owners
+
+Chain owners are the primary governing entities of a chain. They hold significant control over the chain,
+including the power to manage the committee of validators. They can rotate [validators](#validator-nodes) to ensure the
+chain's integrity and efficient operation. Chain owners establish and maintain the governance model of the chain, which
+dictates how validators are selected and rewarded.
+
+## Validator Nodes
+
+Validator nodes are the workhorses of a blockchain, possessing write access and thus responsible for producing blocks.
+These nodes form a committee that collaboratively runs smart contracts and reaches [consensus](consensus.md) on state
+updates. Each validator plays their part in executing code, verifying the results, and committing these updates to the
+chain.
+
+This process involves adding new blocks to the chain and updating the state hash in the Layer 1 (L1)
+ledger. [Chain owners](#chain-owners) can change the composition of this committee , allowing for flexibility and
+adaptability in the network's management.
+
+Often, validator nodes operate within a private subnet for security, with a designated group of access nodes serving as
+the
+interface with the external world. The management of both validator and access nodes is coordinated through
+the [`governance` core contract](/wasp-wasm/reference/core-contracts/governance/).
+
+## Access Nodes
+
+In contrast to [validator nodes](#validator-nodes), access nodes only have read access to the blockchain. They play a
+crucial role in responding to queries about the chain's state and forwarding requests to the committee of validators.
+These nodes provide external access to smart contracts, enabling queries
+([view calls](smart-contract-execution.md#view-entry-points)) and the sending of
+[off-ledger requests](smart-contract-execution.md#off-ledger-requests). 

docs/learn/smart-contracts/consensus.md

@@ -1,53 +1,54 @@
 ---
-description: IOTA Smart Contracts consensus is how Layer 2 validators agree to change the chain state in the same way.
+description: An insightful overview of the consensus process in IOTA Smart Contracts, detailing the steps involved in updating the chain.
 image: /img/logo/WASP_logo_dark.png
 keywords:
-  - smart contracts
-  - consensus
-  - validator committee
-  - validators
-  - validator nodes
-  - explanation
+- IOTA Smart Contracts
+- Consensus Process
+- Validator Nodes
+- Blockchain Updates
+- State Anchor
 ---
-
 # 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.
+## TL;DR;
 
-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.
+- [Introduction](#introduction): IOTA's Smart Contract protocol requires consensus among validators, with more than two-thirds agreement needed for state changes.
+- [1. Formulate the Batch Proposals](#1-formulate-the-batch-proposals): Validator nodes begin the consensus process with batch proposals, requiring mutual agreement to ensure uniform inputs and results.
+- [2. Agree On the Batch](#2-agree-on-the-batch): A finalized batch is created by filtering and ordering requests from all proposals, safeguarding against manipulation.
+- [3. Establish the State Anchor](#3-establish-the-state-anchor): Validators independently execute smart contract requests to create a new block, followed by crafting a state anchor for Layer 1 transaction validation.
 
-## 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.
+## Introduction
 
-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.
+In IOTA's Smart Contract protocol, updating the chain requires consensus
+among [validator](chain-owners-validators-and-access-nodes.md) nodes. This means more than two-thirds of validators must
+agree on any state change. This requirement is crucial for maintaining the chain's integrity and prevents any single
+node from causing disruption.
 
-## The Batch
+Since smart contracts are deterministic, all honest nodes will yield identical results, provided they receive the same
+input. However, variations in access points to the Tangle and the inherent randomness in receiving contract requests
+can lead to different perspectives among nodes.
 
-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/)).
+## 1. Formulate the Batch Proposals
+
+The consensus process starts with each validator node presenting a batch proposal. This proposal includes a timestamp, a
+list of pending requests, and the node's partial signature of its commitment to the current state. Nodes must
+then mutually agree on a set of batch proposals to process. This agreement process ensures that a common subset of
+proposals is selected, allowing nodes to work with identical inputs and, consequently, produce matching results.
 
-## State Anchor
+## 2. Agree On the Batch
+
+Transforming the selected batch proposals into a finalized batch involves counting and filtering requests from all
+proposals. This method ensures uniformity in the order of requests. The combined partial signatures of all validators
+create a full signature, which, through a pseudo-random function, determines the final sequence of requests. This step
+is essential to guard against manipulation and predictability (shielding the system
+from [MEV attacks](https://ethereum.org/en/developers/docs/mev/)).
 
-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.
+## 3. Establish the State Anchor
 
-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.
+Once the input is agreed upon, each validator independently executes the smart contract requests, leading to the
+creation of a new block. Subsequently, each node constructs a state anchor - a Layer 1 transaction attesting to the
+commitment to this new state. The state anchor, bearing a timestamp derived from all batch proposals, is signed by all
+validators. This unified signature guarantees that any validator can publish the transaction to Layer 1. Although state
+anchors can be published after every update, they are typically released every ten seconds to minimize the load on the
+Tangle.