diff --git a/docs/about/architecture/_category_.json b/docs/about/architecture/_category_.json new file mode 100644 index 0000000..8f5a09a --- /dev/null +++ b/docs/about/architecture/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Architecture", + "position": 7 +} diff --git a/docs/about/architecture/astar-parachain.md b/docs/about/architecture/astar-parachain.md new file mode 100644 index 0000000..0ed4dd9 --- /dev/null +++ b/docs/about/architecture/astar-parachain.md @@ -0,0 +1,57 @@ +--- +title: Astar Parachain +sidebar_position: 1 +--- + +# Overview +If you are already building on Polkadot you will not need to go over the sections covering Substrate and how to create a Runtime, but it will be helpful for you to understand the environment, terminology and how to leverage Polkadot's highly interoperable environment. + +Polkadot is a multi-chain environment which enables specialized blockchains (called Parachains) to communicate with each other in a secure, trustless environment. + +Astar is a parachain connected to the Polkadot Relay chain, specialized for: +* Executing all types of smart contracts. +* Providing a hybrid EVM + Wasm environment supporting Cross-VM (XVM) smart contract calls. +* Incentivizing ecosystem innovation and providing basic income for dApp developers. +* Seamlessly aggregating features or assets from parachains in the ecosystem. + +## What is Polkadot +To get started, let's kick it off with two short videos that do a very good job at explaining some core concepts around Polkadot. First, watch Bill Laboon, Director of Education and Support at the Web3 Foundation, explain the basics of Polkadot. + + + +Ok, you can’t learn it all in one minute. But how about in 5 minutes? Have a look at this excellent video from DeFi Teller, explaining how Polkadot works. + + + +## How the Relay Chain works +The Polkadot network uses a sharded model where shards - called "parachains", allow transactions to be processed in parallel instead of sequentially. Each parachain in the network has a unique state transition function. Polkadot is a Relay Chain acting as the main chain of the system. + +Parachains construct and propose blocks to validators on the Relay Chain, where the blocks undergo rigorous availability and validity checks before being added to the finalized chain. As the Relay Chain provides the security guarantees, collators - full nodes of these parachains - don't have any security responsibilities, and thus do not require a robust incentive system. This is how the entire network stays up to date with the many transactions that take place. + +## Substrate +Based on Polkadot's design, as long as a chain's logic can compile to Wasm and adheres to the Relay Chain API, then it can connect to the Polkadot network as a parachain. +However, the majority of parachains today are built using [Substrate](https://substrate.io/) because Substrate-based chains are easy to integrate into Polkadot or Kusama to become a parachain. Essentially, Substrate is the SDK which can be used to build parachains and Polkadot is the means of securing the chains and allowing them to communicate with each other. + +Astar Network is built with Substrate and inherints many Substrate features, such as Accounts. + +At a high level, a Substrate node provides a layered environment with two main elements: +1. An outer node that handles network activity such as peer discovery, managing transaction requests, reaching consensus with peers, and responding to RPC calls. +2. A runtime that contains all of the business logic for executing the state transition function of the blockchain. +Read more about [Architecture](https://docs.substrate.io/fundamentals/architecture/). + +### FRAME +FRAME is an acronym for Framework for Runtime Aggregation of Modularized Entities which encompasses a significant number of modules and support libraries that simplify runtime development. In Substrate, these modules (called pallets) offer customizable business logic for different use cases and features that you might want to include in your runtime. For example, there are pallets that provide a framework of business logic for staking, consensus, governance, and other common activities. +Read more about [Runtime development](https://docs.substrate.io/fundamentals/runtime-development/) + + +## Where Do Smart Contracts Execute? +The Polkadot runtime does not support smart contracts. Smart contracts require a Virtual Machine (VM) environment where contracts can be executed, and the most well-known and widely supported platform being the Ethereum Virtual Machine (EVM). Substrate FRAME contains modules that support Wasm smart contract execution, as well as EVM. + +### Ethereum Virtual Machine (EVM) +The Ethereum Virtual Machine (EVM) is a virtual computer with components that enable Ethereum network participants to store data and agree on the state of that data. On a Substrate-based blockchain, the core responsibilities of the EVM are implemented in the EVM pallet, that's responsible for executing Ethereum contract bytecode written in a high level language like Solidity. Astar EVM provides a fully Ethereum Virtual Machine compatible platform, which you can learn more about in the [EVM chapter](/docs/build/build-on-layer-1/smart-contracts/EVM/index.md) + +### Substrate Virtual Machine for Wasm Contracts +Substrate also ships with a module for smart contracts, called `pallet-contracts`. If a parachain is developed on Substrate it can easily add smart contract functionality by including this pallet. Astar supports this Polkadot Native approach to smart contracts, and you can learn more in the [Wasm chapter](/docs/build/build-on-layer-1/smart-contracts/wasm/index.md). + + + diff --git a/docs/about/architecture/img/fig4.jpg b/docs/about/architecture/img/fig4.jpg new file mode 100644 index 0000000..45de91e Binary files /dev/null and b/docs/about/architecture/img/fig4.jpg differ diff --git a/docs/about/architecture/index.md b/docs/about/architecture/index.md new file mode 100644 index 0000000..15f3605 --- /dev/null +++ b/docs/about/architecture/index.md @@ -0,0 +1,29 @@ +--- +title: Architecture +--- + +import Figure from '/src/components/figure' + +# Overview +Before you get started on your journey towards becoming an Astar network hacker, it will be beneficial to know about what Polkadot and Ethereum are, because Astar Network connects to both, and each have their own set of benefits benefits and limitations. + +
+ +Some highlights on the Polkadot parachain side are dApp Staking, ink! smart contracts, cross-chain messaging (XCM), and forkless upgradability, and on the Ethereum layer 2 side are the highest levels of EVM equivalence, shared liquidity across layer 2 networks, and access to the largest pool of developers in the blockchain industry that we can tailor our products for, on-demand. + +For now, let's go over some basics that apply to all blockchains whether they are sovereign layer 1 networks, or rely on another blockchain such as the Polkadot Relay Chain for shared security and interoperability. + +## Blockchain Basics +A blockchain is a decentralized ledger that records information in a sequence of blocks. The information contained in a block is an ordered set of instructions that may or may not result in a change in state. + +In a blockchain network, individual computers—called nodes—communicate with each other to form a decentralized peer-to-peer (P2P) network. There is no central authority that controls the network and, typically, each node that participates in block production stores a copy of the blocks that make up the canonical chain. + +In most cases, users interact with a blockchain by submitting a request that might result in a change in state, for example, a request to change the owner of a file or to transfer funds from one account to another. These transactions requests are gossiped to other nodes on the network and assembled into a block by a block author. To ensure the security of the data on the chain and the ongoing progress of the chain, the nodes use some form of consensus to agree on the state of the data in each block and on the order of transactions executed. [Read more...](https://docs.substrate.io/fundamentals/blockchain-basics/) + +## Applications Running on a Blockchain +Applications that run on a blockchain, often referred to as decentralized applications or dApps, are typically web applications written using front-end frameworks, but powered by smart contracts on the backend, to affect the blockchain state. + +A **smart contract** is a program that runs on a blockchain and executes transactions on behalf of users under specific conditions. Developers can write smart contracts to ensure that the outcomes of programmatically-executed transactions are recorded, and can't be tampered with. Yet, smart contracts operate in a sandboxed environment, where developers don't have access to underlying blockchain functionality, such as consensus, storage, or transaction layers, and instead, abide by a chain's fixed rules and restrictions. Smart contract developers often accept these limitations as a tradeoff that shortens the development lifecycle, by avoiding having to make core design decisions. + +## Ethereum Virtual Machine (EVM) +The Ethereum Virtual Machine (EVM) is a virtual computer with components that enables network participants (not necessarily on Ethereum) to store data and agree on the state of that data. Smart contracts run on the EVM, and most Layer 1 blockchains support an EVM-compatible virtual machine environment. Astar Parachain and Astar zkEVM both support EVM-compatible environments. \ No newline at end of file diff --git a/docs/about/astar.md b/docs/about/astar.md new file mode 100644 index 0000000..73d28d9 --- /dev/null +++ b/docs/about/astar.md @@ -0,0 +1,27 @@ +--- +sidebar_position: 1 +--- + +# About Astar Network + +[Astar Network]: https://astar.network/ + +Astar Network is Japan's most popular smart contract platform, supporting both EVM and WebAssembly (Wasm) environments, and interoperability between them using a Cross-Virtual Machine. Astar Network is friendly to all kinds of developers, and the tools and languages they already know. Backed by the shared security of Polkadot, Astar shines brilliantly on its own within a vibrant and healthy ecosystem, and in the blockchain industry overall driving international corporate adoption, and consumer interest in Web3 technologies. + +## Lack of developer incentives + +Astar's Build2Earn system is designed to grow the network in an innovative way, while simultaneously rewarding participants and builders. It allows developers to earn incentives for building and maintaining their decentralized applications, and users to earn incentives for supporting their favorite projects, all while encouraging growth of the ecosystem overall. + +## Scalability + +Blockchains do not scale by design, mostly due to the security assurances inherent in their decentralized consensus mechanisms. If blockchains were faster, they would be less secure. There is an upper limit to the amount of data that can be stored in individual blocks, and at times of network saturation, users of typical blockchains may notice their transactions sitting unconfirmed or in a pending state for long periods of time, resulting in a poor user experience. + +The solution to the issue, up until now, has been a patchwork of independent blockchains loosely connected by bridges - often subject to attack due to their reliance on custodial elements, with no common security standards or methods of interoperability between all. The idea of 'cross-chain', therefore, has mostly been to copy and paste a smart contract from one blockchain, to another. Projects that create real value are quickly copied and deployed elsewhere for better, or for worse, with almost no real innovation taking place overall. + +Astar Network is changing that, and ushering in the next generation of multichain smart contracts uniquely able to utilize the best features from both EVM and WebAssembly Virtual Machines, and any number of application-specific blockchains across the broader Polkadot ecosystem. All while being future-proof. + +## Interoperability + +This interoperability framework, empowered by the shared security of Polkadot coupled with Astar XVM, allows developers to use and build smart contracts in ways they never have before. By fostering cooperation and integrations across multiple blockchains and applications, complex synergies can be developed, leading to the realization of truly innovative solutions that can't be replicated in any other environment. + +Many different blockchains exist, but few have interoperability as their defining feature. Welcome to Astar Network. diff --git a/docs/about/economics/Inflation.md b/docs/about/economics/Inflation.md new file mode 100644 index 0000000..82770fe --- /dev/null +++ b/docs/about/economics/Inflation.md @@ -0,0 +1,167 @@ +--- +sidebar_position: 2 +--- + +Astar has a soft-capped 'yearly' inflation and uncapped max supply. +Inflation is distributed amongst actors in the network, in varying proportions. +Actors include: +* stakers +* dApp owners +* collators +* treasury + + +## Basic Time Units + +### Cycles +**Cycle** can be considered as a 'year' in the Astar Network. +When a new cycle starts, new inflation configuration is calculated according to the total issuance at that point in time. +E.g. if 'yearly' inflation is set to be 7%, and total issuance is 1,000,000 ASTR, then the soft-capped max inflation for that +cycle will be 70,000 ASTR. + +Cycle length is configurable, but in practice it will resemble a 'year' off-chain. + + $inflation\_soft\_cap = inflation\_rate * total\_issuance$ + +### Periods + +Each **cycle** consists of one or more **periods**. +**Periods** are a core time unit in the dApp Staking protocol. Each period consists of a `Voting` and `Build&Earn` subperiods. + +During the `Voting` subperiod, neither stakers nor dApp owners can earn any rewards, only _collators_ and _treasury_ continue earning. +During the the `Build&Earn` subperiod, stakers earn staking rewards per **era** and have the opportunity to earn bonus reward at the end of a period. +dApp owners also earn rewards, based on how well their dApp is performing in dApp staking, at the end of each **era**. + +### Eras + +Each **period** is divided up into multiple **eras**. +**Era** is the core time unit in dApp staking, and its length is measured in the number of blocks. + +`BuildAndEarn` subperiod consists of one or more _standard_ **eras**. Each era has a fixed length. +`Voting` subperiod always consists of exactly **one era** and this _voting_ era is unique as its length (in blocks) can be longer than a _standard_ era length (but always a multiple of _standard_ era length). + +### Example + +* Block is produced every 12 seconds +* **Era length** is 7200 blocks which equals 24 hours (1 day) (This is _standard_ era length) +* `Voting` subperiod length is 10 eras (This is the single _voting_ era which lasts 10 x 7700 blocks) +* `Build&Earn` subperiod length is 81 eras +* Cycle length is **4 periods** + +With such configuration, we'd end up with a cycle lasting 364 days (roughly a year), and each period taking around 3 months to complete. + +## Recalculation + +When a new cycle begins, soft-inflation cap is recalculated, and according to the calculated value, rewards for all network actors are adjusted. + +The reason why it's a _soft-cap_, instead of a _hard-cap_ is how staker & dApp rewards are distributed. +Rewards are only minted when they are claimed, and it is possible that at the time of reward recalculation, some rewards remain unclaimed. +As a result, theoretically, it's possible for the cycle inflation to exceed the _soft-cap_ even though in practice it will be highly unlikely +due to _lazy minting_ & _fee burn_ mechanisms. + +## Inflation Distribution + +Based on the calculated _soft-cap_, rewards for all network participants are adjusted. + +### Collators + +_Collators_ get a fixed amount of the cycle's _soft-capped_ inflation. +This amount is equally divided by the number of blocks in the cycle. + +$collator\_reward\_per\_block = \frac{total\_collator\_cycle\_reward}{blocks\_per\_cycle}$ + +### Treasury + +Similar to the _collators_, treasury gets a fixed amount of the cycle's _soft-capped_ inflation +distributed in equal amounts throughout all the blocks in the cycle. + +$treasury\_reward\_per\_block = \frac{total\_treasury\_cycle\_reward}{blocks\_per\_cycle}$ + +### dApps + +dApp reward are _assigned_ at the end of each era during `Build&Earn` subperiod. +This means that the total cycle's dApp reward amount has to be equally divided by the total number of `Build&Earn` eras in a cycle. + +$dapp\_reward\_pool\_per\_era = \frac{total\_dapp\_cycle\_reward}{periods\_per\_cycle * eras\_per\_build\_and\_earn}$ + +The dApp staking protocol will calculate how much each staked dApp should get. + +### Stakers + +There are two components to the staker rewards - regular _staking_ rewards & the _bonus_ reward for loyal stakers. + +#### Regular Staker Rewards + +Regular staker rewards are awarded for staking native currency, **ASTR**, on a dApp. +These rewards have two components - the _base_ reward and the _adjustable_ reward. + +Base reward is the amount assigned to the reward pool at the end of each era regardless of how much has been staked in total. + +$base\_staker\_reward\_pool\_per\_era = \frac{total\_base\_staker\_cycle\_reward}{number\_of\_cycles * eras\_per\_build\_and\_earn}$ + +The adjustable part is the dynamic part, and depends on the _total value staked_ and the _target stake value_. +This amount linearly increases as the _total value staked_ increases, and then saturates once the amount is reached or exceeded. +With this component, _staker rewards_ are not a _zero-sum game_. + +$max_\_adjustable\_staker\_reward\_pool\_per\_era = \frac{total\_adjustable\_staker\_cycle\_reward}{number\_of\_cycles * eras\_per\_build\_and\_earn}$ + +The adjustable part of the reward is calculated once an era ends, using the _total value staked_ at that point in time. + +$adjustable\_factor = min(1, \frac{total\_value\_staked\_percent}{ideal\_staking\_percent})$ + +Using the _adjustable\_factor_, adjustable portion of the staker reward is: + +$adjustable\_staker\_reward\_pool = max_\_adjustable\_staker\_reward\_pool\_per\_era * adjustable\_factor$ + +When the _adjustable factor_ is less than **1**, it means the remainder is never minted, reducing the overall inflation. + +With the above formulas, we can finally express how much staker _Alice_ earns in era **n**: + +$staker\_reward\_per\_era_{Alice} = \frac{staked\_value_{Alice,n}}{total\_staked\_value_n} * (base\_staker\_reward\_pool\_per\_era_n + adjustable\_staker\_reward\_pool_n)$ + +#### Bonus Rewards + +In case a staker stakes during the `Voting` subperiod, and doesn't reduce their stake during the `Build&Earn` subperiod below what +was staked at the end of the `Voting` subperiod, it will make them eligible for the bonus reward. + +Bonus reward pool is assigned per period, and can be expressed as: + +$bonus\_reward\_pool\_per\_period = \frac{total\_bonus\_cycle\_reward}{periods\_per\_cycle}$ + +The bonus reward for a staker _Alice_ can then be expressed as: + +$bonus\_staker\_reward_{Alice} = \frac{voting\_subperiod\_staked\_value_{Alice}}{total\_voting\_subperiod\_staked\_value} * (bonus\_reward\_pool\_per\_period)$ + +## Lazy Minting + +Both _staker_ and _dApp_ rewards are minted in a lazy fashion - when they are needed. Only collator & treasury rewards are minted per block. + +With the _adjustable staker reward_ and the dApp staking tier system, the inflation in practice will be much lower than the calculated _soft-cap_. +Maximum adjustable award amounts is possible only if the ideal staking rate is reached or exceeded. +For the dApp rewards, it's unlikely that all of the tiers will be filled with dApps - it might be that the tier capacity is larger than the demand, +or that simply some dApps don't attract enough support to enter a tier. These rewards will never be even minted thus lowering the effective inflation rate. + +Rewards don't persist forever, and must be claimed before they _expire_. +Although this is expected to be very lenient, it's still possible to happen. + +None of the aforementioned mechanism are _burn_ mechanisms, instead they just delay the _minting_ operation until it's needed. +The major burn mechanism is part of the fee system, where a significant portion of fees get burned. +Only due to this, it's practically impossible for the _soft-capped max inflation_ to be reached when considering rewards assigned & issued during +a single cycle. + +## Parameters + +| Parameter | Astar | Shiden | Shibuya | +|------------------------------|-------|--------|---------| +| Periods Per Cycle | 3 | 6 | 2 | +| Eras Per Voting Subperiod | 11 | 6 | 8 | +| Eras Per Build&Earn Subperiod| 111 | 55 | 20 | +| Blocks Per Era | 7200 (~24 hours) | 7200 (~24 hours) | 1800 (~6 hours) | +| Cycle Inflation Rate | 7% | 7% | 1% | +| Treasury Part | 5% | 5% | 5% | +| Collators Part | 3.2% | 3.2% | 3% | +| dApps Part | 13% | 13% | 20% | +| Base Staker Part | 25% | 10% | 25% | +| Adjustable Staker Part | 40% | 58.8% | 35% | +| Bonus Part | 13.8% | 10% | 12% | +| Ideal Staking Rate | 50% | 50% | 20% | diff --git a/docs/about/economics/_category_.json b/docs/about/economics/_category_.json new file mode 100644 index 0000000..8602410 --- /dev/null +++ b/docs/about/economics/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Tokenomics 2.0", + "position": 10 +} diff --git a/docs/about/economics/astar-tokens.md b/docs/about/economics/astar-tokens.md new file mode 100644 index 0000000..5d4a208 --- /dev/null +++ b/docs/about/economics/astar-tokens.md @@ -0,0 +1,66 @@ +--- +sidebar_position: 3 +--- +# Astar Token + +## Overview +The native token of Astar Network is Astar Token, with the ticker ASTR. The initial supply of ASTR was 7,000,000,000 units. The current tokenomics model of the network is inflationary and the inflation is estimated to be ~665,000,000 yearly. +ASTR token has 18 decimals. +At the genesis, ASTR were allocated as follows: + +| Allocation | % | +|----|----| +|Users and Early Supporters| 30| +|Parachain Auction in 2021 | 20 | +| Parachain Auctions Reserve | 5| +| Protocol Development | 10 | +|On-Chain DAO| 5| +|Marketing | 5 | +| Early Financial Backers | 10 | +| Team (Employee Incentives) | 5 | +| Foundation | 10 | + +## Utility +Astar Token is the utility token for Astar Network that has 3 primary functions. + +1. dApp Staking +2. Transactions +3. On-chain Governance + + +### dApp Staking + +Astar Network's core team has developed a unique concept called dApp Staking, which is exclusively available on Astar within the Polkadot ecosystem. The goal of Astar Network is to establish itself as the primary hub for decentralized applications (dApps) on Polkadot. Hence, we prepared incentives for dApp developers who choose to build their smart contracts on Astar Network. + +dApp Staking is a simple but effective mechanism. Astar Network's innovative approach allows Astar token holders to show their support for their preferred dApps by staking Astar tokens. By doing so, they not only contribute to the ecosystem's growth but also earn Astar tokens through block rewards. Additionally, dApp developers can receive rewards based on the amount staked on their applications. As part of Astar Network's commitment to sustainability and decentralization, developers can earn Astar tokens by creating smart contracts or infrastructure for the Astar Network community, making it a robust and decentralized grant mechanism. + +### Transactions + +Every on-chain transaction requires the sender to pay fees. Part of the fee is burned and part is deposited to the collator. + +### On-chain Governance + +At Astar Network, we believe in the power of decentralized decision-making. That's why we're committed to implementing on-chain governance, where every member of the community has a say in shaping the network's future. The Astar token plays a crucial role in this process, serving as the primary means for facilitating governance activities such as voting and referenda. + +## Shiden and Shibuya + +Both Shiden and Shibuya have their own tokens. +Shiden's token is SDN. +You can see the SDN initial allocation below: + +| Allocation | % | +|----|----| +|Users and Early Supporters| 30| +|Parachain Auctions | 30 | +| Parachain Auctions Reserve | 5| +| Protocol Development | 10 | +|On-Chain DAO| 5| +|Marketing | 5 | +| Ecosystem Growth | 10 | +| Team (Employee Incentives) | 5 | + +Shibuya's token is SBY. +There are ways to get SBY for testing purposes via Faucet on the Astar Portal. + +## Learn more +Obtain [SBY tokens](/docs/build/build-on-layer-1/environment/faucet.md) diff --git a/docs/about/economics/img/Astar-Block-Consumption.jpeg b/docs/about/economics/img/Astar-Block-Consumption.jpeg new file mode 100644 index 0000000..82879a4 Binary files /dev/null and b/docs/about/economics/img/Astar-Block-Consumption.jpeg differ diff --git a/docs/about/economics/img/inflation_1.png b/docs/about/economics/img/inflation_1.png new file mode 100644 index 0000000..31de01d Binary files /dev/null and b/docs/about/economics/img/inflation_1.png differ diff --git a/docs/about/economics/img/tokenomics_1.png b/docs/about/economics/img/tokenomics_1.png new file mode 100644 index 0000000..816ff42 Binary files /dev/null and b/docs/about/economics/img/tokenomics_1.png differ diff --git a/docs/about/economics/index.md b/docs/about/economics/index.md new file mode 100644 index 0000000..c6256c1 --- /dev/null +++ b/docs/about/economics/index.md @@ -0,0 +1,38 @@ +--- +sidebar_position: 12 +--- +# Tokenomics 2.0 + +Astar Network's tokenomics has been revised to best serve the needs of network participants, from users and builders to enterprise partners. + +Tokenomics 2.0 introduces a sustainable token allocation structure and network fees as well as a lower inflation rate. + +:::info +The outline of the phased approach to Tokenomics 2.0 as it progressed: +- Phase 0 - Forum Discussion: + - ✅ ongoing throughout all phases +- Phase 1 - Fee Adjustments: + - ✅ Shibuya testnet - live since October 2023 + - ✅ Shiden - live since November 2023 + - ✅ Astar - live since November 2023 +- Phase 2 - Hybrid Inflation Model (Reduction of collators' reward and treasury reward, reduction of inflation) + - ✅ Shibuya testnet - live since November 2023 + - ✅ Shiden - live since December 2023 + - ✅ Astar - live since December 2023 +- Phase 3 - Full Inflation Model (activation of dAppStaking v3 which affects block reward calculation, further reduction of inflation) + - ✅ Shibuya testnet - live since December 2023 + - ✅ Shiden - live since February 2024 + - ✅ Astar - live since February 2024 +::: + +:::tip +Astar, Shiden and Shibuya share the same economic model, however configuration differences exist. Following chapters focus on Astar (ASTR token) but also apply to Shiden (SDN token) and Shibuya (SBY token). +::: + +
+ +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + + diff --git a/docs/about/economics/legacy_inflation.md b/docs/about/economics/legacy_inflation.md new file mode 100644 index 0000000..fde6366 --- /dev/null +++ b/docs/about/economics/legacy_inflation.md @@ -0,0 +1,190 @@ +--- +sidebar_position: 3 +title: Legacy Tokenomics +--- + +:::note +The following subchapters cover legacy Astar tokenomics models. +For the latest, please refer to the _Tokenomics 2.0_ model. +::: + +# Tokenomics 1.0 + +import tokenomics from '/docs/about/economics/img/tokenomics_1.png' +import inflation from '/docs/about/economics/img/inflation_1.png' + +[Astar Network]: https://astar.network/ + +:::tip +Astar and Shiden share the same economic model, though there were differences in their initial supply configurations. +The following chapters focus on Astar and ASTR, however, this information also applies to Shiden and SDN token. +::: + +## Overview + +In previous chapters we defined the initial ASTR token distribution. However, Astar uses an inflationary tokenomics model (unbound supply) where tokens are issued each time a new block is produced. These tokens power the dApp staking system and are used to reward stakers and collators. + +[Astar Network] tokenomics model is built around supporting developers via dApp staking. At its core, ASTR token has a number of utilities: + +1. Payment for transaction fees +2. Staking dApps +3. dApp staking rewards & collator rewards + +### Inflation Model + +For each block produced, Astar issues a fixed number of tokens. Initially, these numbers were chosen to generate approximately 10% inflation, based on the initial supply. + +Since January 2023, ASTR inflation has been reduced by 5% to ~665,000,000 ASTR yearly. + +| Network | Issued Per Block | Issued Per Era* | +| ------- | ---------------- | -------------- | +| Astar | 253.08 ASTR | 1,822,176 ASTR | +| Shiden | 2.664 SDN | 19,180.8 SDN | + +\* 1 era =~ 1 day, assuming a new block is produced every **12** seconds. + +The reader might notice that Astar issues 95 times more tokens per block than Shiden. This is due to Astar having a 100 times greater initial supply than Shiden. + +### Beneficiaries + +Each block reward is distributed to a set of beneficiaries. +​ +#### Collators + +The collator responsible for building the block will receive **collator's** portion of reward. This is the main financial incentive for the collators. Portion is configured as percentage of the block reward on-chain and is constant per block unless manually changed. + +In addition, it will receive fees paid by the users for transactions that were included in the produced block. + +For **Shiden**, **100%** of the fees are burned, and the full tip is paid to the collator. +For **Astar**, **20%** of the fees & tips are burned, and the rest is paid to the collator. + +#### On-chain Treasury + +Treasury receives a variable portion of block reward. It is then allocated to a range of initiatives across the Astar ecosystem. This includes building reserves for parachain auctions, as well as supporting various projects and activities that help grow and strengthen our network. + +#### dApp Staking + +`dApp staking`, Astar's innovative developer incentive mechanism, receives a variable portion of the block rewards depending on current **total value locked** (or **TVL** in further text) in dApps staking. + +Part of it is dedicated for supporting dApp developers while another part goes towards stakers who locked their ASTR to *stake* or *vote* for a dApp. + +
+ +
+ +### Model Overview + +Previous chapters described that inflation per block is fixed - however, the way we distributed this reward for some beneficiaries is dynamic and depends on certain parameters. It's important to emphasize that all of the related parameters of the model are read on-chain - **nothing** is provided off-chain. This makes it secure and easily verifiable. + +There are two main things to understand before diving deeper into the model - **TVL** and **configurable block reward parameters**. + +#### TVL + +The main variable in the system that fluctuates from block to block, based on user actions, is **TVL** from dApp staking. +:::note +TVL in this context does not consider non-ASTR tokens locked by other protocols built on top of Astar (e.g. DeFi protocols) and as such has no effect on the reward distribution schema. +::: + +We're interested particularly in **TVL percentage** +- $total\_issuance$ - total amount of issued **ASTR** tokens +- $TVL$ - total amount of tokens locked in dApps-staking +- $TVL_{\%} = {TVL \over total}$ + +In case **total_issuance** equals 1000 and **TVL** is 242, **TVL percentage** will be `24.2%`. + +#### Configurable Parameters + +The following parameters influence how each block reward is distributed. + +| Name | Description | Example Value | +| ----------------------- | ----------- ------------------------------- | ------------- | +| Collators Percent | Fixed percentage that goes to collators | 10% | +| Base Treasury Percent | Minimum percentage that always goes to treasury | 10 % | +| Base Staker Percent | Minimum percentage that always goes to dApps-staking staker rewards pool | 20 % | +| dApps Percent | Fixed percentage that goes to dApps-staking dApp reward pool | 15 % | +| Adjustable Percent | Percentage that is split between treasury and stakers, depending on the TVL | 45 % | +| Ideal dApps-staking TVL | TVL percentage which is considered to be ideal | 60% | + +The amount received by stakers and the treasury is dynamic and depends on TVL. However, there is a lower bound on how much goes towards them. These are the *base* parameters. Collators and dApps always receive a fixed percentage of the reward. + +##### Adjustable Percent + +Depending on the TVL, the **adjustable percent** of the block reward is split between stakers and the treasury. +$$ +\begin{aligned} +a&djustable_{staker} = min(1, {TVL_{\%} \over TVL_{ideal}}) * adjustable_{\%} +\newline\newline +t&otal_{staker} = base_{staker} + adjustable_{staker} +\newline\newline +t&otal_{treasury} = base_{treasury} + (adjustable_{\%} - adjustable_{staker}) +\end{aligned} +$$ + +As more tokens are staked and TVL increases, the portion of staker rewards increases in proportion to the growth of the network. This approach helps to compensate for the *zero-sum* nature of staking and incentivize more users to participate in securing the network. It's important to note that this reward increase is linear up to a certain threshold, known as the $TVL_{ideal}$ point. Once this threshold is reached, the reward increase will saturate, meaning that any further increase in TVL will not result in an increase in staker rewards. This ensures a fair and sustainable reward system that benefits all members of the Astar community. + +Note that in Polkadot's model, when ideal TVL is reached, staker rewards drop exponentially. In our case, they only become saturated, making it a *zero-sum-game*. Motivation behind our approach is simplicity. + +##### Interest Rate + +Using the parameters from the previous chapters, we can express yearly interest rate for the stakers: +$$ +i = {inflation_{annual} * total_{staker} \over TVL_{\%}} +$$ + +For example, in case $total_{staker} = 55\%$ and $TVL_{\%} = 40\%$, we end up with ${0.1 * 0.55 \over 0.4}$ which is `13.75%` annual interest rate. + +However, inflation dilutes the interest rate so it's more precise to consider *inflation adjusted annual interest rate*. + +$$ +i_{adjusted} = {i + 1 \over inflation_{anual} + 1} - 1 +$$ + +To follow up on the example above, *inflation adjusted* value would be ${0.1375 + 1 \over 0.1 + 1} - 1$ which is `3.4%`. + +### Model Visualization + +The following graph is a visualization of the described model. + +* green line is interest rate $i$ +* blue line is total staker inflation $total_{staker}$ +* red line is inflation adjusted interest rate $i_{adjusted}$ + +
+
+ +
Model Visualization
+
+
+ +You can check this model and configure parameters yourself [here](https://www.desmos.com/calculator/cjjkt6smk5). + +# Hybrid Inflation + +The hybrid inflation model served as a step between the _Tokenomics 1.0_ and _Tokenomics 2.0_. + +### Inflation Adjustment + +Inflation rates have been lowered. The maximum token reward per block, reached based on the optimal staking rate or staking TVL (Total Value Locked), has been reduced from 253.08 to 231.20. Please note that this is temporary until the next phase of Tokenomics 2.0 coming with dApp Staking v3. + +### Treasury rewards + +The dynamic treasury allocation has been removed in favor of a fixed annual inflation rate of 5%. Which correspond to a reward of 11.06 ASTR per block. + +### Collators rewards + +Collators will now receive a steady 3.2% of the annual inflation which correspond to a reward of 7.07 ASTR per block. Although this represents a reduction from the previous model, the upcoming alignment of EVM fees and Substrate native fees is expected to increase overall fee earnings for collators. + +### Stakers & dApp Rewards + +The rewards for dApp staking, both for users and dApps, will remain unchanged in absolute terms. No immediate modifications will be implemented in this area. Future updates, including the introduction of dApp staking v3, will occur in the third phase of Tokenomics 2.0. + +We use the blockReward distribution to ensure those three requirements (and calculate them from the reward per block): + +| | Percentage | Reward ASTR | +|------------------|------------|-------------| +| Block reward | 100% | 231.20 | +| Treasury | 4.78% | 11.06 | +| Collators | 3.06% | 7.07 | +| dApp reward | 17.27% | 39.93 | +| Base Staker | 23.04% | 53.27 | +| Adjustable Staker | 51.84% | 119.85 | \ No newline at end of file diff --git a/docs/about/economics/tokenomics2-network-fees.md b/docs/about/economics/tokenomics2-network-fees.md new file mode 100644 index 0000000..0df2c6e --- /dev/null +++ b/docs/about/economics/tokenomics2-network-fees.md @@ -0,0 +1,157 @@ +--- +sidebar_position: 1 +--- + +import Figure from "/src/components/figure" + +# Fee Model + +Each block is a limited resource - it can only fit a limited amount of transactions. This is an oversimplification, but the point is that every transaction included in the block consumes a portion of the block’s resources. + +Astar is a parachain in the Polkadot ecosystem, which relies on the shared security the Polkadot relay chain provides. However, it comes at the cost of having certain limitations placed on block resources. Most readers should know that a block is produced on Astar every 12 seconds - a limitation imposed by Polkadot. Only 0.5 out of those 12 seconds account for the time required to **execute** the block. This means it takes **0.5 seconds** of execution time on some CPU to execute the block logic. This is the first limiting resource - usually called `ref time` (time required to execute on the reference machine). + +As a simple example - consider a token transferred from **Alice** to **Bob**. If such a transaction consumes **0.001 seconds** of execution time, executing two such transactions in a single block would consume **0.002 seconds**. Calling a smart contract, e.g., a DEX swap, is much more resource intensive and may, for example, consume **0.01 seconds, or 100x that of a simple transfer from one account to another**. + +The other limiting factor is the **Proof of Validity** (PoV) size. Since Polkadot validators provide security by validating blocks authored by parachain collators, they need access to the data required to validate the block. Expanding on the previous example with **Alice** and **Bob**, Astar would need to provide Polkadot validators with information about how many initial tokens **Alice** and **Bob** had and the transaction itself. This is (almost) enough data for validators to work with, but it is strictly limited to only **5 MB (megabytes)** per block. + +In summary, there are two main factors limiting block production: `ref time` and `PoV size`, which taken all together, are collectively referred to as `weight`, an important concept when calculating transaction fees. + +
+ +Transaction Fees on Astar are comprised of Native (Substrate) and EVM fees. Native and EVM transaction fees are calculated in different ways. Tokenomics 2.0 aligns the fees calculation between the two systems so that transactions consuming the same amount of block resources are priced roughly the same regardless of transaction type (Native or EVM). + +This section describes Tokenomics 2.0 fee model calculation details. + +## Native Fees + +Native fees are applied to transactions native to Substrate. For example, balance transfer, using dApp staking, creating a multisig, voting on a referendum, etc. + +Fees are calculated using a [model](https://research.web3.foundation/Polkadot/overview/token-economics#adjustment-of-fees-over-time) commonly used by Polkadot and (probably) all parachains: + +$$ +\begin{align} +native\_fee &= base\_fee + c * weight\_fee + length\_fee + rent\_fee + tip +\end{align} +$$ + +where following applies: + +$$ +\begin{align} +weight\_fee &= weight_{factor} * \frac{transaction_{weight}}{base_{weight}} +\\ +length\_fee &= length_{factor} * transaction\_length +\\ +rent\_fee &= storage\_items*price\_per\_item + storage\_bytes*price\_per\_byte +\end{align} +$$ + +- $base\_weight$ - fixed base weight of each transaction included in the block. +- $base\_fee$ - a fixed fee that needs to be paid for every transaction included in the block. +- $weight\_fee$ - is the fee related to the weight of the transaction. +- $c$ - fee multiplier; if network utilization is above ideal, `c` factor will increase, forcing users to pay more. And vice-versa, when network congestion is low, fee multiplier will decrease. +- $length\_fee$ - this is part of the fee related to the transaction length (number of bytes). +- $rent\_fee$ - deposit fee for storing data on chain. Detailed explanation of rent fee calculation in case of Wasm transactions can be found under the [in the Build section](/docs/build/build-on-layer-1/smart-contracts/wasm/transaction-fees.md#storage-rent). +- $tip$ - extra payment transaction submitter pays to ensure their transaction gets included faster into a block. + +Native fees are inherently dynamic using the fee multiplies `c` which is calculated in each block using the following formulas: + +$$ +\begin{align} +c_{n} &= c_{n-1} * (1 + adjustment + \frac{adjustment^2}{2}) +\\ +adjustment &= v * (s - s^*) +\\ +s &= \frac{block\_weight}{max\_block\_normal\_dispatch\_weight} +\end{align} +$$ + +with several configuration parameters: + +- $s*$ - ideal block fullness; desired long term average block fullness. +- $v$ - variability factor; controls how fast the adjustment factor changes. If value is small, it will adjust slowly, and if it is large, it will adjust quickly. +- $block\_weight$ - total weight of the previous block. +- $c_{min}$ - the smallest possible value of fee multiplier $c$. +- $c_{max}$ - the largest possible value of fee multiplier $c$. + +and using $s$ to describe current block fullness: + +- If $s > s*$, meaning block fullness if **more** than the ideal, the adjustment will be a positive number. +- If $s < s*$, meaning block fullness is **less** than the idea, the adjustment will be a negative number. + +Based on the network usage (congestion), factor $c$ will either increase or decrease from block to block. If network is used heavily and blocks are full, it will increase, scaling up the weight fee and thus making the transactions more expensive. If network congestion is below the ideal the fee multiplier will decrease, making transactions less expensive. + +## EVM Fees + +Astar is fully Ethereum compatible. This means it also supports Ethereum’s [gas concept](https://ethereum.org/en/developers/docs/gas/). Gas is similar to weight but not quite the same. As a result, Ethereum transaction fees are calculated a bit differently. A simplified formula looks like this + +$$ethereum\_fee = used\_gas * (base\_fee\_per\_gas + priority\_fee\_per\_gas)$$ + +- $used\_gas$ - encapsulates all the resources spent to execute the transaction. +- $base\_fee\_per\_gas$ - how much needs to be paid by the user per unit of gas. +- $priority\_fee\_per\_gas$ - how much is the user tipping each unit of gas. + +Comparing it with the previous example using native fees, it’s clear that Ethereum transactions are less configurable and more information is abstracted from the user. One of the important differences compared to native fee model is the non-existence of rent fees: when storage is created, the price of that storage is included in the gas fee, and even if some storage is removed later on, the user doesn’t receive a refund. + +In order to align fees between two different systems, EVM fee formula for Astar Network is adjusted in a way that $base\_fee\_per\_gas$ becomes a dynamic parameter calculated in each block $n$: + +$$ +\begin{align} +EVM\_fee &= used\_gas * (base\_fee\_per\_gas + priority\_fee\_per\_gas) +\\ +base\_fee\_per\_gas_{n} &= base\_fee\_per\_gas_{n-1} * (1 + adjustment + \frac{adjustment^2}{2}) +\\ +\end{align} +$$ + +with the following configuration parameters: + +- $base\_fee\_per\_gas_{min}$ - the smallest possible value of base_fee_per_gas. +- $base\_fee\_per\_gas_{max}$ - the largest possible value of base_fee_per_gas. + +## Fee Model Parameters + +Values of all the Fee Model parameters are listed in the table below. + +| Parameter name | Value on Shibuya | Value on Shiden | Value on Astar | +| -------------------------------------- | ---------------- | --------------- | --------------- | +| $base\_weight$ | 98974 | 98974 | 98974 | +| $weight_{factor}$ (per byte) | 0.030855 SBY | 0.00030855 SDN | 0.030855 ASTR | +| $length_{factor}$ (per byte) | 0.0000235 SBY | 0.000000235 SDN | 0.0000235 ASTR | +| $max\_block\_normal\_dispatch\_weight$ | 375,000,000,000 | 375,000,000,000 | 375,000,000,000 | +| $s*$ | 0.25 | 0.25 | 0.25 | +| $v$ | 0.000015 | 0.000015 | 0.000015 | +| $c_{min}$ | 0.1 | 0.1 | 0.1 | +| $c_{max}$ | 10 | 10 | 10 | +| $price\_per\_item$ | 0.00004 SBY | 0.0000004 SDN | 0.00004 ASTR | +| $price\_per\_byte$ | 0.000001 SBY | 0.00000001 SDN | 0.000001 ASTR | +| $base\_fee\_per\_gas_{min}$ | 0.0000008 SBY | 0.000000008 SDN | 0.0000008 ASTR | +| $base\_fee\_per\_gas_{max}$ | 0.00008 SBY | 0.0000008 SDN | 0.00008 ASTR | + +The values for the parameters above are set so that EVM fee and the Native fee are equal and equal to 0.5 ASTR or 0.005 SDN for an average weight and length transaction with no rent fee. + +## Rent Fee + +Executing certain on-chain actions can result in additional storage being created. +E.g. if an account decides to create an _identity_, this has to be stored on-chain, whoever is running a node needs to store this piece of information somehow. +To prevent _spamming_, such actions usually incur some _rent_ fee which needs to be _deposited_. +Unlike regular transaction fee, once the storage entry has been removed, the _rent_ fee is also returned to the account. + +For concrete values per entry & per byte, please refer to the table above. + +Some actions which incur _rent_ fee are: + +- creating an identity, including sub-accounts +- creating a multisig call +- creating an asset & metadata (**NOTE: see table below**) +- creating a proxy, announcing proxy calls +- interacting with WASM smart contracts + + +For `pallet-assets` _asset_, creation price is higher than the regular price. +This is because creating an asset carries more _weight_ than simply creating an e.g. _proxy_. +Assets can be registered as cross-chain assets and they can be interacted via precompiles, which makes them usable by any account. + +| Action | Price on Shibuya | Price on Shiden | Price on Astar | +| -------------- | ---------------- | --------------- | -------------- | +| Asset creation | 10 SBY | 10 SDN | 1000 ASTR | diff --git a/docs/about/glossary.md b/docs/about/glossary.md new file mode 100644 index 0000000..8ec14d5 --- /dev/null +++ b/docs/about/glossary.md @@ -0,0 +1,147 @@ +--- +sidebar_position: 5 +--- + +# Glossary + + ### Archive node + A node that stores all historical states of a blockchain between blocks. + + ### ASTR + The native token of Astar. Used for dApp staking. + + ### Ask! + An embedded domain-specific language (eDSL) for writing smart contracts based on AssemblyScript. + + ### Bridge + A mechanism that allows the transfer of assets or data between two different blockchain networks. + + ### Collator + A node that maintains a parachain by collecting parachain transactions and producing state transition proofs for the validators. + + ### Cross-chain + Ability of different blockchain networks to communicate and exchange data or assets with each other, allowing for interoperability and enhancing the functionality and scalability of blockchain ecosystems. + + ### DAO + Short for Decentralized Autonomous Organization, a blockchain-based organization that allows for decentralized decision-making and management by its members. + + ### DApp + A generic term for a decentralized application, that is, one that runs as part of a distributed network as opposed to being run on a specific system or set of systems. + + ### Data Availability + +Often abbreviated to DA, Data Availability refers to a component of modular blockchains that handles off-chain storage of ephemeral-type data that is referenced rarely, though for which availability needs to be guaranteed for historical reference and security purposes. Data Availability systems are highly specialized to provide resilient data storage for sovereign rollups and layer 1 networks. + + ### EVM + Short for Ethereum Virtual Machine. A software environment that executes smart contracts on the Ethereum compatible blockchain networks. + + ### Existential Deposit + The minimum amount of a native token required for an account to exist. If at any point in time the balance drops below the existential deposit amount, it is reaped (balance set to zero) to prevent long-term network bloat. + + ### H160 + An Ethereum format address for Substrate-based blockchains. + + ### HRMP + Short for Horizontal Relay-routed Message Passing. A precursor to the complete XCMP implementation, that mimics the same interface and semantics of XCMP. The plan is to retire HRMP once the implementation of XCMP is complete. + + ### Ink! + An embedded domain-specific language (eDSL) for writing smart contracts based on Rust. + + ### Layer 1 + The underlying infrastructure of a blockchain network, which includes the block production mechanism, the data structure, and the rules for validating transactions. + + ### Layer 2 + Programs built on top of layer 1 such as smart contracts or solutions to improve scalability, reduce transaction costs, and enhance the functionality of the blockchain network. + + ### Light client + A client that does not download the full blockchain, and instead downloads only block headers. Connects to full nodes to query data. + + ### Mainnet + Short for "main network": the fully functional production chain that runs its own network. + + ### Modular Blockchain +A concept of layer 2 scaling. Modular blockchain systems move two or more of the four key blockchain functions off-chain to highly specialized workers dedicated solely to providing specific blockchain functions such as transaction execution or data storage. + + ### Monolithic Blockchain + Like an all-in-one printer/fax/scanner/copier machine, all blockchains are tasked with providing multiple functions: Consensus, Execution, Data Storage, and Settlement, which can be imagined as a vertical, monolithic stack. + + ### Node + A device connected to a blockchain network that stores a copy of the blockchain ledger and participates in validating transactions and maintaining the network's security and integrity. + + ### Optimiums + A concept related to layer 2 scaling. Optimiums combine an off-chain execution environment based on Optimistic rollups with a Data Availability layer, effectively moving three of the four key blockchain functions off-chain, freeing up the need for expensive resources on layer 1, leaving it to perform final settlement, only. + + ### Pallet + A Substrate runtime module. + + ### Parachain + A blockchain that meets several characteristics that allow it to work within the confines of the Polkadot Host. Also known as “parallelized chain”. + + ### Polkadot + A heterogeneous, multi-chain network allowing various blockchains of different characteristics to perform arbitrary, cross-chain communication under shared security. + + ### Relayer + A node that relays messages between different chains in Polkadot. + + ### Rollup + A layer 2 scaling solution that moves the smart contract execution environment either to cryptographically (zero-knowledge-based) or optimistically secured off-chain networks with independent means of consensus. Rollups bundle multiple transactions into one to increase throughput and reduce fees on the underlying layer 1 network. + + ### Sharding + Partition of a blockchain network that allows for parallel processing of transactions to increase scalability and network capacity. + + ### Shiden + The "canary network" for Astar connected to Kusama, a canary network for Polkadot. It consists of an early-release, unaudited version of the Astar codebase. It is not a testnet. For more info refer to the [Networks](/docs/about/networks.md) section. + + ### Shibuya + A testnet for Shiden and Astar. For more info refer to the [Networks](/docs/about/networks.md) section. + + ### Smart Contract + A self-executing computer program that automatically enforces and executes the terms of an agreement between parties on a blockchain network. + + ### SS58 + Standardized format for encoding and decoding account addresses. It stands for Substrate 58, where 58 refers to the base-58 encoding scheme used to encode the address and is used to represent user accounts and public keys in Substrate-based blockchains. + + ### Staking + Allocating tokens to a process with defined objective (e.g. security, elections etc.) and earn rewards on the network. In Astar used to nominate dApps to provide basic income to developers. + + ### Substrate + A modular framework for building blockchains. Astar is built with Substrate. + + ### Swanky Suite + A suite of tools for building Wasm smart contracts on Astar that simplifly compilation, deployment and testing. + + ### Testnet + Short for "test network": an experimental network where testing and development takes place. Networks are often executed on a testnet before they are deployed to a mainnet. + + ### Validium + A concept related to layer 2 scaling. Validiums combine an off-chain execution environment based on zero-knowledge validity proofs with a Data Availability layer, effectively moving three of the four key blockchain functions over to highly specialized workers, freeing up the need for expensive resources on layer 1, leaving it to perform final settlement, only. + + ### Vesting + A mechanism where a certain amount of tokens is released to the owner gradually over a period of time, often used for incentivizing long-term commitments and discouraging short-term speculation. + + ### Wallet + A program that allows one to store private keys and sign transactions for Astar or other blockchain networks. + + ### Wasm + + Also WebAssembly, a language-agnostic, binary instruction format for a stack-based virtual machine. + + ### XC-20 + A standard for cross-chain assets in Polkadot ecosystem with ERC-20 interface. + + ### XCM + Short for Cross-Consensus Messaging, a **messaging format**  and language used to communicate between consensus systems. + + ### XVM + Short for Cross Virtual Machine, a pallet that provides interfaces for smart contracts that run on different virtual machines to interact with each other. + + ### Zero-knowledge proof + A cryptographic protocol that allows one party to prove knowledge of a secret without revealing the secret itself. + + ### zKatana + A testnet for Astar zkEVM. For more info refer to the [Networks](/docs/about/networks.md) section. + + ### Zombienet + A CLI tool to easily spawn ephemeral Substrate-based networks and perform tests against them. + + diff --git a/docs/about/networks.md b/docs/about/networks.md new file mode 100644 index 0000000..77fcfe9 --- /dev/null +++ b/docs/about/networks.md @@ -0,0 +1,53 @@ +--- +sidebar_position: 6 +--- + +# Networks +## Overview + +Prior to commencing development it's important to understand the Astar Network family, and choose an appropriate network to deploy on based on what you would like to do. Currently, there are a number of networks available, including the Local network which runs exclusively within your development environment. All networks support EVM RPCs, and Astar Parachain supports Substrate RPC as well. + +![Astar networks](../about/products/img/fig4.jpg) + +## Local Networks + +### Substrate Node +You can clone the Astar repository and run the local node provided, or download the precompiled binary and run it, instead. Both methods are described in the [Nodes](/docs/build/build-on-layer-1/nodes/index.md) section. + +### Swanky Node + +Swanky Node is a Substrate based blockchain configured to enable the smart contract module `pallet-contracts`, and other features that assist local development of Wasm smart contracts. +For more information about Swanky Node, check out the [Swanky Suite](https://docs.astar.network/docs/build/build-on-layer-1/smart-contracts/wasm/swanky-suite/) section. [INSERT PROPER LINK] + +### Zombienet + +With Zombienet users can download arbitrary Relay Chain and parachain binaries (or use images) to setup a configurable local test network. Users will have access to all privileged actions on the Relay Chain and parachains, which simplifies testing. For more information about Zombienet, check out the [Build Environment](https://docs.astar.network/docs/build/environment/zombienet-testing) chapter. [INSERT PROPER LINK] + +## Testnets + +### Shibuya (Substrate) + +Shibuya has nearly the same chain specifications as Shiden & Astar, and provides an ideal environment for developers to test and debug, prior to launching their dApp on mainnet. +Shibuya is running as a parachain of the Tokio Relay Chain, which is managed internally by the Astar team, and supports Shibuya, only, as test parachain. + +The Shibuya native token symbol is SBY. + +To obtain test tokens from the faucet, please visit the Astar Portal and connect to Shibuya. If for any reason the faucet is empty, please contact the Astar team on Discord. + +## Mainnets + +Astar has three mainnets. One parachain on Kusama, One parachain on Polkadot, and a zkEVM-based network on Ethereum Layer 2. + +### Shiden Parachain (Substrate) + +Shiden is a parachain connected to the Kusama Relay Chain, and used to deploy and test new releases of Astar runtime in a live production (canary) environment. Shiden is not considered a testnet since SDN has its own tokenomics and value, but is used to validate and stabilize new software releases and upgrades for Astar Network. + +The Shiden native token symbol is SDN. + +### Astar Parachain (Substrate) + +By now you may have guessed that Astar parachain is connected to Polkadot Relay chain. + +The Astar native token symbol is ASTR. + + diff --git a/docs/about/products/astar-portal/index.md b/docs/about/products/astar-portal/index.md new file mode 100644 index 0000000..1d6924c --- /dev/null +++ b/docs/about/products/astar-portal/index.md @@ -0,0 +1,7 @@ +--- +title: Astar Portal +--- + +# Overview + +About Astar Portal. [INSERT] \ No newline at end of file diff --git a/docs/about/products/astar-portal/troubleshooting.md b/docs/about/products/astar-portal/troubleshooting.md new file mode 100644 index 0000000..b32ef2f --- /dev/null +++ b/docs/about/products/astar-portal/troubleshooting.md @@ -0,0 +1,36 @@ +--- +sidebar_position: 16 +--- + +# Portal Troubleshooting Guide + +This section will guide you to troubleshoot and solve most issues when connecting to the portal. + +## Can't Connect Wallet To The Portal + +**Allow Polkadot.js to access the portal** +1. Go to Polkadot.js browser extension. +2. Click on the `Gear` icon. +3. Click on `Manage Website Access`. +4. Make sure `https://portal.astar.network` is allowed. + +**Allow Polkadot.js to be used on Astar/Shiden** +1. Go to Polkadot.js browser extension. +2. Click on the `3 dots`. +3. On the dropdown menu, select `Allow use on any chain`. +4. If you have other extensions installed, please revoke access of those extensions. + +## Getting Errors Or Unable To Execute Certain Functions +Some of you may be unable to execute certain funtions. Please try these steps. +1. Update metadata (if required). +2. Clear cache, restart browser and connect wallet to the portal again. +3. On the top right corner, switch to a different endpoint. +4. Brave browser is known to give errors. Use Chrome or Firefox instead. +5. Use VPN. + +## Unable To Claim Staking Rewards +1. If you can't claim the staking rewards on the portal. Visit [HERE](https://docs.astar.network/docs/use/user-guides/manual_claim). +2. If the transferrable balance in the wallet is too low, you might not be able to claim the staking rewards. Top up your wallet or turn off `auto-restake` and then claim the rewards. Turning off `auto-restake` reduces the amount of transactions therefore reducing the amount of gas needed. + + +If none of the above is helpful, please contact any of the team members or ambassadors on [Discord](https://discord.gg/2FGq5KqwBh). diff --git a/docs/about/products/dapp-staking/_category_.json b/docs/about/products/dapp-staking/_category_.json new file mode 100644 index 0000000..d5ded3f --- /dev/null +++ b/docs/about/products/dapp-staking/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "dApp Staking V3", + "position": 4 +} diff --git a/docs/about/products/dapp-staking/dapp-staking-faq.md b/docs/about/products/dapp-staking/dapp-staking-faq.md new file mode 100644 index 0000000..314bd78 --- /dev/null +++ b/docs/about/products/dapp-staking/dapp-staking-faq.md @@ -0,0 +1,223 @@ +--- +sidebar_position: 2 +title: dApp Staking V3 FAQ +sidebar_label: dApp Staking FAQ +--- + +import Figure from "/src/components/figure" + +## General Info About Migration From V2 to V3 + +These are major remarks about the migration: + +- All registered dApps will be migrated, no actions required from the owners. +- Staker’s _locked_ tokens will be migrated. +- Stakes **WILL NOT** be migrated, all stakers will need to pick which dApp(s) to stake on again. + - This is required to keep in line with the new _periods_ and stake reset. + - **It’s important for stakers to stake again their tokens to continue earning rewards**. +- Once V3 is deployed, V2 will be removed. + +If any of the terms above are unclear to you (e.g. _staking_ vs _locking_) you can find detailed exaplanation the following sections: + +- [Tokenomics 2.0](/docs/about/economics/index.md) +- [dApp Staking V3 Technical Overview](/docs/about/products/dapp-staking/dapp-staking-protocol.md/) + +### Practical explanation with an example: + +Locking tokens means they become eligible to be used for dApp staking. This is similar (or same) as before in V2. Locked tokens cannot be used to pay transaction fees, cannot be sent to other accounts, etc. + +In V2, both _locking_ & _staking_ were a single action (_stake_) but in V3 they are split. Once V3 is deployed, all stakes (TVL) will be migrated to locked state within dApp Staking. + +This means if `Alice` was _staking_ on dApp `DAPP_1` 3000 ASTR, after the migration, `Alice` will have 3000 ASTR _locked_. But these 3000 ASTR won’t be _staked_ on anything. Instead, `Alice` will need to decide what to stake on (maybe on dApp `DAPP_1` again) and do the 2nd step - _stake_ action. + +In case she doesn’t want to stake anymore, she can _unlock_, which is similar to the old _unbond&unstake_ and wait for the unlocking period to pass (roughly 10 days) before these funds can be freely used again (e.g. transfer to someone else). + +No stakes are getting carried over, but all TVL is getting carried over. + +## For Stakers + +### Q: What is staking? + +Staking means *voting* for or *nominating* a dApp to receive rewards. + +User's stake on a dApp must be equal or greater than the MinimumStakeAmount (**50 SDN or 500 ASTR**). + +### Q: How do I participate in dApp Staking? + +You can stake on your favorite dApp(s) on [Astar Portal](https://portal.astar.network/astar/dapp-staking/discover). + +The user-friendly interface will allow you to track how many tokens you have available to stake, your stakes, accumulated rewards, current phase, and more. You can lock, unlocks, stake, unstake and move your tokens between dApps directly on the Portal. + +There, you can also view information about every dApp, their communities and teams. + +### Q: What does locking the tokens mean? + +Locking up funds essentially means “setting them aside” so they can be used for staking. + +This is just a “status” of a token on a blockchain level. **There's no need for any separate actions to lock your tokens;** it's done automatically when you stake. + +Please notice, that locked funds **NEVER** leave the staker's wallet - it's only not possible to use those funds for fee payments or transferring them. + +In order to participate, user must have a `MinimumLockedAmount` of native currency locked. + +### Q: Does locking bring rewards? + +**❗ Locking doesn't bring any rewards, unless tokens are staked.** + +Your tokens remain **locked**, but **not staked** in the following cases: + +- During the *migration to dApp Staking V3*, when all staked tokens will be unstaked, they will remain locked. In order to withdraw these tokens, you should initiate the unlocking process (that lasts 10 days). +- The same will happen at the *beginning of each period*. As explained in the article, at the beginning of each period all tokens will be unstaked, but they will remain locked. Same as during migration, you will be able to re-stake them, or initiate the unlocking process. +Please remember that you have to stake during these phases to continue getting rewards. + +### Q: How do I unstake my tokens? + +You can unstake tokens at any time without a specific process, but **unstaking during an era excludes those tokens from that era's reward calculation**. + +Unstaking reduces the staked amount immediately for both the current and next eras. Similar to staking, you must claim all unclaimed rewards before you can unstake. + +### Q: How do I unlock my tokens? + +You can unlock your tokens whenever you choose. Unlocking your tokens also automatically unstakes them from any dApp they are staked on, so there is no need for a separate unstaking action. + +The tokens will have to go through the unlocking process that will be initiated *automatically*. This is a common mechanism to mitigate selling pressure. + +**There's no need for any separate actions to initiate the unlocking of your tokens.** + +Once unlocking is complete, you can then withdraw these tokens to your free balance. + +### Q: When will I start getting rewards after I stake? + +If you stake during the dedicated **Voting Subperiod**, you qualify for bonus rewards as long as you maintain or increase your staked amount during the following Build&Earn Subperiod. Bonus rewards can be claimed after the period ends. + +If you stake during any era of **Build&Earn Subperiod**, the staked amount is only eligible for rewards from the next era onward. + +### Q: When can I claim my rewards? + +You can get rewards for the eras in which the tokens were staked fully (the whole eras). + +Rewards are only claimable for completed eras and can be accumulated. However, if you decide to stake more, you must claim all your rewards first. + +Generally, it’s recommended to claim your rewards once a week. + +### Q: What are bonus rewards? + +If a staker staked on a dApp during the `Voting` Subperiod and **keeps the same staked amount or higher** on a dApp through the whole `Build&Earn` Subperiod, they are eligible for the bonus rewards. + +### Q: Can my rewards expire? + +Unclaimed rewards will eventually expire, so it's important to claim them in time or they'll miss out on earnings. + +We encourage stakers’ engagement. This way, failing to actively revisit dApp staking at the start of each new period to select dApps for staking means missing out on bonus rewards and earnings. + +### Q: What happens to my rewards if the project I'm staking on is unregistered from dApp Staking? + +If a project is unregistered from dApp Staking, tokens staked on that project will still receive basic rewards for as long as the tokens remain staked. Users will still be able to receive their unclaimed rewards. + +However, we recommend that you claim all your rewards and stake on a new project, as it's important to support builders. + +### Q: What About Unclaimed Rewards from dApp Staking V2? + +Once V3 is launched, all of the unclaimed V2 rewards will become inaccessible. Please do your best to claim the rewards yourself, and encourage others to do the same. + +However, to prevent users from loosing long accumulated rewards, a special state will be introduced into V2: **Decommission Mode** during which it will be possible that someone else can claim other stakers' rewards (and pay fees). + +:::note + +**Example:** +Using the special calls, anyone will be able to claim rewards for anyone else. E.g. `Alice` can claim rewards for `Bob` - this essentially means that `Alice` pays for the transaction fee to claim `Bob's`. Of course, `Bob's` rewards are deposited into his account, not `Alice's`. + +::: + +Astar team will ensure that all pending rewards are claimed during the decommissioning. We won’t launch V3 until all unclaimed rewards have been claimed. + +:::info +Please refer to [this Astar Forum discussion](https://forum.astar.network/t/dapp-staking-migration-from-v2-to-v3/5807) for all the details regarding unclaimed rewards. +::: + +### Q: What should you do to prepare for dApp Staking V3 migration? + +*All you should do to prepare for dApp Staking V3 launch is to claim your rewards.* Nothing else is required from your side. + +**❗ Staker’s locked tokens will be migrated, but stakes WILL NOT.** + +As a staker, you will need to pick which dApp(s) to stake on again. **It’s important to do so to continue earning rewards.** + +### Q: I've staked 16 dApps and now I can't add or move tokens and I'm getting an error. What should I do? + +
+ +An address can stake on a maximum of 16 contracts (dApps). +- You must unstake all your tokens from one of these dApps, so that you'll be staking on 15 dApps instead of 16. +- You can then add more tokens in staking or move your staked tokens. + +## For Developers + +### Q: How can I participate? + +The process of application and registration for dApps will not change. + +Please, find more information here: + +- Requirements: https://docs.astar.network/docs/about/products/dapp-stakingfor-devs/requirements; +- Registration: https://docs.astar.network/docs/about/products/dapp-stakingfor-devs/register-dapp. + +***❗ Once the dApp has been registered, stakers can stake on it immediately, and the dApp can earn rewards from the era in which it was registered.*** + +### Q: How do I manage my dApp & claim rewards? + +When you participate in dApp Staking, you have all the information about your dApp available on [Astar Portal](https://portal.astar.network/astar/dapp-staking/discover), in *“Your Project”* tab. + +There you can find your current tier, number of stakers, total earned (total stakes) and your rewards. + +### Q: How are dApps assigned to tiers? + +At the end of each **Build&Earn** Subperiod, dApps are assigned to a tier based on the total value staked on them by users. There are *4 tiers*. + +The threshold for tier 4 is fixed, while it is dynamic for the other tiers. + +### Q: Is the amount of dApp Staking rewards fixed per dApp? + +Rewards for dApps are **dynamic** (tier-dependent), meaning they change from one tier to another. + +The rewards of a tier are split evenly among all its slots, ensuring equal rewards for each dApp within a tier, regardless of whether all slots are filled. + +### Q: What happens to my rewards if my project is unregistered from dApp Staking? + +In the event that a dApp is unregistered from dApp Staking, all developer unclaimed rewards will become unavailable. We recommend that dApp owners claim their rewards regularly. + +### Q: We are a dApp participating in dAppStaking V2, What do we need to do? + +Inform your community and stakers that they should be active once dApp Staking V3 goes live and support your project by staking. + +## For Ledger Users + +### Q: I am a Ledger Astar Native App User, what do I need to do? + +:::danger +For Ledger users who use the native account ([Astar Native App](https://support.ledger.com/hc/en-us/articles/10971402968733-Astar-ASTR)), dApp staking V3 will be temporarily unavailable. +::: + +This is due to how Ledger app works & what is currently being developed. + +Ledger users will still be able to withdraw funds from dApp staking, they only won’t be able to stake & claim rewards in the new protocol version. + +**Why this limitation?** +Ledger is currently developing a new generic app for all Polkadot/Kusama parachains, and that should be available soon (within months). Once that’s available, Ledger native users will be able to participate in dApp staking V3. + +**What can I do right now?** +If you wish to actively participate in dApp Staking v3 from the start, you should [initiate the unbonding period immediately](https://docs.astar.network/docs/about/products/dapp-stakingdapp-staking-v2/unbonding) and move your funds to either an Astar EVM Account supported by Ledger (see below), or move funds to a hot wallet. + +:::info +It is possible that by the dApp staking v3 launch Ledger generic app will be available, completely removing this limitation. + +Keep an eye out on this page and official announcement channels for more info as it becomes available. +::: + +### Q: I am a Ledger Astar EVM App User, what do I need to do? + +All users using Astar EVM Ledger App ([Astar EVM](https://support.ledger.com/hc/en-us/articles/5555310160669-Astar-EVM-ASTR)) users, there are not limitations moving to dApp Staking V3. You will be able to participate in dApp staking V3 immediately. + +### Still got a question? + + Ask us a question via [Discord](https://discord.com/invite/astarnetwork) or [Stack Exchange](https://substrate.stackexchange.com/questions/tagged/astar) (please use tag Astar). diff --git a/docs/about/products/dapp-staking/dapp-staking-protocol.md b/docs/about/products/dapp-staking/dapp-staking-protocol.md new file mode 100644 index 0000000..7c9fb45 --- /dev/null +++ b/docs/about/products/dapp-staking/dapp-staking-protocol.md @@ -0,0 +1,347 @@ +--- +sidebar_position: 1 +title: dApp Staking v3 Technical Overview +--- + +## Introduction + +Astar and Shiden networks provide a unique way for developers to earn rewards by developing products that native token holders can decide to support. + +The principle is simple - stakers _lock_ their tokens to _stake_ on a dApp, and if the dApp attracts enough support, it is rewarded in native currency, derived from the inflation. +In turn stakers are rewarded for locking & staking their tokens. + +The following chapters will provide an overview of the functionality and terminology with accompanying examples. + +## Functionality Overview + +### Eras + +Eras are the basic _time unit_ in dApp staking and their length is measured in the number of blocks. + +Eras are not expected to last long, e.g. current production networks era length is roughly 1 day (7200 blocks). +After an era ends, it's usually possible to claim rewards for it, if staker or dApp are eligible. + +### Periods + +Periods are another _time unit_ in dApp staking. They are expected to be more lengthy than eras. +Each period is denoted by a number, e.g. **1**, which increments each time a new period begins. + +Each period consists of two subperiods: + +* `Voting` +* `Build&Earn` + +Period beginning is marked by the `Voting` subperiod, after which follows the `Build&Earn` subperiod. + +Stakes are **only** valid throughout a period. When new period starts, all stakes are reset to **zero**. Protocol dynamic prevents inactive projects having high stakes due to inertia of stakers while at the same time allows more visibility for dApps joining the protocol and equal chance in attracting stakers' attention. + +Even though stakes are reset, locks (or freezes) of tokens remain. + +#### Voting Subperiod + +When `Voting` subperiod starts, all _stakes_ are reset to **zero**. +Projects participating in dApp staking are expected to market themselves to (re)attract stakers. + +Stakers must assess whether the project they want to stake on brings value to the ecosystem, and then `vote` for it (or _stake_ on it). +Casting a vote, or staking, during the `Voting` subperiod makes the staker eligible for bonus rewards. so they are encouraged to participate during this time. + +`Voting` subperiod length is expressed in _standard_ era lengths, even though the entire voting subperiod is treated as a single _voting era_. +E.g. if `Voting` subperiod lasts for **5 eras**, and each era lasts for **100 blocks**, total length of the `Voting` subperiod will be **500** blocks **BUT** it will consume only a single numeric era: + +* Block 1, Era 1 starts, Period 1 starts, `Voting` subperiod starts +* Block 501, Era 2 starts, Period 1 continues, `Build&Earn` subperiod starts + +Neither stakers nor dApps earn rewards during the `Voting` subperiod; rewards are only generated for eras in the `Build&Earn` subperiod. However, as mentioned before, it’s crucial for dApps to use this time to market themselves and attract stakers, and for stakers to assess which projects they want to support. + +It is important to award projects which the staker believes will bring value to the network and possibly themselves. +Voting on a poor project means that poor performance is rewarded, damaging the network instead of improving it. + +#### Build&Earn + +`Build&Earn` subperiod consists of one or more eras. +E.g. if `Build&Earn` subperiod lasts for **10 eras**, and each era lasts for **100 blocks**, these **10 eras** would consume **1000 blocks** in total. + +After each _era_ ends, eligible stakers and dApps can claim the rewards they earned. + +Rewards are **only** claimable for the finished eras. +E.g. if the **era 3** is ongoing, staker can claim rewards for **era 2** if they were eligible. + +Staker is **only** eligible for rewards **if** they have been staking for the entire era. E.g. if staker stakes in **era 2**, they are only eligible for rewards +from **era 3**, which can be claimed from **era 4** onwards. + +Even though `Build&Earn` comes after the `Voting`, it is still possible to _stake_ during this period, and stakers are encouraged to do so +since this will increase the staker rewards they earn. +The only exemption is the **final era** of the `Build&Earn` subperiod - it's not possible to _stake_ then since the stake would be invalid anyhow (stake is only valid from the next era which would be in the next period when all stakes are reset to _zero_). + +To continue the previous example where era length is **100** blocks, let's assume that `Build&Earn` subperiod lasts for 10 eras: + +* Block 1, Era 1 starts, Period 1 starts, `Voting` subperiod starts +* Block 501, Era 2 starts, Period 1 continues, `Build&Earn` subperiod starts +* Block 601, Era 3 starts, Period 1 continues, `Build&Earn` subperiod continues +* Block 701, Era 4 starts, Period 1 continues, `Build&Earn` subperiod continues +* ... +* Block 1401, Era 11 starts, Period 1 continues, `Build&Earn` subperiod enters the final era +* Block 1501, Era 12 starts, Period 2 starts, `Voting` subperiod starts +* Block 2001, Era 13 starts, Period 2 continues, `Build&Earn` subperiod starts + +### dApps & Smart Contracts + +#### Registration + +Projects, or _dApps_, must be registered into protocol to participate. +Only a privileged origin can perform dApp registration. +At the moment of writing this, dApps & projects can request to be registered via Astar's forum. + +Once the dApp has been registered, stakers can stake on it immediately, and it can earn rewards from the era in which it was registered. + +There is a limit of how many smart contracts can be registered at once. Once the limit is reached, any additional attempt to register a new contract will fail. +This puts an upper bound on how many contracts the protocol can support. + +#### Reward Beneficiary & Ownership + +After a dApp has been registered, it is possible to modify reward beneficiary or even the owner of the dApp. The owner can perform reward delegation and can further transfer ownership. + +This is useful if dApp owners want to deposit rewards and/or transfer ownership to a DAO or a multisig account. + +#### Unregistration + +dApp can be removed from the protocol by unregistering it. +This is an action that can only be done by a privileged origin. +Unregistration can be the result of bad performance, reorganization or any other reason +which governance decides it's viable. + +After a dApp has been unregistered, it's no longer eligible to receive rewards. +Past rewards also become unavailable, if they haven't been claimed already. + +### Stakers + +#### Locking Tokens + +In order for users to participate in dApp staking, the first step they need to take is lock (or freeze) some native currency. Reserved tokens cannot be locked, but tokens locked by another lock can be re-locked into dApp staking (double locked). + +This is useful for _vested_ tokens, which although cannot be transferred to another account, can still be used to participate in dApp staking. + +:::note +Locked funds **NEVER** leave the staker's wallet - it's only not possible to use those funds for fee payment or for transfer. +::: + +In order to participate, user must have a `MinimumLockedAmount` of native currency locked. This doesn't mean that they cannot lock _less_ in a single call, but total locked amount must always be equal or greater than `MinimumLockedAmount`. + +E.g. if an account isn't participating in dApp staking and threshold is set to **10 ASTR**, attempting to lock **9 ASTR** will fail. +However, if user already has **10 ASTR** locked, they can safely lock an additional **1 ASTR**, for **11 ASTR locked in total. + +In case amount specified for locking is greater than what user has available, only what's available will be locked - it's not possible to lock more than what's available. + +Once tokens have been locked, they can be used to stake immediately. +Users should ensure to do so since _locking_ doesn't bring any rewards, unless tokens are staked as well. + +:::note +It's not possible to use the same account for dApp staking & as the collator candidate. +::: + +#### Unlocking Tokens + +User can at any time decide to unlock their tokens. However, it's not possible to unlock tokens which are staked, so user has to unstake them first. + +After _unlock_ is successfully executed, the tokens aren't immediately unlocked, but instead must undergo the unlocking process. +This process takes a predefined amount of blocks to finish. This is a well known & widely used mechanism to reduce selling pressure. + +Once unlocking process has finished, user can _claim_ their unlocked tokens into their free balance. + +There is a limited number of `unlocking chunks` a user can have at any point in time. If limit is reached, user must claim existing unlocked chunks, or wait for them to be unlocked before claiming them to free up space for new chunks. This mechanism exists simply to prevent users from creating unlimited amounts of chunks in storage. + +In case unlocking some amount would take the user below the `MinimumLockedAmount`, **everything** will be unlocked. +E.g. if minimum locked amount is set to **10 ASTR**, user has **15 ASTR** locked, and they decide tu _unlock_ **6 ASTR**, this would take them to **9 ASTR** which is below threshold. As a result, all **15 ASTR** will be unlocked. + +In case users would like to re-lock the _unlocking chunks_ back into the dApp staking protocol, they can easily do that, without having to wait for the unlocking process +to finish. + +#### Staking Tokens + +Locked tokens, which aren't being used for staking, can be used to stake on a dApp. This translates to _voting_ or _nominating_ a dApp to receive rewards derived from the inflation. User can stake on multiple dApps if they want to. + +The staked amount is only eligible for rewards from the next era - in other words, only the amount that has been staked for the entire era is eligible to receive rewards. +E.g. if user had staked **15 ASTR** in **era 5** on a dApp, and decides to stake an additional **5 ASTR**, the new total stake amount of **20 ASTR** is only eligible for rewards from **era 6**. Assuming staker doesn't do additional changes, rewards for **era 5** will be calculated for stake amount of **15 ASTR**, while rewards for **era 6** will be calculated for stake amount of **20 ASTR**. + +It is not possible to stake if there are unclaimed rewards from past eras. User must ensure to first claim their pending rewards, before staking. This is also beneficial to the users since it allows them to lock & stake the earned rewards as well. + +User's stake on a contract must be equal or greater than the `MinimumStakeAmount`. This is similar to the minimum lock amount, but this limit is per contract. +Although user can stake on multiple smart contracts, the amount is limited. To be more precise, amount of database entries that can exist per user is limited. +This should not be a problem in practice though. + +The protocol keeps track of how much was staked by the user in the `Voting` and `Build&Earn` subperiods. This is important for the bonus reward calculation. + +It is not possible to stake on a dApp that has been unregistered. +However, if dApp is unregistered after user has staked on it, user will keep earning +rewards for the staked amount. + +#### Unstaking Tokens + +User can at any time decide to unstake staked tokens. There's no _unstaking_ process associated with this action. +However, unstaking some amount forfeits it from being included in the reward calculation for that era - this is why it's important +to choose staked dApps carefully. + +Unlike stake operation, which stakes from the _next_ era, unstake will reduce the staked amount for the current and next era if stake exists. + +Same as with stake operation, it's not possible to unstake anything until unclaimed rewards have been claimed. User must ensure to first claim all rewards, before attempting to unstake. + +The amount unstaked will always first reduce the amount staked in the ongoing subperiod. E.g. if `Voting` subperiod has stake of **100 ASTR**, and `Build&Earn` subperiod has stake of **50**, calling unstake with amount of **70 ASTR** during `Build&Earn` subperiod will see `Build&Earn` stake amount reduced to **zero**, while `Voting` stake will be reduced to **80**. + +If unstake would reduce the staked amount below `MinimumStakeAmount`, everything is unstaked. + +Once period finishes, all stakes are reset back to zero. This means that no unstake operation is needed after period ends to _unstake_ funds - it's done automatically. + +#### Claiming Staker Rewards + +Stakers can claim rewards for passed eras during which they were staked for the entire duration of the era. +Even if multiple contracts were staked, claim reward call will claim rewards for all of them. + +Only rewards for the finished eras can be claimed. It is possible to claim rewards for multiple eras using a single call. This can happen if staker hasn't claimed rewards in some time, and many eras have passed since then, accumulating pending rewards. There is a limit on how many rewards can a single call claim, so if a lot of rewards have accumulated, it's possible that multiple claim calls will be required to claim all of the pending rewards. + +Rewards don't remain available forever, and if not claimed within some time period, they will be treated as expired. This will be a longer period, but will still exist. + +Rewards are calculated using a simple formula: + +$staker\_reward = \frac{staker\_reward\_pool * staker\_staked\_amount}{total\_staked\_amount}$ + +#### Claiming Bonus Reward + +If staker staked on a dApp during the `Voting` subperiod, and didn't reduce their staked amount below what was staked at the end of the `Voting`` subperiod, this makes them eligible for the bonus reward. + +E.g. if staker had staked **10 ASTR** during the `Voting` subperiod, once `Build&Earn` subperiod starts, they can stake & unstake as much as they want as long as they don't reduce the `Voting` subperiod stake below **10 ASTR**. +It is ok to stake an additional **30 ASTR**, and then unstake **5 ASTR**, because such order of operations would leave the staker with **10 ASTR** staked in the `Voting` subperiod & **25 ASTR** staked in the `Build&Earn` subperiod. +However, if user was to stake an additional **30 ASTR** in the `Build&Earn` subperiod, but would unstake **31 ASTR**, this would put the stake amount in `Build&Earn` subperiod to **zero**, and reduce `Voting` subperiod stake amount to **9 ASTR**. This would mean user is no longer eligible for the bonus rewards. + +Bonus rewards need to be claimed per contract, unlike staker rewards. + +Bonus reward is calculated using a simple formula: + +$bonus\_reward = \frac{bonus\_reward\_pool * staker\_voting\_subperiod\_stake}{total\_voting\_subperiod\_stake}$ + +### Developers + +Main thing for developers to do is develop a good product & attract stakers to stake on them. + +#### Claiming dApp Reward + +If at the end of a `Build&Earn` subperiod era dApp has high enough score (support) to enter a reward tier, it will get rewards assigned to it. +Rewards aren't paid out automatically but must be claimed instead, similar to staker & bonus rewards. + +dApp reward is calculated based on the tier in which ended. All dApps that end up in one tier will get the exact same reward. + +### Tier System + +At the end of each `Build&Earn` subperiod era, dApps are evaluated using a simple metric - total value staked on them. +Based on this metric, they are sorted, and assigned to tiers. + +There is a predefined limited number of tiers, and each tier has a limited capacity of slots. +Each tier also has a _threshold_ which a dApp must satisfy in order to enter it. + +#### Tiers Capacity + +There is a limited amount of slots for dApps which means dApps have to compete for them. +The amount isn't static but is recalculated at the start of each period. + +Since the purpose of dApp staking isn't for dApps to earn obscene amounts of rewards, but to provide +support to operate and further develop existing dApp, number of slots is scaled with the value of **ASTR** expressed in **USD**. + +At the beginning of **each era**, using the _moving average_ **ASTR** price, new number of slots is calculated: + +$ number\_of\_slots_{Astar} = floor(1000 * ASTR_{USD} + 50)$ + +This approach means that as **ASTR** value increases, so does the number of slots for dApp staking, and vice-versa. + +Once number of slots is calculated, it is divided up into slots per tier. +The portions are statically configured, e.g. _tier 1_ gets **10%** of the slots, _tier 2_ gets **25%** of the slots, and so on. + +Same principle is applied to Shiden, but with a slightly modified formula: + +$ number\_of\_slots_{Shiden} = floor(100 * SDN_{USD} + 50)$ + +These formulas were designed with a _baseline_ price in mind. +Using the _baseline_ price, the _baseline_ number of slots can be calculated. + +This value is important since it's used as a reference when calculating tier threshold adjustment. + +#### Tier Threshold Entry + +A dApp isn't entitled to a tier by just participating in the dApp Staking. +It needs to attract sufficient support to even be eligible for entry into a tier. + +E.g. a threshold to enter _tier 1_ might be set to **1,000,000 ASTR**. +Since number of slots is dynamic, so has to be the threshold to allow for more realistic competition. +It's not fair to define the same threshold for entering a tier if there are 50 slots or 500 slots since the +staked amount will be more diluted between various dApps. + +The formula for adjusting tier entry threshold: + +$\Delta\%_{threshold} = (\frac{100\%}{100\% + \Delta\%_{dApps}} - 1) * 100\%$ + +where $\Delta\%_{dApps}$ is the change in the number of dApps, expressed as a percent. In case number has been reduced, the _delta_ will be negative. +The comparison is always done between the _baseline_ number of slots and the new number of slots. + +$new\_threshold = base\_threshold * (1 + \Delta\%_{threshold})$ + +At the moment, there are two types of tier entry thresholds: + +* `Dynamic` - adjusts the threshold based on the aforementioned formula. +* `Fixed` - defines a static, fixed threshold which doesn't adapt. + +The `Dynamic` threshold is used for _higher_ tiers, and also defines the minimum amount to which the threshold can fall. +E.g. a threshold might define _current_ value as **1,000,000 ASTR**. Since this can be decreased if number of slots goes up, +it also defines a minimum amount the threshold can take, e.g. **500,000 ASTR**. + +The `Fixed` threshold is used for the _lowest tier_, and defines a static value. + +#### Tier Rewards + +Better tiers bring bigger rewards, so dApps are encouraged to compete for higher tiers and attract staker's support. +dApp reward pool is divided between tiers, e.g. _tier 1_ gets **40%** of the total reward pool, and the assigned tier reward pool +is further divided between the dApps in the pool. + +This means that each dApp within a tier always gets the same amount of reward. +Even if tier capacity hasn't been fully taken, rewards are paid out as if they were. + +For example, if _tier 1_ has capacity for 10 dApps, and reward pool is **500 ASTR**, it means that each dApp that ends up +in this tier will earn **50 ASTR**. Even if only 3 dApps manage to enter this tier, they will still earn each **50 ASTR**. +The rest, **350 ASTR** in this case, won't be minted. + +#### More On Tiers + +If there are more dApps eligible for a tier than there is capacity, the dApps with the higher score get the advantage. +dApps which missed out on a higher tier get priority for entry into the next lower tier (if there still is any). + +In the case a dApp doesn't satisfy the entry threshold for any tier, even though there is still capacity, the dApp will simply +be left out of tiers and won't earn **any** reward. + +In a special and unlikely case that two or more dApps have the exact same score and satisfy tier entry threshold, but there isn't enough +leftover tier capacity to accommodate them all, this is considered _undefined_ behavior. Some of the dApps will manage to enter the tier, while +others will be left out. There is no strict rule which defines this behavior - instead dApps are encouraged to ensure their tier entry by +having a larger stake than the other dApp(s). Technically, at the moment, the dApp with the lower `dApp Id` will have the advantage over a dApp with +the larger Id but this can change in the future. + +### Reward Expiry + +Unclaimed rewards aren't kept indefinitely in storage. Eventually, they expire. +Stakers & developers should make sure they claim those rewards before this happens. + +In case they don't, they will simply miss on the earnings. + +However, this should not be a problem given how the system is designed. +There is no longer _stake&forget_ - users are expected to revisit dApp staking at least at the +beginning of each new period to pick out old or new dApps on which to stake on. +If they don't do that, they miss out on the bonus reward & won't earn any staker rewards. + +### Oracle Price Feed + +Tier slots, thresholds and rewards need to be adjusted for the native currency price. This has been mentioned in previous chapters. E.g. if price of the **ASTR** goes up, the protocol can accommodate more dApps, and vice-versa. + +This is done in multiple steps: + +1. Permissioned oracle feeds the native currency price on-chain. +2. Price is aggregated over the defined time period (e.g. the entire day), and average value is calculated. +3. Aggregated price is stored into a circular buffer used to calculate moving average. +4. dApp staking tier configuration re-calculation relies on the moving average price. + +The _moving-average_ approach is utilized to soften the impact of crypto's high price volatility. +It's important to keep the _window_ small enough to be able to react to price changes in timely manner, but long enough to _dampen_ sudden & temporary spikes. diff --git a/docs/about/products/dapp-staking/for-devs/_category_.json b/docs/about/products/dapp-staking/for-devs/_category_.json new file mode 100644 index 0000000..436baed --- /dev/null +++ b/docs/about/products/dapp-staking/for-devs/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "For Devs", + "position": 2 +} diff --git a/docs/about/products/dapp-staking/for-devs/create-promotion.md b/docs/about/products/dapp-staking/for-devs/create-promotion.md new file mode 100644 index 0000000..9f79c4e --- /dev/null +++ b/docs/about/products/dapp-staking/for-devs/create-promotion.md @@ -0,0 +1,33 @@ +--- +sidebar_position: 4 +--- + +import Figure from '/src/components/figure' + +# Create a promotion card on top page + +If you have a campaign or new product you would like to share in the community, this will help you spread the news. It will create a card which will be shown on the top of the dApp Staking page as well as the Portal asset page. + +You can create a PR once a month, at most. + +
+ +# Steps for creating a PR for the promotion card + +- Fork our [astar-apps](https://github.com/AstarNetwork/astar-apps) repository. + +- Find a file [dapp_promotion.json](https://github.com/AstarNetwork/astar-apps/blob/main/src/data/dapp_promotions.json) and put a promotion details there. + +- add a promotion image to [public/images/dapp_promotions](https://github.com/AstarNetwork/astar-apps/tree/main/public/images/dapp_promotions) folder. + +- Create a PR to the release-hotfix branch in [astar-apps](https://github.com/AstarNetwork/astar-apps). + + +:::info +- **Image must be 16:9 and recommended size is less than 1MB**. +- **Description is limited to 65 characters maximum**. +- Your PR will be merged after being reviewed by the dApp Staking operation team. +- Card can be removed at any time, for any reason, at the discretion of the operation team. +- Multiple PRs or more than one PR within a month from the same team will not be approved. +::: + diff --git a/docs/about/products/dapp-staking/for-devs/img/Polkadotjs_1.png b/docs/about/products/dapp-staking/for-devs/img/Polkadotjs_1.png new file mode 100644 index 0000000..d92b9ba Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Polkadotjs_1.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Polkadotjs_2.png b/docs/about/products/dapp-staking/for-devs/img/Polkadotjs_2.png new file mode 100644 index 0000000..792166e Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Polkadotjs_2.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Polkadotjs_3.png b/docs/about/products/dapp-staking/for-devs/img/Polkadotjs_3.png new file mode 100644 index 0000000..95cfd1d Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Polkadotjs_3.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Polkadotjs_4.png b/docs/about/products/dapp-staking/for-devs/img/Polkadotjs_4.png new file mode 100644 index 0000000..a750ca1 Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Polkadotjs_4.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Project.png b/docs/about/products/dapp-staking/for-devs/img/Project.png new file mode 100644 index 0000000..f9186d5 Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Project.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Promotion_card_1.png b/docs/about/products/dapp-staking/for-devs/img/Promotion_card_1.png new file mode 100644 index 0000000..cbe3471 Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Promotion_card_1.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Promotion_card_2.png b/docs/about/products/dapp-staking/for-devs/img/Promotion_card_2.png new file mode 100644 index 0000000..a9a2fd8 Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Promotion_card_2.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Promotion_card_3.png b/docs/about/products/dapp-staking/for-devs/img/Promotion_card_3.png new file mode 100644 index 0000000..b26316d Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Promotion_card_3.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Registration_1.png b/docs/about/products/dapp-staking/for-devs/img/Registration_1.png new file mode 100644 index 0000000..6b37b09 Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Registration_1.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Registration_2.png b/docs/about/products/dapp-staking/for-devs/img/Registration_2.png new file mode 100644 index 0000000..7b47932 Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Registration_2.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Registration_banner.png b/docs/about/products/dapp-staking/for-devs/img/Registration_banner.png new file mode 100644 index 0000000..7ab15cc Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Registration_banner.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Subwallet_1.webp b/docs/about/products/dapp-staking/for-devs/img/Subwallet_1.webp new file mode 100644 index 0000000..9871c06 Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Subwallet_1.webp differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Subwallet_2.webp b/docs/about/products/dapp-staking/for-devs/img/Subwallet_2.webp new file mode 100644 index 0000000..0f5bedd Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Subwallet_2.webp differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Subwallet_3.png b/docs/about/products/dapp-staking/for-devs/img/Subwallet_3.png new file mode 100644 index 0000000..24ed17c Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Subwallet_3.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Talisman_1.webp b/docs/about/products/dapp-staking/for-devs/img/Talisman_1.webp new file mode 100644 index 0000000..4df7df1 Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Talisman_1.webp differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Talisman_2.webp b/docs/about/products/dapp-staking/for-devs/img/Talisman_2.webp new file mode 100644 index 0000000..f6335fb Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Talisman_2.webp differ diff --git a/docs/about/products/dapp-staking/for-devs/img/Talisman_3.webp b/docs/about/products/dapp-staking/for-devs/img/Talisman_3.webp new file mode 100644 index 0000000..fa37c8a Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/Talisman_3.webp differ diff --git a/docs/about/products/dapp-staking/for-devs/img/dApp_owner_page.png b/docs/about/products/dapp-staking/for-devs/img/dApp_owner_page.png new file mode 100644 index 0000000..1086df8 Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/dApp_owner_page.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/dApp_owner_page_2.png b/docs/about/products/dapp-staking/for-devs/img/dApp_owner_page_2.png new file mode 100644 index 0000000..24bc572 Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/dApp_owner_page_2.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/dApp_page.png b/docs/about/products/dapp-staking/for-devs/img/dApp_page.png new file mode 100644 index 0000000..e5fc1c8 Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/dApp_page.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/dApp_page_2.png b/docs/about/products/dapp-staking/for-devs/img/dApp_page_2.png new file mode 100644 index 0000000..4e7c85e Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/dApp_page_2.png differ diff --git a/docs/about/products/dapp-staking/for-devs/img/dApp_rewards.png b/docs/about/products/dapp-staking/for-devs/img/dApp_rewards.png new file mode 100644 index 0000000..d0ecab6 Binary files /dev/null and b/docs/about/products/dapp-staking/for-devs/img/dApp_rewards.png differ diff --git a/docs/about/products/dapp-staking/for-devs/index.md b/docs/about/products/dapp-staking/for-devs/index.md new file mode 100644 index 0000000..5ccbe4f --- /dev/null +++ b/docs/about/products/dapp-staking/for-devs/index.md @@ -0,0 +1,73 @@ +import Figure from "/src/components/figure" + +# For Developers + +## Overview + +Discover [dApp Staking] (/docs/about/products/dapp-staking/), **LINK TO UPDATE** a unique mechanism that allows communities to support their favorite teams by staking ASTR or SDN with them. When staking ASTR or SDN on a dApp, users not only support the development of innovative apps but also receive staking rewards from inflation. + +You can educate yourself more by reading the technical documentation about [dApp Staking] (/docs/about/products/dapp-staking/). **LINK TO UPDATE** + +**Are you a product owner and want to list your dApp in our staking mechanism to earn rewards?** + +Please take the following parameters into consideration and make sure you meet the [requirements](/use/how-to-guides/layer-1/dapp-staking/for-devs/requirements.md): + +:::tip + +Before reading the dApp Staking section for dApp owner, make sure you understand the concept of periods, subperiods and eras, as well as the dApp Staking V3 parameters explained [here] (/docs/about/products/dapp-staking/#period--subperiods). **LINK TO UPDATE** + +::: + +### Tier System and Rewards + +dApp Staking introduces the concept of a tier system for dApps. It's important to fully understand the [tier mechanism] (/docs/about/products/dapp-staking/dapp-staking-protocol#tier-system) before proceeding with dApp Staking application and registration as a dApp owner. **LINK TO UPDATE** + +Currently, there are **4 tiers** with a limited number of slots per tier. Tier capacity for dApp staking is calculated at the start of each period based on the ASTR price as described [here] (/docs/about/products/dapp-staking/dapp-staking-protocol#tier-system). **LINK TO UPDATE** + +The slots allocated to each tier can be viewed on the [dApp Staking Page](https://portal.astar.network/astar/dapp-staking/discover) of the Astar Portal. + +At the end of each **Build&Earn** subperiod, dApps are assigned to a tier based on the total value staked on them by users. Each tier has a **threshold** that a dApp must reach in order to access it. + +The threshold for tier 4 is fixed, but for the other tiers, the threshold is **dynamic** and calculated at the start of each new period based on the total number of slots for the period. To find out more, [click here] (/docs/about/products/dapp-staking/dapp-staking-protocol#tier-threshold-entry). **LINK TO UPDATE** + +**Rewards** for dApps are also **dynamic**, fluctuating from tier to tier. The higher the tier, the greater the number of ASTR tokens allocated from inflation as rewards for that tier. + +The rewards of a tier are divided between all available slots and distributed to the dApps occupying slots. This means that the rewards for dApps within a tier are the same for each dApp, even if not all slots within a tier are occupied. + +*Refer to the [dApp staking parameters] (/docs/about/products/dapp-staking/protocol-parameters#network-values) page to find out more about the tier system and reward allocation.* **LINK TO UPDATE** + +:::tip +You have to claim your rewards to receive them. We recommend that you claim your rewards at least once a week or, optimistically, 2 or 3 times a week. + + ::: + +:::info + +**Example:** + +- Tier 1 has 5 slots for dApps and 50,000 ASTR tokens are allocated as a reward; +- At the end of the voting subperiod, only 3 slots are occupied by dApps in Tier 1 ; +- These 3 dApps will each receive 10,000 ASTR as reward; +- The remaining 20,000 ASTR tokens will not be minted by the network and will be considered burnt; + +::: + +If there are more dApps eligible for a tier than there is capacity, the dApps with the higher score get the advantage. dApps which missed out on a higher tier get priority for entry into the next lower tier (if there still is any). + +In the case a dApp doesn't satisfy the entry threshold for any tier, even though there is still capacity, the dApp will simply be left out of tiers and won't earn any reward. + +:::warning + +In the event that a dApp is **unregistered** from dApp Staking following a governance decision, all developer unclaimed rewards will become unavailable. We recommend that dApp owners claim their rewards regularly. + +::: + +In case you have any questions, please check the [FAQ page] (/docs/about/products/dapp-staking/dapp-staking-faq/) **LINK TO UPDATE** in the Learn section or join our [Discord channel](https://discord.com/invite/astarnetwork). + +### Other pages may be of interest: + +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + + diff --git a/docs/about/products/dapp-staking/for-devs/manage-dApp-Staking.md b/docs/about/products/dapp-staking/for-devs/manage-dApp-Staking.md new file mode 100644 index 0000000..d1da0fe --- /dev/null +++ b/docs/about/products/dapp-staking/for-devs/manage-dApp-Staking.md @@ -0,0 +1,38 @@ +--- +sidebar_position: 3 +--- + +import Figure from "/src/components/figure" + +# Manage dApp & claim rewards + +As a dApp owner, a new panel will appear in the Asset page of the Astar portal: **Your Project** ; + +
+ +By clicking on your dApp in the **Your Project** panel, you will have access to everything related to your dApp, from claiming developer rewards to editing your project information; + +### Your Dashboard: + +- **Curent Tier:** The current tier to which your dApp has been assigned. See [Tier system] (/docs/about/products/dapp-stakingfor-devs/#tier-system-and-rewards) for more information; **LINK TO UPDATE** +- **Number of stakers:** Total of current stakers on your dApp; +- **Total Earned:** Total tokens received in the dApp Staking program; + +
+ +### Your Rewards: + +Here you can see how many tokens you have earned for past periods and what you still have to `claim`; + +
+ +To claim your tokens, click on the **Claim your rewards** button and sign the transaction with your wallet; +Claiming will release all your pending rewards; + +### Edit: + +- **Edit Project Page:** Allows you to edit information about your dApp Staking projects; +- **Edit your owner info:** If you want to change the registered smart contract address and the address receiving developer rewards ; +- **Add a promotion card:** If you are running a campaign, you can create a promotion card that will be added to the dApp Staking section of the Portal after review; + +
\ No newline at end of file diff --git a/docs/about/products/dapp-staking/for-devs/register-dapp.md b/docs/about/products/dapp-staking/for-devs/register-dapp.md new file mode 100644 index 0000000..58abc9a --- /dev/null +++ b/docs/about/products/dapp-staking/for-devs/register-dapp.md @@ -0,0 +1,181 @@ +--- +sidebar_position: 2 +--- + +import Figure from "/src/components/figure" + +# Register dApp + +Once you have been approved by the Astar Council under Astar governance, you can take the following steps: + +## Step 1: Native wallet & Verified Smart-contract + +Before you can register your dApp or project, make sure you have : + +#### 1. An [Astar Native developer wallet] (/docs/use/how-to-guides/layer-1/manage-wallets/create-wallet) with some tokens to cover gas fee. *No Ledger hardware wallet or EVM wallet.* **LINK TO UPDATE** + +You can use one of the following wallets: + +
+**[Polkadot.js](https://chrome.google.com/webstore/detail/polkadot%7Bjs%7D-extension/mopnmbcafieddcagagdcbnhejhlodfdd?hl=en)** *(Recommended)* + +The Polkadot\{.js\} plugin provides a reasonable balance of security and usability. It provides a separate local mechanism to generate your address and interact with the Astar portal. We recommend users who are new to our ecosystem and want to create an Astar native address use this wallet. If you don't have the Polkadot JS extension you will receive a popup in our portal when you try to connect your wallet. + +### Install the Browser Plugin + +The browser plugin is available for both [Google Chrome](https://chrome.google.com/webstore/detail/polkadot%7Bjs%7D-extension/mopnmbcafieddcagagdcbnhejhlodfdd?hl=en) (and Chromium-based browsers like Brave) and [Firefox](https://addons.mozilla.org/en-US/firefox/addon/polkadot-js-extension). After installing the plugin, you should see the orange and white Polkadot\{.js\} logo in your browser menu bar. + +
+ +### Create Account + +Open the Polkadot\{.js\} browser extension by clicking the logo on the top bar of your browser. You will see a browser popup. + +
+ +Click the big plus button `Create new account`. The Polkadot\{.js\} plugin will then use system randomness to make a new seed for you and display it to you in the form of twelve words. + +
+ +You should back up these words. Please, store the seed somewhere safe, secret, and secure. If you cannot access your account via Polkadot\{.js\} for some reason, you can re-enter your seed through the `Add account menu` by selecting `Import account from pre-existing seed`. + +
+ +Best to create an account that is allowed on any chain in the Polkadot ecosystem including Astar or Shiden Network. Your account will automatically change format when connected to a chain. + +A **descriptive name** is arbitrary and for your use only. It is not stored on the blockchain and will not be visible to other users who look at your address via a block explorer. If you're juggling multiple accounts, it helps to make this as descriptive and detailed as needed. + +The **password** will be used to encrypt this account's information. You will need to re-enter it when using the account for any kind of outgoing transaction or when using it to cryptographically sign a message. + +After clicking on `Add the account with the generated seed`, your account is created. We recommend also saving your account as json file somewhere safe. + +
+ +
+**[Talisman](https://www.talisman.xyz/)** + +### Install the Browser Extension + +The extension is available on [chrome](https://chromewebstore.google.com/detail/talisman-ethereum-and-pol/fijngjgcjhjmmpcmkeiomlglpeiijkld?hl=en-GB) and [firefox](https://addons.mozilla.org/en-US/firefox/addon/talisman-wallet-extension/). + + +### Create a New Account + +Once the extension is downloaded you can proceed to setup your account. + +1. In order to set up a wallet, click `New wallet`. + +
+ +2. Add a password for your account and click `Continue`. + +
+ +3. Last step is to decide on allowing anonymous information to help talisman improve the wallet. Click any option and the setup is finished! + +
+ +### Create a new account in video + +

+ +**Don't forget to Back Up Your Secret Phrase! Consult [this guide](https://docs.talisman.xyz/talisman/start/installing-talisman/back-up-your-secret-phrase) if necessary.** + +
+ +
+**[Subwallet](https://www.subwallet.app/)** + +### Install the Browser Extension + +The extension is available on [chrome](https://chromewebstore.google.com/detail/subwallet-polkadot-wallet/onhogfjeacnfoofkfgppdlbmlmnplgbn) and [firefox](https://addons.mozilla.org/en-US/firefox/addon/subwallet/). + +### Create a New Account + +1. After installing SubWallet extension, open the wallet and choose `Create a new account`; + +
+ +2. Create a master password and click `Continue`; + +
+ +3. Keep your recovery phrase (also known as seed phrase or secret phrase) in a safe place; + +
+ +4. Your account has been successfully set up. Click `Exit` to get to Homepage; + +### Create a new account in video + +

+ +
+ +#### Connect your wallet to Astar Portal + +Visit the [Astar Portal](https://portal.astar.network/astar/assets) and connect your wallet. Once signed in, you'll see your native Astar address on the home page. + +Format: `YQnbw3oWxBnCUarnbePrjFcrSgVPP2jqTZYzWcccmN8fXhd` + +#### 2. Deploy a Smart-Contract in our ecosystem and verify the contract in an explorer. + +1. The first option is to use one of your **own smart contracts** and verify it. + +2. The second option is reserved for those who don't handle smart contracts. Deploy our `helloworld.sol` contract and provide all the information in the header of the contract. [Template contract](https://github.com/AstarNetwork/builders-program/blob/main/hellowold.sol). + +The smart contract can be on Astar Native (WASM) or Astar EVM ([Public Endpoints] (/docs/build/environment/endpoints/#public-endpoints)). *(Not on Astar zkEVM)* **LINK TO UPDATE** + +For the explorer, you can use: +- [Subscan](https://astar.subscan.io/) for Astar Native; +- [Blockscout EVM](https://astar.blockscout.com/) for EVM; + +#### 3. Once the vote is passed, share your addresses with the Astar Foundation. + +You can share your **Astar native address** and the **verified smart-contract address** in the discussion of your dApp Staking application on the [Astar Forum](https://forum.astar.network/); + +The Astar Foundation will whitelist your addresses for dApp Staking registration and inform you that you can proceed to step 2. + +## Step 2: Register your dApp on the Astar Portal + +After whitelisting, visit the dApp Staking page on the [Astar portal](https://portal.astar.network/astar/dapp-staking/discover). + +Connect your native wallet and choose the network on which you are going to register for dApp Staking *(Astar Network or Shiden Network)*; + +
+ +If the wallet has been whitelisted, a banner with a `Register Now` button, like the one below, will appear: + +
+ +Click on **Register Now** and fill in the form with all your project details: + +- Name of your dApp or project; +- Logo (Recommended size 512x512 px); +- Contract addres *(automatically filled)*; +- Project URL; +- At least 4 images of your project (Recommended a images with size 16:9 within 1 MB); +- Builders information (person contributing to the project); +- Description of the project; +- Community links; +- Category and tags; + +
+ +
+ +Once you've filled in all your details, click **Next** button and enter the description that will appear on your **New Listing Card**; + +
+ +Finally, click on **Register** and sign the transaction on the network; + +Congratulations! 🎉 Your project is now listed in dApp Staking and you can start your campaign and communication to attract stakers. + +
+ +:::tip + +When your dApp is deployed, we would appreciate it if you shared this with your community. We have created a template that you can use to write the article. You can find it [here](https://astarnetwork.notion.site/dApp-staking-template-Astar-Network-07d029f2d89644f48a17650522968682). + +::: \ No newline at end of file diff --git a/docs/about/products/dapp-staking/for-devs/requirements.md b/docs/about/products/dapp-staking/for-devs/requirements.md new file mode 100644 index 0000000..37a30bf --- /dev/null +++ b/docs/about/products/dapp-staking/for-devs/requirements.md @@ -0,0 +1,80 @@ +--- +sidebar_position: 1 +--- + +import Figure from "/src/components/figure" + +# Requirements + +**Are you a project owner and want to list your dApp in our staking mechanism to earn rewards?** + +Please read these guidelines carefully. If you meet all the requirements, please reach out to us on [Discord](https://discord.com/invite/astarnetwork) or on post your proposal on the [Astar Forum](https://forum.astar.network/). + +:::info + +Astar is aiming to become a DAO in a couple of years. While moving towards becoming a DAO our dApp staking onboarding also includes passing our council. The dApp staking application process is as stated below: +::: + +### Astar Network + +- Your dApp is **launched and live on Astar Network** +- Does your project contribute to Astar TVL? Make sure you are listed on [DefilLama] (/docs/build/integrations/dapp-listing/defillama). **LINK TO UPDATE** +- List your project on [DappRadar] (/docs/build/integrations/dapp-listing/dappradar). **LINK TO UPDATE** +- Your dApp has #astar-network, #dAppStaking tags in your GitHub repo. +- You need to create a PR to the Ecosystem Page. As our website is open-source, you can contribute directly to it - just create a PR on your own! [Here](https://github.com/AstarNetwork/astarwebsite_v2/blob/349db39d724b57f58fbee84b3fa500bf0d29bee6/components/Header.vue) +- If you wish to have your project listed on Astar website [ecosystem page](https://astar.network/community/ecosystem), fill in this [FORM](https://forms.gle/xsGUnCt3fm4isWWF7). +- Create your proposal to join dApp staking on our [forum](https://forum.astar.network/c/initiatives/dapp-staking-applications/21). For creating your proposal, you can take inspiration from the following [template](/use/how-to-guides/layer-1/dapp-staking/for-devs/requirements#template-for-dapp-staking-application). +- After the proposal is created, we will get the community to discuss. You are expected to answer all the questions. This will take around 4-5 days. +- The voting will be opened after the discussion period. +- For now, only the forum members with `Trust Level 2` and above are allowed to vote. +- After the voting is passed, you are should follow the registration instructions in the [Register dApp](/use/how-to-guides/layer-1/dapp-staking/for-devs/register-dapp) page. + +#### What about infrastructure partners? + +You don’t have any dApp but you are providing infrastructure services to the Astar ecosystem. You also can be added to dApp staking. + +- You already have a long-term partnership with Astar and a close relationship with some projects. +- You have a proven record in our ecosystem. +- You have docs about how to use your tools in our documentation and in yours. You can add instructions to our documentation by creating a PR on our Github. +- Create a proposal to join dApp staking on our [forum](https://forum.astar.network/c/initiatives/dapp-staking-applications/21). For creating your proposal, you can take inspiration from the following [template](/use/how-to-guides/layer-1/dapp-staking/for-devs/requirements#template-for-dapp-staking-application). +- After the proposal is created, we will get the community to discuss. You are expected to answer all the questions. This will take around 4-5 days. +- The voting will be opened after the discussion period. +- For now, only the forum members with Trust Level 2 and above are allowed to vote. +- After the voting is passed, you are should follow the registration instructions in the [Register dApp](/use/how-to-guides/layer-1/dapp-staking/for-devs/register-dapp) page. + +#### What about other projects who can't meet the above requirements? + +You can't add your project to DefilLama because it's not generating any TVL, also DappRadar is not an option because there is no use of smart contracts? These are the current steps to follow: + +- Be active in our community Discord channel and post your project updates in our dedicated `#project discussion` channel. +- Create a proposal to join dApp staking on our [forum](https://forum.astar.network/c/initiatives/dapp-staking-applications/21). For creating your proposal, you can take inspiration from the following [template](/use/how-to-guides/layer-1/dapp-staking/for-devs/requirements#template-for-dapp-staking-application). +- After the proposal is created, we will get the community to discuss. You are expected to answer all the questions. This will take around 4-5 days. +- The voting will be opened after the discussion period. +- For now, only the forum members with Trust Level 2 and above are allowed to vote. +- After the voting is passed, you are should follow the registration instructions in the [Register dApp](/use/how-to-guides/layer-1/dapp-staking/for-devs/register-dapp) page. + +### Shiden Network + +- Your dApp is **launched and live on Shiden Network**. +- Does your project contribute to the growth of Shiden it would be great to list your project on DappRadar and or DefilLama. This is not a requirement but it would help grow the trust for your project with our community. +- Infrastructure partners who are contributing to our ecosystem and need to cover their costs can apply to our dApp staking mechanism on Shiden. + +### Template for dApp Staking application + +:::info + +### Title: Project Name - dApp Staking Application + +**Introduction:** Brief introduction of your proposal; +**Project Overview:** Presentation of your project; +**Mission:** What is your mission and what do you want to achieve with your project? You can also share your vision; +**Team:** Introducing the team behind the project and the main contributors. You can share links to personal profiles; +**Security:** Share how you manage the security of your projects and users. You can share audit reports if you have them; +**Past Performance & Milestones:** Describe your latest achievements and the milestones you have reached in your project; +**Roadmap:** Present your plans and the next steps in your project; +**dApp Staking Reward Usage Breakdown:** Describe how you will use the rewards you earn with dApp Staking; +**Appendix:** Links to your projects, products and communities + +Being as specific and detailed as possible in your proposal will help council members to make their decisions, and be sure to answer any questions they may have when discussing your application. + +::: \ No newline at end of file diff --git a/docs/about/products/dapp-staking/for-stakers/_category_.json b/docs/about/products/dapp-staking/for-stakers/_category_.json new file mode 100644 index 0000000..42d07c4 --- /dev/null +++ b/docs/about/products/dapp-staking/for-stakers/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "For Stakers", + "position": 1 +} diff --git a/docs/about/products/dapp-staking/for-stakers/img/1.png b/docs/about/products/dapp-staking/for-stakers/img/1.png new file mode 100644 index 0000000..c70c4b7 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/1.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/14_Myrewards.png b/docs/about/products/dapp-staking/for-stakers/img/14_Myrewards.png new file mode 100644 index 0000000..876d058 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/14_Myrewards.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/15_Unbonding.png b/docs/about/products/dapp-staking/for-stakers/img/15_Unbonding.png new file mode 100644 index 0000000..7ef9836 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/15_Unbonding.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/16_MydApps.png b/docs/about/products/dapp-staking/for-stakers/img/16_MydApps.png new file mode 100644 index 0000000..1587219 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/16_MydApps.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/18_projects.png b/docs/about/products/dapp-staking/for-stakers/img/18_projects.png new file mode 100644 index 0000000..496d837 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/18_projects.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/19_Staking.png b/docs/about/products/dapp-staking/for-stakers/img/19_Staking.png new file mode 100644 index 0000000..7ebb684 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/19_Staking.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/20_unbonding_modal.png b/docs/about/products/dapp-staking/for-stakers/img/20_unbonding_modal.png new file mode 100644 index 0000000..4142ae9 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/20_unbonding_modal.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/21_Re-Stake.png b/docs/about/products/dapp-staking/for-stakers/img/21_Re-Stake.png new file mode 100644 index 0000000..d9c941e Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/21_Re-Stake.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/22_nomination01.png b/docs/about/products/dapp-staking/for-stakers/img/22_nomination01.png new file mode 100644 index 0000000..d8b28b9 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/22_nomination01.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/23_nomination02.png b/docs/about/products/dapp-staking/for-stakers/img/23_nomination02.png new file mode 100644 index 0000000..0e6d5aa Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/23_nomination02.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/24_nomination03.png b/docs/about/products/dapp-staking/for-stakers/img/24_nomination03.png new file mode 100644 index 0000000..b3fb40f Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/24_nomination03.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/8.png b/docs/about/products/dapp-staking/for-stakers/img/8.png new file mode 100644 index 0000000..7330991 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/8.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/MydApps_Panel_1.png b/docs/about/products/dapp-staking/for-stakers/img/MydApps_Panel_1.png new file mode 100644 index 0000000..606d5b7 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/MydApps_Panel_1.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/Networks.png b/docs/about/products/dapp-staking/for-stakers/img/Networks.png new file mode 100644 index 0000000..ffe630c Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/Networks.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/Projects_page.png b/docs/about/products/dapp-staking/for-stakers/img/Projects_page.png new file mode 100644 index 0000000..fc74403 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/Projects_page.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/Staking_Page.png b/docs/about/products/dapp-staking/for-stakers/img/Staking_Page.png new file mode 100644 index 0000000..3f8b392 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/Staking_Page.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/Staking_Page_2.png b/docs/about/products/dapp-staking/for-stakers/img/Staking_Page_2.png new file mode 100644 index 0000000..a2fc9c0 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/Staking_Page_2.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/Staking_Page_3.png b/docs/about/products/dapp-staking/for-stakers/img/Staking_Page_3.png new file mode 100644 index 0000000..8c1a60c Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/Staking_Page_3.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/Staking_Panel_1.png b/docs/about/products/dapp-staking/for-stakers/img/Staking_Panel_1.png new file mode 100644 index 0000000..3da8981 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/Staking_Panel_1.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/Staking_Panel_2.png b/docs/about/products/dapp-staking/for-stakers/img/Staking_Panel_2.png new file mode 100644 index 0000000..f1c04ae Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/Staking_Panel_2.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/Unbonding_1.png b/docs/about/products/dapp-staking/for-stakers/img/Unbonding_1.png new file mode 100644 index 0000000..7c15cea Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/Unbonding_1.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/Unbonding_2.png b/docs/about/products/dapp-staking/for-stakers/img/Unbonding_2.png new file mode 100644 index 0000000..e7954f0 Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/Unbonding_2.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/img/Vote_Page.png b/docs/about/products/dapp-staking/for-stakers/img/Vote_Page.png new file mode 100644 index 0000000..10b9e8b Binary files /dev/null and b/docs/about/products/dapp-staking/for-stakers/img/Vote_Page.png differ diff --git a/docs/about/products/dapp-staking/for-stakers/index.md b/docs/about/products/dapp-staking/for-stakers/index.md new file mode 100644 index 0000000..84a1845 --- /dev/null +++ b/docs/about/products/dapp-staking/for-stakers/index.md @@ -0,0 +1,79 @@ +import Figure from "/src/components/figure" + +# For Stakers + +## Overview + +Do you love to stake? Or do you want to support your favorite project on Astar Network or Shiden Network? + +Discover [dApp Staking] (/docs/about/products/dapp-staking/) **LINK TO UPDATE**, a unique mechanism that allows communities to support their favorite teams by staking ASTR or SDN with them. When staking ASTR or SDN on a dApp, users not only support the development of innovative apps but also receive staking rewards from inflation. + +You can educate yourself more by reading the technical documentation about [dApp Staking] (/docs/about/products/dapp-staking/). **LINK TO UPDATE** + +:::tip + +Before reading the dApp Staking section for stakers, make sure you understand the concept of periods, subperiods and eras, as well as the dApp Staking V3 parameters explained [here] (/docs/about/products/dapp-staking/#understand-the-terminology-and-parameters-of-dapp-staking). **LINK TO UPDATE** + +::: + +### Basic Staking Rewards: + +dApp Staking rewards are generated only if tokens have been staked on a dApp for at least 1 full `Era` and distributed on the following `Era` (Era+1); + +:::tip + +For stakers, if you stake today, you will start earning tomorrow (next era), and the rewards will be distributed the day after tomorrow. +For dApps If you get into a tier today, you will start earning rewards tomorrow (next era) and the rewards will be distributed the day after tomorrow. + +::: + +For stakers, the APR is the same for all stakers, regardless of which dApp they stake on; +For dApps, staking rewards depends on the Tier system, dApps go into rewards tier based on the amount of tokens staked by users. + +Rewards must be claimed before trying to `stake` or `unstake`. +*(If using the Astar Portal, the interface will automatically claim the rewards when trying to stake)* + +If a project is **unregistered** from dApp Staking, staked tokens on that project will still receive **basic rewards** as long as the tokens remain staked. + +:::warning + +There is no rewards during the Unlocking period when unstaking from dApp Staking; + +::: + +### Bonus Staking Rewards: + +If an user stake on dApp(s) during the **Voting Subperiod** and keep the same staked amount or higher on a dApp through the whole **Build&Earn Subperiod**, they will be eligible for the **Bonus Reward** for this dApp. + +:::info + +**Example** + +- User stake 1500 ASTR on **dApp A** and 1000 ASTR on **dApp B** during the `Voting`subperiod. +- During the `Build&Earn` subperiod, user move 500 ASTR from **dApp B** to **dApp A**; +- He now has 2000 ASTR on **dApp A** and 500 ASTR on **dApp B**, so he's still eligible for the `Bonus reward` for **dApp A** but no longer for **dApp B** because the tokens staked on **dApp** B are less than those staked at the end of the `Voting` subperiod (500 < 1000 ASTR). +- To be eligible for the `Bonus reward` for **dApp B**, the user must stake an additional 500 ASTR on **dApp B** to reach 1000 ASTR. + +::: + +Bonus rewards for a period can only be claimed after the period finishes. + + +### Other: + +- You need to keep a minimum of 10 ASTR or 5 SDN tokens as transferable after staking. +- **You need to claim to receive your rewards, we recommend claiming your staking rewards once a week.** +- When unlocking tokens, there is a unlocking period on Astar and on Shiden. The unlocking period lenghts can be consulted [here] (/docs/about/products/dapp-staking/#parameters). **LINK TO UPDATE** +Please note that this is based on a perfect block production of 12s. In case of any delay, your unlocking period can be a little longer. + +In case you have any questions, please check the [FAQ page] (/docs/about/products/dapp-staking/dapp-staking-faq/) **LINK TO UPDATE** in the Learn section or join our [Discord channel](https://discord.com/invite/astarnetwork). + +### Other pages may be of interest: + +
+ +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + + diff --git a/docs/about/products/dapp-staking/for-stakers/manage-dApp-Staking.md b/docs/about/products/dapp-staking/for-stakers/manage-dApp-Staking.md new file mode 100644 index 0000000..441e73c --- /dev/null +++ b/docs/about/products/dapp-staking/for-stakers/manage-dApp-Staking.md @@ -0,0 +1,54 @@ +--- +sidebar_position: 2 +--- + +import Figure from "/src/components/figure" + +# Manage dApp Staking & claim rewards + +Once you have staked, a new panel named **Staking** will appear in the [Assets Page](https://portal.astar.network/astar/assets). + +### My Staking Panel: + +My Staking Panel is where you track your staking and locked tokens, see your pending rewards and take actions with your tokens and rewards; + +- **Locked amount:** Total amount of tokens locked in the address; + - **Unlock (↑):** Unlock your locked tokens *(subject to [unlocking parameters](/use/how-to-guides/layer-1/dapp-staking/for-stakers/unstaking)*); + - **Stake (↓):** Stake your locked tokens in dApp Staking; +- **Staked amount**: Total amount of tokens you have staked; +- **Rewards**: Total of the estimated Basic and Bonus rewards; + - **Available**: Basic estimated rewards earned during the **Build&Earn subperiod**; + - **Bonus:** Bonus estimated rewards earned during the **Vote subperiod** if eligible; + +
+ +To claim your rewards, you need to click on the **Claim Button** and sign the transaction; + +If you have a lot of unclaimed rewards (`Eras`), you may have to make several `Claim` calls to receive all your rewards; + +All pending rewards on a dApp must be claimed before staking again. + +### My dApps Panel: + +My dApps Panel is where you can see all dApps you have staked with and manage your stake. + +- **Bonus:** if you are eligible for the [Bonus](/use/how-to-guides/layer-1/dapp-staking/for-stakers#bonus-staking-rewards) on this dApps; +- **Move (→) :** you can move staked tokens between different dApps; +- **Add (↓) :** you can add more tokens in dApp staking on the desired dApp; +- **Unlock (↑) :** you can select how many tokens you want to unlock from your staked amount. + +
+ +### Unlocking Panel: + +The unlocking panel is where you can see the progress of unlocking and withdrawing. +For the runtime logic, when unlocking, you don’t unlock from a specific dApp but unlock as `Chunks`. First pending unlocking gives Chunk 1, second pending unlocking gives Chunk 2 etc. + +After you have unstaked and when those ERAs pass, you will be able to withdraw. More information about [Unlocking](/use/how-to-guides/layer-1/dapp-staking/for-stakers/unstaking/). +The unlocking period lenghts can be consulted [here] (/docs/about/products/dapp-staking/#parameters). **LINK TO UPDATE** + +- **Remaining days:** The number of days or `Eras` you have to wait before you can withdraw your tokens; +- **Available to withdraw:** Unlock your tokens and make them `transferable`; +- **Re-lock:** Lock your tokens again to use them in dApp Staking; + +
\ No newline at end of file diff --git a/docs/about/products/dapp-staking/for-stakers/move-staked-tokens.md b/docs/about/products/dapp-staking/for-stakers/move-staked-tokens.md new file mode 100644 index 0000000..7e38190 --- /dev/null +++ b/docs/about/products/dapp-staking/for-stakers/move-staked-tokens.md @@ -0,0 +1,28 @@ +--- +sidebar_position: 3 +--- + +import Figure from "/src/components/figure" + +# Move staked tokens between dApps + +Once your tokens have been staked on a dApp, you always have the option of reconsidering your decisions and moving them to another dApp. + +1) Go to the **Staking Panel** in the [Asset Page](https://portal.astar.network/astar/assets); +2) Under **My dApps**, click on the **Move button (→)** of the dApp from which you want to move your tokens. + +
+ +3) Select the dApp(s) to which you want to `Move` your tokens and enter the desired amount; + +
+ +4) Confirm your decisions by clicking on the **Confirm Button** and sign the transaction on the network; + +Bear in mind that when you move tokens from one dApp to another, you are `unstaking` from one dApp to `stake` on a new dApp, which therefore has an impact on your rewards for those dApps: + +- If you move tokens from a dApp and your staked tokens are less than the [minimum staking] (/docs/about/products/dapp-staking/#parameters) amount for a dApp, all your tokens will be `unstaked` from that dApp; **LINK TO UPDATE** +- If you move your tokens from one dApp to another, you'll lose the **basic staking rewards** for the current `Era` for the dApp you moved, and you won't earn rewards on the new dApp until the next `Era`; +- During the Build&Earn subperiod, if you move your tokens from one dApp to another and your staked tokens on the initial dApp at the end of the **Build&Earn subperiod** are less than your staked tokens at the end of the **Voting subperiod** for the same dApp, you will no longer be eligible for the **Bonus Rewards** for that dApp; + +Typically, users only receive rewards for stakes that have been present throughout the entire `Era`, from the first to the last block. In a runtime logic, the protocol does not distribute rewards to a user who started staking in the last block of the `Era` compared to a user who staked throughout the entire `Era`. diff --git a/docs/about/products/dapp-staking/for-stakers/staking.md b/docs/about/products/dapp-staking/for-stakers/staking.md new file mode 100644 index 0000000..f2a07c2 --- /dev/null +++ b/docs/about/products/dapp-staking/for-stakers/staking.md @@ -0,0 +1,77 @@ +--- +sidebar_position: 1 +--- + +import Figure from "/src/components/figure" + +# How to stake + +:::tip + +To earn rewards continuously, users have to vote and stake **every [new period](/use/how-to-guides/layer-1/dapp-staking/for-stakers/).** + +::: + +At the end of a Period, tokens are unstaked from all dApps, remain locked on the account but must be staked back on dApps for the new Period. + +### Visit dApp Staking on the Portal + +Go to the [Astar Portal](https://portal.astar.network/astar/dapp-staking/discover) and click on the `dApp Staking` page. + +Make sure you are connected to the correct network. +- **Shibuya Network**: testnet +- **Shiden Network**: mainnet on Kusama +- **Astar Network**: mainnet on Polkadot + +
+ +### Discover Projects + +:::tip + +Staked TVL and Project Leaderboards are available at the top of the page. + + +::: + +Click on the project cards for more information, access to their communities or to view team profiles. You can also find useful resources on our [forum](https://forum.astar.network/) or check [DefilLama](https://defillama.com/) or [DappRadar](https://dappradar.com/). + +
+ +### Vote & Stake + +:::important + +Before using dApp Staking, make sure you understand all the parameters and rules described [here] (/docs/about/products/dapp-staking/#parameters). **LINK TO UPDATE** +An address can only stake on a maximum of 16 contracts (dApps). +::: + +1) On the [dApp staking](https://portal.astar.network/astar/dapp-staking/discover) page, you can either: + +- Click on the `Vote/Stake today` button; +- Select your favorite project and click on the `Vote & Stake` button on the project page; + +
+ +2) Once on the voting page, you can choose up to 16 projects that you would like to support; + + +
+ +3) To stake, enter the desired amount of tokens for the dApp(s) you have chosen. This may be the same or a different amount for each. + +:::tip + +Make sure to always keep some tokens free for gas manage to claim your rewards. + +::: + +
+ +:::note + +You can see how many tokens you have available to stake from **transferable** or **locked balances** in the section above the `Confirm` button; + +::: + +5) Confirm your decisions by clicking on `Confirm` and sign the transaction on the network; diff --git a/docs/about/products/dapp-staking/for-stakers/unstaking.md b/docs/about/products/dapp-staking/for-stakers/unstaking.md new file mode 100644 index 0000000..7dd3d39 --- /dev/null +++ b/docs/about/products/dapp-staking/for-stakers/unstaking.md @@ -0,0 +1,76 @@ +--- +sidebar_position: 4 +--- + +import Figure from "/src/components/figure" + +# Unstaking from dApps + +## Overview + +**Locking** is a process by which tokens are temporarily `locked`. Staking is one of the scenarios that require tokens to be bonded. +**Unlocking** is the action of telling the network that you want to unlock these tokens. After the unlocking period, you can withdraw the tokens, and they become `transferable`. + +Please note that this is based on a perfect block production of 12s. In case of any delay, your unlocking period can be a little longer. +The unlocking period lenghts can be consulted [here] (/docs/about/products/dapp-staking/#parameters). **LINK TO UPDATE** + +:::warning + +When you unlock or unstake your tokens from dApps Staking, you won’t earn rewards during the unlocking period! + +::: + +### How to unlock staked tokens: + +If you have staked on one of the dApp(s), you can now click on `Unlock` from **My dApps Panel** in the [Asset Page](https://portal.astar.network/astar/assets) to make your tokens transferables. + +
+ +1) Click on the **Unlock button (↑)** on the dApp you want to unstake from; + +2) Select the amount you want to **Unlock**, or click on **Max** to `unlock` your complete stake. + +3) To sign your transaction, click on **Start Unlocking**. + +:::tip + +If you `unstake` some of your tokens from a dApp and your remaining tokens are below the minimum staking amount for a dApp, all your tokens will be unstaked from that dApp; +If you `unstake` your tokens from one dApp during the Build&Earn subperiod and your staked tokens on this dApp are less than your staked tokens at the end of the Voting subperiod for the same dApp, you will no longer be eligible for the Bonus Rewards for that dApp; + +::: + +
+ +When unlocking tokens, a new window appears in your Staking Panel: **Unlocking**. + +
+ +- **Remaining Days** gives you an estimation on how many days or `Eras` you have to wait before being able to withdraw your tokens. +- When your unlock period is over, you need to withdraw your funds by clicking on the **withdraw button**. Sign the transaction and your tokens will be made transferrable in your wallet. + +**Chunks** + +Each unlocking is called a Chunk. But what is a Chunk? + +An unlocking chunk is some amount of ASTR that is undergoing the unlocking period. + +***E.g.***: One chunk can be described as: *"1000 ASTR is undergoing the unlocking period and will be available for transfer on block 42000000"*. + +### How to unlock locked tokens: + +If you have tokens that are still locked but not in staking, you can unlock them to make them transferable. + +:::note + +These tokens will always be subject to the unlocking period. + +::: + +In the **My Staking Panel** on the [Asset Page](https://portal.astar.network/astar/assets), you may have tokens under **Locked amount**, which are tokens that are not staked but could be unlocked. + +1) To release them, click on **Unlock (↑)**, which will trigger a transaction to `unlock` them all. + +
+ +2) At the end of the unlocking period, you can withdraw them by clicking on the **withdraw button**. +3) Sign the transaction and your tokens will be made transferrable in your wallet. diff --git a/docs/about/products/dapp-staking/index.md b/docs/about/products/dapp-staking/index.md new file mode 100644 index 0000000..8be7656 --- /dev/null +++ b/docs/about/products/dapp-staking/index.md @@ -0,0 +1,167 @@ +--- +sidebar_position: 1 +title: dApp Staking Overview +--- + +*At Astar, we're driven by the mission to transform the internet into a freely owned space by the people, where everyone has inviolable control over their data and assets. This commitment to a user-governed internet lies at the heart of the Web3 vision that inspires us.* + +dApp Staking is a crucial accelerator in realizing the Web3 vision, as it lays the foundation for the development of exceptional dApps for users and fuels the drive towards making Web3 accessible to all. + +## What is dApp Staking + +dApp Staking is Astar’s unique mechanism to financially incentivise developers who build decentralized applications (dApps). By engaging in dApp staking, developers can receive a basic income, which allows them to continue building and enhancing their dApps. Moreover, it allows to build a strong relationship between developers, stakers and users of dApps, where everyone is rewarded. + +dApp staking on the Astar/Shiden Network operates similarly to staking on validators. However, in new paradigm, individuals known as dApp stakers have the ability to stake their Astar or Shiden tokens on specific dApps they wish to support. + +At every block on the network, a portion of the inflation is allocated to dApp staking. This reward is then distributed between the operators (developers) of the dApps and the stakers. + +The mechanism is simple: developers earn rewards while building their great projects and attracting supporters, while stakers earn by backing their favorite dApps. + +## Benefits of dApp Staking on Astar and Shiden Network + +For Web3 to flourish, there needs to be a symbiotic relationship between dApp stakers, dApp developers, and dApp users. On Astar and Shiden, dApp staking is the mechanism that enables this mutually beneficial relationship to occur. + +- **Developer Compensation:** Unlike traditional approaches where dApp developers need to rely on grant programs, token issuance, and fundraising efforts to generate income, dApp staking on Astar/Shiden provides developers with a basic income. As long as a dApp has been nominated, developers can receive a steady stream of rewards. + +- **Increased Popularity, Increased Reward:** As a dApp gains popularity and attracts more nominators from the community, the developers who built the dApp can receive a larger percentage of the block rewards. This incentivizes developers to create high-quality dApps that resonate with users and foster community engagement. + +- **Reduced Dependency on Gas Fees:** Building on other blockchains often entails paying substantial gas fees for transactions and interactions. However, on the Astar and Shiden Network, developers can receive compensation through dApp staking, minimizing their reliance on gas fees and making it more economically feasible to continue dApp development. + +### Benefits for Stakers: Increase in Token Value & Earn Tokens + +Astar or Shiden dApp stakers want the value of their tokens to increase but for the value of their tokens to increase, the underlying value of the asset needs to increase. + +This increase in value can happen when the Network grows or when there are fewer tokens in circulation. This way, stakers can not only make their tokens more valuable over time but also earn high returns (APRs) by staking their tokens on dApps. + +This market dynamic enables dApp stakers to get more long-term value from their tokens while earning high APRs from staking their tokens to dApps. + +:::tip + +Please refer to [this section](/docs/about/products/dapp-staking/for-stakers/index.md) to learn more about participating as a **Staker**. + +::: + +### Benefits for Builders: Earn Rewards + +For great dApps to be built, developers need to build them. For developers to build great dApps, they need financial incentives. + +Ultimately, the most precious human resource in the Web3 ecosystem are developers. Before dApp staking, there were little to no financial incentives for developers to make dApps or to build infrastructure on public blockchains. + +With dApp staking, developers can **earn a basic income** while building dApps on Astar or Shiden. Having financial incentives entices more developers to build and improve their dApps. The more developers build on our ecosystem, the greater the benefits for the whole ecosystem. + +That is why Astar considers it essential to provide developers with financial motivation and to ensure they are able to build and earn simultaneously, focusing on development without additional hustle. + +:::tip + +Please refer to [this section](/docs/about/products/dapp-staking/index.md) to learn more about participating as a **dApp builder**. + +::: + +### Benefits for dApp Users: Increase in dApp & Network Utility + +dApp staking plays an essential role in improving the quality of the ecosystem, as it facilitates the growth and improvement of dApps. This gives developers the opportunity to generate revenue while building high-quality dApps. + +The presence of more high-quality dApps not only attracts and retains more users, but also initiates a network effect. This phenomenon encourages ecosystem expansion and increases the intrinsic value of the network in the long term. + +In short, the importance of dApp staking lies in its contribution to the ongoing improvement and greater utility of the ecosystem. The multiplication of high-quality dApps, combined with a growing number of users, results in a network effect that increases the overall value of the ecosystem in the long term. + +### Understand the terminology and parameters of dApp Staking + +To understand how dApp staking v3 works, it’s essential to grasp the following basics: + +#### Era + +`Eras` is a basic time unit in dApp Staking. The length of an Era is 7200 blocks, equivalent to roughly 1 day. + +#### Period & Subperiods + +`Period` is a more lengthy time unit of dApp Staking. + +*To put it simply, if we consider a Period in dApp Staking, it's similar to a concept of a month in human terms , made up of several days (Eras in this case).* + +Each Period consists of two Subperiods: + +- Voting +- Build&Earn + +*Continuing with our human time analogy, it's like dividing a month into two (unequal) parts – the first part can be seen as the Voting phase, and the second part is the Build&Earn phase.* + +**Voting (Staking) Subperiod** + +A subperiod when stakers can decide to vote for dApp(s) to stake their tokens and when dApps owners and team can market their products, conduct campaign and attract stakers. +No staking rewards are generated during the Voting subperiod but if users vote and stake on dApps during this subperiod, they will become eligible for the **Bonus Reward**; + +:::important + +It's very important for dApp owners and their teams to get organized before and during the **voting subperiod** to market their products, run campaigns to attract as many stakers and tokens as possible during this period. + +::: + +**Build&Earn Subperiod** + +A subperiod when stakers and dApps start earning rewards; +Users can still stake tokens during the Build&Earn subperiod to increase the rewards they get from staking. However, the amount staked during Build&Earn does not contribute to the Bonus Reward. + +At the end of a **Build&Earn** subperiod, the current period ends. A new period begins, and all tokens are `unstaked` from dApp(s) but remain `locked`. A new **Voting Subperiod** starts. + +As an user or a dApp owner, you need to take the following parameters into consideration before using dApp Staking: + +#### Parameters + +| Parameters | Astar Network | Shiden Network | Shibuya | +| ------------------------------ | ------------------- | ------------------- | ------------------- | +| Eras Per Period | 122 (~122 days) | 61 (~61 days) | 28 (~7 days) | +| Eras Per Voting Subperiod | 11 (~11 days) | 6 (~6 days) | 8 (~48 hours) | +| Eras Per Build&Earn Subperiod | 111 (~111 days) | 55 (~55 days) | 20 (~120 hours) | +| Blocks Per Era | 7200 (~24 hours) | 7200 (~24 hours) | 1800 (~6 hours) | +| Unlocking Period | 9 Eras (~9 days) | 4 Eras (~4 days) | 4 Eras (~1 day) | +| Minimum Amount to Stake | 500 ASTR | 50 SDN | 5 SBY | + +For the full list of parameters, please check the [dApp staking parameters page](/docs/about/products/dapp-staking/protocol-parameters.md) and [Tokenomics 2.0 page](/docs/about/economics/Inflation.md#parameters). + +#### Tier System + +Tier System is a method to rank dApps based on the total value staked on them. The Tier System is updated at the end of each Build&Earn Subperiod era. + +There are a limited number of tiers, each with a set number of slots and a minimum threshold for dApps to qualify. + +A dApp must gain enough support to enter a tier, with dynamic thresholds for fair competition. Higher tiers offer larger rewards. + +You can always view in what tier the dApp is in the Projects Leaderboard on the Astar Portal. + +:::tip + +Find out more about the Tier system for dApps [here](/docs/about/products/dapp-staking/for-devs/index.md#tier-system-and-rewards). + +::: + +## What should I do next + +*The concept of dApp Staking is simple:* + +Users support dApps in the ecosystem by staking on them, and when the dApp gathers enough support, it receives rewards in native currency, sourced from inflation. + +As a result, stakers are rewarded for their commitment and staking efforts. + +:::tip + +- If you are **ASTR or SDN token holder** interested in **staking**, refer to [this section](/docs/about/products/dapp-staking/for-stakers/index.md) to learn more about participating as a staker. + +- If you are a **dApp developer** building on Astar, refer to [this section](/docs/about/products/dapp-staking/for-devs/index.md) to learn more about participating as a dApp builder. + +- For detailed **technical overview** of dAppStaking protocol, visit this [page](/docs/about/products/dapp-staking/dapp-staking-protocol.md) + +- Check the [**FAQ section**](/docs/about/products/dapp-staking/dapp-staking-faq.md), especially covering topics around new version of dApp Staking (V3) planned to go live on Astar in Q1 2024. + +::: + +### Security Audit + +dApp staking v3 has been audited by [SR Labs](https://www.srlabs.de/). For more information check out [this link](https://github.com/AstarNetwork/Audits/blob/72337c6d9aede3c3ae4f72024077c651f9bf2886/reports/2024-01%20Astar%20dApp%20Staking%20v3%20-%20SR%20Labs.pdf) + +### Other pages may be of interest: + +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + diff --git a/docs/about/products/dapp-staking/protocol-parameters.md b/docs/about/products/dapp-staking/protocol-parameters.md new file mode 100644 index 0000000..19a8e05 --- /dev/null +++ b/docs/about/products/dapp-staking/protocol-parameters.md @@ -0,0 +1,102 @@ +--- +sidebar_position: 3 +title: dApp Staking Parameters +--- + +## Overview + +The following parameters are tightly tied to dApp staking, however, some parameters are shared with the _Tokenomics 2.0_ model. +To find out more, please check the documentation [here](/docs/about/economics/Inflation.md). + +### Era Reward Span Length + +How many eras of reward information do we store in a single database entry. +This puts an upper limit on how many rewards can a single `claim_staker_reward` call claim. +Increasing this number has an impact on the PoV size consumed by the claim calls so it has to be kept relatively small. + +### Reward Retention In Periods + +For how many periods do we keep staker & dApp rewards before they expire, and become unavailable for claiming. +The larger this parameter is, the higher the deviation from the max inflation rate can occur since if many users have very old unclaimed rewards, and decide to claim them at a similar point in time, this would cause inflation to be spike up. + +### Max Number Of Contracts + +There is a technical limitation on how many dApps the protocol can support at this time. +However, this limit won't have a _real_ impact on the protocol since at the moment of writing this document, neither Astar or Shiden are close to that limit. + +### Max Unlocking Chunks + +Maximum number of unlocking chunks that a staker can simultaneously have. +The _chunk_ consists of some _amount_ together with _block number_ after which the chunk becomes unlocked. + +### Minimum Locked Amount + +The minimum amount user has to _lock_ in order to participate in dApp staking protocol. +From the technical standpoint, the _locked_ amount should cover the storage rent fee requirements, and prevents spamming of accounts with low _lock_ amount. +From the user’s standpoint, having low _locked_ amount doesn’t make much sense because their rewards might not even be high enough to cover the transaction fee expense to claim those rewards. + +### Unlocking Period + +Number of blocks required for _unlocking chunk_ to become _unlocked_ after starting the unlocking process. + +### Max Number Of Staked Contracts + +Max number of staked contract entries a single account is allowed to have at once. +This is again a technical bound, to provide additional security to the pallet. + +### Minimum Stake Amount + +Similar to the _minimum lock amount_, but refers to the _stake_ amount. +It's suggested to keep this value same as the _minimum locked amount_. + +### Number Of Tiers + +Number of distinct tiers in the protocol. + +### Reward Distribution + +Describes the portion/percentage of the dApp reward pool that goes towards each tier. +E.g. `[10%, 20%, 30%, 40%]` means that `10%` of the reward pool goes for **tier 1** rewards, `20%` for **tier 2** rewards, and so on. + +### Slot Distribution + +Describes the portion/percentage of the total number of slots that goes towards each tier. +E.g. `[5%, 15%, 20%, 60%]` means that `5%` of the total slots are assigned for **tier 1** dApps, `15%` for **tier 2** dApps, and so on. + +### Tier Thresholds + +The threshold that dApp has to satisfy, essentially the total staked amount, in order to be eligible to enter a tier. +There are two types of thresholds: + +* `Fixed` - threshold has a fixed value and doesn't change +* `Dynamic` - threshold has an initial value, which changes dynamically as the number of slots change, but also has a minimum allowed value. + +### Price Aggregation Duration + +Time period, expressed in blocks, during which native currency price is aggregated. When expired, average value is calculated and stored into the _moving-average_ circular buffer. + +## Circular Buffer Length + +Length of the circular buffer used to implement the _moving-average_ solution. + +## Network Values + +| Parameter name | Astar | Shiden | Shibuya | +| ------------------------------ | --------------------- | --------------------- | -------------------- | +| Era Reward Span Length | 16 | 16 | 16 | +| Reward Retention In Periods | 4 | 3 | 2 | +| Max Number Of Contracts | 500 | 500 | 500 | +| Max Unlocking Chunks | 8 | 8 | 8 | +| Minimum Locked Amount | 500 ASTR | 50 SDN | 5 SBY | +| Unlocking Period | 9 | 4 | 4 | +| Max Number Of Staked Contracts | 16 | 16 | 8 | +| Minimum Stake Amount | 500 ASTR | 50 SDN | 5 SBY | +| Number Of Tiers | 4 | 4 | 4 | +| Reward Distribution | [25%, 47%, 25%, 3%] | [25%, 47%, 25%, 3%] | [40%, 30%, 20%, 10%] | +| Slot Portions | [5%, 20%, 30%, 45%] | [5%, 20%, 30%, 45%] | [10%, 20%, 30%, 40%] | +| Tier 1 Threshold | Dynamic(300M/200M ASTR) | Dynamic(3M/2M SDN) | Dynamic(3000/2500 SBY) | +| Tier 2 Threshold | Dynamic(75M/50M ASTR) | Dynamic(750k/500k SDN)| Dynamic(2000/1500 SBY) | +| Tier 3 Threshold | Dynamic(20M/15M ASTR) | Dynamic(200k/150k SDN)| Dynamic(800/500 SBY) | +| Tier 4 Threshold | Fixed(1.5M ASTR) | Fixed(50k SDN) | Fixed(200 SBY) | +| Price Aggregation Duration | 7200 blocks | 7200 blocks | 7200 blocks | +| Circular Buffer Length | 7 | 7 | 7 | diff --git a/docs/about/products/img/Maxium_contracts_error.png b/docs/about/products/img/Maxium_contracts_error.png new file mode 100644 index 0000000..8b69c5a Binary files /dev/null and b/docs/about/products/img/Maxium_contracts_error.png differ diff --git a/docs/about/products/img/fig4.jpg b/docs/about/products/img/fig4.jpg new file mode 100644 index 0000000..45de91e Binary files /dev/null and b/docs/about/products/img/fig4.jpg differ diff --git a/docs/about/products/img/inflation_1.png b/docs/about/products/img/inflation_1.png new file mode 100644 index 0000000..31de01d Binary files /dev/null and b/docs/about/products/img/inflation_1.png differ diff --git a/docs/about/products/img/tokenomics_1.png b/docs/about/products/img/tokenomics_1.png new file mode 100644 index 0000000..816ff42 Binary files /dev/null and b/docs/about/products/img/tokenomics_1.png differ diff --git a/docs/build/build-on-layer-1/environment/zombienet-testing.md b/docs/build/build-on-layer-1/environment/zombienet-testing.md index 968a0d1..f70358c 100644 --- a/docs/build/build-on-layer-1/environment/zombienet-testing.md +++ b/docs/build/build-on-layer-1/environment/zombienet-testing.md @@ -90,7 +90,7 @@ For all steps, encoded call data will be provided to simplify the process for th After completing the previous steps, cross-chain SDN and SBY wrappers are configured as payable and sufficient assets. The following steps will explain how to execute a cross-chain remote call. `Alice` will send an instruction from `Shiden` to execute `System::remark_with_event` on `Shibuya`. -`Alice` isn't able to directly control `Alice` on the destination chain, instead a new account will be derived. More information can be found [INSERT LINK TO GUIDE] (/docs/learn/interoperability/xcm/building-with-xcm/xc-remote-transact.md#derived-remote-accounts). +`Alice` isn't able to directly control `Alice` on the destination chain, instead a new account will be derived. More information can be found [INSERT LINK TO GUIDE] (/docs/build/build-on-layer-1/smart-contracts/buildiing-cross-chain-contracts/xcm/building-with-xcm/xc-remote-transact.md#derived-remote-accounts). 1. Calculate `Alice's` derived account on `Shibuya` when sending instructions from `Shiden`. ``` diff --git a/docs/build/build-on-layer-1/introduction/create_account.md b/docs/build/build-on-layer-1/introduction/create_account.md index 43a7a92..012388e 100644 --- a/docs/build/build-on-layer-1/introduction/create_account.md +++ b/docs/build/build-on-layer-1/introduction/create_account.md @@ -3,7 +3,7 @@ sidebar_position: 3 --- # Create Account -If you never created a native Astar account, please follow the instructions in the [User Guide] (/docs/use/manage-wallets/create-wallet.md) [INSERT LINK]. +If you never created a native Astar account, please follow the instructions in the [User Guide] (/docs/use/how-to-guides/layer-1/manage-wallets/create-wallet.md) [INSERT LINK]. If you are building EVM smart contracts you will need Metamask. Watch this short video to learn how. diff --git a/docs/build/build-on-layer-1/smart-contracts/EVM/infra/verify_smart_contract.md b/docs/build/build-on-layer-1/smart-contracts/EVM/infra/verify_smart_contract.md index 727ab6b..913d2cf 100644 --- a/docs/build/build-on-layer-1/smart-contracts/EVM/infra/verify_smart_contract.md +++ b/docs/build/build-on-layer-1/smart-contracts/EVM/infra/verify_smart_contract.md @@ -34,7 +34,7 @@ Due to compiler constraints, contracts **with OpenZeppelin-related source contra In this section, we will go through the process of verifying a smart contract **without OpenZeppelin-related source contracts.** In the previous guide, we went through the process of using Remix IDE to deploy a smart contract on Astar EVM. Let's start from there: -[How to use Remix IDE to deploy an on-chain storage contract on Astar EVM | Astar Docs](/docs/build/build-on-layer-1/builder-guides/astar_features/use_remix.md) +[How to use Remix IDE to deploy an on-chain storage contract on Astar EVM | Astar Docs](/docs/build/builder-guides/layer-1/evm/astar_features/use_remix.md) Copy the deployed contract address under the `Deployed Contracts` section diff --git a/docs/build/build-on-layer-1/smart-contracts/EVM/precompiles/xc20.md b/docs/build/build-on-layer-1/smart-contracts/EVM/precompiles/xc20.md index 3cf8515..c38885c 100644 --- a/docs/build/build-on-layer-1/smart-contracts/EVM/precompiles/xc20.md +++ b/docs/build/build-on-layer-1/smart-contracts/EVM/precompiles/xc20.md @@ -2,7 +2,7 @@ XC20 standard, created by the Moonbeam team, ensures compatibility between the EVM and Substrate framework that powers Polkadot via precompiles — special built-in smart contracts made to look like ERC20s. Calling functions on an XC20 invokes underlying Substrate functionality, which could be instructions to move tokens to another chain, or send them to another local address. This compatibility layer connects the world of EVM and smart contracts to advanced Substrate-based interoperability scenarios. -For XC20 overview see the following [page] (/docs/learn/interoperability/xcm/building-with-xcm/create-xc20-assets). [INSERT LINK] +For XC20 overview see the following [page] (/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/create-xc20-assets). [INSERT LINK] # See also diff --git a/docs/build/build-on-layer-1/smart-contracts/EVM/precompiles/xcm/xcm.md b/docs/build/build-on-layer-1/smart-contracts/EVM/precompiles/xcm/xcm.md index c63ccf1..2729c39 100644 --- a/docs/build/build-on-layer-1/smart-contracts/EVM/precompiles/xcm/xcm.md +++ b/docs/build/build-on-layer-1/smart-contracts/EVM/precompiles/xcm/xcm.md @@ -244,5 +244,5 @@ XCM.Multilocation memory asset = XCM.Multilocation({ Three builder guides on the subject of EVM XCM are available in Builder section: - [How to create and interact with a mintable XC20 asset via Solidity smart contract](https://docs.astar.network/build/build-on-layer-1/builder-guides/leverage_parachains/interact_with_xc20.md) -- [Harnessing Crust Network for NFT Minting: A Developer's Guide](/docs/build/build-on-layer-1/builder-guides/leverage_parachains/mint-nfts-crust.md) -- [How to set up a Zombienet for XCM testing](/docs/build/build-on-layer-1/builder-guides/leverage_parachains/zombienet.md) +- [Harnessing Crust Network for NFT Minting: A Developer's Guide](/docs/build/builder-guides/layer-1/evm/leverage_parachains/mint-nfts-crust.md) +- [How to set up a Zombienet for XCM testing](/docs/build/builder-guides/layer-1/evm/leverage_parachains/zombienet.md) diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/_category_.json b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/_category_.json new file mode 100644 index 0000000..6ce45b4 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Interoperability", + "position": 11 +} diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/asset-list.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/asset-list.md new file mode 100644 index 0000000..1b99387 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/asset-list.md @@ -0,0 +1,51 @@ +--- +sidebar_position: 4 +--- + +# XCM Asset List + +## XC20 + +We can differentiate between managed project's XC20 assets which have been tested by Astar and Shiden Network maintainers and other permissionless XC20 assets created on-chain. + +Currently, this is a list of managed XC20 assets: + +### Astar + +Asset | Symbol | Decimals | EVM Address | Asset Id +---| --- | --- | --- | --- +Polkadot | `DOT` | 10 | `0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF` | `340282366920938463463374607431768211455` +Tether USD | `USDT` | 6 | `0xFFFFFFFF000000000000000000000001000007C0` | `4294969280` +Acala | `ACA` | 12 | `0xFFFFFFFF00000000000000010000000000000000` | `18446744073709551616` +Acala Dollar | `aUSD` | 12 | `0xFFFFFFFF00000000000000010000000000000001` | `18446744073709551617` +Liquid DOT | `LDOT` | 10 | `0xFFFFFFFF00000000000000010000000000000002` | `18446744073709551618` +Glimmer | `GLMR` | 18 | `0xFFFFFFFF00000000000000010000000000000003` | `18446744073709551619` +Inter iBTC | `iBTC` | 8 | `0xFFFFFFFF00000000000000010000000000000004` | `18446744073709551620` +INTR | `INTR` | 10 | `0xFFFFFFFF00000000000000010000000000000005` | `18446744073709551621` +Phala Token | `PHA` | 12 | `0xFFFFFFFF00000000000000010000000000000006` | `18446744073709551622` +Bifrost Native Token | `BNC` | 12 | `0xFFFFFFFF00000000000000010000000000000007` | `18446744073709551623` +Voucher DOT | `vDOT` | 10 | `0xFFFFFFFF00000000000000010000000000000008` | `18446744073709551624` +Clover Finance | `CLV` | 18 | `0xFFFFFFFF00000000000000010000000000000009` | `18446744073709551625` +Voucher Slot DOT | `vsDOT` | 10 | `0xFFFFFFFF0000000000000001000000000000000A` | `18446744073709551626` +PINK Token | 'PINK' | 10 | `0xFFFFFFFF00000000000000010000000000000011` | `18446744073709551633` + +### Shiden + +Asset | Symbol | Decimals | EVM Address | Asset Id +---| --- | --- | --- | --- +Kusama | `KSM` | 12 | `0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF` | `340282366920938463463374607431768211455` +Tether USD | `USDT` | 6 | `0xFFFFFFFF000000000000000000000001000007C0` | `4294969280` +Acala Dollar | `aUSD` | 12 | `0xFFFFFFFF00000000000000010000000000000000` | `18446744073709551616` +Karura | `KAR` | 12 | `0xFFFFFFFF00000000000000010000000000000002` | `18446744073709551618` +Liquid KSM | `LKSM` | 12 | `0xFFFFFFFF00000000000000010000000000000003` | `18446744073709551619` +Moonriver | `MOVR` | 18 | `0xFFFFFFFF00000000000000010000000000000004` | `18446744073709551620` +Kintsugi iBTC | `KBTC` | 8 | `0xFFFFFFFF00000000000000010000000000000005` | `18446744073709551621` +KINT | `KINT` | 12 | `0xFFFFFFFF00000000000000010000000000000006` | `18446744073709551622` +Phala Token | `PHA` | 12 | `0xFFFFFFFF00000000000000010000000000000007` | `18446744073709551623` +Crust Shadow Native Token | `CSM` | 12 | `0xFFFFFFFF00000000000000010000000000000008` | `18446744073709551624` +Sakura | `SKU` | 18 | `0xFFFFFFFF0000000000000001000000000000000A` | `18446744073709551626` +Bifrost Native Coin | `BNC` | 12 | `0xFFFFFFFF0000000000000001000000000000000B` | `18446744073709551627` +Voucher KSM | `vKSM` | 12 | `0xFFFFFFFF0000000000000001000000000000000C` | `18446744073709551628` +Voucher Slot KSM | `vsKSM` | 12 | `0xFFFFFFFF0000000000000001000000000000000D` | `18446744073709551629` + +--- diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/faq.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/faq.md new file mode 100644 index 0000000..c51167a --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/faq.md @@ -0,0 +1,53 @@ +--- +sidebar_position: 5 +--- + +# XCM FAQ + +### Q: Is there a way to see my DOT/SDN balance (on Astar/Shiden) on the Polkadot.js? + +Yes. visit Polkadot.js, connect your wallet and go to Network > Balances and select the token you are interested in. The example below demonstrates how to view the SDN balance: + +![Viewing KSM balance on Shiden Network](img/1.png) + +### Q: I used XCM to transfer 5 DOT from Polkadot to Astar, but only received 4.999 + +Please note that the gas amount will be deducted from the amount entered, so the amount transferred should be adjusted according to account for the gas fee estimate. For more information, visit [here] (https://docs.astar.network/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/xcm-transactions). + +### Q: My balance should be 1.00012 DOT but the Portal is displaying 1 DOT, where are they? + +The current version of Astar Portal rounds balances to the 3rd decimal. If you have a similar issue please refer to the [previous FAQ entry] (building-with-xcm/faq-for-smart-contracts.md) and instructions on how to use Polkadot.js to find your exact balance. + +### Q: Can I send my DOT token to other Parachains? + +Not at the moment. + +### Q: How can I send my DOT token back to Polkadot? + +You can send back DOT/KSM to the Relay Chain using both EVM and native wallets. Visit the Assets Page and choose the XCM link of the relevant token. + +### Q: Why is the XCM button for DOT/KSM disabled when I connect my wallet on the Astar Portal? + +Ensure you have a non-zero balance of the native token as described in [this section](https://docs.astar.network/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/xcm-transactions). + +### Q: I transferred X tokens to another account, but the amount transferred and received by the target account is greater than X. What is going on? + +XC20 assets have a defined minimum-balance. The minimum-balance is the minimum balance of an asset that any single account must have. In this specific case, if an account's balance would be reduced below that amount in an asset transfer transaction, then the amount actually transferred would include the remaining amount of specific asset on the initiating account. + +Take a look at an example of a transaction in case of an asset whose minimum-balance is 10: Alice has 10.9 tokens and tries to send Bob 10 tokens. Alice's remaining balance in that case would become 0.9, which is less than minimum amount, so the amount transferred would be set to 10.9 tokens, so Alice's balance will become 0, to avoid any funds being reaped by not fulfilling the Existential Deposit. + +For more information, check out this section within our documentation. + +### Q: Where can I find other chains' addresses? + +You can find all the different chains' addresses in Polkadot/Kusama : + +1. Using [Sub ID] (https://sub.id/) + +Simply input your Astar native address and you will be able to see all the related addresses of the account. + +2. Display it on Polkadot.js extension by selecting the chain you would like to know the address of. + +Please note that you will only be able to make an XCM withdrawal if the receiver's Relay Chain account balance is greater than the Minimum Balance (1.1 DOT for Polkadot and 0.01 KSM for Kusama). + + diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/img/1.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/img/1.png new file mode 100644 index 0000000..97f007b Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/img/1.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/_category_.json b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/_category_.json new file mode 100644 index 0000000..c29ac21 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Cross-Chain Messaging - XCM", + "position": 5 +} \ No newline at end of file diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/asset-list.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/asset-list.md new file mode 100644 index 0000000..b878f52 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/asset-list.md @@ -0,0 +1,62 @@ +--- +sidebar_position: 4 +--- + +# XCM Asset List + +## XC20 + +We can differentiate between managed project's XC20 assets which have been tested by Astar and Shiden Network maintainers and other permissionless XC20 assets created on-chain. + +Currently, this is a list of managed XC20 assets: + +### Astar + +Asset | Symbol | Decimals | EVM Address | Asset Id +---| --- | --- | --- | --- +Polkadot | `DOT` | 10 | `0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF` | `340282366920938463463374607431768211455` +Tether USD | `USDT` | 6 | `0xFFFFFFFF000000000000000000000001000007C0` | `4294969280` +Circle USDC | `USDC` | 6 | `0xFFFFFFFF000000000000000000000001000007C1` | `4294969281` +Acala | `ACA` | 12 | `0xFFFFFFFF00000000000000010000000000000000` | `18446744073709551616` +Acala Dollar | `aUSD` | 12 | `0xFFFFFFFF00000000000000010000000000000001` | `18446744073709551617` +Liquid DOT | `LDOT` | 10 | `0xFFFFFFFF00000000000000010000000000000002` | `18446744073709551618` +Glimmer | `GLMR` | 18 | `0xFFFFFFFF00000000000000010000000000000003` | `18446744073709551619` +Inter iBTC | `iBTC` | 8 | `0xFFFFFFFF00000000000000010000000000000004` | `18446744073709551620` +INTR | `INTR` | 10 | `0xFFFFFFFF00000000000000010000000000000005` | `18446744073709551621` +Phala Token | `PHA` | 12 | `0xFFFFFFFF00000000000000010000000000000006` | `18446744073709551622` +Bifrost Native Token | `BNC` | 12 | `0xFFFFFFFF00000000000000010000000000000007` | `18446744073709551623` +Voucher DOT | `vDOT` | 10 | `0xFFFFFFFF00000000000000010000000000000008` | `18446744073709551624` +Clover Finance | `CLV` | 18 | `0xFFFFFFFF00000000000000010000000000000009` | `18446744073709551625` +Voucher Slot DOT | `vsDOT` | 10 | `0xFFFfFffF0000000000000001000000000000000A` | `18446744073709551626` +Darwinia Native Token | `RING` | 18 | `0xFFFfFffF0000000000000001000000000000000B` | `18446744073709551627` +Equilibrium Native Token | `EQ` | 9 | `0xFFFfFffF0000000000000001000000000000000C` | `18446744073709551628` +Equilibrium USD | `EQD` | 9 | `0xFFFfFffF0000000000000001000000000000000D` | `18446744073709551629` +HydraDX | `HDX` | 12 | `0xFFFfFffF0000000000000001000000000000000E` | `18446744073709551630` +Unique Network | `UNQ` | 18 | `0xFFFfFffF0000000000000001000000000000000F` | `18446744073709551631` +Voucher ASTR | `vASTR` | 18 | `0xFFFfFffF00000000000000010000000000000010` | `18446744073709551632` +PINK Token | 'PINK' | 10 | `0xFFFFFFFF00000000000000010000000000000011` | `18446744073709551633` + +### Shiden + +Asset | Symbol | Decimals | EVM Address | Asset Id +---| --- | --- | --- | --- +Kusama | `KSM` | 12 | `0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF` | `340282366920938463463374607431768211455` +Tether USD | `USDT` | 6 | `0xFFFFFFFF000000000000000000000001000007C0` | `4294969280` +Circle USDC | `USDC` | 6 | `0xFFFFFFFF000000000000000000000001000007C1` | `4294969281` +Acala Dollar | `aUSD` | 12 | `0xFFFFFFFF00000000000000010000000000000000` | `18446744073709551616` +Karura | `KAR` | 12 | `0xFFFFFFFF00000000000000010000000000000002` | `18446744073709551618` +Liquid KSM | `LKSM` | 12 | `0xFFFFFFFF00000000000000010000000000000003` | `18446744073709551619` +Moonriver | `MOVR` | 18 | `0xFFFFFFFF00000000000000010000000000000004` | `18446744073709551620` +Kintsugi iBTC | `KBTC` | 8 | `0xFFFFFFFF00000000000000010000000000000005` | `18446744073709551621` +KINT | `KINT` | 12 | `0xFFFFFFFF00000000000000010000000000000006` | `18446744073709551622` +Phala Token | `PHA` | 12 | `0xFFFFFFFF00000000000000010000000000000007` | `18446744073709551623` +Crust Shadow Native Token | `CSM` | 12 | `0xFFFFFFFF00000000000000010000000000000008` | `18446744073709551624` +Sakura | `SKU` | 18 | `0xFFFfFffF0000000000000001000000000000000A` | `18446744073709551626` +Bifrost Native Coin | `BNC` | 12 | `0xFFFfFffF0000000000000001000000000000000B` | `18446744073709551627` +Voucher KSM | `vKSM` | 12 | `0xFFFfFffF0000000000000001000000000000000C` | `18446744073709551628` +Voucher Slot KSM | `vsKSM` | 12 | `0xFFFfFffF0000000000000001000000000000000D` | `18446744073709551629` +Genshiro Native Token | `GENS` | 9 | `0xFFFfFffF0000000000000001000000000000000E` | `18446744073709551630` +Equilibrium USD | `EQD` | 9 | `0xFFFfFffF0000000000000001000000000000000F` | `18446744073709551631` +Metaverse.Network Pioneer | `NEER` | 18 | `0xFFFFFFFF00000000000000010000000000000010` | `18446744073709551632` +Quartz | `QTZ` | 18 | `0xFFFFFFFF00000000000000010000000000000011` | `18446744073709551633` + diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/_category_.json b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/_category_.json new file mode 100644 index 0000000..50cd579 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Building with XCM", + "position": 2 +} \ No newline at end of file diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/client-applications.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/client-applications.md new file mode 100644 index 0000000..5c8f847 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/client-applications.md @@ -0,0 +1,258 @@ +--- +sidebar_position: 9 +--- + +# Client Applications + +In this chapter, we will examine how to use TypeScript to interact with the XCM pallet and construct XCM transactions. Using this information, you will be able to create an XCM dApp, or bridge. + +While interacting with the XCM pallet via the Substrate RPC, we will make use of the [`polkadot/api`](https://github.com/polkadot-js/api) package, throughout this chapter. + +First, you will need to initialize the API as you would with any Substrate application. + +```js +import { ApiPromise, WsProvider } from '@polkadot/api'; + +const myApp = async () => { + const provider = new WsProvider('wss://rpc.shiden.astar.network'); + const chainApi = await (new ApiPromise({ provider })).isReady; + + const paraId = await chainApi.query.parachainInfo.parachainId.toString(); + + // Should output 2007 + console.log(paraId) +}; +``` + +On Astar Network, we use the [Substrate Assets pallet](https://github.com/paritytech/substrate/tree/master/frame/assets) to handle the XCM multi-asset representation. Let’s retrieve the list of assets from the network. + +```js + +// import the known types +import { AssetMetadata, AssetDetails } from '@polkadot/types/interfaces'; + +// we create a custom interface for convenience +interface ChainAsset extends AssetDetails { + id: string; + metadata: AssetMetadata; +} + + //...snip + + // note that this function requires the chain to implement the Assets pallet + + // note: The asset ID will have different meanings depending on the range + // 1 ~ 2^32-1 = User-defined assets. Anyone can register this assets on chain. + // 2^32 ~ 2^64-1 = Statemine/Statemint assets map. This is a direct map of all the assets stored in the common-goods state chain. + // 2^64 ~ 2^128-1 = Ecosystem assets like native assets on another parachain or other valuable tokens. + // 2^128 ~ 1 = Relaychain native token (DOT or KSM). + + const assetsListRaw = await chainApi.query.assets.asset.entries(); + const assetMetadataListRaw = await chainApi.query.assets.metadata.entries(); + + const assetInfos = assetsListRaw.map((i, index) => { + const assetId = (i[0].toHuman() as string[])[0].replaceAll(',', ''); + const assetInfo = i[1].toHuman() as any as AssetDetails; + const metadata = assetMetadataListRaw[index][1].toHuman() as any as AssetMetadata; + return { + id: assetId, + ...assetInfo, + metadata, + } as ChainAsset; + }); + // convert the list into a string array of numbers without the comma and no nested entries +}; +``` + +Running this function will produce a list of assets that are registered on the chain. This is useful when you want to create a UI that lists all possible assets, including XCM-compatible assets. + +Next, let’s execute a cross-consensus function. Parachains will have a pallet called `polkadotXcm`, while Relay Chains will use the pallet `xcmPallet`. Both of them will use the same functions and syntax for sending XCM transactions. + +In this example, we will send the Relay Chain asset to the parachain, as we've done in previous chapters, but this time, we’ll use TypeScript. + +Let’s create two API instances, one for the parachain and another for the Relay Chain. Although for our example, we will only call the extrinsic from the Relay Chain, and initialize the parachain API instance to dynamically obtain the parachain ID. + +```js +import { ApiPromise, WsProvider } from '@polkadot/api'; +import { Vec, u32 } from '@polkadot/types'; + +const parachainApi = async () => { + const provider = new WsProvider('wss://rpc.shiden.astar.network'); + const chainApi = await (new ApiPromise({ provider })).isReady; + + const paraId = (await chainApi.query.parachainInfo.parachainId()).toString(); + + // Should output 2007 + console.log(paraId); + return chainApi; +}; + +const relaychainApi = async () => { + const provider = new WsProvider('wss://kusama-rpc.polkadot.io'); + const chainApi = await (new ApiPromise({ provider })).isReady; + + const parachains = ((await chainApi.query.paras.parachains()) as Vec).map((i) => i.toNumber()); + + // Should output a list of parachain IDs + console.log(parachains); + return chainApi; +}; +``` + +Next, we create the main function for handling the actual XCM transaction. + +```js +import { Keyring } from '@polkadot/keyring'; +import { decodeAddress, cryptoWaitReady } from '@polkadot/util-crypto'; + +const myApp = async () => { + await cryptoWaitReady(); + + const keyring = new Keyring({ type: 'sr25519' }); + // ensure that this account has some KSM + const account = keyring.addFromUri('account seed', { name: 'Default' }, 'sr25519'); + + const parachainApiInst = await parachainApi(); + const relaychainApiInst = await relaychainApi(); + + const parachainId = await parachainApiInst.query.parachainInfo.parachainId.toString(); + + // the target parachain connected to the current relaychain + const dest = { + V1: { + interior: { + X1: { + Parachain: parachainId, + }, + }, + parents: 0, + }, + }; + // the account ID within the destination parachain + const beneficiary = { + V1: { + interior: { + X1: { + AccountId32: { + network: 'Any', + id: decodeAddress(account.address), + }, + }, + }, + parents: 0, + }, + }; + + // 1 KSM + const amountToSend = new BN(10).pow(new BN(12)); + // amount of fungible tokens to be transferred + const assets = { + V1: [ + { + fun: { + Fungible: amountToSend, + }, + id: { + Concrete: { + interior: 'Here', + parents: 0, + }, + }, + }, + ], + }; + + const txHash = await relaychainApiInst.tx.xcmPallet.reserveTransferAssets(dest, beneficiary, assets, 0).signAndSend(account); +}; +``` + +To summarize, the first half of the function loads the account that will send the KSM and initialize the API. The real magic happens in the latter half of the function. + +```js + // the target parachain connected to the current relaychain + const dest = { + V1: { + interior: { + X1: { + Parachain: parachainId, + }, + }, + parents: 0, + }, + }; + // the account ID within the destination parachain + const beneficiary = { + V1: { + interior: { + X1: { + AccountId32: { + network: 'Any', + id: decodeAddress(account.address), + }, + }, + }, + parents: 0, + }, + }; + + // 1 KSM + const amountToSend = new BN(10).pow(new BN(12)); + // amount of fungible tokens to be transferred + const assets = { + V1: [ + { + fun: { + Fungible: amountToSend, + }, + id: { + Concrete: { + interior: 'Here', + parents: 0, + }, + }, + }, + ], + }; +``` + +As you can see, the `dest` refers to the destination or target chain that will receive the asset identified by the parachain ID. The `beneficiary` refers to the account within the parachain that will receive the token. Finally, the `assets` parameter refers to the amount you wish to send. Finally, we can sign the transaction with the following function: + +```js +// This can be zero +const feeAsset = 0; +const txHash = await relaychainApiInst.tx.xcmPallet.reserveTransferAssets(dest, beneficiary, assets, feeAsset).signAndSend(account); +``` + +Now once you finish the XCM transaction, you can list all the assets with the following script: + +```js +const assetsListRaw = await parachainApiInst.query.assets.asset.entries(); +const assetMetadataListRaw = await parachainApiInst.query.assets.metadata.entries(); + +const assetInfos = assetsListRaw.map((i, index) => { + const assetId = (i[0].toHuman() as string[])[0].replaceAll(',', ''); + const assetInfo = i[1].toHuman() as any as AssetDetails; + const metadata = assetMetadataListRaw[index][1].toHuman() as any as AssetMetadata; + return { + id: assetId, + ...assetInfo, + metadata, + } as ChainAsset; +}); + +const assetBalance = await Promise.all(assetInfos.map(async (i) => { + const balance = await parachainApiInst.query.assets.account(i.id, account.address); + return { + symbol: i.metadata.symbol.toString(), + balance: balance.toString(), + } +})) + +console.log(assetBalance); +``` + +Now, you should be able to transfer the asset from the Relay Chain to the parachain, and check to see if it was successful by listing all the assets within the asset pallet that the current account holds. + +Please note that the gas fee will be deducted from the amount transferred, so it should be adjusted accordingly, based on the estimated gas fee. Please refer to the [Gas Price API](https://app.gitbook.com/o/-LgGrgOEDyFYjYWIb1DT/s/-M8GVK5H7hOsGnYqg-7q-872737601/~/changes/aJQFFWQNMjlao1SSjj4a/build/api/gas-price-api) if required, for specific use cases. + +You can find an entire project that integrates similar functionality in [this repository](https://github.com/AstarNetwork/astar-xcm-tools). diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/create-xc20-assets.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/create-xc20-assets.md new file mode 100644 index 0000000..858fe6f --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/create-xc20-assets.md @@ -0,0 +1,96 @@ +--- +sidebar_position: 2 +--- + +# Create XC20 Assets + +## Overview + +XC20 assets, created by the [Moonbeam](https://moonbeam.network/blog/introducing-xc-20s-the-new-standard-for-cross-chain-tokens-on-dotsama/) team, maintains compatibility between the EVM and Substrate framework that powers Polkadot, via precompiles — a set of built-in smart contracts made to look like ERC20s. Calling functions on an XC20 will invoke underlying Substrate functionality, which may be instructions for transferring tokens to another chain, or to send them to another local address. This compatibility layer connects the world of EVM and smart contracts to advanced Substrate-based interoperability scenarios. + +## Create an XC20 Asset + +XC20 asset refers to interface it uses to wrap around an asset in `assets-pallets`. So first we will need to create, mint and set metadata for an asset in `assets-pallets` and then access it from smart-contract using XC20 precompile interface. + +This section of the guide will demonstrate how to register an asset using [Polkadot.js Apps](https://polkadot.js.org/apps). + +## Create the Asset + +Before the asset's Metadata can be set, we will need to create an asset on the network using the following steps: + +1. Navigate within [Polkadot.js Apps](https://polkadot.js.org/apps) to Network and click on **Assets**. +2. Click on **+Create** on the right to open the create asset pop-up. +3. Enter the **asset name, asset symbol**, and set the number of **decimals** for the asset. This doesn't have to be 18 decimals like the network native assets, it's completely configurable. +4. The **minimum balance** is the Existential Deposit (ED) of your asset. The ED exists so that accounts with very small balances, or that are empty, do not "bloat" the state of the blockchain and diminish its performance. **NOTE**: setting this value to pico units and minimum balance to 1, will only require 0.000000000001 units. We suggest having a minimum balance of **1**. +5. The asset id will be automatically generated for you. The valid range for permissionless creation is up to `2^32 - 1`. +6. When everything is filled in, click **Next** on the next screen. +7. Set your **roles** and create the asset by signing with the creator account. + +:::note +Please make sure the account creating the asset has sufficient balance to pay the [rent fee](/docs/about/economics/tokenomics2-network-fees.md#Rent_Fee). +::: + +![Create your asset](img/5.png) +![Set roles](img/6.png) + +There are a few roles that are important to take note of when registering and managing assets. These roles, with the exception of the creator, can all be designated to other accounts by the owner via the assets -> setTeam extrinsic. The roles are as follows: + +- **Creator** - the account responsible for creating the asset. +- **Issuer** - the designated account capable of issuing or minting tokens. Defaults to the owner. +- **Admin** - the designated account capable of burning tokens and unfreezing accounts and assets. Defaults to the owner. +- **Freezer** - the designated account capable of freezing accounts and assets. Defaults to the owner. + +## Mint Asset + +The asset is now created on our network, but has no supply. To mint the tokens, click on the +Mint button next to the asset to open the mint pop-up. + +![Mint your assets](img/7.png) + +1. Only the **issuer account** has permission to mint the token. +2. Enter the address that will receive the minted tokens. We recommend using a [multisig](/docs/use/how-to-guides/layer-1/manage-wallets/create-multisig.md/). + +## Set Asset Metadata + +The metadata includes the asset name, symbol, and decimals. + +To set the asset metadata, click on **Developer** at the top of the page and then select **Extrinsics** from the dropdown. From there, take the following steps: + +1. Select the owner's account +2. From the **submit the following extrinsic** dropdown, choose **assets** +3. Then select the `setMetadata` extrinsic +4. Enter the asset id from the asset you created before +5. Enter the name of the asset +6. Set the symbol for the asset +7. Set the decimals for the asset +8. Click on **Submit Transaction** + +![Set Token Metadata](img/8.png) + +You can use the **Extrinsics** page to perform other functions such as minting tokens, delegating a team, freeze and thaw assets or accounts, and more. + +## Calculate XC20 Precompile Address + +To access our asset as XC20 in MetaMask or another EVM wallet, we will need to use its precompile address. The XC20 precompile address is using the following rule: + +`address = "0xFFFFFFFF" + DecimalToHexWith32Digits(AssetId)` + +The first step is to take the asset Id and convert it to a hex value. You can use the search engine of your choice to look up a simple tool for converting decimals to hex values. In this tutorial, we will use this [decimal to hexadecimal converter](https://www.rapidtables.com/convert/number/decimal-to-hex.html). + +For asset ID `19992021`, the hex value is `1310DD5`. + +XC20 precompiles can only fall between `0xFFFFFFFF00000000000000000000000000000000` and `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF`. As such, the first 8 characters of the address will always be `FFFFFFFF`. Since Ethereum addresses are 40 characters long, you will need to prepend 0s to the hex value until the address has 40 characters. + +The hex value that was already generated in the example is 7 characters long, so prepending the first 8 characters, `FFFFFFFF`, to the hex value will give you the part of the 40-character address you need to interact with the XC20 precompile. Note that you still need to add zeros to get the 40-character address. You add the zeros between `FFFFFFFF` and generated hex. + +For this example, the full address is `0xFFFFFFFF00000000000000000000000001310dD5`. + +:::note +To use this address inside a solidity smart-contract, check sum of the address should be respected. Please use [toChecksumAddress](https://web3-tools.netlify.app/) converter that will convert your address. +for example `0xFFFFFFFF00000000000000000000000001310dD5` will be converted to `0xfFFfffFF00000000000000000000000001310dD5` +::: + +Now that you've generated the XC20 precompile address, you can use the address to interact with the XC20 as you would with any other ERC20 in Remix. + +:::note +Native token (SDN/ASTR) XC20 address is by convention `0x0000000000000000000000000000000000000000` +::: diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/erc20-cross-chain-compatible.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/erc20-cross-chain-compatible.md new file mode 100644 index 0000000..91911df --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/erc20-cross-chain-compatible.md @@ -0,0 +1,128 @@ +--- +sidebar_position: 4 +--- + +# Making Existing ERC20 Assets Cross-chain Compatible + +If you would like to make an existing ERC20 asset cross-chain compatible, it's quite simple, following the instructions below + +## XC20+ Extension + +In short, the **XC20** standard allows smart contracts to interact with cross-chain compatible assets, as if they were typical ERC20 assets. +Unlike standard ERC20 assets deployed within the EVM environment, where balances, issuance, etc. are stored directly, **XC20** assets are mapped to a Substrate pallet, which means that developers do not have access to the same logic inherent to ERC20 format, such as `_mint` or `_burn`. + +In general, this is fine for existing **XC20** assets since we shouldn't be minting or burning them in smart contracts (e.g. there is no valid reason to mint cross-chain DOT on Astar). However, there are use cases where having an extended set of functionalities is useful and required, such as for wrapped tokens. + +For this reason, we provide an extended **XC20** interface called **XC20+**. It provides the following methods: +```Solidity +// Used to check what is the existential deposit of XC20 asset +function minimumBalance() external view returns (uint256); + +// Used to mint new funds +function mint(address beneficiary, uint256 amount) external returns (bool); + +// Used to burn funds +function burn(address who, uint256 amount) external returns (bool); +``` +The aforementioned list could be extended in the future. + +Please note that minting and burning requires certain priviliges - read about **XC20** assets to learn more. + +:::caution + +Please note that the `burn()` function in **XC20+** is inhereting the behaviour of `pallet-assets` `burn()` function. Calling `pallet-assets` `burn()` function with a amount higher than the current balance will result in a burn of the amount available, and returning success. + +In contracts, the `burn()` implementation in [`ERC20Burnable.sol`](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/3214f6c2567f0e7938f481b0a6b5cd2fe3b13cdb/contracts/token/ERC20/ERC20.sol#L283) will burn the amount if it is lower or equal to the account's balance. + +::: + +## Wrapped Tokens +A wrapped token is a token whose value is tied to an underlying cryptocurrency. An amount of the original token is locked in a digital vault, and in return allows an equivalent amount of wrapped tokens to be minted. + +This is useful for several reasons, to mention a few: +* To extend the functionalities of an existing token in conjunction with other ERC20 modules. +* To allow a native cryptocurrency to behave like an ERC20, e.g. Wrapped Ether (WETH). +* To allow the use of currencies outside their native blockchain, e.g. Wrapped bitcoin (WBTC). + +In the next example we will examie how to wrap an existing ERC20 token into **XC20**. + +## Wrapping ERC20 into XC20 + +In this example, the underlying token will be an existing ERC20, called BURRITO. We want to wrap some BURRITOs and make them cross-chain-ready. Using a standard [ERC20Wrapper](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/extensions/ERC20Wrapper.sol) token spec from OpenZeppelin will not be enough. Therefore we will need to override some of the ERC20Wrapper functions, and use **XC20+** functions. +Let's call the newly wrapped token xcBURRITO. +xcBURRITO takes the address of the underlaying token (BURRITO) and the newly created asset's address as constructor parameters. And we’ll set values for the other required parameters, but notice that we have to include the ERC20Permit constructor call, because xcBURRITO is now a parent of BURITTO. +```Solidity +constructor(IERC20 burrito) + ERC20("Wrapped Burrito", "xcBUR") + ERC20Permit("Wrapped Burrito") + ERC20Wrapper(burrito) +{} +``` +Since we can't use ERC20Wrapper out of box we'll override it and use the **XC20+** interface. +```Solidity +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Wrapper.sol"; +import "./Burrito.sol"; + +contract XcBurrito is Xc20Plus, ERC20Wrapper, BURRITO{ + constructor(IERC20 burrito) + Xc20Plus("Wrapped Burrito", "xcBUR") + ERC20Permit("Wrapped Burrito") + ERC20Wrapper(burrito) + {} + + function _mint(address _to, uint256 _amount) + internal + override(ERC20) + { + // add here your pre-mint hooks if needed + + require( + IERC20Plus(xcBurrito).mint(_to, _amount), "Minting xc token failed" + ); + + // add here your post-mint hooks if needed + } +} +``` + +## Procedure +### 1. Create an XC20 asset +Follow the documentation on how to [Create XC20 Assets](/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/create-xc20-assets.md). + +### 2. Deploy the xcBurrito.sol smart contract +To deploy the XcBurrito contract you will need 2 input parameters +- Burrito ERC20 token address (H160) +- **XC20** asset address (H160) + - Follow the instructions about how to [Calculate an XC20 Address](/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/create-xc20-assets.md#calculate-xc20-precompile-address). For example, if the asset_id is 17 (=0x11), the resulting EVM address will be `0xffffffff00000000000000000000000000000011` + +### 3. Transfer XC Asset Ownership to the xcBurrito Smart Contract +To allow the **xcBurrito** contract to be able to mint/burn you need to call the `setTeam()` extrinsic on pallet-assets, and configure the `issuer` and `admin` to be **xcBurrito**. This will allow the contract to issue wrapped **XC20** assets, but since the EVM contract has 24 bytes (H160), we will need to transform the EVM address to ss58 format before we can call the extrinsic. + +![Set the team of XC20 asset by calling setTeam()](img/erc20-cross-chain-compatible-1.png) + +You can renounce ownership of the **XC20** by calling the `transferOwnership()` extrinsic on pallet-assets. Do note that after calling the extrinsic, you will no longer be able to +change the `issuer` or `admin` parameters, so you will want to ensure they are set correctly. + +![Renounce the ownership of an XC20 asset by calling transferOwnership()](img/erc20-cross-chain-compatible-2.png) + +Now the xcBurrito contract is able to mint **XC20** tokens for callers who own Burrito ERC20 tokens. + +## User Actions +To convert Burrito tokens into xcBurrito assets, users will need to perform the following actions. +1. Approve the xcBurrito smart contract to transfer ERC20 Burrito tokens from a user's balance, to the xcBurrito contract. As an alternative, the `permit()` call can be used to improve UX. +2. User calls xcBurrito `depositFor()` for minting new **XC20** tokens, or `withdrawTo()` for burning **XC20** tokens. +3. The newly wrapped assets are able to be transferred between chains, like any other **XC20** asset (please see the XCM documentation for more details). + +## End result +The result of `depositFor(user, amount)` will be: +- XcBurrito locks an `amount` of ERC20 Burrito token. +- User's balance of ERC20 Burrito is decreased by `amount` +- XcBurrito contract mints the same `amount` of xcBurrito assets +- User's balance of xcBurrito asset is increased by `amount` + + +The result of `withdrawTo(user, amount)` will be: +- XcBurrito contract burns an `amount` of XcBurrito asset +- User's balance of xcBurrito asset is decreased by `amount` +- XcBurrito contract transfers `amount` of ERC20 Burrito token to user +- User's balance of ERC20 Burrito is increased by `amount` diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/faq-for-smart-contracts.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/faq-for-smart-contracts.md new file mode 100644 index 0000000..1833896 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/faq-for-smart-contracts.md @@ -0,0 +1,14 @@ +--- +sidebar_position: 10 +--- + +# FAQ for Smart Contracts + +## Q: Unable to use `transferFrom` for XC20 (DOT, KSM...) in Solidity contract + +This was an issue when an account had to hold some amount of native currency in order to be eligible to receive foreign currency. +Since this was causing problems for our users, it was changed and no is no longer a requirement; now being able to pay gas with foreign assets. + +Please note that for custom assets, which aren't supported as payment asset by Astar or Shiden, account (or contract) still has +to hold at least the ED in native currency to be eligible to receive a custom asset. + diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/1.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/1.png new file mode 100644 index 0000000..4cb3bc8 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/1.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/10.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/10.png new file mode 100644 index 0000000..f53f9aa Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/10.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/11.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/11.png new file mode 100644 index 0000000..96c53c8 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/11.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/12.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/12.png new file mode 100644 index 0000000..97eae33 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/12.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/13.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/13.png new file mode 100644 index 0000000..a233982 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/13.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/14.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/14.png new file mode 100644 index 0000000..3f46b19 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/14.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/15.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/15.png new file mode 100644 index 0000000..de08648 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/15.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/16.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/16.png new file mode 100644 index 0000000..7344989 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/16.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/17.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/17.png new file mode 100644 index 0000000..47d155c Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/17.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/2.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/2.png new file mode 100644 index 0000000..c373801 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/2.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/3.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/3.png new file mode 100644 index 0000000..1920196 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/3.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/4.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/4.png new file mode 100644 index 0000000..31218f3 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/4.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/5.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/5.png new file mode 100644 index 0000000..abb530f Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/5.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/6.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/6.png new file mode 100644 index 0000000..b46de53 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/6.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/7.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/7.png new file mode 100644 index 0000000..748472c Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/7.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/8.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/8.png new file mode 100644 index 0000000..4f698eb Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/8.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/9.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/9.png new file mode 100644 index 0000000..2381221 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/9.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/erc20-cross-chain-compatible-1.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/erc20-cross-chain-compatible-1.png new file mode 100644 index 0000000..3940f42 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/erc20-cross-chain-compatible-1.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/erc20-cross-chain-compatible-2.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/erc20-cross-chain-compatible-2.png new file mode 100644 index 0000000..a5ef6db Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/erc20-cross-chain-compatible-2.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/001_dapps_staking_claim.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/001_dapps_staking_claim.png new file mode 100644 index 0000000..77ac60d Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/001_dapps_staking_claim.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/002_unsigned_transaction.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/002_unsigned_transaction.png new file mode 100644 index 0000000..f3b1137 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/002_unsigned_transaction.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/003_non_signed_tx_data.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/003_non_signed_tx_data.png new file mode 100644 index 0000000..622d4a6 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/003_non_signed_tx_data.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/004_rpc_query_info_weight_transact_call.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/004_rpc_query_info_weight_transact_call.png new file mode 100644 index 0000000..b918fe7 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/004_rpc_query_info_weight_transact_call.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/005_xcm_execute_weight_hack.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/005_xcm_execute_weight_hack.png new file mode 100644 index 0000000..5fa1083 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/005_xcm_execute_weight_hack.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/006_total_fee_for_execution.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/006_total_fee_for_execution.png new file mode 100644 index 0000000..0fde183 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/006_total_fee_for_execution.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/007_wasm_flipper_call.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/007_wasm_flipper_call.png new file mode 100644 index 0000000..53d8cc7 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/img/remote-transact/007_wasm_flipper_call.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/index.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/index.md new file mode 100644 index 0000000..c312d34 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/index.md @@ -0,0 +1,9 @@ +# Building with XCM + +
+ +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + + diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/native-transactions.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/native-transactions.md new file mode 100644 index 0000000..2f1d0a8 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/native-transactions.md @@ -0,0 +1,61 @@ +--- +sidebar_position: 1 +--- + +# Native XCM Transactions + +Let’s examine how to transfer native Relay Chain assets (DOT or KSM) to Astar or Shiden. + +For this demonstration we’ll be using the Polkadot.js portal. Regular users will be interacting through our portal where all this complexity will remain abstract. + +For this demonstration, we will transfer **KSM** tokens from Kusama to Shiden Network. + +## In Practise + +We will be using chopsticks for this demo (more info on the dedicated [chopsticks page](/docs/build/build-on-layer-1/environment/chopsticks.md). +This command will spawn a chopsticks network that will replicate current state of Kusama relay-chain and Shiden parachain allowing XCM: + +```bash +npx @acala-network/chopsticks@latest xcm -r kusama -p shiden +``` + +The Relay Chain native asset is represented on Astar or Shiden by asset Id `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF` or `340282366920938463463374607431768211455` in decimal. + +In the Shiden chopsticks [configs file](https://github.com/AcalaNetwork/chopsticks/blob/97b42a16d9f3fb32069eb2c19e05d7b80e250c3c/configs/shiden.yml#L25) Alice holds 100000KSM + +![1](img/1.png) + +Let's transfer some **KSM** from Kusama to Shiden using Alice. + +This will be an example of VMP protocol usage or DMP to be more specific. We will make use of the `reserve_transfer_asset` functionality. This consists of moving assets from one blockchain to another blockchain via an intermediary *Sovereign* account. In the process, origin chain assets won’t be destroyed, instead, the *Sovereign* will hold them, while the target chain mints wrapped versions, and deposits them to the target address. + +The *Sovereign* account ensures that the same assets cannot be used simultaneously on both chains. It also guarantees that the wrapped assets are interchangeable with the assets on the origin chain. + +Alice wants to send some tokens to herself on Shiden Network, so she prepares a `reserve_transfer_asset` call on the Relay Chain. The parameters look like this: + +![XCM message to send KSM from Kusama to Shiden via reserveAssetTransfer](img/2.png) + +We should specify: + +- Destination + - Using the MultiLocation notation, we describe the target chain, which is Shiden, as `/Parachain(2007)`. The notation resembles filesystem paths where the Relay Chain is considered to be root. +- Beneficiary + - Once again using the *MultiLocation* notation, we describe the beneficiary of the asset transfer. Take note that this is the context of the destination chain. We’re transferring to Alice whose address is `ajYMsCKsEAhEvHpeA4XqsfiA9v1CdzZPrCfS6pEfeGHW9j8` on Shiden. But instead of specifying the Shiden address, we’ll specify the account ID (or public key) associated with this address: `0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d` +- Assets being transferred + - Finally, we describe the assets being transferred. Since we’re transferring native Relay Chain assets, we specify these are **Concrete assets** and their location is **Here** in the context of the Relay Chain. The asset is fungible, therefore we need to specify the amount being transferred, in this case, a total of **1000000000** tokens. + +After initiating the transfer, we can observe what happens on the Relay Chain: + +![Execution of an XCM message was attempted and funds were transferred from Alice to the Sovereign account.](img/3.png) + +Execution of an XCM message was attempted and funds were transferred from Alice to the Sovereign account. + +On the Shiden side, we can observe the following: + +![4](img/4.png) + +XCM message has been received and instructions executed. As a result, an asset with Id `340282366920938463463374607431768211455` has been minted, a total of **996000000** tokens. These tokens have been deposited into the designation account. + +Note that that received amount is less than what was originally sent. This is because **4000000** has been used to pay the transaction fee on the destination chain. + +We’ve successfully transferred **KSM** assets from Kusama over to Shiden! diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/send-xc20-evm.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/send-xc20-evm.md new file mode 100644 index 0000000..49840d3 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/send-xc20-evm.md @@ -0,0 +1,95 @@ +--- +sidebar_position: 3 +--- + +# Using XC20 Assets in EVM + +## Overview + +Using XCM within the EVM environment is entirely possible because Astar network uses the XC20 interface, which maps native assets listed in the Assets pallet to an ERC20-compatible interface that EVM dApps can use. + +:::info + +XC20s and ERC20s are similar, but there are distinct differences to be aware of since XC20s are Substrate-based assets. + +One of the XC20-specific features is the existence of a **minimum-balance** threshold, specific to each asset. The minimum-balance of an asset resembles an amount which is sufficient to allow the account's existence on the system without requiring any other existential-deposit. The implication of this feature is that when transferring a certain amount of XC20 tokens, the actual amount transferred may be slightly greater in the case that the transfer would otherwise take the sender balance above zero, but below the minimum balance. + +In addition, XC20 transactions executed via the Substrate API won’t be visible from EVM-based block explorers such as Blockscout. Only transactions executed via the Ethereum API will be visible through those explorers. + +XC20s can interact through an ERC20 interface, so have the additional benefit of being accessible from both the Substrate and Ethereum APIs. This ultimately provides greater flexibility for developers when working with these types of assets, and allows seamless integrations with EVM-based smart contracts such as DEXs, lending platforms, and others. + +::: + +## Transfer XC20 to EVM address + +First, let’s approach this at a high level, and move on to a more technical example for dApps. + +Let’s say we want to transfer some KSM token from Kusama to `0xd2C6929A72e466213D1c2Df8359194784650A50e`. From the Kusama side of things, the payload for sending the KSM tokens will be similar to the ones we used in the previous [section](/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/native-transactions.md). +However, the `Beneficiary` address `AccountId` will be a mapped ss58 address of the recipient’s EVM address, as that is the only address format that XCM will accept. You can read [this article](https://medium.com/astar-network/using-astar-network-account-between-substrate-and-evm-656643df22a0) about how to create the mapped address. To keep things short, the address mappings are: + +- **H160**: `0xd2C6929A72e466213D1c2Df8359194784650A50e` +- **ss58**: `YPRZVFHaRvXdnbAQsXcgqiJokpoHNkUXzR6XTBBJQKHtorT` (with prefix 5 for Shiden/Astar) +- **Public key**: `0x6c65500b73e2cec702f06dcd5299b31e4d0b6cf7728937b7d5edac79611292f2` + +To obtain the asset address on the EVM, we will need to retrieve its asset `Id`. In our case, we will be using KSM, which has the asset `Id` `340282366920938463463374607431768211455`. Now we will need to convert the `Id` to hex, and append it to `0xffffffff`. In this example, the resulting address is `0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF`, which we can now use directly within Solidity smart contracts, or MetaMask. More info in previous [section](/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/send-xc20-evm.md#calculate-xc20-precompile-address) + +## Import Assets on MetaMask + +On the previous page, we created a new asset and generated the contract address. Now, let's add it to MetaMask: + +:::caution + +If you can't enter anything in the decimals field, then you haven't minted any assets. Ensure you have minted some assets before proceeding to the next step. + +::: + +1. Make sure you are connected to [the network](https://app.gitbook.com/o/-LgGrgOEDyFYjYWIb1DT/s/-M8GVK5H7hOsGnYqg-7q-872737601/~/changes/aJQFFWQNMjlao1SSjj4a/integration/network-details) where you created your token. +2. Near the bottom of the asset overview section, click Import Tokens. +3. Enter the following: + 1. Token Contract Address + 2. Token Symbol + 3. Token Decimals + +![Add Custom Token](img/9.png) + +As you can see in the image above, importing an asset by its contract address will allow MetaMask to read the metadata correctly, and add it to your wallet. + +![Assets overview](img/10.png) + +## Transfer XC20 assets to EVM + +### Step 1: Obtain the ss58 Native Address Mapped to your EVM Address + +To transfer your newly minted assets to the EVM, you will need to obtain the mapped ss58 (Substrate native) address linked to your H160 (MetaMask) address. You are able to obtain that address by following these steps: + +1. Open our EVM to Substrate address [converter](https://hoonsubin.github.io/evm-substrate-address-converter/). +2. Switch to the H160 address scheme. +3. Copy your EVM address from MetaMask and paste it into the Input address field. +4. Your mapped native address will be displayed. + +![EVM to Substrate address converter](img/11.png) + +### Step 2: Send asset to an EVM address + +For this section, we need to return to [Polkadot.js Apps](https://polkadot.js.org/apps/). Make sure you are connected to the same network on which you created your asset. + +In this guide, we will send 1000 of the newly minted assets to an EVM account. + +1. Navigate to `Developer -> Extrinsics` +2. Use the `assets -> transfer` extrinsic. +3. Select the account that has permission to send the asset. +4. Enter the `asset id`. See the previous page to determine what asset id you will need to enter. In this example, we are using `19992021`. +5. Enter your native address in the `Id` field, the one you received after converting your EVM address to native. +6. The last field is the amount, and we want to send `1000` tokens. In this example, we enter `1000` followed by 18 zeros, due to the asset requiring 18 decimals of precision. +7. Sign and Submit the transaction. + +![Overview](img/12.png) + +![XC20 on MetaMask](img/13.png) + +:::info + +- We are working closely with our block explorers to map new assets, so they will be visible in our explorers. +- If you receive an error transferring your tokens to another EVM account, try increasing the gas fee. + +::: \ No newline at end of file diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/xc-assets-withdraw.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/xc-assets-withdraw.md new file mode 100644 index 0000000..1260117 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/xc-assets-withdraw.md @@ -0,0 +1,54 @@ +--- +sidebar_position: 8 +--- + +# Withdraw Assets + +In the Polkadot ecosystem there are two ways to transfer assets between remote chains: teleportation and reserve transfer. Teleportation is essentially burning an asset on one side, and minting it on the other, so that the total balance before and after the teleportation remains the same. + +The second way to transfer assets uses wrapped tokens, backed by assets on the origin chain. Assets to be transferred are locked on the origin chain, and 1:1 versions are created on the destination. Depending on the business logic, the origin chain that still owns the assets, may want to mint some derivatives to reflect that ownership. In this way, the original assets don't actually leave the chain, but their ownership becomes transferrable. + +Suppose we would like to import Shibuya `SBY` tokens as wrapped assets on Shiden, resulting in `wSBY`. + +- Shibuya network will need to have Shiden's sovereign account. This account is controlled by Shiden and represents all funds sent to it, from the remote chain (Shiden, from Shibuya's perspective in this example). +- Shiden network will need create the `wSBY` asset, and configure it to act as a cross-chain (XC20) asset. +- HRMP channels should both be enabled, and configured for parachains to communicate and exchange XCM messages. +- In order pay for execution time, `wSBY` should be configured as a payment asset on Shiden. + +During the transfer the following will occur: +1. An amount of `SBY` are moved from the source account to the sovereign account of Shiden on Shibuya. +2. An XCM message containing the `ReserveTransferAssets` instruction is sent to Shiden. +3. The `ReserveTransferAssets` instruction is processed by the `assets` pallet on Shiden, and the corresponding amount of `wSBY` is minted on Shiden. +4. Minted `wSBY` tokens are deposited to the destination account. +5. A small amount of `wSBY` is deducted from the destination account as payment for execution time + +**Note:** The above example is specific to the implementation of two particular parachains. XCM does not dictate or impose any restrictions on how to interpret incoming messages, or how to manage derivative assets. Other parachains may or may not use the `assets` pallet; the only assumption is that `assets_reserve_transfer` will form an XCM message with an origin specified by its `parachain_id`. Everything else is dependent on the remote chain and its logic, and there are no retries attempted on failure. + +# EVM precompiles + +This functionality is exposed to EVM smart contracts via precompiles. The interface can be found [here](https://github.com/AstarNetwork/Astar) under XCM precompiles. + +```js + function assets_reserve_transfer( + address[] calldata asset_id, + uint256[] calldata asset_amount, + bytes32 recipient_account_id, + bool is_relay, + uint256 parachain_id, + uint256 fee_index + ) external payable returns (bool); +``` + +- `asset_id` - A list of assets to transfer; for transferring native assets, see the next section. +- `asset_amount` - The corresponding amount of assets. +- `recipient_account_id` - The recipient account id on the destination chain (or a Relay Chain). +- `is_relay` Is true if destination account is on the Relay Chain. +- `parachain_id` - The destination parachain id. +- `fee_index` - Which asset from `asset_id` is use for paying XCM fees. + +**Note:** there is another version of `assets_reserve_transfer` precompile that accepts `address` instead of `bytes32` for the `recipient_account_id`. + + +# Implementation details + +Astar uses a custom XCM pallet that was extended by `reserve_withdraw_assets`. diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/xc-remote-transact.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/xc-remote-transact.md new file mode 100644 index 0000000..d6f20ca --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/xc-remote-transact.md @@ -0,0 +1,213 @@ +--- +sidebar_position: 6 +--- + +# Remote Transact via XCM + +:::danger +This section contains contents for developers only. + +XCM message format is generally used for low level instruction and information exchange between parachains and can cause loss of funds if used improperly. + +Network users are advised to use dApps and tooling built around XCM instead. + +::: + +## Feature Overview + +The XCM `Transact` instruction allows the sender to execute arbitrary calls on the destination chain. This feature is extremely useful since it allows us to control accounts on a remote chain. + +For example, a user can send a `Transact` instruction from **Astar** to **Polkadot** that transfers `DOT` from their derived account on **Polkadot** to an arbitrary receiver account on **Polkadot**. They don't need to interact directly with the **Polkadot** chain, but nevertheless are able to change its state. It's important to note that this is only one example - any call that can be interpreted by the remote (destination) chain is able to be sent and executed. + +This is of particular use for smart contracts, since it allows them to integrate custom logic for cross-chain interoperability. + +It's important to understand the difference between sending an XCM instruction sequence and receiving/interpreting it. + +Sending an XCM transaction from `Astar` or `Shiden` to a remote chain may be successful on the sender side, but fail to execute on the destination, and the same is true for the opposite scenario. This can happen for multiple reasons - the XCM sequence might be incorrect, the remote chain doesn't know how to inrerpret the provided `call`, or the remote chain doesn't allow remote execution, at all. + +The developer or user must ensure that the destination chain supports the encoded call and remote transactions, in general, before they initiate the XCM transaction. + +## Remotely Transact on Astar/Shiden/Shibuya + +### XCM Sequence + +At the moment, remote execution from origins other than parachain accounts are only allowed to be initiated by the `Shibuya` runtime and `Shiden` runtime. + +A permissible sequence of instructions will therefore have to start like: + +1. `DescendOrigin` +2. `WithdrawAsset` +3. `BuyExecution` +4. `Transact` or `SetAppendix` or _whatever user wants_ + +This XCM sequence, used as a prefix, may be followed by arbitrary instructions, for example: `Transact`. +Although we cannot guarantee it, other chains will most likely adopt the same or a similar prefix for XCM instruction sequences. + +#### DescendOrigin + +The DescendOrigin parameter ensures that the origin isn't a parachain, but a more complex junction like `{ parachain: 2006, accountId: 0x123aff....ff }`. If this is omitted, all calls will be executed as if they were sent from the _root-only_ parachain's sovereign account, which we do not allow. + +#### WithdrawAsset + +Withdraws assets on the destination chain from the derived sender account. The account must have the specified asset and the requested amount, otherwise the instruction will fail. These assets are used to pay for the XCM execution time. + +#### BuyExecution + +Buys XCM executuion time, using the withdrawn assets. + +#### Transact + +Execute the specified encoded call data, without consuming more weight than specified. +Call data can be virtually anything supported by the remote chain - it doesn't matter what the origin chain supports. + +## Derived Remote Accounts + +When executing a remote transaction, the remote chain will derive a new address based on the sender's multilocation. +The way this address is derived is determined by the chain itself so this documentation cannot guarantee how any other chain but Astar-based chains. + +For Astar-based runtimes, a generalized approach, aligned with `Polkadot` and `Kusama` is used. +Multilocation is SCALE-encoded, step-by-step, until finally it is hashed using the `Blake2_256`, with the output being the derived address. + +| Name | Value | +| --------------------------- | --------------------------------------------------------------------------------------------- | +| Alice's Address in Polkadot | 15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5 | +| Alice's Public Key | 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d | +| Alice's Multiloc in Astar | \{ parents: 1, interior: AccountId32 \{network: NetworkId::Polkadot, id: 0xd4359...a27d \} \} | + +--- + +For example, let's assume `Alice` is sending an XCM sequence from `AssetHub` to `Astar`. +Sibling parachain's account is derived using a simple approach: + +`blake2_256(("SiblingChain", compact_parachain_id, b"AccountId32", public_key).encode())` + +| Name | Value | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| Alice's MultiLoc in Astar | \{ parents: 1, interior: X2(Parachain(1000), AccountId32 \{network: NetworkId::Polkadot, id: 0xd4359...a27d \}) \} | +| Alice's Derived Account | 0x88275533b5d43292c86d05985c3a6e226fee2baeddb4f3b90e30a70bec4d7bff | + +Similarly, in case `Alice` is sending XCM from a chain that uses **H160** address format: + +`blake2_256(("SiblingChain", compact_parachain_id, b"AccountKey20", public_key).encode())` + +--- + +In case `Alice` is sending XCM from `Polkadot`, the encoded data changes a bit and would be like: + +`blake2_256((b"ParentChain", b"AccountId32", public key).encode())` + +| Name | Value | +| ------------------------- | ------------------------------------------------------------------------------------------------- | +| Alice's Multiloc in Astar | \{ parents: 1, interior: X1(AccountId32 \{network: NetworkId::Polkadot, id: 0xd4359...a27d \}) \} | +| Alice's Derived Account | 0x7dcb1027ecb97011ebe79ca233def50d1f216eb05d76367c8984f67ccc5d2dd1 | + +--- + +You can use the `xcm-tools` binary to generate the derived address, based on your needs. + +## Remotely Transact via EVM Smart Contracts + +Astar allows EVM smart contracts to send `Transact` instructions to remote chains, giving them the ability to execute arbitrary calls. + +### XCM Sequence + +To simplify the API via which EVM smart contracts send the `Transact` instruction, and to ensure security, we expose a function that builds a sequence like: + +1. `DescendOrigin` +2. `WithdrawAsset` +3. `BuyExecution` +4. `Transact` + +`DescendOrigin` will ensure that the origin is correctly set to be the smart contract's derived ss58 address. + +`WithdrawAsset` at the moment requires that asset representation is present in our runtimes. However, it is expected that the remote chain's derived address will be funded so it can pay for XCM execution. + +`BuyExecution` will use the previously withdrawn assets. The `weight_limit` will be set to `Unlimited`. This isn't too important for the instruction sequence being used, since the user controls the maximum allowed weight via the amount of withdrawn assets. However, the funds should be sufficient to pay for both the XCM sequence execution, and the encoded remote call. + +`Transact` will execute the encoded call. The `origin_type` is set to `SovereignAccount` and cannot be changed by the end user. + +There are no refunds at the end of sequence. Unused weight will be handled by the remote chain. + +### Remotely Derived Contract Address + +For example, let's assume you have a contract deployed on Shibuya and are calling the XCM precompile `remote_transact` with the intention of sending an XCM sequence to a sibling parachain. This sibling parachain uses the same address derivation as do our runtimes. The address derivation path will look like this: + +| Name | Address | +| ----------------------------- | -------------------------------------------------------------------------------------------------------------- | +| Contract H160 Address | `0x48DD0a20a199f96B56eCE7e994D83614A148aA63` | +| Contract Derived SS58 Address | `agn53DdEuRgQsvgxqj5M1AecxB6LpbXT7T1R1hjVcoEBR6M` | +| SS58 Address Public Key | `0xd219fe1b02545c7dd7e718b1530b4e32b23288351f61e5975c7dc49b004ff119` | +| Caller Multilocation | `{ parents: 1, interior: X2 ( Parachain(2000), AccountId32 {network: NetworkId::Any, id: 0xd219f...f119 } ) }` | +| Derived Remote Address | `5FrhDFydxUwbWyXT1XDBhRUUYpQtiJJ6skB6n2XV4NubC9fP` | + +:::note +The remote address derivation scheme has changed after writing the initial example but the whole process is otherwise still valid and correct. +::: + +This means that the instructions like `WithdrawAsset` and `Transact` will be executed as if origin was address `5FrhDFydxUwbWyXT1XDBhRUUYpQtiJJ6skB6n2XV4NubC9fP`. + +### Precompiles API + +`Transact` functionality is exposed to EVM smart contracts via precompiles. The interface can be found [here](https://github.com/AstarNetwork/Astar) under XCM precompiles. + +```solidity + function remote_transact( + Multilocation memory destination, + address payment_asset_id, + uint256 payment_amount, + bytes calldata call, + WeightV2 memory transact_weight +) external returns (bool); +``` + +The `destination` is the Multilocation of destination chain and can either be a sibling parachain `Id` or the Relay Chain (in which case parachain `Id` is ignored). +`payment asset Id & amount` - Determines which asset to withdraw on the destination chain and how much. Used to pay for execution time. Current limitation is that the asset used must have a local derivative since it's referenced via H160 address. +`call` - The encoded call to be executed on the remote chain. +`transact_weight` - The max weight that can be consumed by the execution of the call on the remote chain. + +Continue reading below to gain a better understanding of how to calculate these parameters. + +### Payment Asset + +At the moment, users can only specify the paymet asset via a `H160` address. Even though the payment asset references an asset in the destination chain, the remote asset must have a local derivative. This will be updated and improved in the future so that users can specify asset multilocations directly. + +In case the user wants to pay using a local currency derivative (wrapped ASTR or SDN) on the destination chain, a specialized H160 address padded with zeroes,`0x0000000000000000000000000000000000000000`, should be used. + +### Transaction Weight + +Specifying the correct amount of assets to withdraw and buy execution time with, as well as choosing the correct transaction weight, can be tricky. Neither are controlled by the `Astar` or `Shiden` runtimes, instead, these parameters are handled by the runtime of the destination chain. There are a few points and tips that can help user calculate the correct values. + +The asset required for payment is used for two distinct executions: + +1. XCM instructions - There are 4 XCM instructions in the sequence, and each one is weighed by the destination chain in order to determine how much should be paid for their execution. For quite sometime both parachains and relay used benchmarked weights for each XCM instructions, please check the destination relay/parachain weights for XCM. Astar XCM weights can be found [here](https://github.com/AstarNetwork/Astar/tree/master/runtime/astar/src/weights/xcm). +2. Call weight - The weight of the `call` on the remote chain. + +The withdrawn asset amount must therefore cover `[Sum of XCM instr weight] + weight(call)` units of weight. (For example, see weight for `WithdrawAsset` intr for astar [here](https://github.com/AstarNetwork/Astar/blob/19b60fa2b831d4b5c5a935ee29233c0727150d45/runtime/astar/src/weights/xcm/fungible.rs#L138)). + +The weight of the `call` is determined by the destination chain's runtime, so is not controlled by either `Astar` or `Shiden`. Users should be sure to weigh the remote call correctly on the destination chain, before sending it via XCM. + +Keep in mind that these values may change - if a destination runtime gets upgraded or reconfigured, the values could change and you will need to adjust them in your smart contract. + +### Calculating Values + +Astar cannot guarantee that the following approach will work on all parachains, since each of them can be customized independently. But generally, all parachains should have access to these methods. + +Let's assume for this example that we're on some other chain, and want to execute a transaction remotely on `Astar`. + +**Step 1** Visit `Astar` network in _polkadot-js_ and locate the extrinsic we would like to execute. For the sake of simplicity, let's assume it's `dappsStaking->claimStaker`, although it could be any call. Fill all arg fields. Then copy the `encoded call data` (click on the copy icon). + +![1-encoded-call](img/remote-transact/001_dapps_staking_claim.png) + +**Step 2** Go to Developer > Runtime calls and select `transactionPaymentCallApi -> queryCallInfo` and paaste the encoded call data into the `call` field. Then click on `Submit Runtime call`. + +![2-sign-no-submit](img/remote-transact/002_unsigned_transaction.png) + +**Step 3** Requires a bit of a workaround. We need to know how much the cost is to execute a **single** XCM instruction on the destination chain. The only reliable way to know this is to check with other parachain team to learn the exact value. + +| Name | Amount of weight `ref_time` | +| ---------------- | --------------------------------------- | +| Call | 886_264_000 | +| XCM instructions | [Sum of cost of XCM intr in destination chain] | +| Total | 4_886_264_000 | + +The total weight is **4_886_264_000** units of `ref_time` and **24_668** of `proof_size`. In order to maximize the chance of successful execution, we should add a sefety limit of +10% to the total weight. So `ref_time`: **5_374_890_400** and `proof_size`: **27_134**. diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/xc-reserve-transfer.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/xc-reserve-transfer.md new file mode 100644 index 0000000..874b38a --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/xc-reserve-transfer.md @@ -0,0 +1,76 @@ +--- +sidebar_position: 7 +--- + +# Transfer Reserve Assets + +XCM allows us to transfer assets from one chain to another in several ways. In this chapter we'll examine how to use reserve transfers. + +Suppose we would like to import Shibuya `SBY` tokens as wrapped assets on Shiden, resulting in `wSBY`. + +- Shibuya network will need to have Shiden's sovereign account. This account is controlled by Shiden and represents all funds sent to it, from the remote chain (Shiden, from Shibuya's perspective in this example). +- Shiden network will need create the `wSBY` asset, and configure it to act as a cross-chain (XC20) asset. +- HRMP channels should both be enabled, and configured for parachains to communicate and exchange XCM messages. +- In order pay for execution time, `wSBY` should be configured as a payment asset on Shiden. + +During the transfer the following will occur: +1. An amount of `SBY` are moved from the source account to the sovereign account of Shiden on Shibuya. +2. An XCM message containing the `ReserveTransferAssets` instruction is sent to Shiden. +3. The `ReserveTransferAssets` instruction is processed by the `assets` pallet on Shiden, and the corresponding amount of `wSBY` is minted on Shiden. +4. Minted `wSBY` tokens are deposited to the destination account. +5. A small amount of `wSBY` is deducted from the destination account as payment for execution time + +**Note:** The above example is specific to the implementation of two particular parachains. XCM does not dictate or impose any restrictions on how to interpret incoming messages, or how to manage derivative assets. Other parachains may or may not use the `assets` pallet; the only assumption is that `assets_reserve_transfer` will form an XCM message with an origin specified by its `parachain_id`. Everything else is dependent on the remote chain and its logic, and there are no retries attempted on failure. + +# EVM precompiles + +This functionality is exposed to EVM smart contracts via precompiles. The interface can be found [here](https://github.com/AstarNetwork/Astar) under XCM precompiles. + +```js + function assets_reserve_transfer( + address[] calldata asset_id, + uint256[] calldata asset_amount, + bytes32 recipient_account_id, + bool is_relay, + uint256 parachain_id, + uint256 fee_index + ) external payable returns (bool); +``` + +- `asset_id` - A list of assets to transfer; for transferring native assets, see the next section. +- `asset_amount` - The corresponding amount of assets. +- `recipient_account_id` - The recipient account id on the destination chain (or a Relay Chain). +- `is_relay` Is true if destination account is on the Relay Chain. +- `parachain_id` - The destination parachain id. +- `fee_index` - Which asset from `asset_id` is use for paying XCM fees. + +**Note:** there is another version of `assets_reserve_transfer` precompile that accepts `address` instead of `bytes32` for the `recipient_account_id`. + +# Transferring Native Assets + +Current API identifes assets being transferred by specifying an H160 style address (XC20). This prevents us from sending native tokens since there's no representation for it. However, there is a workaround for that which uses a special H160 address, padded with zeroes `0x0000000000000000000000000000000000000000` and by convention, is interpreted as a command to send the native token (`MultiLocation { parents: 0, interior: Here }`). + +For example, an EVM call such as: +``` +reserve_transfer: + asset_id = [ "0x00...0" ] + asset_amount = [ "333333333" ] + ... + fee_index = 0 +``` + +The precompile internals will transform call args into something like this: +``` +assets = [{ parents: 0, interior: Here }] +asset_amounts = [ 333333333 ] +``` + +Native assets can be used for paying transaction fees like any other assets. In that case, the `fee_index` should point to the `asset_id` entry containing `0x00...0`. + +# Transaction Fees + +Every transaction must be paid for. This mechanism is implemented to prevent transaction floods by disincentivizing misuse of the network, so only those tokens that have real value can be used to pay for execution fees. + +Commonly, we will pay for transactions using the network native token, and it's expected that its emission is controlled and will not cause problems, however in some cases it may be necessary to allow users to pay for transactions, using foreign assets only. + +To achieve that, the remote chain should be configured to allow payment of XCM execution, in that particular asset. diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/xc20-smart-contracts.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/xc20-smart-contracts.md new file mode 100644 index 0000000..8649fa7 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/xc20-smart-contracts.md @@ -0,0 +1,72 @@ +--- +sidebar_position: 5 +--- + +# XC20 in Smart Contracts + +So far we’ve successfully transferred assets from Kusama to Shiden and shown how we can access those assets the same as any other within MetaMask. Now we will take it one step further and demonstrate how to use these assets with smart contracts. + +Here is an example staking contract we’ll be using for the demonstration (for DOT, replace `ksm` with `dot`): + +:::note +XC20 address of relay chain token (KSM and DOT) is `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF` (because `Id` `340,282,366,920,938,463,463,374,607,431,768,211,455` to hex is `FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF`). +To use this address inside a solidity smart-contract, check sum of the address should be respected. Please use [toChecksumAddress](https://web3-tools.netlify.app/) converter that will convert your address. +for example `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF` will be converted to `0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF` +::: + +```js +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.0; + +// A partial ERC20 interface, just for the demo purposes +interface IERC20 { + function balanceOf(address owner) external view returns (uint256); + function approve(address spender, uint256 amount) external returns (bool); + function transfer(address to, uint256 amount) external returns (bool); + function transferFrom(address from, address to, uint256 amount) external returns (bool); +} + +contract XC20_Demo { + IERC20 public ksm = IERC20(0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF); + mapping(address => uint256) public stakers; + + constructor() payable {} + + function stake(uint256 amount) public { + require(ksm.transferFrom(msg.sender, address(this), amount)); + stakers[msg.sender] += amount; + } + + function unstake(uint256 amount) public { + require(stakers[msg.sender] >= amount); + require(ksm.transfer(msg.sender, amount)); + stakers[msg.sender] -= amount; + } +} +``` + +Using the partial ERC20 interface (all methods are actually supported), we can check the balance of the account we used previously: `0x107bAe763DC63e0686C574FdE1B58115c7d19280` + +![14](img/14.png) + +The amount shown is the same amount we see in MetaMask, **15 KSM** in total. + +Now, Lets stake 5 KSM in our simple staking dApp. The first step will be to approve the staking demo contract `0x62425e07119144B5D5A16D96430c31aD0E17A877` for the transfer, using the IERC20 interface: + +![15](img/15.png) + +Now we can stake 5 KSM. + +![16](img/16.png) + +After the operation is complete, we can check the staked amount. + +![17](img/17.png) + +We’ve successfully staked 5 KSM! + +To summarize what we’ve done so far: + +1. Transferred KSM tokens from Kusama to Shiden. +2. Verified the tokens are present within MetaMask. +3. Confirmed we are able to manipulate the XC20 tokens in the same way as other ERC20 tokens, via smart contract. diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/faq.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/faq.md new file mode 100644 index 0000000..6d3928f --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/faq.md @@ -0,0 +1,53 @@ +--- +sidebar_position: 5 +--- + +# FAQ + +## Q: Is there a way to see my DOT/SDN balance (on Astar/Shiden) on the Polkadot.js? + +Yes. visit Polkadot.js, connect your wallet and go to Network > Balances and select the token you are interested in. The example below demonstrates how to view the SDN balance: + +![Viewing KSM balance on Shiden Network](img/1.png) + +## Q: I used XCM to transfer 5 DOT from Polkadot to Astar, but only received 4.999 + +Please note that the gas amount will be deducted from the amount entered, so the amount transferred should be adjusted according to account for the gas fee estimate. For more information, visit [here](/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/index.md) + +## Q: My balance should be 1.00012 DOT but the Portal is displaying 1 DOT, where are they? + +The current version of Astar Portal rounds balances to the 3rd decimal. If you have a similar issue please refer to the [previous FAQ entry](/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/faq-for-smart-contracts.md) and instructions on how to use Polkadot.js to find your exact balance. + +## Q: Can I send my DOT token to other Parachains? + +Not at the moment. + +## Q: How can I send my DOT token back to Polkadot? + +You can send back DOT/KSM to the Relay Chain using both EVM and native wallets. Visit the Assets Page and choose the XCM link of the relevant token. + +## Q: Why is the XCM button for DOT/KSM disabled when I connect my wallet on the Astar Portal? + +Ensure you have a non-zero balance of the native token. + +## Q: I transferred X tokens to another account, but the amount transferred and received by the target account is greater than X. What is going on? + +XC20 assets have a defined minimum-balance. The minimum-balance is the minimum balance of an asset that any single account must have. In this specific case, if an account's balance would be reduced below that amount in an asset transfer transaction, then the amount actually transferred would include the remaining amount of specific asset on the initiating account. + +Take a look at an example of a transaction in case of an asset whose minimum-balance is 10: Alice has 10.9 tokens and tries to send Bob 10 tokens. Alice's remaining balance in that case would become 0.9, which is less than minimum amount, so the amount transferred would be set to 10.9 tokens, so Alice's balance will become 0, to avoid any funds being reaped by not fulfilling the Existential Deposit. + +For more information, check out this [section within our documentation](/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/send-xc20-evm.md). + +## Q: Where can I find other chains' addresses? + +You can find all the different chains' addresses in Polkadot/Kusama : + +1. Using [Sub ID](https://sub.id/) + +Simply input your Astar native address and you will be able to see all the related addresses of the account. + +2. Display it on Polkadot.js extension by selecting the chain you would like to know the address of. + +Please note that you will only be able to make an XCM withdrawal if the receiver's Relay Chain account balance is greater than the Minimum Balance (1.1 DOT for Polkadot and 0.01 KSM for Kusama). + + diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/img/1.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/img/1.png new file mode 100644 index 0000000..97f007b Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/img/1.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/index.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/index.md new file mode 100644 index 0000000..3bcf66f --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/index.md @@ -0,0 +1,38 @@ +# XCM + +## Astar's Vision + +[The Astar Vision Part 1: Interoperability and Multi-chain dApps](https://medium.com/astar-network/the-astar-vision-part-1-interoperability-and-multi-chain-dapps-30f014087831) + +[The Astar Vision Part 2: Asset Diversity Through XCM dApps and Smart Contracts](https://medium.com/astar-network/the-astar-vision-part-2-asset-diversity-through-xcm-dapps-and-smart-contracts-3a689dee5b77) + +[The Astar Vision Part 3: The Innovation Hub of Web3.0](https://medium.com/astar-network/the-astar-vision-part-3-the-innovation-hub-of-web3-0-1cace547aba3) + + +## Basic information + +XCM, the Cross(X)-Consensus Message format, is a messaging protocol that enables communication between blockchain networks with different consensus models, not just Polkadot Parachains. XCM supports arbitrary message passing, asset transfer, and remote function calls, facilitating interoperability between different chains. This means that developers can use XCM to build not only Parachain-native dApps, but also true multi-chain dApps that span multiple blockchains. + +With XCM, developers can create decentralized applications that execute functions across multiple chains, improving the user experience and creating new opportunities for cooperation and integration with other projects. XCM enables the development of cross-chain DEXs and other applications that require communication across multiple blockchain networks. + +While XCM is only one message format supported by the Polkadot network, it offers significant benefits over other message passing systems. For example, XCMP (sometimes known as HRMP) is a highly scalable and protocol-agnostic transport system for horizontal message passing between parachains that supports all arbitrary messages. In contrast, VMP (Vertical Message Passing) involves message passing between the Relay Chain and a parachain, where all message data exists on the Relay Chain. This makes VMP less scalable than XCMP. + +## External References + +Readers and developers are encouraged to go over the official documentation to learn more about XCM and the protocols, before diving in on the specific usage of XCM on Astar and Shiden Networks: + +- [Learn Cross-chain](https://wiki.polkadot.network/docs/learn-crosschain) +- XCM articles by Gavin Wood: [part 1](https://medium.com/polkadot-network/xcm-the-cross-consensus-message-format-3b77b1373392), [part 2](https://medium.com/polkadot-network/xcm-part-ii-versioning-and-compatibility-b313fc257b83), and [part 3](https://medium.com/polkadot-network/xcm-part-iii-execution-and-error-management-ceb8155dd166). +- [XCM format](https://github.com/paritytech/xcm-format) (consult while reading the articles) +- [Sub0 - Getting Started with XCM](https://www.youtube.com/watch?v=5cgq5jOZx9g) +- [How to make a cross-chain transfer](https://www.youtube.com/watch?v=5cgq5jOZx9g) + +## Get Started + +
+ +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + + diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/_category_.json b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/_category_.json new file mode 100644 index 0000000..06e148a --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Integration", + "position": 3 +} \ No newline at end of file diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/add-to-portal.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/add-to-portal.md new file mode 100644 index 0000000..01b4910 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/add-to-portal.md @@ -0,0 +1,104 @@ +--- +sidebar_position: 5 +--- + +# Add assets to Astar Portal + +Once a channel is opened between parachains and assets have been registered, developers can create a PR on [Astar Portal](https://github.com/AstarNetwork/astar-apps) Github, to have their assets added. Here’s what you need to know about the integration of the XCM assets into Astar Portal. + +## Define the Parachain Information + +1. Add the `Chain name` for the [Chain](https://github.com/AstarNetwork/astar-apps/blob/main/src/v2/models/XcmModels.ts#L2) enum. +2. Add the `parachain id` for the [parachainIds](https://github.com/AstarNetwork/astar-apps/blob/main/src/v2/models/XcmModels.ts#L17) enum. +3. Add the `chain metadata` for the [xcmChainObj](https://github.com/AstarNetwork/astar-apps/blob/main/src/modules/xcm/index.ts#L48) object variable. + + e.g. + +``` + interface XcmChain { + name: Chain; + parachainId: parachainIds; + relayChain: Chain; + subscan: string; + // Note: an image URL address for the chain logo + img: string; + // Note: websocket endpoint for connecting to the parachains API + endpoint: string; + // Note: `true` if ASTR/SDN is listed on the parachains + isAstarNativeToken: boolean; +} + + const xcmChainObj = { + [Chain.STATEMINT]: { + name: Chain.STATEMINT, + relayChain: Chain.POLKADOT, + img: 'https://polkadot.js.org/apps/static/statemine.65437936..svg', + parachainId: parachainIds.STATEMINT, + endpoint: 'wss://statemint-rpc.dwellir.com', + subscan: 'https://statemint.subscan.io', + isAstarNativeToken: false, + } +``` + +## Define the Asset Information + +Add the asset information for the [xcmToken](https://github.com/AstarNetwork/astar-apps/blob/main/src/modules/xcm/tokens/index.ts#L15) object variable. + +e.g. + +``` +interface XcmTokenInformation { + symbol: string; + logo: string; + originChain: string; + isNativeToken: boolean; + isXcmCompatible: boolean; + // Note: Asset ID on Astar/Shiden + assetId: string; + // Note: Asset ID on the origin chain + originAssetId: string; + // Note: this amount should be at lest higher than the Existential Deposit on the origin chain + minBridgeAmount: string; +} + +const xcmToken = { + [endpointKey.ASTAR]: [ + { + symbol: 'USDT', + isNativeToken: false, + assetId: '4294969280', + originAssetId: '1984', + logo: 'https://assets.coingecko.com/coins/images/325/small/Tether-logo.png?1598003707', + isXcmCompatible: true, + originChain: Chain.STATEMINT, + minBridgeAmount: '0.21', + }, + ], + [endpointKey.SHIDEN]: [ + { + symbol: 'KAR', + isNativeToken: true, + assetId: '18446744073709551618', + originAssetId: 'KAR', + logo: 'https://assets.coingecko.com/coins/images/17172/small/karura.jpeg?1626782066', + isXcmCompatible: true, + originChain: Chain.KARURA, + minBridgeAmount: '0.11', + }, + ], +} +``` + +## Define Methods for XCM Transfers and Fetching Asset Balances + +1. Create a class (Repository) that inherits from the [XcmRepository](https://github.com/AstarNetwork/astar-apps/blob/main/src/v2/repositories/implementations/XcmRepository.ts) class and define the logic under `getTransferCall` and `getTokenBalance` methods [(e.g.)](https://github.com/AstarNetwork/astar-apps/blob/main/src/v2/repositories/implementations/xcm/AcalaXcmRepository.ts). +2. Export the Repository class in [/src/v2/repositories/implementations/index.ts](https://github.com/AstarNetwork/astar-apps/blob/main/src/v2/repositories/implementations/index.ts) +3. Add the Repository at [XcmRepositoryConfiguration](https://github.com/AstarNetwork/astar-apps/blob/main/src/v2/config/xcm/XcmRepositoryConfiguration.ts#L11) object variable. + +## Requirements for creating a PR + +1. You've tested deposit and withdrawal functions on Astar Portal. +2. Deposit and withdrawal functions have additionally been tested with the `minBridgeAmount`. +3. You've tested withdrawal of assets to accounts that have 0 balance of the assets being withdrawn (to check whether `minBridgeAmount` is higher than `Existential Deposit` defined on the origin chain). +4. You've included Subscan link(s) to the XCM transaction details, for each of the assets you've registered. +5. And finally, have deployed the forked app, and submitted the staging URL [ref](/docs/build/builder-guides/layer-1/evm/integration_toolings/deploy-astar-portal.md). diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/asset-registration.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/asset-registration.md new file mode 100644 index 0000000..e43c3a7 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/asset-registration.md @@ -0,0 +1,42 @@ +--- +sidebar_position: 2 +--- + +# XCM Asset Registration + +## Overview + +This step mostly concerns the technical side of asset registration, but once we have opened channels, we should agree on which assets to bridge. The most common and expected assets are native assets. E.g. **ACA** from Acala or **GLMR** from Moonbeam. + +The first step here is to create a local asset on our network which will represent the token. We will use permissioned `asset_id` (root-only). Asset metadata should reflect what’s used on the reserve parachain, e.g. asset name, symbol name, and number of decimals. + +We use unit minimal balance (existential deposit) for supported foregin assets. + +Regarding asset location, let’s take **ACA** token as a reference `{ "parents": 1, "interior": { "X2": [{ "Parachain": 2000 }, { "GeneralKey": [0, 128] } ]}}`. + +We will need to register the mapping between our local created asset Id and that MultiLocation. + +Local asset Id will be chosen from a pre-determined range, starting at **2^64** and increasing from there. + +`2 ** 64 + offset` + +For **offset** 0, this will produce the permissoned asset id: **18446744073709551616**. + +## Request to Add XCM Asset + +To add an XCM asset on Astar or Shiden you will need to create a proposal on our [forum](https://forum.astar.network/). Create your proposal in the correct category: + +- Shiden Network: [https://forum.astar.network/c/shiden/proposal/10](https://forum.astar.network/c/shiden/proposal/10) +- Astar Network: [https://forum.astar.network/c/astar/proposal/20](https://forum.astar.network/c/astar/proposal/20) + +We have created a template that you can use to post your proposal. You can find the template [here](https://astarnetwork.notion.site/XCM-Asset-Registration-Template-ece966dca72d43a38645b54f2fb9f674). + +## Workflow + +### Create Proposal + +After creating your proposal, we will inform our community, and it is expected that you follow up in case there are any questions. To continue with the next step you will need to be approved by our council (governance), which will be done via poll on our forum. + +### Mapping Asset + +After your proposal receives approval from our council, we will map your asset into our network. diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/hrmp.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/hrmp.md new file mode 100644 index 0000000..ff43823 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/hrmp.md @@ -0,0 +1,109 @@ +--- +sidebar_position: 1 +--- + +# Open HRMP Channels + +## Overview + +Before two parachains can communicate directly with one another, they must open channels with one another. Since each channel is uni-directional, two of them must be opened; one in each direction. + +## Technical Instructions + +### Understanding the Parameters + +Opening a channel requires that the parachain sovereign account on the Relay Chain have a balance in the native token (KSM or DOT). This is mandatory, otherwise, the channel opening will fail, as the transactions won't be executed. + +The easiest way to check the required parameters is by opening the Relay Chain in [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer), under Developer -> Chain State -> `configuration` -> `activeConfig`. What you're interested in will look like this (taken from Polkadot): + +```json +hrmpMaxParachainOutboundChannels: 30 +hrmpMaxParathreadOutboundChannels: 0 +hrmpSenderDeposit: 100,000,000,000 +hrmpRecipientDeposit: 100,000,000,000 +hrmpChannelMaxCapacity: 1,000 +hrmpChannelMaxTotalSize: 102,400 +hrmpMaxParachainInboundChannels: 30 +hrmpMaxParathreadInboundChannels: 0 +hrmpChannelMaxMessageSize: 102,400 +``` + +Based on the information above, we can see that **10 DOT** is required to open a channel or to confirm it. We can also see that there are a maximum number of inbound and outbound channels per parachain - 30 in the case of Polkadot, at the time of this writing. + +The two parameters that need to be specified when opening a channel are: + +- `max_capacity` - max number of messages that can be queued in the channel. +- `max_message_size` - max size of the message being sent. + +We can choose the max values when opening the channel accordingly. + +## Relay Chain Encoded Call + +The first step is to prepare the encoded call data for either requesting channel opening, or accepting an existing open channel request. + +1. Visit polkadot.js app in your browser and select either Polkadot or Kusama. +2. Click on `Developer -> Extrinsic`. +3. Find hrmp under all the available pallets and select it. +4. Select the `hrmpInitOpenChannel` call and fill out the parameters. + 1. **recipient**: the parachain with which you want to open the channel. + 2. **proposedMaxCapacity**: pick the value from activeConfig. + 3. **proposedMaxMessageSize**: pick the value from activeConfig. +5. Copy and store the encoded call data for later: + 1. e.g. `0x3c00d6070000e803000000900100` + +You can repeat the exact same steps to get the encoded call data for hrmpAcceptOpenChannel. + +## XCM To Relay Chain + +The assumption here is that you're using Polkadot's standard `pallet-xcm`, which has a send call. + +Using a **root** call from your parachain, you should send an XCM message to the Relay Chain, instructing it to execute the encoded call data you've prepared in the previous step. + +1. Open your parachain in [polkadot.js app](https://polkadot.js.org/apps) +2. Click on `Developer -> Extrinsic` +3. Find the XCM pallet in the dropdown menu (probably called `polkadotXcm` or `xcmPallet`) +4. Select `send` as the call: + 1. **destination**: `V1 {XcmV1MultiLocation { parents: 1, interior: Here}}` + 2. **message**: + 1. `V2` (or latest supported version) + 2. Now add 5 instructions to the message. + 3. **WithdrawAsset**: `{Concrete {0, Here}, Fungible {1000000000000}}`: + 1. 1 DOT or 1 KSM is sufficient to execute this. + 2. You must ensure that your sovereign account on the Relay Chain is sufficiently funded. + 3. Refer to [XCM Tools](https://app.gitbook.com/o/-LgGrgOEDyFYjYWIb1DT/s/-M8GVK5H7hOsGnYqg-7q-872737601/~/changes/AhpKoCvdYLwztMP8vCAb/xcm/xcm-integration/xcm-tools) page for help with calculating the sovereign account. + 4. **BuyExecution**: `{Concrete {0, Here}, Fungible {1000000000000}, Unlimited}` + 5. **Transact**: `{Native, 1000000000, }`: + 1. Use the encoded call data you've prepared before. + 6. **RefundSurplus** + 7. **DepositAsset**: `{Wild {All}, 1, {parents: 0, interior: X1(Parachain(2007))}}` +5. Send and then verify the execution on the Relay Chain + +You will need to send two such calls for both accepting request, and initiating it (or you can prepare a batch call). Once a channel has been accepted, it will become available at the start of next session. + +## Submit Request to Open HRMP Channel + +To open an HRMP channel with Astar or Shiden you will need to create a proposal on our [forum](https://forum.astar.network/). Create your proposal in the correct category: + +- Shiden Network: [https://forum.astar.network/c/shiden/proposal/10](https://forum.astar.network/c/shiden/proposal/10) +- Astar Network: [https://forum.astar.network/c/astar/proposal/20](https://forum.astar.network/c/astar/proposal/20) + +We have created a template that you can use to post your proposal, which you can find [here](https://astarnetwork.notion.site/Open-HRMP-Channel-Template-166eb1b8202d4439a8c00e4a50fe0d89). + +## Workflow + +### Create Proposal + +After creating your proposal, we will inform our community, and it is expected that you should follow up in case the community has questions. To continue with the next step you will need to be approved by our council (governance), which will be done through a poll on our forum. + +### Onboarding on Testnet + +The first step is for the parachain to onboard their testnet to the Rococo Relay Chain. Once that is done, you should inform us about your endpoint and parachain Id. + +- Exchange public endpoints. +- Exchange parachain-Ids. + +We will open channels, register assets and initiate test transfers. + +### Opening an HRMP Channel + +After testing on Rococo, we will begin the process of opening the HRMP channel, and if necessary, will also initiate the process adding the XCM asset. Read more about adding XCM assets [here](https://app.gitbook.com/o/-LgGrgOEDyFYjYWIb1DT/s/-M8GVK5H7hOsGnYqg-7q-872737601/xcm/xcm-integration/xcm-asset-registration). diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/multilocation.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/multilocation.md new file mode 100644 index 0000000..b546e15 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/multilocation.md @@ -0,0 +1,39 @@ +--- +sidebar_position: 3 +--- + +# Asset MultiLocation + +You can use these `MultiLocation` values to add Astar native assets to a parachains' foreign token list, along with other assets minted on our chain. + +## Rococo Astar + +`{ parents: 1, interior: X1(Parachain(2006)) }` + +- Decimals: **18** +- Existential deposit: **1_000_000** + +## Astar + +`{ parents: 1, interior: X1(Parachain(2006)) }` + +- Name: **Astar** +- Symbol: **ASTR** +- Decimals: **18** +- Existential deposit: **1_000_000** + +## Shiden + +`{ parents: 1, interior: X1(Parachain(2007)) }` + +- Name: **Shiden** +- Symbol: **SDN** +- Decimals: **18** +- Existential deposit: **1_000_000** + +## Custom asset + +`{ parents: 1, interior: X3(Parachain(2006/7), PalletInstance(36), GeneralIndex(*asset_id*) }` + +- Please note that these assets can be created by any user. +- Asset metadata (if available) can be found on-chain, by consulting the asset owner, or in our [official asset list](/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/asset-list.md). diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/tools.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/tools.md new file mode 100644 index 0000000..4157dd5 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/integration/tools.md @@ -0,0 +1,68 @@ +--- +sidebar_position: 4 +--- + +# XCM Tools + +We've prepared an xcm-tools crate which provides an easy way for users to find a sovereign account or calculate an XC20 asset Id. This section is intended for developers or integrators who possess basic technical knowledge. + +## Installation + +1. Make sure your machine is capable of compiling Substrate code. For more info, check [here](https://docs.substrate.io/install/). +2. Clone [Astar repo](https://github.com/AstarNetwork/Astar) +3. Position yourself in repository root and run `cargo build --release -p xcm-tools` +4. After compilation finishes, check the `./target/release` folder for the `xcm-tools` binary +5. Store it for later use so you don't have to recompile it from scratch. + +## Sovereign Account + +For finding a parachain's sovereign account address on the Relay Chain, use the following command: + +```bash +./xcm-tools sovereign-account 2006 +5Ec4AhPW97z4ZyYkd3mYkJrSeZWcwVv4wiANES2QrJi1x17F +``` + +Replace **2006** with the parachain Id you require. + +For calculating a sibling parachain's sovereign account address, use the following command: +```bash +./xcm-tools sovereign-account -s 2006 +5Eg2fntKDrAxhaGuB3idrxCFu3BveuyB1MooVPYuj2jaoSsw +``` + +E.g. this will be the sovereign account address of Astar on Statemint. +Replace 2006 with the parachain Id you require. + +## XC20 Address + +For calculating an XC20 EVM address, use the following command: +```bash +./xcm-tools asset-id 42424242424242 +pallet_assets: 42424242424242 +EVM XC20: 0xffffffff000000000000000000002695a9e649b2 +``` + +You can also input a standard asset Id (as seen by pallet-assets), and it will output the H160 address of that asset. + +## Remote Account + +For calculating the remote account, see ([here](https://github.com/paritytech/polkadot/blob/master/xcm/xcm-builder/src/location_conversion.rs#L25)), we have provide a dedicated command. However, the possible `MultiLocation`s format is limited to: + +1. `{ parents: 1, interior: X1(AccountId32{ network: _, id: 0x}) }` +2. `{ parents: 1, interior: X2(Parachain(), AccountId32{ network: _, id: 0x}) }` +2. `{ parents: 1, interior: X2(Parachain(), AccountKey20{ network: _, key: 0x}) }` + +For the first case, use the following command: +```bash +./xcm-tools remote-account -a 0x84746218b9858233f45f99d742aa3ea2f31aeb5a525938f240fdee3000000000 +5H2dw5K45MfT4dwB7u924MYFASzGoWvACzKuMo3TdgJRkg2R +``` +The value under `-a` is a SS58 public key. + +For the second case, use the following command: +```bash +./xcm-tools remote-account -p 1000 -a 0x84746218b9858233f45f99d742aa3ea2f31aeb5a525938f240fdee3000000000 +5FkWm28hUM7XC9qvrS3w4RP38wCgajfvFpqyfjeTSVxShdzC +``` +The value under `-p` is parachain Id, while `-a` is again the public key. diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/_category_.json b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/_category_.json new file mode 100644 index 0000000..53d6cac --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Using XCM", + "position": 1 +} \ No newline at end of file diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/1.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/1.png new file mode 100644 index 0000000..73274d5 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/1.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/2.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/2.png new file mode 100644 index 0000000..3442c3d Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/2.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/3.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/3.png new file mode 100644 index 0000000..7cb7dbf Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/3.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/4.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/4.png new file mode 100644 index 0000000..f22d91f Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/4.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/5.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/5.png new file mode 100644 index 0000000..fbced39 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/5.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/6.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/6.png new file mode 100644 index 0000000..9ddd6b7 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/6.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/7.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/7.png new file mode 100644 index 0000000..3a28b06 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/7.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/8.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/8.png new file mode 100644 index 0000000..cb38cb5 Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/img/8.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/index.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/index.md new file mode 100644 index 0000000..7864bf9 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/using-xcm/index.md @@ -0,0 +1,18 @@ +# XCM + +Astar Network stands as a flexible and highly interoperable decentralized application hub supporting not only WebAssembly and EVM smart contracts, but cross-VM communications (XVM), as well. +Astar commonly utilize XCM to leverage assets from other parachains. Furthermore, XCM finds utility within smart contracts to build purely cross-chain dApps, for deployment on either EVM or Wasm stack, or both. + + + +The most frequently encountered scenario involves users transferring their **DOT** from Polkadot over to **Astar**, and vice-versa. The Astar ecosystem version of **DOT** can then be used for smart contracts, and dApps can integrate it. Another commonly observed application is within DeFi dApps, where XCM enables **DOT** trading without requiring a bridge, and offer asset swaps across multiple chains that would have previously required many steps, requiring only one transaction. + +In this section, we will describe the technical details of XCM so that developers can leverage it in their dApps. Do note that Astar/Polkadot and Shiden/Kusama examples are interchangeable as the features are supported on both networks. + +
+ +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + + diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xvm/img/xvm-architecture.png b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xvm/img/xvm-architecture.png new file mode 100644 index 0000000..bf4c47e Binary files /dev/null and b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xvm/img/xvm-architecture.png differ diff --git a/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xvm/index.md b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xvm/index.md new file mode 100644 index 0000000..a5fd2d5 --- /dev/null +++ b/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xvm/index.md @@ -0,0 +1,95 @@ +# XVM + +Note that at this time XVM features are only launched in Shibuya testnet. Stay tuned for Shiden and Astar! + +## Intro: Multiple VMs as one; one VM for all + +As a smart contract platform, Astar Network currently supports both EVM and Wasm (WebAssembly) contracts. Based on specific needs, developers are free to build on either VM. This brings both flexibility for builders and larger groups of users to Astar Network. But the Astar team doesn’t just stop there. Even better, our multi-VM solution, XVM, is introduced to bring true interoperability between different VMs. + +XVM allows smart contracts in different VMs to work together seamlessly. A smart contract in EVM can call a Wasm contract just like it’s another EVM contract and verse visa. From either EVM or Wasm perspective, contracts in different VMs can work together like they are in one: the XVM. + +## Architecture + +![XVM.png](./img/xvm-architecture.png) + +### Components + +The XVM architecture contains five main components: + +- `pallet-xvm`: the hub module to call EVM or Wasm. +- XVM precompile: a custom precompile that allows EVM contracts to call `pallet-xvm` . +- Chain extension: the interface that allows ink! contracts to call `pallet-xvm` +- EVM: Astar EVM implementation, which is Ethereum compatible. +- `pallet-contracts`: the VM for ink! smart contracts. + +`pallet-xvm` module is the core part of XVM. It provides functions to allow other components to call EVM or Wasm, while *XVM precompile* and *chain extension* play the role of gateways for contracts to call the `pallet-xvm` module. + +### Cross-VM calls + +A typical XVM cross-VM call could be either: + +1. Call from EVM into Wasm, or +2. Call from Wasm into EVM + +For calls from EVM into Wasm, the call will be initiated by smart contracts in EVM. The call path is: EVM contract -> precompile -> `pallet-xvm` -> Wasm. + +For calls from Wasm into EVM, the call will be initiated by smart contracts in Wasm. The call path is: Wasm contract -> chain extension -> `pallet-xvm` -> EVM. + +Note that only calling from one VM to another is allowed. Calling the contracts within the same VM will be reverted with an error. + +### Interfaces + +For Solidity EVM contracts, the XVM interface is defined as follows: + +```solidity +interface XVM { + function xvm_call( + uint8 vm_id, + bytes calldata to, + bytes calldata input, + uint256 value, + uint256 storage_deposit_limit + ) external payable returns (bool success, bytes memory data); +} +``` + +For ink! Wasm contracts, XVM can be called with *chain extension*: + +```rust +pub type CallResult = u32; + +#[ink::chain_extension] +pub trait XvmCall { + type ErrorCode = u32; + + #[ink(extension = 0x00010001, handle_status = false)] + fn call(vm_id: u8, target: Vec, input: Vec, value: u128) -> CallResult; +} +``` + +EVM and Wasm contracts have a similar interface for XVM calls. The common arguments they share: + +- `vm_id`: ID of the target VM to call. Use `0x0F` to call EVM and `0x1F` to call Wasm. +- `to`: the address of the target contract. For EVM contracts, it’s a `H160` bytes. For Wasm it’s `AccountId32` bytes. +- `input`: the encoded call arguments. +- `value`: the amount of native token to transfer, used for payable calls. + +Note that in the context of caller VM, the caller address is always the address of the caller contract, instead of the user address. For instance, Alice calls an EVM smart contract `ContractA` that calls into an ink! contract, within the ink! contract’s call, the `self.env.caller` is `ContractA` address instead of Alice. + +#### `input` encoding + +As mentioned above, `input` of encoded arguments is needed for XVM calls. The encoding specification depends on which VM to call. + +For calls to EVM (`0x0F` as VM Id), refer to [here](https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector-and-argument-encoding) for Solidity ABI specifications and [here](https://docs.soliditylang.org/en/latest/abi-spec.html#examples) for examples. + +For calls to Wasm (`0x1F` as VM Id), the `input` is encoded as: `selector_bytes ++ scale_encoded_args`. + +#### Gaps between EVM and Wasm contracts + +In the case of calling from EVM to Wasm, to call XVM in EVM, an extra parameter `storage_deposit_limit` is needed. It is required by `pallet-contracts`, to specify the maximum storage deposit to pay storage rent. As mentioned above, as the caller’s address is always a contract address instead of a user, it’s the caller contract’s address that pays for the storage rent. For Solidity contracts that call Wasm contracts via XVM, developers need to make sure the contract has enough balance for the payment, or the call fails. To pass a sufficient `storage_deposit_limit` value, developers need to know how much is required from the caller contract. For instance, they can benchmark the target call and get the limit in worst-case scenario `N`, and pass `2 x N` for margin of safety. + +Another worth mentioning gap for payable calls from EVM to Wasm is the concept of *ED(existential deposit)* in `pallet-contracts`. Using the `pallet-balances` in Substrate for payable calls, `pallet-contracts` assumes all addresses, including EVM contracts address, need to meet the minimum balance requirement to keep alive (which is not true as there are no ED requirements in EVM). As mentioned above, the caller address is always the calling contract, for payable calls from EVM to Wasm, developers need to make sure their EVM contract address meets the ED requirement, otherwise, the payable call will fail in Wasm and be reverted. + +### Error handling + +The errors incurred in XVM calls bubble up from the caller VM to the caller VM. If an error is returned in either EVM or Wasm, the whole XVM call will be reverted. \ No newline at end of file diff --git a/docs/build/build-on-layer-1/builder-guides/_category_.json b/docs/build/builder-guides/layer-1/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/_category_.json rename to docs/build/builder-guides/layer-1/_category_.json diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/_category_.json b/docs/build/builder-guides/layer-1/evm/astar_features/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/_category_.json rename to docs/build/builder-guides/layer-1/evm/astar_features/_category_.json diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/astarBase.md b/docs/build/builder-guides/layer-1/evm/astar_features/astarBase.md similarity index 99% rename from docs/build/build-on-layer-1/builder-guides/astar_features/astarBase.md rename to docs/build/builder-guides/layer-1/evm/astar_features/astarBase.md index 907aa0e..39d153d 100644 --- a/docs/build/build-on-layer-1/builder-guides/astar_features/astarBase.md +++ b/docs/build/builder-guides/layer-1/evm/astar_features/astarBase.md @@ -399,6 +399,6 @@ That’s a wrap! Happy hacking! ## Reference -- Official Guide for AstarBase](/docs/build/build-on-layer-1/builder-guides/astar_features/astarBase.md/) +- Official Guide for AstarBase](/docs/build/builder-guides/layer-1/evm/astar_features/astarBase.md/) - Official Document for creating a React app: - [https://reactjs.org/docs/create-a-new-react-app.html](https://reactjs.org/docs/create-a-new-react-app.html) diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 1.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 1.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 1.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 1.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 2.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 2.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 2.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 2.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 3.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 3.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 3.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 3.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 4.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 4.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 4.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 4.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 5.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 5.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 5.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 5.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 6.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 6.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 6.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 6.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 7.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 7.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 7.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 7.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 8.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 8.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled 8.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled 8.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-Remix-cookbook/Untitled.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-Remix-cookbook/Untitled.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-Truffle-cookbook/1.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-Truffle-cookbook/1.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-Truffle-cookbook/1.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-Truffle-cookbook/1.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-Truffle-cookbook/2.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-Truffle-cookbook/2.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-Truffle-cookbook/2.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-Truffle-cookbook/2.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-Truffle-cookbook/3.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-Truffle-cookbook/3.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-Truffle-cookbook/3.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-Truffle-cookbook/3.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-Truffle-cookbook/4.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-Truffle-cookbook/4.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-Truffle-cookbook/4.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-Truffle-cookbook/4.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-localchain-cookbook/Untitled 1.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-localchain-cookbook/Untitled 1.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-localchain-cookbook/Untitled 1.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-localchain-cookbook/Untitled 1.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-localchain-cookbook/Untitled 2.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-localchain-cookbook/Untitled 2.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-localchain-cookbook/Untitled 2.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-localchain-cookbook/Untitled 2.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-localchain-cookbook/Untitled 3.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-localchain-cookbook/Untitled 3.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-localchain-cookbook/Untitled 3.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-localchain-cookbook/Untitled 3.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-localchain-cookbook/Untitled.png b/docs/build/builder-guides/layer-1/evm/astar_features/img-localchain-cookbook/Untitled.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-localchain-cookbook/Untitled.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img-localchain-cookbook/Untitled.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img-localchain-cookbook/img b/docs/build/builder-guides/layer-1/evm/astar_features/img-localchain-cookbook/img similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img-localchain-cookbook/img rename to docs/build/builder-guides/layer-1/evm/astar_features/img-localchain-cookbook/img diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img/1.png b/docs/build/builder-guides/layer-1/evm/astar_features/img/1.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img/1.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img/1.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img/2.png b/docs/build/builder-guides/layer-1/evm/astar_features/img/2.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img/2.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img/2.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img/3.png b/docs/build/builder-guides/layer-1/evm/astar_features/img/3.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img/3.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img/3.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img/4.png b/docs/build/builder-guides/layer-1/evm/astar_features/img/4.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img/4.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img/4.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img/5.png b/docs/build/builder-guides/layer-1/evm/astar_features/img/5.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img/5.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img/5.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/img/6.png b/docs/build/builder-guides/layer-1/evm/astar_features/img/6.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/img/6.png rename to docs/build/builder-guides/layer-1/evm/astar_features/img/6.png diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/run_local_network.md b/docs/build/builder-guides/layer-1/evm/astar_features/run_local_network.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/run_local_network.md rename to docs/build/builder-guides/layer-1/evm/astar_features/run_local_network.md diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/truffle.md b/docs/build/builder-guides/layer-1/evm/astar_features/truffle.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/truffle.md rename to docs/build/builder-guides/layer-1/evm/astar_features/truffle.md diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/use_hardhat.md b/docs/build/builder-guides/layer-1/evm/astar_features/use_hardhat.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/use_hardhat.md rename to docs/build/builder-guides/layer-1/evm/astar_features/use_hardhat.md diff --git a/docs/build/build-on-layer-1/builder-guides/astar_features/use_remix.md b/docs/build/builder-guides/layer-1/evm/astar_features/use_remix.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/astar_features/use_remix.md rename to docs/build/builder-guides/layer-1/evm/astar_features/use_remix.md diff --git a/docs/build/build-on-layer-1/builder-guides/hacking/_category_.json b/docs/build/builder-guides/layer-1/evm/hacking/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/hacking/_category_.json rename to docs/build/builder-guides/layer-1/evm/hacking/_category_.json diff --git a/docs/build/build-on-layer-1/builder-guides/hacking/general.md b/docs/build/builder-guides/layer-1/evm/hacking/general.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/hacking/general.md rename to docs/build/builder-guides/layer-1/evm/hacking/general.md diff --git a/docs/build/build-on-layer-1/builder-guides/hacking/hack_evm.md b/docs/build/builder-guides/layer-1/evm/hacking/hack_evm.md similarity index 85% rename from docs/build/build-on-layer-1/builder-guides/hacking/hack_evm.md rename to docs/build/builder-guides/layer-1/evm/hacking/hack_evm.md index 5197ab7..035bba1 100644 --- a/docs/build/build-on-layer-1/builder-guides/hacking/hack_evm.md +++ b/docs/build/builder-guides/layer-1/evm/hacking/hack_evm.md @@ -12,7 +12,7 @@ Read the linked chapters or use tutorials to be able to answer following questio ## Setup MetaMask and Remix * Did you install and connect your MetaMask to Shibuya? Which `Chain Id` did you use to setup Shibuya Network in MetaMask? -* Connect to browser IDE Remix using this [tutorial](/docs/build/build-on-layer-1/builder-guides/astar_features/use_remix.md) +* Connect to browser IDE Remix using this [tutorial](/docs/build/builder-guides/layer-1/evm/astar_features/use_remix.md) * Does your environment look like this:
@@ -29,7 +29,7 @@ Since it's inception, Solidity has become mainstream language for smart contract ## Setup Hardhat and Truffle The Truffle and Hardhat are preferred tools to develop, deploy and test smart contract. For this guide we will pick Hardhat. -Setup your Hardhat environment using [How to use Hardhat to deploy on Shibuya](/docs/build/build-on-layer-1/builder-guides/astar_features/use_hardhat.md). +Setup your Hardhat environment using [How to use Hardhat to deploy on Shibuya](/docs/build/builder-guides/layer-1/evm/astar_features/use_hardhat.md). -What is [next](/docs/build/build-on-layer-1/builder-guides/hacking/next.md)? +What is [next](/docs/build/builder-guides/layer-1/evm/hacking/next.md)? diff --git a/docs/build/build-on-layer-1/builder-guides/hacking/hack_wasm.md b/docs/build/builder-guides/layer-1/evm/hacking/hack_wasm.md similarity index 90% rename from docs/build/build-on-layer-1/builder-guides/hacking/hack_wasm.md rename to docs/build/builder-guides/layer-1/evm/hacking/hack_wasm.md index 1861c8e..6b90ea2 100644 --- a/docs/build/build-on-layer-1/builder-guides/hacking/hack_wasm.md +++ b/docs/build/builder-guides/layer-1/evm/hacking/hack_wasm.md @@ -30,7 +30,7 @@ Please note that the current version of polkadot-JS is broken for contracts beca ::: -## From Zero to ink Hero [Tutorials](/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/flipper-contract/flipper.md) +## From Zero to ink Hero [Tutorials](/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/flipper-contract/flipper.md) Depending on your confidence, use any of these tutorial. If you are just starting, the Flipper contract is the way to go. * Your task is to deploy the contract from the tutorial to Shibuya Network. * After you build contract notice where the `.contract` and `metadata.json` are created. @@ -40,4 +40,4 @@ Depending on your confidence, use any of these tutorial. If you are just startin * Use Polkadot-JS UI to reload same contract you just deployed using Contracts-UI. -What is [next](/docs/build/build-on-layer-1/builder-guides/hacking/next.md)? +What is [next](/docs/build/builder-guides/layer-1/evm/hacking/next.md)? diff --git a/docs/build/build-on-layer-1/builder-guides/hacking/img/custom_net.png b/docs/build/builder-guides/layer-1/evm/hacking/img/custom_net.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/hacking/img/custom_net.png rename to docs/build/builder-guides/layer-1/evm/hacking/img/custom_net.png diff --git a/docs/build/build-on-layer-1/builder-guides/hacking/img/zombie.png b/docs/build/builder-guides/layer-1/evm/hacking/img/zombie.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/hacking/img/zombie.png rename to docs/build/builder-guides/layer-1/evm/hacking/img/zombie.png diff --git a/docs/build/build-on-layer-1/builder-guides/hacking/index.md b/docs/build/builder-guides/layer-1/evm/hacking/index.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/hacking/index.md rename to docs/build/builder-guides/layer-1/evm/hacking/index.md diff --git a/docs/build/build-on-layer-1/builder-guides/hacking/next.md b/docs/build/builder-guides/layer-1/evm/hacking/next.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/hacking/next.md rename to docs/build/builder-guides/layer-1/evm/hacking/next.md diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/_category_.json b/docs/build/builder-guides/layer-1/evm/integration_toolings/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/_category_.json rename to docs/build/builder-guides/layer-1/evm/integration_toolings/_category_.json diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/add-wallets-to-portal.md b/docs/build/builder-guides/layer-1/evm/integration_toolings/add-wallets-to-portal.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/add-wallets-to-portal.md rename to docs/build/builder-guides/layer-1/evm/integration_toolings/add-wallets-to-portal.md diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/cookbook_1.md b/docs/build/builder-guides/layer-1/evm/integration_toolings/cookbook_1.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/cookbook_1.md rename to docs/build/builder-guides/layer-1/evm/integration_toolings/cookbook_1.md diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/deploy-astar-portal.md b/docs/build/builder-guides/layer-1/evm/integration_toolings/deploy-astar-portal.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/deploy-astar-portal.md rename to docs/build/builder-guides/layer-1/evm/integration_toolings/deploy-astar-portal.md diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/img/1.png b/docs/build/builder-guides/layer-1/evm/integration_toolings/img/1.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/img/1.png rename to docs/build/builder-guides/layer-1/evm/integration_toolings/img/1.png diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/img/22.png b/docs/build/builder-guides/layer-1/evm/integration_toolings/img/22.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/img/22.png rename to docs/build/builder-guides/layer-1/evm/integration_toolings/img/22.png diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/img/python0.png b/docs/build/builder-guides/layer-1/evm/integration_toolings/img/python0.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/img/python0.png rename to docs/build/builder-guides/layer-1/evm/integration_toolings/img/python0.png diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/img/sidecar-diagram.jpg b/docs/build/builder-guides/layer-1/evm/integration_toolings/img/sidecar-diagram.jpg similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/img/sidecar-diagram.jpg rename to docs/build/builder-guides/layer-1/evm/integration_toolings/img/sidecar-diagram.jpg diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/img/vercel1.png b/docs/build/builder-guides/layer-1/evm/integration_toolings/img/vercel1.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/img/vercel1.png rename to docs/build/builder-guides/layer-1/evm/integration_toolings/img/vercel1.png diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/img/vercel2.png b/docs/build/builder-guides/layer-1/evm/integration_toolings/img/vercel2.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/img/vercel2.png rename to docs/build/builder-guides/layer-1/evm/integration_toolings/img/vercel2.png diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/img/vercel3.jpg b/docs/build/builder-guides/layer-1/evm/integration_toolings/img/vercel3.jpg similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/img/vercel3.jpg rename to docs/build/builder-guides/layer-1/evm/integration_toolings/img/vercel3.jpg diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/img/vercel4.png b/docs/build/builder-guides/layer-1/evm/integration_toolings/img/vercel4.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/img/vercel4.png rename to docs/build/builder-guides/layer-1/evm/integration_toolings/img/vercel4.png diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/use-python.md b/docs/build/builder-guides/layer-1/evm/integration_toolings/use-python.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/use-python.md rename to docs/build/builder-guides/layer-1/evm/integration_toolings/use-python.md diff --git a/docs/build/build-on-layer-1/builder-guides/integration_toolings/using-sidecar.md b/docs/build/builder-guides/layer-1/evm/integration_toolings/using-sidecar.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/integration_toolings/using-sidecar.md rename to docs/build/builder-guides/layer-1/evm/integration_toolings/using-sidecar.md diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/_category_.json b/docs/build/builder-guides/layer-1/evm/leverage_parachains/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/_category_.json rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/_category_.json diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/img-zombienet-cookbook/Untitled 1.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/img-zombienet-cookbook/Untitled 1.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/img-zombienet-cookbook/Untitled 1.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/img-zombienet-cookbook/Untitled 1.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/img-zombienet-cookbook/Untitled 2.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/img-zombienet-cookbook/Untitled 2.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/img-zombienet-cookbook/Untitled 2.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/img-zombienet-cookbook/Untitled 2.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/img-zombienet-cookbook/Untitled 3.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/img-zombienet-cookbook/Untitled 3.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/img-zombienet-cookbook/Untitled 3.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/img-zombienet-cookbook/Untitled 3.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/img-zombienet-cookbook/Untitled.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/img-zombienet-cookbook/Untitled.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/img-zombienet-cookbook/Untitled.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/img-zombienet-cookbook/Untitled.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/img-zombienet-cookbook/img b/docs/build/builder-guides/layer-1/evm/leverage_parachains/img-zombienet-cookbook/img similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/img-zombienet-cookbook/img rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/img-zombienet-cookbook/img diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/interact_with_xc20.md b/docs/build/builder-guides/layer-1/evm/leverage_parachains/interact_with_xc20.md similarity index 98% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/interact_with_xc20.md rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/interact_with_xc20.md index 6deca0b..8a291a9 100644 --- a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/interact_with_xc20.md +++ b/docs/build/builder-guides/layer-1/evm/leverage_parachains/interact_with_xc20.md @@ -124,7 +124,7 @@ In order to confirm receiving the asset on EVM, we need to add the specific asse - Convert the `asset ID` from hexadecimal to decimal - Add the prefix of `0xffffffff` - for example, our Cookbook Token, CKT, has `asset ID` of `229`. Following the step above, we will have the converted address of `0xffffffff000000000000000000000000000000E5`. -- More information can be found in the following guide: [Send XC20 Assets to EVM](/docs/build/build-on-layer-1/builder-guides/leverage_parachains/interact_with_xc20.md#send-the-asset-to-evm) +- More information can be found in the following guide: [Send XC20 Assets to EVM](/docs/build/builder-guides/layer-1/evm/leverage_parachains/interact_with_xc20.md#send-the-asset-to-evm) ![Untitled](mintable-xc20-cookbook/Untitled%207.png) diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/mint-nfts-crust.md b/docs/build/builder-guides/layer-1/evm/leverage_parachains/mint-nfts-crust.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/mint-nfts-crust.md rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/mint-nfts-crust.md diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 1.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 1.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 1.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 1.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 2.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 2.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 2.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 2.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 3.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 3.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 3.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 3.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 4.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 4.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 4.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 4.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 5.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 5.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 5.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 5.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 6.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 6.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 6.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 6.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 7.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 7.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 7.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 7.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 8.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 8.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 8.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 8.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 9.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 9.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled 9.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled 9.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled.png b/docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/Untitled.png rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/Untitled.png diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/img0 b/docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/img0 similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/mintable-xc20-cookbook/img0 rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/mintable-xc20-cookbook/img0 diff --git a/docs/build/build-on-layer-1/builder-guides/leverage_parachains/zombienet.md b/docs/build/builder-guides/layer-1/evm/leverage_parachains/zombienet.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/leverage_parachains/zombienet.md rename to docs/build/builder-guides/layer-1/evm/leverage_parachains/zombienet.md diff --git a/docs/build/build-on-layer-1/builder-guides/index.md b/docs/build/builder-guides/layer-1/index.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/index.md rename to docs/build/builder-guides/layer-1/index.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Factory/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Factory/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Factory/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Factory/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Factory/create-pair.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Factory/create-pair.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Factory/create-pair.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Factory/create-pair.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Factory/getters.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Factory/getters.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Factory/getters.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Factory/getters.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Factory/modifiers.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Factory/modifiers.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Factory/modifiers.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Factory/modifiers.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/burn.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/burn.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/burn.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/burn.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/mint.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/mint.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/mint.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/mint.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/modifiers.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/modifiers.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/modifiers.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/modifiers.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/psp22.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/psp22.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/psp22.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/psp22.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/storage.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/storage.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/storage.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/storage.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/swap.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/swap.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Pair/swap.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Pair/swap.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Structure/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Structure/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Structure/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Structure/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Structure/file-structure.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Structure/file-structure.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/Structure/file-structure.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/Structure/file-structure.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/dex.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/dex.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/dex/dex.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/dex/dex.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/flipper-contract/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/flipper-contract/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/flipper-contract/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/flipper-contract/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/flipper-contract/flipper-contract.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/flipper-contract/flipper-contract.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/flipper-contract/flipper-contract.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/flipper-contract/flipper-contract.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/flipper-contract/flipper.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/flipper-contract/flipper.md similarity index 98% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/flipper-contract/flipper.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/flipper-contract/flipper.md index caaae73..25fcee8 100644 --- a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/flipper-contract/flipper.md +++ b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/flipper-contract/flipper.md @@ -297,5 +297,5 @@ impl Flipper { ### Compile, Deploy and Interact with Contracts -Follow this guide to deploy your contract [using Polkadot UI](https://docs.astar.network/docs/build/build-on-layer-1/smart-contracts/wasm/tooling/polkadotjs/). Once deployed, you will be able to interact with it. +Follow this guide to deploy your contract [using Polkadot UI](https://docs.astar.network/docs/build/builder-guides/layer-1/wasm/tooling/polkadotjs/). Once deployed, you will be able to interact with it. diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/index.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/index.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/index.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/index.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/manic-minter/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/manic-minter/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/manic-minter/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/manic-minter/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/manic-minter/manic-contract.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/manic-minter/manic-contract.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/manic-minter/manic-contract.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/manic-minter/manic-contract.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/manic-minter/manic-e2e.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/manic-minter/manic-e2e.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/manic-minter/manic-e2e.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/manic-minter/manic-e2e.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/manic-minter/manic-minter.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/manic-minter/manic-minter.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/manic-minter/manic-minter.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/manic-minter/manic-minter.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/manic-minter/manic-setup.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/manic-minter/manic-setup.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/manic-minter/manic-setup.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/manic-minter/manic-setup.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/CustomTrait/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/CustomTrait/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/CustomTrait/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/CustomTrait/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/CustomTrait/customtrait.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/CustomTrait/customtrait.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/CustomTrait/customtrait.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/CustomTrait/customtrait.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/Events/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/Events/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/Events/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/Events/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/Events/events.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/Events/events.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/Events/events.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/Events/events.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/Override/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/Override/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/Override/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/Override/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/Override/override.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/Override/override.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/Override/override.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/Override/override.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/PayableMintImpl/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/PayableMintImpl/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/PayableMintImpl/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/PayableMintImpl/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/PayableMintImpl/payablemintimpl.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/PayableMintImpl/payablemintimpl.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/PayableMintImpl/payablemintimpl.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/PayableMintImpl/payablemintimpl.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/PayableMintTrait/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/PayableMintTrait/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/PayableMintTrait/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/PayableMintTrait/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/PayableMintTrait/payableminttrait.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/PayableMintTrait/payableminttrait.md similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/PayableMintTrait/payableminttrait.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/PayableMintTrait/payableminttrait.md diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/Wizard/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/Wizard/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/Wizard/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/Wizard/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/Wizard/index.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/Wizard/wizard.md similarity index 97% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/Wizard/index.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/Wizard/wizard.md index d625e19..c465c53 100644 --- a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/Wizard/index.md +++ b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/Wizard/wizard.md @@ -5,7 +5,7 @@ To create a smart contract which follows PSP34 standard use Openbrush Wizard: 1. Open [Openbrush.io](https://openbrush.io/) website and go to bottom of the page. 2. Select PSP34. -3. Select the version to match the rest of the tutorial. Check *What will be used* in the [opening chapter](/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/nft.md#what-will-be-used). +3. Select the version to match the rest of the tutorial. Check *What will be used* in the [opening chapter](/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/nft.md#what-will-be-used). 4. Name your contract. In this tutorial we will use `Shiden34`. 5. Add your symbol name. In this tutorial we will use `SH34`. 6. Select extensions: *Metadata*, *Mintable*, *Enumerable*. diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/_category_.json b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/_category_.json rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/_category_.json diff --git a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/nft.md b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/nft.md similarity index 98% rename from docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/nft.md rename to docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/nft.md index a62d9a6..4f77e51 100644 --- a/docs/build/build-on-layer-1/smart-contracts/wasm/from-zero-to-ink-hero/nft/nft.md +++ b/docs/build/builder-guides/layer-1/wasm/from-zero-to-ink-hero/nft/nft.md @@ -34,7 +34,7 @@ To follow this tutorial you will need: - Event handling. ## Summary -[I. OpenBrush wizard](./Wizard/index.md) +[I. OpenBrush wizard](./Wizard/wizard.md) [II. Override mint() method](./Override/override.md) [III Custom Trait for mint()](./CustomTrait/customtrait.md) [IV. PayableMint Trait definition](./PayableMintTrait/payableminttrait.md) diff --git a/docs/build/build-on-layer-1/builder-guides/xvm_wasm/_category_.json b/docs/build/builder-guides/layer-1/wasm/xvm_wasm/_category_.json similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/xvm_wasm/_category_.json rename to docs/build/builder-guides/layer-1/wasm/xvm_wasm/_category_.json diff --git a/docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/01.png b/docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/01.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/01.png rename to docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/01.png diff --git a/docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/02.png b/docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/02.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/02.png rename to docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/02.png diff --git a/docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/03.png b/docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/03.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/03.png rename to docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/03.png diff --git a/docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/04.png b/docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/04.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/04.png rename to docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/04.png diff --git a/docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/05.png b/docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/05.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/05.png rename to docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/05.png diff --git a/docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/06.png b/docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/06.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/06.png rename to docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/06.png diff --git a/docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/07.png b/docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/07.png similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/xvm_wasm/img/07.png rename to docs/build/builder-guides/layer-1/wasm/xvm_wasm/img/07.png diff --git a/docs/build/build-on-layer-1/builder-guides/xvm_wasm/manage_psp22_asset.md b/docs/build/builder-guides/layer-1/wasm/xvm_wasm/manage_psp22_asset.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/xvm_wasm/manage_psp22_asset.md rename to docs/build/builder-guides/layer-1/wasm/xvm_wasm/manage_psp22_asset.md diff --git a/docs/build/build-on-layer-1/builder-guides/xvm_wasm/pseudo_random.md b/docs/build/builder-guides/layer-1/wasm/xvm_wasm/pseudo_random.md similarity index 100% rename from docs/build/build-on-layer-1/builder-guides/xvm_wasm/pseudo_random.md rename to docs/build/builder-guides/layer-1/wasm/xvm_wasm/pseudo_random.md diff --git a/docs/use/accounts.md b/docs/use/accounts.md new file mode 100644 index 0000000..12acf37 --- /dev/null +++ b/docs/use/accounts.md @@ -0,0 +1,32 @@ +--- +sidebar_position: 2 +--- +# Accounts +## Overview + +An account on Astar Network consists of two parts - a private key and a public key. A public key is also known as an address of an account because it is accessible and known to the public - just like an e-mail address, for example. A private key is a key to access and manage your address. With that said, anybody can send tokens to your address, but only you can access them with your private key. Therefore, it is crucial to keep your private keys safe at all times. + +Astar Network supports two virtual machines (Wasm VM and EVM) and therefore utilizes two account formats. + +## Substrate Accounts + +Astar is built with Substrate, a framework to build blockchains, and uses Substrate accounts. Substrate-based chains use the underlying public key to derive one or more public addresses. Instead of using the public key directly, Substrate allows you generate multiple addresses and address formats for an account, meaning you only need to generate your public key, private key pair once and derive different addresses for different Substrate-chains. + +The private key is a cryptographically-secure sequence of randomly-generated numbers. For human readability, the private key generates a random sequence of words called a secret seed phrase or mnemonic. + +The address format used in Substrate-based chains like Astar is ss58. ss58 is a modification of Base-58-check from Bitcoin, with some minor modifications. Notably, the format contains an address type prefix that identifies an address as belonging to a specific network. + +Astar supports spezialized accounts, such as Proxy and Keyless accounts. +You can read more about Proxy accounts [here](/docs/use/how-to-guides/layer-1/manage-wallets/setup-proxy.md). + +## EVM Accounts + +Astar EVM side allows Ethereum-style addresses (H160 format), which is 40+2 hex-characters long, in a Substrate based chain. This address matches a private key, which can be used to sign transactions in the Ethereum side of the chain. Furthermore, the address is mapped into a storage slot inside the Substrate Balance pallet to a Substrate-style address (H256 format). + + +## Learn more +[Create a Substrate account](/docs/use/how-to-guides/layer-1/manage-wallets/create-wallet.md) + +[Create an EVM account](/docs/use/how-to-guides/layer-1/evm-guides/setup-metamask.md) + +[Read about Substrate accounts](https://docs.substrate.io/learn/accounts-addresses-keys/) \ No newline at end of file diff --git a/docs/use/astar.md b/docs/use/astar.md new file mode 100644 index 0000000..73d28d9 --- /dev/null +++ b/docs/use/astar.md @@ -0,0 +1,27 @@ +--- +sidebar_position: 1 +--- + +# About Astar Network + +[Astar Network]: https://astar.network/ + +Astar Network is Japan's most popular smart contract platform, supporting both EVM and WebAssembly (Wasm) environments, and interoperability between them using a Cross-Virtual Machine. Astar Network is friendly to all kinds of developers, and the tools and languages they already know. Backed by the shared security of Polkadot, Astar shines brilliantly on its own within a vibrant and healthy ecosystem, and in the blockchain industry overall driving international corporate adoption, and consumer interest in Web3 technologies. + +## Lack of developer incentives + +Astar's Build2Earn system is designed to grow the network in an innovative way, while simultaneously rewarding participants and builders. It allows developers to earn incentives for building and maintaining their decentralized applications, and users to earn incentives for supporting their favorite projects, all while encouraging growth of the ecosystem overall. + +## Scalability + +Blockchains do not scale by design, mostly due to the security assurances inherent in their decentralized consensus mechanisms. If blockchains were faster, they would be less secure. There is an upper limit to the amount of data that can be stored in individual blocks, and at times of network saturation, users of typical blockchains may notice their transactions sitting unconfirmed or in a pending state for long periods of time, resulting in a poor user experience. + +The solution to the issue, up until now, has been a patchwork of independent blockchains loosely connected by bridges - often subject to attack due to their reliance on custodial elements, with no common security standards or methods of interoperability between all. The idea of 'cross-chain', therefore, has mostly been to copy and paste a smart contract from one blockchain, to another. Projects that create real value are quickly copied and deployed elsewhere for better, or for worse, with almost no real innovation taking place overall. + +Astar Network is changing that, and ushering in the next generation of multichain smart contracts uniquely able to utilize the best features from both EVM and WebAssembly Virtual Machines, and any number of application-specific blockchains across the broader Polkadot ecosystem. All while being future-proof. + +## Interoperability + +This interoperability framework, empowered by the shared security of Polkadot coupled with Astar XVM, allows developers to use and build smart contracts in ways they never have before. By fostering cooperation and integrations across multiple blockchains and applications, complex synergies can be developed, leading to the realization of truly innovative solutions that can't be replicated in any other environment. + +Many different blockchains exist, but few have interoperability as their defining feature. Welcome to Astar Network. diff --git a/docs/use/get-started/accounts.md b/docs/use/get-started/accounts.md index 5eb8aba..2079d43 100644 --- a/docs/use/get-started/accounts.md +++ b/docs/use/get-started/accounts.md @@ -41,8 +41,8 @@ You will interact with our Astar native address when using WASM dApps are ready ## Learn more -[Create a Substrate account] (/docs/use/manage-wallets/create-wallet/) **LINK TO UPDATE** +[Create a Substrate account] (/docs/use/how-to-guides/layer-1/manage-wallets/create-wallet/) **LINK TO UPDATE** -[Create an EVM account] (/docs/use/evm-guides/setup-metamask/) **LINK TO UPDATE** +[Create an EVM account] (/docs/use/how-to-guides/layer-1/evm-guides/setup-metamask/) **LINK TO UPDATE** [Read about Substrate accounts] (https://docs.substrate.io/learn/accounts-addresses-keys/) **LINK TO UPDATE** \ No newline at end of file diff --git a/docs/use/get-started/astar-evm-wallet/wallet/metamask/manage-xc20-with-metamask.md b/docs/use/get-started/astar-evm-wallet/wallet/metamask/manage-xc20-with-metamask.md index 0b874e1..5cae607 100644 --- a/docs/use/get-started/astar-evm-wallet/wallet/metamask/manage-xc20-with-metamask.md +++ b/docs/use/get-started/astar-evm-wallet/wallet/metamask/manage-xc20-with-metamask.md @@ -29,6 +29,6 @@ Click on **Import Tokens** in MetaMask popup.
-When you are finished adding and importing DOT, you will see them in your wallet. You can find the full list of supported XCM assets [(/docs/learn/interoperability/xcm/asset-list)].**[INSERT LINK]** +When you are finished adding and importing DOT, you will see them in your wallet. You can find the full list of supported XCM assets [(/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/asset-list)].**[INSERT LINK]** -To manually import assets that are not listed on the *Assets page*, follow [this guide] (/docs/learn/interoperability/xcm/building-with-xcm/send-xc20-evm.md#import-assets-on-metamask). **[INSERT LINK]** +To manually import assets that are not listed on the *Assets page*, follow [this guide] (/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/building-with-xcm/send-xc20-evm.md#import-assets-on-metamask). **[INSERT LINK]** diff --git a/docs/use/get-started/astar-substrate-wallet/multisig-wallet/polkaSafe/index.md b/docs/use/get-started/astar-substrate-wallet/multisig-wallet/polkaSafe/index.md index 13b277c..3e0b89a 100644 --- a/docs/use/get-started/astar-substrate-wallet/multisig-wallet/polkaSafe/index.md +++ b/docs/use/get-started/astar-substrate-wallet/multisig-wallet/polkaSafe/index.md @@ -17,7 +17,7 @@ At the time of this release, PolkaSafe only supports Astar Network. - Install a [Substrate wallet](/docs/use/get-started/astar-substrate-wallet/index.md) (such as Polkadot.js, SubWallet, or Talisman) on your browser. -- Prepare at least two Astar wallet addresses [See reference] (/docs/use/manage-wallets/using-a-multisig-account-on-astar-portal.md) **LINK TO UPDATE** +- Prepare at least two Astar wallet addresses [See reference] (/docs/use/how-to-guides/layer-1/manage-wallets/using-a-multisig-account-on-astar-portal.md) **LINK TO UPDATE** ## Understanding the Benefits of Multisig Accounts diff --git a/docs/use/how-to-guides/layer-1/astar-portal/transfer-tokens.md b/docs/use/how-to-guides/layer-1/astar-portal/transfer-tokens.md index dad0c3f..f988355 100644 --- a/docs/use/how-to-guides/layer-1/astar-portal/transfer-tokens.md +++ b/docs/use/how-to-guides/layer-1/astar-portal/transfer-tokens.md @@ -230,7 +230,7 @@ If you wish to move cross-chain (XCM) assets to Astar Substrate accounts from As
-a. If you are on Astar EVM, insert the destination address. You will need to use the [origin chain’s address] (https://docs.astar.network/docs/learn/interoperability/xcm/faq#q-where-can-i-find-other-chains-addresses). **[INSERT LINK]** +a. If you are on Astar EVM, insert the destination address. You will need to use the [origin chain’s address] (https://docs.astar.network/docs/build/build-on-layer-1/smart-contracts/building-cross-chain-contracts/xcm/faq#q-where-can-i-find-other-chains-addresses). **[INSERT LINK]**
diff --git a/docs/use/how-to-guides/layer-1/dapp-staking/for-devs/index.md b/docs/use/how-to-guides/layer-1/dapp-staking/for-devs/index.md index cc11bc3..5ccbe4f 100644 --- a/docs/use/how-to-guides/layer-1/dapp-staking/for-devs/index.md +++ b/docs/use/how-to-guides/layer-1/dapp-staking/for-devs/index.md @@ -4,9 +4,9 @@ import Figure from "/src/components/figure" ## Overview -Discover [dApp Staking] (/docs/learn/dapp-staking/), **LINK TO UPDATE** a unique mechanism that allows communities to support their favorite teams by staking ASTR or SDN with them. When staking ASTR or SDN on a dApp, users not only support the development of innovative apps but also receive staking rewards from inflation. +Discover [dApp Staking] (/docs/about/products/dapp-staking/), **LINK TO UPDATE** a unique mechanism that allows communities to support their favorite teams by staking ASTR or SDN with them. When staking ASTR or SDN on a dApp, users not only support the development of innovative apps but also receive staking rewards from inflation. -You can educate yourself more by reading the technical documentation about [dApp Staking] (/docs/learn/dapp-staking/). **LINK TO UPDATE** +You can educate yourself more by reading the technical documentation about [dApp Staking] (/docs/about/products/dapp-staking/). **LINK TO UPDATE** **Are you a product owner and want to list your dApp in our staking mechanism to earn rewards?** @@ -14,27 +14,27 @@ Please take the following parameters into consideration and make sure you meet t :::tip -Before reading the dApp Staking section for dApp owner, make sure you understand the concept of periods, subperiods and eras, as well as the dApp Staking V3 parameters explained [here] (/docs/learn/dapp-staking/#period--subperiods). **LINK TO UPDATE** +Before reading the dApp Staking section for dApp owner, make sure you understand the concept of periods, subperiods and eras, as well as the dApp Staking V3 parameters explained [here] (/docs/about/products/dapp-staking/#period--subperiods). **LINK TO UPDATE** ::: ### Tier System and Rewards -dApp Staking introduces the concept of a tier system for dApps. It's important to fully understand the [tier mechanism] (/docs/learn/dapp-staking/dapp-staking-protocol#tier-system) before proceeding with dApp Staking application and registration as a dApp owner. **LINK TO UPDATE** +dApp Staking introduces the concept of a tier system for dApps. It's important to fully understand the [tier mechanism] (/docs/about/products/dapp-staking/dapp-staking-protocol#tier-system) before proceeding with dApp Staking application and registration as a dApp owner. **LINK TO UPDATE** -Currently, there are **4 tiers** with a limited number of slots per tier. Tier capacity for dApp staking is calculated at the start of each period based on the ASTR price as described [here] (/docs/learn/dapp-staking/dapp-staking-protocol#tier-system). **LINK TO UPDATE** +Currently, there are **4 tiers** with a limited number of slots per tier. Tier capacity for dApp staking is calculated at the start of each period based on the ASTR price as described [here] (/docs/about/products/dapp-staking/dapp-staking-protocol#tier-system). **LINK TO UPDATE** The slots allocated to each tier can be viewed on the [dApp Staking Page](https://portal.astar.network/astar/dapp-staking/discover) of the Astar Portal. At the end of each **Build&Earn** subperiod, dApps are assigned to a tier based on the total value staked on them by users. Each tier has a **threshold** that a dApp must reach in order to access it. -The threshold for tier 4 is fixed, but for the other tiers, the threshold is **dynamic** and calculated at the start of each new period based on the total number of slots for the period. To find out more, [click here] (/docs/learn/dapp-staking/dapp-staking-protocol#tier-threshold-entry). **LINK TO UPDATE** +The threshold for tier 4 is fixed, but for the other tiers, the threshold is **dynamic** and calculated at the start of each new period based on the total number of slots for the period. To find out more, [click here] (/docs/about/products/dapp-staking/dapp-staking-protocol#tier-threshold-entry). **LINK TO UPDATE** **Rewards** for dApps are also **dynamic**, fluctuating from tier to tier. The higher the tier, the greater the number of ASTR tokens allocated from inflation as rewards for that tier. The rewards of a tier are divided between all available slots and distributed to the dApps occupying slots. This means that the rewards for dApps within a tier are the same for each dApp, even if not all slots within a tier are occupied. -*Refer to the [dApp staking parameters] (/docs/learn/dapp-staking/protocol-parameters#network-values) page to find out more about the tier system and reward allocation.* **LINK TO UPDATE** +*Refer to the [dApp staking parameters] (/docs/about/products/dapp-staking/protocol-parameters#network-values) page to find out more about the tier system and reward allocation.* **LINK TO UPDATE** :::tip You have to claim your rewards to receive them. We recommend that you claim your rewards at least once a week or, optimistically, 2 or 3 times a week. @@ -62,7 +62,7 @@ In the event that a dApp is **unregistered** from dApp Staking following a gover ::: -In case you have any questions, please check the [FAQ page] (/docs/learn/dapp-staking/dapp-staking-faq/) **LINK TO UPDATE** in the Learn section or join our [Discord channel](https://discord.com/invite/astarnetwork). +In case you have any questions, please check the [FAQ page] (/docs/about/products/dapp-staking/dapp-staking-faq/) **LINK TO UPDATE** in the Learn section or join our [Discord channel](https://discord.com/invite/astarnetwork). ### Other pages may be of interest: diff --git a/docs/use/how-to-guides/layer-1/dapp-staking/for-devs/manage-dApp-Staking.md b/docs/use/how-to-guides/layer-1/dapp-staking/for-devs/manage-dApp-Staking.md index bff3432..d1da0fe 100644 --- a/docs/use/how-to-guides/layer-1/dapp-staking/for-devs/manage-dApp-Staking.md +++ b/docs/use/how-to-guides/layer-1/dapp-staking/for-devs/manage-dApp-Staking.md @@ -14,7 +14,7 @@ By clicking on your dApp in the **Your Project** panel, you will have access to ### Your Dashboard: -- **Curent Tier:** The current tier to which your dApp has been assigned. See [Tier system] (/docs/use/dapp-staking/for-devs/#tier-system-and-rewards) for more information; **LINK TO UPDATE** +- **Curent Tier:** The current tier to which your dApp has been assigned. See [Tier system] (/docs/about/products/dapp-stakingfor-devs/#tier-system-and-rewards) for more information; **LINK TO UPDATE** - **Number of stakers:** Total of current stakers on your dApp; - **Total Earned:** Total tokens received in the dApp Staking program; diff --git a/docs/use/how-to-guides/layer-1/dapp-staking/for-devs/register-dapp.md b/docs/use/how-to-guides/layer-1/dapp-staking/for-devs/register-dapp.md index f9f1eef..58abc9a 100644 --- a/docs/use/how-to-guides/layer-1/dapp-staking/for-devs/register-dapp.md +++ b/docs/use/how-to-guides/layer-1/dapp-staking/for-devs/register-dapp.md @@ -12,7 +12,7 @@ Once you have been approved by the Astar Council under Astar governance, you can Before you can register your dApp or project, make sure you have : -#### 1. An [Astar Native developer wallet] (/docs/use/manage-wallets/create-wallet) with some tokens to cover gas fee. *No Ledger hardware wallet or EVM wallet.* **LINK TO UPDATE** +#### 1. An [Astar Native developer wallet] (/docs/use/how-to-guides/layer-1/manage-wallets/create-wallet) with some tokens to cover gas fee. *No Ledger hardware wallet or EVM wallet.* **LINK TO UPDATE** You can use one of the following wallets: diff --git a/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/index.md b/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/index.md index bccd5c5..84a1845 100644 --- a/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/index.md +++ b/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/index.md @@ -6,13 +6,13 @@ import Figure from "/src/components/figure" Do you love to stake? Or do you want to support your favorite project on Astar Network or Shiden Network? -Discover [dApp Staking] (/docs/learn/dapp-staking/) **LINK TO UPDATE**, a unique mechanism that allows communities to support their favorite teams by staking ASTR or SDN with them. When staking ASTR or SDN on a dApp, users not only support the development of innovative apps but also receive staking rewards from inflation. +Discover [dApp Staking] (/docs/about/products/dapp-staking/) **LINK TO UPDATE**, a unique mechanism that allows communities to support their favorite teams by staking ASTR or SDN with them. When staking ASTR or SDN on a dApp, users not only support the development of innovative apps but also receive staking rewards from inflation. -You can educate yourself more by reading the technical documentation about [dApp Staking] (/docs/learn/dapp-staking/). **LINK TO UPDATE** +You can educate yourself more by reading the technical documentation about [dApp Staking] (/docs/about/products/dapp-staking/). **LINK TO UPDATE** :::tip -Before reading the dApp Staking section for stakers, make sure you understand the concept of periods, subperiods and eras, as well as the dApp Staking V3 parameters explained [here] (/docs/learn/dapp-staking/#understand-the-terminology-and-parameters-of-dapp-staking). **LINK TO UPDATE** +Before reading the dApp Staking section for stakers, make sure you understand the concept of periods, subperiods and eras, as well as the dApp Staking V3 parameters explained [here] (/docs/about/products/dapp-staking/#understand-the-terminology-and-parameters-of-dapp-staking). **LINK TO UPDATE** ::: @@ -63,10 +63,10 @@ Bonus rewards for a period can only be claimed after the period finishes. - You need to keep a minimum of 10 ASTR or 5 SDN tokens as transferable after staking. - **You need to claim to receive your rewards, we recommend claiming your staking rewards once a week.** -- When unlocking tokens, there is a unlocking period on Astar and on Shiden. The unlocking period lenghts can be consulted [here] (/docs/learn/dapp-staking/#parameters). **LINK TO UPDATE** +- When unlocking tokens, there is a unlocking period on Astar and on Shiden. The unlocking period lenghts can be consulted [here] (/docs/about/products/dapp-staking/#parameters). **LINK TO UPDATE** Please note that this is based on a perfect block production of 12s. In case of any delay, your unlocking period can be a little longer. -In case you have any questions, please check the [FAQ page] (/docs/learn/dapp-staking/dapp-staking-faq/) **LINK TO UPDATE** in the Learn section or join our [Discord channel](https://discord.com/invite/astarnetwork). +In case you have any questions, please check the [FAQ page] (/docs/about/products/dapp-staking/dapp-staking-faq/) **LINK TO UPDATE** in the Learn section or join our [Discord channel](https://discord.com/invite/astarnetwork). ### Other pages may be of interest: diff --git a/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/manage-dApp-Staking.md b/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/manage-dApp-Staking.md index 8cb4201..441e73c 100644 --- a/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/manage-dApp-Staking.md +++ b/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/manage-dApp-Staking.md @@ -45,7 +45,7 @@ The unlocking panel is where you can see the progress of unlocking and withdrawi For the runtime logic, when unlocking, you don’t unlock from a specific dApp but unlock as `Chunks`. First pending unlocking gives Chunk 1, second pending unlocking gives Chunk 2 etc. After you have unstaked and when those ERAs pass, you will be able to withdraw. More information about [Unlocking](/use/how-to-guides/layer-1/dapp-staking/for-stakers/unstaking/). -The unlocking period lenghts can be consulted [here] (/docs/learn/dapp-staking/#parameters). **LINK TO UPDATE** +The unlocking period lenghts can be consulted [here] (/docs/about/products/dapp-staking/#parameters). **LINK TO UPDATE** - **Remaining days:** The number of days or `Eras` you have to wait before you can withdraw your tokens; - **Available to withdraw:** Unlock your tokens and make them `transferable`; diff --git a/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/move-staked-tokens.md b/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/move-staked-tokens.md index 9d41345..7e38190 100644 --- a/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/move-staked-tokens.md +++ b/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/move-staked-tokens.md @@ -21,7 +21,7 @@ Once your tokens have been staked on a dApp, you always have the option of recon Bear in mind that when you move tokens from one dApp to another, you are `unstaking` from one dApp to `stake` on a new dApp, which therefore has an impact on your rewards for those dApps: -- If you move tokens from a dApp and your staked tokens are less than the [minimum staking] (/docs/learn/dapp-staking/#parameters) amount for a dApp, all your tokens will be `unstaked` from that dApp; **LINK TO UPDATE** +- If you move tokens from a dApp and your staked tokens are less than the [minimum staking] (/docs/about/products/dapp-staking/#parameters) amount for a dApp, all your tokens will be `unstaked` from that dApp; **LINK TO UPDATE** - If you move your tokens from one dApp to another, you'll lose the **basic staking rewards** for the current `Era` for the dApp you moved, and you won't earn rewards on the new dApp until the next `Era`; - During the Build&Earn subperiod, if you move your tokens from one dApp to another and your staked tokens on the initial dApp at the end of the **Build&Earn subperiod** are less than your staked tokens at the end of the **Voting subperiod** for the same dApp, you will no longer be eligible for the **Bonus Rewards** for that dApp; diff --git a/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/staking.md b/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/staking.md index 42b86a2..f2a07c2 100644 --- a/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/staking.md +++ b/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/staking.md @@ -42,7 +42,7 @@ Click on the project cards for more information, access to their communities or :::important -Before using dApp Staking, make sure you understand all the parameters and rules described [here] (/docs/learn/dapp-staking/#parameters). **LINK TO UPDATE** +Before using dApp Staking, make sure you understand all the parameters and rules described [here] (/docs/about/products/dapp-staking/#parameters). **LINK TO UPDATE** An address can only stake on a maximum of 16 contracts (dApps). ::: diff --git a/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/unstaking.md b/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/unstaking.md index e780008..7dd3d39 100644 --- a/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/unstaking.md +++ b/docs/use/how-to-guides/layer-1/dapp-staking/for-stakers/unstaking.md @@ -12,7 +12,7 @@ import Figure from "/src/components/figure" **Unlocking** is the action of telling the network that you want to unlock these tokens. After the unlocking period, you can withdraw the tokens, and they become `transferable`. Please note that this is based on a perfect block production of 12s. In case of any delay, your unlocking period can be a little longer. -The unlocking period lenghts can be consulted [here] (/docs/learn/dapp-staking/#parameters). **LINK TO UPDATE** +The unlocking period lenghts can be consulted [here] (/docs/about/products/dapp-staking/#parameters). **LINK TO UPDATE** :::warning diff --git a/docs/use/how-to-guides/layer-1/dapp-staking/index.md b/docs/use/how-to-guides/layer-1/dapp-staking/index.md index 6440155..3ce6884 100644 --- a/docs/use/how-to-guides/layer-1/dapp-staking/index.md +++ b/docs/use/how-to-guides/layer-1/dapp-staking/index.md @@ -12,7 +12,7 @@ For every block produced on the network, a segment of inflation is specifically As a dApp gains popularity and attracts more stakers, the developers stand to receive a greater share of block rewards. Importantly, the dApp staking program is inclusive, accommodating projects utilizing EVM and Wasm technologies, along with zkEVM dApps. -For a more detailed explanation of dApp Staking, refer to the comprehensive presentation in the [Learn section] (/docs/learn/dapp-staking/). **LINK TO UPDATE** +For a more detailed explanation of dApp Staking, refer to the comprehensive presentation in the [Learn section] (/docs/about/products/dapp-staking/). **LINK TO UPDATE** ### User & Developers guides diff --git a/docs/use/how-to-guides/layer-1/evm-guides/_category_.json b/docs/use/how-to-guides/layer-1/evm-guides/_category_.json new file mode 100644 index 0000000..12156f4 --- /dev/null +++ b/docs/use/how-to-guides/layer-1/evm-guides/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "EVM Guides", + "position": 3 +} \ No newline at end of file diff --git a/docs/use/how-to-guides/layer-1/evm-guides/claim-lockdrop.md b/docs/use/how-to-guides/layer-1/evm-guides/claim-lockdrop.md new file mode 100644 index 0000000..09e5393 --- /dev/null +++ b/docs/use/how-to-guides/layer-1/evm-guides/claim-lockdrop.md @@ -0,0 +1,23 @@ +--- +sidebar_position: 14 +--- + +# How to claim ETH from Lockdrop + +This section will guide you on how to claim the ETH that you locked during Lockdrop 1 and 2. +
+ +1. Go to the [Lockdrop page](https://lockdrop.astar.network/). +2. Select either Lockdrop 1 or Lockdrop 2. +3. You will be prompted to connect Metamask. +4. Connect the wallet that you used to lock the ETH and make sure that you are on the Ethereum Network. +5. Click "Unlock Tokens". +6. Click the 🔒. +![image](https://user-images.githubusercontent.com/37278708/214504565-03984cde-a785-44c0-bade-5220ef6fc3e8.png) + +6. You will need to pay the gas fee to complete the transaction. +7. The ETH shall be in your wallet after the transaction is complete. +8. If you have troubles connecting, use VPN. + + +The other method to claim is by simply sending 0 ETH to the lock address. This will trigger the claim. diff --git a/docs/use/how-to-guides/layer-1/evm-guides/setup-metamask.md b/docs/use/how-to-guides/layer-1/evm-guides/setup-metamask.md new file mode 100644 index 0000000..f168863 --- /dev/null +++ b/docs/use/how-to-guides/layer-1/evm-guides/setup-metamask.md @@ -0,0 +1,35 @@ +--- +sidebar_position: 5 +--- + +# How to setup Astar Network to Metamask + +In this tutorial we will navigate you how to add Astar/Shiden Network to your Metamask account. + +
+ +Adding Astar Network to Metamask is very easy. +
+ +1. You will just need to go to [our Portal](https://portal.astar.network/) and try to connect to Metamask. + +Screenshot 2022-09-06 at 14 08 21
+
+ +2. Metamask will pop-up and ask you if you would like to add Astar Network. Please check the info and approve.
+ +Screenshot 2022-09-06 at 14 33 44 + +
+ +:::note +Alternatively, you can also set it up manually by giving information bellow. +
+Network Details
+Network Name: Astar Network Mainnet
+Network URL: https://evm.astar.network
+Chain ID: 592
+Currency Symbol: astr
+Block Explorer URL: https://blockscout.com/astar + +::: diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/_category_.json b/docs/use/how-to-guides/layer-1/manage-wallets/_category_.json new file mode 100644 index 0000000..701a13f --- /dev/null +++ b/docs/use/how-to-guides/layer-1/manage-wallets/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Manage Wallets", + "position": 2 +} diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/astarpass-register.md b/docs/use/how-to-guides/layer-1/manage-wallets/astarpass-register.md new file mode 100644 index 0000000..7b9676f --- /dev/null +++ b/docs/use/how-to-guides/layer-1/manage-wallets/astarpass-register.md @@ -0,0 +1,40 @@ +--- +sidebar_position: 15 +--- + +# Register or Unregister AstarPass/ShidenPass + +This section will guide you on how to register AstarPass/ShidenPass + +1. Before registration, you need to have both Native and EVM wallets. +2. The EVM wallet must have at least 0.01 ASTR and 0.01 SDN respectively for AstarPas and ShidenPass. This is needed for the gas. +3. For AstarPass, go [HERE](https://astarpass.astar.network/#/register). +4. For ShidenPass, go [HERE](https://shidenpass.astar.network/#/register). +5. Connect both Native and EVM wallets as required. +6. You will be prompted to sign the transaction on the EVM wallet. +7. When the transaction is complete, your registration status will be displayed on the screen. +![image](https://user-images.githubusercontent.com/37278708/218656434-f8043acb-fc81-46e9-a664-5f124d675680.png) + +# Unregister AstarPass +This section will guide you on how to unregister AstarPass +1. To unregister AstarPass, there will be a fee of 500 ASTR. You need to have 500 ASTR plus gas in the EVM wallet. +2. Go [HERE](https://blockscout.com/astar/address/0x8E2fa5A4D4e4f0581B69aF2f8F2Ef2CF205aE8F0/write-proxy#address-tabs). +3. On Row 11, enter `500` and click `Write`. + +![image](https://user-images.githubusercontent.com/37278708/218657946-4e53e708-a68b-4571-ba24-4a935bb56086.png) + +4. You will be prompted to sign a transaction on Metamask. Make sure you are signing with the wallet that you want to unregister. +5. If you are not connected with the correct wallet, please switch to another wallet and sign the transaction. +6. Sign the transaction and 500 ASTR will be deducted from your wallet. + +# Unregister ShidenPass +This section will guide you on how to unregister ShidenPass +1. To unregister ShidenPass, there will be a fee of 1 SDN. You need to have 1 SDN plus gas in the EVM wallet. +2. Go [HERE](https://blockscout.com/shiden/address/0x25257be737210F72DA4F51aCB66903A7520e59d6/write-proxy#address-tabs). +3. On Row 12, enter `1` and click `Write`. + +![image](https://user-images.githubusercontent.com/37278708/218659211-1d90fab0-89c2-4915-8ec4-aa5885b7fefd.png) + +4. You will be prompted to sign a transaction on Metamask. Make you are signing with the wallet that you want to unregister. +5. If you are not connected with the correct wallet, please switch to another wallet and sign the transaction. +6. Sign the transaction and 1 SDN will be deducted from your wallet. diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/create-multisig.md b/docs/use/how-to-guides/layer-1/manage-wallets/create-multisig.md new file mode 100644 index 0000000..102fbd6 --- /dev/null +++ b/docs/use/how-to-guides/layer-1/manage-wallets/create-multisig.md @@ -0,0 +1,32 @@ +--- +sidebar_position: 2 +--- + +# Create a Multisig Wallet + +This tutorial serves as a guide to create a multisig substrate wallet. + +## Add contacts + +1. Go to +2. Go to Accounts -> Address Book +3. Click `+ Add Contact` and add all the contact addresses that you want to include in the multisig wallet. +4. For example; Bob, Charlie and Dave. + +![12](img/12.png) + +## Create new wallet + +1. Go to Accounts -> `+ Multisig` +2. From the available signatories, select the ones that you want to include in the multisig. +3. Add a threshold. A threshold of 2 means a minimum of 2 signatories are required to sign the transactions. +4. Give the multisig wallet a name. +5. Click "Create". + +![13](img/13.png) + +## Test the wallet + +1. The multisig wallet is created. +2. To test the multisig wallet, it is recommended to first use Shibuya testnet. You can get SBY faucet from by connecting your own wallet. +3. After getting the SBY faucet, send the SBY tokens to the multisig wallet and then you can start playing around. diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/create-wallet.md b/docs/use/how-to-guides/layer-1/manage-wallets/create-wallet.md new file mode 100644 index 0000000..ae3f9c7 --- /dev/null +++ b/docs/use/how-to-guides/layer-1/manage-wallets/create-wallet.md @@ -0,0 +1,89 @@ +--- +sidebar_position: 1 +--- + +# Create an Astar Wallet + +## Astar Accounts + +### Address Format + +The address format used in Substrate-based chains like Astar is SS58. SS58 is a modification of Base-58-check from Bitcoin with some minor modifications. Notably, the format contains an address type prefix that identifies an address as belonging to a specific network. Astar Network is special in the Polkadot ecosystem because it's the only parachain that supports EVM as WASM smart contract. With the use of two different virtual machines comes two different kinds of addresses. + +- An Astar Native address or SS58 address +- An Astar EVM address or H160 address which starts with 0x + +1 +2 + +You will interact with our Astar native address when using WASM dApps are ready or our dApps Staking page. Using this address requires another extension than MetaMask. We recommend using the Polkadot JS extension if you are new to the ecosystem. + +## Astar Portal + +[Astar Portal]: https://portal.astar.network/ + +The [Astar Portal] is the place to be for doing anything in our ecosystem. The Astar developers created a one-stop-place for everyone who wants to interact in our ecosystem. + +Through our portal, you can connect to different networks in the Astar ecosystem. + +- **Astar Network**: parachain on Polkadot. +- **Shiden Network**: parachain on Kusama. +- **Shibuya**: parachain testnet + +2 + +## Recommend: Polkadot{.js} Browser Plugin + +The Polkadot{.js} plugin provides a reasonable balance of security and usability. It provides a separate local mechanism to generate your address and interact with the Astar portal. We recommend users who are new to our ecosystem and want to create an Astar native address use this wallet. If you don't have the Polkadot JS extension you will receive a popup in our portal when you try to connect your wallet. + +### Install the Browser Plugin + +The browser plugin is available for both [Google Chrome](https://chrome.google.com/webstore/detail/polkadot%7Bjs%7D-extension/mopnmbcafieddcagagdcbnhejhlodfdd?hl=en) (and Chromium-based browsers like Brave) and [Firefox](https://addons.mozilla.org/en-US/firefox/addon/polkadot-js-extension). After installing the plugin, you should see the orange and white Polkadot{.js} logo in your browser menu bar. + +![4](img/4.png) + +### Create Account + +Open the Polkadot{.js} browser extension by clicking the logo on the top bar of your browser. You will see a browser popup. + +![6](img/6.png) + +Click the big plus button - "Create new account". The Polkadot{.js} plugin will then use system randomness to make a new seed for you and display it to you in the form of twelve words. + +![7](img/7.png) + +You should back up these words. Please, store the seed somewhere safe, secret, and secure. If you cannot access your account via Polkadot{.js} for some reason, you can re-enter your seed through the "Add account menu" by selecting "Import account from pre-existing seed". + +![8](img/8.png) + +Best to create an account that is allowed on any chain in the Polkadot ecosystem. This account can then be used for Polkadot and Kusama. Your account will automatically change format when connected to a chain. + +A **descriptive name** is arbitrary and for your use only. It is not stored on the blockchain and will not be visible to other users who look at your address via a block explorer. If you're juggling multiple accounts, it helps to make this as descriptive and detailed as needed. + +The **password** will be used to encrypt this account's information. You will need to re-enter it when using the account for any kind of outgoing transaction or when using it to cryptographically sign a message. + +:::danger +Note that this password does **NOT** protect your seed phrase. If someone knows the twelve words in your mnemonic seed, they still have control over your account even if they do not know the password. +::: + +After clicking on "Add the account with the generated seed", your account is created. We recommend also saving your account as json file somewhere safe. + +## Connect your wallet to Astar Portal + +Return to [Astar Portal] and refresh the page. You will get a popup that Polkadot JS needs to be authorized to be used on our portal. Give the extension permission to do so! + +![9](img/9.png) + +When you have given the extension permission, let's connect the wallet. A popup will show with all possible extensions. We just create a new account with Polkadot JS, so let's select this extension. + +10 + +Once you have clicked on Polkadot JS, you can select your newly created account. Select your account and press confirm. + +11 + +You have now successfully connected an Astar wallet to our portal. Note that you can use this wallet on all parachains in the Dotsama ecosystem. + +## Support + +In case you have any problems. Join our community and our Ambassadors will support you. Please remember that we will never DM you first! If you get approached by someone pretending to be part of the team, do not trust them. diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/1.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/1.png new file mode 100644 index 0000000..a53896d Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/1.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/10.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/10.png new file mode 100644 index 0000000..d895d39 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/10.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/11.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/11.png new file mode 100644 index 0000000..bfb495f Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/11.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/12.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/12.png new file mode 100644 index 0000000..555b1c0 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/12.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/13.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/13.png new file mode 100644 index 0000000..103b965 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/13.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/14.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/14.png new file mode 100644 index 0000000..05920e9 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/14.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/15.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/15.png new file mode 100644 index 0000000..8f95366 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/15.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/16.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/16.png new file mode 100644 index 0000000..4060d39 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/16.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/17.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/17.png new file mode 100644 index 0000000..26368c7 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/17.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/18.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/18.png new file mode 100644 index 0000000..50007e0 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/18.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/19.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/19.png new file mode 100644 index 0000000..63629c3 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/19.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/2.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/2.png new file mode 100644 index 0000000..0b16377 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/2.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/20.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/20.png new file mode 100644 index 0000000..ad4a9c2 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/20.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/21.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/21.png new file mode 100644 index 0000000..aa2ee7e Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/21.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/22.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/22.png new file mode 100644 index 0000000..2a71152 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/22.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/23.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/23.png new file mode 100644 index 0000000..1a8fe63 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/23.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/24.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/24.png new file mode 100644 index 0000000..b8bcb4e Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/24.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/25.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/25.png new file mode 100644 index 0000000..acdd92c Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/25.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/26.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/26.png new file mode 100644 index 0000000..d4d7b15 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/26.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/27.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/27.png new file mode 100644 index 0000000..6a4bfb5 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/27.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/28.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/28.png new file mode 100644 index 0000000..42bf4fb Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/28.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/29.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/29.png new file mode 100644 index 0000000..bb5ae98 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/29.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/3.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/3.png new file mode 100644 index 0000000..262f4b6 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/3.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/30.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/30.png new file mode 100644 index 0000000..c7a2322 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/30.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/31.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/31.png new file mode 100644 index 0000000..853aa34 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/31.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/32.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/32.png new file mode 100644 index 0000000..8e02d94 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/32.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/33.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/33.png new file mode 100644 index 0000000..76de725 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/33.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/34.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/34.png new file mode 100644 index 0000000..668e7b2 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/34.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/35.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/35.png new file mode 100644 index 0000000..a71b4d5 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/35.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/36.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/36.png new file mode 100644 index 0000000..9d92db8 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/36.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/37.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/37.png new file mode 100644 index 0000000..7ee129c Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/37.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/38.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/38.png new file mode 100644 index 0000000..70e8c08 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/38.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/4.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/4.png new file mode 100644 index 0000000..d92b9ba Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/4.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/5.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/5.png new file mode 100644 index 0000000..85c3a1f Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/5.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/6.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/6.png new file mode 100644 index 0000000..792166e Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/6.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/7.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/7.png new file mode 100644 index 0000000..95cfd1d Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/7.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/8.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/8.png new file mode 100644 index 0000000..a750ca1 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/8.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/9.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/9.png new file mode 100644 index 0000000..e82b5a7 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/9.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide00.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide00.png new file mode 100644 index 0000000..796cef1 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide00.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide01.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide01.png new file mode 100644 index 0000000..2f30fd0 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide01.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide02.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide02.png new file mode 100644 index 0000000..e6fcbcb Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide02.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide03.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide03.png new file mode 100644 index 0000000..2880697 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide03.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide04.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide04.png new file mode 100644 index 0000000..4ab97cb Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide04.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide05.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide05.png new file mode 100644 index 0000000..c1eeb09 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide05.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide06.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide06.png new file mode 100644 index 0000000..f57710d Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/inkredible_guide06.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_1.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_1.png new file mode 100644 index 0000000..d44df80 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_1.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_10.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_10.png new file mode 100644 index 0000000..6d87f09 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_10.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_11.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_11.png new file mode 100644 index 0000000..d0524d3 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_11.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_12.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_12.png new file mode 100644 index 0000000..8056a8b Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_12.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_13.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_13.png new file mode 100644 index 0000000..1c7adb9 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_13.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_14.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_14.png new file mode 100644 index 0000000..52e7273 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_14.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_15.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_15.png new file mode 100644 index 0000000..0d4f697 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_15.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_2.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_2.png new file mode 100644 index 0000000..4262d34 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_2.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_3.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_3.png new file mode 100644 index 0000000..daae209 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_3.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_4.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_4.png new file mode 100644 index 0000000..1aa22c3 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_4.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_5.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_5.png new file mode 100644 index 0000000..f58d9e5 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_5.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_6.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_6.png new file mode 100644 index 0000000..56e0449 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_6.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_7.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_7.png new file mode 100644 index 0000000..481ae33 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_7.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_8.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_8.png new file mode 100644 index 0000000..40f0e70 Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_8.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_9.png b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_9.png new file mode 100644 index 0000000..66f826a Binary files /dev/null and b/docs/use/how-to-guides/layer-1/manage-wallets/img/multisig_guide_9.png differ diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/mobile_wallet.md b/docs/use/how-to-guides/layer-1/manage-wallets/mobile_wallet.md new file mode 100644 index 0000000..2103161 --- /dev/null +++ b/docs/use/how-to-guides/layer-1/manage-wallets/mobile_wallet.md @@ -0,0 +1,40 @@ +--- +sidebar_position: 4 +--- + +# Create an Astar Wallet on a Mobile Device + +**This guide will support you to setup an Astar/Shiden wallet for both EVM and Native on your mobile.** +--- + +There are a few mobile wallets that support Astar native environment such as [Nova Wallet](https://novawallet.io/), [Math Wallet](https://mathwallet.org/en-us/) and [SubWallet](https://subwallet.app/), while [Metamask](https://metamask.io/download/) supports Astar EVM. In this tutorial, we will use Math Wallet since it supports both Native and EVM. + +1. Download [Math Wallet](https://mathwallet.org/en-us/) for either Android or iOS. +2. Select Astar for Native and Astar EVM for EVM. + +![image](https://user-images.githubusercontent.com/37278708/199638326-b2dc20cf-1446-40f9-9b7a-152ee5f35da7.png) +![image](https://user-images.githubusercontent.com/37278708/199638421-d27fa62b-72b0-485f-a654-f949bf128f89.png) + +3. Select "Create Wallet" if you want to create a new wallet (You can also import wallet if you want to restore an existing wallet from other devices). +4. Give the wallet a name and password and please remember to store your password in a safe and secure place. +5. Write down the 12-word seed phrase and store it in a safe and secure place. + +![image](https://user-images.githubusercontent.com/37278708/199640362-e22c2328-0d5a-472a-acbf-c5b357c23339.png) + + +7. On the next screen, verify that you have the correct seed phrase and click confirm. + +![image](https://user-images.githubusercontent.com/37278708/199640403-1b8091b6-9e65-4aef-920c-751698682c55.png) + + +8. Your Astar wallet is now ready. +9. Click on the dApp browser and you will be able to use [Astar portal](https://portal.astar.network/) to use dApp staking (only on Astar Native) and make [token transfers](https://docs.astar.network/docs/user-guides/transfer-tokens) between native to EVM and vice versa. + +![image](https://user-images.githubusercontent.com/37278708/199640641-81e1ed72-1357-490f-b9c6-ccab0d6f3cd8.png) +![image](https://user-images.githubusercontent.com/37278708/199640688-eb338b50-8581-4e85-8402-4808aea05739.png) + +11. If you have the EVM wallet, you can use it to navigate the dApps within the EVM environment. + +--- + +That's all and as a **REMINDER**, please make sure you save the seed phrase and password in a safe and secure place. Don't share this with anyone! diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/pallet-proxy.md b/docs/use/how-to-guides/layer-1/manage-wallets/pallet-proxy.md new file mode 100644 index 0000000..ccbb0e2 --- /dev/null +++ b/docs/use/how-to-guides/layer-1/manage-wallets/pallet-proxy.md @@ -0,0 +1,95 @@ +--- +sidebar_position: 17 +--- + +# Create a Proxy Account +--- +This tutorial will be using [Polkadot.js Apps](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frpc.shiden.astar.network#/extrinsics) for manipulating proxies. + +To create a proxy account, follow these steps: + +1. **Go to the Developer tab:** Locate and navigate to the "Developer" tab on the website. + +2. **Select Extrinsics:** Within the Developer tab, find the "Extrinsics" and select it. + +3. **Select the primary account:** Choose the primary account for which you want to create a proxy from the list. We will be using **ALICE** as primary account in this tutorial. + +4. **Submit the following extrinsic:** From the `submit the following extrinsic` dropdown, select **proxy** + +5. Choose the **addProxy** extrinsic + +6. Select the **delegate** account for the proxy + +7. **Choose the proxyType:** From the proxyType dropdown, choose **Balances** + +8. **(Optional) Add a time delay:** If desired, you may have the option to add a time delay to the transaction. This adds an extra layer of security by requiring the primary account to review the pending transaction before it is executed. Specify the desired number of blocks for the time delay. + +9. **Submit the transaction:** Once you have filled in all the necessary details, find the button to submit the transaction. Click on it to initiate the process. + +![33](img/33.png) + +You will then be prompted to authorize and sign the transaction. Go ahead and click **Sign and Submit** to create the proxy relationship. + +![34](img/34.png) + +Once the transaction has been successfully submitted, you will receive notifications confirming the transaction. + +You can also find the event `proxy.ProxyAdded` in recently emitted events inside **Network** > **Explorer** tab. + +![35](img/35.png) + +**Verifying Proxy Account** +--- +There are many ways of verifying if your proxy was added or not. Easiest way to do so is using the **Accounts** page. + +1. Navigate to the Accounts page by clicking on **Accounts** tab and then selecting **Accounts**. + +2. Here find you **Primary Account** and click on the 3 dots as seen in the provided picture. + + +![36](img/36.png) + +3. Select **Manage proxies** option. + + +Here you can see the list of all proxies that you account has. For this tutorial, it is only **Balances** proxy that we added in the above section. + +![37](img/37.png) + +:::tip + +You can also remove the proxy by clicking on the (X) icon next to the proxy account (in our case **BOB**). After clicking (X) button, the proxy will diappear from the list, Click on `Submit`. + +Once the transaction has successfully been submitted, you can review your current proxies or if you removed all proxies you will notice the proxy icon is no longer being displayed next to the primary account. + +::: + +**Executing a Proxy Transaction** +--- + To execute a proxy transaction, go back to the **Extrinsic** page and do the following: + + ## Submitting a Proxy Transaction + +To submit a proxy transaction, follow these steps: + +1. **Select the proxy account:** Choose the proxy account to submit the transaction from using the "Select Account" dropdown. + +2. **Submit the following extrinsic:** From the "Submit the following extrinsic" menu, select "proxy". + +3. **Choose the proxy extrinsic:** Select the "proxy" extrinsic. + +4. **Select the primary account:** From the "real" dropdown, select **Id** and then select the **Primary Account** (ALICE in our case) + +5. Select the **balances** call + +6. Choose the **transfer** extrinsic + +7. **Enter the destination address:** In the "dest" field, enter the address where you want to send the funds. + +8. **Enter the value:** In the "value" field, enter the amount of funds to send. + +9. **Click Submit Transaction:** Once you have entered all the necessary details, click on "Submit Transaction" to initiate the transaction. + +![38](img/38.png) + +Congratulations! You've completed the entire process successfully. You have created a proxy account, reviewed all the proxy accounts linked to your primary account, performed a proxy transaction, and even removed a proxy account. Well done! \ No newline at end of file diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/restore-ecdsa.md b/docs/use/how-to-guides/layer-1/manage-wallets/restore-ecdsa.md new file mode 100644 index 0000000..a6ed2f3 --- /dev/null +++ b/docs/use/how-to-guides/layer-1/manage-wallets/restore-ecdsa.md @@ -0,0 +1,44 @@ +--- +sidebar_position: 6 +--- + +# Restore a ECDSA wallet on Polkadot.js + +During Lockdrop 1 & 2, some of you might have claimed PLM tokens to the default wallet. If you are one of them and have lost access to your Polkadot.js wallet, this tutorial will guide you on how to restore that wallet. + +
+ +This is a 2-step process. +1. Restore the wallet on Polkadot.js. +2. Restore the json file on Polkadot.js extension. + +## Step 1: +1. Go to [Polkadot.js](https://polkadot.js.org/apps/#/settings). +2. Go to "Settings". +3. On the Account Options dropdown menu, select `Allow local in-browser account storage` +4. Click Save". +![image](https://user-images.githubusercontent.com/37278708/214497161-f31e7685-f090-4e4c-806e-6a47bf18e48f.png) + +6. Next, go to Account and click on Add Account. +7. Change “Mnemonic” to “Raw Seed”. +8. Expand "Advanced creation options". +9. On "keypair crypto type", and select `ECDSA`. +10. On the SEED box, type 0x and paste your ETH private key. +11. Tick the box “I have saved my mnemonic phrase safely”. +12. Click “Next”. +![image](https://user-images.githubusercontent.com/37278708/214499043-aacc13c5-8e31-4a91-8384-e943169011a6.png) + +12. Give the account a name and a password, and click “Next”. Make sure to save the password. +13. Click “Save”. +![image](https://user-images.githubusercontent.com/37278708/214498123-dab270e0-9534-410f-8115-e254ac707041.png) + +14. You will be prompted to save the json file. Please save the json file safely as you will need this in the next step. + +## Step 2: +1. Go to https://polkadot.js.org/extension/ to download and install the browser extension wallet. +2. After installation, click on the “+’ icon and select “Restore account from a backup json file” +3. Select the json file that you saved from Step 1 and click “Restore”. +4. Enter the password that you saved from Step 1 and click”Restore”. +5. The wallet is now restored on the Polkadot.js extension. +6. Click on the 3 dots and select “Allow use on any chain”. +7. Your ECDSA wallet is now restored on Polkadot.js and you can use it with Astar Portal. diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/restore-ledger.md b/docs/use/how-to-guides/layer-1/manage-wallets/restore-ledger.md new file mode 100644 index 0000000..b4388b9 --- /dev/null +++ b/docs/use/how-to-guides/layer-1/manage-wallets/restore-ledger.md @@ -0,0 +1,44 @@ +--- +sidebar_position: 7 +--- + +# Restore Ledger wallet on Polkadot.js + +Some of you might have issues making transactions with Ledger wallet on the portal. This is because the Ledger App that you are using is a minimal version. For now, restoring the Ledger seed phrase on Polkadot.js may help the issue. + +
+ +This is a 2-step process. +1. Restore the wallet on Polkadot.js. +2. Restore the json file on Polkadot.js extension. + +## Step 1: +1. Go to [Polkadot.js](https://polkadot.js.org/apps/#/settings). +2. Go to Settings. +4. On the Account Options dropdown menus, select `Allow local in-browser account storage`and `Attach Ledger via WebUSB (Chrome, recommended)`. +5. Click "Save". +![image](https://user-images.githubusercontent.com/37278708/218649665-db576329-7a93-4286-9b46-965e9bed3b2d.png) + +6. Next, go to "Account" and click on “Add Account”. +7. Replace the mnemonic seed with your Ledger seed. +8. Expand "Advanced creation options". +9. On "keypair crypto type", select `Ledger (ed25519, BIP32 derivation)`. +10. On "ledger app type", select `Astar Network`. +11. Tick the box “I have saved my mnemonic phrase safely”. +12. Click “Next”. +![image](https://user-images.githubusercontent.com/37278708/218649577-6eaf7936-bf3b-4610-8d3e-458b39353780.png) + +12. Give the account a name and a password, and click “Next”. Make sure to save the password. +13. Click “Save”. +![image](https://user-images.githubusercontent.com/37278708/214498123-dab270e0-9534-410f-8115-e254ac707041.png) + +14. You will be prompted to save the json file. Please save the json file safely as you will need this in the next step. + +## Step 2: +1. Go to https://polkadot.js.org/extension/ to download and install the browser extension wallet. +2. After installation, click on the “+’ icon and select “Restore account from a backup json file” +3. Select the json file that you saved from Step 1 and click “Restore”. +4. Enter the password that you saved from Step 1 and click”Restore”. +5. The wallet is now restored on the Polkadot.js extension. +6. Click on the 3 dots and select “Allow use on any chain”. +7. Your Ledger wallet is now restored on Polkadot.js and you can use it with Astar Portal. diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/setup-proxy.md b/docs/use/how-to-guides/layer-1/manage-wallets/setup-proxy.md new file mode 100644 index 0000000..c3d61ec --- /dev/null +++ b/docs/use/how-to-guides/layer-1/manage-wallets/setup-proxy.md @@ -0,0 +1,113 @@ +--- +sidebar_position: 8 +--- +# Proxy accounts + +## Overview + +Pallet Proxy enables accounts to grant specific permissions to other accounts, empowering them to make calls on their behalf, thereby safeguarding the security of the underlying accounts. +On this page, you will find a detailed overview of the various proxy types, extrinsics, general definitions, and features associated with the proxy pallet. Additionally, there are tutorials available to help you understand and utilize the proxy functionality effectively. + +**Proxy Types** +--- +1. **Any** - This proxy type allow delegate account to make any call that are supported by proxy pallet. This is highest level of priveledge so should always use that with caution. + +2. **NonTransfer** - This proxy type allow delegate account to make any call supported by proxy pallet expect for the asset transfer funtionalities. This can come handy when you want to keep your funds secure in cold storage and want to delegate all the other functionalities to a proxy account. +To see complete list of functionality, checkout the source code in Astar repo. + +3. **Balances** - This proxy type gives control of handling accounts and balances to the delegate account. Complete list of calls can be found [here](https://docs.rs/pallet-balances/latest/pallet_balances/pallet/enum.Call.html). + +4. **Assets** - This proxy type allows delegate account to control the functionalities related to fungible assets which includes asset issuance, transferal, minting etc. This is to be notes that this proxy types doesn't control the native currency like Astar or Shiden which are controled by Balances proxy. + +5. **IdentityJudgement** - This proxy type allows a single functionality to delegate account which is to provide a judgement to an identity in a naming system. The delegator must be a registrar. + +6. **CancelProxy** - This proxy type allows delegate account to to reject and remove any announced proxy calls. + +7. **DappsStaking** - This proxy type allows delegate account to perform DappStaking related transactions such as register, unregister contracts, claim rewards etc. + + +**Extrinsics** +--- +The proxy pallet provides the following extrinsics (functions): +* **addProxy**(delegate, proxyType, delay) - allows the sender to register a proxy account capable of making calls on behalf of the sender. If the delay value is set to a number greater than 0, the proxy account must announce a transaction and wait for the specified number of blocks before executing it as a proxy. This function also emits a ProxyAdded event. + +* **announce**(real, callHash) - used to record the announcement of a proxy transaction made by proxy accounts that have a delay requirement. This function emits an Announced event. + +* **anonymous**(proxyType, delay, index) - generates a new account with an inaccessible private key, making it inaccessible. The sender assumes the role of a proxy for this account, based on the specified type and delay. Caution: If the proxy is removed, the primary account will become inaccessible. This function emits an AnonymousCreated event. + +* **killAnonymous**(spawner, proxyType, index, height, extIndex) - removes a previously spawned anonymous proxy. + +* **proxy**(real, forceProxyType, call) - performs a transaction as a proxy. This function emits a ProxyExecuted event. + +* **proxyAnnounced**(delegate, real, forceProxyType, call) - executes a transaction as a proxy and removes any previous corresponding announcements. This function emits a ProxyExecuted event. + +* **rejectAnnouncement**(delegate, callHash) - if the sender is a prime account, it removes a specific announcement from their proxy account. + +* **removeAnnouncement**(real, callHash) - if the sender is a proxy account, it removes a specific announcement to their prime account. + +* **removeProxies()** - unregisters all proxy accounts associated with the sender. +* **removeProxy**(delegate, proxyType, delay) - unregisters a specific proxy account linked to the sender. This function emits a ProxyRemoved event. + + +**Constants for Pallet Proxy** +--- + +| Constant | Description | +|--------------------------|--------------------------------------------------------------------------------------------------------------| +| announcementDepositBase | base amount of currency required to reserve when creating an announcement. | +| announcementDepositFactor| amount of currency required per announcement made. | +| maxPending | maximum number of time-delayed announcements allowed to be pending. | +| maxProxies | maximum number of proxies permitted for a single account. | +| proxyDepositBase | base amount of currency required to reserve when creating a proxy. | +| proxyDepositFactor | amount of currency required per proxy added. | + + +**Why Proxy Deposits ?** +--- +To create proxies within the network, it is necessary to provide deposits in the native currency (like ASTR or SDN). The deposit is required because adding a proxy requires some storage space on-chain, which must be replicated across every peer in the network. Due to the costly nature of this, these functions could open up the network to a Denial-of-Service attack. + +When creating a proxy, a bond is deducted from your free balance and transferred to your reserved balance. This mechanism helps maintain the integrity and stability of the proxy system while providing assurance that the bond can be returned when the proxy is deactivated or removed. + +The required deposit amount for `n` proxies is equal to: + +`ProxyDepositBase` + `ProxyDepositFactor` * `n` + + +**Pure / Anonymous Proxy** +--- + +Anonymous proxies (Pure Proxies) are freshly generated accounts, distinct from original one, which originate from a primary account. The primary account assumes the role of a proxy, representing the anonymous proxy. These proxies are non-deterministic and lack a private key, yet possess a randomly generated address. It is worth noting that anonymous proxies remain ownerless, as no individual possesses a private key to exercise control over them. + +Despite their complexity and associated dangers, pure proxies have many important benefits like enhanced security and multi-sig account management. + +:::tip + +It is highly encouraged to checkout [**this**](https://wiki.polkadot.network/docs/learn-proxies#anonymous-proxy-pure-proxy) documentation by Polkadot for more information about Pure proxy, its limitations and benefits. + +Video resource for Pure Proxy - https://youtu.be/MqY6yU-YLO0 + +::: + +**Time-Delayed Proxy** +--- + +To enhance the security of proxies, we can implement a delay mechanism measured in blocks. A delay value of 10 corresponds to ten blocks, resulting in a delay of around two minute (for Astar network). The proxy will utilize the `proxy.announce` extrinsic to declare its intended action and will wait for the specified number of blocks according to the defined delay time before executing it. + +During this delay window, the intended action can be canceled by either the proxy itself using the `proxy.removeAnnouncement` extrinsic or by the accounts controlling the proxy through the `proxy.rejectAnnouncement` extrinsic. The announcement made by the proxy includes the hash of the intended function call, enabling the identification and validation of the action. + +By incorporating this delay mechanism, any malicious activities can be detected and reversed within the designated delay period. After the time-delay has passed, the proxy can proceed with executing the announced call using the `proxy.proxyAnnounced` extrinsic. + +:::caution + +Any attempt to sign the transaction using **proxy** extrinsic with pure proxy will fail. Read more about [**pure**](https://wiki.polkadot.network/docs/learn-proxies#anonymous-proxy-pure-proxy) proxies here. + + +::: + +This implementation adds an additional layer of security to proxies, providing confidence in their usage, knowing that actions can be observed and undone within the specified delay period. + +:::tip + +Check out this [**video**](https://www.youtube.com/watch?v=3L7Vu2SX0PE) by Polkadot to learn how to set up time-delayed proxies. + +::: \ No newline at end of file diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/using-a-multisig-account-on-astar-portal.md b/docs/use/how-to-guides/layer-1/manage-wallets/using-a-multisig-account-on-astar-portal.md new file mode 100644 index 0000000..809109c --- /dev/null +++ b/docs/use/how-to-guides/layer-1/manage-wallets/using-a-multisig-account-on-astar-portal.md @@ -0,0 +1,99 @@ +--- +sidebar_position: 3 +--- + +# Use a Multisig Account on Astar Portal + +This guide will assist you in utilizing a multisig account on Astar Portal via PolkaSafe. + +:::danger +At the time of this release, PolkaSafe only supports Astar Network. +::: + + +## **Prerequisites** + +- Install a Substrate wallet extension (such as Polkadot.js, SubWallet, or Talisman) on your browser. + +- Prepare at least two Astar wallet addresses [See reference](/docs/use/how-to-guides/layer-1/manage-wallets/using-a-multisig-account-on-astar-portal.md) + +## Understanding the Benefits of Multisig Accounts + +Multisig accounts offer several key benefits, particularly in terms of security, control, and flexibility: + +1. **Enhanced Security:** The need for more keys reduces the risk of unauthorized access. +2. **Reduced Risk:** You won't lose access to the account even if you lose a single key. +3. **Access Control:** Multisig allows multiple users to share control over an account. +4. **Flexibility:** You can customize the number of required signatures for transactions. +5. **Dispute Resolution:** Multisig prevents unilateral decisions by requiring majority or total agreement. +6. **Auditability:** Multisig accounts provide a clear record of approved transactions. + +## Creating a Multisig Account on PolkaSafe + +PolkaSafe integrates with Polkadot's multisig solution, offering seamless user experience and robust security features for managing assets in the Polkadot ecosystem. You can use the multisig accounts created on PolkaSafe with the Astar Portal. + +1. Visit [PolkaSafe](https://app.polkasafe.xyz/). +2. Select Astar network and click 'Connect Wallet.' +![multisig_guide_1.png](img/multisig_guide_1.png) +3. Choose a wallet and select an account with more than 0 ASTR. +4. Sign the message via the wallet extension. +5. Select 'Create Multisig.' +![multisig_guide_2.png](img/multisig_guide_2.png) +6. Choose the signatory addresses to include in the multisig account. You can select from your wallet or add an address manually. +:::danger +Ledger accounts cannot be multisig signatories +::: +![multisig_guide_3.png](img/multisig_guide_3.png) +7. Input the threshold number (the minimum required signatures to authorize and execute a transaction) and name the multisig account. +8. Sign the message to add a small Existential Deposit to the multisig account. +![multisig_guide_4.png](img/multisig_guide_4.png) +9. Optionally, you can enable proxy signatory management to allow enhanced functionalities for your multisig account. [See reference](/docs/use/how-to-guides/layer-1/manage-wallets/pallet-proxy.md) +10. Now, you can manage your multisig account on PolkaSafe. +![multisig_guide_5.png](img/multisig_guide_5.png) + +## (Optional) Enabling Proxy Signatory Management for Your Multisig Account on PolkaSafe +Adding a proxy account to your multisig account enhances functionality and flexibility. A proxy allows signatories to alter key parameters and setup account backups. Furthermore, the proxy wallet address remains unchanged even when the multisig account's consensus conditions are modified. A proxy can: + +1. Edit the Threshold: Alter the number of required signatures for transaction authorization. +2. Modify Signatories: Change the signatories of the multisig account. +3. Create Backups: Establish a backup of the multisig account, facilitating seamless asset transfers. In other words, all assets will be in the proxy account. This means that when you add or remove any signatory, the multisig address will change, but the proxy address will not. Therefore, assets in the proxy account won't be lost. + +You can add a proxy to your multisig account either during multisig creation or from the account dashboard. + +![multisig_guide_12.png](img/multisig_guide_12.png) +![multisig_guide_13.png](img/multisig_guide_13.png) + +Switch to the proxy account by clicking the switch icon. +![multisig_guide_14.png](img/multisig_guide_14.png) + +The address should now display as the proxy account. +![multisig_guide_15.png](img/multisig_guide_15.png) + +:::tip +Editing a multisig account (e.g., adding signatories) creates a new multisig address linked to the existing proxy address. This new multisig lacks an Existential Deposit, so you must add some balance to the new multisig address before initiating transactions. +::: + +## Sending Transactions on Astar Portal and Approving them on PolkaSafe + +1. Go to the Astar Portal and select PolkaSafe. +![multisig_guide_6.png](img/multisig_guide_6.png) +2. Choose one of the signatories (owners) to create multisig transactions. +![multisig_guide_7.png](img/multisig_guide_7.png) +1. Sign the message on the wallet extension (the wallet popup might **take a moment** to appear).
+2. Select the multisig account and click Connect.
+![multisig_guide_8.png](img/multisig_guide_8.png) +1. You can now use the Astar Portal in the same way you would with normal accounts. +2. Once the transaction is completed, click 'Approve on PolkaSafe' and approve the transaction on PolkaSafe. You should connect to signatory accounts other than the one selected on Astar Portal.
+![multisig_guide_9.png](img/multisig_guide_9.png) +1. If you want to understand the transaction details, copy the 'Call Data' and paste it on the [Decode page](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frpc.astar.network#/extrinsics/decode) on the Polkadot.js portal. +![multisig_guide_10.png](img/multisig_guide_10.png) +![multisig_guide_11.png](img/multisig_guide_11.png) + +## References: +### PolkaSafe +* [PolkaSafe Documentation](https://docs.polkasafe.xyz/) +* [Introduction to Multisig Accounts](https://wiki.polkadot.network/docs/learn-account-multisig) +* [Creating a pure proxy](https://docs.polkasafe.xyz/setup-polkasafe/creating-a-pure-proxy) +### Polkadot Wiki +* [Multi-Signature Accounts](https://wiki.polkadot.network/docs/learn-account-multisig#introduction-to-multisig-accounts) +* [Proxy Accounts](https://wiki.polkadot.network/docs/learn-proxies) \ No newline at end of file diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/wallet-providers/_category_.json b/docs/use/how-to-guides/layer-1/manage-wallets/wallet-providers/_category_.json new file mode 100644 index 0000000..73422b6 --- /dev/null +++ b/docs/use/how-to-guides/layer-1/manage-wallets/wallet-providers/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Wallet Providers", + "position": 9 +} diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/wallet-providers/enkrypt-wallet.md b/docs/use/how-to-guides/layer-1/manage-wallets/wallet-providers/enkrypt-wallet.md new file mode 100644 index 0000000..f73df2e --- /dev/null +++ b/docs/use/how-to-guides/layer-1/manage-wallets/wallet-providers/enkrypt-wallet.md @@ -0,0 +1,127 @@ +--- +sidebar_position: 1 +title: Enkrypt Wallet +--- + +# Enkrypt Wallet + +![](https://i.imgur.com/imLQ4G4.png) + +## Connecting Enkrypt to Astar + +--- + +Enkrypt is a multichain, non-custodial, and open-source web3 browser wallet built by the team behind MEW (MyEtherWallet). With Enkrypt, users and developers can generate accounts, manage tokens and NFTs, and interact with dApps on Astar, as well as EVM chains. Follow the instructions in this guide in order to connect Enkrypt to Astar! + +![](https://i.imgur.com/c3yv69l.jpg) + +--- +## Install Enkrypt +You’ll first need to install the extension to begin. You can visit [Enkrypt.com](https://www.enkrypt.com/?mtm_campaign=Interacting%20with%20Astar%20using%20Enkrypt) to find the download link that corresponds with your browser. Click download in the top right corner. + +![](https://i.imgur.com/clC5IOa.png) + +You’ll be redirected to the download page shown below. Note that every browser’s download page will look slightly different from each other. + +![](https://i.imgur.com/cqCevR0.png) + +Add the extension to your browser. After downloading and installing Enkrypt you’re ready to go. + +--- +## Create A Wallet +When first opening up the extension, you’ll be met with a window containing a quick description of Enkrypt. You can create a new wallet or restore an existing wallet. Let’s start with creating a new wallet. + +![](https://i.imgur.com/aSdrCXp.png) + +After clicking “Create a new wallet” you’ll be able to pick a password. By clicking the crossed out eye symbol within the textbox, you can toggle the ability to see what you’re typing on or off. Enter your desired password and click “Next”. It’ll ask you to type your password in again for confirmation. Once you’ve done that, it’s time for your secret recovery phrase. + +![](https://i.imgur.com/rdAfVXa.png) + +![](https://i.imgur.com/npuMOQk.png) + +The window below will pop up. Note that your secret recovery is uniquely yours, and you will NOT have the same words shown below. You will have a completely unique and random set of 12 words. Write your secret recovery phrase down, and keep it somewhere safe. Never give your phrase to anyone for any reason. This is the key to your wallet and gives full access to your crypto. When you’re done, click “Next”. + +![](https://i.imgur.com/2U2MY1b.png) + +To be sure you have written down the secret recovery phrase, a pop-up will appear asking you to double check. Select the correct words according to your unique recovery phrase, then click “Next”. + +![](https://i.imgur.com/wTsgdb7.png) + +After you’ve set up your secret recovery phrase, your wallet is ready for you. + +At this point, we'd like to stress that Enkrypt is non-custodial and only you have the keys to your wallet. Not your keys, not your crypto! Enkrypt does NOT hold custody of assets, and does NOT collect or sell personal user data. On a lighter note, remember to pin the Enkrypt extension in your browser! + +--- +## Restore Wallet +If you already have a wallet, like MetaMask or Polkadot.js, you can import it into Enkrypt. In order to do so, follow the steps below. + +Click on “Restore existing wallet”. + +![](https://i.imgur.com/PLhSJyE.png) + +Next, click “Use recovery phrase”. + +![](https://i.imgur.com/vhpvq53.png) + +Enter your 12-24 word recovery phrase and click “Next”. + +![](https://i.imgur.com/bNbxr31.png) + +After entering your recovery phrase, your wallet is ready! Make sure to pin Enkrypt to your extension bar for quick access! + +![](https://i.imgur.com/9Sd1Xah.png) + +![](https://i.imgur.com/tzvoInk.png) + +Once you’ve got your wallet setup, you’ll be greeted with the pop-up shown below. Enter your password to proceed. Alternatively, if you’ve forgotten your password, click the link at the bottom entitled “I forgot my password” to begin the password recovery process. Remember, Enkrypt can't recover the password for you – you will need your recovery phrase to reset password. + +![](https://i.imgur.com/MPznxPI.png) + +--- +## Connect Enkrypt to Astar +Once you have Enkrypt installed and have created or restored your wallet, connect to Astar by clicking on the “Manage networks” button on the bottom left. + +![](https://i.imgur.com/PAm2GrB.png) + +After clicking on “Manage networks” the following window will appear. Scrolling down in this window will reveal more available networks. Click the button on the right of each corresponding network in order to activate or deactivate it. A green button indicates the network is currently being shown in your wallet, while a gray button indicates that it is not. When you’re done selecting Astar, you can simply click out of the window or click the “X” on the top right to continue. + +![](https://i.imgur.com/c21up34.png) + +After exiting the pop-up window, you should see Astar in your network list. See below for an example. Click on a network in order to start interacting on that chain. + +![](https://i.imgur.com/VTNFL9j.png) + +--- +## Basics +Below you’ll find screenshots showing you where to receive, send, and buy crypto using Enkrypt. By clicking on the drop-down menu on the top-center of the app, you’ll be able to see your different accounts. Enkrypt generates multiple EVM and Substrate addresses from the same recovery phrase. Use these addresses to receive crypto into your Enkrypt wallet. You can copy the address, open a QR code, or see it on a block explorer using the buttons on the upper right. + +![](https://i.imgur.com/wjLysH4.png) + +![](https://i.imgur.com/BnRPXNK.png) + +Clicking on “buy” will open up a webpage, prompting you to purchase via our partner Simplex (ETH, BNB, and MATIC currently available). Clicking on “send” will open a new page within Enkrypt - fill it out to send a transaction! + +Please refer to the MEW help center for detailed guides on using Enkrypt to buy, send, swap, add and import accounts, connect a hardware wallet, and interact with dApps on Dotsama and Ethereum: https://help.myetherwallet.com/en/collections/3575691-enkrypt + +![](https://i.imgur.com/QjXxk1M.png) + +![](https://i.imgur.com/dsWU9Vb.png) + +--- +## Working With DApps + +Every chain integrated into Enkrypt has its own “Featured dApps” section as seen below. The featured dApps change from time to time, so be sure to keep an eye out for new and exciting dApps in the Kusama ecosystem. If you build dApps and would like to see yours featured - get in touch at [enkrypt.com](https://www.enkrypt.com/?mtm_campaign=Interacting%20with%20Astar%20using%20Enkrypt)! + +![astar-dapps](https://blog.enkrypt.com/content/images/2022/11/astar-dapps.png) + +When landing on a dApps webpage, simply choose Enkrypt when asked how you would like to connect. If you don’t see Enkrypt, choose Polkadot.js or MetaMask, and it will automatically connect to Enkrypt for you, assuming you have Enkrypt installed. + +You can easily switch between networks and accounts directly in the Enkrypt extension while interacting with a dApp page. + +![](https://i.imgur.com/UgsoPP7.png) + +--- + +###### Join our [Discord](https://discord.com/invite/Gz8vBneyKe) community 🌐 | Follow us on [Twitter](https://twitter.com/enkrypt) 🐦 | Check out our [blog](https://blog.enkrypt.com) 📰 + +--- diff --git a/docs/use/how-to-guides/layer-1/manage-wallets/wallet-providers/index.md b/docs/use/how-to-guides/layer-1/manage-wallets/wallet-providers/index.md new file mode 100644 index 0000000..b085b68 --- /dev/null +++ b/docs/use/how-to-guides/layer-1/manage-wallets/wallet-providers/index.md @@ -0,0 +1,10 @@ +# Wallet Providers + +Here you will find various wallets compatible with Astar Network. + +```mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +``` \ No newline at end of file diff --git a/docs/use/how-to-guides/layer-2/ASTR-Liquid-Staking.md b/docs/use/how-to-guides/layer-2/ASTR-Liquid-Staking.md index 22e2dcd..7bdf9e4 100644 --- a/docs/use/how-to-guides/layer-2/ASTR-Liquid-Staking.md +++ b/docs/use/how-to-guides/layer-2/ASTR-Liquid-Staking.md @@ -7,7 +7,7 @@ title: ASTR Liquid dApp Staking with Bifrost Finance import Figure from "/src/components/figure" This page explains how to participate in Astar dApp Staking via Bifrost Liquid Staking solution on **Astar zkEVM**. -[More information about dApp Staking] (/docs/use/dapp-staking/index/). **LINK TO UPDATE** +[More information about dApp Staking] (/docs/about/products/dapp-stakingindex/). **LINK TO UPDATE** If you have `ASTR` on Astar L1 (Subtrate or EVM), consult [this guide] (/docs/use/zkevm-guides/Bridge-Astar-EVM/) to transfer them from Astar to Astar zkEVM. **LINK TO UPDATE** diff --git a/docs/use/polkadot/Proxies.md b/docs/use/polkadot/Proxies.md new file mode 100644 index 0000000..c3d61ec --- /dev/null +++ b/docs/use/polkadot/Proxies.md @@ -0,0 +1,113 @@ +--- +sidebar_position: 8 +--- +# Proxy accounts + +## Overview + +Pallet Proxy enables accounts to grant specific permissions to other accounts, empowering them to make calls on their behalf, thereby safeguarding the security of the underlying accounts. +On this page, you will find a detailed overview of the various proxy types, extrinsics, general definitions, and features associated with the proxy pallet. Additionally, there are tutorials available to help you understand and utilize the proxy functionality effectively. + +**Proxy Types** +--- +1. **Any** - This proxy type allow delegate account to make any call that are supported by proxy pallet. This is highest level of priveledge so should always use that with caution. + +2. **NonTransfer** - This proxy type allow delegate account to make any call supported by proxy pallet expect for the asset transfer funtionalities. This can come handy when you want to keep your funds secure in cold storage and want to delegate all the other functionalities to a proxy account. +To see complete list of functionality, checkout the source code in Astar repo. + +3. **Balances** - This proxy type gives control of handling accounts and balances to the delegate account. Complete list of calls can be found [here](https://docs.rs/pallet-balances/latest/pallet_balances/pallet/enum.Call.html). + +4. **Assets** - This proxy type allows delegate account to control the functionalities related to fungible assets which includes asset issuance, transferal, minting etc. This is to be notes that this proxy types doesn't control the native currency like Astar or Shiden which are controled by Balances proxy. + +5. **IdentityJudgement** - This proxy type allows a single functionality to delegate account which is to provide a judgement to an identity in a naming system. The delegator must be a registrar. + +6. **CancelProxy** - This proxy type allows delegate account to to reject and remove any announced proxy calls. + +7. **DappsStaking** - This proxy type allows delegate account to perform DappStaking related transactions such as register, unregister contracts, claim rewards etc. + + +**Extrinsics** +--- +The proxy pallet provides the following extrinsics (functions): +* **addProxy**(delegate, proxyType, delay) - allows the sender to register a proxy account capable of making calls on behalf of the sender. If the delay value is set to a number greater than 0, the proxy account must announce a transaction and wait for the specified number of blocks before executing it as a proxy. This function also emits a ProxyAdded event. + +* **announce**(real, callHash) - used to record the announcement of a proxy transaction made by proxy accounts that have a delay requirement. This function emits an Announced event. + +* **anonymous**(proxyType, delay, index) - generates a new account with an inaccessible private key, making it inaccessible. The sender assumes the role of a proxy for this account, based on the specified type and delay. Caution: If the proxy is removed, the primary account will become inaccessible. This function emits an AnonymousCreated event. + +* **killAnonymous**(spawner, proxyType, index, height, extIndex) - removes a previously spawned anonymous proxy. + +* **proxy**(real, forceProxyType, call) - performs a transaction as a proxy. This function emits a ProxyExecuted event. + +* **proxyAnnounced**(delegate, real, forceProxyType, call) - executes a transaction as a proxy and removes any previous corresponding announcements. This function emits a ProxyExecuted event. + +* **rejectAnnouncement**(delegate, callHash) - if the sender is a prime account, it removes a specific announcement from their proxy account. + +* **removeAnnouncement**(real, callHash) - if the sender is a proxy account, it removes a specific announcement to their prime account. + +* **removeProxies()** - unregisters all proxy accounts associated with the sender. +* **removeProxy**(delegate, proxyType, delay) - unregisters a specific proxy account linked to the sender. This function emits a ProxyRemoved event. + + +**Constants for Pallet Proxy** +--- + +| Constant | Description | +|--------------------------|--------------------------------------------------------------------------------------------------------------| +| announcementDepositBase | base amount of currency required to reserve when creating an announcement. | +| announcementDepositFactor| amount of currency required per announcement made. | +| maxPending | maximum number of time-delayed announcements allowed to be pending. | +| maxProxies | maximum number of proxies permitted for a single account. | +| proxyDepositBase | base amount of currency required to reserve when creating a proxy. | +| proxyDepositFactor | amount of currency required per proxy added. | + + +**Why Proxy Deposits ?** +--- +To create proxies within the network, it is necessary to provide deposits in the native currency (like ASTR or SDN). The deposit is required because adding a proxy requires some storage space on-chain, which must be replicated across every peer in the network. Due to the costly nature of this, these functions could open up the network to a Denial-of-Service attack. + +When creating a proxy, a bond is deducted from your free balance and transferred to your reserved balance. This mechanism helps maintain the integrity and stability of the proxy system while providing assurance that the bond can be returned when the proxy is deactivated or removed. + +The required deposit amount for `n` proxies is equal to: + +`ProxyDepositBase` + `ProxyDepositFactor` * `n` + + +**Pure / Anonymous Proxy** +--- + +Anonymous proxies (Pure Proxies) are freshly generated accounts, distinct from original one, which originate from a primary account. The primary account assumes the role of a proxy, representing the anonymous proxy. These proxies are non-deterministic and lack a private key, yet possess a randomly generated address. It is worth noting that anonymous proxies remain ownerless, as no individual possesses a private key to exercise control over them. + +Despite their complexity and associated dangers, pure proxies have many important benefits like enhanced security and multi-sig account management. + +:::tip + +It is highly encouraged to checkout [**this**](https://wiki.polkadot.network/docs/learn-proxies#anonymous-proxy-pure-proxy) documentation by Polkadot for more information about Pure proxy, its limitations and benefits. + +Video resource for Pure Proxy - https://youtu.be/MqY6yU-YLO0 + +::: + +**Time-Delayed Proxy** +--- + +To enhance the security of proxies, we can implement a delay mechanism measured in blocks. A delay value of 10 corresponds to ten blocks, resulting in a delay of around two minute (for Astar network). The proxy will utilize the `proxy.announce` extrinsic to declare its intended action and will wait for the specified number of blocks according to the defined delay time before executing it. + +During this delay window, the intended action can be canceled by either the proxy itself using the `proxy.removeAnnouncement` extrinsic or by the accounts controlling the proxy through the `proxy.rejectAnnouncement` extrinsic. The announcement made by the proxy includes the hash of the intended function call, enabling the identification and validation of the action. + +By incorporating this delay mechanism, any malicious activities can be detected and reversed within the designated delay period. After the time-delay has passed, the proxy can proceed with executing the announced call using the `proxy.proxyAnnounced` extrinsic. + +:::caution + +Any attempt to sign the transaction using **proxy** extrinsic with pure proxy will fail. Read more about [**pure**](https://wiki.polkadot.network/docs/learn-proxies#anonymous-proxy-pure-proxy) proxies here. + + +::: + +This implementation adds an additional layer of security to proxies, providing confidence in their usage, knowing that actions can be observed and undone within the specified delay period. + +:::tip + +Check out this [**video**](https://www.youtube.com/watch?v=3L7Vu2SX0PE) by Polkadot to learn how to set up time-delayed proxies. + +::: \ No newline at end of file