From 9fb007a3c3a362eec497b2ff342cd029809f55fe Mon Sep 17 00:00:00 2001 From: owenwahlgren Date: Fri, 27 Sep 2024 15:12:58 -0400 Subject: [PATCH] update through hash-function-precompile --- .../00-evm-and-precompiles.mdx | 15 --- .../02-intro-to-evm/01-origin-of-evm.mdx | 16 +-- .../02-accounts-keys-address.mdx | 27 ++-- .../03-transactons-and-blocks.mdx | 18 +-- .../05-different-evm-versions.mdx | 23 ++-- .../03-development-env-setup/00-intro.mdx | 2 +- ...odespaces.mdx => 02-create-codespaces.mdx} | 0 .../02-what-is-codespaces.mdx | 46 ------- ...-vscode.mdx => 03-codespace-in-vscode.mdx} | 2 +- .../04-your-evm-blockchain/00-intro.mdx | 22 ++-- .../01-avalanche-cli.mdx | 16 +-- .../00-vm-configuration.mdx | 28 ----- .../04-gas-fees-and-limit.mdx | 33 ----- .../00-vm-configuration.mdx | 28 +++++ .../01-genesis-block.mdx | 11 +- .../02-create-your-genesis.mdx | 0 .../03-setup-chainid.mdx | 4 +- .../04-gas-fees-and-limit.mdx | 33 +++++ .../05-gas-fee-configuration.mdx | 0 .../06-configuring-gas-fees.mdx | 0 .../07-initial-token-allocation.mdx | 2 +- ...uild-and-run-custom-genesis-blockchain.mdx | 2 +- .../01-what-are-precompiles.mdx | 40 +++--- .../06-precompiles/02-why-precompiles.mdx | 26 ++-- .../03-interact-wtih-precompile.mdx | 8 +- .../07-hash-function-precompile/00-intro.mdx | 55 ++++---- .../01-create-solidity-interface.mdx | 4 +- .../02-generate-the-precompile.mdx | 8 +- .../03-unpack-input-pack-output.mdx | 2 +- .../04-implementing-precompile.mdx | 2 +- .../05-configkey-and-contractaddr.mdx | 116 ++++++++--------- .../06-register-precompile.mdx | 49 ++------ ...build-and-run.mdx => 07-build-and-run.mdx} | 6 +- .../07-creating-genesis-block.mdx | 118 ------------------ .../08-interact-with-md5.mdx | 23 ++++ content/course/customizing-evm/index.mdx | 39 +++--- content/course/customizing-evm/meta.json | 4 +- 37 files changed, 328 insertions(+), 500 deletions(-) delete mode 100644 content/course/customizing-evm/02-intro-to-evm/00-evm-and-precompiles.mdx rename content/course/customizing-evm/03-development-env-setup/{03-create-codespaces.mdx => 02-create-codespaces.mdx} (100%) delete mode 100644 content/course/customizing-evm/03-development-env-setup/02-what-is-codespaces.mdx rename content/course/customizing-evm/03-development-env-setup/{04-codespace-in-vscode.mdx => 03-codespace-in-vscode.mdx} (93%) delete mode 100644 content/course/customizing-evm/05-evm-configuration/00-vm-configuration.mdx delete mode 100644 content/course/customizing-evm/05-evm-configuration/04-gas-fees-and-limit.mdx create mode 100644 content/course/customizing-evm/05-genesis-configuration/00-vm-configuration.mdx rename content/course/customizing-evm/{05-evm-configuration => 05-genesis-configuration}/01-genesis-block.mdx (79%) rename content/course/customizing-evm/{05-evm-configuration => 05-genesis-configuration}/02-create-your-genesis.mdx (100%) rename content/course/customizing-evm/{05-evm-configuration => 05-genesis-configuration}/03-setup-chainid.mdx (61%) create mode 100644 content/course/customizing-evm/05-genesis-configuration/04-gas-fees-and-limit.mdx rename content/course/customizing-evm/{05-evm-configuration => 05-genesis-configuration}/05-gas-fee-configuration.mdx (100%) rename content/course/customizing-evm/{05-evm-configuration => 05-genesis-configuration}/06-configuring-gas-fees.mdx (100%) rename content/course/customizing-evm/{05-evm-configuration => 05-genesis-configuration}/07-initial-token-allocation.mdx (94%) rename content/course/customizing-evm/{05-evm-configuration => 05-genesis-configuration}/08-build-and-run-custom-genesis-blockchain.mdx (95%) rename content/course/customizing-evm/07-hash-function-precompile/{08-build-and-run.mdx => 07-build-and-run.mdx} (93%) delete mode 100644 content/course/customizing-evm/07-hash-function-precompile/07-creating-genesis-block.mdx create mode 100644 content/course/customizing-evm/07-hash-function-precompile/08-interact-with-md5.mdx diff --git a/content/course/customizing-evm/02-intro-to-evm/00-evm-and-precompiles.mdx b/content/course/customizing-evm/02-intro-to-evm/00-evm-and-precompiles.mdx deleted file mode 100644 index 32864a55..00000000 --- a/content/course/customizing-evm/02-intro-to-evm/00-evm-and-precompiles.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: The EVM and Precompiles -description: Learn the basics of the EVM and precompiles -updated: 2024-05-31 -authors: [ashucoder9, martineckardt] -icon: Book ---- - -In this section, we will explore the fundamentals of the EVM. - -- [Learn about the origin of the EVM](/course/customizing-evm/02-intro-to-evm/01-origin-of-evm) -- [Become familiar with the concepts of accounts, keys, and addresses](/course/customizing-evm/02-intro-to-evm/02-accounts-keys-address) -- [Understand the principles of transactions and blocks](/course/customizing-evm/02-intro-to-evm/03-transactons-and-blocks) - -Let's get started! 🚀 diff --git a/content/course/customizing-evm/02-intro-to-evm/01-origin-of-evm.mdx b/content/course/customizing-evm/02-intro-to-evm/01-origin-of-evm.mdx index 1a7894a3..64795401 100644 --- a/content/course/customizing-evm/02-intro-to-evm/01-origin-of-evm.mdx +++ b/content/course/customizing-evm/02-intro-to-evm/01-origin-of-evm.mdx @@ -1,17 +1,17 @@ --- title: Origin of the EVM -description: Learn about the origin of Ethereum Virtual Machine (EVM). -updated: 2024-05-31 -authors: [ashucoder9] +description: Learn about the origin of the Ethereum Virtual Machine. +updated: 2024-09-27 +authors: [ashucoder9, owenwahlgren] icon: BookOpen --- -The Ethereum Virtual Machine (EVM) is a key component of Ethereum’s infrastructure, responsible for executing smart contracts across the network. The origins of the EVM can be traced back to the creation of the Ethereum blockchain itself, which was proposed in a whitepaper by Vitalik Buterin in late 2013. +The **Ethereum Virtual Machine (EVM)** is a fundamental component of Ethereum’s infrastructure, responsible for executing smart contracts across the network. The origins of the EVM can be traced back to the creation of the Ethereum blockchain itself, proposed in a whitepaper by **Vitalik Buterin** in late 2013. -Buterin and the founding Ethereum team envisioned a platform where developers could build decentralized applications (dApps) on a blockchain. To accomplish this, they needed a way to execute arbitrary, complex computations in a secure and decentralized way. This is where the idea of the EVM was born. +Buterin and the founding Ethereum team envisioned a platform where developers could build **decentralized applications (dApps)** on a blockchain. To accomplish this, they needed a way to execute arbitrary, complex computations in a secure and decentralized manner. This is how the concept of the EVM was born. -The EVM, an integral part of the Ethereum ecosystem, operates as a quasi-Turing complete machine. This means it can run nearly any algorithm, given enough resources, and it's isolated from the main network, providing a sandboxed environment for smart contract execution. +The EVM, an integral part of the Ethereum ecosystem, operates as a **quasi-Turing complete machine**. This means it can run nearly any algorithm, given enough resources. It's isolated from the main network, providing a sandboxed environment for smart contract execution. -After the whitepaper was published, the Ethereum project moved into a development phase, with the first live version of the Ethereum network, including the EVM, launching on July 30, 2015. The Ethereum blockchain was designed to include the EVM at the protocol level to allow users to create and execute smart contracts. These smart contracts are essentially programs or scripts that autonomously execute the terms of a contract, and they are written in a high-level language such as Solidity or Vyper, which are then compiled down to EVM bytecode for execution on the EVM. +Following the publication of the whitepaper, the Ethereum project moved into development. The first live version of the Ethereum network, including the EVM, launched on **July 30, 2015**. The Ethereum blockchain was designed with the EVM at the protocol level, enabling users to create and execute smart contracts. These smart contracts are essentially programs that autonomously execute the terms of an agreement. They are written in high-level languages like **Solidity** or **Vyper**, which are then compiled down to EVM bytecode for execution on the EVM. -Since its creation, the EVM has become a vital component of the Ethereum blockchain, and it has set a precedent for other blockchain platforms that have adopted similar models for executing smart contracts. The advent of the EVM has undoubtedly revolutionized the blockchain world, introducing the concept of programmable blockchains. \ No newline at end of file +Since its creation, the EVM has become a crucial component of the Ethereum blockchain and has set a standard for other blockchain platforms that have adopted similar models for executing smart contracts. The advent of the EVM has undoubtedly revolutionized the blockchain world by introducing the concept of **programmable blockchains**. diff --git a/content/course/customizing-evm/02-intro-to-evm/02-accounts-keys-address.mdx b/content/course/customizing-evm/02-intro-to-evm/02-accounts-keys-address.mdx index 9915ee0c..39741585 100644 --- a/content/course/customizing-evm/02-intro-to-evm/02-accounts-keys-address.mdx +++ b/content/course/customizing-evm/02-intro-to-evm/02-accounts-keys-address.mdx @@ -1,8 +1,8 @@ --- -title: Accounts, Keys and Addresses -description: Learn about Accounts, Keys and Addresses in EVM. -updated: 2024-05-31 -authors: [ashucoder9] +title: Accounts, Keys, and Addresses +description: Learn about Accounts, Keys, and Addresses in EVM. +updated: 2024-09-27 +authors: [ashucoder9, owenwahlgrne] icon: BookOpen --- @@ -10,29 +10,28 @@ icon: BookOpen In the EVM, there are two types of accounts: -1. **Externally Owned Accounts (EOAs)**: These are accounts controlled by private keys and have no associated code with them. They can send transactions by creating and signing them with their private keys. Essentially, if you are an end user of Ethereum, you're likely using an EOA. +1. **Externally Owned Accounts (EOAs)**: These accounts are controlled by private keys and do not have associated code. They can send transactions by creating and signing them with their private keys. If you're an end user of Ethereum, you're likely using an EOA. -2. **Contract Accounts**: These are accounts that have associated code with them (Smart Contracts). Contract accounts can't initiate transactions on their own. Instead, they only perform an operation when instructed to do so by an EOA. This could be a simple token transfer or a function call in a smart contract. +2. **Contract Accounts**: These accounts have associated code (smart contracts). Contract accounts can't initiate transactions on their own; instead, they only perform actions when instructed by an EOA. This could be as simple as a token transfer or a function call within a smart contract. ## Public and Private Keys -In Ethereum, as in many blockchain platforms, a cryptographic algorithm called the Elliptic Curve Digital Signature Algorithm (ECDSA) is used to generate a pair of keys: a public key and a private key. +In Ethereum, as in many blockchain platforms, the **Elliptic Curve Digital Signature Algorithm (ECDSA)** is used to generate a pair of keys: a public key and a private key. -The private key is a 32-byte number generated randomly. - -The public key is derived from the private key using a specific elliptic curve cryptography function. It is 64 bytes long, consisting of two concatenated 32-byte coordinates. +- The **private key** is a 32-byte number generated randomly. +- The **public key** is derived from the private key using elliptic curve cryptography. It is 64 bytes long, made up of two concatenated 32-byte coordinates. ## Addresses An EVM address is derived from the public key through the following steps: -1. **Keccak-256 Hashing**: The public key is first passed through the Keccak-256 hashing function (the version of SHA-3 used by Ethereum). Keccak-256 outputs a 64-byte string: +1. **Keccak-256 Hashing**: The public key is first passed through the Keccak-256 hashing function (the version of SHA-3 used by Ethereum). Keccak-256 outputs a 64-byte string, for example: `025ad33e2479a53b02dc0be66eb0ce272fc0f4358c57a8f0a442410c3d831a` -2. **Rightmost 20 bytes**: The resulting string is truncated to keep only the last 20 bytes. In hexadecimal, this means retaining the rightmost 40 hex digits (since two hex digits represent one byte): +2. **Rightmost 20 bytes**: The resulting string is truncated to keep only the last 20 bytes. In hexadecimal, this means retaining the rightmost 40 hex digits (since two hex digits represent one byte), like so: `e66eb0ce272fc0f4358c57a8f0a442410c3d831a` -3. **Adding '0x'**: Finally, "0x" is added at the start of the address for a total of 42 characters. The "0x" prefix indicates that what follows is a hexadecimal number, a common convention in the Ethereum ecosystem: +3. **Adding '0x'**: Finally, "0x" is prefixed to the address for a total of 42 characters. The "0x" indicates that the following characters represent a hexadecimal number, a common convention in Ethereum: `0xe66eb0ce272fc0f4358c57a8f0a442410c3d831a` -This process ensures that each Ethereum address corresponds uniquely to a public key. Since the address is a truncated hash of the public key, it's not possible to reverse-engineer the public key from the address. +This process ensures that each Ethereum address uniquely corresponds to a public key. Since the address is a truncated hash of the public key, it's impossible to reverse-engineer the public key from the address. diff --git a/content/course/customizing-evm/02-intro-to-evm/03-transactons-and-blocks.mdx b/content/course/customizing-evm/02-intro-to-evm/03-transactons-and-blocks.mdx index 995e9efe..4bab0584 100644 --- a/content/course/customizing-evm/02-intro-to-evm/03-transactons-and-blocks.mdx +++ b/content/course/customizing-evm/02-intro-to-evm/03-transactons-and-blocks.mdx @@ -1,31 +1,31 @@ --- title: Transactions and Blocks description: Learn about another fundamental aspect of the Ethereum ecosystem - Transactions and Blocks. -updated: 2024-05-31 -authors: [ashucoder9] +updated: 2024-09-27 +authors: [ashucoder9, owenwahlgren] icon: BookOpen --- ## Transactions -In the EVM, a transaction is the smallest unit of work that can be included in a block. It represents a state transition, modifying account data and moving Ether across the network. +In the EVM, a transaction is the smallest unit of work that can be included in a block. It represents a **state transition**, modifying account data and transferring Ether across the network. Transactions can either transfer Ether or invoke smart contracts. Each transaction includes the following components: - **Nonce**: A unique value set by the sender to ensure the transaction is processed only once, preventing replay attacks. -- **Gas Price**: The amount the sender is willing to pay per unit of gas, typically measured in `nanoAvax`, where 1 `nAvax` = 1/(10^9) Avax. This consists of three components: +- **Gas Price**: The amount the sender is willing to pay per unit of gas, typically measured in `nanoAvax` (1 `nAvax` = 1/(10^9) Avax). It consists of three parts: - **Base Gas Fee**: The minimum `nAvax` required per unit of gas. - - **Maximum Priority Gas Fee**: Additional `nAvax` the sender is willing to pay per unit of gas, on top of the base fee. - - **Maximum Total Gas Fee**: The maximum `nAvax` the sender is willing to spend per unit of gas. The gas price paid equals the maximum total gas fee if the base gas fee plus the maximum priority fee exceeds the maximum total gas fee. -- **Gas Limit**: The maximum amount of gas units the sender is willing to pay for executing the transaction. If the gas limit is reached, the transaction fails, preventing indefinite execution. + - **Maximum Priority Gas Fee**: Additional `nAvax` the sender is willing to pay on top of the base fee. + - **Maximum Total Gas Fee**: The maximum `nAvax` the sender is willing to spend per unit of gas. If the sum of the base gas fee and the priority gas fee exceeds this amount, the gas price paid will be capped at the maximum total gas fee. +- **Gas Limit**: The maximum amount of gas units the sender is willing to pay for executing the transaction. If this limit is reached, the transaction fails, preventing indefinite execution. - **To**: The recipient's Ethereum address or the target smart contract. - **V, R, S**: Cryptographic data used to create the sender's signature. ## Blocks -A block in the EVM consists of a set of transactions that have been validated by miners, bundled together, and linked to the previous block. Each block contains: +A block in the EVM is a bundle of validated transactions, grouped together and linked to the previous block. Each block contains: -- **Block Number**: The index of the block, viewed as a position in a zero-indexed linked list. +- **Block Number**: The index of the block, representing its position in a zero-indexed linked list. - **Timestamp**: The time the block was mined. - **Transactions Root**: The Merkle root of all transactions within the block. - **Receipts Root**: The Merkle root of all transaction receipts. diff --git a/content/course/customizing-evm/02-intro-to-evm/05-different-evm-versions.mdx b/content/course/customizing-evm/02-intro-to-evm/05-different-evm-versions.mdx index 68f4973b..f8f9401f 100644 --- a/content/course/customizing-evm/02-intro-to-evm/05-different-evm-versions.mdx +++ b/content/course/customizing-evm/02-intro-to-evm/05-different-evm-versions.mdx @@ -1,8 +1,8 @@ --- title: Different Versions of EVM -description: Learn about the different versions of the Ethereum Virtual Machine (EVM) in the Avalanche ecosystem. -updated: 2024-05-31 -authors: [ashucoder9] +description: Learn about the different versions of the Ethereum Virtual Machine in the Avalanche ecosystem. +updated: 2024-09-27 +authors: [ashucoder9, owenwahlgren] icon: BookOpen --- @@ -12,20 +12,17 @@ Geth (or [go-ethereum](https://github.com/ethereum/go-ethereum)) is the official ## Coreth -[Coreth](https://github.com/ava-labs/coreth) is a fork of Geth maintained by Ava Labs that implements the Virtual Machine for the C-Chain. It has been adapted to work with Avalanche Consensus. +[Coreth](https://github.com/ava-labs/coreth) is a fork of Geth maintained by Ava Labs. It implements the EVM for the C-Chain and has been adapted to work with Avalanche Consensus. ## Subnet-EVM -[Subnet-EVM](https://github.com/ava-labs/subnet-evm) is a fork of Coreth designed to make it easy to launch customized EVM-based blockchains on an Avalanche L1. It differs from Coreth in the following ways: +[Subnet-EVM](https://github.com/ava-labs/subnet-evm) is a fork of Coreth designed to facilitate launching customized EVM-based blockchains on an Avalanche L1. It differs from Coreth in the following ways: -→ **Configurable fees and gas limits added in the genesis file** - -→ **Avalanche hardforks merged into a single "Subnet-EVM" hardfork** - -→ **Atomic transactions and shared memory removed** - -→ **Multicoin contracts and state removed** +- **Configurable Fees and Gas Limits**: Customizable fees and gas limits can be set in the genesis file. +- **Unified Subnet-EVM Hardfork**: All Avalanche hardforks are merged into a single "Subnet-EVM" hardfork. +- **Atomic Transactions and Shared Memory Removed**: Support for atomic transactions and shared memory has been removed. +- **Multicoin Contracts and State Removed**: Multicoin contracts and state tracking are no longer supported. ## Precompile-EVM -Precompile-EVM allows precompiles to be registered with Subnet-EVM without forking the Subnet-EVM codebase. This simplifies common customizations to Subnet-EVM, making them more accessible and easier to maintain. It also streamlines updates for Subnet-EVM. +Precompile-EVM allows precompiles to be registered with Subnet-EVM without needing to fork the Subnet-EVM codebase. This simplifies common customizations to Subnet-EVM, making them more accessible and easier to maintain. It also streamlines updates for Subnet-EVM. diff --git a/content/course/customizing-evm/03-development-env-setup/00-intro.mdx b/content/course/customizing-evm/03-development-env-setup/00-intro.mdx index 8bead5b5..af53bcb0 100644 --- a/content/course/customizing-evm/03-development-env-setup/00-intro.mdx +++ b/content/course/customizing-evm/03-development-env-setup/00-intro.mdx @@ -1,5 +1,5 @@ --- -title: Setting Up Our Development Environment +title: Set Up Development Environment description: Start by setting up your development environment. updated: 2024-05-31 authors: [ashucoder9] diff --git a/content/course/customizing-evm/03-development-env-setup/03-create-codespaces.mdx b/content/course/customizing-evm/03-development-env-setup/02-create-codespaces.mdx similarity index 100% rename from content/course/customizing-evm/03-development-env-setup/03-create-codespaces.mdx rename to content/course/customizing-evm/03-development-env-setup/02-create-codespaces.mdx diff --git a/content/course/customizing-evm/03-development-env-setup/02-what-is-codespaces.mdx b/content/course/customizing-evm/03-development-env-setup/02-what-is-codespaces.mdx deleted file mode 100644 index f5eda838..00000000 --- a/content/course/customizing-evm/03-development-env-setup/02-what-is-codespaces.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: What are Codespaces? -description: Learn how to setup GitHub Codespaces. -updated: 2024-05-31 -authors: [ashucoder9] -icon: Book ---- - -You've chosen to set up your development environment using Codespaces! By leveraging Codespaces, you will be able to develop in the cloud in a sandboxed environment that is both persistent and is able to run in any browser. In this section, we will: - -- Learn about Codespaces -- Create a Codespace and use it with your Browser -- Open the Codespace in VS Code (optional) -- Learn how to stop and resume working in a Codespace - -Let's first start with learning about Codespaces. - -## Codespaces - -GitHub Codespaces is a development environment service offered by GitHub that allows developers to write, run, test, and debug their code directly within a browser or Visual Studio Code. It provides a fully-featured cloud-hosted development environment, which can be customized to suit the requirements of a particular project, enabling developers to work from anywhere without the need to set up a local development environment. - -By leveraging the power of the cloud, Codespaces eliminates inconsistencies between different local environments and streamlines collaboration among team members, all while being seamlessly integrated with the existing GitHub workflow. - -## Building with Codespaces in the Browser - -Developing software in a browser is made possible through web-based Integrated Development Environments (IDEs), like GitHub Codespaces. These IDEs are designed to run within a web browser and provide many of the features found in traditional desktop IDEs. - -![](/course-images/customizing-evm/8.png) - -### Pros - -- Access: Users can access the browser-based IDE from any device with internet connectivity and a modern web browser. -- No Installation: Users do not have to install additional software - -### Cons - -- Performance: Browser-based IDEs might not be as responsive or fast as native desktop IDEs, especially for large projects or computationally intensive tasks. -- Functionality: Some advanced features found in desktop IDEs might be absent or limited in a browser environment (keyboard shortcuts, port-forwarding). - -## Building with Codespaces through VS Code - -GitHub Codespaces can be used with Visual Studio Code (VS Code), enabling developers to connect to a Codespace directly from their local VS Code installation. This brings the convenience of cloud-hosted environments to the familiarity of VS Code. - -You can find detailed instruction on how to open a codespace from your local VS Code later in this course. - -![](/course-images/customizing-evm/9.png) \ No newline at end of file diff --git a/content/course/customizing-evm/03-development-env-setup/04-codespace-in-vscode.mdx b/content/course/customizing-evm/03-development-env-setup/03-codespace-in-vscode.mdx similarity index 93% rename from content/course/customizing-evm/03-development-env-setup/04-codespace-in-vscode.mdx rename to content/course/customizing-evm/03-development-env-setup/03-codespace-in-vscode.mdx index bb2aa432..e228d44c 100644 --- a/content/course/customizing-evm/03-development-env-setup/04-codespace-in-vscode.mdx +++ b/content/course/customizing-evm/03-development-env-setup/03-codespace-in-vscode.mdx @@ -1,5 +1,5 @@ --- -title: Open Codespace in VS Code +title: Codespace in VS Code description: Learn how to setup GitHub Codespaces. updated: 2024-05-31 authors: [ashucoder9] diff --git a/content/course/customizing-evm/04-your-evm-blockchain/00-intro.mdx b/content/course/customizing-evm/04-your-evm-blockchain/00-intro.mdx index 93e382bf..8fc6f571 100644 --- a/content/course/customizing-evm/04-your-evm-blockchain/00-intro.mdx +++ b/content/course/customizing-evm/04-your-evm-blockchain/00-intro.mdx @@ -1,26 +1,22 @@ --- title: Your Own EVM Blockchain description: Learn how to spin up your own EVM blockchain. -updated: 2024-05-31 -authors: [ashucoder9] +updated: 2024-09-27 +authors: [ashucoder9, owenwahlgren] icon: Book --- -In this part of our course, we'll explore how to run your own Avalanche Network with a custom EVM. Running your own EVM allows you to address specific use cases and highlights one of the key advantages of multi-chain systems over monolithic ones. +In this part of the course, we'll explore how to run your own Avalanche L1 with a custom EVM. Running your own EVM allows you to address specific use cases, showcasing one of the key advantages of multi-chain systems over monolithic blockchains. -## Hands-On Exercise +## Topics -In this section, you won't need to write any Go code. Instead, you'll run some commands to set up your EVM blockchain. +We’ll cover the following topics: -## Structure of This Section +- **Avalanche CLI**: Learn how to configure and launch an Avalanche L1 using the Avalanche CLI. +- **Token Transfer**: Explore how to perform token transfers with Foundry. -We will cover the following topics: - -- **Avalanche CLI**: Learn how to use this tool to create your own Avalanche Network and add Avalanche L1s and blockchains. -- **Token Transfer**: Discover how to perform token transfers with Foundry. - -This practical exercise will help you consolidate your knowledge and see the impact of customizations on EVM performance firsthand. +This hands-on exercise will solidify your knowledge and allow you to observe how customizations impact EVM performance. ## Learning Objective -By the end of this section, you'll be equipped with the skills to effectively run your own Avalanche Network with a custom EVM blockchain, paving the way for your blockchain projects. +By the end of this section, you’ll have the skills to effectively run your own Avalanche L1 with a custom EVM blockchain, empowering you to start building your blockchain projects! diff --git a/content/course/customizing-evm/04-your-evm-blockchain/01-avalanche-cli.mdx b/content/course/customizing-evm/04-your-evm-blockchain/01-avalanche-cli.mdx index e949d6ac..78b99fa8 100644 --- a/content/course/customizing-evm/04-your-evm-blockchain/01-avalanche-cli.mdx +++ b/content/course/customizing-evm/04-your-evm-blockchain/01-avalanche-cli.mdx @@ -8,18 +8,18 @@ icon: BookOpen ## What is the Avalanche CLI? -Avalanche-CLI is a command-line tool that provides developers with comprehensive access to Avalanche functionalities. It is designed to help developers build and test their independent blockchains. +The Avalanche CLI is a command-line tool that gives developers comprehensive access to Avalanche's functionalities, making it easier to build and test independent blockchains. -Each Avalanche network includes a Primary Network, which comprises a Contract (C), Platform (P), and Exchange (X) chain. Note that the term "Primary Network" is somewhat misleading, as it refers to a special Avalanche L1 rather than a distinct network. +Each Avalanche network includes the Primary Network, which consists of the Contract (C), Platform (P), and Exchange (X) chains. It's important to note that "Primary Network" refers to a special Avalanche L1 rather than a distinct, standalone network. -Your local network is completely independent of the Mainnet or Fuji Testnet. You can even operate an Avalanche Network offline. Local Avalanche networks support, but are not limited to, the following commands: +Your local network operates independently from both the Mainnet and Fuji Testnet. You can even run an Avalanche L1 offline. Local Avalanche networks support, but are not limited to, the following commands: -- **Start and Stop a Network**: Start and stop a local network. -- **Health Check**: Provide information on the health of each node in the network. -- **Create Blockchains**: Create a new blockchain using specified parameters. +- **Start and Stop a Network**: Easily start or stop a local network. +- **Health Check**: Check the health status of each node in the network. +- **Create Blockchains**: Spin up new blockchains with custom parameters. -Managing a local network with multiple nodes can be complex. To simplify this, the Avalanche CLI includes user-friendly commands. +Managing a local network with multiple nodes can be complex, but the Avalanche CLI simplifies the process with user-friendly commands. ## Usage -The Precompile-EVM repository pre-loads Avalanche CLI along with Foundry, so you don’t need to install any additional tools to start building within Codespaces. Simply use the terminal in your Codespace to run Avalanche CLI commands. +The Precompile-EVM repository comes preloaded with the Avalanche CLI and Foundry, so you don’t need to install additional tools when working within Codespaces. Just use the terminal in your Codespace to run Avalanche CLI commands and start building. diff --git a/content/course/customizing-evm/05-evm-configuration/00-vm-configuration.mdx b/content/course/customizing-evm/05-evm-configuration/00-vm-configuration.mdx deleted file mode 100644 index e43737c6..00000000 --- a/content/course/customizing-evm/05-evm-configuration/00-vm-configuration.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: VM Configuration -description: Learn about Virtual Machine configuration. -updated: 2024-05-31 -authors: [ashucoder9] -icon: Book ---- - -In this part of our course, we will explore how to optimize your EVM for specific use cases through chain configuration. Tailoring EVM configurations to fit specific use cases is a key advantage of multi-chain systems. - -## Exercise - -In this section, you won’t need to write any Go code. Instead, we’ll adjust values in the JSON file of the genesis block. - -## Structure of This Section - -We will cover the following topics: - -- **Genesis Block**: The cornerstone of any blockchain. We’ll provide an overview of its components and how its properties can be customized. -- **Fee Configuration**: Learn how to balance incentivizing validators with ensuring economic feasibility for users. This is crucial in a public network to manage congestion and discourage wasteful transactions. -- **Initial Token Allocation**: Understand how to specify the initial distribution of tokens in your custom EVM to set your network up for success. -- **Preinstalled Precompiles**: Discover how to configure preinstalled precompiles to leverage powerful functionalities, such as restricting who can issue transactions or deploy contracts to your chain. - -Finally, we’ll demonstrate how to run a local EVM with a custom Genesis Block. This exercise will help you consolidate your learnings and see the impact of customizations on EVM performance firsthand. - -## Learning Objective - -By the end of this section, you will be equipped to customize the EVM in Avalanche effectively, unlocking a range of possibilities for your blockchain projects. Let’s dive into the world of EVM customization and chain configuration together! diff --git a/content/course/customizing-evm/05-evm-configuration/04-gas-fees-and-limit.mdx b/content/course/customizing-evm/05-evm-configuration/04-gas-fees-and-limit.mdx deleted file mode 100644 index c0e114f7..00000000 --- a/content/course/customizing-evm/05-evm-configuration/04-gas-fees-and-limit.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Gas Fees and Gas Limit -description: Learn about Gas Fees and Gas Limit in the context of the EVM. -updated: 2024-05-31 -authors: [ashucoder9] -icon: BookOpen ---- - -## Background - -In the context of the EVM, gas is a unit that measures the amount of computational effort required to execute specific operations. Each operation performed by a contract or transaction on an EVM chain consumes a certain number of gas units based on its complexity. Operations that require more computational resources cost more gas. The EVM calculates the required gas units automatically, and developers are encouraged to optimize their contract code to reduce gas consumption. - -The cost of executing a transaction is determined by the gas units consumed and the gas price. The transaction cost is calculated as follows: - -``` -Transaction Cost = Gas Units * Gas Price -``` - -For EVM Avalanche L1s, gas payment can be configured to better suit the use case of the Avalanche L1. This means that the Avalanche L1 design can decide whether the gas fees are burned, paid to incentivize validators, or used for any other custom behavior. - -## Purpose - -The primary goal of setting and enforcing computational costs via gas is to prevent spam and abuse on the network. By requiring users to pay for each computational step, the network deters malicious actors from launching denial-of-service (DoS) attacks, which involve flooding the network with spurious transactions. Essentially, the gas system serves as a deterrent against such attacks. - -## Gas Price and Gas Limit - -Each transaction specifies the gas price and gas limit: - -**Gas Price:** The gas price is the amount of the Avalanche L1's native token that the sender is willing to spend per unit of gas, typically denoted in `gwei` (1 native token = 1,000,000,000 `gwei`). A well-designed gas mechanism adapts the gas price according to network activity to protect the network from spam. - -**Gas Limit:** The gas limit is the maximum amount of gas the sender is willing to use for the transaction. The gas limit was introduced to prevent infinite loops in contract execution. In a Turing-complete language like Solidity (the main programming language in the EVM), it is possible to write a contract with an infinite loop, either accidentally or intentionally. While an infinite loop might be a nuisance in traditional computing, it could cause significant issues in a decentralized blockchain by causing the network to hang as it attempts to process a never-ending transaction. The gas limit prevents this by halting execution once the gas consumed reaches the limit. - -If a transaction exceeds the gas limit, it fails, but the fee amounting to the gas limit is still paid by the sender. diff --git a/content/course/customizing-evm/05-genesis-configuration/00-vm-configuration.mdx b/content/course/customizing-evm/05-genesis-configuration/00-vm-configuration.mdx new file mode 100644 index 00000000..30a2c312 --- /dev/null +++ b/content/course/customizing-evm/05-genesis-configuration/00-vm-configuration.mdx @@ -0,0 +1,28 @@ +--- +title: EVM Configuration +description: Learn about Virtual Machine configuration. +updated: 2024-09-27 +authors: [ashucoder9] +icon: Book +--- + +In this part of the course, we'll explore how to optimize your EVM through chain configuration, tailoring it to fit specific use cases. Customizing EVM configurations is a key advantage of multi-chain systems. + +## Exercise + +In this section, you won’t need to write any Go code. Instead, we’ll adjust values in the JSON file of the genesis block. + +## Topics + +We will cover the following topics: + +- **Genesis Block**: The foundation of any blockchain. We’ll review its components and how to customize its properties. +- **Fee Configuration**: Learn how to balance validator incentives with user affordability. This is crucial for managing network congestion and discouraging wasteful transactions on public networks. +- **Initial Token Allocation**: Understand how to define the initial token distribution in your custom EVM, setting your network up for success. +- **Preinstalled Precompiles**: Discover how to configure preinstalled precompiles to leverage features like restricting who can issue transactions or deploy contracts on your chain. + +Finally, we’ll demonstrate how to run a local EVM with a custom Genesis Block. This exercise will solidify your understanding and allow you to observe the performance impact of your EVM customizations. + +## Learning Objective + +By the end of this section, you'll be able to effectively customize the EVM in Avalanche, unlocking new possibilities for your blockchain projects. Let’s dive into EVM customization and chain configuration together! diff --git a/content/course/customizing-evm/05-evm-configuration/01-genesis-block.mdx b/content/course/customizing-evm/05-genesis-configuration/01-genesis-block.mdx similarity index 79% rename from content/course/customizing-evm/05-evm-configuration/01-genesis-block.mdx rename to content/course/customizing-evm/05-genesis-configuration/01-genesis-block.mdx index 334fcc74..6028f912 100644 --- a/content/course/customizing-evm/05-evm-configuration/01-genesis-block.mdx +++ b/content/course/customizing-evm/05-genesis-configuration/01-genesis-block.mdx @@ -1,20 +1,20 @@ --- title: Genesis Block description: Learn about the Genesis Block. -updated: 2024-05-31 +updated: 2024-09-27 authors: [ashucoder9] icon: BookOpen --- ## Background -Each blockchain starts with a genesis state when it is created. For example, the Ethereum mainnet genesis block included the addresses and balances of participants from the Ethereum pre-sale, marking the initial distribution of ether. +Each blockchain begins with a genesis state when it is created. For instance, the Ethereum mainnet genesis block included the addresses and balances from the Ethereum pre-sale, marking the initial distribution of ether. -For Subnet-EVM and Precompile-EVM, the genesis block includes additional parameters that allow us to configure the behavior of our customized EVM to meet specific requirements. Since each blockchain has its own genesis block, you can create two blockchains with the same VM but different genesis blocks. +For Subnet-EVM and Precompile-EVM, the genesis block contains additional parameters that allow us to configure the behavior of our customized EVM to meet specific requirements. Since each blockchain has its own genesis block, you can create two blockchains with the same VM but different genesis blocks. ## Format -Here is an example of a genesis block: +Here’s an example of a genesis block: ```json { @@ -66,5 +66,6 @@ Here is an example of a genesis block: "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000" } ``` +We will explore the relevant configurable parameters in the upcoming activities. Some parameters (e.g., `eip150Block`, `byzantiumBlock`) are omitted here as they are not relevant for most use cases. -We will explore the relevant configurable parameters in the upcoming activities. Some parameters (e.g., `eip150Block`, `byzantiumBlock`) are omitted here as they are not relevant for most use cases. \ No newline at end of file +This version provides a clean and concise explanation of the genesis block and its structure, keeping the focus on what's essential. diff --git a/content/course/customizing-evm/05-evm-configuration/02-create-your-genesis.mdx b/content/course/customizing-evm/05-genesis-configuration/02-create-your-genesis.mdx similarity index 100% rename from content/course/customizing-evm/05-evm-configuration/02-create-your-genesis.mdx rename to content/course/customizing-evm/05-genesis-configuration/02-create-your-genesis.mdx diff --git a/content/course/customizing-evm/05-evm-configuration/03-setup-chainid.mdx b/content/course/customizing-evm/05-genesis-configuration/03-setup-chainid.mdx similarity index 61% rename from content/course/customizing-evm/05-evm-configuration/03-setup-chainid.mdx rename to content/course/customizing-evm/05-genesis-configuration/03-setup-chainid.mdx index feb41653..34030f6a 100644 --- a/content/course/customizing-evm/05-evm-configuration/03-setup-chainid.mdx +++ b/content/course/customizing-evm/05-genesis-configuration/03-setup-chainid.mdx @@ -1,14 +1,14 @@ --- title: Setup Your ChainID description: Learn how to setup ChainID for your own blockchain. -updated: 2024-05-31 +updated: 2024-09-27 authors: [ashucoder9] icon: Terminal --- ## What is ChainID? -The `ChainID` of an Ethereum Virtual Machine (EVM) blockchain is a unique identifier that distinguishes Ethereum chains from one another. Introduced in Ethereum Improvement Proposal (EIP) 155, this mechanism prevents transaction replay attacks, which could occur when the same transaction is valid across multiple chains. +The `ChainID` of an EVM blockchain is a unique identifier that distinguishes Ethereum chains from one another. Introduced in Ethereum Improvement Proposal (EIP) 155, this mechanism prevents transaction replay attacks, which could occur when the same transaction is valid across multiple chains. ## Setting the ChainID diff --git a/content/course/customizing-evm/05-genesis-configuration/04-gas-fees-and-limit.mdx b/content/course/customizing-evm/05-genesis-configuration/04-gas-fees-and-limit.mdx new file mode 100644 index 00000000..cd87a230 --- /dev/null +++ b/content/course/customizing-evm/05-genesis-configuration/04-gas-fees-and-limit.mdx @@ -0,0 +1,33 @@ +--- +title: Gas Fees and Gas Limit +description: Learn about Gas Fees and Gas Limit in the context of the EVM. +updated: 2024-05-31 +authors: [ashucoder9] +icon: BookOpen +--- + +## Background + +In the context of the EVM, gas is a unit that measures the computational effort required to execute specific operations. Each operation performed by a contract or transaction on an EVM chain consumes a certain number of gas units based on its complexity. Operations that require more computational resources cost more gas. The EVM calculates the required gas units automatically, and developers are encouraged to optimize their contract code to reduce gas consumption. + +The cost of executing a transaction is determined by the gas units consumed and the gas price, calculated as follows: + +``` +Transaction Cost = Gas Units * Gas Price +``` + +For EVM Avalanche L1s, gas payment can be configured to better suit the use case of the Avalanche L1. This means that the Avalanche L1 design can decide whether the gas fees are burned, paid to incentivize validators, or used for any other custom behavior. + +## Purpose + +The primary goal of setting and enforcing computational costs via gas is to prevent spam and abuse on the network. By requiring users to pay for each computational step, the network deters malicious actors from launching denial-of-service (DoS) attacks, which involve flooding the network with spurious transactions. Essentially, the gas system serves as a deterrent against such attacks. + +## Gas Price and Gas Limit + +Each transaction specifies the gas price and gas limit: + +**`Gas Price`:** The gas price is the amount of the Avalanche L1's native token that the sender is willing to spend per unit of gas, typically denoted in `gwei` (1 native token = 1,000,000,000 `gwei`). A well-designed gas mechanism adapts the gas price according to network activity to protect the network from spam. + +**`Gas Limit`:** The gas limit is the maximum amount of gas the sender is willing to use for the transaction. It was introduced to prevent infinite loops in contract execution. In a Turing-complete language like Solidity (the main programming language in the EVM), it is possible to write a contract with an infinite loop, either accidentally or intentionally. While an infinite loop might be a nuisance in traditional computing, it could cause significant issues in a decentralized blockchain by causing the network to hang as it attempts to process a never-ending transaction. The gas limit prevents this by halting execution once the gas consumed reaches the limit. + +If a transaction exceeds the gas limit, it fails, but the fee amounting to the gas limit is still paid by the sender. diff --git a/content/course/customizing-evm/05-evm-configuration/05-gas-fee-configuration.mdx b/content/course/customizing-evm/05-genesis-configuration/05-gas-fee-configuration.mdx similarity index 100% rename from content/course/customizing-evm/05-evm-configuration/05-gas-fee-configuration.mdx rename to content/course/customizing-evm/05-genesis-configuration/05-gas-fee-configuration.mdx diff --git a/content/course/customizing-evm/05-evm-configuration/06-configuring-gas-fees.mdx b/content/course/customizing-evm/05-genesis-configuration/06-configuring-gas-fees.mdx similarity index 100% rename from content/course/customizing-evm/05-evm-configuration/06-configuring-gas-fees.mdx rename to content/course/customizing-evm/05-genesis-configuration/06-configuring-gas-fees.mdx diff --git a/content/course/customizing-evm/05-evm-configuration/07-initial-token-allocation.mdx b/content/course/customizing-evm/05-genesis-configuration/07-initial-token-allocation.mdx similarity index 94% rename from content/course/customizing-evm/05-evm-configuration/07-initial-token-allocation.mdx rename to content/course/customizing-evm/05-genesis-configuration/07-initial-token-allocation.mdx index 6b5449c7..0e4ce4b4 100644 --- a/content/course/customizing-evm/05-evm-configuration/07-initial-token-allocation.mdx +++ b/content/course/customizing-evm/05-genesis-configuration/07-initial-token-allocation.mdx @@ -36,7 +36,7 @@ Keys in the allocation are hex addresses without the canonical 0x prefix. Balanc The default configuration for testing purposes allocates a significant number of tokens to the address `8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC`. -The private key for this address is: `56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027`. +The private key for this address (as defined in the `.devcontainer`) is: `56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027`. Never use this address or private key for anything other than testing on a local test network. The private key is publicly known, and any real funds transferred to this address are likely to be stolen. diff --git a/content/course/customizing-evm/05-evm-configuration/08-build-and-run-custom-genesis-blockchain.mdx b/content/course/customizing-evm/05-genesis-configuration/08-build-and-run-custom-genesis-blockchain.mdx similarity index 95% rename from content/course/customizing-evm/05-evm-configuration/08-build-and-run-custom-genesis-blockchain.mdx rename to content/course/customizing-evm/05-genesis-configuration/08-build-and-run-custom-genesis-blockchain.mdx index e402101f..2b0683d0 100644 --- a/content/course/customizing-evm/05-evm-configuration/08-build-and-run-custom-genesis-blockchain.mdx +++ b/content/course/customizing-evm/05-genesis-configuration/08-build-and-run-custom-genesis-blockchain.mdx @@ -1,5 +1,5 @@ --- -title: Build and Run Custom Genesis Blockchain +title: Build and Run Custom Genesis EVM description: Learn how to build and run your blockchain with custom genesis file. updated: 2024-05-31 authors: [ashucoder9] diff --git a/content/course/customizing-evm/06-precompiles/01-what-are-precompiles.mdx b/content/course/customizing-evm/06-precompiles/01-what-are-precompiles.mdx index f268fcd3..72f41459 100644 --- a/content/course/customizing-evm/06-precompiles/01-what-are-precompiles.mdx +++ b/content/course/customizing-evm/06-precompiles/01-what-are-precompiles.mdx @@ -6,15 +6,15 @@ authors: [ashucoder9] icon: BookOpen --- -Precompiled contracts are a way to execute code written in the low-level coding language Go from the EVM. Go is much faster and more efficient than Solidity. +Precompiled contracts allow the execution of code written in the low-level programming language Go from the EVM, which is significantly faster and more efficient than Solidity. ## Overview -If you are familiar with Python programming, you might be familiar with a similar concept. Many Python functions and libraries are written in the programming language C, since it is much more efficient than Python. Python developers can import these precompile modules and call these functions just as if they were written in Python. The only difference is that the modules are faster and more efficient. +If you're familiar with Python, you might recognize a similar concept where many Python functions and libraries are implemented in C for efficiency. Python developers can import these precompiled modules and call functions as if they were written in Python. The main difference is that the modules execute faster and more efficiently. -Precompiles can be called from a Solidity smart contract in the same way, as if they were another contract written in Solidity. The EVM keeps a list of addresses reserved and mapped to the precompiles. When a smart contract calls a function of a contract with an address on that list, the EVM executes the precompile written in Go instead of the smart contract. +Precompiles can be called from a Solidity smart contract just like any other contract. The EVM maintains a list of reserved addresses mapped to precompiles. When a smart contract calls a function of a contract at one of these addresses, the EVM executes the precompile written in Go instead of the Solidity contract. -For instance, if we mapped the address 0x030...01 to the SHA256 precompile that hashes its input using the SHA256 Hash Function, we can call the Precompile like this: +For example, if we map the address `0x030...01` to the SHA256 precompile that hashes its input using the SHA256 hash function, we can call the precompile as follows: ```solidity // SPDX-License-Identifier: MIT @@ -28,19 +28,19 @@ interface ISHA256 { contract MyContract { ISHA256 mySHA256Precompile = ISHA256(0x0300000000000000000000000000000000000001); + function doSomething() public { bytes32 hash = mySHA256Precompile.hashWithSHA256("test"); } } ``` +In the code above, we call the precompile using the defined interface for our SHA256 precompile within `MyContract`. -In the code above we are calling the precompile with the address we are defining the interface of our SHA256 precompile and calling it in our contract MyContract. +Note that there is no implementation of the precompile in Solidity itself. This will only work if the precompile is implemented in Go and registered at the address `0x030...01`. -Note that there is no implementation of the precompile in solidity itself. This will only work if we implemented this precompile in Go and registered at the address `0x030...01`. +### PrecompiledContract Interface -## PrecompiledContract Interface - -When implementing a precompile in the Avalanche L1-EVM, we have to implement the following function of the `StatefulPrecompiledContract` Interface in Go: +When implementing a precompile in the Avalanche L1-EVM, the following function of the `StatefulPrecompiledContract` interface must be implemented in Go: ```go // StatefulPrecompiledContract is the interface for executing a precompiled contract @@ -56,18 +56,16 @@ type StatefulPrecompiledContract interface { } ``` -Let's ignore what stateful means as well as the first parameter `accessibleState` for now. We will cover this in the later section Stateful Precompiles. - -From the function specifying the logic of our precompile we have access to the following data: +We will cover the meaning of "stateful" and the first parameter `accessibleState` later. For now, let's focus on the function that specifies the logic of our precompile, which provides access to the following data: -- **caller**: The address of the account that called the precompile -- **addr**: The address of the precompile being called -- **input**: All inputs encoded in a byte array -- **suppliedGas**: How much gas was supplied to the call of the precompile -- **readOnly**: A boolean flag to indicate if the interaction is only reading or modifying the state. +- caller: The address of the account that called the precompile. +- addr: The address of the precompile being called. +- input: All inputs encoded in a byte array. +- suppliedGas: The amount of gas supplied for the precompile call. +- readOnly: A boolean flag indicating if the interaction is only reading or modifying the state. -The precompile implementation has the return the following values: +The precompile implementation must return the following values: -- **ret**: All return values encoded in a byte array -- **remainingGas**: How much gas remains after the execution -- **err**: If an error occurs, return it. Otherwise return nil +- ret: All return values encoded in a byte array. +- remainingGas: The amount of gas remaining after execution. +- err: If an error occurs, return it. Otherwise, return nil. \ No newline at end of file diff --git a/content/course/customizing-evm/06-precompiles/02-why-precompiles.mdx b/content/course/customizing-evm/06-precompiles/02-why-precompiles.mdx index 459b51fc..14b30461 100644 --- a/content/course/customizing-evm/06-precompiles/02-why-precompiles.mdx +++ b/content/course/customizing-evm/06-precompiles/02-why-precompiles.mdx @@ -6,40 +6,40 @@ authors: [ashucoder9] icon: BookOpen --- -Adding precompiles to the Ethereum Virtual Machine (EVM) has several value propositions. We have described a few of them briefly in this chapter. +Adding precompiles to the EVM offers several significant advantages, which we will outline in this chapter. ## Performance Optimization -Precompiles are primarily used to optimize the performance of specific types of computations. Adding a new precompile can significantly reduce the computational resources required to perform certain tasks, which can improve the performance of smart contracts and decentralized applications (DApps) depending on these tasks. +Precompiles primarily optimize the performance of specific computations. Introducing a new precompile can greatly reduce the computational resources required for certain tasks, thereby enhancing the performance of smart contracts and decentralized applications (DApps) that rely on these tasks. -The SHA256 hash function (0x02) and the RIPEMD160 hash function (0x03) are examples of precompiles that significantly improve performance. If these functions had to be implemented in a smart contract, they would be computationally expensive and slow. However, as precompiles, they are executed quickly and efficiently. +For instance, the SHA256 hash function (0x02) and the RIPEMD160 hash function (0x03) serve as examples of precompiles that significantly boost performance. Implementing these functions within a smart contract would be computationally expensive and slow, whereas as precompiles, they execute quickly and efficiently. ## Security -By incorporating a function as a precompile, it is possible to leverage libraries that have been thoroughly reviewed and audited. This can reduce the risk of bugs and vulnerabilities, improving overall security. +Incorporating a function as a precompile allows developers to leverage libraries that have been thoroughly reviewed and audited, thus reducing the risk of bugs and vulnerabilities, which enhances overall security. -For example, the ModExp (0x05) precompile safely performs modular exponentiation, a complex mathematical operation used in various cryptographic functions. +For example, the ModExp (0x05) precompile safely performs modular exponentiation, a complex mathematical operation utilized in various cryptographic functions. ## Access to Go Libraries -Since precompiles are implemented in Go, we can utilize existing Go Libraries. Go has a rich ecosystem of Libraries. Accessing them avoids the need for reimplementation, which takes effort and risks introducing bugs in the process of translating from Go to Solidity. +Precompiles are implemented in Go, allowing access to the rich ecosystem of existing Go libraries. This access eliminates the need for reimplementation, which can be labor-intensive and carries the risk of introducing bugs during the translation from Go to Solidity. -Check out the implementation of the sha256 hash algorithm to see how much effort a reimplementation to solidity would mean. +Consider the implementation of the SHA256 hash algorithm to understand the complexity involved in reimplementing it in Solidity. ## Gas Efficiency -Adding a new precompile to the EVM can make certain computations more gas-efficient, reducing costs of execution. This makes it feasible to incorporate more complex operations into smart contracts, enhancing their functionality without unduly increasing the cost of transactions. +Introducing a new precompile to the EVM can enhance gas efficiency for specific computations, thereby lowering execution costs. This makes it feasible to incorporate more complex operations into smart contracts, expanding their functionality without significantly increasing transaction costs. -The identity precompile (0x04) copies and returns input data. Though simple, it offers gas efficiency because it's faster and cheaper than implementing the same functionality in a standard contract. +The identity precompile (0x04), which copies and returns input data, exemplifies this. Though simple, it provides gas efficiency by being faster and cheaper than implementing the same functionality in a standard contract. ## Advanced Features and Functionality -By adding new precompiles to the EVM, it is possible to introduce new features and functionalities, such as advanced cryptographic operations, complex mathematical calculations, data structures, and more. This can open up new possibilities for dApps and smart contracts, allowing them to perform tasks that would otherwise be too computationally expensive or technically challenging. +By adding new precompiles to the EVM, developers can introduce advanced features and functionalities, such as complex mathematical calculations, advanced cryptographic operations, and new data structures. This can unlock new possibilities for DApps and smart contracts, enabling them to execute tasks that would otherwise be too computationally demanding or technically challenging. -The precompiles for elliptic curve operations, such as ecadd (0x06), ecmul (0x07), and ecpairing (0x08), enable the use of advanced cryptographic functionality in EVM smart contracts. These precompiles are essential for implementing zk-SNARKs, a form of zero-knowledge proof, in Ethereum. +Precompiles for elliptic curve operations, such as ecadd (0x06), ecmul (0x07), and ecpairing (0x08), enable advanced cryptographic functionality within EVM smart contracts. These precompiles are crucial for implementing zk-SNARKs, a form of zero-knowledge proof, in Ethereum. ## Interoperability -Some precompiles can enhance the interoperability of the EVM with other blockchains or systems. For instance, precompiles could be used to verify proofs from other chains or to perform operations compatible with other cryptographic standards. +Certain precompiles can enhance the interoperability of the EVM with other blockchains or systems. For instance, precompiles can be utilized to verify proofs from other chains or perform operations compatible with different cryptographic standards. -The BLS12-381 elliptic curve operations precompiles (0x0a through 0x13, added in the Istanbul upgrade) enhance EVM's interoperability. They allow for operations compatible with the BLS signature scheme and could potentially facilitate inter-blockchain communication. \ No newline at end of file +The BLS12-381 elliptic curve operations precompiles (0x0a through 0x13, added in the Istanbul upgrade) improve EVM interoperability by allowing operations that are compatible with the BLS signature scheme, potentially facilitating inter-blockchain communication. diff --git a/content/course/customizing-evm/06-precompiles/03-interact-wtih-precompile.mdx b/content/course/customizing-evm/06-precompiles/03-interact-wtih-precompile.mdx index 28e50e88..27180471 100644 --- a/content/course/customizing-evm/06-precompiles/03-interact-wtih-precompile.mdx +++ b/content/course/customizing-evm/06-precompiles/03-interact-wtih-precompile.mdx @@ -6,7 +6,7 @@ authors: [ashucoder9] icon: Terminal --- -So let's get to it and interact with a precompile on the C-Chain of your local network. +So let's get to it and interact with a precompile on the C-Chain of your local network. The SHA256 precompile is already available on the C-Chain. ## Call Precompile from Foundry @@ -18,4 +18,8 @@ In this example, we will call the SHA256 precompile to generate hash of the inpu cast call --rpc-url local-c --private-key $PK 0x0000000000000000000000000000000000000002 "run(string)(bytes32)" "test" ``` -You should see a bytes32 hash of the input string `test` as the output. \ No newline at end of file +You should see a bytes32 hash of the input string `test` as the output. + +```bash +0xa770b926e13a31fb823282e9473fd1da9e85afe23690336770c490986ef1b1fc +``` \ No newline at end of file diff --git a/content/course/customizing-evm/07-hash-function-precompile/00-intro.mdx b/content/course/customizing-evm/07-hash-function-precompile/00-intro.mdx index a783e4f1..cc243b12 100644 --- a/content/course/customizing-evm/07-hash-function-precompile/00-intro.mdx +++ b/content/course/customizing-evm/07-hash-function-precompile/00-intro.mdx @@ -1,47 +1,60 @@ --- -title: Creating a Hash Function Precompile +title: Overview description: Learn how to create a Hash Function Precompile. updated: 2024-05-31 authors: [ashucoder9] icon: Book --- +import {Step, Steps} from 'fumadocs-ui/components/steps'; ## What We're Building -In this section, we'll create a precompile for the hash function md5. Since there's a Go library for this hash function, we can avoid reimplementing the algorithm in Solidity and make use of the better efficiency of Go over Solidity. +In this section, we'll create a precompile for the MD5 hash function. By utilizing the existing Go library for this hash function, we can avoid reimplementing the algorithm in Solidity and take advantage of Go's superior efficiency. -A hash function is a special type of function that takes input data of any size (a letter, a word, the text of a book, all combined texts available on the internet, ...) and converts it into a fixed-size output. This output, called a hash value, represents the original data. The process is often referred to as "hashing." +A hash function is a special type of function that takes input data of any size (such as a letter, a word, the text of a book, or even all combined texts available on the internet) and converts it into a fixed-size output. This output, known as a hash value, represents the original data. The process is often referred to as "hashing." -Hash functions have a few properties: +Hash functions possess several key properties: -- **Deterministic**: Given the same input, a hash function will always produce the same output. If you hash the word "apple" a thousand times, you'll get the same hash value each time. -- **Fixed Size**: No matter the size of the input data, whether it's a single character or an entire novel, the hash function always produces an output (the hash value) of the same length. +- **Deterministic**: Given the same input, a hash function will always produce the same output. For instance, hashing the word "apple" a thousand times will yield the same hash value each time. +- **Fixed Size**: Regardless of the input data size—whether it's a single character or an entire novel—the hash function always produces an output (the hash value) of a consistent length. - **Fast Computation**: Hash functions are designed to be quick and efficient, returning a hash value with minimal computational resources and time. -- **Preimage Resistance**: It's computationally infeasible to retrieve the original input data if you only have the hash value. This property is especially important in cryptographic hash functions, where it helps to secure data. -- **Avalanche Effect**: A small change to the input should produce such drastic changes in output that the new hash value appears uncorrelated with the old hash value. If you hash "apple" and "Apple", the resulting hash values should look completely different. -- **Collision Resistance**: It's very unlikely that two different pieces of input data will result in the same hash value. However, due to the limited length of hash values, this is theoretically possible in a scenario called a "collision." Good hash functions make these collisions exceedingly rare. +- **Preimage Resistance**: It's computationally infeasible to retrieve the original input data from the hash value alone. This property is especially crucial in cryptographic hash functions for data security. +- **Avalanche Effect**: A small change to the input should cause significant changes in the output, making the new hash value appear uncorrelated with the old one. For example, hashing "apple" and "Apple" should produce completely different hash values. +- **Collision Resistance**: It is highly unlikely for two different pieces of input data to yield the same hash value. However, due to the limited length of hash values, collisions are theoretically possible. A good hash function minimizes the occurrence of such collisions. -Hash functions are used in various applications in computer science, such as data retrieval, data integrity verification, password storage, and in blockchain technology for cryptocurrencies like Bitcoin. +Hash functions are utilized in various applications across computer science, including data retrieval, data integrity verification, password storage, and in blockchain technology for cryptocurrencies like Bitcoin. ## Reference Implementation -To help you understand how precompiles are built, we'll compare each step with a reference example: A precompile for the sha256 hash function. Both precompiles are very similar and just have a single function, which returns the hashed value. +To aid your understanding of building precompiles, we will compare each step with a reference example: a precompile for the SHA256 hash function. Both precompiles are quite similar, featuring a single function that returns the hashed value. ## Overview of Steps -Here's an overview of the steps: - -1. Create a Solidity interface for the precompile -2. Generate the ABI -3. Write the precompile code in Go -4. Configure and register the precompile -5. Build and run your customized EVM -6. Connect Remix to your customized EVM and interact with the precompile - -Let's begin! \ No newline at end of file +Here's an overview of the steps involved: + + +Create a Solidity interface for the precompile. + + +Generate the ABI. + + +Write the precompile code in Go. + + +Configure and register the precompile. + + +Build and run your customized EVM. + + +Connect Remix to your customized EVM and interact with the precompile. + + +Let's get started! diff --git a/content/course/customizing-evm/07-hash-function-precompile/01-create-solidity-interface.mdx b/content/course/customizing-evm/07-hash-function-precompile/01-create-solidity-interface.mdx index b2b16e81..6b4fc971 100644 --- a/content/course/customizing-evm/07-hash-function-precompile/01-create-solidity-interface.mdx +++ b/content/course/customizing-evm/07-hash-function-precompile/01-create-solidity-interface.mdx @@ -58,7 +58,7 @@ interface IMD5 { Now that we have an interface of our precompile, let's create an ABI of our Solidity interface. Open the integrated VS Code terminal (control + \`), and change to the `/contracts` directory. ```bash -cd $GOPATH/src/github.com/ava-labs/precompile-evm/contracts +cd contracts ``` Run the command to compile the solidity interface to the ABI: @@ -67,7 +67,7 @@ Run the command to compile the solidity interface to the ABI: npx solc@latest --abi ./contracts/interfaces/IMD5.sol -o ./abis --base-path . --include-path ./node_modules ``` -Now rename the file: +Rename the file: ```bash mv ./abis/contracts_interfaces_IMD5_sol_IMD5.abi ./abis/IMD5.abi diff --git a/content/course/customizing-evm/07-hash-function-precompile/02-generate-the-precompile.mdx b/content/course/customizing-evm/07-hash-function-precompile/02-generate-the-precompile.mdx index 192b2476..673e5388 100644 --- a/content/course/customizing-evm/07-hash-function-precompile/02-generate-the-precompile.mdx +++ b/content/course/customizing-evm/07-hash-function-precompile/02-generate-the-precompile.mdx @@ -1,8 +1,8 @@ --- -title: Generating the Precompile +title: Generate the Precompile description: Learn how to generate your precompile. -updated: 2024-05-31 -authors: [ashucoder9] +updated: 2024-09-27 +authors: [ashucoder9, owenwahlgren] icon: Terminal comments: true --- @@ -16,7 +16,7 @@ In the last section, we created the ABI for our precompile contract. Now, we'll To start, go to the root directory of your precompile-evm project: ```bash -cd $GOPATH/src/github.com/ava-labs/precompile-evm +cd .. ``` Now generate the files necessary for the precompile. diff --git a/content/course/customizing-evm/07-hash-function-precompile/03-unpack-input-pack-output.mdx b/content/course/customizing-evm/07-hash-function-precompile/03-unpack-input-pack-output.mdx index 5c889e23..8d6f1374 100644 --- a/content/course/customizing-evm/07-hash-function-precompile/03-unpack-input-pack-output.mdx +++ b/content/course/customizing-evm/07-hash-function-precompile/03-unpack-input-pack-output.mdx @@ -1,5 +1,5 @@ --- -title: Unpacking Inputs and Packing Outputs +title: Packing and Unpacking description: Learn how to unpack inputs and pack outputs. updated: 2024-05-31 authors: [ashucoder9] diff --git a/content/course/customizing-evm/07-hash-function-precompile/04-implementing-precompile.mdx b/content/course/customizing-evm/07-hash-function-precompile/04-implementing-precompile.mdx index 60c2eb09..54a186e8 100644 --- a/content/course/customizing-evm/07-hash-function-precompile/04-implementing-precompile.mdx +++ b/content/course/customizing-evm/07-hash-function-precompile/04-implementing-precompile.mdx @@ -1,5 +1,5 @@ --- -title: Implementing the Precompile +title: Implement the Precompile description: Learn how to implement the Precompile. updated: 2024-05-31 authors: [ashucoder9] diff --git a/content/course/customizing-evm/07-hash-function-precompile/05-configkey-and-contractaddr.mdx b/content/course/customizing-evm/07-hash-function-precompile/05-configkey-and-contractaddr.mdx index 8e909d20..539288e4 100644 --- a/content/course/customizing-evm/07-hash-function-precompile/05-configkey-and-contractaddr.mdx +++ b/content/course/customizing-evm/07-hash-function-precompile/05-configkey-and-contractaddr.mdx @@ -1,8 +1,8 @@ --- -title: Setting Config Key and Contract Address -description: Learn how to set ConfigKey and ContractAddress -updated: 2024-05-31 -authors: [ashucoder9] +title: ConfigKey, ContractAddress, and Genesis +description: Learn how to set ConfigKey, ContractAddress, and update the genesis configuration. +updated: 2024-09-27 +authors: [ashucoder9, owenwahlgren] icon: Terminal --- @@ -10,21 +10,57 @@ icon: Terminal The precompile config key is used to configure the precompile in the `chainConfig`. It's set in the `module.go` file of our precompile. -The generator chooses an initial value that should be sufficient for many cases. For the sha256 precompile this is: +The generator chooses an initial value that should be sufficient for many cases. In our case: -```go title="sha256/module.go" +```go title="md5/module.go" // ConfigKey is the key used in json config files to specify this precompile precompileconfig. // must be unique across all precompiles. -const ConfigKey = "sha256Config" +const ConfigKey = "md5Config" ``` +This key is used for each precompile in the geneis configuration to set the activation timestamp of the precompile. + +## Contract Address -This key is used for each precompile in the chainConfig to set the activation timestamp of the precompile. +Each precompile has a unique contract address we can use to call it. This is the address we used earlier to instantiate the precompile in our solidity code or in remix when we interacted with the sha256 precompile. + +```go title="md5/module.go" +// ContractAddress is the defined address of the precompile contract. +// This should be unique across all precompile contracts. +// See precompile/registry/registry.go for registered precompile contracts and more information. + +var ContractAddress = common.HexToAddress("{ASUITABLEHEXADDRESS}") // SET A SUITABLE HEX ADDRESS HERE +``` + +The `0x01` range is reserved for precompiles added by Ethereum. + +The `0x02` range is reserved for precompiles provided by Avalanche. + +The `0x03` range is reserved for custom precompiles. + +Lets set our contract address to `0x0300000000000000000000000000000000000002` + +```go title="md5/module.go" +var ContractAddress = common.HexToAddress("0x0300000000000000000000000000000000000002") // SET A SUITABLE HEX ADDRESS HERE +``` + +## Update Genesis Configuration +Now that the `ConfigKey` and `ContractAddress` are set, we need to update the genesis configuration to register the precompile. ```json title=".devcontainer/genesis-example.json" { "config": { "chainId": 99999, - // ... + "homesteadBlock": 0, + "eip150Block": 0, + "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0", + "eip155Block": 0, + "eip158Block": 0, + "byzantiumBlock": 0, + "constantinopleBlock": 0, + "petersburgBlock": 0, + "istanbulBlock": 0, + "muirGlacierBlock": 0, + "subnetEVMTimestamp": 0, "feeConfig": { "gasLimit": 20000000, "minBaseFee": 1000000000, @@ -35,13 +71,12 @@ This key is used for each precompile in the chainConfig to set the activation ti "targetBlockRate": 2, "blockGasCostStep": 500000 }, - - "sha256Config": { // [!code highlight:2] + "sha256Config": { "blockTimestamp": 0 - } - - // Add the md5Config here - + }, + "md5Config": { // [!code highlight:3] + "blockTimestamp": 0 + } }, "alloc": { "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": { @@ -49,45 +84,14 @@ This key is used for each precompile in the chainConfig to set the activation ti } }, "nonce": "0x0", - // ... + "timestamp": "0x0", + "extraData": "0x00", + "gasLimit": "0x1312D00", + "difficulty": "0x0", + "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "coinbase": "0x0000000000000000000000000000000000000000", + "number": "0x0", + "gasUsed": "0x0", + "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000" } -``` - -## Contract Address - -Each precompile has a unique contract address we can use to call it. This is the address we used earlier to instantiate the precompile in our solidity code or in remix when we interacted with the precompile. - -```go title="sha256/module.go" -// ContractAddress is the defined address of the precompile contract. -// This should be unique across all precompile contracts. -// See precompile/registry/registry.go for registered precompile contracts and more information. - -var ContractAddress = common.HexToAddress("0x0300000000000000000000000000000000000001") -``` - -The `0x01` range is reserved for precompiles added by Ethereum. - -The `0x02` range is reserved for precompiles provided by Avalanche. - -The `0x03` range is reserved for custom precompiles. - -## Setting ConfigKey and ContractAddress for MD5 Precompile - -Set a custom precompile address in the `md5/module.go` file. - - - - -```go title="md5/module.go" -// ConfigKey is the key used in json config files to specify this precompile precompileconfig. -// must be unique across all precompiles. -const ConfigKey = "md5Config" -​ -// ContractAddress is the defined address of the precompile contract. -// This should be unique across all precompile contracts. -// See precompile/registry/registry.go for registered precompile contracts and more information. -var ContractAddress = common.HexToAddress("0x0300000000000000000000000000000000000002") -``` - - - \ No newline at end of file +``` \ No newline at end of file diff --git a/content/course/customizing-evm/07-hash-function-precompile/06-register-precompile.mdx b/content/course/customizing-evm/07-hash-function-precompile/06-register-precompile.mdx index 9e092cfc..57893b0f 100644 --- a/content/course/customizing-evm/07-hash-function-precompile/06-register-precompile.mdx +++ b/content/course/customizing-evm/07-hash-function-precompile/06-register-precompile.mdx @@ -1,12 +1,12 @@ --- -title: Registering Your Precompile +title: Register Your Precompile description: Learn how to register your precompile. -updated: 2024-05-31 -authors: [ashucoder9] +updated: 2024-09-27 +authors: [owenwahlgren] icon: Terminal --- -The next step in developing our precompile is to **register it with precompile-evm**. For this, take a look at `plugin/main.go`. You should see the following file: +The next step in developing our precompile is to **register it with precompile-evm**. Take a look at `plugin/main.go`. You should see the following file: ```go title="plugin/main.go" // (c) 2019-2023, Ava Labs, Inc. All rights reserved. @@ -36,7 +36,7 @@ func main() { } ``` -As of now, we do not have any precompile registered. As a first step, register the SHA-256 precompile. Your updated file should look like the following: +As of now, we do not have any precompile registered. To reigster a precompile, simply import the precompile package in the `plugin/main.go` file. ```go title="plugin/main.go" // (c) 2019-2023, Ava Labs, Inc. All rights reserved. @@ -54,7 +54,8 @@ import ( // Each precompile generated by the precompilegen tool has a self-registering init function // that registers the precompile with the subnet-evm. Importing the precompile package here // will cause the precompile to be registered with the subnet-evm. - _ "github.com/ava-labs/precompile-evm/sha256" + _ "github.com/ava-labs/precompile-evm/sha256"// [!code highlight:2] + _ "github.com/ava-labs/precompile-evm/md5" ) const Version = "v0.1.4" @@ -64,39 +65,3 @@ func main() { runner.Run(versionString) } ``` - -Now, register the MD5 precompile using the same format as for the SHA-256 precompile. Add the necessary line to `main.go` so that we can use the MD5 precompile. - - - - -```go title="plugin/main.go" -// (c) 2019-2023, Ava Labs, Inc. All rights reserved. -// See the file LICENSE for licensing terms. - -package main - -import ( - "fmt" - - "github.com/ava-labs/avalanchego/version" - "github.com/ava-labs/subnet-evm/plugin/evm" - "github.com/ava-labs/subnet-evm/plugin/runner" - - // Each precompile generated by the precompilegen tool has a self-registering init function - // that registers the precompile with the subnet-evm. Importing the precompile package here - // will cause the precompile to be registered with the subnet-evm. - _ "github.com/ava-labs/precompile-evm/sha256" - _ "github.com/ava-labs/precompile-evm/md5" -) - -const Version = "v0.1.4" - -func main() { - versionString := fmt.Sprintf("Precompile-EVM/%s Avalanche L1-EVM/%s [AvalancheGo=%s, rpcchainvm=%d]", Version, evm.Version, version.Current, version.RPCChainVMProtocol) - runner.Run(versionString) -} -``` - - - \ No newline at end of file diff --git a/content/course/customizing-evm/07-hash-function-precompile/08-build-and-run.mdx b/content/course/customizing-evm/07-hash-function-precompile/07-build-and-run.mdx similarity index 93% rename from content/course/customizing-evm/07-hash-function-precompile/08-build-and-run.mdx rename to content/course/customizing-evm/07-hash-function-precompile/07-build-and-run.mdx index e7b5eb80..477db5b7 100644 --- a/content/course/customizing-evm/07-hash-function-precompile/08-build-and-run.mdx +++ b/content/course/customizing-evm/07-hash-function-precompile/07-build-and-run.mdx @@ -1,8 +1,8 @@ --- title: Build and Run description: Learn how to build and run your custom VM on a local network. -updated: 2024-05-31 -authors: [ashucoder9] +updated: 2024-09-27 +authors: [ashucoder9, owenwahlgren] icon: Terminal --- @@ -39,7 +39,7 @@ Make sure you replace the binary name with the actual binary name of your Precom Next, launch the Avalanche L1 with your custom VM: ```bash -avalanche subnet deploy myblockchain +avalanche blockchain deploy myblockchain ``` After around 1 minute the blockchain should have been created and some more output should appear in the terminal. You'll also see the RPC URL of your blockchain in the terminal. \ No newline at end of file diff --git a/content/course/customizing-evm/07-hash-function-precompile/07-creating-genesis-block.mdx b/content/course/customizing-evm/07-hash-function-precompile/07-creating-genesis-block.mdx deleted file mode 100644 index f4dac0b7..00000000 --- a/content/course/customizing-evm/07-hash-function-precompile/07-creating-genesis-block.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Creating Genesis Block with precompileConfig -description: Learn how to create the genesis block with precompileConfig. -updated: 2024-05-31 -authors: [ashucoder9] -icon: Terminal ---- - -In order to create a new Blockchain from our customized EVM, we must define a Genesis block just as we did in our section earlier. - -```json title="tests/precompile/genesis/sha256.json" -{ - "config": { - "chainId": 99999, - "homesteadBlock": 0, - "eip150Block": 0, - "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0", - "eip155Block": 0, - "eip158Block": 0, - "byzantiumBlock": 0, - "constantinopleBlock": 0, - "petersburgBlock": 0, - "istanbulBlock": 0, - "muirGlacierBlock": 0, - "subnetEVMTimestamp": 0, - "feeConfig": { - "gasLimit": 20000000, - "minBaseFee": 1000000000, - "targetGas": 100000000, - "baseFeeChangeDenominator": 48, - "minBlockGasCost": 0, - "maxBlockGasCost": 10000000, - "targetBlockRate": 2, - "blockGasCostStep": 500000 - }, - "sha256Config": { - "blockTimestamp": 0 - } - }, - "alloc": { - "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": { - "balance": "0x52B7D2DCC80CD2E4000000" - } - }, - "nonce": "0x0", - "timestamp": "0x0", - "extraData": "0x00", - "gasLimit": "0x1312D00", - "difficulty": "0x0", - "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "coinbase": "0x0000000000000000000000000000000000000000", - "number": "0x0", - "gasUsed": "0x0", - "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000" -} -``` - -The precompile config only has a single entry called `blockTimestamp`. This is the activation time of the precompile. Initially, we will set this 0 so that the precompile will be available from the start. Later we will see more advanced configurations. - -## Adding PrecompileConfig for MD5 Precompile - -To incorporate the MD5 into the gensis block, we need to update the config JSON to include a key for the MD5 precompile. This key is the `configKey` that we specified in the `module.go` file of the MD5 precompile in previous section. Copy the `sha256.json` into a new file called `MD5.json`, and add the necessary key-pair value to the config. - - - - -```json title="tests/precompile/genesis/MD5.json" -{ - "config": { - "chainId": 99999, - "homesteadBlock": 0, - "eip150Block": 0, - "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0", - "eip155Block": 0, - "eip158Block": 0, - "byzantiumBlock": 0, - "constantinopleBlock": 0, - "petersburgBlock": 0, - "istanbulBlock": 0, - "muirGlacierBlock": 0, - "subnetEVMTimestamp": 0, - "feeConfig": { - "gasLimit": 20000000, - "minBaseFee": 1000000000, - "targetGas": 100000000, - "baseFeeChangeDenominator": 48, - "minBlockGasCost": 0, - "maxBlockGasCost": 10000000, - "targetBlockRate": 2, - "blockGasCostStep": 500000 - }, - "sha256Config": { - "blockTimestamp": 0 - }, - "md5Config": { - "blockTimestamp": 0 - } - }, - "alloc": { - "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": { - "balance": "0x52B7D2DCC80CD2E4000000" - } - }, - "nonce": "0x0", - "timestamp": "0x0", - "extraData": "0x00", - "gasLimit": "0x1312D00", - "difficulty": "0x0", - "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "coinbase": "0x0000000000000000000000000000000000000000", - "number": "0x0", - "gasUsed": "0x0", - "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000" -} -``` - - - \ No newline at end of file diff --git a/content/course/customizing-evm/07-hash-function-precompile/08-interact-with-md5.mdx b/content/course/customizing-evm/07-hash-function-precompile/08-interact-with-md5.mdx new file mode 100644 index 00000000..68141cd2 --- /dev/null +++ b/content/course/customizing-evm/07-hash-function-precompile/08-interact-with-md5.mdx @@ -0,0 +1,23 @@ +--- +title: Interact with Precompile +description: Interact with the MD5 precompile we just deployed. +updated: 2024-08-27 +authors: [owenwahlgren] +icon: Terminal +--- + +## Call Precompile from Foundry + +Now we will call our MD5 precompile to generate a bytes16 hash of the input string. + +**MD5 Precompile Address:** `0x0300000000000000000000000000000000000002` + +```bash +cast call --rpc-url myblockchain --private-key $PK 0x0300000000000000000000000000000000000002 "hashWithMD5(string)(bytes16)" "test" +``` + +You should see the bytes16 hash of the input string `test` as the output. + +```bash +0x098f6bcd4621d373cade4e832627b4f6 +``` \ No newline at end of file diff --git a/content/course/customizing-evm/index.mdx b/content/course/customizing-evm/index.mdx index 996e3243..d84f9500 100644 --- a/content/course/customizing-evm/index.mdx +++ b/content/course/customizing-evm/index.mdx @@ -1,31 +1,33 @@ --- title: Welcome to the Course description: Learn how to customize the Ethereum Virtual Machine. -updated: 2024-05-31 -authors: [ashucoder9] +updated: 2024-09-27 +authors: [ashucoder9, owenwahlgren] icon: Smile --- - -In this course you will learn how to customize your own EVM. We will configure the EVM using the available parameters of the `chainConfig` and modify the VM by adding precompiles. At the end of this course you will be able to build customized and optimized versions of the EVM. +import { Step, Steps } from 'fumadocs-ui/components/steps'; ## Why take this Course? A significant innovation in blockchain is the development of multi-chain systems, such as Avalanche, which provide a significant improvement in scalability, interoperability, and flexibility. At the core of these multi-chain systems is the ability to run multiple blockchains powered by different virtual machines simultaneously. Each VM of a chain is optimized for specialized use cases, thereby boosting the network's overall performance. -Configuring and modifying the Ethereum Virtual Machine (EVM) is an efficient way to create a specialized virtual machine, as it allows developers to build upon years of active community work and leverage the extensive ecosystem surrounding the EVM, including wallets, explorers, and development frameworks. - -Customizing the EVM on the Ethereum network or any other "one-chain-fits-all" network is a complex process, as it requires broad consensus that the proposed changes will benefit all participants. This makes tailoring these chains for specific use cases difficult, if not impossible. +Configuring and modifying the EVM is an efficient way to create a specialized virtual machine, as it allows developers to build upon years of active community work and leverage the extensive ecosystem surrounding the EVM, including wallets, explorers, and development frameworks. ## Course Content -### EVM Basics & Precompiles + + -In the first section of the course we will go through some basic concepts of the EVM, such as the account-based model, keys, addresses, transactions, and blocks. Furthermore, we will explain what a precompile is and let you interact with a precompile on the Fuji testnet. +### EVM Basics & Precompiles +In the first section of the course we will go through some basic concepts of the EVM, such as the account-based model, keys, addresses, transactions, and blocks. Furthermore, we will explain what a precompile is and show you how to interact with a precompile on the Fuji testnet. + + ### Development Environment Setup We will explore various ways to set up a development environment for building customized EVMs. You'll learn about GitHub Codespaces and Development Containers (`.devcontainer`). If you choose a local setup, you'll install a code editor, the Go language, configure your shell, and install additional dependencies. - + + ### Hands-On Exercises The following sections contain hands-on exercises where you customize the EVM. The difficulty of the customizations will increase from section to section. Find out more about each exercise by clicking its name below: @@ -87,6 +89,8 @@ The following sections contain hands-on exercises where you customize the EVM. T + + ## Prerequisites @@ -95,22 +99,25 @@ The following sections contain hands-on exercises where you customize the EVM. T This course is intended for people with a solid understanding of the basic concepts of Avalanche. You should be familiar with these concepts: 1. **Virtual Machines**: What they are and what VM customization means -2. **Blockchains**: What the difference between a VM, Blockchain, and an Avalanche L1 is +2. **Blockchains**: What the components are of a blockchain and how they interact, specifically how Avalanche L1s leverage precompiles. If some of this is not clear, I strongly recommend taking the [Avalanche Fundamentals](/course/avalanche-fundamentals) and [Multi-Chain Architecture](/course/multi-chain-architecture) courses first. -### Software Development +### Coding -You will need a general understanding of Software Development. You won't have to write a lot of code, but you will have to be able to understand some. Therefore, we recommend: +You will need a general understanding of software development. You won't have to write a lot of code, but you will have to be able to understand some. Therefore, we recommend: -1. **Solidity**: Basic knowledge, familiarity with types and interfaces. Familiarity with Hardhat will help in advanced sections. +1. **Solidity**: Basic knowledge, familiarity with types and interfaces. Familiarity with Foundry will help in advanced sections. 2. **Go**: You don't necessarily need to know Go, but should have some experience with an advanced object-oriented and typed language (C, C++, Java, Typescript) 3. **Testing**: It will help you in later sections if you are generally familiar with the concept of unit testing ## Learning Outcomes -By the end of this course, students will: +By the end of this course, students will be able to: -- Understand what Precompiles are and when to use them +- Understand what Precompiles are and when to use them. - Understand how developing precompiles allows developers to create more optimized and capable blockchain systems, enabling them to address entirely new use cases that were previously unattainable. - Apply the knowledge gained in the course by building multiple precompiles + + +![](/wolfie/wolfie-hack.png) diff --git a/content/course/customizing-evm/meta.json b/content/course/customizing-evm/meta.json index b5fe2696..e9f64d4d 100644 --- a/content/course/customizing-evm/meta.json +++ b/content/course/customizing-evm/meta.json @@ -9,8 +9,8 @@ "...03-development-env-setup", "---Your Own EVM Blockchain---", "...04-your-evm-blockchain", - "---EVM Configuration---", - "...05-evm-configuration", + "---Genesis Configuration---", + "...05-genesis-configuration", "---Precompiles---", "...06-precompiles", "---Hash Function Precompile---",