diff --git a/docs/content/about-iota/about-iota.mdx b/docs/content/about-iota/about-iota.mdx index a306cac3b35..1ffb6acb93e 100644 --- a/docs/content/about-iota/about-iota.mdx +++ b/docs/content/about-iota/about-iota.mdx @@ -1,57 +1,80 @@ ---- -title: About IOTA ---- +# About IOTA -The name IOTA is the ninth letter of the Greek alphabet (Ι, ι) and is used figuratively in English to mean a very small amount, reflecting its status as one of the smallest Greek letters. +The IOTA ecosystem enables programmability in both [Layer 1](#layer-1) and [Layer 2](#layer-2) using [Move](#move) and [EVM/Solidity](#evm) smart contracts respectively. -When you read about IOTA in this documentation, it's referencing all the pieces of the system that comprise the blockchain. This includes the blockchain itself, its various networks (Mainnet, for example), the activity on the blockchain (transaction blocks), the distributed entities that verify this activity (validators), and the Full nodes that execute transaction blocks. The documentation refers to the entirety of these elements as the IOTA platform, or simply IOTA. +## Layer 1 -## The IOTA blockchain +### Move -IOTA is defined as a Layer 1 protocol blockchain. In basic terms, this means that IOTA performs its own consensus and validation for transaction blocks (activity) on its networks using its own native token (IOTA, in this case). Ethereum (ETH) and Bitcoin (BTC) are other examples of Layer 1 blockchains. +Move is a powerful, secure programming language designed specifically for digital asset management and smart contracts. Its unique features make it an ideal choice for developers working in the blockchain space. Here are the key features of Move: -Layer 2 blockchains, by contrast, leverage the infrastructure of Layer 1 networks, relying on the Layer 1 blockchain to finalize transaction blocks. Polygon (MATIC) is an example of a Layer 2 blockchain that extends Ethereum. +#### Object-Centric Design -## IOTA tokens +Move is fundamentally object-centric, allowing developers to intuitively model complex data structures and interactions. In Move, you can define objects representing assets, users, contracts, and more, facilitating a natural and straightforward way to manage state and behavior. -The native token for the IOTA network is IOTA. Transaction blocks on IOTA often deal with small fractions of the value of one IOTA. To make these transaction blocks easier to work with, IOTA provides NANOS. It takes one billion NANOS to equal one IOTA. +#### Performance -It costs money to provide computational power to process transaction blocks and store their results. The term for the cost of processing transaction blocks is "gas". You pay for gas and the cost of storing data with a blockchain's native tokens, in this case, IOTA (or NANOS). +Move is based on the object model, not a shared global state. This allows transactions to be executed in parallel, which translates into a network with high throughput, less congestion, and therefore lower [gas](#gas-on-iota) fees. -To learn more about the tokenomics of IOTA, see the following topics: +#### Security -- [IOTA Tokenomics](./tokenomics.mdx) -- [IOTA Token](./tokenomics/iota-token.mdx) -- [Gas in IOTA](./tokenomics/gas-in-iota.mdx) +Move is based on Rust, a programming language known for its [performance and safety](iota-architecture/iota-security.mdx). It's almost impossible to make a programming mistake that the compiler won't catch before you deploy your smart contract. Additionally, given the object-centric approach, assets that reside in your account can't be accessed without your account keys. These features allow for more complex smart contract applications, as any mistakes outside implementation logic will be caught before deploying. -## Delegated proof-of-stake consensus +:::warning -IOTA uses a delegated proof-of-stake (DPoS) consensus mechanism to validate on-chain transaction blocks. This means that validators on the IOTA network must have a certain amount of IOTA secured on IOTA Mainnet, either with their own funds or in partnership with IOTA Foundation, to prove their interest in the security of the blockchain. This approach aligns the interest of all validators with that of IOTA users (an efficient, secure blockchain), without the high energy-resource demands of earlier blockchains. +While the Move compiler catches many development mistakes, smart contracts can still have unintended edge cases and issues within their written logic. For this reason, it's still highly recommended to have smart contracts audited and double-checked, even when written in Move. -To learn more about consensus on IOTA, see the following guides and topics: +::: -- [Validator Committee](../operator/validator-committee.mdx) -- [IOTA Full Node Data Management](../operator/data-management.mdx) - +### Networks +#### IOTA Mainnet -## IOTA networks +The IOTA Mainnet processes production transaction blocks. The IOTA Mainnet's tokens have a real-world value, so we recommend that you use the IOTA Testnet or Devnet to develop your application. -IOTA has several networks available, each serving a different purpose. +#### IOTA Testnet -- **Mainnet:** The network that processes production transaction blocks. When you trade IOTA or NFTs that are ultimately based on fiat currency, you are doing so on the Mainnet network of IOTA. -- **Testnet:** Staging network to provide quality assurance that any planned changes to IOTA do not adversely impact performance. Developers can use this network to test their code before placing it in production. -- **Devnet:** A more unstable network that is used to develop new features. Developers can leverage this network to code against the latest planned features of IOTA. -- **Localnet:** You can run an IOTA network on your local computer. Developing on a local network provides an optimized workflow in an environment you control. +The IOTA Testnet serves as a staging network and quality assurance. You can use this network to test your dApps and verify that planned changes do not adversely impact performance before deploying them to production. -To learn more about these networks and how to interact with them, see the following guides: +#### IOTA Devnet -- [Create a Local IOTA Network](../developer/getting-started/local-network.mdx) -- [Connect to IOTA](../developer/getting-started/connect.mdx) +The IOTA Devnet is used to develop new features. You can use this network to code with the latest planned features of IOTA. -## Move +## Layer 2 -The Move language provides the logic for all activity on IOTA, like trading NFTs, playing IOTA-integrated games (dApps), and all other transaction-based events. The IOTA platform uses a concept novel to earlier blockchains, where blocks on the chain are actually objects that define assets rather than simple key-value stores that define addresses. The increased programmability inherent with objects required a more robust logic engine to maximize the benefits of this new approach to blockchain technology. +### EVM -To learn more about Move, see [Move Concepts](../developer/iota-101/iota-move-concepts/iota-move-concepts.mdx). +[EVM](https://ethereum.org/en/developers/docs/evm/) stands for "Ethereum Virtual Machine" and is currently the tried and tested virtual machine running most smart contract networks. + +[Solidity](https://soliditylang.org/) is the programming language of choice for the EVM. It was created for this specific purpose. + +The main benefit of using EVM/Solidity is its sheer amount of resources from years of development. The [IOTA Smart Contracts](../developer/iota-evm/introduction.mdx) implementation is fully compatible with these resources, allowing you to leverage all existing EVM developer tools for developing on the IOTA EVM. Any contracts you've previously written can be deployed on IOTA Smart Contracts without modification. + +Keep in mind that while EVM has become a standard for smart contract execution on L2s, +it is not inherently designed for the unique features and capabilities of L1s like Move smart contracts. +Move, with its focus on asset safety, resource management, and formal verification, +offers a fundamentally different approach at the L1 level. + +### Networks + +#### IOTA EVM and Shimmer EVM + +IOTA EVM and Shimmer EVM are two distinct Layer 2 EVMs +running on top of the [IOTA Mainnet](./tokenomics/iota-token.mdx). + +#### IOTA EVM Testnet + +IOTA EVM Testnet is the Layer 2 EVM running on top of the IOTA Testnet network. This network is subject to occasional resets (no data retention), usually announced with a one-week grace period. + +## IOTA Tokens + +The [IOTA token](./tokenomics/iota-token.mdx) is the main token in the IOTA ecosystem. One IOTA can be divided into smaller units called NANOs, with one IOTA being equivalent to one billion NANOs. + +### Gas on IOTA + +Transactions on the IOTA network require [gas](./tokenomics/gas-in-iota.mdx) fees, which are paid using IOTA or NANOs. + +## Consensus on IOTA + +IOTA uses a delegated proof-of-stake (DPoS) consensus mechanism to validate on-chain transaction blocks. [Validators](../operator/validator-committee.mdx) on the IOTA network must secure a certain amount of IOTA tokens on the IOTA Mainnet to demonstrate their commitment to the network's security. This approach aligns the interests of all validators with those of IOTA users, ensuring an efficient and secure blockchain without the high energy demands of earlier blockchains. diff --git a/docs/content/about-iota/iota-architecture/consensus.mdx b/docs/content/about-iota/iota-architecture/consensus.mdx index 908b135e8f9..9fe663a2e68 100644 --- a/docs/content/about-iota/iota-architecture/consensus.mdx +++ b/docs/content/about-iota/iota-architecture/consensus.mdx @@ -1,40 +1,62 @@ --- -title: IOTA Mempool and Consensus Engines -sidebar_label: Mempool and Consensus description: Overview of the IOTA mempool and consensus engines, Narwhal and Bullshark. +sidebar_label: Mempool and Consensus --- +# Consensus on IOTA -This is a brief introduction to [Narwhal](https://github.com/iotaledger/iota/tree/develop/narwhal), and [Bullshark](https://arxiv.org/abs/2209.05633), the high-throughput mempool and consensus engines developed by Mysten Labs. IOTA uses Narwhal as the mempool and Bullshark as the consensus engine by default, to sequence transactions that require a total ordering, synchronize transactions between validators, and periodically checkpoint the network's state. +## Narwall and Bullshark -The names highlight that the components split the responsibilities of: +IOTA uses [Narwhal](https://github.com/iotaledger/iota/tree/develop/narwhal), +and [Bullshark](https://arxiv.org/abs/2209.05633), the high-throughput mempool and consensus engines developed by Mysten +Labs, to sequence transactions that require total ordering, synchronize transactions between validators, and +periodically checkpoint the +network's state. -- ensuring the availability of data submitted to consensus = [Narwhal](https://arxiv.org/abs/2105.11827) -- agreeing on a specific ordering of this data = [Bullshark](https://dl.acm.org/doi/abs/10.1145/3548606.3559361) +[Narwhal](https://arxiv.org/abs/2105.11827) ensures that data that was submitted for consensus is readily available, +while [Bullshark](https://dl.acm.org/doi/abs/10.1145/3548606.3559361) is in charge of generating a consensus on the +specific ordering of said data. -The IOTA consensus engine represents the latest variant of decades of work on multi-proposer, high-throughput consensus algorithms that reach throughputs of more than 125,000 transactions per second with a two-second latency for a deployment of 50 parties, with production cryptography, permanent storage, and a scaled-out primary-worker architecture. +The IOTA consensus engine is a cutting-edge advancement in multi-proposer, high-throughput consensus algorithms. It can +achieve over 125,000 transactions per second with a two-second latency for a deployment of 50 participants. This +includes production-level cryptography, permanent storage, and a scaled-out primary-worker architecture. -The IOTA consensus engine approach can offer dramatic scalability benefits in the following cases: +The IOTA consensus engine offers significant scalability advantages in the following scenarios: -- a blockchain that has experimented with larger and larger blocks and has measured runaway latencies before the execution phase -- a blockchain with fast execution (e.g., focused on transactions or with an UTXO data model), but which mempool and consensus do not keep up +* A blockchain that has experimented with larger blocks and encountered increased latency before the execution phase. +* A blockchain with fast execution (e.g., focused on transactions or using a UTXO data model) where the mempool and + consensus processes cannot keep up. -## Features +## Key Features The Narwhal mempool offers: -- a high-throughput data availability engine, with cryptographic proofs of data availability at a [primary node](https://github.com/iotaledger/iota/blob/develop/narwhal/primary) -- a structured graph data structure for traversing this information -- a scaled architecture, splitting the disk I/O and networking requirements across several [workers](https://github.com/iotaledger/iota/blob/develop/narwhal/worker) +* A high-throughput data availability engine with cryptographic proofs of data availability at + a [primary node](https://github.com/iotaledger/iota/blob/develop/narwhal/primary) +* A structured graph data structure for traversing information. +* A scaled architecture that splits disk I/O and networking requirements across + several [workers](https://github.com/iotaledger/iota/blob/develop/narwhal/worker) ## Architecture -A Narwhal instance sets up a message-passing system comprised of a set of $3f+1$ units of stake divided amongst a set of nodes, and assumes a computationally bounded adversary that controls the network and can corrupt parties holding up to f units of stake. The validators collaborate in forming a leaderless graph of batches of transactions - which the literature (in the context of DAG-based consensus) designates as _blocks_ and that IOTA labels _collections_ - to emphasize that this happens in a context where the mempool data is used by an unspecified consensus algorithm. +A Narwhal instance sets up a message-passing system with a set of $3f+1$ units of stake divided among nodes. It assumes +a computationally bounded adversary that controls the network and can corrupt parties holding up to $f$ units of stake. +The validators collaborate to form a leaderless graph of transaction batches, referred to as collections in IOTA (often +called blocks in DAG-based consensus literature). This process uses mempool data with an unspecified consensus +algorithm. -The graph's *vertices* consist of certified collections. Each valid collection signed by its validator-author must contain a round number and must itself be signed by a quorum (2f+1) of validator stake. These 2f+1 signatures are called a _certificate of availability_. Furthermore, that collection must contain hash pointers to a quorum of valid certificates (that is, certificates from validators with 2f + 1 units of stake) from the previous round (see Danezis & al. Fig 2), which constitute the *edges* of the graph. +The graph's _vertices_ are certified collections. Each valid collection, signed by its validator-author, must include a +round number and a certificate of availability signed by a quorum (2f+1) of validator stake. Each collection must also +contain hash pointers to a quorum of valid certificates (from validators with 2f + 1 units of stake) from the previous +round, forming the _edges_ of the graph. -Each collection is formed in the following way: each validator _reliably broadcasts_ a collection for each round. Subject to specified validity conditions, if validators with 2f + 1 stake receive a collection, they acknowledge it with a signature each. Signatures from 2f + 1 validators by stake form a certificate of availability that is then shared and potentially included in collections at round r + 1. +Collections are formed as follows: each validator reliably broadcasts a collection for each round. Subject to specified +validity conditions, if validators with 2f + 1 stake receive a collection, they acknowledge it with a signature. +Signatures from 2f + 1 validators by stake form a certificate of availability, which is then shared and potentially +included in collections at round r + 1. -The following figure represents five rounds of construction of such a DAG (1 to 5), with authorities A, B, C and D participating. For simplicity, each validator holds 1 unit of stake. The collections transitively acknowledged by A's latest round in A5 are represented in full lines in the graph. +The following figure represents five rounds of constructing such a DAG (1 to 5), with validators A, B, C, and D +participating. For simplicity, each validator holds 1 unit of stake. The collections transitively acknowledged by A's +latest round in A5 are represented with solid lines in the graph. ```mermaid flowchart TB; @@ -68,40 +90,57 @@ flowchart TB; D2 --> B1 & C1; ``` -## How it works +## How It Works - * The graph construction allows inserting more transactions in the system at each authority and at each round. - * The certificates prove the data availability of each collection, or block, at each round. - * Their contents constitute a DAG that can be traversed identically at each honest node. +* The graph construction enables the insertion of more transactions into the system by each authority and in each round. +* Certificates prove the data availability of each collection or block in every round. +* The contents form a DAG that can be identically traversed by each honest node. ## Dependencies -Narwhal is implemented using [Tokio](https://github.com/tokio-rs/tokio), [RocksDB](https://github.com/facebook/rocksdb/) and generic cryptography implemented in [fastcrypto](https://github.com/MystenLabs/fastcrypto). +Narwhal is implemented using: + +* [Tokio](https://github.com/tokio-rs/tokio) +* [RocksDB](https://github.com/facebook/rocksdb/) + +Generic cryptography is implemented in [fastcrypto](https://github.com/MystenLabs/fastcrypto). ## Configuration -To conduct a fresh deployment of IOTA Consensus Engine, follow the instructions at [Running Benchmarks](https://github.com/iotaledger/iota/blob/develop/narwhal/benchmark). +You can follow the instructions +on [Running Benchmarks](https://github.com/iotaledger/iota/blob/develop/narwhal/benchmark) to conduct a fresh deployment +of IOTA Consensus Engine. -## Further reading +## Further Reading -Narwhal and Tusk (Danezis et al. 2021) is a consensus system leveraging directed acyclic graphs (DAG). DAG-based consensus has been developed over the last 30 years, and some of the history is summarized in (Wang & al. 2020). The theoretical ancestor of Narwhal and Tusk is DAG-Rider (Keidar & al. 2021). +Narwhal and Tusk (Danezis et al., 2021) is a consensus system that leverages directed acyclic graphs (DAGs). DAG-based +consensus has been developed over the last 30 years, with some history summarized in Wang et al. (2020). The theoretical +ancestor of Narwhal and Tusk is DAG-Rider (Keidar et al., 2021). -Narwhal and Tusk are developed in the [asynchronous model](https://decentralizedthoughts.github.io/2019-06-01-2019-5-31-models/). A partially synchronous variant of Narwhal and Tusk is called Bullshark (Spiegelman et al. 2022). +Narwhal and Tusk are developed in +the [asynchronous model](https://decentralizedthoughts.github.io/2019-06-01-2019-5-31-models/). A partially synchronous +variant of Narwhal and Tusk is called Bullshark (Spiegelman et al. 2022). Narwhal and Tusk started [as a research prototype](https://github.com/facebookresearch/narwhal) at Facebook Novi. -[Bullshark: DAG BFT Protocols Made Practical](https://arxiv.org/pdf/2201.05677.pdf) - +[Bullshark: DAG BFT Protocols Made Practical](https://arxiv.org/pdf/2201.05677.pdf) - Bullshark replaces Tusk for even greater performance. -[Bullshark: The Partially Synchronous Version](https://arxiv.org/pdf/2209.05633.pdf) - +[Bullshark: The Partially Synchronous Version](https://arxiv.org/pdf/2209.05633.pdf) - A simplified version of Bullshark that is used in IOTA today. -[DAG Meets BFT - The Next Generation of BFT Consensus](https://decentralizedthoughts.github.io/2022-06-28-DAG-meets-BFT/) - Explains the evolution of the consensus protocol used by IOTA. +[DAG Meets BFT - The Next Generation of BFT Consensus](https://decentralizedthoughts.github.io/2022-06-28-DAG-meets-BFT/) - +Explains the evolution of the consensus protocol used by IOTA. ## Bibliography - * Danezis, G., Kogias, E. K., Sonnino, A., & Spiegelman, A. (2021). Narwhal and Tusk: A DAG-based Mempool and Efficient BFT Consensus. ArXiv:2105.11827 [Cs]. http://arxiv.org/abs/2105.11827 - * Spiegelman, A., Giridharan, N., Sonnino, A., & Kokoris-Kogias, L. (2022). Bullshark: DAG BFT Protocols Made Practical. ArXiv:2201.05677 [Cs]. https://dl.acm.org/doi/abs/10.1145/3548606.3559361 - * Spiegelman, A., Giridharan, N., Sonnino, A., & Kokoris-Kogias, L. (2022). Bullshark: The Partially Synchronous Version. ArXiv:2209.05633 [Cs]. https://arxiv.org/abs/2209.05633 - * Keidar, I., Kokoris-Kogias, E., Naor, O., & Spiegelman, A. (2021). All You Need is DAG. ArXiv:2102.08325 [Cs]. http://arxiv.org/abs/2102.08325 - * Wang, Q., Yu, J., Chen, S., & Xiang, Y. (2020). SoK: Diving into DAG-based Blockchain Systems. ArXiv:2012.06128 [Cs]. http://arxiv.org/abs/2012.06128 +* Danezis, G., Kogias, E. K., Sonnino, A., & Spiegelman, A. (2021). Narwhal and Tusk: A DAG-based Mempool and Efficient + BFT Consensus. ArXiv:2105.11827 [Cs]. http://arxiv.org/abs/2105.11827 +* Spiegelman, A., Giridharan, N., Sonnino, A., & Kokoris-Kogias, L. (2022). Bullshark: DAG BFT Protocols Made Practical. + ArXiv:2201.05677 [Cs]. https://dl.acm.org/doi/abs/10.1145/3548606.3559361 +* Spiegelman, A., Giridharan, N., Sonnino, A., & Kokoris-Kogias, L. (2022). Bullshark: The Partially Synchronous + Version. ArXiv:2209.05633 [Cs]. https://arxiv.org/abs/2209.05633 +* Keidar, I., Kokoris-Kogias, E., Naor, O., & Spiegelman, A. (2021). All You Need is DAG. ArXiv: + 2102.08325 [Cs]. http://arxiv.org/abs/2102.08325 +* Wang, Q., Yu, J., Chen, S., & Xiang, Y. (2020). SoK: Diving into DAG-based Blockchain Systems. ArXiv: + 2012.06128 [Cs]. http://arxiv.org/abs/2012.06128 diff --git a/docs/content/about-iota/iota-architecture/epochs.mdx b/docs/content/about-iota/iota-architecture/epochs.mdx index e8d708f1094..dc6a1c66bf5 100644 --- a/docs/content/about-iota/iota-architecture/epochs.mdx +++ b/docs/content/about-iota/iota-architecture/epochs.mdx @@ -1,27 +1,38 @@ ---- -title: Epochs and Reconfiguration -draft: true ---- - -In a simplified view, epochs are to the IOTA network what individual days are to a calendar. Reconfiguration, then, is a process at the end of each epoch where that day's activity is tallied and the next day's parameters are set. +# Epochs and Reconfiguration ## Epoch -An epoch is a duration of time where the IOTA validator set and their stakes remain unchanged. On both Mainnet and Testnet, an epoch is about 24 hours. This timeframe allows validators to process transactions efficiently without worrying about ad hoc validator changes during the middle of an epoch. +In IOTA, an epoch is a set period, around 24 hours, during which the +IOTA [validator](../tokenomics/validators-staking.mdx) set and their stakes remain constant. This stable period allows +validators to handle transactions smoothly without unexpected changes. -Epoch values are included in the metadata of transactions on the IOTA network, but the average user is unaffected by its value. The only time a user might need to know about epochs is in the case of expiring transactions, where a transaction is only valid if executed before a set epoch. See [Transactions](../../developer/iota-101/transactions/transactions.mdx) for more information about transactions on IOTA. +Epoch values are part of the transaction data on the IOTA network, but regular users don't need to worry about them. +Users only need to know about epochs if they are dealing with +expiring [transactions](../../developer/iota-101/transactions/transactions.mdx), which must be completed before a +specific epoch ends. ## Reconfiguration -Reconfiguration is a critical process occurring at the end of each epoch. It involves several key steps to adjust the network for the upcoming epoch: - -1. **Finalizing transactions and checkpoints** - - The network reaches consensus on the final set of transactions and checkpoints for the current epoch. This ensures all validators have an identical state at epoch conclusion. - - **Synchronous moment:** This is the only fully synchronous event in the network, crucial for maintaining consistency. -1. **Distribution of gas rewards** - - Computation gas fees are distributed to the validator staking reward pool, from which stakers can withdraw. -1. **Validator set change** - - Any pending staking and unstaking requests during the epoch are finalized and reflected in validators stake distribution. - - Any pending validator change requests are also processed, including adding new validators and removing existing validators. This is the sole opportunity for altering the validator set and stake distribution. -1. **Protocol upgrade** - - If agreed upon by 2f+1 validators, the network might upgrade to a new protocol version, encompassing new features, bug fixes, and updates to Move framework libraries. +Reconfiguration is an important process that happens at the end of each epoch to prepare the network for the next one. +It includes these key steps: + +### 1. Finalizing Transactions and Checkpoints + +The network agrees on the final set of transactions and checkpoints for the current epoch, ensuring all validators have +the same information. This is the only time the network is fully synchronized, known as a _synchronous moment_, which is +essential for consistency. + +### 2. Distribution of Gas Rewards + +Computation gas fees are distributed to the validator staking reward pool, allowing stakers to withdraw their rewards. + +### 3. Validator Set Change + +Any pending staking and unstaking requests are finalized and reflected in the validators' stake distribution. Any +pending changes to the validator set, such as adding or removing validators, are processed. This is the only time the +validator set and stake distribution can be altered. + +### 4. Protocol Upgrade + +If 2f+1 validators agree, the network may upgrade to a new protocol version, which includes new features, bug fixes, and +updates to the Move framework libraries. diff --git a/docs/content/about-iota/iota-architecture.mdx b/docs/content/about-iota/iota-architecture/iota-architecture.mdx similarity index 83% rename from docs/content/about-iota/iota-architecture.mdx rename to docs/content/about-iota/iota-architecture/iota-architecture.mdx index b45075c132f..9546600e829 100644 --- a/docs/content/about-iota/iota-architecture.mdx +++ b/docs/content/about-iota/iota-architecture/iota-architecture.mdx @@ -8,22 +8,22 @@ IOTA shares some similarities with other blockchains but is unique in many ways. Learn about the mechanisms available to secure on-chain assets, and the assurances IOTA provides regarding asset security. Understand IOTA Security explores the overall IOTA security architecture to ensure the asset types you design leverage IOTA to provide a secure experience for asset holders. -Go to [Understand IOTA Security](./iota-architecture/iota-security.mdx). +Go to [Understand IOTA Security](iota-security.mdx). ## Life of a Transaction Life of a Transaction details the transitions that all transactions on IOTA go through from creation to finality. This topic also explores some features of the blockchain (like epochs and checkpoints) that play a role in the life of a transaction. -Go to [Life of a Transaction](./iota-architecture/transaction-lifecycle.mdx). +Go to [Life of a Transaction](transaction-lifecycle.mdx). ## Mempool and Consensus Engines Narwhal and Bullshark combine to form the basis of the IOTA mempool and consensus engine. This topic offers a brief introduction to the technologies that keep the activities on IOTA synchronized and secure. -Go to [Mempool and Consensus Engines](./iota-architecture/consensus.mdx). +Go to [Mempool and Consensus Engines](consensus.mdx). ## Protocol Upgrades The IOTA protocol, framework, and execution engine are frequently extended to include new functionality and bug fixes. This functionality is added in the form of new code which is released to validator operators as part of our regular software releases. The IOTA protocol, however, requires that all IOTA validators agree about the results of executing each transaction. -Go to [Protocol Upgrades](./iota-architecture/protocol-upgrades.mdx). \ No newline at end of file +Go to [Protocol Upgrades](protocol-upgrades.mdx). \ No newline at end of file diff --git a/docs/content/about-iota/iota-architecture/iota-security.mdx b/docs/content/about-iota/iota-architecture/iota-security.mdx index f14436992ab..686b21a2fbf 100644 --- a/docs/content/about-iota/iota-architecture/iota-security.mdx +++ b/docs/content/about-iota/iota-architecture/iota-security.mdx @@ -1,66 +1,65 @@ ---- -title: Security -description: IOTA is designed to provide very high security guarantees to asset owners. Assets on IOTA can be used only by their owners, according to the logic pre-defined by smart contracts that can be audited, and that the network will be available to process them correctly despite some of the validators operating IOTA not following the protocol correctly (fault tolerance). ---- +# Security -This page provides an overview of the major guarantees IOTA provides in terms of security. +## Assets -IOTA asset owners and smart contract designers can start learning here about the mechanisms available to secure their assets, and the assurances IOTA provides for them. Smart contract designers can also learn about the overall IOTA security architecture to ensure the asset types they design leverage IOTA to provide a secure experience to the asset holders. +Security is one of the top priorities in IOTA. From the start, you need to authorize access to any asset using a private key known only to the asset owner. Additionally, the smart contract that defines the asset also sets its rules, which are further secured by the Move compiler to ensure assets are handled properly and no asset can be spent twice or lost due to a logic error. Once a transaction reaches finality, any assets that were modified or created will be updated, persisted, and available for further use. Even if an object is shared or immutable, you can still define access control logic in the smart contract that created it to ensure proper usage. -## Security features {#security-features} +## Validators and Consensus -IOTA is designed to provide very high security guarantees to asset owners. Assets on IOTA can be used only by their owners, according to the logic pre-defined by smart contracts that can be audited, and that the network will be available to process them correctly despite some of the validators operating IOTA not following the protocol correctly (fault tolerance). +The IOTA protocol is run by a set of independent validators. They all run the same protocol and transactions, using their voting power to reach a consensus on which transactions are valid. The system is designed to be fault-tolerant, so your transactions will be processed even if one-third of the validators don't run the protocol correctly. Additionally, every single transaction on IOTA is publicly available and can be audited to ensure any changes to assets were correctly executed. -The security features of the IOTA system ensure a number of properties: +:::tip Validator Selection -- Only the owner of an owned asset can authorize a transaction that operates on this asset. Authorization is performed through the use of a private signature key that is known only to the asset owner. -- Everyone can operate on shared assets or immutable assets, but additional access control logic can be implemented by the smart contract. -- Transactions operate on assets according to predefined rules set by the smart contract creator that defined the asset type. These are expressed using the Move language. -- Once a transaction is finalized, its effects - namely changes to the assets it operates on or new assets created - will be persisted, and the resulting assets will be available for further processing. -- The IOTA system operates through a protocol between a set of independent validators. Yet all its security properties are preserved when a small subset of the validators do not follow the protocol. -- All operations in IOTA can be audited to ensure any assets have been correctly processed. This implies all operations on IOTA are visible to all, and users may wish to use multiple different addresses to protect their privacy. -- Validators are determined periodically through users of IOTA locking and delegating IOTA tokens to one or more validators. +The set of validators changes periodically and is [determined by the amount of locked and delegated IOTAs held](../tokenomics/validators-staking.mdx). -## Security architecture {#security-architecture} +::: -The IOTA system is operated by a set of validators that process transactions. They implement the IOTA protocol that allows them to reach agreement on valid transactions submitted and processed in the system. +### Choosing Validators -The agreement protocols IOTA uses tolerate a fraction of validators not following the IOTA protocol correctly, through the use of Byzantine fault tolerant broadcast and consensus. Specifically, each validator has some voting power, assigned to it through the process of users staking / voting for them using their IOTA tokens. IOTA maintains all its security properties if over 2/3 of the stake is assigned to validators that follow the protocol. However, a number of auditing properties are maintained even if more validators are faulty. +IOTA uses a delegated Proof-of-Stake (dPoS) mechanism to select validators (nodes that help secure and operate the network) for each period. Users can lock and delegate their IOTA tokens to vote for validators, assigning them voting power. Validators are selected based on the number of tokens delegated to them, and any node with sufficient delegated tokens can become a validator. -### Addresses and ownership {#addresses-and-ownership} +### Rewards for Validators and Stakers -A IOTA transaction is valid and can proceed only if the owner of all owned assets it operates on digitally signs it with their private signature key. This signature key can be kept private by the user and not be shared with anyone else. As a result, it is not feasible for any other party to operate on an owned asset of a user undetected, even if all validators do not follow the protocol. +Validators earn rewards from gas fees and share these rewards with users who staked their tokens to support them. If a validator performs poorly, both they and the users who supported them get lower rewards. Users' staked tokens are safe and can't be taken away by validators or anyone else. -A private signature key also corresponds to a public address on the IOTA network that can be used to send a user assets or allow smart contracts to define custom access control logic. A user may have one or more addresses corresponding to multiple signature keys for convenience or privacy reasons. An address does not need any pre-registration, and sending an asset to an address automatically creates this address on the network. However, this means that users should be careful to check the recipient address of transfers, or parties involved in any other operations, as sending assets to an incorrect address may have irrevocable effects. +### Accountability and Rotation of Validators -### Smart contracts define asset types and their logic {#smart-contracts} +Validators must be reliable and behave correctly, or they can be replaced. If validators try to censor transactions or act maliciously, they can be rotated out by the users. Users have a say in how the IOTA network evolves by choosing which validators to support and which protocol to follow. -All assets have a type that is defined within a IOTA Smart Contract. IOTA provides a few system contracts, such as these used to manage the IOTA native token, yet also allows anyone to write and submit custom smart contracts. A transaction on an asset type can call operations defined in only the smart contract that defined the asset type, and is constrained by the logic in the contract. +## Addresses and Keys -For this reason, users are encouraged to operate on their assets using smart contracts they trust, that they or others they trust have audited, and understand the logic they define for operations on their assets. IOTA smart contracts are defined as immutable assets to allow third parties to audit them and also prevent their modification to increase assurance. +To operate on any owned assets on IOTA, you need to hold the corresponding private key. You should keep the key private to guarantee no one can use your assets without your authorization. Even if all the validators agreed to misbehave, they could not access your assets without the private key. -The Move smart contract language is designed with ease of audit and verification in mind. You may be interested in our introduction to Smart Contracts in Move. +Your private key matches a single public address on the IOTA network. You can create any number of addresses on IOTA, each with its own private key. Keep in mind that addresses don't require prior registration; sending any asset to an address will create said address. Since once a transaction reaches finality, it is irreversible; you should always check the recipient address for your transactions. -Shared assets allow multiple users to operate on them through transactions; that may include some of their owned assets as well as one or more shared assets. These shared assets represent data and logic used to implement protocols that mediate between different users in a safe way, according to the smart contract that defined the type of the shared asset. IOTA allows all users to create transactions involving shared assets. But the smart contract type may define additional restrictions on which address and how the shared assets may be used. +## Asset Types and Logic -### Transaction finality {#transaction-finality} +The type and logic of any asset on the IOTA network is defined in a smart contract. Aside from the handful of contracts built into the protocol by IOTA, all contracts in the IOTA network are created by developers outside the IOTA Foundation. Smart contracts on IOTA are immutable, allowing third-party audits and preventing modifications after deployment. Since Move was designed with asset security and smart contract verification at its core, it is easy to audit and guarantee contracts audited by trusted sources are safe. -A valid transaction submitted to all validators has to be certified and its certificate also has to be submitted to all validators to be finalized. Even if a subset of validators do not follow the protocol, the transaction can be finalized through the remaining validators that correctly follow the IOTA protocol. This is achieved through the use of cryptographic Byzantine fault tolerant agreement protocols for broadcast and consensus defined by the IOTA protocol. These protocols ensure both safety, meaning that the incorrect validators cannot convince correct clients of incorrect state, and liveness, meaning that incorrect validators cannot prevent transaction processing. +### Shared Assets -All transactions in IOTA have to be associated with a gas asset to cover the cost of processing by IOTA. A valid transaction may result in successful execution or an aborted execution. An execution may abort due to a condition within the smart contract defining the asset, or because it has ran out of sufficient gas to pay for the cost of execution. In cases of success, the effects of the operation will be finalized; otherwise, the state of assets in the transaction is not changed. However, the gas asset is always charged some amount of gas, to alleviate denial-of-service attacks on the system as a whole. +Move allows for shared assets. Although these shared assets are public in principle, meaning anyone can use them in a transaction, the smart contract that defined them can also restrict which addresses can use them and how. -A user client can perform the process of submitting the transaction and certificate itself or rely on third party services to submit the transaction and interact with validators. Such third parties need not have user private signature keys and cannot forge transactions on the users' behalf. They can reassure a user client a transaction has been finalized through a set of signatures from validators attesting to the transactions finality and its effects. After that point, the users can be assured that changes the transaction resulted in will persist on the state of IOTA. +## Transaction Finality -### Auditing and privacy {#auditing-and-privacy} +### Certification and Finalization -IOTA validators provide facilities for users to read all assets they store, as well as the historical record of transactions they have processed that led to these assets. Validators also provide cryptographic evidence of the full chain of transactions that contributed to an asset state. User clients can request and validate this chain of evidence to ensure all operations were correct and the result of the collective agreement between validators. Services that operate full replicas, mirroring the state of one or more validators, perform such audits routinely. +When you submit a transaction in IOTA, all the validators must agree that it's valid. Once they agree, they create a certificate to confirm its validity, and this certificate must also be shared with all validators. Even if some validators don't follow the rules, the transaction can still be finalized by the majority of validators who do follow the IOTA protocol. This process uses cryptographic methods to ensure that validators who don't follow the rules can't trick the system into accepting false information and that misbehaving validators can't stop the system from processing transactions. -The public auditability of IOTA also implies that all transactions and assets within IOTA are publicly visible. Users that are mindful of their privacy may use multiple addresses to benefit from some degree of pseudonymity, or third-party custodial or non-custodial services. Specific smart contracts with additional cryptographic privacy protections can also be provided by third parties. +### Gas and Transaction Execution -### Censorship-resistance and openness {#censorship-resistance-openness} +Every transaction needs to pay a gas fee for processing costs. A transaction can either be successfully executed or fail. It can fail if there is an issue within the smart contract or if it runs out of gas. If it succeeds, the changes are persisted on the IOTA network. If it fails, no changes are made to the assets, but some gas is still charged to prevent spam attacks on the network. -IOTA uses the established Delegated Proof-of Stake model to periodically determine its set of validators. Users can lock and delegate their IOTA tokens in each epoch to determine the committee of validators that operate the IOTA network in the next epoch. Anyone with over a minimum amount of delegated stake can operate a IOTA validator. +### Submitting Transactions -Validators operate the network and provide rewards to users that stake their IOTA to support them as validators, through gas fee income. Validators with poor reliability, and in turn the users that delegated their stake to them, may receive a lower reward. But user stake cannot be confiscated away either by malicious validators or anyone in the network. +Users can submit transactions themselves or use third-party services to help. These third-party services can't create transactions on behalf of users because they don't have the users' private keys. They can confirm the transaction is finalized by collecting signatures from the validators. Once confirmed, users can trust that the transaction changes are permanent in the IOTA network. -This mechanism ensures that validators are accountable to IOTA users and can be rotated out at the first sign of unreliability or misbehavior, including noticed attempts to censor valid transactions. Through choices of validators, and the protocol they are willing to operate, IOTA users also have a meaningful say on the future evolution of the IOTA system. +## Auditing and Privacy + +### Reading Assets and Transaction History + +IOTA validators allow users to see all the assets they hold and the history of transactions that created those assets. Validators provide cryptographic proof of every transaction that led to the current state of an asset. You can request this proof and verify it to ensure all transactions were correctly processed and agreed upon by the validators. Services that mirror the state of validators perform these checks regularly to ensure everything is correct. + +### Public Auditability + +All transactions and assets on IOTA are publicly visible. Users can use multiple addresses to keep their identity somewhat hidden (pseudonymity) for privacy. Users can also use third-party services that handle their assets for them, either with or without direct control over their private keys. Smart contracts with extra privacy features can also be provided by third parties to enhance user privacy. diff --git a/docs/content/about-iota/iota-architecture/protocol-upgrades.mdx b/docs/content/about-iota/iota-architecture/protocol-upgrades.mdx index 04a723c0fe3..4afc45ef8fd 100644 --- a/docs/content/about-iota/iota-architecture/protocol-upgrades.mdx +++ b/docs/content/about-iota/iota-architecture/protocol-upgrades.mdx @@ -1,39 +1,50 @@ ---- -title: Protocol Upgrades -description: The IOTA protocol, framework, and execution engine are frequently extended to include new functionality and bug fixes. The process to upgrade the network ensures clients use the same source. ---- +# Protocol Upgrades -# Protocol upgrades +The IOTA protocol, framework, and execution engine are frequently updated to include new features and bug fixes. This +new functionality is released as part of our regular software updates to validator operators. However, the IOTA protocol +requires all validators to agree on the results of executing each transaction. -The IOTA protocol, framework, and execution engine are frequently extended to include new functionality and bug fixes. This functionality is added in the form of new code which is released to validator operators as part of our regular software releases. The IOTA protocol, however, requires that all IOTA validators agree about the results of executing each transaction. +This creates a challenge: How to release code that changes transaction execution, given that it's impossible to +ensure all operators upgrade their software simultaneously? +Additionally, how to ensure that all IOTA transaction +history can be replayed even after functionality has changed? -This poses the following challenge: How do we release code that changes transaction execution, given that it is not possible to ensure that all operators upgrade their software at the same instant? Further, how do we ensure that all IOTA transaction history can be replayed even after functionality has changed? +To address this, IOTA uses a process called protocol upgrades. -To solve this problem, IOTA uses a process called protocol upgrades. +## Protocol Upgrade Process -## Protocol upgrade process +The protocol upgrade process includes the following steps: -An outline of the process used for protocol upgrades includes the following steps: +1. An IOTA developer codes the new feature but restricts access to it using a "feature flag"—a boolean config variable + that is initially set to false. +2. The value of the feature flag is retrieved from a struct called `ProtocolConfig`. +3. The developer creates a new version of the `ProtocolConfig` struct where the new feature flag is set to true. +4. A new release of the IOTA validator software is built and released to validator and full node operators. +5. When the validator process starts, it continues to use the previous version of `ProtocolConfig` (with the flag set to + false). This ensures all validators behave identically, regardless of whether they have the new software or not. +6. As validators are upgraded, they signal to the rest of the validator committee that they are prepared to switch to + the new version of the configuration (with the flag enabled). +7. If enough validators vote to switch to the new protocol version, the new version takes effect at the beginning of the + next [epoch](epochs.mdx). +8. The new feature then comes into effect. -1. A IOTA developer codes the new feature, but restricts access to the feature using a "feature flag" - a boolean config variable that is initially set to false. -1. The value of the feature flag is retrieved from a struct called `ProtocolConfig`. -1. The developer creates a new version of the `ProtocolConfig` struct where the new feature flag is set to true. -1. A new release of the IOTA validator software is built and released to validator and Full node operators. -1. When the validator process starts up, it continues to use the previous version of `ProtocolConfig` (in which the flag is false). This way, all validators continue behaving identically regardless of whether they have the new software or not. -1. As validators are upgraded, they signal to the rest of the validator committee that they are prepared to switch to the new version of the configuration (in which the flag is enabled). -1. If enough validators vote to switch to the new protocol version, then the new version takes effect at the beginning of the next epoch. -1. The new feature now comes into effect. +Full nodes follow a similar process but do not participate in voting. Instead, they follow the actions that validators +recorded. -Full nodes follow a similar process, however, they do not participate in voting. Instead, they follow the actions that validators recorded. +When validators switch to a new protocol version, they do so by recording the new version number in the special +end-of-epoch transaction. Full nodes execute this transaction as they replay the chain history, allowing them to switch +to the new protocol version at the right time. -When validators switch to a new protocol version, they do so by recording the new version number in the special end-of-epoch transaction. Full nodes execute this transaction as they are replaying the chain history, and are thus able to switch to the new protocol version at the right time. +## Framework Upgrades -## Framework upgrades +Not all new IOTA functionality comes from changes to the validator code. There are also changes to the IOTA framework. +For example, IOTA developers periodically add new native functions to the framework to expose new functionality to smart +contracts. The process for framework updates is similar to protocol upgrades. -Not all new IOTA functionality comes in the form of changes to the validator code. There are also changes to the IOTA framework. For instance, IOTA developers periodically add new native functions to the framework to expose new functionality to smart contracts. The process for framework updates is similar to protocol upgrades. - -Instead of using feature flags, however, IOTA objects are used to coordinate framework changes. The IOTA framework is a special object with id `0x2`. -The Move source code for the framework is built into the validator binary. - -If the validator notices that its built-in framework is different from the framework in object `0x2`, it signals to the other validators that it would like to upgrade the framework to a new version. Just as with changes to `ProtocolConfig`, if enough validators agree to perform the upgrade, the new framework object is written at the end of the current epoch. Then, transactions that are executed in the new epoch use the new version of the framework. +Instead of using feature flags, IOTA objects coordinate framework changes. The IOTA framework is a special object with +ID `0x2`. The Move source code for the framework is built into the validator binary. +If the validator notices that its built-in framework differs from the framework in object `0x2`, it signals to the other +validators that it would like to upgrade the framework to a new version. If enough validators agree to perform the +upgrade, the new framework object is written at the end of the current epoch. Transactions executed in the new epoch +then use the new version of the framework. diff --git a/docs/content/about-iota/iota-architecture/staking-rewards.mdx b/docs/content/about-iota/iota-architecture/staking-rewards.mdx index 684fb8763fc..7fab287449e 100644 --- a/docs/content/about-iota/iota-architecture/staking-rewards.mdx +++ b/docs/content/about-iota/iota-architecture/staking-rewards.mdx @@ -1,29 +1,51 @@ ---- -title: Validator Staking and Rewards -draft: true ---- - import StakingPoolReqs from "../../_snippets/staking-pool-reqs.mdx"; -IOTA is a Delegated-Proof-of-Stake (DPoS) system, where the voting power of validators is granted by stakes delegated to them from IOTA token holders. When rewards are distributed at the end of each epoch, validators receive their share of the rewards based on their performance and their commission rate. The rewards auto-compound as validators staking pools receive new delegated stakes. +# Staking and Rewards + +IOTA uses a Delegated Proof-of-Stake (DPoS) system, where [validators](../tokenomics/validators-staking.mdx) get their +voting power from IOTA token holders who delegate their stakes to them. +When rewards are distributed at the end of each [epoch](epochs.mdx), +validators receive their [rewards](#rewards-distribution) based on their [performance](#performance) +and [commission rate](#commission-rate). +The rewards automatically increase as validators' staking pools receive new delegated stakes. + +## Staking on IOTA vs. Other Blockchains + +The IOTA staking mechanism has some unique features compared to other blockchains: + +### Self-custodial Staking -## Staking on IOTA versus other blockchains +Stakers keep their staked IOTA tokens in their own account. -The IOTA staking mechanism has a few features that might be different from staking on other blockchains: +### Auto-compounding Rewards -- Staking is self-custodial on IOTA: stakers keep their staked IOTA tokens in an owned object. -- Staking rewards auto-compound on IOTA due to its liquidity-pool-inspired design. -- When a user requests to stake with a validator, their stake starts counting towards the voting power of that validator for the epoch after the current epoch. Similarly, when a user withdraws their stake, their stake stops counting the epoch after the current epoch. +Rewards automatically reinvest due to a liquidity-pool-inspired design. + +### Staking Timing + +When a user stakes with a validator, their stake counts towards the validator's voting power starting from the next +epoch. Similarly, when a user withdraws their stake, it stops counting from the next epoch. -## Rewards distribution +## Rewards Distribution + +At the end of each [epoch](epochs.mdx), gas fees and stake subsidies are distributed among validators and stakers as +rewards. The amount of rewards a validator gets depends on: + +### Performance + +If a validator underperforms, other validators can report them, causing the reported validator to lose all their rewards +for that epoch. -At the end of each epoch, gas fees collected, together with stake subsidies, are distributed among validators and stakers as staking rewards. The amount of rewards a validator gets depends on the following factors: +### Commission Rate -- Performance. If a validator does not operate performantly, other validators may choose to report them via the tallying rule. The entire staking rewards of the reported validator are slashed for the epoch. -- Commission rate. Commission rate determines the cut of staking rewards a validator is taking from their stakers. For example, if a validator has commission rate at 10%, then 10% of all staking rewards of stakers with this validator are given to the validator each epoch as new stake objects owned by the validator. +This is the percentage a validator takes from their stakers' rewards. +For example, if a validator's commission rate is 10%, they take 10% of the rewards each epoch as new stake objects. -## Rewards withdrawal +### Rewards Withdrawal -Because validator rewards are distributed to them as regular stake objects, staking rewards withdrawal works exactly the same for validators as for stakers. More precisely, a validator can call the [`0x3::iota_system::request_withdraw_stake`](https://github.com/iotaledger/iota/blob/6234ae2cc8137f3a2a34cd0aa1ac4fd5f31260e2/crates/iota-framework/packages/iota-system/sources/iota_system.move#L272) function to withdraw their stake and receive their rewards. +Validators receive rewards as regular stake objects, so they withdraw their staking rewards the same way as stakers. +Validators can call +the [`0x3::iota_system::request_withdraw_stake`](https://github.com/iotaledger/iota/blob/6234ae2cc8137f3a2a34cd0aa1ac4fd5f31260e2/crates/iota-framework/packages/iota-system/sources/iota_system.move#L272) +function to withdraw their stake and receive their rewards. diff --git a/docs/content/about-iota/iota-architecture/transaction-lifecycle.mdx b/docs/content/about-iota/iota-architecture/transaction-lifecycle.mdx index 3ee56330b72..8bc9d402953 100644 --- a/docs/content/about-iota/iota-architecture/transaction-lifecycle.mdx +++ b/docs/content/about-iota/iota-architecture/transaction-lifecycle.mdx @@ -1,193 +1,126 @@ ---- -title: Life of a Transaction -description: The life of a transaction on the IOTA network has some differences compared to those from other blockchains. ---- +# Transaction Life Cycle -A transaction on the IOTA network goes through many different steps during its life cycle. +## High-level Overview -## Life cycle overview +![Transaction life cycle](/img/about-iota/iota-architecture/txn-lifecycle.png) -At a high level, the following figure outlines the life cycle of a transaction on the IOTA blockchain. +1. **Create a Transaction**: A user [submits](#submission) a transaction and signs it with a private key. The transaction can affect objects owned by the user, as well as [shared objects](../../developer/iota-101/objects/object-ownership/shared.mdx). -![Transaction life cycle](./images/txn-lifecycle.png) +2. **Submit to Validators**: The IOTA protocol sends the transaction to every validator. The validators validate the transaction. If valid, the validators sign it and return the signed transaction to the client. -The following steps align with those in the preceding image. +3. **Form a Transaction Certificate**: After collecting responses from a supermajority of validators, the client can form a transaction certificate. Unlike consensus-based blockchains, IOTA validators are not burdened by needing to propagate signatures or aggregate certificates; this is the responsibility of the client or gateway. -1. The first step of the process is the creation of a transaction. A user with a private key creates and signs a user transaction to either mutate objects they own, or a mix of objects they own and [shared objects](../../developer/iota-101/objects/object-ownership/shared.mdx). +4. **Send the Certificate**: The client sends the assembled certificate back to all validators. The validators check its validity and acknowledge receipt. If the transaction involves only owned objects, IOTA can process and execute it immediately without waiting for consensus (**fast path consensus**). All certificates are forwarded to the IOTA DAG-based consensus protocol. -1. IOTA sends the transaction to each validator (often through a Full node). Validators perform a series of validity and safety checks, sign it, and return the signed transaction to the client. +5. **Consensus and Execution**: The IOTA DAG-based consensus protocol eventually produces a total order of certificates. Validators check and execute certificates that involve shared objects. -1. The client then collects the responses from a set of validators that account for at least 2/3 stake on IOTA (a supermajority) to form a transaction certificate. As a result, unlike consensus-based blockchains, IOTA validators do not need to propagate signatures on a best-effort basis (gossip signatures) or aggregate certificates. This effort is now the responsibility of the client or gateway. +6. **Effect Certificate**: Clients can gather responses from a supermajority of validators, assemble them into an effect certificate, and use it as proof that the transaction is settled. -1. After assembling the certificate, the client sends it back to all validators, who check its validity and acknowledge its receipt to the client. If the transaction involves owned objects exclusively, IOTA can process the transaction certificate immediately and execute it without waiting for the [consensus engine](./consensus.mdx) (**direct fast path**). All certificates are forwarded to the IOTA DAG-based consensus protocol (also operated by the IOTA validators). +7. **Checkpoints and Reconfiguration**: IOTA forms checkpoints for every consensus commit, which are also used to drive the reconfiguration protocol. -1. Consensus eventually outputs a total order of certificates; the validators check and execute those that contain shared objects. +## Real-world Example -1. Clients can collect a supermajority of validator responses, assemble them into an effect certificate, and use it as proof of the settlement of the transaction. +Let's say you want to pay 10 IOTA to your local coffee shop for your morning coffee. How can the coffee shop be sure that the payment is complete and allow you to take your coffee? -1. Subsequently, IOTA forms checkpoints for every consensus commit, which it also uses to drive the reconfiguration protocol. +### Transaction Creation -## Submission +You open your wallet app and scan the coffee shop's QR code, which contains their payment address. The app creates a transaction to transfer 10 IOTA from your address to the coffee shop's address. You review the details and approve the transaction. The app signs the transaction with your private key, creating a signed transaction. -All transactions on IOTA begin when they are submitted to the network. For example, imagine you want to transfer an NFT that you own in your wallet to your friend. First, you would create a transaction using a wallet or some other app. The transaction includes your gas payment object and a command to transfer the NFT object to your friend's address. Before the wallet or app submits the transaction to the network, it must also sign it. +### Transaction Broadcast -After the transaction is signed, the wallet or app submits the transaction to a IOTA Full node on behalf of the user. +Your wallet app sends the signed transaction to a full node, which then broadcasts it to all validators in the network. -## Certification +### Transaction Certification -Certification happens after a transaction gets submitted to a Full node. Upon submission, the Full node begins the process of certifying the transaction. The Full node cannot certify the transaction on its own because it does not have a complete view of transactions across the network. Consequently, the Full node must send the transaction to a validator. The validator performs a validity check on the transaction and signs it if it passes. To be considered valid, the transaction must pass the following checks: +Validators receive the transaction from the full node. They check if it's valid and lock the involved objects to prevent double-spending. After validation, they send their signature back to the full node. When the full node collects enough validator signatures (a quorum), it creates a transaction certificate, which includes the transaction and the validator signatures. - - The transaction has a valid user signature. - - The initiator of the transaction must have access to all the owned input objects the transaction uses. In the previous NFT example, the validity check makes sure you own the NFT you're trying to send to a friend. - - All the shared input objects used by the transaction exist. - - The gas coin is a `Coin` object, and it contains at least as much gas as specified in the transaction's gas budget. +### Transaction Finalization -If all the validity checks pass, the validator then attempts to lock all the owned input objects to the given transaction digest. This ensures each owned input object can only be used by one transaction at a time and is the way that IOTA prevents double-spending. In other words, this makes sure that you send your NFT to only one friend instead of trying to send the same NFT to all your friends. +The full node broadcasts this transaction certificate to all validators. Validators verify the certificate, execute the transaction, and unlock the previously locked objects. They then sign the transaction effects (a detailed list of changes) and return these signed effects to the full node. The full node verifies these effects and, once it has enough signatures, forms an effects certificate. -If the locking succeeds, the validator signs the transaction using its BLS private key and returns the signature to the Full node. A single validator signature is not enough, though. The Full node must collect signatures from enough validators to form a supermajority. +Your wallet app receives this effects certificate, which you can show to the coffee shop to prove that the transaction is complete and irreversible. -:::info +## Transaction Life Cycle -Full nodes collect signatures from validators in parallel to minimize latency. +### Submission -::: +If you want to transfer an NFT from your wallet to a friend's wallet, you would create a transaction using a wallet app. This transaction includes the gas payment and a command to transfer the NFT. Before sending this transaction to the network, the wallet app needs to sign it. Once signed, the wallet app **submits** the transaction to an IOTA full node. -After the Full node collects a supermajority, or quorum, of validator signatures, the transaction is considered certified. To be precise, the Full node has formed a _transaction certificate_. +### Certification -Because of the locking step described previously, it is impossible to concurrently form certificates for two different transactions that attempt to use the same owned object. This is true even if there are some dishonest validators that illegally sign both transactions, because of a principle in distributed computing called "quorum intersection". +After submission to a full node, the certification process begins. The full node can't certify the transaction alone because it does not have the full view of the network's transactions. Therefore, it sends the transaction to a validator. The validator checks if the transaction is valid and signs it if it is. The checks include: -If fewer than 1/3rd of the validators are dishonest (Byzantine), then the set of signers for any two certificates must have an overlap that includes at least one honest validator. And, crucially, because that validator is honest, it never signs two transactions that attempt to access the same input object at the same version. After the transaction completes, the input object version changes and can be accessed again by subsequent transactions. +* A valid user signature. +* The transaction's initiator owns the input objects (e.g., the NFT being transferred). +* All shared input objects in the transaction exist. +* The gas payment is sufficient. -## Execution +If these checks pass, the validator locks the input objects to the transaction, preventing double-spending, and proceeds to sign the transaction and returns the signature to the node. The node needs signatures from a majority of validators to certify the transaction. -Full nodes send transactions that have a certificate to validators for execution. Each validator verifies the signatures on the certificate. -If the certificate signatures are valid, then the validator can be sure that the transaction is valid and is not attempting to double-spend any objects. +The full node collects these signatures in parallel to speed up the process. Once it has enough signatures (a quorum), the transaction is certified, forming a **transaction certificate**. -Then, each validator does the following, based on whether the transaction: -- Does not access any shared input objects, in which case it executes it immediately. -- Does access shared input objects, in which case it submits the object to IOTA's consensus layer, which orders the transaction with respect to other transactions using the same shared objects and then executes it. +Even if some validators are dishonest, the principle of "quorum intersection" ensures that as long as most validators are honest, double-spending is prevented. An honest validator will not sign two transactions that try to use the same object at the same time. -## Certified Effects +### Execution -After the transaction executes, the validator signs the effects of the transaction and returns them to the Full node. -The transaction effects are essentially a list of all the actions that the transaction took, which mainly include: -- All the objects that were mutated, created, wrapped, unwrapped, or deleted. -- The gas that was spent. -- The execution status (Success or an error code) of the transaction. +Certified transactions are then sent to validators for **execution**. Validators verify the certificate signatures to ensure the transaction is valid and not attempting to double-spend. -Eventually, the Full node collects effects signatures from a supermajority of validators. This collection of signatures, plus the effects themselves, is called an _effects certificate_. +Depending on whether the transaction uses shared input objects, the validators will either: -:::tip +* Execute it immediately if no shared objects are involved. +* Submit it to IOTA's consensus layer to order the transaction with others if shared objects are involved, and then execute it. -An effects certificate is a guarantee of transaction finality. +This ensures that transactions are processed in the correct order and prevent conflicts. -::: +### Effects Certificate -After you or a Full node observes an effects certificate, you are guaranteed that the transaction is going to be included in a checkpoint, which means that the transaction cannot be reverted. +After the transaction is executed, the validator signs off on the effects of the transaction and sends them back to the full node. The effects of a transaction are essentially a detailed record of what happened, including: -If you wanted, you could present the effects certificate to your friend to prove that you sent them the NFT. The presence of the validator signatures means that an effects certificate cannot be forged. +* Any objects that were changed, created, wrapped, unwrapped, or deleted. +* The amount of gas spent. +* The transaction's execution status (either success or an error code). -## Checkpoints +The full node then gathers these signed effects from a majority of validators, forming an **effects certificate**, which guarantees that the transaction is final. -Inclusion in a checkpoint is the final stage in the life of a transaction. As validators execute transactions, they submit them to consensus. +Once you or the full node sees an effects certificate, you can be sure that the transaction will be included in a [checkpoint](#checkpoints), meaning it can't be undone. This certificate can also serve as proof that you sent the NFT to your friend since it can't be faked due to the validator signatures. -While transactions that use shared input objects must be sent to consensus before they are executed, owned-input-only transactions are also sent to consensus. The difference is that owned-input-only transactions are executed first. +### Checkpoints -The consensus layer produces a universally agreed-upon ordering of transactions. This ordering is the starting point for the creation of checkpoints. +The final stage in a transaction's life is its inclusion in a checkpoint. Validators send executed transactions to the consensus layer, which orders all transactions universally. This ordered list of transactions is used to create checkpoints. Checkpoints include: -The validators take chunks of ordered transactions from the consensus layer and use them to form a checkpoint. Each chunk of transactions is first made causally complete and causally ordered - this means that the validators add any missing dependencies to the list of transactions and order them so that dependencies always appear before dependents in checkpoints. +* Ordered transaction lists. +* Transaction effects. -Then the validator constructs a checkpoint, which (among other data) contains a list of transaction digests as well as the digests of the transaction effects of each transaction. Because checkpoints must be complete, the network sometimes has to wait for the availability of all transactions to form the checkpoints, which may take a couple of commits to process. This process typically completes in the order of a few seconds. +Transactions are added to checkpoints once they are complete and causally ordered, meaning any related dependencies are included and ordered correctly. This ensures the transactions are processed in the right sequence. Forming checkpoints usually takes a few seconds. Once included in a checkpoint, the transaction is permanently recorded on the IOTA network. -At this point, the transaction has reached the end of its life cycle and is included in the permanent record of transaction activity on the IOTA network. +### Transaction Finality -## Transaction finality +Transaction finality means that once a transaction is executed, it can't be reversed or changed. From the time a transaction is sent to when it receives validator signatures, less than half a second passes. At this point, the sender knows the transaction will be processed and can't be undone. Honest validators will reject any subsequent transactions that try to use the same input objects within the same epoch. -Transaction finality is the point at which the execution of a transaction becomes irreversible and its details cannot be altered or changed. +### Settlement Finality -The network round trip of sending a transaction and receiving a validator signature takes less than half a second to complete. At this point the sender knows the transaction is irrevocable and is going to be processed within the epoch, no matter what. The transaction has reached finality; honest validators deem invalid any subsequent transactions using the same owned input objects during the same epoch. +After executing a transaction, validators send back the signed effects to the network. When a majority of validators have executed the transaction and the [effects certificate](#effects-certificate) exists, the transaction's effects (like transfers or newly created objects) are implemented. This allows the network to process new transactions that depend on these effects. -## Settlement finality +Settlement finality depends on [object ownership](../../developer/iota-101/objects/object-ownership/object-ownership.mdx). For transactions involving only owned objects, this happens quickly, in under half a second. For those involving shared objects, it happens shortly after consensus, which can take a few seconds. At this point, the transaction reaches settlement finality, meaning the network can now process more transactions using the same input objects. -After a validator executes a transaction, it returns signed effects from that transaction to the network. +### Checkpoint Processing -After the supermajority of validators have executed the transaction, and an effects certificate exists, the effects of the transaction (transfers, newly minted objects, and so on) have been implemented. At this point, the network can process transactions that depend on those effects. +The [real-world example](#real-world-example) at the beginning of the article demonstrates a finalized transaction through an effects certificate. However, if a full node goes offline before collecting all signatures, your wallet app will try another full node. If your phone dies during this process, the coffee shop will still see your payment on its terminal connected to a different full node, thanks to checkpoints. -For transactions that involve owned objects only, this happens before consensus in under half a second. If a transaction includes shared objects, it happens shortly after consensus, which can take a few seconds. At this point, the transaction reached settlement finality because now you can process more transactions on the same input objects. See [Object Ownership](../../developer/iota-101/objects/object-ownership/object-ownership.mdx) for more information. +A checkpoint contains a list of transactions and is signed by a majority of validators, making it final. If a full node learns about your transaction through checkpoints, it ensures that the transaction will be finalized. -## An example path to an effects certificate +### Local Execution on a Full Node -As a real-world example, suppose you want to pay the local coffee shop 10 IOTA for your morning coffee. How can the coffee shop be sure that the payment is complete and allow you to take your coffee? +Before sending back an effects certificate, a full node might execute the transaction locally if the request asks it to. This is more important for high-frequency applications like gaming but can add unnecessary delay for simple transactions like buying coffee. The `WaitForLocalExecution` parameter requests this local execution, while you can use the `WaitForEffects` parameter for a quicker response. -Step 1: Transaction creation +Additionally, when any app builds a transaction, the full node is usually in charge of choosing the object that is used to pay for the transaction's gas. Since gas is paid in IOTA, which is a shared object, if the full node is not up-to-date, it could potentially lead to an invalid transaction or even a [client equivocation](../../developer/iota-101/transactions/sponsored-transactions.mdx#potential-risks-using-sponsored-transactions). You can avoid this unwanted behavior by sending the `WaitForLocalExecution` parameter. -You open the wallet app on your phone, scan the coffee shop's QR code that contains the recipient on-chain address. The wallet app constructs a transaction that transfers 10 IOTA from your IOTA address to the coffee shop's address. You review the transaction details and approve it. The wallet app then signs the transaction with your private key. Now you have a signed transaction. +### Epoch Change -Step 2: Transaction broadcast - -Your wallet app submits the signed transaction to a Full node. The Full node broadcasts the transaction to all validators in the network. - -Step 3: Transaction certification - -Validators receive the transaction from the Full node. After examining its validity, a validator locks the referenced owned objects, and returns its signature of the transaction to the Full node. - -After the Full node collects a quorum of signatures, it forms a transaction certificate. The transaction certificate contains the transaction and signatures from the supermajority of validators. - -Step 4: Transaction finalization - -The Full node broadcasts the transaction certificate to all validators. Validators receive the transaction certificate, verify its validity (for example, there are indeed enough signatures), execute the transaction, and unlock the previously locked owned objects. Transaction effects are the output of an executed transaction. Validators sign the transaction effects and return them to the Full node, along with their signatures. - -The Full node verifies that effects returned from validators are identical. After it collects a supermajority of signatures, it forms an `EffectsCertificate` object. The effects certificate contains the transaction effects and signatures from a supermajority of validators. - -At this point, as your wallet app gets back the effects certificate from the Full node, you can share this effect certified transaction with the coffee shop. The coffee shop can then be sure that the transaction is executed and irreversible. - -### Checkpoint processing - -The process in the previous section demonstrates a finalized transaction through an effects certificate. As the process shows, the Full node plays the quorum driving role. - -What if the Full node goes offline before it collects a quorum of validator-signed effects? Your wallet app will probably retry the process with a different Full node. Unfortunately, your phone runs out of battery before it sends the signed transaction to a new Full node. - -No worries. The coffee shop shortly notices your payment arrive in its terminal, connected to a different Full node. This Full node learns about your transaction through checkpoints. - -As mentioned, a checkpoint contains a list of transactions. If a transaction appears in a certified checkpoint (a checkpoint that has been signed by a supermajority of validators), it is considered finalized. - -The Full node that the coffee shop's terminal connects to knows about your transaction through state sync. In this case, as long as one validator receives the transaction certificate from your original Full node, the transaction will highly likely finalize even without an effects certificate. The coffee shop is assured of payment and can give you your coffee. - -### Local execution on Full node - -Before the Full node sends back an effects certificate to your wallet app, it may try to execute the transaction locally, if the request asks it to. - -The purpose of this extra step is to keep the Full node up to date as much as possible, especially when the wallet app frequently hits the same Full node. In this coffee shop example, this might be trivial, but for a high frequency application, such as gaming, it could be important. - -When an app constructs a transaction, it typically requests that the Full node choose a gas object for it. Gas objects are owned objects, meaning that if the Full node is stale and not aware of the right version of the object, it could lead to invalid transactions, or worse, client equivocation if the client software does not handle it properly. Executing on Full node before returning `EffectsCertificate` is one way to avoid this situation. A request can ask for such behavior by using the `WaitForLocalExecution` parameter. See [Sponsored Transactions](../../developer/iota-101/transactions/sponsored-transactions.mdx) for more on client equivocation. - -Using `WaitForLocalExecution` is not always the best choice, however. For example, with this coffee payment it adds a layer of end-to-end latency without significant benefits. In this case, using the `WaitForEffects` parameter instead to have a slightly shorter user-perceived latency. - -### Epoch change - -Periodically (~24 hours), the IOTA network enters the process of epoch change. During epoch change, the network calculates and distributes staking rewards, validators metadata take effect, and other network processes are performed. All user transactions are delayed until the new epoch begins. - -If your transaction is submitted at epoch boundary, in rare perfect timing, it is possible that a quorum of validators already decided to not accept any new transaction certificates in the current epoch. Of course, this means your coffee purchase is not be checkpointed either. For any transactions that are certified but not finalized, they are reverted if executed, or its owned objects are unlocked and not yet executed. In this case, the transaction certificate does not guarantee finality. In the new epoch, this transaction certificate will become void because validator signatures are signed over epoch ID. To continue this transaction, a new transaction certificate is necessary with the new epoch ID. The standard Full node implementation handles this automatically. - -### Verifying finality - -Assume your wallet app crashed during the original transaction. If the app stores the signed transaction locally before sending it to the Full node, which is best practice, then when the app restarts it tries to verify if the transaction has been finalized first. If it has, then no other steps are necessary. If it hasn't, then the app needs to resubmit the transaction. - -The wallet app can query the Full node with the `getTransactionBlock` method. Assuming the Full node is honest: -- If the response contains transaction details, the transaction must have been finalized. It is either executed with `WaitForLocalExecution`, or executed as a checkpointed transaction. -- If the response is `None`, it could mean the transaction was dropped in some step, or is already finalized but this Full node does not know yet. In this scenario, the safer option is to resubmit the transaction. - -Before a transaction is locally executed, its effects are not reflected on the Full node. The same idea applies to the coffee shop's Full node. Your transaction was not submitted through this Full node, hence it does not have a chance to locally execute it before it's included in a checkpoint. This Full node must wait for the transaction to be checkpointed and state synced, which normally takes a few seconds. After the Full node receives this transaction in a checkpoint, it is executed and has effects updated locally, for example the coffee shop's balance increases. - -## Summary - -Hopefully, you now have a better understanding of how a transaction gets certified and finalized. - -1. A transaction certificate does not always guaranteed finality, even though it's highly likely. Specifically, a transaction certificate might become void after an epoch change. - -2. An effects certificate guarantees finality - it takes a supermajority of validators to execute the transaction and commit to the effects. - -3. An inclusion in a certified checkpoint guarantees finality - it takes a supermajority of validators to certify the checkpoint, in which every transaction is executed and effects-committed. +Every ~24 hours, the IOTA network undergoes an epoch change, during which staking rewards are calculated and distributed, validator metadata is updated, and other network processes occur. User transactions are paused during this time. If your transaction is submitted at the epoch boundary, it may need resubmission in the new epoch. Transactions that were certified but not yet finalized will be reverted. Any transaction certificate from the previous epoch will become invalid, so the full node will resubmit the invalid transactions. +### Verifying Finality +If your wallet app crashes during a transaction, it stores the signed transaction locally. Upon restarting, it will verify if the transaction was finalized. If finalized, no further steps are required. If not, the app will need to resubmit the transaction. +The wallet app can query the full node with the `getTransactionBlock` method to check if the transaction is finalized. If the response contains transaction details, it is finalized. If the response is `None`, the transaction may need to be resubmitted. This ensures that the coffee shop's full node will eventually recognize the transaction once it's included in a checkpoint and update the coffee shop's balance. diff --git a/docs/content/about-iota/tokenomics/proof-of-stake.mdx b/docs/content/about-iota/tokenomics/proof-of-stake.mdx index 3286921902f..4b66ef29796 100644 --- a/docs/content/about-iota/tokenomics/proof-of-stake.mdx +++ b/docs/content/about-iota/tokenomics/proof-of-stake.mdx @@ -10,7 +10,7 @@ Within each epoch, a fixed set of validators process operations, each with a spe ## Economic model {#economic-model} -This section covers how the different components of the IOTA economy interact with each other to introduce the IOTA DPoS system. For reference, see the Staking and Tokenomics diagram in the [IOTA Tokenomics](../tokenomics.mdx) overview. +This section covers how the different components of the IOTA economy interact with each other to introduce the IOTA DPoS system. For reference, see the Staking and Tokenomics diagram in the [IOTA Tokenomics](tokenomics.mdx) overview. The IOTA economic model works as follows: diff --git a/docs/content/about-iota/tokenomics.mdx b/docs/content/about-iota/tokenomics/tokenomics.mdx similarity index 75% rename from docs/content/about-iota/tokenomics.mdx rename to docs/content/about-iota/tokenomics/tokenomics.mdx index 7fd6bf09212..265276ded3f 100644 --- a/docs/content/about-iota/tokenomics.mdx +++ b/docs/content/about-iota/tokenomics/tokenomics.mdx @@ -19,9 +19,9 @@ Three main types of participants characterize the IOTA economy: The IOTA economy is composed of four core components: -- **[IOTA](./tokenomics/iota-token.mdx):** The IOTA token is the IOTA platform native asset. -- **[Gas fees](./tokenomics/gas-in-iota.mdx):** Gas fees are charged on all network operations and used to reward participants of the proof-of-stake mechanism and prevent spam and denial-of-service attacks. -- **[Proof-of-stake](./tokenomics/proof-of-stake.mdx):** The delegated proof-of-stake mechanism is used to select, incentivize, and reward honest behavior by IOTA Validators and the IOTA owners that stake with them. +- **[IOTA](iota-token.mdx):** The IOTA token is the IOTA platform native asset. +- **[Gas fees](gas-in-iota.mdx):** Gas fees are charged on all network operations and used to reward participants of the proof-of-stake mechanism and prevent spam and denial-of-service attacks. +- **[Proof-of-stake](proof-of-stake.mdx):** The delegated proof-of-stake mechanism is used to select, incentivize, and reward honest behavior by IOTA Validators and the IOTA owners that stake with them. - **Voting:** On-chain voting is used for governance and protocol upgrades. @@ -29,7 +29,7 @@ The IOTA economy is composed of four core components: The following flowchart presents the tokenomic flow of IOTA at a high level. Referring back to this chart after you learn concepts in this section should provide additional clarity. -![IOTA tokenomics flow](./images/iota-tokenomics-flow.png "Flowchart showing the tokenomics structure.") +![IOTA tokenomics flow](/img/about-iota/tokenomics/iota-tokenomics-flow.png "Flowchart showing the tokenomics structure.") ## Tokenomics whitepaper diff --git a/docs/content/developer/evm-to-move/why-move.mdx b/docs/content/developer/evm-to-move/why-move.mdx index a7356c80784..9b675a6f2b5 100644 --- a/docs/content/developer/evm-to-move/why-move.mdx +++ b/docs/content/developer/evm-to-move/why-move.mdx @@ -12,7 +12,7 @@ While EVM/Solidity is the most famous smart contracts platform, it has some down IOTA Move is here to learn from these downsides and come up with a better alternative addressing these issues: * **Performance, scaling, and cost:** Given that IOTA Move is based on the object model (similar to UTXO's) and not a globally shared state, transactions can be executed in parallel, resulting in a much higher (potential) throughput over a traditional blockchain with shared state. This results in a lot less congestion and, thus, lower fees on an actively used network. -* **Security:** Move was designed with security in mind. The language itself is based on Rust and is very strict regarding its typing system. You really have to try to make a microsake that the compiler won't catch before deploying. There's no such thing as re-entry, and given the object-based approach of Move, Assets residing in your account can't be touched at all by the smart contract itself without access to your account keys. +* **Security:** Move was designed with security in mind. The language itself is based on Rust and is very strict regarding its typing system. You really have to try to make a mistake that the compiler won't catch before deploying. There's no such thing as re-entry, and given the object-based approach of Move, Assets residing in your account can't be touched at all by the smart contract itself without access to your account keys. * **Tokens:** In IOTA Move, there is no difference between the IOTA token (`Coin`) and a custom token (`Coin`), not in terms of use or implementation. These objects reside in your own account and can thus easily be found without needing to know a Smart Contract address (this goes for any other type of owned object as well). There's no strange `approve()` functionality, and you keep control over your own owned assets. * **Developer Experience:** While Move is more challenging to get started with compared to Solidity due to its novelty and less mature developer tooling, the safety of the language and the ease of finding and resolving issues in your code make up for that. With Move, it's not so scary anymore to write complex logic from scratch, given most mistakes (apart from obvious implementation logic, doing things 'as intended') are caught directly by the compiler. This allows for more innovation, fewer value-destroying bugs, and a more excellent developer experience, fueling the next generation of smart contracts. diff --git a/docs/content/developer/standards/coin.mdx b/docs/content/developer/standards/coin.mdx index 3a566ba903a..57f48a089ff 100644 --- a/docs/content/developer/standards/coin.mdx +++ b/docs/content/developer/standards/coin.mdx @@ -6,7 +6,7 @@ sidebar_label: Coin The Coin standard is the technical standard used for smart contracts on IOTA for creating coins on the IOTA blockchain. The standardization of coin creation on IOTA means that wallets, exchanges, and other smart contracts can manage coins created on IOTA the same as they manage IOTA, without any additional processing logic. -See [IOTA Tokenomics](../../about-iota/tokenomics.mdx) to learn more about the IOTA native coin and its use on the IOTA network. +See [IOTA Tokenomics](../../about-iota/tokenomics/tokenomics.mdx) to learn more about the IOTA native coin and its use on the IOTA network. Although coins on IOTA follow the Coin standard, they can offer specialized abilities. For example, you can create a regulated token that allows its creator to add specific addresses to a deny list, so that the identified addresses cannot use the token as inputs to transactions. @@ -269,4 +269,5 @@ Check out the following content for more information about coins and tokens on I - [Closed-Loop Token Standard](closed-loop-token.mdx): Details the Token standard on IOTA. - [`coin` module documentation](../../references/framework/iota-framework/coin.mdx): Automated documentation output for the IOTA framework `coin` module. - [`token` module documentation](../../references/framework/iota-framework/token.mdx): Automated documentation output for the IOTA framework `token` module. -- [Tokenomics](../../about-iota/tokenomics.mdx): Discover the IOTA ecosystem and where IOTA coins fit within it. \ No newline at end of file +- [Tokenomics](../../about-iota/tokenomics/tokenomics.mdx): Discover the IOTA ecosystem and where IOTA coins fit within it. + diff --git a/docs/content/sidebars/about-iota.js b/docs/content/sidebars/about-iota.js index 6f87c49b0d4..234979b0dbb 100644 --- a/docs/content/sidebars/about-iota.js +++ b/docs/content/sidebars/about-iota.js @@ -10,7 +10,7 @@ const aboutIota = [ collapsed: false, link: { type: 'doc', - id: 'about-iota/iota-architecture', + id: 'about-iota/iota-architecture/iota-architecture', }, items: [ 'about-iota/iota-architecture/iota-security', @@ -27,7 +27,7 @@ const aboutIota = [ collapsed: false, link: { type: 'doc', - id: 'about-iota/tokenomics', + id: 'about-iota/tokenomics/tokenomics', }, items: [ 'about-iota/tokenomics/iota-token', diff --git a/docs/content/about-iota/iota-architecture/images/txn-lifecycle.png b/docs/site/static/img/about-iota/iota-architecture/txn-lifecycle.png similarity index 100% rename from docs/content/about-iota/iota-architecture/images/txn-lifecycle.png rename to docs/site/static/img/about-iota/iota-architecture/txn-lifecycle.png diff --git a/docs/content/about-iota/tokenomics/images/gas-fees-explorer.png b/docs/site/static/img/about-iota/tokenomics/gas-fees-explorer.png similarity index 100% rename from docs/content/about-iota/tokenomics/images/gas-fees-explorer.png rename to docs/site/static/img/about-iota/tokenomics/gas-fees-explorer.png diff --git a/docs/content/about-iota/images/iota-tokenomics-flow.png b/docs/site/static/img/about-iota/tokenomics/iota-tokenomics-flow.png similarity index 100% rename from docs/content/about-iota/images/iota-tokenomics-flow.png rename to docs/site/static/img/about-iota/tokenomics/iota-tokenomics-flow.png