# Acala & Karura Wiki Welcome to the Acala & Karura wiki, the hub for those interested in learning, building, or using the Acala and Karura protocols. The wiki is divided into sections to cater to each of these different groups within the Acala ecosystem: 1. If you're eager to start building your project to connect to Acala or Karura, see the [build](/build/evm+-documentation) section. 2. If you're interested in operating a node, head on over to the [integration](/integrate/acala) section. 3. If you are here to learn, peruse the [learn](/learn/acala-introduction) section. 4. If you want to quickly find some general information, such as communities, links, the Alliance, please find [ecosystem](/ecosystem/general-links). 5. If you are ready to get started using Acala or Karura, head to [Get Started](/get-started/acala-network) section. If you're looking for an introduction to Acala please [go here](/learn/acala-introduction). ### Other Wikis: * [Acala Dollar](https://docs.acaladollar.app/) * [AcalaSwap](https://docs.acalaswap.app/) * [Homa Liquid Staking](https://docs.homastaking.app/) * [Acala Apps](https://wiki-apps.acala.network/) * [Karura Apps](https://wiki.karura.app/) * [EVM+ Documentation]() ### Want to get started using? * [Get Started with the live Acala Network](/integrate/acala/endpoints) * [Get Started with the live Karura network](/get-started/get-started) * [Get Started](broken://pages/8ov3x2LEfWPoXsNBlQOU) with the testnet - Try the test network. * [Learn](/learn/acala-introduction) - **Quick navigation in order to learn Acala.** ### Want to build on Acala? * [Builder Guides](/build/evm+-documentation) - Tools, libraries, and resources to help you build. * [Starters Guide](/build/development-guide) - **Overview on how to get started building your project on Acala.** ### Want to maintain the network? * [Integration Guide](/integrate/acala) - Information covering running a node on the Acala and Karura Network. ### Resources * [Community / Ecosystem](/ecosystem/community) - List of community rooms and channels to talk to others about Acala. * [Contributing Guide ](/misc/contributing)- Rules for contributing to the wiki. # Overview {% hint style="warning" %} *The following documentation outlines the intended features and processes that Acala Sinai Upgrade intends to implement in the future. This document will continue to be updated and reviewed as we progress with the Sinai Upgrade. Please note that certain sections may contain inaccuracies or outdated information.* {% endhint %} ## Overview *The Sinai Upgrade, akin to the biblical Mount Sinai where transformative revelations were received, marks the next major phase in Acala’s journey of innovation and growth. It is a testament to our unwavering faith in the vision of web3 finance, our commitment to overcoming challenges, and our dedication to creating a sustainable and prosperous future.* Following the successful Exodus Upgrade, the Sinai Upgrade aims to elevate the Acala Network to new heights, introducing ground-breaking features and enhancements for a robust and dynamic DeFi ecosystem. The goals of the Acala Sinai Upgrade * Improve infrastructure on a performance, security and governance level. * Build the liquidity layer of web3 finance including Multi-chain LSTFi * Complete the path of aSEED ## Roadmap * Overview of the Sinai Upgrade ([X article](https://x.com/AcalaNetwork/status/1778115130108108824)) * Sentinel providing cross chain security ([X article](https://x.com/AcalaNetwork/status/1773019267555864668)) * aSeed Conversion on Karura ([Karura subsquare](https://karura.subsquare.io/democracy/referenda/104)) {% content-ref url="/pages/fq41xqxIDvYDyk0dhoMI" %} [Execution Roadmap](/acala-exodus-upgrade/execution-roadmap) {% endcontent-ref %} # Execution Roadmap {% hint style="warning" %} The following documentation outlines the intended features and processes that Acala Sinai Upgrade intends to implement in the future. This document will continue to be updated and reviewed as we progress with the Sinai Upgrade. Please note that certain sections may contain inaccuracies or outdated information. {% endhint %} ## Execution Roadmap
## Execution Status * [x] One-Click MultiChain Cross-stack DeFi * [ ] Ethereum, Solana & L2 chain Liquidity Integration * [ ] LSTFi Ecosystem Expansion * [ ] Euphrates Goes Multichain * [ ] Open Gov Upgrade * [x] Cross Chain Security * [ ] Performance Upgrade: Asynchronous Backing * [ ] JAM Service Research & Development * [x] aSEED II: Conversion * [ ] aSEED III: Redemption The Sinai Upgrade is the next major phase of Acala’s technological advancement, following the successful completion of the Exodus upgrade. This section outlines the objectives and key features of the Sinai Upgrade. #### One-Click MultiChain Cross-stack DeFi This innovative feature streamlines the process of interacting with multiple blockchain ecosystems through a single, user-friendly interface. By enabling seamless cross-chain transactions, Acala aims to significantly reduce the complexity and improve the efficiency of accessing diverse DeFi products across different blockchains. Acala has taken user experience as a top priority when building new products. #### Ethereum, Solana & L2 chain Liquidity Integration Acala Network will expand its interoperability by integrating liquidity from Ethereum, Solana, and various Layer 2 (L2) chains. This upcoming enhancement will allow for smoother asset transfers and greater access to a diverse range of decentralized finance (DeFi) opportunities across these leading blockchain networks. Read more about the liquidity integration in this [article](https://medium.com/acalanetwork/the-new-frontier-of-restaking-and-yield-bearing-lp-pools-on-acala-4cd4ac23e9b7). #### LSTFi Ecosystem Expansion Acala Network is set to broaden its DeFi landscape focusing on the enhancement and diversification of Liquid Staking Token Finance (LSTFi). This initiative will introduce new products and partnerships that leverage the benefits of liquid staking tokens, offering users more flexibility and yield-generating opportunities. As part of this expansion, the platform will integrate additional staking options and financial instruments designed to optimize liquidity and yield. This strategic development of native and non-native products will not only enrich our current offerings but also attract a wider audience, establishing a more robust and versatile DeFi ecosystem. #### Euphrates Goes Multichain The [Euphrates platform](https://farm.acala.network/), known for its boosted liquid staking capabilities, will extend its reach across multiple popular blockchain networks. This strategic enhancement aims to funnel liquidity into various applications across different chains, thereby maximizing user rewards and broadening investment opportunities. By integrating with multiple chains, Euphrates will enhance its ability to attract diverse pools of liquidity. This expansion supports a seamless and efficient interaction for users, reinforcing Euphrates’ position as a leader in innovative staking solutions. #### Open Gov Upgrade The Open Gov Upgrade marks a transformative step in enhancing our on-chain governance system by adopting a model used within the Polkadot ecosystem. This change will better democratize decision-making processes, allowing for more transparent and community-driven governance. ACA holders will be able to propose, vote on, and implement changes directly within the ecosystem, ensuring that the platform remains responsive to the needs and preferences of its community. The upgrade will introduce mechanisms for greater participation and accountability, fostering a more inclusive and adaptable governance framework. #### Cross Chain Security Enhancement Recognizing the critical importance of robust security in a multichain landscape, we are committed to enhancing protective measures across blockchain networks. To this end, we have introduced Sentinel, an open-source tool that currently offers essential functionalities like rate limiting between parachains to maintain network stability and prevent misuse. As we continue to expand our multichain capabilities, Sentinel will evolve to include more advanced security features. These enhancements will fortify our cross-chain security framework, providing comprehensive protection against a broader spectrum of vulnerabilities and attacks, ensuring a safer and more reliable blockchain environment for all users. #### Performance Upgrade: Asynchronous Backing The Acala network is set to undergo a significant performance upgrade through the implementation of asynchronous backing. This advanced feature is designed to enhance the network's throughput and efficiency by allowing transactions to be processed in a non-linear, asynchronous manner. This upgrade is critical for supporting higher transaction volumes and providing a smoother, faster user experience, aligning with Acala’s commitment to scalable and robust blockchain solutions. #### JAM Service Research & Development The Acala team is actively involved in the research and development of the newly introduced Polkadot JAM chain. By leveraging our expertise in development in blockchain technology, we aim to enhance and refine the functionalities of this cutting-edge chain. This initiative allows us to advance decentralized technologies and further cement our leadership in the blockchain industry. #### aSEED II: Vault Conversion We are developing a conversion pallet designed to allow a percentage of the collateral in a vault to be transferred to the aSEED treasury, while the remaining collateral is returned to the vault owner. Additionally, this conversion can be scheduled to execute at a future date, providing vault owners ample time to prepare for the changes. #### aSEED III: Redemption We are preparing to implement a redemption mechanism for aSEED by drafting proposals and establishing voting protocols for redemption criteria, such as eligibility after 12 months with the underlying aSEED value being at least $1. The delivery of the redemption pallet code will enable the redemption of aSEED using treasury assets, allowing users to exit their aSEED positions.

# aUSD SEED (aSEED) The goal of aUSD Seed (aSEED) is to provide a pathforward for aUSD with options to exit existing aUSD holdings/vaults or to participate in Acala’s future growth. {% hint style="warning" %} *The following documentation outlines the intended features and processes that Acala Exodus Upgrade intends to implement in the future. This document will continue to be updated and reviewed as we progress with the Exodus Upgrade. Please note that certain sections may contain inaccuracies or outdated information.* {% endhint %} ## aUSD Conversion aUSD will be converted to aSEED 1:1 across all avenues including account balance, and liquidity pools etc. This means current aUSD holders will hold aSEED instead, and aUSD LPs will be converted to aSEED LPs. Preparation: prior to aUSD to aSEED conversion, set Honzon risk parameters to stop minting, liquidation etc. aUSD (Karura) will be converted to aSEED (Karura), aUSD (Acala) will be converted to aSEED (Acala). ### aUSD Conversion Date aUSD Conversion is targeted to be on July 20 (exact block TBD) provided that the community vote is passed and on-chain changes are executed. From this date, `aUSD` will become `aSEED` (aUSD Seed). The on-chain `assetRegistry` will be updated with the new symbol (aSEED) and name (aUSD SEED). If you are a holder of aUSD, then you do not need to take any action. If you are a vault owner, you can continue to manage your vaults after this date till CDP Conversion date. If you are a builder of a tool that consumes `@acala-network/api` then there should be no real changes to be made in your application. However if your application displays the token symbol and token name in an offchain way, then you will need to ensure you display the correct symbol and name. **Find aSEED brand assets** [**here**](https://wiki.acala.network/ecosystem/media-kits#acala-brand-assets)**.** ## CDP Conversion For a CDP owner who has borrowed $$x$$ amount of aUSD with a deposit of $$y\_{c\_i}$$ amount of collateral type $$c\_i$$, and chooses not to repay their CDP debt by the aSEED conversion event: At the aSEED conversion * their $$x$$ amount of aUSD tokens will become $$x$$ amount of aSEED tokens ​ * the amount of collateral going into the aSEED treasury is: $$ \frac{x \hat{P\_a} }{ \hat{P\_{c\_i}}} $$ where $$\hat{P\_a}, \hat{P\_{c\_i}}$$ are the aSEED conversion prices of aUSD and collateral type $$c\_i$$ passed at the community votes (for Acala see the vote [here](https://voting.opensquare.io/space/acala/proposal/QmXFw8DZbX5wDFeD1kQtFDy8tmE4FKEir7tZVqe9vCqBTb), for Karura see the vote [here](https://voting.opensquare.io/space/karura/proposal/QmUuHgFt4fN4iKU6JzW2utx2cykz4Er3EyhLHRwYEjDk3r)) * the amount of collateral returning to the CDP owner is: $$ y\_{c\_i} - \frac{x \hat{P\_a} }{ \hat{P\_{c\_i}}} $$ ### Example For a CDP owner who has borrowed 200 aUSD with a deposit of 100 DOTs, and chooses not to repay their CDP debt by the aSEED conversion event: ​ At the aSEED conversion, ​ * their 100 aUSD tokens will become 100 aSEED tokens * the amount of DOTs going into the aSEED treasury is: $$ \frac{200 \cdot 0.538322 }{4.587095} = 23.471151 $$ * the amount of DOTs returning to the CDP owner is: $$ 100 - \frac{200 \cdot 0.538322 }{4.587095} = 76.528848 $$ ## Redemption aSEED holders can redeem the underlying assets in the aSEED treasury in future under certain set criteria, e.g. after 12 months and aSEED underlying value >= $1. The pallet code will be developed and criteria parameters will be voted in via governance. # aSEED Integration Guide ## Overview aSEED does not have a pegged price; it is redeemable to aSEED treasury underlying asset [in future under certain criteria](https://wiki.acala.network/acala-exodus-upgrade/ausd-seed-aseed#redemption). Below are liquidity venues for aSEED: Acala * Acala Swap * Stellaswap Karura * Karura Swap * Zenlink ## Integrate via EVM+ aSEED is available as ERC-20 assets on Acala EVM+ on both Acala and Karura Contract Address * aSEED (Karura): 0x0000000000000000000100000000000000000081 * aSEED (Acala): 0x0000000000000000000100000000000000000001 ## Integrate via Substrate Refer to [token transfer guide](https://wiki.acala.network/integrate/acala/token-transfer) # aSEED Redemption Guide aSEED Redemption went live after the passing of governance proposal [140](https://acala.subsquare.io/democracy/referenda/140). aSEED holders are free to redeem aSEED's underlying assets from the aSEED treasury. ## Video {% embed url="" %} ## aSEED Redemption 1\) Go to or click the aSEED tab on the Acala Dapp
2\) Enter the amount of aSEED you wish to redeem and click Redeem
3\) Confirm the current aSEED value and click Proceed 4\) Sign the transaction in your wallet and a balance of LDOT, DOT and USDCet will arrive in your wallet shortly.
# ACA ## Overview Acala network has grown beyond the original ACA scope which has limited utility to support new growth based on new infrastructure and protocols built. The Exodus Upgrade aims to align stakeholders, participants within the Acala ecosystem, protocol functionalities and network infrastructures, and ACA as a utility and securing element of Acala Network. It will optimize for network growth, sustainability and safety by boosting ACA utility and ACA holder engagement. {% hint style="warning" %} The following documentation outlines the intended features and processes that Acala Exodus Upgrade intends to implement in the future. This document will continue to be updated and reviewed as we progress with the Exodus Upgrade. Please note that certain sections may contain inaccuracies or outdated information. {% endhint %}
### ACA Utility The following are new ACA utilities in addition to existing utilities such as used as transaction fees, vote in governance proposals, pallet deployments etc. * ACA Staking * Ecosystem token contributions are farmable via staked ACA * Vote for emission distribution to liquidity pools and dApps * A portion (e.g. 20% via governance) of staked ACA can be used as a mitigation tool in case of a shortfall event within the protocols that are native to Acala ACA will also power captive liquidity with the following initial long-term incentivized liquidity pools in Acala Swap * ACA to DOT * ACA to USDT (or USDC) * LSDs to DOT * LSDs to USDT (or USDC) * LSD to LSD * DOT to USDT (or USDC) * aUSD to DOT (or aSEED-DOT after aSEED launch) ### ACA Emissions Acala will have a total of 100 million ACA emissions per year limited to 6 years upon governance approval. 50% of the emission will be reserved for ACA staking, and 50% reserved for yield farming for liquidity pools, dApps built on the Universal Asset Hub (UAH), and other avenues that help build liquidity and adoption. ### ACA Burns A portion of unspent emissions will be burned periodically e.g. 1% unspent emission every month, a portion of the network fees accumulated over a period of time will also be burned e.g. cumulative network fees will be recorded every six months, and 20% will be burned via governance. This overtime may make ACA deflationary. \ Note: Karura KAR will follow the same upgrade with 1/10 of the emission as ACA. # ACA/KAR Staking * [ACA Staking Guide](https://guide.acalaapps.wiki/staking/aca-staking) * ACA-USDCet Liquidity Pool: [dapp](https://apps.karura.network/swap/bootstrap), [doc](https://wiki.karura.app/stake/bootstrapping) * [KAR Staking Guide](https://wiki.karura.app/stake/kar-staking) * KAR-USDCet Liquidity Pool: dapp, [doc](https://guide.acalaapps.wiki/acala-swap/bootstrapping-guide) # LDOT ### Overview LDOT is Acala Network’s flagship Liquid Staking Token (LST), representing staked DOT while retaining liquidity for use in DeFi. As Acala evolves into the liquidity layer for Polkadot and beyond, LDOT serves a central role in aligning capital efficiency with staking security. The ongoing integration of LDOT into Acala’s Universal Asset Hub (UAH), ecosystem dApps, and partner protocols is designed to expand its utility, deepen liquidity, and enhance overall network value. This documentation outlines the current and intended utilities, liquidity incentives, and integration pathways for LDOT as a core asset within the Acala ecosystem. Updates will be made as new protocols and features are launched. *** ### LDOT Utility LDOT is designed to maximize DOT staking yield while preserving liquidity for use across DeFi applications. The following outlines LDOT’s key utilities within Acala Network: * **Staking Liquidity Representation**:\ LDOT represents staked DOT on Polkadot via Acala’s native liquid staking protocol. Users receive LDOT in return for staking DOT, accruing staking rewards over time. * **Liquidity Pool Participation**:\ LDOT is a core component of long-term incentivized pools in Acala Swap, Stellaswap and beyond: * LDOT to DOT * LDOT to ACA * LDOT to other LSDs (e.g., JitoSOL, wstETH, etc.) * **Validator Voting**:\ LDOT holders may participate in validator voting using their LDOT as voting power. 1 LDOT equals to 1 vote for a validator candidate. * **Cross-Chain Utility**:\ LDOT is supported in the broader Polkadot ecosystem via XCM, allowing it to be used in DeFi platforms across parachains. *** ### LDOT Minting & Redemption * Users can mint LDOT by staking DOT via Acala’s Liquid Staking protocol. The staked DOT continues to earn native staking rewards. * LDOT is redeemable for DOT via: * **Instant Swap** (on secondary markets or swap pools) * **Delayed Unbonding** (native redemption process with a waiting period aligned with Polkadot’s unbonding cycle) *** ### LDOT and Network Safety As a staking derivative, LDOT plays a role in enhancing network security without sacrificing capital flexibility. The Acala staking system ensures proper validator selection and slashing coverage to protect users and the network. *** ### Summary LDOT is essential to Acala’s liquidity strategy and DeFi expansion. It connects DOT staking to DeFi utility, enabling users to earn while remaining active participants in Acala’s evolving ecosystem. Continued upgrades will expand LDOT’s role in Acala’s cross-chain liquidity, governance, and product suite. # Validator Candidate Guide To become an LDOT validator, candidates must bond LDOT as insurance. Once 10,000 LDOT is bonded, the validator becomes eligible for voting in the Validators section. This bond can be slashed, therefore proceed only if you fully understand the risks. Eligibility does not guarantee selection as only the top 16 validators, chosen by LDOT nominators, are included in the active set. ### How to Start a Candidate 1. Visit or select the Candidates tab within the Liquid Staking tab on the Acala dApp.
1. Click Add Candidate, enter your validator address, the amount to bind, (minimum of 1000 LDOT) and click Submit.
3. Confirm your bounded amount.
### How to Bind or Unbind 1. Visit or select the Candidates tab within the Liquid Staking tab on the Acala dApp.
2. Click Add/Remove on your active validator or validator candidate.
3. Select the Add tab if you wish to bind or the Remove tab if you wish to unbind.
4. Submit and confirm your transaction. *Note: the unbinding process takes 14 days.* ### How to Rebind or Claim 1. Visit or select the Candidates tab within the Liquid Staking tab on the Acala dApp.
2. On the My Bound section, select Rebound/Claim
3. With the Rebind tab active, the timers of your active unbounding transactions are displayed, you may choose to select the transactions you wish to rebind.
4. With the Claim tab active, you can see the claimable LDOT that has completed the unbounding period.
5. Rebind or Claim your tokens and confirm the transaction with your wallet. # Validator Voting Guide Below are the steps to vote for a LDOT validator candidate ### How to Vote a Candidate 1. Visit or select the Candidates section within the Liquid Staking tab on the Acala dApp.
2. Enter the amount of LDOT you wish to use to vote and then submit and confirm your transaction.
3. Click Vote and then select the validators you wish to commit your LDOT towards. Once satisfied with your decision, click Save.
4. A confirmation screen will pop up with a summary of your choices. Click Save to confirm your choices.
5. When finished, you will see an overview of your LDOT voting page. Here you can manage your LDOT voting power, edit the validators you support or unbound your LDOT.
# Universal Asset Hub (UAH) ## Overview Liquidity is fragmented on different L1, L2 and parachains. Real adoption requires deep and ubiquitous liquidity accessible for any dApp on any chain and any parachain. This is the goal for Acala’s Universal Asset Hub (UAH). {% hint style="warning" %} The following documentation outlines the intended features and processes that Acala Exodus Upgrade intends to implement in the future. This document will continue to be updated and reviewed as we progress with the Exodus Upgrade. Please note that certain sections may contain inaccuracies or outdated information. {% endhint %} ## LST Variaty & Liquidity Acala has been reliant on DOT, DOT LST (liquid staking token), and DOT derivatives as collateral and liquidity, and has been leading the Polkadot native assets TVL and xcm transaction volume. With the Exodus Upgrade, this will be taken to the next level and with expanded scope. An initial step of the Exodus Upgrade is to boost DOT LSTs to DOT, to other LSTs, and to USDC/USDT liquidity, meanwhile launching with new LST partners that have significant synergy with Acala, and preparing expansion for multichain LSTs. ### Types of LSTs: **Acala built:** LDOT, powered by the Homa protocol, is a DeFi-native non-custodial LST. It’s live and battle-tested on Acala **Acala hosted:** LSDOT, an enterprise-grade LST built by Liquid Collective, is a compliant and secure solution for more adoption through partners like Alluvial, Coinbase and Figment. It will be built on top of the Homa protocol and launched on Acala. tDOT, a synthetic DOT LST by Taiga that aggregates LST liquidity. Already live on Acala. **Multichain LSTs:** We will expand to build multichain LST liquidity from where the demand is e.g. Ethereum LSTs including LSETH (enterprise-grade LST by Liquid Collective), stETH by Lido, tapETH (Curve for LSTs). Through building with the Tapio protocol (tapETH) in stealth mode in the past months, we have received reaffirming feedback to contribute our innovation in the ever-growing LSTFi ecosystem, which is now aligned with our strategy via the Exodus Upgrade. ## Acala Multichain Asset Router Fragmented liquidity leads to fragmented developer and user experience. Thus UAH aims to offer liquidity agnostic to blockchains and seamless to DApps. This is powered by Acala Multichain Asset Router built on top of the XCM standard and Wormhole protocol using Substrate and Acala EVM+. UAH supports both Substrate token formats and EVM token standards, and will expand to other standards that deem to bring liquidity and adoption.
## LSTFi Ecosystem An LSTFi ecosystem will be fostered to create innovative use cases and bring in more adoption of Web3, which will be powered by Acala EVM+ dApp platform and long-term yield farming from upgraded ACA tokenomics. ACA holders can vote to direct ACA emission contribution to incentives programs for dApps and pools, and stake to participate in sharing ACA staking rewards and ecosystem project token contributions. This will potentially create a flywheel for ACA holder engagement and liquidity growth and will bring along more innovations, partners and communities to Acala. Euphrates liquidity dApp The Euphrates dApp will initially be deployed with DOT-based LST liquidity vaults, and later expand to support Ethereum and other multichain LST liquidity vaults which will open up opportunities for DOT holders to get exposure for Ethereum LSTFi and vice versa. \
# Acala Introduction A concise introduction. Acala is a decentralized liquidity blockchain that offers unified liquidity and built-in cross-chain capabilities. Acala’s key products, LDOT and Euphrates, exemplify its mission by providing a liquid staking solution, a liquidity distribution platform, and a liquidity center ideal for building robust decentralized applications. These solutions empower users globally to stake assets, maintain liquidity, and participate in a variety of financial activities. ## Assets * **Liquid DOT (LDOT)**: Acala's Liquid Staking DOT protocol, LDOT, allows users to stake their DOT and receive LDOT in return. This unique asset represents the staked DOT plus accrued rewards, providing users with liquidity and enabling active participation in the ecosystem’s financial service * **Acala Token (ACA)**: the native token of Acala network. Serving as the governance and utility token, ACA is pivotal in regulating network parameters and acting as the transaction fee token within Acala. ACA underscores Acala’s decentralized governance framework, allowing stakeholders to guide the platform's evolution. * **aSEED (formerly aUSD):** aSEED is Acala's upgraded asset, converted from aUSD. It provides users with the flexibility to exit existing holdings or engage in future growth of Acala's active aUSD treasury. Holders of aSEED can redeem the underlying assets once the redemption criteria is set by governance. * **Liquid Crowdloan DOT (LCDOT):** LCDOT is a token that represented the DOT locked during Acala's crowdloan. It provided users with liquidity while their DOT was staked in the crowdloan, enabling them to participate actively within the ecosystem. Holders of LCDOT either had their DOT automatically airdropped to them or could convert their LCDOT back to DOT at a 1:1 ratio using the designated [portal](https://apps.acala.network/withdraw-crowdloan). ## The Liquidity Layer of Hybrid Finance As a liquidity-focused blockchain, Acala empowers users to unlock the full potential of their digital assets. Acala’s cross-chain capabilities and robust infrastructure enable the integration of diverse assets, making them available for institutions, projects, and individual users. Acala facilitates seamless interactions across various blockchains and applications, enhancing asset utility and user engagement. ## Euphrates: Diverse Financial Opportunities [Euphrates](https://farm.acala.network/) offers a range of financial opportunities for its users. It serves as a one-stop shop for users seeking financial opportunities and for developers aiming to boost liquidity to their applications or protocols. For users, Euphrates offers the ability to support various protocols with their capital and earn native ecosystem rewards and ACA from Acala. For developers, it provides a robust distribution platform, fostering a vibrant and incentivized financial environment. ## The Homa Protocol: LDOT The [Homa Protocol](https://docs.homastaking.app/) empowers users within crypto ecosystems by allowing them to maintain the liquidity of their staked assets, creating financial opportunities without sacrificing staking rewards. Liquid DOT, or LDOT is the current product live using the Homa Protocol. Users can employ LDOT in liquidity pools or use it as collateral in decentralized finance applications, which increases capital efficiency and enables the development of new financial products. Additionally, LDOT plays a critical role in decentralized finance, driving ecosystem growth and fostering innovation. ### Acala Token Emissions and Burns The total supply of ACA is capped at 1.6 billion tokens. Acala Network will emit 100 million ACA annually for up to six years. Half of these emissions will be allocated to ACA staking, encouraging active participation, while the other half will be directed toward yield farming in liquidity pools, supporting DApps on the [Universal Asset Hub (UAH)](https://wiki.acala.network/acala-exodus-upgrade/universal-asset-hub-uah), [Euphrates](https://farmdoc.acala.network/), and other initiatives aimed at boosting liquidity and adoption. Additionally, the network will regularly burn 1% of any unspent emissions each month, along with 20% of the accumulated network fees. These actions, which are subject to governance adjustments, have the potential to make ACA deflationary over time, thereby enhancing its scarcity and value proposition. * [Acala Whitepaper](https://github.com/AcalaNetwork/Acala-white-paper/blob/master/Acala_Whitepaper.pdf) * [Acala Token Economy Paper](https://github.com/AcalaNetwork/Acala-white-paper/blob/master/Acala_Token_Economy_Paper.pdf) * [Acala Token Page](https://acala.network/acala/token) ## Network Security Acala leverages Polkadot’s robust security protocols for block validation and finalization, ensuring a high level of integrity and decentralization. The network is maintained by collators who facilitate the processing of transactions and state transitions, ensuring the network's continuous operation. Acala inherits trustless bridge between itself and Polkadot as well as all connected parachains using cross-chain message passing (or [XCM](https://wiki.polkadot.network/docs/learn-crosschain)). ### Collators Acala blockchain is maintained by collators, who maintains a full node, collects parachain transactions from users and producing state transition proofs for Polkadot validators. In other words, collators maintain parachains by aggregating parachain transactions into parachain block candidates and producing state transition proofs for validators based on those blocks. Acala blockchain is secured by the Polkadot Relay Chain, and kept alive by the collators. **Unlike validators, collators has nothing to do with security of the network, by being a parachain, the network is by default trustless and decentralized, and a parachain only needs one honest collator to be censorship-resistant.** Read more on Collators [here](https://wiki.polkadot.network/docs/learn-collator). ### Parachain Slots Polkadot has a limited number of parachains. It uses an auction mechanism to allocate parachain slots where the DOT tokens are used for bidding. A parachain can lease the slot for up to 2 years on Polkadot (1 year on Kusama). Acala has been building an on-chain Treasury of DOTs (network-controlled-value) to ensure it is self-sustainable. This is also the magic behind ACA being a fixed supply non-inflationary network token. * [Polkadot Parachain](https://wiki.polkadot.network/docs/learn-parachains) * [Treasury Whitepaper](https://github.com/AcalaNetwork/Acala-white-paper/blob/master/Building_a_Decentralized_Sovereign_Wealth_Fund.pdf) ### Emergency Shutdown In extreme cases, Acala can implement an emergency shutdown through its governance system to protect the network and its users. This mechanism ensures that all operations are decommissioned systematically, safeguarding assets and stakeholder interests. ### Conclusion Acala continues to push the boundaries of DeFi by providing innovative liquidity solutions and promoting a secure, integrated, and user-centric blockchain environment. LDOT and Euphrates play a central role in this strategy, enabling broader participation and fostering the development of the crypto finance landscape.
# Redenomination of ACA Effective on April 6 2021, the total fixed supply of (new) ACA will increase 10 times to 1,000,000,000. ACA token distribution and token economics remain the same. Acala chain is not live, so ACA redenomination does NOT have any impact on anyone, therefore this is for your information only. Key Points for the redenomination: * The total fixed supply of (old) ACA in the [whitepaper](https://github.com/AcalaNetwork/Acala-white-paper/blob/master/Acala_Whitepaper.pdf) is 100,000,000. * After 10x redenomination, the total fixed supply of (new) ACA will increase 10 times to 1,000,000,000. * ACA balances will increase by a factor of 10. * The distribution of ACA does NOT change, and holders of ACA still own an equal share of the network as before the change. ACA token economics also does NOT change. * As an example, if an account has 1,000,000 (old) ACA that is 1% of the total supply, then after redenomination, the account would still have 1% of the total supply which is 10,000,000 (new) ACA. * The main benefit of this change similar to the [redenomination of DOT](https://wiki.polkadot.network/docs/en/redenomination) is to avoid using small decimals when dealing with ACA and make calculations easier. * The main benefit of doing this before mainnet is that redenomination is way simpler before the Acala chain is live, with less confusion and NO impact to users and service providers like exchanges and wallets, etc. # Trilogy Networks The evolution of the Acala Network will be marked by trilogy networks. The evolution of the Acala is marked by trilogy networks. Acala stablecoin protocol, Acalaswap protocol and Homa staking protocol are deployed on all three networks: * **#1 Mandala Test Network**: is a risk-free and value-free playground for us, users and developers to test drive functionalities of Acala. Expect bugs, chaos, and unannounced reboots. Find out Mandala Testnet details [here](broken://pages/8ov3x2LEfWPoXsNBlQOU). * **#2 Karura Network**: is an unaudited and experimental release of Acala protocols on the Kusama network as a parachain. It will have economic value represented as its native tokens KAR, and KSM, both of which can be used as reserve assets of the stablecoin. Find out Karura Network details [here](/integrate/karura/endpoints). * **#3 Acala Network**: is deployed on the Polkadot network as parachain upon its launch. # Flexible Fees Any accepted tokens can be used as transaction fees on the Acala Network. Transaction fees are ultimately settled in the network native token ACA. Therefore a fee token must have a liquidity pool with the Acala stablecoin, which will create a route to the native token ACA. The system will automatically find the next available and supported fee token if the default token has zero balance. * Acala Network * Default fee token: ACA * Default order: ACA > aUSD > DOT > LDOT * Karura Network * Default fee token: KAR * Default order: KAR > kUSD > KSM > LKSM # How to change default fee token ## Default Fee Token You can check default fee token order on-chain, go to [Polkadot Webapp](https://polkadot.js.org/apps) - Select the chain (Acala or Karura) Navigate to `Developer` - `Chain state` > `Constants` >`transactionPayment defaultFeeSwapPathList` ![](/files/-MgFPkPslAEG5F0vnJqp) On Acala, the order might be ACA > aUSD > LCDOT > DOT. If a user has no ACA balance, then aUSD will automatically be used as fee token. Users can set their next default fee token to other tokens by executing the following transaction: ``` transactionPayment.setAlternativeFeeSwapPath(fee_swap_path) ``` # Governance Overivew The development direction. Acala takes a phased approach to employ various governance mechanisms that will allow it to progressively decentralize and ultimately be commanded by the majority network stakeholders. Acala's governance framework is based on Polkadot's technology that employs a **Referenda chamber**, **a General Council**, and **a Technical Committee** to govern the network. Acala however has sub councils that manage specialized aspects of the network including the **Financial Council** and the **Homa Staking Council**. ## Referenda Referenda is a simple, inclusive, stake-based voting scheme. Referenda can be started by public proposals or council proposals. There is an enactment delay period associated with it. Emergency proposals (e.g. fix urgent network issues) can be "fast-tracked" to have a shorter enactment period. Acala experiments with Polkadot's voting mechanisms including Tallying, Voluntary Locking, Adaptive Quorum Biasing. Read more [here](https://wiki.polkadot.network/docs/learn-governance/#referenda). ## Councils ### General Council Acala will initially be governed by a Referenda chamber together with a General Council appointed by the Acala Foundation whose decisions regarding the network such as runtime upgrades, resolving network issues and improvements are made transparent on-chain. Meanwhile, any ACA holders can propose any changes to the network, protocols and the Acala Treasury will be collectively voted for or against via the Referenda chamber. The General Council then provides oversight with veto rights to stop proposals that may deem malicious, posing security risks or not in the best interest of the Acala network. Once the network is sufficiently bootstrapped, stabilized, and security measures are in place, a Referenda will be started to move governance to the Elected Council phase where the candidacy of councilors is open, and councilors are elected by public voting. ### Financial Council Overseeing updates of stablecoin protocol parameters, and other protocol fee parameters * Elected by the General Council via 2/3 approval rating. ### Homa Staking Council Overseeing updates of Liquid Staking parameters e.g. validator selection * Elected by ACA holders. ### Oracle Collective Electing Oracle operators. Membership of the [Oracle Gateway](/learn/acala-introduction#open-oracle-gateway) requires approval from the General Council, which is essentially a Proof-of-Authority model that only authorized trusted operators can provide price feeds into the network. This model will evolve with the contemporary R\&D on the Oracle problem. * Elected by the General Council via 2/3 approval rating. ## Technical Committee Fastracking emergency proposals that are critical to the network operation, delaying an enactment, and canceling uncontroversially dangerous proposals. * Elected by the General Council via 2/3 approval rating. ## Emergency Actions * Fasttrack a scheduled task to 12 hours+ * Requires: 1/3+ Technical Committee consensus * Fasttrack a scheduled task to <12 hours * Requires: 2/3+ Technical Committee consensus * Delay a scheduled task for up to 48 hours * Requires: 1/3 Technical Committee consensus * Cancel a scheduled task * Requires: from schedule Origin OR * 3/4+ General Council consensus # Participate in Democracy The public Referenda Chamber is one of the three bodies alongside the General Council (and its sub-councils) and the Technical Committee governing the Karura network. Public referenda can be proposed and voted by any token holder with a bond. Every voting period, one proposal with the most support (# of seconds) will be moved to the referenda table for public voting. Voters who are willing to lock up tokens for a greater duration of time can have their votes amplified. This is largely modeled from the [Polkadot governance system](https://wiki.polkadot.network/docs/learn-governance) with Karura/Acala customization. ## Governance Parameters These are important governance parameters, which may change over time as we progress through the governance phases. * Launch Period: Public referenda is every **2 days** * Voting Period: Votes are tallied every **2 days** * Emergency Voting Period: Voting period for fast-tracked emergency referendum is **3 Hours** * Minimum Deposit: Proposing a referendum requires a minimum deposit of **100 KAR** * Enactment Period: Minimum period for locking funds and the period between a proposal being approved and enacted is **1 day** * Cool-off Period: Vetoed proposal may not be re-submitted within **7 days** Most of these parameters are visible on the Polkadot App. You can also view upcoming governance events on `the Event Calendar` ![](/files/-MebyAUgKFd9iGgfr29E) ## Propose a Referendum A referendum consists of some action that you want to propose. If voted in by token holders, then the action will be enacted on-chain automatically. You are required to bond some tokens to propose an action. Once a proposal is submitted, it can not be canceled. On the [Polkadot Apps - Karura parachain](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkarura-rpc-1.aca-api.network#/democracy), you can use the “Democracy” tab to make a new proposal. The action, such as 'force transfer balance from account A to account B', is encoded in a preimage, and the hash of the action is called preimage hash. Since the preimage can be quite large (hence costly to submit), you can submit a Proposal first which includes the preimage hash only, and submit the preimage (or have someone else submit it for you) later but before voting completes. ### Step 1: Submit a Proposal #### Get the preimage hash By clicking on the `Submit preimage` button, then fill in the action you want to propose, copy and note down the preimage hash `0x244fcb51680c90172ba55241d3d9229676c4471a4645aed223a2272b33264026`. Once you noted down the hash, you can now cancel the prompt. ![](/files/-MeMjrBOIqqs8AGW81g-) #### Submit a proposal Submit a proposal by clicking on the `Submit a proposal` button, and pasting in the preimage hash to submit it. Then the proposal shall appear in the proposal table. ![](https://lh5.googleusercontent.com/pzSjpt4wxQscdDdnjIFNE0iCRxLcPGHdJoEfXXaf8E7FIHfg66C0FSKIaoky0QMa3v0sl_E9LoJ1x0b_30X-2zzAZBZbijf8RhuMu_1J2UFapoaaDl0cIE58l7k3nw30nYaK0rCu) ### Step 2: Submit a Preimage Before voting of your proposal completes, you will need to submit the actual preimage. Otherwise, it cannot be enacted on-chain. You can repeat the ‘Submit a preimage’ process as previously mentioned, and click the ‘Submit preimage’ button to send the transaction. ## Vote on a Referenda To Vote on Referenda, you must hold KAR tokens and these tokens must be held in a wallet that has the functionality to participate in Democracy like Polkadot.js. If you don't have your tokens in Polkadot.js wallet, you can read more about [account generation](/get-started/get-started/karura-account). Once a proposal is in as a referendum, it will show up in the referenda table. You can navigate to the [Polkadot Apps - Karura Parachain Democracy](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkarura-rpc-1.aca-api.network#/democracy) to cast your vote. ![](/files/-MeMilPv_JhWrDzMyMkz) You can click on the ‘Vote’ button to vote. Select "Vote Aye" to support the proposal, and select "Vote Nay" to disapprove the proposal. You can also increase your conviction with the same number of tokens by locking them. The longer you are willing to lock your tokens, the stronger your vote will be weighted. Read more on [voting](https://wiki.polkadot.network/docs/maintain-guides-democracy/#voting-on-a-proposal) and [tallying](https://wiki.polkadot.network/docs/learn-governance#tallying). ![](/files/-Mf6RU7wtrNQrciSG_w-) ## Unlock locked tokens You will need to explicitly unlock these tokens once the locking period ends. You can go to the `Accounts` page, click the menu button for the voted account, and select the menu item`Clear expired democracy locks` to claim it back. Read more [here](https://wiki.polkadot.network/docs/maintain-guides-democracy/#unlocking-locked-tokens). ![](/files/-Mf-ovNhPIZBcN4-LRPT) ### Check Locked Democracy Votes Go to `Developer` - `Chain state`, then select `democracy` and `locks`. Select the account used for voting in the dropdown, and click the `+` button to see whether there's locked votes, and if any how long they are locked for. ![](/files/-Mf6S04L32upPGdENLdq) ## Delegate Vote You can delegate your vote to others to vote on your behalf. On [the Polkadot Apps - Karura parachain,](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkarura-rpc-1.aca-api.network#/extrinsics) go to the `Developer` tab -- `Extrinsics` , then select `democracy.delegate` . ![](/files/-MeMjgEuarbxslyUeDKi) # How to Verify a Runtime Upgrade This guide uses the runtime upgrade release 1.1.3 as an example. Once the upgrade is proposed, you shall see it on the [Polkadot App - Karura parachain - Democracy section](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkarura-rpc-2.aca-api.network%2Fws#/democracy). ![](/files/-MeZXYlfuyfZqQkjk66o) ## Upgrade Preimage Info Expand the proposal, and find the Preimage info. * Preimage: `parachainSystem.authorizeUpgrade(0xd9660e7d73163f7b2e1591c08c60e68f4b47cb85dcba54d55c53b9573876f55e)`\ * Hash: `0x4f8bf2c02c5a1e8cdcf7a94dabf2805c563c46a87876c684c5d79ffb745db115` ## Verify against code In the discussion post of the proposal, it shall provide the release tag, runtime WASM file and other necessary information for others to verify it against the preimage proposed. * Release page: * Runtime Wasm: ### Take the following step to verify #### 1. Build your own Wasm Runtime for the release * srtool is used to build wasm * More about srtool: * * * follow these steps to build * Install Docker * * Clone Acala repo * `git clone https://github.com/AcalaNetwork/Acala.git` * Checkout release branch * `git checkout release-karura-1.1.3` * Build with srtool * `make srtool-build-wasm-karur` * Wait for compiling done and your wasm is built #### 2. Generate hash & compare In the `Developer - Extrinsics` tab, use the following and upload the wasm to generate the call hash. Compare this with the preimage hash proposed. ![](/files/-MeZ_MgvVs_OgFAA_jU-) # How to Verify Referendum Proposal Navigate to [Polkadot JS App](https://polkadot.js.org/apps/#/explorer) - select intended network e.g. Acala or Karura, then select `Developer` - `Extrinsics` Click on the `Decode` tab on top of the page. Put the hex-encoded proposal in the `hex-ecoded-call` input box. The content of the proposal shall automatically displayed on the page to be verified. At the bottom of the page, the `encoded call hash` shall be checked against the actual proposal on-chain. # Treasury [Watch the Acala Treasury intro video](https://www.youtube.com/watch?v=Wh8g89OPFH8) The Acala Treasury is a reserve of digital tokens, native and foreign to the Acala ecosystem, stewarded by ACA holders and funded from Acala protocol fees and community contribution events with the purpose of enabling long-term network self-sustainability and growth. Deployment of the Treasury is primarily focused on * Self-funding a parachain slots on Polkadot * Bootstrapping protocol liquidity (e.g. provide LKSM, kUSD or DEX pair liquidity) * Platform and protocol operations and improvements * Network security operations and enhancements Further surplus can be deployed for * Software and tool development * Community, marketing, and event funding * Any other future community Karura Treasury Proposals (KTPs) ## Existential Goal The primary objective of the Acala Treasury is to build up its DOT reserve to ensure Acala has a sustainable reservoir of DOT to lease a parachain slot from Kusama for the foreseeable future. The Treasury can trustlessly deploy the tokens to bond a parachain for itself to sustain its operation, bootstrap liquidity of the DeFi protocols on Acala to solve the chick-and-egg problem of market makers and takers hence benefiting the entire network. # Acala EVM+ {% content-ref url="/pages/-MRwNVg5XTy3Xi8FsNDT" %} [Why Acala EVM+](/learn/acala-evm/why-acala-evm) {% endcontent-ref %} {% content-ref url="/pages/-MRwNtabnKdFhKXrK3WD" %} [Existing Solutions](/learn/acala-evm/existing-solutions) {% endcontent-ref %} {% content-ref url="/pages/-MRwO9T7KdFWxDgr968V" %} [Acala EVM+](/learn/acala-evm/acala-evm-composable-defi-stack) {% endcontent-ref %} {% content-ref url="/pages/-MRwYMJks8gzGhKx-c3r" %} [How does it work?](/learn/acala-evm/how-does-it-work) {% endcontent-ref %} {% content-ref url="/pages/-MRw\_1272yk\_\_RzAfsWF" %} [Get Started](/build/development-guide/smart-contracts/get-started-evm) {% endcontent-ref %} # Why Acala EVM+ ## Why Acala EVM+ EVM is currently the most popular smart contract platform. Many new generation blockchains who claim to be faster and cheaper than Ethereum, would still keep the Ethereum compatibility, to attract Solidity developers allowing them to reuse existing toolchains and migrate existing contracts with minimal effort. Despite how bloated and expensive Ethereum has become, none of the challenger chains have taken any significant market share thus far. It is clear to us that building a better, faster and cheaper Ethereum is not nearly enough. Just like Ethereum can do things Bitcoin can never do, which subsequently inspired many new innovations, Substrate and Polkadot are categorically different from Ethereum that will empower many new (chain level) innovations outside of the EVM sandbox. On the Acala chain, there’re DeFi primitives (stablecoin, DEX and liquid staking), liquidity and users that can be tapped into, there are also innovations that are simply not possible on Ethereum - customizable economic policy, flexible fees, allowing users to pay transaction fee with any supported tokens; native cross-chain capabilities; on-chain governance apparatus (no more locked funds); full upgradability (no more contract migrations) and more. We’d love to have all of these composable and compatible with EVM. # Existing Solutions Current Substrate EVM compatibility solution i.e. [Frontier](https://github.com/paritytech/frontier) emulates the Ethereum node. It aims to implement the full set of Ethereum RPC and to emulate the Ethereum block production process. This allows existing Ethereum tools such as Metamask and Remix to work with a Frontier enabled node seamlessly. Integrating Frontier has revealed the following challenges in order below by their severity: ## **1. Confined inside the EVM Sandbox** Frontier allows users to interact with EVM via Metamask or other existing Ethereum tools, none of which fully support Substrate yet. Any functionalities from native modules of Substrate, such as Acala DeX, token pallets that support multiple currencies and cross-chain capability, and any other pallets built by any parachains such as margin trading pallet by Laminar can not be accessed via Metamask or other existing Ethereum tools. This means users will need to use a Substrate wallet (e.g. Polkadot-js Extension) and Metamask at the same time if they ever want to taste the real power of Acala, Substrate or Polkadot for that matter. This is certainly a deal-breaker for us. ## **2. Making Nodes more Expensive** [Frontier](https://github.com/paritytech/frontier) is heavy by design. Substrate does not store transactions by hash nor historical events, nor does it provide any event filtering ability. Substrate nodes are lightweight by design in order to minimize resource usage (disk space & CPU). Ethereum nodes, on the other hand, allow users to query transactions by hash and offer powerful event log querying API. Frontier injects special block importing logic, storing the transactions and events into an off-chain auxiliary store in order to power the query API required by Ethereum. This adds maintenance costs as it requires more powerful machines and larger disk space to operate a node. This goes against the goal to have a lightweight node to lower barriers for people from anywhere to run nodes which helps the network to be more decentralized. # Acala EVM+ ## Acala EVM+ - Code Name: Project Bodhi Acala and all Substrate-based chains are fundamentally different from Ethereum. If we are trying to emulate an Ethereum node, we will suffer from the worst of both worlds. It will be a step backward for us to inherit all the restrictions from a legacy blockchain platform. We see EVM as one part of the Acala/Substrate/Polkadot, together the Acala network will provide a categorically different experience. Acala EVM will try to achieve these design goals 1. Enable users to have a complete full-stack Acala (and Substrate) experience seamlessly with a single wallet. 2. Enable protocol composability for EVM and runtime 3. Enable developers to develop and deploy DApps on Acala with great tooling support The Acala EVM delivers the following benefits and features from the best of both Ethereum and Substrate platforms: {% content-ref url="/pages/-MS0RVh03cREJOF0hp4M" %} [Composable DeFi Stack](/learn/acala-evm/acala-evm-composable-defi-stack/composable-defi-stack) {% endcontent-ref %} {% content-ref url="/pages/-MS0RjJCPUiOQ5BYqA00" %} [Flexible Fees](/learn/acala-evm/acala-evm-composable-defi-stack/flexi-fees) {% endcontent-ref %} {% content-ref url="/pages/-MS0RstLBN56EIA8-5Dz" %} [On-chain Scheduler](/learn/acala-evm/acala-evm-composable-defi-stack/on-chain-scheduler) {% endcontent-ref %} {% content-ref url="/pages/-MS0RtbrQGjJ3tKqHXlH" %} [Setup EVM Account](/build/development-guide/smart-contracts/get-started-evm/evm-account) {% endcontent-ref %} {% content-ref url="/pages/-MS0Ru2tc4Kyqdwq\_NJi" %} [Queryable & Lightweight](/learn/acala-evm/acala-evm-composable-defi-stack/queryable-and-lightweight) {% endcontent-ref %} {% content-ref url="/pages/-MS0Ru\_iR5L28e6tRRwn" %} [Upgradable Contracts](/learn/acala-evm/acala-evm-composable-defi-stack/upgradable-contracts) {% endcontent-ref %} {% content-ref url="/pages/-MS0RuuDUNBuFePx1k0h" %} [Compatible Toolings](/learn/acala-evm/acala-evm-composable-defi-stack/compatible-toolings) {% endcontent-ref %} {% content-ref url="/pages/-MS0S\_RQ7GEHj83O0-Z\_" %} [No Dust Account](/learn/acala-evm/acala-evm-composable-defi-stack/no-dust-account) {% endcontent-ref %} # Composable DeFi Stack ### **Fully Composable DeFi Primitives in EVM and Runtime** Smart Contract Dapps deployed in Acala EVM can directly use native and cross-chain assets such as DOT, ACA, aUSD, renBTC, etc. ERC-20 tokens deployed in EVM can also be made available at runtime level, to be listed in the DeX, or (by governance approval) to be used as fee tokens. Smart Contract Dapps can directly use Acala DeFi primitives (DeX, stablecoin lending, and liquid staking), bridges, oracle infrastructure, native and cross-chain liquidity to compose various interesting DeFi applications, such as lending, special-purpose DeX, financial products based on staking and more. The process is seamless for users and developers, but behind the scene native tokens and protocols (aka runtime modules) are made available in EVM in the form of precompiled contracts. A transaction initiated by a smart contract in EVM is translated into a Substrate transaction and signed by any Polkadot extensions using polkadot.js. The response will be processed by the SDK ([bodhi.js](https://github.com/AcalaNetwork/bodhi.js)) and converted into an Ethereum compatible format. ### Available Composable Contracts These pre-compiled contracts are now made available to Acala EVM * **Native and cross-chain tokens available in ERC20**: DOT, ACA, aUSD, XBTC, LDOT, RENBTC. Try it [here](/build/development-guide/smart-contracts/advanced/use-native-tokens). * Oracle contract to get price feed: this exposes the [Open Oracle Gateway](/learn/acala-introduction#open-oracle-gateway) functionalities such as guaranteed Quality of Service. Try it [here](https://wiki.acala.network/build/development-guide/smart-contracts/advanced/use-oracle-feeds). * On-chain auto-scheduler that enables use cases like subscriptions and recurring payments etc. Try it [here](/build/development-guide/smart-contracts/advanced/use-on-chain-scheduler). * Advanced contract deployment features like state renting to avoid scams and wastage of on-chain resources. * More to come: we're gradually exposing more native functionalities to the Acala EVM, next to come is the DeFi primitives (DeX, stablecoin lending, and liquid staking). Find out more on these contracts [here](https://github.com/AcalaNetwork/predeploy-contracts#predeployed-system-contract). # Flexible Fees ## **Pay Gas Fees in Virtually Any Token** With the Acala EVM, fees can be paid in any accepted tokens, such as ACA, aUSD, DOT, and wrapped BTC. More tokens can be supported as native fee tokens with a simple governance approval. Behind the scenes, Acala DEX is being used as a unified liquidity pool for settling the fees into the network token, but the experience is completely transparent to users and developers. # EVM Account ## **Single Wallet, Single Account Experience** Users can use **one extension/wallet**, and **a single Substrate account** to interact with the Substrate runtime, contracts in EVM, and wasm contracts or a hybrid of these. If a user wants to use a particular Ethereum address, then simply link it with his/her Substrate address (basically proving the user owns both addresses), thereafter the user can just use the Substrate account with [Polkadot{js} extension](https://wiki.polkadot.network/docs/en/learn-account-generation) or alike to sign any Ethereum transactions seamlessly. This allows users to use all functionalities within Acala and cross-chain capabilities without managing multiple accounts or wallets. {% content-ref url="/pages/-MS0RtbrQGjJ3tKqHXlH" %} [Setup EVM Account](/build/development-guide/smart-contracts/get-started-evm/evm-account) {% endcontent-ref %} # On-chain Scheduler ## **On-chain Automatic Scheduler** On Ethereum and most other EVM platforms, there is no way to automatically schedule a transaction natively. This means many useful and perhaps essential financial services that we take for granted today, such as subscription, are not possible. On Acala and Substrate, the automatic scheduler is a native feature of the blockchain. It is now made available in the Acala EVM in the form of pre-compiled contracts that any smart contract can call upon. This will enable a wide range of use cases such as automatic and recurring payment rails, subscription services such as a Web3 version of Stripe, automatic profit-taking, reinvestment mechanisms, and a means to liquidate risky positions without external actors like keepers. Try the auto-scheduler contract [here](/build/development-guide/smart-contracts/advanced/use-on-chain-scheduler). # Queryable & Lightweight ### **Keep Nodes Lightweight while Queryable** We retain the standard Substrate node which is lightweight and easily maintainable. For querying transactions and event logs, we offer an indexer node that is open-sourced and anyone can run a copy of it like a full-node. For convenience, we’d offer one docker image to run both nodes, but it is important that there’s a choice for people who want to run one or another for their purposes. # Upgradable Contracts ### **Upgradeable Smart Contracts.** In Acala EVM, developers no longer need to write complex migration contracts to fix bugs or make improvements to existing applications. The contract maintainer can simply send a transaction with the new contract byte-code to seamlessly upgrade the contracts, without the need to `migrate` users nor liquidity. There’s also a two-staged deployment process to reduce the risk of directly testing on mainnet with the public. * **Deployed Private Contract**: Once a contract is deployed, it is by default private to the public and visible only to the `Contract Maintainer` (who deployed the contract) and opt-in developers. All necessary testing and final verification can be done before making it public. `Contract Maintainer` can also remove the contract at this stage if needed. * **Deployed Public Contract**: `Contract Maintainer` can make the contract public aka open business to the public. To incentivize users to be mindful of acquiring storage on a public ledger, and also in effect to reduce scams, we use `State Renting` mechanism. `Contract Maintainer` is required to put up a bond when deploying a contract, which will be refunded when the contract is removed from the chain. Some barriers of entry would encourage more responsible behaviors, and we are constantly researching the space for better mechanisms to achieve this. # Compatible Toolings ### **Compatible Developer Tooling** Acala EVM enables developers to develop, test and deploy DApps with existing tooling support, such as [Remix](https://remix.ethereum.org/) and [Waffle](https://getwaffle.io/). More toolchains will be added as we progress. Existing Solidity DApps and node.js applications can communicate with Acala nodes with minimum changes. Developers can use Acala’s web3 provider [bodhi.js](https://github.com/AcalaNetwork/bodhi.js) to interact with an Acala node seamlessly. # No Dust Account ### **Avoid Dust Accounts** Dust accounts are accounts with very little funds, generally less than the amount needed to conduct a transaction. Too many dust accounts add unnecessary data to the blockchain, which would make it difficult for full nodes to sync with the network (since every full node has a complete copy of the blockchain). On the Acala network, an address is only active when it holds a minimum amount (exact number TBD). This minimum amount is called “Existential Deposit” (ED), similar to [ED on Polkadot](https://support.polkadot.network/support/solutions/articles/65000168651-what-is-the-existential-deposit-#:~:text=On%20the%20Polkadot%20network%2C%20an,needed%20to%20conduct%20a%20transaction.). All native tokens e.g. DOT, ACA, aUSD, BTC etc. would have this feature, but it is not enforced upon ERC-20 tokens in the EVM. # How does it work? ## The Stack Project Bodhi is Acala’s answer to composable EVM compatibility. ![](https://i.imgur.com/gYegu9s.png) Instead of emulating the full Ethereum RPC node ([Frontier](https://github.com/paritytech/frontier) approach), we emulate the Ethereum JavaScript SDK client experience (by implementing a web3 provider as Bodhi.js). This initiative has received an Open Grant from Web3 Foundation and is under development. Read more [here](https://github.com/AcalaNetwork/Open-Grants-Program/blob/master/applications/project_bodhi.md). ## Get Started Try out Acala EVM [here](/build/development-guide/smart-contracts/get-started-evm). # Acala Network **Acala Network** * [Set up Wallet & Accounts](/get-started/acala-network/acala-account) * [Bridge DOT to Acala](/get-started/acala-network/acalas-dot-bridge) * [Acala Web App](https://apps.acala.network/) * [Acala Mobile](https://polkawallet.io/) * [Acala Web App Guide](https://guide.acalaapps.wiki/) # Acala Launch Phases Acala network has a phased launch plan. Keep up-to-date with the roll-out plan by viewing this [live roadmap](https://aca.la/acala-roadmap). **Current Phase: Win Acala Parachain Slot Auction - Acala Genesis Launch** ## 🚀 (Done) Acala Genesis - Launch The Genesis block of the Acala network will be launched on 18th December, 2021, as a Proof of Authority network. Governance was restricted to a single super-user (sudo) key, which is held by the Acala Foundation to issue transactions and upgrades to resolve issues and completes the launch process. Since genesis, Acala's network security is provided by Polkadot's Nominated Proof of Stake (NPoS) Validators upon launch. Acala's Collators will be provided by node service partners at this stage. **Acala parachain is available on** [**Subscan**](https://acala.subscan.io) **&** [**Polkadot App**](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Facala.api.onfinality.io%2Fpublic-ws#/explorer)**.** ## 🏒 (Done) **Finalize ACA Distribution** **You can view ACA distributions are available** [**here**](https://distribution.acala.network)**.** * [x] Airdrops * [x] Build Acala #1 * [x] Build Acala #2 * [x] Acala crowdloan * [x] Others ## 🕵️ (Done) Tech Verification & Runtime Upgrade Acala will perform a set of tests and verifications to ensure the network is operational. * [x] Collators are producing blocks as expected * [x] Polkadot is verifying blocks from Acala as expected * [x] Runtime upgrade to fix any issues * [x] Block time is stable * [x] p2p connectivity is good * [x] RPC node availability is good ## 🤹 (Done) Enable DOT Transfer from Polkadot to Acala Transfer DOT from Polkadot Relay Chain to Acala parachain and back via **xtoken** will be enabled. However, transfer within the Acala parachain will still be disabled at this stage. Read the how-to [here](https://github.com/AcalaNetwork/acala-wiki/blob/master/acala/defi-hub/inter-polkadot-transfer.md). ## 🏵 (Done) Upgrade to Support LCDOT ## 🎯 (Done) Distribute ACA & LCDOT Batch distribution of ACA & LCDOT to * [x] Airdrops to pre-ACA holders * [x] Build Acala Participants * [x] Crowdloan Participants via Acala Website, Polkawallet and partner exchanges. * [x] Other round participants If you have participated via exchanges or custodial agencies, the rewards will be distributed to you by these exchange and custodial agencies. Please contact them directly for the distribution schedule. ## 🎁 (Done) Claim ACA & LCDOT **You can check whether your ACA rewards need to be claimed** [**here**](https://github.com/AcalaNetwork/acala-wiki/blob/master/acala/crowdloan/claim-aca.md)**.** If you have participated via exchanges or custodial agencies, the rewards will be distributed to you by these exchange and custodial agencies. Please contact them directly for the distribution schedule. If you participated in Acala\*\* **crowdloan via the** \*\*Polkadot web app directly, or via non-custodial wallets other than Polkawallet and Fearless wallet, you will need to agree to our T\&C by completing a claim process for ACA. The Claim ACA website can be found [here](https://distribution.acala.network/claim). ## 🎒 (Done) Collator Onboarding ## 🎁 (Done) DOT Treasury Donation Ceremony ## ✋ (Done) Council Governance + Democracy After the chain has been running stably with the collator set, the sudo key will perform a runtime upgrade and enable appointed Councilors and democracy. Other councils including Financial Council, Technical Council, and Liquid Staking Council, as well as public referenda will also be enabled. Read more [here](https://github.com/AcalaNetwork/acala-wiki/blob/master/acala/get-started/governance/participate-in-democracy.md). ## 🗳️ (Done) Enable Democracy Once the chain has been running well under Elected Council, it will propose to enable democracy - public referenda. Enable public referenda so that anyone can propose a referendum by depositing the minimum amount of tokens for a certain period. ## 💥 (Done) Remove Sudo Sudo module will be removed via a runtime upgrade, and the Acala network will be governed by on-chain governance and token holders hereafter. ## 🚃 (Done) Enable Balance Transfers Balance transfers within the Acala network are restricted until this point. ## 👩‍🌾 (Done) Enable Primitive Protocols * [x] Enable Stablecoin * [x] Enable Swap * [x] Enable Liquid Staking ## 🚜 (Done) Bootstrap Plan & Sequence Details of launching specific collaterals and liquidity pools, as well as associated bootstrap programs will be announced separately. ## 🤖 (Done) Enable EVM+ # Wallet & Account This document covers the basics of Acala, Karura, Polkadot and Kusama account addresses. ## Address Format Acala and Karura use the Substrate-based chain address format SS58. Read more [here](https://wiki.polkadot.network/docs/en/learn-accounts). * Acala addresses usually but not always start with the number 2. * Karura addresses could start with a small letter like l, r, p, q, o... * Polkadot addresses always start with the number 1. * Kusama addresses always start with a capital letter like C, D, F, G, H, J... * Generic Substrate addresses start with 5. ## Existential Deposit Karura uses an [*existential deposit* (ED)](https://wiki.polkadot.network/docs/learn-accounts#existential-deposit-and-reaping) to prevent dust accounts from bloating state. If an account drops below the ED, the state of this account will be removed from the blockchain to preserve scarce on-chain storage resources. The balance on this account will be removed and donated to the Treasury. You still retain access to the account, but it no longer has an on-chains state. **Transfers:** when you transfer an amount from account A to account B * if after the transfer, account A's balance is below ED, it will be removed. So make sure to leave enough balance on account A to keep it alive. * if account B has no balance, and the transfer amount is below ED, account B would be as if never receive any amount, because its state would be removed from the chain. So make sure to send enough amount to keep a fresh account alive. **Swap**: when you swap token A for token B, if token A balance then falls below ED requirement, then the transaction might fail. Anyone can build a front-end using acala.js SDK to facilitate this transaction and check ED for you, but you shall always be aware of it. **Claim rewards**: when claiming LP tokens or other rewards, if the balance is below ED requirement after the claim, then the balance might be wiped. ED applies to all supported token accounts, and each type of token account e.g. DOT account has its own ED requirement, meaning if DOT account balance is lower than ED, then your DOT balance may get wiped, while all other balances won't be affected. Any transactions that change the balance of a particular token e.g. swap, then you shall be aware of its ED requirement. Here's the list of ED requirements for currently available tokens on Karura: * ACA ED: 0.1 ACA * aUSD ED: 0.1 aUSD * DOT ED: 0.01 DOT * LDOT ED: 0.05 LDOT You can verify the existential deposit of ACA by checking the chain state for the constant `balances.existentialDeposit` ([ED Runtime Code](https://github.com/AcalaNetwork/Acala/blob/35078ea2b2d0e3a3937a075c54d94c77faea2f36/runtime/acala/src/lib.rs#L752-L754)) ([ED SDK](https://github.com/AcalaNetwork/acala.js/blob/master/packages/sdk-wallet/src/utils/get-existential-deposit-config.ts)) ## Account Generation You can generate Acala and Karura account in the following ways: * Polkadot{.js} Browser Extension * Polkawallet Mobile App * Ledger Hardware Wallet # Account Generation You can generate Acala and Karura account in the following ways: * [Polkadot{.js} Browser Extension](/get-started/get-started/karura-account/account-generation/polkadot-.js-browser-extension) * [Polkawallet Mobile App](/get-started/get-started/karura-account/account-generation/polkawallet-mobile-app) * Talisman Wallet [install](https://docs.talisman.xyz/talisman/navigating-the-paraverse/account-management/download-the-extension), [create new wallet](https://docs.talisman.xyz/talisman/navigating-the-paraverse/account-management/create-a-talisman-wallet) * SubWallet [install](https://docs.subwallet.app/main/extension-user-guide/getting-started/install-subwallet), [create new wallet](https://docs.subwallet.app/main/extension-user-guide/account-management/create-a-new-account-with-seed-phrase) * [Ledger Hardware Wallet](/get-started/acala-network/acala-account/account-generation/ledger-hardware-wallet) # Polkadot{.js} Browser Extension ### Install the Browser Extension The browser extension 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). Download the plugins [here](https://polkadot.js.org/extension/). ![](/files/-M_dCLYCSww-lIL9hYYX) ### 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 not unlike the one below ![](/files/-M_dD50MlKV95MR4yG4t) Click the big plus button or select "Create new account" from the small plus icon in the top right. 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. ![](/files/-M_dDK3C-NtFvAMNwiSt) You should back up these words as [explained here](https://wiki.polkadot.network/docs/en/learn-account-generation#storing-your-key-safely). It is imperative to 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". ### Name Account & Password The account name is arbitrary and for your use only. 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. 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. ![](/files/-M_dDr2uh8p2z6RRpQYf) ### Set Address for Acala Mainnet Now we will ensure that the addresses are displayed as Acala mainnet addresses. Click on "Options" at the top-right corner of the plugin window, and under "Display address format for" select "Acala". **Your address's format is only visual** - the data used to derive this representation of your address are the same, so **you can use the same address on multiple chains**. You can copy your address by clicking on the account's icon. ![](/files/-M_dEaN0F2NnxThLxNu-) ### Set Address for Karura Mainnet Click on "Options" at the top-right corner of the plugin window, and under "Display address format for" select "Karura". **Your address's format is only visual** - the data used to derive this representation of your address are the same, so **you can use the same address on multiple chains**. You can copy your address by clicking on the account's icon. ![](/files/-MbdRZuBQFh3CP9oYLi9) ### Set Address for Polkadot Mainnet Click on "Options" at the top-right corner of the plugin window, and under "Display address format for" select "Polkadot". **Your address's format is only visual** - the data used to derive this representation of your address are the same, so **you can use the same address on multiple chains**. You can copy your address by clicking on the account's icon. ![](/files/-M_lzxaAC_H6sfIeMChL) ### Set Address for Kusama Mainnet Click on "Options" at the top of the plugin window, and under "Display address format for" select "Kusama". **Your address's format is only visual** - the data used to derive this representation of your address are the same, so **you can use the same address on multiple chains**. You can copy your address by clicking on the account's icon. ![](/files/-M_m-313S-tBRN22FXN1) ### Convert Address for different chain formats You can use the [Subscan Address Transform tool](https://polkadot.subscan.io/tools/ss58_transform) to convert your address between the different chain formats. Enter any address in the input box on the left-hand side, then click **`Transform`** button, you can see address formats for all chains on the right-hand side. # Polkawallet Mobile App ## I**nstall Polkawallet App** Download the Polkawallet app via [its official website](https://polkawallet.io/). The app is available through the Apple App Store for iOS devices, Google Play for Android devices, and as Android APK. ### Create Account 1. Click on the "Create Account" button. ![](https://lh5.googleusercontent.com/VaB4EcpFPO9Qmvl2K_MVKk8rVevhEzDsD45WZzkWKe3B6DXyoSU8-IenMk3slTe4uGLVl4IzAEmOz-A0SyJ508VUy49UfiGpsBT5R7q2QRmeybP1cE-2fU52iOdoudgcdmsLv_Kl) 2\. A new screen will appear explaining the importance of recording your mnemonic phrase in a safe place. Click the "Next" button. ![](https://lh6.googleusercontent.com/509_xAUccOu0djt4YJZsvrLW4H_fdBxmOmMMwpRrseGSt9xcyZdx4Tgge7ZofXk6um7rSR6LcPL7c23rJHF2ZHv7FlLl2SbYciqd3-ck_v_hlco0RRP7oPpin90nv2YETvvN_cEb) ‌3. Your mnemonic phrase will appear. Write the mnemonic on a piece of paper and store it somewhere safe. Click on the "Next" button. ![](https://lh5.googleusercontent.com/XD1NG32OkmzZYToN8Fb-noLzUJmacWIACYhi-gSyV3-s58n4Ovu6sS0qQMRe1NkMMyLA4LBz_wEHRnEDwVnQgEaXQwCrgvUr0fNvA8SDilS7mrrnP--9bx3-SnHaioy_prFD4KoE) 4\. Confirm your mnemonic by entering the words in the correct order. Click on the "Next" button when completed. ![](https://lh4.googleusercontent.com/ROVs8A4woJy9RYKmsGd6Jm1W8GMzG_cpB6ba3XLViS18GMTmRK0giSV7qkDh2XZrKxxLv4LFLEFuiRT6Lw3wri8yu6cT9tBMyw00vMhxq5Vmwb2qBOUg9-Eey7RHMbh4araqvk7P) ### **Name Account & Password** Name your account and create a strong password (at least 6 characters). Click on the "Next" button when completed. ![](https://lh4.googleusercontent.com/PWXIJxAuCBlb-QGBrpce0gvFgG_C_jWUL125eOU_ke_thRY4WDhUq1AvDa6bAWHWy_sD5BXp40gM5zzJRdkDGF5XrtLEuLD5TwJ1sV8FDdjr1QRjDm9I-hzfXGsqBLsq0QVFgb02) Your wallet is now set up! The screen will default to the Polkadot network. You can determine which network you're connected to by looking at the grey text under the account name. In the case of this screenshot, it says "Polkadot." ![](https://lh5.googleusercontent.com/xlFLRGhSFMpRc1QeJrObC8vazj7YCLIe2AvW-euSwN4bvjlZWhTbcyBxF4SPTXQGuOCJtdxMW_1IMNyoL88RzC51RGN7CkLepjjOXTnJkEkp0ZSRzS58F7rAVMamcuXJ_01S6AhE) ### Set Address for Polkadot Mainnet 1. Click the menu button on the top-right corner. 2\. In the opened menu select the Polkadot logo, then press on the appeared address on the main screen. ### Set Address for Kusama Mainnet 1. Click the menu button on the top-right corner. 2. In the opened menu select the Kusama logo, then press on the appeared address on the main screen. ### Set Address for Acala Mainnet (Coming Soon) ### Set Address for Karura Mainnet (Coming Soon) # Ledger Hardware Wallet Following steps from this article, you will be able to access Acala account on Ledger Hardware Wallet via Polkadot{.js} web wallet, as well as interacting with the account with Acala App through Polkadot{.js} browser extension. When using Ledger devices, always ensure you are using the latest version of Acala App, Ledger Live, and firmware on your Ledger device. ### Step 1 - Install Acala App on your Ledger Hardware Wallet 1. **Connect** and **unlock** your Ledger device on your computer 2. Open **Ledger Live**, follow on screen instruction to allow access on your Ledger device 3. In **My Ledger, s**earch for **Acala** then click **Install** 4. Proceed to Step 2 below ### Step 2 - Add your Acala Account on Ledger Hardware Wallet on Polkadot{.js} Note: please add the account using Polkadot{.js} on web, do not use Polkadot.js browser extension to perform this step (it will be Step 3 below). 1. **Connect** and **unlock** your Ledger device on your computer, **open** the **Acala App** on your Ledger device 2. On your browser, **go to** [Polkadot.js Web Wallet](https://polkadot.js.org/)\ Note: Use the same browser with Polkadot.js browser extension installed if you would like to access this account with Acala apps, **click** on either the **apps wallet (hosted)** or **apps wallet (ipfs)** tile 3. **Switch** to **Acala** network 3.1. \*\*\*\* Clicking on top left corner of the site\ ![](/files/kKta8eRxY388FRRysX8o) 3.2. **Click** and expand **Polkadot & Parachains** then **select** **Acala** via any of the RPCs listed and **click Switch**\ ![](/files/GIojJYj5KY3ZH5HIQSBc) 4. **Go** to Settings\*\*, click\*\* manage hardware connection\*\*,\*\* and **select**:\ 4.1. **Attach Ledger via WebHID** if you are on macOS or Linux.\ 4.2. A**ttach Ledger via WebUSB** if you are on Windows.\ 4.3. **Click** Save 5. **Go** to Accounts - Accounts via the top menu\ 5.1. Select **Add via Ledger**\ \*\*\*\*5.2. Input a name for the account\ 5.3. Select the Ledger Device connected if prompted\ 5.4. Done ### Step 3 - Add your Acala Account on Ledger Hardware Wallet on Polkadot{.js} Browser Extension 1. **Click** on Polkadot.js browser extension, **click** + then **click** "Attach Ledger Account to add an account\ \ ![](/files/ONArHxrFiBV9KYR3VRwd) 2. **Select** Acala\ ![](/files/kmbsnPBqmVaqbhsEz9ZM) 3. **Input** name of the account and **click** Import 4. Done, and now you can interact with Acala account on Ledger account, with Acala apps through Polkadot.js browser extension. # Exchange Withdraw/Deposit #### DOT **withdraw/deposit to/from Acala network** ⚠️ **NOT All Exchanges support direct withdraw/deposit DOT to/from Acala network.** Please do Do NOT transfer DOT to an exchange address on Acala App except for the ones listed below as they become available. Exchanges that support direct withdraw/deposit DOT to/from Acala Network: Unless DOT on Acala is explicitly supported by Exchange, please withdraw/transfer by withdraw/transfer to Polkadot then bridge to Acala using Acala App. #### ACA Withdraw/Deposit Exchanges that support the Acala network and the ACA token would support direct withdraw/deposit ACA to/from Acala network. Please do confirm with your exchange. Always send a small amount to verify before sending the full amount. #### Other Tokens on Acala By default Exchanges do NOT automatically support direct withdraw/deposit new tokens on Acala network, e.g. LCDOT. We will update the status of support as we progress.
# Balance Type and Vesting ## Balance Types On Acala there are the following steps balance types * **Transferrable Balance**: as the name suggests, this balance can be used for transfers, paying fees and performing any actions on-chain. * **Locked Balance:** this balance is frozen, depending on the scheme, it could be locked for a certain period of time before being transferrable, or it could be vested where a portion of the balance gradually becomes transferrable, or a combination of these. The tokens are released lazily, meaning you are required to perform a `claim` transaction to obtain it. The guide for claiming vested tokens is in the next section. * **Total Balance:** is the sum of transferrable balance plus the locked balance. The entire balance can be used for governance operations such as voting. ## Check & Claim Vested Tokens ### Claiming Vested ACA via Web App You can claim your vested ACA here ### Claiming Vested ACA **Even though tokens may be vested (unlocked), you will still need to claim them before you can transfer them or use them in DeFi applications on the Acala platform.** You can learn how to claim your tokens by following the guide below: 1\) Go to your Polkadot.js **extension** and make sure it is set to `allow use on any chain`. ![](/files/UCcQWEbIojrxPPCJeyHs) 2\) Go to [Polkadot JS Apps](https://polkadot.js.org/apps/#/explorer) and connect to the Acala network. You can do this by clicking on the dropdown box in the upper left hand corner (shown below). ![](/files/eTRyDLGDTTQU02i00J9l) 3\) Select an Acala node (any is fine) and click `Switch`. ![](/files/iTyaoRZfi3ef3L25xkTW) 4\) Select `Accounts`. You should see your ACA amount. You can expand the balance in your account to see if there's a vested (locked) balance. If there's one, it will be displayed. ![](/files/xQx3BWa7VPhkpm7zyreE) Go to the `Developer - Extrinsics` section, use the account that you want to claim the vested balance. Select `vesting` then `claim()` in the `submit the following extrinsics` field, then click the `Submit Transaction` button to complete the process. ![](/files/hbc7bJqkd8J0Q2D8nBEO) ### Claiming Vested ACA for Other Accounts Users can also claim vested ACA for other accounts by going to the `Developer - Extrinsics` section. Select the account you'd like to use to initiate the claim in `using the selected account`. Submit the `vesting` then `claimFor(dest)` extrinsic and the account you'd like to claim **for** which is the account that has the locked tokens (shown at bottom of screenshot). Note that submitting this transaction only makes the vested tokens transferrable. It does not transfer them to the account that initiates the claim. ![](/files/u8wpQm9pO8up9MHJEIg1) ### Check Vesting Go to the `Developer - Chain state` section, select `vesting` then `vestingSchedules()` , then select your account, then click the `+` button to see what vesting schedule it has. ![](/files/MI8fy73D6wvdSfyMmRJi) Below is an example result * `start`: the tokens are locked until **Polkadot block #** * `period`: release period e.g. release every block or every 432,000 block as in the example * `periodCount`: how many vesting periods * `perPeriod`: how much to release each period ``` [ { start: 13,795,200 period: 432,000 periodCount: 12 perPeriod: 100 ACA } ] ``` # Check Address for Different Chains If you already set up a Polkadot account, Acala account, or any Substrate-based chain account, there are two options to check the corresponding DOT address: * you can use [Subscan Address Transform](https://acala-testnet.subscan.io/tools/ss58_transform); * setting your wallets in polkadot.js extension * use PolkaWallet mobile app ## Using Subscan transform 1. Navigate to [Subscan Address Transform](https://acala-testnet.subscan.io/tools/ss58_transform) and paste your existing account address into "Input Account or Public Key". ![](https://i.imgur.com/v7damrj.png) 1. Press "Transform" and find the corresponding Polkadot address in the appeared list on the right (in the screenshot, it is second from the top). ![](https://i.imgur.com/bv0T6dD.png) ## Using Polkadot.js extension 1. Open polkadot.js extension in your browser and press 3 dots on the right from your account name. 2. In the opened window click on the dropdown menu and pick "Polkadot Relay Chain" ![](https://i.imgur.com/GxbRxhs.jpg) 3. Now all your accounts are converted to Polkadot format, you can copy them. ## Using Polkawallet 1. Open PolkaWallet on your mobile device and click the menu button on the top-right corner. ![](https://i.imgur.com/JwPrsVe.jpg%20=250x) 2. In the opened menu select Polkadot logo (second from the top) and press on the appeared address on the main screen. 3. ![](https://i.imgur.com/YGx8nne.jpg%20=250x) 4. Click on the account block under the "Add Account" button, which will navigate you back to the main page. ![](https://i.imgur.com/JwPrsVe.jpg%20=250x) 5. Now your wallet is set up and you can copy your Polkadot address. You can see that your wallet changed color to black and among your assets you can see DOT. # Acala's DOT Bridge ### Background As the DeFi Hub of Polkadot, Acala is building financial infrastructures and an ecosystem around DOT. Acala has been taking a phased launch approach to account for any technical dependencies on Polkadot. One of these dependencies is the XCM Bridge Infrastructure, a component of the Polkadot ecosystem that enables Cross-Consensus Communication between parachains. While the development of XCM is near completion, it’s expected that it will take an indeterminate amount of time to appropriately test and deploy for the broader ecosystem. To provide an answer to the desire from the community for DOT liquidity on Acala, we are pleased to announce an interim non-custodial bridge solution to support DOT transfers to Acala, endorsed by Parity. While it is a limited one-direction DOT bridge that enables transferring DOT from Polkadot to Acala, once XCM is available on Polkadot, it will be seamlessly upgraded to use XCM with no migration required for DOT holders. Note: Regarding DOT withdrawal from Acala, please refer to [Exchange Withdraw/Deposit](/get-started/acala-network/acala-account/exchange-withdraw-deposit). ### What is the Acala's DOT Bridge The DOT bridge is Acala's solution which: * is a non-custodial bridge DOT from Polkadot to Acala * enables a path for users with DOT to participate in Acala's DeFi economy * is seamlessly upgradeable to Polkadot's [XCM](https://polkadot.network/blog/xcm-the-cross-consensus-message-format/) when it becomes available. No migration or extra actions required for DOT holders. ### Before you start You should be aware of some limitations in using Acala's DOT Bridge: * bringing DOT from Polkadot to Acala is one-way, currently there is no way to bridge the DOT back - until Polkadot's XCM mentioned above becomes available, or until direct DOT withdraw and deposit from/to Exchanges become available * it only works for DOT, not any other tokens or assets * DOT transfers over 5,000 DOT will require approval as an extra security protection, which will take up to 24 hours to process ### How to use the Bridge? If you read the above and would like to action, welcome to the Acala world! You will find a step by step guide [here](https://guide.acalaapps.wiki/general/bringing-tokens-to-karura/sending-dot-to-acala). # Acala Assets These are native assets on the Acala Network * **Acala Token (ACA)** | Decimal Place: 12\ ERC20 mirrored token address 0x0000000000000000000100000000000000000000 * **Acala Dollar (aUSD)** | Decimal Place: 12\ ERC20 mirrored token address 0x0000000000000000000100000000000000000001 * **Liquid Staking DOT (LDOT)** | Decimal Place: 10\ ERC20 mirrored token address 0x0000000000000000000100000000000000000003 * **Liquid Crowdloan DOT (LCDOT)** | Decimal Place: 10\ ERC20 mirrored token address 0x000000000000000000040000000000000000000d * **Polkadot DOT (DOT)** | Decimal Place: 10\ ERC20 mirrored token address 0x0000000000000000000100000000000000000002 ### On-Chain Metadata {% embed url="" %} # Governance Read Governance overview [here](/learn/governance-overview). Below are governance discussion and proposal avenues: * [Acala Subsquare - Discussion & View related on-chain Proposal](https://acala.subsquare.io/) * [Polkadot Web App - On-chain Voting](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Facala-rpc-0.aca-api.network#/extrinsics) * [Acala Discourse Forum - long form, informal discussions](http://forum.acala.network) ## Governance Parameters These are important governance parameters, which may change over time as we progress through the governance phases. * Launch Period: Public referenda is every **5 days** * Voting Period: Votes are tallied every **5 days** * Emergency Voting Period: Voting period for fast-tracked emergency referendum is **3 Hours** * Minimum Deposit: Proposing a referendum requires a minimum deposit of **200 ACA** * Enactment Period: Minimum period for locking funds and the period between a proposal being approved and enacted is **2 days** * Cool-off Period: Vetoed proposal may not be re-submitted within **7 days** Most of these parameters are visible on the Polkadot App. You can also view upcoming governance events on `the Event Calendar` ![](/files/SH2HIPGK9Kth4uVpgpSr) ## Propose a Referendum A referendum consists of some action that you want to propose. If voted in by token holders, then the action will be enacted on-chain automatically. You are required to bond some tokens to propose an action. Once a proposal is submitted, it can not be canceled. On the [Polkadot Apps - Acala parachain](https://polkadot.js.org/apps/#/accounts), you can use the “Democracy” tab to make a new proposal. The action, such as 'force transfer balance from account A to account B', is encoded in a preimage, and the hash of the action is called preimage hash. Since the preimage can be quite large (hence costly to submit), you can submit a Proposal first which includes the preimage hash only, and submit the preimage (or have someone else submit it for you) later but before voting completes. ### Step 1: Submit a Proposal #### Get the preimage hash By clicking on the `Submit preimage` button, then fill in the action you want to propose, copy and note down the preimage hash `0xe2dafd2ace4fbc0b2f6d28f92db250d052975c704a16058b9d620a6a24800357`. Once you noted down the hash, you can now cancel the prompt. ![](/files/4D6zPe3FAvedsGLKAuFk) #### Submit a proposal Submit a proposal by clicking on the `Submit a proposal` button, and pasting in the preimage hash to submit it. Then the proposal shall appear in the proposal table. ### Step 2: Submit a Preimage Before voting of your proposal completes, you will need to submit the actual preimage. Otherwise, it cannot be enacted on-chain. You can repeat the ‘Submit a preimage’ process as previously mentioned, and click the ‘Submit preimage’ button to send the transaction. ## Vote on a Referenda To Vote on Referenda, you must hold KAR tokens and these tokens must be held in a wallet that has the functionality to participate in Democracy like Polkadot.js. If you don't have your tokens in Polkadot.js wallet, you can read more about [account generation](/get-started/acala-network/acala-account#account-generation). Once a proposal is in as a referendum, it will show up in the referenda table. You can navigate to the [Polkadot Apps - Acala Parachain Democracy](https://polkadot.js.org/apps/#/democracy) to cast your vote. ![](/files/jYXZaQ0yXVIh9jCaOWzP) You can click on the ‘Vote’ button to vote. Select "Vote Aye" to support the proposal, and select "Vote Nay" to disapprove the proposal. You can also increase your conviction with the same number of tokens by locking them. The longer you are willing to lock your tokens, the stronger your vote will be weighted. Read more on [voting](https://wiki.polkadot.network/docs/maintain-guides-democracy/#voting-on-a-proposal) and [tallying](https://wiki.polkadot.network/docs/learn-governance#tallying). ![](/files/xg985vjxTJaZqaJA1EFB) ## Unlock locked tokens You will need to explicitly unlock these tokens once the locking period ends. You can go to the `Accounts` page, click the menu button for the voted account, and select the menu item`Clear expired democracy locks` to claim it back. Read more [here](https://wiki.polkadot.network/docs/maintain-guides-democracy/#unlocking-locked-tokens). ### Check Locked Democracy Votes Go to `Developer` - `Chain state`, then select `democracy` and `locks`. Select the account used for voting in the dropdown, and click the `+` button to see whether there's locked votes, and if any how long they are locked for. ## Delegate Vote You can delegate your vote to others to vote on your behalf. On the [Polkadot Apps - Acala parachain](https://polkadot.js.org/apps/#/accounts), go to the `Developer` tab -- `Extrinsics` , then select `democracy.delegate` . ![](/files/5OpGq5iKmlvHHdG8qjis) # Karura Network Get Started **Karura Network** * [Set up Wallet & Accounts](/get-started/acala-network/acala-account) * [Bridge KSM to Karura](/get-started/get-started/inter-kusama-transfer) * [Karura Web App](https://apps.karura.network/) * [Karura Web App Guide](https://wiki.karura.app/) # Karura Launch Phases Karura network has a phased launch plan. Keep up-to-date with the roll-out plan by viewing this [live roadmap](https://aca.la/karura-roadmap). **Current Phase: Technical Verification & Runtime Upgrade** ## 🚀 (Done) Karura Genesis - Launch The Genesis block of the Karura network was launched on 23rd June, 2021, as a Proof of Authority network. Governance was restricted to a single super-user (sudo) key, which is held by the Acala Foundation to issue transactions and upgrades to resolve issues and completes the launch process. Since genesis, Karura's network security is provided by Kusama's Nominated Proof of Stake (NPoS) Validators upon launch. Karura's Collators will be provided by node service partners at this stage. **Karura parachain is available on** [**Subscan**](https://karura.subscan.io/) **&** [**Polkadot App**](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkarura.api.onfinality.io%2Fpublic-ws#/explorer)**.** ## 🏒 (Done) **Finalize KAR Distribution** **You can view KAR distributions are available** [**here**](https://distribution.acala.network/)**.** * [x] Testnet campaign rewards & airdrops * [x] "Build Acala #1" rewards * [x] Karura crowdloan * [x] Other events ## 🕵️ (Done) Tech Verification & Runtime Upgrade Karura will perform a set of tests and verifications to ensure the network is operational. * [x] Collators are producing blocks as expected * [x] Kusama is verifying blocks from Karura as expected * [x] Runtime upgrade to fix any issues * [x] Block time is stable * [x] p2p connectivity is good * [x] RPC node availability is good ## 🤹 (Done) Enable KSM Transfer from Kusama to Karura Transfer KSM from Kusama Relay Chain to Karura parachain and back via **xtoken** will be enabled. However, transfer within the Karura parachain will still be disabled at this stage. Read the how-to [here](/get-started/get-started/inter-kusama-transfer). ## 🎯 (Done) Distribute KAR Batch distribution of KAR to * [x] Testnet campaign rewards & airdrops * [x] "Build Acala #1" rewards * [x] Karura crowdloan participants * [x] Other events If you have participated via exchanges or custodial agencies, the rewards will be distributed to you by these exchange and custodial agencies. Please contact them directly for the distribution schedule. ## 🎁 (Done) Claim KAR **You can check whether your KAR rewards need to be claimed** [**here**](/crowdloans/crowdloan/claim-kar)**.** If you have participated via exchanges or custodial agencies, the rewards will be distributed to you by these exchange and custodial agencies. Please contact them directly for the distribution schedule. If you participated in Karura crowdloan via the Polkadot web app directly, or via non-custodial wallets other than Polkawallet and Fearless wallet, you will need to agree to our T\&C by completing a claim process for KAR. The Claim KAR website can be found [here](https://distribution.acala.network/claim). ## ✋ (Done) Council Governance + Democracy After the chain has been running stably with the collator set, the sudo key will perform a runtime upgrade and enable appointed Councilors and democracy. Other councils including Financial Council, Technical Council, and Liquid Staking Council, as well as public referenda will also be enabled. Read more [here](/learn/governance-overview/participate-in-democracy). ## 💥 (Done) Remove Sudo Sudo module will be removed via a runtime upgrade, and the Karura network will be governed by on-chain governance and token holders hereafter. ## 🚃 (Done) Enable Balance Transfers Balance transfers within the Karura network are restricted until this point. ## 👩‍🌾 (WIP) Core DeFi Functionalities More details will be provided as we launch each DeFi protocol. * [x] Karura DeX * [x] Enable DeX * [x] Enable KSM/KAR pair * [x] Start Bootstrap * [x] Trading begins * [x] KSM/kUSD pair * [x] Start Bootstrap * [x] Trading begins * [x] Start Liquidity Program * [x] KAR/kUSD pair * [x] LKSM/kUSD pair * [ ] ... * [x] kUSD Borrowing * [x] Enable kUSD stablecoin protocol * [x] Enable KSM collateral (capped) * [x] Enable LKSM collateral * [ ] ... * [x] Liquid KSM * [x] Enable "Canary" Liquid KSM * [x] mint LKSM - including withdrawal * [x] KSM staking reward accrues * [x] LKSM as collateral * [x] Liquid Staking upgrade * [ ] USDT * [ ] as collateral * [x] as trading pair * [x] Enable Acala EVM # Check Distribution Rewards to be distributed are all recorded on the [`Distribution Website`](https://distribution.acala.network) Most of the KAR rewards for Karura crowdloan event and Build Acala #1 have been distributed (except for the ones that need to be claimed). You can check your balances in the following ways: * on the [Polkadot Apps - Karura parachain - Accounts](https://polkadot.js.org/apps/#/accounts) (you need to switch to the Karura parachain under Kusama) OR * on [Karura Subscan explorer](https://karura.subscan.io/) * If you participated via exchanges, all participated exchange rewards have been distributed to them, so please contact them directly If your rewards are marked as `To be Claimed`, please [follow the guide here](/crowdloans/crowdloan/claim-kar) to claim. ## Check on Polkadot Apps Go to [Polkadot Apps - Karura parachain - Accounts](https://polkadot.js.org/apps/#/accounts), you need to switch to the Karura parachain and go to the Accounts page. ![](/files/-MeRL845bjQi0rowo3m2) Make sure your account in the Polkadot{js} extension is switched to **`Allow use on any chain`** ![](/files/-MeRMQNqWiiq9Y57wfYG) ## Check on Karura Subscan Explorer Go to the [Karura Subscan Explorer](https://karura.subscan.io/), and search your address to see details of balances. ![](/files/-MeRNii-8PFed34OJBsB) # Wallets & Account This document covers the basics of Acala, Karura, Polkadot and Kusama account addresses. ## Address Format Acala and Karura use the Substrate-based chain address format SS58. Read more [here](https://wiki.polkadot.network/docs/en/learn-accounts). * Acala addresses always start with the number 2. * Karura addresses could start with a small letter like l, r, p, q, o... * Polkadot addresses always start with the number 1. * Kusama addresses always start with a capital letter like C, D, F, G, H, J... * Generic Substrate addresses start with 5. ## Existential Deposit Karura uses an [*existential deposit* (ED)](https://wiki.polkadot.network/docs/learn-accounts#existential-deposit-and-reaping) to prevent dust accounts from bloating state. If an account drops below the ED, the state of this account will be removed from the blockchain to preserve scarce on-chain storage resources. The balance on this account will be removed and donated to the Treasury. You still retain access to the account, but it no longer has an on-chains state. **Transfers:** when you transfer an amount from account A to account B * if after the transfer, account A's balance is below ED, it will be removed. So make sure to leave enough balance on account A to keep it alive. * if account B has no balance, and the transfer amount is below ED, account B would be as if never receive any amount, because its state would be removed from the chain. So make sure to send enough amount to keep a fresh account alive. **Swap**: when you swap token A for token B, if token A balance then falls below ED requirement, then the transaction might fail. Anyone can build a front-end using acala.js SDK to facilitate this transaction and check ED for you, but you shall always be aware of it. **Claim rewards**: when claiming LP tokens or other rewards, if the balance is below ED requirement after the claim, then the balance might be wiped. ED applies to all supported token accounts, and each type of token account e.g. KSM account has its own ED requirement, meaning if KSM account balance is lower than ED, then your KSM balance may get wiped, while all other balances won't be affected. Any transactions that change the balance of a particular token e.g. swap, then you shall be aware of its ED requirement. Here's the list of ED requirements for currently available tokens on Karura: * KAR ED: 0.1 KAR * kUSD ED: 0.01 kUSD * KSM ED: 0.0001 KSM * LKSM ED: 0.0001 LKSM ([Source code](https://github.com/AcalaNetwork/Acala/blob/0411433ee03c8a9efdc16c2b6014bd0c120f12d4/runtime/karura/src/lib.rs#L747-L751))\
## Account Generation You can generate Acala and Karura account in the following ways: * Polkadot{.js} Browser Extension * Polkawallet Mobile App * Ledger Hardware Wallet ###
# Account Generation You can generate Acala and Karura account in the following ways: * [Polkadot{.js} Browser Extension](/get-started/acala-network/acala-account/account-generation/polkadot-.js-browser-extension) * [Polkawallet Mobile App](/get-started/acala-network/acala-account/account-generation/polkawallet-mobile-app) * Talisman Wallet [install](https://docs.talisman.xyz/talisman/navigating-the-paraverse/account-management/download-the-extension), [create new wallet](https://docs.talisman.xyz/talisman/navigating-the-paraverse/account-management/create-a-talisman-wallet) * SubWallet [install](https://docs.subwallet.app/main/extension-user-guide/getting-started/install-subwallet), [create new wallet](https://docs.subwallet.app/main/extension-user-guide/account-management/create-a-new-account-with-seed-phrase) * [Ledger Hardware Wallet](/get-started/get-started/karura-account/account-generation/ledger-hardware-wallet) # Polkadot{.js} Browser Extension ## Polkadot{.js} Browser Extension ### Install the Browser Extension The browser extension 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). Download the extension [here](https://polkadot.js.org/extension/). ![](/files/-M_dCLYCSww-lIL9hYYX) ### 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 not unlike the one below ![](/files/-M_dD50MlKV95MR4yG4t) Click the big plus button or select "Create new account" from the small plus icon in the top right. 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. ![](/files/-M_dDK3C-NtFvAMNwiSt) You should back up these words as [explained here](https://wiki.polkadot.network/docs/en/learn-account-generation#storing-your-key-safely). It is imperative to 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". ### Name Account & Password The account name is arbitrary and for your use only. 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. 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. ![](/files/-M_dDr2uh8p2z6RRpQYf) ### Set Address for Acala Mainnet Now we will ensure that the addresses are displayed as Acala mainnet addresses. Click on "Options" at the top-right corner of the plugin window, and under "Display address format for" select "Acala". **Your address's format is only visual** - the data used to derive this representation of your address are the same, so **you can use the same address on multiple chains**. You can copy your address by clicking on the account's icon. ![](/files/-M_dEaN0F2NnxThLxNu-) ### Set Address for Karura Mainnet Click on "Options" at the top-right corner of the plugin window, and under "Display address format for" select "Karura". **Your address's format is only visual** - the data used to derive this representation of your address are the same, so **you can use the same address on multiple chains**. You can copy your address by clicking on the account's icon. ![](/files/-MbdRZuBQFh3CP9oYLi9) ### Set Address for Polkadot Mainnet Click on "Options" at the top-right corner of the plugin window, and under "Display address format for" select "Polkadot". **Your address's format is only visual** - the data used to derive this representation of your address are the same, so **you can use the same address on multiple chains**. You can copy your address by clicking on the account's icon. ![](/files/-M_lzxaAC_H6sfIeMChL) ### Set Address for Kusama Mainnet Click on "Options" at the top of the plugin window, and under "Display address format for" select "Kusama". **Your address's format is only visual** - the data used to derive this representation of your address are the same, so **you can use the same address on multiple chains**. You can copy your address by clicking on the account's icon. ![](/files/-M_m-313S-tBRN22FXN1) ### Convert Address for different chain formats You can use the [Subscan Address Transform tool](https://polkadot.subscan.io/tools/ss58_transform) to convert your address between the different chain formats. Enter any address in the input box on the left-hand side, then click **`Transform`** button, you can see address formats for all chains on the right-hand side. # Polkawallet Mobile App ### **Install Polkawallet App** Download the Polkawallet app via [its official website](https://polkawallet.io/). The app is available through the Apple App Store for iOS devices, Google Play for Android devices, and as Android APK. ### Create Account 1. Click on the "Create Account" button. ![](https://lh5.googleusercontent.com/VaB4EcpFPO9Qmvl2K_MVKk8rVevhEzDsD45WZzkWKe3B6DXyoSU8-IenMk3slTe4uGLVl4IzAEmOz-A0SyJ508VUy49UfiGpsBT5R7q2QRmeybP1cE-2fU52iOdoudgcdmsLv_Kl) 2\. A new screen will appear explaining the importance of recording your mnemonic phrase in a safe place. Click the "Next" button. ![](https://lh6.googleusercontent.com/509_xAUccOu0djt4YJZsvrLW4H_fdBxmOmMMwpRrseGSt9xcyZdx4Tgge7ZofXk6um7rSR6LcPL7c23rJHF2ZHv7FlLl2SbYciqd3-ck_v_hlco0RRP7oPpin90nv2YETvvN_cEb) ‌3. Your mnemonic phrase will appear. Write the mnemonic on a piece of paper and store it somewhere safe. Click on the "Next" button. ![](https://lh5.googleusercontent.com/XD1NG32OkmzZYToN8Fb-noLzUJmacWIACYhi-gSyV3-s58n4Ovu6sS0qQMRe1NkMMyLA4LBz_wEHRnEDwVnQgEaXQwCrgvUr0fNvA8SDilS7mrrnP--9bx3-SnHaioy_prFD4KoE) 4\. Confirm your mnemonic by entering the words in the correct order. Click on the "Next" button when completed. ![](https://lh4.googleusercontent.com/ROVs8A4woJy9RYKmsGd6Jm1W8GMzG_cpB6ba3XLViS18GMTmRK0giSV7qkDh2XZrKxxLv4LFLEFuiRT6Lw3wri8yu6cT9tBMyw00vMhxq5Vmwb2qBOUg9-Eey7RHMbh4araqvk7P) ### **Name Account & Password** Name your account and create a strong password (at least 6 characters). Click on the "Next" button when completed. ![](https://lh4.googleusercontent.com/PWXIJxAuCBlb-QGBrpce0gvFgG_C_jWUL125eOU_ke_thRY4WDhUq1AvDa6bAWHWy_sD5BXp40gM5zzJRdkDGF5XrtLEuLD5TwJ1sV8FDdjr1QRjDm9I-hzfXGsqBLsq0QVFgb02) Your wallet is now set up! The screen will default to the Polkadot network. You can determine which network you're connected to by looking at the grey text under the account name. In the case of this screenshot, it says "Polkadot." ![](https://lh5.googleusercontent.com/xlFLRGhSFMpRc1QeJrObC8vazj7YCLIe2AvW-euSwN4bvjlZWhTbcyBxF4SPTXQGuOCJtdxMW_1IMNyoL88RzC51RGN7CkLepjjOXTnJkEkp0ZSRzS58F7rAVMamcuXJ_01S6AhE) ### Set Address for Polkadot Mainnet 1. Click the menu button on the top-right corner. ![](https://i.imgur.com/JwPrsVe.jpg%20=250x) 2\. In the opened menu select the Polkadot logo, then press on the appeared address on the main screen. ### Set Address for Kusama Mainnet 1. Click the menu button on the top-right corner. 2. In the opened menu select the Kusama logo, then press on the appeared address on the main screen. ### # Ledger Hardware Wallet Following steps from this article, you will be able to access Karura account on Ledger Hardware Wallet via Polkadot{.js} web wallet, as well as interacting with the account with Karura App through Polkadot{.js} browser extension. When using Ledger devices, always ensure you are using the latest version of Karura App, Ledger Live, and firmware on your Ledger device. ### Step 1 - Install Karura App on your Ledger Hardware Wallet {% embed url="" %} Karura App installation tutorial from Ledger {% endembed %} You can find the tutorial from Ledger above, or follow steps below: 1. **Connect** and **unlock** your Ledger device on your computer 2. Open **Ledger Live**, follow on screen instruction to allow access on your Ledger device 3. In **My Ledger, s**earch for **Karura** then click **Install** 4. Proceed to Step 2 below ### Step 2 - Add your Karura Account on Ledger Hardware Wallet on Polkadot{.js} Note: please add the account using Polkadot{.js} on web, do not use Polkadot.js browser extension to perform this step (it will be Step 3 below). {% embed url="" %} Ledger Karura account on Polkadot.js web tutorial from Ledger {% endembed %} You can find the tutorial from Ledger above, or follow steps below: 1. **Connect** and **unlock** your Ledger device on your computer, **open** the **Karura App** on your Ledger device 2. On your browser, **go to** [Polkadot.js Web Wallet](https://polkadot.js.org/)\ Note: Use the same browser with Polkadot.js browser extension installed if you would like to access this account with Karura apps, **click** on either the **apps wallet (hosted)** or **apps wallet (ipfs)** tile 3. **Switch** to **Karura** network 3.1. Clicking on top left corner of the site\ ![](/files/kKta8eRxY388FRRysX8o) 3.2. **Click** and expand **Kusama & Parachains** then **select** **Karura** via any of the RPCs listed and **click Switch**\ ![](/files/nXJqmxUpUA3PLgpz8Wjj) 4. **Go** to Settings**, click** manage hardware connection**,** and **select**:\ 4.1. **Attach Ledger via WebHID** if you are on macOS or Linux.\ 4.2. A**ttach Ledger via WebUSD** if you are on Windows.\ 4.3. **Click** Save 5. **Go** to Accounts - Accounts via the top menu\ 5.1. Select **Add via Ledger**\ 5.2. Input a name for the account\ 5.3. Select the Ledger Device connected if prompted\ 5.4. Done ### Step 3 - Add your Karura Account on Ledger Hardware Wallet on Polkadot{.js} Browser Extension 1. **Click** on Polkadot.js browser extension, **click** + then **click** "Attach Ledger Account to add an account\ \ ![](/files/8IG3Xn68qnNxtFkzR646) 2. **Select** Karura\ ![](/files/GqzXQOEE8Zvt0ZoeFu50) 3. **Input** name of the account and **click** Import 4. Done, and now you can interact with Karura account on Ledger account, with Karura app through Polkadot.js browser extension. # Exchange Withdraw/Deposit ## KSM Withdraw/Deposit ⚠️ **Exchanges do NOT currently support direct withdraw/deposit KSM to/from Karura network. Please do NOT send KSM to an exchange address on Karura App.** ### How to Send KSM from an Exchange to Karura? 1. Withdraw KSM from Exchange to your **Kusama account on the Kusama network.** You should be able to check balance on the [Polkadot App - Kusama Accounts](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkusama-rpc.polkadot.io#/accounts) once the withdraw is successfull. Please consult your exchange regarding details of withdrawing KSM to Kusama network. 2. [Use Inter-Kusama Transfer](/get-started/get-started/inter-kusama-transfer) on the Karura App to send KSM from Kusama network to Karura network. You should be able to check KSM balance on the [Karura App wallet.](https://apps.karura.network/portfolio) ### How to Send KSM from Karura to an Exchange? 1. [Use Inter-Kusama Transfer](/get-started/get-started/inter-kusama-transfer) on the Karura App to send KSM from Karura network to Kusama network. You should be able to check updated KSM balance on Kusama network via the [Polkadot App - Kusama Accounts](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkusama-rpc.polkadot.io#/accounts). 2. Please then follow your exchange's instruction to send KSM on Kusama network to the exchange account. ## KAR Withdraw/Deposit Exchanges that support the Karura network and the KAR token would support direct withdraw/deposit KAR to/from Karura network. Please do confirm with your exchange. Always send a small amount to verify before sending the full amount. ## Other Tokens on Karura By default Exchanges do NOT automatically support direct withdraw/deposit new tokens on Karura network. We will update the status of support as we progress. # Balance Type & Vesting ## Balance Types On Karura there are the following steps balance types * **Transferrable Balance**: as the name suggests, this balance can be used for transfers, paying fees and performing any actions on-chain. * **Locked Balance:** this balance is frozen, depending on the scheme, it could be locked for a certain period of time before being transferrable, or it could be vested where a portion of the balance gradually becomes transferrable, or a combination of these. The tokens are released lazily, meaning you are required to perform a `claim` transaction to obtain it. The guide for claiming vested tokens is in the next section. * **Total Balance:** is the sum of transferrable balance plus the locked balance. The entire balance can be used for governance operations such as voting. ## Check & Claim Vested Tokens ### Claiming Vested KAR via Web App You can claim your vested KAR here ![](/files/3cEjZdTjbetbeg8OaeJC) ### On Polkadot App Go to the [Polkadot App - Karura Parachain - Accounts section](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkarura-rpc-1.aca-api.network#/accounts), expand the balance of your account, if there's a vested (locked) balance, it will be displayed. ![](/files/-MeYDedAXjfbdgO82gXV) Go to the `Developer - Extrinsics` section, use the account that you want to claim the vested balance. Select `vesting` then `claim()` in the `submit the following extrinsics` filed, then click the `Submit Transaction` button to complete the process. ![](/files/-MeYE7F683gega0LvMQs) ### Check Vesting Go to the `Developer - Chain state` section, select `vesting` then `vestingSchedules()` , then select your account, then click the `+` button to see what vesting schedule it has. ![](/files/-MfAR6DPoXMAuAQZTVIL) Below is an example result * `start`: the tokens are locked until **Kusama block #** * `period`: release period e.g. release every block or every 432,000 block as in the example * `periodCount`: how many vesting periods * `perPeriod`: how much to release each period ``` [ { start: 8,886,950, period: 432,000, periodCount: 5, perPeriod: 100 KAR } ] ``` ### Claiming Vested KAR for Other Accounts Users can also claim vested KAR for other accounts by going to the `Developer - Extrinsics` section. Select the account you'd like to use to initiate the claim in `using the selected account`. Submit the `vesting` then `claimFor(dest)` extrinsic and the account you'd like to claim **for** which is the account that has the locked tokens (shown at bottom of screenshot). Note that submitting this transaction only makes the vested tokens transferrable. It does not transfer them to the account that initiates the claim. ![](/files/2kdwsOYZebd0uLUPezEg) ### On Karura App You can claim the released portion of vested KAR on the [Karura App](https://apps.karura.network/). ![](/files/-MeYGmhGEpd2S2Ter3fb) # Check Address for Different Chains If you already set up a Polkadot account, Acala account, or any Substrate-based chain account, there are two options to check the corresponding DOT address: * you can use [Subscan Address Transform](https://acala-testnet.subscan.io/tools/ss58_transform); * setting your wallets in polkadot.js extension * use PolkaWallet mobile app ## Using Subscan transform 1. Navigate to [Subscan Address Transform](https://acala-testnet.subscan.io/tools/ss58_transform) and paste your existing account address into "Input Account or Public Key". ![](https://i.imgur.com/v7damrj.png) 1. Press "Transform" and find the corresponding Polkadot address in the appeared list on the right (in the screenshot, it is second from the top). ![](https://i.imgur.com/bv0T6dD.png) ## Using Polkadot.js extension 1. Open polkadot.js extension in your browser and press 3 dots on the right from your account name. 2. In the opened window click on the dropdown menu and pick "Polkadot Relay Chain" ![](https://i.imgur.com/GxbRxhs.jpg) 3. Now all your accounts are converted to Polkadot format, you can copy them. ## Using Polkawallet 1. Open PolkaWallet on your mobile device and click the menu button on the top-right corner. ![](https://i.imgur.com/JwPrsVe.jpg%20=250x) 2. In the opened menu select Polkadot logo (second from the top) and press on the appeared address on the main screen. 3. ![](https://i.imgur.com/YGx8nne.jpg%20=250x) 4. Click on the account block under the "Add Account" button, which will navigate you back to the main page. ![](https://i.imgur.com/JwPrsVe.jpg%20=250x) 5. Now your wallet is set up and you can copy your Polkadot address. You can see that your wallet changed color to black and among your assets you can see DOT. # Inter Kusama Transfer Karura is an experimental network, or a 'canary network', for Acala. It's an early unaudited release of the Acala code that holds real economic value. It is highly experimental. ⚠️ Exchanges do NOT currently support direct withdraw/deposit KSM to/from Karura network. **Please do NOT send KSM to an exchange address on Karura App.** Read more [here](/get-started/get-started/karura-account/exchange). * [Karura Web App Transfer Guide](https://wiki.karura.app/general/transfer-guide) ## Why Transfer KSM to Karura KSM is the native token of Kusama. It is used as the fee token, staking token to provide network security and governance token on the Kusama Relay chain. The launch of Karura's parachain unlocks new use cases for KSM: * Participate in trustless trading with other tokens via [Karura Swap](https://apps.karura.network/swap) * Use as liquidity for KSM-based trading pairs in Karura Swap, use KSM to power the KAR/KSM pair (learn about becoming a liquidity provider & risks involved [here](https://docs.acalaswap.app/overview/liquidity-pools#impermanent-loss)). This will also enable KSM as transaction fees on Karura. Read more [here](https://wiki.acala.network/karura/get-started/transaction-fees). * Use as a collateral asset to mint the kUSD stablecoin, which can then be used for leveraged trades and other use cases. * Stake in Karura's Liquid KSM staking pool to mint LKSM, which can then be used as collaterals, transferred, or traded. * LKSM is a programmable staking asset as the building block for many other protocols and applications * Liquidity mining program coming soon. ## Cross-chain Fungible Token Transfer Cross-chain transfer uses the Polkadot’s [Cross-chain Message Passing (XCMP)](https://wiki.polkadot.network/docs/learn-crosschain) technology, specifically the [Horizontal Relay-routed Message Passing (HRMP)](https://wiki.polkadot.network/docs/learn-crosschain#horizontal-relay-routed-message-passing-hrmp) as the basis for sending and receiving generic cross-chain messages. For sending and receiving fungible tokens, Karura has used the xtokens fungible token transfer implementation developed by Acala. You can find the source code: [xtokens](https://github.com/open-web3-stack/open-runtime-module-library/tree/3bf16d6efc8c35039a062748ff20fa6db6e8faa0/xtokens) and [xcm-support](https://github.com/open-web3-stack/open-runtime-module-library/tree/3bf16d6efc8c35039a062748ff20fa6db6e8faa0/xcm-support). You can also find the Cross-chain Message (XCM) Format developed by Parity [here](https://github.com/paritytech/xcm-format). ## Transfer KSM from Kusama to Karura Use the [Karura App](https://apps.karura.network/portfolio), go to `Cross Chain` tab then select `Inter Kusama Transfer`. **Note:** The account you logged into the Karura App must have some KSM (also be mindful of Existential Deposits). Select `Kusama` as the `From Chain`, and `Karura` as the `To Chain`. Your KSM balance (on Kusama) shall be displayed then. Then select the `To Account`, which can be the current account that you logged in to the Karura App. ![](/files/-Mg3iMxgU9WtTe3IlL55) There are two parts to the transaction fees (read more on fees [here](/get-started/get-started/transaction-fees)) * The `Origin Chain Transfer Fee` is charged by Kusama * The `Destination Chain Transfer Fee` is charged by Karura, modeled closely with the Statemine chain Then click \`Transfer\`, please be patient and it might take a few moments for the Kusama Relay chain to send and confirm your KSM to Karura 🚀 ### Check Transactions There are two transactions involved, one was on Kusama sending the KSM to parachain, the second is on Karura sending the KSM to the designated account. **On Kusama Side** Go to the [Kusama Subscan Explorer](https://kusama.subscan.io/), search with your Kusama account, and you shall see the relevant `xcmpallet` transaction in the Extrinsics table. ![](/files/-MeZUXa4shnP8VkbdRfZ) **On Karura Side** A Subquery will be implemented to make it easier to search and find your cross-chain transactions. Right now you can go to Karura Subscan to search Events where `module = parachainsystem` and `event = downwardmessagesprocessed`. OR [use this link](https://karura.subscan.io/event?address=\&module=parachainsystem\&event=downwardmessagesprocessed\&startDate=\&endDate=) to navigate there. [Example Transaction on Subscan](https://karura.subscan.io/extrinsic/135672-1?event=135672-1) ## Transfer KSM from Karura to Kusama Use the [Karura App](https://apps.karura.network/portfolio), goto `Cross Chain` tab then select `Inter Kusama Transfer`. Select `Karura` as the `From Chain`, and `Kusama` as the `To Chain`. Your KSM balance (on Karura) shall be displayed then. Then select the `To Account`, which can be the current account that you logged in to the Karura App. Make sure your account is set as `Allow use on any chain` on the Polkadot{js} extension. ![](/files/-Mg3iWRcKypgOJQ0AodM) There are two parts to the transaction fee (read more on fees [here](/get-started/get-started/transaction-fees)) * The ‘Origin Chain Transfer Fee\` is charged by Karura * The \`Destination Chain Transfer Fee\` is charged by Kusama Then click \`Transfer\`, please be patient and it might take a few moments for your KSM arrive back to Kusama 🚀 ### Check Transactions There are two transactions involved, one was on Karura sending the KSM to Kusama Relay chain, the second is on Kusama sending the KSM to the designated account. **On Karura Side** A Subquery will be implemented to make it easier to search and find your cross-chain transactions. Right now you can go to [Karura Subscan Explorer](https://karura.subscan.io) to search Events where `module = xtoken` and `account = sender account`. OR [use this link](https://karura.subscan.io/event?address=\&module=xtokens\&event=all) to navigate there. [Example Transaction on Subscan](https://karura.subscan.io/extrinsic/0x259558bf1a18f19c88915324d69fb5b7d7399ca4d382d651979d18d8cd0e5334?event=135681-3) **On Kusama Side** Go to the [Kusama Subscan Explorer](https://kusama.subscan.io/), search with your Kusama account, and you shall see the relevant `xcmpallet` transaction in the Extrinsics table. [Example Transaction on Subscan](https://kusama.subscan.io/extrinsic/8338413-2) # Karura Assets These are native assets on the Karura Network * **Karura Token (KAR)** | Decimal Place: 12\ ERC20 mirrored token address 0x0000000000000000000100000000000000000080 * **Acala Dollar (aUSD)** | Decimal Place: 12\ ERC20 mirrored token address 0x0000000000000000000100000000000000000081 * **Liquid Staking KSM (LKSM)** | Decimal Place: 12\ ERC20 mirrored token address 0x0000000000000000000100000000000000000083 * **Kusama Token (KSM)** | Decimal Place: 12\ ERC20 mirrored token address 0x0000000000000000000100000000000000000082 ### On-chain Metadata {% embed url="" %} # Governance Read Governance overview [here](/learn/governance-overview). Below are governance discussion and proposal avenues: * [Karura Subsquare - Discussion & View related on-chain Proposal](https://karura.subsquare.io/) * [Polkadot Web App - On-chain Voting](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkarura-rpc-1.aca-api.network#/extrinsics) * [Acala Discourse Forum - long form, informal discussions](http://forum.acala.network) ## Governance Parameters These are important governance parameters, which may change over time as we progress through the governance phases. * Launch Period: Public referenda is every **2 days** * Voting Period: Votes are tallied every **2 days** * Emergency Voting Period: Voting period for fast-tracked emergency referendum is **3 Hours** * Minimum Deposit: Proposing a referendum requires a minimum deposit of **100 KAR** * Enactment Period: Minimum period for locking funds and the period between a proposal being approved and enacted is **1 day** * Cool-off Period: Vetoed proposal may not be re-submitted within **7 days** Most of these parameters are visible on the Polkadot App. You can also view upcoming governance events on `the Event Calendar` ![](/files/-MebyAUgKFd9iGgfr29E) ## Propose a Referendum A referendum consists of some action that you want to propose. If voted in by token holders, then the action will be enacted on-chain automatically. You are required to bond some tokens to propose an action. Once a proposal is submitted, it can not be canceled. On the [Polkadot Apps - Karura parachain](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkarura-rpc-1.aca-api.network#/democracy), you can use the “Democracy” tab to make a new proposal. The action, such as 'force transfer balance from account A to account B', is encoded in a preimage, and the hash of the action is called preimage hash. Since the preimage can be quite large (hence costly to submit), you can submit a Proposal first which includes the preimage hash only, and submit the preimage (or have someone else submit it for you) later but before voting completes. ### Step 1: Submit a Proposal #### Get the preimage hash By clicking on the `Submit preimage` button, then fill in the action you want to propose, copy and note down the preimage hash `0x244fcb51680c90172ba55241d3d9229676c4471a4645aed223a2272b33264026`. Once you noted down the hash, you can now cancel the prompt. ![](/files/-MeMjrBOIqqs8AGW81g-) #### Submit a proposal Submit a proposal by clicking on the `Submit a proposal` button, and pasting in the preimage hash to submit it. Then the proposal shall appear in the proposal table. ![](https://lh5.googleusercontent.com/pzSjpt4wxQscdDdnjIFNE0iCRxLcPGHdJoEfXXaf8E7FIHfg66C0FSKIaoky0QMa3v0sl_E9LoJ1x0b_30X-2zzAZBZbijf8RhuMu_1J2UFapoaaDl0cIE58l7k3nw30nYaK0rCu) ### Step 2: Submit a Preimage Before voting of your proposal completes, you will need to submit the actual preimage. Otherwise, it cannot be enacted on-chain. You can repeat the ‘Submit a preimage’ process as previously mentioned, and click the ‘Submit preimage’ button to send the transaction. ## Vote on a Referenda To Vote on Referenda, you must hold KAR tokens and these tokens must be held in a wallet that has the functionality to participate in Democracy like Polkadot.js. If you don't have your tokens in Polkadot.js wallet, you can read more about [account generation](/get-started/get-started/karura-account). Once a proposal is in as a referendum, it will show up in the referenda table. You can navigate to the [Polkadot Apps - Karura Parachain Democracy](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkarura-rpc-1.aca-api.network#/democracy) to cast your vote. ![](/files/-MeMilPv_JhWrDzMyMkz) You can click on the ‘Vote’ button to vote. Select "Vote Aye" to support the proposal, and select "Vote Nay" to disapprove the proposal. You can also increase your conviction with the same number of tokens by locking them. The longer you are willing to lock your tokens, the stronger your vote will be weighted. Read more on [voting](https://wiki.polkadot.network/docs/maintain-guides-democracy/#voting-on-a-proposal) and [tallying](https://wiki.polkadot.network/docs/learn-governance#tallying). ![](/files/-Mf6RU7wtrNQrciSG_w-) ## Unlock locked tokens You will need to explicitly unlock these tokens once the locking period ends. You can go to the `Accounts` page, click the menu button for the voted account, and select the menu item`Clear expired democracy locks` to claim it back. Read more [here](https://wiki.polkadot.network/docs/maintain-guides-democracy/#unlocking-locked-tokens). ![](/files/-Mf-ovNhPIZBcN4-LRPT) ### Check Locked Democracy Votes Go to `Developer` - `Chain state`, then select `democracy` and `locks`. Select the account used for voting in the dropdown, and click the `+` button to see whether there's locked votes, and if any how long they are locked for. ![](/files/-Mf6S04L32upPGdENLdq) ## Delegate Vote You can delegate your vote to others to vote on your behalf. On [the Polkadot Apps - Karura parachain,](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkarura-rpc-1.aca-api.network#/extrinsics) go to the `Developer` tab -- `Extrinsics` , then select `democracy.delegate` . ![](/files/-MeMjgEuarbxslyUeDKi) # Transaction Fees **🔔 Karura allows fees to be paid in any supported token.** However once transfer is enabled, there will be a period of time transaction fees are required to be paid in the native token $KAR, until KSM/KAR, kUSD/KAR and other [Karura Swap](https://apps.karura.network/swap) pools are bootstrapped, then KSM, kUSD and other tokens can be used to pay transaction fees. Transaction fees are used to prevent users from consuming too much limited resources of the blockchain, such as storage and computation power. Karura uses weight-based fees, unlike gas, are predictable and charged pre-dispatch. ### Fee Estimates These are rough estimates of typical relevant transactions: * **Transfer from Kusama to Karura,** there are two components to the cross-chain transfer fees: * Kusama fee, determined by Kusama * Karura fee: 0.3 milliKSM\~ * **Transfer from Karura to Kusama,** there are two components to the cross-chain transfer fees: * Karura fee: 4 milliKAR (0.004 KAR)\~ * Kusama fee, determined by Kusama * **Karura** * **Transfer:** 4 milliKAR (0.004 KAR)\~ * **DeX swap:** 12 milliKAR\~ * **Add liquidity:** 18 milliKAR\~ * **Adjust kUSD loan:** 18 milliKAR\~ Note: these are estimates and will be changed based on actual transaction size, network conditions and other factors. For now, all transaction fees go to the Karura Treasury - a tiny contribution to a sustainable future. Read more [here](/learn/treasury). ### Fee Adjustment Fees on Karura are adjusted based on transaction volume, while still predictable. Karura has a block fullness target, fees increase or decrease for the next block based on the fullness of the current block relative to the target. ### Bring Your Own Gas Why users are restricted to pay fees in the native token when transferring other tokens?! On Karura you don't need to. Users can pay fees in any tokens that are supported on the Karura network. When paying fees in tokens other than KAR, fees are still estimated in KAR, a real-time swap operation (between paid token and KAR) is executed automatically by the chain. This operation is atomic and transparent to the users. # Mandala Testnet ### Web App [Mandala Web application](https://apps.mandala.acala.network) ### Explorer [https://acala-testnet.subscan.io/](https://acala-testnet.subscan.io) ### RPC Endpoints * wss\://mandala-tc9-rpc.aca-staging.network ### EVM RPC See ### Faucet * [On Discord in the #acala-testnet-faucet Channel](https://discord.gg/5JJgXKSznc) # Acala Network Integration Guide Acala is a parachain of the Polkadot Relay chain, with all of its network security and consensus provided by Polkadot's Validator set. As a [Substrate](https://www.substrate.io/)-based chain, most of Acala's integration points are the same as Kusama and Polkadot. As a parachain specifically though, the key differences will be outlined in this document. This guide contains the following sections: 1. [Protocol Info](/integrate/acala/protocol-info) 2. [Token Transfer](/integrate/acala/token-transfer) 3. [Networks](/integrate/acala/endpoints) 4. [Run a Full Node](/integrate/acala/full-node) 5. [Run a Collator Node](/integrate/acala/collator) # Protocol Info ## Tokens | Name | Symbol | Decimal | [ED](https://wiki.polkadot.network/docs/learn-accounts#existential-deposit-and-reaping) | Token Type | Check Balance | Total issuance | | -------------------- | ------ | ------- | --------------------------------------------------------------------------------------- | -------------------- | ----------------- | ---------------------- | | Acala | ACA | 12 | 0.1 | Native / Tokens(ACA) | `system.account` | 1,000,000,000 | | Acala USD | aUSD | 12 | 0.1 | Tokens(AUSD) | `tokens.accounts` | `tokens.totalIssuance` | | Polkadot | DOT | 10 | 0.01 | Tokens(DOT) | `tokens.accounts` | `tokens.totalIssuance` | | Liquid DOT | LDOT | 10 | 0.05 | Tokens(LDOT) | `tokens.accounts` | `tokens.totalIssuance` | | Liquid Crowdloan DOT | LCDOT | 10 | | LiquidCrowdloan(13) | `tokens.accounts` | `tokens.totalIssuance` | | Tapio DOT | tDOT | 10 | 0.01 | StableAssetId(0) | `tokens.accounts` | `tokens.totalIssuance` | | Moonbeam | GLMR | 18 | 0.1 | ForeignAssetId(0) | `tokens.accounts` | `tokens.totalIssuance` | | Parallel | PARA | 12 | 0.1 | ForeignAssetId(1) | `tokens.accounts` | `tokens.totalIssuance` | ![](/files/sszVrJvDdYnYRgPSTV1O) ![](/files/vMRcHd5WW8XOJQmZMVfz) ## Account ### Address Format Acala uses the [SS58 (Substrate) address format](https://github.com/paritytech/substrate/wiki/External-Address-Format-\(SS58\)). Relevant SS58 prefixes are: * **Acala**: 10 ([ss58 registry details](https://github.com/paritytech/substrate/blob/df4a58833a650cf37fc97764bf6c9314435e3cb2/ss58-registry.json#L103-L111)) * **Karura**: 8 ([ss58 registry details](https://github.com/paritytech/substrate/blob/df4a58833a650cf37fc97764bf6c9314435e3cb2/ss58-registry.json#L85-L92)) * **Mandala**: 42 ### Existential Deposit Acala uses an *existential deposit* (ED) to prevent dust accounts from bloating state. If an account drops below the ED, it will be removed from this account and be donated to the Treasury. ED of native token ACA is configured in the runtime. Non-native tokens (DOT, aUSD, BTC etc) can be queried via SDK. The amount of ED can only be decreased, not increased, therefore it often starts with a higher number. `transfer` and `deposit` in `pallet_balances` and `orml_tokens` will check the ED of the receiver account. A transaction may fail due to not meeting ED requirements, a typical one would be a user is swapping token A for token B, where token A balance no longer meets ED requirements. A front-end DApp shall perform checks and prompt user for such incidents. Read more on ED [here](/get-started/acala-network/acala-account). ## Protocol Fees * **Mint aUSD with DOT & lDOT:** * **Liquidation penalty:** 12% * **Stability Fee:** 3% ## Transaction Fees Acala uses weight-based fees, unlike gas, are predictable and charged pre-dispatch. See the [transaction fee](/get-started/get-started/transaction-fees) page for more info. ## Types Type definitions allow the SDK to know how to serialize / deserialize blocks, transactions and events. Acala's type definition bundle can be found [here](https://unpkg.com/browse/@acala-network/type-definitions@latest/json/typesBundle.json). ## MultiLocation You can use these MultiLocation to add Acala token assets to other parachains foreign token list. Asset Name: Acala Dollar\ Asset Symbol: AUSD\ Decimals: 12\ existentialDeposit: 0.1 `{"parents": 1, "interior": {"X2": [{"Parachain": 2000}, {"GeneralKey": 0x0001} ]}}` Asset Name: Liquid DOT\ Asset Symbol: LDOT\ Decimals: 10\ existentialDeposit: 0.05 `{"parents": 1, "interior": {"X2": [{"Parachain": 2000}, {"GeneralKey": 0x0003} ]}}` Asset Name: Acala Native Token\ Asset Symbol: ACA\ Decimals: 12\ existentialDeposit: 0.1 `{"parents": 1, "interior": {"X2": [{"Parachain": 2000}, {"GeneralKey": 0x0000} ]}}` ### Autogenerated MultiLocations {% embed url="" %} Click Run to generate the current full list of MultiLocations {% endembed %} ## JS SDK Acala.js: Documentation: Please also refer to the [documentation of polkadot.js](https://polkadot.js.org/docs/api/). ## Telemetry ## Polkadot apps ## Explorer # Token Transfer Acala supports different types of tokens than Polkadot, and allows various ways to transfer tokens. This guide will walk through tokens available on Acala, tools can be used for transfers, how to send transfer transactions, monitor and track these transactions. ## Token Types ### Token | Symbol | Description | CurrencyId | Decimals | Minimal Balance | | ------ | ----------------------------------------------------- | ----------- | -------- | --------------- | | ACA | native token of Acala network | Token(ACA) | 12 | 0.1 ACA | | aSEED | multi-collateralized stablecoin | Token(AUSD) | 12 | 0.1 aUSD | | DOT | crossed to Acala from Polkadot Relay Chain | Token(DOT) | 10 | 0.01 DOT | | LDOT | tokenized staked DOT from the Liquid Staking protocol | Token(LDOT) | 10 | 0.05 LDOT | {% hint style="info" %} aUSD is converted to [aSEED](/acala-exodus-upgrade/ausd-seed-aseed) on July 20 2023 {% endhint %} `AssetRegistry` registered the metadata info of this type token. ### DexShare The lp share token for the trading pair of Acala DEX. The CurrencyId type of Acala DEX's lp token are `CurrencyId::DexShare`, and the decimals and minimal balance of lp token are same as the first token in `DexShare`. For example, `CurrencyId::DexShare(Token(ACA), Token(AUSD))` is the CurrencyId of lp token of ACA/aSEED pair, its decimal is 12, and minimal balance is 0.1, these are same as ACA. Currently, `AssetRegistry` does not register metadata info of any lp token. ### Erc20 Token issued by ERC20 contracts deployed in Acala EVM+. The CurrencyId type is `Erc20(Address)`, `Address` is the ERC20 contract address on EVM+. ### LiquidCrowdloan | Symbol | Description | CurrencyId | Decimals | Minimal Balance | | ------ | ------------------------------------------- | ------------------- | -------- | --------------- | | LcDOT | tokenized liquid receipt of crowdloaned DOT | LiquidCrowdloan(13) | 10 | 0.01 LcDOT | `AssetRegistry` registered the metadata info of this type token. ### ForeignAsset Tokens originated from other parachains. `AssetRegistry` registered the metadata info of this type token. ## Query token's metadata on assetRegistry ![query asset metadata](/files/sszVrJvDdYnYRgPSTV1O) ## Tools * JS/TS SDK: * Blockchain explorer: * api-sidecar: * txwrapper: * SubQuery: ## Token balances Query chain state to get token balances. ### Native token (ACA) balances Query `system` module to get native token (ACA) balances data. #### system.account * Returns the `AccountInfo` of given account. For different types of balances, check the fields in `AccountInfo.data` * `free`: the free balance. * `reserve`: the reserved balance. ### Other tokens For non-native tokens, like DOT, LDOT, aUSD, query `tokens` module to get balances info. #### tokens.accounts * Returns the `OrmlAccountData` of given account and currency ID. For different types of balances, check the fields: * `free`: the free balance. * `reserved`: the reserved balance. #### tokens.lock * Returns the `BalanceLock` of given account and currency ID. `BalanceLock` has two fields: * `id`: the lock identifier. * `amount.` the locked amount. * Note locks could be overlapped, and the same amount of tokens could be under locked by multiple locks. ## Send Tokens ### Transactions #### currencies.transfer * * This can be used to send any supported tokens in the network, including ACA, DOT, LDOT, LCDOT, aUSD etc. #### currencies.transferNativeCurrency * * This can be used to send native token (ACA). It has slightly cheaper transaction fees compare to currencies.transfer #### balances.transfer * * Same as `currencies.transferNativeCurrency`, only for native token (ACA). * Compatible with Polkadot / Polkadot and most other Substrate-based chains. #### xtokens transfer by XCM * ORML's [Xtokens Module](https://github.com/open-web3-stack/open-runtime-module-library/blob/master/xtokens) supports token transfer by cross-consensus messages (XCM), and has a number of dispatchable functions to support different use cases. * **xtokens transfer functions:**\ xtokens.transfer\ xtokens.transfer\_multiasset\ xtokens.transfer\_with\_fee xtokens.transfer\_multiasset\_with\_fee xtokens.transfer\_multicurrencies xtokens.transfer\_multiassets * * Can be used to send any supported tokens in the source and destination networks, including ERC20 tokens. ## Receive Tokens There are multiple ways to detect incoming balance transfers: * Monitor events * Subscribe storage changes * Monitor transactions ### Monitor Events Monitoring events is a recommended way to track incoming balance transfers. It can handle **ALL** types of transfer transactions including the one that is not initiated by a transaction directly (e.g. delayed proxy). #### balances.transfer * * Emitted when a native token (ACA) transfer happened. #### currencies.transfer * * Emitted when a token transfer happened. * NOTE: This is not emitted when balances.transfer is used to make a transfer. #### currencies.deposit * * Emitted when a token is minted to an account. This could happen when it is a cross-chain transfer or it is a transaction minting stablecoins. * For cross-chain transfer, there would be `ExecutedDownward` event along with the deposit. #### xtokens.transferredmultiassets * * Emitted when a cross-chain transfer happened from Karura to other chains. * Triggered by`xtokens.transfer, xtokens.transfer_multiasset, xtokens.transfer_with_fee, xtokens.transfer_multiasset_with_fee, xtokens.transfer_multicurrencies, xtokens.transfer_multiassets` extrinsics . ### Storage changes RPC * [state\_subscribeStorage](https://polkadot.js.org/docs/substrate/rpc#subscribestoragekeys-vecstoragekey-storagechangeset) * Subscribe to a list of account balances. However, it does not guarantee subscription delivery due to connection errors or blockchain reorg. ### Monitor Transactions It is possible to fetch transactions in every block, check for transfer transactions, and check if the transfer transaction is successful. However, this may likely yield false-negative results i.e. deposit received but failed to recognize, due to the various ways for transfer. Refer to Send Tokens section for direct transfer transactions. In additional, to sending transfer transactions individually, there are common utility methods to batch send transfer transactions: #### utility.batch * * This can be used to send batch transaction * NOTE: batched transactions will always emit success events. * `utility.BatchCompleted` event indicates that all transactions are successful * `utility.BatchInterrupted` event indicates which transaction failed. Transactions before the failed transaction are executed successfully and will not be reverted. #### utility.batchAll * * This is similar to utility.batch but will revert all transactions upon failed transaction. ## [Transfer Code Samples](https://github.com/AcalaNetwork/acala-js-example/blob/21a3be3538260cc8a047856bf163dad75de1db3a/src/transfer-examples/readme.md) # Node Interaction ### WebSocket RPC Endpoints * `wss://acala-rpc.n.dwellir.com` * `wss://acala-polkadot.api.onfinality.io/public-ws` * `wss://rpc-acala.luckyfriday.io` * `wss://acala-rpc.aca-api.network` ### HTTPS RPC Endpoints * `https://acala-rpc.n.dwellir.com` * `https://rpc-acala.luckyfriday.io` * `https://acala-rpc.aca-api.network` # Full Node ## Spec Requirement Same as the Polkadot full node requirements. ## Latest Release Version {% embed url="" %} Shows the latest release version of Acala, Karura & Mandala {% endembed %} ## Run from Source Code * Clone the repo: * Checkout tag here: * Install dependencies using instructions from [here](https://github.com/AcalaNetwork/acala-node?tab=readme-ov-file#building) * Build Acala: \`cargo build --release * Run `./target/release/acala --chain=acala` ## Using Docker * Image: `acala/acala-node:latest` or `acala/acala-node:[version number]` * `docker run acala/acala-node:latest --chain=acala` ## Common CLI * CLI is mostly the same as any Substrate-based chain such as Kusama and Polkadot * Because there are two node services are running, `--` is used to split the CLI. Arguments before `--` are passed to the parachain full-node service and arguments after `--` is passed to the Relay Chain full-node service. * For example `--chain=parachain.json --rpc-port=9944 -- --chain=relaychain.json --rpc-port=9945` means * The parachain service is using `parachain.json` as the chain spec and the web socket RPC port is 9944 * The Relay Chain service is using `relaychain.json` as the chain spec and the web socket RPC port is 9945 * It is recommended to explicitly specify the ports for both services to avoid confusion * For example `--listen-addr=/ip4/0.0.0.0/tcp/30333 --listen-addr=/ip4/0.0.0.0/tcp/30334/ws -- --listen-addr=/ip4/0.0.0.0/tcp/30335 --listen-addr=/ip4/0.0.0.0/tcp/30336/ws` * It is recommended to add `--execution=wasm` for parachain service to avoid syncing issues. * It is recommended to add `--relay-chain-rpc-url` or `--relay-chain-rpc-urls` for parachain service to avoid fully sync with the relay chain to work, so in general, they will use fewer system resources. ## Example CLI ### Archive PRC Node ``` --base-path=/acala/data --chain=acala --name=rpc-1 --pruning=archive --rpc-external --rpc-cors=all --rpc-port=9944 --rpc-max-connections=2000 --relay-chain-rpc-url=wss://polkadot-rpc.publicnode.com ``` # Collator ## Overview Collators maintain parachains by collecting parachain transactions from users and producing state transition proofs for Relay Chain validators. In other words, collators maintain parachains by aggregating parachain transactions into parachain block candidates and producing state transition proofs for validators based on those blocks. While Acala’s network security and consensus (nPoS) are provided by Polkadot Relay chain's Validator set, the Collator set of Acala will keep the network alive by collecting parachain transactions for validators to verify them. **Unlike validators, collators has nothing to do with security of the network, by being a parachain, the network is by default trustless and decentralized, and a parachain only needs one honest collator to be censorship-resistant.** Read more on Collators [here](https://wiki.polkadot.network/docs/learn-collator). Acala's Collator node maintains a full-node service for the Polkadot Realy Chain, and a full-node service for the Acala network. Each service has its own http/ws RPC endpoints, P2P ports etc. The base path of the Polkadot full-node service is located inside of the base path of the Acala full-node service. ## Collator Node ### Spec Requirement Same as [the Polkadot validator node requirement](https://guide.polkadot.network/docs/maintain-guides-how-to-validate-polkadot/#requirements). ### Run Node Refer to the [Full Node Guide](/integrate/acala/full-node). ### Collator Configuration #### **Key Management** Acala Collator needs Aura session key. RPC `author_rotateKeys` or `author_insertKey` can be used to update session key. #### **Registration** * Acala is currently using the `collectorSelection` pallet from Statemint to handle collator registration. During the authorized Collator set phase, the required candidacy bond will be an unattainably high value to prevent public registration. * Authorized providers will need to submit the public key of the Aura session key for the collator. #### CLI * `--collator` for the parachain part ### **Example CLI** ``` --base-path=/acala/data --chain=acala --name=collator-1 --collator --execution=wasm --relay-chain-rpc-url=wss://polkadot-rpc.publicnode.com ``` # Karura Network Integration Guide Karura is a parachain of the Kusama Relay chain, with all of its network security and consensus provided by Kusama's Validator set. As a [Substrate](https://www.substrate.io/)-based chain, most of Karura's integration points are the same as Kusama and Polkadot. As a parachain specifically though, the key differences will be outlined in this document. This guide contains the following sections: 1. [Protocol Info](/integrate/karura/protocol-info) 2. [Token Transfer](/integrate/karura/token-transfer) 3. [Networks](/integrate/karura/endpoints) 4. [Run a Full Node](/integrate/karura/full-node) 5. [Run a Collator Node](/integrate/karura/collator) # Protocol Info ## Tokens * **Token decimals:** * Karura (KAR): 12 * LKSM: 12 * Karura Dollar (kUSD): 12 * **Base unit:** “Plank" * **Balance type:** * **Total Fixed Supply of KAR:** 100,000,000 ## Account ### Address Format Karura uses the [SS58 (Substrate) address format](https://github.com/paritytech/substrate/wiki/External-Address-Format-\(SS58\)). Relevant SS58 prefixes are: * **Acala**: 10 ([ss58 registry details](https://github.com/paritytech/substrate/blob/df4a58833a650cf37fc97764bf6c9314435e3cb2/ss58-registry.json#L103-L111)) * **Karura**: 8 ([ss58 registry details](https://github.com/paritytech/substrate/blob/df4a58833a650cf37fc97764bf6c9314435e3cb2/ss58-registry.json#L85-L92)) * **Mandala**: 42 ### Existential Deposit Karura uses an *existential deposit* (ED) to prevent dust accounts from bloating state. If an account drops below the ED, it will be removed from this account and be donated to the Treasury. ED of native token KAR is configured in the runtime. Non-native tokens (KSM, kUSD, BTC etc) can be queried via SDK. The amount of ED can only be decreased, not increased, therefore it often starts with a higher number. `transfer` and `deposit` in `pallet_balances` and `orml_tokens` will check the ED of the receiver account. A transaction may fail due to not meeting ED requirements, a typical one would be a user is swapping token A for token B, where token A balance no longer meets ED requirements. A front-end DApp shall perform checks and prompt user for such incidents. Read more on ED [here](/get-started/get-started/karura-account#existential-deposit). ## Protocol Fees * **Mint kUSD with KSM & lKSM:** * **Liquidation penalty:** 12% * **Stability Fee:** 3% ## Transaction Fees Karura uses weight-based fees, unlike gas, are predictable and charged pre-dispatch. See the [transaction fee](/get-started/get-started/transaction-fees) page for more info. ## Types Type definitions allow the SDK to know how to serialize / deserialize blocks, transactions and events. Acala's type definition bundle can be found [here](https://unpkg.com/browse/@acala-network/type-definitions@latest/json/typesBundle.json). ## MultiLocation You can use these MultiLocation to add Karura token assets to other parachains foreign token list. Asset Name: Acala Dollar\ Asset Symbol: AUSD\ Decimals: 12\ existentialDeposit: 0.01 `{"parents": 1, "interior": {"X2": [{"Parachain": 2000}, { "GeneralKey": 0x0081} ]}}` Asset Name: Liquid KSM\ Asset Symbol: LKSM\ Decimals: 12\ existentialDeposit: 0.0005 `{"parents": 1, "interior": {"X2": [{"Parachain": 2000}, {"GeneralKey": 0x0083} ]}}` Asset Name: Karura Native Token\ Asset Symbol: KAR\ Decimals: 12\ existentialDeposit: 0.1 `{"parents": 1, "interior": {"X2": [{"Parachain": 2000}, { "GeneralKey": 0x0080} ]}}` ### Autogenerated MultiLocations {% embed url="" %} Click Run to generate the current full list of MultiLocations {% endembed %} ## JS SDK Acala.js: Documentation: Please also refer to the [documentation of polkadot.js](https://polkadot.js.org/docs/api/). ## Telemetry ## Polkadot apps ## Explorer # Token Transfer Karura supports different types of tokens than Kusama, and allows various ways to transfer tokens. This guide will walk through tokens available on Karura, tools can be used for transfers, how to send transfer transactions, monitor and track these transactions. ## Token Types ### Token | Symbol | Description | CurrencyId | Decimals | Minimal Balance | | ------ | ------------------------------------------------------ | ------------ | -------- | --------------- | | KAR | native token of Karura network | Token(KAR) | 12 | 0.1 KAR | | aUSD | multi-collateralized stablecoin | Token(KUSD) | 12 | 0.01 aUSD | | KSM | crossed to Karura from Kusama Relay Chain | Token(KSM) | 10 | 0.01 KSM | | LKSM | tokenized staked LKSM from the Liquid Staking protocol | Token(LKSM) | 10 | 0.05 LKSM | | BNC | Bifrost Native Token | Token(BNC) | 12 | 0.008 BNC | | TAI | Taiga | Token(TAI) | 12 | 1 TAI | | PHA | Phala Native Token | Token(PHA) | 12 | 0.04 PHA | | KINT | Kintsugi Native Token | Token(KINT) | 12 | 0.00013333 KINT | | VSKSM | Bifrost Voucher Slot KSM | Token(VSKSM) | 12 | 0.0001 VSKSM | | KBTC | Kintsugi Wrapped BTC | Token(KBTC) | 8 | 0.00000066 KBTC | `AssetRegistry` registered the metadata info of this type token. ### DexShare The lp share token for the trading pair of Karura DEX. The CurrencyId type of Karura DEX's lp token are `CurrencyId::DexShare`, and the decimals and minimal balance of lp token are same as the first token in `DexShare`. For example, `CurrencyId::DexShare(Token(KAR), Token(KSM))` is the CurrencyId of lp token of KAR/KSM pair, its decimal is 12, and minimal balance is 0.1, these are same as KAR. Currently, `AssetRegistry` does not register metadata info of any lp token. ### Erc20 Token issued by ERC20 contracts deployed in Karura EVM+. The CurrencyId type is `Erc20(Address)`, `Address` is the ERC20 contract address on EVM+. ### StableAssetPoolToken | Symbol | Description | CurrencyId | Decimals | Minimal Balance | | ------ | ----------- | ----------------------- | -------- | --------------- | | taiKSM | Taiga KSM | StableAssetPoolToken(0) | 12 | 0.0001 taiKSM | `AssetRegistry` registered the metadata info of this type token. ### ForeignAsset | Symbol | Description | CurrencyId | Decimals | Minimal Balance | | ------ | ------------------------- | --------------- | -------- | --------------- | | RMRK | RMRK | ForeignAsset(0) | 10 | 0.01 RMRK | | ARIS | PolarisDAO | ForeignAsset(1) | 8 | 0.001 ARIS | | QTZ | Quartz | ForeignAsset(2) | 18 | 1 QTZ | | MOVR | Moonriver | ForeignAsset(3) | 18 | 0.001 MOVR | | HKO | Heiko | ForeignAsset(4) | 12 | 0.1 HKO | | CSM | Crust Shadow Native Token | ForeignAsset(5) | 12 | 1 CSM | | KICO | KICO | ForeignAsset(6) | 14 | 1 KICO | | USDT | Tether USD | ForeignAsset(7) | 6 | 0.01 USDT | Tokens originated from other parachains. `AssetRegistry` registered the metadata info of this type token. ## Query token's metadata on assetRegistry ![query asset metadata](/files/q9lKbCSmsE2J8pzAfpyk) * **Native Network Token** * KAR * **Native Protocol Tokens** * LKSM: tokenized staked KSM from the Liquid Staking protocol * kUSD: multi-collateralized stablecoin * **Foreign Tokens** * KSM: crossed to Karura from Kusama Relay Chain * Tokens originated from other parachains * Tokens crossed from other blockchains such as ETH, renBTC or Compound CASH * **ERC20 Tokens** * Token issued by ERC20 contracts deployed in Karura EVM ## Tools * JS/TS SDK: * Blockchain explorer: * api-sidecar: * txwrapper: * SubQuery: ## Token balances Query chain state to get token balances. ### Native token (KAR) balances Query `system` module to get native token (KAR) balances data. #### system.account * Returns the `AccountInfo` of given account. For different types of balances, check the fields in `AccountInfo.data` * `free`: the free balance. * `reserve`: the reserved balance. ### Other tokens For non-native tokens, like KSM, LKSM, kUSD, query `tokens` module to get balances info. #### tokens.accounts * Returns the `OrmlAccountData` of given account and currency ID. For different types of balances, check the fields: * `free`: the free balance. * `reserved`: the reserved balance. #### tokens.lock * Returns the `BalanceLock` of given account and currency ID. `BalanceLock` has two fields: * `id`: the lock identifier. * `amount.` the locked amount. * Note locks could be overlapped, and the same amount of tokens could be under locked by multiple locks. ## Send Tokens ### Transactions #### currencies.transfer * * This can be used to send any supported tokens in the network, including KAR, KSM, LKSM, kUSD etc. #### currencies.transferNativeCurrency * * This can be used to send native token (KAR). It has slightly cheaper transaction fees compare to currencies.transfer #### balances.transfer * * Same as `currencies.transferNativeCurrency`, only for native token (KAR). * Compatible with Polkadot / Kusama and most other Substrate-based chains. #### xtokens transfer by XCM * ORML's [Xtokens Module](https://github.com/open-web3-stack/open-runtime-module-library/blob/master/xtokens) supports token transfer by cross-consensus messages (XCM), and has a number of dispatchable functions to support different use cases. * **xtokens transfer functions:**\ xtokens.transfer\ xtokens.transfer\_multiasset\ xtokens.transfer\_with\_fee xtokens.transfer\_multiasset\_with\_fee xtokens.transfer\_multicurrencies xtokens.transfer\_multiassets * * Can be used to send any supported tokens in the source and destination networks, including ERC20 tokens. ## Receive Tokens There are multiple ways to detect incoming balance transfers: * Monitor events * Subscribe storage changes * Monitor transactions ### Monitor Events Monitoring events is a recommended way to track incoming balance transfers. It can handle **ALL** types of transfer transactions including the one that is not initiated by a transaction directly (e.g. delayed proxy). #### balances.transfer * * Emitted when a native token (KAR) transfer happened. #### currencies.transfer * * Emitted when a token transfer happened. * NOTE: This is not emitted when balances.transfer is used to make a transfer. #### currencies.deposit * * Emitted when a token is minted to an account. This could happen when it is a cross-chain transfer or it is a transaction minting stablecoins. * For cross-chain transfer, there would be `ExecutedDownward` event along with the deposit. #### xtokens.transferredmultiassets * * Emitted when a cross-chain transfer happened from Karura to other chains. * Triggered by`xtokens.transfer, xtokens.transfer_multiasset, xtokens.transfer_with_fee, xtokens.transfer_multiasset_with_fee, xtokens.transfer_multicurrencies, xtokens.transfer_multiassets` extrinsics . ### Storage changes RPC * [state\_subscribeStorage](https://polkadot.js.org/docs/substrate/rpc#subscribestoragekeys-vecstoragekey-storagechangeset) * Subscribe to a list of account balances. However, it does not guarantee subscription delivery due to connection errors or blockchain reorg. ### Monitor Transactions It is possible to fetch transactions in every block, check for transfer transactions, and check if the transfer transaction is successful. However, this may likely yield false-negative results i.e. deposit received but failed to recognize, due to the various ways for transfer. Refer to Send Tokens section for direct transfer transactions. In additional, to sending transfer transactions individually, there are common utility methods to batch send transfer transactions: #### utility.batch * * This can be used to send batch transaction * NOTE: batched transactions will always emit success events. * `utility.BatchCompleted` event indicates that all transactions are successful * `utility.BatchInterrupted` event indicates which transaction failed. Transactions before the failed transaction are executed successfully and will not be reverted. #### utility.batchAll * * This is similar to utility.batch but will revert all transactions upon failed transaction. ## [Transfer Code Samples](https://github.com/AcalaNetwork/acala-js-example/blob/21a3be3538260cc8a047856bf163dad75de1db3a/src/transfer-examples/readme.md) # Node Interaction ### WebSocket RPC Endpoints * `wss://karura-rpc.n.dwellir.com` * `wss://karura.api.onfinality.io/public-ws` * `wss://rpc-karura.luckyfriday.io` * `wss://karura-rpc.aca-api.network` ### HTTPS RPC Endpoints * `https://karura-rpc.n.dwellir.com` * `https://rpc-karura.luckyfriday.io` * `https://karura-rpc.aca-api.network` # Full Node ## Spec Requirement You can check if your machine satisfy the spec requirement by using the following make command to benchmark your machine. ``` // If you are running docker image: docker run acala/acala-node:latest benchmark machine --chain=karura // If you are using dev environment: make benchmark-machine ``` Note: You need to setup your dev environment first for make commands to work. The benchmark result will look similar to this: ![](/files/Gkv7rhQI8OY3Ge3nJexo) ## Run from Source Code * Clone the repo: * Checkout tag here: \ Install dependencies using instructions from [here](https://github.com/AcalaNetwork/acala-node?tab=readme-ov-file#building) * Build Karura: `cargo build --release` * Run `./target/release/acala --chain=karura` ## Using Docker * Image: `acala/acala-node:latest` or `acala/acala-node:[version number]` * `docker run acala/acala-node:latest --chain=karura` ## Common CLI * CLI is mostly the same as any Substrate-based chain such as Polkadot and Kusama * Because there are two node services are running, `--` is used to split the CLI. Arguments before `--` are passed to the parachain full-node service and arguments after `--` is passed to the Relay Chain full-node service. * For example `--chain=parachain.json --rpc-port=9944 -- --chain=relaychain.json --rpc-port=9945` means * The parachain service is using `parachain.json` as the chain spec and the web socket RPC port is 9944 * The Relay Chain service is using `relaychain.json` as the chain spec and the web socket RPC port is 9945 * It is recommended to explicitly specify the ports for both services to avoid confusion * For example `--listen-addr=/ip4/0.0.0.0/tcp/30333 --listen-addr=/ip4/0.0.0.0/tcp/30334/ws -- --listen-addr=/ip4/0.0.0.0/tcp/30335 --listen-addr=/ip4/0.0.0.0/tcp/30336/ws` * It is recommended to add `--execution=wasm` for parachain service to avoid syncing issues. * It is recommended to add `--relay-chain-rpc-url` or `--relay-chain-rpc-urls` for parachain service to avoid fully sync with the relay chain to work, so in general, they will use fewer system resources. ## Example CLI ### Archive PRC Node ``` --base-path=/acala/data --chain=karura --name=rpc-1 --pruning=archive --rpc-external --rpc-cors=all --rpc-port=9944 --rpc-max-connections=2000 --relay-chain-rpc-url=wss://kusama-rpc.publicnode.com ``` # Collator ## Overview Collators maintain parachains by collecting parachain transactions from users and producing state transition proofs for Relay Chain validators. In other words, collators maintain parachains by aggregating parachain transactions into parachain block candidates and producing state transition proofs for validators based on those blocks. While Karura’s network security and consensus (nPoS) are provided by Kusama Relay chain's Validator set, the Collator set of Karura will keep the network alive by collecting parachain transactions for validators to verify them. **Unlike validators, collators has nothing to do with security of the network, by being a parachain, the network is by default trustless and decentralized, and a parachain only needs one honest collator to be censorship-resistant.** Read more on Collators [here](https://wiki.polkadot.network/docs/learn-collator). Karura's Collator node maintains a full-node service for the Kusama Realy Chain, and a full-node service for the Karura network. Each service has its own http/ws RPC endpoints, P2P ports etc. The base path of the Kusama full-node service is located inside of the base path of the Karura full-node service. ## Collator Roll Out Plan Karura takes a phased approach to roll out the Collator operation. Since Collators are non-security critical operation, a parachain only needs one honest Collator to be censorship-resistant, and more collators are not necessarily good e.g. it will slow down the network, the Collator roll-out plan is designed first-and-foremost to ensure network stability and operation. **Current Phase: Private Collator Set** **Phase 0: Private Collator Set**\ The Genesis of the Karura network was launched on 23rd June, 2021. Upon genesis, Karura's network security and the consensus is provided by Kusama Relay Chain's nominated Proof-of-Stake (nPoS) validators. Just like Statemine (the common-good asset parachain on Kusama), Karura's Collators initially will be run by the Acala Foundation, until the Collator software is stable and can be released to the wider community. **Phase 1: Authorized Collator Set (We are here)**\ Through governance approval, Karura will then open the Collator set to an authorized set of collators. While there are no block rewards nor additional incentives for these authorized collators, they are paid a reasonable rate for their node service provisioning by the Acala Foundation. These collators are known reputable node service providers who have a proven track-record of service levels and demonstrated a deep commitment to the network. It is expected that there will be much chaos and software upgrades during this phase still, and these collators are required to work closely with the core dev team to ensure network stability. It is expected that the Karura network will maintain such an authorized Collator Set until the network is fully stabilized, the collator staking module and the reward scheme are fully implemented and audited. **Phase 2: Public Collator Set**\ Through governance approval, Karura will then enable the permissionless election of Collators and enable collator rewards. Due to the fact that Collators are non-security critical, a parachain only needs a small set of Collators to ensure liveness and censorship-resistance, the reward scheme will reflect this accordingly. You can express interest in becoming a collator/liveness provider for the Karura Network (and later Acala Network) by [filling in this form](https://forms.gle/WQesfKVZmJeXov1e9). You can subscribe to the [`Node Operator - Announcement`](https://discord.gg/uWSZWsUcEn) channel on our Discord for updates and breaking changes. ## Collator Node ### Spec Requirement Same as [the Kusama validator node requirement](https://guide.kusama.network/docs/maintain-guides-how-to-validate-kusama/#requirements). ### Run Node Refer to the [Full Node Guide](/integrate/karura/full-node). ### Collator Configuration #### **Key Management** Karura Collator needs Aura session key. RPC `author_rotateKeys` or `author_insertKey` can be used to update session key. #### **Registration** * Karura is currently using the `collectorSelection` pallet from Statemint to handle collator registration. During the authorized Collator set phase, the required candidacy bond will be an unattainably high value to prevent public registration. * Authorized providers will need to submit the public key of the Aura session key for the collator. #### **Machine Spec** Karura Collators need to ensure their machines satisfy the minimum spec requirement for running a full node. See ["Spec Requirement"](/integrate/karura/full-node#spec-requirement) for more details. #### CLI * `--collator` for the parachain part ### **Example CLI** ``` --base-path=/acala/data --chain=karura --name=collator-1 --collator --execution=wasm --relay-chain-rpc-url=wss://kusama-rpc.publicnode.com ``` # EVM+ documentation If you wish to learn more about development in the Acala EVM+, you can do so by visiting the official Acala EVM+ documentation: {% embed url="" %} Acala EVM+ official documentation {% endembed %} # SDKs * Acala.js: * Documentation: * Please also refer to the [documentation of polkadot.js](https://polkadot.js.org/docs/api/). * Types: # Acala Stablecoin To interact with Acala or Karura from Javascript you can use `@polkadot/api` along with `@acala-network/api`. You can learn more about `@polkadot/api` \[here]. (). We do also provide a [Stablecoin SDK](https://github.com/AcalaNetwork/acala.js/tree/master/packages/sdk-loan) which provides more some automation around stablecoins. ## Source Code of Karura Stablecoin ## Read-Only Functions (State queries) These functions only read information from the chain, and thus don't require signing transactions with a private key. Read more about state queries here: [State queries docs](https://polkadot.js.org/docs/api/start/api.query) ### Get Vault for specific Account for given Collateral Type Returns amount of `collateral` and amount of minted stablecoin as `debit` for specific collateral type and account. > Note :warning: `debit` reflects the only amount of minted kUSD. The amount of debt is higher as it includes accumulated interest. To calculate the total amount to payback you need to use `debitExchangeRate` parameter (the example for fetching `debitExchangeRate` is shown below). ```typescript positions(currencyId: CurrencyId, accountId: AccountId): Promise<{collateral: number, debit: number}> ``` **Arguments** | Name | Type | | | ---------- | ---------- | ---------------------------------------------------- | | currencyId | CurrencyId | collateral currency Id | | accountId | AccountId | account to fetch vaults for, can be passed as string | Example: ```typescript const result = await api.query.loans.positions( { TOKEN: "KSM" }, "" ); console.log(result.toHuman()); ``` #### Full code snippet: [loan-examples/get-positions.js](https://github.com/AcalaNetwork/acala-js-example/blob/master/src/loan-examples/get-positions.ts) ### Get total amount of collateral and borrowed kUSD for Collateral Type Returns total amount of `collateral` and amount of borrowed stablecoin as `debit` for specific collateral type. ```typescript totalPositions(currencyId: CurrencyId): Promise<{collateral: number, debit: number}> ``` **Arguments** | Name | Type | | | ---------- | ---------- | --------------------------------------------- | | currencyId | CurrencyId | identificator for currency used as collateral | Example: ```typescript const result = await api.query.loans.totalPositions( { TOKEN: "KSM" } ); console.log(result.toHuman()); ``` #### Full code snippet: [loan-examples/total-positions.ts](https://github.com/AcalaNetwork/acala-js-example/blob/master/src/loan-examples/total-positions.ts) ### Get Risk Parameters for given Collateral type. Each accepted by Karura Collateral Type can have different risk parameters. These values are controlled by Karura Governance. ```typescript collateralParams(currencyId: CurrencyId): Promise<{ maximumTotalDebitValue: number, interestRatePerSec: number, liquidationRatio: number, liquidationPenalty: number, requiredCollateralRatio: number, }> ``` **Arguments** | Name | Type | | | ---------- | ---------- | --------------------------------------------- | | currencyId | CurrencyId | identificator for currency used as collateral | **Return values** | Name | Type | | | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | maximumTotalDebitValue | Number | maximum amount of KUSD that can be borrowed for one vault | | interestRatePerSec | Percent | the percentage of borrowed kUSD to be paid each next block. This amount should be added to `globalInterestRatePerSec` to calculate the debt | | liquidationRatio | Percent | collateral ratio (collateral value / debt value) reaching which the vault gets liquidated | | liquidationPenalty | Percent | penalty that is charged from the vault if the vault gets liquidated | | requiredCollateralRatio | Percent | Minimum collateral ratio till which user can borrow kUSD | Example: ``` const result = await api.query.cdpEngine.collateralParams({ TOKEN: "KSM" }); console.log(result.toHuman()); ``` #### Full code snippet: [loan-examples/collateral-params.ts](https://github.com/AcalaNetwork/acala-js-example/blob/master/src/loan-examples/collateral-params.ts) ### Get Debt Exchange Rate for given collateral type This parameter is used to calculate the debt. The amount of minted kUSD should be multiplied by this parameter. As the Interest rate is accumulated depends on block number, it makes sense to fetch this parameter for a certain block. ```typescript debitExchangeRate(currencyId: CurrencyId): Promise ``` **Arguments** | Name | Type | | | ---------- | ---------- | --------------------------------------------- | | currencyId | CurrencyId | identificator for currency used as collateral | Example: ``` const result = await api.query.cdpEngine.debitExchangeRate.at( '; const debitAdjustment = ; const extrinsic = api.tx.honzon.adjustLoan( currencyId, collateralAdjustment, debitAdjustment ); const hash = await extrinsic.signAndSend(signer); console.log('hash', hash.toHuman()); ``` > Note :warning: the supply amount should be denormalised with KAR decimals for this example #### Full code snippet: [loan-examples/adjustLoan.ts](https://github.com/AcalaNetwork/acala-js-example/blob/master/src/loan-examples/adjustLoan.ts) ### Grants permission for transferring loan Sets permission to transfer caller's loan to another Account (`to`). ```typescript authorize(curencyId: CurrencyId, to: AccountId): Extrinsic ``` Returns `Extrinsic` type that should be signed with a private key. **Arguments** | Name | Type | | | ---------- | ---------- | --------------------------------------------------- | | currencyId | CurrencyId | collateral CurrencyId | | to | AccountId | sets permission to transfer loan for this accountId | **Example**: ```typescript const accountId = ""; const extrinsic = api.tx.honzon.authorize( { TOKEN: "KSM" }, accountId ); const hash = await extrinsic.signAndSend(signer); console.log("hash", hash.toHuman()); ``` #### Full code snippet: [loan-examples/authorize.ts](https://github.com/AcalaNetwork/acala-js-example/blob/master/src/loan-examples/authorize.ts) ### Removes permission for transferring loan Removes permission to transfer caller's loan to another Account (`to`). This method can be used to decline previously given permission. ```typescript unauthorize(curencyId: CurrencyId, to: AccountId): Extrinsic ``` Returns `Extrinsic` type that should be signed with a private key. **Arguments** | Name | Type | | | ---------- | ---------- | ------------------------------------------------------ | | currencyId | CurrencyId | collateral CurrencyId | | to | AccountId | removes permission to transfer loan for this accountId | **Example**: ```typescript const accountId = ""; const extrinsic = api.tx.honzon.unauthorize( { TOKEN: "KSM" }, accountId ); const hash = await extrinsic.signAndSend(signer); console.log("hash", hash.toHuman()); ``` ### Removes permissions for ALL accounts to transfer the vault Removes permission to transfer caller's vault to ALL accounts for all Collateral types. This method can be used to decline previously given permission. ``` unauthorizeAll(): Extrinsic ``` Returns `Extrinsic` type that should be signed with a private key. **Example**: ```typescript const extrinsic = api.tx.honzon.unauthorizeAll(); const hash = await extrinsic.signAndSend(signer); console.log("hash", hash.toHuman()); ``` ### Transfering Vault to another account Transfers Vault to the caller's account if it has permissions (if `authorize` was called previously by `from` account). ``` transferLoanFrom(currency_id, from): Extrinsic ``` Returns `Extrinsic` type that should be signed with a private key. **Arguments** | Name | Type | | | ---------- | ---------- | ---------------------------------------------------- | | currencyId | CurrencyId | collateral CurrencyId | | from | AccountId | transfers collateral from this account to the caller | **Example**: ```typescript const fromAccountId = ""; const extrinsic = api.tx.honzon.transferLoanFrom( { TOKEN: "KSM" }, fromAccountId ); const hash = await extrinsic.signAndSend(signer); console.log("hash", hash.toHuman()); ``` ### Closing caller's Vault by swapping collateral in DeX This action can be done with `adjustLoan`, but there is a shortcut created for this purpose which is applied only to safe vaults (where the collateral ratio is above liquidation level) and where the debt amount is positive. This method closes the caller's Vault by selling a sufficient amount of collateral on Karura Dex. ```typescript closeLoanHasDebitByDex( currency_id: CurrencyId, max_collateral_amount: number, maybe_path?: CurrencyId[] ): Extrinsic ``` Returns `Extrinsic` type that should be signed with a private key. **Arguments** | Name | Type | | | ----------------------- | ------------- | -------------------------------------------------------------------------------- | | currencyId | CurrencyId | collateral CurrencyId | | max\_collateral\_amount | number | the maximum collateral that's allowed to be swapped in DeX to pay back the Vault | | maybe\_path | CurrencyId\[] | swap path that can be used for swapping collateral for kUSD in DeX | **Example**: ```typescript const extrinsic = api.tx.honzon.closeLoanHasDebitByDex( { TOKEN: "KSM" }, // large number, allows swapping almost any amount 1 * 10 ** 30, [{ TOKEN: "KSM" }, { TOKEN: "KUSD" }] ); const hash = await extrinsic.signAndSend(signer); console.log("hash", hash.toHuman()); ``` #### Full code snippet: [loan-examples/close-vault-with-dex.ts](https://github.com/AcalaNetwork/acala-js-example/blob/master/src/loan-examples/close-vault-with-dex.ts) # Homa Liquid Staking To interact with Acala or Karura from Javascript you can use `@polkadot/api` along with `@acala-network/api`. For those looking to stake DOT or unstake LDOT, we also offer the [Homa SDK](https://github.com/AcalaNetwork/acala.js/tree/master/packages/sdk-homa). ## Homa Example The following example demonstrates how to utilize the Homa SDK and the Polkadot API for staking DOT and unstaking LDOT. You can fork the [live example](https://replit.com/@xlc/acalajs-examples#index.js) on replit and run the example yourself. {% hint style="warning" %} To run the example on replit, you neeed to first fork it, otherwise it will only show an empty webview page. Actual result will be logged to console instead of the webview page, only after you fork it. {% endhint %} ### prepare env, api, and sdk first import deps ```ts const { fetchConfig, setupWithServer } = require('@acala-network/chopsticks') const { ApiPromise, WsProvider } = require('@polkadot/api') const { Homa, Wallet } = require('@acala-network/sdk') const { createTestKeyring } = require('@polkadot/keyring') ``` use Chopsticks to fork mainnet to a local testnet ```ts const acalaConfig = await fetchConfig('acala') acalaConfig.port = 8111 // set the port acalaConfig.block = 4286000 acalaConfig.db = './db.sqlite' const { chain, listenPort, close } = await setupWithServer(acalaConfig) // This server can be accessed at wss://acalajs-examples--xlc.repl.co/ // Use https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Facalajs-examples--xlc.repl.co to connect to this testnet console.log('Chopsticks is running on port', listenPort) ``` ``` ------------------------------------------- console ------------------------------------------- INFO (14701): Loading config file https://raw.githubusercontent.com/AcalaNetwork/chopsticks/master/configs/acala.yml 2023-08-23 14:22:26 REGISTRY: Unknown signed extensions SetEvmOrigin found, treating them as no-effect Chopsticks is running on port 8111 INFO (rpc/14701): Acala RPC listening on port 8111 ``` setup Acala api connect to the local testnet ```ts const provider = new WsProvider(`ws://localhost:${listenPort}`) const api = new ApiPromise({ provider, noInitWarn: true }) await api.isReady ``` add a couple helpers ```js // send a transaction and wait for it to be included const sendTxAndWait = (tx) => { return new Promise((resolve) => { tx.send((status) => { if (status.isInBlock || status.isFinalized) { resolve(status.events) } }) }) } // sign tx with a mock signature that will be accepted by Chopsticks // so we can act on behalf of any accounts without the private key // this requires mockSignatureHost to be enabled const fakeSign = (tx, addr, nonce) => { const mockSignature = new Uint8Array(64) mockSignature.fill(0xcd) mockSignature.set([0xde, 0xad, 0xbe, 0xef]) tx.signFake(addr, { nonce, genesisHash: api.genesisHash, runtimeVersion: api.runtimeVersion, blockHash: api.genesisHash, }) // update fake signature tx.signature.set(mockSignature) return tx } ``` setup wallet sdk and homa sdk ```ts const wallet = new Wallet(api) await wallet.isReady const homa = new Homa(api, wallet) await homa.isReady ``` query some info ```ts // treasury address const address = '23M5ttkmR6KcoTAAE6gcmibnKFtVaTP5yxnY8HF1BmrJ2A1i' console.log('Address', address) const ldot = { Token: 'LDOT' } // check LDOT balance const balance = await api.query.tokens.accounts(address, ldot) const free = balance.free.toNumber() console.log('LDOT Balance:', free / 10 ** 10) // get exchange rate const exchangeRate = (await homa.getEnv()).exchangeRate.toNumber() console.log('Exchange Rate:', exchangeRate) // calculate DOT amount const dotAmount = free * exchangeRate console.log('DOT amount:', dotAmount / 10 ** 10) ``` ``` ------------------------------------------- console ------------------------------------------- Address 23M5ttkmR6KcoTAAE6gcmibnKFtVaTP5yxnY8HF1BmrJ2A1i LDOT Balance: 21.1962713105 Exchange Rate: 0.13037338530710973 DOT amount: 2.7634296466378525 ``` ### stake DOT ```ts // Bob const testaddr = '246gNkjCexYRsCpdjtVhz35sHjcb21jpqipzT9u4uwKV8iEE' // use Chopsticks to mint this user some ACA and DOT await api.rpc('dev_setStorage', { System: { Account: [ [ // key [testaddr], // value { providers: 2, // 1 for ACA, 1 for DOT data: { free: 1000 * 1e12 // 1000 ACA } } ] ] }, Tokens: { Accounts: [ [ // key [ testaddr, { Token: 'DOT' } ], // value { free: 100 * 10e10 // 100 DOT } ] ] } }) { // create tx to use 100 DOT to mint LDOT const tx = api.tx.homa.mint(100 * 10e10) fakeSign(tx, testaddr, 0) console.log('\nSend tx to use 100 DOT to mint LDOT') const events = await sendTxAndWait(tx) console.log('tx events', events.map(x => x.event.toHuman())) } const ldotBalance = (await api.query.tokens.accounts(testaddr, ldot)).free.toNumber() console.log('\nMinted', ldotBalance / 1e10, 'LDOT') ``` ``` ------------------------------------------- console ------------------------------------------- Send tx to use 100 DOT to mint LDOT INFO (block-builder/14701): Try building block #4,286,001 number: 4286001 extrinsicsCount: 1 umpCount: 0 tx events [ ] Minted 7667.5245218183 LDOT ``` ### unstake LDOT There are number of ways to unstake LDOT / convert it back to DOT 1. Slow unstake by wait for 28 days. 2. Use fast redeem by matching with new stakers. A fast redeem fee is charged. This is only available if there are DOT in the pending pool. 3. Use the Taiga tDOT pool to swap LDOT to DOT. A swap fee is charged. The swap rate depends on the pool balance #### slow unstake ```ts // unstake half const unstakeAmount = Math.floor(ldotBalance / 2) { // create tx to unstake without fast redeem. i.e. wait for 28 days unstaking period const tx = api.tx.homa.requestRedeem(unstakeAmount, false /* true to allow fast redeem if possible */) fakeSign(tx, testaddr, 1) console.log('Send tx to unstake', unstakeAmount / 1e10, 'LDOT') const events = await sendTxAndWait(tx) console.log('tx events', events.map(x => x.event.toHuman())) } // the redeem request is still pending and not yet enacted on relaychain const pendingRedeemLDOT = (await api.query.homa.redeemRequests(testaddr)) console.log('\nPending redeem LDOT amount', pendingRedeemLDOT.toHuman()) const keyring = createTestKeyring() const sudoKey = keyring.getPair('5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY') // Alice // simulate relaychain era bump // this will trigger XCM to do unstake on relaychain await sendTxAndWait(await api.tx.sudo.sudo(api.tx.homa.forceBumpCurrentEra(1)).signAsync(sudoKey)) const unbondings = await api.query.homa.unbondings.entries(testaddr) console.log('\nUnbonding requests', unbondings.map(([key, value]) => [key.toHuman(), value.toHuman()])) // bump 28 era so that the DOT is available for withdraw await sendTxAndWait(await api.tx.sudo.sudo(api.tx.homa.forceBumpCurrentEra(28)).signAsync(sudoKey)) await sendTxAndWait(fakeSign(api.tx.homa.claimRedemption(testaddr /* any account can trigger redeem */), testaddr, 2)) const dotBalance = (await api.query.tokens.accounts(testaddr, { token: 'DOT'})).free.toNumber() console.log('\nRedeemed', dotBalance / 1e10, 'DOT') ``` ``` ------------------------------------------- console ------------------------------------------- Send tx to unstake 3833.7622609091 LDOT INFO (block-builder/14701): Block built number: 4286001 hash: "0xaaec1a0bc862a76af6b53bcc60c7b62256487cce5c468828360950491d281d7f" extrinsics: [ "0xbd0184008eaf04151687736326c9fea1…cdcdcdcd00000074000b00a0724e1809" ] pendingExtrinsicsCount: 0 ump: {} INFO (block-builder/14701): Try building block #4,286,002 number: 4286002 extrinsicsCount: 1 umpCount: 0 tx events [ ] Pending redeem LDOT amount [ '38,337,622,609,091', false ] INFO (block-builder/14701): Block built number: 4286002 hash: "0xed20da2f91d4a5f2d3104c2c25bd3005d965a4837e0ccb90f9bba865b6b0c2fd" extrinsics: [ "0xc10184008eaf04151687736326c9fea1…cdcdcd00040074010bc38c602cde2200" ] pendingExtrinsicsCount: 0 ump: {} INFO (block-builder/14701): Try building block #4,286,003 number: 4286003 extrinsicsCount: 1 umpCount: 0 Unbonding requests [ [ [ '246gNkjCexYRsCpdjtVhz35sHjcb21jpqipzT9u4uwKV8iEE', '1,205' ], '4,999,981,935,420' ] ] INFO (block-builder/14701): Block built number: 4286003 hash: "0xece387f4671b9245969411be150f01958642c28b8e663c8b374dc24941e361d4" extrinsics: [ "0xbd018400d43593c715fdd31c61141abd…6d6e0a8924010000ff00740801000000" ] pendingExtrinsicsCount: 0 ump: {} INFO (block-builder/14701): Try building block #4,286,004 number: 4286004 extrinsicsCount: 1 umpCount: 0 INFO (block-builder/14701): Block built number: 4286004 hash: "0x6509c89c4bb36e7181a0d0016ec80c74bed40faa967b0179d7c149d0e0212baf" extrinsics: [ "0xbd018400d43593c715fdd31c61141abd…e53ea68134010400ff0074081c000000" ] pendingExtrinsicsCount: 0 ump: {} INFO (block-builder/14701): Try building block #4,286,005 number: 4286005 extrinsicsCount: 1 umpCount: 0 Redeemed 499.998193542 DOT ``` #### swap with taiga tDOT pool use aggregatedDex to perform swap, which allow multiple step swap with both Taiga pool and Acala Dex pool in a single tx ```ts const tx = api.tx.aggregatedDex.swapWithExactSupply( [{Taiga: [/*pool id*/ 0, /*supply asset*/1, /*target asset*/0]}], unstakeAmount, 0 // should always set a min target to prevent unexpected result ) fakeSign(tx, testaddr, 3) console.log('Send tx to swap', unstakeAmount / 1e10, 'LDOT') const events = await sendTxAndWait(tx) console.log('tx events', events.map(x => x.event.toHuman())) ``` ``` ------------------------------------------- console ------------------------------------------- Send tx to swap 3833.7622609091 LDOT INFO (block-builder/14701): Block built number: 4286005 hash: "0xf62a24768622c45aca7411c77df101dffb934f2a4d63dfd19dc3ff795e008f71" extrinsics: [ "0x210284008eaf04151687736326c9fea1…87613693c912909cb226aa4794f26a48" ] pendingExtrinsicsCount: 0 ump: {} INFO (block-builder/14701): Try building block #4,286,006 number: 4286006 extrinsicsCount: 1 umpCount: 0 tx events [ ] INFO (block-builder/14701): Block built number: 4286006 hash: "0xcd8e6b58affca45dae23d1321cf0ff22897d0ae8782c6703bcf31ccba8a0accb" extrinsics: [ "0xf90184008eaf04151687736326c9fea1…01000000000000000bc38c602cde2200" ] pendingExtrinsicsCount: 0 ump: {} ``` #### clean up shutdown the Chopsticks server ```ts await close() ``` ## More References * Homa source code can be found [here](https://github.com/AcalaNetwork/Acala/tree/master/modules/homa). * You can learn more about `@polkadot/api` [here](https://polkadot.js.org/docs/api). * [chopsticks doc](https://github.com/AcalaNetwork/chopsticks#chopsticks) # Guides # Node Interaction This page will guide you through some basic interactions with your node. This page will guide you through some basic interactions with your node. Always refer to the proper documentation for the tool you are using. This guide should *guide you to the proper tools,* not be seen as canonical reference. * [Substrate RPC API](https://crates.parity.io/sc_rpc_api/index.html) * [Polkadot JS RPC Documentation](https://polkadot.js.org/docs/api/) * [Substrate API Sidecar](https://github.com/paritytech/substrate-api-sidecar) ### RPC The Substrate Chain client exposes HTTP and WS endpoints for RPC connections. The default ports are 9933 for HTTP and 9944 for WS. To get a list of all RPC methods, the node has an RPC endpoint called `rpc_methods`. For example: ``` $ curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "rpc_methods"}' http://localhost:9933/ {"jsonrpc":"2.0","result":{"methods":["account_nextIndex","author_hasKey","author_hasSessionKeys","author_insertKey","author_pendingExtrinsics","author_removeExtrinsic","author_rotateKeys","author_submitAndWatchExtrinsic","author_submitExtrinsic","author_unwatchExtrinsic","chain_getBlock","chain_getBlockHash","chain_getFinalisedHead","chain_getFinalizedHead","chain_getHead","chain_getHeader","chain_getRuntimeVersion","chain_subscribeAllHeads","chain_subscribeFinalisedHeads","chain_subscribeFinalizedHeads","chain_subscribeNewHead","chain_subscribeNewHeads","chain_subscribeRuntimeVersion","chain_unsubscribeAllHeads","chain_unsubscribeFinalisedHeads","chain_unsubscribeFinalizedHeads","chain_unsubscribeNewHead","chain_unsubscribeNewHeads","chain_unsubscribeRuntimeVersion","offchain_localStorageGet","offchain_localStorageSet","payment_queryInfo","state_call","state_callAt","state_getChildKeys","state_getChildStorage","state_getChildStorageHash","state_getChildStorageSize","state_getKeys","state_getKeysPaged","state_getKeysPagedAt","state_getMetadata","state_getPairs","state_getRuntimeVersion","state_getStorage","state_getStorageAt","state_getStorageHash","state_getStorageHashAt","state_getStorageSize","state_getStorageSizeAt","state_queryStorage","state_subscribeRuntimeVersion","state_subscribeStorage","state_unsubscribeRuntimeVersion","state_unsubscribeStorage","subscribe_newHead","system_accountNextIndex","system_addReservedPeer","system_chain","system_health","system_name","system_networkState","system_nodeRoles","system_peers","system_properties","system_removeReservedPeer","system_version","unsubscribe_newHead"],"version":1},"id":1} ``` Add parameters in the call, for example get a block by its hash value: ``` $ curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "chain_getBlock", "params":["0x3fa6a530850324391fde50bdf0094bdc17ee17ec84aca389b4047ef54fea0037"]}' http://localhost:9933 {"jsonrpc":"2.0","result":{"block":{"extrinsics":["0x280402000b50055ee97001","0x1004140000"],"header":{"digest":{"logs":["0x06424142453402af000000937fbd0f00000000","0x054241424501011e38401b0aab22f4d72ebc95329c3798445786b92ca1ae69366aacb6e1584851f5fcdfcc0f518df121265c343059c62ab0a34e8e88fda8578810fbe508b6f583"]},"extrinsicsRoot":"0x0e354333c062892e774898e7ff5e23bf1cdd8314755fac15079e25c1a7765f06","number":"0x16c28c","parentHash":"0xe3bf2e8f0e901c292de24d07ebc412d67224ce52a3d1ffae76dc4bd78351e8ac","stateRoot":"0xd582f0dfeb6a7c73c47db735ae82d37fbeb5bada67ee8abcd43479df0f8fc8d8"}},"justification":null},"id":1} ``` Some return values may not appear meaningful at first glance. Substrate uses [SCALE encoding](https://substrate.dev/docs/en/knowledgebase/advanced/codec) as a format that is suitable for resource-constrained execution environments. You will need to decode the information and use the chain [metadata](https://substrate.dev/docs/en/knowledgebase/runtime/metadata) (`state_getMetadata`) to obtain human-readable information. #### Tracking the Chain Head Use the RPC endpoint `chain_subscribeFinalizedHeads` to subscribe to a stream of hashes of finalized headers, or `chain_FinalizedHeads` to fetch the latest hash of the finalized header. Use `chain_getBlock` to get the block associated with a given hash. `chain_getBlock` only accepts block hashes, so if you need to query intermediate blocks, use `chain_getBlockHash` to get the block hash from a block number. ### Substrate API Sidecar Parity maintains an RPC client, written in TypeScript, that exposes a limited set of endpoints. It handles the metadata and codec logic so that you are always dealing with decoded information. It also aggregates information that an infrastructure business may need for accounting and auditing, e.g. transaction fees. The sidecar can fetch blocks, get the balance of an address atomically (i.e., with a corresponding block number), get the chain's metadata, get a transaction fee prediction, and submit transactions to a node's transaction queue. If you have any feature/endpoint requests, log an issue in the [repo](https://github.com/paritytech/substrate-api-sidecar). The client runs on an HTTP host. The following examples use python3, but you can query any way you prefer at `http://HOST:PORT/`. The default is `http://127.0.0.1:8080`. #### Fetching a Block Fetch a block using the `block/number` endpoint. To get the chain tip, omit the block number. ``` import requests import json url = 'http://127.0.0.1:8080/block/2077200' response = requests.get(url) if response.ok: block_info = json.loads(response.text) print(block_info) ``` This returns a fully decoded block. In the `balances.transfer` extrinsic, the `partialFee` item is the transaction fee. It is called "partial fee" because the total fee would include the `tip` field. Notice that some extrinsics do not have a signature. These are inherents. > When tracking transaction fees, the `extrinsics.paysFee` value is not sufficient for determining if the extrinsic had a fee. This field only means that it would require a fee if submitted as a transaction. In order to charge a fee, a transaction also needs to be signed. So in the following example, the `timestamp.set` extrinsic does not pay a fee because it is an *inherent,* put in the block by the block author. ``` {'number': '2077200', 'hash': '0x00e4e8bd8ec39e54aa26f01f5af7484d771f810fd7f1f4685a204dbc8fbfe80b', 'parentHash': '0xf4065df1171047819592013770a98fff4b9058a96c4499676b72b1b93f5589e9', 'stateRoot': '0xf1258925262058ef5d9eaaed49bd878e82584356f42aade40b68cdbd219be46c', 'extrinsicsRoot': '0xbd4ea887b1a3cb3068db0524b938a0fb13093584b4e6664b3f121448a871cd3d', 'logs': [{'type': 'PreRuntime', 'index': '6', 'value': ['BABE', '0x02b300000087b5c60f00000000']}, {'type': 'Seal', 'index': '5', 'value': ['BABE', '0x689eddf91f1551f74de96ab0e2e52f41522bd82920cbe595148f873aa6d0541f48cfbb9b281181f2e52141b1c401dde7259634485fdab02cc7b63febe51ff78a']}], 'onInitialize': {'events': []}, 'extrinsics': [{'method': 'timestamp.set', 'signature': None, 'nonce': '0', 'args': ['1588085034000'], 'tip': '0', 'hash': '0x3cb46207ef8fadf3def3400ae2cb2a09b780431a6daf0b9bde15d91aeaf8faa3', 'info': {}, 'events': [{'method': 'system.ExtrinsicSuccess', 'data': [{'weight': '10000000', 'class': 'Mandatory', 'paysFee': True}]}], 'success': True, 'paysFee': True}, {'method': 'finalityTracker.finalHint', 'signature': None, 'nonce': '0', 'args': ['2077197'], 'tip': '0', 'hash': '0x2214831b2a13c75288d2267ebd089fffef82ba99d41f6c319ca06e24facc4d51', 'info': {}, 'events': [{'method': 'system.ExtrinsicSuccess', 'data': [{'weight': '10000000', 'class': 'Mandatory', 'paysFee': True}]}], 'success': True, 'paysFee': True}, {'method': 'parachains.setHeads', 'signature': None, 'nonce': '0', 'args': [[]], 'tip': '0', 'hash': '0xcf52705d1ade64fc0b05859ac28358c0770a217dd76b75e586ae848c56ae810d', 'info': {}, 'events': [{'method': 'system.ExtrinsicSuccess', 'data': [{'weight': '1000000000', 'class': 'Mandatory', 'paysFee': True}]}], 'success': True, 'paysFee': True}, {'method': 'balances.transfer', 'signature': {'signature': '0xf4cd36691d6ceb0a913e9d8409bde34e83761829f2fb25db15052de7ba9a6f7c4c54949f884d59005248c2c8b2951575ad0ae8f3c5d866e147a1771f47d91385', 'signer': 'HUewJvzVuEeyaxH2vx9XiyAPKrpu1Zj5r5Pi9VrGiBVty7q'}, 'nonce': '155', 'args': ['GoJ89MXptpNt1dH4NaZ73YtzknhrYeZcBJ33mifX5BMqoFz', '5000000000000'], 'tip': '0', 'hash': '0xc7b57537e2e63f866083ea22265cb65c846528d76378a3b3490eeada97f83d1d', 'info': {'weight': '200000000', 'class': 'Normal', 'partialFee': '10000000000'}, 'events': [{'method': 'system.NewAccount', 'data': ['GoJ89MXptpNt1dH4NaZ73YtzknhrYeZcBJ33mifX5BMqoFz']}, {'method': 'balances.Endowed', 'data': ['GoJ89MXptpNt1dH4NaZ73YtzknhrYeZcBJ33mifX5BMqoFz', '5000000000000']}, {'method': 'balances.Transfer', 'data': ['HUewJvzVuEeyaxH2vx9XiyAPKrpu1Zj5r5Pi9VrGiBVty7q', 'GoJ89MXptpNt1dH4NaZ73YtzknhrYeZcBJ33mifX5BMqoFz', '5000000000000']}, {'method': 'treasury.Deposit', 'data': ['8000000000']}, {'method': 'balances.Deposit', 'data': ['E58yuhUAwWzhn2V4thF3VciAJU75eePPipMhxWZe9JKVVfq', '2000000000']}, {'method': 'system.ExtrinsicSuccess', 'data': [{'weight': '200000000', 'class': 'Normal', 'paysFee': True}]}], 'success': True, 'paysFee': True}], 'onFinalize': {'events': []}} ``` > The JS number type is a 53 bit precision float. There is no guarantee that the numerical values in the response will have a numerical type. Any numbers larger than `2**53-1` will have a string type. #### Submitting a Transaction Submit a serialized transaction using the `tx` endpoint with an HTTP POST request. ``` import requests import json url = 'http://127.0.0.1:8080/tx/' tx_headers = {'Content-type' : 'application/json', 'Accept' : 'text/plain'} response = requests.post( url, data='{"tx": "0xed0...000"}', # A serialized tx. headers=tx_headers ) tx_response = json.loads(response.text) ``` If successful, this endpoint returns a JSON with the transaction hash. In case of error, it will return an error report, e.g.: ``` { "error": "Failed to parse a tx" | "Failed to submit a tx", "cause": "Upstream error description" } ``` # Transaction Construction This page will discuss the transaction format in Acala and how to create, sign, and broadcast transactions. This page will discuss the transaction format in Polkadot and how to create, sign, and broadcast transactions. Like the other pages in this guide, this page demonstrates some of the available tools. **Always refer to each tool's documentation when integrating.** ### Transaction Format Polkadot has some basic transaction information that is common to all transactions. * Address: The SS58-encoded address of the sending account. * Block Hash: The hash of the checkpoint block. * Block Number: The number of the checkpoint block. * Genesis Hash: The genesis hash of the chain. * Metadata: The SCALE-encoded metadata for the runtime when submitted. * Nonce: The nonce for this transaction.\* * Spec Version: The current spec version for the runtime. * Transaction Version: The current version for transaction format. * Tip: Optional, the tip to increase transaction priority. * Era Period: Optional, the number of blocks after the checkpoint for which a transaction is valid. If zero, the transaction is immortal. \*The nonce queried from the System module does not account for pending transactions. You must track and increment the nonce manually if you want to submit multiple valid transactions at the same time. Each transaction will have its own (or no) parameters to add. For example, the `transferKeepAlive` function from the Balances pallet will take: * `dest`: Destination address * `#[compact] value`: Number of tokens (compact encoding) Once you have all the necessary information, you will need to: 1. Construct an unsigned transaction. 2. Create a signing payload. 3. Sign the payload. 4. Serialize the signed payload into a transaction. 5. Submit the serialized transaction. Parity provides the following tools to help perform these steps. ### Acala JS \[TODO] ### Tx Wrapper If you do not want to use the CLI for signing operations, Parity provides an SDK called [TxWrapper](https://github.com/paritytech/txwrapper) to generate and sign transactions offline. See the [examples](https://github.com/paritytech/txwrapper/tree/master/examples) for a guide. **Import a private key** ``` import { importPrivateKey } from '@substrate/txwrapper'; const keypair = importPrivateKey(“pulp gaze fuel ... mercy inherit equal”); ``` **Derive an address from a public key** ``` import { deriveAddress } from '@substrate/txwrapper'; // Public key, can be either hex string, or Uint8Array const publicKey = “0x2ca17d26ca376087dc30ed52deb74bf0f64aca96fe78b05ec3e720a72adb1235”; const address = deriveAddress(publicKey); ``` **Construct a transaction offline** ``` import { methods } from "@substrate/txwrapper"; const unsigned = methods.balances.transferKeepAlive( { dest: "15vrtLsCQFG3qRYUcaEeeEih4JwepocNJHkpsrqojqnZPc2y", value: 500000000000, }, { address: "121X5bEgTZcGQx5NZjwuTjqqKoiG8B2wEAvrUFjuw24ZGZf2", blockHash: "0x1fc7493f3c1e9ac758a183839906475f8363aafb1b1d3e910fe16fab4ae1b582", blockNumber: 4302222, genesisHash: "0xe3777fa922cafbff200cadeaea1a76bd7898ad5b89f7848999058b50e715f636", metadataRpc, // must import from client RPC call state_getMetadata nonce: 2, specVersion: 1019, tip: 0, eraPeriod: 64, // number of blocks from checkpoint that transaction is valid transactionVersion: 1, }, { metadataRpc, registry, // Type registry } ); ``` **Construct a signing payload** ``` import { methods, createSigningPayload } from '@substrate/txwrapper'; // See "Construct a transaction offline" for "{...}" const unsigned = methods.balances.transferKeepAlive({...}, {...}, {...}); const signingPayload = createSigningPayload(unsigned, { registry }); ``` **Serialize a signed transaction** ``` import { createSignedTx } from "@substrate/txwrapper"; // Example code, replace `signWithAlice` with actual remote signer. // An example is given here: // https://github.com/paritytech/txwrapper/blob/630c38d/examples/index.ts#L50-L68 const signature = await signWithAlice(signingPayload); const signedTx = createSignedTx(unsigned, signature, { metadataRpc, registry }); ``` **Decode payload types** You may want to decode payloads to verify their contents prior to submission. ``` import { decode } from "@substrate/txwrapper"; // Decode an unsigned tx const txInfo = decode(unsigned, { metadataRpc, registry }); // Decode a signing payload const txInfo = decode(signingPayload, { metadataRpc, registry }); // Decode a signed tx const txInfo = decode(signedTx, { metadataRpc, registry }); ``` **Check a transaction's hash** ``` import { getTxHash } from ‘@substrate/txwrapper’; const txHash = getTxHash(signedTx); ``` ### Submitting a Signed Payload There are several ways to submit a signed payload: 1. Signer CLI (`yarn run:signer submit --tx --ws `) 2. [Substrate API Sidecar](https://wiki.polkadot.network/docs/en/build-node-interaction#substrate-api-sidecar) 3. [RPC](https://wiki.polkadot.network/docs/en/build-node-interaction#polkadot-rpc) with `author_submitExtrinsic` or `author_submitAndWatchExtrinsic`, the latter of which will subscribe you to events to be notified as a transaction gets validated and included in the chain. ### Notes Some addresses to use in the examples. See [Subkey documentation](https://substrate.dev/docs/en/knowledgebase/integrate/subkey). ``` $ subkey --network polkadot generate Secret phrase `pulp gaze fuel ... mercy inherit equal` is account: Secret seed: 0x57450b3e09ba4598 ... ... ... ... ... ... ... .. 219756eeba80bb16 Public key (hex): 0x2ca17d26ca376087dc30ed52deb74bf0f64aca96fe78b05ec3e720a72adb1235 Account ID: 0x2ca17d26ca376087dc30ed52deb74bf0f64aca96fe78b05ec3e720a72adb1235 SS58 Address: 121X5bEgTZcGQx5NZjwuTjqqKoiG8B2wEAvrUFjuw24ZGZf2 $ subkey --network polkadot generate Secret phrase `exercise auction soft ... obey control easily` is account: Secret seed: 0x5f4bbb9fbb69261a ... ... ... ... ... ... ... .. 4691ed7d1130fbbd Public key (hex): 0xda04de6cd781c98acf0693dfb97c11011938ad22fcc476ed0089ac5aec3fe243 Account ID: 0xda04de6cd781c98acf0693dfb97c11011938ad22fcc476ed0089ac5aec3fe243 SS58 Address: 15vrtLsCQFG3qRYUcaEeeEih4JwepocNJHkpsrqojqnZPc2y ``` # Build DApps There are 4 ways to build with Acala: 1. [**Build Pallet DApp**](/build/development-guide/deploy-ecosystem-modules): deploy permissioned protocol aka ***runtime modules/pallets on the Acala network***. This is available now with more flexibility for customization & integration. Ren Protocol's Bitcoin bridge gateway is implemented this way. 2. [Build Solidity Smart Contract DApp](/build/development-guide/smart-contracts): deploy permisionless smart contracts using ***Solidity on Acala EVM***. This is fully composable with aggregated cross-chain liquidity like BTC and DOT, and Acala's existing DeFi stack, and is a landing pad for DApps to access the Polkadot ecosystem. Ampleforth is deployed this way. 3. [Bridge Parachains: ](/build/development-guide/composable-chains)build a chain and ***connect with Acala using cross-chain message-passing protocol by Polkadot***. We are connected to multiple parachains including common-good asset chain Statemine, where assets can be freely bridged to our chain for listing and other integrations. If you are also a parachain and are ready to test cross-chain functionalities, please contact us for options. 4. Deploy smart contracts using *Ink!* rust-based native smart contract platform. This is yet to be production-ready and will be made available on Acala later, but if you are interested, feel free to contact us and learn more. Developers, teams, or organizations looking to integrate the aUSD stablecoin and Acala Network can contact the Acala team here to schedule time to discuss the integration: # Deploy Ecosystem Modules Building with Acala at the runtime level using sub-module. Below is a rough guideline for building with Acala at the runtime level using sub-module: 1. Project team sets up a sub-module repo 2. Project team builds & tests locally 3. Project team submits repo for review 4. Acala pulls in the sub-module, deploys on testnet via runtime upgrade 5. Security audit 6. Governance **1. Project Structure** You will be creating a sub-module in your own repo, when it's ready we can pull it into Acala's repo. This allows you to have independence of your codebase and license etc. ``` // on Acala side, folder structure as follows - Acala repo - ecosystem-modules - your-sub-module ``` [Example sub-module](https://github.com/AcalaNetwork/ecosystem-template/tree/f42c127bf10239821e1e7a56565cda4d64cd8d66). You shall create a repo in your organization to be used as sub-module. Your sub-module will be pulled into the [ecosystem-modules](https://github.com/AcalaNetwork/Acala/tree/master/ecosystem-modules) under Acala repo. **2. Local Testing** Fork [Acala repo](https://github.com/AcalaNetwork/Acala), pull your sub-module in, and test locally. **3. Submit code for review** Acala will provide technical support during your development including architectural and technical guidance, as well as sharing available libraries and standards. Once you have completed development, please submit your repo and our tech team will help review and provide feedback before pull into our repo. **4. Testnet Deployment** [Acala Mandala Test Network](broken://pages/8ov3x2LEfWPoXsNBlQOU) is a live no-value testnet to verify new chain logics and functionalities. Your module once passed the review, can be deployed on Mandala via runtime upgrade. **5. Audit** Module level integration in essence changes chain logic to the Acala Network, while it offers project team highest level of flexibility and customization, it also puts responsibility on Acala to ensure the code is secure and fit for purpose, and does no pose unintended consequences to the overall chain operation. Therefore we will perform security audit on modules added to Acala, and we will be in touch when that happens. **6. Governance** Deploying on Karura canary network (connecting to Kusama) and mainnet (connecting to Polkadot) will be decided by respective governance. # Composable Chains Currently, cross-chain message passing and parachains are available on Polkadot/Kusama. Acala/Karura is now launched on Polkadot/Kusama, and is testing cross-chain fungible token transfers, and other functionalities. ## Composable With Acala * Karura is live on Kusama [here](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkusama-rpc.polkadot.io#/parachains) * Acala is live on Polkadot [here](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frpc.polkadot.io#/parachains) ### Background [Polkadot Cross-Consensus Message Format (XCM)](https://github.com/paritytech/xcm-format) is a generic message format that doesn't specify use cases like fungible tokens. Therefore, we need to provide an implementation of the required use case e.g. cross-chain transfer, for parachains to be interoperable with the same context, namely, send/receive fungible assets between parachains, and between relay chain and parachains. We want to keep the same interface for Relay Chain assets (like DOT or KSM), and for native parachains assets (like ACA for Acala or KAR for Karura), and abstract from implementation details making it easy to integrate. The [XCM Fungible Asset Implementation Guide](https://github.com/open-web3-stack/open-runtime-module-library/discussions/385) has laid out cross-chain fungible asset design considerations and discussions, as well as a reference implementation orml-xtokens that Acala and many others are currently adopted and testing. Each parachain has its own fungible token, for parachains who want to do cross chain transfer of its asset and sibling parachain's token, [`orml-xtokens`](https://github.com/open-web3-stack/open-runtime-module-library/tree/master/xtokens) is a reference implementation of XCM for fungible tokens that can help easily doing cross-chain token transfer job. > Note: the reference implementation is by no means definitive, rather it is the starting point for the parachain community to experiment and iterate. Please provide feedback to [`xtokens`](https://github.com/open-web3-stack/open-runtime-module-library/tree/master/xtokens) or the [implementation guide](https://github.com/open-web3-stack/open-runtime-module-library/discussions/385). Parachains have it's own implementation to manage not only local asset, but also foreign asset. Currently, Acala use [asset-registry](https://github.com/AcalaNetwork/Acala/tree/master/modules/asset-registry). Thus, for parachains want to be added to Acala or Karura, please refer to the user guide [here](https://docs.acalaswap.app/developer-guides/create-a-new-token). Other parachain may have different asset management(i.e. use [pallet-assets](https://github.com/paritytech/substrate/tree/master/frame/assets) from substrate) or just manual maintain the assets, but they all use `orml-xtokens` doing cross-chain token transfer. ## Integration Guide ### Step 0 Local Parachain Testnet Checkout README in [Acala main repo](https://github.com/AcalaNetwork/Acala), there're two tools to setup a local parachain testnet environment now: * use parachain-launch which run with docker. Follow [this guide](https://hackmd.io/dhmCATb_QqygCPxkxaDcmA) by @bertstachios. * use polkadot-launch which run with binary build release file. ### Step 1 Integrate `xtokens` module to Support Acala/Karura Tokens To receive tokens issued on Acala's chain(aUSD, ACA, renBTC, LDOT etc) or Karura's chain(kUSD, KAR, LKSM etc), you need to include them in your currency type; and also, to implement currency id conversion. Check [example here](https://github.com/AcalaNetwork/Acala/blob/2.3.1/runtime/acala/src/lib.rs#L1700-L1814) for currency id conversion in Acala runtime. > `CurrencyIdConvert` can convert `CurrencyId` to `MultiLocation` and also convert `MultiLocation` to `CurrencyId`. The former convert is used by orml-xtokens to send xcm to recipient chain, while the later one is used when you received xcm instruction that need to transfer to correct token. ### Step 2 Make your token available in Acala/Karura There is an onboarding procedure to introduce new tokens on Acala/Karura to avoid spam tokens. Acala use [asset-registry](https://github.com/AcalaNetwork/Acala/tree/master/modules/asset-registry) to manage assets, please refer to the user guide [here](https://docs.acalaswap.app/developer-guides/create-a-new-token) to add new tokens on Acala/Karura. ### Step 3 Open HRMP Channel > If you use parachain-launch or polkdot-launch, both tools support initiate hrmp channes when startup local testnet, so the cross-chain token transfer is ready to go. Of course you can manual init hrmp channels by the instructions below. Your chain shall already be connected to Polkadot/Kusama as a parachain. While XCMP (Cross-chain Message Passing) is still being implemented - that is sending cross-chain messages directly to each other without passing through the Relay chain, a stop-gap protocol HRMP (Horizontal Relay-routed Message Passing) is in place. > HRMP has the same interface and functionality as XCMP but is much more demanding on resources since it stores all messages in the Relay Chain storage. When XCMP has been implemented, HRMP is planned to be deprecated and phased out in favor of it. The two parachains will need to open HRMP channel on either side to send and receive cross-chain messages. [Instructions here to open HRMP Channel](/build/development-guide/composable-chains/open-hrmp-channel). ## #ComposableWith All chains on Polkadot/Kusama shall be ***composable with*** each other, from exchanging value to exchanging and altering states. For example, chains can not only transfer values trustlessly, they can also call pallet/smart contract functions of each other e.g. minting PolkaBTC on Interlay chain, transferring PolkaBTC to Acala, and collateralizing it for aUSD all in one transaction. Acala will be composable with the following (potential) parachains. If you have or are implementing `xtokens`, please PR to this Repo to add yourself: * Bifrost * Astar * Interlay * Phala * Moonbeam * Centrifuge * HydraDX * Darwinia * Kilt * Crust * Snowfork * Bit.Country * ... Don't hesitate to contact us if you'd like to try it out, need support, and/or want to run some cross-chain testing together with us! # Open HRMP Channel Refer to this documentation to formulate and send HRMP init open channel request to us. {% embed url="" %} # Open-Web3-Stack & ORML Open Web3 Stack is a common-good collection of libraries to accelerate application development on Substrate. It aims to provide application building blocks that are common for most specialist chains. Open Web3 Stack contains the following repos * **Open Runtime Module Library (ORML)** where we implemented all the commonly used pallets, modules * **Open-web3.js** - frontend SDK for using extended Substrate logic from ORML * **Guardian** - a worker for monitoring and executing certain tasks * **Rococo-community**: a hosted environment for testing parachains and cross-chain communication ### ORML Find out more [here](https://github.com/open-web3-stack/open-runtime-module-library). * [orml-traits](https://github.com/open-web3-stack/open-runtime-module-library/blob/master/traits) * Shared traits including `BasicCurrency`, `MultiCurrency`, `Auction` and more. * [orml-utilities](https://github.com/open-web3-stack/open-runtime-module-library/blob/master/utilities) * Various utilities including `OrderSet`. * [orml-tokens](https://github.com/open-web3-stack/open-runtime-module-library/blob/master/tokens) * Fungible tokens module that implements `MultiCurrency` trait. * [orml-currencies](https://github.com/open-web3-stack/open-runtime-module-library/blob/master/currencies) * Provide `MultiCurrency` implementation using `pallet-balances` and `orml-tokens` module. * [orml-nft](https://github.com/open-web3-stack/open-runtime-module-library/tree/master/nft) * Non-fungible-token module provides basic functions to create and manager NFT(non fungible token) * [orml-oracle](https://github.com/open-web3-stack/open-runtime-module-library/blob/master/oracle) * Oracle module that makes off-chain data available on-chain. * [orml-auction](https://github.com/open-web3-stack/open-runtime-module-library/blob/master/auction) * Auction module that implements `Auction` trait. * [orml-vesting](https://github.com/open-web3-stack/open-runtime-module-library/blob/master/vesting) * Provides scheduled balance locking mechanism, in a *graded vesting* way. * [orml-gradually-update](https://github.com/open-web3-stack/open-runtime-module-library/blob/master/gradually-update) * Provides way to adjust numeric parameter gradually over a period of time. * [orml-xtokens](https://github.com/open-web3-stack/open-runtime-module-library/blob/master/xtokens) * Provides way to do cross-chain assets transfer. * [Step-by-Step guide](https://github.com/open-web3-stack/open-runtime-module-library/wiki/xtokens) to make XCM cross-chain fungible asset transfer available on your parachain * [orml-xcm-support](https://github.com/open-web3-stack/open-runtime-module-library/blob/master/xcm-support) * Provides traits, types, and implementations to support XCM integration. ### Guardian With Guardian, **with mere configuration**, you can set up a number of automatic tasks for monitoring and executing commands for a chain of concern. A task can be `monitoring margin positions` with conditions (if collateral ratio < 110%) then trigger actions (e.g. post warning message to database service, or execute a script to add position). Here're the [examples](https://github.com/open-web3-stack/guardian/tree/master/packages/example-guardian) and relevant [documentation](https://github.com/open-web3-stack/guardian/tree/master/packages/guardian/docs). ### Open-web3.js Open-web3 is a bunch of frontend packages that allow to interact with orml, indexer and oracles. Find out more [here](https://github.com/open-web3-stack/open-web3.js). ### Testnet The TL;DR is, we recommend to use [Chopsticks](https://github.com/AcalaNetwork/chopsticks) and create your own testnet. Chopsticks is a testing client that can fork a Substrate network with ease, with Chopsticks, you can fork Acala (or even two parachains on both sides of a cross-chain transfer) at a specific block height and start interact/test with it. As the 'testnet' is forked when needed, it will have the latest runtime and latest code, you can test with confident that your code will behave the same in production if it is going live now. Get started [here](https://github.com/AcalaNetwork/chopsticks). P.S. In case you are looking for it, Rococo parachain testnet is retired. # Smart Contracts {% content-ref url="/pages/-MRw\_1272yk\_\_RzAfsWF" %} [Get Started](/build/development-guide/smart-contracts/get-started-evm) {% endcontent-ref %} {% content-ref url="/pages/-MS0UTFcdu4mduMbqq1f" %} [Advanced](/build/development-guide/smart-contracts/advanced) {% endcontent-ref %} {% content-ref url="/pages/-MRwMncLimvI9YxVg6SM" %} [Acala EVM+](/learn/acala-evm) {% endcontent-ref %} # Get Started {% content-ref url="/pages/-MRw\_AJ5BTzbO739WArt" %} [Connect to a Node](/build/development-guide/smart-contracts/get-started-evm/connect-to-a-node) {% endcontent-ref %} {% content-ref url="/pages/-MRw\_S4-z5X9K8\_cVbXJ" %} [Polkadot Explorer](/build/development-guide/smart-contracts/get-started-evm/acala-console) {% endcontent-ref %} {% content-ref url="/pages/-MRw\_V3a5tI-uaQ9\_UTE" %} [EVM Playground](/build/development-guide/smart-contracts/get-started-evm/evm-playground) {% endcontent-ref %} {% content-ref url="/pages/-MRw\_XVt24Pjbq-nLWqR" %} [Use Remix](/build/development-guide/smart-contracts/get-started-evm/use-remix) {% endcontent-ref %} {% content-ref url="/pages/-MRw\_ZqgIlILN1yPWQVD" %} [Use Waffle](/build/development-guide/smart-contracts/get-started-evm/use-waffle) {% endcontent-ref %} {% content-ref url="/spaces/-MAz4EenwXLth\_HO\_hmJ-887967055/pages/0puvZZOmwteoepmgwvMR" %} [Use Hardhat](/build/development-guide/smart-contracts/get-started-evm/use-hardhat) {% endcontent-ref %} {% content-ref url="/pages/-MRw\_g1rZqo3VjyytMHC" %} [Deploy Contracts](/build/development-guide/smart-contracts/get-started-evm/deploy-contracts) {% endcontent-ref %} # Connect to a Node To use Acala EVM, you need to connect to an Acala Node. You can either 1. connect to a deployed test network (maintained by Acala) OR 2. run a local Acala test node ## **1. Connect to a deployed test network** Find all available testnet nodes [here](broken://pages/8ov3x2LEfWPoXsNBlQOU#rpc-endpoints). You can use [Polkadot Explorer](/build/development-guide/smart-contracts/get-started-evm/acala-console) to communicate with the node, and [EVM Playground](/build/development-guide/smart-contracts/get-started-evm/evm-playground) to deploy and execute contracts. ## **2. Run a local Acala test node** Alternatively, you can run a local test node. To run your own node, you need to have installed [Docker](https://www.docker.com/) on your machine. If you don’t have it installed, please follow the instructions [here](https://docs.docker.com/get-docker/). To check whether Docker is successfully installed run the command below: ```bash docker version ``` If you receive the version number, you can start your local Acala node with the command below: ```bash docker pull acala/acala-node:latest docker run -it -p 9944:9944 -p 9933:9933 acala/acala-node:latest --dev --ws-external --rpc-external --rpc-cors=all ``` The output of your node should look like this: ![](https://i.imgur.com/EyryyFs.png) # Use MetaMask with EVM+ Instructions on how to connect MetaMask to Acala EVM+ in order to interact with the smart contracts deployed on it. {% hint style="info" %} To connect to a network other than Mandala TC7, replace the values from the detailed instructions with the corresponding values from the bottom of this page. {% endhint %} ## Mandala TC8 In order to be able to interact with the Acala EVM+ in Mandala TC8, you first need to navigate to the **Add network** section of the MetaMask. You can find it at the bottom of the list of available networks after clicking on the currently active network. ![MetaMask => Currently active network => Add network](/files/fv2XPwGeJYbrsBWs5JI4) This should open up a form to add a new network to your MetaMask (you might have to unlock MetaMask before it opens). Once the form is opened, use the following information to add the Mandala TC8 network:
KeyValue
Network nameMandala TC8
New RPC URLhttps://eth-rpc-mandala.aca-staging.network
Chain ID595
Currency symbolACA
Block Explorer URLhttps://blockscout.mandala.acala.network/
![Mandala TC7 connection details](/files/KQDVLA7Ry51kftTnt3qx) Mandala TC8 should now be connected and you should see your ACA balance (if you already have it). ![MetaMask connected to Mandala TC7](/files/w0GeghvyZtZbqtjLl1n2) {% hint style="info" %} You might have to bind your MetaMask account to your Substrate account in order to see your balance. {% endhint %} ## Acala main network
KeyValue
NameAcala
Primary URLhttps://eth-rpc-acala.aca-api.network/
Alternative URLhttps://rpc.evm.acala.network/
Chan ID787
Explorerhttps://blockscout.acala.network/
WS endpoint URLwss://eth-rpc-acala.aca-api.network/ws
SubQL URLhttps://acala-evm-subql.aca-api.network
SymbolACA
## Karura main network
KeyValue
NameKarura
Primary URLhttps://eth-rpc-karura.aca-api.network/
Alternative URLhttps://rpc.evm.karura.network/
Chan ID686
Explorerhttps://blockscout.karura.network/
WS endpoint URLwss://eth-rpc-karura.aca-api.network/ws
SubQL URLhttps://karura-evm-subql.aca-api.network
SymbolKAR
# Setup EVM Account ## **Single Wallet, Single Account Experience** Users can use **one extension/wallet**, and **a single Substrate account** to interact with the Substrate runtime, contracts in EVM, and wasm contracts or a hybrid of these. If a user wants to use a particular Ethereum address, then simply link it with his/her Substrate address (basically proving the user owns both addresses), thereafter the user can just use the Substrate account with [Polkadot{js} extension](https://wiki.polkadot.network/docs/en/learn-account-generation) or alike to sign any Ethereum transactions seamlessly. This allows users to use all functionalities within Acala and cross-chain capabilities without managing multiple accounts or wallets. ## Setup EVM Account A user on Acala will always have a Substrate-based account that enables users to easily navigate multiple blockchains and sign any (EVM and Susbtrate) transactions with a single account. Read more on Acala Substrate Account [here](/get-started/acala-network/acala-account). Follow the guide [here](/get-started/acala-network/acala-account#create-account) or [here](https://wiki.polkadot.network/docs/en/learn-account-generation) to generate a Substrate account. To enable Single Account and use Acala EVM, you either 1. Bind an auto-generated Ethereum address OR 2. Bind an existing Ethereum account to the Substrate account ### **1. Bind an auto-generate EVM Account** A user can generate an EVM address for each Substrate account. The user then can bind the EVM address to the Substrate account, so balances of native tokens e.g. DOT, renBTC, aUSD etc. on the Substrate account, are then available on the EVM address to use. In the Acala EVM, if funds are sent to a Substrate account without an associated EVM address, an EVM address will be automatically generated and bound with the Substrate account. Balances are automatically synchronized between the Substrate account and the associated EVM address. For example, a user teleports 10 renBTC to Acala, his/her balance will be shown in the Substrate account, the balance will also be shown and transferrable in the EVM address. #### EVM Address Generation The EVM Address is generated using the `blake2_256` hash function with a prefix `evm` and the associated Substrate account as input. Check out the source code [here](https://github.com/AcalaNetwork/Acala/blob/master/modules/evm-accounts/src/lib.rs#L185-L186). ``` blake2_256("evm:" ++ account_id)[0..20] ``` #### Claiming the default EVM address Navigate to the [Polkadot.js web app](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Facala-mandala.api.onfinality.io%2Fpublic-ws#/extrinsics). The ability to claim the default EVM address can be found under `Extrinsics` in the `Developer` tab. ![Developer > Extrinsics](/files/OVAkCJFV1XYDllQqaAV4) **Step 1: Select the Polkadot account** If you haven't yet installed the Polkadot{js} extension and created an account, please do so by following the steps [here](https://wiki.polkadot.network/docs/en/learn-account-generation#polkadotjs-browser-plugin). If the account is created and the extension is installed correctly, the account should be available in the `using the selected account` dropdown. In case you have no funds in the Substrate account, please use the #acala-testnet-faucet channel in our [Discord](https://discord.gg/5JJgXKSznc), to get some. You will need the funds to sent the transaction to bind the Substrate and EVM accounts. **Step 2: Select the correct extrinsic** To claim the default EVM address, select `evmAddress` from the `submit the following extrinsic` dropdown and select the `claimDefaultAccount()` option. **Step 3: Claim the account** Using the `Send transaction`, the Substrate wallet should prompt you to sign the transaction. Once the transaction is signed and added to the blockchain, your accounts should be bound. ![Sign and Submit transaction confirmation](/files/7m9JWl615yY45bN8r5i6) **Step 4: Validate the account binding** Once the accounts have been bound, you can validate the binding of the accounts, using the same Polkadot.js web app. The chain state is validated using state queries, which can be found under `Developer` dropdown's `Chain state` option. ![Developer > Chain state](/files/cldQwSdKD6TOb93wa1zz) Select the `evmAccounts` from the `selected state query` dropdown. The `evmAddress(AccountId32)` option should return the EVM address bound to the Substrate account selected in the dropdown below. Pressing the `+` button should query the chain for the associated EVM address and return it: ![Successful query for bound EVM address](/files/sKprUH4bflB75gBBDfCq) ### **2. Bind an Existing Ethereum Account** In any case, if users want to use an existing Ethereum account in Acala EVM, this address will need to be claimed and bound to their Subatrate account. ***One Substrate account can only be associated with one Ethereum address.*** A Substrate address already linked to a generated EVM address can no longer link to an existing Ethereum address and vice versa. Binding an existing Ethereum account requires users to prove they own the Ethereum account private key, by signing a message, include it in a `claim` transaction and send it to the Acala network. #### Step 1: Get the genesis hash * Select the **Metadata** from the **Settings** Section of the [Polkadot App](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fmandala-tc7-rpcnode.aca-dev.network%2Fws#/settings/metadata) * Copy the **Genesis Hash** hex string ![Step 1: Getting the Genesis hash](/files/7jhEIIB2ZjSrBun9XeoT) #### Step 2: Get the Chain ID for your target address * Select the **Developer** tab, then **Chain state** from the dropdown * Select **Constant** and then **evm** from the **constant query** dropdown * Choose **chainId** from the method/action dropdown * Click the **+** button on the right ![Developer > Chain state > Constants > evm > chainId](/files/2DsRBztVD0Jc0It5mFux) #### Step 3: Create the signature of the claim on the [EVM+ Playground](https://evm.acala.network/#/Bind%20Account) 1. Select the right account in Metamask 2. Fill in the **Substrate address**, **Chain id** & **Genesis hash** 3. Click **Sign** & copy the **signature** to the next step ![Step 3: Create the signature of the claim](/files/Vxc9UOthFRPQEIE0z1Mo) #### Step 4: Claim Account on the Developer Section of the [Polkadot App](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fmandala-tc7-rpcnode.aca-dev.network%2Fws#/extrinsics) The **ethAddress** should be the same as your Metamask wallet address that you used above to generate the signature. 1. Select **evmAcounts** from the **extrinsic** dropdown menu 2. Select **claimAccount(ethAddress, ethSignature)** from the method/action dropdown 3. Fill in the **ethAddress** & **ethSignature** 4. Click **Submit Transaction** ![Step 4: Fill in eth address and eth signature](/files/hbycticdvBPiW0IlhCna) #### Step 5: Confirm the bindings 1. Select the **Developer** tab, then **Chain state** from the dropdown 2. Select **Storage** and then **evmAccounts** from the **state query** dropdown 3. Click the **+** button on the right 4. Double check that the **evmAccounts.evmAddresses** is indeed the right one. ![Developer > Chain state > Storage > evmAccounts > evmAddresses](/files/Q3NzdF8hx09xtN6mUOjO) #### Use Cases Below are two potential use cases of binding an existing Ethereum address. **Use Case 1** For example, a DeFi protocol on Ethereum is now expanding its operation to Polkadot, by deploying their contracts on the Acala network. They will this new branch by airdropping tokens to their existing users if they also use the protocols on Acala. The easiest way is to airdrop tokens to existing Ethereum addresses on Acala. Hence users would just bind their current Ethereum address to a Substrate address, use it for any EVM transactions, and receive airdrops. **Use Case 2** For DApps like [Linkdrop](https://linkdrop.io), users are required to sign messages using Ethereum private key. Using Linkdrop on Acala, would require users to claim their existing Ethereum address, and bind it to their Substrate account. Thereafter they can send transactions on behalf of the Ethereum account. # Polkadot Explorer Polkadot Explorer is used to communicate with an Acala Node, where you can query the state of the blockchain e.g. balances of accounts, block information etc., and execute transactions to interact with various runtime modules of the chain e.g. transfer a token, do a token swap on the DeX etc. Open the [Polkadot Explorer](https://polkadot.js.org/apps/). The Console is a generated front-end provided by Polkadot that can connect to various Substrate nodes. To connect the Console to your particular node, open the dropdown menu on the top left corner ![](https://i.imgur.com/8G8Rnbe.png) Open the `Development` section, select `Local Node` to connect to your local Acala node. ![](https://i.imgur.com/TygeyXu.png) Select `Custom` to connect to a deployed node, and paste the Websocket URL to the `custom endpoint` input box. You can find deployed nodes [here](broken://pages/8ov3x2LEfWPoXsNBlQOU#rpc-endpoints). Then click `Switch` on the top, and wait for the page to refresh and connect to the network. If your current endpoint already matches your selection, the `Switch` button will be disabled. ## Check Balance Click the `Developer` tab on the top navigation bar, and select `Chain State` in the dropdown list. ![](https://i.imgur.com/BvFEcsZ.png) To perform a state query and get your account's balance, do the following: 1. Click on the `selected state query`, and select `tokens`. 2. Select the `accounts` storage. 3. Select your account (in the example `Alice` ) from the `AccountId` dropdown. 4. Select `Token` from the `CurrencyId` dropdown, and `DOT` as `Token: TokenSymbol` 5. Press `+` button to initiate the call. ![](https://i.imgur.com/5hdanQC.png) Your account's DOT balance will be shown below. ![](https://i.imgur.com/nOB7L3k.png) # EVM Playground We have created a web application - **Acala EVM Playground** to test various functionalities of Acala EVM. It’s a fork from parity `canvas-ui`. To launch the Playground, please navigate to . By default, the Playground is connected to the Acala test network. It can also be connected it to a local node. If you've used the Playground before, the connection information may be cached. ## Set Up Node Connection Click on the connection tab at the bottom left corner of the Playground. ![](https://i.imgur.com/9qnD9Gq.png) Click on the `Node to connect to` dropdown to choose a node you want to connect to * Select `Local Node` to connect to your local Acala node. * Select `Acala` to connect to deployed Acala test network. * Click `Use custom endpoint` to enter a custom Websocket URL ![](https://i.imgur.com/eHAdxLb.png) ## Check Balance Let’s check the DOT balance of an account. On the left sidebar click `Execute`. A list of native token contracts would appear e.g. DOT, aUSD, ACA, renBTC, etc. These native tokens (including cross-chain assets like renBTC) are exposed as pre-compiled contracts that would otherwise not be available in an EVM. Their supply, balances on accounts and functions are all available in EVM. Select `DOT` and press `Execute` under it. ![](https://i.imgur.com/gGqwRZM.png) 1. Pick your account (in the example `Alice`) from the `Call from Account`. 2. Pick `balanceOf` from `Message to Send`. 3. Notice `EVM Address` under your account, copy and paste it to the `owner: address` argument field. 4. Click the `Call` button to execute. ![](https://i.imgur.com/8XQSarA.png) The `Call results` at the bottom should show your account's DOT balance. ![](https://i.imgur.com/2TNjbUM.png) # Use Remix There are multiple tools you can use to develop and compile Solidity contracts, we'd present two here as options * online web app Remix * Solidity development and testing framework Waffle ## Compile a Solidity Contract using Remix Comment This guide walks through the process of creating and deploying a Solidity-based smart contract to the Acala standalone node using the [Remix](http://remix.ethereum.org/). Remix is one of the commonly used development environments for smart contracts on Ethereum. ## **1. Launch Remix** Navigate to . Under `Environments`, select `Solidity` to configure Remix for Solidity development, then navigate to the `File Explorers` view. Here’s an example to compile an ERC20 contract using Remix. Open Remix and under the `File` section click `New File`. ![](https://i.imgur.com/J9jtCF4.png) In the file explorer in the left window will appear an input, where you write filename: `BasicToken.sol`. ## **2. Compile the Solidity code** Paste the following code into the editor tab that comes up. ``` pragma solidity ^0.7.0; import 'https://github.com/OpenZeppelin/openzeppelin-contracts/blob/release-v3.2.0-solc-0.7/contracts/token/ERC20/ERC20.sol'; // This ERC-20 contract mints the specified amount of tokens to the contract creator. contract BasicToken is ERC20 { constructor(uint256 initialSupply) ERC20("BASICT", "BAT") public { _mint(msg.sender, initialSupply); } } ``` Note: this is a simple ERC-20 contract based on the Open Zeppelin ERC-20 template. On construction, it creates the BasicToken with the symbol BAT, and mints the total initial supply. Below is the editor view. Remix will include all of the Open Zeppelin dependencies and compile the contract. Then select `Solidity compiler` on the sidebar, and press the `Compile BasicToken.sol` button. Remix downloads all of the Open Zeppelin dependencies and compiles the contract. ## **3. Get the ABI File** Navigate back to `File explorers` , in the `artifacts` section find the `BasicToken.json` file. Copy and paste the content and save it locally, this is the ABI file that will be deployed to Acala EVM later. ![](https://i.imgur.com/qzonFHr.png) # Use Waffle There are multiple tools you can use to develop and compile Solidity contracts, we'd present two here as options * online web app Remix * Solidity development and testing framework Waffle ## Compile Solidity Contract using Waffle Comment **Note:** you can skip this section if you compiled the smart contract with Remix. This guide walks through the process of deploying a Solidity-based smart contract to Acala using [Waffle](https://github.com/EthWorks/Waffle). Waffle is one of the most commonly used smart contract development frameworks for Ethereum. ## **1. Check Prerequisites** First, we need to install Node.js (we use v15.x in this example) and the npm package manager. For installation follow guides in the official documentation for your operating system: [install NodeJS](https://nodejs.org/en/download/package-manager/) We can verify that everything installed correctly by querying the version for each package: ``` node -v ``` ``` npm -v ``` Install yarn package manager: ``` npm install --global yarn ``` Check if it's installed correctly: ``` yarn -v ``` ## **2. Using Waffle With Our Examples** We've made it easy by collecting all required dependencies in the [AcalaNetwork/evm-examples](https://github.com/AcalaNetwork/evm-examples) repo. Simply clone the repository and install the dependencies. ``` git clone https://github.com/AcalaNetwork/evm-examples cd evm-examples/erc20 yarn install ``` ## **3. Using Waffle from Scratch (optional)** Alternatively, you can install each library separately as the following: Create a project folder `smart-contract-waffle` ``` mkdir smart-contract-waffle cd smart-contract-waffle ``` Initiate package manager ``` yarn init -y ``` Install all following dependencies ``` yarn add --dev @openzeppelin/contracts@3.3.0 ethereum-waffle@3.2.1 ``` Note: it's recommended to install dependencies with exact versions as specified to avoid breaking changes. Then create a waffle settings file ``` touch waffle.json ``` Paste the following in the `waffle.json` file ``` { "compilerType": "solcjs", "compilerVersion": "0.6.2", "sourceDirectory": "./contracts", "outputDirectory": "./build" } ``` This sets up the solidity compiler with version `0.6.2`, compiles contracts from the `./contracts` folder, and saves the bytecode output and ABI files to `./build` folder. Now create the `./contracts` folder, and add the `BasicToken.sol` contract. ``` mkdir contracts touch contracts/BasicToken.sol ``` Paste the following content into the `BasicToken.sol` file and save. ``` pragma solidity ^0.6.0; import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; // Example class - a mock class using delivering from ERC20 contract BasicToken is ERC20 { constructor(uint256 initialBalance) public ERC20("Basic", "BSC") { _mint(msg.sender, initialBalance); } } ``` ## **4. Compile the Smart Contract** Now compile the contract into ABI and bytecode. Run the following in the terminal ``` yarn waffle ``` ## **5. Get the ABI file** Waffle will then generate the output file `./build/BasicToken.json` into the `./build` folder. Note: this file should be the same as the one created with Remix. Waffle also provides a full suite of testing utilities, check out their documentation and code samples [here](https://github.com/EthWorks/Waffle). # Use Hardhat This example is inpired by the [Getting Started](https://hardhat.org/getting-started/) section of Hardhat Documentation. ## Prerequisites * node * yarn ## Let's create a basic sample project ``` mkdir hardhat && cd hardhat yarn add hardhat yarn hardhat ``` ``` 888 888 888 888 888 888 888 888 888 888 888 888 888 888 888 8888888888 8888b. 888d888 .d88888 88888b. 8888b. 888888 888 888 "88b 888P" d88" 888 888 "88b "88b 888 888 888 .d888888 888 888 888 888 888 .d888888 888 888 888 888 888 888 Y88b 888 888 888 888 888 Y88b. 888 888 "Y888888 888 "Y88888 888 888 "Y888888 "Y888 Welcome to Hardhat v2.6.8 ✔ What do you want to do? · Create a basic sample project ✔ Hardhat project root: · /home/.../hardhat ✔ Do you want to add a .gitignore? (Y/n) · y ✔ Do you want to install this sample project's dependencies with yarn (@nomiclabs/hardhat-waffle ethereum-waffle chai @nomiclabs/hardhat-ethers ethers)? (Y/n) · y ``` ## Add the RPC nodes Add the networks section to the `hardhat.config.js` file inside the `module.exports` like so: ``` module.exports = { solidity: "0.8.4", networks: { development: { url: 'http://localhost:8545', chainId: 595, gasPrice: 429496729610000, // Development built-in default deployment account accounts: ["0xa872f6cbd25a0e04a08b1e21098017a9e6194d101d75e13111f71410c59cd57f"] } } } ``` ## To compile it, simply run: `yarn hardhat compile` ``` Compiling 2 files with 0.8.4 Compilation finished successfully ``` ## You can run your tests with: `yarn hardhat test --network development` ``` Greeter ✓ Should return the new greeting once it's changed (554ms) 1 passing (555ms) ``` ## Next, to deploy the contract we will use a Hardhat script: `yarn hardhat run scripts/sample-script.js --network development` ``` Greeter deployed to: 0x3d3593927228553b349767ABa68d4fb1514678CB ``` ## Going beyond and reading the on-chain data Using the hardhat console, you can interact with your deployed contracts. `yarn hardhat console --network development` ``` Welcome to Node.js v14.18.1. Type ".help" for more information. > const Greeter = await ethers.getContractFactory("Greeter"); undefined > const greeter = await Greeter.attach('0x3d3593927228553b349767ABa68d4fb1514678CB') undefined > await greeter.greet() 'Hello, Hardhat!' ``` # Deploy Contracts The `Acala EVM Playground` is useful to test various functionalities of Acala EVM. It’s a fork from parity `canvas-ui`. ## **1. Setup** To deploy your smart contract you can use our testnet or you can run your local dev node. ### Run your own development network To run your own development network, you can follow the [instructions](https://evmdocs.acala.network/network/network-setup/local-development-network) on setting up your own development network in the official EVM+ documentation. Once your development network is operational, you can connect your EVM wallet to it by using the following parameters:
KeyValue
NameMandala
URLhttp://127.0.0.1:8545
Chain ID595
WS endpoint URLws://127.0.0.1:9944
SymbolACA
You can reference the [instructions](/build/development-guide/smart-contracts/get-started-evm/connect-to-a-node/use-metamask-with-evm+) on how to connect MetaMask to the EVM+ and substitute the values from instructions with the values from above. After your EVM wallet is connected to the Acala EVM+, you can continue to the [EVM playground](https://evm.acala.network/). ### **Deploy to our test network** To deploy to our test network you need to have the [polkadot{.js}](https://polkadot.js.org/extension/) wallet extension installed in your browser. Once you have the extension installed, you can [bind your accounts](https://wiki.acala.network/build/development-guide/smart-contracts/get-started-evm/pages/-MS0RtbrQGjJ3tKqHXlH#2.-bind-an-existing-ethereum-account) with an EVM address and get test network funds from the [Discord faucet](broken://pages/8ov3x2LEfWPoXsNBlQOU#faucet). {% hint style="info" %} **Note:** For the remainder of this page we will assume you are using a local development network. If you are deploying to the test network. {% endhint %} ## **2. Upload Contract ABI & bytecode** To deploy a smart contract using [EVM playgrounds](https://evm.acala.network/), you need to compile your smart contract in your preferred development framework so that you have the ABI bundle available to upload.
How to create an ExampleToken ABI bundle In case you want to use the same smart contract as it is used in this example, you can follow these short instructions on how to create it. First clone the Acala Hardhat tutorials example: ```shell git clone git@github.com:AcalaNetwork/hardhat-tutorials.git ``` Move into the examples repository and into the `token` example: ```shell cd hardhat-tutorials/token ``` Within the example directory, install all of the dependencies and compile the smart contracts: ```shell yarn && yarn build ``` This will compile the `Token` smart contract and create an ABI bundle to the directory `artifacts/contracts/Token.sol/` the bundle file is called `Token.json`.
Upload `ExampleToken` ABI & bytecode file by navigating to . Go to the `Upload` tab. ![EVM playground => Upload](/files/FJXIy2ZWmuGIfThWCx5P) Assign the `Name` of your smart contract. You will be able to identify the smart contract in the `Deploy` tab with it, once it gets uploaded. To upload the ABI bundle itself, you can either drag and drop it into the upload section, or click on the section and select the file. ![EVM playgrounds => Upload => Add file](/files/LAXBuFXM4xrjwtuf9Vbs) Once you have selected the correct ABI bundle, the methods of the smart contract should be displayed. You can verify that the correct methods are listed and press `Upload` to upload the ABI bundle. ## **3. Deploy the Contract** Smart contracts can be deployed under the [Deploy tab](https://evm.acala.network/#/deploy) of the EVM playgrounds. The ABI bundles that you uploaded in the `Upload` tab can be seen here: ![EVM playgrounds => Deploy](/files/OYZEzFChm2SgmDXG4ThH) The methods available for an ABI bundle can be seen by expanding the `ABI` menu. This can be helpful if you have multiple bundles uploaded and you want to be sure that you will be interacting with the right one. ![EVM playgrounds => Deploy => Expand ABI section](/files/yZrmjqMv2XThtWdfDkYT) When you have verified that you are interacting with the ABI bundle that has the correct methods available, you can click `Deploy`, which should open a deployment interface: ![EVM playgrounds => Deploy => Deploy selected ABI bundle](/files/Hj2kQMMOUIPUadojW9Sg) The interface consists of the following components: * Button to connect to your EVM wallet (this is why connecting MetaMask to the EVM+ is a prerequisite for this entry) * Smart contract name, that can be changed, so you can deploy the same ABI bundle multiple times and easily differentiate between them * ABI bundle identifications * Fields to input the smart contract constructor parameters * Value field to determine wether to send some of the native currency with the deploy transaction * Fields to override the [`gas parameters`](https://evmdocs.acala.network/network/gas-parameters) * `Deploy` button to deploy the smart contract once you are satisfied with the deployment parameters ### 1. Connect your EVM wallet Pressing the button will prompt your EVM wallet to connect to the site. You can select the account that you want to use with the EVM playgrounds and connect it. ![](/files/fXX6QVUWMkUHGGkIcNur)![](/files/37mKmTcdDG4bjH06nOin) The selected account should be displayed at the top of the page now: ![Displayed deployment account](/files/NwZg6TazeIwqCLZWkXiK) ### 2. Update the required deployment parameters Depending on the requirements, you can modify the deployment parameters of your smart contract. It is required to fill out the constructor parameters, but modifying other values is optional.
![Filled out deployment values](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAr4HPdeSWiuUx1XzEALT%2Fuploads%2F9wxhZ96rDiIYMPvpYUKb%2Fimage.png?alt=media\&token=9afddcce-b216-42e2-bd55-24a7c0cd5cad) Once the values are filled out and double checked, the smart contract is ready to be deployed. {% hint style="warning" %} The `validUntil` field value has to be higher than the current block number, or the deployment transaction will fail, due to the validator treating it as outdated. You can verify the current block number in a [block explorer](https://evmdocs.acala.network/network/gas-parameters). {% endhint %} ### 3. Deploy the smart contract Once the parameters of deployment are ready, you can deploy the smart contract by pressing the `Deploy` button. This should prompt your EVM wallet to confirm your deployment transaction:
![Confirming the deployment transaction](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAr4HPdeSWiuUx1XzEALT%2Fuploads%2FKRsWktz8uflxQILeGFkm%2Fimage.png?alt=media\&token=c5401b2a-5b30-4770-a1bf-018d1dd3fe2b) Once the transaction is included in a block, the deployed smart contract can be found under `Execute` tab. ## **4. Interact with the Contract** Navigate to the `Execute` tab. Find the deployed `ExampleToken` contract and Click the `Execute` button on the bottom of the "ExampleToken" box. ## **5. Query Balances** To perform a query on an account's balance, do the following steps: 1. Make sure that the account you used to deploy the smart contract is connected to the `EVM playgrounds`. 2. Pick `balanceOf` from the `Message to Send` dropdown. 3. Copy and paste the address of the account that you used to deploy the smart contract to the `account: address` input. ![Filled out balance query](/files/uV8NQLbsjwEVBR8xPuC9) {% hint style="info" %} **Note:** Solidity smart contracts have two types of methods: `views` and `executable` methods. {% endhint %} * `Views` are used to query information from the blockchain without writing data to it. `Views` transactions are free. The Playground uses the `Call` button to indicate this. * `Executable` methods can write data onto the blockchain, and these transactions aren’t free. Click the `Execute` button to execute it. Finally, click `Call` at the bottom, and `Call results` should show the ExampleToken balance of `123456789`. ![Completed balance query](/files/EZWWgJDuIbMPHb1npspn) ## **6. Transfer** Now let's try transferring ExampleTokens to another account. 1. Make sure that the deployer account is connected to the EVM playgrounds. 2. Select `transfer` from the `Message to Send` dropdown. 3. Fill out the `recipient address` input box with another EVM address to which to send the tokens. 4. Enter transfer amount in the `amount: unit256` argument box, note the token has a standard 18 decimals. 5. Click `Execute`. ![Filled out token transaction](/files/uu84il2EFZ1DsRSdoiUw) A notification will pop-up to confirm that the transaction is successfully executed. Now you can check the balances of both of the accounts, and confirm that they have changed. deployer's account: ![Deployer's balance](/files/sypsd07AGXh9ZGXJRpfP) Other account: ![Other account's balance](/files/nKaPxzwUUaa52q4IViH2) # Advanced {% content-ref url="/pages/-MS0UsY3H8lCNtwQj7VQ" %} [Use Native & Cross-chain Tokens](/build/development-guide/smart-contracts/advanced/use-native-tokens) {% endcontent-ref %} {% content-ref url="/pages/-MS0UxL2kKddEFRFtSdF" %} [Upcoming Features](/build/development-guide/smart-contracts/advanced/use-flexi-fee) {% endcontent-ref %} {% content-ref url="/pages/-MS0V4xqSNRS-1z81uLR" %} [Use On-chain Scheduler](/build/development-guide/smart-contracts/advanced/use-on-chain-scheduler) {% endcontent-ref %} {% content-ref url="/pages/-MS0VCxkVGsvROL4\_aJ2" %} [Use Oracle Feeds](/build/development-guide/smart-contracts/advanced/use-oracle-feeds) {% endcontent-ref %} --- [Next Page](/llms-full.txt/1)