diff --git a/source/about.rst b/source/about.rst index b17e3654..d1172d11 100644 --- a/source/about.rst +++ b/source/about.rst @@ -1,16 +1,15 @@ *************************************** -The Homestead Documentation Initiative +The Homestead Documentation initiative *************************************** |Gitter| .. |Gitter| image:: img/homestead-guide.svg :target: https://gitter.im/ethereum/homestead-guide?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge -Purpose and Audience +Purpose and audience =============================================================================== -This guide should serve to be an entry level for all Ethereum users and developers. -The goal is to create documentation with information, short tutorials, and examples that will cover all of the basic and intermediate functionality of using Ethereum to interact with dapps or develop a dapp. +This guide serves as an entry level text for Ethereum users and developers. The goal is to create documentation with information, short tutorials, and examples that will cover all of the basic and intermediate functionality of using Ethereum to interact with dapps or develop a dapp. Any information that is overly specific, technical, or not necessary to accomplish the documentation's goal will remain on the Ethereum Github Wiki. It may be referenced in this guide if necessary. @@ -24,7 +23,7 @@ Examples of overly specific and technical documentation include: * ETHash, CASPER, ABI, RLP, or other technical specs. * Full API specs for protocols. Caveat: If an example, information, or tutorial needs to reference API calls for a client or interface in order to fulfill its example it is acceptable to reference the specific call. Be sure to make a reference where the user can find remaining pieces of the specific documentation that may be on the GitHub Wiki. -Resources for Exemplary Documentation +Resources for exemplary documentation =============================================================================== Here are some examples of previous Ethereum documentation + good examples of documentation. @@ -36,7 +35,7 @@ Here are some examples of previous Ethereum documentation + good examples of doc * Other Ethereum Links: https://souptacular.gitbooks.io/ethereum-tutorials-and-tips-by-hudson/content/giant_ethereum_resource_list.html * Django Docs - https://docs.djangoproject.com/en/1.9/ -Restructured Text Markup, Sphinx +Restructured text markup, Sphinx ======================================= * Best Cheat Sheet - https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst @@ -45,7 +44,7 @@ Restructured Text Markup, Sphinx * RST Primer http://sphinx-doc.org/rest.html * http://sphinx-doc.org/markup/inline.html -Compilation and Deployment +Compilation and deployment =============================================================================== We use `make` with the autogenerated read-the-docs `Makefile` to build the doc. @@ -56,7 +55,7 @@ We use `make` with the autogenerated read-the-docs `Makefile` to build the doc. cd homestead-guide make html -Processing Tips +Processing tips =============================================================================== Fix section delimiter lines (always use 80-long ones to have correct length, unless the title is greater than 80 chars in length) @@ -69,12 +68,12 @@ Fix section delimiter lines (always use 80-long ones to have correct length, unl for f in `ls source/*/*.rst`; do cat $f|perl -pe 's/\++$/++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++/' > $f.o; mv $f.o $f; done for f in `ls source/*/*.rst`; do cat $f|perl -pe 's/\#+$/################################################################################/' > $f.o; mv $f.o $f; done -Referencing Old Documentation +Referencing old documentation =============================================================================== old-docs-for-reference folder has all of the Frontier Gitbook and Ethereum Wiki doc. Feel free to copy/paste information from those documents that is still relevant. -Migrate and Convert Old Wiki Content Using Pandoc +Migrate and convert old Wiki content using Pandoc =============================================================================== If you still want to clone the absolute latest Ethereum Wiki and Frontier Guide docs: diff --git a/source/account-management.rst b/source/account-management.rst index 741b84da..b4492c47 100644 --- a/source/account-management.rst +++ b/source/account-management.rst @@ -1,5 +1,5 @@ ******************************************************************************** -Account Management +Account management ******************************************************************************** .. _Accounts: @@ -7,17 +7,25 @@ Account Management Accounts ================================================================================ -Accounts play a central role in Ethereum. There are two types of accounts: *externally owned accounts* (EOAs) and *contract accounts*. Here we focus on externally owned accounts, which will be referred to simply as *accounts*. Contract accounts will be referred to as *contracts* and are :ref:`discussed in detail in Contracts `. This generic notion of account subsuming both externally owned accounts and contracts is justified in that these entities are so called *state objects*. These entities have a state: accounts have balance and contracts have both balance and contract storage. The state of all accounts is the state of the Ethereum network which is updated with every block and which the network really needs to reach a consensus about. -Accounts are essential for users to interact with the Ethereum blockchain via transactions. +Accounts play a central role in Ethereum. There are two types of accounts: *externally owned accounts* (EOAs) and *contract accounts*. -If we restrict Ethereum to only externally owned accounts and allow only transactions between them, we arrive at an "altcoin" system that is less powerful than bitcoin itself and can only be used to transfer ether. +This section describes externally owned accounts, which will be referred to simply as *accounts*. Contract accounts will be referred to as *contracts* and are :ref:`discussed in detail in Contracts `. -Accounts represent identities of external agents (e.g., human personas, mining nodes or automated agents). Accounts use public key cryptography to sign transaction so that the EVM can securely validate the identity of a transaction sender. +This generic notion of account subsuming both externally owned accounts and contracts is justified in that these entities are so called *state objects*. These entities have a state: accounts have balance and contracts have both balance and contract storage. The state of all accounts is the state of the Ethereum network which is updated with every block and which the network really needs to reach a consensus about. +Accounts interact with the Ethereum blockchain via transactions. + +Accounts represent identities of external agents (e.g., human personas, mining nodes +or automated agents). Accounts use public key cryptography to sign transactions so +that the EVM can securely validate the identity of a transaction sender. Keyfiles ================================================================================ -Every account is defined by a pair of keys, a private key and public key. Accounts are indexed by their *address* which is derived from the public key by taking the last 20 bytes. Every private key/address pair is encoded in a *keyfile*. Keyfiles are JSON text files which you can open and view in any text editor. The critical component of the keyfile, your account’s private key, is always encrypted, and it is encrypted with the password you enter when you create the account. Keyfiles are found in the ``keystore`` subdirectory of your Ethereum node’s data directory. Make sure you backup your keyfiles regularly! See the section :ref:`backup-and-restore-accounts` for more information. +Every account is defined by a pair of keys, a private key and public key. Accounts +are indexed by their *address* which is derived from the public key by taking the +last 20 bytes. Every private key/address pair is encoded in a *keyfile*. + +Keyfiles are JSON text files which you can open and view in any text editor. The critical component of the keyfile, your account’s private key, is always encrypted, and it is encrypted with the password you enter when you create the account. Keyfiles are found in the ``keystore`` subdirectory of your Ethereum node’s data directory. Make sure you backup your keyfiles regularly! See the section :ref:`backup-and-restore-accounts` for more information. Creating a key is tantamount to creating an account. @@ -30,7 +38,7 @@ Of course your new account will not contain any Ether. But it'll be yours and yo It is safe to transfer the entire directory or any individual keyfile between Ethereum nodes. -.. Warning:: Note that in case you are adding keyfiles to your node from a different node, the order of accounts may change. So make sure you do not rely or change the index in your scripts or code snippets. +.. Warning:: Note that in case you are adding keyfiles to your node from a different node, the order of accounts may change. So make sure you do not rely on or change the index in your scripts or code snippets. .. _creating_an_account: @@ -82,7 +90,7 @@ To list all the accounts with keyfiles currently in you’re ``keystore`` folder account #2: {7f444580bfef4b9bc7e14eb7fb2a029336b07c9d} -The filenames of keyfiles has the format ``UTC---
``. The order of accounts when listing, is lexicographic, but as a consequence of the timestamp format, it is actually order of creation. +The filenames of keyfiles has the format ``UTC---
``. The order of accounts when listing, is lexicographic (alphabetic), but as a consequence of the timestamp format, it is actually order of creation. Using geth console @@ -166,7 +174,7 @@ Creating an account using the GUI Mist Ethereum wallet couldn’t be easier. In .. Note:: The Mist wallet is still in active development, so details of the steps outlined above may change with upgrades. -Creating a Multi-Signature Wallet in Mist +Creating a multi-signature wallet in Mist -------------------------------------------------------------------------------- The Mist Ethereum wallet has an option to secure your wallet balance with a multisig wallet. The advantage of using a multisig wallet is that it requires authorization from more than one account to withdrawal larger amounts from your balance. Before you can create a multisig wallet, you'll need to create more than one account. @@ -205,7 +213,7 @@ Troubleshooting: Using Eth -------------------------------------------------------------------------------- -Every options related to key management available using geth can be used the same way in eth. +Every option related to key management available using geth can be used the same way in eth. Below are "account" related options: @@ -301,43 +309,6 @@ Now let's make sure it worked properly by listing the keys in the wallet: It reports one key on each line (for a total of one key here). In this case our key is stored in a file 055dde... and has an ICAP address beginning XE472EVK.... Not especially easy things to remember so rather helpful that it has its proper name, test, too. -Importing your presale wallet -================================================================================ - - -Using Mist Ethereum wallet --------------------------------------------------------------------------------- - -Importing your presale wallet using the GUI Mist Ethereum wallet is very easy. In fact, you will be asked if you want to import your presale wallet during the installation of the app. - -.. Warning:: Mist wallet is beta software. Beware and use it at your own risk. - -Instructions for installing the Mist Ethereum wallet are given in the section :ref:`Creating an account: Using Mist Ethereum wallet `. - -Simply drag-and-drop your ``.json`` presale wallet file into the designated area and enter your password to import your presale account. - -.. image:: img/51PresaleImportInstall.png - :width: 582px - :height: 469px - :scale: 75 % - :alt: presale-import - :align: center - -If you choose not to import your presale wallet during installation of the app, you can import it at any time by selecting the ``Accounts`` menu in the app’s menu bar and then selecting ``Import Pre-sale Accounts``. - -.. Note:: The Mist wallet is still in active development, so details of the steps outlined above may change with upgrades. - -Using geth --------------------------------------------------------------------------------- - -If you have a standalone installation of geth, importing your presale wallet is accomplished by executing the following command in a terminal: - -.. code-block:: Bash - - geth wallet import /path/to/my/presale-wallet.json - -You will be prompted to enter your password. - Updating an account ================================================================================ diff --git a/source/contracts-and-transactions/accessing-contracts-and-transactions.rst b/source/contracts-and-transactions/accessing-contracts-and-transactions.rst index d02bfc08..b025a298 100644 --- a/source/contracts-and-transactions/accessing-contracts-and-transactions.rst +++ b/source/contracts-and-transactions/accessing-contracts-and-transactions.rst @@ -1,5 +1,5 @@ ******************************************************************************** -Accessing Contracts and Transactions +Accessing contracts and transactions ******************************************************************************** RPC @@ -249,7 +249,7 @@ can connect to a local or remote geth or eth node. It will load the web3.js libr smart contract from the console using web3.js. In fact the examples in the :ref:`Web3.js ` section can by copied into the console. -Viewing Contracts and Transactions +Viewing contracts and transactions ================================================================================ There are several online blockchain explorers available that will allow you to inspect the Ethereum blockchain. @@ -265,7 +265,7 @@ Hosted blockchain explorers - `EtherCamp `_ - `EtherScan `_ (and for `Testnet `_) -Other Resources +Other resources -------------------------------------------------------------------------------- * `EtherNodes `_ - Geographic distribution of nodes and split by client diff --git a/source/contracts-and-transactions/account-types-gas-and-transactions.rst b/source/contracts-and-transactions/account-types-gas-and-transactions.rst index e06018c5..ba57dc48 100644 --- a/source/contracts-and-transactions/account-types-gas-and-transactions.rst +++ b/source/contracts-and-transactions/account-types-gas-and-transactions.rst @@ -1,7 +1,7 @@ .. _account-types-gas-and-transactions: ******************************************************************************** -Account Types, Gas, and Transactions +Account types, gas, and transactions ******************************************************************************** EOA vs contract accounts diff --git a/source/contracts-and-transactions/developer-tools.rst b/source/contracts-and-transactions/developer-tools.rst index 4f03b44f..f49793b3 100644 --- a/source/contracts-and-transactions/developer-tools.rst +++ b/source/contracts-and-transactions/developer-tools.rst @@ -32,7 +32,7 @@ Dapp browsers * `Supernova `_ - (discontinued). ******************************************************************************** -Developer Tools +Developer tools ******************************************************************************** diff --git a/source/contracts-and-transactions/ethereum-tests/index.rst b/source/contracts-and-transactions/ethereum-tests/index.rst index b0b274bf..5f134d64 100644 --- a/source/contracts-and-transactions/ethereum-tests/index.rst +++ b/source/contracts-and-transactions/ethereum-tests/index.rst @@ -1,10 +1,10 @@ -.. _Ethereum Tests: +.. _Ethereum tests: ################################################################################ -Ethereum Tests +Ethereum tests ################################################################################ -| Common tests for all clients to test against. The `git repo `_ updated regulary with new tests. -| This section describes basic test concepts and templates which are created by cpp-client. +| Common tests for all clients to test against. The `git repo `_ updated regulary with new tests. +| This section describes basic test concepts and templates which are created by cpp-client. | .. toctree:: diff --git a/source/contracts-and-transactions/index.rst b/source/contracts-and-transactions/index.rst index f615486f..01d3c50d 100644 --- a/source/contracts-and-transactions/index.rst +++ b/source/contracts-and-transactions/index.rst @@ -1,5 +1,5 @@ ################################################################################ -Contracts and Transactions +Contracts and transactions ################################################################################ .. toctree:: diff --git a/source/contracts-and-transactions/web3-base-layer-services.rst b/source/contracts-and-transactions/web3-base-layer-services.rst index f2664ba5..d3555435 100644 --- a/source/contracts-and-transactions/web3-base-layer-services.rst +++ b/source/contracts-and-transactions/web3-base-layer-services.rst @@ -1,5 +1,5 @@ ******************************************************************************** -Web3 Base Layer Services +Web3 base layer services ******************************************************************************** In addition to the Ethereum blockchain, more components are being developed that decentralise other important aspects of web applications. diff --git a/source/ethereum-clients/choosing-a-client.rst b/source/ethereum-clients/choosing-a-client.rst index f1df14a8..16702e05 100644 --- a/source/ethereum-clients/choosing-a-client.rst +++ b/source/ethereum-clients/choosing-a-client.rst @@ -63,7 +63,7 @@ releases. The table below contains links to the latest release. .. _ruby-ethereum-v0.9.3: https://rubygems.org/gems/ruby-ethereum/versions/0.9.3 ******************************************************************************** -Installing a Client +Installing a client ******************************************************************************** There are a number of "official" clients whose development has been funded diff --git a/source/ethereum-clients/index.rst b/source/ethereum-clients/index.rst index 43a07369..9e446027 100644 --- a/source/ethereum-clients/index.rst +++ b/source/ethereum-clients/index.rst @@ -1,7 +1,7 @@ -.. _Ethereum Clients: +.. _Ethereum clients: ################################################################################ -Ethereum Clients +Ethereum clients ################################################################################ .. toctree:: diff --git a/source/frequently-asked-questions/frequently-asked-questions.rst b/source/frequently-asked-questions/frequently-asked-questions.rst index 9c19857a..b0fd7658 100644 --- a/source/frequently-asked-questions/frequently-asked-questions.rst +++ b/source/frequently-asked-questions/frequently-asked-questions.rst @@ -104,10 +104,6 @@ How will Ethereum ensure the network is capable of making 10,000+ transactions-p ---------------------------------------------------------------------------------------------- Ethereum is planning on implementing a proof-of-stake consensus protocol change during the Serenity phase of their development roadmap. More information on the likely Ethereum PoS candidate and how it may increase transactions-per-second can be `found here `_. -Where do the contracts reside? ----------------------------------------------------------------------------------------------- -TODO - Your question is still not answered? ---------------------------------------------------------------------------------------------- Ask the community on `Ethereum StackExchange `_. diff --git a/source/glossary.rst b/source/glossary.rst index 19e9bd4d..a759fda9 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -13,11 +13,10 @@ Glossary .. _dec-app: decentralized application (= dapp_) - Service that operates without a central trusted party. An application that enables direct interaction/agreements/communication between end users and/or resources without a middleman. See :ref:`dapps`. + A service that operates without a central trusted party. An application that enables direct interaction/agreements/communication between end users and/or resources without a middleman. See :ref:`dapps`. DAO - decentralized autonomous organization - DAO is type of contract on the blockchain (or a suite of contracts) that is supposed to codify, enforce or automate the workings of an organization including governance, fund-raising, operations, spending and expansion. + A DAO (decentralized autonomous organization) is a type of contract on the blockchain codifies, enforces or automates the workings of an organization including governance, fund-raising, operations, spending and expansion. identity A set of cryptographically verifiable interactions that have the property that they were all created by the same person. @@ -32,7 +31,11 @@ Glossary The property of an identity that other entities believe that identity to be either (1) competent at some specific task, or (2) trustworthy in some context, i.e., not likely to betray others even if short-term profitable. escrow - If two mutually-untrusting entities are engaged in commerce, they may wish to pass funds through a mutually trusted third party and instruct that party to send the funds to the payee only when evidence of product delivery has been shown. This reduces the risk of the payer or payee committing fraud. Both this construction and the third party is called escrow. + A bond that allows two mutually-untrusting entities to pass funds through + a mutually trusted third party and instruct that party to send the funds + to the payee only when evidence of product delivery has been shown. This + reduces the risk of the payer or payee committing fraud. Both this + construction and the third party are called escrows. deposit Digital property placed into a contract involving another party such that if certain conditions are not satisfied that property is automatically forfeited and either credited to a counterparty as insurance against the conditions, or destroyed (= burnt = equally distributed) or donated to some charitable funds. @@ -203,7 +206,7 @@ Glossary The agreement among all nodes in the network about the state of the Ethereum network. homestead - Homestead is the second major version release of the Ethereum platform. Homestead includes several protocol changes and a networking change that makes possible further network upgrades: `EIP\-2 Main homestead hardfork changes `_; `EIP\-7 Hardfork EVM update (DELEGATECALL) `_; `EIP\-8 devp2p forward compatibility `_. Homestead will launch when block 1,150,000 is reached on the Mainnet. On the Testnet, Homestead will launch at block 494,000. + Homestead is the second major version release of the Ethereum platform. Homestead includes several protocol changes and a networking change that makes possible further network upgrades: `EIP\-2 Main homestead hardfork changes `_; `EIP\-7 Hardfork EVM update (DELEGATECALL) `_; `EIP\-8 devp2p forward compatibility `_. Homestead launched when block 1,150,000 was reached on the Mainnet. metropolis The third stage of Ethereum's release. This is the stage when the user interfaces come out (e.g. Mist), including a dapp store, and non-technical users should feel comfortable joining at this point. diff --git a/source/index.rst b/source/index.rst index 17eaa691..c874c5c9 100644 --- a/source/index.rst +++ b/source/index.rst @@ -13,10 +13,10 @@ Ethereum Homestead Documentation :alt: ethereum-logo :align: center -This documentation is the result of an ongoing collaborative effort by -volunteers from the Ethereum :ref:`community`. Although it has not been -authorized by the :ref:`foundation`, we hope you will find it useful. -We welcome new :ref:`contributors`. +The Ethereum Homestead Documentation describes the Ethereum blockchain network +as of its second major software update, Homestead. + +The Ethereum volunteer :ref:`community` maintains the documentation and welcomes :ref:`contributors`. Contents diff --git a/source/introduction/contributors.rst b/source/introduction/contributors.rst index 98a26a54..6b9339e7 100644 --- a/source/introduction/contributors.rst +++ b/source/introduction/contributors.rst @@ -11,7 +11,7 @@ which was coordinated by: - `Viktor Trón ("zelig") `_ - `Hudson Jameson ("Souptacular") `_ - + We would like to thank everybody who helped in this effort for `their contributions `_: .. image:: ../img/Feels-Good-Man-Frog-02.png diff --git a/source/introduction/index.rst b/source/introduction/index.rst index 0d5dbe5e..2c00069e 100644 --- a/source/introduction/index.rst +++ b/source/introduction/index.rst @@ -6,11 +6,10 @@ Introduction :maxdepth: 2 what-is-ethereum.rst - how-to-use-this-guide.rst the-homestead-release.rst - web3.rst + decentralized_apps.rst history-of-ethereum.rst community.rst foundation.rst - contributors.rst \ No newline at end of file + contributors.rst diff --git a/source/introduction/the-homestead-release.rst b/source/introduction/the-homestead-release.rst index 36f2da95..d4530cfe 100644 --- a/source/introduction/the-homestead-release.rst +++ b/source/introduction/the-homestead-release.rst @@ -1,8 +1,8 @@ ******************************************************************************** -The Homestead Release +The Homestead release ******************************************************************************** -Homestead is the second major version of the Ethereum platform and is the first production release of Ethereum. It includes several protocol changes and a networking change that provides the ability to do further network upgrades. The first version of Ethereum, called the Frontier release, was essentially a beta release that allowed developers to learn, experiment, and begin building Ethereum decentralized apps and tools. +Homestead is the second major version of the Ethereum platform and is the first production release of Ethereum. It includes several protocol changes and a networking change that provides the ability to do further network upgrades. The first version of Ethereum, called the Frontier release, was essentially a beta release that allowed developers to learn, experiment, and begin building Ethereum decentralized apps and tools. Milestones of the Ethereum development roadmap ----------------------------------------------- diff --git a/source/introduction/web3.rst b/source/introduction/web3.rst deleted file mode 100644 index 0d15c45a..00000000 --- a/source/introduction/web3.rst +++ /dev/null @@ -1,43 +0,0 @@ - -Web 3: A platform for decentralized apps -******************************************************************************** - - - -Many have come to believe that an open, trustless blockchain platform like Ethereum is perfectly suited to serve as the shared "back end" to a decentralized, secure internet - Web 3.0. An internet where core services like DNS and digital identity are decentralized, and where individuals can engage in economic interactions with each other. - -As intended by the Ethereum developers, Ethereum is a blank canvas and you have the freedom to build whatever you want with it. The Ethereum protocol is meant to be generalized so that the core features can be combined in arbitrary ways. Ideally, dapp projects on Ethereum will leverage the Ethereum blockchain to build solutions that rely on decentralized consensus to provide new products and services that were not previously possible. - -Ethereum is perhaps best described as an ecosystem: the core protocol is supported by various pieces of infrastructure, code, and community that together make up the Ethereum project. Ethereum can also be understood by looking at the projects that use Ethereum. Already, there are a number of high-profile projects built on Ethereum such as Augur, Digix, Maker, and many more (see :ref:`dapps`). In addition, there are development teams that build open source components that anyone can use. While each of these organizations are separate from the Ethereum Foundation and have their own goals, they undoubtedly benefit the overall Ethereum ecosystem. - -Further Watching/Reading: - -* Vitalik Buterin - TNABC 2015: https://www.youtube.com/watch?v=Fjhe0MVRHO4 - -* Gavin Wood - DEVCON 1 - Ethereum for Dummies: https://www.youtube.com/watch?v=U_LK0t_qaPo - -* Ethereum London Meetup (best detailed here): https://www.youtube.com/watch?v=GJGIeSCgskc - -Smart contracts -================================================================================ - -by Alex: - -Would you enter in a contract with someone you've never met? Would you agree to lend money to some farmer in Ethiopia? Would you become an investor in a minority-run newspaper in a war zone? Would you go to the hassle of writing up a legal binding contract for a $5 dollar purchase over the internet? - -The answer is no for most of these questions, the reason being that a contract requires a large infrastructure: sometimes you need a working trust relationship between the two parties, sometimes you rely on a working legal system, police force and lawyer costs. - -In Ethereum you don't need any of that: if all the requisites to the contract can be put in the blockchain then they will, in a trustless environment for almost no cost. - -Instead of thinking of moving your current contracts to the blockchain, think of all the thousand little contracts that you would never agree to simply because they weren't economically feasible or there was not enough legal protection.. - - -DAO -================================================================================ - -Here is just one example: imagine you own a small business with your friends. Lawyers and accountants are expensive, and trusting a single partner to oversee the books can be a source of tension (even an opportunity for fraud). Complying strictly with a system in which more than one partner oversees the books can be trying and is subject to fraud whenever the protocol isn't followed exactly. - -Using a smart contract, ownership in your company and terms for the disbursal of funds can be specified at the outset. The smart contract can be written such that it is only changeable given the approval of a majority of owners. Smart contracts like these will likely be available as open source software, so you won't even need to hire your own programmer instead of an accountant/lawyer. - -A smart contract like this scales instantly. A couple of teenagers can split revenue from a lemonade stand just as transparently as a sovereign wealth fund can disburse funds to the hundred million citizens who are entitled to it. In both cases the price of this transparency is likely to be fractions of a penny per dollar. - diff --git a/source/introduction/what-is-ethereum.rst b/source/introduction/what-is-ethereum.rst index 5d293c73..e2f766c0 100644 --- a/source/introduction/what-is-ethereum.rst +++ b/source/introduction/what-is-ethereum.rst @@ -1,42 +1,86 @@ .. _what-is-ethereum: ################################################################################ -What is Ethereum? +What is Ethereum ? ################################################################################ +.. raw:: html -Ethereum is an open blockchain platform that lets anyone build and use decentralized applications that run on blockchain technology. Like Bitcoin, no one controls or owns Ethereum – it is an open-source project built by many people around the world. But unlike the Bitcoin protocol, Ethereum was designed to be adaptable and flexible. It is easy to create new applications on the Ethereum platform, and with the Homestead release, it is now safe for anyone to use those applications. + + + +Ethereum is a blockchain platform that lets you build decentralized applications +and deploy them via its distributed network of database nodes. People around the +world develop and maintain its open source, on-chain programming environment. ================================================================================ -A next generation blockchain +Origins ================================================================================ + .. raw:: html + + + + + +In late 2013, Ethereum's inventor Vitalik Buterin proposed that a single blockchain +with the capability to be reprogrammed to perform any arbitrarily complex +computation could subsume these many other projects. In 2014, Ethereum founders +Vitalik Buterin, Gavin Wood and Jeffrey Wilcke began implementing Ethereum as a +scalable, trustless smart contract platform. -Blockchain technology is the technological basis of Bitcoin, first described by its mysterious author Satoshi Nakamoto in his white paper "Bitcoin: A Peer-to-Peer Electronic Cash System", published in 2008. While the use of blockchains for more general uses was already discussed in the original paper, it was not until a few years later that blockchain technology emerged as a generic term. A blockchain is a distributed computing architecture where every network node executes and records the same transactions, which are grouped into blocks. Only one block can be added at a time, and every block contains a mathematical proof that verifies that it follows in sequence from the previous block. In this way, the blockchain’s "distributed database" is kept in consensus across the whole network. Individual user interactions with the ledger (transactions) are secured by strong cryptography. Nodes that maintain and verify the network are incentivized by mathematically enforced economic incentives coded into the protocol. +================================================================================ +The Ethereum Virtual Machine +================================================================================ -In Bitcoin's case the distributed database is conceived of as a table of account balances, a ledger, and transactions are transfers of the bitcoin token to facilitate trustless finance between individuals. But as bitcoin began attracting greater attention from developers and technologists, novel projects began to use the bitcoin network for purposes other than transfers of value tokens. Many of these took the form of "alt coins" - separate blockchains with cryptocurrencies of their own which improved on the original bitcoin protocol to add new features or capabilities. In late 2013, Ethereum's inventor Vitalik Buterin proposed that a single blockchain with the capability to be reprogrammed to perform any arbitrarily complex computation could subsume these many other projects. +Unlike previous generations of blockchain technology which pre-defined operations, +Ethereum allows you to create on chain program operations of any complexity. +In this way, it serves as a platform for many different types of decentralized +blockchain applications, including cryptocurrencies. -In 2014, Ethereum founders Vitalik Buterin, Gavin Wood and Jeffrey Wilcke began work on a next-generation blockchain that had the ambitions to implement a general, fully trustless smart contract platform. +The Ethereum network protocols define the platform at the heart of which is the +:ref:`Ethereum Virtual Machine ("EVM") `, which can execute code of +arbitrary algorithmic complexity. -================================================================================ -Ethereum Virtual Machine -================================================================================ +In computer science terms, Ethereum is "Turing complete", meaning that developers +can create applications that run on the EVM using friendly programming languages +modelled on existing languages like JavaScript and Python. -Ethereum is a programmable blockchain. Rather than give users a set of pre-defined operations (e.g. bitcoin transactions), Ethereum allows users to create their own operations of any complexity they wish. In this way, it serves as a platform for many different types of decentralized blockchain applications, including but not limited to cryptocurrencies. +Like any blockchain, Ethereum also includes a peer-to-peer network protocol. The +Ethereum blockchain database is maintained and updated by many nodes connected to +the network. Each and every node of the network runs the EVM and executes the +same instructions. For this reason, Ethereum is sometimes described as a "world computer". -Ethereum in the narrow sense refers to a suite of protocols that define a platform for decentralised applications. At the heart of it is the :ref:`Ethereum Virtual Machine ("EVM") `, which can execute code of arbitrary algorithmic complexity. In computer science terms, Ethereum is "Turing complete". Developers can create applications that run on the EVM using friendly programming languages modelled on existing languages like JavaScript and Python. +This massive parallelisation of computing across the entire Ethereum network is +not done to make computation more efficient. In fact, this process makes computation +on Ethereum far slower and more expensive than on a traditional "computer". -Like any blockchain, Ethereum also includes a peer-to-peer network protocol. The Ethereum blockchain database is maintained and updated by many nodes connected to the network. Each and every node of the network runs the EVM and executes the same instructions. For this reason, Ethereum is sometimes described evocatively as a "world computer". +Rather, every Ethereum node runs the EVM to maintain consensus across the blockchain. +Decentralized consensus gives Ethereum extreme levels of fault tolerance, and makes +data stored on the blockchain censorship-resistant. -This massive parallelisation of computing across the entire Ethereum network is not done to make computation more efficient. In fact, this process makes computation on Ethereum far slower and more expensive than on a traditional "computer". Rather, every Ethereum node runs the EVM in order to maintain consensus across the blockchain. Decentralized consensus gives Ethereum extreme levels of fault tolerance, ensures zero downtime, and makes data stored on the blockchain forever unchangeable and censorship-resistant. +The Ethereum platform itself is not an end-user application. It is up to entrepreneurs +and developers to decide what it should be used for. -The Ethereum platform itself is featureless or value-agnostic. Similar to programming languages, it is up to entrepreneurs and developers to decide what it should be used for. However, it is clear that certain application types benefit more than others from Ethereum's capabilities. Specifically, ethereum is **suited for applications that automate direct interaction between peers or facilitate coordinated group action across a network**. For instance, applications for coordinating peer-to-peer marketplaces, or the automation of complex financial contracts. Bitcoin allows for individuals to exchange cash without involving any middlemen like financial institutions, banks, or governments. Ethereum’s impact may be more far-reaching. In theory, financial interactions or exchanges of any complexity could be carried out automatically and reliably using code running on Ethereum. Beyond financial applications, any environments where trust, security, and permanence are important – for instance, asset-registries, voting, governance, and the internet of things – could be massively impacted by the Ethereum platform. +Specifically, Ethereum is suited for applications that automate direct interaction +between peers or facilitate coordinated group action across a network. Examples +include applications for coordinating peer-to-peer marketplaces or the +automation of complex financial contracts. + +In contrast with blockchain technologies that largely limit themselves to the exchange of money, +Ethereum serves much wider purposes. Beyond financial applications, any environments +where trust, security, and permanence are important – for instance, asset-registries, +voting, governance, and the internet of things – make ideal candidates for the Ethereum platform. ================================================================================ How does Ethereum work? ================================================================================ -Ethereum incorporates many features and technologies that will be familiar to users of Bitcoin, while also introducing many modifications and innovations of its own. +Ethereum incorporates many features and technologies that will be familiar to users +of other blockchain technologies while also introducing many innovations of its own. + +For example, :ref:`Ethereum's blockchain holds accounts ` and tracks their state. +All state transitions on the Ethereum blockchain are transfers of value and information between accounts. -Whereas the Bitcoin blockchain was purely a list of transactions, :ref:`Ethereum's basic unit is the account `. The Ethereum blockchain tracks the state of every account, and all state transitions on the Ethereum blockchain are transfers of value and information between accounts. There are two types of accounts: +There are two types of accounts: - Externally Owned Accounts (EOAs), which are controlled by private keys - Contract Accounts, which are controlled by their contract code and can only be "activated" by an EOA @@ -45,19 +89,16 @@ For most users, the basic difference between these is that human users control E Contract accounts only perform an operation when instructed to do so by an EOA. So it is not possible for a Contract account to be performing native operations like random number generation or API calls – it can do these things only if prompted by an EOA. This is because Ethereum requires nodes to be able to agree on the outcome of computation, which requires a guarantee of strictly deterministic execution. -Like in Bitcoin, users must pay small transaction fees to the network. This protects the Ethereum blockchain from frivolous or malicious computational tasks, like DDoS attacks or infinite loops. The sender of a transaction must pay for each step of the "program" they activated, including computation and memory storage. These fees are paid in amounts of Ethereum's native value-token, ether. +Small transaction fees protect the Ethereum blockchain from frivolous or malicious computational tasks, like DDoS attacks or infinite loops. The sender of a transaction must pay for each step of the "program" they activated, including computation and memory storage. These fees are paid in amounts of Ethereum's native value-token, ether. These transaction fees are collected by the nodes that validate the network. These "miners" are nodes in the Ethereum network that receive, propagate, verify, and execute transactions. The miners then group the transactions – which include many updates to the "state" of accounts in the Ethereum blockchain – into what are called "blocks", and miners then compete with one another for *their* block to be the next one to be added to the blockchain. Miners are rewarded with ether for each successful block they mine. This provides the economic incentive for people to dedicate hardware and electricity to the Ethereum network. -Just as in the Bitcoin network, miners are tasked with solving a complex mathematical problem in order to successfully "mine" a block. This is known as a "Proof of Work". Any computational problem that requires orders of magnitude more resources to solve algorithmically than it takes to verify the solution is a good candidate for proof of work. In order to discourage centralisation due to the use of specialised hardware (e.g. ASICs), as has occurred in the Bitcoin network, Ethereum chose a memory-hard computational problem. If the problem requires memory as well as CPU, the ideal hardware is in fact the general computer. This makes Ethereum's Proof of Work ASIC-resistant, allowing a more decentralized distribution of security than blockchains whose mining is dominated by specialized hardware, like Bitcoin. +Miners are tasked with solving a complex mathematical problem in order to successfully "mine" a block. This is known as a "Proof of Work". Any computational problem that requires orders of magnitude more resources to solve algorithmically than it takes to verify the solution is a good candidate for proof of work. To discourage centralisation due to the use of specialised hardware (e.g. ASICs), Ethereum chose a memory-hard computational problem. +If the problem requires memory as well as CPU, the ideal hardware is in fact the general computer. This makes Ethereum's Proof of Work ASIC-resistant, allowing a more decentralized distribution of security than blockchains whose mining is dominated by specialized hardware. -Learn about Ethereum -============================== -[to be extended] - -PR videos with some pathos: +Some marketing videos: --------------------------------- * `Ethereum: the World Computer `_ @@ -67,7 +108,6 @@ PR videos with some pathos: Blockchain and Ethereum 101 ---------------------------------- -* `Explain bitcoin like I'm five `_ - an excellent introduction to blockchain technology and bitcoin to the mildly techsavvy layperson. * https://medium.com/@creole/7-a-simple-view-of-ethereum-e276f76c980b * http://blog.chain.com/post/92660909216/explaining-ethereum @@ -82,7 +122,7 @@ Blockchain and Ethereum 101 `[6] `_ `[7] `_ `[8] `_ -`[9] `_ +`[9] `_ `[10] `_ `[11] `_ `[12] `_ @@ -92,10 +132,10 @@ Blockchain and Ethereum 101 `[16] `_ `[17] `_ `[18] `_ -`[19] `_ -Videos + +A technical video ---------------------- * http://change.is/video/ethereum-the-world-computer-featuring-dr-gavin-wood @@ -103,7 +143,7 @@ Videos Infographics -------------------------------- -* `Ethereum explained...[to your mother] `_ +* `Ethereum explained... `_ * http://decentral.ca/wp-content/uploads/2016/03/infographic.jpg * https://medium.com/@angelomilan/ethereum-explained-to-my-mom-infographic-673e32054c1c#.n9kzhme6v diff --git a/source/network/connecting-to-the-network.rst b/source/network/connecting-to-the-network.rst index fece85fc..6cf3763e 100644 --- a/source/network/connecting-to-the-network.rst +++ b/source/network/connecting-to-the-network.rst @@ -1,7 +1,7 @@ .. _sec:connecting-to-the-network: ******************************************************************************** -Connecting to the Network +Connecting to the network ******************************************************************************** This section @@ -148,7 +148,7 @@ see `this link `_ .. _cr-static-nodes: -Static Nodes, Trusted Nodes, and Boot Nodes +Static nodes, trusted bodes, and boot nodes ================================================================================ Geth supports a feature called static nodes if you have certain peers you always want to connect to. Static nodes are re-connected on disconnects. You can configure permanent static nodes by putting something like the following into ``/static-nodes.json`` (this should be the same folder that your ``chaindata`` and ``keystore`` folders are in) diff --git a/source/network/test-networks.rst b/source/network/test-networks.rst index 60cdd527..1799a553 100644 --- a/source/network/test-networks.rst +++ b/source/network/test-networks.rst @@ -1,7 +1,7 @@ .. _test-networks: ******************************************************************************** -Test Networks +Test networks ******************************************************************************** Morden testnet