From 994da293fbdf32b25acb37a4d3b1e51fd3a138cb Mon Sep 17 00:00:00 2001 From: "C.Domashnev" <58366873+cdomashn@users.noreply.github.com> Date: Sat, 25 Dec 2021 15:44:24 -0500 Subject: [PATCH] Fixed Broken Links --- LICENSE.md | 43 + archive/Solidity.md | 128 + archive/ethereum-contract-abi.md | 383 +++ archive/javascript-api.md | 2416 +++++++++++++++++ archive/poll-for-token-proposal-EIP-20.md | 4 +- archive/proposal-reversion-notification.md | 2 +- archive/proposal-transaction-proxy-hooks.md | 2 +- archive/serpent.md | 2 +- archive/white-paper.md | 500 ++++ .../\303\220\316\236Vp2p-Wire-Protocol.md" | 90 + clients/client-version-strings.md | 2 +- ...app-browsers-wallets-and-other-projects.md | 6 +- concepts/casper-proof-of-stake-compendium.md | 2 +- concepts/dagger-hashimoto.md | 2 +- concepts/ethash/dag-disk-storage-format.md | 2 +- concepts/ethash/dag.md | 2 +- concepts/ethash/ethash.md | 6 +- ...reum-virtual-machine-(evm)-awesome-list.md | 4 +- concepts/evm/evm.md | 10 +- concepts/evm/implementations.md | 2 +- concepts/light-client-protocol.md | 2 +- concepts/proof-of-stake-faqs.md | 2 +- concepts/security-categorization.md | 6 +- concepts/standardized-contract-apis.md | 2 +- concepts/url-hint-protocol.md | 0 concepts/whisper/overview.md | 0 concepts/whisper/poc-2-protocol-spec.md | 2 +- concepts/whisper/poc-2-wire-protocol.md | 2 +- concepts/whisper/whisper-overview.md | 0 concepts/whisper/whisper.md | 0 concepts/whisper/wire-protocol.md | 2 +- concepts/wishlist.md | 10 +- enterprise/enterprise.md | 2 +- enterprise/whymainnet.md | 2 +- eth1/clients.md | 2 +- eth1/coredevsberlin.md | 2 +- eth1/eth1.md | 5 +- eth2/eth2.md | 1 - faqs/famous-bugs.md | 2 +- faqs/faqs.md | 20 +- faqs/glossary.md | 4 +- fundamentals/dapp-developer-resources.md | 14 +- fundamentals/dapp-development.md | 14 +- fundamentals/decentralized-apps-dapps.md | 18 +- fundamentals/design-rationale.md | 6 +- fundamentals/ethereum-introduction.md | 20 +- fundamentals/fundamentals.md | 1 - fundamentals/getting-ether.md | 14 +- fundamentals/getting-started.md | 4 +- fundamentals/mining.md | 8 +- fundamentals/patricia-tree.md | 4 +- fundamentals/rlp.md | 4 +- fundamentals/specs/bad-block-reporting.md | 2 +- funding/experiments.md | 12 +- governance/governance-compendium.md | 2 +- governance/maintainers.md | 12 +- governance/polices-and-guidelines.md | 2 +- governance/security-issue-process.md | 2 +- home.md | 7 +- howto/ethereum-development-tutorial.md | 6 +- howto/smart-contract-safety.md | 2 +- ideas/distributed-preimage-archive.md | 2 +- ideas/middleware-and-dapp-project-ideas.md | 2 +- json-rpc/api.md | 12 +- ...ess-economics-and-other-research-topics.md | 2 +- research/rd.md | 2 +- ...nd-other-crypto-infrastructure-projects.md | 10 +- roadmap/berlin.md | 2 +- roadmap/istanbul.md | 8 +- roadmap/istanbul/tracker.md | 3 +- roadmap/london.md | 2 +- roadmap/petersburg.md | 2 +- roadmap/releases.md | 8 +- roadmap/roadmap.md | 22 +- scalability/chain-fibers-redux.md | 2 +- sharding/Sharding-FAQs.md | 10 +- .../sharding-introduction-r-d-compendium.md | 14 +- sharding/sharding-roadmap.md | 6 +- 78 files changed, 3746 insertions(+), 193 deletions(-) create mode 100644 LICENSE.md create mode 100644 archive/Solidity.md create mode 100644 archive/ethereum-contract-abi.md create mode 100644 archive/javascript-api.md create mode 100644 archive/white-paper.md create mode 100644 "archive/\303\220\316\236Vp2p-Wire-Protocol.md" mode change 100755 => 100644 concepts/proof-of-stake-faqs.md mode change 100755 => 100644 concepts/security-categorization.md mode change 100755 => 100644 concepts/standardized-contract-apis.md mode change 100755 => 100644 concepts/url-hint-protocol.md mode change 100755 => 100644 concepts/whisper/overview.md mode change 100755 => 100644 concepts/whisper/poc-2-protocol-spec.md mode change 100755 => 100644 concepts/whisper/poc-2-wire-protocol.md mode change 100755 => 100644 concepts/whisper/whisper-overview.md mode change 100755 => 100644 concepts/whisper/whisper.md mode change 100755 => 100644 concepts/whisper/wire-protocol.md mode change 100755 => 100644 concepts/wishlist.md diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..c26e70b --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,43 @@ +# LICENSE + +Unless otherwise noted, this project is in the public domain. + +Additionally, waived are all contributors' copyright and related rights in the work worldwide through the CC0 1.0 Universal public domain dedication. + +*** + +## CC0 1.0 Universal Summary + +The code within this repository is distributed under the **Creative Commons (CCO 1.0) license** and further details concerning this license can be found at: +[Legal Code (read the full text)][1]. +on March 30, 2021. + +*** + +## No Copyright + +The person who associated a work with this deed has dedicated the work to +the public domain by waiving all of his or her rights to the work worldwide +under copyright law, including all related and neighboring rights, to the +extent allowed by law. + +You can copy, modify, distribute and perform the work, even for commercial +purposes, all without asking permission. + +*** + +## Other Information + +In no way are the patent or trademark rights of any person affected by CC0, +nor are the rights that other persons may have in the work or in how the +work is used, such as publicity or privacy rights. + +Unless expressly stated otherwise, the person who associated a work with +this deed makes no warranties about the work, and disclaims liability for +all uses of the work, to the fullest extent permitted by applicable law. +When using or citing the work, you should not imply endorsement by the +author or the affirmer. + + +[1]: https://creativecommons.org/publicdomain/zero/1.0/legalcode + diff --git a/archive/Solidity.md b/archive/Solidity.md new file mode 100644 index 0000000..b819e94 --- /dev/null +++ b/archive/Solidity.md @@ -0,0 +1,128 @@ +--- +name: Solidity +category: +--- + +## This page might be outdated. + +Solidity is probably the first example of a Contract-Oriented Language, a slight reworking of the well-established group of Object-Oriented Languages. Here's an example of Solidity: + +``` +contract PriceFeed is owned, mortal, priced, named("GoldFeed") +{ + function updateInfo(uint newInfo) onlyowner { + info = newInfo; + } + + function get() constant costs returns(uint r) { + r = info; + } + + uint info; +} +``` + +From the syntax, it will feel mostly similar to something between JavaScript and C++ but with a number of additions to make it suitable for writing contracts within Ethereum. Language additions include: + +* static typing; +* property-based language transforms; +* contracts as first-class entities; +* state as part of a contract able to map & segment information into the permanent storage; +* invariants, pre- and post-conditions as part of a contract; +* variadic return values with named components; +* a safe language subset allowing guaranteed static analysis & proofs; +* an inbuilt test-generation and execution environment for situations where formal proofing is not practical. + +### Documentation + +It is expected that each method, together with the contract itself, will be documented in several ways. Aside from informal descriptions, each method should come with a formalised method to describe exactly its effect on the state of Ethereum. It should also include, where possible, pre- and post-conditions on the contract state, and the contract itself should include invariants over its own state, again each translated into natural language. + +For GavCoin, a meta coin that that is sub-divisible down to 1,000, and includes two functions `balance` and `send`, we might see the basic, undocumented contract as: + +``` +contract GavCoin is named("GavCoin") +{ + function GavCoin() { + balances[transaction.sender] = 100000000000; + } + function send(address to, uint256 valueInmGAV) { + balances[to] += valueInmGAV; + balances[transaction.sender] -= valueInmGAV; + } + function balance(address who) constant returns (uint256 balanceInmGAV) { + balanceInmGAV = balances[who]; + } + + invariant reduce(0, +, map(valueOf, balances)) == 100000000000; + + mapping (address => uint256) balances; +}; +``` + +Of course it is wrong. A static checker will analyse this (with the language assertion that the uint256 type must not be allowed to underflow unless explicitly given that attribute) and come back with something like: + +``` +Line 8: >>> balances[transaction.sender] -= valueInmGAV <<<: + balances[...] may underflow with '-=' operation using unbounded operand valueInmGAV. + Suggestion: surround code with conditional to bound operand valueInmGAV. +``` + +This is basically saying that it can see no reason why `valueInmGAV` could be no bigger than `balances[transaction.sender]`. And it's right. We forgot to check the parameters. It's easily fixed by adding the conditional and altering the method to: + +``` + void send(address to, uint256 valueInmGAV) { + if (balances[transaction.sender] >= valueInmGAV) { + balances[to] += valueInmGAV; + balances[transaction.sender] -= valueInmGAV; + } + } +``` + +This would then be formally documented: + +``` +/// @title Some title here. +/// @author Homer Simpson +contract GavCoin is named("GavCoin") +{ + /// @notice Endows `message.caller.address()` with 1m GAV. + function GavCoin() { + balances[transaction.sender] = 100000000000; + } + + /// @notice Send `(valueInmGAV / 1000).fixed(0,3)` GAV from the account of + /// `message.caller.address()`, to an account accessible only by `to.address()`. + /// @dev This is the developer documentation. + /// @param to The docs for the first param. + /// @param valueInmGav The docs for the second param. + function send(address to, uint256 valueInmGAV) { + if (balances[message.caller] >= valueInmGAV) { + balances[to] += valueInmGAV; + balances[message.caller] -= valueInmGAV; + } + } + + /// @notice `(balanceInmGAV / 1000).fixed(0,3)` GAV is the total funds available to `who.address()`. + function balance(address who) constant returns (uint256 balanceInmGAV) { + balanceInmGAV = balances[who]; + } + + /// @notice The sum total amount of GAV in the system is 1 million. + invariant reduce(0, add, map(valueOf, balances)) == 100000000000; + + mapping (address => uint256) balances; +}; +``` + +This documentation would then allow the Ethereum browser to translate any message (and thus transaction) going in to this contract into English (and on to other languages hence). It would also allow a lay viewer to immediately discern what the contract conforms to; in this case they could see that it's premined in favour of the transaction sender and that the total amount of coins in the system never changes. + +For example, should a DApp, malicious or otherwise, attempt to send a transaction that gives all the user's GAV to itself, the user would, prior to signing and submission, receive a message saying something like: + +``` +Untrusted ÐApp "Foo Sprocket DApp" attempting to transact in your name: +Send 45.780 GAV from the account of Your Name Here to an account accessible only by Foo Sprocket DApp. +Do you wish to allow this? +``` + +Of course, they might be a bit more cunning and send it to an anonymous address, however, by differentiating friends' (and other known people) addresses from anonymous or untrusted addresses both visibly and clearly, we can imagine a mechanism that, at least for simple contracts, allow users a good level of security without excessive harm to their experience. + diff --git a/archive/ethereum-contract-abi.md b/archive/ethereum-contract-abi.md new file mode 100644 index 0000000..1bec785 --- /dev/null +++ b/archive/ethereum-contract-abi.md @@ -0,0 +1,383 @@ +--- +name: Ethereum Contract ABI +category: +--- + +# Functions + +## Basic design + +We assume the ABI is strongly typed, known at compilation time and static. No introspection mechanism will be provided. We assert that all contracts will have the interface definitions of any contracts they call available at compile-time. + +This specification does not address contracts whose interface is dynamic or otherwise known only at run-time. Should these cases become important they can be adequately handled as facilities built within the Ethereum ecosystem. + +## Function Selector + +The first four bytes of the call data for a function call specifies the function to be called. It is the +first (left, high-order in big-endian) four bytes of the Keccak (SHA-3) hash of the signature of the function. The signature is defined as the canonical expression of the basic prototype, i.e. +the function name with the parenthesised list of parameter types. Parameter types are split by a single comma - no spaces are used. + +## Argument Encoding + +Starting from the fifth byte, the encoded arguments follow. This encoding is also used in other places, e.g. the return values and also event arguments are encoded in the same way, without the four bytes specifying the function. + +### Types + +The following elementary types exist: +- `uint`: unsigned integer type of `N` bits, `0 < N <= 256`, `N % 8 == 0`. e.g. `uint32`, `uint8`, `uint256`. +- `int`: two's complement signed integer type of `N` bits, `0 < N <= 256`, `N % 8 == 0`. +- `address`: equivalent to `bytes20`, except for the assumed interpretation and language typing. +- `uint`, `int`: synonyms for `uint256`, `int256` respectively (not to be used for computing the function selector). +- `bool`: equivalent to `uint8` restricted to the values 0 and 1 +- `realx`: fixed-point signed number of `N+M` bits, `0 < N + M <= 256`, `N % 8 == M % 8 == 0`. Corresponds to the int256 equivalent binary value divided by `2^M`. +- `urealx`: unsigned variant of `realx`. +- `real`, `ureal`: synonyms for `real128x128`, `ureal128x128` respectively (not to be used for computing the function selector). +- `bytes`: binary type of `N` bytes, `N >= 0`. + +The following (fixed-size) array type exists: +- `[N]`: a fixed-length array of the given fixed-length type. + +The following non-fixed-size types exist: +- `bytes`: dynamic sized byte sequence. +- `string`: dynamic sized unicode string assumed to be UTF-8 encoded. +- `[]`: a variable-length array of the given fixed-length type. + +### Formal Specification of the Encoding + +We will now formally specify the encoding, such that it will have the following +properties, which are especially useful if some arguments are nested arrays: + +**Properties:** + +1. The number of reads necessary to access a value is at most the depth of the +value inside the argument array structure, i.e. four reads are needed to +retrieve `a_i[k][l][r]`. In a previous version of the ABI, the number of reads scaled +linearly with the total number of dynamic parameters in the worst case. + +2. The data of a variable or array element is not interleaved with other data +and it is relocatable, i.e. it only uses relative "addresses" + +We distinguish static and dynamic types. Static types are encoded in-place and dynamic types are encoded at a separately allocated location after the current block. + +**Definition:** The following types are called "dynamic": +* `bytes` +* `string` +* `T[]` for any `T` +* `T[k]` for any dynamic `T` and any `k > 0` + +All other types are called "static". + +**Definition:** `len(a)` is the number of bytes in a binary string `a`. +The type of `len(a)` is assumed to be `uint256`. + +We define `enc`, the actual encoding, as a mapping of values of the ABI types to binary strings such +that `len(enc(X))` depends on the value of `X` if and only if the type of `X` +is dynamic. + +**Definition:** For any ABI value `X`, we recursively define `enc(X)`, depending +on the type of `X` being + +- `T[k]` for any `T` and `k`: + + `enc(X) = head(X[0]) ... head(X[k-1]) tail(X[0]) ... tail(X[k-1])` + + where `head` and `tail` are defined for `X[i]` being of a static type as + `head(X[i]) = enc(X[i])` and `tail(X[i]) = ""` (the empty string) + and as + `head(X[i]) = enc(len(head(X[0]) ... head(X[k-1]) tail(X[0]) ... tail(X[i-1])))` + `tail(X[i]) = enc(X[i])` + otherwise. + + Note that in the dynamic case, `head(X[i])` is well-defined since the lengths of + the head parts only depend on the types and not the values. Its value is the offset + of the beginning of `tail(X[i])` relative to the start of `enc(X)`. + +- `T[]` where `X` has `k` elements (`k` is assumed to be of type `uint256`): + + `enc(X) = enc(k) enc([X[1], ..., X[k]])` + + i.e. it is encoded as if it were an array of static size `k`, prefixed with + the number of elements. + +- `bytes`, of length `k` (which is assumed to be of type `uint256`): + + `enc(X) = enc(k) pad_right(X)`, i.e. the number of bytes is encoded as a + `uint256` followed by the actual value of `X` as a byte sequence, followed by + the minimum number of zero-bytes such that `len(enc(X))` is a multiple of 32. + +- `string`: + + `enc(X) = enc(enc_utf8(X))`, i.e. `X` is utf-8 encoded and this value is interpreted as of `bytes` type and encoded further. Note that the length used in this subsequent encoding is the number of bytes of the utf-8 encoded string, not its number of characters. + +- `uint`: `enc(X)` is the big-endian encoding of `X`, padded on the higher-order (left) side with zero-bytes such that the length is a multiple of 32 bytes. +- `address`: as in the `uint160` case +- `int`: `enc(X)` is the big-endian two's complement encoding of `X`, padded on the higher-oder (left) side with `0xff` for negative `X` and with zero bytes for positive `X` such that the length is a multiple of 32 bytes. +- `bool`: as in the `uint8` case, where `1` is used for `true` and `0` for `false` +- `realx`: `enc(X)` is `enc(X * 2**M)` where `X * 2**M` is interpreted as a `int256`. +- `real`: as in the `real128x128` case +- `urealx`: `enc(X)` is `enc(X * 2**M)` where `X * 2**M` is interpreted as a `uint256`. +- `ureal`: as in the `ureal128x128` case +- `bytes`: `enc(X)` is the sequence of bytes in `X` padded with zero-bytes to a length of 32. + +Note that for any `X`, `len(enc(X))` is a multiple of 32. + +## Function Selector and Argument Encoding + +All in all, a call to the function `f` with parameters `a_1, ..., a_n` is encoded as + + `function_selector(f) enc([a_1, ..., a_n])` + +and the return values `v_1, ..., v_k` of `f` are encoded as + + `enc([v_1, ..., v_k])` + +where the types of `[a_1, ..., a_n]` and `[v_1, ..., v_k]` are assumed to be +fixed-size arrays of length `n` and `k`, respectively. Note that strictly, +`[a_1, ..., a_n]` can be an "array" with elements of different types, but the +encoding is still well-defined as the assumed common type `T` (above) is not +actually used. + +## Examples + +Given the contract: + +```js +contract Foo { + function bar(real[2] xy) {} + function baz(uint32 x, bool y) returns (bool r) { r = x > 32 || y; } + function sam(bytes name, bool z, uint[] data) {} +} +``` + +Thus for our `Foo` example if we wanted to call `baz` with the parameters `69` and `true`, we would pass 68 bytes total, which can be broken down into: + +- `0xcdcd77c0`: the Method ID. This is derived as the first 4 bytes of the Keccak hash of the ASCII form of the signature `baz(uint32,bool)`. +- `0x0000000000000000000000000000000000000000000000000000000000000045`: the first parameter, a uint32 value `69` padded to 32 bytes +- `0x0000000000000000000000000000000000000000000000000000000000000001`: the second parameter - boolean `true`, padded to 32 bytes + +In total: +``` +0xcdcd77c000000000000000000000000000000000000000000000000000000000000000450000000000000000000000000000000000000000000000000000000000000001 +``` +It returns a single `bool`. If, for example, it were to return `false`, its output would be the single byte array `0x0000000000000000000000000000000000000000000000000000000000000000`, a single bool. + +If we wanted to call `bar` with the argument `[2.125, 8.5]`, we would pass 68 bytes total, broken down into: +- `0x3e279860`: the Method ID. This is derived from the signature `bar(real128x128[2])`. Note that `real` is substituted for its canonical representation `real128x128`. +- `0x0000000000000000000000000000000240000000000000000000000000000000`: the first part of the first parameter, a real128x128 value `2.125`. +- `0x0000000000000000000000000000000880000000000000000000000000000000`: the first part of the first parameter, a real128x128 value `8.5`. + +In total: +``` +0x3e27986000000000000000000000000000000002400000000000000000000000000000000000000000000000000000000000000880000000000000000000000000000000 +``` + +If we wanted to call `sam` with the arguments `"dave"`, `true` and `[1,2,3]`, we would pass 292 bytes total, broken down into: +- `0x8FF261B0`: the Method ID. This is derived from the signature `sam(bytes,bool,uint256[])`. Note that `uint` is substituted for its canonical representation `uint256`. +- `0x0000000000000000000000000000000000000000000000000000000000000060`: the location of the data part of the first parameter (dynamic type), measured in bytes from the start of the arguments block. In this case, `0x60`. +- `0x0000000000000000000000000000000000000000000000000000000000000001`: the second parameter: boolean true. +- `0x00000000000000000000000000000000000000000000000000000000000000c0`: the location of the data part of the third parameter (dynamic type), measured in bytes. In this case, `0xc0`. +- `0x0000000000000000000000000000000000000000000000000000000000000004`: the data part of the first argument, it starts with the length of the byte array in elements, in this case, 4. +- `0x6461766500000000000000000000000000000000000000000000000000000000`: the contents of the first argument: the UTF-8 (equal to ASCII in this case) encoding of `"dave"`, padded on the right to 32 bytes. +- `0x0000000000000000000000000000000000000000000000000000000000000003`: the data part of the third argument, it starts with the length of the array in elements, in this case, 3. +- `0x0000000000000000000000000000000000000000000000000000000000000001`: the first entry of the third parameter. +- `0x0000000000000000000000000000000000000000000000000000000000000002`: the second entry of the third parameter. +- `0x0000000000000000000000000000000000000000000000000000000000000003`: the third entry of the third parameter. + +In total: +``` +0x8FF261B00000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000000000000464617665000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003 +``` + + +### Use of Dynamic Types + +A call to a function with the signature `f(uint,uint32[],bytes10,bytes)` with values `(0x123, [0x456, 0x789], "1234567890", "Hello, world!")` is encoded in the following way: + +We take the first four bytes of `sha3("f(uint256,uint32[],bytes10,bytes)")`, i.e. `0x8be65246`. +Then we encode the head parts of all four arguments. For the static types `uint256` and `bytes10`, these are directly the values we want to pass, whereas for the dynamic types `uint32[]` and `bytes`, we use the offset in bytes to the start of their data area, measured from the start of the value encoding (i.e. not counting the first four bytes containing the hash of the function signature). These are: + + - `0x0000000000000000000000000000000000000000000000000000000000000123` (`0x123` padded to 32 bytes) + - `0x0000000000000000000000000000000000000000000000000000000000000080` (offset to start of data part of second parameter, 4*32 bytes, exactly the size of the head part) + - `0x3132333435363738393000000000000000000000000000000000000000000000` (`"1234567890"` padded to 32 bytes on the right) + - `0x00000000000000000000000000000000000000000000000000000000000000e0` (offset to start of data part of fourth parameter = offset to start of data part of first dynamic parameter + size of data part of first dynamic parameter = 4*32 + 3*32 (see below)) + +After this, the data part of the first dynamic argument, `[0x456, 0x789]` follows: + + - `0x0000000000000000000000000000000000000000000000000000000000000002` (number of elements of the array, 2) + - `0x0000000000000000000000000000000000000000000000000000000000000456` (first element) + - `0x0000000000000000000000000000000000000000000000000000000000000789` (second element) + +Finally, we encode the data part of the second dynamic argument, `"Hello, world!"`: + + - `0x000000000000000000000000000000000000000000000000000000000000000d` (number of elements (bytes in this case): 13) + - `0x48656c6c6f2c20776f726c642100000000000000000000000000000000000000` (`"Hello, world!"` padded to 32 bytes on the right) + +All together, the encoding is (spaces added for clarity): + +`0x8be65246 0000000000000000000000000000000000000000000000000000000000000123 0000000000000000000000000000000000000000000000000000000000000080 3132333435363738393000000000000000000000000000000000000000000000 00000000000000000000000000000000000000000000000000000000000000e0 0000000000000000000000000000000000000000000000000000000000000002 0000000000000000000000000000000000000000000000000000000000000456 0000000000000000000000000000000000000000000000000000000000000789 000000000000000000000000000000000000000000000000000000000000000d 48656c6c6f2c20776f726c642100000000000000000000000000000000000000` + + +# Events + +Events are an abstraction of the Ethereum logging/event-watching protocol. Log entries provide the contract's address, a series of up to four topics and some arbitrary length binary data. Events leverage the existing function ABI in order to interpret this (together with an interface spec) as a properly typed structure. + +Given an event name and series of event parameters, we split them into two sub-series: those which are indexed and those which are not. Those which are indexed, which may number up to 3, are used alongside the Keccak hash of the event signature to form the topics of the log entry. Those which as not indexed form the byte array of the event. + +In effect, a log entry using this ABI is described as: + +- `address`: the address of the contract (intrinsically provided by Ethereum); +- `topics[0]`: `keccak(EVENT_NAME+"("+EVENT_ARGS.map(canonical_type_of).join(",")+")")` (`canonical_type_of` is a function that simply returns the canonical type of a given argument, e.g. for `uint indexed foo`, it would return `uint256`). If the event is declared as `anonymous` the `topics[0]` is not generated; +- `topics[n]`: `EVENT_INDEXED_ARGS[n - 1]` (`EVENT_INDEXED_ARGS` is the series of `EVENT_ARGS` that are indexed); +- `data`: `abi_serialise(EVENT_NON_INDEXED_ARGS)` (`EVENT_NON_INDEXED_ARGS` is the series of `EVENT_ARGS` that are not indexed, `abi_serialise` is the ABI serialisation function used for returning a series of typed values from a function, as described above). + +# JSON + +The JSON format for a contract's interface is given by an array of function and/or event descriptions. A function description is a JSON object with the fields: + +- `type`: `"function"` or `"constructor"` (can be omitted, defaulting to function); +- `name`: the name of the function (only present for function types); +- `inputs`: an array of objects, each of which contains: +* `name`: the name of the parameter; +* `type`: the canonical type of the parameter. +- `outputs`: an array of objects similar to `inputs`, can be omitted. + +An event description is a JSON object with fairly similar fields: + +- `type`: always `"event"` +- `name`: the name of the event; +- `inputs`: an array of objects, each of which contains: +* `name`: the name of the parameter; +* `type`: the canonical type of the parameter. +* `indexed`: `true` if the field is part of the log's topics, `false` if it one of the log's data segment. +* `anonymous`: `true` if the event was declared as `anonymous`. + +For example, + +```js +contract Test { +function Test(){ b = 0x12345678901234567890123456789012; } +event Event(uint indexed a, bytes32 b) +event Event2(uint indexed a, bytes32 b) +function foo(uint a) { Event(a, b); } +bytes32 b; +} +``` + +would result in the JSON: + +```js +[{ +"type":"event", +"inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}], +"name":"Event" +}, { +"type":"event", +"inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}], +"name":"Event2" +}, { +"type":"event", +"inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}], +"name":"Event2" +}, { +"type":"function", +"inputs": [{"name":"a","type":"uint256"}], +"name":"foo", +"outputs": [] +}] +``` + +# Example Javascript Usage + +```js +var Test = eth.contract( +[{ +"type":"event", +"inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}], +"name":"Event" +}, { +"type":"event", +"inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}], +"name":"Event2" +}, { +"type":"function", +"inputs": [{"name":"a","type":"uint256"}], +"name":"foo", +"outputs": [] +}]); +var theTest = new Test(addrTest); + +// examples of usage: +// every log entry ("event") coming from theTest (i.e. Event & Event2): +var f0 = eth.filter(theTest); +// just log entries ("events") of type "Event" coming from theTest: +var f1 = eth.filter(theTest.Event); +// also written as +var f1 = theTest.Event(); +// just log entries ("events") of type "Event" and "Event2" coming from theTest: +var f2 = eth.filter([theTest.Event, theTest.Event2]); +// just log entries ("events") of type "Event" coming from theTest with indexed parameter 'a' equal to 69: +var f3 = eth.filter(theTest.Event, {'a': 69}); +// also written as +var f3 = theTest.Event({'a': 69}); +// just log entries ("events") of type "Event" coming from theTest with indexed parameter 'a' equal to 69 or 42: +var f4 = eth.filter(theTest.Event, {'a': [69, 42]}); +// also written as +var f4 = theTest.Event({'a': [69, 42]}); + +// options may also be supplied as a second parameter with `earliest`, `latest`, `offset` and `max`, as defined for `eth.filter`. +var options = { 'max': 100 }; +var f4 = theTest.Event({'a': [69, 42]}, options); + +var trigger; +f4.watch(trigger); + +// call foo to make an Event: +theTest.foo(69); + +// would call trigger like: +//trigger(theTest.Event, {'a': 69, 'b': '0x12345678901234567890123456789012'}, n); +// where n is the block number that the event triggered in. +``` + +Implementation: + +```js +// e.g. f4 would be similar to: +web3.eth.filter({'max': 100, 'address': theTest.address, 'topics': [ [69, 42] ]}); +// except that the resultant data would need to be converted from the basic log entry format like: +{ + 'address': theTest.address, + 'topics': [web3.sha3("Event(uint256,bytes32)"), 0x00...0045 /* 69 in hex format */], + 'data': '0x12345678901234567890123456789012', + 'number': n +} +// into data good for the trigger, specifically the three fields: + Test.Event // derivable from the first topic + {'a': 69, 'b': '0x12345678901234567890123456789012'} // derivable from the 'indexed' bool in the interface, the later 'topics' and the 'data' + n // from the 'number' +``` + +Event result: +```js +[ { + 'event': Test.Event, + 'args': {'a': 69, 'b': '0x12345678901234567890123456789012'}, + 'number': n + }, + { ... + } ... +] +``` + +### JUST DONE! [develop branch] +**NOTE: THIS IS OLD - IGNORE IT unless reading for historical purposes** + +- Internal LogFilter, log-entry matching mechanism and eth_installFilter needs to support matching multiple values (OR semantics) *per* topic index (at present it will only match topics with AND semantics and set-inclusion, not per-index). + +i.e. at present you can only ask for each of a number of given topic values to be matched throughout each topic: + +- `topics: [69, 42, "Gav"]` would match against logs with 3 topics `[42, 69, "Gav"]`, `["Gav", 69, 42]` but **not** against logs with topics `[42, 70, "Gav"]`. + +we need to be able to provide one of a number of topic values, and, each of these options for each topic index: + +- `topics: [[69, 42], [] /* anything */, "Gav"]` should match against logs with 3 topics `[42, 69, "Gav"]`, `[42, 70, "Gav"]` but **not** against `["Gav", 69, 42]`. \ No newline at end of file diff --git a/archive/javascript-api.md b/archive/javascript-api.md new file mode 100644 index 0000000..ec38fa8 --- /dev/null +++ b/archive/javascript-api.md @@ -0,0 +1,2416 @@ +--- +name: Javascript API +category: +--- + +# Web3 JavaScript Ðapp API + +To make your Ðapp work on Ethereum, you can use the `web3` object provided by the [web3.js library](https://github.com/ethereum/web3.js). Under the hood it communicates to a local node through [RPC calls](/json-rpc/api.md). web3.js works with any Ethereum node, which exposes an RPC layer. + +`web3` contains the `eth` object - `web3.eth` (for specifically Ethereum blockchain interactions) and the `shh` object - `web3.shh` (for Whisper interaction). Over time we'll introduce other objects for each of the other web3 protocols. Working [examples can be found here](https://github.com/ethereum/web3.js/tree/master/example). + +If you want to look at some more sophisticated examples using web3.js check out these [useful Ðapp patterns](/concepts/useful-dapp-patterns.md). + +## Using callbacks + +As this API is designed to work with a local RPC node and all its functions are by default use synchronous HTTP requests.con + +If you want to make an asynchronous request, you can pass an optional callback as the last parameter to most functions. +All callbacks are using an [error first callback](http://fredkschott.com/post/2014/03/understanding-error-first-callbacks-in-node-js/) style: + +```js +web3.eth.getBlock(48, function(error, result){ + if(!error) + console.log(result) + else + console.error(error); +}) +``` + +## Batch requests + +Batch requests allow queuing up requests and processing them at once. + +```js +var batch = web3.createBatch(); +batch.add(web3.eth.getBalance.request('0x0000000000000000000000000000000000000000', 'latest', callback)); +batch.add(web3.eth.contract(abi).at(address).balance.request(address, callback2)); +batch.execute(); +``` + +## A note on big numbers in web3.js + +You will always get a BigNumber object for balance values as JavaScript is not able to handle big numbers correctly. +Look at the following examples: + +```js +"101010100324325345346456456456456456456" +// "101010100324325345346456456456456456456" +101010100324325345346456456456456456456 +// 1.0101010032432535e+38 +``` + +web3.js depends on the [BigNumber Library](https://github.com/MikeMcl/bignumber.js/) and adds it automatically. + +```js +var balance = new BigNumber('131242344353464564564574574567456'); +// or var balance = web3.eth.getBalance(someAddress); + +balance.plus(21).toString(10); // toString(10) converts it to a number string +// "131242344353464564564574574567477" +``` + +The next example wouldn't work as we have more than 20 floating points, therefore it is recommended that you always keep your balance in *wei* and only transform it to other units when presenting to the user: +```js +var balance = new BigNumber('13124.234435346456466666457455567456'); + +balance.plus(21).toString(10); // toString(10) converts it to a number string, but can only show max 20 floating points +// "13145.23443534645646666646" // you number would be cut after the 20 floating point +``` + +## Web3 Javascript Ðapp API Reference + +* [web3](#web3) + * [version](#web3versionapi) + * [api](#web3versionapi) + * [node](#web3versionnode) + * [network](#web3versionnetwork) + * [ethereum](#web3versionethereum) + * [whisper](#web3versionwhisper) + * [isConnected()](#web3isconnected) + * [setProvider(provider)](#web3setprovider) + * [currentProvider](#web3currentprovider) + * [reset()](#web3reset) + * [sha3(string)](#web3sha3) + * [toHex(stringOrNumber)](#web3tohex) + * [toAscii(hexString)](#web3toascii) + * [fromAscii(textString, [padding])](#web3fromascii) + * [toDecimal(hexString)](#web3todecimal) + * [toChecksumAddress(string)](#web3tochecksumaddress) + * [fromDecimal(number)](#web3fromdecimal) + * [fromWei(numberStringOrBigNumber, unit)](#web3fromwei) + * [toWei(numberStringOrBigNumber, unit)](#web3towei) + * [toBigNumber(numberOrHexString)](#web3tobignumber) + * [isAddress(hexString)](#web3isAddress) + * [net](#web3net) + * [listening/getListening](#web3netlistening) + * [peerCount/getPeerCount](#web3ethpeercount) + * [eth](#web3eth) + * [defaultAccount](#web3ethdefaultaccount) + * [defaultBlock](#web3ethdefaultblock) + * [syncing/getSyncing](#web3ethsyncing) + * [isSyncing](#web3ethissyncing) + * [coinbase/getCoinbase](#web3ethcoinbase) + * [hashrate/getHashrate](#web3ethhashrate) + * [gasPrice/getGasPrice](#web3ethgasprice) + * [accounts/getAccounts](#web3ethaccounts) + * [mining/getMining](#web3ethmining) + * [blockNumber/getBlockNumber](#web3ethblocknumber) + * [register(hexString)](#web3ethregister) (Not implemented yet) + * [unRegister(hexString)](#web3ethunregister) (Not implemented yet) + * [getBalance(address)](#web3ethgetbalance) + * [getStorageAt(address, position)](#web3ethgetstorageat) + * [getCode(address)](#web3ethgetcode) + * [getBlock(hash/number)](#web3ethgetblock) + * [getBlockTransactionCount(hash/number)](#web3ethgetblocktransactioncount) + * [getUncle(hash/number)](#web3ethgetuncle) + * [getBlockUncleCount(hash/number)](#web3ethgetblockunclecount) + * [getTransaction(hash)](#web3ethgettransaction) + * [getTransactionFromBlock(hashOrNumber, indexNumber)](#web3ethgettransactionfromblock) + * [getTransactionReceipt(hash)](#web3ethgettransactionreceipt) + * [getTransactionCount(address)](#web3ethgettransactioncount) + * [sendTransaction(object)](#web3ethsendtransaction) + * [call(object)](#web3ethcall) + * [estimateGas(object)](#web3ethestimategas) + * [filter(array (, options) )](#web3ethfilter) + - [watch(callback)](#web3ethfilter) + - [stopWatching(callback)](#web3ethfilter) + - [get()](#web3ethfilter) + * [contract(abiArray)](#web3ethcontract) + * [contract.myMethod()](#contract-methods) + * [contract.myEvent()](#contract-events) + * [contract.allEvents()](#contract-allevents) + * [getCompilers()](#web3ethgetcompilers) + * [compile.lll(string)](#web3ethcompilelll) + * [compile.solidity(string)](#web3ethcompilesolidity) + * [compile.serpent(string)](#web3ethcompileserpent) + * [namereg](#web3ethnamereg) + * [sendIBANTransaction](#web3ethsendibantransaction) + * [iban](#web3ethiban) + * [fromAddress](#web3ethibanfromaddress) + * [fromBban](#web3ethibanfrombban) + * [createIndirect](#web3ethibancreateindirect) + * [isValid](#web3ethibanisvalid) + * [isDirect](#web3ethibanisdirect) + * [isIndirect](#web3ethibanisindirect) + * [checksum](#web3ethibanchecksum) + * [institution](#web3ethibaninstitution) + * [client](#web3ethibanclient) + * [address](#web3ethibanaddress) + * [toString](#web3ethibantostring) + * [db](#web3db) + * [putString(name, key, value)](#web3dbputstring) + * [getString(name, key)](#web3dbgetstring) + * [putHex(name, key, value)](#web3dbputhex) + * [getHex(name, key)](#web3dbgethex) + * [shh](#web3shh) + * [post(postObject)](#web3shhpost) + * [newIdentity()](#web3shhnewidentity) + * [hasIdentity(hexString)](#web3shhhaveidentity) + * [newGroup(_id, _who)](#web3shhnewgroup) + * [addToGroup(_id, _who)](#web3shhaddtogroup) + * [filter(object/string)](#web3shhfilter) + * [watch(callback)](#web3shhfilter) + * [stopWatching(callback)](#web3shhfilter) + * [get(callback)](#web3shhfilter) + +### Usage + +#### web3 +The `web3` object provides all methods. + +##### Example + +```js +var Web3 = require('web3'); +// create an instance of web3 using the HTTP provider. +// NOTE in mist web3 is already available, so check first if it's available before instantiating +var web3 = new Web3(new Web3.providers.HttpProvider("http://localhost:8545")); +``` + +*** + +#### web3.version.api + +```js +web3.version.api +// or async +web3.version.getApi(callback(error, result){ ... }) +``` + +##### Returns + +`String` - The ethereum js api version. + +##### Example + +```js +var version = web3.version.api; +console.log(version); // "0.2.0" +``` + +*** + +#### web3.version.node + + web3.version.node + // or async + web3.version.getClient(callback(error, result){ ... }) + + +##### Returns + +`String` - The client/node version. + +##### Example + +```js +var version = web3.version.node; +console.log(version); // "Mist/v0.9.3/darwin/go1.4.1" +``` + +*** + +#### web3.version.network + + web3.version.network + // or async + web3.version.getNetwork(callback(error, result){ ... }) + + +##### Returns + +`String` - The network protocol version. + +##### Example + +```js +var version = web3.version.network; +console.log(version); // 54 +``` + +*** + +#### web3.version.ethereum + + web3.version.ethereum + // or async + web3.version.getEthereum(callback(error, result){ ... }) + + +##### Returns + +`String` - The ethereum protocol version. + +##### Example + +```js +var version = web3.version.ethereum; +console.log(version); // 60 +``` + +*** + +#### web3.version.whisper + + web3.version.whisper + // or async + web3.version.getWhisper(callback(error, result){ ... }) + + +##### Returns + +`String` - The whisper protocol version. + +##### Example + +```js +var version = web3.version.whisper; +console.log(version); // 20 +``` + +*** +#### web3.isConnected + + web3.isConnected() + +Should be called to check if a connection to a node exists + +##### Parameters +none + +##### Returns + +`Boolean` + +##### Example + +```js +if(!web3.isConnected()) { + + // show some dialog to ask the user to start a node + +} else { + + // start web3 filters, calls, etc + +} +``` + +*** + +#### web3.setProvider + + web3.setProvider(provider) + +Should be called to set provider. + +##### Parameters +none + +##### Returns + +`undefined` + +##### Example + +```js +web3.setProvider(new web3.providers.HttpProvider('http://localhost:8545')); // 8080 for cpp/AZ, 8545 for go/mist +``` + +*** + +#### web3.currentProvider + + web3.currentProvider + +Will contain the current provider, if one is set. This can be used to check if mist etc. set already a provider. + + +##### Returns + +`Object` - The provider set or `null`; + +##### Example + +```js +// Check if mist etc. already set a provider +if(!web3.currentProvider) + web3.setProvider(new web3.providers.HttpProvider("http://localhost:8545")); + +``` + +*** + +#### web3.reset + + web3.reset(keepIsSyncing) + +Should be called to reset state of web3. Resets everything except manager. Uninstalls all filters. Stops polling. + +##### Parameters + +1. `Boolean` - If `true` it will uninstall all filters, but will keep the [web3.eth.isSyncing()](#web3ethissyncing) polls + +##### Returns + +`undefined` + +##### Example + +```js +web3.reset(); +``` + +*** + +#### web3.sha3 + + web3.sha3(string [, callback]) + +##### Parameters + +1. `String` - The string to hash using the SHA3 algorithm +2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + + +##### Returns + +`String` - The SHA3 of the given data. + +##### Example + +```js +var str = web3.sha3("Some ASCII string to be hashed"); +console.log(str); // "0x536f6d6520415343494920737472696e6720746f20626520686173686564" + +var hash = web3.sha3(str); +console.log(hash); // "0xb21dbc7a5eb6042d91f8f584af266f1a512ac89520f43562c6c1e37eab6eb0c4" +``` + +*** + +#### web3.toHex + + web3.toHex(mixed); + +Converts any value into HEX. + +##### Parameters + +1. `String|Number|Object|Array|BigNumber` - The value to parse to HEX. If its an object or array it will be `JSON.stringify` first. If its a BigNumber it will make it the HEX value of a number. + +##### Returns + +`String` - The hex string of `mixed`. + +##### Example + +```js +var str = web3.toHex({test: 'test'}); +console.log(str); // '0x7b2274657374223a2274657374227d' +``` + +*** + +#### web3.toAscii + + web3.toAscii(hexString); + +Converts a HEX string into a ASCII string. + +##### Parameters + +1. `String` - A HEX string to be converted to ascii. + +##### Returns + +`String` - An ASCII string made from the given `hexString`. + +##### Example + +```js +var str = web3.toAscii("0x657468657265756d000000000000000000000000000000000000000000000000"); +console.log(str); // "ethereum" +``` + +*** + +#### web3.fromAscii + + web3.fromAscii(string [, padding]); + +Converts any ASCII string to a HEX string. + +##### Parameters + +1. `String` - An ASCII string to be converted to HEX. +2. `Number` - The number of bytes the returned HEX string should have. + +##### Returns + +`String` - The converted HEX string. + +##### Example + +```js +var str = web3.fromAscii('ethereum'); +console.log(str); // "0x657468657265756d" + +var str2 = web3.fromAscii('ethereum', 32); +console.log(str2); // "0x657468657265756d000000000000000000000000000000000000000000000000" +``` + +*** + +#### web3.toChecksumAddress + + web3.toChecksumAddress(hexString); + +Converts a string to the checksummed address equivalent. + +##### Parameters + +1. `String` - A string to be converted to a checksummed address. + + +##### Returns + +`String` - A string containing the checksummed address. + +##### Example + +```js +var myAddress = web3.toChecksumAddress('0xa0c876ec9f2d817c4304a727536f36363840c02c'); +console.log(myAddress); // '0xA0C876eC9F2d817c4304A727536f36363840c02c' +``` + +*** + +#### web3.toDecimal + + web3.toDecimal(hexString); + +Converts a HEX string to its number representation. + +##### Parameters + +1. `String` - An HEX string to be converted to a number. + + +##### Returns + +`Number` - The number representing the data `hexString`. + +##### Example + +```js +var number = web3.toDecimal('0x15'); +console.log(number); // 21 +``` + +*** + +#### web3.fromDecimal + + web3.fromDecimal(number); + +Converts a number or number string to its HEX representation. + +##### Parameters + +1. `Number|String` - A number to be converted to a HEX string. + +##### Returns + +`String` - The HEX string representing of the given `number`. + +##### Example + +```js +var value = web3.fromDecimal('21'); +console.log(value); // "0x15" +``` + +*** + +#### web3.fromWei + + web3.fromWei(number, unit) + +Converts a number of wei into the following ethereum units: + +- `kwei`/`ada` +- `mwei`/`babbage` +- `gwei`/`shannon` +- `szabo` +- `finney` +- `ether` +- `kether`/`grand`/`einstein` +- `mether` +- `gether` +- `tether` + +##### Parameters + +1. `Number|String|BigNumber` - A number or BigNumber instance. +2. `String` - One of the above ether units. + + +##### Returns + +`String|BigNumber` - Either a number string, or a BigNumber instance, depending on the given `number` parameter. + +##### Example + +```js +var value = web3.fromWei('21000000000000', 'finney'); +console.log(value); // "0.021" +``` + +*** + +#### web3.toWei + + web3.toWei(number, unit) + +Converts an ethereum unit into wei. Possible units are: + +- `kwei`/`ada` +- `mwei`/`babbage` +- `gwei`/`shannon` +- `szabo` +- `finney` +- `ether` +- `kether`/`grand`/`einstein` +- `mether` +- `gether` +- `tether` + +##### Parameters + +1. `Number|String|BigNumber` - A number or BigNumber instance. +2. `String` - One of the above ether units. + +##### Returns + +`String|BigNumber` - Either a number string, or a BigNumber instance, depending on the given `number` parameter. + +##### Example + +```js +var value = web3.toWei('1', 'ether'); +console.log(value); // "1000000000000000000" +``` + +*** + +#### web3.toBigNumber + + web3.toBigNumber(numberOrHexString); + +Converts a given number into a BigNumber instance. + +See the [note on BigNumber](#a-note-on-big-numbers-in-javascript). + +##### Parameters + +1. `Number|String` - A number, number string or HEX string of a number. + + +##### Returns + +`BigNumber` - A BigNumber instance representing the given value. + + +##### Example + +```js +var value = web3.toBigNumber('200000000000000000000001'); +console.log(value); // instanceOf BigNumber +console.log(value.toNumber()); // 2.0000000000000002e+23 +console.log(value.toString(10)); // '200000000000000000000001' +``` + +*** + +### web3.net + +#### web3.net.listening + + web3.net.listening + // or async + web3.net.getListening(callback(error, result){ ... }) + +This property is read only and says whether the node is actively listening for network connections or not. + +##### Returns + +`Boolean` - `true` if the client is actively listening for network connections, otherwise `false`. + +##### Example + +```js +var listening = web3.net.listening; +console.log(listening); // true of false +``` + +*** + +#### web3.net.peerCount + + web3.net.peerCount + // or async + web3.net.getPeerCount(callback(error, result){ ... }) + +This property is read only and returns the number of connected peers. + +##### Returns + +`Number` - The number of peers currently connected to the client. + +##### Example + +```js +var peerCount = web3.net.peerCount; +console.log(peerCount); // 4 +``` + +*** + +### web3.eth + +Contains the ethereum blockchain related methods. + +##### Example + +```js +var eth = web3.eth; +``` + +*** + +#### web3.eth.defaultAccount + + web3.eth.defaultAccount + +This default address is used for the following methods (optionally you can overwrite it by specifying the `from` property): + +- [web3.eth.sendTransaction()](#web3ethsendtransaction) +- [web3.eth.call()](#web3ethcall) + +##### Values + +`String`, 20 Bytes - Any address you own, or where you have the private key for. + +*Default is* `undefined`. + +##### Returns + +`String`, 20 Bytes - The currently set default address. + +##### Example + +```js +var defaultAccount = web3.eth.defaultAccount; +console.log(defaultAccount); // '' + +// set the default block +web3.eth.defaultAccount = '0x8888f1f195afa192cfee860698584c030f4c9db1'; +``` + +*** + +#### web3.eth.defaultBlock + + web3.eth.defaultBlock + +This default block is used for the following methods (optionally you can overwrite the defaultBlock by passing it as the last parameter): + +- [web3.eth.getBalance()](#web3ethgetbalance) +- [web3.eth.getCode()](#web3ethgetcode) +- [web3.eth.getTransactionCount()](#web3ethgettransactioncount) +- [web3.eth.getStorageAt()](#web3ethgetstorageat) +- [web3.eth.call()](#web3ethcall) + +##### Values + +Default block parameters can be one of the following: + +- `Number` - a block number +- `String` - `"earliest"`, the genisis block +- `String` - `"latest"`, the latest block (current head of the blockchain) +- `String` - `"pending"`, the currently mined block (including pending transactions) + +*Default is* `latest` + +##### Returns + +`Number|String` - The default block number to use when querying a state. + +##### Example + +```js +var defaultBlock = web3.eth.defaultBlock; +console.log(defaultBlock); // 'latest' + +// set the default block +web3.eth.defaultBlock = 231; +``` + +*** + +#### web3.eth.syncing + + web3.eth.syncing + // or async + web3.eth.getSyncing(callback(error, result){ ... }) + +This property is read only and returns the either a sync object, when the node is syncing or `false`. + +##### Returns + +`Object|Boolean` - A sync object as follows, when the node is currently syncing or `false`: + - `startingBlock`: `Number` - The block number where the sync started. + - `currentBlock`: `Number` - The block number where at which block the node currently synced to already. + - `highestBlock`: `Number` - The estimated block number to sync to. + +##### Example + +```js +var sync = web3.eth.syncing; +console.log(sync); +/* +{ + startingBlock: 300, + currentBlock: 312, + highestBlock: 512 +} +*/ +``` + +*** + +#### web3.eth.isSyncing + + web3.eth.isSyncing(callback); + +This convenience function calls the `callback` everytime a sync starts, updates and stops. + +##### Returns + +`Object` - a isSyncing object with the following methods: + + * `syncing.addCallback()`: Adds another callback, which will be called when the node starts or stops syncing. + * `syncing.stopWatching()`: Stops the syncing callbacks. + +##### Callback return value + +- `Boolean` - The callback will be fired with `true` when the syncing starts and with `false` when it stopped. +- `Object` - While syncing it will return the syncing object: + - `startingBlock`: `Number` - The block number where the sync started. + - `currentBlock`: `Number` - The block number where at which block the node currently synced to already. + - `highestBlock`: `Number` - The estimated block number to sync to. + + +##### Example + +```js +web3.eth.isSyncing(function(error, sync){ + if(!error) { + // stop all app activity + if(sync === true) { + // we use `true`, so it stops all filters, but not the web3.eth.syncing polling + web3.reset(true); + + // show sync info + } else if(sync) { + console.log(sync.currentBlock); + + // re-gain app operation + } else { + // run your app init function... + } + } +}); +``` + +*** + +#### web3.eth.coinbase + + web3.eth.coinbase + // or async + web3.eth.getCoinbase(callback(error, result){ ... }) + +This property is read only and returns the coinbase address were the mining rewards go to. + +##### Returns + +`String` - The coinbase address of the client. + +##### Example + +```js +var coinbase = web3.eth.coinbase; +console.log(coinbase); // "0x407d73d8a49eeb85d32cf465507dd71d507100c1" +``` + +*** + +#### web3.eth.mining + + web3.eth.mining + // or async + web3.eth.getMining(callback(error, result){ ... }) + + +This property is read only and says whether the node is mining or not. + + +##### Returns + +`Boolean` - `true` if the client is mining, otherwise `false`. + +##### Example + +```js +var mining = web3.eth.mining; +console.log(mining); // true or false +``` + +*** + +#### web3.eth.hashrate + + web3.eth.hashrate + // or async + web3.eth.getHashrate(callback(error, result){ ... }) + +This property is read only and returns the number of hashes per second that the node is mining with. + + +##### Returns + +`Number` - number of hashes per second. + +##### Example + +```js +var hashrate = web3.eth.hashrate; +console.log(hashrate); // 493736 +``` + +*** + +#### web3.eth.gasPrice + + web3.eth.gasPrice + // or async + web3.eth.getGasPrice(callback(error, result){ ... }) + + +This property is read only and returns the current gas price. +The gas price is determined by the x latest blocks median gas price. + +##### Returns + +`BigNumber` - A BigNumber instance of the current gas price in wei. + +See the [note on BigNumber](#a-note-on-big-numbers-in-javascript). + +##### Example + +```js +var gasPrice = web3.eth.gasPrice; +console.log(gasPrice.toString(10)); // "10000000000000" +``` + +*** + +#### web3.eth.accounts + + web3.eth.accounts + // or async + web3.eth.getAccounts(callback(error, result){ ... }) + +This property is read only and returns a list of accounts the node controls. + +##### Returns + +`Array` - An array of addresses controlled by client. + +##### Example + +```js +var accounts = web3.eth.accounts; +console.log(accounts); // ["0x407d73d8a49eeb85d32cf465507dd71d507100c1"] +``` + +*** + +#### web3.eth.blockNumber + + web3.eth.blockNumber + // or async + web3.eth.getBlockNumber(callback(error, result){ ... }) + +This property is read only and returns the current block number. + +##### Returns + +`Number` - The number of the most recent block. + +##### Example + +```js +var number = web3.eth.blockNumber; +console.log(number); // 2744 +``` + +*** + +#### web3.eth.register + + web3.eth.register(addressHexString [, callback]) + +(Not Implemented yet) +Registers the given address to be included in `web3.eth.accounts`. This allows non-private-key owned accounts to be associated as an owned account (e.g., contract wallets). + +##### Parameters + +1. `String` - The address to register +2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + + +##### Returns + +? + + +##### Example + +```js +web3.eth.register("0x407d73d8a49eeb85d32cf465507dd71d507100ca") +``` + +*** + +#### web3.eth.unRegister + + web3.eth.unRegister(addressHexString [, callback]) + + +(Not Implemented yet) +Unregisters a given address. + +##### Parameters + +1. `String` - The address to unregister. +2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + + +##### Returns + +? + + +##### Example + +```js +web3.eth.unregister("0x407d73d8a49eeb85d32cf465507dd71d507100ca") +``` + +*** + +#### web3.eth.getBalance + + web3.eth.getBalance(addressHexString [, defaultBlock] [, callback]) + +Get the balance of an address at a given block. + +##### Parameters + +1. `String` - The address to get the balance of. +2. `Number|String` - (optional) If you pass this parameter it will not use the default block set with [web3.eth.defaultBlock](#web3ethdefaultblock). +3. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`String` - A BigNumber instance of the current balance for the given address in wei. + +See the [note on BigNumber](#a-note-on-big-numbers-in-javascript). + +##### Example + +```js +var balance = web3.eth.getBalance("0x407d73d8a49eeb85d32cf465507dd71d507100c1"); +console.log(balance); // instanceof BigNumber +console.log(balance.toString(10)); // '1000000000000' +console.log(balance.toNumber()); // 1000000000000 +``` + +*** + +#### web3.eth.getStorageAt + + web3.eth.getStorageAt(addressHexString, position [, defaultBlock] [, callback]) + +Get the storage at a specific position of an address. + +##### Parameters + +1. `String` - The address to get the storage from. +2. `Number` - The index position of the storage. +3. `Number|String` - (optional) If you pass this parameter it will not use the default block set with [web3.eth.defaultBlock](#web3ethdefaultblock). +4. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + + +##### Returns + +`String` - The value in storage at the given position. + +##### Example + +```js +var state = web3.eth.getStorageAt("0x407d73d8a49eeb85d32cf465507dd71d507100c1", 0); +console.log(state); // "0x03" +``` + +*** + +#### web3.eth.getCode + + web3.eth.getCode(addressHexString [, defaultBlock] [, callback]) + +Get the code at a specific address. + +##### Parameters + +1. `String` - The address to get the code from. +2. `Number|String` - (optional) If you pass this parameter it will not use the default block set with [web3.eth.defaultBlock](#web3ethdefaultblock). +3. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`String` - The data at given address `addressHexString`. + +##### Example + +```js +var code = web3.eth.getCode("0xd5677cf67b5aa051bb40496e68ad359eb97cfbf8"); +console.log(code); // "0x600160008035811a818181146012578301005b601b6001356025565b8060005260206000f25b600060078202905091905056" +``` + +*** + +#### web3.eth.getBlock + + web3.eth.getBlock(blockHashOrBlockNumber [, returnTransactionObjects] [, callback]) + +Returns a block matching the block number or block hash. + +##### Parameters + +1. `String|Number` - The block number or hash. Or the string `"earliest"`, `"latest"` or `"pending"` as in the [default block parameter](#web3ethdefaultblock). +2. `Boolean` - (optional, default `false`) If `true`, the returned block will contain all transactions as objects, if `false` it will only contains the transaction hashes. +3. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`Object` - The block object: + + - `number`: `Number` - the block number. `null` when its pending block. + - `hash`: `String`, 32 Bytes - hash of the block. `null` when its pending block. + - `parentHash`: `String`, 32 Bytes - hash of the parent block. + - `nonce`: `String`, 8 Bytes - hash of the generated proof-of-work. `null` when its pending block. + - `sha3Uncles`: `String`, 32 Bytes - SHA3 of the uncles data in the block. + - `logsBloom`: `String`, 256 Bytes - the bloom filter for the logs of the block. `null` when its pending block. + - `transactionsRoot`: `String`, 32 Bytes - the root of the transaction trie of the block + - `stateRoot`: `String`, 32 Bytes - the root of the final state trie of the block. + - `miner`: `String`, 20 Bytes - the address of the beneficiary to whom the mining rewards were given. + - `difficulty`: `BigNumber` - integer of the difficulty for this block. + - `totalDifficulty`: `BigNumber` - integer of the total difficulty of the chain until this block. + - `extraData`: `String` - the "extra data" field of this block. + - `size`: `Number` - integer the size of this block in bytes. + - `gasLimit`: `Number` - the maximum gas allowed in this block. + - `gasUsed`: `Number` - the total used gas by all transactions in this block. + - `timestamp`: `Number` - the unix timestamp for when the block was collated. + - `transactions`: `Array` - Array of transaction objects, or 32 Bytes transaction hashes depending on the last given parameter. + - `uncles`: `Array` - Array of uncle hashes. + +##### Example + +```js +var info = web3.eth.block(3150); +console.log(info); +/* +{ + "number": 3, + "hash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46", + "parentHash": "0x2302e1c0b972d00932deb5dab9eb2982f570597d9d42504c05d9c2147eaf9c88", + "nonce": "0xfb6e1a62d119228b", + "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "transactionsRoot": "0x3a1b03875115b79539e5bd33fb00d8f7b7cd61929d5a3c574f507b8acf415bee", + "stateRoot": "0xf1133199d44695dfa8fd1bcfe424d82854b5cebef75bddd7e40ea94cda515bcb", + "miner": "0x8888f1f195afa192cfee860698584c030f4c9db1", + "difficulty": BigNumber, + "totalDifficulty": BigNumber, + "size": 616, + "extraData": "0x", + "gasLimit": 3141592, + "gasUsed": 21662, + "timestamp": 1429287689, + "transactions": [ + "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b" + ], + "uncles": [] +} +*/ +``` + +*** + +#### web3.eth.getBlockTransactionCount + + web3.eth.getBlockTransactionCount(hashStringOrBlockNumber [, callback]) + +Returns the number of transaction in a given block. + +##### Parameters + +1. `String|Number` - The block number or hash. Or the string `"earliest"`, `"latest"` or `"pending"` as in the [default block parameter](#web3ethdefaultblock). +2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`Number` - The number of transactions in the given block. + +##### Example + +```js +var number = web3.eth.getBlockTransactionCount("0x407d73d8a49eeb85d32cf465507dd71d507100c1"); +console.log(number); // 1 +``` + +*** + +#### web3.eth.getUncle + + web3.eth.getUncle(blockHashStringOrNumber, uncleNumber [, returnTransactionObjects] [, callback]) + +Returns a blocks uncle by a given uncle index position. + +##### Parameters + +1. `String|Number` - The block number or hash. Or the string `"earliest"`, `"latest"` or `"pending"` as in the [default block parameter](#web3ethdefaultblock). +2. `Number` - The index position of the uncle. +3. `Boolean` - (optional, default `false`) If `true`, the returned block will contain all transactions as objects, if `false` it will only contains the transaction hashes. +4. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + + +##### Returns + +`Object` - the returned uncle. For a return value see [web3.eth.getBlock()](#web3ethgetblock). + +**Note**: An uncle doesn't contain individual transactions. + +##### Example + +```js +var uncle = web3.eth.getUncle(500, 0); +console.log(uncle); // see web3.eth.getBlock + +``` + +*** + +##### web3.eth.getTransaction + + web3.eth.getTransaction(transactionHash [, callback]) + +Returns a transaction matching the given transaction hash. + +##### Parameters + +1. `String` - The transaction hash. +2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + + +##### Returns + +`Object` - A transaction object its hash `transactionHash`: + + - `hash`: `String`, 32 Bytes - hash of the transaction. + - `nonce`: `Number` - the number of transactions made by the sender prior to this one. + - `blockHash`: `String`, 32 Bytes - hash of the block where this transaction was in. `null` when its pending. + - `blockNumber`: `Number` - block number where this transaction was in. `null` when its pending. + - `transactionIndex`: `Number` - integer of the transactions index position in the block. `null` when its pending. + - `from`: `String`, 20 Bytes - address of the sender. + - `to`: `String`, 20 Bytes - address of the receiver. `null` when its a contract creation transaction. + - `value`: `BigNumber` - value transferred in Wei. + - `gasPrice`: `BigNumber` - gas price provided by the sender in Wei. + - `gas`: `Number` - gas provided by the sender. + - `input`: `String` - the data sent along with the transaction. + + +##### Example + +```js +var blockNumber = 668; +var indexOfTransaction = 0 + +var transaction = web3.eth.getTransaction(blockNumber, indexOfTransaction); +console.log(transaction); +/* +{ + "hash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b", + "nonce": 2, + "blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46", + "blockNumber": 3, + "transactionIndex": 0, + "from": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", + "to": "0x6295ee1b4f6dd65047762f924ecd367c17eabf8f", + "value": BigNumber, + "gas": 314159, + "gasPrice": BigNumber, + "input": "0x57cb2fc4" +} +*/ + +``` + +*** + +#### web3.eth.getTransactionFromBlock + + getTransactionFromBlock(hashStringOrNumber, indexNumber [, callback]) + +Returns a transaction based on a block hash or number and the transactions index position. + +##### Parameters + +1. `String` - A block number or hash. Or the string `"earliest"`, `"latest"` or `"pending"` as in the [default block parameter](#web3ethdefaultblock). +2. `Number` - The transactions index position. +3. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`Object` - A transaction object, see [web3.eth.getTransaction](#web3ethgettransaction): + + +##### Example + +```js +var transaction = web3.eth.getTransactionFromBlock('0x4534534534', 2); +console.log(transaction); // see web3.eth.getTransaction + +``` + +*** + +#### web3.eth.getTransactionReceipt + + web3.eth.getTransactionReceipt(hashString [, callback]) + +Returns the receipt of a transaction by transaction hash. + +**Note** That the receipt is not available for pending transactions. + + +##### Parameters + +1. `String` - The transaction hash. +2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`Object` - A transaction receipt object, or `null` when no receipt was found: + + - `blockHash`: `String`, 32 Bytes - hash of the block where this transaction was in. + - `blockNumber`: `Number` - block number where this transaction was in. + - `transactionHash`: `String`, 32 Bytes - hash of the transaction. + - `transactionIndex`: `Number` - integer of the transactions index position in the block. + - `from`: `String`, 20 Bytes - address of the sender. + - `to`: `String`, 20 Bytes - address of the receiver. `null` when its a contract creation transaction. + - `cumulativeGasUsed `: `Number ` - The total amount of gas used when this transaction was executed in the block. + - `gasUsed `: `Number ` - The amount of gas used by this specific transaction alone. + - `contractAddress `: `String` - 20 Bytes - The contract address created, if the transaction was a contract creation, otherwise `null`. + - `logs `: `Array` - Array of log objects, which this transaction generated. + +##### Example +```js +var receipt = web3.eth.getTransactionReceipt('0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b'); +console.log(receipt); +{ + "transactionHash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b", + "transactionIndex": 0, + "blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46", + "blockNumber": 3, + "contractAddress": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", + "cumulativeGasUsed": 314159, + "gasUsed": 30234, + "logs": [{ + // logs as returned by getFilterLogs, etc. + }, ...] +} +``` + +*** + +#### web3.eth.getTransactionCount + + web3.eth.getTransactionCount(addressHexString [, defaultBlock] [, callback]) + +Get the numbers of transactions sent from this address. + +##### Parameters + +1. `String` - The address to get the numbers of transactions from. +2. `Number|String` - (optional) If you pass this parameter it will not use the default block set with [web3.eth.defaultBlock](#web3ethdefaultblock). +3. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`Number` - The number of transactions sent from the given address. + +##### Example + +```js +var number = web3.eth.getTransactionCount("0x407d73d8a49eeb85d32cf465507dd71d507100c1"); +console.log(number); // 1 +``` + +*** + +#### web3.eth.sendTransaction + + web3.eth.sendTransaction(transactionObject [, callback]) + +Sends a transaction to the network. + +##### Parameters + +1. `Object` - The transaction object to send: + - `from`: `String` - The address for the sending account. Uses the [web3.eth.defaultAccount](#web3ethdefaultaccount) property, if not specified. + - `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. + - `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. + - `data`: `String` - (optional) Either a [byte string](/archive/Solidity.md) 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. +2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`String` - The 32 Bytes transaction hash as HEX string. + +If the transaction was a contract creation use [web3.eth.getTransactionReceipt()](#web3gettransactionreceipt) to get the contract address, after the transaction was mined. + +##### Example + +```js + +// compiled solidity source code using https://chriseth.github.io/cpp-ethereum/ +var code = "603d80600c6000396000f3007c01000000000000000000000000000000000000000000000000000000006000350463c6888fa18114602d57005b600760043502 +8060005260206000f3"; + +web3.eth.sendTransaction({data: code}, function(err, address) { + if (!err) + console.log(address); // "0x7f9fade1c0d57a7af66ab4ead7c2eb7b11a91385" +}); +``` + +*** + +#### web3.eth.call + + web3.eth.call(callObject [, defaultBlock] [, callback]) + +Executes a message call transaction, which is directly executed in the VM of the node, but never mined into the blockchain. + +##### Parameters + +1. `Object` - A transaction object see [web3.eth.sendTransaction](#web3ethsendtransaction), with the difference that for calls the `from` property is optional as well. +2. `Number|String` - (optional) If you pass this parameter it will not use the default block set with [web3.eth.defaultBlock](#web3ethdefaultblock). +3. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`String` - The returned data of the call, e.g. a codes functions return value. + +##### Example + +```js +var result = web3.eth.call({ + to: "0xc4abd0339eb8d57087278718986382264244252f", + data: "0xc6888fa10000000000000000000000000000000000000000000000000000000000000003" +}); +console.log(result); // "0x0000000000000000000000000000000000000000000000000000000000000015" +``` + +*** + +#### web3.eth.estimateGas + + web3.eth.estimateGas(callObject [, defaultBlock] [, callback]) + +Executes a message call or transaction, which is directly executed in the VM of the node, but never mined into the blockchain and returns the amount of the gas used. + +##### Parameters + +See [web3.eth.sendTransaction](#web3ethsendtransaction), expect that all properties are optional. + +##### Returns + +`Number` - the used gas for the simulated call/transaction. + +##### Example + +```js +var result = web3.eth.estimateGas({ + to: "0xc4abd0339eb8d57087278718986382264244252f", + data: "0xc6888fa10000000000000000000000000000000000000000000000000000000000000003" +}); +console.log(result); // "0x0000000000000000000000000000000000000000000000000000000000000015" +``` + +*** + +#### web3.eth.filter + +```js +// can be 'latest' or 'pending' +var filter = web3.eth.filter(filterString); +// OR object are log filter options +var filter = web3.eth.filter(options); + +// watch for changes +filter.watch(function(error, result){ + if (!error) + console.log(result); +}); + +// Additionally you can start watching right away, by passing a callback: +web3.eth.filter(options, function(error, result){ + if (!error) + console.log(result); +}); +``` + +##### Parameters + +1. `String|Object` - The string `"latest"` or `"pending"` to watch for changes in the latest block or pending transactions respectively. Or a filter options object as follows: + * `fromBlock`: `Number|String` - The number of the earliest block (`latest` may be given to mean the most recent and `pending` currently mining, block). By default `latest`. + * `toBlock`: `Number|String` - The number of the latest block (`latest` may be given to mean the most recent and `pending` currently mining, block). By default `latest`. + * `address`: `String` - An address or a list of addresses to only get logs from particular account(s). + * `topics`: `Array of Strings` - An array of values which must each appear in the log entries. The order is important, if you want to leave topics out use `null`, e.g. `[null, '0x00...']`. You can also pass another array for each topic with options for that topic e.g. `[null, ['option1', 'option2']]` + +##### Returns + +`Object` - A filter object with the following methods: + + * `filter.get(callback)`: Returns all of the log entries that fit the filter. + * `filter.watch(callback)`: Watches for state changes that fit the filter and calls the callback. See [this note](#using-callbacks) for details. + * `filter.stopWatching()`: Stops the watch and uninstalls the filter in the node. Should always be called once it is done. + +##### Watch callback return value + +- `String` - When using the `"latest"` parameter, it returns the block hash of the last incoming block. +- `String` - When using the `"pending"` parameter, it returns a transaction hash of the last add pending transaction. +- `Object` - When using manual filter options, it returns a log object as follows: + - `logIndex`: `Number` - integer of the log index position in the block. `null` when its pending log. + - `transactionIndex`: `Number` - integer of the transactions index position log was created from. `null` when its pending log. + - `transactionHash`: `String`, 32 Bytes - hash of the transactions this log was created from. `null` when its pending log. + - `blockHash`: `String`, 32 Bytes - hash of the block where this log was in. `null` when its pending. `null` when its pending log. + - `blockNumber`: `Number` - the block number where this log was in. `null` when its pending. `null` when its pending log. + - `address`: `String`, 32 Bytes - address from which this log originated. + - `data`: `String` - contains one or more 32 Bytes non-indexed arguments of the log. + - `topics`: `Array of Strings` - Array of 0 to 4 32 Bytes `DATA` of indexed log arguments. (In *solidity*: The first topic is the *hash* of the signature of the event (e.g. `Deposit(address,bytes32,uint256)`), except you declared the event with the `anonymous` specifier.) + +**Note** For event filter return values see [Contract Events](#contract-events) + +##### Example + +```js +var filter = web3.eth.filter('pending'); + +filter.watch(function (error, log) { + console.log(log); // {"address":"0x0000000000000000000000000000000000000000", "data":"0x0000000000000000000000000000000000000000000000000000000000000000", ...} +}); + +// get all past logs again. +var myResults = filter.get(function(error, logs){ ... }); + +... + +// stops and uninstalls the filter +filter.stopWatching(); + +``` + +*** + +#### web3.eth.contract + + web3.eth.contract(abiArray) + +Creates a contract object for a solidity contract, which can be used to initiate contracts on an address. +You can read more about events [here](/archive/ethereum-contract-abi.md#example-javascript-usage). + +##### Parameters + +1. `Array` - ABI array with descriptions of functions and events of the contract. + +##### Returns + +`Object` - A contract object, which can be initiated as follows: + +```js +var MyContract = web3.eth.contract(abiArray); + +// instantiate by address +var contractInstance = MyContract.at([address]); + +// deploy new contract +var contractInstance = MyContract.new([contructorParam1] [, contructorParam2], {data: '0x12345...', from: myAccount, gas: 1000000}); + +// Get the data to deploy the contract manually +var contractData = MyContract.new.getData([contructorParam1] [, contructorParam2], {data: '0x12345...'}); +// contractData = '0x12345643213456000000000023434234' +``` + +And then you can either initiate an existing contract on an address, +or deploy the contract using the compiled byte code: + +```js +// Instantiate from an existing address: +var myContractInstance = MyContract.at(myContractAddress); + + +// Or deploy a new contract: + +// Deploy the contract asyncronous: +var myContractReturned = MyContract.new(param1, param2, { + data: myContractCode, + gas: 300000, + from: mySenderAddress}, function(err, myContract){ + if(!err) { + // NOTE: The callback will fire twice! + // Once the contract has the transactionHash property set and once its deployed on an address. + + // e.g. check tx hash on the first call (transaction send) + if(!myContract.address) { + console.log(myContract.transactionHash) // The hash of the transaction, which deploys the contract + + // check address on the second call (contract deployed) + } else { + console.log(myContract.address) // the contract address + } + + // Note that the returned "myContractReturned" === "myContract", + // so the returned "myContractReturned" object will also get the address set. + } + }); + +// Deploy contract syncronous: The address will be added as soon as the contract is mined. +// Additionally you can watch the transaction by using the "transactionHash" property +var myContractInstance = MyContract.new(param1, param2, {data: myContractCode, gas: 300000, from: mySenderAddress}); +myContractInstance.transactionHash // The hash of the transaction, which created the contract +myContractInstance.address // undefined at start, but will be auto-filled later +``` + +**Note** When you deploy a new contract, you should check for the next 12 blocks or so if the contract code is still at the address (using [web3.eth.getCode()](#web3ethgetcode)), to make sure a fork didn't change that. + +##### Example + +```js +// contract abi +var abi = [{ + name: 'myConstantMethod', + type: 'function', + constant: true, + inputs: [{ name: 'a', type: 'string' }], + outputs: [{name: 'd', type: 'string' }] +}, { + name: 'myStateChangingMethod', + type: 'function', + constant: false, + inputs: [{ name: 'a', type: 'string' }, { name: 'b', type: 'int' }], + outputs: [] +}, { + name: 'myEvent', + type: 'event', + inputs: [{name: 'a', type: 'int', indexed: true},{name: 'b', type: 'bool', indexed: false] +}]; + +// creation of contract object +var MyContract = web3.eth.contract(abi); + +// initiate contract for an address +var myContractInstance = MyContract.at('0xc4abd0339eb8d57087278718986382264244252f'); + +// call constant function +var result = myContractInstance.myConstantMethod('myParam'); +console.log(result) // '0x25434534534' + +// send a transaction to a function +myContractInstance.myStateChangingMethod('someParam1', 23, {value: 200, gas: 2000}); + +// short hand style +web3.eth.contract(abi).at(address).myAwesomeMethod(...); + +// create filter +var filter = myContractInstance.myEvent({a: 5}, function (error, result) { + if (!error) + console.log(result); + /* + { + address: '0x8718986382264244252fc4abd0339eb8d5708727', + topics: "0x12345678901234567890123456789012", "0x0000000000000000000000000000000000000000000000000000000000000005", + data: "0x0000000000000000000000000000000000000000000000000000000000000001", + ... + } + */ +}); +``` + +*** + +#### Contract Methods + +```js +// Automatically determines the use of call or sendTransaction based on the method type +myContractInstance.myMethod(param1 [, param2, ...] [, transactionObject] [, callback]); + +// Explicitly calling this method +myContractInstance.myMethod.call(param1 [, param2, ...] [, transactionObject] [, callback]); + +// Explicitly sending a transaction to this method +myContractInstance.myMethod.sendTransaction(param1 [, param2, ...] [, transactionObject] [, callback]); + +// Explicitly sending a transaction to this method +myContractInstance.myMethod.sendTransaction(param1 [, param2, ...] [, transactionObject] [, callback]); + +// Get the call data, so you can call the contract through some other means +var myCallData = myContractInstance.myMethod.getData(param1 [, param2, ...]); +// myCallData = '0x45ff3ff6000000000004545345345345..' +``` + +The contract object exposes the contracts methods, which can be called using parameters and a transaction object. + +##### Parameters + +- `String|Number` - (optional) Zero or more parameters of the function. +- `Object` - (optional) The (previous) last parameter can be a transaction object, see [web3.eth.sendTransaction](#web3ethsendtransaction) parameter 1 for more. +- `Function` - (optional) If you pass a callback as the last parameter the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`String` - If its a call the result data, if its a send transaction a created contract address, or the transaction hash, see [web3.eth.sendTransaction](#web3ethsendtransaction) for details. + + +##### Example + +```js +// creation of contract object +var MyContract = web3.eth.contract(abi); + +// initiate contract for an address +var myContractInstance = MyContract.at('0x78e97bcc5b5dd9ed228fed7a4887c0d7287344a9'); + +var result = myContractInstance.myConstantMethod('myParam'); +console.log(result) // '0x25434534534' + +myContractInstance.myStateChangingMethod('someParam1', 23, {value: 200, gas: 2000}, function(err, result){ ... }); +``` + +*** + + +#### Contract Events + +```js +var event = myContractInstance.MyEvent({valueA: 23} [, additionalFilterObject]) + +// watch for changes +event.watch(function(error, result){ + if (!error) + console.log(result); +}); + +// Or pass a callback to start watching immediately +var event = myContractInstance.MyEvent([{valueA: 23}] [, additionalFilterObject] , function(error, result){ + if (!error) + console.log(result); +}); + +``` + +You can use events like [filters](#web3ethfilter) and they have the same methods, but you pass different objects to create the event filter. + +##### Parameters + +1. `Object` - Indexed return values you want to filter the logs by, e.g. `{'valueA': 1, 'valueB': [myFirstAddress, mySecondAddress]}`. By default all filter values are set to `null`. It means, that they will match any event of given type sent from this contract. +2. `Object` - Additional filter options, see [filters](#web3ethfilter) parameter 1 for more. By default filterObject has field 'address' set to address of the contract. Also first topic is the signature of event. +3. `Function` - (optional) If you pass a callback as the last parameter it will immediately start watching and you don't need to call `myEvent.watch(function(){})`. See [this note](#using-callbacks) for details. + +##### Callback return + + +`Object` - An event object as follows: + +- `args`: `Object` - The arguments coming from the event. +- `event`: `String` - The event name. +- `logIndex`: `Number` - integer of the log index position in the block. +- `transactionIndex`: `Number` - integer of the transactions index position log was created from. +- `transactionHash`: `String`, 32 Bytes - hash of the transactions this log was created from. +- `address`: `String`, 32 Bytes - address from which this log originated. +- `blockHash`: `String`, 32 Bytes - hash of the block where this log was in. `null` when its pending. +- `blockNumber`: `Number` - the block number where this log was in. `null` when its pending. + + +##### Example + +```js +var MyContract = web3.eth.contract(abi); +var myContractInstance = MyContract.at('0x78e97bcc5b5dd9ed228fed7a4887c0d7287344a9'); + +// watch for an event with {some: 'args'} +var myEvent = myContractInstance.MyEvent({some: 'args'}, {fromBlock: 0, toBlock: 'latest'}); +myEvent.watch(function(error, result){ + ... +}); + +// would get all past logs again. +var myResults = myEvent.get(function(error, logs){ ... }); + +... + +// would stop and uninstall the filter +myEvent.stopWatching(); +``` + +*** + +#### Contract allEvents + +```js +var events = myContractInstance.allEvents([additionalFilterObject]); + +// watch for changes +events.watch(function(error, event){ + if (!error) + console.log(event); +}); + +// Or pass a callback to start watching immediately +var events = myContractInstance.allEvents([additionalFilterObject,] function(error, log){ + if (!error) + console.log(log); +}); + +``` + +Will call the callback for all events which are created by this contract. + +##### Parameters + +1. `Object` - Additional filter options, see [filters](#web3ethfilter) parameter 1 for more. By default filterObject has field 'address' set to address of the contract. Also first topic is the signature of event. +2. `Function` - (optional) If you pass a callback as the last parameter it will immediately start watching and you don't need to call `myEvent.watch(function(){})`. See [this note](#using-callbacks) for details. + +##### Callback return + + +`Object` - See [Contract Events](#contract-events) for more. + +##### Example + +```js +var MyContract = web3.eth.contract(abi); +var myContractInstance = MyContract.at('0x78e97bcc5b5dd9ed228fed7a4887c0d7287344a9'); + +// watch for an event with {some: 'args'} +var events = myContractInstance.allEvents({fromBlock: 0, toBlock: 'latest'}); +events.watch(function(error, result){ + ... +}); + +// would get all past logs again. +events.get(function(error, logs){ ... }); + +... + +// would stop and uninstall the filter +myEvent.stopWatching(); +``` + +**** + +#### web3.eth.getCompilers + + web3.eth.getCompilers([callback]) + +Gets a list of available compilers. + +##### Parameters + +1. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`Array` - An array of strings of available compilers. + +##### Example + +```js +var number = web3.eth.getCompilers(); +console.log(number); // ["lll", "solidity", "serpent"] +``` + +*** + +#### web3.eth.compile.solidity + + web3.eth.compile.solidity(sourceString [, callback]) + +Compiles solidity source code. + +##### Parameters + +1. `String` - The solidity source code. +2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`Object` - Contract and compiler info. + + +##### Example + +```js +var source = "" + + "contract test {\n" + + " function multiply(uint a) returns(uint d) {\n" + + " return a * 7;\n" + + " }\n" + + "}\n"; +var compiled = web3.eth.compile.solidity(source); +console.log(compiled); +// { + "test": { + "code": "0x605280600c6000396000f3006000357c010000000000000000000000000000000000000000000000000000000090048063c6888fa114602e57005b60376004356041565b8060005260206000f35b6000600782029050604d565b91905056", + "info": { + "source": "contract test {\n\tfunction multiply(uint a) returns(uint d) {\n\t\treturn a * 7;\n\t}\n}\n", + "language": "Solidity", + "languageVersion": "0", + "compilerVersion": "0.8.2", + "abiDefinition": [ + { + "constant": false, + "inputs": [ + { + "name": "a", + "type": "uint256" + } + ], + "name": "multiply", + "outputs": [ + { + "name": "d", + "type": "uint256" + } + ], + "type": "function" + } + ], + "userDoc": { + "methods": {} + }, + "developerDoc": { + "methods": {} + } + } + } +} +``` + +*** + +#### web3.eth.compile.lll + + web3. eth.compile.lll(sourceString [, callback]) + +Compiles LLL source code. + +##### Parameters + +1. `String` - The LLL source code. +2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`String` - The compiled LLL code as HEX string. + + +##### Example + +```js +var source = "..."; + +var code = web3.eth.compile.lll(source); +console.log(code); // "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056" +``` + +*** + +#### web3.eth.compile.serpent + + web3.eth.compile.serpent(sourceString [, callback]) + +Compiles serpent source code. + +##### Parameters + +1. `String` - The serpent source code. +2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`String` - The compiled serpent code as HEX string. + + +```js +var source = "..."; + +var code = web3.eth.compile.serpent(source); +console.log(code); // "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056" +``` + +*** + +#### web3.eth.namereg + + web3.eth.namereg + +Returns GlobalRegistrar object. + +##### Usage + +see [namereg](https://github.com/ethereum/web3.js/blob/master/example/namereg.html) example + +*** + +### web3.db + +#### web3.db.putString + + web3.db.putString(db, key, value) + +This method should be called, when we want to store a string in the local leveldb database. + +##### Parameters + +1. `String` - The database to store to. +2. `String` - The name of the store. +3. `String` - The string value to store. + +##### Returns + +`Boolean` - `true` if successfull, otherwise `false`. + +##### Example + + param is db name, second is the key, and third is the string value. +```js +web3.db.putString('testDB', 'key', 'myString') // true +``` + +*** + +#### web3.db.getString + + web3.db.getString(db, key) + +This method should be called, when we want to get string from the local leveldb database. + +##### Parameters + +1. `String` - The database string name to retrieve from. +2. `String` - The name of the store. + +##### Returns + +`String` - The stored value. + +##### Example + param is db name and second is the key of string value. +```js +var value = web3.db.getString('testDB', 'key'); +console.log(value); // "myString" +``` + +*** + +#### web3.db.putHex + + web3.db.putHex(db, key, value) + +This method should be called, when we want to store binary data in HEX form in the local leveldb database. + +##### Parameters + +1. `String` - The database to store to. +2. `String` - The name of the store. +3. `String` - The HEX string to store. + +##### Returns + +`Boolean` - `true` if successfull, otherwise `false`. + +##### Example +```js +web3.db.putHex('testDB', 'key', '0x4f554b443'); // true + +``` + +*** + +#### web3.db.getHex + + web3.db.getHex(db, key) + +This method should be called, when we want to get a binary data in HEX form from the local leveldb database. + +##### Parameters + +1. `String` - The database to store to. +2. `String` - The name of the store. + +##### Returns + +`String` - The stored HEX value. + + +##### Example + param is db name and second is the key of value. +```js +var value = web3.db.getHex('testDB', 'key'); +console.log(value); // "0x4f554b443" +``` + +*** + +### web3.shh + +[Whisper Overview](/concepts/whisper/whisper-overview.md) + +##### Example + +```js +var shh = web3.shh; +``` + +*** + +#### web3.shh.post + + web3.shh.post(object [, callback]) + +This method should be called, when we want to post whisper message to the network. + +##### Parameters + +1. `Object` - The post object: + - `from`: `String`, 60 Bytes HEX - (optional) The identity of the sender. + - `to`: `String`, 60 Bytes HEX - (optional) The identity of the receiver. When present whisper will encrypt the message so that only the receiver can decrypt it. + - `topics`: `Array of Strings` - Array of topics `Strings`, for the receiver to identify messages. + - `payload`: `String|Number|Object` - The payload of the message. Will be autoconverted to a HEX string before. + - `priority`: `Number` - The integer of the priority in a rang from ... (?). + - `ttl`: `Number` - integer of the time to live in seconds. +2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`Boolean` - returns `true` if the message was send, otherwise `false`. + + +##### Example + +```js +var identity = web3.shh.newIdentity(); +var topic = 'example'; +var payload = 'hello whisper world!'; + +var message = { + from: identity, + topics: [topic], + payload: payload, + ttl: 100, + workToProve: 100 // or priority TODO +}; + +web3.shh.post(message); +``` + +*** + +#### web3.shh.newIdentity + + web3.shh.newIdentity([callback]) + +Should be called to create new identity. + +##### Parameters + +1. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + + +##### Returns + +`String` - A new identity HEX string. + + +##### Example + +```js +var identity = web3.shh.newIdentity(); +console.log(identity); // "0xc931d93e97ab07fe42d923478ba2465f283f440fd6cabea4dd7a2c807108f651b7135d1d6ca9007d5b68aa497e4619ac10aa3b27726e1863c1fd9b570d99bbaf" +``` + +*** + +#### web3.shh.hasIdentity + + web3.shh.hasIdentity(identity, [callback]) + +Should be called, if we want to check if user has given identity. + +##### Parameters + +1. `String` - The identity to check. +2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Returns + +`Boolean` - returns `true` if the identity exists, otherwise `false`. + + +##### Example + +```js +var identity = web3.shh.newIdentity(); +var result = web3.shh.hasIdentity(identity); +console.log(result); // true + +var result2 = web3.shh.hasIdentity(identity + "0"); +console.log(result2); // false +``` + +*** + +#### web3.shh.newGroup + +##### Example +```js +// TODO: not implemented yet +``` + +*** + +#### web3.shh.addToGroup + +##### Example +```js +// TODO: not implemented yet +``` + +*** + +#### web3.shh.filter + +```js +var filter = web3.shh.filter(options) + +// watch for changes +filter.watch(function(error, result){ + if (!error) + console.log(result); +}); +``` + +Watch for incoming whisper messages. + +##### Parameters + +1. `Object` - The filter options: + * `topics`: `Array of Strings` - Filters messages by this topic(s). You can use the following combinations: + - `['topic1', 'topic2'] == 'topic1' && 'topic2'` + - `['topic1', ['topic2', 'topic3']] == 'topic1' && ('topic2' || 'topic3')` + - `[null, 'topic1', 'topic2'] == ANYTHING && 'topic1' && 'topic2'` -> `null` works as a wildcard + * `to`: Filter by identity of receiver of the message. If provided and the node has this identity, it will decrypt incoming encrypted messages. +2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous. See [this note](#using-callbacks) for details. + +##### Callback return + +`Object` - The incoming message: + + - `from`: `String`, 60 Bytes - The sender of the message, if a sender was specified. + - `to`: `String`, 60 Bytes - The receiver of the message, if a receiver was specified. + - `expiry`: `Number` - Integer of the time in seconds when this message should expire (?). + - `ttl`: `Number` - Integer of the time the message should float in the system in seconds (?). + - `sent`: `Number` - Integer of the unix timestamp when the message was sent. + - `topics`: `Array of String` - Array of `String` topics the message contained. + - `payload`: `String` - The payload of the message. + - `workProved`: `Number` - Integer of the work this message required before it was send (?). + +*** + +#### web3.eth.sendIBANTransaction + +```js +var txHash = web3.eth.sendIBANTransaction('0x00c5496aee77c1ba1f0854206a26dda82a81d6d8', 'XE81ETHXREGGAVOFYORK', 0x100); +``` + +Sends IBAN transaction from user account to destination IBAN address. + +##### Parameters + +- `string` - address from which we want to send transaction +- `string` - IBAN address to which we want to send transaction +- `value` - value that we want to send in IBAN transaction + +*** + +#### web3.eth.iban + +```js +var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); +``` + +*** + +#### web3.eth.iban.fromAddress + +```js +var i = web3.eth.iban.fromAddress('0x00c5496aee77c1ba1f0854206a26dda82a81d6d8'); +console.log(i.toString()); // 'XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS +``` + +*** + +#### web3.eth.iban.fromBban + +```js +var i = web3.eth.iban.fromBban('ETHXREGGAVOFYORK'); +console.log(i.toString()); // "XE81ETHXREGGAVOFYORK" +``` + +*** + +#### web3.eth.iban.createIndirect + +```js +var i = web3.eth.iban.createIndirect({ + institution: "XREG", + identifier: "GAVOFYORK" +}); +console.log(i.toString()); // "XE81ETHXREGGAVOFYORK" +``` + +*** + +#### web3.eth.iban.isValid + +```js +var valid = web3.eth.iban.isValid("XE81ETHXREGGAVOFYORK"); +console.log(valid); // true + +var valid2 = web3.eth.iban.isValid("XE82ETHXREGGAVOFYORK"); +console.log(valid2); // false, cause checksum is incorrect + +var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); +var valid3 = i.isValid(); +console.log(valid3); // true + +``` + +*** + +#### web3.eth.iban.isDirect + +```js +var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); +var direct = i.isDirect(); +console.log(direct); // false +``` + +*** + +#### web3.eth.iban.isIndirect + +```js +var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); +var indirect = i.isIndirect(); +console.log(indirect); // true +``` + +*** + +#### web3.eth.iban.checksum + +```js +var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); +var checksum = i.checksum(); +console.log(checksum); // "81" +``` + +*** + +#### web3.eth.iban.institution + +```js +var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); +var institution = i.institution(); +console.log(institution); // 'XREG' +``` + +*** + +#### web3.eth.iban.client + +```js +var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); +var client = i.client(); +console.log(client); // 'GAVOFYORK' +``` + +*** + +#### web3.eth.iban.address + +```js +var i = new web3.eth.iban('XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS'); +var address = i.address(); +console.log(address); // '00c5496aee77c1ba1f0854206a26dda82a81d6d8' +``` + +*** + +#### web3.eth.iban.toString + +```js +var i = new web3.eth.iban('XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS'); +console.log(i.toString()); // 'XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS' +``` diff --git a/archive/poll-for-token-proposal-EIP-20.md b/archive/poll-for-token-proposal-EIP-20.md index 8e87b29..9dbef80 100644 --- a/archive/poll-for-token-proposal-EIP-20.md +++ b/archive/poll-for-token-proposal-EIP-20.md @@ -1,6 +1,6 @@ --- -title: Untitled Page -description: +title: Poll for token proposal EIP 20 +description: It's here for historical record published: true date: 2020-06-16T10:13:47.004Z tags: diff --git a/archive/proposal-reversion-notification.md b/archive/proposal-reversion-notification.md index 0de6893..2b87c5c 100644 --- a/archive/proposal-reversion-notification.md +++ b/archive/proposal-reversion-notification.md @@ -1,5 +1,5 @@ --- -title: Proposal: Reversion Notification +title: Proposal:Reversion Notification description: published: true date: 2020-06-16T10:03:36.567Z diff --git a/archive/proposal-transaction-proxy-hooks.md b/archive/proposal-transaction-proxy-hooks.md index 674e407..ecf7b06 100644 --- a/archive/proposal-transaction-proxy-hooks.md +++ b/archive/proposal-transaction-proxy-hooks.md @@ -1,5 +1,5 @@ --- -title: Proposal: Transaction Proxy Hooks +title: Proposal:Transaction Proxy Hooks description: published: true date: 2020-06-16T09:59:45.204Z diff --git a/archive/serpent.md b/archive/serpent.md index 429a9b5..8c4968c 100644 --- a/archive/serpent.md +++ b/archive/serpent.md @@ -14,7 +14,7 @@ tags: Serpent is one of the high-level programming languages used to write Ethereum contracts. The language, as suggested by its name, is designed to be very similar to Python; it is intended to be maximally clean and simple, combining many of the efficiency benefits of a low-level language with ease-of-use in programming style, and at the same time adding special domain-specific features for contract programming. The latest version of the Serpent compiler, available [on github](http://github.com/ethereum/serpent), is written in C++, allowing it to be easily included in any client. -This tutorial assumes basic knowledge of how Ethereum works, including the concept of blocks, transactions, contracts and messages and the fact that contracts take a byte array as input and provide a byte array as output. If you do not, then go [here](https://github.com/ethereum/wiki/wiki/Ethereum-Development-Tutorial) for a basic tutorial. +This tutorial assumes basic knowledge of how Ethereum works, including the concept of blocks, transactions, contracts and messages and the fact that contracts take a byte array as input and provide a byte array as output. If you do not, then go [here](/howto/ethereum-development-tutorial.md) for a basic tutorial. This documentation is not complete and these examples may further help: diff --git a/archive/white-paper.md b/archive/white-paper.md new file mode 100644 index 0000000..bd6ce5f --- /dev/null +++ b/archive/white-paper.md @@ -0,0 +1,500 @@ +---gg +name: White Paper +category: Basics +--- + +### A Next-Generation Smart Contract and Decentralized Application Platform + +Satoshi Nakamoto's development of Bitcoin in 2009 has often been hailed as a radical development in money and currency, being the first example of a digital asset which simultaneously has no backing or "[intrinsic value](http://bitcoinmagazine.com/8640/an-exploration-of-intrinsic-value-what-it-is-why-bitcoin-doesnt-have-it-and-why-bitcoin-does-have-it/)" and no centralized issuer or controller. However, another, arguably more important, part of the Bitcoin experiment is the underlying blockchain technology as a tool of distributed consensus, and attention is rapidly starting to shift to this other aspect of Bitcoin. Commonly cited alternative applications of blockchain technology include using on-blockchain digital assets to represent custom currencies and financial instruments (["colored coins"](https://docs.google.com/a/buterin.com/document/d/1AnkP_cVZTCMLIzw4DvsW6M8Q2JC0lIzrTLuoWu2z1BE/edit)), the ownership of an underlying physical device (["smart property"](https://en.bitcoin.it/wiki/Smart_Property)), non-fungible assets such as domain names (["Namecoin"](http://namecoin.org)), as well as more complex applications involving having digital assets being directly controlled by a piece of code implementing arbitrary rules (["smart contracts"](http://szabo.best.vwh.net/smart_contracts_idea.html)) or even blockchain-based "[decentralized autonomous organizations](http://bitcoinmagazine.com/7050/bootstrapping-a-decentralized-autonomous-corporation-part-i/)" (DAOs). What Ethereum intends to provide is a blockchain with a built-in fully fledged Turing-complete programming language that can be used to create "contracts" that can be used to encode arbitrary state transition functions, allowing users to create any of the systems described above, as well as many others that we have not yet imagined, simply by writing up the logic in a few lines of code. + +### Table of Contents + +* [History](#history) + * [Bitcoin As A State Transition System](#bitcoin-as-a-state-transition-system) + * [Mining](#mining) + * [Merkle Trees](#merkle-trees) + * [Alternative Blockchain Applications](#alternative-blockchain-applications) + * [Scripting](#scripting) +* [Ethereum](#ethereum) + * [Ethereum Accounts](#ethereum-accounts) + * [Messages and Transactions](#messages-and-transactions) + * [Ethereum State Transition Function](#ethereum-state-transition-function) + * [Code Execution](#code-execution) + * [Blockchain and Mining](#blockchain-and-mining) +* [Applications](#applications) + * [Token Systems](#token-systems) + * [Financial derivatives](#financial-derivatives-and-stable-value-currencies) + * [Identity and Reputation Systems](#identity-and-reputation-systems) + * [Decentralized File Storage](#decentralized-file-storage) + * [Decentralized Autonomous Organizations](#decentralized-autonomous-organizations) + * [Further Applications](#further-applications) +* [Miscellanea And Concerns](#miscellanea-and-concerns) + * [Modified GHOST Implementation](#modified-ghost-implementation) + * [Fees](#fees) + * [Computation And Turing-Completeness](#computation-and-turing-completeness) + * [Currency And Issuance](#currency-and-issuance) + * [Mining Centralization](#mining-centralization) + * [Scalability](#scalability) +* [Conclusion](#conclusion) +* [References and Further Reading](#references-and-further-reading) + +## Introduction to Bitcoin and Existing Concepts + +### History + +The concept of decentralized digital currency, as well as alternative applications like property registries, has been around for decades. The anonymous e-cash protocols of the 1980s and the 1990s, mostly reliant on a cryptographic primitive known as Chaumian blinding, provided a currency with a high degree of privacy, but the protocols largely failed to gain traction because of their reliance on a centralized intermediary. In 1998, Wei Dai's [b-money](http://www.weidai.com/bmoney.txt) became the first proposal to introduce the idea of creating money through solving computational puzzles as well as decentralized consensus, but the proposal was scant on details as to how decentralized consensus could actually be implemented. In 2005, Hal Finney introduced a concept of "[reusable proofs of work](http://www.finney.org/~hal/rpow/)", a system which uses ideas from b-money together with Adam Back's computationally difficult Hashcash puzzles to create a concept for a cryptocurrency, but once again fell short of the ideal by relying on trusted computing as a backend. In 2009, a decentralized currency was for the first time implemented in practice by Satoshi Nakamoto, combining established primitives for managing ownership through public key cryptography with a consensus algorithm for keeping track of who owns coins, known as "proof of work". + +The mechanism behind proof of work was a breakthrough in the space because it simultaneously solved two problems. First, it provided a simple and moderately effective consensus algorithm, allowing nodes in the network to collectively agree on a set of canonical updates to the state of the Bitcoin ledger. Second, it provided a mechanism for allowing free entry into the consensus process, solving the political problem of deciding who gets to influence the consensus, while simultaneously preventing sybil attacks. It does this by substituting a formal barrier to participation, such as the requirement to be registered as a unique entity on a particular list, with an economic barrier - the weight of a single node in the consensus voting process is directly proportional to the computing power that the node brings. Since then, an alternative approach has been proposed called _proof of stake_, calculating the weight of a node as being proportional to its currency holdings and not computational resources; the discussion of the relative merits of the two approaches is beyond the scope of this paper but it should be noted that both approaches can be used to serve as the backbone of a cryptocurrency. + +### Bitcoin As A State Transition System + +![statetransition.png](https://raw.githubusercontent.com/vbuterin/diagrams/master/statetransition.png) + +From a technical standpoint, the ledger of a cryptocurrency such as Bitcoin can be thought of as a state transition system, where there is a "state" consisting of the ownership status of all existing bitcoins and a "state transition function" that takes a state and a transaction and outputs a new state which is the result. In a standard banking system, for example, the state is a balance sheet, a transaction is a request to move $X from A to B, and the state transition function reduces the value in A's account by $X and increases the value in B's account by $X. If A's account has less than $X in the first place, the state transition function returns an error. Hence, one can formally define: + + APPLY(S,TX) -> S' or ERROR + +In the banking system defined above: + + APPLY({ Alice: $50, Bob: $50 },"send $20 from Alice to Bob") = { Alice: $30, Bob: $70 } + +But: + + APPLY({ Alice: $50, Bob: $50 },"send $70 from Alice to Bob") = ERROR + +The "state" in Bitcoin is the collection of all coins (technically, "unspent transaction outputs" or UTXO) that have been minted and not yet spent, with each UTXO having a denomination and an owner (defined by a 20-byte address which is essentially a cryptographic public key[1]). A transaction contains one or more inputs, with each input containing a reference to an existing UTXO and a cryptographic signature produced by the private key associated with the owner's address, and one or more outputs, with each output containing a new UTXO to be added to the state. + +The state transition function `APPLY(S,TX) -> S'` can be defined roughly as follows: + +1. For each input in `TX`: + * If the referenced UTXO is not in `S`, return an error. + * If the provided signature does not match the owner of the UTXO, return an error. +2. If the sum of the denominations of all input UTXO is less than the sum of the denominations of all output UTXO, return an error. +3. Return `S` with all input UTXO removed and all output UTXO added. + +The first half of the first step prevents transaction senders from spending coins that do not exist, the second half of the first step prevents transaction senders from spending other people's coins, and the second step enforces conservation of value. In order to use this for payment, the protocol is as follows. Suppose Alice wants to send 11.7 BTC to Bob. First, Alice will look for a set of available UTXO that she owns that totals up to at least 11.7 BTC. Realistically, Alice will not be able to get exactly 11.7 BTC; say that the smallest she can get is 6+4+2=12. She then creates a transaction with those three inputs and two outputs. The first output will be 11.7 BTC with Bob's address as its owner, and the second output will be the remaining 0.3 BTC "change", with the owner being Alice herself. + +### Mining + +![block_picture.jpg](https://raw.githubusercontent.com/vbuterin/diagrams/master/block.png) + +If we had access to a trustworthy centralized service, this system would be trivial to implement; it could simply be coded exactly as described, using a centralized server's hard drive to keep track of the state. However, with Bitcoin we are trying to build a decentralized currency system, so we will need to combine the state transaction system with a consensus system in order to ensure that everyone agrees on the order of transactions. Bitcoin's decentralized consensus process requires nodes in the network to continuously attempt to produce packages of transactions called "blocks". The network is intended to produce roughly one block every ten minutes, with each block containing a timestamp, a nonce, a reference to (ie. hash of) the previous block and a list of all of the transactions that have taken place since the previous block. Over time, this creates a persistent, ever-growing, "blockchain" that constantly updates to represent the latest state of the Bitcoin ledger. + +The algorithm for checking if a block is valid, expressed in this paradigm, is as follows: + +1. Check if the previous block referenced by the block exists and is valid. +2. Check that the timestamp of the block is greater than that of the previous block[2] and less than 2 hours into the future +3. Check that the proof of work on the block is valid. +4. Let `S[0]` be the state at the end of the previous block. +5. Suppose `TX` is the block's transaction list with `n` transactions. For all `i` in `0...n-1`, set `S[i+1] = APPLY(S[i],TX[i])` If any application returns an error, exit and return false. +6. Return true, and register `S[n]` as the state at the end of this block. + +Essentially, each transaction in the block must provide a valid state transition from what was the canonical state before the transaction was executed to some new state. Note that the state is not encoded in the block in any way; it is purely an abstraction to be remembered by the validating node and can only be (securely) computed for any block by starting from the genesis state and sequentially applying every transaction in every block. Additionally, note that the order in which the miner includes transactions into the block matters; if there are two transactions A and B in a block such that B spends a UTXO created by A, then the block will be valid if A comes before B but not otherwise. + +The one validity condition present in the above list that is not found in other systems is the requirement for "proof of work". The precise condition is that the double-SHA256 hash of every block, treated as a 256-bit number, must be less than a dynamically adjusted target, which as of the time of this writing is approximately 2187. The purpose of this is to make block creation computationally "hard", thereby preventing sybil attackers from remaking the entire blockchain in their favor. Because SHA256 is designed to be a completely unpredictable pseudorandom function, the only way to create a valid block is simply trial and error, repeatedly incrementing the nonce and seeing if the new hash matches. + +At the current target of ~2187, the network must make an average of ~269 tries before a valid block is found; in general, the target is recalibrated by the network every 2016 blocks so that on average a new block is produced by some node in the network every ten minutes. In order to compensate miners for this computational work, the miner of every block is entitled to include a transaction giving themselves 25 BTC out of nowhere. Additionally, if any transaction has a higher total denomination in its inputs than in its outputs, the difference also goes to the miner as a "transaction fee". Incidentally, this is also the only mechanism by which BTC are issued; the genesis state contained no coins at all. + +In order to better understand the purpose of mining, let us examine what happens in the event of a malicious attacker. Since Bitcoin's underlying cryptography is known to be secure, the attacker will target the one part of the Bitcoin system that is not protected by cryptography directly: the order of transactions. The attacker's strategy is simple: + +1. Send 100 BTC to a merchant in exchange for some product (preferably a rapid-delivery digital good) +2. Wait for the delivery of the product +3. Produce another transaction sending the same 100 BTC to himself +4. Try to convince the network that his transaction to himself was the one that came first. + +Once step (1) has taken place, after a few minutes some miner will include the transaction in a block, say block number 270000. After about one hour, five more blocks will have been added to the chain after that block, with each of those blocks indirectly pointing to the transaction and thus "confirming" it. At this point, the merchant will accept the payment as finalized and deliver the product; since we are assuming this is a digital good, delivery is instant. Now, the attacker creates another transaction sending the 100 BTC to himself. If the attacker simply releases it into the wild, the transaction will not be processed; miners will attempt to run `APPLY(S,TX)` and notice that `TX` consumes a UTXO which is no longer in the state. So instead, the attacker creates a "fork" of the blockchain, starting by mining another version of block 270000 pointing to the same block 269999 as a parent but with the new transaction in place of the old one. Because the block data is different, this requires redoing the proof of work. Furthermore, the attacker's new version of block 270000 has a different hash, so the original blocks 270001 to 270005 do not "point" to it; thus, the original chain and the attacker's new chain are completely separate. The rule is that in a fork the longest blockchain is taken to be the truth, and so legitimate miners will work on the 270005 chain while the attacker alone is working on the 270000 chain. In order for the attacker to make his blockchain the longest, he would need to have more computational power than the rest of the network combined in order to catch up (hence, "51% attack"). + +### Merkle Trees + +![SPV in bitcoin](https://raw.githubusercontent.com/ethereum/www/master-postsale/src/extras/gh_wiki/spv_bitcoin.png) + +_Left: it suffices to present only a small number of nodes in a Merkle tree to give a proof of the validity of a branch._ + +_Right: any attempt to change any part of the Merkle tree will eventually lead to an inconsistency somewhere up the chain._ + +An important scalability feature of Bitcoin is that the block is stored in a multi-level data structure. The "hash" of a block is actually only the hash of the block header, a roughly 200-byte piece of data that contains the timestamp, nonce, previous block hash and the root hash of a data structure called the Merkle tree storing all transactions in the block. A Merkle tree is a type of binary tree, composed of a set of nodes with a large number of leaf nodes at the bottom of the tree containing the underlying data, a set of intermediate nodes where each node is the hash of its two children, and finally a single root node, also formed from the hash of its two children, representing the "top" of the tree. The purpose of the Merkle tree is to allow the data in a block to be delivered piecemeal: a node can download only the header of a block from one source, the small part of the tree relevant to them from another source, and still be assured that all of the data is correct. The reason why this works is that hashes propagate upward: if a malicious user attempts to swap in a fake transaction into the bottom of a Merkle tree, this change will cause a change in the node above, and then a change in the node above that, finally changing the root of the tree and therefore the hash of the block, causing the protocol to register it as a completely different block (almost certainly with an invalid proof of work). + +The Merkle tree protocol is arguably essential to long-term sustainability. A "full node" in the Bitcoin network, one that stores and processes the entirety of every block, takes up about 15 GB of disk space in the Bitcoin network as of April 2014, and is growing by over a gigabyte per month. Currently, this is viable for some desktop computers and not phones, and later on in the future only businesses and hobbyists will be able to participate. A protocol known as "simplified payment verification" (SPV) allows for another class of nodes to exist, called "light nodes", which download the block headers, verify the proof of work on the block headers, and then download only the "branches" associated with transactions that are relevant to them. This allows light nodes to determine with a strong guarantee of security what the status of any Bitcoin transaction, and their current balance, is while downloading only a very small portion of the entire blockchain. + +### Alternative Blockchain Applications + +The idea of taking the underlying blockchain idea and applying it to other concepts also has a long history. In 2005, Nick Szabo came out with the concept of "[secure property titles with owner authority](http://szabo.best.vwh.net/securetitle.html)", a document describing how "new advances in replicated database technology" will allow for a blockchain-based system for storing a registry of who owns what land, creating an elaborate framework including concepts such as homesteading, adverse possession and Georgian land tax. However, there was unfortunately no effective replicated database system available at the time, and so the protocol was never implemented in practice. After 2009, however, once Bitcoin's decentralized consensus was developed a number of alternative applications rapidly began to emerge. + +* **Namecoin** - created in 2010, [Namecoin](https://namecoin.org/) is best described as a decentralized name registration database. In decentralized protocols like Tor, Bitcoin and BitMessage, there needs to be some way of identifying accounts so that other people can interact with them, but in all existing solutions the only kind of identifier available is a pseudorandom hash like `1LW79wp5ZBqaHW1jL5TCiBCrhQYtHagUWy`. Ideally, one would like to be able to have an account with a name like "george". However, the problem is that if one person can create an account named "george" then someone else can use the same process to register "george" for themselves as well and impersonate them. The only solution is a first-to-file paradigm, where the first registerer succeeds and the second fails - a problem perfectly suited for the Bitcoin consensus protocol. Namecoin is the oldest, and most successful, implementation of a name registration system using such an idea. +* **Colored coins** - the purpose of [colored coins](https://docs.google.com/a/buterin.com/document/d/1AnkP_cVZTCMLIzw4DvsW6M8Q2JC0lIzrTLuoWu2z1BE/edit) is to serve as a protocol to allow people to create their own digital currencies - or, in the important trivial case of a currency with one unit, digital tokens, on the Bitcoin blockchain. In the colored coins protocol, one "issues" a new currency by publicly assigning a color to a specific Bitcoin UTXO, and the protocol recursively defines the color of other UTXO to be the same as the color of the inputs that the transaction creating them spent (some special rules apply in the case of mixed-color inputs). This allows users to maintain wallets containing only UTXO of a specific color and send them around much like regular bitcoins, backtracking through the blockchain to determine the color of any UTXO that they receive. +* **Metacoins** - the idea behind a metacoin is to have a protocol that lives on top of Bitcoin, using Bitcoin transactions to store metacoin transactions but having a different state transition function, `APPLY'`. Because the metacoin protocol cannot prevent invalid metacoin transactions from appearing in the Bitcoin blockchain, a rule is added that if `APPLY'(S,TX)` returns an error, the protocol defaults to `APPLY'(S,TX) = S`. This provides an easy mechanism for creating an arbitrary cryptocurrency protocol, potentially with advanced features that cannot be implemented inside of Bitcoin itself, but with a very low development cost since the complexities of mining and networking are already handled by the Bitcoin protocol. Metacoins have been used to implement some classes of financial contracts, name registration and decentralized exchange. + +Thus, in general, there are two approaches toward building a consensus protocol: building an independent network, and building a protocol on top of Bitcoin. The former approach, while reasonably successful in the case of applications like Namecoin, is difficult to implement; each individual implementation needs to bootstrap an independent blockchain, as well as building and testing all of the necessary state transition and networking code. Additionally, we predict that the set of applications for decentralized consensus technology will follow a power law distribution where the vast majority of applications would be too small to warrant their own blockchain, and we note that there exist large classes of decentralized applications, particularly decentralized autonomous organizations, that need to interact with each other. + +The Bitcoin-based approach, on the other hand, has the flaw that it does not inherit the simplified payment verification features of Bitcoin. SPV works for Bitcoin because it can use blockchain depth as a proxy for validity; at some point, once the ancestors of a transaction go far enough back, it is safe to say that they were legitimately part of the state. Blockchain-based meta-protocols, on the other hand, cannot force the blockchain not to include transactions that are not valid within the context of their own protocols. Hence, a fully secure SPV meta-protocol implementation would need to backward scan all the way to the beginning of the Bitcoin blockchain to determine whether or not certain transactions are valid. Currently, all "light" implementations of Bitcoin-based meta-protocols rely on a trusted server to provide the data, arguably a highly suboptimal result especially when one of the primary purposes of a cryptocurrency is to eliminate the need for trust. + +### Scripting + +Even without any extensions, the Bitcoin protocol actually does facilitate a weak version of a concept of "smart contracts". UTXO in Bitcoin can be owned not just by a public key, but also by a more complicated script expressed in a simple stack-based programming language. In this paradigm, a transaction spending that UTXO must provide data that satisfies the script. Indeed, even the basic public key ownership mechanism is implemented via a script: the script takes an elliptic curve signature as input, verifies it against the transaction and the address that owns the UTXO, and returns 1 if the verification is successful and 0 otherwise. Other, more complicated, scripts exist for various additional use cases. For example, one can construct a script that requires signatures from two out of a given three private keys to validate ("multisig"), a setup useful for corporate accounts, secure savings accounts and some merchant escrow situations. Scripts can also be used to pay bounties for solutions to computational problems, and one can even construct a script that says something like "this Bitcoin UTXO is yours if you can provide an SPV proof that you sent a Dogecoin transaction of this denomination to me", essentially allowing decentralized cross-cryptocurrency exchange. + +However, the scripting language as implemented in Bitcoin has several important limitations: + +* **Lack of Turing-completeness** - that is to say, while there is a large subset of computation that the Bitcoin scripting language supports, it does not nearly support everything. The main category that is missing is loops. This is done to avoid infinite loops during transaction verification; theoretically it is a surmountable obstacle for script programmers, since any loop can be simulated by simply repeating the underlying code many times with an if statement, but it does lead to scripts that are very space-inefficient. For example, implementing an alternative elliptic curve signature algorithm would likely require 256 repeated multiplication rounds all individually included in the code. +* **Value-blindness** - there is no way for a UTXO script to provide fine-grained control over the amount that can be withdrawn. For example, one powerful use case of an oracle contract would be a hedging contract, where A and B put in $1000 worth of BTC and after 30 days the script sends $1000 worth of BTC to A and the rest to B. This would require an oracle to determine the value of 1 BTC in USD, but even then it is a massive improvement in terms of trust and infrastructure requirement over the fully centralized solutions that are available now. However, because UTXO are all-or-nothing, the only way to achieve this is through the very inefficient hack of having many UTXO of varying denominations (eg. one UTXO of 2k for every k up to 30) and having the oracle pick which UTXO to send to A and which to B. +* **Lack of state** - UTXO can either be spent or unspent; there is no opportunity for multi-stage contracts or scripts which keep any other internal state beyond that. This makes it hard to make multi-stage options contracts, decentralized exchange offers or two-stage cryptographic commitment protocols (necessary for secure computational bounties). It also means that UTXO can only be used to build simple, one-off contracts and not more complex "stateful" contracts such as decentralized organizations, and makes meta-protocols difficult to implement. Binary state combined with value-blindness also mean that another important application, withdrawal limits, is impossible. +* **Blockchain-blindness** - UTXO are blind to blockchain data such as the nonce, the timestamp and previous block hash. This severely limits applications in gambling, and several other categories, by depriving the scripting language of a potentially valuable source of randomness. + +Thus, we see three approaches to building advanced applications on top of cryptocurrency: building a new blockchain, using scripting on top of Bitcoin, and building a meta-protocol on top of Bitcoin. Building a new blockchain allows for unlimited freedom in building a feature set, but at the cost of development time, bootstrapping effort and security. Using scripting is easy to implement and standardize, but is very limited in its capabilities, and meta-protocols, while easy, suffer from faults in scalability. With Ethereum, we intend to build an alternative framework that provides even larger gains in ease of development as well as even stronger light client properties, while at the same time allowing applications to share an economic environment and blockchain security. + +## Ethereum + +The intent of Ethereum is to create an alternative protocol for building decentralized applications, providing a different set of tradeoffs that we believe will be very useful for a large class of decentralized applications, with particular emphasis on situations where rapid development time, security for small and rarely used applications, and the ability of different applications to very efficiently interact, are important. Ethereum does this by building what is essentially the ultimate abstract foundational layer: a blockchain with a built-in Turing-complete programming language, allowing anyone to write smart contracts and decentralized applications where they can create their own arbitrary rules for ownership, transaction formats and state transition functions. A bare-bones version of Namecoin can be written in two lines of code, and other protocols like currencies and reputation systems can be built in under twenty. Smart contracts, cryptographic "boxes" that contain value and only unlock it if certain conditions are met, can also be built on top of the platform, with vastly more power than that offered by Bitcoin scripting because of the added powers of Turing-completeness, value-awareness, blockchain-awareness and state. + +### Ethereum Accounts + +In Ethereum, the state is made up of objects called "accounts", with each account having a 20-byte address and state transitions being direct transfers of value and information between accounts. An Ethereum account contains four fields: + +* The **nonce**, a counter used to make sure each transaction can only be processed once +* The account's current **ether balance** +* The account's **contract code**, if present +* The account's **storage** (empty by default) + +"Ether" is the main internal crypto-fuel of Ethereum, and is used to pay transaction fees. In general, there are two types of accounts: **externally owned accounts**, controlled by private keys, and **contract accounts**, controlled by their contract code. An externally owned account has no code, and one can send messages from an externally owned account by creating and signing a transaction; in a contract account, every time the contract account receives a message its code activates, allowing it to read and write to internal storage and send other messages or create contracts in turn. + +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. + +### Messages and Transactions + +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. Transactions contain: + +* The recipient of the message +* A signature identifying the sender +* The amount of ether to transfer from the sender to the recipient +* An optional data field +* 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 + +The first three are standard fields expected in any cryptocurrency. The data field has no function by default, but the virtual machine has an opcode using which a contract can access the data; as an example use case, if a contract is functioning as an on-blockchain domain registration service, then it may wish to interpret the data being passed to it as containing two "fields", the first field being a domain to register and the second field being the IP address to register it to. The contract would read these values from the message data and appropriately place them in storage. + +The `STARTGAS` and `GASPRICE` fields are crucial for Ethereum's anti-denial of service model. In order to prevent accidental or hostile infinite loops or other computational wastage in code, each transaction is required to set a limit to how many computational steps of code execution it can use. The fundamental unit of computation is "gas"; usually, a computational step costs 1 gas, but some operations cost higher amounts of gas because they are more computationally expensive, or increase the amount of data that must be stored as part of the state. There is also a fee of 5 gas for every byte in the transaction data. The intent of the fee system is to require an attacker to pay proportionately for every resource that they consume, including computation, bandwidth and storage; hence, any transaction that leads to the network consuming a greater amount of any of these resources must have a gas fee roughly proportional to the increment. + +### Messages + +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. A message contains: + +* The sender of the message (implicit) +* The recipient of the message +* The amount of ether to transfer alongside the message +* An optional data field +* A `STARTGAS` value + +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. + +Note that the gas allowance assigned by a transaction or contract applies to the total gas consumed by that transaction and all sub-executions. For example, if an external actor A sends a transaction to B with 1000 gas, and B consumes 600 gas before sending a message to C, and the internal execution of C consumes 300 gas before returning, then B can spend another 100 gas before running out of gas. + +### Ethereum State Transition Function + +![ethertransition.png](https://raw.githubusercontent.com/vbuterin/diagrams/master/ethertransition.png) + +The Ethereum state transition function, `APPLY(S,TX) -> S'` can be defined as follows: + +1. Check if the transaction is well-formed (ie. has the right number of values), the signature is valid, and the nonce matches the nonce in the sender's account. If not, return an error. +2. Calculate the transaction fee as `STARTGAS * GASPRICE`, and determine the sending address from the signature. Subtract the fee from the sender's account balance and increment the sender's nonce. If there is not enough balance to spend, return an error. +3. Initialize `GAS = STARTGAS`, and take off a certain quantity of gas per byte to pay for the bytes in the transaction. +4. Transfer the transaction value from the sender's account to the receiving account. If the receiving account does not yet exist, create it. If the receiving account is a contract, run the contract's code either to completion or until the execution runs out of gas. +5. If the value transfer failed because the sender did not have enough money, or the code execution ran out of gas, revert all state changes except the payment of the fees, and add the fees to the miner's account. +6. Otherwise, refund the fees for all remaining gas to the sender, and send the fees paid for gas consumed to the miner. + +For example, suppose that the contract's code is: + + if !self.storage[calldataload(0)]: + self.storage[calldataload(0)] = calldataload(32) + +Note that in reality the contract code is written in the low-level EVM code; this example is written in Serpent, one of our high-level languages, for clarity, and can be compiled down to EVM code. Suppose that the contract's storage starts off empty, and a transaction is sent with 10 ether value, 2000 gas, 0.001 ether gasprice, and 64 bytes of data, with bytes 0-31 representing the number `2` and bytes 32-63 representing the string `CHARLIE`. The process for the state transition function in this case is as follows: + +1. Check that the transaction is valid and well formed. +2. Check that the transaction sender has at least 2000 * 0.001 = 2 ether. If it is, then subtract 2 ether from the sender's account. +3. Initialize gas = 2000; assuming the transaction is 170 bytes long and the byte-fee is 5, subtract 850 so that there is 1150 gas left. +3. Subtract 10 more ether from the sender's account, and add it to the contract's account. +4. Run the code. In this case, this is simple: it checks if the contract's storage at index `2` is used, notices that it is not, and so it sets the storage at index `2` to the value `CHARLIE`. Suppose this takes 187 gas, so the remaining amount of gas is 1150 - 187 = 963 +5. Add 963 * 0.001 = 0.963 ether back to the sender's account, and return the resulting state. + +If there was no contract at the receiving end of the transaction, then the total transaction fee would simply be equal to the provided `GASPRICE` multiplied by the length of the transaction in bytes, and the data sent alongside the transaction would be irrelevant. + +Note that messages work equivalently to transactions in terms of reverts: if a message execution runs out of gas, then that message's execution, and all other executions triggered by that execution, revert, but parent executions do not need to revert. This means that it is "safe" for a contract to call another contract, as if A calls B with G gas then A's execution is guaranteed to lose at most G gas. Finally, note that there is an opcode, `CREATE`, that creates a contract; its execution mechanics are generally similar to `CALL`, with the exception that the output of the execution determines the code of a newly created contract. + +### Code Execution + +The code in Ethereum contracts is written in a low-level, stack-based bytecode language, referred to as "Ethereum virtual machine code" or "EVM code". The code consists of a series of bytes, where each byte represents an operation. In general, code execution is an infinite loop that consists of repeatedly carrying out the operation at the current program counter (which begins at zero) and then incrementing the program counter by one, until the end of the code is reached or an error or `STOP` or `RETURN` instruction is detected. The operations have access to three types of space in which to store data: + +* The **stack**, a last-in-first-out container to which values can be pushed and popped +* **Memory**, an infinitely expandable byte array +* The contract's long-term **storage**, a key/value store. Unlike stack and memory, which reset after computation ends, storage persists for the long term. + +The code can also access the value, sender and data of the incoming message, as well as block header data, and the code can also return a byte array of data as an output. + +The formal execution model of EVM code is surprisingly simple. While the Ethereum virtual machine is running, its full computational state can be defined by the tuple `(block_state, transaction, message, code, memory, stack, pc, gas)`, where `block_state` is the global state containing all accounts and includes balances and storage. At the start of every round of execution, the current instruction is found by taking the `pc`th byte of `code` (or 0 if `pc >= len(code)`), and each instruction has its own definition in terms of how it affects the tuple. For example, `ADD` pops two items off the stack and pushes their sum, reduces `gas` by 1 and increments `pc` by 1, and `SSTORE` pushes the top two items off the stack and inserts the second item into the contract's storage at the index specified by the first item. Although there are many ways to optimize Ethereum virtual machine execution via just-in-time compilation, a basic implementation of Ethereum can be done in a few hundred lines of code. + +### Blockchain and Mining + +![apply_block_diagram.png](https://raw.githubusercontent.com/vbuterin/diagrams/master/apply_block_diagram.png) + +The Ethereum blockchain is in many ways similar to the Bitcoin blockchain, although it does have some differences. The main difference between Ethereum and Bitcoin with regard to the blockchain architecture is that, unlike Bitcoin, Ethereum blocks contain a copy of both the transaction list and the most recent state. Aside from that, two other values, the block number and the difficulty, are also stored in the block. The basic block validation algorithm in Ethereum is as follows: + +1. Check if the previous block referenced exists and is valid. +2. Check that the timestamp of the block is greater than that of the referenced previous block and less than 15 minutes into the future +3. Check that the block number, difficulty, transaction root, uncle root and gas limit (various low-level Ethereum-specific concepts) are valid. +4. Check that the proof of work on the block is valid. +5. Let `S[0]` be the state at the end of the previous block. +6. Let `TX` be the block's transaction list, with `n` transactions. For all `i` in `0...n-1`, set `S[i+1] = APPLY(S[i],TX[i])`. If any applications returns an error, or if the total gas consumed in the block up until this point exceeds the `GASLIMIT`, return an error. +7. Let `S_FINAL` be `S[n]`, but adding the block reward paid to the miner. +8. Check if the Merkle tree root of the state `S_FINAL` is equal to the final state root provided in the block header. If it is, the block is valid; otherwise, it is not valid. + +The approach may seem highly inefficient at first glance, because it needs to store the entire state with each block, but in reality efficiency should be comparable to that of Bitcoin. The reason is that the state is stored in the tree structure, and after every block only a small part of the tree needs to be changed. Thus, in general, between two adjacent blocks the vast majority of the tree should be the same, and therefore the data can be stored once and referenced twice using pointers (ie. hashes of subtrees). A special kind of tree known as a "Patricia tree" is used to accomplish this, including a modification to the Merkle tree concept that allows for nodes to be inserted and deleted, and not just changed, efficiently. Additionally, because all of the state information is part of the last block, there is no need to store the entire blockchain history - a strategy which, if it could be applied to Bitcoin, can be calculated to provide 5-20x savings in space. + +A commonly asked question is "where" contract code is executed, in terms of physical hardware. This has a simple answer: the process of executing contract code is part of the definition of the state transition function, which is part of the block validation algorithm, so if a transaction is added into block `B` the code execution spawned by that transaction will be executed by all nodes, now and in the future, that download and validate block `B`. + +## Applications + +In general, there are three types of applications on top of Ethereum. The first category is financial applications, providing users with more powerful ways of managing and entering into contracts using their money. This includes sub-currencies, financial derivatives, hedging contracts, savings wallets, wills, and ultimately even some classes of full-scale employment contracts. The second category is semi-financial applications, where money is involved but there is also a heavy non-monetary side to what is being done; a perfect example is self-enforcing bounties for solutions to computational problems. Finally, there are applications such as online voting and decentralized governance that are not financial at all. + +### Token Systems + +On-blockchain token systems have many applications ranging from sub-currencies representing assets such as USD or gold to company stocks, individual tokens representing smart property, secure unforgeable coupons, and even token systems with no ties to conventional value at all, used as point systems for incentivization. Token systems are surprisingly easy to implement in Ethereum. The key point to understand is that all a currency, or token system, fundamentally is a database with one operation: subtract X units from A and give X units to B, with the proviso that (i) A had at least X units before the transaction and (2) the transaction is approved by A. All that it takes to implement a token system is to implement this logic into a contract. + +The basic code for implementing a token system in Serpent looks as follows: + + def send(to, value): + if self.storage[msg.sender] >= value: + self.storage[msg.sender] = self.storage[msg.sender] - value + self.storage[to] = self.storage[to] + value + +This is essentially a literal implementation of the "banking system" state transition function described further above in this document. A few extra lines of code need to be added to provide for the initial step of distributing the currency units in the first place and a few other edge cases, and ideally a function would be added to let other contracts query for the balance of an address. But that's all there is to it. Theoretically, Ethereum-based token systems acting as sub-currencies can potentially include another important feature that on-chain Bitcoin-based meta-currencies lack: the ability to pay transaction fees directly in that currency. The way this would be implemented is that the contract would maintain an ether balance with which it would refund ether used to pay fees to the sender, and it would refill this balance by collecting the internal currency units that it takes in fees and reselling them in a constant running auction. Users would thus need to "activate" their accounts with ether, but once the ether is there it would be reusable because the contract would refund it each time. + +### Financial derivatives and Stable-Value Currencies + +Financial derivatives are the most common application of a "smart contract", and one of the simplest to implement in code. The main challenge in implementing financial contracts is that the majority of them require reference to an external price ticker; for example, a very desirable application is a smart contract that hedges against the volatility of ether (or another cryptocurrency) with respect to the US dollar, but doing this requires the contract to know what the value of ETH/USD is. The simplest way to do this is through a "data feed" contract maintained by a specific party (eg. NASDAQ) designed so that that party has the ability to update the contract as needed, and providing an interface that allows other contracts to send a message to that contract and get back a response that provides the price. + +Given that critical ingredient, the hedging contract would look as follows: + +1. Wait for party A to input 1000 ether. +2. Wait for party B to input 1000 ether. +3. Record the USD value of 1000 ether, calculated by querying the data feed contract, in storage, say this is $x. +4. After 30 days, allow A or B to "reactivate" the contract in order to send $x worth of ether (calculated by querying the data feed contract again to get the new price) to A and the rest to B. + +Such a contract would have significant potential in crypto-commerce. One of the main problems cited about cryptocurrency is the fact that it's volatile; although many users and merchants may want the security and convenience of dealing with cryptographic assets, they many not wish to face that prospect of losing 23% of the value of their funds in a single day. Up until now, the most commonly proposed solution has been issuer-backed assets; the idea is that an issuer creates a sub-currency in which they have the right to issue and revoke units, and provide one unit of the currency to anyone who provides them (offline) with one unit of a specified underlying asset (eg. gold, USD). The issuer then promises to provide one unit of the underlying asset to anyone who sends back one unit of the crypto-asset. This mechanism allows any non-cryptographic asset to be "uplifted" into a cryptographic asset, provided that the issuer can be trusted. + +In practice, however, issuers are not always trustworthy, and in some cases the banking infrastructure is too weak, or too hostile, for such services to exist. Financial derivatives provide an alternative. Here, instead of a single issuer providing the funds to back up an asset, a decentralized market of speculators, betting that the price of a cryptographic reference asset (eg. ETH) will go up, plays that role. Unlike issuers, speculators have no option to default on their side of the bargain because the hedging contract holds their funds in escrow. Note that this approach is not fully decentralized, because a trusted source is still needed to provide the price ticker, although arguably even still this is a massive improvement in terms of reducing infrastructure requirements (unlike being an issuer, issuing a price feed requires no licenses and can likely be categorized as free speech) and reducing the potential for fraud. + +### Identity and Reputation Systems + +The earliest alternative cryptocurrency of all, [Namecoin](http://namecoin.org/), attempted to use a Bitcoin-like blockchain to provide a name registration system, where users can register their names in a public database alongside other data. The major cited use case is for a [DNS](http://en.wikipedia.org/wiki/Domain_Name_System) system, mapping domain names like "bitcoin.org" (or, in Namecoin's case, "bitcoin.bit") to an IP address. Other use cases include email authentication and potentially more advanced reputation systems. Here is the basic contract to provide a Namecoin-like name registration system on Ethereum: + + def register(name, value): + if !self.storage[name]: + self.storage[name] = value + +The contract is very simple; all it is is a database inside the Ethereum network that can be added to, but not modified or removed from. Anyone can register a name with some value, and that registration then sticks forever. A more sophisticated name registration contract will also have a "function clause" allowing other contracts to query it, as well as a mechanism for the "owner" (ie. the first registerer) of a name to change the data or transfer ownership. One can even add reputation and web-of-trust functionality on top. + +### Decentralized File Storage + +Over the past few years, there have emerged a number of popular online file storage startups, the most prominent being Dropbox, seeking to allow users to upload a backup of their hard drive and have the service store the backup and allow the user to access it in exchange for a monthly fee. However, at this point the file storage market is at times relatively inefficient; a cursory look at various [existing solutions](http://online-storage-service-review.toptenreviews.com/) shows that, particularly at the "uncanny valley" 20-200 GB level at which neither free quotas nor enterprise-level discounts kick in, monthly prices for mainstream file storage costs are such that you are paying for more than the cost of the entire hard drive in a single month. Ethereum contracts can allow for the development of a decentralized file storage ecosystem, where individual users can earn small quantities of money by renting out their own hard drives and unused space can be used to further drive down the costs of file storage. + +The key underpinning piece of such a device would be what we have termed the "decentralized Dropbox contract". This contract works as follows. First, one splits the desired data up into blocks, encrypting each block for privacy, and builds a Merkle tree out of it. One then makes a contract with the rule that, every N blocks, the contract would pick a random index in the Merkle tree (using the previous block hash, accessible from contract code, as a source of randomness), and give X ether to the first entity to supply a transaction with a simplified payment verification-like proof of ownership of the block at that particular index in the tree. When a user wants to re-download their file, they can use a micropayment channel protocol (eg. pay 1 szabo per 32 kilobytes) to recover the file; the most fee-efficient approach is for the payer not to publish the transaction until the end, instead replacing the transaction with a slightly more lucrative one with the same nonce after every 32 kilobytes. + +An important feature of the protocol is that, although it may seem like one is trusting many random nodes not to decide to forget the file, one can reduce that risk down to near-zero by splitting the file into many pieces via secret sharing, and watching the contracts to see each piece is still in some node's possession. If a contract is still paying out money, that provides a cryptographic proof that someone out there is still storing the file. + +### Decentralized Autonomous Organizations + +The general concept of a "decentralized autonomous organization" is that of a virtual entity that has a certain set of members or shareholders which, perhaps with a 67% majority, have the right to spend the entity's funds and modify its code. The members would collectively decide on how the organization should allocate its funds. Methods for allocating a DAO's funds could range from bounties, salaries to even more exotic mechanisms such as an internal currency to reward work. This essentially replicates the legal trappings of a traditional company or nonprofit but using only cryptographic blockchain technology for enforcement. So far much of the talk around DAOs has been around the "capitalist" model of a "decentralized autonomous corporation" (DAC) with dividend-receiving shareholders and tradable shares; an alternative, perhaps described as a "decentralized autonomous community", would have all members have an equal share in the decision making and require 67% of existing members to agree to add or remove a member. The requirement that one person can only have one membership would then need to be enforced collectively by the group. + +A general outline for how to code a DAO is as follows. The simplest design is simply a piece of self-modifying code that changes if two thirds of members agree on a change. Although code is theoretically immutable, one can easily get around this and have de-facto mutability by having chunks of the code in separate contracts, and having the address of which contracts to call stored in the modifiable storage. In a simple implementation of such a DAO contract, there would be three transaction types, distinquished by the data provided in the transaction: + +* `[0,i,K,V]` to register a proposal with index `i` to change the address at storage index `K` to value `V` +* `[0,i]` to register a vote in favor of proposal `i` +* `[2,i]` to finalize proposal `i` if enough votes have been made + +The contract would then have clauses for each of these. It would maintain a record of all open storage changes, along with a list of who voted for them. It would also have a list of all members. When any storage change gets to two thirds of members voting for it, a finalizing transaction could execute the change. A more sophisticated skeleton would also have built-in voting ability for features like sending a transaction, adding members and removing members, and may even provide for [Liquid Democracy](http://en.wikipedia.org/wiki/Delegative_democracy)-style vote delegation (ie. anyone can assign someone to vote for them, and assignment is transitive so if A assigns B and B assigns C then C determines A's vote). This design would allow the DAO to grow organically as a decentralized community, allowing people to eventually delegate the task of filtering out who is a member to specialists, although unlike in the "current system" specialists can easily pop in and out of existence over time as individual community members change their alignments. + +An alternative model is for a decentralized corporation, where any account can have zero or more shares, and two thirds of the shares are required to make a decision. A complete skeleton would involve asset management functionality, the ability to make an offer to buy or sell shares, and the ability to accept offers (preferably with an order-matching mechanism inside the contract). Delegation would also exist Liquid Democracy-style, generalizing the concept of a "board of directors". + +### Further Applications + +**1. Savings wallets**. Suppose that Alice wants to keep her funds safe, but is worried that she will lose or someone will hack her private key. She puts ether into a contract with Bob, a bank, as follows: + +* Alice alone can withdraw a maximum of 1% of the funds per day. +* Bob alone can withdraw a maximum of 1% of the funds per day, but Alice has the ability to make a transaction with her key shutting off this ability. +* Alice and Bob together can withdraw anything. + +Normally, 1% per day is enough for Alice, and if Alice wants to withdraw more she can contact Bob for help. If Alice's key gets hacked, she runs to Bob to move the funds to a new contract. If she loses her key, Bob will get the funds out eventually. If Bob turns out to be malicious, then she can turn off his ability to withdraw. + +**2. Crop insurance**. One can easily make a financial derivatives contract but using a data feed of the weather instead of any price index. If a farmer in Iowa purchases a derivative that pays out inversely based on the precipitation in Iowa, then if there is a drought, the farmer will automatically receive money and if there is enough rain the farmer will be happy because their crops would do well. This can be expanded to natural disaster insurance generally. + +**3. A decentralized data feed**. For financial contracts for difference, it may actually be possible to decentralize the data feed via a protocol called "[SchellingCoin](http://blog.ethereum.org/2014/03/28/schellingcoin-a-minimal-trust-universal-data-feed/)". SchellingCoin basically works as follows: N parties all put into the system the value of a given datum (eg. the ETH/USD price), the values are sorted, and everyone between the 25th and 75th percentile gets one token as a reward. Everyone has the incentive to provide the answer that everyone else will provide, and the only value that a large number of players can realistically agree on is the obvious default: the truth. This creates a decentralized protocol that can theoretically provide any number of values, including the ETH/USD price, the temperature in Berlin or even the result of a particular hard computation. + +**4. Smart multisignature escrow**. Bitcoin allows multisignature transaction contracts where, for example, three out of a given five keys can spend the funds. Ethereum allows for more granularity; for example, four out of five can spend everything, three out of five can spend up to 10% per day, and two out of five can spend up to 0.5% per day. Additionally, Ethereum multisig is asynchronous - two parties can register their signatures on the blockchain at different times and the last signature will automatically send the transaction. + +**5. Cloud computing**. The EVM technology can also be used to create a verifiable computing environment, allowing users to ask others to carry out computations and then optionally ask for proofs that computations at certain randomly selected checkpoints were done correctly. This allows for the creation of a cloud computing market where any user can participate with their desktop, laptop or specialized server, and spot-checking together with security deposits can be used to ensure that the system is trustworthy (ie. nodes cannot profitably cheat). Although such a system may not be suitable for all tasks; tasks that require a high level of inter-process communication, for example, cannot easily be done on a large cloud of nodes. Other tasks, however, are much easier to parallelize; projects like SETI@home, folding@home and genetic algorithms can easily be implemented on top of such a platform. + +**6. Peer-to-peer gambling**. Any number of peer-to-peer gambling protocols, such as Frank Stajano and Richard Clayton's [Cyberdice](http://www.cl.cam.ac.uk/~fms27/papers/2008-StajanoCla-cyberdice.pdf), can be implemented on the Ethereum blockchain. The simplest gambling protocol is actually simply a contract for difference on the next block hash, and more advanced protocols can be built up from there, creating gambling services with near-zero fees that have no ability to cheat. + +**7. Prediction markets**. Provided an oracle or SchellingCoin, prediction markets are also easy to implement, and prediction markets together with SchellingCoin may prove to be the first mainstream application of [futarchy](http://hanson.gmu.edu/futarchy.html) as a governance protocol for decentralized organizations. + +**8. On-chain decentralized marketplaces**, using the identity and reputation system as a base. + +## Miscellanea And Concerns + +### Modified GHOST Implementation + +The "Greedy Heaviest Observed Subtree" (GHOST) protocol is an innovation first introduced by Yonatan Sompolinsky and Aviv Zohar in [December 2013](http://www.cs.huji.ac.il/~avivz/pubs/13/btc_scalability_full.pdf). The motivation behind GHOST is that blockchains with fast confirmation times currently suffer from reduced security due to a high stale rate - because blocks take a certain time to propagate through the network, if miner A mines a block and then miner B happens to mine another block before miner A's block propagates to B, miner B's block will end up wasted and will not contribute to network security. Furthermore, there is a centralization issue: if miner A is a mining pool with 30% hashpower and B has 10% hashpower, A will have a risk of producing a stale block 70% of the time (since the other 30% of the time A produced the last block and so will get mining data immediately) whereas B will have a risk of producing a stale block 90% of the time. Thus, if the block interval is short enough for the stale rate to be high, A will be substantially more efficient simply by virtue of its size. With these two effects combined, blockchains which produce blocks quickly are very likely to lead to one mining pool having a large enough percentage of the network hashpower to have de facto control over the mining process. + +As described by Sompolinsky and Zohar, GHOST solves the first issue of network security loss by including stale blocks in the calculation of which chain is the "longest"; that is to say, not just the parent and further ancestors of a block, but also the stale descendants of the block's ancestor (in Ethereum jargon, "uncles") are added to the calculation of which block has the largest total proof of work backing it. To solve the second issue of centralization bias, we go beyond the protocol described by Sompolinsky and Zohar, and also provide block rewards to stales: a stale block receives 87.5% of its base reward, and the nephew that includes the stale block receives the remaining 12.5%. Transaction fees, however, are not awarded to uncles. + +Ethereum implements a simplified version of GHOST which only goes down seven levels. Specifically, it is defined as follows: + +* A block must specify a parent, and it must specify 0 or more uncles +* An uncle included in block `B` must have the following properties: + * It must be a direct child of the `k`-th generation ancestor of `B`, where `2 <= k <= 7`. + * It cannot be an ancestor of `B` + * An uncle must be a valid block header, but does not need to be a previously verified or even valid block + * An uncle must be different from all uncles included in previous blocks and all other uncles included in the same block (non-double-inclusion) +* For every uncle `U` in block `B`, the miner of `B` gets an additional 3.125% added to its coinbase reward and the miner of `U` gets 93.75% of a standard coinbase reward. + +This limited version of GHOST, with uncles includable only up to 7 generations, was used for two reasons. First, unlimited GHOST would include too many complications into the calculation of which uncles for a given block are valid. Second, unlimited GHOST with compensation as used in Ethereum removes the incentive for a miner to mine on the main chain and not the chain of a public attacker. + +### Fees + +Because every transaction published into the blockchain imposes on the network the cost of needing to download and verify it, there is a need for some regulatory mechanism, typically involving transaction fees, to prevent abuse. The default approach, used in Bitcoin, is to have purely voluntary fees, relying on miners to act as the gatekeepers and set dynamic minimums. This approach has been received very favorably in the Bitcoin community particularly because it is "market-based", allowing supply and demand between miners and transaction senders determine the price. The problem with this line of reasoning is, however, that transaction processing is not a market; although it is intuitively attractive to construe transaction processing as a service that the miner is offering to the sender, in reality every transaction that a miner includes will need to be processed by every node in the network, so the vast majority of the cost of transaction processing is borne by third parties and not the miner that is making the decision of whether or not to include it. Hence, tragedy-of-the-commons problems are very likely to occur. + +However, as it turns out this flaw in the market-based mechanism, when given a particular inaccurate simplifying assumption, magically cancels itself out. The argument is as follows. Suppose that: + +1. A transaction leads to `k` operations, offering the reward `kR` to any miner that includes it where `R` is set by the sender and `k` and `R` are (roughly) visible to the miner beforehand. +2. An operation has a processing cost of `C` to any node (ie. all nodes have equal efficiency) +3. There are `N` mining nodes, each with exactly equal processing power (ie. `1/N` of total) +4. No non-mining full nodes exist. + +A miner would be willing to process a transaction if the expected reward is greater than the cost. Thus, the expected reward is `kR/N` since the miner has a `1/N` chance of processing the next block, and the processing cost for the miner is simply `kC`. Hence, miners will include transactions where `kR/N > kC`, or `R > NC`. Note that `R` is the per-operation fee provided by the sender, and is thus a lower bound on the benefit that the sender derives from the transaction, and `NC` is the cost to the entire network together of processing an operation. Hence, miners have the incentive to include only those transactions for which the total utilitarian benefit exceeds the cost. + +However, there are several important deviations from those assumptions in reality: + +1. The miner does pay a higher cost to process the transaction than the other verifying nodes, since the extra verification time delays block propagation and thus increases the chance the block will become a stale. +2. There do exist nonmining full nodes. +3. The mining power distribution may end up radically inegalitarian in practice. +4. Speculators, political enemies and crazies whose utility function includes causing harm to the network do exist, and they can cleverly set up contracts where their cost is much lower than the cost paid by other verifying nodes. + +(1) provides a tendency for the miner to include fewer transactions, and (2) increases `NC`; hence, these two effects at least partially cancel each other out. (3) and (4) are the major issue; to solve them we simply institute a floating cap: no block can have more operations than `BLK_LIMIT_FACTOR` times the long-term exponential moving average. Specifically: + + blk.oplimit = floor((blk.parent.oplimit * (EMA_FACTOR - 1) + floor(parent.opcount * BLK_LIMIT_FACTOR)) / EMA_FACTOR) + +`BLK_LIMIT_FACTOR` and `EMA_FACTOR` are constants that will be set to 65536 and 1.5 for the time being, but will likely be changed after further analysis. + +There is another factor disincentivizing large block sizes in Bitcoin: blocks that are large will take longer to propagate, and thus have a higher probability of becoming stales. In Ethereum, highly gas-consuming blocks can also take longer to propagate both because they are physically larger and because they take longer to process the transaction state transitions to validate. This delay disincentive is a significant consideration in Bitcoin, but less so in Ethereum because of the GHOST protocol; hence, relying on regulated block limits provides a more stable baseline. + +### Computation And Turing-Completeness + +An important note is that the Ethereum virtual machine is Turing-complete; this means that EVM code can encode any computation that can be conceivably carried out, including infinite loops. EVM code allows looping in two ways. First, there is a `JUMP` instruction that allows the program to jump back to a previous spot in the code, and a `JUMPI` instruction to do conditional jumping, allowing for statements like `while x < 27: x = x * 2`. Second, contracts can call other contracts, potentially allowing for looping through recursion. This naturally leads to a problem: can malicious users essentially shut miners and full nodes down by forcing them to enter into an infinite loop? The issue arises because of a problem in computer science known as the halting problem: there is no way to tell, in the general case, whether or not a given program will ever halt. + +As described in the state transition section, our solution works by requiring a transaction to set a maximum number of computational steps that it is allowed to take, and if execution takes longer computation is reverted but fees are still paid. Messages work in the same way. To show the motivation behind our solution, consider the following examples: + +* An attacker creates a contract which runs an infinite loop, and then sends a transaction activating that loop to the miner. The miner will process the transaction, running the infinite loop, and wait for it to run out of gas. Even though the execution runs out of gas and stops halfway through, the transaction is still valid and the miner still claims the fee from the attacker for each computational step. +* An attacker creates a very long infinite loop with the intent of forcing the miner to keep computing for such a long time that by the time computation finishes a few more blocks will have come out and it will not be possible for the miner to include the transaction to claim the fee. However, the attacker will be required to submit a value for `STARTGAS` limiting the number of computational steps that execution can take, so the miner will know ahead of time that the computation will take an excessively large number of steps. +* An attacker sees a contract with code of some form like `send(A,contract.storage[A]); contract.storage[A] = 0`, and sends a transaction with just enough gas to run the first step but not the second (ie. making a withdrawal but not letting the balance go down). The contract author does not need to worry about protecting against such attacks, because if execution stops halfway through the changes get reverted. +* A financial contract works by taking the median of nine proprietary data feeds in order to minimize risk. An attacker takes over one of the data feeds, which is designed to be modifiable via the variable-address-call mechanism described in the section on DAOs, and converts it to run an infinite loop, thereby attempting to force any attempts to claim funds from the financial contract to run out of gas. However, the financial contract can set a gas limit on the message to prevent this problem. + +The alternative to Turing-completeness is Turing-incompleteness, where `JUMP` and `JUMPI` do not exist and only one copy of each contract is allowed to exist in the call stack at any given time. With this system, the fee system described and the uncertainties around the effectiveness of our solution might not be necessary, as the cost of executing a contract would be bounded above by its size. Additionally, Turing-incompleteness is not even that big a limitation; out of all the contract examples we have conceived internally, so far only one required a loop, and even that loop could be removed by making 26 repetitions of a one-line piece of code. Given the serious implications of Turing-completeness, and the limited benefit, why not simply have a Turing-incomplete language? In reality, however, Turing-incompleteness is far from a neat solution to the problem. To see why, consider the following contracts: + + C0: call(C1); call(C1); + C1: call(C2); call(C2); + C2: call(C3); call(C3); + ... + C49: call(C50); call(C50); + C50: (run one step of a program and record the change in storage) + +Now, send a transaction to A. Thus, in 51 transactions, we have a contract that takes up 250 computational steps. Miners could try to detect such logic bombs ahead of time by maintaining a value alongside each contract specifying the maximum number of computational steps that it can take, and calculating this for contracts calling other contracts recursively, but that would require miners to forbid contracts that create other contracts (since the creation and execution of all 26 contracts above could easily be rolled into a single contract). Another problematic point is that the address field of a message is a variable, so in general it may not even be possible to tell which other contracts a given contract will call ahead of time. Hence, all in all, we have a surprising conclusion: Turing-completeness is surprisingly easy to manage, and the lack of Turing-completeness is equally surprisingly difficult to manage unless the exact same controls are in place - but in that case why not just let the protocol be Turing-complete? + +### Currency And Issuance + +The Ethereum network includes its own built-in currency, ether, which serves the dual purpose of providing a primary liquidity layer to allow for efficient exchange between various types of digital assets and, more importantly, of providing a mechanism for paying transaction fees. For convenience and to avoid future argument (see the current mBTC/uBTC/satoshi debate in Bitcoin), the denominations will be pre-labelled: + +* 1: wei +* 1012: szabo +* 1015: finney +* 1018: ether + +This should be taken as an expanded version of the concept of "dollars" and "cents" or "BTC" and "satoshi". In the near future, we expect "ether" to be used for ordinary transactions, "finney" for microtransactions and "szabo" and "wei" for technical discussions around fees and protocol implementation; the remaining denominations may become useful later and should not be included in clients at this point. + +The issuance model will be as follows: + +* Ether will be released in a currency sale at the price of 1000-2000 ether per BTC, a mechanism intended to fund the Ethereum organization and pay for development that has been used with success by other platforms such as Mastercoin and NXT. Earlier buyers will benefit from larger discounts. The BTC received from the sale will be used entirely to pay salaries and bounties to developers and invested into various for-profit and non-profit projects in the Ethereum and cryptocurrency ecosystem. +* 0.099x the total amount sold (60102216 ETH) will be allocated to the organization to compensate early contributors and pay ETH-denominated expenses before the genesis block. +* 0.099x the total amount sold will be maintained as a long-term reserve. +* 0.26x the total amount sold will be allocated to miners per year forever after that point. + +| Group | At launch | After 1 year | After 5 years +| ------------- | ------------- |-------------| ----------- | +| Currency units | 1.198X | 1.458X | 2.498X | +| Purchasers | 83.5% | 68.6% | 40.0% | +| Reserve spent pre-sale | 8.26% | 6.79% | 3.96% | +| Reserve used post-sale | 8.26% | 6.79% | 3.96% | +| Miners | 0% | 17.8% | 52.0% | + +**Long-Term Supply Growth Rate (percent)** + +_Despite the linear currency issuance, just like with Bitcoin over time the supply growth rate nevertheless tends to zero_ + +The two main choices in the above model are (1) the existence and size of an endowment pool, and (2) the existence of a permanently growing linear supply, as opposed to a capped supply as in Bitcoin. The justification of the endowment pool is as follows. If the endowment pool did not exist, and the linear issuance reduced to 0.217x to provide the same inflation rate, then the total quantity of ether would be 16.5% less and so each unit would be 19.8% more valuable. Hence, in the equilibrium 19.8% more ether would be purchased in the sale, so each unit would once again be exactly as valuable as before. The organization would also then have 1.198x as much BTC, which can be considered to be split into two slices: the original BTC, and the additional 0.198x. Hence, this situation is _exactly equivalent_ to the endowment, but with one important difference: the organization holds purely BTC, and so is not incentivized to support the value of the ether unit. + +The permanent linear supply growth model reduces the risk of what some see as excessive wealth concentration in Bitcoin, and gives individuals living in present and future eras a fair chance to acquire currency units, while at the same time retaining a strong incentive to obtain and hold ether because the "supply growth rate" as a percentage still tends to zero over time. We also theorize that because coins are always lost over time due to carelessness, death, etc, and coin loss can be modeled as a percentage of the total supply per year, that the total currency supply in circulation will in fact eventually stabilize at a value equal to the annual issuance divided by the loss rate (eg. at a loss rate of 1%, once the supply reaches 26X then 0.26X will be mined and 0.26X lost every year, creating an equilibrium). + +Note that in the future, it is likely that Ethereum will switch to a proof-of-stake model for security, reducing the issuance requirement to somewhere between zero and 0.05X per year. In the event that the Ethereum organization loses funding or for any other reason disappears, we leave open a "social contract": anyone has the right to create a future candidate version of Ethereum, with the only condition being that the quantity of ether must be at most equal to `60102216 * (1.198 + 0.26 * n)` where `n` is the number of years after the genesis block. Creators are free to crowd-sell or otherwise assign some or all of the difference between the PoS-driven supply expansion and the maximum allowable supply expansion to pay for development. Candidate upgrades that do not comply with the social contract may justifiably be forked into compliant versions. + +### Mining Centralization + +The Bitcoin mining algorithm works by having miners compute SHA256 on slightly modified versions of the block header millions of times over and over again, until eventually one node comes up with a version whose hash is less than the target (currently around 2192). However, this mining algorithm is vulnerable to two forms of centralization. First, the mining ecosystem has come to be dominated by ASICs (application-specific integrated circuits), computer chips designed for, and therefore thousands of times more efficient at, the specific task of Bitcoin mining. This means that Bitcoin mining is no longer a highly decentralized and egalitarian pursuit, requiring millions of dollars of capital to effectively participate in. Second, most Bitcoin miners do not actually perform block validation locally; instead, they rely on a centralized mining pool to provide the block headers. This problem is arguably worse: as of the time of this writing, the top three mining pools indirectly control roughly 50% of processing power in the Bitcoin network, although this is mitigated by the fact that miners can switch to other mining pools if a pool or coalition attempts a 51% attack. + +The current intent at Ethereum is to use a mining algorithm where miners are required to fetch random data from the state, compute some randomly selected transactions from the last N blocks in the blockchain, and return the hash of the result. This has two important benefits. First, Ethereum contracts can include any kind of computation, so an Ethereum ASIC would essentially be an ASIC for general computation - ie. a better CPU. Second, mining requires access to the entire blockchain, forcing miners to store the entire blockchain and at least be capable of verifying every transaction. This removes the need for centralized mining pools; although mining pools can still serve the legitimate role of evening out the randomness of reward distribution, this function can be served equally well by peer-to-peer pools with no central control. + +This model is untested, and there may be difficulties along the way in avoiding certain clever optimizations when using contract execution as a mining algorithm. However, one notably interesting feature of this algorithm is that it allows anyone to "poison the well", by introducing a large number of contracts into the blockchain specifically designed to stymie certain ASICs. The economic incentives exist for ASIC manufacturers to use such a trick to attack each other. Thus, the solution that we are developing is ultimately an adaptive economic human solution rather than purely a technical one. + +### Scalability + +One common concern about Ethereum is the issue of scalability. Like Bitcoin, Ethereum suffers from the flaw that every transaction needs to be processed by every node in the network. With Bitcoin, the size of the current blockchain rests at about 15 GB, growing by about 1 MB per hour. If the Bitcoin network were to process Visa's 2000 transactions per second, it would grow by 1 MB per three seconds (1 GB per hour, 8 TB per year). Ethereum is likely to suffer a similar growth pattern, worsened by the fact that there will be many applications on top of the Ethereum blockchain instead of just a currency as is the case with Bitcoin, but ameliorated by the fact that Ethereum full nodes need to store just the state instead of the entire blockchain history. + +The problem with such a large blockchain size is centralization risk. If the blockchain size increases to, say, 100 TB, then the likely scenario would be that only a very small number of large businesses would run full nodes, with all regular users using light SPV nodes. In such a situation, there arises the potential concern that the full nodes could band together and all agree to cheat in some profitable fashion (eg. change the block reward, give themselves BTC). Light nodes would have no way of detecting this immediately. Of course, at least one honest full node would likely exist, and after a few hours information about the fraud would trickle out through channels like Reddit, but at that point it would be too late: it would be up to the ordinary users to organize an effort to blacklist the given blocks, a massive and likely infeasible coordination problem on a similar scale as that of pulling off a successful 51% attack. In the case of Bitcoin, this is currently a problem, but there exists a blockchain modification [suggested by Peter Todd](https://web.archive.org/web/20140623061815/http://sourceforge.net/p/bitcoin/mailman/message/31709140/) which will alleviate this issue. + +In the near term, Ethereum will use two additional strategies to cope with this problem. First, because of the blockchain-based mining algorithms, at least every miner will be forced to be a full node, creating a lower bound on the number of full nodes. Second and more importantly, however, we will include an intermediate state tree root in the blockchain after processing each transaction. Even if block validation is centralized, as long as one honest verifying node exists, the centralization problem can be circumvented via a verification protocol. If a miner publishes an invalid block, that block must either be badly formatted, or the state `S[n]` is incorrect. Since `S[0]` is known to be correct, there must be some first state `S[i]` that is incorrect where `S[i-1]` is correct. The verifying node would provide the index `i`, along with a "proof of invalidity" consisting of the subset of Patricia tree nodes needing to process `APPLY(S[i-1],TX[i]) -> S[i]`. Nodes would be able to use those nodes to run that part of the computation, and see that the `S[i]` generated does not match the `S[i]` provided. + +Another, more sophisticated, attack would involve the malicious miners publishing incomplete blocks, so the full information does not even exist to determine whether or not blocks are valid. The solution to this is a challenge-response protocol: verification nodes issue "challenges" in the form of target transaction indices, and upon receiving a node a light node treats the block as untrusted until another node, whether the miner or another verifier, provides a subset of Patricia nodes as a proof of validity. + +## Conclusion + +The Ethereum protocol was originally conceived as an upgraded version of a cryptocurrency, providing advanced features such as on-blockchain escrow, withdrawal limits, financial contracts, gambling markets and the like via a highly generalized programming language. The Ethereum protocol would not "support" any of the applications directly, but the existence of a Turing-complete programming language means that arbitrary contracts can theoretically be created for any transaction type or application. What is more interesting about Ethereum, however, is that the Ethereum protocol moves far beyond just currency. Protocols around decentralized file storage, decentralized computation and decentralized prediction markets, among dozens of other such concepts, have the potential to substantially increase the efficiency of the computational industry, and provide a massive boost to other peer-to-peer protocols by adding for the first time an economic layer. Finally, there is also a substantial array of applications that have nothing to do with money at all. + +The concept of an arbitrary state transition function as implemented by the Ethereum protocol provides for a platform with unique potential; rather than being a closed-ended, single-purpose protocol intended for a specific array of applications in data storage, gambling or finance, Ethereum is open-ended by design, and we believe that it is extremely well-suited to serving as a foundational layer for a very large number of both financial and non-financial protocols in the years to come. + +## Notes and Further Reading + +#### Notes + +1. A sophisticated reader may notice that in fact a Bitcoin address is the hash of the elliptic curve public key, and not the public key itself. However, it is in fact perfectly legitimate cryptographic terminology to refer to the pubkey hash as a public key itself. This is because Bitcoin's cryptography can be considered to be a custom digital signature algorithm, where the public key consists of the hash of the ECC pubkey, the signature consists of the ECC pubkey concatenated with the ECC signature, and the verification algorithm involves checking the ECC pubkey in the signature against the ECC pubkey hash provided as a public key and then verifying the ECC signature against the ECC pubkey. +2. Technically, the median of the 11 previous blocks. +3. Internally, 2 and "CHARLIE" are both numbers, with the latter being in big-endian base 256 representation. Numbers can be at least 0 and at most 2256-1. + +#### Further Reading + +1. Intrinsic value: http://bitcoinmagazine.com/8640/an-exploration-of-intrinsic-value-what-it-is-why-bitcoin-doesnt-have-it-and-why-bitcoin-does-have-it/ +2. Smart property: https://en.bitcoin.it/wiki/Smart_Property +3. Smart contracts: https://en.bitcoin.it/wiki/Contracts +4. B-money: http://www.weidai.com/bmoney.txt +5. Reusable proofs of work: http://www.finney.org/~hal/rpow/ +6. Secure property titles with owner authority: http://szabo.best.vwh.net/securetitle.html +7. Bitcoin whitepaper: http://bitcoin.org/bitcoin.pdf +8. Namecoin: https://namecoin.org/ +9. Zooko's triangle: http://en.wikipedia.org/wiki/Zooko's_triangle +10. Colored coins whitepaper: https://docs.google.com/a/buterin.com/document/d/1AnkP_cVZTCMLIzw4DvsW6M8Q2JC0lIzrTLuoWu2z1BE/edit +11. Mastercoin whitepaper: https://github.com/mastercoin-MSC/spec +12. Decentralized autonomous corporations, Bitcoin Magazine: http://bitcoinmagazine.com/7050/bootstrapping-a-decentralized-autonomous-corporation-part-i/ +13. Simplified payment verification: https://en.bitcoin.it/wiki/Scalability#Simplifiedpaymentverification +14. Merkle trees: http://en.wikipedia.org/wiki/Merkle_tree +15. Patricia trees: http://en.wikipedia.org/wiki/Patricia_tree +16. GHOST: http://www.cs.huji.ac.il/~avivz/pubs/13/btc_scalability_full.pdf +17. StorJ and Autonomous Agents, Jeff Garzik: http://garzikrants.blogspot.ca/2013/01/storj-and-bitcoin-autonomous-agents.html +18. Mike Hearn on Smart Property at Turing Festival: http://www.youtube.com/watch?v=Pu4PAMFPo5Y +19. [Ethereum RLP](/fundamentals/rlp.md) +20. [Ethereum Merkle Patricia trees](/fundamentals/patricia-tree.md) +21. Peter Todd on Merkle sum trees: http://sourceforge.net/p/bitcoin/mailman/message/31709140/ diff --git "a/archive/\303\220\316\236Vp2p-Wire-Protocol.md" "b/archive/\303\220\316\236Vp2p-Wire-Protocol.md" new file mode 100644 index 0000000..27a8850 --- /dev/null +++ "b/archive/\303\220\316\236Vp2p-Wire-Protocol.md" @@ -0,0 +1,90 @@ +--- +name: DEV P2P Wire Protocol +category: +--- + +Peer-to-peer communications between nodes running Ethereum/Whisper/&c. clients are designed to be governed by a simple wire-protocol making use of existing ÐΞV technologies and standards such as [RLP](/fundamentals/rlp.md) wherever practical. + +This document is intended to specify this protocol comprehensively. + +### Low-Level + +ÐΞVp2p nodes may connect to each other over TCP only. Peers are free to advertise and accept connections on any port(s) they wish, however, a default port on which the connection may be listened and made will be 30303. + +Though TCP provides a connection-oriented medium, ÐΞVp2p nodes communicate in terms of packets. These packets are formed as a 4-byte synchronisation token (0x22400891), a 4-byte "payload size", to be interpreted as a big-endian integer and finally an N-byte RLP-serialised data structure, where N is the aforementioned "payload size". To be clear, the payload size specifies the number of bytes in the packet ''following'' the first 8. + +### Payload Contents + +There are a number of different types of payload that may be encoded within the RLP. This ''type'' is always determined by the first entry of the RLP, interpreted as an integer. + +ÐΞVp2p is designed to support arbitrary sub-protocols (aka _capabilities_) over the basic wire protocol. Each sub-protocol is given as much of the message-ID space as it needs (all such protocols must statically specify how many message IDs they require). On connection and reception of the `Hello` message, both peers have equivalent information about what subprotocols they share (including versions) and are able to form consensus over the composition of message ID space. + +Message IDs are assumed to be compact from ID 0x10 onwards (0x00-0x10 is reserved for ÐΞVp2p messages) and given to each shared (equal-version, equal name) sub-protocol in alphabetic order. Sub-protocols that are not shared are ignored. If multiple versions are shared of the same (equal name) sub-protocol, the numerically highest wins, others are ignored. + +### P2P + +**Hello** +[`0x00`: `P`, `p2pVersion`: `P`, `clientId`: `B`, [[`cap1`: `B_3`, `capVersion1`: `P`], [`cap2`: `B_3`, `capVersion2`: `P`], `...`], `listenPort`: `P`, `nodeId`: `B_64`] First packet sent over the connection, and sent once by both sides. No other messages may be sent until a Hello is received. +* `p2pVersion` Specifies the implemented version of the P2P protocol. Now must be 1. +* `clientId` Specifies the client software identity, as a human-readable string (e.g. "Ethereum(++)/1.0.0"). +* `cap` Specifies a peer capability name as a length-3 ASCII string. Current supported capabilities are `eth`, `shh`. +* `capVersion` Specifies a peer capability version as a positive integer. Current supported versions are 34 for `eth`, and 1 for `shh`. +* `listenPort` specifies the port that the client is listening on (on the interface that the present connection traverses). If 0 it indicates the client is not listening. +* `nodeId` is the Unique Identity of the node and specifies a 512-bit hash that identifies this node. + +**Disconnect** +[`0x01`: `P`, `reason`: `P`] Inform the peer that a disconnection is imminent; if received, a peer should disconnect immediately. When sending, well-behaved hosts give their peers a fighting chance (read: wait 2 seconds) to disconnect to before disconnecting themselves. +* `reason` is an optional integer specifying one of a number of reasons for disconnect: + * `0x00` Disconnect requested; + * `0x01` TCP sub-system error; + * `0x02` Breach of protocol, e.g. a malformed message, bad RLP, incorrect magic number &c.; + * `0x03` Useless peer; + * `0x04` Too many peers; + * `0x05` Already connected; + * `0x06` Incompatible P2P protocol version; + * `0x07` Null node identity received - this is automatically invalid; + * `0x08` Client quitting; + * `0x09` Unexpected identity (i.e. a different identity to a previous connection/what a trusted peer told us). + * `0x0a` Identity is the same as this node (i.e. connected to itself); + * `0x0b` Timeout on receiving a message (i.e. nothing received since sending last ping); + * `0x10` Some other reason specific to a subprotocol. + +**Ping** +[`0x02`: `P`] Requests an immediate reply of `Pong` from the peer. + +**Pong** +[`0x03`: `P`] Reply to peer's `Ping` packet. + +**NotImplemented (was GetPeers)** +[`0x04`: `...`] + +**NotImplemented (was Peers)** +[`0x05`: `...`] + +### Node identity and reputation + +In a later version of this protocol, node ID will become the public key. Nodes will have to demonstrate ownership over their ID by interpreting a packet encrypted with their node ID (or perhaps signing a random nonce with their private key). + +A proof-of-work may be associated with the node ID through the big-endian magnitude of the public key. Nodes with a great proof-of-work (public key of lower magnitude) may be given preference since it is less likely that the node will alter its ID later or masquerade under multiple IDs. + +Nodes are free to store ratings for given IDs (how useful the node has been in the past) and give preference accordingly. Nodes may also track node IDs (and their provenance) in order to help determine potential man-in-the-middle attacks. + +Clients are free to mark down new nodes and use the node ID as a means of determining a node's reputation. In a future version of this wire protocol, n + +### Example Packets + +`0x22400891000000088400000043414243` + +A Hello packet specifying the client id is "ABC". + +Peer 1: `0x22400891000000028102` + +Peer 2: `0x22400891000000028103` + +A Ping and the returned Pong. + +### Session Management + +Upon connecting, all clients (i.e. both sides of the connection) must send a `Hello` message. Upon receiving the `Hello` message and verifying compatibility of the network and versions, a session is active and any other P2P messages may be sent. + +At any time, a Disconnect message may be sent. \ No newline at end of file diff --git a/clients/client-version-strings.md b/clients/client-version-strings.md index e09bf85..5513d8b 100644 --- a/clients/client-version-strings.md +++ b/clients/client-version-strings.md @@ -1,6 +1,6 @@ # Client Version Strings -Every client implementation of the Ethereum protocol – along with every version of it – has a _human readable_ string identifier. Although this ID is exchanged in the [P2P protocol](%C3%90%CE%9EVp2p-Wire-Protocol#p2p), it itself isn't used by the protocol for anything, rather it enables easily localizing issues with a particular client, or a particular version of a client. +Every client implementation of the Ethereum protocol – along with every version of it – has a _human readable_ string identifier. Although this ID is exchanged in the [P2P protocol](/archive/%C3%90%CE%9EVp2p-Wire-Protocol.md#p2p), it itself isn't used by the protocol for anything, rather it enables easily localizing issues with a particular client, or a particular version of a client. Still, there tools popping up that analyze and create various statistics about the network topology itself, which have a hard time conforming to the identifier/versioning schema employed by each implementation. To avoid requiring each such tool to implement a full ID parsing for every type of node in the network, this document outlines a **suggested** schema, part of which would be common among all implementations, and some would be specific to one or the other. This would allow simple tools to properly parse the common information out of each client's ID string, whereas more complex tools might also further inspect the client specific metadata. diff --git a/clients/clients-tools-dapp-browsers-wallets-and-other-projects.md b/clients/clients-tools-dapp-browsers-wallets-and-other-projects.md index 51985bf..7d06f24 100644 --- a/clients/clients-tools-dapp-browsers-wallets-and-other-projects.md +++ b/clients/clients-tools-dapp-browsers-wallets-and-other-projects.md @@ -49,9 +49,9 @@ NOTE: all clients are listed in alphabetical order. ## Other projects, tools, etc. -- [sharding](../sharding/sharding-introduction-r-d-compendium.md) -- [Casper Proof-of-Stake](../concepts/casper-proof-of-stake-compendium.md) -- [smart contract languages](../fundamentals/dapp-development.md): +- [sharding](/sharding/sharding-introduction-r-d-compendium.md) +- [Casper Proof-of-Stake](/concepts/casper-proof-of-stake-compendium.md) +- [smart contract languages](/fundamentals/dapp-development.md): - Solidity: [repo](https://github.com/ethereum/solidity), join the chat at , [docs](https://solidity.readthedocs.org/en/latest/), see the above link for more resources. - Vyper: [repo](https://github.com/ethereum/vyper) - LLL and other deprecated languages diff --git a/concepts/casper-proof-of-stake-compendium.md b/concepts/casper-proof-of-stake-compendium.md index 749151f..70ecbd5 100644 --- a/concepts/casper-proof-of-stake-compendium.md +++ b/concepts/casper-proof-of-stake-compendium.md @@ -6,7 +6,7 @@ See: -- [FAQs](./proof-of-stake-faqs.md) +- [FAQs](/concepts/proof-of-stake-faqs.md) ## Casper FFG diff --git a/concepts/dagger-hashimoto.md b/concepts/dagger-hashimoto.md index 2a2b03d..9af14a4 100644 --- a/concepts/dagger-hashimoto.md +++ b/concepts/dagger-hashimoto.md @@ -2,7 +2,7 @@ ## Introduction -Dagger Hashimoto was a precursor research implementation and specification for the mining algorithm for Ethereum 1.0, while it has been superceded by [Ethash](http://github.com/ethereum/wiki/wiki/Ethash). +Dagger Hashimoto was a precursor research implementation and specification for the mining algorithm for Ethereum 1.0, while it has been superceded by [Ethash](/concepts/ethash/ethash.md). The information in this article shall be kept for historical purposes. diff --git a/concepts/ethash/dag-disk-storage-format.md b/concepts/ethash/dag-disk-storage-format.md index a8b2703..2f49b56 100644 --- a/concepts/ethash/dag-disk-storage-format.md +++ b/concepts/ethash/dag-disk-storage-format.md @@ -1,6 +1,6 @@ # Ethash DAG Disk Storage Format -Ethash is the PoW system. It requires a great huge dataset known as the DAG (name refers to [Dagger Hashimoto](Dagger-Hashimoto)). This takes a good long while to generate which is a pain. As such we tend to memoise it. Clients wishing to store the DAG in a cache should conform to this spec in order to share the cache with other clients: +Ethash is the PoW system. It requires a great huge dataset known as the DAG (name refers to [Dagger Hashimoto](/concepts/dagger-hashimoto.md)). This takes a good long while to generate which is a pain. As such we tend to memoise it. Clients wishing to store the DAG in a cache should conform to this spec in order to share the cache with other clients: ## Location diff --git a/concepts/ethash/dag.md b/concepts/ethash/dag.md index e91c000..ce1c335 100644 --- a/concepts/ethash/dag.md +++ b/concepts/ethash/dag.md @@ -1,6 +1,6 @@ # Ethash DAG -Ethash is the PoW system. It requires a ~1GB dataset known as the DAG (see [Dagger Hashimoto](Dagger-Hashimoto)). This typically takes hours to generate so we tend to memorise it. Clients wishing to store the DAG in a cache should conform to this spec in order to share the cache with other clients: +Ethash is the PoW system. It requires a ~1GB dataset known as the DAG (see [Dagger Hashimoto](/concepts/dagger-hashimoto.md)). This typically takes hours to generate so we tend to memorise it. Clients wishing to store the DAG in a cache should conform to this spec in order to share the cache with other clients: ## Location diff --git a/concepts/ethash/ethash.md b/concepts/ethash/ethash.md index 04a867d..af3b4c7 100644 --- a/concepts/ethash/ethash.md +++ b/concepts/ethash/ethash.md @@ -10,7 +10,7 @@ tags: **This spec is REVISION 23. Whenever you substantively (ie. not clarifications) update the algorithm, please update the revision number in this sentence. Also, in all implementations please include a spec revision number** -Ethash is the planned PoW algorithm for Ethereum 1.0. It is the latest version of Dagger-Hashimoto, although it can no longer appropriately be called that since many of the original features of both algorithms have been drastically changed in the last month of research and development. [Read the original version](/concepts/dagger-hashimoto). +Ethash is the planned PoW algorithm for Ethereum 1.0. It is the latest version of Dagger-Hashimoto, although it can no longer appropriately be called that since many of the original features of both algorithms have been drastically changed in the last month of research and development. [Read the original version](/concepts/dagger-hashimoto.md). The general route that the algorithm takes is as follows: @@ -21,7 +21,7 @@ The general route that the algorithm takes is as follows: The large dataset is updated once every 30000 blocks, so the vast majority of a miner's effort will be reading the dataset, not making changes to it. -See [Ethhash design rationale](/concepts/ethash/design-rationale) for design rationale considerations for this algorithm. +See [Ethhash design rationale](/concepts/ethash/design-rationale.md) for design rationale considerations for this algorithm. ## Definitions @@ -140,7 +140,7 @@ def calc_dataset(full_size, cache): ## Main Loop -Now, we specify the main "hashimoto"-like loop, where we aggregate data from the full dataset in order to produce our final value for a particular header and nonce. In the code below, `header` represents the SHA3-256 _hash_ of the [RLP](RLP) representation of a _truncated_ block header, that is, of a header excluding the fields **mixHash** and **nonce**. `nonce` is the eight bytes of a 64 bit unsigned integer in big-endian order. So `nonce[::-1]` is the eight-byte little-endian representation of that value: +Now, we specify the main "hashimoto"-like loop, where we aggregate data from the full dataset in order to produce our final value for a particular header and nonce. In the code below, `header` represents the SHA3-256 _hash_ of the [RLP](/fundamentals/rlp.md) representation of a _truncated_ block header, that is, of a header excluding the fields **mixHash** and **nonce**. `nonce` is the eight bytes of a 64 bit unsigned integer in big-endian order. So `nonce[::-1]` is the eight-byte little-endian representation of that value: ```python def hashimoto(header, nonce, full_size, dataset_lookup): diff --git a/concepts/evm/ethereum-virtual-machine-(evm)-awesome-list.md b/concepts/evm/ethereum-virtual-machine-(evm)-awesome-list.md index 0baa270..010e683 100644 --- a/concepts/evm/ethereum-virtual-machine-(evm)-awesome-list.md +++ b/concepts/evm/ethereum-virtual-machine-(evm)-awesome-list.md @@ -12,7 +12,7 @@ A curated list of resources on the Ethereum Virtual Machine (EVM), which is the Not listed there yet, but in the spirit of [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome) -Here is [how to contribute](../../governance/contributing.md). +Here is [how to contribute](/governance/contributing.md). ## Specification @@ -52,7 +52,7 @@ Here is [how to contribute](../../governance/contributing.md). - A Python implementation designed to be highly configurable and modular and compliant with the Ethereum test suite, work is in progress on it to run a full node and develop sharding. - [EthereumJ](https://github.com/ethereum/ethereumj) in Java - A client with its own EVM implementation -- For more, see [here](Clients). +- For more, see [here](/clients/clients-tools-dapp-browsers-wallets-and-other-projects.md). ### Other Implementations diff --git a/concepts/evm/evm.md b/concepts/evm/evm.md index bdc022a..84ed44f 100644 --- a/concepts/evm/evm.md +++ b/concepts/evm/evm.md @@ -1,8 +1,8 @@ # Ethereum Virtual Machine (EVM) -You can browse [all EVM pages](/evm/all), and here are selected top picks: +You can browse [all EVM pages](/concepts/evm/evm.md), and here are selected top picks: -* [List of EVM implementations](/evm/implementations) +* [List of EVM implementations](/concepts/evm/implementations.md) ## EVM Awesome List @@ -14,7 +14,7 @@ A curated list of resources on the Ethereum Virtual Machine (EVM), which is the Not listed there yet, but in the spirit of [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome) -Here is [how to contribute](../../governance/contributing.md). +Here is [how to contribute](/governance/contributing.md). ## Specification @@ -38,7 +38,7 @@ Here is [how to contribute](../../governance/contributing.md). - A hands on guide to understanding how the EVM works, with examples written in raw byte-code and solidity * [Diving Into The Ethereum Virtual Machine](https://medium.com/@hayeah/diving-into-the-ethereum-vm-6e8d5d2f3c30) - An article series examining different aspects of the EVM by walking you through Solidity's assembly output -* [Consensus Datastructures](../../fundamentals/specs/consensus-datastructures.md) +* [Consensus Datastructures](/fundamentals/specs/consensus-datastructures.md) ## Tests @@ -61,7 +61,7 @@ Here is [how to contribute](../../governance/contributing.md). - A Python implementation designed to be highly configurable and modular and compliant with the Ethereum test suite, work is in progress on it to run a full node and develop sharding. * [EthereumJ](https://github.com/ethereum/ethereumj) in Java - A client with its own EVM implementation -* For more, see [here](../../clients/clients-tools-dapp-browsers-wallets-and-other-projects.md). +* For more, see [here](/clients/clients-tools-dapp-browsers-wallets-and-other-projects.md). ### Other Implementations diff --git a/concepts/evm/implementations.md b/concepts/evm/implementations.md index 2c87334..f451c26 100644 --- a/concepts/evm/implementations.md +++ b/concepts/evm/implementations.md @@ -1,7 +1,7 @@ -All the ETH1 Clients include an EVM implementation, so they are copy-pasted from the [source page](/eth1/clients) for convenience. +All the ETH1 Clients include an EVM implementation, so they are copy-pasted from the [source page](/eth1/clients.md) for convenience. |Client Name|Organization|Programming Language|License| |---|---|---|---| diff --git a/concepts/light-client-protocol.md b/concepts/light-client-protocol.md index 7f5f319..3ac6184 100644 --- a/concepts/light-client-protocol.md +++ b/concepts/light-client-protocol.md @@ -9,7 +9,7 @@ The purpose of the light client protocol is to allow users in low-capacity envir ## Background: Patricia Merkle Trees -All substantial quantities of data in Ethereum are stored in a data structure known as the [Patricia Merkle tree](../fundamentals/patricia-tree.md), a tree structure where each node in the tree is the hash of its children. Each set of key/value pairs maps to a unique root hash, and only a small subset of nodes is needed to prove that a particular key/value combination is in the tree corresponding to a particular root hash. +All substantial quantities of data in Ethereum are stored in a data structure known as the [Patricia Merkle tree](/fundamentals/patricia-tree.md), a tree structure where each node in the tree is the hash of its children. Each set of key/value pairs maps to a unique root hash, and only a small subset of nodes is needed to prove that a particular key/value combination is in the tree corresponding to a particular root hash. The size complexity of a Merkle proof scales linearly with the height of a tree; because each child in a tree has a particular number of children (in our case, up to 17), this means that the size complexity of a Merkle proof is logarithmic in the quantity of data stored. This means that, even if the entire state tree is a few gigabytes in size, if a node receives a state root from a trusted source that node has the ability to know with full certainty the validity of any information with the tree by only downloading a few kilobytes of data in a proof. diff --git a/concepts/proof-of-stake-faqs.md b/concepts/proof-of-stake-faqs.md old mode 100755 new mode 100644 index 169d1b0..f9eed45 --- a/concepts/proof-of-stake-faqs.md +++ b/concepts/proof-of-stake-faqs.md @@ -243,4 +243,4 @@ Generally, yes; any proof of stake algorithm can be used as a consensus algorith ## Further reading -- [Casper proof of stake compedium](./casper-proof-of-stake-compendium.md) +- [Casper proof of stake compedium](/concepts/casper-proof-of-stake-compendium.md) diff --git a/concepts/security-categorization.md b/concepts/security-categorization.md old mode 100755 new mode 100644 index 7b57e3c..4238827 --- a/concepts/security-categorization.md +++ b/concepts/security-categorization.md @@ -1,6 +1,6 @@ # Security Categorization -[See also](../fundamentals/design-rationale.md), for descriptions of potentially counterintuitive design decisions in Ethereum. +[See also](/fundamentals/design-rationale.md), for descriptions of potentially counterintuitive design decisions in Ethereum. The purpose of this document is to attempt to create a taxonomy of key security properties that we are targeting for the Ethereum protocol, implementation and materials to have at launch time, as well as provide supplementary information where needed for each one. @@ -13,7 +13,7 @@ The purpose of this document is to attempt to create a taxonomy of key security ## Proof of Work -The working spec description of Dagger Hashimoto is available [here](./ethash/ethash.md). +The working spec description of Dagger Hashimoto is available [here](/concepts/ethash/ethash.md). The algorithm is intended to have the following key properties: @@ -70,7 +70,7 @@ The following properties are desired: ## Wire protocol -The wire protocol is described [here](./whisper/poc-2-wire-protocol.md). +The wire protocol is described [here](/concepts/whisper/poc-2-wire-protocol.md). The wire protocol should be secure against the following issues: diff --git a/concepts/standardized-contract-apis.md b/concepts/standardized-contract-apis.md old mode 100755 new mode 100644 index 4b12d14..34679b1 --- a/concepts/standardized-contract-apis.md +++ b/concepts/standardized-contract-apis.md @@ -10,7 +10,7 @@ tags: **NOTE** The token API is currently debated as an ERC (Ethereum request for comment) and may be outdated: -Although Ethereum allows developers to create absolutely any kind of application without restriction to specific feature types, and prides itself on its "lack of features", there is nevertheless a need to standardize certain very common use cases in order to allow users and applications to more easily interact with each other. This includes sending currency units, registering names, making offers on exchanges, and other similar functions. A standard typically consists of a set of function signatures for a few methods, eg. `send`, `register`, `delete`, providing the set of arguments and their formats in the [Ethereum contract ABI](Ethereum-Contract-ABI) language. +Although Ethereum allows developers to create absolutely any kind of application without restriction to specific feature types, and prides itself on its "lack of features", there is nevertheless a need to standardize certain very common use cases in order to allow users and applications to more easily interact with each other. This includes sending currency units, registering names, making offers on exchanges, and other similar functions. A standard typically consists of a set of function signatures for a few methods, eg. `send`, `register`, `delete`, providing the set of arguments and their formats in the [Ethereum contract ABI](/archive/ethereum-contract-abi.md) language. The standards described below have sample implementations available [here](https://github.com/ethereum/dapp-bin/tree/master/standardized_contract_apis). diff --git a/concepts/url-hint-protocol.md b/concepts/url-hint-protocol.md old mode 100755 new mode 100644 diff --git a/concepts/whisper/overview.md b/concepts/whisper/overview.md old mode 100755 new mode 100644 diff --git a/concepts/whisper/poc-2-protocol-spec.md b/concepts/whisper/poc-2-protocol-spec.md old mode 100755 new mode 100644 index fce71b0..127e1fa --- a/concepts/whisper/poc-2-protocol-spec.md +++ b/concepts/whisper/poc-2-protocol-spec.md @@ -102,7 +102,7 @@ In the Javascript API, the distinction between envelopes and messages is blurred ## Basic Operation -Nodes are expected to receive and send envelopes continuously, as per the [protocol specification](Whisper-Wire-Protocol). They should maintain a map of envelopes, indexed by expiry time, and prune accordingly. They should also efficiently deliver messages to the front-end API through maintaining mappings between topics and envelopes. +Nodes are expected to receive and send envelopes continuously, as per the [protocol specification](/concepts/whisper/poc-2-protocol-spec.md). They should maintain a map of envelopes, indexed by expiry time, and prune accordingly. They should also efficiently deliver messages to the front-end API through maintaining mappings between topics and envelopes. When a node's envelope memory becomes exhausted, a node may drop envelopes it considers unimportant or unlikely to please its peers. Nodes should consider peers good that pass them envelopes with low TTLs and high proofs-of-work. Nodes should consider peers bad that pass then expired envelopes or, worse, those that have an implied insertion time prior to the present. diff --git a/concepts/whisper/poc-2-wire-protocol.md b/concepts/whisper/poc-2-wire-protocol.md old mode 100755 new mode 100644 index 459b275..b97a47a --- a/concepts/whisper/poc-2-wire-protocol.md +++ b/concepts/whisper/poc-2-wire-protocol.md @@ -6,7 +6,7 @@ date: 2020-06-16T08:36:00.099Z tags: --- -Peer-to-peer communications between nodes running Whisper clients run using the underlying [ÐΞVp2p Wire Protocol](%C3%90%CE%9EVp2p-Wire-Protocol). +Peer-to-peer communications between nodes running Whisper clients run using the underlying [ÐΞVp2p Wire Protocol](/archive/%C3%90%CE%9EVp2p-Wire-Protocol.md). This is a preliminary wire protocol for the Whisper subsystem. It will change. diff --git a/concepts/whisper/whisper-overview.md b/concepts/whisper/whisper-overview.md old mode 100755 new mode 100644 diff --git a/concepts/whisper/whisper.md b/concepts/whisper/whisper.md old mode 100755 new mode 100644 diff --git a/concepts/whisper/wire-protocol.md b/concepts/whisper/wire-protocol.md old mode 100755 new mode 100644 index 566f2fe..21720b6 --- a/concepts/whisper/wire-protocol.md +++ b/concepts/whisper/wire-protocol.md @@ -6,7 +6,7 @@ date: 2020-06-16T08:33:19.683Z tags: --- -Peer-to-peer communications between nodes running Whisper clients run using the underlying [ÐΞVp2p Wire Protocol](%C3%90%CE%9EVp2p-Wire-Protocol). +Peer-to-peer communications between nodes running Whisper clients run using the underlying [ÐΞVp2p Wire Protocol](/archive/%C3%90%CE%9EVp2p-Wire-Protocol.md). This is a preliminary wire protocol for the Whisper subsystem. It will change. diff --git a/concepts/wishlist.md b/concepts/wishlist.md old mode 100755 new mode 100644 index cb7b181..764f8d7 --- a/concepts/wishlist.md +++ b/concepts/wishlist.md @@ -11,10 +11,10 @@ tags: This document outlines known flaws and missing features in current versions of Ethereum that we would like to see fixed in future versions. For the latest information, see [ethresear.ch](https://ethresear.ch/). ## Sharding -Read [Sharding-FAQs](/sharding/Sharding-FAQs) +Read [Sharding-FAQs](/sharding/Sharding-FAQs.md) ## Proof of Stake -Read [proof-of-stake-faqs](/concepts/proof-of-stake-faqs) +Read [proof-of-stake-faqs](/concepts/proof-of-stake-faqs.md) ## Trie @@ -24,7 +24,7 @@ The current trie has the following known problems: - RLP is complex (see below) and slows down serialization/deserialization time, especially in slow interpreted language implementations (e.g. Python). - Because the trie is hexary and not binary, the size of a Merkle branch of any value is ~3.75x longer than needed. Because our Merkle branch encoding is suboptimal, this increases to 4x. This is because in a binary tree with 2^n key/value pairs, the size of a node is 64 bytes, and there are n nodes in a branch, so a naive Merkle branch will be 64_n bytes long. If we make the optimization of not storing the part of each node that is simply the hash of the next node, this decreases to 32 _ n. In a hexary tree, each node is 512 bytes, and there are n/4 nodes in a branch, so a naive Merkle branch is 512 \_ n/4 = 128_n bytes long. The de-duplication optimization reduces this to 120\*n. Practically speaking, this means that in a trie with 1 billion key/value pairs, an optimal Merkle branch would be 960 bytes long, but ours is 3840 bytes (plus more due to overhead). The trie was originally done in a hexary format to reduce the number of required database lookups to fetch a value, but these gains can be achieved in a different way by clumping together nearby trie nodes when they get stored in the database. -A possible solution is to switch to a binary trie. See an implementation [here](https://github.com/ethereum/research/tree/master/trie_research), as well as [sharding account redesign](Wishlist#parallelization) below. +A possible solution is to switch to a binary trie. See an implementation [here](https://github.com/ethereum/research/tree/master/trie_research), as well as [sharding account redesign](wishlist.md#parallelization) below. ## More expressive Merkle trees @@ -47,7 +47,7 @@ This can be improved by allowing transactions to statically declare what portion See: - EIP 648: -- Sharding account redesign: . This also relates to [tries as above](Wishlist#trie). +- Sharding account redesign: . This also relates to [tries as above](wishlist.md#trie). ## Pre-fetchability and Stateless Client Support @@ -77,7 +77,7 @@ There is a mismatch between storage filling gas cost and the externality the sto There should ideally be some mechanism by which one can create events that trigger automatically at certain times in the future, without any overlay protocols (as one simple application of this, consider a dice game that depends on future block data as a source of randomness). For this to work effectively, one must introduce an "event tree" into the Ethereum state alongside the state tree, and add specialized opcodes for creating events (events can be seen as one-way calls that get "frozen" and then executed in the future). A mechanism for gas costs for events, particularly recurring events, should be determined. -See "what are guaranteed cross-shard calls" for some discussion in the context of sharding read [Sharding-FAQs](/sharding/Sharding-FAQs). +See "what are guaranteed cross-shard calls" for some discussion in the context of sharding read [Sharding-FAQs](/sharding/Sharding-FAQs.md). ## Verification diff --git a/enterprise/enterprise.md b/enterprise/enterprise.md index 1dd2ab4..a433a2c 100644 --- a/enterprise/enterprise.md +++ b/enterprise/enterprise.md @@ -10,4 +10,4 @@ tags: Welcome to the Ethereum Wiki Enterprise section! -* [Why use Mainnet for enterprise applications](/enterprise/whymainnet) \ No newline at end of file +* [Why use Mainnet for enterprise applications](/enterprise/whymainnet.md) \ No newline at end of file diff --git a/enterprise/whymainnet.md b/enterprise/whymainnet.md index 7b583b9..0c6392f 100644 --- a/enterprise/whymainnet.md +++ b/enterprise/whymainnet.md @@ -17,4 +17,4 @@ tags: Slightly more, but not by much. Often your biggest privacy risks are from the organizations that would be part of your consortium chain (they are your biggest competitors and most motivated to glean information from your chain data!). > **Is Mainnet able to handle our transaction volume?** -Varies. It gets more complicated, but there is a variety of Layer2 scaling solutions such as the work from [Plasma Group](https://plasma.group/). \ No newline at end of file +Varies. It gets more complicated, but there is a variety of Layer2 scaling solutions such as the work from [Plasma Group](https://plasma.group/)(dead link). \ No newline at end of file diff --git a/eth1/clients.md b/eth1/clients.md index ff65f79..2252231 100644 --- a/eth1/clients.md +++ b/eth1/clients.md @@ -24,7 +24,7 @@ tags: Sourced in part from the [Constantinople Progress Tracker](https://github.com/ethereum/pm/wiki/Constantinople-Progress-Tracker). See also: -* [older list of client tools, dapp browsers, wallets, and other projects](/clients-tools-dapp-browsers-wallets-and-other-projects) +* [older list of client tools, dapp browsers, wallets, and other projects](/clients/clients-tools-dapp-browsers-wallets-and-other-projects.md) * [ETH2 Clients](/eth2/clients) - Beacon Chain implementations to date --- diff --git a/eth1/coredevsberlin.md b/eth1/coredevsberlin.md index 0085b4d..254eeb9 100644 --- a/eth1/coredevsberlin.md +++ b/eth1/coredevsberlin.md @@ -1,7 +1,7 @@ -Two days of meetings were held at Full Node in Berlin to discuss the [Istanbul hardfork](/roadmap/istanbul) and more broadly the [ETH1x roadmap](/roadmap) and processes and collaboration. +Two days of meetings were held at Full Node in Berlin to discuss the [Istanbul hardfork](/roadmap/istanbul.md) and more broadly the [ETH1x roadmap](/roadmap/roadmap.md) and processes and collaboration. Original [ETHMagicians thread](https://ethereum-magicians.org/t/istanbul-eth1x-roadmap-planning-meeting-april-17th-18th-in-berlin/2899). diff --git a/eth1/eth1.md b/eth1/eth1.md index 5436a96..53e2da1 100644 --- a/eth1/eth1.md +++ b/eth1/eth1.md @@ -8,7 +8,7 @@ tags: This is the current "version" of Ethereum. [EthHub has extensive information and background on ETH1x](https://docs.ethhub.io/ethereum-roadmap/ethereum-1.x/). -You may also want to review the [roadmap](/roadmap), or view [all Eth1 pages](/eth1/all). +You may also want to review the [roadmap](/roadmap/roadmap.md). # Working Groups A list of current working groups focused on core research, upgrades, and challenges. @@ -77,6 +77,5 @@ Ongoing infrastructure focus areas for coordinating work & support on the core n # Meetings * July 2019? -* April 17-18th, 2019 [Core Devs Berlin](/eth1/coredevsberlin) - feedback and poll on July meeting https://ethereum-magicians.org/t/coredevs-eth1x-istanbul-meeting-july-poll-feedback/3197 +* April 17-18th, 2019 [Core Devs Berlin](/eth1/coredevsberlin.md) - feedback and poll on July meeting https://ethereum-magicians.org/t/coredevs-eth1x-istanbul-meeting-july-poll-feedback/3197 * February 2020 ETH1x Roadmap AMA [notes & video on EthMagicians](https://ethereum-magicians.org/t/eth-roadmap-ama-webinar-feb-6th-8am-pst-1700-utc-1/2518) -* January 2019 [Core Devs Stanford](/eth1/coredevsstanford) diff --git a/eth2/eth2.md b/eth2/eth2.md index 12a663f..1cec4e6 100644 --- a/eth2/eth2.md +++ b/eth2/eth2.md @@ -5,7 +5,6 @@ The best starting point for technical ETH2 info is: * Specs https://github.com/ethereum/eth2.0-specs * Project Management https://github.com/ethereum/eth2.0-pm -Also: [Browse all ETH2 pages](/eth2/all) # FAQ Frequently Asked Questions about ETH2. Feel free to create a sub-page if your answers are long. diff --git a/faqs/famous-bugs.md b/faqs/famous-bugs.md index 0df65ed..5b8a3f0 100644 --- a/faqs/famous-bugs.md +++ b/faqs/famous-bugs.md @@ -8,7 +8,7 @@ tags: # Famous Bugs -Bugs that resulted in lost or stuck funds have been moved to [here](./major-issues-resulting-in-lost-or-stuck-funds.md). +Bugs that resulted in lost or stuck funds have been moved to [here](/faqs/major-issues-resulting-in-lost-or-stuck-funds.md). ## Geth Consensus Bug > On 2016-11-24, a consensus bug occurred due to two implementations having different behavior in the case of state reverts. [3](https://blog.ethereum.org/2016/11/25/security-alert-11242016-consensus-bug-geth-v1-4-19-v1-5-2/). The specification was amended to clarify that empty account deletions are reverted when the state is reverted... Details: Geth was failing to revert empty account deletions when the transaction causing the deletions of empty accounts ended with an an out-of-gas exception. An additional issue was found in Parity, where the Parity client incorrectly failed to revert empty account deletions in a more limited set of contexts involving out-of-gas calls to precompiled contracts; the new Geth behavior matches Parity’s, and empty accounts will cease to be a source of concern in general in about one week once the state clearing process finishes. [The source is here.](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-161.md#addendum-2017-08-15) diff --git a/faqs/faqs.md b/faqs/faqs.md index 901c5ed..d67316a 100644 --- a/faqs/faqs.md +++ b/faqs/faqs.md @@ -6,7 +6,7 @@ ## What is Ethereum? -There are several ways to answer this question, such as [here](./fundamentals/ethereum-introduction.md), as well as the dedicated [What is Ethereum](./fundamentals/what-is-ethereum.md) wiki page, which was made at the time of the Frontier release, so it is outdated. +There are several ways to answer this question, such as [here](/fundamentals/ethereum-introduction.md), as well as the dedicated [What is Ethereum](/fundamentals/what-is-ethereum.md) wiki page, which was made at the time of the Frontier release, so it is outdated. If you prefer to learn by watching videos, see: @@ -17,7 +17,7 @@ If you prefer to learn by watching videos, see: ## How do I buy Ether or ETH? -Read [this](../fundamentals/ethereum-introduction.md#how-do-you-buy-and-sell-ether-the-currency-of-ethereum). +Read [this](/fundamentals/ethereum-introduction.md#how-do-you-buy-and-sell-ether-the-currency-of-ethereum). ## Where can I learn more about Ethereum? @@ -48,8 +48,8 @@ Read [this](../fundamentals/ethereum-introduction.md#how-do-you-buy-and-sell-eth ## Where can I learn about the Ether sale and mining? -- [The Ether Sale FAQ](https://forum.ethereum.org/discussion/196/the-ether-sale-faq/p1) -- [The Mining FAQ](https://forum.ethereum.org/discussion/197/mining-faq-live-updates/p1) +- [The Ether Sale FAQ](https://forum.ethereum.org/discussion/196/the-ether-sale-faq/p1)(dead link) +- [The Mining FAQ](https://forum.ethereum.org/discussion/197/mining-faq-live-updates/p1)(dead link) ## Wallets @@ -84,8 +84,8 @@ Other: - [Homebrew Ethereum](https://github.com/caktux/homebrew-ethereum) ([@caktux](https://github.com/caktux)) - Guides - [eth/AlethZero super easy install guide for OSX](https://forum.ethereum.org/discussion/1388/alethzero-super-easy-install-guide-for-osx) ([@stephantual](https://github.com/stephantual)) - - [Go-Ethereum simple build guide for OSX](http://forum.ethereum.org/discussion/905/go-ethereum-cli-ethereal-simple-build-guide-for-osx-now-with-one-line-install) ([@stephantual](https://github.com/stephantual)) - - [Building on Ubuntu](https://github.com/ethereum/cpp-ethereum/wiki/Building-on-Ubuntu#user-content-trusty-1404) + - [Go-Ethereum simple build guide for OSX](http://forum.ethereum.org/discussion/905/go-ethereum-cli-ethereal-simple-build-guide-for-osx-now-with-one-line-install) ([@stephantual](https://github.com/stephantual))(dead link) + - [Building on Ubuntu](https://github.com/ethereum/cpp-ethereum/wiki/Building-on-Ubuntu#user-content-trusty-1404)(dead link) - Builds - [Ethdev Buildbot](http://build.ethdev.com/waterfall) @@ -120,7 +120,7 @@ With the eth client ### Where can I learn about contract development? - Articles - - [Ethereum Development Tutorial](../howto/ethereum-development-tutorial.md) + - [Ethereum Development Tutorial](/howto/ethereum-development-tutorial.md) - Videos - [Ethereum](https://www.youtube.com/user/ethereumproject/videos) - [EtherCasts](https://www.youtube.com/user/EtherCasts/videos) @@ -128,7 +128,7 @@ With the eth client ### Where can I learn Serpent, the Python-like language? - Specifications - - [The Serpent Language](Serpent) + - [The Serpent Language](/archive/serpent.md) - Examples - [Vitalik's Serpent examples](https://github.com/ethereum/serpent/tree/master/examples) - Tutorials @@ -177,7 +177,7 @@ With the eth client - [The PoC 6 API for C++](https://github.com/ethereum/cpp-ethereum/wiki/Client-Development-with-PoC-6) - [The PoC 5 API for Go](https://github.com/ethereum/go-ethereum/wiki/PoC-5-Public-Go-API) - [The PoC 6 API for QML](https://github.com/ethereum/go-ethereum/wiki/QML-PoC6-API) -- [The PoC 7 API for JavaScript](https://github.com/ethereum/wiki/wiki/JavaScript-API) +- [The PoC 7 API for JavaScript](/archive/javascript-api.md) ### Where can I learn about ÐApp development? @@ -193,7 +193,7 @@ Official - [Ethereum command-line client (Go)](https://github.com/ethereum/go-ethereum/wiki/Command-Line-Options) - [Mist Browser (Go)](https://github.com/ethereum/go-ethereum) - [Pyeth command-line client (Python)](https://github.com/ethereum/pyethereum#interacting-with-the-network) -- [Serpent Compiler (Python)](Serpent) +- [Serpent Compiler (Python)](/archive/serpent.md) Community diff --git a/faqs/glossary.md b/faqs/glossary.md index cd7c971..7741ba7 100644 --- a/faqs/glossary.md +++ b/faqs/glossary.md @@ -34,7 +34,7 @@ See also: See also: -- **Serialization**: the process of converting a data structure into a sequence of bytes. Ethereum internally uses an encoding format called recursive-length prefix encoding (RLP), described [here](../fundamentals/rlp.md) +- **Serialization**: the process of converting a data structure into a sequence of bytes. Ethereum internally uses an encoding format called recursive-length prefix encoding (RLP), described [here](/fundamentals/rlp.md) - **Patricia tree** (or **trie**): a data structure which stores the state of every account. The trie is built by starting from each individual node, then splitting the nodes into groups of up to 16 and hashing each group, then making hashes of hashes and so forth until there is one final "root hash" for the entire trie. The trie has the important properties that (1) there is exactly one possible trie and therefore one possible root hash for each set of data, (2) it is very easy to update, add or remove nodes in the trie and generate the new root hash, (3) there is no way to modify any part of the tree without changing the root hash, so if the root hash is included in a signed document or a valid block the signature or proof of work secures the entire tree, and (4) one can provide just the "branch" of a tree going down to a particular node as cryptographic proof that that node is indeed in the tree with that exact content. Patricia trees are also used to store the internal storage of accounts as well as transactions and ommers. See [here](http://easythereentropy.wordpress.com/2014/06/04/understanding-the-ethereum-trie/) for a more detailed description. - **Uncle**: See **Ommer**, the gender-neutral alternative to aunt/uncle. - **Ommer**: a child of a parent of a parent of a block that is not the parent, or more generally a child of an ancestor that is not itself an ancestor. If A is an ommer of B, B is a **nibling** (niece/nephew) of A. @@ -50,7 +50,7 @@ See also: ## Casper and scaling research -See [proof of stake FAQs](../concepts/proof-of-stake-faqs.md) and [sharding FAQs](../sharding/sharding-faqs.md). +See [proof of stake FAQs](/concepts/proof-of-stake-faqs.md) and [sharding FAQs](/sharding/Sharding-FAQs.md). - **Security deposit**: a quantity of ether that a user deposits into a mechanism (often a proof of stake consensus mechanism, though this can also be used for other applications) that a user normally expects to be able to eventually withdraw and recover, but which can be taken away in the event of malfeasance from the user's side. - **Validator**: a participant in proof of stake consensus. Validators need to submit a security deposit in order to get included in the validator set. diff --git a/fundamentals/dapp-developer-resources.md b/fundamentals/dapp-developer-resources.md index 0655777..ec05a67 100644 --- a/fundamentals/dapp-developer-resources.md +++ b/fundamentals/dapp-developer-resources.md @@ -4,22 +4,22 @@ As a Ðapp developer you have three main resources which allow Ðapp development ## Main Resources -- [Web3 JavaScript API](JavaScript-API) - This is the main JavaScript SDK to use when you want to interact with a nodes API -- [JSON RPC API](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://web3js.readthedocs.io/en/v1.2.9/index.html). +- [Web3 JavaScript API](/archive/javascript-api.md) - This is the main JavaScript SDK to use when you want to interact with a nodes API +- [JSON RPC API](/json-rpc/api.md) - 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://web3js.readthedocs.io/en/v1.2.9/index.html). - [Solidity Documentation](https://solidity.readthedocs.org/en/latest/) - Solidity is the Ethereum-developed Smart Contract language, which compiles to EVM (Ethereum Virtual Machine) opcodes. - [Remix IDE](http://remix.ethereum.org/) - Solidity editor in the browser that helps efficient writing, debugging and deploying contracts - [Dapp Insight](https://dappinsight.com) - This is a most popular Dapp analytics tool which listing all the running Dapps in the world with their true usage data. ## Other Resources: -- [Standardized Contract APIs](Standardized_Contract_APIs) - Standard contract API, which should be used to make some contract types accessible by other Ðapps. (Not yet finalised) -- [Useful Ðapp Patterns](Useful-Ðapp-Patterns) - Code snippets which are useful for Ðapp development. -- [Dapp using Meteor](Dapp-using-Meteor) - This short tutorial gives an intro on how to start building a Ðapp using [Meteor](https://www.meteor.com), and also why Meteor is a good fit for Ðapps. +- [Standardized Contract APIs](/concepts/standardized-contract-apis.md) - Standard contract API, which should be used to make some contract types accessible by other Ðapps. (Not yet finalised) +- [Useful Ðapp Patterns](/concepts/useful-dapp-patterns.md) - Code snippets which are useful for Ðapp development. +- [Dapp using Meteor](/howto/dapp-using-meteor.md) - This short tutorial gives an intro on how to start building a Ðapp using [Meteor](https://www.meteor.com), and also why Meteor is a good fit for Ðapps. ## Useful read -- [FAQs](FAQs) - Collection of links, useful for understanding the Ethereum eco system. -- [Glossary](Glossary) - Great explanation of Blockchain related terms. +- [FAQs](/faqs/faqs.md) - Collection of links, useful for understanding the Ethereum eco system. +- [Glossary](/faqs/glossary.md) - Great explanation of Blockchain related terms. ## Gitter Chats diff --git a/fundamentals/dapp-development.md b/fundamentals/dapp-development.md index ba9f734..54b91fb 100644 --- a/fundamentals/dapp-development.md +++ b/fundamentals/dapp-development.md @@ -15,14 +15,14 @@ ## Miscellaneous resources and info -- [Safety](../howto/smart-contract-safety.md) -- [ÐApp Developer Resources](../fundamentals/dapp-developer-resources.md) +- [Safety](/howto/smart-contract-safety.md) +- [ÐApp Developer Resources](/fundamentals/dapp-developer-resources.md) - [JavaScript API](https://web3js.readthedocs.io/en/v1.2.9/index.html) -- [JSON RPC API](../json-rpc/api.md) -- [Useful Ðapp Patterns](https://github.com/ethereum/wiki/wiki/Useful-Ðapp-Patterns) -- [Standardized Contract APIs](../concepts/standardized-contract-apis.md) -- [Ethereum development tutorial](../howto/ethereum-development-tutorial.md) -- [ÐApp using Meteor](../howto/dapp-using-meteor.md) +- [JSON RPC API](/json-rpc/api.md) +- [Useful Ðapp Patterns](/concepts/useful-dapp-patterns.md) +- [Standardized Contract APIs](/concepts/standardized-contract-apis.md) +- [Ethereum development tutorial](/howto/ethereum-development-tutorial.md) +- [ÐApp using Meteor](/howto/dapp-using-meteor.md) - [Dapp Insight: dapp statistics](https://dappinsight.com) diff --git a/fundamentals/decentralized-apps-dapps.md b/fundamentals/decentralized-apps-dapps.md index e9ccaca..0578434 100755 --- a/fundamentals/decentralized-apps-dapps.md +++ b/fundamentals/decentralized-apps-dapps.md @@ -15,18 +15,18 @@ tags: Want to see live uses of Ethereum? Just download a dapp (decentralised app) browser such as [Trust Wallet](https://play.google.com/store/apps/details?id=com.wallet.crypto.trustapp), [Cipher](https://play.google.com/store/apps/details?id=com.cipherbrowser.cipher) or [Coinbase Wallet](https://play.google.com/store/apps/details?id=org.toshi) and browse away! -Any good, service, governance or economic activity can be decentralized and tokenized with and transacted via Ethereum. The token represents the dapp (an abbreviation for decentralized app) while it uses the Ethereum blockchain, but the price of the token is different. Alternatively, a dapp may not have a token, and may thus be funded by other means (e.g. as listed [here](https://github.com/ethereum/wiki/wiki/Grants-and-funding-sources)) than selling tokens via an ICO (Initial Coin Offering) or ITO (Initial Token Offering), [DAICO](https://ethresear.ch/search?q=DAICO) (Decentralized Autonomous Initial Coin Offering), or [iterative investment](https://ethresear.ch/t/daico-and-iterative-investment/1052). Note that ideally, if someone is using a dapp, a user should not be able to tell that they are, i.e., a dapp should ideally not require any extra effort from a person using it, compared to a web 2.0 app (like e.g. Facebook, email web clients like Gmail and Protonmail, Twitter, etc.). Activity that has any economic or governance aspect, conceived or as of yet inconceived, can be done via Ethereum, provided that the right code is written and the necessary hardware or other required things are used (such as computers running an Ethereum node, and in some special cases, a measurement device to measure a resource flow for additional verification/auditable purposes, like a meter for electricity ⚡🔌, water 🚰 or gas 🔥; or a waste 🗑️ volume detector). +Any good, service, governance or economic activity can be decentralized and tokenized with and transacted via Ethereum. The token represents the dapp (an abbreviation for decentralized app) while it uses the Ethereum blockchain, but the price of the token is different. Alternatively, a dapp may not have a token, and may thus be funded by other means (e.g. as listed [here](/funding/funding.md)) than selling tokens via an ICO (Initial Coin Offering) or ITO (Initial Token Offering), [DAICO](https://ethresear.ch/search?q=DAICO) (Decentralized Autonomous Initial Coin Offering), or [iterative investment](https://ethresear.ch/t/daico-and-iterative-investment/1052). Note that ideally, if someone is using a dapp, a user should not be able to tell that they are, i.e., a dapp should ideally not require any extra effort from a person using it, compared to a web 2.0 app (like e.g. Facebook, email web clients like Gmail and Protonmail, Twitter, etc.). Activity that has any economic or governance aspect, conceived or as of yet inconceived, can be done via Ethereum, provided that the right code is written and the necessary hardware or other required things are used (such as computers running an Ethereum node, and in some special cases, a measurement device to measure a resource flow for additional verification/auditable purposes, like a meter for electricity ⚡🔌, water 🚰 or gas 🔥; or a waste 🗑️ volume detector). -One kind of application that is particularly intriguing is decentralized autonomous organisations (**DAOs**); this includes entities as large as, or even larger than nation-states 🇦🇺🇺🇸🇮🇳🇬🇧🇨🇳🇧🇷🇷🇺🇯🇵, social networks, multinational public companies, etc.). Note that having complete autonomy is probably not a good idea, since code may not be able to handle new issues that arise, so human intervention should probably always be an option, but preferably in the hands of a small, non-profit entity or some decentralized solution (perhaps similar to the Aragon Network). See [governance](https://github.com/ethereum/wiki/wiki/Governance-compendium) for more info. By analogy, you wouldn't want a nuclear power plant to be completely automated with no possible means of human intervention. As a precaution, you'd want several safeguards including, for example, an off button. 😉 As explained in this Ethereum Wiki here, the first DAO, known as The DAO, resulted in many funds being stolen, and Ethereum hard forking into Ethereum and Ethereum Classic. +One kind of application that is particularly intriguing is decentralized autonomous organisations (**DAOs**); this includes entities as large as, or even larger than nation-states 🇦🇺🇺🇸🇮🇳🇬🇧🇨🇳🇧🇷🇷🇺🇯🇵, social networks, multinational public companies, etc.). Note that having complete autonomy is probably not a good idea, since code may not be able to handle new issues that arise, so human intervention should probably always be an option, but preferably in the hands of a small, non-profit entity or some decentralized solution (perhaps similar to the Aragon Network). See [governance](/governance/governance-compendium) for more info. By analogy, you wouldn't want a nuclear power plant to be completely automated with no possible means of human intervention. As a precaution, you'd want several safeguards including, for example, an off button. 😉 As explained in this Ethereum Wiki here, the first DAO, known as The DAO, resulted in many funds being stolen, and Ethereum hard forking into Ethereum and Ethereum Classic. ## List -The following list is sourced from [Coin Market Cap tokens (you can sort by market cap)](https://coinmarketcap.com/tokens/) and State of the Dapps, both of which lists many more, as well as elsewhere, e.g. Gitter research room chats. ([Dapp Insight](https://dappinsight.com) was added later but in addition to State of the Dapps, gives stats on live dapps.) There are 854 dapps on State of the Dapps as of Dec 1 2017; then [909 on Jan 1 2018] (https://web.archive.org/web/20180101114436/https://www.stateofthedapps.com/). 😯 You can search by tags. Other examples are also presented e.g. on day 4 of [Devcon 3](http://www.ryanyosua.me/devcon-3-talks/), as well as outlined in the Ethereum whitepaper in the introduction and applications section. Note also that while most of the dapps in the following list run on the Ethereum platform, some examples do not, and where they don't run on Ethereum, it is generally noted as what they do run on. This is not a big deal, as any dapp could theoretically run on another blockchain, (or indirectly via inter-blockchains like Cosmos or Polkadot) provided that the host blockchain has the required features. Also note that the below list is not an endorsement, and is not exhaustive or necessarily well-maintained. At worst, it's included because it was briefly looked into and it seemed like a good idea, while more time may have been spent doing due diligence on some ideas and can therefore have a better idea of its usefulness. Dapps that have been implemented, or are under development, or have been publicly conceptualised, includes: +The following list is sourced from [Coin Market Cap tokens (you can sort by market cap)](https://coinmarketcap.com/tokens/) and State of the Dapps, both of which lists many more, as well as elsewhere, e.g. Gitter research room chats. ([Dapp Insight](https://dappinsight.com) was added later but in addition to State of the Dapps, gives stats on live dapps.) There are 854 dapps on State of the Dapps as of Dec 1 2017; then [909 on Jan 1 2018] (https://web.archive.org/web/20180101114436/https://www.stateofthedapps.com/). 😯 You can search by tags. Other examples are also presented e.g. on day 4 of [Devcon 3](http://www.ryanyosua.me/devcon-3-talks/), as well as outlined in the Ethereum whitepaper in the introduction and applications section. Note also that while most of the dapps in the following list run on the Ethereum platform, some examples do not, and where they don't run on Ethereum, it is generally noted as what they do run on. This is not a big deal, as any dapp could theoretically run on another blockchain, (or indirectly via inter-blockchains like Cosmos or Polkadot) provided that the host blockchain has the required features. Also note that the below list is not an endorsement, and is not exhaustive or necessarily well-maintained. At worst, it's included because it was briefly looked into and it seemed like a good idea, while more time may have been spent doing due diligence on some ideas and can therefore have a better idea of its usefulness. Dapps that have been implemented, or are under development, or have been publicly conceptualised, includes: * [Tenzorum](https://tenzorum.org/). "Tenzorum is the portal to use the web of the future in your devices, today. It allows you to get the full benefits of decentralization without compromising on user-experience or security." This is really important for usability and scalability. * [Skraps](https://dashboard.skraps.io/?ref=8278838008f786e1c017acf2), an investment platform that keeps things simple, allowing users to invest spare change from everyday transactions into cryptocurrencies. It also allows cryptocurrency investors to become portfolio managers, getting additional income when other investors look at and use their portfolio. It makes it easier for investors to diversify. * a stable coin, e.g. [Synthetix](https://www.synthetix.io/), [Dai](https://makerdao.com/whitepaper/DaiDec17WP.pdf), and [Tether](https://tether.to/); @@ -34,7 +34,7 @@ The following list is sourced from [Coin Market Cap tokens (you can sort by mark * [Veritaseum](http://veritas.veritaseum.com/), which "enables software-driven P2P capital markets without brokerages, banks and traditional exchanges". * [tokens denominated against ethical investment fund portfolios](https://twitter.com/JamesCRay01/status/1046893184800841728) * [invoice financing with Populous](https://populous.co/) -* [decentralized exchanges](https://github.com/ethereum/wiki/wiki/Getting-Ether#trustless-services) to buy and sell cryptos and fiat, e.g. localethereum; for cryptos only there is Decentrex, Omega One and NVO, where the latter two have not been launched as of November 30. +* [decentralized exchanges](/fundamentals/getting-ether.md#trustless-services) to buy and sell cryptos and fiat, e.g. localethereum; for cryptos only there is Decentrex, Omega One and NVO, where the latter two have not been launched as of November 30. * non-decentralized exchanges such as [Coinbase](https://www.coinbase.com/) (US), [BTCmarkets](https://btcmarkets.net/) (Australia), while more are below, or ones that only exchange cryptocurrencies like Poloniex; * other exchanges like [OmiseGo](https://omisego.network/) and [Kyber Network](https://kyber.network/). "OmiseGO is a public Ethereum-based financial technology for use in mainstream digital wallets, that enables real-time, peer-to-peer value exchange and payment services agnostically across jurisdictions and organizational silos, and across both fiat money and decentralized currencies. Designed to enable financial inclusion and disrupt existing institutions, access will be made available to everyone via the OmiseGO network and digital wallet framework." "KyberNetwork is a new system which allows the exchange and conversion of digital assets. We provide rich payment APIs and a new contract wallet that allow anyone to seamlessly receive payments from any token. Users can also mitigate the risks of price fluctuations in the cryptocurrency world with our derivative trading."; * exchange platforms like [Binance](https://www.binance.com/aboutUs.html); @@ -43,14 +43,14 @@ The following list is sourced from [Coin Market Cap tokens (you can sort by mark * [MaidSafe](https://maidsafe.net/), which has another browser that actually runs on the [Omni](http://www.omnilayer.org/) layer that runs on Bitcoin, not Ethereum. It is also claiming to be: "The World's First Autonomous Data Network". [Currently you have to receive an invite which requires roughly an hour of interaction on their Discourse forum/site.](https://web.archive.org/web/20171230003420/https://invite.maidsafe.net/) * [ZeroNet](https://zeronet.io/), another decentralized internet network that runs on Bitcoin cryptography and the [BitTorrent network](http://www.bittorrent.com/). [It on Ubuntu 17.10](http://127.0.0.1:43110/Talk.ZeroNetwork.bit/?Topic:1514631579_13fVMZu2wTNAykEvkYHYfGmTBMSFxz9gFG/It+would+be+good+if+you+could+link+to+a+comment). You can make [your own site](http://127.0.0.1:43110/1zz1z8YPFQizJshGkgHq7GVtBSPCyQM5W/), although [you may have issues with following a tutorial](http://127.0.0.1:43110/Blog.ZeroNetwork.bit/?Post:99:ZeroChat+tutorial#comment_1_13fVMZu2wTNAykEvkYHYfGmTBMSFxz9gFG). Note that this link won't work unless you are running ZeroNet.sh) by clicking the download button on the homepage (then as detailed concisely below the button) extracting it and running (in bash) `./ZeroNet.sh` while `cd`ed to the extracted folder that ZeroNet.sh is located in. * storage, e.g. Swarm and a distributed hypermedia protocol, IPFS [website](https://ipfs.io/), [doc](https://github.com/ipfs/ipfs); -* communication protocols, e.g. Whisper (also see here for code), which allows dapps (you don't need to capitalize this since it is an abbreviation of decentralized applications) to communicate with each other; +* communication protocols, e.g. Whisper (also see here for code), which allows dapps (you don't need to capitalize this since it is an abbreviation of decentralized applications) to communicate with each other; * multi-chain networks/tools like [Polkadot](https://polkadot.io/) and [BTCRelay](http://btcrelay.org/) * Ethereum Name Service (names like jamesray.eth map to an address); * mesh networking e.g. implemented here and as voted for here on Twitter (which also has other ideas posted in the comments); * social networks e.g. Akasha (news here); * decentralized social news network: [Sapiens](https://tokensale.sapien.network); * Status: "A Mobile Ethereum OS: Browse, chat and make payments securely on the decentralized web."; -* decentralized search engines, e.g. [BitClave](https://www.chipin.com/bitclave-ico-searchengine-pays-you/), [Presearch](https://www.presearch.io/#what) Weipoint (a news post is here); +* decentralized search engines, e.g. [BitClave](https://www.chipin.com/bitclave-ico-searchengine-pays-you/)(dead link), [Presearch](https://www.presearch.io/#what) Weipoint(dead link) (a news post is here (dead link)); * reputation and ratings network e.g. as used by [Etheal](https://etheal.com/), which is described below (CTRL+F); * identity (e.g. as provided by uPort, as well as [in-blockchain proposal](https://www.ethnews.com/erc725-a-self-sovereign-identity-standard-for-ethereum) and [Shyft](https://www.shyft.network/)); @@ -74,7 +74,7 @@ Grid+ uses Ethereum and SolarCoin, EnergyCoin, although both are altcoins rather than Ethereum tokens; * governance of any organisation, e.g. Democracy.Earth; and also governance of DAOs, e.g. Aragon. There's also [Holographic consensus](https://medium.com/daostack/decentralized-governance-first-principles-1fc6eaa492ed) and a [Gitter channel for governance in Eth](https://gitter.im/ethereum/governance); -* decentralized search engines like [BitClave](https://www.bitclave.com/en/), [Weipoint](https://www.weipoint.com/) and [Epocum](https://www.stateofthedapps.com/dapps/epocum); +* decentralized search engines like [BitClave](https://www.bitclave.com/), [Weipoint](https://www.weipoint.com/)(dead link) and [Epocum](https://www.stateofthedapps.com/dapps/epocum); * wallets like MyEtherWallet or hardware wallets Trezor or Ledger; * blockchain explorers like [Etherscan](https://etherscan.io/); * a gateway to decentralized services such as [Infura](https://infura.io/); @@ -129,7 +129,7 @@ Continuing the list: Examples that have been conceptualized, but not implemented (at least as far as the creator of this wiki is aware of) include: * reducing transaction costs for existing business models (here is a good read about that). However, to tokenize online centric business models, the network model should change from client-server to peer-to-peer, to avoid a conflict of interest. This is more difficult to achieve since a server is a piece of infrastructure, and transferring to a peer-to-peer model would cause it to be a sunk cost. Additionally, it may be difficult to build a replacement dapp for a successful website, because it is hard to get a network of engaged users to change to using something else (inertia). Centralized web apps (not just mobile apps but websites, and use the word to contrast with dapps) include: -* * Google (although note [Weipoint](https://www.weipoint.com/) (dead link), [Bitclave](https://www.bitclave.com/) and [Presearch](https://www.presearch.org)), +* * Google (although note [Weipoint](https://www.weipoint.com/)(dead link), [Bitclave](https://www.bitclave.com/) and [Presearch](https://www.presearch.org)), * * social networks like [Facebook](http://www.trustnodes.com/2018/01/04/zuckerberg-studying-cryptocurrency-implementation-facebook), Twitter, (although note e.g. [Akasha](https://akasha.world/) above, [Peepeth](https://peepeth.com/), and [Status](https://status.im)) while [Mark Zuckerberg said that Facebook will look into cryptocurrencies](https://www.facebook.com/zuck/posts/10104380170714571); * * online marketplaces e.g. Amazon, eBay and Alibaba (decentralized alternatives include [OpenBazaar](https://www.openbazaar.org/) for goods and bnbs; [Soma](https://soma.co/) for products or services, [Canya for services](https://canya.io/) also note this simple implementation and subreddit [here](https://www.reddit.com/r/ethmarket/), as well as more specific or niche marketplaces like [Cryptokitties](https://www.cryptokitties.co/)). For more info see [here](https://www.forbes.com/sites/rogeraitken/2017/10/24/whats-the-future-of-online-marketplaces-blockchains-technology-impact/#3f6bde2a63a0). Note that many successful mainstream apps use reputation networks, and search engines, so if you can implement just one of these (and make it usable in other dapps) then that would be really useful. * making economically viable other business models that have seen low uptake or aren't economically viable without blockchain tech. So-called sharing economy business models (which are more aptly called tasker or rentier capitalism models) like Airbnb, Uber, AirTasker, Fiverr, Upwork, TaskRabbit, and Menulog are particularly ripe for transformation (the term transformation is preferrable to disruption, since it should be a net positive change, while negative effects are manageable or solvable), since no trusted third party for a transaction is needed, such as banks 🏦, credit card 💳 companies or PayPal, just a smart contract; and @@ -147,7 +147,7 @@ More examples are e.g. [here in a blog post](https://medium.com/@Ethereum_AI/eth - [Everex](https://www.everex.io/), a blockchain-powered financial service platform; Here's a challenge: keep an eye out for activity that has not been implemented on Ethereum (or could be implemented in a better way; check this article and research to check whether it's implemented and if so, how well) and then: -* develop a dapp for the idea yourself (after learning Solidity, if you don't already know it). Apply for [grants or other funding sources](https://github.com/ethereum/wiki/wiki/Grants-and-funding-sources); and/or +* develop a dapp for the idea yourself (after learning Solidity, if you don't already know it). Apply for [grants or other funding sources](/funding/funding.md); and/or * Open-source the idea; and/or * Or join an existing project. diff --git a/fundamentals/design-rationale.md b/fundamentals/design-rationale.md index 6d21d38..e7b6eba 100644 --- a/fundamentals/design-rationale.md +++ b/fundamentals/design-rationale.md @@ -58,7 +58,7 @@ The Merkle Patricia tree/trie, previously envisioned by Alan Reiner and implemen 1. Every unique set of key/value pairs maps uniquely to a root hash, and it is not possible to spoof membership of a key/value pair in a trie (unless an attacker has ~2^128 computing power) 2. It is possible to change, add or delete key/value pairs in logarithmic time -This gives us a way of providing an efficient, easily updateable, "fingerprint" of our entire state tree. The Ethereum MPT is formally described [here](./patricia-tree.md). +This gives us a way of providing an efficient, easily updateable, "fingerprint" of our entire state tree. The Ethereum MPT is formally described [here](/fundamentals/patricia-tree.md). Specific design decisions in the MPT include: @@ -70,7 +70,7 @@ Specific design decisions in the MPT include: ## RLP -RLP ("recursive length prefix") encoding is the main serialization format used in Ethereum, and is used everywhere - for blocks, transactions, account state data and wire protocol messages. RLP is formally described [here](./rlp.md). +RLP ("recursive length prefix") encoding is the main serialization format used in Ethereum, and is used everywhere - for blocks, transactions, account state data and wire protocol messages. RLP is formally described [here](/fundamentals/rlp.md). RLP is intended to be a highly minimalistic serialization format; its sole purpose is to store nested arrays of bytes. Unlike [protobuf](https://developers.google.com/protocol-buffers/docs/pythontutorial), [BSON](http://bsonspec.org/) and other existing solutions, RLP does not attempt to define any specific data types such as booleans, floats, doubles or even integers; instead, it simply exists to store structure, in the form of nested arrays, and leaves it up to the protocol to determine the meaning of the arrays. Key/value maps are also not explicitly supported; the semi-official suggestion for supporting key/value maps is to represent such maps as `[[k1, v1], [k2, v2], ...]` where `k1, k2...` are sorted using the standard ordering for strings. @@ -106,7 +106,7 @@ Where: - `logs` is a list of items of the form `[address, [topic1, topic2...], data]` that are produced by the `LOG0` ... `LOG4` opcodes during the execution of the transaction (including by the main call and sub-calls). `address` is the address of the contract that produced the log, the topics are up to 4 32-byte values, and the data is an arbitrarily sized byte array. - `logbloom` is a bloom filter made up of the addresses and topics of all logs in the transaction. -There is also a bloom in the block header, which is the OR of all of the blooms for the transactions in the block. The purpose of this construction is to make the Ethereum protocol light-client friendly in as many ways as possible. For more details on Ethereum light clients and their use cases, see the [light client page (principles section)](../concepts/light-client-protocol.md#principles). +There is also a bloom in the block header, which is the OR of all of the blooms for the transactions in the block. The purpose of this construction is to make the Ethereum protocol light-client friendly in as many ways as possible. For more details on Ethereum light clients and their use cases, see the [light client page (principles section)](/concepts/light-client-protocol.md#principles). ## Uncle incentivization diff --git a/fundamentals/ethereum-introduction.md b/fundamentals/ethereum-introduction.md index 905fdb3..ef5b159 100755 --- a/fundamentals/ethereum-introduction.md +++ b/fundamentals/ethereum-introduction.md @@ -14,7 +14,7 @@ For an introduction to blockchains, see [this TED talk](https://www.youtube.com/ Ethereum has been described in several ways. -The simplest way to understand Ethereum is to know what it does. Just like how it is not necessary to fully understand the intricate workings of how a car works in order to appreciate it's utility, or to understand how electricity arrives in your light bulb when you turn it on, understanding the current and potential utility of Ethereum is a good start. Ethereum can be used for virtually any kind of transaction or agreement (to put it another way, any kind of activity that has an economic or governance aspect), at a lower cost than conventional alternatives, such as debit card payments, in a way that is trustless, secure, safe and censorship-resistant, all with high probability. An extensive and growing list of uses is available [here](../fundamentals/decentralized-apps-dapps.md). +The simplest way to understand Ethereum is to know what it does. Just like how it is not necessary to fully understand the intricate workings of how a car works in order to appreciate it's utility, or to understand how electricity arrives in your light bulb when you turn it on, understanding the current and potential utility of Ethereum is a good start. Ethereum can be used for virtually any kind of transaction or agreement (to put it another way, any kind of activity that has an economic or governance aspect), at a lower cost than conventional alternatives, such as debit card payments, in a way that is trustless, secure, safe and censorship-resistant, all with high probability. An extensive and growing list of uses is available [here](/fundamentals/decentralized-apps-dapps.md). @@ -54,7 +54,7 @@ The platform part of Ethereum makes it much more useful than just a cryptocurren ### List of dapps -For a list of dapps, visit [here](../fundamentals/decentralized-apps-dapps.md). +For a list of dapps, visit [here](/fundamentals/decentralized-apps-dapps.md). ## Market analysis @@ -62,7 +62,7 @@ Assessing the actual usage of blockchains is a more reliable indicator than the -As of the 9th of January 2018, [the market capitalisation of Ethereum is $118.5 billion USD](https://cryptolization.com/ethereum) (refer to the link for the latest figure), and [it has been in circulation since 30 July 2015](../roadmap/releases.md), with the [first transaction](https://www.reddit.com/r/ethereum/comments/6qildp/what_is_the_first_ever_ethereum_transaction/) after the [genesis block](https://etherscan.io/block/0) using Ethereum on [7 August 2015](https://etherscan.io/block/46147). Compare this with the next largest and the current largest cryptocurrency, [Bitcoin, with a market cap of $253.0 billion USD](https://cryptolization.com/ethereum), where [it has been in circulation since January 2009](http://www.newyorker.com/reporting/2011/10/10/111010fa_fact_davis). Technically, Ethereum has had a much faster growth rate, while more importantly for long term investment (I do not encourage speculation or buying with capital that you can't afford to lose, without due diligence as that only causes volatility as has been seen) the fundamentals are much better than Bitcoin. While it is true that Bitcoin has more of a market and currency, e.g. in terms of more entities that will accept it as a form of payment, the creator of this wiki expects that time will change that (indeed the market cap of Ethereum recently surpassed half that of Bitcoin, around May 2017). Also, [the number of transactions of Ethereum surpassed that of several cryptocurrencies combined on 22 Nov 2017](https://www.reddit.com/r/ethereum/comments/7est9k/ethereum_is_now_processing_more_transactions_a/). However, note [this retort](https://www.reddit.com/r/ethereum/comments/7est9k/ethereum_is_now_processing_more_transactions_a/dq7a31u/). +As of the 9th of January 2018, [the market capitalisation of Ethereum is $118.5 billion USD](https://cryptolization.com/ethereum) (refer to the link for the latest figure), and [it has been in circulation since 30 July 2015](/roadmap/releases.md), with the [first transaction](https://www.reddit.com/r/ethereum/comments/6qildp/what_is_the_first_ever_ethereum_transaction/) after the [genesis block](https://etherscan.io/block/0) using Ethereum on [7 August 2015](https://etherscan.io/block/46147). Compare this with the next largest and the current largest cryptocurrency, [Bitcoin, with a market cap of $253.0 billion USD](https://cryptolization.com/ethereum), where [it has been in circulation since January 2009](http://www.newyorker.com/reporting/2011/10/10/111010fa_fact_davis). Technically, Ethereum has had a much faster growth rate, while more importantly for long term investment (I do not encourage speculation or buying with capital that you can't afford to lose, without due diligence as that only causes volatility as has been seen) the fundamentals are much better than Bitcoin. While it is true that Bitcoin has more of a market and currency, e.g. in terms of more entities that will accept it as a form of payment, the creator of this wiki expects that time will change that (indeed the market cap of Ethereum recently surpassed half that of Bitcoin, around May 2017). Also, [the number of transactions of Ethereum surpassed that of several cryptocurrencies combined on 22 Nov 2017](https://www.reddit.com/r/ethereum/comments/7est9k/ethereum_is_now_processing_more_transactions_a/). However, note [this retort](https://www.reddit.com/r/ethereum/comments/7est9k/ethereum_is_now_processing_more_transactions_a/dq7a31u/). ## Issues @@ -72,7 +72,7 @@ There also several issues with Ethereum, such as not being scalable enough, not Ethereum will need to scale to process far more transactions per second (to become a "world computer") than Visa, Mastercard and American Express combined (which process on the order of [tens of thousands of transactions per second](https://usa.visa.com/run-your-business/small-business-tools/retail.html) [in the link, CTRL+F 24,000]), while Ethereum 1.0, the current version as of December 30 2017, processed [a record of 1103523 transactions on Friday, December 22, 2017, or 12.77 transactions per second](https://web.archive.org/web/20171230005127/https://etherscan.io/chart/tx). -Note that [Ripple claims that it's Consensus Ledger can process a thousand transactions per second](https://ripple.com/dev-blog/ripple-consensus-ledger-can-sustain-1000-transactions-per-second/), while it could process more with payment channels. "Although payment channels achieve practically infinite scalability by decoupling payment from settlement, they do so without incurring the risk typically associated with delayed settlement." Further note that Ripple achieves this by trading off on decentralization, through a [distributed network of validators or distributed servers](https://ripple.com/build/xrp-ledger-consensus-process/), while it has been described as a [federation protocol](https://wiki.ripple.com/Federation_protocol). +Note that [Ripple claims that it's Consensus Ledger can process a thousand transactions per second](https://ripple.com/dev-blog/ripple-consensus-ledger-can-sustain-1000-transactions-per-second/), while it could process more with payment channels. "Although payment channels achieve practically infinite scalability by decoupling payment from settlement, they do so without incurring the risk typically associated with delayed settlement." Further note that Ripple achieves this by trading off on decentralization, through a [distributed network of validators or distributed servers](https://ripple.com/build/xrp-ledger-consensus-process/), while it has been described as a [federation protocol](https://wiki.ripple.com/Federation_protocol)(dead link). There are even more scalable blockchains that use a delegated proof of stake (DPOS) consensus protocol, such as Bitshares and Steem. [Bitshares can apparently process 100,000 TPS](https://bitshares.org/technology/industrial-performance-and-scalability/). @@ -99,7 +99,7 @@ The mining process to crack cryptographic code (specifically to discover the non ## Quantum computing attacks -If quantum computing becomes more performant Ethereum's cryptographic signature scheme, Elliptic Curve Digital Signature Algorithm (ECDSA), would be insecure. However, there are solutions for this that will be implemented soon in the [Constantinople release](Releases) with [EIP 86: Abstraction of transaction origin and signature, which has "**Custom cryptography**: users can upgrade to ed25519 signatures, Lamport hash ladder signatures or whatever other scheme they want on their own terms; they do not need to stick with ECDSA." Lamport signatures could be used in a quantum resistant algorithm](https://github.com/ethereum/EIPs/pull/208). More info on that is e.g. [here](https://ethereum.stackexchange.com/a/13577/95840)), [here](https://blog.ethereum.org/2015/12/24/understanding-serenity-part-i-abstraction/), and [here](./../howto/ethereum-development-tutorial.md). +If quantum computing becomes more performant Ethereum's cryptographic signature scheme, Elliptic Curve Digital Signature Algorithm (ECDSA), would be insecure. However, there are solutions for this that will be implemented soon in the [Constantinople release](/roadmap/releases.md) with [EIP 86: Abstraction of transaction origin and signature, which has "**Custom cryptography**: users can upgrade to ed25519 signatures, Lamport hash ladder signatures or whatever other scheme they want on their own terms; they do not need to stick with ECDSA." Lamport signatures could be used in a quantum resistant algorithm](https://github.com/ethereum/EIPs/pull/208). More info on that is e.g. [here](https://ethereum.stackexchange.com/a/13577/95840)), [here](https://blog.ethereum.org/2015/12/24/understanding-serenity-part-i-abstraction/), and [here](/howto/ethereum-development-tutorial.md). ## No technological artefacts can be a panacea @@ -107,11 +107,11 @@ For the continual improvement of humanity, there needs to be balance in life bet ## Bugs -Ethereum has had expensive bugs, such as those listed [here](../faqs/major-issues-resulting-in-lost-or-stuck-funds.md) and [here](../faqs/famous-bugs.md). +Ethereum has had expensive bugs, such as those listed [here](/faqs/major-issues-resulting-in-lost-or-stuck-funds.md) and [here](/faqs/famous-bugs.md). ## How do you buy and sell Ether, the currency of Ethereum? -Refer to [here](./getting-ether.md). +Refer to [here](/fundamentals/getting-ether.md). ## Development @@ -128,16 +128,16 @@ If you want to help contribute to core development, there is also: ## Core development -- [client development](../clients/clients-tools-dapp-browsers-wallets-and-other-projects.md); +- [client development](/clients/clients-tools-dapp-browsers-wallets-and-other-projects.md); - if you're interested in testing, see the documentation [here](https://ethereum-tests.readthedocs.io/en/latest/), as well as [the Github tests repo](https://github.com/ethereum/tests), [a Gist here (it is outdated)](https://gist.github.com/Souptacular/fd197b1fac7c6d2660b0bef27a33ed40#lll-and-evm-stack-resources), and [Gitter here](https://gitter.im/ethereum/tests); - documentation and specification review, e.g. (and in particular) of [EIPs](https://github.com/ethereum/EIPs); - [many other repositories](https://github.com/ethereum). -For R&D, refer to [here](../research/rd.md). +For R&D, refer to [here](/research/rd.md). ## Programming languages -- Learn Python first, e.g. with [Learn Python the Hard Way](https://www.learnpythonthehardway.org/) (I learnt using this, but it's rather condescending, so I'd recommend [Pydocs](https://docs.python.org/3/) instead). There's others, e.g. [Codecademy](https://www.codecademy.com/learn/learn-python), and [Coursera](https://www.coursera.org/courses?languages=en&query=learn+python), etc. Knowing Python is useful for research and demonstration, with demonstration e.g. for [client development](../clients/clients-tools-dapp-browsers-wallets-and-other-projects.md), e.g. for [Py-EVM](https://github.com/ethereum/py-evm) which is being used as an Ethereum client, to implement statelessness and sharding, as well as [vyper](https://github.com/ethereum/Vyper), an experimental, secure, smart contract programming language; +- Learn Python first, e.g. with [Learn Python the Hard Way](https://www.learnpythonthehardway.org/) (I learnt using this, but it's rather condescending, so I'd recommend [Pydocs](https://docs.python.org/3/) instead). There's others, e.g. [Codecademy](https://www.codecademy.com/learn/learn-python), and [Coursera](https://www.coursera.org/courses?languages=en&query=learn+python), etc. Knowing Python is useful for research and demonstration, with demonstration e.g. for [client development](/clients/clients-tools-dapp-browsers-wallets-and-other-projects.md), e.g. for [Py-EVM](https://github.com/ethereum/py-evm) which is being used as an Ethereum client, to implement statelessness and sharding, as well as [vyper](https://github.com/ethereum/Vyper), an experimental, secure, smart contract programming language; - [LLL](https://media.consensys.net/an-introduction-to-lll-for-ethereum-smart-contract-development-e26e38ea6c23) (also see [here](https://github.com/ethereum/solidity/tree/develop/liblll) and [here](https://github.com/ethereum/solidity/tree/develop/lllc)); - [JULIA](https://solidity.readthedocs.io/en/develop/julia.html), an intermediate language for different Ethereum virtual machines; diff --git a/fundamentals/fundamentals.md b/fundamentals/fundamentals.md index fda7a9c..ef3c94b 100644 --- a/fundamentals/fundamentals.md +++ b/fundamentals/fundamentals.md @@ -13,7 +13,6 @@ There are numerous pages underneath me. * [enode-url-format.md](enode-url-format.md) * [ethereum-introduction.md](ethereum-introduction.md) * [getting-ether.md](getting-ether.md) -* [glossary.md](glossary.md) * [mining.md](mining.md) * [patricia-tree.md](mining.md) * [rlp.md](rlp.md) diff --git a/fundamentals/getting-ether.md b/fundamentals/getting-ether.md index 596b393..ea40c18 100644 --- a/fundamentals/getting-ether.md +++ b/fundamentals/getting-ether.md @@ -27,11 +27,11 @@ In order to obtain Ether, you need to either: friendly [Mist Ethereum GUI Wallet](https://github.com/ethereum/mist/releases) that as of Beta 6 introduced the ability to purchase ether using the [ShapeShift API](http://shapeshift.io/). - **not recommended**: become an Ethereum miner (see - [here](https://forum.ethereum.org/discussion/8886/quick-start-guide-to-mine-ethereum/p1). + [here](https://forum.ethereum.org/discussion/8886/quick-start-guide-to-mine-ethereum/p1)(dead link). Note that [this](https://ethereum-homestead.readthedocs.io/en/latest/mining.html) Homestead guide is outdated, which is the same as - [this](./mining.md) mining wiki). + [this](/fundamentals/mining.md) mining wiki). However, this is not recommended as Ethereum is going to transition to proof-of-stake, making mining obsolescent. Becoming a miner would involve investing in a mining rig (several GPUs, plus maybe other @@ -119,10 +119,6 @@ You can also search for "{insert your country} Ether exchange". There's also this: . -For further info (which lists more exchanges), see -[here](Getting-Ether:-further-info). - - ## Centralised fixed rate exchanges @@ -311,7 +307,7 @@ https://www.huobi.com https://www.okcoin.com -https://yunbi.com +https://yunbi.com (dead link) **European Euros** @@ -329,11 +325,11 @@ https://bitso.com https://coinone.co.kr/ -https://www.bithumb.com/ +https://www.bithumb.com/ (dead link) ## More details about what James Ray tried (not very necessary to know) -You could skip to the [next section](https://github.com/ethereum/wiki/wiki/Ethereum-introduction.md#development) +You could skip to the [next section](/fundamentals/getting-ether#development) I bought BTC in a different way. Step 2 worked for me. I will try step 1 next time I buy more BTC. diff --git a/fundamentals/getting-started.md b/fundamentals/getting-started.md index 1cb4d14..22f6104 100644 --- a/fundamentals/getting-started.md +++ b/fundamentals/getting-started.md @@ -3,9 +3,9 @@ For an introduction to Ethereum, see the [beginners](https://ethereum.org/beginners/) section of ethereum.org. -For an introduction targeted see [Ethereum introduction](./ethereum-introduction.md). If you want to get a deeper understanding, start by reading the [whitepaper](https://ethereum.org/whitepaper) and the [design rationale](./design-rationale.md). For a more formal review, read the [yellow paper](https://ethereum.github.io/yellowpaper/paper.pdf). If you are interested in being a core developer, find a project that interests you, and start contributing to that (maybe pro-bono initially, until maintainers like you and decide to hire you). +For an introduction targeted see [Ethereum introduction](/fundamentals/ethereum-introduction.md). If you want to get a deeper understanding, start by reading the [whitepaper](https://ethereum.org/whitepaper) and the [design rationale](/fundamentals/design-rationale.md). For a more formal review, read the [yellow paper](https://ethereum.github.io/yellowpaper/paper.pdf). If you are interested in being a core developer, find a project that interests you, and start contributing to that (maybe pro-bono initially, until maintainers like you and decide to hire you). -If you are interested in developing smart contracts you can see [here](https://en.wikipedia.org/wiki/Ethereum#Programming_languages), as well as under [ÐApp Development](./dapp-development.md) (which is also in the sidebar). +If you are interested in developing smart contracts you can see [here](https://en.wikipedia.org/wiki/Ethereum#Programming_languages), as well as under [ÐApp Development](/fundamentals/dapp-development.md) (which is also in the sidebar). For getting started guides, see here diff --git a/fundamentals/mining.md b/fundamentals/mining.md index 520d655..7f13f49 100644 --- a/fundamentals/mining.md +++ b/fundamentals/mining.md @@ -18,13 +18,13 @@ Ethereum Frontier, like all blockchain technologies uses an incentive-driven mod Miners produce blocks which the others check for validity. Among other well-formedness criteria, a block is only valid if it contains **proof of work** (PoW) of a given **difficulty**. Note that in Ethereum 1.1, this is likely going to be replaced by a **proof of stake** model. -The proof of work algorithm used is called [Ethash](../concepts/ethash/ethash.md) (a modified version of [Dagger-Hashimoto](../concepts/dagger-hashimoto.md)) involves finding a nonce input to the algorithm so that the result is below a certain threshold depending on the difficulty. The point in PoW algorithms is that there is no better strategy to find such a nonce than enumerating the possibilities while verification of a solution is trivial and cheap. If outputs have a uniform distribution, then we can guarantee that on average the time needed to find a nonce depends on the difficulty threshold, making it possible to control the time of finding a new block just by manipulating difficulty. +The proof of work algorithm used is called [Ethash](/concepts/ethash/ethash.md) (a modified version of [Dagger-Hashimoto](/concepts/dagger-hashimoto.md)) involves finding a nonce input to the algorithm so that the result is below a certain threshold depending on the difficulty. The point in PoW algorithms is that there is no better strategy to find such a nonce than enumerating the possibilities while verification of a solution is trivial and cheap. If outputs have a uniform distribution, then we can guarantee that on average the time needed to find a nonce depends on the difficulty threshold, making it possible to control the time of finding a new block just by manipulating difficulty. The difficulty dynamically adjusts so that on average one block is produced by the entire network every 12 seconds (ie., 12 s block time). This heartbeat basically punctuates the synchronisation of system state and guarantees that maintaining a fork (to allow double spend) or rewriting history is impossible unless the attacker possesses more than half of the network mining power (so called 51% attack). Any node participating in the network can be a miner and their expected revenue from mining will be directly proportional to their (relative) mining power or **hashrate**, ie., number of nonces tried per second normalised by the total hashrate of the network. -Ethash PoW is memory hard, making it basically ASIC resistant. This means that calculating the PoW requires choosing subsets of a fixed resource dependent on the nonce and block header. This resource (a few gigabyte size data) is called a **DAG** (directed acyclic graph). The [DAG](../concepts/ethash/dag.md) is totally different every 30000 blocks (a 100 hour window, called an **epoch**) and takes a while to generate. Since the DAG only depends on block height, it can be pregenerated but if it is not, the client need to wait the end of this process to produce a block. Until clients actually precache DAGs ahead of time the network may experience a massive block delay on each epoch transition. Note that the DAG does not need to be generated for verifying the PoW essentially allowing for verification with both low CPU and small memory. +Ethash PoW is memory hard, making it basically ASIC resistant. This means that calculating the PoW requires choosing subsets of a fixed resource dependent on the nonce and block header. This resource (a few gigabyte size data) is called a **DAG** (directed acyclic graph). The [DAG](/concepts/ethash/dag.md) is totally different every 30000 blocks (a 100 hour window, called an **epoch**) and takes a while to generate. Since the DAG only depends on block height, it can be pregenerated but if it is not, the client need to wait the end of this process to produce a block. Until clients actually precache DAGs ahead of time the network may experience a massive block delay on each epoch transition. Note that the DAG does not need to be generated for verifying the PoW essentially allowing for verification with both low CPU and small memory. As a special case, when you start up your node from scratch, mining will only start once the DAG is built for the current epoch. @@ -59,7 +59,7 @@ For instance `geth makedag 360000 ~/.ethash`. Note that ethash uses `~/.ethash` # The Algorithm -Our algorithm, [Ethash](../concepts/ethash/ethash.md) (previously known as Dagger-Hashimoto), is based around the provision of a large, transient, randomly generated dataset which forms a DAG (the Dagger-part), and attempting to solve a particular constraint on it, partly determined through a block's header-hash. +Our algorithm, [Ethash](/concepts/ethash/ethash.md) (previously known as Dagger-Hashimoto), is based around the provision of a large, transient, randomly generated dataset which forms a DAG (the Dagger-part), and attempting to solve a particular constraint on it, partly determined through a block's header-hash. It is designed to hash a fast verifiability time within a slow CPU-only environment, yet provide vast speed-ups for mining when provided with a large amount of memory with high-bandwidth. The large memory requirements mean that large-scale miners get comparatively little super-linear benefit. The high bandwidth requirement means that a speed-up from piling on many super-fast processing units sharing the same memory gives little benefit over a single unit. @@ -81,4 +81,4 @@ An sgminer module for Ethash is expected to be released at some point during, bu Communication between the external mining application and the Ethereum daemon for work provision and submission happens through the JSON-RPC API. Two RPC functions are provided; `eth_getWork` and `eth_submitWork`. -These are formally documented on the [JSON-RPC API](../json-rpc/api.md) wiki article. +These are formally documented on the [JSON-RPC API](/json-rpc/api.md) wiki article. diff --git a/fundamentals/patricia-tree.md b/fundamentals/patricia-tree.md index 25d731d..fe07805 100644 --- a/fundamentals/patricia-tree.md +++ b/fundamentals/patricia-tree.md @@ -162,7 +162,7 @@ Now, we build such a trie with the following key/value pairs in the underlying D hashD: [ <>, <>, <>, <>, <>, <>, hashE, <>, <>, <>, <>, <>, <>, <>, <>, <>, 'verb' ] hashE: [ <17>, [ <>, <>, <>, <>, <>, <>, [ <35>, 'coin' ], <>, <>, <>, <>, <>, <>, <>, <>, <>, 'puppy' ] ] -When one node is referenced inside another node, what is included is `H(rlp.encode(x))`, where `H(x) = sha3(x) if len(x) >= 32 else x` and `rlp.encode` is the [RLP](/fundamentals/rlp) encoding function. +When one node is referenced inside another node, what is included is `H(rlp.encode(x))`, where `H(x) = sha3(x) if len(x) >= 32 else x` and `rlp.encode` is the [RLP](/fundamentals/rlp.md) encoding function. Note that when updating a trie, one needs to store the key/value pair `(sha3(x), x)` in a persistent lookup table _if_ the newly-created node has length >= 32. However, if the node is shorter than that, one does not need to store anything, since the function f(x) = x is reversible. @@ -181,7 +181,7 @@ From a block header there are 3 roots from 3 of these tries. There is one global state trie, and it updates over time. In it, a `path` is always: `sha3(ethereumAddress)` and a `value` is always: `rlp(ethereumAccount)`. More specifically an ethereum `account` is a 4 item array of `[nonce,balance,storageRoot,codeHash]`. At this point it's worth noting that this `storageRoot` is the root of another patricia trie: ### Storage Trie -Storage trie is where *all* contract data lives. There is a separate storage trie for each account. To calculate a 'path' in this trie first understand how solidity organizes a [variable's position](/json-rpc/API#eth_getstorageat). To get the `path` there is one extra hashing (the link does not describe this). For instance the `path` for the zeroith variable is `sha3(<0000000000000000000000000000000000000000000000000000000000000000>)` which is always `290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563`. The value at the leaf is the rlp encoding of the storage value `1234` (`0x04d2`), which is `<82 04 d2>`. +Storage trie is where *all* contract data lives. There is a separate storage trie for each account. To calculate a 'path' in this trie first understand how solidity organizes a [variable's position](https://openethereum.github.io/JSONRPC-eth-module#eth_getstorageat). To get the `path` there is one extra hashing (the link does not describe this). For instance the `path` for the zeroith variable is `sha3(<0000000000000000000000000000000000000000000000000000000000000000>)` which is always `290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563`. The value at the leaf is the rlp encoding of the storage value `1234` (`0x04d2`), which is `<82 04 d2>`. For the mapping example, the `path` is `sha3(<6661e9d6d8b923d5bbaab1b96e1dd51ff6ea2a93520fdc9eb75d059238b8c5e9>)` #### Transactions Trie diff --git a/fundamentals/rlp.md b/fundamentals/rlp.md index 3d7182b..0092067 100644 --- a/fundamentals/rlp.md +++ b/fundamentals/rlp.md @@ -1,10 +1,10 @@ # RLP -Note: it is planned for RLP to be **replaced** by a more preferable form of serialization, as outlined [here](https://ethresear.ch/t/blob-serialisation/1705), and implemented by [sharding clients](./../sharding-introduction-r-d-compendium.md). +Note: it is planned for RLP to be **replaced** by a more preferable form of serialization, as outlined [here](https://ethresear.ch/t/blob-serialisation/1705), and implemented by [sharding clients](/sharding/sharding-introduction-r-d-compendium.md). The purpose of RLP (Recursive Length Prefix) is to encode arbitrarily nested arrays of binary data, and RLP is the main encoding method used to serialize objects in Ethereum. The only purpose of RLP is to encode structure; encoding specific data types (eg. strings, floats) is left up to higher-order protocols; but positive RLP integers must be represented in big endian binary form with no leading zeroes (thus making the integer value zero be equivalent to the empty byte array). Deserialised positive integers with leading zeroes must be treated as invalid. The integer representation of string length must also be encoded this way, as well as integers in the payload. Additional information can be found in the Ethereum yellow paper Appendix B. -If one wishes to use RLP to encode a dictionary, the two suggested canonical forms are to either use `[[k1,v1],[k2,v2]...]` with keys in lexicographic order or to use the higher-level [Patricia Tree](./patricia-tree.md) encoding as Ethereum does. +If one wishes to use RLP to encode a dictionary, the two suggested canonical forms are to either use `[[k1,v1],[k2,v2]...]` with keys in lexicographic order or to use the higher-level [Patricia Tree](patricia-tree.md) encoding as Ethereum does. ## Definition diff --git a/fundamentals/specs/bad-block-reporting.md b/fundamentals/specs/bad-block-reporting.md index 108db3e..9608de1 100644 --- a/fundamentals/specs/bad-block-reporting.md +++ b/fundamentals/specs/bad-block-reporting.md @@ -1,6 +1,6 @@ # Bad Block Reporting -Send a JSONRPC request to `https://badblocks.ethdev.com`: +Send a JSONRPC request to `https://badblocks.ethdev.com` (dead link): Call `eth_badBlock(BADBLOCK)`, with `BADBLOCK` the object described below: diff --git a/funding/experiments.md b/funding/experiments.md index f2b799d..687bb3c 100644 --- a/funding/experiments.md +++ b/funding/experiments.md @@ -6,13 +6,13 @@ date: 2019-07-31T15:15:54.268Z tags: --- -See the top level [Funding](/funding) page for sources of funding and related info. +See the top level [Funding](/funding/funding.md) page for sources of funding and related info. -Please use this [EthMagicians thread for discussion »](https://ethereum-magicians.org/t/funding-and-eth1x/3496) +Please use this [EthMagicians thread for discussion »](https://ethereum-magicians.org/t/funding/funding.md-and-eth1x/3496) # Resources -* Related to this page, @bmann wrote up a Funding Taxonomy & Issues https://ethereum-magicians.org/t/funding-taxonomy-issues-for-ethereum-ecosystem/2014 +* Related to this page, @bmann wrote up a Funding Taxonomy & Issues https://ethereum-magicians.org/t/funding/funding.md-taxonomy-issues-for-ethereum-ecosystem/2014 * Long term cashflow & budgets for projects, with templates by @bmann https://ethereum-magicians.org/t/discussing-long-term-cashflow-and-budgets-for-ethereum-projects-teams-and-individuals/1849 # Funding Required @@ -70,15 +70,15 @@ And, should go without saying: if per project or R&D work isn't longer term, and # What needs funding in ETH1x? -The [ETH1 page](/eth1) lists Working Groups, which came out of [CoreDevsBerlin](/eth1/coredevsberlin). Alexey's State Rent group is sort of "perma funded" by the EF for now, and Alexey negotiated 3 months of funding for some of the other Working Groups. +The [ETH1 page](/eth1/eth1.md) lists Working Groups, which came out of [CoreDevsBerlin](/eth1/coredevsberlin.md). Alexey's State Rent group is sort of "perma funded" by the EF for now, and Alexey negotiated 3 months of funding for some of the other Working Groups. Infrastructure, using Testing as an example, is largely leaderless. There are a couple of people paid by the EF that work on it. Hasn't been an effort to coordinate testnets, consensus tests, network tests, etc. White Block / Zak Cole have said they could lead some of this. Coordination (eg. release management) doesn't have a solid process and no one dedicated to it other than Hudson (who also is the only community person, travels a ton, AND does devops work for the foundation). Danno & Tim Beiko who work for Pegasys / ConsenSys deserve a shout out for leaning into the hard fork process and EIP / All Core Devs process. Alex (axic) is also doing a ton of work around this, but is also juggling EVM work and eWASM work and a ton of other development projects. -Infrastructure for ETH1x broadly is kind of run by various people who work with the EF, but is also largely undocumented and not currently able to be run by anyone outside the EF. There is an attempt at documenting what infrastructure is needed / who has keys to what on the [Infrastructure](/infrastructure) page. +Infrastructure for ETH1x broadly is kind of run by various people who work with the EF, but is also largely undocumented and not currently able to be run by anyone outside the EF. There is an attempt at documenting what infrastructure is needed / who has keys to what on the [Infrastructure](/governance/infrastructure.md) page. -I think it would be a very interesting process to see how many people are working on ETH1x across the EF, Parity, and Pegasys (just listing those that have active mainnet clients -- see [ETH1 clients](/eth1/clients)). +I think it would be a very interesting process to see how many people are working on ETH1x across the EF, Parity, and Pegasys (just listing those that have active mainnet clients -- see [ETH1 clients](/eth1/clients.md)). Infrastructure is this special case which is most effective when done "centrally" or at least collaborated on closely. diff --git a/governance/governance-compendium.md b/governance/governance-compendium.md index 0ffe4fa..d5a9a92 100644 --- a/governance/governance-compendium.md +++ b/governance/governance-compendium.md @@ -32,7 +32,7 @@ tags: > > By making it possible for everyone in the world to organize, we are enabling a borderless, permissionless and more efficient creation of value - - [EthSignals.org](https://www.ethsignals.org) – Working group on improving Ethereum Governance with better signalling. Support the [tennagraph.com](tennagraph.com) – dapp for stances collection around EIPs. + - [EthSignals.org](https://www.ethsignals.org) – Working group on improving Ethereum Governance with better signalling. Support the [tennagraph.com](http://tennagraph.com) – dapp for stances collection around EIPs. While the following projects do not have blockchain governance as a mission, they do relate to governance or deliberately use or plan to use governance mechanisms: diff --git a/governance/maintainers.md b/governance/maintainers.md index d8e3f05..c4595f1 100755 --- a/governance/maintainers.md +++ b/governance/maintainers.md @@ -5,14 +5,14 @@ The [wiki home page](/) has links to some of these items. The purpose of this pa | Component | Specification | Maintainers | Notes | |---|---|---|---| -| Ethereum Virtual Machine (EVM) - specification for processing smart contract code at the core of Ethereum | [Yellow Paper ethereum/yellowpaper](https://github.com/ethereum/yellowpaper) & [JelloPaper](https://jellopaper.org)[^jellopaper] | [nicksavers](https://github.com/nicksavers)[^yellowpapermaintainer] | See local wiki page [EVM Awesome List](ethereum-virtual-machine-evm-awesome-list) for additional resources | +| Ethereum Virtual Machine (EVM) - specification for processing smart contract code at the core of Ethereum | [Yellow Paper ethereum/yellowpaper](https://github.com/ethereum/yellowpaper) & [JelloPaper](https://jellopaper.org)[^jellopaper] | [nicksavers](https://github.com/nicksavers)[^yellowpapermaintainer] | See local wiki page [EVM Awesome List](/concepts/evm/ethereum-virtual-machine-(evm)-awesome-list.md) for additional resources | | DevP2P - peer-to-peer networking protocols used by Ethereum | [ethereum/devp2p](https://github.com/ethereum/devp2p/) | [subtly](https://github.com/subtly), [Felix Lange](https://github.com/fjl) | -| JSON-RPC API - middleware interface used to talk to Ethereum nodes | [ethereum/wiki](./json-rpc.md) | [bitpshr](https://github.com/bitpshr) (proposed) | See footnote [^jsonrpc] | -| Contract ABIs | [solidity docs](https://solidity.readthedocs.io/en/develop/abi-spec.html)| UNKNOWN | See local wiki page [Ethereum-Contract-ABI](Ethereum-Contract-ABI) | +| JSON-RPC API - middleware interface used to talk to Ethereum nodes | [ethereum/wiki](/json-rpc/api.md) | [bitpshr](https://github.com/bitpshr) (proposed) | See footnote [^jsonrpc] | +| Contract ABIs | [solidity docs](https://solidity.readthedocs.io/en/develop/abi-spec.html)| UNKNOWN | See local wiki page [/archive/ethereum-contract-abi.md](/archive/ethereum-contract-abi.md) | | Interfaces Repo | [ethereum/interfaces](https://github.com/ethereum/interfaces) | UNKNOWN | | -| Light Ethereum Subprotocol (LES) - protocol to support light nodes of mobile, embedded, and other low resource clients | [zsfelfoldi/go-ethereum/wiki](https://github.com/zsfelfoldi/go-ethereum/wiki/Light-Ethereum-Subprotocol-%28LES%29) | [zsfelfoldi](https://github.com/zsfelfoldi) | See the local wiki page [Light-client-protocol](Light-client-protocol) for more info | -| Whisper - a communication protocol for DApps to communicate with each other | [go-ethereum/wiki Whisper v6 RPC API](https://github.com/ethereum/go-ethereum/wiki/Whisper-v6-RPC-API) | UNKNOWN | Local wiki pages [Whisper](Whisper) & [Whisper Overview](Whisper-Overview) are from go-ethereum/wiki | -| Swarm | [go-ethereum/2959](https://github.com/ethereum/go-ethereum/pull/2959) | UNKNOWN | See local wiki page [Swarm Hash](/glossary/swarm-hash) & [original 2015 info on go-ethereum/wiki](https://github.com/ethereum/go-ethereum/wiki/Swarm---distributed-preimage-archive) & maybe [ethereum/wiki/Distributed-Preimage-Archive](../ideas/distributed-preimage-archive.md) | +| Light Ethereum Subprotocol (LES) - protocol to support light nodes of mobile, embedded, and other low resource clients | [zsfelfoldi/go-ethereum/wiki](https://github.com/zsfelfoldi/go-ethereum/wiki/Light-Ethereum-Subprotocol-%28LES%29) | [zsfelfoldi](https://github.com/zsfelfoldi) | See the local wiki page [Light-client-protocol](/concepts/light-client-protocol.md) for more info | +| Whisper - a communication protocol for DApps to communicate with each other | [go-ethereum/wiki Whisper v6 RPC API](https://github.com/ethereum/go-ethereum/wiki/Whisper-v6-RPC-API) | UNKNOWN | Local wiki pages [Whisper](/concepts/whisper/whisper.md) & [Whisper Overview](/concepts/whisper/overview.md) are from go-ethereum/wiki | +| Swarm | [go-ethereum/2959](https://github.com/ethereum/go-ethereum/pull/2959) | UNKNOWN | See local wiki page [Swarm Hash](/concepts/swarm-hash.md) & [original 2015 info on go-ethereum/wiki](https://github.com/ethereum/go-ethereum/wiki/Swarm---distributed-preimage-archive) & maybe [ethereum/wiki/Distributed-Preimage-Archive](/ideas/distributed-preimage-archive.md) | [^jsonrpc]: The JSON-RPC spec is stale / unmaintained. [EIP-1474 has been merged as draft](http://eips.ethereum.org/EIPS/eip-1474), and some work to have a separate spec repo here [ethereum-json-rpc-spec](https://github.com/spadebuilders/ethereum-json-rpc-spec). [bitpshr](https://github.com/bitpshr) has volunteered to be a maintainer. diff --git a/governance/polices-and-guidelines.md b/governance/polices-and-guidelines.md index 3b3939a..f6222aa 100755 --- a/governance/polices-and-guidelines.md +++ b/governance/polices-and-guidelines.md @@ -8,7 +8,7 @@ tags: # Index of Pages -* [design-rationale.md](../fundamentals/design-rationale.md) +* [design-rationale.md](/fundamentals/design-rationale.md) * [governance-compendium.md](governance-compendium.md) diff --git a/governance/security-issue-process.md b/governance/security-issue-process.md index 9646023..1071571 100755 --- a/governance/security-issue-process.md +++ b/governance/security-issue-process.md @@ -1,6 +1,6 @@ # Security Issue Process -Draft of steps that should be taken when finding a security issue in Ethereum. Security issue is defined as a problem in scope of [Security-Categorization](Security-Categorization). +Draft of steps that should be taken when finding a security issue in Ethereum. Security issue is defined as a problem in scope of [Security-Categorization](/concepts/security-categorization.md). Partly inspired by [OWASP Risk Rating](https://www.owasp.org/index.php/OWASP_Risk_Rating_Methodology) diff --git a/home.md b/home.md index 81bdf70..5f55165 100755 --- a/home.md +++ b/home.md @@ -16,12 +16,12 @@ tags: This is the community [wiki](https://en.wikipedia.org/wiki/Wiki) covering all sorts of information on the next-generation peer-to-peer technology platform built by the Ethereum community, including **Ethereum**, _the generalized blockchain for smart contract development_, as well as related protocols like: - **[IPFS](https://ipfs.io)**, a distributed storage platform. -- **[Whisper](Whisper-pages)**, _the private low-level datagram communication platform_ +- **[Whisper](/concepts/whisper/whisper.md)**, _the private low-level datagram communication platform_ - **[Swarm](http://swarm-gateways.net/bzz:/theswarm.eth/)**, a distributed storage platform and content distribution service. ## Issues and pull requests -If you have a technical issue with a specific client, application or tool, e.g. those listed [here](Clients-tools-dapp-browsers-wallets-and-other-projects), please ask in the Gitter room of that project, and if your issue is still not resolved, post an issue in the repo for that project. +If you have a technical issue with a specific client, application or tool, e.g. those listed [here](/clients/clients-tools-dapp-browsers-wallets-and-other-projects.md), please ask in the Gitter room of that project, and if your issue is still not resolved, post an issue in the repo for that project. You can make suggestions to all pages using the "Edit on GitHub" link in the top right of each page. When suggesting a change, please add a comment as to why you're making the change. @@ -35,7 +35,7 @@ Eth.wiki adopts Wikipedia's [five pillars](https://en.wikipedia.org/wiki/Wikiped ### License and contributor license agreement -All contributions are accepted under the [CC0 license](https://creativecommons.org/publicdomain/zero/1.0/legalcode) [1](https://creativecommons.org/share-your-work/public-domain/cc0/), which makes your contributions have no rights reserved, putting them in the public domain. This will help to allow for the dissemination of information about Ethereum, the Ethereum ecosystem and Web 3 to the public, in a completely permissive manner. To state that you accept your contributions to be under a CC0 license, please add yourself to the list of external contributors [here](CC0-license#list-of-contributors). +All contributions are accepted under the [CC0 license](https://creativecommons.org/publicdomain/zero/1.0/legalcode) [1](https://creativecommons.org/share-your-work/public-domain/cc0/), which makes your contributions have no rights reserved, putting them in the public domain. This will help to allow for the dissemination of information about Ethereum, the Ethereum ecosystem and Web 3 to the public, in a completely permissive manner. ## Other Ethereum Wikis @@ -45,3 +45,4 @@ All contributions are accepted under the [CC0 license](https://creativecommons.o - [Giveth](https://wiki.giveth.io/) - [The Homestead Guide](http://ethdocs.org/en/latest/) (a historical reference, some parts may be outdated). - [Old github wiki](https://github.com/ethereum/wiki/wiki) + diff --git a/howto/ethereum-development-tutorial.md b/howto/ethereum-development-tutorial.md index 6cb7041..d8d031b 100644 --- a/howto/ethereum-development-tutorial.md +++ b/howto/ethereum-development-tutorial.md @@ -121,7 +121,7 @@ Finally, we SSTORE to save the value 2020202020 in storage at index 54. At index 17, there is no instruction, so we stop. If there was anything left in the stack or memory, it would be deleted, but the storage will stay and be available next time someone sends a message. Thus, if the sender of this message sends the same message again (or perhaps someone else tries to reregister 54 to 3030303030), the next time the `JUMPI` at position 8 would not process, and execution would STOP early at position 9. -Fortunately, you do not have to program in low-level assembly; a high-level language especially designed for writing contracts, known as [Solidity](Solidity), exists to make it much easier for you to write contracts (there are several others, too, including [LLL](https://github.com/ethereum/cpp-ethereum/wiki/LLL-PoC-5), [Vyper](https://github.com/vyperlang/vyper) and [Mutan](https://github.com/ethereum/go-ethereum/wiki/Mutan-0.2), which you may find easier to learn or use depending on your experience). Any code you write in these languages gets compiled into EVM, and to create the contracts you send the transaction containing the EVM bytecode. +Fortunately, you do not have to program in low-level assembly; a high-level language especially designed for writing contracts, known as [Solidity](http://solidity.readthedocs.io), exists to make it much easier for you to write contracts (there are several others, too, including [LLL](https://github.com/ethereum/cpp-ethereum/wiki/LLL-PoC-5), [Vyper](https://github.com/vyperlang/vyper) and [Mutan](https://github.com/ethereum/go-ethereum/wiki/Mutan-0.2), which you may find easier to learn or use depending on your experience). Any code you write in these languages gets compiled into EVM, and to create the contracts you send the transaction containing the EVM bytecode. There are two types of transactions: a sending transaction and a contract creating transaction. A sending transaction is a standard transaction, containing a receiving address, an ether amount, a data bytearray and some other parameters, and a signature from the private key associated with the sender account. A contract creating transaction looks like a standard transaction, except the receiving address is blank. When a contract creating transaction makes its way into the blockchain, the data bytearray in the transaction is interpreted as EVM code, and the value returned by that EVM execution is taken to be the code of the new contract; hence, you can have a transaction do certain things during initialization. The address of the new contract is deterministically calculated based on the sending address and the number of times that the sending account has made a transaction before (this value, called the account nonce, is also kept for unrelated security reasons). Thus, the full code that you need to put onto the blockchain to produce the above name registry is as follows: @@ -147,7 +147,7 @@ A complete listing of the opcodes in the EVM can be found in the [yellow paper]( ## Basics of the Ethereum Blockchain -The Ethereum blockchain (or "ledger") is the decentralized, massively replicated database in which the current state of all accounts is stored. The blockchain uses a database called a [Patricia tree](Patricia-Tree) (or "trie") to store all accounts; this is essentially a specialized kind of Merkle tree that acts as a generic key/value store. Like a standard Merkle tree, a Patricia tree has a "root hash" that can be used to refer to the entire tree, and the contents of the tree cannot be modified without changing the root hash. For each account, the tree stores a 4-tuple containing `[account_nonce, ether_balance, code_hash, storage_root]`, where `account_nonce` is the number of transactions sent from the account (kept to prevent replay attacks), `ether_balance` is the balance of the account, `code_hash` the hash of the code if the account is a contract and "" otherwise, and `storage_root` is the root of yet another Patricia tree which stores the storage data. +The Ethereum blockchain (or "ledger") is the decentralized, massively replicated database in which the current state of all accounts is stored. The blockchain uses a database called a [Patricia tree](/fundamentals/patricia-tree.md) (or "trie") to store all accounts; this is essentially a specialized kind of Merkle tree that acts as a generic key/value store. Like a standard Merkle tree, a Patricia tree has a "root hash" that can be used to refer to the entire tree, and the contents of the tree cannot be modified without changing the root hash. For each account, the tree stores a 4-tuple containing `[account_nonce, ether_balance, code_hash, storage_root]`, where `account_nonce` is the number of transactions sent from the account (kept to prevent replay attacks), `ether_balance` is the balance of the account, `code_hash` the hash of the code if the account is a contract and "" otherwise, and `storage_root` is the root of yet another Patricia tree which stores the storage data. ![we](https://raw.githubusercontent.com/ethereumbuilders/GitBook/master/en/vitalik-diagrams/chaindiag.png) @@ -175,4 +175,4 @@ To get early traffic to your Ðapp, you can submit your Ðapp to [Dapp Insight]( ## Fine Points To Keep Track Of -See [subtleties](../faqs/subtleties.md) +See [subtleties](/faqs/subtleties.md) diff --git a/howto/smart-contract-safety.md b/howto/smart-contract-safety.md index 308f29c..3b30e36 100644 --- a/howto/smart-contract-safety.md +++ b/howto/smart-contract-safety.md @@ -891,7 +891,7 @@ Here are some of them. Feel free to add more. ##### By Community -- +- (dead link) - - - diff --git a/ideas/distributed-preimage-archive.md b/ideas/distributed-preimage-archive.md index 0ebef26..ca7298d 100644 --- a/ideas/distributed-preimage-archive.md +++ b/ideas/distributed-preimage-archive.md @@ -78,6 +78,6 @@ From the set up of the first forward onwards, all retrieval requests of the same ## Routing -It is based on Kademlia's routing. [details](Cademlia-Peer-Selection) +It is based on Kademlia's routing. [details](/ideas/kademlia-peer-selection.md) _to be continued..._ diff --git a/ideas/middleware-and-dapp-project-ideas.md b/ideas/middleware-and-dapp-project-ideas.md index 635d59f..9b46265 100755 --- a/ideas/middleware-and-dapp-project-ideas.md +++ b/ideas/middleware-and-dapp-project-ideas.md @@ -73,7 +73,7 @@ Supported actions should ideally include: ## RANDAO -Essentially, [this](https://forum.ethereum.org/discussion/2031/randao-a-dao-working-as-rng). Set it up as a decentralized service which any lottery or other randomness-based game can use; also, build a "full node software" package/plugin which facilitates participating in the RANDAO by providing random numbers. +Essentially, [this](https://forum.ethereum.org/discussion/2031/randao-a-dao-working-as-rng)(dead link). Set it up as a decentralized service which any lottery or other randomness-based game can use; also, build a "full node software" package/plugin which facilitates participating in the RANDAO by providing random numbers. ## Interface with national ID diff --git a/json-rpc/api.md b/json-rpc/api.md index 6692d37..18c4fdf 100755 --- a/json-rpc/api.md +++ b/json-rpc/api.md @@ -24,7 +24,7 @@ Nethermind has pub/sub support. See [this](https://docs.nethermind.io/nethermind To talk to an ethereum node from inside a JavaScript application use the [web3.js](https://github.com/ethereum/web3.js) library, which gives a convenient interface for the RPC methods. -See the [JavaScript API](/clients/javascript-api) for more details. +See the [JavaScript API](/archive/javascript-api.md) for more details. ## JSON-RPC Endpoint @@ -124,11 +124,11 @@ Currently [cpp-ethereum](https://github.com/ethereum/cpp-ethereum),[go-ethereum] The following methods have an extra default block parameter: -- [eth_getBalance](#eth_getbalance) -- [eth_getCode](#eth_getcode) -- [eth_getTransactionCount](#eth_gettransactioncount) -- [eth_getStorageAt](#eth_getstorageat) -- [eth_call](#eth_call) +- [eth_getBalance](https://openethereum.github.io/JSONRPC-eth-module#eth_getbalance) +- [eth_getCode](https://openethereum.github.io/JSONRPC-eth-module#eth_getcode) +- [eth_getTransactionCount](https://openethereum.github.io/JSONRPC-eth-module#eth_gettransactioncount) +- [eth_getStorageAt](https://openethereum.github.io/JSONRPC-eth-module#eth_getstorageat) +- [eth_call](https://openethereum.github.io/JSONRPC-eth-module#eth_call) When requests are made that act on the state of ethereum, the last default block parameter determines the height of the block. diff --git a/research/alternative-blockchains-randomness-economics-and-other-research-topics.md b/research/alternative-blockchains-randomness-economics-and-other-research-topics.md index 1cdf610..36711f6 100644 --- a/research/alternative-blockchains-randomness-economics-and-other-research-topics.md +++ b/research/alternative-blockchains-randomness-economics-and-other-research-topics.md @@ -37,7 +37,7 @@ Cryptocurrencies](https://ipfs.io/ipfs/QmUy4jh5mGNZvLkjies1RWM4YuvJh5o2FYopNPVYw ### Ziliqa -[Ziliqa](https://docs.zilliqa.com/whitepaper.pdf): a PoW sharded architecture consisting of a dataflow smart contract layer, and 5 other layers. Uses the EC-Schnorr multiginature signature scheme. However, RANDAO is preferable to aggregate/multisignature schemes since it is not prone to a 51% attack. Also uses committees, as is planned with Dfinity and Ethereum, although here the committees manage how miners are assigned to shards, whereas in Ethereum that is the task of the beacon chain and the sharding manager contract on the main chain. Uses PBFT consensus, which doesn't seem to be as good as [Casper](../concepts/casper-proof-of-stake-compendium.md) [FFG](https://eips.ethereum.org/EIPS/eip-1011), which is also used with PoW. +[Ziliqa](https://docs.zilliqa.com/whitepaper.pdf): a PoW sharded architecture consisting of a dataflow smart contract layer, and 5 other layers. Uses the EC-Schnorr multiginature signature scheme. However, RANDAO is preferable to aggregate/multisignature schemes since it is not prone to a 51% attack. Also uses committees, as is planned with Dfinity and Ethereum, although here the committees manage how miners are assigned to shards, whereas in Ethereum that is the task of the beacon chain and the sharding manager contract on the main chain. Uses PBFT consensus, which doesn't seem to be as good as [Casper](/concepts/casper-proof-of-stake-compendium.md) [FFG](https://eips.ethereum.org/EIPS/eip-1011), which is also used with PoW. ### EOS diff --git a/research/rd.md b/research/rd.md index 6ff3f51..5b6c55a 100755 --- a/research/rd.md +++ b/research/rd.md @@ -4,7 +4,7 @@ A broad introduction to and overview of Ethereum research is available at [Ether ## Sharding -Sharding introductory information is available [here](Sharding-introduction-R&D-compendium). +Sharding introductory information is available [here](/sharding/sharding-introduction-r-d-compendium.md). ## Ethereum research communication channels diff --git a/research/scaling-projects-and-proposals-and-other-crypto-infrastructure-projects.md b/research/scaling-projects-and-proposals-and-other-crypto-infrastructure-projects.md index 2d709ac..0be5772 100644 --- a/research/scaling-projects-and-proposals-and-other-crypto-infrastructure-projects.md +++ b/research/scaling-projects-and-proposals-and-other-crypto-infrastructure-projects.md @@ -14,8 +14,8 @@ Of all the crypto projects I've looked into so far, including Ethereum, [Holocha See also [these scaling proposals](https://github.com/jpitts/eth-community-discussions/blob/master/proposals-to-scale.md). Alternative approaches to scaling other than sharding include state channels, side chains, multi-chains and off-chain computation. Projects are included [here in this summary spreadsheet by the Web3 Foundation](https://docs.google.com/spreadsheets/d/1BQ0bK_LhSQvxtvXryVoIcmxeKMuVJCq6oD0aS5_hpC8). [Parity Substrate](https://www.reddit.com/r/ethereum/comments/8dgoup/parity_substrate/) is another project. Other designs and sources of inspiration include: -- [projects related to relaying transactions](https://github.com/ethereum/wiki/wiki/Relay-projects) -- [storage incentivization projects](https://github.com/ethereum/wiki/wiki/Storage-projects) +- [projects related to relaying transactions](/research/relay-projects.md) +- [storage incentivization projects](/research/storage-projects.md) - [Dfinity](https://www.dfinity.org/pdf-viewer/pdfs/viewer?file=../library/dfinity-consensus.pdf), uses a random beacon chain and notaries, which Ethereum plans to implement, although the randomness source may be [RANDAO](https://github.com/ethereum/research/blob/master/sharding_fork_choice_poc/beacon_chain_node.py) instead of BLS aggregate signatures. - [Truebit](https://truebit.io/) interactive verification off-chain protocol for Ethereum. @@ -34,7 +34,7 @@ Cryptocurrencies](https://ipfs.io/ipfs/QmUy4jh5mGNZvLkjies1RWM4YuvJh5o2FYopNPVYw ## Ziliqa -[Ziliqa](https://docs.zilliqa.com/whitepaper.pdf): a PoW sharded architecture consisting of a dataflow smart contract layer, and 5 other layers. Uses the EC-Schnorr multiginature signature scheme. However, RANDAO is preferable to aggregate/multisignature schemes since it is not prone to a 51% attack. Also uses committees, as is planned with Dfinity and Ethereum, although here the committees manage how miners are assigned to shards, whereas in Ethereum that is the task of the beacon chain and the sharding manager contract on the main chain. Uses PBFT consensus, which doesn't seem to be as good as [Casper](https://github.com/ethereum/wiki/wiki/Casper-Proof-of-Stake-compendium) [FFG](https://eips.ethereum.org/EIPS/eip-1011), which is also used with PoW. +[Ziliqa](https://docs.zilliqa.com/whitepaper.pdf): a PoW sharded architecture consisting of a dataflow smart contract layer, and 5 other layers. Uses the EC-Schnorr multiginature signature scheme. However, RANDAO is preferable to aggregate/multisignature schemes since it is not prone to a 51% attack. Also uses committees, as is planned with Dfinity and Ethereum, although here the committees manage how miners are assigned to shards, whereas in Ethereum that is the task of the beacon chain and the sharding manager contract on the main chain. Uses PBFT consensus, which doesn't seem to be as good as [Casper](/concepts/casper-proof-of-stake-compendium.md) [FFG](https://eips.ethereum.org/EIPS/eip-1011), which is also used with PoW. ## EOS @@ -44,7 +44,7 @@ Cryptocurrencies](https://ipfs.io/ipfs/QmUy4jh5mGNZvLkjies1RWM4YuvJh5o2FYopNPVYw Both lack a Turing complete language to use for stored procedures (more commonly known by the less appropriate name of smart contract) and decentralised apps (dapps) -Regarding Bitcoin Cash, doubling the block limit does not seem like a good idea, as it makes the network more centralized. The roadmap also includes "adaptive block size (market driven growth to 1 TB). Again this is not good for decentralization and security. It's uncertain how Bitcoin Cash and Bitcoin are going to be sustainable by having low rewards and high fees (and no gas limit, which is not good for pricing economics; FMI see DRAFT: Position paper on resource pricing (https://ethresear.ch/t/draft-position-paper-on-resource-pricing/2838)). Both will continue to use PoW which is bad for scaling, energy consumption, decentralization and security. Bitcoin using Lightning Network isn't sustainable long-term (like other L2 solutions); FMI see ethereum/wiki (https://github.com/ethereum/wiki/wiki/Sharding-FAQs#how-does-plasma-state-channels-and-other-layer-2-technologies-fit-into-the-trilemma). +Regarding Bitcoin Cash, doubling the block limit does not seem like a good idea, as it makes the network more centralized. The roadmap also includes "adaptive block size (market driven growth to 1 TB). Again this is not good for decentralization and security. It's uncertain how Bitcoin Cash and Bitcoin are going to be sustainable by having low rewards and high fees (and no gas limit, which is not good for pricing economics; FMI see DRAFT: Position paper on resource pricing (https://ethresear.ch/t/draft-position-paper-on-resource-pricing/2838)). Both will continue to use PoW which is bad for scaling, energy consumption, decentralization and security. Bitcoin using Lightning Network isn't sustainable long-term (like other L2 solutions); FMI see ethereum/wiki (/sharding/Sharding-FAQs.md#how-does-plasma-state-channels-and-other-layer-2-technologies-fit-into-the-trilemma). ## Early research -For precursor research scaling ideas, see para 2. [here](https://vitalik.ca/2017-09-15-prehistory.html) (see the links to hypercubes and [Chain Fibers](https://github.com/ethereum/wiki/wiki/Chain-Fibers-Redux)—a precursor to [sharding](https://github.com/ethereum/wiki/wiki/Sharding-introduction-R&D-compendium), as well as hub-and-spoke chains). \ No newline at end of file +For precursor research scaling ideas, see para 2. [here](https://vitalik.ca/2017-09-15-prehistory.html) (see the links to hypercubes and [Chain Fibers](/scalability/chain-fibers-redux.md)—a precursor to [sharding](/sharding/sharding-introduction-r-d-compendium.md), as well as hub-and-spoke chains). \ No newline at end of file diff --git a/roadmap/berlin.md b/roadmap/berlin.md index ad9ce3d..b0c2fcd 100755 --- a/roadmap/berlin.md +++ b/roadmap/berlin.md @@ -6,7 +6,7 @@ date: 2019-08-31T06:20:37.853Z tags: --- -The [Etherum 1.x](/eth1) page is a good starting point for an overview of Working Groups and areas of focus. +The [Etherum 1.x](/eth1/eth1.md) page is a good starting point for an overview of Working Groups and areas of focus. # Philosophy diff --git a/roadmap/istanbul.md b/roadmap/istanbul.md index 7973369..4630dc1 100755 --- a/roadmap/istanbul.md +++ b/roadmap/istanbul.md @@ -6,7 +6,7 @@ date: 2019-12-08T12:08:56.664Z tags: --- -The [Etherum 1.x](/eth1) page is a good starting point for an overview of Working Groups and areas of focus. +The [Etherum 1.x](/eth1/eth1.md) page is a good starting point for an overview of Working Groups and areas of focus. # Philosophy @@ -200,7 +200,7 @@ Below are some themes that were among the discussed potential changes. |[EIP-1380](https://eips.ethereum.org/EIPS/eip-1380)|Reduced gas cost for call to self|Tentatively accepted (Berlin)|Tentatively accepted in decision [67.1](https://github.com/ethereum/pm/blob/master/All%20Core%20Devs%20Meetings/Meeting%2067.md)|Independent| |[EIP-1559](https://eips.ethereum.org/EIPS/eip-1559)|Fee market change for ETH 1.0 chain|Withdrawn| Not completed in time. Concerns about effect on [transaction propagation](https://youtu.be/lF_XxqxgVuA?t=4506). Withdrawn in decision [67.4](https://github.com/ethereum/pm/blob/master/All%20Core%20Devs%20Meetings/Meeting%2067.md) due to lack of champion.|Independent| |[EIP-1702](https://eips.ethereum.org/EIPS/eip-1702)| Generalized Account Versioning Scheme|Tentatively accepted (Berlin)|Design-1 variant was been accepted in decision [63.2](https://github.com/ethereum/pm/blob/master/All%20Core%20Devs%20Meetings/Meeting%2063.md). Concerns about what specifically this is needed for.|Account versioning| -|[EIP-1706](https**://eips.ethereum.org/EIPS/eip-1706)|Disable SSTORE with gasleft lower than call stipend|Rejected/Withdrawn|Replaced by EIP-2200 (Accepted)|Storage writing| +|[EIP-1706](https://eips.ethereum.org/EIPS/eip-1706)|Disable SSTORE with gasleft lower than call stipend|Rejected/Withdrawn|Replaced by EIP-2200 (Accepted)|Storage writing| |[EIP-1707](https://github.com/ethereum/EIPs/pull/1707)|Use Version Byte Prefix for Contract Account Versioning|Rejected/Withdrawn (not proposed)|Superceded by 1702 (which is tentatively accepted (Berlin))|Account versioning| |[EIP-1712](https://github.com/ethereum/EIPs/pull/1712)|Disallow Deployment of Unused Opcodes|Rejected/Withdrawn (not proposed)|Superceded by 1702 (which is tentatively accepted (Berlin))|Account versioning| |[EIP-1803](https://eips.ethereum.org/EIPS/eip-1803)|Rename opcodes for clarity|Rejected/Withdrawn|Rejected in decision [67.2](https://github.com/ethereum/pm/blob/master/All%20Core%20Devs%20Meetings/Meeting%2067.md) due to lack of champion.|Independent| @@ -354,7 +354,7 @@ There was a [discussion](https://ethereum-magicians.org/t/eip-1109-remove-call-c - It can be [beneficial](https://gitter.im/ethereum/AllCoreDevs?at=5cfa2e6a702b7e5e76439672) to implement net gas metering without account versioning, because existing contracts can also receive gas reduction. #### Key decisions: -- Are there any opposed to implementing 1706 even if not explicitly required by 1283 (that is, if account versioning goes ahead)? If no, people need to review the 1706 [implementation](paritytech/parity-ethereum#10191) (the original fix for 1283). +- Are there any opposed to implementing 1706 even if not explicitly required by 1283 (that is, if account versioning goes ahead)? If no, people need to review the 1706 [implementation](https://github.com/paritytech/parity-ethereum#10191) (the original fix for 1283). #### Storage Writing Cluster Outcome @@ -496,4 +496,4 @@ Planned prototyping and implementation, in order of decreasing priority: # Post-Istanbul -The next fork will be called [Muir Glacier](eth.wiki/roadmap/muir_glacier) and will address the difficulty bomb. +The next fork will be called [Muir Glacier](/roadmap/muir_glacier.md) and will address the difficulty bomb. diff --git a/roadmap/istanbul/tracker.md b/roadmap/istanbul/tracker.md index 8236c5c..f07adea 100755 --- a/roadmap/istanbul/tracker.md +++ b/roadmap/istanbul/tracker.md @@ -6,8 +6,7 @@ date: 2019-07-01T17:38:54.103Z tags: --- -* See [Istanbul Roadmap](/roadmap/istanbul) -* See [all Istanbul pages](/roadmap/istanbul/all) +* See [Istanbul Roadmap](/roadmap/istanbul.md) ## Clients diff --git a/roadmap/london.md b/roadmap/london.md index 3639493..2ffe6f0 100755 --- a/roadmap/london.md +++ b/roadmap/london.md @@ -6,7 +6,7 @@ date: 2019-08-31T06:09:10.582Z tags: --- -The [Etherum 1.x](/eth1) page is a good starting point for an overview of Working Groups and areas of focus. +The [Etherum 1.x](/eth1/eth1.md) page is a good starting point for an overview of Working Groups and areas of focus. # Philosophy diff --git a/roadmap/petersburg.md b/roadmap/petersburg.md index 515c6b8..4d9fe70 100755 --- a/roadmap/petersburg.md +++ b/roadmap/petersburg.md @@ -1,7 +1,7 @@ -Petersburg is the "fix" that is being applied on top of [Constantinople](/roadmap#constantinople). It removes [EIP-1283](https://eips.ethereum.org/EIPS/eip-1283), and it is being applied / deployed at the same time as the February 25th, 2019 Constantinople work. +Petersburg is the "fix" that is being applied on top of [Constantinople](/roadmap/roadmap.md#constantinople). It removes [EIP-1283](https://eips.ethereum.org/EIPS/eip-1283), and it is being applied / deployed at the same time as the February 25th, 2019 Constantinople work. Roughly, Constantinople activates the new EIPs including 1283, and then Petersburg immediately de-activates 1283. diff --git a/roadmap/releases.md b/roadmap/releases.md index 6ca3cb2..d8bcb58 100755 --- a/roadmap/releases.md +++ b/roadmap/releases.md @@ -11,9 +11,9 @@ While still valid, the substance behind Ethereum has changed, and will continue - **Release step 2.0: Homestead**, launched 14 March 2016 (Pi Day) at block number 1,150,000 as announced [here](https://blog.ethereum.org/2016/02/29/homestead-release/). For changes in the Homestead release, see [this EIP](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.md). Homestead marked the exit from a beta product to a stable release. - **Release step 2.1: DAO Hard Fork** - **Release step 2.2: Tangerine Whistle**, aka Anti-DoS, EIP 150 -- **Release step 2.3: Spurious Dragon**, aka State-clearing, EIP 158/161, was released in Nov 2016. Spurious Dragon is aiming for [Dapp developers](../fundamentals/dapp-developer-resources.md) as well as end users for limited categories of applications, and had a number of security enhancements. -- **Release Step 3.0: Metropolis phase 1: Byzantium**, October 16 2017 as announced [here](https://blog.ethereum.org/2017/10/12/byzantium-hf-announcement/). Byzantium aims to introduce various privacy and functionality improvements. Details are [here](https://github.com/ethereum/EIPs#accepted-eips-planned-for-adoption-in-the-byzantium-metropolis-hard-fork). For the Byzantium Hard Fork, refer to [here](https://web.archive.org/web/20171026151615/https://github.com/ethereum/EIPs#accepted-eips-planned-for-adoption-in-the-byzantium-metropolis-hard-fork), which is an archive link showing the Byzantium EIPs. Also, refer to [here](../roadmap/byzantium-hard-fork-changes.md) for a quick summary of Byzantium EIPs. +- **Release step 2.3: Spurious Dragon**, aka State-clearing, EIP 158/161, was released in Nov 2016. Spurious Dragon is aiming for [Dapp developers](/fundamentals/dapp-developer-resources.md) as well as end users for limited categories of applications, and had a number of security enhancements. +- **Release Step 3.0: Metropolis phase 1: Byzantium**, October 16 2017 as announced [here](https://blog.ethereum.org/2017/10/12/byzantium-hf-announcement/). Byzantium aims to introduce various privacy and functionality improvements. Details are [here](https://github.com/ethereum/EIPs#accepted-eips-planned-for-adoption-in-the-byzantium-metropolis-hard-fork). For the Byzantium Hard Fork, refer to [here](https://web.archive.org/web/20171026151615/https://github.com/ethereum/EIPs#accepted-eips-planned-for-adoption-in-the-byzantium-metropolis-hard-fork), which is an archive link showing the Byzantium EIPs. Also, refer to [here](/roadmap/byzantium-hard-fork-changes.md) for a quick summary of Byzantium EIPs. - **Release Step 3.1: Metropolis phase 2: Constantinople**, TBA, expected in 2018. Details on Metropolis are [here](https://github.com/ethereum/EIPs#deferred-eips-adoption-postponed-until-the-constantinople-metropolis-hard-fork). [This archive link lists the deferred Constantinople EIPs](https://web.archive.org/web/20180103233351/https://github.com/ethereum/EIPS#deferred-eips-adoption-postponed-until-the-constantinople-metropolis-hard-fork). This is an archive link in case the EIPs list is changed in a way that does not breakdown EIPs into different releases, as is the case up until now. -- **Release Step Four: Serenity**, TBA. Serenity is meant to move from consensus through [Proof-of-Work](Ethash) to [Proof-of-Stake](../concepts/proof-of-stake-faqs.md). Details are [here](https://blog.ethereum.org/2016/03/05/serenity-poc2/) and [here](https://blog.ethereum.org/2015/12/24/understanding-serenity-part-i-abstraction/), although the second post seems outdated as abstraction has moved forward to Constantinople. +- **Release Step Four: Serenity**, TBA. Serenity is meant to move from consensus through [Proof-of-Work](/concepts/ethash/ethash.md) to [Proof-of-Stake](/concepts/proof-of-stake-faqs.md). Details are [here](https://blog.ethereum.org/2016/03/05/serenity-poc2/) and [here](https://blog.ethereum.org/2015/12/24/understanding-serenity-part-i-abstraction/), although the second post seems outdated as abstraction has moved forward to Constantinople. - For other changes, refer to the [the finalized list of EIPs](https://github.com/ethereum/EIPS#finalized-eips-standards-that-have-been-adopted). -- Further releases will focus on massive scalability increases through sharding as well as virtual machine improvements and other features, as detailed [here](../concepts/wishlist.md). +- Further releases will focus on massive scalability increases through sharding as well as virtual machine improvements and other features, as detailed [here](/concepts/wishlist.md). diff --git a/roadmap/roadmap.md b/roadmap/roadmap.md index 1deaaff..59d3a89 100755 --- a/roadmap/roadmap.md +++ b/roadmap/roadmap.md @@ -1,10 +1,10 @@ # Roadmap -Prior information is available on the [releases](/releases) page. +Prior information is available on the [releases](/roadmap/releases.md) page. The formal process of hardforks is documented in [EIP 233](https://eips.ethereum.org/EIPS/eip-233), along with some recent discussion on [EthMagicians](https://ethereum-magicians.org/t/eep-5-ethereum-hardfork-process-request-for-collaboration/2305). -The [ETH1](/eth1) page lists Working Groups and areas of focus. +The [ETH1](/eth1/eth1.md) page lists Working Groups and areas of focus. ## Philosophy @@ -32,10 +32,10 @@ Steps for EIPs: | 5 | 2675000 | 2016-11-22 | Spurious Dragon | | 6 | 4370000 | 2017-10-16 | Byzantium | | 7 | 7280000 | 2019-02-28 | Constantinople | -| 8 | 9069000 | 2019-12-08 | [Istanbul](/roadmap/istanbul) | -| 9 | 9200000 | 2019-12-31 (tentative) | [Muir Glacier](/roadmap/muir_glacier) | -| 10 | TBD | 2020-06 (tentative) | [Berlin](/roadmap/berlin) | -| 11 | TBD | TBD | [London](/roadmap/london) | +| 8 | 9069000 | 2019-12-08 | [Istanbul](/roadmap/istanbul.md) | +| 9 | 9200000 | 2019-12-31 (tentative) | [Muir Glacier](/roadmap/muir_glacier.md) | +| 10 | TBD | 2020-06 (tentative) | [Berlin](/roadmap/berlin.md) | +| 11 | TBD | TBD | [London](/roadmap/london.md) | | 12 | TBC | TBC | Shanghai | | 13 | TBC | TBC | Devcon names thereafter | @@ -81,7 +81,7 @@ meta-EIP [here](https://eips.ethereum.org/EIPS/eip-609) ## Constantinople -Initially planned for Q1 of 2019, this fork was delayed to allow for evaluation of one of the EIPs. The fork went ahead without that EIP (EIP-1283) and was referred to by some as the Petersburg fork. More [here](/roadmap/petersburg). +Initially planned for Q1 of 2019, this fork was delayed to allow for evaluation of one of the EIPs. The fork went ahead without that EIP (EIP-1283) and was referred to by some as the Petersburg fork. More [here](/roadmap/petersburg.md). Noteable in this upgrade were changes to allow layer 2 solutions to pre-define the addresses of future contracts. This allows state channels to deploy contracts that could be deployed on-chain, but may not be required to. @@ -98,7 +98,7 @@ More details can be found in: ## Istanbul -See the wiki page [here](/roadmap/istanbul) and the hard fork meta [here](https://eips.ethereum.org/EIPS/eip-1679) +See the wiki page [here](/roadmap/istanbul.md) and the hard fork meta [here](https://eips.ethereum.org/EIPS/eip-1679) EIP-152: Add Blake2 compression function F precompile EIP-1108: Reduce alt_bn128 precompile gas costs @@ -113,15 +113,15 @@ The Cat Herders blog [here](https://medium.com/ethereum-cat-herders/istanbul-tes ## Muir Glacier -An update to delay the difficulty bomb, see the wiki page [here](/roadmap/muir_glacier). +An update to delay the difficulty bomb, see the wiki page [here](/roadmap/muir_glacier.md). ## Berlin -See the wiki page [here](/roadmap/berlin). +See the wiki page [here](/roadmap/berlin.md). ## London -See the wiki page [here](/roadmap/london). +See the wiki page [here](/roadmap/london.md). ## Subsequent forks diff --git a/scalability/chain-fibers-redux.md b/scalability/chain-fibers-redux.md index 159afd2..55c4cd9 100644 --- a/scalability/chain-fibers-redux.md +++ b/scalability/chain-fibers-redux.md @@ -1,6 +1,6 @@ # Chain Fibers Redux -_This article describes a scalability proposal made by Gavin Wood in 2015. Many of the principles described here have been a key inspiration for subsequent "[sharding](../sharding/sharding-faqs.md)" proposals._ +_This article describes a scalability proposal made by Gavin Wood in 2015. Many of the principles described here have been a key inspiration for subsequent "[sharding](/sharding/Sharding-FAQs.md)" proposals._ ## Blockchain Scalability: Chain-Fibers Redux diff --git a/sharding/Sharding-FAQs.md b/sharding/Sharding-FAQs.md index 75a9bba..3a1cfb0 100644 --- a/sharding/Sharding-FAQs.md +++ b/sharding/Sharding-FAQs.md @@ -37,7 +37,7 @@ Many sharding proposals (e.g. [this early BFT sharding proposal from Loi Luu et Channel-based strategies (lightning network, Raiden, etc) can scale transaction capacity by a constant factor but cannot scale state storage, and also come with their own unique sets of tradeoffs and limitations particularly involving denial-of-service attacks. On-chain scaling via sharding (plus other techniques) and off-chain scaling via channels are arguably both necessary and complementary. -There exist approaches that use advanced cryptography, such as [Mimblewimble](https://scalingbitcoin.org/papers/mimblewimble.txt) and strategies based on ZK-SNARKs (eg. [Coda](https://codaprotocol.com/)), to solve one specific part of the scaling problem: initial full node synchronization. Instead of verifying the entire history from genesis, nodes could verify a cryptographic proof that the current state legitimately follows from the history. These approaches do solve a legitimate problem, but they are not a substitute for sharding, as they do not remove the need for nodes to download and verify very large amounts of data to stay on the chain in real time. +There exist approaches that use advanced cryptography, such as [Mimblewimble](https://scalingbitcoin.org/papers/mimblewimble.txt) and strategies based on ZK-SNARKs (eg. [Coda](https://codaprotocol.com/)(dead link)), to solve one specific part of the scaling problem: initial full node synchronization. Instead of verifying the entire history from genesis, nodes could verify a cryptographic proof that the current state legitimately follows from the history. These approaches do solve a legitimate problem, but they are not a substitute for sharding, as they do not remove the need for nodes to download and verify very large amounts of data to stay on the chain in real time. ## How does Plasma, state channels and other layer 2 technologies fit into the trilemma? @@ -45,9 +45,9 @@ In the event of a large attack on [Plasma](https://www.plasma.io) subchains, all Note that there is one design that states that: "Given a malicious operator (the worst case), the system degrades to an on-chain token. A malicious operator cannot steal funds and cannot deprive people of their funds for any meaningful amount of time."—. See also [here](https://twitter.com/PhABCD/status/1090090236380626944) for related information. -[State channels](http://www.jeffcoleman.ca/state-channels/) have similar properties, though with different tradeoffs between versatility and speed of finality. Other layer 2 technologies include [TrueBit](https://people.cs.uchicago.edu/~teutsch/papers/truebit.pdf) off-chain interactive verification of execution and [Raiden](https://raiden.network/), which is another organisation working on state channels. [Proof of stake](../concepts/proof-of-stake-faqs.md) with Casper (which is layer 1) would also improve scaling—it is more decentralizable, not requiring a computer that is able to mine, which tends towards centralized mining farms and institutionalized mining pools as difficulty increases and the size of the state of the blockchain increases. +[State channels](http://www.jeffcoleman.ca/state-channels/) have similar properties, though with different tradeoffs between versatility and speed of finality. Other layer 2 technologies include [TrueBit](https://people.cs.uchicago.edu/~teutsch/papers/truebit.pdf) off-chain interactive verification of execution and [Raiden](https://raiden.network/), which is another organisation working on state channels. [Proof of stake](/concepts/proof-of-stake-faqs.md) with Casper (which is layer 1) would also improve scaling—it is more decentralizable, not requiring a computer that is able to mine, which tends towards centralized mining farms and institutionalized mining pools as difficulty increases and the size of the state of the blockchain increases. -Sharding is different to state channels and Plasma in that periodically notaries are pseudo-randomly assigned to vote on the validity of collations (analogous to blocks, but without an EVM state transition function in phase 1), then these collations are accepted into the main chain after the votes are verified by a committee on the main chain, via a sharding manager contract on the main chain. In phase 5 (see the [roadmap](../sharding/sharding-roadmap.md) for details), shards are tightly coupled to the main chain, so that if any shard or the main chain is invalid, the whole network is invalid. There are other differences between each mechanism, but at a high level, Plasma, state channels and Truebit are off-chain for an indefinite interval, connect to the main chain at the smart contract, layer 2 level, while they can draw back into and open up from the main chain, whereas shards are regularly linked to the main chain via consensus in-protocol. +Sharding is different to state channels and Plasma in that periodically notaries are pseudo-randomly assigned to vote on the validity of collations (analogous to blocks, but without an EVM state transition function in phase 1), then these collations are accepted into the main chain after the votes are verified by a committee on the main chain, via a sharding manager contract on the main chain. In phase 5 (see the [roadmap](/sharding/sharding-roadmap.md) for details), shards are tightly coupled to the main chain, so that if any shard or the main chain is invalid, the whole network is invalid. There are other differences between each mechanism, but at a high level, Plasma, state channels and Truebit are off-chain for an indefinite interval, connect to the main chain at the smart contract, layer 2 level, while they can draw back into and open up from the main chain, whereas shards are regularly linked to the main chain via consensus in-protocol. See also [these tweets from Vlad](https://twitter.com/VladZamfir/status/1001447804219346945). @@ -155,7 +155,7 @@ Now, let’s look at the risk of attacks being made that try to influence the ra Due to the [central limit theorem](https://en.wikipedia.org/wiki/Central_limit_theorem), the standard deviation of the number of samples, and based [on other known results in math](http://math.stackexchange.com/questions/89030/expectation-of-the-maximum-of-gaussian-random-variables) the expected maximum of N random samples is slightly under M + S \* sqrt(2 \* log(N)) where M is the mean and S is the standard deviation. Hence the reward for manipulating the randomness and effectively re-rolling the dice (i.e. increasing N) drops off sharply, e.g. with 0 re-trials your expected reward is $100, with one re-trial it's $105.5, with two it's $108.5, with three it's $110.3, with four it's $111.6, with five it's $112.6 and with six it's $113.5. Hence, after five retrials it stops being worth it. As a result, an economically motivated attacker with ten percent of stake will (socially wastefully) spend $5 to get an additional revenue of $13, for a net surplus of $8. -However, this kind of logic assumes that one single round of re-rolling the dice is expensive. Many older proof of stake algorithms have a “stake grinding” vulnerability where re-rolling the dice simply means making a computation locally on one’s computer; algorithms with this vulnerability are certainly unacceptable in a sharding context. Newer algorithms (see the “validator selection” section in the [proof of stake FAQ](../concepts/proof-of-stake-faqs.md)) have the property that re-rolling the dice can only be done by voluntarily giving up one’s spot in the block creation process, which entails giving up rewards and fees. The best way to mitigate the impact of marginal economically motivated attacks on sample selection is to find ways to increase this cost. One method to increase the cost by a factor of sqrt(N) from N rounds of voting is the [majority-bit method devised by Iddo Bentov](https://arxiv.org/pdf/1406.5694.pdf). +However, this kind of logic assumes that one single round of re-rolling the dice is expensive. Many older proof of stake algorithms have a “stake grinding” vulnerability where re-rolling the dice simply means making a computation locally on one’s computer; algorithms with this vulnerability are certainly unacceptable in a sharding context. Newer algorithms (see the “validator selection” section in the [proof of stake FAQ](/concepts/proof-of-stake-faqs.md)) have the property that re-rolling the dice can only be done by voluntarily giving up one’s spot in the block creation process, which entails giving up rewards and fees. The best way to mitigate the impact of marginal economically motivated attacks on sample selection is to find ways to increase this cost. One method to increase the cost by a factor of sqrt(N) from N rounds of voting is the [majority-bit method devised by Iddo Bentov](https://arxiv.org/pdf/1406.5694.pdf). Another form of random number generation that is not exploitable by minority coalitions is the deterministic threshold signature approach most researched and advocated by Dominic Williams. The strategy here is to use a [deterministic threshold signature](https://eprint.iacr.org/2002/081.pdf) to generate the random seed from which samples are selected. Deterministic threshold signatures have the property that the value is guaranteed to be the same regardless of which of a given set of participants provides their data to the algorithm, provided that at least ⅔ of participants do participate honestly. This approach is more obviously not economically exploitable and fully resistant to all forms of stake-grinding, but it has several weaknesses: @@ -357,4 +357,4 @@ Abstracting the execution engine or allowing multiple execution engines to exist 14. Thanks to Justin Drake for pointing me to cryptographic accumulators, as well as [this paper](https://eprint.iacr.org/2009/612.pdf) that gives the argument for the impossibility of sublinear batching. See also this thread: -Further reading related to sharding, and more generally scalability and research, is available [here](./sharding-introduction-r-d-compendium.md) and [here](../research/rd.md). +Further reading related to sharding, and more generally scalability and research, is available [here](/sharding/sharding-introduction-r-d-compendium.md) and [here](/research/rd.md). diff --git a/sharding/sharding-introduction-r-d-compendium.md b/sharding/sharding-introduction-r-d-compendium.md index abcabb2..fcc04b7 100755 --- a/sharding/sharding-introduction-r-d-compendium.md +++ b/sharding/sharding-introduction-r-d-compendium.md @@ -13,16 +13,16 @@ tags: > Sharding+Casper/shasper with Ethereum 2.0 is the planned scaling approach for Ethereum; work is in progress on R&D. -Ethereum 1.0 can only process 7-15 transactions per second, the goal of sharding is to partition all network computational resources into shards, so that a node (a single computer as a peer connected to the network) doesn't have to process (download, compute, store, read) every transaction in the history of the blockchain, in order to make a new transaction (write and upload) or otherwise participate in securing and using Ethereum; rather a node can just participate in a single shard, or more if it so chooses. Multiple shards are handled separately by different subsets of securing participants, aka securitors (which include notaries, proposers, miners and validators)[\[1\]](https://eprint.iacr.org/2017/406.pdf). The primary goal is a massive scalability improvement, potentially exponential in phase 6 of the [roadmap](/sharding/sharding-roadmap); and probably at least a 100 fold increase in transactions per second with earlier phases. Quadratic sharding involves having shards at a depth of at most 1 from the main chain, that is, there are no shards within a shard, or a manager shard managing sub-shards; whereas exponential sharding has shards within shards, recursively. +Ethereum 1.0 can only process 7-15 transactions per second, the goal of sharding is to partition all network computational resources into shards, so that a node (a single computer as a peer connected to the network) doesn't have to process (download, compute, store, read) every transaction in the history of the blockchain, in order to make a new transaction (write and upload) or otherwise participate in securing and using Ethereum; rather a node can just participate in a single shard, or more if it so chooses. Multiple shards are handled separately by different subsets of securing participants, aka securitors (which include notaries, proposers, miners and validators)[\[1\]](https://eprint.iacr.org/2017/406.pdf). The primary goal is a massive scalability improvement, potentially exponential in phase 6 of the [roadmap](/sharding/sharding-roadmap.md); and probably at least a 100 fold increase in transactions per second with earlier phases. Quadratic sharding involves having shards at a depth of at most 1 from the main chain, that is, there are no shards within a shard, or a manager shard managing sub-shards; whereas exponential sharding has shards within shards, recursively. -Each one of the shards (likely 100 live in phase 1) will have as high a capacity (and likely more with phase 1) than the current existing Ethereum chain. A smart contract will exist on the main chain, called the sharding manager contract, which manages how data and transactions in shards are accepted as valid by the main chain, via notaries voting on the validity and data availability of collations (collections of data and transactions, analogous to blocks, but where they occur more frequently than blocks) in shards, and proposers proposing blobs (analogous to transactions but without execution in [phase 1](/sharding/sharding-roadmap)) which are collected into collations. +Each one of the shards (likely 100 live in phase 1) will have as high a capacity (and likely more with phase 1) than the current existing Ethereum chain. A smart contract will exist on the main chain, called the sharding manager contract, which manages how data and transactions in shards are accepted as valid by the main chain, via notaries voting on the validity and data availability of collations (collections of data and transactions, analogous to blocks, but where they occur more frequently than blocks) in shards, and proposers proposing blobs (analogous to transactions but without execution in [phase 1](/sharding/sharding-roadmap.md)) which are collected into collations. ## Information For information on sharding, refer to (sorted roughly from the most recent/important information to less recent): -- sharding [roadmap](/sharding/sharding-roadmap) -- [Sharding FAQs](/sharding/Sharding-FAQs) +- sharding [roadmap](/sharding/sharding-roadmap.md) +- [Sharding FAQs](/sharding/Sharding-FAQs.md) - a summary [here](https://twitter.com/sinahab/status/992755776765792256); - [ethresear.ch sharding category](https://ethresear.ch/c/sharding) (watch new posts); - [sharding protocol research tracker](https://github.com/Drops-of-Diamond/diamond_drops/issues/13) @@ -32,7 +32,7 @@ For information on sharding, refer to (sorted roughly from the most recent/impor - [Sharding workshop notes](https://hackmd.io/s/HJ_BbgCFz#%E2%9F%A0-General-Introduction) - [Ethereum sharding workshop blog post](https://medium.com/@icebearhww/ethereum-sharding-workshop-in-taipei-a44c0db8b8d9) - [HackMD note: Ethereum Research Sharding Compendium](http://notes.ethereum.org/s/BJc_eGVFM) -- [Wiki: ethresear.ch Sharding Compendium](/sharding/ethresearch-sharding-compendium) +- [Wiki: ethresear.ch Sharding Compendium](/sharding/ethresearch-sharding-compendium.md) ## Implementations @@ -57,8 +57,8 @@ Implementations under development include: ## Alternative scaling approaches to sharding -- Moved to [here](/research/alternative-blockchains-randomness-economics-and-other-research-topics). -- For precursor research scaling ideas, see para 2. [here](https://vitalik.ca/2017-09-15-prehistory.html) (see the links to hypercubes and [Chain Fibers](/scalability/chain-fibers-redux)—a precursor to [sharding](/sharding/sharding-introduction-r-d-compendium), as well as hub-and-spoke chains). - +- Moved to [here](/research/alternative-blockchains-randomness-economics-and-other-research-topics.md). +- For precursor research scaling ideas, see para 2. [here](https://vitalik.ca/2017-09-15-prehistory.html) (see the links to hypercubes and [Chain Fibers](/scalability/chain-fibers-redux.md)—a precursor to [sharding](/sharding/sharding-introduction-r-d-compendium.md), as well as hub-and-spoke chains). - - [Scaling proposals](https://github.com/jpitts/eth-community-discussions/blob/master/proposals-to-scale.md) ## Glossary diff --git a/sharding/sharding-roadmap.md b/sharding/sharding-roadmap.md index 9f5ab71..bd77538 100755 --- a/sharding/sharding-roadmap.md +++ b/sharding/sharding-roadmap.md @@ -24,7 +24,7 @@ Sourced originally from the now [retired spec for phase 1 sharding](https://ethr * Blobs (Binary Large Objects) are collated in shards without transactions (which require execution) * Proposers submit blobs * Notaries - * For more details, see the [phase 1 spec](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/1_shard-data-chains.md) and [implementations](https://github.com/ethereum/wiki/wiki/Sharding-introduction-R&D-compendium#implementations). + * For more details, see the [phase 1 spec](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/1_shard-data-chains.md) and [implementations](/sharding/sharding-introduction-r-d-compendium.md#implementations). ### Phase 2: EVM state transition function - Full nodes only @@ -48,7 +48,7 @@ Sourced originally from the now [retired spec for phase 1 sharding](https://ethr ### Phase 5: Tight coupling with main chain security: [here](https://hackmd.io/s/HJ_BbgCFz#%E2%9F%A0-1600---1645--Ethereum-20-End-game) and [more](https://ethresear.ch/search?q=tight%20coupling). - Data availability proofs: [A note on data availability and erasure coding](https://github.com/ethereum/research/wiki/A-note-on-data-availability-and-erasure-coding), , -- [Casper](Casper-Proof-of-Stake-compendium) integration. +- [Casper](/concepts/casper-proof-of-stake-compendium.md) integration. - [Internally fork-free sharding](https://ethresear.ch/search?q=internally%20fork-free) - Manager shard @@ -65,7 +65,7 @@ And a lot more: . ## Ethereum 3.0 -- Casper CBC integration. See [here](https://github.com/ethereum/wiki/wiki/Casper-Proof-of-Stake-compendium) FMI. +- Casper CBC integration. See [here](/concepts/casper-proof-of-stake-compendium.md) FMI. - zk-STARKs, e.g. via [StarkWare](https://www.starkware.co/); videos [here](https://www.youtube.com/watch?v=VUN35BC11Qw&t=2s), [here](https://www.youtube.com/watch?v=9VuZvdxFZQo&t=7s) and [here](https://www.youtube.com/watch?v=9VuZvdxFZQo&t=7s), as well as a paper [here](https://eprint.iacr.org/2018/046) (the abstract is a more succinct intro than the videos), while the full paper is more detailed; and - [heterogeneous sharding](https://ethresear.ch/t/heterogeneous-sharding/1979) - Outdated: [Are there any ideas that’s potentially more useful than implementing sharding?](https://ethresear.ch/t/are-there-any-ideas-thats-potentially-more-useful-than-implementing-sharding/334/3). \ No newline at end of file