Imported documentation.

1 files changed, 464 insertions, 0 deletions

diff --git a/docs/introduction-to-smart-contracts.rst b/docs/introduction-to-smart-contracts.rst
new file mode 100644
index 00000000..b0f1896a
--- /dev/null
+++ b/docs/introduction-to-smart-contracts.rst
@@ -0,0 +1,464 @@
+###############################
+Introduction to Smart Contracts
+###############################
+
+.. _simple-smart-contract:
+
+***********************
+A Simple Smart Contract
+***********************
+
+Let us begin with the most basic example. It is fine if you do not understand everything
+right now, we will go into more detail later.
+
+Storage
+=======
+
+.. Gist: a4532ce30246847b371b
+
+::
+
+    contract SimpleStorage {
+        uint storedData;
+        function set(uint x) {
+            storedData = x;
+        }
+        function get() constant returns (uint retVal) {
+            return storedData;
+        }
+    }
+
+A contract in the sense of Solidity is a collection of code (its functions) and
+data (its *state*) that resides at a specific address on the Ethereum
+blockchain. The line `uint storedData;` declares a state variable called `storedData` of
+type `uint` (unsigned integer of 256 bits). You can think of it as a single slot
+in a database that can be queried and altered by calling functions of the
+code that manages the database. In the case of Ethereum, this is always the owning
+contract. And in this case, the functions `set` and `get` can be used to modify
+or retrieve the value of the variable.
+
+To access a state variable, you do not need the prefix `this.` as is common in
+other languages.
+
+This contract does not yet do much apart from (due to the infrastructure
+built by Ethereum) allowing anyone to store a single number that is accessible by
+anyone in the world without (feasible) a way to prevent you from publishing
+this number. Of course, anyone could just call `set` again with a different value
+and overwrite your number, but the number will still be stored in the history
+of the blockchain. Later, we will see how you can impose access restrictions
+so that only you can alter the number.
+
+.. index:: ! subcurrency
+
+Subcurrency Example
+===================
+
+The following contract will implement the simplest form of a
+cryptocurrency. It is possible to generate coins out of thin air, but
+only the person that created the contract will be able to do that (it is trivial
+to implement a different issuance scheme).
+Furthermore, anyone can send coins to each other without any need for
+registering with username and password - all you need is an Ethereum keypair.
+
+
+.. note::
+    This is not a nice example for browser-solidity.
+    If you use `browser-solidity <https://chriseth.github.io/browser-solidity>`_
+    to try this example, you cannot change the address where you call
+    functions from. So you will always be the "minter", you can mint coins and send
+    them somewhere, but you cannot impersonate someone else. This might change in
+    the future.
+
+.. Gist: ad490694f3e5b3de47ab
+
+::
+
+    contract Coin {
+        // The keyword "public" makes those variables
+        // readable from outside.
+        address public minter;
+        mapping (address => uint) public balances;
+
+        // Events allow light clients to react on
+        // changes efficiently.
+        event Sent(address from, address to, uint amount);
+
+        // This is the constructor whose code is
+        // run only when the contract is created.
+        function Coin() {
+            minter = msg.sender;
+        }
+        function mint(address receiver, uint amount) {
+            if (msg.sender != minter) return;
+            balances[receiver] += amount;
+        }
+        function send(address receiver, uint amount) {
+            if (balances[msg.sender] < amount) return;
+            balances[msg.sender] -= amount;
+            balances[receiver] += amount;
+            Sent(msg.sender, receiver, amount);
+        }
+    }
+
+This contract introduces some new concepts, let us go through them one by one
+
+The line `address public minter;` declares a state variable of type address
+that is publicly accessible. The `address` type is a 160 bit value
+that does not allow any arithmetic operations. It is suitable for
+storing addresses of contracts or keypairs belonging to external
+persons. The keyword `public` automatically generates a function that
+allows you to access the current value of the state variable.
+Without this keyword, other contracts have no way to access the variable
+and only the code of this contract can write to it.
+The function will look something like this::
+
+    function minter() returns (address) { return minter; }
+
+Of course, adding a function exactly like that will not work
+because we would have a
+function and a state variable with the same name, but hopefully, you
+get the idea - the compiler figures that out for you.
+
+.. index:: mapping
+
+The next line, `mapping (address => uint) public balances;` also
+creates a public state variable, but it of a more complex datatype.
+The type maps addresses to unsigned integers.
+Mappings can be seen as hashtables which are
+virtually initialized such that every possible key exists and is mapped to a
+value whose byte-representation is all zeros. This analogy does not go
+too far, though, as it is neither possible to obtain a list of all keys of
+a mapping, nor a list of all values. So either keep in mind (or
+better, keep a list or use a more advanced data type) what you
+added to the mapping or use it in a context where this is not needed,
+like this one. The accessor function created by the `public` keyword
+is a bit more complex in this case. It roughly looks like the
+following::
+
+    function balances(address _account) returns (uint balance) {
+        return balances[_account];
+    }
+
+As you see, you can use this function to easily query the balance of a
+single account.
+
+.. index:: event
+
+The line `event Sent(address from, address to, uint value);` declares
+a so-called "event" which is fired in the last line of the function
+`send`. User interfaces (as well as server appliances of course) can
+listen for those events being fired on the blockchain without much
+cost. As soon as it is fired, the listener will also receive the
+arguments `from`, `to` and `value`, which makes it easy to track
+transactions. In order to listen for this event, you would use ::
+
+    Coin.Sent().watch({}, '', function(error, result) {
+        if (!error) {
+            console.log("Coin transfer: " + result.args.amount +
+                " coins were sent from " + result.args.from +
+                " to " + result.args.to + ".");
+            console.log("Balances now:\n" +
+                "Sender: " + Coin.balances.call(result.args.from) +
+                "Receiver: " + Coin.balances.call(result.args.to));
+        }
+    }
+
+Note how the automatically generated function `balances` is called from
+the user interface.
+
+.. index:: coin
+
+The special function `Coin` is the
+constructor which is run during creation of the contract and
+cannot be called afterwards. It permanently stores the address of the person creating the
+contract: `msg` (together with `tx` and `block`) is a magic global variable that
+contains some properties which allow access to the blockchain. `msg.sender` is
+always the address where the current (external) function call came from.
+
+Finally, the functions that will actually end up with the contract and can be called
+by users and contracts alike are `mint` and `send`.
+If `mint` is called by anyone except the account that created the contract,
+nothing will happen. On the other hand, `send` can be used by anyone (who already
+has some of these coins) to send coins to anyone else. Note that if you use
+this contract to send coins to an address, you will not see anything when you
+look at that address on a blockchain explorer, because the fact that you sent
+coins and the changed balances are only stored in the data storage of this
+particular coin contract. By the use of events it is relatively easy to create
+a "blockchain explorer" that tracks transactions and balances of your new coin.
+
+.. _blockchain-basics:
+
+*****************
+Blockchain Basics
+*****************
+
+Blockchains as a concept are not too hard to understand for programmers. The reason is that
+most of the complications (mining, hashing, elliptic-curve cryptography, peer-to-peer networks, ...)
+are just there to provide a certain set of features and promises. Once you accept these
+features as given, you do not have to worry about the underlying technology - or do you have
+to know how Amazon's AWS works internally in order to use it?
+
+.. index:: transaction
+
+Transactions
+============
+
+A blockchain is a globally shared, transactional database.
+This means that everyone can read entries in the database just by participating in the network.
+If you want to change something in the database, you have to create a so-called transaction
+which has to be accepted by all others.
+The word transaction implies that the change you want to make (assume you want to change
+two values at the same time) is either not done at all or completely applied. Furthermore,
+while your transaction is applied to the database, no other transaction can alter it.
+
+As an example, imagine a table that lists the balances of all accounts in an
+electronic currency. If a transfer from one account to another is requested,
+the transactional nature of the database ensures that if the amount is
+subtracted from one account, it is always added to the other account. If due
+to whatever reason, adding the amount to the target account is not possible,
+the source account is also not modified.
+
+Furthermore, a transaction is always cryptographically signed by the sender (creator).
+This makes it straightforward to guard access to specific modifications of the
+database. In the example of the electronic currency, a simple check ensures that
+only the person holding the keys to the account can transfer money from it.
+
+.. index:: ! block
+
+Blocks
+======
+
+One major obstacle to overcome is what in bitcoin terms is called "double-spend attack":
+What happens if two transactions exist in the network that both want to empty an account,
+a so-called conflict?
+
+The abstract answer to this is that you do not have to care. An order of the transactions
+will be selected for you, the transactions will be bundled into what is called a "block"
+and then they will be executed and distributed among all participating nodes.
+If two transactions contradict each other, the one that ends up being second will
+be rejected and not become part of the block.
+
+These blocks form a linear sequence in time and that is where the word "blockchain"
+derives from. Blocks are added to the chain in rather regular intervals - for
+Ethereum this is roughly every 17 seconds.
+
+As part of the "order selection mechanism" (which is called "mining") it may happen that
+blocks are reverted from time to time, but only at the "tip" of the chain. The more
+blocks are reverted the less likely it is. So it might be that your transactions
+are reverted and even removed from the blockchain, but the longer you wait, the less
+likely it will be.
+
+
+.. _the-ethereum-virtual-machine:
+
+.. index:: !evm, ! ethereum virtual machine
+
+****************************
+The Ethereum Virtual Machine
+****************************
+
+Overview
+========
+
+The Ethereum Virtual Machine or 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.
+
+.. index:: ! account, address, storage, balance
+
+Accounts
+========
+
+There are two kinds of accounts in Ethereum which share the same
+address space: **External accounts** that are controlled by
+public-private key pairs (i.e. humans) and **contract accounts** which are
+controlled by the code stored together with the account.
+
+The address of an external account is determined from
+the public key while the address of a contract is
+determined at the time the contract is created
+(it is derived from the creator address and the number
+of transactions sent from that address, the so-called "nonce").
+
+Apart from the fact whether an account stores code or not,
+the EVM treats the two types equally, though.
+
+Every account has a persistent key-value store mapping 256 bit words to 256 bit
+words called **storage**.
+
+Furthermore, every account has a **balance** in
+Ether (in "Wei" to be exact) which can be modified by sending transactions that
+include Ether.
+
+.. index:: ! transaction
+
+Transactions
+============
+
+A transaction is a message that is sent from one account to another
+account (which might be the same or the special zero-account, see below).
+It can include binary data (its payload) and Ether.
+
+If the target account contains code, that code is executed and
+the payload is provided as input data.
+
+If the target account is the zero-account (the account with the
+address `0`), the transaction creates a **new contract**.
+As already mentioned, the address of that contract is not
+the zero address but an address derived from the sender and
+its number of transaction sent (the "nonce"). The payload
+of such a contract creation transaction is taken to be
+EVM bytecode and executed. The output of this execution is
+permanently stored as the code of the contract.
+This means that in order to create a contract, you do not
+send the actual code of the contract, but in fact code that
+returns that code.
+
+.. index:: ! gas, ! gas price
+
+Gas
+===
+
+Upon creation, each transaction is charged with a certain amount of **gas**,
+whose purpose is to limit the amount of work that is needed to execute
+the transaction and to pay for this execution. While the EVM executes the
+transaction, the gas is gradually depleted according to specific rules.
+
+The **gas price** is a value set by the creator of the transaction, who
+has to pay `gas_price * gas` up front from the sending account.
+If some gas is left after the execution, it is refunded in the same way.
+
+If the gas is used up at any point (i.e. it is negative),
+an out-of-gas exception is triggered, which reverts all modifications
+made to the state in the current call frame.
+
+.. index:: ! storage, ! memory, ! stack
+
+Storage, Memory and the Stack
+=============================
+
+Each account has a persistent memory area which is called **storage**.
+Storage is a key-value store that maps 256 bit words to 256 bit words.
+It is not possible to enumerate storage from within a contract
+and it is comparatively costly to read and even more so, to modify
+storage. A contract can neither read nor write to any storage apart
+from its own.
+
+The second memory area is called **memory**, of which a contract obtains
+a freshly cleared instance for each message call. Memory can be
+addressed at byte level, but read and written to in 32 byte (256 bit)
+chunks. Memory is more costly the larger it grows (it scales
+quadratically).
+
+The EVM is not a register machine but a stack machine, so all
+computations are performed on an area called the **stack**. It has a maximum size of
+1024 elements and contains words of 256 bits. Access to the stack is
+limited to the top end in the following way:
+It is possible to copy one of
+the topmost 16 elements to the top of the stack or swap the
+topmost element with one of the 16 elements below it.
+All other operations take the topmost two (or one, or more, depending on
+the operation) elements from the stack and push the result onto the stack.
+Of course it is possible to move stack elements to storage or memory,
+but it is not possible to just access arbitrary elements deeper in the stack
+without first removing the top of the stack.
+
+.. index:: ! instruction
+
+Instruction Set
+===============
+
+The instruction set of the EVM is kept minimal in order to avoid
+incorrect implementations which could cause consensus problems.
+All instructions operate on the basic data type, 256 bit words.
+The usual arithmetic, bit, logical and comparison operations are present.
+Conditional and unconditional jumps are possible. Furthermore,
+contracts can access relevant properties of the current block
+like its number and timestamp.
+
+.. index:: ! message call, function;call
+
+Message Calls
+=============
+
+Contracts can call other contracts or send Ether to non-contract
+accounts by the means of message calls. Message calls are similar
+to transactions, in that they have a source, a target, data payload,
+Ether, gas and return data. In fact, every transaction consists of
+a top-level message call which in turn can create further message calls.
+
+A contract can decide how much of its remaining **gas** should be sent
+with the inner message call and how much it wants to retain.
+If an out-of-gas exception happens in the inner call (or any
+other exception), this will be signalled by an error value put onto the stack.
+In this case, only the gas sent together with the call is used up.
+In Solidity, the calling contract causes a manual exception by default in
+such situations, so that exceptions "bubble up" the call stack.
+
+As already said, the called contract (which can be the same as the caller)
+will receive a freshly cleared instance of memory and has access to the
+call payload - which will be provided in a separate area called the **calldata**.
+After it finished execution, it can return data which will be stored at
+a location in the caller's memory preallocated by the caller.
+
+Calls are **limited** to a depth of 1024, which means that for more complex
+operations, loops should be preferred over recursive calls.
+
+.. index:: callcode, library
+
+Callcode and Libraries
+======================
+
+There exists a special variant of a message call, named **callcode**
+which is identical to a message call apart from the fact that
+the code at the target address is executed in the context of the calling
+contract.
+
+This means that a contract can dynamically load code from a different
+address at runtime. Storage, current address and balance still
+refer to the calling contract, only the code is taken from the called address.
+
+This makes it possible to implement the "library" feature in Solidity:
+Reusable library code that can be applied to a contract's storage in
+order to e.g. implement a complex data structure.
+
+.. index:: log
+
+Logs
+====
+
+It is possible to store data in a specially indexed data structure
+that maps all they way up to the block level. This feature called **logs**
+is used by Solidity in order to implement **events**.
+Contracts cannot access log data after it has been created, but they
+can be efficiently accessed from outside the blockchain.
+Since some part of the log data is stored in bloom filters, it is
+possible to search for this data in an efficient and cryptographically
+secure way, so network peers that do not download the whole blockchain
+("light clients") can still find these logs.
+
+.. index:: contract creation
+
+Create
+======
+
+Contracts can even create other contracts using a special opcode (i.e.
+they do not simply call the zero address). The only difference between
+these **create calls** and normal message calls is that the payload data is
+executed and the result stored as code and the caller / creator
+receives the address of the new contract on the stack.
+
+.. index:: selfdestruct
+
+Selfdestruct
+============
+
+The only possibility that code is removed from the blockchain is
+when a contract at that address performs the `SELFDESTRUCT` operation.
+The remaining Ether stored at that address is sent to a designated
+target and then the storage and code is removed.
+
+Note that even if a contract's code does not contain the `SELFDESTRUCT`
+opcode, it can still perform that operation using callcode.