From 003e22e102920cd62c6c9d1eea78b35e6b8ab034 Mon Sep 17 00:00:00 2001 From: Lucas Tortora Date: Mon, 8 Jan 2024 17:10:09 -0300 Subject: [PATCH] * add simplified learn articles * TODO re add current articles as explanations in build. * fix links and redirects --- articleRedirects.js | 2 +- .../docs/explanations/how-accounts-work.md | 6 +- .../docs/getting-started/compatibility.md | 7 +- .../how-tos/magic-contract/call-a-function.md | 2 +- .../docs/explanations/how-accounts-work.md | 18 +- .../docs/how-tos/schema-tool/yaml.mdx | 2 +- docs/learn/sidebars.ts | 34 +-- .../accounts-addresses-and-fees.md | 42 ++++ ...hain-owners-validators-and-access-nodes.md | 48 ++++ docs/learn/smart-contracts/consensus.md | 77 +++---- docs/learn/smart-contracts/introduction.md | 43 +++- docs/learn/smart-contracts/invocation.md | 111 ---------- .../learn/smart-contracts/isc-architecture.md | 32 --- .../smart-contracts/protocol-overview.md | 55 +++++ docs/learn/smart-contracts/sandbox.md | 45 ---- .../smart-contracts/smart-contract-anatomy.md | 80 ------- .../smart-contract-execution.md | 70 ++++++ docs/learn/smart-contracts/smart-contracts.md | 54 ----- .../state-management-and-anchoring.md | 46 ++++ docs/learn/smart-contracts/state_manager.md | 209 ------------------ docs/learn/smart-contracts/states.md | 122 ---------- docs/learn/smart-contracts/validators.md | 49 ---- 22 files changed, 366 insertions(+), 788 deletions(-) create mode 100644 docs/learn/smart-contracts/accounts-addresses-and-fees.md create mode 100644 docs/learn/smart-contracts/chain-owners-validators-and-access-nodes.md delete mode 100644 docs/learn/smart-contracts/invocation.md delete mode 100644 docs/learn/smart-contracts/isc-architecture.md create mode 100644 docs/learn/smart-contracts/protocol-overview.md delete mode 100644 docs/learn/smart-contracts/sandbox.md delete mode 100644 docs/learn/smart-contracts/smart-contract-anatomy.md create mode 100644 docs/learn/smart-contracts/smart-contract-execution.md delete mode 100644 docs/learn/smart-contracts/smart-contracts.md create mode 100644 docs/learn/smart-contracts/state-management-and-anchoring.md delete mode 100644 docs/learn/smart-contracts/state_manager.md delete mode 100644 docs/learn/smart-contracts/states.md delete mode 100644 docs/learn/smart-contracts/validators.md diff --git a/articleRedirects.js b/articleRedirects.js index 70a1b92c8d6..de84ef65681 100644 --- a/articleRedirects.js +++ b/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', diff --git a/docs/build/wasp-evm/v1.0.0-rc.6/docs/explanations/how-accounts-work.md b/docs/build/wasp-evm/v1.0.0-rc.6/docs/explanations/how-accounts-work.md index 2d8888f99b3..f1add703747 100644 --- a/docs/build/wasp-evm/v1.0.0-rc.6/docs/explanations/how-accounts-work.md +++ b/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 `@`. For +ID_](/learn/smart-contracts/state-management-and-anchoring#digital-assets), with syntax `@`. For example: `cebf5908@tgl1pzehtgythywhnhnz26s2vtpe2wy4y64pfcwkp9qvzhpwghzxhwkps2tk0nd`. Note that this allows trustless transfers of assets between smart contracts on the same or different chains. diff --git a/docs/build/wasp-evm/v1.0.0-rc.6/docs/getting-started/compatibility.md b/docs/build/wasp-evm/v1.0.0-rc.6/docs/getting-started/compatibility.md index e70ea5e060f..f3eb83bd7e3 100644 --- a/docs/build/wasp-evm/v1.0.0-rc.6/docs/getting-started/compatibility.md +++ b/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 diff --git a/docs/build/wasp-evm/v1.0.0-rc.6/docs/how-tos/magic-contract/call-a-function.md b/docs/build/wasp-evm/v1.0.0-rc.6/docs/how-tos/magic-contract/call-a-function.md index 25d1c74cf69..b33836a50d6 100644 --- a/docs/build/wasp-evm/v1.0.0-rc.6/docs/how-tos/magic-contract/call-a-function.md +++ b/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; diff --git a/docs/build/wasp-wasm/v1.0.0-rc.6/docs/explanations/how-accounts-work.md b/docs/build/wasp-wasm/v1.0.0-rc.6/docs/explanations/how-accounts-work.md index cf485279079..2b92eaa625e 100644 --- a/docs/build/wasp-wasm/v1.0.0-rc.6/docs/explanations/how-accounts-work.md +++ b/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 `@`. For +ID_](/learn/smart-contracts/state-management-and-anchoring#digital-assets), with syntax `@`. For example: `cebf5908@tgl1pzehtgythywhnhnz26s2vtpe2wy4y64pfcwkp9qvzhpwghzxhwkps2tk0nd`. Note that this allows trustless transfers of assets between smart contracts on the same or different chains. diff --git a/docs/build/wasp-wasm/v1.0.0-rc.6/docs/how-tos/schema-tool/yaml.mdx b/docs/build/wasp-wasm/v1.0.0-rc.6/docs/how-tos/schema-tool/yaml.mdx index 4662b574262..226f18465ef 100644 --- a/docs/build/wasp-wasm/v1.0.0-rc.6/docs/how-tos/schema-tool/yaml.mdx +++ b/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 diff --git a/docs/learn/sidebars.ts b/docs/learn/sidebars.ts index 8560b796872..23148c21954 100644 --- a/docs/learn/sidebars.ts +++ b/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', }, ], }, diff --git a/docs/learn/smart-contracts/accounts-addresses-and-fees.md b/docs/learn/smart-contracts/accounts-addresses-and-fees.md new file mode 100644 index 00000000000..a95461d3c89 --- /dev/null +++ b/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. + diff --git a/docs/learn/smart-contracts/chain-owners-validators-and-access-nodes.md b/docs/learn/smart-contracts/chain-owners-validators-and-access-nodes.md new file mode 100644 index 00000000000..f53e5f4735d --- /dev/null +++ b/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). \ No newline at end of file diff --git a/docs/learn/smart-contracts/consensus.md b/docs/learn/smart-contracts/consensus.md index 78192da0a89..6206e66cce6 100644 --- a/docs/learn/smart-contracts/consensus.md +++ b/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. \ No newline at end of file diff --git a/docs/learn/smart-contracts/introduction.md b/docs/learn/smart-contracts/introduction.md index db258bb1d9a..56a5e84d065 100644 --- a/docs/learn/smart-contracts/introduction.md +++ b/docs/learn/smart-contracts/introduction.md @@ -4,11 +4,11 @@ all executing and validating the same code.' image: /img/banner/banner_wasp_core_concepts_smart_contracts.png keywords: -- smart contracts -- blockchain -- parallel -- scaling -- explanation + - smart contracts + - blockchain + - parallel + - scaling + - explanation --- @@ -22,6 +22,36 @@ Smart contracts are software applications that run on a distributed network with validating the same code. This ensures the application behaves as expected and that there is no tampering in the program's execution. +### Smart Contract Applications Across Industries + +#### Voting Systems + +Smart contracts can revolutionize [voting systems](https://wiki.iota.org/learn/governance/governance-tech/) by offering +secure, transparent platforms for conducting elections. They ensure the integrity of the voting process, making it +tamper-proof, creating confidence in electoral systems. + +#### Decentralized Finance (DeFi) + +You can use smart contracts to automate complex financial processes like lending, borrowing, and asset trading, +eliminating the need for intermediaries, directly translating into reduced transaction costs and increased transaction +speeds. + +#### Supply Chain Management + +Smart contracts in supply chains provide real-time tracking and authentication of products from manufacturing to +delivery. They ensure transparency and compliance, enhancing trust between suppliers, retailers, and consumers. + +#### Real Estate Transactions + +In real estate, smart contracts streamline property sales by automating title transfers and payments, reducing paperwork +and expediting transactions. This digital approach simplifies the buying and selling process, making it more efficient +and secure. + +#### Intellectual Property and Royalties + +For artists and creators, smart contracts enable direct royalty payments, bypassing traditional intermediaries. This +system ensures fair compensation and transparent distribution of earnings in the music and entertainment industry. + ### Applications You Can Trust As you can be certain that the executed code is always the same (and will not change), this results in @@ -30,8 +60,7 @@ smart contract rules define what the contract can and can not do, making it a de decision-maker. You can use smart contracts for all kinds of purposes. A recurring reason to use a smart contract is to automate -specific -actions without needing a centralized entity to enforce this specific action. A good example is a smart contract +specific actions without needing a centralized entity to enforce this specific action. A good example is a smart contract that can exchange a certain amount of IOTA tokens for land ownership. The smart contract will accept both the IOTA tokens and the land ownership, and will predictably exchange them between both parties without the risk of one of the parties not delivering on their promise. **With a smart contract, code is law**. diff --git a/docs/learn/smart-contracts/invocation.md b/docs/learn/smart-contracts/invocation.md deleted file mode 100644 index d0040378057..00000000000 --- a/docs/learn/smart-contracts/invocation.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -description: 'Smart contracts can be invoked through their entry points, from outside via a request, or from inside via a -call.' -image: /img/logo/WASP_logo_dark.png -keywords: - -- smart contracts -- requests -- on-ledger -- off-ledger -- calls -- invocation -- explanation - ---- - -# Calling a Smart Contract - -## Entry Points - -Like any other computer program, a smart contract will lie dormant until someone or something instructs it to activate. -In the case of smart contracts, the most common way to activate them is to call one of -their [entry points](./smart-contract-anatomy.md#entry-points). It is the same as calling a program's function. It will -take a set of instructions of the smart contract and execute it over the current chain's state. _View entry points_ can -only read the state, while _full entry points_ can read and write to it. - -To invoke a smart contract from outside the chain, the _sender_ (some entity that needs to be identified by a -private/public key pair) has to wrap the call to the entry point into a _request_. -The request has to be cryptographically signed and submitted to the [consensus](./consensus.md) procedure to let the -chain's committee evaluate it and engrave the outcome of its execution into a new state update. - -Upon receiving a request, the committee will execute the wrapped call fully or reject the request with all its potential -changes, never modifying the state halfway. This means that every single request is an atomic operation. - -### Synchronous Composability - -After being invoked by a request, the smart contract code is allowed to invoke entry points of other smart contracts on -the same chain. This means it can _call_ other smart contracts. - -Smart contract calls are deterministic and synchronous, meaning they always produce the same result and execute all -instructions immediately after another. -If a smart contract calls another smart contract, the resulting set of instructions is also deterministic and -synchronous. This means that for a request, it makes no difference if a smart contract's entry point contains the whole -set of instructions or if it is composed by multiple calls to different smart contracts of the chain. - -Being able to combine smart contracts in this way is called _synchronous composability_. - ---- - -## Requests - -A request contains a call to a smart contract and a signature of the sender. The sender also owns the assets and funds -processed within the request. -Unlike calls between smart contracts, requests are not executed immediately. -Instead, they must wait until the chain's _validator_ nodes include them in a request batch. -This means that requests have a delay and are executed in an unpredictable order. - -### Asynchronous Composability - -Requests are not sent by humans exclusively. Smart contracts can also create requests. -For example, a user can send a request to a smart contract that, in turn, sends a request to a decentralized third-party -exchange which would will the user's funds from one currency to another and send them back through another request. - -This is called _asynchronous composability_. - -### 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. However, it is the slowest way to invoke a smart contract. - -### 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 move assets -between chains or Layer 1 accounts. - ---- - -## Gas - -Gas expresses the "cost" of running a request in a chain. Each operation (arithmetics, write to disk, dispatch events, -etc.) has an associated gas cost. - -For users to specify how much they're willing to pay for a request, they need to specify a `GasBudget` in the request. -This gas budget is the "maximum operations that this request can execute" and will be charged as a fee based on the -chain's current [fee policy](/wasp-wasm/reference/core-contracts/governance#fee-policy). - -The funds to cover the gas used will be charged directly from the user's on-chain account. - ---- - -## Allowance - -Any funds sent to the chain via on-ledger requests are credited to the sender's account. - -For contracts to use funds owned by the _caller_, the _caller_ must specify an `Allowance` in the request. Contracts can -then claim any of the allowed funds using the sandbox `TransferAllowedFunds` function. - -The Allowance property looks like the following: - -```go -{ - BaseTokens: uint64 - NativeTokens: [{TokenID, uint256}, ...] - NFTs: [NFTID, ...] -} -``` diff --git a/docs/learn/smart-contracts/isc-architecture.md b/docs/learn/smart-contracts/isc-architecture.md deleted file mode 100644 index 04f216cf7a0..00000000000 --- a/docs/learn/smart-contracts/isc-architecture.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -description: An overview of the IOTA Smart Contracts architecture. -image: /img/multichain.png -keywords: - - smart contracts - - architecture - - Layer 2 - - L2 - - Layer 1 - - L1 - - explanation ---- - -# ISC Architecture - -IOTA Smart Contracts work as a _layer 2_ (L2 for short) extension of the [_IOTA Multi-Asset -Ledger_](../protocols/stardust/core-concepts/multi-asset-ledger.md) (Layer 1, or L1 for short, also sometimes -called the UTXO Ledger). - -In IOTA Smart Contracts, each L2 chain has its own state and smart contracts that cause this state to change. -As validator nodes execute the smart contracts, they tally these state changes and write them into the chain. -Each time they update the state, they collectively agree on a new state and commit to it by publishing its hash to L1. - -Each Layer 2 chain is functionally similar to a traditional blockchain. -However, ISC chains can communicate with Layer 1 and each other, making ISC a more sophisticated protocol. - -![IOTA Smart Contacts multichain architecture](/img/multichain.png 'Click to see the full-size image.') - -_IOTA Smart Contacts multichain architecture._ - -You can find the comprehensive overview of architectural design decisions of IOTA Smart Contracts in the -[ISC white paper](https://files.iota.org/papers/ISC_WP_Nov_10_2021.pdf). diff --git a/docs/learn/smart-contracts/protocol-overview.md b/docs/learn/smart-contracts/protocol-overview.md new file mode 100644 index 00000000000..694e4233f90 --- /dev/null +++ b/docs/learn/smart-contracts/protocol-overview.md @@ -0,0 +1,55 @@ +--- +description: An overview of the ISC Protocol, detailing the function and interaction of smart contracts, virtual machines, validators, state, and blockchains in IOTA. +image: /img/logo/WASP_logo_dark.png +keywords: +- ISC Protocol +- IOTA Smart Contracts +- Virtual Machines +- Validators +- Blockchain Technology +--- +# ISC Protocol Overview + +## TL;DR; + +- [Smart Contracts](#smart-contracts): Digital programs on a blockchain, written in various programming languages, compiled into bytecode and executed by virtual machines. +- [Virtual Machines](#virtual-machines): Essential engines that run smart contracts, process inputs, and enforce rules, with IOTA supporting EVM and WASM VM. +- [Validators](#validators): Key network components operating virtual machines, managing blockchain state and history, and facilitating smart contract execution. +- [State](#state): The dynamic data interacted with and altered by smart contracts, forming the blockchain's historical record. +- [Blockchains](#blockchains): Structures of linked blocks containing state updates, representing the chain’s history and enabling parallel smart contract execution. + + +## Smart Contracts + +Smart contracts are like digital programs on a blockchain, consisting of functions that either view or update the +blockchain's state based on given inputs. They are versatile, written in languages like Solidity, Rust, or Go, and are +compiled into bytecode. This bytecode is then executed by a [virtual machine](#virtual-machines), acting as the +blockchain's engine to process these contracts. + +## Virtual Machines + +[Validators](#validators) run th virtual machines are the powerhouses that run smart contracts. They take the +current [state](#state) of the [blockchain](#blockchains) and the inputs from users, execute the smart contract's +bytecode, and produce a new state. These machines also set rules and restrictions for smart contracts, ensuring secure +and orderly operation. The IOTA architecture currently supports two types of virtual machines: + +* The production-ready EVM (Ethereum Virtual Machine) +* The **experimental** WASM VM (WebAssembly Virtual Machine). + +## Validators + +Validators are critical components in a blockchain network. They operate the virtual machines and are responsible for +storing the [state](accounts-addresses-and-fees.md) and history of the blockchain. Validators process requests to run smart contracts, +achieve consensus on state updates, and create a blockchain that represents the history of said state updates. + +## State + +The state in a [blockchain](#blockchains) is the data that smart contracts interact with and modify. It's a record of +all changes made by executing smart contracts, committed in blocks, and forms the backbone of the blockchain's history. + +## Blockchains + +Blockchains in IOTA are structures composed of blocks linked cryptographically, containing [state](#state) updates. They +chronicle the history of all updates leading to the current state. Chain owners own these blockchains which are produced +by validators. These blockchains are anchored in the IOTA ledger, allowing for parallel anchoring of chains and enabling +simultaneous execution of smart contracts across different chains. diff --git a/docs/learn/smart-contracts/sandbox.md b/docs/learn/smart-contracts/sandbox.md deleted file mode 100644 index d0c70b8e2d7..00000000000 --- a/docs/learn/smart-contracts/sandbox.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -description: 'Smart Contracts can only interact with the world by using the Sandbox interface which provides limited and -deterministic access to the state through a key/value storage abstraction.' -image: /img/sandbox.png -keywords: - -- smart contracts -- sandbox -- interface -- storage abstraction -- explanation - ---- - -# Sandbox Interface - -A smart contract's access to the world has to be restricted. Imagine a smart contract that would directly tap into a -weather forecast website: as the weather changes, the result of the contract's execution will also change. This smart -contract is not deterministic, meaning that you cannot reproduce the result yourself to verify it because the result for -each execution could be different. - -The access to the chain's state has to be curated, too. The chain owner and developers of individual smart contracts are -not necessarily the same entity. A single malicious contract could ruin the whole chain if not limited to its own space. -Instead of working on the state as a whole, each smart contract can only modify a part of it. - -The only way for smart contracts to access data is to use the _Sandbox_ interface, which is deterministic. It provides -their internal state as a list of key/value pairs. - -![Sandbox](/img/sandbox.png) - -Besides reading and writing to the contract state, the Sandbox interface allows smart contracts to access: - -- The [ID](/wasp-wasm/explanations/how-accounts-work) of the contract. -- The details of the current request or view call. -- The current request allowance and a way to claim the allowance. -- The balances owned by the contract. -- The ID of whoever had deployed the contract. -- The timestamp of the current block. -- Cryptographic utilities like hashing, signature verification, and so on. -- The [events](/wasp-wasm/how-tos/schema-tool/events) dispatch. -- Entropy that emulates randomness in an unpredictable yet deterministic way. -- Logging. Used for debugging in a test environment. - -The Sandbox API available in "view calls" is slightly more limited than the one available in normal "execution calls". -For example, besides the state access being read-only for a view, they cannot issue requests, emit events, etc. diff --git a/docs/learn/smart-contracts/smart-contract-anatomy.md b/docs/learn/smart-contracts/smart-contract-anatomy.md deleted file mode 100644 index 1aaa6b03be0..00000000000 --- a/docs/learn/smart-contracts/smart-contract-anatomy.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -description: Each smart contract instance has a program with a collection of entry points and a state. -image: /img/tutorial/SC-structure.png -keywords: - - smart contracts - - structure - - state - - entry points - - Wasm - - explanation ---- - -# Anatomy of a Smart Contract - -Smart contracts are programs that are immutably stored in the chain. - -Through _VM abstraction_, the ISC virtual machine is agnostic about the interpreter used to execute each smart contract. -It can support different _VM types_ (i.e., interpreters) simultaneously on the same chain. -For example, it is possible to have [Wasm](/wasp-wasm/introduction/) and [EVM/Solidity](/wasp-evm/introduction/) smart -contracts coexisting on the same chain. - -The logical structure of IOTA Smart Contracts is independent of the _VM_ type: - -![Smart Contract Structure](/img/tutorial/SC-structure.png) - -## Identifying a Smart Contract - -Each smart contract on the chain is identified by a _hname_ (pronounced "aitch-name"), which is a `uint32` value -calculated as a hash of the smart contract's instance name (a string). -For example, the hname of the [`root`](/wasp-wasm/reference/core-contracts/root/) core contract -is `0xcebf5908`. This -value uniquely identifies this contract in every chain. - -## State - -The smart contract state is the data owned by the smart contract and stored on the chain. -The state is a collection of key/value pairs. -Each key and value are byte arrays of arbitrary size (there are practical limits set by the underlying database, of -course). -You can think of the smart contract state as a partition of the chain's data state, which can only be written by the -smart contract program itself. - -The smart contract also owns an _account_ on the chain, stored as part of the chain state. -The smart contract account represents the balances of base tokens, native tokens, and NFTs controlled by the smart -contract. - -The smart contract program can access its state and account through an interface layer called the _Sandbox_. -Only the smart contract program can change its data state and spend from its -account. Tokens can be sent to the smart contract account by any other agent on -the ledger, be it a wallet with an address or another smart contract. - -See [Accounts](https://wiki.iota.org/build/wasp-wasm/how-accounts-work/) for more information on sending and receiving -tokens. - -## Entry Points - -Each smart contract has a program with a collection of _entry points_. -An entry point is a function through which you can invoke the program. - -There are two types of entry points: - -- _Full entry points_ (or simply _entry points_): These functions can modify - (mutate) the smart contract's state. -- _View entry points_ (or _views_): These are read-only functions. They are only used - to retrieve the information from the smart contract state. They cannot - modify the state, i.e., they are read-only calls. - -## Execution Results - -After a request to a Smart Contract is executed (a call to a full entry point), a _receipt_ will be added to -the [`blocklog`](/wasp-wasm/reference/core-contracts/blocklog/) core contract. The receipt details the -execution results -of said request: whether it was successful, the block it was included in, and other information. -Any events dispatched by the smart contract in context of this execution will also be added to the receipt. - -## Error Handling - -Smart contract calls can fail: for example, if they are interrupted for any reason (e.g., an exception) or if it -produces an error (missing parameter or other inconsistency). -Any gas spent will be charged to the sender, and the error message or value is stored in the receipt. diff --git a/docs/learn/smart-contracts/smart-contract-execution.md b/docs/learn/smart-contracts/smart-contract-execution.md new file mode 100644 index 00000000000..dd4083df540 --- /dev/null +++ b/docs/learn/smart-contracts/smart-contract-execution.md @@ -0,0 +1,70 @@ +--- +description: An in-depth exploration of smart contract execution in blockchain technology, detailing their structure, invocation, and associated fees. +image: /img/logo/WASP_logo_dark.png +keywords: +- Smart Contracts +- Blockchain Technology +- Validators +- User Requests +- Gas Fees +--- + +# Smart Contract Execution + +## TL;DR; + +- [Introduction](#introduction): Smart contracts are self-executing contracts on blockchain networks, activated by validators in response to user requests. +- [Structure of a Smart Contract](#structure-of-a-smart-contract): Comprising functions within a decentralized framework, smart contracts have a unique state and accounts, managed by validator node consensus. +- [View Entry Points](#view-entry-points): Read-only operations in smart contracts that do not modify data or incur execution fees. +- [Full Entry Points](#full-entry-points): Functions that can alter a contract's state and typically require execution fees. +- [Invoking a Smart Contract](#invoking-a-smart-contract): Activation of smart contracts through requests, which can be off-ledger or on-ledger, with associated gas fees for computational resources. + +## Introduction + +Smart contracts are essentially self-executing contracts, run on blockchain networks. Network nodes, also known as +[Validators](chain-owners-validators-and-access-nodes.md) activate these contracts in response to specific [user requests](#invoking-a-smart-contract). + +## Structure of a Smart Contract + +At it's core a smart contract is a collection of functions, much like a traditional computer program. However, they operate +within the blockchain’s decentralized framework, meaning that a network of [validator nodes](chain-owners-validators-and-access-nodes.md) run the exact +same code and come to a [consensus](consensus.md) on the next [state](accounts-addresses-and-fees.md) update. + +Every smart contract has its unique state, which is essentially a collection of data stored as key-value pairs. This +state is only modifiable by the contract's functions, ensuring secure and controlled interactions. Additionally, smart +contracts possess their own accounts within the blockchain, representing their token balances. This structure allows +them to interact with and manage digital assets autonomously. + +### View Entry Points + +View entry points, or functions, are read-only operations that do not alter the contract's data; therefore, they do not incur +any execution fees. + +### Full Entry Points + +Full entry points, or functions, can modify the contract's state and typically require fees to execute. +These fees compensate for the computational resources used in processing the functions. + +## Invoking a Smart Contract + +To activate or 'invoke' a smart contract, users, or other contracts, send requests to the chain. These requests are +calls to the contract’s functions and must be cryptographically signed to ensure security and authenticity. +The type of request determines how it is processed: + +### Off-Ledger Requests + +Off-ledger requests are directly sent to the blockchain's validator nodes, bypassing the main ledger. This type of +request is faster as it avoids the additional processing time of the main ledger but is typically used when the +necessary assets are already within the blockchain’s ecosystem. + +### On-Ledger Requests + +On-ledger requests, on the other hand, pass through the blockchain's main ledger. While slower due to the ledger’s +processing, these requests are essential for transactions that involve transferring assets across different chains or +accounts. The blockchain’s ledger, like the Tangle in IOTA's case, acts as a mediator in these transactions, ensuring +validity and security. + +### Fees and Gas + +Running a request on a blockchain involves computational resources, for which users must compensate. This compensation, +known as 'gas', varies depending on the complexity and size of the request. Users specify a `GasBudget` \ No newline at end of file diff --git a/docs/learn/smart-contracts/smart-contracts.md b/docs/learn/smart-contracts/smart-contracts.md deleted file mode 100644 index db258bb1d9a..00000000000 --- a/docs/learn/smart-contracts/smart-contracts.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -description: 'Smart contracts are applications you can trust that run on a distributed network with multiple validators -all executing and validating the same code.' -image: /img/banner/banner_wasp_core_concepts_smart_contracts.png -keywords: - -- smart contracts -- blockchain -- parallel -- scaling -- explanation - ---- - -# Smart Contracts - -![Wasp Node Smart Contracts](/img/banner/banner_wasp_core_concepts_smart_contracts.png) - -## What Are Smart Contracts? - -Smart contracts are software applications that run on a distributed network with multiple validators executing and -validating the same code. This ensures the application behaves as expected and that there is no tampering in the -program's execution. - -### Applications You Can Trust - -As you can be certain that the executed code is always the same (and will not change), this results in -applications you can trust. This allows you to use smart contracts for applications with a trust issue. The -smart contract rules define what the contract can and can not do, making it a decentralized and predictable -decision-maker. - -You can use smart contracts for all kinds of purposes. A recurring reason to use a smart contract is to automate -specific -actions without needing a centralized entity to enforce this specific action. A good example is a smart contract -that can exchange a certain amount of IOTA tokens for land ownership. The smart contract will accept -both the IOTA tokens and the land ownership, and will predictably exchange them between both parties without the risk of -one of the parties not delivering on their promise. **With a smart contract, code is law**. - -### Scalable Smart Contracts - -Anyone willing to pay the fees for deploying a smart contract on a public blockchain can deploy one. Once your smart -contract has been deployed to the chain, you no longer have the option to change it, and you can be sure that your -smart contract application will be there as long as that blockchain exists. Smart contracts can communicate with one -another, and you can invoke programmed public functions on a smart contract to trigger actions on a smart contract, or -address the state of a smart contract. - -Because smart contracts do not run on a single computer but on many validators, a network of validators can only -process so many smart contracts at once, even if the software has been written optimally. This means smart contracts are -expensive to execute, and do not scale well on a single blockchain, often resulting in congested networks and costly -fees for executing functions on smart contracts. **By allowing many blockchains executing smart contracts to run in -parallel** and communicate with one another, **IOTA Smart Contracts solves this scalability problem.** - -At the same time, ISC provides advanced means of communication between its chains and preserves the ability to create -complex, composed smart contracts. diff --git a/docs/learn/smart-contracts/state-management-and-anchoring.md b/docs/learn/smart-contracts/state-management-and-anchoring.md new file mode 100644 index 00000000000..7320c737431 --- /dev/null +++ b/docs/learn/smart-contracts/state-management-and-anchoring.md @@ -0,0 +1,46 @@ +--- +description: An overview of state management and anchoring in IOTA Smart Contracts, detailing how blockchain state and digital assets are handled and secured. +image: /img/logo/WASP_logo_dark.png +keywords: + - IOTA Smart Contracts + - State Management + - Blockchain Technology + - Digital Assets + - Anchoring Process +--- + +# State Management and Anchoring + +## TL;DR; + +- [Introduction](#introduction): In IOTA Smart Contracts, 'state' represents the chain's current status, including data and digital assets, updated via blockchain blocks. +- [Digital Assets](#digital-assets): Digital assets in IOTA are managed by Layer 1 addresses, with each smart contract chain having a unique address to act as a custodian. +- [Data](#data): The data state comprises key/value pairs managed outside the UTXO ledger by validator nodes, ensuring data consistency and traceability. +- [Anchoring](#anchoring): The anchoring process embeds the data state hash into the L1 ledger, creating a tamper-proof record and ensuring a globally consistent state. + +## Introduction + +In IOTA Smart Contracts, the 'state' represents the current status of the chain, including its data and digital assets. +This state is updated through blocks that form an immutable blockchain. Each block contains changes or mutations, +leading to a new state. + +## Digital Assets + +Digital assets in IOTA are controlled by addresses on the Layer 1 (L1) IOTA UTXO ledger. Each smart contract chain has a +unique L1 address acting as a custodian for these assets, which include base tokens, native tokens, and NFTs. These +assets are consolidated within the chain's account, and their movements are tracked as part of the chain's state +changes. + +## Data + +The data state of an IOTA chain comprises key/value pairs maintained outside the UTXO ledger in a distributed database +managed by validator nodes. This database contains the 'solid state', while the 'virtual state' is an in-memory +collection during smart contract execution. The data state is defined by its hash, timestamp, and index, ensuring +consistency and traceability of changes. + +## Anchoring + +Anchoring is the process of embedding the hash of the data state into a state UTXO on the L1 ledger, providing a +tamper-proof record. This mechanism ensures that there is global consensus on the chain’s state, which is both immutable +and consistent. The state transition in the chain occurs via a transaction that updates both the chain's assets and the +state hash, represented as a sequence of UTXOs on the L1 ledger. diff --git a/docs/learn/smart-contracts/state_manager.md b/docs/learn/smart-contracts/state_manager.md deleted file mode 100644 index b3265edd14d..00000000000 --- a/docs/learn/smart-contracts/state_manager.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -description: State manager is Wasp component, which is responsible for keeping the store up to date. -image: /img/logo/WASP_logo_dark.png -keywords: - - state manager - - pruning - - snapshot - - write ahead log - - WAL ---- - -# State Manager - -State manager aims at keeping the state of the node up to date by retrieving missing data and ensuring that it is -consistently stored in the DB. It services requests by other Wasp components (consensus, _mempool_), which mainly -consist of ensuring that the required state is available in the node: that it may be retrieved from the permanent -store of the node (the database; DB). An obvious way to obtain the latest state is to obtain all of the blocks, -that resulted in making that state. So to obtain state index `n`, state manager first must commit block index `0` -(origin block), then block index `1`, then block index `2` etc. up to block index `n` precisely in that order. -There are two ways for state manager to obtain blocks (other than origin block): - -1. Receive them directly from this node's consensus when the new state[^1] is decided. State manager has no influence - to this process. -2. Receive them from neighbouring nodes upon request, provided the block is available there. - -Independently of the way the block is received, it is stored in state manager's cache (for quicker access) and WAL -(to ensure availability). Therefore it may happen that the block can be retrieved from there. - -[^1] A block is a difference between two consecutive states. To make state index `n`, block index `n` must be obtained -and committed on top of state index `n-1`. Although state manager manipulates blocks, in this description sometimes -"state" and "block" will be used interchangeably as "obtaining block" or "committing block" is essentially the same as -"obtaining state" or "committing state" respectively, having in mind that previous state is already obtained or committed. Block -and state has some other common properties, e.g. block index `n`, which applied to state index `n-1` produces state index `n`, -contains the same commitment as state index `n`. - -## Snapshot - -Once in a while there might be a need to add a new node to the network. This node has no knowledge of chain's history -and it still needs to have the newest state of the chain (to catch up the chain). If the chain has been running for a while, -it might have gone through many sate transitions and downloading that many blocks may take a long period of time. To avoid that, -some nodes in the network can be configured to dump a complete state of the chain at some time into a file periodically -(see `snapshots.period` parameter). This file is called a snapshot. Loading a snapshot to DB produces the same state as downloading -and committing all the blocks that produced that state. However as those blocks aren't downloaded, they are not available in the DB, -except a block with the same state index as snapshot. - -The snapshot format is as follows: - -1. number `4` in 4 byte unsigned integer little endian format representing the length of state index, -2. state index in 4 byte unsigned integer little endian format, -3. number `40` in 4 byte unsigned integer little endian format representing the length of state commitment: `20` bytes for trie root and - `20` bytes for hash of a block, which was last committed to make this state (block with the same index as state), -4. trie root in `20` bytes, -5. the mentioned block's hash in `20` bytes, -6. number `0` in 1 byte unsigned integer format representing snapshot version, -7. bytes representing mentioned block, -8. bytes representing trie of the state. - -The node that makes a snapshot can serve it over http and new nodes can use this to speed up the catch up. Serving the snapshots -over http is beyond the scope of Wasp and should be done in addition. Wasp is only responsible for making snapshots in local -(configurable by `snapshots.localPath` parameter) folder and obtaining them on start when needed from the same local folder or from -configured (by `snapshots.networkPaths` parameter) URLs. A folder, referenced in the `snapshots.networkPaths` parameter must contain -`INDEX` file with new line separated list of snapshot file names. - -If a chain starts with an empty database (usually if the database hasn't been created yet or was deleted), the node checks if -it can load a snapshot: it scans the local folder and all the network addresses for available snapshot files. In the local folder, it reads -all the files with names that satisfy the search pattern `*-*.snap`. In each network location, Wasp reads all the files listed in `INDEX` -file of that location. Wasp reads a state index and a commitment from the contents of these files. File names are not used to obtain -this information, and full snapshot files are not (down)loaded yet. The node chooses -the one with the largest state index and loads it to the store among all available snapshot files. If several files have the same largest state index, -the node loads them one by one, starting from the local ones until one snapshot is loaded correctly. If loading fails for all candidates, -the node will start with an empty database. - -You can use the `snapshots.snapshotsToLoad` parameter to load a specific snapshot. In that case, the node searches for snapshots with -the block hash provided in the parameter. Once again, if loading all found files fails, the node starts with an empty database. - -After a snapshot is loaded, earlier blocks (ones with a smaller state index than the snapshot) cannot be retrieved and committed to the DB -(this is discussed in [Obtaining blocks section](#obtaining-blocks)). This constraint can cause problems (especially in reorg) -if the loaded snapshot is too recent. To avoid that, making snapshots is delayed by `snapshots.delay` states. E.g., if `snapshots.period` -is `100` and `snapshots.delay` is `20`, then snapshot index `100` will be produced. When block index `120` is committed, snapshot index -`200` will be produced, when snapshot index `220` is committed, etc... For the data to be available after this delay, `snapshot.delay` -value must be considerably smaller than `stateManager.pruningMinStatesToKeep`. - -## Obtaining blocks - -Requests to the state manager contain the state commitment and the state manager must ensure, that block (state) with this -commitment is present in the DB. It is possible that to satisfy the request state manager needs to retrieve -several blocks. However this cannot be done in one step as only the commitment of the requested block is known. For this -reason state (block) contains a commitment of the previous block. Previous block must be committed prior to committing the -requested block. And this logic can be extended up to the block, which is already present in the DB, or until the origin -state is reached. - -E.g., let's say, that the last state in the DB is state index `10` and request to have state index `12` is received. -State manager does this in following steps: - -1. Block index `12` is obtained, and commitment of block index `11` is known. -2. As the commitment of block (state) index `11` is known, the block may be requested and obtained. After obtaining block - index `11` commitment of block index `10` is known. -3. Using block index `10` commitment the DB is checked to make sure that it is already present. -4. As block index `10` is already committed, block index `11` is committed. This makes state `11` present in the DB. -5. As state `11` is already committed, block index `12` is committed. This makes state `12` present in the DB and completes - the request. - -To obtain blocks, state manager sends requests to 5 other randomly chosen nodes. If the block is not received (either messages -got lost or these nodes do not have the requested block), 5 other randomly chosen nodes are queried. This process is repeated -until the block is received (usually from other node but may also be from this node's consensus) or the request is no longer -valid. - -If difference between state indexes of requested state and available in the DB state is large, this chain can get very long. -In order to limit its length, if requested block index is a) smaller than state index of snapshot, which was loaded on node -start, or b) smaller than largest state index among the pruned blocks (see [Pruning](#pruning)), the node panics. If this panicking -continues, the administrator may decide to delete the DB and start the node from (possibly configured) snapshot. - -## Block cache - -Block cache is in memory block storage. It keeps a limited amount (configured by `stateManager.blockCacheMaxSize`) of blocks -for limited amount of time (configured by `stateManager.blockCacheBlocksInCacheDuration`) to make the retrieval -quicker. E.g., in the last step of example of the previous section block index `12` must be committed. It is obtained in -the step 1, but as several steps of the algorithm are spread over time with requests to other nodes in between, and -several requests to obtain the same block may be present, it is not feasible to store it in request. However it would -be wasteful to fetch it twice on the same request. So the block is stored in cache in step 1 of the algorithm and -retrieved from cache later in the last step. - -The block is kept in the cache no longer that predetermined amount of time (configured by `stateManager.blockCacheBlocksInCacheDuration`). -If upon writing to cache blocks in cache limit is exceeded, block, which is in cache the longest, is removed from cache. - -## Block write ahead log (WAL) - -Upon receiving a block, its contents is dumped into a file and stored in a file system. The set of such files is WAL. - -The primary motivation behind creating it was in order not to deadlock the chain. Upon deciding on next state committee -nodes send the newest block to state manager and at the same time one of the nodes send the newest transaction to L1. -In an unfavourable chain of events it might happen that state managers of the committee nodes are not fast enough to commit -the block to the DB (see algorithm in [Obtaining blocks section](#obtaining-blocks)), before the node crashes. This leaves -the nodes in the old state as none of the nodes had time to commit the block. However the L1 reports the new state as -the latest although none of the nodes can be transferred to it. The solution is to put the block into WAL as soon as -possible so it won't be lost. - -Currently upon receiving the new confirmed block from node's consensus, state manager is sure that its predecessor is in the DB, -because consensus sends other requests before sending the new block, so WAL isn't that crucial any more. However, it is useful -in several occasions: - -1. Storing preliminary block, which is sent by consensus of other nodes. -2. When the node is catching up many states and block cache limit is too small to store all the blocks, WAL is used to avoid - fetching the same block twice. -3. In case of adding new node to the network to avoid catch up taking a lot of time when snapshots are not available, - the new node can be configured (`wal.loadToStore=true`) to load the DB with blocks from WAL on startup. WAL can be copied - from some other node. This is also true for any catch up over many states. - -## Pruning - -In order to limit the DB size, old states are deleted (pruned) from it on a regular basis. The amount of states to keep is -configured by two parameters: one in the configuration of the node (`stateManager.pruningMinStatesToKeep`) and one in the governance contract -(`BlockKeepAmount`). The resulting limit of previous states to keep is the larger of the two. Every time a block is committed -to the DB, states which are over the limit are pruned. However, to avoid freezing State manager for too long, no more than -`stateManager.pruningMaxStatesToDelete` blocks are pruned in a single run. The algorithm ensures that oldest states are pruned -first to avoid gaps between available states on the event of some failure. - -Pruning may be disabled completely via node configuration to make an archive node: node that contains all the state ever -obtained by the chain. Note, that such node will require a lot of resources to maintain: mainly disk storage. - -## Parameters - -### State manager - -The following parameters may be provided in section `stateManager`: - -- `blockCacheMaxSize`: the limit of the blocks in block cache. Default is 1k. -- `blockCacheBlocksInCacheDuration`: the limit of the time block stays in block cache. Default is 1 hour. -- `blockCacheBlockCleaningPeriod`: how often state manager should find and delete blocks, that stayed in block cache - for too long. Default is every minute. -- `stateManagerGetBlockRetry`: how often requests to retrieve the needed blocks from other nodes should be repeated. - Default is every 3 seconds. -- `stateManagerRequestCleaningPeriod`: how often state manager should find and delete requests, that are no longer valid. - Default is every second. -- `stateManagerTimerTickPeriod`: how often state manager should check if some maintenance (cleaning requests or block cache, - resending requests for blocks) is needed. Default is every second. There is no point in making this value larger than - any of `blockCacheBlockCleaningPeriod`, `stateManagerGetBlockRetry` or `stateManagerRequestCleaningPeriod`. -- `pruningMinStatesToKeep` : minimum number of old states to keep in the DB. Note that if `BlockKeepAmount` in - governance contract is larger than this value, then more old states will be kept. - Default is 10k. 0 (and below) disables pruning. -- `pruningMaxStatesToDelete`: maximum number of states to prune in one run. This is needed in order not to grab - state manager's time for pruning for too long. Default is 1k. - -### Snapshots - -The following parameters may be provided in section `snapshots`: - -- `snapshotsToLoad`: the comma sepparated list of `:` pairs, where chain `` must be started using snapshot with block hash ``. - The list can also contain `` entry. This hash will be used for other chains, which are not configured separately. There is - no point in having several `` or `:` entries with the same `` as only the last such entry is taken into - account. Note that if the chain is configured to start from some snapshot and the snapshot is not available (or another error occurs - during snapshot loading), the chain will start with an empty DB. The default is an empty list, which means that the newest available snapshot - will be loaded for every chain. -- `period`: how often state snapshots should be made: 1000 meaning "every 1000th state", 0 meaning "making snapshots is disabled". - Snapshots are disabled by default. -- `delay`: how many states to delay making the snapshot; it must be considerably smaller than `stateManager.pruningMinStatesToKeep`. - The default is 20. -- `localPath`: the path to the snapshots folder in this node's disk. Default is `waspdb/snap`. -- `networkPaths`: the comma-separated list of URLs that serve snapshots. The URLs may have the HTTP (e.g., `http://server.org/path/`) or the HTTPS - (e.g., `https://server.org/path/`) scheme for remote locations or a file path (e.g., `file://path/to/folder`) scheme for local snapshot locations. - The scheme is compulsory in the URL. The list is empty by default. - -### WAL - -The following parameters may be provided in section `wal`: - -- `loadToStore`: load blocks from WAL to the store on node start-up. This function is off (`false`) by default. -- `enabled`: whether the WAL is enabled. It is enabled by default. -- `path`: the path to the WAL folder. Default is `waspdb/wal`. diff --git a/docs/learn/smart-contracts/states.md b/docs/learn/smart-contracts/states.md deleted file mode 100644 index c507af37dfa..00000000000 --- a/docs/learn/smart-contracts/states.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -description: 'The state of the chain consists of balances of native IOTA digital assets and a collection of key/value -pairs which represents use case-specific data stored in the chain by its smart contracts outside the UTXO ledger.' -image: /img/chain0.png -keywords: - -- state -- transitions -- balances -- digital assets -- UTXO -- transitions -- explanation ---- - -# State, Transitions, and State Anchoring - -## State of the Chain - -The state of the chain consists of: - -- A ledger of accounts owning IOTA _digital assets_ (base tokens, native tokens, and NFTs). The chain acts as a custodian - for those funds on behalf of each account's owner. -- A collection of arbitrary key/value pairs (the _data state_) that contains use case-specific data stored by the smart - contracts in the chain. - -The chain's state is an append-only (immutable) _data structure_ maintained by the distributed consensus of its -validators. - -## Digital Assets on the Chain - -Each native L1 account in the IOTA UTXO ledger is represented by an address and controlled by an entity holding the -corresponding private/public key pair. -In the UTXO ledger, an account is a collection of UTXOs belonging to the address. - -Each ISC L2 chain has a L1 account, called the _chain account_, holding all tokens entrusted to the chain in a single -UTXO, the _state output_. -It is similar to how a bank holds all deposits in its vault. This way, the chain (the entity controlling the state -output) becomes a custodian for the assets owned by its clients, similar to how the bank’s client owns the money -deposited in the bank. - -The consolidated assets held in the chain are the _total assets on-chain_, which are contained in the state output of -the chain. - -The chain account is controlled by a _chain address_, also known as _chain ID_. -It is a special kind of L1 address, an _alias address_, which abstracts the controlling entity (the state controller -address) from the identity of the chain: the controlling entity of the chain may change, while the chain ID stays the -same. - -## The Data State - -The data state of the chain consists of a collection of key/value pairs. -Each key and each value are arbitrary byte arrays. - -In its persistent form, the data state is stored in a key/value database outside the UTXO ledger and maintained by the -validator nodes of the chain. -The state stored in the database is called the _solid state_. - -While a smart contract request is being executed, the _virtual state_ is an in-memory collection of key/value pairs that -can become solid upon being committed to the database. -An essential property of the virtual state is the possibility of having several virtual states in parallel as -candidates, with a possibility for one of them to be solidified. - -The data state has a state hash, a timestamp, and a state index. -The state hash is usually a Merkle root, but it can be any hashing function of all data in the data state. - -The data state hash and on-chain assets are contained in a single atomic unit on the L1 ledger: the state UTXO. -Each state mutation (state transition) of the chain is an atomic event that changes the on-chain assets and the data -state, consuming the previous state UTXO and producing a new one. - -## Anchoring the State - -The data state is stored outside the ledger, on the distributed database maintained by _validator_ nodes. -_Anchoring the state_ means placing the hash of the data state into the state UTXO and adding it to the L1 UTXO ledger. -The UTXO ledger guarantees that there is _exactly one_ such output for each chain on the ledger at every moment. -We call this output the _state output_ (or state anchor) and the containing transaction the _state transaction_ (or -anchor transaction) of the chain. -The state output is controlled (i.e., can be unlocked/consumed) by the entity running the chain. - -With the anchoring mechanism, the UTXO ledger provides the following guarantees to the IOTA Smart Contracts chain: - -- There is a global consensus on the state of the chain -- The state is immutable and tamper-proof -- The state is consistent (see below) - -The state output contains: - -- The identity of the chain (its L1 alias address) -- The hash of the data state -- The state index, which is incremented with each new state output - -## State Transitions - -The data state is updated by mutations of its key/value pairs. -Each mutation either sets a value for a key or deletes a key (and the associated value). -Any update to the data state can be reduced to a partially ordered sequence of mutations. - -A _block_ is a collection of mutations to the data state that is applied in a state transition: - -```go -next data state = apply(current data state, block) -``` - -The state transition in the chain occurs atomically in a L1 transaction that consumes the previous state UTXO and -produces the next one. The transaction includes the movement of the chain's assets and the update of the state hash, - -At any moment in time, the data state of the chain is a result of applying the historical sequence of blocks, starting -from the empty data state. - -![State transitions](/img/chain0.png) - -On the L1 UTXO ledger, the state's history is represented as a sequence (chain) of UTXOs, each holding the chain’s -assets in a particular state and the anchoring hash of the data state. -Note that not all the state's transition history may be available: due to practical reasons, older transactions may be -pruned in a snapshot process. -The only thing guaranteed is that the tip of the chain of UTXOs is always available (which includes the latest data -state hash). - -The ISC virtual machine (VM) computes the blocks and state outputs that anchor the state, which ensures that the state -transitions are calculated deterministically and consistently. - -![Chain](/img/chain1.png) diff --git a/docs/learn/smart-contracts/validators.md b/docs/learn/smart-contracts/validators.md deleted file mode 100644 index 07e1ea7633c..00000000000 --- a/docs/learn/smart-contracts/validators.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -description: Each chain is run by a network of validator nodes which run a consensus on the chain state update. -image: /img/logo/WASP_logo_dark.png -keywords: - - validators - - validator nodes - - access nodes - - consensus - - state update - - explanation ---- - -# Validators - -Each chain is run by that chain's _committee of validators_. This committee owns a key that is split between all of its -validators. Each key share is useless on its own, but a collective signature gives validators complete control over the -chain. - -The committee of validators is responsible for executing the smart contracts in the chain and thus calculating a _state -update_. -All validators execute exactly the same code and reach a consensus on the state update. -Once the next state is computed and validated, it is committed to each validator's database, a new _block_ is added to -the chain (containing the state mutations), and the _state hash_ is saved in the L1 ledger. - -Depending on the governance model, chain owners can rotate the committee of validators. -By rotating the committee of validators, validators can be deleted, added, or replaced. - -ISC does not define how to select validators to form a committee: it could be a solitary choice of the chain's owner, or -it could be a public competition between candidates. -ISC does not define how validators are rewarded either. - -## Access Nodes - -It is possible to have some nodes act as _access nodes_ to the chain without being part of the committee of -validators. -All nodes in the subnet (validators and non-validators) are connected through statically assigned trust -relationships and each node is also connected to the IOTA L1 node to receive updates on the chain’s L1 -account. - -Any node can optionally provide access to smart contracts for external callers, allowing them to: - -- Query the state of the chain (i.e., _view calls_) -- Send off-ledger requests directly to the node (instead of sending an on-ledger request as a L1 transaction) - -It is common for validator nodes to be part of a private subnet and have only a group of access nodes exposed to the -outside world, protecting the committee from external attacks. - -The management of validator and access nodes is done through -the [`governance` core contract](/wasp-wasm/reference/core-contracts/governance/).