Cleaned up formatting and warnings/notes. Changed Web3 page to Dapps

source/contracts-and-transactions/account-types-gas-and-transactions.rst

@@ -4,23 +4,23 @@
 Account Types, Gas, and Transactions
 ********************************************************************************
 
-EOA vs Contract Accounts
+EOA vs contract accounts
 ================================================================================
 
 There are two types of accounts in Ethereum
   - Externally Owned Accounts
   - Contracts Accounts
 
-Externally Owned Accounts (EOAs)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Externally owned accounts (EOAs)
+--------------------------------------------------------------------------------
 
 - Can have an Ether balance.
 - Can send transactions.
 - Are controlled by private keys.
 - Has no code.
 
-Contract Accounts:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Contract accounts
+--------------------------------------------------------------------------------
 - Can have an Ether balance.
 - Can send transactions.
 - Can send messages.
@@ -30,9 +30,9 @@ Contract Accounts:
 
 All Ether balances and values are denominated in units of wei: 1 Ether is 1e18 wei.
 
-Note that "contracts" in Ethereum should not be seen as something that should be "fulfilled" or "complied with"; rather, they are more like "autonomous agents" that live inside of the Ethereum execution environment, always executing a specific piece of code when "poked" by a message or transaction, and having direct control over their own ether balance and their own key/value store to keep track of persistent variables.
+.. note:: "Contracts" in Ethereum should not be seen as something that should be "fulfilled" or "complied with"; rather, they are more like "autonomous agents" that live inside of the Ethereum execution environment, always executing a specific piece of code when "poked" by a message or transaction, and having direct control over their own ether balance and their own key/value store to keep track of persistent variables.
 
-What is a Transaction?
+What is a transaction?
 ================================================================================
 The term "transaction" is used in Ethereum to refer to the signed data package that stores a message to be sent from an externally owned account.
 
@@ -44,7 +44,7 @@ Transactions contain:
  - A ``STARTGAS`` value, representing the maximum number of computational steps the transaction execution is allowed to take.
  - A ``GASPRICE`` value, representing the fee the sender pays per computational step.
 
-What is a Message?
+What is a message?
 ================================================================================
 Contracts have the ability to send "messages" to other contracts. Messages are virtual objects that are never serialized and exist only in the Ethereum execution environment.
 
@@ -57,15 +57,15 @@ A message contains:
 
 Essentially, a message is like a transaction, except it is produced by a contract and not an external actor. A message is produced when a contract currently executing code executes the ``CALL`` opcode, which produces and executes a message. Like a transaction, a message leads to the recipient account running its code. Thus, contracts can have relationships with other contracts in exactly the same way that external actors can.
 
-What is Gas?
+What is gas?
 ================================================================================
 Ethereum implements an execution environment on the blockchain called the Ethereum Virtual Machine (EVM). When you are running a decentralized application (dApp), every instruction is executed on every node of the network. This has a cost: for every operation in a contract that can be executed there is a specified cost, expressed in number of gas units.
 
 Gas is name for the execution fee for every operation made on an Ethereum blockchain. Its price is expressed in ether and it's decided by the miners, which can refuse to process transaction with less than a certain gas price. To get gas you simply need to add ether to your account. The Ethereum client automatically converts Ether to gas and gas to Ether when transactions are processed.
 
 The Ethereum protocol charges a fee per computational step that is executed in a contract or transaction to prevent deliberate attacks and abuse on the Ethereum network. Every transaction is required to include a gas limit and a fee that it is willing to pay per gas. Miners have the choice of including the transaction and collecting the fee or not. If the total number of gas used by the computational steps spawned by the transaction, including the original message and any sub-messages that may be triggered, is less than or equal to the gas limit, then the transaction processes. If the total gas exceeds the gas limit, then all changes are reverted, except that the transaction is still valid and the fee can still be collected by the miner. This means that it is wiser to send transactions with a gas limit well above the estimates
 
-Estimating Transaction Costs
+Estimating transaction costs
 ================================================================================
 The total cost of a transaction is based on 2 factors:
 
@@ -76,17 +76,17 @@ The total cost of a transaction is based on 2 factors:
 **Total cost = gasUsed * gasPrice**
 
 gasUsed
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------------------------------------------
 Each operation in the EVM was assigned a number of how much gas it consumes. ``gasUsed`` is summing up all the gas for all the operations executed. There is a `spreadsheet <http://ethereum.stackexchange.com/q/52/42>`_ which offers a glimpse to some of the analysis behind them.
 
 For estimating ``gasUsed``, there is an `estimateGas API <http://ethereum.stackexchange.com/q/266/42>`_ that can be used but has some caveats.
 
 gasPrice
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------------------------------------------
 A user constructs and signs a transaction, and each user may specify whatever ``gasPrice`` they desire, this includes zero. However, the Ethereum clients launched at Frontier had a default gasPrice of 0.05e12 wei. As miners optimize for their revenue, if most transactions are being submitted with a gasPrice of 0.05e12 wei, it would be difficult to convince a miner to accept a transaction that specified a lower, or zero, gasPrice.
 
-Example Transaction Cost
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Example transaction cost
+--------------------------------------------------------------------------------
 
 Let’s take a contract that just adds 2 numbers. The EVM OPCODE ``ADD`` consumes 3 gas.
 
@@ -105,7 +105,7 @@ of passing the 2 numbers to contract, before they can even be added.
 * `Ethereum Gas Prices <https://docs.google.com/spreadsheets/d/1m89CVujrQe5LAFJ8-YAUCcNK950dUzMQPMJBxRtGCqs>`_
 
 =================  =========    =============================
-operation name     gas cost     Remark
+Operation Name     Gas Cost     Remark
 =================  =========    =============================
 step               1            default amount per an execution cycle
 stop               0            free
@@ -122,7 +122,7 @@ transaction        500          base fee transaction
 contract creation  53000        changed in homestead from 21000
 =================  =========    =============================
 
-Account Interactions Example - Betting Contract
+Account interactions example - betting contract
 ================================================================================
 As previously mentioned, there are two types of accounts:
 
@@ -165,9 +165,8 @@ Note that the GavCoin is all "stored" as entries in the GavCoin contract's datab
 ..
    :align: center
 
-Signing Transactions Offline
+Signing transactions offline
 ================================================================================
 [ Maybe add this to the FAQ and point to the ethkey section of turboethereum guide? ]
 
-* `Resilience Raw Transaction Broadcaster <https://github.com/resilience-me/broadcaster/>`_
-
+* `Resilience Raw Transaction Broadcaster <https://github.com/resilience-me/broadcaster/>`_

source/contracts-and-transactions/contracts.rst

@@ -2,7 +2,7 @@
 Contracts
 ********************************************************************************
 
-What is a Contract?
+What is a contract?
 ================================================================================
 
 A contract is a collection of code (its functions) and data (its state) that
@@ -18,7 +18,9 @@ to be uploaded on the blockchain. Note that other languages also exist, notably
 Serpent and LLL, which are described further in the
 :ref:`ethereum-high-level-languages` section of this documentation.
 
-Write a Contract 
+.. note::
+
+Writing a contract 
 ================================================================================
 
 No language would be complete without a Hello World program. Operating within
@@ -37,14 +39,13 @@ blockchain:
 This contract will create a log entry on the blockchain of type Print with a
 parameter "Hello, World!" each time it is executed.
 
-Visit the `Solidity documentation
-<https://solidity.readthedocs.org/en/latest/>`_ for more examples and
+.. seealso:: `Solidity documentation
+<https://solidity.readthedocs.org/en/latest/>`_ has more examples and
 guidelines to writing Solidty code.
 
-Compile a Contract 
+Compiling a contract 
 ================================================================================
 
-
 Compilation of solidity contracts can be accomplished via a number of
 mechanisms.
 
@@ -59,7 +60,7 @@ mechanisms.
 .. note::  More information on solc and compiling Solidity contract code can be found `here <https://solidity.readthedocs.org/en/latest/frequently-asked-questions.html#how-do-i-compile-contracts>`_.
 
 
-Setting up the solidity compiler in geth.
+Setting up the solidity compiler in geth
 --------------------------------------------------------------------------------
 
 If you start up your ``geth`` node, you can check which compilers are
@@ -219,7 +220,7 @@ most current GlobalRegistrar code:
     contracts = eth.compile.solidity(globalRegistrarSrc)
 
 
-Create and Deploy a Contract
+Create and deploy a contract
 ================================================================================
 
 Before you begin this section, make sure you have both an unlocked account as
@@ -266,7 +267,7 @@ The asynchronous way of doing the same looks like this:
 
 .. _interacting_with_a_contract:
 
-Interacting with a Contract
+Interacting with a contract
 ================================================================================
 
 Interaction with a contract is typically done using an abstraction layer such
@@ -316,7 +317,7 @@ In the example above, there are no side effects, therefore ``sendTransaction``
 only burns gas and increases the entropy of the universe.
 
 
-Contract Metadata
+Contract metadata
 ================================================================================
 
 In the previous sections we explained how you create a contract on the
@@ -393,7 +394,7 @@ longer necessary.)
     });
 
 
-Testing Contracts and Transactions
+Testing contracts and transactions
 ================================================================================
 
 Often you need to resort to a low level strategy of testing and debugging
@@ -412,7 +413,7 @@ verbosity level is recommended:
     geth --datadir ~/dapps/testing/00/ --port 30310 --rpcport 8110 --networkid 4567890 --nodiscover --maxpeers 0 --vmdebug --verbosity 6 --pprof --pprofport 6110 console 2>> ~/dapp/testint/00/00.log
 
 Before you can submit any transactions, you need set up your private test
-chain. See :ref:`test-networks`
+chain. See :ref:`test-networks`.
 
 .. code:: js
 
@@ -464,5 +465,4 @@ If you submitted contract creation transaction, you can check if the desired cod
     txhash = eth.sendTansaction({from:primary, data: code})
     //... mining
     contractaddress = eth.getTransactionReceipt(txhash);
-    eth.getCode(contractaddress)
-
+    eth.getCode(contractaddress)

source/developing-on-ethereum/developer-tools.rst

@@ -4,35 +4,27 @@ Developer Tools
 As a Ðapp developer you have five main resources which allow Ðapp
 development.
 
-
-Five Primary Resources
+Five primary resources
 ================================================================================
 ÐApp development requires an understanding of the Web3 Javascript API, the JSON RPC API, and the Solidity programming language. 
 
 .. note:: There are developer tools that help you develop, test, and deploy ÐApps in a way that automatically utilizes the resources listed below.
 
 
-* `Web3 JavaScript API <https://github.com/ethereum/wiki/wiki/JavaScript-API>`__ - This is the main
-  JavaScript SDK to use when you want to interact with an Ethereum node.
-* `JSON RPC API <https://github.com/ethereum/wiki/wiki/JSON-RPC>`__ - This is
-  the low level JSON RPC 2.0 interface to interface with a node. This API is
-  used by the `Web3 JavaScript API <https://github.com/ethereum/wiki/wiki/JavaScript-API>`__.
+* `Web3 JavaScript API <https://github.com/ethereum/wiki/wiki/JavaScript-API>`__ - This is the main JavaScript SDK to use when you want to interact with an Ethereum node.
+* `JSON RPC API <https://github.com/ethereum/wiki/wiki/JSON-RPC>`__ - This is the low level JSON RPC 2.0 interface to interface with a node. This API is used by the `Web3 JavaScript API <https://github.com/ethereum/wiki/wiki/JavaScript-API>`__.
 * `Solidity Documentation <https://solidity.readthedocs.org/en/latest/>`__ -
-  Solidity is the Ethereum developed Smart Contract language, which compiles to
-  EVM (Ethereum Virtual Machine) opcodes.
-* :ref:`test-networks` - Test networks help developers develop and test
-  Ethereum code and network interactions without spending their own Ether on
-  the main network. Test network options are listed below.
+  Solidity is the Ethereum developed Smart Contract language, which compiles to EVM (Ethereum Virtual Machine) opcodes.
+* :ref:`test-networks` - Test networks help developers develop and test Ethereum code and network interactions without spending their own Ether on the main network. Test network options are listed below.
 * :ref:`IDE-or-development-framework`. This assists you in developing,
   debugging, and deploying Ethereum applications. 
 
 
 .. _ethereum-high-level-languages:
 
-Ethereum High Level Languages
+Ethereum high level languages
 ===========================================================================
-
-Contracts live on the blockchain in an Ethereum-specific binary format (EVM bytecode) that is executed by the Ethereum Virtual Machine (EVM). However, contracts are typically written in a higher level language and then compiled using an EVM compiler into byte code which is then deployed to the blockchain.
+Contracts live on the blockchain in an Ethereum-specific binary format (EVM bytecode) that is executed by the Ethereum Virtual Machine (EVM). However, contracts are typically written in a higher level language (HLL) and then compiled using the EVM compiler into byte code to be deployed to the blockchain.
 
 Below are the different high level languages developers can use to write smart contracts for Ethereum.
 
@@ -62,7 +54,7 @@ LLL
 * `LIBLLL in GitHub <https://github.com/ethereum/libethereum/tree/develop/liblll>`_
 * `Examples of LLL <https://www.reddit.com/r/ethereum/comments/3secu1/anyone_have_a_copy_of_the_old_lll_tutorials/>`_
 
-Mutan (Deprecated)
+Mutan (deprecated)
 --------------------------------------------------------------------------------
 
 `Mutan <https://github.com/obscuren/mutan>`_ is a statically typed, C-like language designed and developed by Jeffrey Wilcke. It is no longer maintained.
@@ -72,12 +64,8 @@ Mutan (Deprecated)
 
 IDEs/Frameworks
 ================================================================================
-
 Below are developer frameworks and IDEs used for writing Ethereum Đapps.
 
-TODO
-  expand at least some of these to subsections, add reference to community
-
 * `Mix Ethereum IDE <https://github.com/ethereum/mix>`__ - Mix is an IDE that allows developers to build and deploy contracts and decentralized applications on top of the Ethereum blockchain. It includes a Solidity source code debugger.
 * `Truffle <https://github.com/ConsenSys/truffle>`__ - Truffle is a development environment, testing framework and asset pipeline for Ethereum.
 * `Dapple <https://github.com/nexusdev/dapple>`__ - Dapple is a tool for Solidity developers to help build and manage complex contract systems on Ethereum-like blockchains.
@@ -87,7 +75,7 @@ TODO
 * `Resilience Raw Transaction Broadcaster <https://github.com/resilience-me/broadcaster/>`_
 
 
-Base Layer Services
+Base layer services
 =================================================
 
 Ethereum Alarm Clock
@@ -121,7 +109,6 @@ having to actually pay the high gas costs of executing them on-chain.
 
 The EVM
 ================================================================================
-
 The Ethereum Virtual Machine (EVM) is the runtime environment for smart contracts in Ethereum. It is not only sandboxed, but actually completely isolated, which means that code running inside the EVM has no access to network, filesystem, or other processes. Smart contracts even have limited access to other smart contracts.
 
-Contracts live on the blockchain in an Ethereum-specific binary format (EVM bytecode). However, contracts are typically written in an Ethereum high level language, compiled into byte code using an EVM compiler, and finally uploaded on the blockchain using an Ethereum client.
+Contracts live on the blockchain in an Ethereum-specific binary format (EVM bytecode). However, contracts are typically written in an Ethereum high level language, compiled into byte code using an EVM compiler, and finally uploaded on the blockchain using an Ethereum client.