diff --git a/docs/content/about-iota/iota-architecture/epochs.mdx b/docs/content/about-iota/iota-architecture/epochs.mdx index e543edcc4d6..b8a6c61ab58 100644 --- a/docs/content/about-iota/iota-architecture/epochs.mdx +++ b/docs/content/about-iota/iota-architecture/epochs.mdx @@ -1,5 +1,5 @@ import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/about-iota/iota-architecture/epochs.json'; +import {questions} from '@site/static/json/about-iota/iota-architecture/epochs.json'; # Epochs and Reconfiguration diff --git a/docs/content/about-iota/iota-architecture/iota-security.mdx b/docs/content/about-iota/iota-architecture/iota-security.mdx index f524ccf7030..c5977b33bd9 100644 --- a/docs/content/about-iota/iota-architecture/iota-security.mdx +++ b/docs/content/about-iota/iota-architecture/iota-security.mdx @@ -1,5 +1,5 @@ import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/about-iota/iota-architecture/iota-security.json'; +import {questions} from '@site/static/json/about-iota/iota-architecture/iota-security.json'; # Security diff --git a/docs/content/about-iota/iota-architecture/protocol-upgrades.mdx b/docs/content/about-iota/iota-architecture/protocol-upgrades.mdx index 3e98b4030d9..b562160ce1e 100644 --- a/docs/content/about-iota/iota-architecture/protocol-upgrades.mdx +++ b/docs/content/about-iota/iota-architecture/protocol-upgrades.mdx @@ -1,5 +1,5 @@ import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/about-iota/iota-architecture/protocol-upgrades.json'; +import {questions} from '@site/static/json/about-iota/iota-architecture/protocol-upgrades.json'; # Protocol Upgrades diff --git a/docs/content/about-iota/iota-architecture/staking-rewards.mdx b/docs/content/about-iota/iota-architecture/staking-rewards.mdx index 21c7ab5d878..56ee5d50fac 100644 --- a/docs/content/about-iota/iota-architecture/staking-rewards.mdx +++ b/docs/content/about-iota/iota-architecture/staking-rewards.mdx @@ -1,6 +1,6 @@ import StakingPoolReqs from "../../_snippets/staking-pool-reqs.mdx"; import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/about-iota/iota-architecture/staking-reward.json'; +import {questions} from '@site/static/json/about-iota/iota-architecture/staking-reward.json'; # Staking and Rewards diff --git a/docs/content/about-iota/iota-architecture/transaction-lifecycle.mdx b/docs/content/about-iota/iota-architecture/transaction-lifecycle.mdx index 599dff115f7..b71d02737c1 100644 --- a/docs/content/about-iota/iota-architecture/transaction-lifecycle.mdx +++ b/docs/content/about-iota/iota-architecture/transaction-lifecycle.mdx @@ -1,5 +1,5 @@ import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/about-iota/iota-architecture/transaction-lifecycle.json'; +import {questions} from '@site/static/json/about-iota/iota-architecture/transaction-lifecycle.json'; import ThemedImage from '@theme/ThemedImage'; # Transaction Life Cycle diff --git a/docs/content/about-iota/tokenomics/gas-in-iota.mdx b/docs/content/about-iota/tokenomics/gas-in-iota.mdx index 896ef5f5f7f..026cf58ab32 100644 --- a/docs/content/about-iota/tokenomics/gas-in-iota.mdx +++ b/docs/content/about-iota/tokenomics/gas-in-iota.mdx @@ -4,7 +4,7 @@ description: An IOTA transaction must both pay for the computational cost of exe --- import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/about-iota/tokenomics/gas-in-iota.json'; +import {questions} from '@site/static/json/about-iota/tokenomics/gas-in-iota.json'; An IOTA transaction must both pay for the computational cost of execution and pay a deposit for storing the objects a transaction creates or mutates. Specifically, [IOTA Gas Pricing](gas-pricing.mdx) is such that any transaction pays the following gas fees: diff --git a/docs/content/about-iota/tokenomics/gas-pricing.mdx b/docs/content/about-iota/tokenomics/gas-pricing.mdx index d7bb6f50064..581fd825c0e 100644 --- a/docs/content/about-iota/tokenomics/gas-pricing.mdx +++ b/docs/content/about-iota/tokenomics/gas-pricing.mdx @@ -3,7 +3,7 @@ title: IOTA Gas Pricing --- import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/about-iota/tokenomics/gas-pricing.json'; +import {questions} from '@site/static/json/about-iota/tokenomics/gas-pricing.json'; The IOTA gas-pricing mechanism achieves three outcomes: delivering low, predictable transaction fees, incentivizing validators to optimize their transaction processing operations, and preventing denial of service attacks. diff --git a/docs/content/about-iota/tokenomics/iota-token.mdx b/docs/content/about-iota/tokenomics/iota-token.mdx index 4e48c0d6e11..b0789349d07 100644 --- a/docs/content/about-iota/tokenomics/iota-token.mdx +++ b/docs/content/about-iota/tokenomics/iota-token.mdx @@ -4,7 +4,7 @@ description: The native asset on IOTA is called IOTA. --- import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/about-iota/tokenomics/iota-token.json'; +import {questions} from '@site/static/json/about-iota/tokenomics/iota-token.json'; The native asset on IOTA is called IOTA. diff --git a/docs/content/about-iota/tokenomics/proof-of-stake.mdx b/docs/content/about-iota/tokenomics/proof-of-stake.mdx index 22f6ac9239c..95feeecd22d 100644 --- a/docs/content/about-iota/tokenomics/proof-of-stake.mdx +++ b/docs/content/about-iota/tokenomics/proof-of-stake.mdx @@ -3,7 +3,7 @@ title: Proof of Stake --- import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/about-iota/tokenomics/proof-of-stake.json'; +import {questions} from '@site/static/json/about-iota/tokenomics/proof-of-stake.json'; The IOTA platform relies on delegated proof-of-stake (DPoS) to determine the set of validators that process transactions. diff --git a/docs/content/about-iota/tokenomics/staking-unstaking.mdx b/docs/content/about-iota/tokenomics/staking-unstaking.mdx index 1517046de17..d166bc119c4 100644 --- a/docs/content/about-iota/tokenomics/staking-unstaking.mdx +++ b/docs/content/about-iota/tokenomics/staking-unstaking.mdx @@ -4,7 +4,7 @@ description: Staking and unstaking IOTA with validators earns a percentage of re --- import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/about-iota/tokenomics/staking-unstaking.json'; +import {questions} from '@site/static/json/about-iota/tokenomics/staking-unstaking.json'; IOTA uses a Delegated-Proof-of-Stake (DPoS) system to secure and operate the network, meaning that the voting power of a validator in the network is determined by the amount of stake delegated to them by IOTA token holders. The more stake delegated to a validator, the more voting power they have. In exchange for processing transactions and performing consensus, validators earn rewards based on a given IOTA inflation rate. These rewards are then shared among stakers as staking rewards. diff --git a/docs/content/about-iota/tokenomics/tokenomics.mdx b/docs/content/about-iota/tokenomics/tokenomics.mdx index 981e93ea2e2..9a6305afcb4 100644 --- a/docs/content/about-iota/tokenomics/tokenomics.mdx +++ b/docs/content/about-iota/tokenomics/tokenomics.mdx @@ -2,7 +2,7 @@ title: IOTA Tokenomics --- import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/about-iota/tokenomics/tokenomics.json'; +import {questions} from '@site/static/json/about-iota/tokenomics/tokenomics.json'; import ThemedImage from '@theme/ThemedImage'; The collective ideation that the term tokenomics encompasses includes a wide range of concepts that define the science and behavior of blockchain economies. In basic terms, tokenomics are the financial foundation of blockchains. Much the same way a building with a poor foundation is doomed to fail, a blockchain without a well-researched, extensively planned, and painstakingly implemented token economy eventually crumbles. diff --git a/docs/content/about-iota/tokenomics/validators-staking.mdx b/docs/content/about-iota/tokenomics/validators-staking.mdx index 6a628c91ab5..ceb4640e92d 100644 --- a/docs/content/about-iota/tokenomics/validators-staking.mdx +++ b/docs/content/about-iota/tokenomics/validators-staking.mdx @@ -4,7 +4,7 @@ title: Validators and Staking Pools import StakingPoolReqs from "../../_snippets/staking-pool-reqs.mdx"; import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/about-iota/tokenomics/validators-staking.json'; +import {questions} from '@site/static/json/about-iota/tokenomics/validators-staking.json'; Each IOTA validator maintains its own staking pool to track the amount of stake and to compound staking rewards. Validator pools operate together with a time series of exchange rates that are computed at each epoch boundary. These exchange rates determine the amount of IOTA tokens that each past IOTA staker can withdraw in the future. Importantly, the exchange rates increase as more rewards are deposited into a staking pool and the longer an amount of IOTA is deposited in a staking pool, the more rewards it will accrue. diff --git a/docs/content/developer/evm-to-move/creating-nft.mdx b/docs/content/developer/evm-to-move/creating-nft.mdx index 243c2932164..17d9289feaa 100644 --- a/docs/content/developer/evm-to-move/creating-nft.mdx +++ b/docs/content/developer/evm-to-move/creating-nft.mdx @@ -3,7 +3,7 @@ title: Creating an ERC-721-like NFT --- import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/developer/evm-to-move/creating-nft.json'; +import {questions} from '@site/static/json/developer/evm-to-move/creating-nft.json'; ## How this works in Solidity / EVM diff --git a/docs/content/developer/evm-to-move/creating-token.mdx b/docs/content/developer/evm-to-move/creating-token.mdx index ed4c48d38ef..43ef88ebde6 100644 --- a/docs/content/developer/evm-to-move/creating-token.mdx +++ b/docs/content/developer/evm-to-move/creating-token.mdx @@ -3,7 +3,7 @@ title: Creating an ERC-20-like token --- import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/developer/evm-to-move/creating-token.json'; +import {questions} from '@site/static/json/developer/evm-to-move/creating-token.json'; ## How this works in Solidity / EVM diff --git a/docs/content/developer/evm-to-move/tooling-apis.mdx b/docs/content/developer/evm-to-move/tooling-apis.mdx index 258599084db..ddb204e9531 100644 --- a/docs/content/developer/evm-to-move/tooling-apis.mdx +++ b/docs/content/developer/evm-to-move/tooling-apis.mdx @@ -3,7 +3,7 @@ title: Tooling and APIs --- import Quiz from '@site/src/components/Quiz'; -import {questions} from '../../../site/static/json/developer/evm-to-move/tooling-apis.json'; +import {questions} from '@site/static/json/developer/evm-to-move/tooling-apis.json'; ## Tooling for EVM/Solidity diff --git a/docs/content/developer/iota-101/nft/marketplace.mdx b/docs/content/developer/iota-101/nft/marketplace.mdx index e5c20e2fa67..e0932cc554b 100644 --- a/docs/content/developer/iota-101/nft/marketplace.mdx +++ b/docs/content/developer/iota-101/nft/marketplace.mdx @@ -5,7 +5,7 @@ description: A brief introduction to implementing NFT marketplace extension usin -import Marketplace from '../../../../examples/move/nft_marketplace/README.md'; +import Marketplace from '@site/../examples/move/nft_marketplace/README.md'; # Marketplace Extension diff --git a/docs/content/operator/iota-full-node/docker.mdx b/docs/content/operator/iota-full-node/docker.mdx index da8706fedaa..e22f8102d87 100644 --- a/docs/content/operator/iota-full-node/docker.mdx +++ b/docs/content/operator/iota-full-node/docker.mdx @@ -3,7 +3,7 @@ description: Learn how to set up an IOTA Full Node using docker. --- import Quiz from '@site/src/components/Quiz'; import questions from '/json/node-operators/iota-full-node/node-setup.json'; -import Docker from './../../../../docker/fullnode/README.md'; +import Docker from '@site/../../docker/fullnode/README.md'; import WarningAdvanced from './../../_snippets/warning-advanced-instructions-node-setup.mdx' import NodeHardwareRequirements from './../../_snippets/node-hardware-requirements.mdx' diff --git a/docs/content/operator/validator-operation/ansible/README.mdx b/docs/content/operator/validator-operation/ansible/README.mdx index 29c76e118c2..62ef23c2573 100644 --- a/docs/content/operator/validator-operation/ansible/README.mdx +++ b/docs/content/operator/validator-operation/ansible/README.mdx @@ -2,7 +2,7 @@ sidebar_label: Ansible Configuration --- -import Configuration from './../../../../../nre/ansible/README.md'; +import Configuration from '@site/../../nre/ansible/README.md'; # Ansible Configuration diff --git a/docs/content/operator/validator-operation/docker/README.mdx b/docs/content/operator/validator-operation/docker/README.mdx index 08351c3e676..2d2e80d6841 100644 --- a/docs/content/operator/validator-operation/docker/README.mdx +++ b/docs/content/operator/validator-operation/docker/README.mdx @@ -1,7 +1,7 @@ --- sidebar_label: Docker Configuration --- -import Configuration from './../../../../../nre/docker/README.md'; +import Configuration from '@site/../../nre/docker/README.md'; # System Configuration diff --git a/docs/content/operator/validator-operation/systemd/README.mdx b/docs/content/operator/validator-operation/systemd/README.mdx index 57d80709cf9..bf5d1d4bdcc 100644 --- a/docs/content/operator/validator-operation/systemd/README.mdx +++ b/docs/content/operator/validator-operation/systemd/README.mdx @@ -1,7 +1,7 @@ --- sidebar_label: Systemd Configuration --- -import Configuration from './../../../../../nre/systemd/README.md'; +import Configuration from '@site/../../nre/systemd/README.md'; # System Configuration diff --git a/docs/content/operator/validator-operation/validator-tasks.mdx b/docs/content/operator/validator-operation/validator-tasks.mdx index 7ea7fc905c7..fd67e941d12 100644 --- a/docs/content/operator/validator-operation/validator-tasks.mdx +++ b/docs/content/operator/validator-operation/validator-tasks.mdx @@ -1,4 +1,4 @@ -import ValidatorTasks from './../../../../nre/validator_tasks.md'; +import ValidatorTasks from '@site/../../nre/validator_tasks.md'; import Quiz from '@site/src/components/Quiz'; import questions from '/json/node-operators/validator-tasks.json'; diff --git a/docs/content/operator/validator-tools.mdx b/docs/content/operator/validator-tools.mdx index 7c567f20821..e2b3137a335 100644 --- a/docs/content/operator/validator-tools.mdx +++ b/docs/content/operator/validator-tools.mdx @@ -1,4 +1,4 @@ -import ValidatorTools from './../../../nre/validator_tool.md'; +import ValidatorTools from '@site/../../nre/validator_tool.md'; import Quiz from '@site/src/components/Quiz'; import questions from '/json/node-operators/validator-tools.json'; diff --git a/docs/content/references/rust-sdk.mdx b/docs/content/references/rust-sdk.mdx index 19d219ae26d..382861da36e 100644 --- a/docs/content/references/rust-sdk.mdx +++ b/docs/content/references/rust-sdk.mdx @@ -3,7 +3,7 @@ title: IOTA Rust SDK description: The IOTA Rust SDK provides Rust wrappers around the IOTA API. Using the SDK, you can interact with IOTA networks using the Rust programming language. --- -import README from "../../../crates/iota-sdk/README.md"; +import README from "@site/../../crates/iota-sdk/README.md"; The IOTA Rust SDK crate is in the [**crates\iota-sdk** directory](https://github.com/iotaledger/iota/tree/develop/crates/iota-sdk) of the IOTA repository. diff --git a/docs/site/docusaurus.config.js b/docs/site/docusaurus.config.js index feb04ab538a..bf9d37e1b57 100644 --- a/docs/site/docusaurus.config.js +++ b/docs/site/docusaurus.config.js @@ -118,6 +118,21 @@ const config = { /** @type {import('@docusaurus/preset-classic').Options} */ ({ docs: { + lastVersion: 'current', + versions: { + current: { + label: 'Testnet', + path: '/', + badge: true, + banner: 'none', + }, + devnet: { + label: 'Devnet', + path: 'devnet', + badge: true, + banner: 'none', + }, + }, path: "../content", routeBasePath: "/", sidebarPath: require.resolve("./sidebars.js"), @@ -240,28 +255,44 @@ const config = { }, items: [ { + type: 'docsVersion', label: "About IOTA", to: "about-iota", + activeBaseRegex: 'about-iota[/]{0,1}.*', }, { + type: 'docsVersion', label: "Developers", to: "developer", + activeBaseRegex: 'developer[/]{0,1}.*', }, { + type: 'docsVersion', label: "Node Operators", to: "operator", + activeBaseRegex: 'operator[/]{0,1}.*', }, { + type: 'docsVersion', label: "References", to: "references", + activeBaseRegex: 'references[/]{0,1}(?!.*(ts-sdk))', }, { + type: 'docsVersion', label: "TS SDK", to: "references/ts-sdk/typescript/", + activeBaseRegex: 'ts-sdk[/]{0,1}.*', }, { + type: 'docsVersion', label: "IOTA Identity", to: "iota-identity", + activeBaseRegex: 'iota-identity[/]{0,1}.*', + }, + { + type: 'docsVersionDropdown', + position: 'right', }, ], }, diff --git a/docs/site/versioned_docs/version-devnet/_snippets/address-prefix.mdx b/docs/site/versioned_docs/version-devnet/_snippets/address-prefix.mdx new file mode 100644 index 00000000000..4369fb3a870 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/address-prefix.mdx @@ -0,0 +1,3 @@ +You can pass literal addresses and objects IDs by prefixing them with '@'. This is needed to distinguish a hexadecimal value from an address in some situations. + +For addresses that are in your local wallet, you can use their alias instead (passing them without '@', for example, --transfer-objects my_alias). diff --git a/docs/site/versioned_docs/version-devnet/_snippets/app-examples-swap-source.mdx b/docs/site/versioned_docs/version-devnet/_snippets/app-examples-swap-source.mdx new file mode 100644 index 00000000000..dd5f1c6c3f7 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/app-examples-swap-source.mdx @@ -0,0 +1,5 @@ +:::info + +You can view the [complete source code for this app example](https://github.com/iotaledger/iota/tree/develop/examples/trading) in the IOTA repository. + +::: \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/automated-address-management.mdx b/docs/site/versioned_docs/version-devnet/_snippets/automated-address-management.mdx new file mode 100644 index 00000000000..b90d70f50fb --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/automated-address-management.mdx @@ -0,0 +1,6 @@ +:::tip Automated Address Management + +IOTA supports [Automated Address Management](../developer/iota-101/move-overview/package-upgrades/automated-address-management.mdx), +with which addresses will automatically be updated in the `Move.lock` file. + +::: \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/cli-check-install.mdx b/docs/site/versioned_docs/version-devnet/_snippets/cli-check-install.mdx new file mode 100644 index 00000000000..860557ad1cc --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/cli-check-install.mdx @@ -0,0 +1,11 @@ +## Check IOTA CLI installation + +Before you can use the IOTA CLI, you must install it. To check if the CLI exists on your system, open a terminal or console and type the following command: + +```shell +iota --version +``` + +If the terminal or console responds with a version number, you already have the IOTA CLI installed. + +If the command is not found, follow the instructions in [Install IOTA](/developer/getting-started/install-iota.mdx) to get the IOTA CLI on your system. \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/data-wipe.mdx b/docs/site/versioned_docs/version-devnet/_snippets/data-wipe.mdx new file mode 100644 index 00000000000..088491c79ca --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/data-wipe.mdx @@ -0,0 +1,8 @@ + +:::danger Data persistence is not guaranteed on the Testnet and Devnet + +Devnet data is wiped regularly as part of scheduled software updates. + +The data on Testnet persists through the regular update process, but might be wiped when necessary. Testnet data wipes are announced ahead of time. + +::: diff --git a/docs/site/versioned_docs/version-devnet/_snippets/faucet.mdx b/docs/site/versioned_docs/version-devnet/_snippets/faucet.mdx new file mode 100644 index 00000000000..0660722c579 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/faucet.mdx @@ -0,0 +1,6 @@ +:::info + +Faucets on Devnet and Testnet are rate limited. If you run the script too many times, you +surpass the limit and must wait to successfully run it again. + +::: \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/info-high-traffic.mdx b/docs/site/versioned_docs/version-devnet/_snippets/info-high-traffic.mdx new file mode 100644 index 00000000000..734ea92ab9e --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/info-high-traffic.mdx @@ -0,0 +1,7 @@ +:::info + +It is suggested to use dedicated nodes/shared services rather than public endpoints for production apps with high traffic volume. + +You can either run your own Full nodes, or outsource this to a professional infrastructure provider (preferred for apps that have high traffic). + +::: \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/info-pnpm-required.mdx b/docs/site/versioned_docs/version-devnet/_snippets/info-pnpm-required.mdx new file mode 100644 index 00000000000..fd8bb4741eb --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/info-pnpm-required.mdx @@ -0,0 +1,5 @@ +:::info + +You must use the pnpm or yarn package managers to create IOTA project scaffolds. Follow the [pnpm install](https://pnpm.io/installation) or [yarn install](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable) instructions, if needed. + +::: \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/initialize-iota-client-cli.mdx b/docs/site/versioned_docs/version-devnet/_snippets/initialize-iota-client-cli.mdx new file mode 100644 index 00000000000..1b621052b49 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/initialize-iota-client-cli.mdx @@ -0,0 +1,26 @@ +:::info + +See [Publish a Package](../developer/getting-started/publish.mdx) for a more detailed guide on publishing packages or [IOTA Client CLI](/references/cli/client.mdx) for a complete reference of `client` commands in the IOTA CLI. + +::: + +Before publishing your code, you must first initialize the IOTA Client CLI, if you haven't already. To do so, in a terminal or console at the root directory of the project enter `iota client`. If you receive the following response, complete the remaining instructions: + +``` +Config file ["/.iota/iota_config/client.yaml"] doesn't exist, do you want to connect to a IOTA Full node server [y/N]? +``` + +Enter `y` to proceed. You receive the following response: + +``` +IOTA Full node server URL (Defaults to IOTA Devnet if not specified) : +``` + +Leave this blank (press Enter). You receive the following response: + +``` +Select key scheme to generate keypair (0 for ed25519, 1 for secp256k1, 2: for secp256r1): +``` + +Select `0`. Now you should have a IOTA address set up. + diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/EVM-required-prior-knowledge.md b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/EVM-required-prior-knowledge.md new file mode 100644 index 00000000000..81c1150a394 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/EVM-required-prior-knowledge.md @@ -0,0 +1,14 @@ +:::note Required Prior Knowledge + +This guide assumes you are familiar with the concept +of [tokens](https://en.wikipedia.org/wiki/Cryptocurrency#Crypto_token) +in [blockchain](https://en.wikipedia.org/wiki/Blockchain), +[Ethereum Request for Comments (ERCs)](https://eips.ethereum.org/erc)(also known as Ethereum Improvement Proposals ( +EIP)) +, NFTs, Smart Contracts +and have already tinkered with [Solidity](https://docs.soliditylang.org/en/v0.8.16/). + +You should also have basic knowledge on how to [create](../../developer/iota-evm/how-tos/create-a-basic-contract.mdx) and [deploy](../../developer/iota-evm/how-tos/deploy-a-smart-contract.mdx) +a smart contract. + +::: diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/EVM_compatibility.md b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/EVM_compatibility.md new file mode 100644 index 00000000000..fc1c9ec8887 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/EVM_compatibility.md @@ -0,0 +1,7 @@ +:::info EVM Compatibility + +The ISC EVM layer is also designed to be as compatible as possible with existing Ethereum +[tools](../../developer/iota-evm/getting-started/tools.mdx) and functionalities. However, please make sure you have checked out the current +[properties and limitations](../../developer/iota-evm/getting-started/compatibility.md). + +::: diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/about-accounts.md b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/about-accounts.md new file mode 100644 index 00000000000..efcaf0876b2 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/about-accounts.md @@ -0,0 +1,5 @@ +:::info Accounts in ISC + +Learn more about the [different types of accounts](../../developer/iota-evm/explanations/how-accounts-work.md). + +::: diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/deploy_a_smart_contract.md b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/deploy_a_smart_contract.md new file mode 100644 index 00000000000..40876862755 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/deploy_a_smart_contract.md @@ -0,0 +1,5 @@ +:::tip Deploy a Smart Contract + +Deploy a Solidity Smart Contract following our [how to Deploy a Smart Contract guide](../../developer/iota-evm/how-tos/deploy-a-smart-contract.mdx). + +::: diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/hardhat_config.mdx b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/hardhat_config.mdx new file mode 100644 index 00000000000..8c45877ad70 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/hardhat_config.mdx @@ -0,0 +1,65 @@ +import CodeBlock from '@theme/CodeBlock'; +import { Networks } from '@site/src/components/constant'; + + + + + +{` +networks: { + 'iotaevm-testnet': { + url: '${Networks['iota_testnet'].evm.rpcUrls[0]}', + chainId: ${parseInt(Networks['iota_testnet'].evm.chainId)}, + accounts: [YOUR PRIVATE KEY], + }, +} +`} + + + + + + +{` +networks: { + 'shimmerevm-testnet': { + url: '${Networks['shimmer_testnet'].evm.rpcUrls[0]}', + chainId: ${parseInt(Networks['shimmer_testnet'].evm.chainId)}, + accounts: [YOUR PRIVATE KEY], + }, +} +`} + + + + + + +{` +networks: { + 'iotaevm': { + url: '${Networks['iota'].evm.rpcUrls[0]}', + chainId: ${parseInt(Networks['iota'].evm.chainId)}, + accounts: [YOUR PRIVATE KEY], + }, +} +`} + + + + + + +{` +networks: { + 'shimmerevm': { + url: '${Networks['shimmer'].evm.rpcUrls[0]}', + chainId: ${parseInt(Networks['shimmer'].evm.chainId)}, + accounts: [YOUR PRIVATE KEY], + }, +} +`} + + + + \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/how-tos/token/check_storage_deposit.md b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/how-tos/token/check_storage_deposit.md new file mode 100644 index 00000000000..1ec0d5b6d13 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/how-tos/token/check_storage_deposit.md @@ -0,0 +1,10 @@ +### 1. Check the Storage Deposit + +Check if the amount paid to the contract is the same as the required storage deposit +and set the allowance. + +```solidity +require(msg.value == _storageDeposit*(10**12), "Please send exact funds to pay for storage deposit"); +ISCAssets memory allowance; +allowance.baseTokens = _storageDeposit; +``` diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/how-tos/token/example_code_intro.mdx b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/how-tos/token/example_code_intro.mdx new file mode 100644 index 00000000000..cdd6b4a7b94 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/how-tos/token/example_code_intro.mdx @@ -0,0 +1,9 @@ +import Ownership from '../../ownership.md'; +import Payable from '../../payable.md'; +import CheckStorageDeposit from './check_storage_deposit.md' + + + + + + diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/how-tos/token/obsolete_token_creation.md b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/how-tos/token/obsolete_token_creation.md new file mode 100644 index 00000000000..262570a7fb5 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/how-tos/token/obsolete_token_creation.md @@ -0,0 +1,5 @@ +:::caution + +This method is now obsolete, use the new [`createNativeTokenFoundry`](../../../../developer/iota-evm/how-tos/core-contracts/token/create-native-token.mdx) method instead. + +::: diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/metamask_buttons.mdx b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/metamask_buttons.mdx new file mode 100644 index 00000000000..3dcf48233bf --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/metamask_buttons.mdx @@ -0,0 +1,17 @@ +import { AddToMetaMaskButton } from '@site/src/components/AddToMetaMaskButton'; +import { Networks } from '@site/src/components/constant'; + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/on_off_ledger_request.md b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/on_off_ledger_request.md new file mode 100644 index 00000000000..0782fb88c24 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/on_off_ledger_request.md @@ -0,0 +1,13 @@ +### On-Ledger Requests + +An on-ledger request is a Layer 1 transaction that validator nodes retrieve from the Tangle. The Tangle acts as an +arbiter between users and chains and guarantees that the transaction is valid, making it the only way to transfer assets +to a chain or between chains. + +### Off-Ledger Requests + +If all necessary assets are in the chain already, it is possible to send a request directly to that chain's validator +nodes. +This way, you don’t have to wait for the Tangle to process the message, significantly reducing the overall confirmation +time. +Due to the shorter delay, off-ledger requests are preferred over on-ledger requests unless you need to deposit assets to the chain. diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/oracles_contract_data.mdx b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/oracles_contract_data.mdx new file mode 100644 index 00000000000..dd533a6e252 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/oracles_contract_data.mdx @@ -0,0 +1,35 @@ +import { AddToMetaMaskButton } from '@site/src/components/AddToMetaMaskButton'; +import { Networks } from '@site/src/components/constant'; + + + + +| Contract Type | Contract Address | +|:----------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------:| +| Pyth contract | [https://explorer.evm.iota.org/address/0x8D254a21b3C86D32F7179855531CE99164721933](https://explorer.evm.iota.org/address/0x8D254a21b3C86D32F7179855531CE99164721933) | +| Supra Pull Contract | [https://explorer.evm.iota.org/address/0x2FA6DbFe4291136Cf272E1A3294362b6651e8517](https://explorer.evm.iota.org/address/0x2FA6DbFe4291136Cf272E1A3294362b6651e8517) | +| Supra Storage Contract | [https://explorer.evm.iota.org/address/0xD02cc7a670047b6b012556A88e275c685d25e0c9](https://explorer.evm.iota.org/address/0xD02cc7a670047b6b012556A88e275c685d25e0c9) | +| Supra Push Contract | [https://explorer.evm.iota.org/address/0xD02cc7a670047b6b012556A88e275c685d25e0c9](https://explorer.evm.iota.org/address/0xD02cc7a670047b6b012556A88e275c685d25e0c9) | + + + + +| Contract Type | Contract Address | +|:----------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------:| +| Pyth contract | [https://explorer.evm.shimmer.network/address/0x290f23E4a034Db5237edCb5aA2D94Acb4DD19fD2](https://explorer.evm.shimmer.network/address/0x290f23E4a034Db5237edCb5aA2D94Acb4DD19fD2) | +| Supra Pull Contract | [https://explorer.evm.shimmer.network/address/0xe41444462709484272F54371F3f53bBF900Ec49E](https://explorer.evm.shimmer.network/address/0xe41444462709484272F54371F3f53bBF900Ec49E) | +| Supra Storage Contract | [https://explorer.evm.shimmer.network/address/0x3E5E89d14576cE9f20a8347aA682517fe65B4ACB](https://explorer.evm.shimmer.network/address/0x3E5E89d14576cE9f20a8347aA682517fe65B4ACB) | +| Supra Push Contract | [https://explorer.evm.shimmer.network/address/0x3df842b27c997cEc63160E79CB4398c82645A1c3](https://explorer.evm.shimmer.network/address/0x3df842b27c997cEc63160E79CB4398c82645A1c3) | + + + + +:::tip Oracle Documentation + +You can find detailed documentation on the Oracles in their official documentation: + +* [Pyth Oracle Docs](https://docs.pyth.network/price-feeds/contract-addresses/evm) +* [Supra Pull Docs](https://gb-docs.supraoracles.com/docs/data-feeds/pull-model/networks) +* [Supra Push Docs](https://gb-docs.supraoracles.com/docs/data-feeds/decentralized/networks) + +::: diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/ownership.md b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/ownership.md new file mode 100644 index 00000000000..78cae0552fb --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/ownership.md @@ -0,0 +1,7 @@ +:::info Ownership + +You might want to look into making the function ownable with, for example, +[OpenZeppelin](https://docs.openzeppelin.com/contracts/5.x/access-control#ownership-and-ownable) +so only owners of the contract can call certain functionalities of your contract. + +::: diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/payable.md b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/payable.md new file mode 100644 index 00000000000..c418da00503 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/payable.md @@ -0,0 +1,10 @@ +:::info Payable + +Instead of making the function payable, you could let the contract pay for the storage deposit. +If so, you will need to change the `require` statement to check if the contract's balance has enough funds: + +```solidity +require(address(this).balance > _storageDeposit); +``` + +::: diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/remix-IDE.md b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/remix-IDE.md new file mode 100644 index 00000000000..f871a85d036 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-evm/remix-IDE.md @@ -0,0 +1,6 @@ +:::tip Remix + +This guide will use the [Remix IDE](https://remix.ethereum.org/), but you can use this contract with any IDE you are +familiar with. + +::: diff --git a/docs/site/versioned_docs/version-devnet/_snippets/iota-oop-beta.mdx b/docs/site/versioned_docs/version-devnet/_snippets/iota-oop-beta.mdx new file mode 100644 index 00000000000..5469c2105b9 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/iota-oop-beta.mdx @@ -0,0 +1,5 @@ +:::info + +IOTA Owned Object Pools (IOTAOOP) is a beta library. Enhancements and changes are likely during development. + +::: \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/linux-deps.mdx b/docs/site/versioned_docs/version-devnet/_snippets/linux-deps.mdx new file mode 100644 index 00000000000..914dc9e5d23 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/linux-deps.mdx @@ -0,0 +1,3 @@ +```bash +sudo apt-get install curl git-all cmake gcc libssl-dev pkg-config libclang-dev libpq-dev build-essential +``` diff --git a/docs/site/versioned_docs/version-devnet/_snippets/macos-deps.mdx b/docs/site/versioned_docs/version-devnet/_snippets/macos-deps.mdx new file mode 100644 index 00000000000..9c64605ec54 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/macos-deps.mdx @@ -0,0 +1,3 @@ +```bash +brew install curl cmake libpq git +``` diff --git a/docs/site/versioned_docs/version-devnet/_snippets/mainnet-runs-stardust.mdx b/docs/site/versioned_docs/version-devnet/_snippets/mainnet-runs-stardust.mdx new file mode 100644 index 00000000000..39032335d81 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/mainnet-runs-stardust.mdx @@ -0,0 +1,5 @@ +:::warning Stardust Protocol + +The IOTA Mainnet runs the [Stardust Protocol](https://wiki.iota.org/learn/protocols/stardust/introduction/). + +::: diff --git a/docs/site/versioned_docs/version-devnet/_snippets/migrate-to-graphql.mdx b/docs/site/versioned_docs/version-devnet/_snippets/migrate-to-graphql.mdx new file mode 100644 index 00000000000..f658d3e144d --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/migrate-to-graphql.mdx @@ -0,0 +1 @@ +This guide compares JSON-RPC queries to their equivalent GraphQL counterpart. While it is possible to systematically rewrite JSON-RPC queries (for example, iota_getTotalTransactionBlocks) to their GraphQL counterparts using this guide, it is recommended that you revisit your application's query patterns to take full advantage of the flexibility that GraphQL offers in serving queries that touch multiple potentially nested endpoints (for example transactions, balances, coins), and use the following examples to get a flavor of how the two APIs express similar concepts. \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/migration-warning.mdx b/docs/site/versioned_docs/version-devnet/_snippets/migration-warning.mdx new file mode 100644 index 00000000000..c7cf9e6a8fb --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/migration-warning.mdx @@ -0,0 +1,5 @@ +:::warning Exchanges and dApp Devs Only + +The migration documentation describes the processes needed to claim and migrate output types manually; However, for the average user, this knowledge is not needed and is abstracted in the wallet web application (dashboard). The specific migration knowledge described here is unnecessary for people using a regular wallet. + +::: \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/move-summary.mdx b/docs/site/versioned_docs/version-devnet/_snippets/move-summary.mdx new file mode 100644 index 00000000000..33d2437be33 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/move-summary.mdx @@ -0,0 +1,7 @@ +Move is an open-source language designed for writing secure packages that interact with on-chain objects, commonly known +as smart contracts. +As a platform-agnostic language, Move supports the development of shared libraries, tools, and communities across +blockchains with varying data structures and execution models. It is highly adaptable, allowing it to be customized to +fit the specific requirements of the blockchain it operates on. For +example, [Move on IOTA](../developer/iota-101/move-overview/move-overview.mdx) showcases optimizations made for the IOTA +blockchain. diff --git a/docs/site/versioned_docs/version-devnet/_snippets/node-hardware-requirements.mdx b/docs/site/versioned_docs/version-devnet/_snippets/node-hardware-requirements.mdx new file mode 100644 index 00000000000..efcb34aa220 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/node-hardware-requirements.mdx @@ -0,0 +1,7 @@ +:::info Minimum Hardware Requirements + +- CPUs: 8 physical cores / 16 vCPUs +- RAM: 128 GB +- Storage (SSD): 4 TB NVMe drive + +::: \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/not-available-on-testnet.mdx b/docs/site/versioned_docs/version-devnet/_snippets/not-available-on-testnet.mdx new file mode 100644 index 00000000000..fee649cb633 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/not-available-on-testnet.mdx @@ -0,0 +1,5 @@ +:::info Mainnet Only + +IOTA EVM is not available on the IOTA Move Testnet. + +::: \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/publish-to-devnet-with-coins.mdx b/docs/site/versioned_docs/version-devnet/_snippets/publish-to-devnet-with-coins.mdx new file mode 100644 index 00000000000..a335a284f54 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/publish-to-devnet-with-coins.mdx @@ -0,0 +1,9 @@ +Before being able to publish your package to Testnet, you need Testnet IOTA tokens. To get some, join the [IOTA Discord](https://discord.gg/IOTA), complete the verification steps, enter the `#testnet-faucet` channel and type `!faucet `. For other ways to get IOTA in your Testnet account, see [Get IOTA Tokens](/developer/getting-started/get-coins). + +Now that you have an account with some Testnet IOTA, you can deploy your contracts. To publish your package, use the following command in the same terminal or console: + +``` +iota client publish +``` + +For the gas budget, use a standard value such as `20000000`. \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/staking-pool-reqs.mdx b/docs/site/versioned_docs/version-devnet/_snippets/staking-pool-reqs.mdx new file mode 100644 index 00000000000..0216473b53d --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/staking-pool-reqs.mdx @@ -0,0 +1,9 @@ +### Validator staking pool requirements + +There are minimum staking requirements a validator must satisfy to become active and to stay in the active validator set. + +More precisely: + +- A validator candidate must accrue at least 2M IOTA of stake before they can request to join the validator set. +- If an active validator’s stake falls below 1.5M IOTA, they have seven epochs of grace period to gain back the stake before being removed from the validator set. +- If an active validator’s stake falls below 1M IOTA, they are removed from the validator set at the end of the current epoch boundary. IOTA uses 24-hour epochs. diff --git a/docs/site/versioned_docs/version-devnet/_snippets/testing-cheat-sheet.mdx b/docs/site/versioned_docs/version-devnet/_snippets/testing-cheat-sheet.mdx new file mode 100644 index 00000000000..38c9652cc45 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/testing-cheat-sheet.mdx @@ -0,0 +1,3 @@ +- Use [`iota::test_scenario`](https://github.com/iotaledger/iota/blob/develop/crates/iota-framework/packages/iota-framework/sources/test/test_scenario.move) to mimic multi-transaction, multi-sender test scenarios. +- Use the [`iota::test_utils`](https://github.com/iotaledger/iota/blob/develop/crates/iota-framework/packages/iota-framework/sources/test/test_utils.move) module for better test error messages via `assert_eq`, debug printing via `print`, and test-only destruction via `destroy`. +- Use `iota move test --coverage` to compute code coverage information for your tests, and `iota move coverage source --module ` to see uncovered lines highlighted in red. Push coverage all the way to 100% if feasible. diff --git a/docs/site/versioned_docs/version-devnet/_snippets/upgrade-single-key-risk.mdx b/docs/site/versioned_docs/version-devnet/_snippets/upgrade-single-key-risk.mdx new file mode 100644 index 00000000000..c56e0added3 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/upgrade-single-key-risk.mdx @@ -0,0 +1,3 @@ +- **Conflicting Interests:** The entity controlling the key may make changes that benefit themselves but are not in the best interests of the broader community. +- **Lack of Consultation:** Upgrades might be executed without sufficient time for package users to review the changes or decide whether to continue using the package if they disagree with the updates. +- **Key Loss:** If the key is lost, it could permanently prevent any future upgrades, leaving the package in a potentially vulnerable or outdated state. diff --git a/docs/site/versioned_docs/version-devnet/_snippets/validator-requirements-tab.mdx b/docs/site/versioned_docs/version-devnet/_snippets/validator-requirements-tab.mdx new file mode 100644 index 00000000000..ab2b951616b --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/validator-requirements-tab.mdx @@ -0,0 +1,23 @@ + + + + +- **RAM:** 128 GB +- **CPU:** 24-core processor +- **Storage:** 4 TB +- **Network Uplink:** 1 Gbps +- **Minimum Stake:** 2 million IOTAs (can be achieved through delegation) + + + + + +- **RAM:** 64 GB +- **CPU:** 8-core processor +- **Storage:** 2 TB +- **Network Uplink:** 1 Gbps +- **Minimum Stake:** 2 million IOTAs (can be achieved through delegation) + + + + \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/_snippets/warning-advanced-instructions-node-setup.mdx b/docs/site/versioned_docs/version-devnet/_snippets/warning-advanced-instructions-node-setup.mdx new file mode 100644 index 00000000000..cc42330d620 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/_snippets/warning-advanced-instructions-node-setup.mdx @@ -0,0 +1,6 @@ +:::warning Advanced + +These instructions are for setting up a Full node for network participation. If you just need a local development environment, +you should instead follow the instructions in [Create a Local IOTA Network](/developer/getting-started/local-network) to create a local Full node, validators, and faucet. + +::: \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/about-iota/FAQ.mdx b/docs/site/versioned_docs/version-devnet/about-iota/FAQ.mdx new file mode 100644 index 00000000000..6fe8086775e --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/FAQ.mdx @@ -0,0 +1,175 @@ +import ValidatorRequirementsTab from '../_snippets/validator-requirements-tab.mdx' + +--- +description: Frequently asked question about IOTA Rebased, Move and the IOTA Rebased Proposal. +--- +# FAQs + +## 1. How does the MoveVM improve security and developer experience? + +MoveVM offers: + +- **Resource-Oriented Programming:** Secure and flexible asset management. +- **Strong Data Abstraction:** Simplifies resource management tasks. +- **Static Verification:** Detects errors before code execution, enhancing security. +- **Formal Verification Support:** Allows rigorous validation of smart contract logic. +- **Improved Developer Experience:** Reduces bugs and vulnerabilities through strict typing. + +## 2. How can I participate in the testnet and provide feedback? + +To participate: + +- **Join the Public Testnet:** Access the IOTA Rebased public testnet to explore new features. +- **Provide Feedback:** Use dedicated channels on the [IOTA Discord](https://discord.iota.org/) server or [GitHub](https://github.com/iotaledger/iota) to report issues. + +## 3. What are the hardware requirements for validators? + +[Validators](https://docs.iota.org/operator/validator-operation/validator-tasks) are expected to have: + + + +## 4. What happens to the existing IOTA EVM? + +The [IOTA EVM](https://wiki.iota.org/isc/introduction/) on Layer 2 will: + +- **Continue Operating:** It will eventually run alongside the new IOTA Rebased Layer 1. +- **Integration Plans:** Future plans include integrating EVM capabilities directly into Layer 1. +- **Temporary Pause During Upgrade:** The EVM chain will be paused and upgraded but will resume normal operations + afterward. + +## 5. What are the key features introduced with IOTA Rebased? + +Key features include: + +- **L1 Smart Contracts:** Smart contract capabilities directly on the Layer 1 network using MoveVM. +- **[Delegated Proof of Stake (dPoS)](./tokenomics/proof-of-stake.mdx):** A fully decentralized network governed by validators and stakers. +- **[Enhanced Tokenomics](./tokenomics/tokenomics.mdx):** Staking rewards, transaction fees with fee-burning, and storage deposits. +- **[Improved Security and Performance](./iota-architecture/iota-security.mdx):** Resilient [consensus](./iota-architecture/consensus.mdx) mechanisms, fairer gas pricing, and dynamic validator selection. + +## 6. Why is IOTA moving to the MoveVM and an object-based architecture? + +The shift to the MoveVM and an object-based architecture is designed to: + +- **Enhance Flexibility and Programmability:** Allow complex applications to be written via smart contracts directly on L1. +- **Support Advanced Use Cases:** Enable sophisticated financial instruments, decentralized exchanges, and intricate supply chain systems. +- **Improve Security:** Leverage MoveVM features like resource-oriented programming and static verification to enhance security. +- **Simplify Development:** Provide strong data abstraction capabilities and support for formal verification, improving the developer experience. + +## 7. How will the tokenomics change under the IOTA Rebased proposal? + +The new tokenomics model includes: + +- **[Staking Rewards](./tokenomics/validators-staking.mdx):** Validators and delegators receive newly minted IOTA tokens as rewards (approximately 767,000 IOTAs per epoch), resulting in an initial annual inflation rate of about 6%. +- **[Transaction Fees](./tokenomics/gas-in-iota.mdx):** Small fees are charged on transactions (around 0.005 IOTA for an average transaction) and are burned to create deflationary pressure. +- **[Storage Deposits](./tokenomics/gas-in-iota.mdx#storage-units):** A redeemable deposit is required for storage, similar to the storage deposit system used in IOTA Stardust. + +## 8. How does staking work in the new tokenomics model? + +Staking involves: + +- **[Delegation to Validators](./tokenomics/validators-staking.mdx):** Token holders can delegate their tokens to validators to help secure the network. +- **[Earning Rewards](./tokenomics/validators-staking.mdx#validator-pool-rewards):** Both validators and their delegators receive staking rewards from newly minted tokens. +- **Proportional Distribution:** Rewards are distributed based on the amount of stake and validator commissions. + +## 9. How will the new fee-burning mechanism work? + +The fee-burning mechanism: + +- **Burns Transaction Fees:** Collected fees are burned, reducing the overall token supply. +- **Deflationary Effect:** Increased network usage leads to more fees burned, creating deflationary pressure. +- **Supply Dynamics:** The mechanism balances inflation from staking rewards and deflation from fee burning. + +## 10. How will the introduction of transaction fees affect users? + +Transaction fees are minimal and serve as a congestion control mechanism: + +- **Low Fees:** Approximately 0.005 IOTA per average transaction. +- **Fee Burning:** Fees are burned to reduce the total supply, creating deflationary pressure. +- **Staking Rewards Offset Fees:** Users can earn staking rewards that may exceed the cost of transaction fees. +- **Sponsored Transactions:** Developers can cover transaction fees on behalf of users, allowing for feeless user experiences. + +## 11. How will this affect current token holders? + +For current token holders: + +- **Balances Maintained:** All balances will be migrated to the new network without loss. +- **Same Private Keys:** Users can access their tokens using their existing private keys in the new IOTA Wallet. +- **[Staking Opportunities](./tokenomics/validators-staking.mdx):** Token holders can participate in staking or delegation to earn rewards. + +## 12. Will there be any migration steps for users? + +No manual migration is needed: + +- **Seamless Transition:** The [migration process](../developer/stardust/stardust-migration.mdx) is designed to be automatic. +- **New Wallet Access:** Users will need to use the new [IOTA Wallet](./iota-wallet/getting-started.mdx) and can import their existing mnemonics or private keys. + +## 13. Will transaction fees impact the feeless nature of IOTA? + +Yes, but: + +- **Minimal Impact:** Fees are very low and designed as a congestion control mechanism. +- **Net Gain for Users:** Staking rewards can offset transaction fees, potentially resulting in more tokens than before. +- **Sponsored Transactions:** Developers can sponsor fees, allowing users to transact without holding IOTA tokens. + +## 14. How will the governance vote work? + +The governance vote allows IOTA token holders to decide on the proposed upgrade: + +- **Announcement Phase:** The proposal is announced, and the community is informed. +- **Voting Open Phase (7 days):** Voters cast their ballots before counting begins. +- **Counting Phase (7 days):** Votes accumulate over time; each IOTA token accumulates voting power at a rate of 0.01 votes per milestone. +- **Quorum Requirement:** A minimum of 5% of the circulating supply must participate for the vote to be valid. +- **Outcome Determination:** The option with the majority of votes prevails. + +## 15. What happens if the proposal is accepted? + +If accepted: + +- **Mainnet Upgrade:** The IOTA network will transition to the new IOTA Rebased protocol after thorough testing and audits. +- **Network Transition:** A final snapshot of the current network will migrate balances to the new network on a 1:1 basis. +- **IOTA EVM Chain Upgrade:** The IOTA EVM Layer 2 chain will be temporarily paused and upgraded to integrate with the new ledger. +- **Wallet Transition:** The IOTA Firefly wallet will be discontinued. Users can access their holdings with the new IOTA Wallet using the same private keys. +- **Token Continuity:** No token migration is necessary; tokens will be available immediately after the launch. + +## 16. What happens if the proposal is rejected? + +If rejected: + +- **Current Operations Continue:** The IOTA network will continue operating as it currently does. +- **Future Decisions:** The IOTA Foundation will decide on future development paths and how to proceed with network improvements. + +## 17. What is the IOTA Rebased proposal? + +The IOTA Rebased proposal is a significant upgrade to the IOTA protocol that aims to enhance the network's capabilities by: + +- **Transitioning to an Object-Based Architecture:** Moving away from the current UTXO model to an object-based ledger. +- **Introducing the Move Virtual Machine (MoveVM):** Implementing MoveVM to enable Layer 1 (L1) smart contract capabilities. +- **Establishing Full Decentralization:** Adopting a delegated proof-of-stake (dPoS) system with validators and stakers to secure the network. +- **Updating Tokenomics:** Introducing staking rewards, transaction fees, and a fee-burning mechanism to create a dynamic supply. + +## 18. What is the future roadmap for IOTA? + +The future roadmap includes: + +- **Protocol Refinements:** Enhancements like resilient consensus mechanisms and fairer gas pricing. +- **Multi-VM Ledger:** Transitioning to support multiple virtual machines, including EVM, on Layer 1. +- **Tooling and Products:** Developing new wallets, SDKs, CLI tools, and identity solutions. +- **Mainnet Launch Timeline:** A potential launch in early 2025 after thorough testing and audits. + +## 19. Why is IOTA making this change now? + +The change addresses: + +- **Market Demands:** There's a clear need for Layer 1 programmability and smart contracts to meet modern application requirements. +- **Technological Evolution:** The new architecture allows for faster, more secure, and scalable solutions. +- **Avoiding Delays:** Continuing with the current roadmap would require additional years of research and development with uncertain outcomes. + +## 20. Where can I find more information and stay updated? + +Stay informed by: + +- **Visiting Official Resources:** Visit the official [IOTA Foundation Blog](https://blog.iota.org/) for regular updated. +- **Joining Community Channels:** Engage with the IOTA community on [Discord](https://discord.iota.org/), + [YouTube](https://www.youtube.com/c/iotafoundation), [X](https://www.twitter.com/iota/) and [GitHub](https://www.github.com/iotaledger/). +- **Following Announcements:** Keep an eye on official blog posts and updates from the IOTA Foundation. + diff --git a/docs/site/versioned_docs/version-devnet/about-iota/about-iota.mdx b/docs/site/versioned_docs/version-devnet/about-iota/about-iota.mdx new file mode 100644 index 00000000000..8909079db5a --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/about-iota.mdx @@ -0,0 +1,89 @@ +import NotAvailableOnTestnet from '../_snippets/not-available-on-testnet.mdx'; +import MainnetRunsStardust from '../_snippets/mainnet-runs-stardust.mdx'; + +# About IOTA + +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. + +## Layer 1 + +### Move + +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: + +#### Object-Centric Design + +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. + +#### Performance + +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. + +#### Security + +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. + +:::warning + +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. + +::: + +### Networks + +#### IOTA Mainnet + + + +The [IOTA Mainnet](https://wiki.iota.org/build/networks-endpoints/#iota) 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 Testnet + +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. + +#### IOTA Devnet + +The IOTA Devnet is used to develop new features. You can use this network to code with the latest planned features of IOTA. + +## Layer 2 + +### EVM + + + +[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](https://wiki.iota.org/isc/introduction/) 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/site/versioned_docs/version-devnet/about-iota/iota-architecture/consensus.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/consensus.mdx new file mode 100644 index 00000000000..253688f9952 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/consensus.mdx @@ -0,0 +1,18 @@ +--- +title: Consensus on IOTA +sidebar_label: Consensus +description: Overview of the IOTA consensus. +--- + +The basic purpose of consensus in blockchains is to agree on a consistent order and ensure the availability of transactions. + +On IOTA, consensus has a simple API: validators submit different user transactions to consensus concurrently, and the consensus outputs a consistent stream of transactions across all well-behaving validators. + +Byzantine-fault tolerant (BFT) consensus protocols are a rich area of research. The next-generation consensus engine in IOTA is based on the **Mysticeti** protocol. +The protocol optimizes for both low latency and high throughput because: +- It allows multiple validators to propose blocks in parallel, utilizing the full bandwidth of the network and providing censorship resistance. These are features of the DAG-based consensus protocols. +- It takes only three rounds of messages to commit blocks from the DAGs, same as pBFT and matches the theoretical minimum. +- The commit rule allows voting and certifying leaders on blocks in parallel, further reducing the median and tail latencies. +- The commit rule also tolerates unavailable leaders without significantly increasing the commit latencies. + +For more details including correctness proofs, the [Mysticeti paper](https://arxiv.org/pdf/2310.14821) is the best source. diff --git a/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/epochs.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/epochs.mdx new file mode 100644 index 00000000000..b8a6c61ab58 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/epochs.mdx @@ -0,0 +1,44 @@ +import Quiz from '@site/src/components/Quiz'; +import {questions} from '@site/static/json/about-iota/iota-architecture/epochs.json'; + +# Epochs and Reconfiguration + +## 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 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 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. + +## Quizzes + diff --git a/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/iota-architecture.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/iota-architecture.mdx new file mode 100644 index 00000000000..0b8885cf916 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/iota-architecture.mdx @@ -0,0 +1,50 @@ +--- +title: IOTA Architecture +--- +import ThemedImage from '@theme/ThemedImage'; + +IOTA shares some similarities with other blockchains but is unique in many ways. Use the topics in this section to understand the features that define the IOTA network. + +## Understand IOTA Security + +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-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](transaction-lifecycle.mdx). + +## Consensus + +Every transaction on IOTA is sequenced by consensus, where validators agree to the same order of execution of the transactions, even if a minority of them are down or are malicious actors that want to harm the network and users. +IOTA currently uses the [Mysticeti](https://arxiv.org/pdf/2310.14821) consensus algorithm. + +Go to [Consensus](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](protocol-upgrades.mdx). + +## IOTA Architecture Diagram + +The following diagram describes the architectural structure for IOTA's solution. + +The core components are: + +- [Execution Layer](../../references/execution-architecture/execution-layer.mdx) +- [IOTA Node](../../operator/iota-full-node/overview.mdx) +- [IOTA RPC](../../references/iota-api) +- [IOTA CLI](../../references/cli) + + diff --git a/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/iota-security.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/iota-security.mdx new file mode 100644 index 00000000000..c5977b33bd9 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/iota-security.mdx @@ -0,0 +1,72 @@ +import Quiz from '@site/src/components/Quiz'; +import {questions} from '@site/static/json/about-iota/iota-architecture/iota-security.json'; + +# Security + +## Assets + +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. + +## Validators and Consensus + +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. + +:::tip Validator Selection + +The set of validators changes periodically and is [determined by the amount of locked and delegated IOTAs held](../tokenomics/validators-staking.mdx). + +::: + +### Choosing Validators + +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. + +### Rewards for Validators and Stakers + +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. + +### Accountability and Rotation of Validators + +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. + +## Addresses and Keys + +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. + +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. + +## Asset Types and Logic + +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. + +### Shared Assets + +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. + +## Transaction Finality + +### Certification and Finalization + +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. + +### Gas and Transaction Execution + +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. + +### Submitting Transactions + +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. + +## 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. + + +## Quizzes + \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/protocol-upgrades.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/protocol-upgrades.mdx new file mode 100644 index 00000000000..b562160ce1e --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/protocol-upgrades.mdx @@ -0,0 +1,56 @@ +import Quiz from '@site/src/components/Quiz'; +import {questions} from '@site/static/json/about-iota/iota-architecture/protocol-upgrades.json'; + +# 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. + +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? + +To address this, IOTA uses a process called protocol upgrades. + +## Protocol Upgrade Process + +The protocol upgrade process 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. + +Full nodes follow a similar process but 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. + +## 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. + +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. + +## Quizzes + diff --git a/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/staking-rewards.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/staking-rewards.mdx new file mode 100644 index 00000000000..56ee5d50fac --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/staking-rewards.mdx @@ -0,0 +1,57 @@ +import StakingPoolReqs from "../../_snippets/staking-pool-reqs.mdx"; +import Quiz from '@site/src/components/Quiz'; +import {questions} from '@site/static/json/about-iota/iota-architecture/staking-reward.json'; + +# 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 + +Stakers keep their staked IOTA tokens in their own account. + +### Auto-compounding Rewards + +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 + +At the end of each [epoch](epochs.mdx), newly minted IOTA tokens are distributed as rewards among validators and stakers. Within each validator staking pool, stakers receive rewards proportionally through the appreciation of the pool's exchange rate. Validators also earn additional rewards, represented as StakedIOTA objects, which they receive at the end of each epoch in proportion to the commissions generated by their staking pool. + +Each epoch's rewards are funded by newly minted IOTA tokens, totaling 767k IOTA per epoch. This amount is distributed across staking pools based on their voting power and the specified tallying rule. 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. + +### Commission Rate + +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 + +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. + +## Quizzes + diff --git a/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/transaction-lifecycle.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/transaction-lifecycle.mdx new file mode 100644 index 00000000000..b71d02737c1 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-architecture/transaction-lifecycle.mdx @@ -0,0 +1,140 @@ +import Quiz from '@site/src/components/Quiz'; +import {questions} from '@site/static/json/about-iota/iota-architecture/transaction-lifecycle.json'; +import ThemedImage from '@theme/ThemedImage'; + +# Transaction Life Cycle + +## High-level Overview + + + +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). + +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. + +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 _certificate_s; this is the responsibility of the client or gateway. + +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 _certificate_s are forwarded to the IOTA DAG-based consensus protocol. + +5. **Consensus and Execution**: The IOTA DAG-based consensus protocol eventually produces a total order of _certificate_s. Validators check and execute _certificate_s that involve shared objects. + +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. + +7. **Checkpoints and Reconfiguration**: IOTA forms checkpoints for every consensus commit, which are also used to drive the reconfiguration protocol. + +## Real-world Example + +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? + +### Transaction Creation + +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. + +### Transaction Broadcast + +Your wallet app sends the signed transaction to a full node, which then broadcasts it to all validators in the network. + +### Transaction Certification + +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. + +### Transaction Finalization + +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_. + +Your wallet app receives this effects _certificate_, which you can show to the coffee shop to prove that the transaction is complete and irreversible. + +## Transaction Life Cycle + +### 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. + +### Certification + +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: + +* 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. + +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. + +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_**. + +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. + +### Execution + +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. + +Depending on whether the transaction uses shared input objects, the validators will either: + +* 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. + +This ensures that transactions are processed in the correct order and prevent conflicts. + +### Effects Certificate + +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: + +* 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). + +The full node then gathers these signed effects from a majority of validators, forming an **effects _certificate_**, which guarantees that the transaction is final. + +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. + +### 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: + +* Ordered transaction lists. +* Transaction effects. + +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. + +### 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. + +### Settlement Finality + +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 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. + +### Checkpoint Processing + +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. + +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. + +### Local Execution on a Full Node + +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. + +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/about-sponsored-transactions.mdx#risk-considerations). You can avoid this unwanted behavior by sending the `WaitForLocalExecution` parameter. + +### Epoch Change + +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. + +## Quizzes + + \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/FAQ.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/FAQ.mdx new file mode 100644 index 00000000000..422248efd83 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/FAQ.mdx @@ -0,0 +1,101 @@ +--- +description: Frequently asked questions about the IOTA Wallet, covering topics like installation, security, transactions, and staking. +--- + +# IOTA Wallet FAQ + +## How Do I Get IOTA Wallet? + +You can install the IOTA Wallet extension from the [Google Chrome Web Store](https://chromewebstore.google.com/detail/iota-wallet/iidjkmdceolghepehaaddojmnjnkkija). +It works across all Chromium-based browsers, including Google Chrome, Microsoft Edge, Firefox, Opera, and Brave. + +## Can I Use IOTA Wallet on Non-Chromium Browsers? + +Currently, IOTA Wallet is designed for Chromium-based browsers. +There are no plans to expand support to other browser types at this time. + +## What Is a Mnemonic Recovery Phrase? + +A mnemonic recovery phrase is a unique 24-word string that IOTA provides when you create a wallet. +It is essential for recovering your wallet and transferring it to another device. +Keep it secure at all times. + +## What Does It Mean to Import an Existing Wallet? + +[Importing](how-to/multi-account.mdx#import-a-profile) a wallet means bringing an account from another wallet into IOTA Wallet using its mnemonic recovery phrase, +private key or seed. + +## How Do I Get IOTA Into My Wallet? + +You can receive IOTA from another address or acquire it from an exchange. + +## My NFTs Are in My Wallet, but I Can’t See the Images. Why? + +IOTA Wallet uses the Object Display standard for showing NFT images. +If an NFT does not follow this standard, the wallet will display the asset without an image. + +## How Do I Send IOTA to Another Person? + +To send IOTA, you need the recipient’s wallet address. +Always double-check the address, as IOTA cannot be recovered if sent to the wrong address, +and transactions cannot be reversed. + +## Failed Transactions and Gas Fees + +### Why Do I Still Pay Gas Fees When My Transaction Fails? + +Transactions may fail due to incorrect specifications or an insufficient gas budget, but gas fees are still required as +compensation for validators processing the attempt. + +### Why Did I Receive a Negative Gas Fee on a Failed Transaction? + +In some cases, a failed transaction may delete gas objects, resulting in storage rebates that exceed the gas fee, +leading to a positive IOTA transfer despite the failure. + +## What Is Staking? + +Staking allows you to earn rewards by delegating your IOTA to validators who help secure the network. +Each validator offers different reward rates. +The minimum amount required to stake is 1 IOTA. + +## How Do I Track My Stake? + +You can monitor your [stakes](how-to/stake.mdx#view-your-current-stakes) on the `Home` tab of the IOTA Wallet. +This includes viewing the average APY earned from validators you are staked with. + +## Can I Set Up Alerts for My Stake? + +At this time, IOTA Wallet does not support alerts. +Rewards are distributed at the end of each 24-hour epoch, and you can withdraw your stake at any time. + +## What Does Active Connections Mean? + +Active Connections shows the apps currently linked to your IOTA Wallet. +These connections remain active until manually removed, even if no transactions are made. +To disconnect, go to the `Active Connections` tab and select the app. + +## Where Can I Find Detailed Information About My Transactions? + +In the `Activity` tab of IOTA Wallet, you’ll find a list of all your transactions. +Click on any transaction to view more details. + +## My Wallet Keeps Logging Me Out. How Do I Stop This? + +For security reasons, IOTA Wallet logs you out after a period of inactivity. +You can increase the auto-lock timeout to a maximum of 30 minutes by [adjusting your wallet settings](how-to/basics.mdx#enable-auto-lock-for-your-iota-wallet). + +## Network and Version Updates + +Make sure you're connected to the correct network for your activities. +Events like network resets on Devnet may temporarily affect the visibility of your assets. + +## I Think Someone Has Access to My IOTA Wallet. What Should I Do? + +If you suspect unauthorized access to your wallet, immediately transfer your assets to a new wallet. +Check for malware, ensure your mnemonic recovery phrase is secure, +and review recent activity using an IOTA transaction explorer. + +## Can I Update My Mnemonic Recovery Phrase to Something More Memorable? + +No, the mnemonic recovery phrase provided by IOTA Wallet cannot be changed. +Always store it securely, as it is essential for wallet recovery. diff --git a/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/getting-started.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/getting-started.mdx new file mode 100644 index 00000000000..ad7dec73c7c --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/getting-started.mdx @@ -0,0 +1,84 @@ +--- +description: A guide for getting started with the IOTA Wallet, including setup, creating accounts, and importing existing wallets. +--- + +# Getting Started with the IOTA Wallet + +The IOTA Wallet offers an easy-to-use platform for managing your digital assets on the IOTA network. + +* **Set up IOTA profiles and accounts**: +Create new addresses to handle coins, tokens, and NFTs. +* **Import private keys:** Transfer assets seamlessly from other wallets using a 32 or 64-byte address. +* **Stake and earn IOTA:** Secure the network through staking while earning rewards. +* **Transfer assets:** Send coins and NFTs easily to another address with a user-friendly interface. +* **Monitor your assets:** View your coins, tokens, and NFTs in one place for a complete overview. + +## Install IOTA Wallet + +## Installing the IOTA Wallet + +1. Open a Chromium-based browser and visit the [IOTA Wallet page](https://chromewebstore.google.com/detail/iota-wallet/iidjkmdceolghepehaaddojmnjnkkija) in the Chrome Web Store. +2. Click the **Add to Chrome** button to install the wallet extension. +3. Approve the permissions for the extension and confirm by selecting **Add Extension**. +4. Once installed, you’ll see the IOTA Wallet icon in your browser, signaling that it's ready for use. +5. To finalize the setup, proceed to create your new wallet. + +## Creating a New Wallet + +1. Open IOTA Wallet, create a new profile by clicking `Add Profile`. + + ![Add Profile](/img/about-iota/iota-wallet/getting-started/add-profile.png) + +2. Choose **Create a New Mnemonic Profile**. + + ![Create Mnemonic Profile](/img/about-iota/iota-wallet/getting-started/create-mnemonic-profile.png) + + +3. Enter your desired password. + + ![Create Password](/img/about-iota/iota-wallet/getting-started/create-password.png) + +4. Carefully read and accept the Terms of Service, and click `Create Wallet`. + + ![Create Wallet](/img/about-iota/iota-wallet/getting-started/create-wallet.png) + +5. Copy and securely save your recovery phrase (mnemonic). This phrase is crucial for recovering your wallet in the + future. + +6. Confirm that you have saved your mnemonic phrase, and then access your newly created wallet by clicking `Open Wallet`. + + ![Open Wallet](/img/about-iota/iota-wallet/getting-started/open-wallet.png) + +:::danger Irrecoverable + +Your mnemonic recovery phrase is essential for regaining access to your wallet if you forget your password or switch devices. If lost, access to your assets cannot be recovered. + +::: + +## Importing an Existing Wallet + +To use your IOTA Wallet on different devices or browsers, you can import it using your 24-word mnemonic recovery phrase: + +1. Open IOTA Wallet and select `Add Profile` + + ![Add Profile](/img/about-iota/iota-wallet/getting-started/add-profile.png) + +2. Click the `Mnemonic` button in the `Import` section. + + ![Import Mnemonic](/img/about-iota/iota-wallet/getting-started/click-import-mnemonic.png) + +3. Enter your 24-word mnemonic recovery phrase and click `Add Profile`. + + ![Add Profile](/img/about-iota/iota-wallet/getting-started/mnemonic.png) + +4. Enter your desired password. + + ![Create Password](/img/about-iota/iota-wallet/getting-started/create-password.png) + +5. Carefully read and accept the Terms of Service, and click `Create Wallet`. + + ![Create Wallet](/img/about-iota/iota-wallet/getting-started/create-wallet.png) + +By following these steps, you can manage, stake, +and transfer your digital assets on the IOTA network from any of your devices, ensuring a seamless experience. + diff --git a/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/basics.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/basics.mdx new file mode 100644 index 00000000000..6ff618b5be7 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/basics.mdx @@ -0,0 +1,113 @@ +--- +description: A collection of how-to guides for managing and using the IOTA Wallet, including balance viewing, sending assets, and security features. +--- + +# Basics + +## View IOTA Wallet Details + +To check your wallet details, including the version, current network, and installed updates, click on the settings icon (gear symbol) in the upper-right corner of the IOTA Wallet interface. + +## Check Your Wallet Balance + +To view the balance and assets in your IOTA Wallet: + +1. Navigate to the `Home` tab. +2. Your IOTA balance will be displayed at the top, with a list of all other coins and tokens you own appearing below. + + ![Home Tab](/img/about-iota/iota-wallet/how-to/basics/home-tab.png) + +## Send Coins + +To send IOTA or other tokens to another address, follow these steps: + +1. Go to the `Home` tab and click the `Send` icon next to your [IOTA Balance](#check-your-wallet-balance). +2. Choose the token you wish to send from the dropdown list. +3. Enter the amount you want to transfer. +4. Input the recipient’s address and click `Review` to confirm. + + ![Review](/img/about-iota/iota-wallet/how-to/basics/send-review.png) + +5. Once you verify the transaction details, click `Send Now ->` to complete the transfer. + + ![Send Review](/img/about-iota/iota-wallet/how-to/basics/send-now.png) + +## View Recent Transaction Details + +To review your transaction history: + +1. Click the `Activity` tab located in the lower-left corner of the wallet. + + ![Review activity](/img/about-iota/iota-wallet/how-to/basics/activity.png) + +2. Select a transaction to see further details about it. + + ![Transaction Details](/img/about-iota/iota-wallet/how-to/basics/transactions.png) + +## View and Manage Your NFTs + +To view and manage your NFTs, follow these steps: + +1. Navigate to the `Assets` tab to see the NFTs you've minted, purchased, or received. +2. Click on any NFT for more detailed information or to send it to another address. + +## Sending an NFT + +To send an NFT: + +1. In the `Assets` tab, select the NFT you wish to transfer. +2. Click `Send Asset`, enter the recipient’s address, and confirm the transaction by clicking `Send Asset`. + +## Enable Auto-Lock for Your IOTA Wallet + +For added security, you can set your wallet to automatically lock after a specified period of inactivity: + +1. Click the settings icon (gear symbol) in the upper-right corner of your wallet. +2. Choose the `Auto Lock Profile` option. + + ![Auto lock profile](/img/about-iota/iota-wallet/how-to/basics/autolock.png) + +3. Set the desired auto-lock time by specifying the idle duration in minutes, then click `Save`. + + ![Auto lock timer](/img/about-iota/iota-wallet/how-to/basics/autolock-time.png) + +## Reset Your IOTA Wallet Password + +If you forget your wallet password, you can reset it using your mnemonic recovery phrase: + +1. On the unlock screen, click `Forgot password?`. + + ![Forgot Password](/img/about-iota/iota-wallet/how-to/basics/forgot-password.png) + +2. Enter your 24-word mnemonic recovery phrase and click `Next`. + + ![Enter Mnemonic](/img/about-iota/iota-wallet/how-to/basics/enter-mnemonic.png) + +3. Create and confirm your new password, then click `Reset Password`. + + ![New Password](/img/about-iota/iota-wallet/how-to/basics/new-password.png) + +## View Connected Apps + +To manage the apps connected to your IOTA Wallet: + +### Access Active Connections + +1. Go to the `Active Connections` view to see a list of all connected apps. + +### Visit App Websites + +1. Click on an app from the list and select `View` to open the associated app's website. + +## Disconnecting from an App + +To disconnect your wallet from an app: + +### Open Active Connections + +1. In the `Apps` tab, select `Active Connections`. + +### Disconnect the App + +1. Choose the app you wish to disconnect from, then click `Disconnect`. +2. Your wallet will disconnect from the app, and you'll be redirected back to the Apps tab. diff --git a/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/get-test-tokens.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/get-test-tokens.mdx new file mode 100644 index 00000000000..25ea400d326 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/get-test-tokens.mdx @@ -0,0 +1,35 @@ +--- +description: A guide on how to use IOTA Wallet for testing on different IOTA networks, including how to switch networks and obtain test IOTA tokens. +--- +# Get Test Tokens + +You can test apps on the IOTA network using IOTA Wallet. The wallet supports connections to IOTA Testnet, IOTA Devnet, a [Local network](../../../developer/getting-started/local-network.mdx), or a Custom RPC URL for a network you create. + +## Change the Active Network Connection + +To switch the network in your IOTA Wallet: + +1. Click the settings cog icon in the top-right corner of the IOTA Wallet. +2. Select `Network`. + + ![Network](/img/about-iota/iota-wallet/how-to/test/click-network.png) + +3. Choose the network you want to connect to. A checkmark will appear next to the selected network. + + ![Select Network](/img/about-iota/iota-wallet/how-to/test/select-network.png) + +## Get IOTA Tokens for Testing + +When you first open the wallet, it will have no coins. You can add test IOTA coins for testing purposes. These test tokens have no real-world value and can only be used on the specific network they were obtained from, like Devnet or Testnet. + +### Request IOTA Test Coins Using the Wallet + +1. After installing the wallet extension, choose either Devnet or Testnet from the network options. +2. If your wallet has no coins, a button will appear allowing you to request tokens. +3. Click `Request Devnet IOTA tokens` or `Request Testnet IOTA tokens`, based on the network you're using. + + ![Request Tokens in Home](/img/about-iota/iota-wallet/how-to/test/request-testnet-home.png) + +4. Once tokens are in your wallet, the button to request more will move to the `Settings` page. Access it by clicking the cog icon in the top-right corner of the wallet interface. + + ![Request Tokens in Settings](/img/about-iota/iota-wallet/how-to/test/request-testnet-settings.png) diff --git a/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/integrate-ledger.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/integrate-ledger.mdx new file mode 100644 index 00000000000..093140c0f72 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/integrate-ledger.mdx @@ -0,0 +1,137 @@ +--- +description: A guide on how to use IOTA Wallet with a Ledger device to manage accounts, send, receive, and stake digital assets securely. +--- + +# Use IOTA Wallet with a Ledger Device + +This guide walks you through using IOTA Wallet with your Ledger device. By connecting your Ledger, you can add up to 10 accounts to IOTA Wallet and use them like any other account. +The added benefit is that your private keys remain securely stored in your Ledger, a cold storage wallet, giving you full control over your assets. + +## Requirements + +Before connecting your Ledger device to IOTA Wallet, ensure the following: + +- Install the latest version of [IOTA Wallet](https://chromewebstore.google.com/detail/iota-wallet/iidjkmdceolghepehaaddojmnjnkkija) from the Chrome Web Store. +- Set up your Ledger device and update it to the latest firmware. +- Install [Ledger Live](https://www.ledger.com/ledger-live) and confirm that your device can connect successfully. + +## Install the IOTA Rebased App on Your Ledger Device + +To use IOTA Wallet with Ledger, install the IOTA Rebased app on your device through Ledger Live. + +1. Unlock your Ledger device. +2. Open Ledger Live and navigate to **My Ledger** in the left panel. +3. Press both buttons on the device to approve the secure connection. +4. In the App Catalog, search for **IOTA Rebased**. +5. Click **Install** to download the IOTA Rebased app to your device. +6. Your device will show the installation progress. + +## Import Accounts from Your Ledger Device + +To import accounts from your Ledger into IOTA Wallet: + +1. Unlock your Ledger device. +2. Open the `IOTA Rebased` app on your Ledger and press both buttons to start it. +3. Close Ledger Live if it is still running. +4. Open [IOTA Wallet](https://chromewebstore.google.com/detail/iota-wallet/iidjkmdceolghepehaaddojmnjnkkija) and enter your password. +5. Go to `Accounts` by clicking on the address at the top of the `Home` section. + + ![Accounts](/img/about-iota/iota-wallet/how-to/multi-account/navigate-to-accounts.png) + +6. Click `Add Profile`. + + ![Add Profile](/img/about-iota/iota-wallet/how-to/multi-account/click-add-profile.png) + +7. Select the `Ledger` button from the `Import from Ledger` section. + + ![Import From Ledger](/img/about-iota/iota-wallet/how-to/ledger/import-from-ledger.png) + +8. On the `Connect Ledger Wallet` screen, click `Continue`. + + ![Connect Ledger Wallet](/img/about-iota/iota-wallet/how-to/ledger/connect-ledger-wallet.png) + +9. Choose the wallets you want to import into IOTA Wallet, then click `Next`. + + ![Select Wallets](/img/about-iota/iota-wallet/how-to/ledger/select-wallets.png) + +10. Enter your password and click `Verify`. + +![Verify Password](/img/about-iota/iota-wallet/how-to/ledger/verify-password.png) + +Your imported Ledger accounts will appear under the `Ledger` cluster on the `Manage Accounts` screen. + +## View Account Balance + +To view your account balance in IOTA Wallet, go to the **Coins** tab. The balance and staked IOTA displayed are for the selected account. + +For accounts imported from Ledger, select the account labeled with **LEDGER** to view its coins and tokens. To see NFTs, navigate to the **NFTs** tab. + +## Receive Digital Assets Using IOTA Wallet + +To receive cryptocurrency or NFTs: + +1. Go to `Accounts` by clicking on the address at the top of the `Home` section. + + ![Accounts](/img/about-iota/iota-wallet/how-to/multi-account/navigate-to-accounts.png) + +2. Select the account you want to receive assets on. + + ![Select Account](/img/about-iota/iota-wallet/how-to/ledger/select-account.png) + +3. Click the receive arrow button next to the account balance. + + ![Receive Button](/img/about-iota/iota-wallet/how-to/ledger/receive-button.png) + +4. Copy your address or share the QR code to receive funds. + + ![Receive QR](/img/about-iota/iota-wallet/how-to/ledger/receive-QR.png) + +## Send Digital Assets Using IOTA Wallet + +To send digital assets from your Ledger account: + +1. Go to `Accounts` by clicking on the address at the top of the `Home` section. + + ![Accounts](/img/about-iota/iota-wallet/how-to/multi-account/navigate-to-accounts.png) + +2. Select the account you want to send assets from. + + ![Select Account](/img/about-iota/iota-wallet/how-to/ledger/select-account.png) + +3. Click the blue send button next to your balance. + + ![Send Button](/img/about-iota/iota-wallet/how-to/ledger/receive-button.png) + +4. Select the coin type, enter the amount, and input the recipient's address. Click `Review` to confirm the details. + + ![Review](/img/about-iota/iota-wallet/how-to/basics/send-review.png) + +5. Once confirmed, click `Send Now ->` to complete the transfer. + + ![Send Review](/img/about-iota/iota-wallet/how-to/basics/send-now.png) + +6. On your Ledger device, verify the transaction details: + - Use the right button to scroll through and verify the addresses. + - Ensure the address on the Ledger matches the one in IOTA Wallet. + - Press both buttons to approve the transaction. + +## Stake IOTA Using IOTA Wallet + +To stake IOTA using a Ledger account, you need to enable blind signing on your device. + +1. Unlock your Ledger device and open the IOTA Rebased app. +2. Enable Blind Signing by scrolling to `Blind signing` and pressing both buttons to activate it. +3. Open IOTA Wallet and select the Ledger account you want to stake from. +4. Click `Start Staking`. + + ![Start Staking](/img/about-iota/iota-wallet/how-to/stake/start-staking.png) + +5. Choose a validator and click `Select Amount`. + + ![Select Validator](/img/about-iota/iota-wallet/how-to/stake/select-validator.png) + +6. Enter the amount of IOTA you want to stake and ensure you leave enough for transaction fees. Click `Stake` to confirm. + + ![Set Stake Amount](/img/about-iota/iota-wallet/how-to/stake/set-stake-amount.png) + +7. On your Ledger device, review the transaction details and press both buttons to approve the staking transaction. diff --git a/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/multi-account.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/multi-account.mdx new file mode 100644 index 00000000000..401101999f2 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/multi-account.mdx @@ -0,0 +1,95 @@ +--- +description: A guide to managing multiple profiles and accounts in IOTA Wallet, including adding, importing, and exporting accounts. +--- + +# Manage Profiles and Accounts + +IOTA Wallet allows you to use multiple profiles and accounts, offering flexibility in managing various assets or purposes for transactions. + +:::tip Profiles vs. Accounts + +A profile is a collection of accounts. + +::: + +## Add Another Account Address + +You can create and use multiple accounts within the IOTA Wallet in two ways. + +### Add a Profile + +1. Go to `Accounts` by clicking on the address at the top of the `Home` section. + + ![Accounts](/img/about-iota/iota-wallet/how-to/multi-account/navigate-to-accounts.png) + +2. Click `Add Profile`. + + ![Add Profile](/img/about-iota/iota-wallet/how-to/multi-account/click-add-profile.png) + +3. Choose to either create a new account or import an existing account. + + ![Select Profile Type](/img/about-iota/iota-wallet/how-to/multi-account/select-profile-type.png) + +### Add Another Mnemonic Account + +1. Navigate to `Accounts` at the top of the `Home` tab and select `Manage`. + + ![Accounts](/img/about-iota/iota-wallet/how-to/multi-account/navigate-to-accounts.png) + +2. Click the `+` icon next to the account type you want to add. + + ![Click plus icon](/img/about-iota/iota-wallet/how-to/multi-account/click-plus-icon.png) + +3. Your new account will appear. To use it, select it from the drop-down list on the Coins tab, or choose the address when connecting your wallet to a site or app. + + ![Select account from dropdown](/img/about-iota/iota-wallet/how-to/multi-account/select-account-from-dropdown.png) + +## Import a Profile + +To import an existing profile into your IOTA Wallet: + +1. Navigate to `Accounts` at the top of the `Home` tab. + + ![Accounts](/img/about-iota/iota-wallet/how-to/multi-account/navigate-to-accounts.png) + +2. Click `Add Profile`. + + ![Add Profile](/img/about-iota/iota-wallet/how-to/multi-account/click-add-profile.png) + +3. From the `Import` section, select `Mnemonic`, `Private Key`, or `Seed`. + + ![Select Profile Type](/img/about-iota/iota-wallet/how-to/multi-account/select-profile-type.png) + +4. Enter or paste the private key, mnemonic, or seed for the account you want to import, then click `Add Profile`. + + ![Import Mnemonic](/img/about-iota/iota-wallet/how-to/multi-account/import-mnemonic.png) + +5. Enter your wallet password and click `Verify`. + + ![Verify](/img/about-iota/iota-wallet/how-to/multi-account/verify.png) + +## Export a Private Key for an Account + +Exporting a private key allows you to use the account with other wallet providers. Handle private keys with extreme caution to prevent unauthorized access to your assets. + +:::danger + +When viewing the private key, ensure no one can see your screen. Click the crossed-out eye icon in the bottom-right corner to reveal the key. + +::: + +1. Go to `Accounts` at the top of the `Home` tab. + + ![Accounts](/img/about-iota/iota-wallet/how-to/multi-account/navigate-to-accounts.png) + +2. Select the account you want to export, click on the `...` icon, and choose `Export Private Key` from the dropdown. + + ![Export Private Key](/img/about-iota/iota-wallet/how-to/multi-account/export-private-key.png) + +3. Enter your wallet password and click `Verify`. + + ![Verify](/img/about-iota/iota-wallet/how-to/multi-account/verify.png) + +4. Click `Copy` to copy the private key to your clipboard. + + ![Copy](/img/about-iota/iota-wallet/how-to/multi-account/click-copy.png) diff --git a/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/stake.mdx b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/stake.mdx new file mode 100644 index 00000000000..385ffdb11b1 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/iota-wallet/how-to/stake.mdx @@ -0,0 +1,71 @@ +--- +description: A guide to staking IOTA tokens, earning rewards, and managing your staked assets. +--- +# Stake IOTA + +Stake your IOTA tokens to earn rewards while helping secure the network. +By staking, you delegate your IOTA to a validator, who will compensate you for your support. + +## Access the Staking Feature + +To start staking your IOTA tokens, follow these steps: + +1. Open your IOTA Wallet and navigate to the `Home` tab. + + ![Home Tab](/img/about-iota/iota-wallet/how-to/basics/home-tab.png) + +2. Click `Start Staking`. + + ![Start Staking](/img/about-iota/iota-wallet/how-to/stake/start-staking.png) + +3. Choose a validator and click `Select Amount`. + + ![Select Validator](/img/about-iota/iota-wallet/how-to/stake/select-validator.png) + +4. Enter the amount of IOTA you want to stake. Make sure to leave enough IOTA in your wallet for potential transaction fees, then confirm by clicking `Stake`. + + ![Set Stake Amount](/img/about-iota/iota-wallet/how-to/stake/set-stake-amount.png) + +5. Track the transaction in the [Explorer](https://explorer.rebased.iota.org/) by clicking `View on Explorer`. + + ![View on Explorer](/img/about-iota/iota-wallet/how-to/stake/view-on-explorer.png) + +After staking, your rewards will begin accruing in the next epoch and will be visible in your wallet. + +## View Your Current Stakes + +To check the status of your active stakes: + +1. Open the `Home` tab and click `Current Stake`. + + ![Current Stake](/img/about-iota/iota-wallet/how-to/stake/current-stake.png) + +2. Select a validator where your funds are currently staked. + + ![Current Stake List](/img/about-iota/iota-wallet/how-to/stake/current-stake-list.png) + +3. View detailed information such as the amount staked, the number of epochs, and other relevant details. + + ![Current Stake Detail](/img/about-iota/iota-wallet/how-to/stake/current-stake-detail.png) + +## Withdraw Your Staked IOTA + +Withdraw your staked IOTA whenever you wish, whether to re-stake with another validator or use your tokens elsewhere. +Once you request a withdrawal, your staking rewards will stop, +and any earned rewards will be distributed at the end of the current epoch. + +1. Go to the `Home` tab and select `Current Stake`. + + ![Current Stake](/img/about-iota/iota-wallet/how-to/stake/current-stake.png) + +2. Choose the validator from which you want to withdraw. + + ![Current Stake List](/img/about-iota/iota-wallet/how-to/stake/current-stake-list.png) + +3. Click on the `Unstake` button. + + ![Unstake Button](/img/about-iota/iota-wallet/how-to/stake/unstake-button.png) + +4. Review the details and click `Unstake`. + + ![Unstake](/img/about-iota/iota-wallet/how-to/stake/unstake.png) diff --git a/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/gas-in-iota.mdx b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/gas-in-iota.mdx new file mode 100644 index 00000000000..026cf58ab32 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/gas-in-iota.mdx @@ -0,0 +1,83 @@ +--- +title: Gas in IOTA +description: An IOTA transaction must both pay for the computational cost of execution and pay a deposit for storing the objects a transaction creates or mutates. +--- + +import Quiz from '@site/src/components/Quiz'; +import {questions} from '@site/static/json/about-iota/tokenomics/gas-in-iota.json'; + +An IOTA transaction must both pay for the computational cost of execution and pay a deposit for storing the objects a transaction creates or mutates. Specifically, [IOTA Gas Pricing](gas-pricing.mdx) is such that any transaction pays the following gas fees: + +`total_gas_fees = computation_units * reference_gas_price + storage_units * storage_price` + +The storage component is 100% rebated upon deletion of the corresponding object from storage, and for this reason, the terms `storage fee` and `storage deposit` are used interchangeably. + +While computation fees and storage deposits are separate, they are conceptually similar in that they each translate computation or storage into IOTA terms by multiplying computation or storage units by the relevant price. + +Finally, storage rebates are provided whenever a transaction deletes previously stored objects. Hence, the net fees that a user pays equals gas fees minus the rebates associated with data deletion: + +`net_gas_fees = computation_fee + storage_deposit - storage_rebate` + +The information on net gas fees displays in the [IOTA network explorer](https://explorer.rebased.iota.org/) for each transaction block. + +## Gas prices + +The [reference gas price](./gas-pricing.mdx#computation-gas-prices) translates the real-time cost of executing a transaction into IOTA units and the validator set updates it at each epoch boundary. Similarly, the [storage price](./gas-pricing.mdx#storage-gas-prices) translates the long-term cost of storing data on chain into IOTA units and updates infrequently; often remaining constant for various consecutive epochs. During regular network operations, all IOTA users can expect to pay the reference gas price and storage price for computation and storage, respectively. + +## Gas units + +Gas units include both + +- [Computation units](#computation-units) +- [Storage units](#storage-units) + +### Computation units + +Different IOTA transactions require varying amounts of computational time for processing and execution. IOTA translates these varying operational loads into transaction fees by measuring each transaction in terms of computation units. In general, more complex transactions require more computation units. + +Importantly, though, IOTA computation gas schedule is built with a bucketing/step approach. Two reasonably similar transactions translate into the exact same amount of computation units if they are in the same bucket, whereas two relatively different transactions translate into different amounts of computation units if they fall in separate buckets. The smallest bucket maps into 1,000 computation units, meaning that all transactions that fall into the smallest bucket cost 1,000 computation units. The largest bucket maps into 5,000,000 computation units; if a transaction requires more computation units, it aborts. + +Buckets start at 1000 units and increment in steps up to 5,000,000, where the step value is set as a protocol parameter (currently the step is equal to 1000, effectively rounding up to the nearest 1000). + +Using bucketing accomplishes two important goals: + + - Frees users from optimizing their smart contracts to deliver marginal gains in gas costs via "gas golfing" — instead, they can focus on step-function improvements in their products and services. + - Gives users the freedom to adjust per-instruction gas costs and experiment with new gas metering schemes without creating significant development disruption. This can happen frequently, so it's important that they do not rely on per-instruction gas costs remaining stable over time. + +### Storage units + +Similarly, IOTA transactions vary depending on the amount of new data written into on-chain storage. The variable storage units capture these differences by mapping the amount of bytes held in storage into storage units. The current IOTA schedule is linear and maps each byte into 100 storage units. So, for example, a transaction that stores 25 bytes costs 2,500 storage units, while a transaction that stores 75 bytes costs 7,500 units. + +Importantly, in IOTA's storage model users pay storage deposit fees for storing data in perpetuity but can also get a full rebate on previously stored data, if that data is deleted. Hence, the amount of storage fees that users pay are 100% rebateable. This storage deposit mechanism incentivizes users to minimize the storage burden they place on all nodes by reducing their storage requirements and cleaning up unused objects. + +### Gas budgets + +Users must submit all transactions they need together with a gas budget. This provides a cap to the amount of gas fees paid, especially because sometimes it might be hard to perfectly forecast how much a transaction costs before the user submits it to the IOTA network. + +The gas budget for an IOTA transaction is defined in IOTA units and transactions are successfully executed if: + +`gas_budget >= max{computation_fees,net_gas_fees}` + +If the gas budget does not fulfill this condition, then the transaction fails and a portion of the gas budget is charged. In cases where the `gas_budget` is insufficient for covering `computation_fees`, then the entirety of the `gas_budget` is charged. In cases where `gas_budget` is sufficient for covering `computation_fees` but not the `net_gas_fees`, then a portion of the `gas_budget` corresponding to `computation_fees` and the fees associated with mutating the transaction's input objects are charged. + +Ultimately, a successful transaction requires the end user to pay the transaction's `net_gas_fees`. However, since it is challenging to perfectly forecast computation time before the transaction is processed, the `gas_budget` condition also requires the `gas_budget` to be at least as large as the transaction's `computation_fees` in case the transaction aborts. In some cases -- especially in the presence of high storage rebates, and, thus negative net storage fees -- the gas budget might be higher than the total gas fees the user pays. + +Importantly, the minimum gas budget is 1000 NANOS (.000001 IOTA). This protects the IOTA network from being spammed with a large number of transactions with minimal gas budgets. The maximum gas budget is 50 billion NANOS or 50 IOTA. This protects the network against overflow of internal multiplications and prevents excessively large gas budgets being used for denial of service attacks. + +As mentioned previously, the storage rebate is 100% of the originally paid storage fees. Because the gas budget applies to the totality of gas fees, it is often the case that a transaction only goes through if the gas budget is considerably higher than the net gas fees that a user ultimately pays. + +### Gas budget examples + +The following table provides some examples of gas accounting on the IOTA network. Within the first two and last two rows, computation units are the same because transactions fall within the same bucket. However, the last two transactions are more complex than the first two and thus fall in a higher bucket. Finally, in the last transaction the storage rebate is large enough to fully offset the transaction gas fees and actually pays the user back a positive amount of IOTA. + +These examples showcase the importance of the gas budget. The minimum gas budget is the smallest amount a transaction can specify to successfully execute. Importantly, when there is a storage rebate, the minimum gas budget is larger than the amount of net gas fees a user ultimately pays — this is especially stark in the last example where the user receives a positive amount back for executing the transaction. This is because the minimum gas budget must be higher than a transaction's computation fees. + +| | Reference Gas Price | Computation Units | Storage Price | Storage Units | Storage Rebate | Minimum Gas Budget | Net Gas Fees | +| ------------------------------------------------------- | ------------------- | ----------------- | ------------- | ------------- | -------------- | ------------------ | -------------- | +| Simple transaction storing 10 bytes | 1,000 NANOS | 1,000 | 75 NANOS | 1,000 | 0 NANOS | 1,075,000 NANOS | 1,075,000 NANOS | +| Simple transaction storing 10 bytes and deleting data | 500 NANOS | 1,000 | 75 NANOS | 1,000 | 100,000 NANOS | 500,000 NANOS | 475,000 NANOS | +| Complex transaction storing 120 bytes | 1,000 NANOS | 5,000 | 200 NANOS | 12,000 | 0 NANOS | 7,400,000 NANOS | 7,400,000 NANOS | +| Complex transaction storing 120 bytes and deleting data | 500 NANOS | 5,000 | 200 NANOS | 12,000 | 5,000,000 NANOS | 2,500,000 NANOS | -100,000 NANOS | + +## Quizzes + diff --git a/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/gas-pricing.mdx b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/gas-pricing.mdx new file mode 100644 index 00000000000..581fd825c0e --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/gas-pricing.mdx @@ -0,0 +1,53 @@ +--- +title: IOTA Gas Pricing +--- + +import Quiz from '@site/src/components/Quiz'; +import {questions} from '@site/static/json/about-iota/tokenomics/gas-pricing.json'; + +The IOTA gas-pricing mechanism achieves three outcomes: delivering low, predictable transaction fees, incentivizing validators to optimize their transaction processing operations, and preventing denial of service attacks. + +This enables you to focus on using the IOTA network to provide the best user experience without needing to forecast the current market price of gas fees. Since validators agree on a network-wide reference price at the start of each epoch, you can use the reference price as a credible anchor when submitting transactions. Moreover, the price setting mechanism rewards good validator behavior, thus aligning incentives between IOTA token holders, the network's operators (validators), and its users. + +A unique feature of the IOTA gas price mechanism is that users pay separate fees for transaction execution and for storing the data associated with each transaction. The gas fees associated with an arbitrary transaction $\tau$ equal: + +$$ +GasFees[\tau] \ = \ ComputationUnits[\tau] \times ComputationPrice[\tau] \ + \ StorageUnits[\tau] \times StoragePrice +$$ + +The gas functions $ComputationUnits[\tau]$ and $StorageUnits[\tau]$ measure the amount of computation and storage resources, respectively, required to process and store the data associated with $\tau$. The gas prices $ComputationPrice[\tau]$ and $StoragePrice$ translate the cost of computation and storage, respectively, into IOTA units. The decoupling between gas units and gas prices is useful since IOTA market price will fluctuate over time in accordance with supply and demand. + +## Computation gas prices + +The computation gas price $ComputationPrice[\tau]$ captures the cost of one unit of computation in IOTA units. This price is set at the transaction level and submitted by the user as the transaction's gas price. Conceptually, it is useful to think about this gas price in two parts: + +$$ +ComputationPrice[\tau] \ = \ ReferencePrice \ + \ Tip[\tau] +$$ + +On the IOTA network, a single $ReferencePrice$ exists throughout each epoch, with IOTA validators updating the $ReferencePrice$ at each epoch boundary. Hence, in practice, when a user submits a gas price above the $ReferencePrice$, it is useful to think of the difference as a tip paid to the network in order to get higher priority. During moments of regular network operations, users are not expected to pay tips and the vast majority of transactions have gas prices equal to $ReferencePrice$. + +More generally, the IOTA gas price mechanism makes the $ReferencePrice$ a credible anchor for you to reference when submitting transactions to the network. Providing reasonable confidence that transactions submitted with gas prices at or close to the reference price are executed in a timely manner. This is achieved through three core steps: + +- **Gas price survey:** All validators are surveyed at the start of each epoch, and every validator submits their reservation price. That is, each validator states the minimum gas price at which they are willing to process transactions. The protocol orders these quotes and chooses the 2/3 percentile by stake as the reference price. The gas price survey goal is to set a reference price under which a [quorum](../../operator/validator-committee.mdx#quorums) of validators are willing to promptly process transactions. +- **Tallying rule:** Throughout the epoch, validators obtain signals over the operations of other validators. Each validator uses these signals to build a (subjective) evaluation over the performance of every other validator. Specifically, each validator constructs a multiplier for the stake rewards of every other validator such that validators who behave well receive boosted rewards, and validators who do not receive reduced rewards. The tallying rule goal is to create a community-enforced mechanism for encouraging validators to honor the reference gas price. +- **Incentivized stake reward distribution rule:** At the end of the epoch, the distribution of stake rewards across validators is adjusted using information from the tallying rule. Specifically, a global multiplier is built for every validator using the median value (weighted by stake) out of the set of individual multipliers constructed during the tallying rule. All else equal, validators that operated performantly receive their regular stake rewards, whereas validators who did not operate performantly at the reference gas price receive slashed rewards. Since stake rewards are influenced by the amount of stake each validator owns, validators are encouraged to obtain more stake by lowering gas fees and pricing out inefficient validators. This benefits IOTA end users since the stake reward distribution rule incentivizes validators to deliver a more cost-efficient network. + +In sum, the gas price mechanism has two main forces: the tallying rule incentivizes validators to honor the quotes submitted during the gas survey, while the distribution rule incentivizes validators to submit low reservations prices. The interaction of these two forces delivers a mechanism encouraging validators to set a low network-level reference gas price - but not too low, because they face penalties if they cannot honor their quotes. In other words, the gas price mechanism encourages a healthy competition for fair prices. + +## Storage gas prices + +The storage gas price $StoragePrice$ captures the costs of covering one unit of storage in perpetuity, in IOTA units. This price is set through governance proposals and is updated infrequently. The goal is to ensure IOTA users pay for their use of on-chain data storage by storage deposits. In contrast to the computation gas price, storage prices are fixed and common for all transactions both within an epoch and across epochs until the storage price is updated. + +The $StoragePrice$ is set exogenously through the governance proposal with the goal of targeting the off-chain dollar cost of data storage. In the long run, as the costs of storage fall due to technological improvements and the dollar price of the IOTA token evolves, governance proposals will update the price in order to reflect the new dollar target price. + +## Gas prices as a coordination mechanism + +Overall, when you submit transactions with computation gas prices at or close to the current epoch $ReferencePrice$ and storage gas prices at the targeted $StoragePrice$, you have the best user experience. The IOTA gas price mechanism provides you with credible reference prices for submitting your transactions. By incentivizing validators to elicit their true reservation prices and honor these quotes, you can credibly assume your transactions are processed in a timely manner. + +After IOTA enables horizontal scaling, validators can add more workers as demand for on-chain activity scales. This increases their costs linearly at the same pace of network activity and lets them process more transactions at the same low gas prices. In cases of extreme network congestion where validators cannot scale fast enough, the tip presence provides a market-based congestion pricing mechanism that discourages further demand spikes by increasing the cost of transacting on the IOTA platform. + +In the long run, the IOTA gas price mechanism creates incentives for validators to optimize their hardware and operations. Validators that invest in becoming more efficient are able to honor lower gas prices and obtain a stake reward boost. IOTA validators are thus encouraged to innovate and improve the experience of end users. + +## Quizzes + \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/iota-token.mdx b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/iota-token.mdx new file mode 100644 index 00000000000..b0789349d07 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/iota-token.mdx @@ -0,0 +1,32 @@ +--- +title: IOTA Token +description: The native asset on IOTA is called IOTA. +--- + +import Quiz from '@site/src/components/Quiz'; +import {questions} from '@site/static/json/about-iota/tokenomics/iota-token.json'; + +The native asset on IOTA is called IOTA. + +At the launch of IOTA Rebased, **4,600,000,000** IOTA tokens were migrated from the previous network called Stardust. +There is no maximum supply of IOTA - the total supply will fluctuate over time according to the combination of a given inflation rate and the burning of fees. + +:::info Decimals + +The amount of decimals for the IOTA token has changed from **6** to **9** with this release, any balance from the Stardust network has been migrated and multiplied by 1000 to accomodate. + +::: + +The IOTA token serves four purposes on the IOTA network: + +- You can stake IOTA to participate in the proof-of-stake mechanism. +- IOTA is the asset denomination needed to pay the gas fees required to execute and store transactions or other operations on the IOTA network. +- You can use IOTA as a versatile and liquid asset for various applications, including the standard features of money - a unit of account, a medium of exchange, or a store of value - and more complex functionality smart contracts enable, interoperability, and composability across the IOTA ecosystem. +- IOTA tokens play an important role in governance by acting as a right to participate in on-chain voting on issues such as protocol upgrades. + +The tokenomics must support all economic activities to scale as more and more people migrate to the IOTA platform. In addition, the presence of storage deposits creates important monetary dynamics, reducing the amount of IOTA in circulation. + +All original IOTA Tokens are represented as a `0x2::iota::IOTA` type of object on IOTA Rebased, accessible on the same (Hex format) addresses from the Stardust based network. No manual migration is needed to access these tokens. + +## Quizzes + diff --git a/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/proof-of-stake.mdx b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/proof-of-stake.mdx new file mode 100644 index 00000000000..95feeecd22d --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/proof-of-stake.mdx @@ -0,0 +1,68 @@ +--- +title: Proof of Stake +--- + +import Quiz from '@site/src/components/Quiz'; +import {questions} from '@site/static/json/about-iota/tokenomics/proof-of-stake.json'; + +The IOTA platform relies on delegated proof-of-stake (DPoS) to determine the set of validators that process transactions. + +## IOTA token staking + +Within each epoch, a fixed set of validators process operations, each with a specific amount of stake from IOTA token holders. +A validator's share of total stake is relevant in that it determines each validator's share of voting power for processing transactions. +Staking IOTA implies the IOTA tokens are locked for the entire epoch. +IOTA token holders are free to withdraw their IOTA or to change their selected validator when the epoch changes. + +## 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. +The IOTA economic model works as follows. + +At the beginning of each epoch, two important events happen: + +- The delegated tokens for a given validator are added up and a new [committee](../../operator/validator-committee.mdx) is formed. +- The reference gas price, set as described in [IOTA Gas Pricing](./gas-pricing.mdx), is updated. + +Following these actions, the protocol computes the total amount of stake as the sum of staked IOTA. + +During each epoch: Users submit transactions to the IOTA platform and validators process them. +For each transaction, users pay the associated computation and storage deposits. +In cases where users delete previous objects or data within objects, users obtain a rebate of their storage deposit. +Validators observe the behavior of other validators and evaluate each other's performance. + +At the end of each epoch: The protocol distributes stake rewards to participants of the DPoS mechanism. +This occurs through three main steps: + +- The total amount of stake rewards is calculated. Currently, the stake rewards per epoch is set as 767000 IOTAs per epoch. +- The total amount of stake rewards is distributed across various pools, proportionally to their stake and accordingly to the tallying rule. +- Each pool's amount of rewards is distributed between the validator and the other parties. Validators first keep a commission $\delta_v$ of the total pool rewards as a fee to cover their costs. The rest of the rewards (i.e., after discounting the validator's commission) is distributed among all users proportionally to their stake (including to the validator). + +Finally, let $\beta_v$ represent the share of stake managed by a validator $v$ that is owned by itself while $(1-\beta_v)$ represents the share owned by third-party stakers. +The rewards for users of validator's $v$ staking pool staking and for the validator $v$ itself equal: + +$$ +UserStakeRewards_v \ = (1-\delta_v)(1-\beta_v)\mu_v\sigma_v \times TotalStakeRewards +$$ + +$$ +ValidatorRewards_v \ = \ \Big(\beta_v+\delta_v(1-\beta_v)\Big)\mu_v\sigma_v \times TotalStakeRewards +$$ + +The $\mu_v$ variable captures the output of the [tallying rule](./gas-pricing.mdx#computation-gas-prices) computed as part of the [gas price mechanism](./gas-pricing.mdx) and corresponds to $\mu_v\geq1$ for performant validators and $\mu_v<1$ for non-performant validators. +This variable ensures that validators have "skin in the game" and are incentivized to operate IOTA efficiently. +The $\sigma_v$ parameter captures each pool's share of total stake. + +Consequently, validators with more stake earn more stake rewards and the joint $\mu_v\sigma_v$ term incentivizes validators to increase their share of stake while also operating the network performantly. +In the long-run, this incentive encourages users to shift the stake distribution towards the network's most efficient validators, delivering a cost-efficient and decentralized network. + +On net, this design encourages validators to operate with low gas price quotes, but not too low or they receive slashed stake rewards. +Consequently, the IOTA gas price mechanism and DPoS system encourages a healthy competition for fair prices where validators set low gas fees while operating with viable business models. + +## IOTA incentives + +The IOTA economic model bestows IOTA users with an important monitoring role. On the one hand, users want their transactions processed as quickly and efficiently as possible. User clients, such as wallets, encourage this by prioritizing communication with the most responsive validators. Such efficient operations are compensated with boosted rewards relative to less responsive validators. On the other hand, IOTA token stakers receive the same boosted or penalized rewards as their selected validator. An unresponsive validator is thus doubly exposed to IOTA incentives: they lose directly through slashed rewards and indirectly through reduced user stake in future epochs as stakers move their tokens to more responsive validators. + +## Quizzes + \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/staking-unstaking.mdx b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/staking-unstaking.mdx new file mode 100644 index 00000000000..d166bc119c4 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/staking-unstaking.mdx @@ -0,0 +1,31 @@ +--- +title: Staking and Unstaking +description: Staking and unstaking IOTA with validators earns a percentage of rewards they receive from gas fees. +--- + +import Quiz from '@site/src/components/Quiz'; +import {questions} from '@site/static/json/about-iota/tokenomics/staking-unstaking.json'; + +IOTA uses a Delegated-Proof-of-Stake (DPoS) system to secure and operate the network, meaning that the voting power of a validator in the network is determined by the amount of stake delegated to them by IOTA token holders. The more stake delegated to a validator, the more voting power they have. In exchange for processing transactions and performing consensus, validators earn rewards based on a given IOTA inflation rate. These rewards are then shared among stakers as staking rewards. + +## Staking + +You stake your IOTA tokens by sending a transaction to the network that calls the staking function implemented as part of the system Move package. This transaction wraps the IOTA tokens in a self-custodial stake object. This stake object contains information including the validator staking pool ID and the activation epoch of the stake. + +IOTA-compatible crypto wallets typically have functionality to initiate staking and unstaking from your IOTA address. See the respective documentation for these tools to begin staking your IOTA. + +## Unstaking + +Similar to staking, a user withdraws stake from a validator by sending a transaction that calls the unstaking function in the system Move package. This transaction unwraps the stake object, and sends both the principal and the accumulated rewards to the user as IOTA tokens. You accrue rewards only during epochs where the stake is active for the entire epoch. The rewards withdrawn from the validator's rewards pool are calculated based on the activation epoch and unstaking epoch of the stake. + +## Choosing a validator for staking + +When you stake on IOTA, you have to choose a specific validator you would like to stake with. The choice of validator can potentially impact the amount of staking rewards you receive. The factors determining this amount include, but are not limited to: + +- Validator commission rate: a validator can choose to set a non-zero commission rate specifying the percentage of staking rewards they are taking from the stakers. For example, if a validator has a commission rate of 10%, then 10% of every staker's staking rewards is given to the validator. Understand that a validator can choose its commission at a future moment in time without prior notice. +- Validator performance: a validator with bad performance might be punished according to the [tallying rule](./gas-pricing.mdx#computation-gas-prices). Punished validators receive only a fraction of staking rewards for the epoch during which they are punished, and you also will receive a fraction of that epoch's rewards when you withdraw your stake from that validator. + +IOTA-compatible crypto wallets and explorers typically provide validator information such as commission and APY. See the respective documentation for these tools for information on how to retrieve this data. + +## Quizzes + \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/tokenomics.mdx b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/tokenomics.mdx new file mode 100644 index 00000000000..9a6305afcb4 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/tokenomics.mdx @@ -0,0 +1,44 @@ +--- +title: IOTA Tokenomics +--- +import Quiz from '@site/src/components/Quiz'; +import {questions} from '@site/static/json/about-iota/tokenomics/tokenomics.json'; +import ThemedImage from '@theme/ThemedImage'; + +The collective ideation that the term tokenomics encompasses includes a wide range of concepts that define the science and behavior of blockchain economies. In basic terms, tokenomics are the financial foundation of blockchains. Much the same way a building with a poor foundation is doomed to fail, a blockchain without a well-researched, extensively planned, and painstakingly implemented token economy eventually crumbles. + +IOTA tokenomics are based on sound financial concepts informed by extensive blockchain research. Designed for scale, the IOTA tokenomics structure is designed to support the financial needs of web3 now and into the future. + +## The IOTA Economy + +Three main types of participants characterize the IOTA economy: + +- **Users** submit transactions to the IOTA platform to create, mutate, and transfer digital assets or interact with more sophisticated applications enabled by smart contracts, interoperability, and composability. +- **IOTA token holders** have the option of staking their tokens to validators and participating in the proof-of-stake mechanism. IOTA owners also hold the rights to participate in IOTA governance. +- **Validators** manage transaction processing and execution on the IOTA platform. + + +## Core components + +The IOTA economy is composed of four core components: + +- **[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, consisting of a computation fees which are burnt and a fully rebated storage deposits. +- **[Staking rewards](proof-of-stake.mdx):** Staking rewards are provided to users participating in the delegated proof-of-stake mechanism, namely delegators and validators. This incentivizes honest behavior by IOTA Validators and the IOTA token holder that delegate to them. +- **Voting:** On-chain voting is used for governance and protocol upgrades. + + +## Tokenomics Visualized + +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. + + + +## Quizzes + \ No newline at end of file diff --git a/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/validators-staking.mdx b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/validators-staking.mdx new file mode 100644 index 00000000000..ceb4640e92d --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/tokenomics/validators-staking.mdx @@ -0,0 +1,29 @@ +--- +title: Validators and Staking Pools +--- + +import StakingPoolReqs from "../../_snippets/staking-pool-reqs.mdx"; +import Quiz from '@site/src/components/Quiz'; +import {questions} from '@site/static/json/about-iota/tokenomics/validators-staking.json'; + +Each IOTA validator maintains its own staking pool to track the amount of stake and to compound staking rewards. Validator pools operate together with a time series of exchange rates that are computed at each epoch boundary. These exchange rates determine the amount of IOTA tokens that each past IOTA staker can withdraw in the future. Importantly, the exchange rates increase as more rewards are deposited into a staking pool and the longer an amount of IOTA is deposited in a staking pool, the more rewards it will accrue. + +When IOTA is deposited to the staking pool in epoch `E`, those IOTA are converted into staked tokens at the epoch `E` exchange rate. As the staking pool earns rewards, the exchange rate appreciates. At epoch `E'`, those staked tokens are worth more and translate into more IOTA. +A global exchange rate table is used to track the accounting. Because all IOTA tokens in the staking pool are treated the same, regardless of whether they were originally deposited as new stake or as stake rewards, all IOTA tokens immediately count as stake and thus compound rewards immediately. + +The staking pool is implemented in a system-level smart contract ([staking_pool.move](https://github.com/iotaledger/iota/blob/develop/crates/iota-framework/packages/iota-system/sources/staking_pool.move)) and is part of the IOTA framework. + +## Validator Pool Rewards + +At each epoch boundary, the system computes the staking rewards for each validator pool proportionally to the staked tokens in each pool. The staking rewards $rewards(i, E)$ for validator pool $i$ at epoch $E$ are computed as follows: + +$$ +rewards(i, E) = \frac{ stakedTokens(i, E)}{\sum_i (stakedTokens(i, E)) }\cdot totalRewards(E). +$$ + +$rewards(i, E)$ is then adjusted to consider potential slashed validators who have not met minimum quality requirements. Additionally, validators earn commissions on the staking pool's tokens. IOTA keeps track of the rewards accrued by both validators and delegators using a single global exchange rate table. + + + +## Quizzes + diff --git a/docs/site/versioned_docs/version-devnet/about-iota/why-move.mdx b/docs/site/versioned_docs/version-devnet/about-iota/why-move.mdx new file mode 100644 index 00000000000..9b675a6f2b5 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/about-iota/why-move.mdx @@ -0,0 +1,31 @@ +--- +title: Why Move? +--- + +While EVM/Solidity is the most famous smart contracts platform, it has some downsides that IOTA Move aims to address: + + - **Performance, scaling, and cost**: EVM builds on top of a global shared state, which is practical but doesn't scale well. This results in limitations in throughput, which is directly reflected in the fees you must pay to interact with these networks. The more congested the network, the more expensive it gets. This is worked around with additional extra execution layers (L2s on top of L1s) or rollup solutions, which also have downsides and limitations. + - **Security:** As the first well-used smart contract language, Solidity did not have much to go by in terms of learnings around secure practices (there was no existing ecosystem yet), and it had to develop over the years with that legacy and backward compatibility in mind. Many of the issues from the past have been mitigated with workarounds. Still, given the nature of things, there are some limitations and annoyances we currently can't get around, like the security issues it has with both the code and infamous design patterns like the `approve()` method in the ERC standards. + - **Tokens:** Assets like ERC20 tokens and ERC721/1155 NFTs are not part of the EVM and are purely standards for smart contracts deployed on an EVM chain interpreted as tokens by clients. While this works and allows much flexibility, it also has its downsides. Due to the nature of tokens being contracts and the state of your balance being stored with those contracts, it's not trivial to find all tokens in your account without knowing all token contract addresses and manually adding them, unlike the Ethereum balance itself, which is a different kind of token which can be found directly but works differently over an ERC20 token. This makes discovering your assets difficult and adds additional complexity to applications to close the gap between the native asset (ETH) and ERC20 tokens with workarounds like wrapped tokens, which is not ideal. + - **Developer experience:** Solidity offers a wealth of developer tools and resources, including various libraries and frameworks to choose from, as well as extensive documentation and tutorials. The language, influenced by popular languages like C++ and JavaScript, is easy to learn and get started with. However, Solidity's lack of strictness allows for mistakes that the compiler may not catch, leading to bugs and security issues that are difficult to identify and resolve. Consequently, the developer experience suffers, and the language itself is not as safe to work with as it could be. + +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 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. + + +To sum this up: +IOTA offers both EVM and Move, so you can choose the best tool for the job. +If you want to build something that needs to be secure, scalable, and cost-effective, IOTA Move is definitely the way to go. However, if you want a fast shortcut to get started with IOTA smart contracts, or you want to migrate an existing EVM project to IOTA, EVM/Solidity is a good choice. + +| EVM/Solidity | Move | +| ------------------------------------------ | ------------------------------------------------------ | +| State as part of contracts | State as objects | +| Global shared state | Owned and Shared objects | +| Transactions executed one by one | Parallel execution | +| No enforced security for standards | Strict type system for standards, assurances | +| Easy to get started with, hard to do right | Harder to get started with, but less room for mistakes | + diff --git a/docs/site/versioned_docs/version-devnet/developer/advanced.mdx b/docs/site/versioned_docs/version-devnet/developer/advanced.mdx new file mode 100644 index 00000000000..ff2220fe649 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/developer/advanced.mdx @@ -0,0 +1,25 @@ +--- +title: Advanced Topics +--- + +import MigrateToGraphql from "../_snippets/migrate-to-graphql.mdx"; + +Information in the Advanced Topics section covers coding practices, useful features, and other developer-focused considerations that might arise as you continue your development journey on IOTA. The topics in this section aren't necessarily more difficult than other topics, but they include subjects you might not encounter or need to consider until you're developing more advanced solutions on the IOTA network. + +## Asset Tokenization + +Asset tokenization refers to the process of representing real-world assets, such as real estate, art, commodities, stocks, or other valuable assets, as digital tokens on the blockchain network. This involves converting the ownership or rights of an asset into digital tokens, which are then recorded and managed on the blockchain. + +Go to [Asset Tokenization](advanced/asset-tokenization.mdx). + +[//]: # () +[//]: # (## Migrating to GraphQL ) + +[//]: # () +[//]: # (See the Migrating to GraphQL guide to upgrade your smart contracts to use the GraphQL API.) + +[//]: # () +[//]: # () + +[//]: # () +[//]: # (Go to [Migrating to GraphQL](advanced/graphql-migration.mdx).) diff --git a/docs/site/versioned_docs/version-devnet/developer/advanced/asset-tokenization.mdx b/docs/site/versioned_docs/version-devnet/developer/advanced/asset-tokenization.mdx new file mode 100644 index 00000000000..bc897ad67f9 --- /dev/null +++ b/docs/site/versioned_docs/version-devnet/developer/advanced/asset-tokenization.mdx @@ -0,0 +1,1096 @@ +--- +title: Asset Tokenization +description: Learn how to tokenize assets on the IOTA blockchain. Asset tokenization refers to the process of representing real-world assets, such as real estate, art, commodities, stocks, or other valuable assets, as digital tokens on the blockchain network. +--- +import InitClient from '../../_snippets/initialize-iota-client-cli.mdx'; + +import Quiz from '@site/src/components/Quiz'; +import questions from '/json/developer/advanced-topics/asset-tokenization.json'; + +Asset tokenization refers to the process of representing real-world assets, such as real estate, art, commodities, stocks, or other valuable assets, as digital tokens on the blockchain network. This involves converting the ownership or rights of an asset into digital tokens, which are then recorded and managed on the blockchain. + +## High-level Overview + +The concept is to divide high-value assets into smaller, more affordable units, representing ownership or a fraction of the asset. + +This strategy enables wider participation from investors who might want to mitigate risk by investing in a portion of a digital asset rather than being the sole owner, thereby expanding accessibility to a broader range of investors. + +This pattern is similar to the [ERC1155](https://eips.ethereum.org/EIPS/eip-1155) multi-token standard with additional functionality. This makes it a suitable choice for Solidity based use cases that one might want to implement on IOTA. + +- **Asset creation** + + Each asset is fractionalized into a total supply, with each fraction represented as either a non-fungible token (NFT) or fungible token (FT) type collectible. This ensures that each individual fraction maintains a balance equal to or greater than one, and when combined, all fractions collectively reach the total supply of the asset. + + Besides the total supply, each asset is defined by various other fields such as name, description, and more. These fields collectively form the metadata for the asset, and they remain consistent across all fractions of the asset. + +- **NFTs vs FTs distinction** + + Each time a tokenized asset is minted, there's a possibility for it to be created with new metadata. If new metadata is incorporated, the tokenized asset is deemed unique, transforming it into an NFT. In this case, its balance is limited to one, signifying that only a single instance of this asset exists. + + If there's no additional metadata, the tokenized asset is categorized as an FT, allowing its balance to exceed one, enabling multiple identical instances of the asset to exist. + + FTs possess the capability to merge (join) among themselves or be split when the balance is greater than one. This functionality allows for the aggregation or division of units of the token, offering flexibility in handling varying quantities as needed. + + As previously mentioned, all the collectibles of tokenized assets, whether NFTs or FTs, when combined, can amount to the maximum total supply of the asset. + +- **Burnability** + + When you create the asset, you can define whether the fractions of the asset are eligible for removal or destruction from circulation. The process of removing or destroying assets is called burning. + + If a tokenized asset is burnable, then burning a fraction causes the circulating supply to decrease by the balance of the burnt item. The total supply, however, remains constant, allowing you to mint the burned fractions again if needed, thus maintaining the predetermined total supply of the asset. + +## Move Packages + +As with all smart contracts on IOTA, Move provides the logic that powers asset tokenization. + +### `asset_tokenization` Package + +:::info + +This reference implementation uses the [Kiosk standard](../standards/kiosk.mdx) to ensure that tokenized assets operate within their defined policy. Use the implementation as presented to have marketable tokenized assets that support rules like royalties, commissions, and so on. + +If using Kiosk is not a requirement, then you can exclude the unlock module and some of the proxy's methods related to transfer policies. + +::: + +Select a module to view its details: + + + + + +The `tokenized_asset` module operates in a manner similar to the `coin` library. + +When it receives a new [one-time witness](../iota-101/move-overview/one-time-witness.mdx) type, it creates a unique representation of a fractional asset. This module employs similar implementations to some methods found in the `Coin` module. It encompasses functionalities pertinent to asset tokenization, including new asset creation, minting, splitting, joining, and burning. + +**Structs** + +- `AssetCap` + + Generate an `AssetCap` for each new asset represented as a fractional NFT. In most scenarios, you should create it as an owned object, which you can then transfer to the platform's administrator for access-restricted method invocation. + + ```rust + struct AssetCap { + id: UID, + // the current supply in circulation + supply: Supply, + // the total max supply allowed to exist at any time + total_supply: u64, + // Determines if the asset can be burned or not + burnable: bool + } + ``` + +- `AssetMetadata` + + The `AssetMetadata` struct defines the metadata representing the entire asset to fractionalize. This should be a shared object. + + ```rust + struct AssetMetadata has key, store { + id: UID, + /// Name of the asset + name: String, + // the total max supply allowed to exist at any time + total_supply: u64, + /// Symbol for the asset + symbol: ascii::String, + /// Description of the asset + description: String, + /// URL for the asset logo + icon_url: Option + } + ``` + +- `TokenizedAsset` + + The `TokenizedAsset` is minted with a specified balance that is less than or equal to the remaining supply. If the `VecMap` of an asset is populated with values, indicating multiple unique entries, it is considered an NFT. Conversely, if the `VecMap` of an asset is not populated, indicating an absence of individual entries, it is considered an FT. + + ```rust + struct TokenizedAsset has key, store { + id: UID, + /// The balance of the tokenized asset + balance: Balance, + /// If the VecMap is populated, it is considered an NFT, else the asset is considered an FT. + metadata: VecMap, + /// URL for the asset image (optional) + image_url: Option, + } + ``` + +- `PlatformCap` + + The `PlatformCap` refers to the capability issued to the individual who deploys the contract. This capability grants specific permissions or authority related to the platform's functionalities, allowing the deployer certain controlled actions or access rights within the deployed contract. + + ```rust + /// Capability that is issued to the one deploying the contract + struct PlatformCap has key, store { id: UID } + ``` + +**Functions** + +- `init` + + This function creates a `PlatformCap` and sends it to the sender. + + ```rust + fun init(ctx: &mut TxContext) {} + ``` + +- `new_asset` + + This function holds the responsibility of creating a fresh representation of an asset, defining its crucial attributes. Upon execution, it returns two distinct objects: the `AssetCap` and `AssetMetadata`. These objects encapsulate the necessary information and characteristics defining the asset within the system. + + ```rust + public fun new_asset( + witness: T, + total_supply: u64, + symbol: ascii::String, + name: String, + description: String, + icon_url: Option, + burnable: bool, + ctx: &mut TxContext + ): (AssetCap, AssetMetadata) {} + ``` + +- `mint` + + The function performs the minting of a tokenized asset. If new metadata is introduced during this process, the resulting tokenized asset is considered unique, resulting in the creation of an NFT with a balance set to 1. Alternatively, if no new metadata is added, the tokenized asset is classified as an FT, permitting its balance to surpass 1, as specified by a provided argument. Upon execution, the function returns the tokenized asset object. + + ```rust + public fun mint( + cap: &mut AssetCap, + keys: vector, + values: vector, + value: u64, + ctx: &mut TxContext + ): TokenizedAsset {} + ``` + +- `split` + + This function is provided with a tokenized asset of the FT type and a balance greater than 1, along with a value less than the object's balance, and performs a split operation on the tokenized asset. The operation divides the existing tokenized asset into two separate tokenized assets. The newly created tokenized asset has a balance equal to the given value, while the balance of the provided object is reduced by the specified value. Upon completion, the function returns the newly created tokenized asset. This function does not accept or operate on tokenized assets of the NFT type. + + ```rust + public fun split( + self: &mut TokenizedAsset, + split_amount: u64, + ctx: &mut TxContext + ): TokenizedAsset {} + ``` + +- `join` + + This function is given two tokenized assets of the FT type and executes a merge operation on the tokenized assets. The operation involves increasing the balance of the first tokenized asset by the balance of the second one. Subsequently, the second tokenized asset is burned or removed from circulation. After the process concludes, the function returns the ID of the burned tokenized asset. + + This function does not accept or operate on tokenized assets of the NFT type. + + ```rust + public fun join( + self: &mut TokenizedAsset, + other: TokenizedAsset + ): ID {} + ``` + +- `burn` + + This function requires the `assetCap` as a parameter, thereby restricting its invocation solely to the platform admin. Additionally, it accepts a tokenized asset that is burned as part of its operation. Upon burning the provided tokenized asset, the circulating supply decreases by the balance of the burnt item. It necessitates a tokenized asset that is burnable. + + ```rust + public fun burn( + cap: &mut AssetCap, + tokenized_asset: TokenizedAsset + ) + ``` + +- `total_supply` + + This function retrieves and returns the value representing the total supply of the asset. + + ```rust + public fun total_supply(cap: &AssetCap): u64 {} + ``` + +- `supply` + + This function retrieves and returns the value representing the current circulating supply of the asset. + + ```rust + public fun supply(cap: &AssetCap): u64 {} + ``` + +- `value` + + This function takes a tokenized asset as input and retrieves its associated balance value. + + ```rust + public fun value(tokenized_asset: &TokenizedAsset): u64 {} + ``` + +- `create_vec_map_from_arrays` + + This internal helper function populates a `VecMap`. It assists in the process of filling or setting key-value pairs within the `VecMap` data structure. + + ```rust + fun create_vec_map_from_arrays( + keys: vector, + values: vector + ): VecMap {} + ``` + + - `tokenized_asset` full example + ```move file=/examples/move/asset_tokenization/asset_tokenization/sources/tokenized_asset.move + ``` + + + + + +The `proxy` module comprises methods that the type owner utilizes to execute publisher-related operations. + +**Structs** + +- `Proxy` + + The `PROXY` struct represents the one-time witness (OTW) to claim the publisher. + + ```rust + struct PROXY has drop {} + ``` + +- `Registry` + + This shared object serves as a repository for the `Publisher` object, specifically intended to control and restrict access to the creation and management of transfer policies for tokenized assets. Mutable access to this object is exclusively granted to the actual publisher. + + ```rust + struct Registry has key { + id: UID, + publisher: Publisher + } + ``` + +- `ProtectedTP` + + This is a shared object that stores an empty transfer policy. It is required to create one per type `` generated by a user. Its involvement is apparent in the unlock module. + + ```rust + struct ProtectedTP has key, store { + id: UID, + policy_cap: TransferPolicyCap, + transfer_policy: TransferPolicy + } + ``` + +**Functions** + +- `init` + + This function is responsible for creating the `Publisher` object, encapsulating it within the registry, and subsequently sharing the `Registry` object. + + ```rust + fun init(otw: PROXY, ctx: &mut TxContext) {} + ``` + +- `setup_tp` + + This function leverages the publisher nested within the registry and the sender's publisher. It generates and returns a transfer policy and the associated transfer policy cap specific to the `TokenizedAsset`. This type 'T' is derived from the `Publisher` object. + + It also generates an empty transfer policy wrapped in a `ProtectedTP` object, which is shared. You can use this functionality under specific conditions to override the kiosk lock rule. + + ```rust + public fun setup_tp( + registry: &Registry, + publisher: &Publisher, + ctx: &mut TxContext + ): (TransferPolicy>, + TransferPolicyCap>) {} + ``` + +- `new_display` + + This function utilizes the publisher nested within the registry and the sender's publisher to generate and return an empty `Display` for the type `TokenizedAsset`, where `T` is encapsulated within the `Publisher` object. + + ```rust + public fun new_display( + registry: &Registry, + publisher: &Publisher, + ctx: &mut TxContext + ): Display> {} + ``` + +- `transfer_policy` + + This function, provided with the `protectedTP`, returns the transfer policy specifically designed for the type `TokenizedAsset` + + ```rust + public(friend) fun transfer_policy( + protected_tp: &ProtectedTP + ): &TransferPolicy {} + + ``` + +- `publisher_mut` + + This function can only be accessed by the owner of the platform cap. It requires the registry as an argument to obtain a mutable reference to the publisher. + + ```rust + public fun publisher_mut( + _: &PlatformCap, + registry: &mut Registry + ): &mut Publisher {} + ``` + - `proxy` full example + ```move file=/examples/move/asset_tokenization/asset_tokenization/sources/proxy.move + ``` + + + + + +The `unlock` module facilitates the unlocking of a tokenized asset specifically for authorized burning and joining. + +It allows tokenized asset type creators to enable these operations for kiosk assets without necessitating adherence to the default set of requirements, such as rules or policies. + +**Structs** + +- `JoinPromise` + + A promise object is established to prevent attempts of permanently unlocking an object beyond the intended scope of joining. + + ```rust + struct JoinPromise { + /// the item where the balance of the burnt tokenized asset will be added. + item: ID, + /// burned is the id of the tokenized asset that will be burned + burned: ID, + /// the expected final balance of the item after merging + expected_balance: u64 + } + ``` + +- `BurnPromise` + + A promise object created to ensure the permanent burning of a specified object. + + ```rust + struct BurnPromise { + expected_supply: u64 + } + ``` + +**Functions** + +- `asset_from_kiosk_to_join` + + This helper function is intended to facilitate the joining of tokenized assets locked in kiosk. It aids in unlocking the tokenized asset that is set for burning and ensures that another tokenized asset of the same type will eventually contain its balance by returning a `JoinPromise.` + + ```rust + public fun asset_from_kiosk_to_join( + self: &TokenizedAsset, // A + to_burn: &TokenizedAsset, // B + protected_tp: &ProtectedTP>, // unlocker + transfer_request: TransferRequest> // transfer request for b + ): JoinPromise {} + ``` + +- `prove_join` + + A function utilized to demonstrate that the unlocked tokenized asset is successfully burned and its balance is incorporated into an existing tokenized asset. + + ```rust + public fun prove_join( + self: &TokenizedAsset, + promise: JoinPromise, + proof: ID) { + } + ``` + +- `asset_from_kiosk_to_burn` + + Helper function that facilitates the burning of tokenized assets locked in a kiosk. It assists in their unlocking while ensuring a promise that the circulating supply will be reduced, achieved by returning a `BurnPromise`. + + ```rust + public fun asset_from_kiosk_to_burn( + to_burn: &TokenizedAsset, + asset_cap: &AssetCap, + protected_tp: &ProtectedTP>, + transfer_request: TransferRequest>, + ): BurnPromise { + } + ``` + +- `prove_burn` + + Ensures that the circulating supply of the asset cap is reduced by the balance of the burned tokenized asset. + + ```rust + public fun prove_burn( + asset_cap: &AssetCap, + promise: BurnPromise) { + } + ``` + - `unlock` full example + ```move file=/examples/move/asset_tokenization/asset_tokenization/sources/unlock.move + ``` + + + + + +### `template` Package + +An example use case package that enables utilization of Rust WASM functionality to support seamless asset creation on the browser. + +This is similar to the launchpad approach and serves as the template package whenever a new asset requires representation as a tokenized asset. + +Effectively allowing users to edit fields of this template contract on the fly and publish it with the edits included. +This package implements two essential modules, each catering to distinct functionalities required for asset tokenization. +More details regarding how Rust WASM was implemented can be found in the [Web Assembly](#webassembly-wasm-and-template-package) section. + +- **Modules** + + - `template` + + This is the module that supports defining a new asset. + + When you need to represent a new asset as a fractional asset, modify this module to `