diff --git a/.github/linkChecker.ts b/.github/linkChecker.ts index 723c60ae16a..dacc01b084a 100644 --- a/.github/linkChecker.ts +++ b/.github/linkChecker.ts @@ -5,7 +5,7 @@ import { sync as globSync } from 'glob'; const baseUrl = 'http://localhost:3000'; // base url of the website -const whitelist = ["crates.io", "softwaretestinghelp.com", "coinbase.com", "assets.website-files.com", "moralis.io"] // some websites return 404 for head requests, so we need to whitelist them, (fix: pass header -H 'Accept: text/html' and parse text/html) +const whitelist = ["crates.io", "softwaretestinghelp.com", "coinbase.com", "assets.website-files.com", "moralis.io", "1rpc.io"] // some websites return 404 for head requests, so we need to whitelist them, (fix: pass header -H 'Accept: text/html' and parse text/html) // see https://github.com/rust-lang/crates.io/issues/788 interface LinkCheckResult { diff --git a/content/docs/dapps/c-chain-or-avalanche-l1.mdx b/content/docs/dapps/c-chain-or-avalanche-l1.mdx new file mode 100644 index 00000000000..13117e6b554 --- /dev/null +++ b/content/docs/dapps/c-chain-or-avalanche-l1.mdx @@ -0,0 +1,63 @@ +--- +title: C-Chain or Avalanche L1? +description: Learn key concepts to decide when to build on an Avalanche L1 vs. C-Chain. +--- + +In this article, we discuss often-overlooked differentiating characteristics of Avalanche L1s, with a primary focus on EVM-based applications. The goal is to identify the pros and cons of building an app on [C-Chain](/learn/primary-network#c-chain) versus [Subnet-EVM](https://github.com/ava-labs/subnet-evm), and help developers make more informed decisions. + +When to Use an Avalanche L1[​](#when-to-use-a-avalanche-l1 "Direct link to heading") +----------------------------------------------------------------------- + +There are many advantages to running your own Avalanche L1. If you find one or more of these a good match for your project then an Avalanche L1 might be a good solution for you. But make sure to check the reasons to use the C-Chain instead, as some trade-offs involved might make that a preferred solution. + +### We Want Our Own Gas Token[​](#we-want-our-own-gas-token "Direct link to heading") + +C-Chain is an Ethereum Virtual Machine (EVM) chain; it requires the gas fees to be paid in its native token. That is, the application may create its own utility tokens (ERC-20) on the C-Chain, but the gas must be paid in AVAX. In the meantime, [Subnet-EVM](https://github.com/ava-labs/subnet-evm) effectively creates an application-specific EVM-chain with full control over native(gas) coins. The operator can pre-allocate the native tokens in the chain genesis, and mint more using the [Subnet-EVM](https://github.com/ava-labs/subnet-evm) precompile contract. And these fees can be either burned (as AVAX burns in C-Chain) or configured to be sent to an address which can be a smart contract. + +Note that the Avalanche L1 gas token is specific to the application in the chain, thus unknown to the external parties. Moving assets to other chains requires trusted bridge contracts (or upcoming cross Avalanche L1 communication feature). + +### We Want Higher Throughput[​](#we-want-higher-throughput "Direct link to heading") + +The primary goal of the gas limit on C-Chain is to restrict the block size and therefore prevent network saturation. If a block can be arbitrarily large, it takes longer to propagate, potentially degrading the network performance. The C-Chain gas limit acts as a deterrent against any system abuse but can be quite limiting for high throughput applications. Unlike C-Chain, Avalanche L1 can be single-tenant, dedicated to the specific application, and thus host its own set of validators with higher bandwidth requirements, which allows for a higher gas limit thus higher transaction throughput. Plus, [Subnet-EVM](https://github.com/ava-labs/subnet-evm) supports fee configuration upgrades that can be adaptive to the surge in application traffic. + +Avalanche L1 workloads are isolated from the Primary Network; which means, the noisy neighbor effect of one workload (for example NFT mint on C-Chain) cannot destabilize the Avalanche L1 or surge its gas price. This failure isolation model in the Avalanche L1 can provide higher application reliability. + +### We Want Strict Access Control[​](#we-want-strict-access-control "Direct link to heading") + +The C-Chain is open and permissionless where anyone can deploy and interact with contracts. However, for regulatory reasons, some applications may need a consistent access control mechanism for all on-chain transactions. With [Subnet-EVM](https://github.com/ava-labs/subnet-evm), an application can require that “only authorized users may deploy contracts or make transactions.” Allow-lists are only updated by the administrators, and the allow list itself is implemented within the precompile contract, thus more transparent and auditable for compliance matters. + +### We Need EVM Customization[​](#we-need-evm-customization "Direct link to heading") + +If your project is deployed on the C-Chain then your execution environment is dictated by the setup of the C-Chain. Changing any of the execution parameters means that the configuration of the C-Chain would need to change, and that is expensive, complex and difficult to change. So if your project needs some other capabilities, different execution parameters or precompiles that C-Chain does not provide, then Avalanche L1s are a solution you need. You can configure the EVM in an Avalanche L1 to run however you want, adding precompiles, and setting runtime parameters to whatever your project needs. + +When to Use the C-Chain[​](#when-to-use-the-c-chain "Direct link to heading") +----------------------------------------------------------------------------- + +All the reasons for using an Avalanche L1 outlined above are very attractive to developers and might make it seem that every new project should look into launching an Avalanche L1 instead of using the C-Chain. Of course, things are rarely that simple and without trade-offs. Here are some advantages of the C-Chain that you should take into account. + +### We Want High Composability with C-Chain Assets[​](#we-want-high-composability-with-c-chain-assets "Direct link to heading") + +C-Chain is a better option for seamless integration with existing C-Chain assets and contracts. It is easier to build a DeFi application on C-Chain, as it provides larger liquidity pools and thus allows for efficient exchange between popular assets. A DeFi Avalanche L1 can still support composability of contracts on C-Chain assets but requires some sort of off-chain system via the bridge contract. In other words, an Avalanche L1 can be a better choice if the application does not need high composability with the existing C-Chain assets. Plus, the upcoming support for cross Avalanche L1 communication will greatly simplify the bridging process. + +### We Want High Security[​](#we-want-high-security "Direct link to heading") + +The security of Avalanche Primary Network is a function of the security of the underlying validators and stake delegators. Some choose C-Chain in order to achieve maximum security by utilizing thousands of Avalanche Primary Network validators. Some may choose to not rely on the entire security of the base chain. + +The better approach is to scale up the security as the application accrues more values and adoption from its users. And Avalanche L1 can provide elastic, on-demand security to take such organic growth into account. + +### We Want Low Initial Cost[​](#we-want-low-initial-cost "Direct link to heading") + +C-Chain has economic advantages of low-cost deployment, whereas each Avalanche L1 validator is required to validate the Primary Network by staking AVAX (minimum 2,000 AVAX for Mainnet). For fault tolerance, we recommend at least five validators for an Avalanche L1, even though there is no requirement that the Avalanche L1 owner should own all these 5 validators, it still further increases the upfront costs. + +### We Want Low Operational Costs[​](#we-want-low-operational-costs "Direct link to heading") + +C-Chain is run and operated by thousands of nodes, it is highly decentralized and reliable, and all the infrastructure (explorers, indexers, exchanges, bridges) has already been built out by dedicated teams that maintain them for you at no extra charge. Project deployed on the C-Chain can leverage all of that basically for free. On the other hand, if you run your own Avalanche L1 you are basically in charge of running your own L1 network. You (or someone who you partner with or pay to) will need to do all those things and you will ultimately be responsible for them. If you don't have a desire, resources or partnerships to operate a high-availability 24/7 platform, you're probably better off deploying on the C-Chain. + +Conclusion[​](#conclusion "Direct link to heading") +--------------------------------------------------- + +Here we presented some considerations both in favor of running your own Avalanche L1 and in favor of deploying on the C-Chain. You should carefully weigh and consider what makes the most sense for your and your project: deploying on an Avalanche L1 or deploying on the C-Chain. + +But, there is also a third way: deploy on C-Chain now, then move to your own Avalanche L1 later. If an application has relatively low transaction rate and no special circumstances that would make the C-Chain a non-starter, you can begin with C-Chain deployment to leverage existing technical infrastructure, and later expand to an Avalanche L1. That way you can focus on working on the core of your project and once you have a solid product/market fit and have gained enough traction that the C-Chain is constricting you, plan a move to your own Avalanche L1. + +Of course, we're happy to talk to you about your architecture and help you choose the best path forward. Feel free to reach out to us on [Discord](https://chat.avalabs.org/) or other [community channels](https://www.avax.network/community) we run. \ No newline at end of file diff --git a/content/docs/dapps/meta.json b/content/docs/dapps/meta.json index 39f1b02ccc9..ec70d7b1112 100644 --- a/content/docs/dapps/meta.json +++ b/content/docs/dapps/meta.json @@ -4,6 +4,7 @@ "pages": [ "---dApps on Avalanche---", "index", + "c-chain-or-avalanche-l1", "chain-settings", "block-explorers", "---Smart Contract Development---", diff --git a/content/docs/evm-l1s/default-precompiles/rewardmanager.mdx b/content/docs/evm-l1s/default-precompiles/rewardmanager.mdx index 1e2a56292cc..40a55a32138 100644 --- a/content/docs/evm-l1s/default-precompiles/rewardmanager.mdx +++ b/content/docs/evm-l1s/default-precompiles/rewardmanager.mdx @@ -1,4 +1,131 @@ --- title: RewardManager Precompile description: Learn how to use the RewardManager Precompile on your Avalanche L1 blockchain. ---- \ No newline at end of file +--- + + +Fee reward mechanism can be configured with this stateful precompile contract called as `RewardManager`. Configuration can include burning fees, sending fees to a predefined address, or enabling fees to be collected by block producers. This precompile can be configured as follows in the genesis file: + +```json +{ + "config": { + "rewardManagerConfig": { + "blockTimestamp": 0, + "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"] + } + } +} +``` + +`adminAddresses` denotes admin accounts who can add other `Admin` or `Enabled` accounts. `Admin`, `Manager` and `Enabled` are both eligible to change the current fee mechanism. + +The precompile implements the `RewardManager` interface which includes the `AllowList` interface. For an example of the `AllowList` interface, see the [TxAllowList](#allowlist-interface) above. + +The `Stateful Precompile` contract powering the `RewardManager` adheres to the following Solidity interface at `0x0200000000000000000000000000000000000004` (you can load this interface and interact directly in Remix). It can be also found in [IRewardManager.sol](https://github.com/ava-labs/subnet-evm/blob/5faabfeaa021a64c2616380ed2d6ec0a96c8f96d/contract-examples/contracts/IRewardManager.sol): + +```solidity +//SPDX-License-Identifier: MIT +pragma solidity ^0.8.0; +import "./IAllowList.sol"; + +interface IRewardManager is IAllowList { + // RewardAddressChanged is the event logged whenever reward address is modified + event RewardAddressChanged( + address indexed sender, + address indexed oldRewardAddress, + address indexed newRewardAddress + ); + + // FeeRecipientsAllowed is the event logged whenever fee recipient is modified + event FeeRecipientsAllowed(address indexed sender); + + // RewardsDisabled is the event logged whenever rewards are disabled + event RewardsDisabled(address indexed sender); + + // setRewardAddress sets the reward address to the given address + function setRewardAddress(address addr) external; + + // allowFeeRecipients allows block builders to claim fees + function allowFeeRecipients() external; + + // disableRewards disables block rewards and starts burning fees + function disableRewards() external; + + // currentRewardAddress returns the current reward address + function currentRewardAddress() external view returns (address rewardAddress); + + // areFeeRecipientsAllowed returns true if fee recipients are allowed + function areFeeRecipientsAllowed() external view returns (bool isAllowed); +} +``` + +`RewardManager` precompile uses `IAllowList` interface directly, meaning that it uses the same `AllowList` interface functions like `readAllowList` and `setAdmin`, `setEnabled`, `setNone`. For more information see [AllowList Solidity interface](#allowlist-interface). + +In addition to the `AllowList` interface, the `RewardManager` adds the following capabilities: + +- `setRewardAddress`: sets the address to which fees are sent. This address can be a contract or a user address. The address becomes the required coinbase address for the blocks that this mechanism is enabled on. Meaning that it will receive the fees collected from the transactions in the block. Receiving fees will not call any contract functions or fallback functions. It will simply increase the balance of the address by the amount of fees. +- `allowFeeRecipients`: enables block producers to claim fees. This will allow block producers to claim fees by specifying their own addresses in their chain configs. See [here](#fee-recipient) for more information on how to specify the fee recipient address in the chain config. +- `disableRewards`: disables block rewards and starts burning fees. +- `currentRewardAddress`: returns the current reward address. This is the address to which fees are sent. It can include black hole address (`0x010...0`) which means that fees are burned. It can also include a predefined hash (`0x0000000000000000000000000000000000000000`) denoting custom fee recipients are allowed. It's advised to use the `areFeeRecipientsAllowed` function to check if custom fee recipients are allowed first. +- `areFeeRecipientsAllowed`: returns true if custom fee recipients are allowed. +- `RewardAddressChanged`: an event that is emitted when the reward address is updated. Topics include the sender, the old reward address, and the new reward address. +- `FeeRecipientsAllowed`: an event that is emitted when fee recipients are allowed. Topics include the sender. +- `RewardsDisabled`: an event that is emitted when rewards are disabled. Topics include the sender. + +These 3 mechanisms (burning, sending to a predefined address, and enabling fees to be collected by block producers) cannot be enabled at the same time. Enabling one mechanism will take over the previous mechanism. For example, if you enable `allowFeeRecipients` and then enable `disableRewards`, the `disableRewards` will take over and fees will be burned. + +Note that reward addresses or fee recipient addresses are not required to be an admin or enabled account. + +#### Initial Configuration[​](#initial-configuration "Direct link to heading") + +It's possible to enable this precompile with an initial configuration to activate its effect on activation timestamp. This provides a way to enable the precompile without an admin address to change the fee reward mechanism. This can be useful for networks that require a one-time reward mechanism change without specifying any admin addresses. Without this initial configuration, the precompile will inherit the `feeRecipients` mechanism activated at genesis. Meaning that if `allowFeeRecipients` is set to true in the genesis file, the precompile will be enabled with the `allowFeeRecipients` mechanism. Otherwise it will keep burning fees. To use the initial configuration, you need to specify the initial reward mechanism in `initialRewardConfig` field in your genesis or upgrade file. + +In order to allow custom fee recipients, you need to specify the `allowFeeRecipients` field in the `initialRewardConfig`: + +```json +{ + "rewardManagerConfig": { + "blockTimestamp": 0, + "initialRewardConfig": { + "allowFeeRecipients": true + } + } +} +``` + +In order to set an address to receive all transaction rewards, you need to specify the `rewardAddress` field in the `initialRewardConfig`: + +```json +{ + "rewardManagerConfig": { + "blockTimestamp": 0, + "initialRewardConfig": { + "rewardAddress": "0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC" + } + } +} +``` + +In order to disable rewards and start burning fees, you need to leave all fields in the `initialRewardConfig` empty: + +```json +{ + "rewardManagerConfig": { + "blockTimestamp": 0, + "initialRewardConfig": {} + } +} +``` + +However this is different than the default behavior of the precompile. If you don't specify the `initialRewardConfig` field, the precompile will inherit the `feeRecipients` mechanism activated at genesis. Meaning that if `allowFeeRecipients` is set to true in the genesis file, the precompile will be enabled with the `allowFeeRecipients` mechanism. Otherwise it will keep burning fees. Example configuration for this case: + +```json +{ + "rewardManagerConfig": { + "blockTimestamp": 0, + "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"] + } +} +``` + +If `allowFeeRecipients` and `rewardAddress` are both specified in the `initialRewardConfig` field then an error will be returned and precompile won't be activated. For further information about precompile initial configurations see [Initial Precompile Configurations](#initial-precompile-configurations). diff --git a/content/docs/evm-l1s/meta.json b/content/docs/evm-l1s/meta.json index 1f259580aa0..d8a33df6f54 100644 --- a/content/docs/evm-l1s/meta.json +++ b/content/docs/evm-l1s/meta.json @@ -3,6 +3,12 @@ "root": true, "pages": [ "index", + "---Validator Manager---", + "validator-manager/contract", + "validator-manager/add-validator", + "validator-manager/remove-validator", + "validator-manager/upgrade", + "validator-manager/custom-validator-manager", "---Default Precompiles---", "default-precompiles/overview", "default-precompiles/allowlist", @@ -17,12 +23,6 @@ "custom-precompiles/defining-your-precompile", "custom-precompiles/writing-test-cases", "custom-precompiles/executing-test-cases", - "custom-precompiles/deploying-precompile", - "---Validator Manager---", - "validator-manager/contract", - "validator-manager/add-validator", - "validator-manager/remove-validator", - "validator-manager/upgrade", - "validator-manager/custom-validator-manager" + "custom-precompiles/deploying-precompile" ] } \ No newline at end of file diff --git a/content/docs/evm-l1s/validator-manager/contract.mdx b/content/docs/evm-l1s/validator-manager/contract.mdx index 51301323b06..384388c4ba1 100644 --- a/content/docs/evm-l1s/validator-manager/contract.mdx +++ b/content/docs/evm-l1s/validator-manager/contract.mdx @@ -40,7 +40,7 @@ PoSValidatorManager <|-- NativeTokenStakingManager ## Deploying -Three concrete `ValidatorManager` contracts are provided - `PoAValidatorManager`, `NativeTokenStakingManager`, and `ERC20TokenStakingManager`. `NativeTokenStakingManager` and `ERC20TokenStakingManager` implement `PoSValidatorManager`, which itself implements `ValidatorManager`. These are implemented as [upgradeable](https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable/blob/main/contracts/proxy/utils/Initializable.sol#L56) contracts. There are numerous [guides](https://blog.chain.link/upgradable-smart-contracts/) for deploying upgradeable smart contracts, but the general steps are as follows: +Three concrete `ValidatorManager` contracts are provided - `PoAValidatorManager`, `NativeTokenStakingManager`, and `ERC20TokenStakingManager`. `NativeTokenStakingManager` and `ERC20TokenStakingManager` implement `PoSValidatorManager`, which itself implements `ValidatorManager`. These are implemented as [upgradeable](https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable/blob/master/contracts/proxy/utils/Initializable.sol) contracts. There are numerous [guides](https://blog.chain.link/upgradable-smart-contracts/) for deploying upgradeable smart contracts, but the general steps are as follows: @@ -69,7 +69,7 @@ Proof-of-Authority validator management is provided via `PoAValidatorManager`, w ### PoSValidatorManager -Proof-of-Stake validator management is provided by the abstract contract `PoSValidatorManager`, which has two concrete implementations: `NativeTokenStakingManager` and `ERC20TokenStakingManager`. In addition to basic validator management provided in `ValidatorManager`, `PoSValidatorManager` supports uptime-based validation rewards, as well as delegation to a chosen validator. This [state transition diagram](./StateTransition.md) illustrates the relationship between validators and delegators. +Proof-of-Stake validator management is provided by the abstract contract `PoSValidatorManager`, which has two concrete implementations: `NativeTokenStakingManager` and `ERC20TokenStakingManager`. In addition to basic validator management provided in `ValidatorManager`, `PoSValidatorManager` supports uptime-based validation rewards, as well as delegation to a chosen validator. This [state transition diagram](https://github.com/ava-labs/teleporter/blob/main/contracts/validator-manager/StateTransition.md) illustrates the relationship between validators and delegators. The `weightToValueFactor` fields of the `PoSValidatorManagerSettings` passed to `PoSValidatorManager`'s `initialize` function sets the factor used to convert between the weight that the validator is registered with on the P-Chain, and the value transferred to the contract as stake. This involves integer division, which may result in loss of precision. When selecting `weightToValueFactor`, it's important to make the following considerations: diff --git a/content/docs/nodes/on-third-party-services/microsoft-azure.mdx b/content/docs/nodes/on-third-party-services/microsoft-azure.mdx index cbdad85643f..a1f7c2b5f2b 100644 --- a/content/docs/nodes/on-third-party-services/microsoft-azure.mdx +++ b/content/docs/nodes/on-third-party-services/microsoft-azure.mdx @@ -13,8 +13,7 @@ Not only does running a validator node enable you to receive rewards in AVAX, bu Hardware requirements to run a validator are relatively modest: 8 CPU cores, 16 GB of RAM and 1 TB SSD. It also doesn't use enormous amounts of energy. Avalanche's [revolutionary consensus mechanism](/learn/avalanche-consensus) is able to scale to millions of validators participating in consensus at once, offering unparalleled decentralisation. -Currently the minimum amount required to stake to become a validator is 2,000 AVAX. Alternatively, validators can also charge a small fee to enable users to delegate their stake with them to help towards running costs. You can use a calculator [here](https://vscout.io/) to see how much rewards you would earn when running a node, compared to delegating. - +Currently the minimum amount required to stake to become a validator is 2,000 AVAX. Alternatively, validators can also charge a small fee to enable users to delegate their stake with them to help towards running costs. In this article we will step through the process of configuring a node on Microsoft Azure. This tutorial assumes no prior experience with Microsoft Azure and will go through each step with as few assumptions possible. At the time of this article, spot pricing for a virtual machine with 2 Cores and 8 GB memory costs as little as 0.01060perhourwhichworksoutatabout0.01060 per hour which works out at about 113.44 a year, **a saving of 83.76%! compared to normal pay as you go prices.** In comparison a virtual machine in AWS with 2 Cores and 4 GB Memory with spot pricing is around $462 a year. diff --git a/content/integrations/goldrush.mdx b/content/integrations/goldrush.mdx index 92e370d03bf..00bce081f71 100644 --- a/content/integrations/goldrush.mdx +++ b/content/integrations/goldrush.mdx @@ -37,7 +37,6 @@ For detailed guides and API references, visit the [GoldRush Docs](https://goldru - [Accounting and tax tools](https://bit.ly/crypto-tax-tool) - [NFT rendering](https://goldrush-nft-gallery-ui.vercel.app/) - [App onboarding](https://goldrush-wallet-portfolio-ui.vercel.app/activity/0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de/) -- [Custom block explorers](https://goldrush-block-explorer.vercel.app/) ## Conclusion Use GoldRush to build faster. GoldRush helps scale hundreds of projects from crypto native teams to Fortune 500 companies. diff --git a/next.config.mjs b/next.config.mjs index 74ab6e0880c..2e140136001 100644 --- a/next.config.mjs +++ b/next.config.mjs @@ -1009,6 +1009,11 @@ const config = { source: '/virtual-machines/evm-customization/:path*', destination: '/evm-l1s/custom-precompiles/:path*', permanent: true, + }, + { + source: '/avalanche-l1s/c-chain-or-avalanche-l1', + destination: '/dapps/c-chain-or-avalanche-l1', + permanent: true, } ] },