Merge pull request #11 from feynman-x/main

docs: outline content adjustment

README-CHINESE.md

@@ -0,0 +1,81 @@
+# EVM 内部原理
+掌握智能合约开发的**基本**且**完整**流程（编写、部署、测试和调用合约）。
+
+本教程不追求知识的大而全，而是遵循马斯克的学习方法：构建知识的语法树。
+
+```
+一点建议：把知识看作是一棵语义树很重要——在进入叶子 / 细节或者之前，先确保自己理解了基本原理，也就是这棵树的树干和大的树枝，然后再深入到树叶 / 细节，否则的话，那些树叶和细节将会无处栖身。
+```
+
+因此，本教程将围绕核心概念展开，相信学习完成后，你将有能力自主探索更多细节。
+
+## 目录
+1. [教程简介](#1-教程简介)
+2. [以太坊开发概述](#2-以太坊开发概述)
+3. [以太坊开发入门](#3-以太坊开发入门实践)
+4. [以太坊进阶](#4-以太坊进阶)
+5. [总结](#5-总结)
+
+
+## 1. 教程简介
+
+通过开发一个实际的 TODO 应用，我们将逐步深入以太坊合约开发的各个方面。从基础开始，逐步深入到更复杂的主题，确保您在每一步都能牢固掌握所学内容。
+
+## 2. 以太坊开发概述
+
+### Solidity 
+Solidity 是以太坊的官方语言，不同于 Solana 可使用 Rust、C++ 等多种语言。
+
+虽然 Vyper 也可用于以太坊应用开发，但由于安全问题（如[Vyper 重入漏洞](https://www.binance.com/en/square/post/884165)），不推荐使用。
+
+如果你有任何一门编程语言的经验，学习 Solidity 会相对容易。可以将 Solidity 理解为高级语言的简化版，例如：Solidity ≈ Java - 多线程。
+
+### Hardhat
+Hardhat 是一个强大的辅助工具，提供编译、测试和部署功能，让开发者专注于合约的开发和验证。
+
+类似工具还有官方的 Remix、开源的 Forge、Truffle 等。本教程选用 Hardhat，掌握一种即可，无需追求全面。
+
+### RPC（远程过程调用）
+部署合约后，调用合约方法或查询数据时需要使用 RPC。
+
+RPC 使用简单，只需提供一个 URL，Hardhat 就能通过该 URL 为我们处理所有相关操作. 具体功能（如 `eth_sendRawTransaction`）暂不深入，聚焦当前学习重点。
+
+## 3. 以太坊开发入门实践
+本章节开始涉及代码编写。建议亲自动手，实践是最好的学习方法。
+
+我们将通过开发一个 TODO 应用，逐步理解以太坊合约开发。完成本章后，你将掌握合约开发的基本知识。
+
+### 1. 创建 TODO 合约
+本小节学习内容: 合约基本结构
+### 2. 创建任务
+本小节学习内容:结构体、数据结构、函数 
+### 3. 完成任务（内存/存储概念）
+本小节学习内容: 内存/存储 关键字
+### 4. 删除任务 
+### 5. 提供查询方法：获取所有任务、判断任务是否存在
+本小节学习内容: view 函数
+### 6. 合约完善
+本小节学习内容: Event 的使用
+
+## 4. 以太坊进阶
+
+### 合约测试
+本小节学习内容: 使用 Hardhat 编写和运行合约测试代码.
+
+合约测试的重要性：你在处理真金白银。且合约一旦部署无法修改，上线后发现问题将束手无策。
+
+充分的测试至关重要，需要编写单元测试。好在这个过程相对简单。
+
+### 合约部署
+本小节学习内容: 使用 Hardhat 部署合约
+
+### 合约交互
+本小节学习内容: 使用 Hardhat 与合约交互
+
+## 5. 总结
+
+### 合约编写原则
+简单的说: 安全 > 性能 > 其他.
+
+### 链上安全简介
+链上安全涉及多个方面，包括重入攻击、整数溢出、权限控制等。开发时需谨慎考虑各种安全风险, 这里会展示一些真实发生过的安全事件.

README.md

@@ -1,64 +1,86 @@
-# EVM Internals
+# EVM Internal Principles
+[中文](./README-CHINESE.md)
 
-Welcome to the **EVM-Internal** tutorial! This guide is designed to provide a comprehensive understanding of the internal implementation of the Ethereum Virtual Machine (EVM). Whether you're a beginner or an experienced developer, this tutorial will help you grasp the core concepts and functionalities of the EVM kernel.
+Welcome to the **EVM-Internal** tutorial ! 
+This guide is designed to teach you master the **basic** and **complete** process of smart contract development (writing, deploying, testing, and calling contracts).
 
-## Table of Contents
+This tutorial does not aim for comprehensive knowledge, but follows Elon Musk's learning method: building a knowledge syntax tree.
+
+```
+A bit of advice:
+It's important to view knowledge as a semantic tree - make sure you understand the fundamental principles,
+i.e. the trunk and big branches, before you get into the leaves/details or there is nothing for them to hang on to.
+```
 
-1. [Introduction](#introduction)
-2. [Overview of EVM](#overview-of-evm)
-3. [Architecture of EVM](#architecture-of-evm)
-4. [Setting Up Your Development Environment](#setting-up-your-development-environment)
-5. [Core Components of EVM](#core-components-of-evm)
-    - 5.1 [Execution Environment](#execution-environment)
-    - 5.2 [Opcode Implementation](#opcode-implementation)
-    - 5.3 [State Management](#state-management)
-6. [Building a Simple EVM Implementation](#building-a-simple-evm-implementation)
-7. [Testing and Debugging](#testing-and-debugging)
-8. [Best Practices](#best-practices)
-9. [Conclusion](#conclusion)
+Therefore, this tutorial will focus on core concepts, and we believe that after completing the study, you will have the ability to explore more details independently.
+
+## Table of Contents
+1. [Tutorial Introduction](#1-tutorial-introduction)
+2. [Ethereum Development Overview](#2-ethereum-development-overview)
+3. [Getting Started with Ethereum Development](#3-getting-started-with-ethereum-development-practice)
+4. [Advanced Ethereum](#4-advanced-ethereum)
+5. [Summary](#5-summary)
 
-## 1. Introduction
 
-The **EVM-Internal** tutorial aims to demystify the Ethereum Virtual Machine's internal workings. By exploring its architecture and components, you'll gain insights into how smart contracts are executed on the Ethereum blockchain.
+## 1. Tutorial Introduction
 
-## 2. Overview of EVM
+By developing a practical TODO application, we will gradually delve into various aspects of Ethereum contract development. Starting from the basics and progressing to more complex topics, we ensure that you can firmly grasp the content learned at each step.
 
-This section provides a high-level overview of the EVM, its purpose, and its role in the Ethereum ecosystem.
+## 2. Ethereum Development Overview
 
-## 3. Architecture of EVM
+### Solidity 
+Solidity is the official language of Ethereum, unlike Solana which can use multiple languages such as Rust, C++, etc.
 
-Learn about the architectural design of the EVM, including its components and how they interact with each other during execution.
+Although Vyper can also be used for Ethereum application development, it is not recommended due to security issues (such as the [Vyper reentrancy vulnerability](https://www.binance.com/en/square/post/884165)).
 
-## 4. Setting Up Your Development Environment
+If you have experience with any programming language, learning Solidity will be relatively easy. Solidity can be understood as a simplified version of high-level languages, for example: Solidity ≈ Java - multithreading.
 
-Step-by-step instructions on setting up your development environment for EVM kernel implementation, including tools and dependencies.
+### Hardhat
+Hardhat is a powerful auxiliary tool that provides compilation, testing, and deployment functions, allowing developers to focus on contract development and verification.
 
-## 5. Core Components of EVM
+Similar tools include the official Remix, open-source Forge, Truffle, etc. This tutorial chooses Hardhat, mastering one is sufficient, there's no need to pursue comprehensiveness.
 
-### 5.1 Execution Environment
+### RPC (Remote Procedure Call)
+After deploying a contract, RPC is needed when calling contract methods or querying data.
 
-Discover the execution environment of the EVM and how it facilitates the processing of transactions and smart contracts.
+RPC is simple to use, just provide a URL, and Hardhat can handle all related operations for us through that URL. We won't delve into specific functions (such as `eth_sendRawTransaction`) for now, focusing on the current learning priorities.
 
-### 5.2 Opcode Implementation
+## 3. Getting Started with Ethereum Development Practice
+This section begins to involve code writing. It's recommended to practice hands-on, as practice is the best learning method.
 
-Explore the various opcodes supported by the EVM, their functionalities, and how to implement them.
+We will gradually understand Ethereum contract development by developing a TODO application. After completing this chapter, you will master the basic knowledge of contract development.
 
-### 5.3 State Management
+### 1. Creating a TODO Contract
+Learning content in this subsection: Basic contract structure
+### 2. Creating Tasks
+Learning content in this subsection: Structs, data structures, functions 
+### 3. Completing Tasks (Memory/Storage Concepts)
+Learning content in this subsection: Memory/Storage keywords
+### 4. Deleting Tasks 
+### 5. Providing Query Methods: Get All Tasks, Check if a Task Exists
+Learning content in this subsection: View functions
+### 6. Contract Refinement
+Learning content in this subsection: Use of Events
 
-Understand how the EVM manages state, including account states and storage, and the mechanisms involved.
+## 4. Advanced Ethereum
 
-## 6. Building a Simple EVM Implementation
+### Contract Testing
+Learning content in this subsection: Writing and running contract test code using Hardhat.
 
-Follow along with detailed instructions to build a simple EVM implementation from scratch, gaining hands-on experience.
+The importance of contract testing: You're dealing with real money. And once a contract is deployed, it cannot be modified, leaving you helpless if problems are discovered after going live.
 
-## 7. Testing and Debugging
+Thorough testing is crucial, and unit tests need to be written. Fortunately, this process is relatively simple.
 
-Learn effective strategies for testing and debugging your EVM implementation to ensure reliability and performance.
+### Contract Deployment
+Learning content in this subsection: Deploying contracts using Hardhat
 
-## 8. Best Practices
+### Contract Interaction
+Learning content in this subsection: Interacting with contracts using Hardhat
 
-Explore best practices for developing and optimizing EVM-related projects, ensuring efficient and secure implementations.
+## 5. Summary
 
-## 9. Conclusion
+### Contract Writing Principles
+Simply put: Security > Performance > Others.
 
-By the end of this tutorial, you will have a solid understanding of the internal workings of the EVM and be equipped to implement your own solutions. Let’s get started on this exciting journey into the world of Ethereum!
+### Introduction to On-chain Security
+On-chain security involves multiple aspects, including reentrancy attacks, integer overflow, access control, etc. Various security risks need to be carefully considered during development. Some real security incidents that have occurred will be showcased here.