mirror of https://github.com/ethereum/go-ethereum
[DOCS] massive documentation update (#20229)
This PR: - reorganizes all documentation pages so they live in the right category - removes lots of legacy docs - contains many improvements to active documentation pages Geth user documentation is now spread across five major categories: - Install and Build: installation and compile instructions - Using Geth: this is for pages about general geth usage. - For dApp Developers: this is for programming guides and functionality specific to dapp development. All the dev guides for mobile framework and Go APIs live here. - JSON-RPC APIs: this has its own section because there is now a sub-page for every name space. I have also added an overview text that explains how to set up the API servers. - For Geth Developers: this is for geth contributorspull/20251/head
Felix Lange
5 years ago
committed by
GitHub
parent
86b20d897e
commit
7416b05b81
@ -0,0 +1,324 @@ |
||||
--- |
||||
title: Mobile Account Management |
||||
--- |
||||
|
||||
To provide Ethereum integration for your mobile applications, the very first thing you |
||||
should be interested in doing is account management. |
||||
|
||||
Although all current leading Ethereum implementations provide account management built in, |
||||
it is ill advised to keep accounts in any location that is shared between multiple |
||||
applications and/or multiple people. The same way you do not entrust your ISP (who is |
||||
after all your gateway into the internet) with your login credentials; you should not |
||||
entrust an Ethereum node (who is your gateway into the Ethereum network) with your |
||||
credentials either. |
||||
|
||||
The proper way to handle user accounts in your mobile applications is to do client side |
||||
account management, everything self-contained within your own application. This way you |
||||
can ensure as fine grained (or as coarse) access permissions to the sensitive data as |
||||
deemed necessary, without relying on any third party application's functionality and/or |
||||
vulnerabilities. |
||||
|
||||
To support this, `go-ethereum` provides a simple, yet thorough accounts library that gives |
||||
you all the tools to do properly secured account management via encrypted keystores and |
||||
passphrase protected accounts. You can leverage all the security of the `go-ethereum` |
||||
crypto implementation while at the same time running everything in your own application. |
||||
|
||||
## Encrypted keystores |
||||
|
||||
Although handling your users' accounts locally on their own mobile device does provide |
||||
certain security guarantees, access keys to Ethereum accounts should never lay around in |
||||
clear-text form. As such, we provide an encrypted keystore that provides the proper |
||||
security guarantees for you without requiring a thorough understanding from your part of |
||||
the associated cryptographic primitives. |
||||
|
||||
The important thing to know when using the encrypted keystore is that the cryptographic |
||||
primitives used within can operate either in *standard* or *light* mode. The former |
||||
provides a higher level of security at the cost of increased computational burden and |
||||
resource consumption: |
||||
|
||||
* *standard* needs 256MB memory and 1 second processing on a modern CPU to access a key |
||||
* *light* needs 4MB memory and 100 millisecond processing on a modern CPU to access a key |
||||
|
||||
As such, *light* is more suitable for mobile applications, but you should be aware of the |
||||
trade-offs nonetheless. |
||||
|
||||
*For those interested in the cryptographic and/or implementation details, the key-store |
||||
uses the `secp256k1` elliptic curve as defined in the [Standards for Efficient |
||||
Cryptography](sec2), implemented by the [`libsecp256k`](secp256k1) library and wrapped by |
||||
[`github.com/ethereum/go-ethereum/accounts`](accounts-go). Accounts are stored on disk in |
||||
the [Web3 Secret Storage](secstore) format.* |
||||
|
||||
[sec2]: http://www.secg.org/sec2-v2.pdf |
||||
[accounts-go]: https://godoc.org/github.com/ethereum/go-ethereum/accounts |
||||
[secp256k1]: https://github.com/bitcoin-core/secp256k1 |
||||
[secstore]: https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition |
||||
|
||||
### Keystores on Android (Java) |
||||
|
||||
The encrypted keystore on Android is implemented by the `KeyStore` class from the |
||||
`org.ethereum.geth` package. The configuration constants (for the *standard* or *light* |
||||
security modes described above) are located in the `Geth` abstract class, similarly from |
||||
the `org.ethereum.geth` package. Hence to do client side account management on Android, |
||||
you'll need to import two classes into your Java code: |
||||
|
||||
```java |
||||
import org.ethereum.geth.Geth; |
||||
import org.ethereum.geth.KeyStore; |
||||
``` |
||||
|
||||
Afterwards you can create a new encrypted keystore via: |
||||
|
||||
```java |
||||
KeyStore ks = new KeyStore("/path/to/keystore", Geth.LightScryptN, Geth.LightScryptP); |
||||
``` |
||||
|
||||
The path to the keystore folder needs to be a location that is writable by the local |
||||
mobile application but non-readable for other installed applications (for security reasons |
||||
obviously), so we'd recommend placing it inside your app's data directory. If you are |
||||
creating the `KeyStore` from within a class extending an Android object, you will most |
||||
probably have access to the `Context.getFilesDir()` method via `this.getFilesDir()`, so |
||||
you could set the keystore path to `this.getFilesDir() + "/keystore"`. |
||||
|
||||
The last two arguments of the `KeyStore` constructor are the crypto parameters defining |
||||
how resource-intensive the keystore encryption should be. You can choose between |
||||
`Geth.StandardScryptN, Geth.StandardScryptP`, `Geth.LightScryptN, Geth.LightScryptP` or |
||||
specify your own numbers (please make sure you understand the underlying cryptography for |
||||
this). We recommend using the *light* version. |
||||
|
||||
### Keystores on iOS (Swift 3) |
||||
|
||||
The encrypted keystore on iOS is implemented by the `GethKeyStore` class from the `Geth` |
||||
framework. The configuration constants (for the *standard* or *light* security modes |
||||
described above) are located in the same namespace as global variables. Hence to do client |
||||
side account management on iOS, you'll need to import the framework into your Swift code: |
||||
|
||||
```swift |
||||
import Geth |
||||
``` |
||||
|
||||
Afterwards you can create a new encrypted account manager via: |
||||
|
||||
```swift |
||||
let ks = GethNewKeyStore("/path/to/keystore", GethLightScryptN, GethLightScryptP); |
||||
``` |
||||
|
||||
The path to the keystore folder needs to be a location that is writable by the local |
||||
mobile application but non-readable for other installed applications (for security reasons |
||||
obviously), so we'd recommend placing it inside your app's document directory. You should |
||||
be able to retrieve the document directory via `let datadir = |
||||
NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true)[0]`, so you |
||||
could set the keystore path to `datadir + "/keystore"`. |
||||
|
||||
The last two arguments of the `GethNewKeyStore` factory method are the crypto parameters |
||||
defining how resource-intensive the keystore encryption should be. You can choose between |
||||
`GethStandardScryptN, GethStandardScryptP`, `GethLightScryptN, GethLightScryptP` or |
||||
specify your own numbers (please make sure you understand the underlying cryptography for |
||||
this). We recommend using the *light* version. |
||||
|
||||
## Account lifecycle |
||||
|
||||
Having created an encrypted keystore for your Ethereum accounts, you can use this for the |
||||
entire account lifecycle requirements of your mobile application. This includes the basic |
||||
functionality of creating new accounts and deleting existing ones; as well as the more |
||||
advanced functionality of updating access credentials, exporting existing accounts, and |
||||
importing them on another device. |
||||
|
||||
Although the keystore defines the encryption strength it uses to store your accounts, |
||||
there is no global master password that can grant access to all of them. Rather each |
||||
account is maintained individually, and stored on disk in its [encrypted |
||||
format](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) |
||||
individually, ensuring a much cleaner and stricter separation of credentials. |
||||
|
||||
This individuality however means that any operation requiring access to an account will |
||||
need to provide the necessary authentication credentials for that particular account in |
||||
the form of a passphrase: |
||||
|
||||
* When creating a new account, the caller must supply a passphrase to encrypt the account |
||||
with. This passphrase will be required for any subsequent access, the lack of which |
||||
will forever forfeit using the newly created account. |
||||
* When deleting an existing account, the caller must supply a passphrase to verify |
||||
ownership of the account. This isn't cryptographically necessary, rather a protective |
||||
measure against accidental loss of accounts. |
||||
* When updating an existing account, the caller must supply both current and new |
||||
passphrases. After completing the operation, the account will not be accessible via the |
||||
old passphrase any more. |
||||
* When exporting an existing account, the caller must supply both the current passphrase |
||||
to decrypt the account, as well as an export passphrase to re-encrypt it with before |
||||
returning the key-file to the user. This is required to allow moving accounts between |
||||
devices without sharing original credentials. |
||||
* When importing a new account, the caller must supply both the encryption passphrase of |
||||
the key-file being imported, as well as a new passhprase with which to store the |
||||
account. This is required to allow storing account with different credentials than used |
||||
for moving them around. |
||||
|
||||
*Please note, there is no recovery mechanisms for losing the passphrases. The |
||||
cryptographic properties of the encrypted keystore (if using the provided parameters) |
||||
guarantee that account credentials cannot be brute forced in any meaningful time.* |
||||
|
||||
### Accounts on Android (Java) |
||||
|
||||
An Ethereum account on Android is implemented by the `Account` class from the |
||||
`org.ethereum.geth` package. Assuming we already have an instance of a `KeyStore` called |
||||
`ks` from the previous section, we can easily execute all of the described lifecycle |
||||
operations with a handful of function calls. |
||||
|
||||
```java |
||||
// Create a new account with the specified encryption passphrase. |
||||
Account newAcc = ksm.newAccount("Creation password"); |
||||
|
||||
// Export the newly created account with a different passphrase. The returned |
||||
// data from this method invocation is a JSON encoded, encrypted key-file. |
||||
byte[] jsonAcc = ks.exportKey(newAcc, "Creation password", "Export password"); |
||||
|
||||
// Update the passphrase on the account created above inside the local keystore. |
||||
ks.updateAccount(newAcc, "Creation password", "Update password"); |
||||
|
||||
// Delete the account updated above from the local keystore. |
||||
ks.deleteAccount(newAcc, "Update password"); |
||||
|
||||
// Import back the account we've exported (and then deleted) above with yet |
||||
// again a fresh passphrase. |
||||
Account impAcc = ks.importKey(jsonAcc, "Export password", "Import password"); |
||||
``` |
||||
|
||||
*Although instances of `Account` can be used to access various information about specific |
||||
Ethereum accounts, they do not contain any sensitive data (such as passphrases or private |
||||
keys), rather act solely as identifiers for client code and the keystore.* |
||||
|
||||
### Accounts on iOS (Swift 3) |
||||
|
||||
An Ethereum account on iOS is implemented by the `GethAccount` class from the `Geth` |
||||
framework. Assuming we already have an instance of a `GethKeyStore` called `ks` from the |
||||
previous section, we can easily execute all of the described lifecycle operations with a |
||||
handful of function calls. |
||||
|
||||
```swift |
||||
// Create a new account with the specified encryption passphrase. |
||||
let newAcc = try! ks?.newAccount("Creation password") |
||||
|
||||
// Export the newly created account with a different passphrase. The returned |
||||
// data from this method invocation is a JSON encoded, encrypted key-file. |
||||
let jsonKey = try! ks?.exportKey(newAcc!, passphrase: "Creation password", newPassphrase: "Export password") |
||||
|
||||
// Update the passphrase on the account created above inside the local keystore. |
||||
try! ks?.update(newAcc, passphrase: "Creation password", newPassphrase: "Update password") |
||||
|
||||
// Delete the account updated above from the local keystore. |
||||
try! ks?.delete(newAcc, passphrase: "Update password") |
||||
|
||||
// Import back the account we've exported (and then deleted) above with yet |
||||
// again a fresh passphrase. |
||||
let impAcc = try! ks?.importKey(jsonKey, passphrase: "Export password", newPassphrase: "Import password") |
||||
``` |
||||
|
||||
*Although instances of `GethAccount` can be used to access various information about |
||||
specific Ethereum accounts, they do not contain any sensitive data (such as passphrases or |
||||
private keys), rather act solely as identifiers for client code and the keystore.* |
||||
|
||||
## Signing authorization |
||||
|
||||
As mentioned above, account objects do not hold the sensitive private keys of the |
||||
associated Ethereum accounts, but are merely placeholders to identify the cryptographic |
||||
keys with. All operations that require authorization (e.g. transaction signing) are |
||||
performed by the account manager after granting it access to the private keys. |
||||
|
||||
There are a few different ways one can authorize the account manager to execute signing |
||||
operations, each having its advantages and drawbacks. Since the different methods have |
||||
wildly different security guarantees, it is essential to be clear on how each works: |
||||
|
||||
* **Single authorization**: The simplest way to sign a transaction via the keystore is to |
||||
provide the passphrase of the account every time something needs to be signed, which |
||||
will ephemerally decrypt the private key, execute the signing operation and immediately |
||||
throw away the decrypted key. The drawbacks are that the passphrase needs to be queried |
||||
from the user every time, which can become annoying if done frequently; or the |
||||
application needs to keep the passphrase in memory, which can have security |
||||
consequences if not done properly; and depending on the keystore's configured strength, |
||||
constantly decrypting keys can result in non-negligible resource requirements. |
||||
* **Multiple authorizations**: A more complex way of signing transactions via the |
||||
keystore is to unlock the account via its passphrase once, and allow the account |
||||
manager to cache the decrypted private key, enabling all subsequent signing requests to |
||||
complete without the passphrase. The lifetime of the cached private key may be managed |
||||
manually (by explicitly locking the account back up) or automatically (by providing a |
||||
timeout during unlock). This mechanism is useful for scenarios where the user may need |
||||
to sign many transactions or the application would need to do so without requiring user |
||||
input. The crucial aspect to remember is that **anyone with access to the account |
||||
manager can sign transactions while a particular account is unlocked** (e.g. device |
||||
left unattended; application running untrusted code). |
||||
|
||||
*Note, creating transactions is out of scope here, so the remainder of this section will |
||||
assume we already have a transaction to sign, and will focus only on creating an |
||||
authorized version of it. Creating an actually meaningful transaction will be covered |
||||
later.* |
||||
|
||||
### Signing on Android (Java) |
||||
|
||||
Assuming we already have an instance of a `KeyStore` called `ks` from the previous |
||||
sections, we can create a new account to sign transactions with via it's already |
||||
demonstrated `newAccount` method; and to avoid going into transaction creation for now, we |
||||
can hard-code a random transaction to sign instead. |
||||
|
||||
```java |
||||
// Create a new account to sign transactions with |
||||
Account signer = ks.newAccount("Signer password"); |
||||
Transaction tx = new Transaction( |
||||
1, new Address("0x0000000000000000000000000000000000000000"), |
||||
new BigInt(0), new BigInt(0), new BigInt(1), null); // Random empty transaction |
||||
BigInt chain = new BigInt(1); // Chain identifier of the main net |
||||
``` |
||||
|
||||
With the boilerplate out of the way, we can now sign transaction using the authorization |
||||
mechanisms described above: |
||||
|
||||
```java |
||||
// Sign a transaction with a single authorization |
||||
Transaction signed = ks.signTxPassphrase(signer, "Signer password", tx, chain); |
||||
|
||||
// Sign a transaction with multiple manually cancelled authorizations |
||||
ks.unlock(signer, "Signer password"); |
||||
signed = ks.signTx(signer, tx, chain); |
||||
ks.lock(signer.getAddress()); |
||||
|
||||
// Sign a transaction with multiple automatically cancelled authorizations |
||||
ks.timedUnlock(signer, "Signer password", 1000000000); |
||||
signed = ks.signTx(signer, tx, chain); |
||||
``` |
||||
|
||||
### Signing on iOS (Swift 3) |
||||
|
||||
Assuming we already have an instance of a `GethKeyStore` called `ks` from the previous |
||||
sections, we can create a new account to sign transactions with via it's already |
||||
demonstrated `newAccount` method; and to avoid going into transaction creation for now, we |
||||
can hard-code a random transaction to sign instead. |
||||
|
||||
```swift |
||||
// Create a new account to sign transactions with |
||||
var error: NSError? |
||||
let signer = try! ks?.newAccount("Signer password") |
||||
|
||||
let to = GethNewAddressFromHex("0x0000000000000000000000000000000000000000", &error) |
||||
let tx = GethNewTransaction(1, to, GethNewBigInt(0), GethNewBigInt(0), GethNewBigInt(0), nil) // Random empty transaction |
||||
let chain = GethNewBigInt(1) // Chain identifier of the main net |
||||
``` |
||||
|
||||
*Note, although Swift usually rewrites `NSError` returns to throws, this particular |
||||
instance seems to have been missed for some reason (possibly due to it being a |
||||
constructor). It will be fixed in a later version of the iOS bindings when the appropriate |
||||
fixed are implemented upstream in the `gomobile` project.* |
||||
|
||||
With the boilerplate out of the way, we can now sign transaction using the authorization |
||||
methods described above: |
||||
|
||||
```swift |
||||
// Sign a transaction with a single authorization |
||||
var signed = try! ks?.signTxPassphrase(signer, passphrase: "Signer password", tx: tx, chainID: chain) |
||||
|
||||
// Sign a transaction with multiple manually cancelled authorizations |
||||
try! ks?.unlock(signer, passphrase: "Signer password") |
||||
signed = try! ks?.signTx(signer, tx: tx, chainID: chain) |
||||
try! ks?.lock(signer?.getAddress()) |
||||
|
||||
// Sign a transaction with multiple automatically cancelled authorizations |
||||
try! ks?.timedUnlock(signer, passphrase: "Signer password", timeout: 1000000000) |
||||
signed = try! ks?.signTx(signer, tx: tx, chainID: chain) |
||||
``` |
||||
|
||||
@ -0,0 +1,179 @@ |
||||
--- |
||||
title: Mobile API |
||||
--- |
||||
|
||||
The Ethereum blockchain along with its two extension protocols Whisper and Swarm was |
||||
originally conceptualized to become the supporting pillar of web3, providing the |
||||
consensus, messaging and storage backbone for a new generation of distributed (actually, |
||||
decentralized) applications called DApps. |
||||
|
||||
The first incarnation towards this dream of web3 was a command line client providing an |
||||
RPC interface into the peer-to-peer protocols. The client was soon enough extended with a |
||||
web-browser-like graphical user interface, permitting developers to write DApps based on |
||||
the tried and proven HTML/CSS/JS technologies. |
||||
|
||||
As many DApps have more complex requirements than what a browser environment can handle, |
||||
it became apparent that providing programmatic access to the web3 pillars would open the |
||||
door towards a new class of applications. As such, the second incarnation of the web |
||||
dream is to open up all our technologies for other projects as reusable components. |
||||
|
||||
Starting with the 1.5 release family of `go-ethereum`, we transitioned away from providing |
||||
only a full blown Ethereum client and started shipping official Go packages that could be |
||||
embedded into third party desktop and server applications. It took only a small leap from |
||||
here to begin porting our code to mobile platforms. |
||||
|
||||
## Quick overview |
||||
|
||||
Similarly to our reusable Go libraries, the mobile wrappers also focus on four main usage |
||||
areas: |
||||
|
||||
- Simplified client side account management |
||||
- Remote node interfacing via different transports |
||||
- Contract interactions through auto-generated bindings |
||||
- In-process Ethereum, Whisper and Swarm peer-to-peer node |
||||
|
||||
You can watch a quick overview about these in Peter's (@karalabe) talk titled "Import |
||||
Geth: Ethereum from Go and beyond", presented at the Ethereum Devcon2 developer conference |
||||
in September, 2016 (Shanghai). Slides are [available |
||||
here](https://ethereum.karalabe.com/talks/2016-devcon.html). |
||||
|
||||
[](https://www.youtube.com/watch?v=R0Ia1U9Gxjg) |
||||
|
||||
## Library bundles |
||||
|
||||
The `go-ethereum` mobile library is distributed either as an Android `.aar` archive |
||||
(containing binaries for `arm-7`, `arm64`, `x86` and `x64`); or as an iOS XCode framework |
||||
(containing binaries for `arm-7`, `arm64` and `x86`). We do not provide library bundles |
||||
for Windows phone the moment. |
||||
|
||||
### Android archive |
||||
|
||||
The simplest way to use `go-ethereum` in your Android project is through a Maven |
||||
dependency. We provide bundles of all our stable releases (starting from v1.5.0) through |
||||
Maven Central, and also provide the latest develop bundle through the Sonatype OSS |
||||
repository. |
||||
|
||||
#### Stable dependency (Maven Central) |
||||
|
||||
To add an Android dependency to the **stable** library release of `go-ethereum`, you'll |
||||
need to ensure that the Maven Central repository is enabled in your Android project, and |
||||
that the `go-ethereum` code is listed as a required dependency of your application. You |
||||
can do both of these by editing the `build.gradle` script in your Android app's folder: |
||||
|
||||
```gradle |
||||
repositories { |
||||
mavenCentral() |
||||
} |
||||
|
||||
dependencies { |
||||
// All your previous dependencies |
||||
compile 'org.ethereum:geth:1.5.2' // Change the version to the latest release |
||||
} |
||||
``` |
||||
|
||||
#### Develop dependency (Sonatype) |
||||
|
||||
To add an Android dependency to the current version of `go-ethereum`, you'll need to |
||||
ensure that the Sonatype snapshot repository is enabled in your Android project, and that |
||||
the `go-ethereum` code is listed as a required `SNAPSHOT` dependency of your application. |
||||
You can do both of these by editing the `build.gradle` script in your Android app's |
||||
folder: |
||||
|
||||
```gradle |
||||
repositories { |
||||
maven { |
||||
url "https://oss.sonatype.org/content/groups/public" |
||||
} |
||||
} |
||||
|
||||
dependencies { |
||||
// All your previous dependencies |
||||
compile 'org.ethereum:geth:1.5.3-SNAPSHOT' // Change the version to the latest release |
||||
} |
||||
``` |
||||
|
||||
#### Custom dependency |
||||
|
||||
If you prefer not to depend on Maven Central or Sonatype; or would like to access an older |
||||
develop build not available any more as an online dependency, you can download any bundle |
||||
directly from [our website](https://geth.ethereum.org/downloads/) and insert it into your |
||||
project in Android Studio via `File -> New -> New module... -> Import .JAR/.AAR Package`. |
||||
|
||||
You will also need to configure `gradle` to link the mobile library bundle to your |
||||
application. This can be done by adding a new entry to the `dependencies` section of your |
||||
`build.gradle` script, pointing it to the module you just added (named `geth` by default). |
||||
|
||||
```gradle |
||||
dependencies { |
||||
// All your previous dependencies |
||||
compile project(':geth') |
||||
} |
||||
``` |
||||
|
||||
#### Manual builds |
||||
|
||||
Lastly, if you would like to make modifications to the `go-ethereum` mobile code and/or |
||||
build it yourself locally instead of downloading a pre-built bundle, you can do so using a |
||||
`make` command. This will create an Android archive called `geth.aar` in the `build/bin` |
||||
folder that you can import into your Android Studio as described above. |
||||
|
||||
```bash |
||||
$ make android |
||||
[...] |
||||
Done building. |
||||
Import "build/bin/geth.aar" to use the library. |
||||
``` |
||||
|
||||
### iOS framework |
||||
|
||||
The simplest way to use `go-ethereum` in your iOS project is through a |
||||
[CocoaPods](https://cocoapods.org/) dependency. We provide bundles of all our stable |
||||
releases (starting from v1.5.3) and also latest develop versions. |
||||
|
||||
#### Automatic dependency |
||||
|
||||
To add an iOS dependency to the current stable or latest develop version of `go-ethereum`, |
||||
you'll need to ensure that your iOS XCode project is configured to use CocoaPods. |
||||
Detailing that is out of scope in this document, but you can find a guide in the upstream |
||||
[Using CocoaPods](https://guides.cocoapods.org/using/using-cocoapods.html) page. |
||||
Afterwards you can edit your `Podfile` to list `go-ethereum` as a dependency: |
||||
|
||||
```ruby |
||||
target 'MyApp' do |
||||
# All your previous dependencies |
||||
pod 'Geth', '1.5.4' # Change the version to the latest release |
||||
end |
||||
``` |
||||
|
||||
Alternatively, if you'd like to use the latest develop version, replace the package |
||||
version `1.5.4` with `~> 1.5.5-unstable` to switch to pre-releases and to always pull in |
||||
the latest bundle from a particular release family. |
||||
|
||||
#### Custom dependency |
||||
|
||||
If you prefer not to depend on CocoaPods; or would like to access an older develop build |
||||
not available any more as an online dependency, you can download any bundle directly from |
||||
[our website](https://geth.ethereum.org/downloads/) and insert it into your project in |
||||
XCode via `Project Settings -> Build Phases -> Link Binary With Libraries`. |
||||
|
||||
Do not forget to extract the framework from the compressed `.tar.gz` archive. You can do |
||||
that either using a GUI tool or from the command line via (replace the archive with your |
||||
downloaded file): |
||||
|
||||
``` |
||||
tar -zxvf geth-ios-all-1.5.3-unstable-e05d35e6.tar.gz |
||||
``` |
||||
|
||||
#### Manual builds |
||||
|
||||
Lastly, if you would like to make modifications to the `go-ethereum` mobile code and/or |
||||
build it yourself locally instead of downloading a pre-built bundle, you can do so using a |
||||
`make` command. This will create an iOS XCode framework called `Geth.framework` in the |
||||
`build/bin` folder that you can import into XCode as described above. |
||||
|
||||
```bash |
||||
$ make ios |
||||
[...] |
||||
Done building. |
||||
Import "build/bin/Geth.framework" to use the library. |
||||
``` |
||||
@ -0,0 +1,252 @@ |
||||
--- |
||||
title: Go Account Management |
||||
--- |
||||
|
||||
To provide Ethereum integration for your native applications, the very first thing you |
||||
should be interested in doing is account management. |
||||
|
||||
Although all current leading Ethereum implementations provide account management built in, |
||||
it is ill advised to keep accounts in any location that is shared between multiple |
||||
applications and/or multiple people. The same way you do not entrust your ISP (who is |
||||
after all your gateway into the internet) with your login credentials; you should not |
||||
entrust an Ethereum node (who is your gateway into the Ethereum network) with your |
||||
credentials either. |
||||
|
||||
The proper way to handle user accounts in your native applications is to do client side |
||||
account management, everything self-contained within your own application. This way you |
||||
can ensure as fine grained (or as coarse) access permissions to the sensitive data as |
||||
deemed necessary, without relying on any third party application's functionality and/or |
||||
vulnerabilities. |
||||
|
||||
To support this, `go-ethereum` provides a simple, yet thorough accounts package that gives |
||||
you all the tools to do properly secured account management via encrypted keystores and |
||||
passphrase protected accounts. You can leverage all the security of the `go-ethereum` |
||||
crypto implementation while at the same time running everything in your own application. |
||||
|
||||
## Encrypted keystores |
||||
|
||||
Although handling accounts locally to an application does provide certain security |
||||
guarantees, access keys to Ethereum accounts should never lay around in clear-text form. |
||||
As such, we provide an encrypted keystore that provides the proper security guarantees for |
||||
you without requiring a thorough understanding from your part of the associated |
||||
cryptographic primitives. |
||||
|
||||
The important thing to know when using the encrypted keystore is that the cryptographic |
||||
primitives used within can operate either in *standard* or *light* mode. The former |
||||
provides a higher level of security at the cost of increased computational burden and |
||||
resource consumption: |
||||
|
||||
* *standard* needs 256MB memory and 1 second processing on a modern CPU to access a key |
||||
* *light* needs 4MB memory and 100 millisecond processing on a modern CPU to access a key |
||||
|
||||
As such, *standard* is more suitable for native applications, but you should be aware of |
||||
the trade-offs nonetheless in case you you're targeting more resource constrained |
||||
environments. |
||||
|
||||
*For those interested in the cryptographic and/or implementation details, the key-store |
||||
uses the `secp256k1` elliptic curve as defined in the [Standards for Efficient |
||||
Cryptography](sec2), implemented by the [`libsecp256k`](secp256k1) library and wrapped by |
||||
[`github.com/ethereum/go-ethereum/accounts`](accounts-go). Accounts are stored on disk in |
||||
the [Web3 Secret Storage](secstore) format.* |
||||
|
||||
[sec2]: http://www.secg.org/sec2-v2.pdf |
||||
[accounts-go]: https://godoc.org/github.com/ethereum/go-ethereum/accounts |
||||
[secp256k1]: https://github.com/bitcoin-core/secp256k1 |
||||
[secstore]: https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition |
||||
|
||||
### Keystores from Go |
||||
|
||||
The encrypted keystore is implemented by the |
||||
[`accounts.Manager`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager) |
||||
struct from the |
||||
[`github.com/ethereum/go-ethereum/accounts`](https://godoc.org/github.com/ethereum/go-ethereum/accounts) |
||||
package, which also contains the configuration constants for the *standard* or *light* |
||||
security modes described above. Hence to do client side account management from Go, you'll |
||||
need to import only the `accounts` package into your code: |
||||
|
||||
```go |
||||
import "github.com/ethereum/go-ethereum/accounts" |
||||
``` |
||||
|
||||
Afterwards you can create a new encrypted account manager via: |
||||
|
||||
```go |
||||
am := accounts.NewManager("/path/to/keystore", accounts.StandardScryptN, accounts.StandardScryptP); |
||||
``` |
||||
|
||||
The path to the keystore folder needs to be a location that is writable by the local user |
||||
but non-readable for other system users (for security reasons obviously), so we'd |
||||
recommend placing it either inside your user's home directory or even more locked down for |
||||
backend applications. |
||||
|
||||
The last two arguments of |
||||
[`accounts.NewManager`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#NewManager) |
||||
are the crypto parameters defining how resource-intensive the keystore encryption should |
||||
be. You can choose between [`accounts.StandardScryptN, accounts.StandardScryptP`, |
||||
`accounts.LightScryptN, |
||||
accounts.LightScryptP`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#pkg-constants) |
||||
or specify your own numbers (please make sure you understand the underlying cryptography |
||||
for this). We recommend using the *standard* version. |
||||
|
||||
## Account lifecycle |
||||
|
||||
Having created an encrypted keystore for your Ethereum accounts, you can use this account |
||||
manager for the entire account lifecycle requirements of your native application. This |
||||
includes the basic functionality of creating new accounts and deleting existing ones; as |
||||
well as the more advanced functionality of updating access credentials, exporting existing |
||||
accounts, and importing them on another device. |
||||
|
||||
Although the keystore defines the encryption strength it uses to store your accounts, |
||||
there is no global master password that can grant access to all of them. Rather each |
||||
account is maintained individually, and stored on disk in its [encrypted |
||||
format](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) |
||||
individually, ensuring a much cleaner and stricter separation of credentials. |
||||
|
||||
This individuality however means that any operation requiring access to an account will |
||||
need to provide the necessary authentication credentials for that particular account in |
||||
the form of a passphrase: |
||||
|
||||
* When creating a new account, the caller must supply a passphrase to encrypt the account |
||||
with. This passphrase will be required for any subsequent access, the lack of which |
||||
will forever forfeit using the newly created account. |
||||
* When deleting an existing account, the caller must supply a passphrase to verify |
||||
ownership of the account. This isn't cryptographically necessary, rather a protective |
||||
measure against accidental loss of accounts. |
||||
* When updating an existing account, the caller must supply both current and new |
||||
passphrases. After completing the operation, the account will not be accessible via the |
||||
old passphrase any more. |
||||
* When exporting an existing account, the caller must supply both the current passphrase |
||||
to decrypt the account, as well as an export passphrase to re-encrypt it with before |
||||
returning the key-file to the user. This is required to allow moving accounts between |
||||
machines and applications without sharing original credentials. |
||||
* When importing a new account, the caller must supply both the encryption passphrase of |
||||
the key-file being imported, as well as a new passhprase with which to store the |
||||
account. This is required to allow storing account with different credentials than used |
||||
for moving them around. |
||||
|
||||
*Please note, there is no recovery mechanisms for losing the passphrases. The |
||||
cryptographic properties of the encrypted keystore (if using the provided parameters) |
||||
guarantee that account credentials cannot be brute forced in any meaningful time.* |
||||
|
||||
### Accounts from Go |
||||
|
||||
An Ethereum account is implemented by the |
||||
[`accounts.Account`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Account) |
||||
struct from the |
||||
[`github.com/ethereum/go-ethereum/accounts`](https://godoc.org/github.com/ethereum/go-ethereum/accounts) |
||||
package. Assuming we already have an instance of an |
||||
[`accounts.Manager`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager) |
||||
called `am` from the previous section, we can easily execute all of the described |
||||
lifecycle operations with a handful of function calls (error handling omitted). |
||||
|
||||
```go |
||||
// Create a new account with the specified encryption passphrase. |
||||
newAcc, _ := am.NewAccount("Creation password"); |
||||
|
||||
// Export the newly created account with a different passphrase. The returned |
||||
// data from this method invocation is a JSON encoded, encrypted key-file. |
||||
jsonAcc, _ := am.Export(newAcc, "Creation password", "Export password"); |
||||
|
||||
// Update the passphrase on the account created above inside the local keystore. |
||||
am.Update(newAcc, "Creation password", "Update password"); |
||||
|
||||
// Delete the account updated above from the local keystore. |
||||
am.Delete(newAcc, "Update password"); |
||||
|
||||
// Import back the account we've exported (and then deleted) above with yet |
||||
// again a fresh passphrase. |
||||
impAcc, _ := am.Import(jsonAcc, "Export password", "Import password"); |
||||
``` |
||||
|
||||
*Although instances of |
||||
[`accounts.Account`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Account) |
||||
can be used to access various information about specific Ethereum accounts, they do not |
||||
contain any sensitive data (such as passphrases or private keys), rather act solely as |
||||
identifiers for client code and the keystore.* |
||||
|
||||
## Signing authorization |
||||
|
||||
As mentioned above, account objects do not hold the sensitive private keys of the |
||||
associated Ethereum accounts, but are merely placeholders to identify the cryptographic |
||||
keys with. All operations that require authorization (e.g. transaction signing) are |
||||
performed by the account manager after granting it access to the private keys. |
||||
|
||||
There are a few different ways one can authorize the account manager to execute signing |
||||
operations, each having its advantages and drawbacks. Since the different methods have |
||||
wildly different security guarantees, it is essential to be clear on how each works: |
||||
|
||||
* **Single authorization**: The simplest way to sign a transaction via the account |
||||
manager is to provide the passphrase of the account every time something needs to be |
||||
signed, which will ephemerally decrypt the private key, execute the signing operation |
||||
and immediately throw away the decrypted key. The drawbacks are that the passphrase |
||||
needs to be queried from the user every time, which can become annoying if done |
||||
frequently; or the application needs to keep the passphrase in memory, which can have |
||||
security consequences if not done properly; and depending on the keystore's configured |
||||
strength, constantly decrypting keys can result in non-negligible resource |
||||
requirements. |
||||
* **Multiple authorizations**: A more complex way of signing transactions via the account |
||||
manager is to unlock the account via its passphrase once, and allow the account manager |
||||
to cache the decrypted private key, enabling all subsequent signing requests to |
||||
complete without the passphrase. The lifetime of the cached private key may be managed |
||||
manually (by explicitly locking the account back up) or automatically (by providing a |
||||
timeout during unlock). This mechanism is useful for scenarios where the user may need |
||||
to sign many transactions or the application would need to do so without requiring user |
||||
input. The crucial aspect to remember is that **anyone with access to the account |
||||
manager can sign transactions while a particular account is unlocked** (e.g. |
||||
application running untrusted code). |
||||
|
||||
*Note, creating transactions is out of scope here, so the remainder of this section will |
||||
assume we already have a transaction hash to sign, and will focus only on creating a |
||||
cryptographic signature authorizing it. Creating an actual transaction and injecting the |
||||
authorization signature into it will be covered later.* |
||||
|
||||
### Signing from Go |
||||
|
||||
Assuming we already have an instance of an |
||||
[`accounts.Manager`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager) |
||||
called `am` from the previous sections, we can create a new account to sign transactions |
||||
with via it's already demonstrated |
||||
[`NewAccount`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.NewAccount) |
||||
method; and to avoid going into transaction creation for now, we can hard-code a random |
||||
[`common.Hash`](https://godoc.org/github.com/ethereum/go-ethereum/common#Hash) to sign |
||||
instead. |
||||
|
||||
```go |
||||
// Create a new account to sign transactions with |
||||
signer, _ := am.NewAccount("Signer password"); |
||||
txHash := common.HexToHash("0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"); |
||||
``` |
||||
|
||||
With the boilerplate out of the way, we can now sign transaction using the authorization |
||||
mechanisms described above: |
||||
|
||||
```go |
||||
// Sign a transaction with a single authorization |
||||
signature, _ := am.SignWithPassphrase(signer, "Signer password", txHash.Bytes()); |
||||
|
||||
// Sign a transaction with multiple manually cancelled authorizations |
||||
am.Unlock(signer, "Signer password"); |
||||
signature, _ = am.Sign(signer.Address, txHash.Bytes()); |
||||
am.Lock(signer.Address); |
||||
|
||||
// Sign a transaction with multiple automatically cancelled authorizations |
||||
am.TimedUnlock(signer, "Signer password", time.Second); |
||||
signature, _ = am.Sign(signer.Address, txHash.Bytes()); |
||||
``` |
||||
|
||||
You may wonder why |
||||
[`SignWithPassphrase`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.SignWithPassphrase) |
||||
takes an |
||||
[`accounts.Account`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Account) |
||||
as the signer, whereas |
||||
[`Sign`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.Sign) takes |
||||
only a |
||||
[`common.Address`](https://godoc.org/github.com/ethereum/go-ethereum/common#Address). The |
||||
reason is that an |
||||
[`accounts.Account`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Account) |
||||
object may also contain a custom key-path, allowing |
||||
[`SignWithPassphrase`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.SignWithPassphrase) |
||||
to sign using accounts outside of the keystore; however |
||||
[`Sign`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.Sign) relies |
||||
on accounts already unlocked within the keystore, so it cannot specify custom paths. |
||||
|
||||
@ -1,6 +1,7 @@ |
||||
--- |
||||
title: Native DApps / Go bindings to Ethereum contracts |
||||
title: Go Contract Bindings |
||||
--- |
||||
|
||||
**[Please note, events are not yet implemented as they need some RPC subscription |
||||
features that are still under review.]** |
||||
|
||||
@ -0,0 +1,72 @@ |
||||
--- |
||||
title: Go API |
||||
--- |
||||
|
||||
The Ethereum blockchain along with its two extension protocols Whisper and Swarm was |
||||
originally conceptualized to become the supporting pillar of web3, providing the |
||||
consensus, messaging and storage backbone for a new generation of distributed (actually, |
||||
decentralized) applications called DApps. |
||||
|
||||
The first incarnation towards this dream of web3 was a command line client providing an |
||||
RPC interface into the peer-to-peer protocols. The client was soon enough extended with a |
||||
web-browser-like graphical user interface, permitting developers to write DApps based on |
||||
the tried and proven HTML/CSS/JS technologies. |
||||
|
||||
As many DApps have more complex requirements than what a browser environment can handle, |
||||
it became apparent that providing programmatic access to the web3 pillars would open the |
||||
door towards a new class of applications. As such, the second incarnation of the web3 |
||||
dream is to open up all our technologies for other projects as reusable components. |
||||
|
||||
Starting with the 1.5 release family of `go-ethereum`, we transitioned away from providing |
||||
only a full blown Ethereum client and started shipping official Go packages that could be |
||||
embedded into third party desktop and server applications. |
||||
|
||||
*Note, this guide will assume you are familiar with Go development. It will make no |
||||
attempts to cover general topics about Go project layouts, import paths or any other |
||||
standard methodologies. If you are new to Go, consider reading its [getting started |
||||
guides](https://github.com/golang/go/wiki#getting-started-with-go) first.* |
||||
|
||||
## Quick overview |
||||
|
||||
Our reusable Go libraries focus on four main usage areas: |
||||
|
||||
- Simplified client side account management |
||||
- Remote node interfacing via different transports |
||||
- Contract interactions through auto-generated bindings |
||||
- In-process Ethereum, Whisper and Swarm peer-to-peer node |
||||
|
||||
You can watch a quick overview about these in Peter's (@karalabe) talk titled "Import |
||||
Geth: Ethereum from Go and beyond", presented at the Ethereum Devcon2 developer conference |
||||
in September, 2016 (Shanghai). Slides are [available |
||||
here](https://ethereum.karalabe.com/talks/2016-devcon.html). |
||||
|
||||
[](https://www.youtube.com/watch?v=R0Ia1U9Gxjg) |
||||
|
||||
## Go packages |
||||
|
||||
The `go-ethereum` library is distributed as a collection of standard Go packages straight |
||||
from our GitHub repository. The packages can be used directly via the official Go toolkit, |
||||
without needing any third party tools. External dependencies are vendored locally into |
||||
`vendor`, ensuring both self-containment as well as code stability. If you reuse |
||||
`go-ethereum` in your own project, please follow these best practices and vendor it |
||||
yourself too to avoid any accidental API breakages! |
||||
|
||||
The canonical import path for `go-ethereum` is `github.com/ethereum/go-ethereum`, with all |
||||
packages residing underneath. Although there are [quite a |
||||
number](https://godoc.org/github.com/ethereum/go-ethereum#pkg-subdirectories) of them, |
||||
you'll only need to care about a limited subset, each of which will be properly introduced |
||||
in their relevant section. |
||||
|
||||
You can download all our packages via: |
||||
|
||||
``` |
||||
$ go get -d github.com/ethereum/go-ethereum/... |
||||
``` |
||||
|
||||
You may also need Go's original context package. Although this was moved into the official |
||||
Go SDK in Go 1.7, `go-ethereum` will depend on the original `golang.org/x/net/context` |
||||
package until we officially drop support for Go 1.5 and Go 1.6. |
||||
|
||||
``` |
||||
$ go get -u golang.org/x/net/context |
||||
``` |
||||
@ -0,0 +1,216 @@ |
||||
--- |
||||
title: EVM Tracing |
||||
--- |
||||
|
||||
There are two different types of transactions in Ethereum: plain value transfers and |
||||
contract executions. A plain value transfer just moves Ether from one account to another |
||||
and as such is uninteresting from this guide's perspective. If however the recipient of a |
||||
transaction is a contract account with associated EVM (Ethereum Virtual Machine) |
||||
bytecode - beside transferring any Ether - the code will also be executed as part of the |
||||
transaction. |
||||
|
||||
Having code associated with Ethereum accounts permits transactions to do arbitrarilly |
||||
complex data storage and enables them to act on the previously stored data by further |
||||
transacting internally with outside accounts and contracts. This creates an intertwined |
||||
ecosystem of contracts, where a single transaction can interact with tens or hunderds of |
||||
accounts. |
||||
|
||||
The downside of contract execution is that it is very hard to say what a transaction |
||||
actually did. A transaction receipt does contain a status code to check whether execution |
||||
succeeded or not, but there's no way to see what data was modified, nor what external |
||||
contracts where invoked. In order to introspect a transaction, we need to trace its |
||||
execution. |
||||
|
||||
## Tracing prerequisites |
||||
|
||||
In its simplest form, tracing a transaction entails requesting the Ethereum node to |
||||
reexecute the desired transaction with varying degrees of data collection and have it |
||||
return the aggregated summary for post processing. Reexecuting a transaction however has a |
||||
few prerequisites to be met. |
||||
|
||||
In order for an Ethereum node to reexecute a transaction, it needs to have available all |
||||
historical state accessed by the transaction: |
||||
|
||||
* Balance, nonce, bytecode and storage of both the recipient as well as all internally invoked contracts. |
||||
* Block metadata referenced during execution of both the outer as well as all internally created transactions. |
||||
* Intermediate state generated by all preceding transactions contained in the same block as the one being traced. |
||||
|
||||
Depending on your node's mode of synchronization and pruning, different configurations |
||||
result in different capabilities: |
||||
|
||||
* An **archive** node retaining **all historical data** can trace arbitrary transactions |
||||
at any point in time. Tracing a single transaction also entails reexecuting all |
||||
preceding transactions in the same block. |
||||
* A **fast synced** node retaining **all historical data** after initial sync can only |
||||
trace transactions from blocks following the initial sync point. Tracing a single |
||||
transaction also entails reexecuting all preceding transactions in the same block. |
||||
* A **fast synced** node retaining only **periodic state data** after initial sync can |
||||
only trace transactions from blocks following the initial sync point. Tracing a single |
||||
transaction entails reexecuting all preceding transactions **both** in the same block, |
||||
as well as all preceding blocks until the previous stored snapshot. |
||||
* A **light synced** node retrieving data **on demand** can in theory trace transactions |
||||
for which all required historical state is readily available in the network. In |
||||
practice, data availability is **not** a feasible assumption. |
||||
|
||||
*There are exceptions to the above rules when running batch traces of entire blocks or |
||||
chain segments. Those will be detailed later.* |
||||
|
||||
## Basic traces |
||||
|
||||
The simplest type of transaction trace that `go-ethereum` can generate are raw EVM opcode |
||||
traces. For every VM instruction the transaction executes, a structured log entry is |
||||
emitted, containing all contextual metadata deemed useful. This includes the *program |
||||
counter*, *opcode name*, *opcode cost*, *remaining gas*, *execution depth* and any |
||||
*occurred error*. The structured logs can optionally also contain the content of the |
||||
*execution stack*, *execution memory* and *contract storage*. |
||||
|
||||
An example log entry for a single opcode looks like: |
||||
|
||||
```json |
||||
{ |
||||
"pc": 48, |
||||
"op": "DIV", |
||||
"gasCost": 5, |
||||
"gas": 64532, |
||||
"depth": 1, |
||||
"error": null, |
||||
"stack": [ |
||||
"00000000000000000000000000000000000000000000000000000000ffffffff", |
||||
"0000000100000000000000000000000000000000000000000000000000000000", |
||||
"2df07fbaabbe40e3244445af30759352e348ec8bebd4dd75467a9f29ec55d98d" |
||||
], |
||||
"memory": [ |
||||
"0000000000000000000000000000000000000000000000000000000000000000", |
||||
"0000000000000000000000000000000000000000000000000000000000000000", |
||||
"0000000000000000000000000000000000000000000000000000000000000060" |
||||
], |
||||
"storage": { |
||||
} |
||||
} |
||||
``` |
||||
|
||||
The entire output of an raw EVM opcode trace is a JSON object having a few metadata |
||||
fields: *consumed gas*, *failure status*, *return value*; and a list of *opcode entries* |
||||
that take the above form: |
||||
|
||||
```json |
||||
{ |
||||
"gas": 25523, |
||||
"failed": false, |
||||
"returnValue": "", |
||||
"structLogs": [] |
||||
} |
||||
``` |
||||
|
||||
### Generating basic traces |
||||
|
||||
To generate a raw EVM opcode trace, `go-ethereum` provides a few [RPC API |
||||
endpoints](debug-api), out of which the most commonly used is |
||||
[`debug_traceTransaction`](trace-tx). |
||||
|
||||
In its simplest form, `traceTransaction` accepts a transaction hash as its sole argument, |
||||
traces the transaction, aggregates all the generated data and returns it as a **large** |
||||
JSON object. A sample invocation from the Geth console would be: |
||||
|
||||
```js |
||||
debug.traceTransaction("0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f") |
||||
``` |
||||
|
||||
The same call can of course be invoked from outside the node too via HTTP RPC. In this |
||||
case, please make sure the HTTP endpoint is enabled via `--rpc` and the `debug` API |
||||
namespace exposed via `--rpcapi=debug`. |
||||
|
||||
``` |
||||
$ curl -H "Content-Type: application/json" -d '{"id": 1, "method": "debug_traceTransaction", "params": ["0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f"]}' localhost:8545 |
||||
``` |
||||
|
||||
Running the above operation on the Rinkeby network (with a node retaining enough history) |
||||
will result in this [trace dump](rinkeby-example-trace-big). |
||||
|
||||
### Tuning basic traces |
||||
|
||||
By default the raw opcode tracer emits all relevant events that occur within the EVM while |
||||
processing a transaction, such as *EVM stack*, *EVM memory* and *updated storage slots*. |
||||
Certain use cases however may not need some of these data fields reported. To cater for |
||||
those use cases, these massive fields may be omitted using a second *options* parameter |
||||
for the tracer: |
||||
|
||||
```json |
||||
{ |
||||
"disableStack": true, |
||||
"disableMemory": true, |
||||
"disableStorage": true |
||||
} |
||||
``` |
||||
|
||||
Running the previous tracer invocation from the Geth console with the data fields |
||||
disabled: |
||||
|
||||
```js |
||||
debug.traceTransaction("0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f", {disableStack: true, disableMemory: true, disableStorage: true}) |
||||
``` |
||||
|
||||
Analogously running the filtered tracer from outside the node too via HTTP RPC: |
||||
|
||||
``` |
||||
$ curl -H "Content-Type: application/json" -d '{"id": 1, "method": "debug_traceTransaction", "params": ["0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f", {"disableStack": true, "disableMemory": true, "disableStorage": true}]}' localhost:8545 |
||||
``` |
||||
|
||||
Running the above operation on the Rinkeby network will result in this significantly |
||||
shorter [trace dump](rinkeby-example-trace). |
||||
|
||||
### Limits of basic traces |
||||
|
||||
Although the raw opcode traces we've generated above have their use, this basic way of |
||||
tracing is problematic in the real world. Having an individual log entry for every single |
||||
opcode is too low level for most use cases, and will require developers to create |
||||
additional tools to post-process the traces. Additionally, a full opcode trace can easily |
||||
go into the hundreds of megabytes, making them very resource intensive to get out of the |
||||
node and process externally. |
||||
|
||||
To avoid all of the previously mentioned issues, `go-ethereum` supports running custom |
||||
JavaScript tracers *within* the Ethereum node, which have full access to the EVM stack, |
||||
memory and contract storage. This permits developers to only gather the data they need, |
||||
and do any processing **at** the data. Please see the next section for our *custom in-node |
||||
tracers*. |
||||
|
||||
### Pruning |
||||
|
||||
Geth by default does in-memory pruning of state, discarding state entries that it deems is |
||||
no longer necessary to maintain. This is configured via the `--gcmode` option. Often, |
||||
people run into the error that state is not available. |
||||
|
||||
Say you want to do a trace on block `B`. Now there are a couple of cases: |
||||
|
||||
1. You have done a fast-sync, pivot block `P` where `P <= B`. |
||||
2. You have done a fast-sync, pivot block `P` where `P > B`. |
||||
3. You have done a full-sync, with pruning |
||||
4. You have done a full-sync, without pruning (`--gcmode=archive`) |
||||
|
||||
Here's what happens in each respective case: |
||||
|
||||
1. Geth will regenerate the desired state by replaying blocks from the closest point ina |
||||
time before `B` where it has full state. This defaults to `128` blocks max, but you can |
||||
specify more in the actual call `... "reexec":1000 .. }` to the tracer. |
||||
2. Sorry, can't be done without replaying from genesis. |
||||
3. Same as 1) |
||||
4. Does not need to replay anything, can immediately load up the state and serve the request. |
||||
|
||||
There is one other option available to you, which may or may not suit your needs. That is |
||||
to use [Evmlab](evmlab). |
||||
|
||||
docker pull holiman/evmlab && docker run -it holiman/evmlab |
||||
|
||||
There you can use the reproducer. The reproducer will incrementally fetch data from infura |
||||
until it has all the information required to create the trace locally on an evm which is |
||||
bundled with the image. It will create a custom genesis containing the state that the |
||||
transaction touches (balances, code, nonce etc). It should be mentioned that the evmlab |
||||
reproducer is strictly guaranteed to be totally exact with regards to gascosts incurred by |
||||
the outer transaction, as evmlab does not fully calculate the gascosts for nonzero data |
||||
etc, but is usually sufficient to analyze contracts and events. |
||||
|
||||
[evmlab]: https://github.com/holiman/evmlab |
||||
[rinkeby-example-trace]: https://gist.github.com/karalabe/d74a7cb33a70f2af75e7824fc772c5b4 |
||||
[rinkeby-example-trace-big]: https://gist.github.com/karalabe/c91f95ac57f5e57f8b950ec65ecc697f |
||||
[debug-api]: ../rpc/ns-debug |
||||
[trace-tx]: ../rpc/ns-debug#debug_tracetransaction |
||||
@ -1,34 +0,0 @@ |
||||
--- |
||||
title: Active go-ethereum projects |
||||
--- |
||||
## Direction of development until the end of 2018 |
||||
|
||||
- Clef: move account management out of geth to clef |
||||
- Constantinople - Tools for testing |
||||
- Automate cross-client testing |
||||
- Progpow (ASIC-resistent PoW algorithm) |
||||
- Ethereum Node Report |
||||
- Topic discovery |
||||
- Build an end-to-end test system |
||||
- Simple API for LES-protocol |
||||
- Loadbalance tests using Swarm team's network simulator |
||||
- Test FlowControl subsystem rewrite |
||||
- Clients get more bandwidth with micro-payment |
||||
- Database IO reductions |
||||
- Historical state pruning |
||||
- Next gen sync algo (cross client) |
||||
- Blockscout for Puppeth |
||||
- Contract based signers for Clique (v1.5) |
||||
- Rinkeby - improve maintenance |
||||
- Concurrent tx execution experiment |
||||
- Dashboard |
||||
- Hive - Devp2p basic tests running as Hive simulation |
||||
- Hive - Devp2p network tests (different clients peering) |
||||
- Hive - Add all known client implementations |
||||
- Hive - Public metrics/test failures page |
||||
- DevP2P - Document protocols |
||||
- Hive - Further tests for networked consensus |
||||
- Discovery - Work with Felix to get ENR/next discovery out asap |
||||
- Countable trie experiment - For better sync statistic and futher storage rent |
||||
- Build an end-to-end test system |
||||
- Finalize simple checkpoint syncing |
||||
@ -1,15 +0,0 @@ |
||||
--- |
||||
title: Developer guide |
||||
--- |
||||
### Native DApps |
||||
|
||||
[Introduction and packages](Native:-Introduction) |
||||
|
||||
[Account management](Native:-Account-management) |
||||
|
||||
### Mobile platforms |
||||
|
||||
[Introduction and packages](Mobile:-Introduction) |
||||
|
||||
[Account management](Mobile:-Account-management) |
||||
|
||||
@ -1,91 +0,0 @@ |
||||
--- |
||||
title: Mobile Clients |
||||
--- |
||||
**This page has been obsoleted. An new guide is in the progress at [[Mobile: Introduction]]** |
||||
|
||||
--- |
||||
|
||||
*This page is meant to be a guide on using go-ethereum from mobile platforms. Since neither the mobile libraries nor the light client protocol is finalized, the content here will be sparse, with emphasis being put on how to get your hands dirty. As the APIs stabilize this section will be expanded accordingly.* |
||||
|
||||
### Changelog |
||||
|
||||
* 30th September, 2016: Create initial page, upload Android light bundle. |
||||
|
||||
### Background |
||||
|
||||
Before reading further, please skim through the slides of a Devcon2 talk: [Import Geth: Ethereum from Go and beyond](https://ethereum.karalabe.com/talks/2016-devcon.html), which introduces the basic concepts behind using go-ethereum as a library, and also showcases a few code snippets on how you can do various client side tasks, both on classical computing nodes as well as Android devices. A recording of the talk will be linked when available. |
||||
|
||||
*Please note, the Android and iOS library bundles linked in the presentation will not be updated (for obvious posterity reasons), so always grab latest bundles from this page (until everything is merged into the proper build infrastructure).* |
||||
|
||||
### Mobile bundles |
||||
|
||||
You can download the latest bundles at: |
||||
|
||||
* [Android (30th September, 2016)](https://bintray.com/karalabe/ethereum/download_file?file_path=geth.aar) - `SHA1: 753e334bf61fa519bec83bcb487179e36d58fc3a` |
||||
* iOS: *light client has not yet been bundled* |
||||
|
||||
### Android quickstart |
||||
|
||||
We assume you are using Android Studio for your development. Please download the latest Android `.aar` bundle from above and import it into your Android Studio project via `File -> New -> New Module`. This will result in a `geth` sub-project inside your work-space. To use the library in your project, please modify your apps `build.gradle` file, adding a dependency to the Geth library: |
||||
|
||||
```gradle |
||||
dependencies { |
||||
// All your previous dependencies |
||||
compile project(':geth') |
||||
} |
||||
``` |
||||
|
||||
To get you hands dirty, here's a code snippet that will |
||||
|
||||
* Start up an in-process light node inside your Android application |
||||
* Display some initial infos about your node |
||||
* Subscribe to new blocks and display them live as they arrive |
||||
|
||||
<img src="http://i.imgur.com/LyTCCqg.png" width="512px" alt="Android in-process node"/> |
||||
|
||||
```java |
||||
import org.ethereum.geth.*; |
||||
|
||||
public class MainActivity extends AppCompatActivity { |
||||
@Override |
||||
protected void onCreate(Bundle savedInstanceState) { |
||||
super.onCreate(savedInstanceState); |
||||
setContentView(R.layout.activity_main); |
||||
|
||||
setTitle("Android In-Process Node"); |
||||
final TextView textbox = (TextView) findViewById(R.id.textbox); |
||||
|
||||
Context ctx = new Context(); |
||||
|
||||
try { |
||||
Node node = Geth.newNode(getFilesDir() + "/.ethereum", new NodeConfig()); |
||||
node.start(); |
||||
|
||||
NodeInfo info = node.getNodeInfo(); |
||||
textbox.append("My name: " + info.getName() + "\n"); |
||||
textbox.append("My address: " + info.getListenerAddress() + "\n"); |
||||
textbox.append("My protocols: " + info.getProtocols() + "\n\n"); |
||||
|
||||
EthereumClient ec = node.getEthereumClient(); |
||||
textbox.append("Latest block: " + ec.getBlockByNumber(ctx, -1).getNumber() + ", syncing...\n"); |
||||
|
||||
NewHeadHandler handler = new NewHeadHandler() { |
||||
@Override public void onError(String error) { } |
||||
@Override public void onNewHead(final Header header) { |
||||
MainActivity.this.runOnUiThread(new Runnable() { |
||||
public void run() { textbox.append("#" + header.getNumber() + ": " + header.getHash().getHex().substring(0, 10) + ".\n"); } |
||||
}); |
||||
} |
||||
}; |
||||
ec.subscribeNewHead(ctx, handler, 16); |
||||
} catch (Exception e) { |
||||
e.printStackTrace(); |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
#### Known quirks |
||||
|
||||
* Many constructors (those that would throw exceptions) are of the form `Geth.newXXX()`, instead of simply the Java style `new XXX()` This is an upstream limitation of the [gomobile](https://github.com/golang/mobile) project, one which is currently being worked on to resolve. |
||||
* There are zero documentations attached to the Java library methods. This too is a limitation of the [gomobile](https://github.com/golang/mobile) project. We will try to propose a fix upstream to make our docs from the Go codebase available in Java. |
||||
@ -1,161 +0,0 @@ |
||||
--- |
||||
title: Peer-to-peer |
||||
--- |
||||
The peer to peer package ([go-ethereum/p2p](https://github.com/ethereum/go-ethereum/tree/master/p2p)) allows you to rapidly and easily add peer to peer networking to any type of application. The p2p package is set up in a modular structure and extending the p2p with your own additional sub protocols is easy and straight forward. |
||||
|
||||
Starting the p2p service only requires you setup a `p2p.Server{}` with a few settings: |
||||
|
||||
```go |
||||
import "github.com/ethereum/go-ethereum/crypto" |
||||
import "github.com/ethereum/go-ethereum/p2p" |
||||
|
||||
nodekey, _ := crypto.GenerateKey() |
||||
srv := p2p.Server{ |
||||
MaxPeers: 10, |
||||
PrivateKey: nodekey, |
||||
Name: "my node name", |
||||
ListenAddr: ":30300", |
||||
Protocols: []p2p.Protocol{}, |
||||
} |
||||
srv.Start() |
||||
``` |
||||
|
||||
If we wanted to extend the capabilities of our p2p server we'd need to pass it an additional sub protocol in the `Protocol: []p2p.Protocol{}` array. |
||||
|
||||
An additional sub protocol that has the ability to respond to the message "foo" with "bar" requires you to setup an `p2p.Protocol{}`: |
||||
|
||||
```go |
||||
func MyProtocol() p2p.Protocol { |
||||
return p2p.Protocol{ // 1. |
||||
Name: "MyProtocol", // 2. |
||||
Version: 1, // 3. |
||||
Length: 1, // 4. |
||||
Run: func(peer *p2p.Peer, ws p2p.MsgReadWriter) error { return nil }, // 5. |
||||
} |
||||
} |
||||
``` |
||||
|
||||
1. A sub-protocol object in the p2p package is called `Protocol{}`. Each time a peer connects with the capability of handling this type of protocol will use this; |
||||
2. The name of your protocol to identify the protocol on the network; |
||||
3. The version of the protocol. |
||||
4. The amount of messages this protocol relies on. Because the p2p is extendible and thus has the ability to send an arbitrary amount of messages (with a type, which we'll see later) the p2p handler needs to know how much space it needs to reserve for your protocol, this to ensure consensus can be reached between the peers doing a negotiation over the message IDs. Our protocol supports only one; `message` (as you'll see later). |
||||
5. The main handler of your protocol. We've left this intentionally blank for now. The `peer` variable is the peer connected to you and provides you with some basic information regarding the peer. The `ws` variable which is a reader and a writer allows you to communicate with the peer. If a message is being send to us by that peer the `MsgReadWriter` will handle it and vice versa. |
||||
|
||||
Lets fill in the blanks and create a somewhat useful peer by allowing it to communicate with another peer: |
||||
|
||||
```go |
||||
const messageId = 0 // 1. |
||||
type Message string // 2. |
||||
|
||||
func msgHandler(peer *p2p.Peer, ws p2p.MsgReadWriter) error { |
||||
for { |
||||
msg, err := ws.ReadMsg() // 3. |
||||
if err != nil { // 4. |
||||
return err // if reading fails return err which will disconnect the peer. |
||||
} |
||||
|
||||
var myMessage [1]Message |
||||
err = msg.Decode(&myMessage) // 5. |
||||
if err != nil { |
||||
// handle decode error |
||||
continue |
||||
} |
||||
|
||||
switch myMessage[0] { |
||||
case "foo": |
||||
err := p2p.SendItems(ws, messageId, "bar") // 6. |
||||
if err != nil { |
||||
return err // return (and disconnect) error if writing fails. |
||||
} |
||||
default: |
||||
fmt.Println("recv:", myMessage) |
||||
} |
||||
} |
||||
|
||||
return nil |
||||
} |
||||
``` |
||||
|
||||
1. The one and only message we know about; |
||||
2. A typed string we decode in to; |
||||
3. `ReadMsg` waits on the line until it receives a message, an error or EOF. |
||||
4. In case of an error during reading it's best to return that error and let the p2p server handle it. This usually results in a disconnect from the peer. |
||||
5. `msg` contains two fields and a decoding method: |
||||
* `Code` contains the message id, `Code == messageId` (i.e., 0) |
||||
* `Payload` the contents of the message. |
||||
* `Decode(<ptr>)` is a helper method for: take `msg.Payload` and decodes the rest of the message in to the given interface. If it fails it will return an error. |
||||
6. If the message we decoded was `foo` respond with a `NewMessage` using the `messageId` message identifier and respond with the message `bar`. The `bar` message would be handled in the `default` case in the same switch. |
||||
|
||||
Now if we'd tie this all up we'd have a working p2p server with a message passing sub protocol. |
||||
|
||||
```go |
||||
package main |
||||
|
||||
import ( |
||||
"fmt" |
||||
"os" |
||||
|
||||
"github.com/ethereum/go-ethereum/crypto" |
||||
"github.com/ethereum/go-ethereum/p2p" |
||||
) |
||||
|
||||
const messageId = 0 |
||||
|
||||
type Message string |
||||
|
||||
func MyProtocol() p2p.Protocol { |
||||
return p2p.Protocol{ |
||||
Name: "MyProtocol", |
||||
Version: 1, |
||||
Length: 1, |
||||
Run: msgHandler, |
||||
} |
||||
} |
||||
|
||||
func main() { |
||||
nodekey, _ := crypto.GenerateKey() |
||||
srv := p2p.Server{ |
||||
MaxPeers: 10, |
||||
PrivateKey: nodekey, |
||||
Name: "my node name", |
||||
ListenAddr: ":30300", |
||||
Protocols: []p2p.Protocol{MyProtocol()}, |
||||
} |
||||
|
||||
if err := srv.Start(); err != nil { |
||||
fmt.Println(err) |
||||
os.Exit(1) |
||||
} |
||||
|
||||
select {} |
||||
} |
||||
|
||||
func msgHandler(peer *p2p.Peer, ws p2p.MsgReadWriter) error { |
||||
for { |
||||
msg, err := ws.ReadMsg() |
||||
if err != nil { |
||||
return err |
||||
} |
||||
|
||||
var myMessage Message |
||||
err = msg.Decode(&myMessage) |
||||
if err != nil { |
||||
// handle decode error |
||||
continue |
||||
} |
||||
|
||||
switch myMessage { |
||||
case "foo": |
||||
err := p2p.SendItems(ws, messageId, "bar")) |
||||
if err != nil { |
||||
return err |
||||
} |
||||
default: |
||||
fmt.Println("recv:", myMessage) |
||||
} |
||||
} |
||||
|
||||
return nil |
||||
} |
||||
``` |
||||
|
||||
@ -1,141 +0,0 @@ |
||||
--- |
||||
title: Tracing / Introduction |
||||
--- |
||||
There are two different types of transactions in Ethereum: plain value transfers and contract executions. A plain value transfer just moves Ether from one account to another and as such is uninteresting from this guide's perspective. If however the recipient of a transaction is a contract account with associated EVM (Ethereum Virtual Machine) bytecode - beside transferring any Ether - the code will also be executed as part of the transaction. |
||||
|
||||
Having code associated with Ethereum accounts permits transactions to do arbitrarilly complex data storage and enables them to act on the previously stored data by further transacting internally with outside accounts and contracts. This creates an intertwined ecosystem of contracts, where a single transaction can interact with tens or hunderds of accounts. |
||||
|
||||
The downside of contract execution is that it is very hard to say what a transaction actually did. A transaction receipt does contain a status code to check whether execution succeeded or not, but there's no way to see what data was modified, nor what external contracts where invoked. In order to introspect a transaction, we need to trace its execution. |
||||
|
||||
## Tracing prerequisites |
||||
|
||||
In its simplest form, tracing a transaction entails requesting the Ethereum node to reexecute the desired transaction with varying degrees of data collection and have it return the aggregated summary for post processing. Reexecuting a transaction however has a few prerequisites to be met. |
||||
|
||||
In order for an Ethereum node to reexecute a transaction, it needs to have available all historical state accessed by the transaction: |
||||
|
||||
* Balance, nonce, bytecode and storage of both the recipient as well as all internally invoked contracts. |
||||
* Block metadata referenced during execution of both the outer as well as all internally created transactions. |
||||
* Intermediate state generated by all preceding transactions contained in the same block as the one being traced. |
||||
|
||||
Depending on your node's mode of synchronization and pruning, different configurations result in different capabilities: |
||||
|
||||
* An **archive** node retaining **all historical data** can trace arbitrary transactions at any point in time. Tracing a single transaction also entails reexecuting all preceding transactions in the same block. |
||||
* A **fast synced** node retaining **all historical data** after initial sync can only trace transactions from blocks following the initial sync point. Tracing a single transaction also entails reexecuting all preceding transactions in the same block. |
||||
* A **fast synced** node retaining only **periodic state data** after initial sync can only trace transactions from blocks following the initial sync point. Tracing a single transaction entails reexecuting all preceding transactions **both** in the same block, as well as all preceding blocks until the previous stored snapshot. |
||||
* A **light synced** node retrieving data **on demand** can in theory trace transactions for which all required historical state is readily available in the network. In practice, data availability is **not** a feasible assumption. |
||||
|
||||
*There are exceptions to the above rules when running batch traces of entire blocks or chain segments. Those will be detailed later.* |
||||
|
||||
## Basic traces |
||||
|
||||
The simplest type of transaction trace that `go-ethereum` can generate are raw EVM opcode traces. For every VM instruction the transaction executes, a structured log entry is emitted, containing all contextual metadata deemed useful. This includes the *program counter*, *opcode name*, *opcode cost*, *remaining gas*, *execution depth* and any *occurred error*. The structured logs can optionally also contain the content of the *execution stack*, *execution memory* and *contract storage*. |
||||
|
||||
An example log entry for a single opcode looks like: |
||||
|
||||
```json |
||||
{ |
||||
"pc": 48, |
||||
"op": "DIV", |
||||
"gasCost": 5, |
||||
"gas": 64532, |
||||
"depth": 1, |
||||
"error": null, |
||||
"stack": [ |
||||
"00000000000000000000000000000000000000000000000000000000ffffffff", |
||||
"0000000100000000000000000000000000000000000000000000000000000000", |
||||
"2df07fbaabbe40e3244445af30759352e348ec8bebd4dd75467a9f29ec55d98d" |
||||
], |
||||
"memory": [ |
||||
"0000000000000000000000000000000000000000000000000000000000000000", |
||||
"0000000000000000000000000000000000000000000000000000000000000000", |
||||
"0000000000000000000000000000000000000000000000000000000000000060" |
||||
], |
||||
"storage": { |
||||
} |
||||
} |
||||
``` |
||||
|
||||
The entire output of an raw EVM opcode trace is a JSON object having a few metadata fields: *consumed gas*, *failure status*, *return value*; and a list of *opcode entries* that take the above form: |
||||
|
||||
```json |
||||
{ |
||||
"gas": 25523, |
||||
"failed": false, |
||||
"returnValue": "", |
||||
"structLogs": [] |
||||
} |
||||
``` |
||||
|
||||
### Generating basic traces |
||||
|
||||
To generate a raw EVM opcode trace, `go-ethereum` provides a few [RPC API endpoints](https://github.com/ethereum/go-ethereum/wiki/Management-APIs), out of which the most commonly used is [`debug_traceTransaction`](https://github.com/ethereum/go-ethereum/wiki/Management-APIs#debug_tracetransaction). |
||||
|
||||
In its simplest form, `traceTransaction` accepts a transaction hash as its sole argument, traces the transaction, aggregates all the generated data and returns it as a **large** JSON object. A sample invocation from the Geth console would be: |
||||
|
||||
```js |
||||
debug.traceTransaction("0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f") |
||||
``` |
||||
|
||||
The same call can of course be invoked from outside the node too via HTTP RPC. In this case, please make sure the HTTP endpoint is enabled via `--rpc` and the `debug` API namespace exposed via `--rpcapi=debug`. |
||||
|
||||
``` |
||||
$ curl -H "Content-Type: application/json" -d '{"id": 1, "method": "debug_traceTransaction", "params": ["0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f"]}' localhost:8545 |
||||
``` |
||||
|
||||
Running the above operation on the Rinkeby network (with a node retaining enough history) will result in this [trace dump](https://gist.github.com/karalabe/c91f95ac57f5e57f8b950ec65ecc697f). |
||||
|
||||
### Tuning basic traces |
||||
|
||||
By default the raw opcode tracer emits all relevant events that occur within the EVM while processing a transaction, such as *EVM stack*, *EVM memory* and *updated storage slots*. Certain use cases however may not need some of these data fields reported. To cater for those use cases, these massive fields may be omitted using a second *options* parameter for the tracer: |
||||
|
||||
```json |
||||
{ |
||||
"disableStack": true, |
||||
"disableMemory": true, |
||||
"disableStorage": true |
||||
} |
||||
``` |
||||
|
||||
Running the previous tracer invocation from the Geth console with the data fields disabled: |
||||
|
||||
```js |
||||
debug.traceTransaction("0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f", {disableStack: true, disableMemory: true, disableStorage: true}) |
||||
``` |
||||
|
||||
Analogously running the filtered tracer from outside the node too via HTTP RPC: |
||||
|
||||
``` |
||||
$ curl -H "Content-Type: application/json" -d '{"id": 1, "method": "debug_traceTransaction", "params": ["0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f", {"disableStack": true, "disableMemory": true, "disableStorage": true}]}' localhost:8545 |
||||
``` |
||||
|
||||
Running the above operation on the Rinkeby network will result in this significantly shorter [trace dump](https://gist.github.com/karalabe/d74a7cb33a70f2af75e7824fc772c5b4). |
||||
|
||||
### Limits of basic traces |
||||
|
||||
Although the raw opcode traces we've generated above have their use, this basic way of tracing is problematic in the real world. Having an individual log entry for every single opcode is too low level for most use cases, and will require developers to create additional tools to post-process the traces. Additionally, a full opcode trace can easily go into the hundreds of megabytes, making them very resource intensive to get out of the node and process externally. |
||||
|
||||
To avoid all of the previously mentioned issues, `go-ethereum` supports running custom JavaScript tracers *within* the Ethereum node, which have full access to the EVM stack, memory and contract storage. This permits developers to only gather the data they need, and do any processing **at** the data. Please see the next section for our *custom in-node tracers*. |
||||
|
||||
### Pruning |
||||
|
||||
Geth by default does in-memory pruning of state, discarding state entries that it deems is no longer necessary to maintain. This is configured via the `--gcmode` option. Often, people run into the error that state is not available. |
||||
|
||||
Say you want to do a trace on block `B`. Now there are a couple of cases: |
||||
|
||||
1. You have done a fast-sync, pivot block `P` where `P <= B`. |
||||
2. You have done a fast-sync, pivot block `P` where `P > B`. |
||||
3. You have done a full-sync, with pruning |
||||
4. You have done a full-sync, without pruning (`--gcmode=archive`) |
||||
|
||||
Here's what happens in each respective case: |
||||
|
||||
1. Geth will regenerate the desired state by replaying blocks from the closest point in time before `B` where it has full state. This defaults to [`128`](https://github.com/ethereum/go-ethereum/blob/master/eth/api_tracer.go#L52) blocks max, but you can specify more in the actual call `... "reexec":1000 .. }` to the tracer. |
||||
2. Sorry, can't be done without replaying from genesis. |
||||
3. Same as 1) |
||||
4. Does not need to replay anything, can immediately load up the state and serve the request. |
||||
|
||||
There is one other option available to you, which may or may not suit your needs. That is to use [Evmlab]( https://github.com/holiman/evmlab). |
||||
``` |
||||
docker pull holiman/evmlab && docker run -it holiman/evmlab |
||||
``` |
||||
There you can use the reproducer. The reproducer will incrementally fetch data from infura until it has all the information required to create the trace locally on an evm which is bundled with the image. It will create a custom genesis containing the state that the transaction touches (balances, code, nonce etc). It should be mentioned that the evmlab reproducer is strictly guaranteed to be totally exact with regards to gascosts incurred by the outer transaction, as evmlab does not fully calculate the gascosts for nonzero data etc, but is usually sufficient to analyze contracts and events. |
||||
@ -1,8 +1,10 @@ |
||||
--- |
||||
title: Developers' guide |
||||
title: Developer guide |
||||
sort_key: A |
||||
--- |
||||
|
||||
**NOTE: These instructions are for people who want to contribute Go source code changes. |
||||
If you just want to run ethereum, use the normal [Installation Instructions](installing-geth)** |
||||
If you just want to run ethereum, use the normal [Installation Instructions](../install-and-build/installing-geth)** |
||||
|
||||
This document is the entry point for developers of the Go implementation of Ethereum. Developers here refer to the hands-on: who are interested in build, develop, debug, submit a bug report or pull request or contribute code to go-ethereum. |
||||
|
||||
@ -1,7 +1,10 @@ |
||||
--- |
||||
title: Issue handling workflow |
||||
title: Issue Handling Workflow |
||||
sort_key: B |
||||
--- |
||||
|
||||
### (Draft proposal) |
||||
|
||||
Keep the number of open issues under 820 |
||||
|
||||
Keep the ratio of open issues per all issues under 13% |
||||
@ -1,22 +0,0 @@ |
||||
--- |
||||
title: Gas price oracle |
||||
--- |
||||
The gas price oracle is a helper function of the Geth client that tries to find an appropriate default gas price when sending transactions. It can be parametrized with the following command line options: |
||||
|
||||
- `gpomin`: lower limit of suggested gas price. This should be set at least as high as the `gasprice` setting usually used by miners so that your transactions will not be rejected automatically because of a too low price. |
||||
|
||||
- `gpomax`: higher limit of suggested gas price. During load peaks when there is a competition between transactions to get into the blocks, the price needs to be limited, otherwise the oracle would eventually try to overbid everyone else at any price. |
||||
|
||||
- `gpofull`: a block is considered "full" when a certain percentage of the block gas limit (specified in percents) is used up by transactions. If a block is not "full", that means that a transaction could have been accepted even with a minimal price offered. |
||||
|
||||
- `gpobasedown`: an exponential ratio (specified in `1/1000ths`) by which the base price decreases when the lowest acceptable price of the last block is below the last base price. |
||||
|
||||
- `gpobaseup`: an exponential ratio (specified in `1/1000ths`) by which the base price increases when the lowest acceptable price of the last block is over the last base price. |
||||
|
||||
- `gpobasecf`: a correction factor (specified in percents) of the base price. The suggested price is the corrected base price, limited by `gpomin` and `gpomax`. |
||||
|
||||
The lowest acceptable price is defined as a price that could have been enough to insert a transaction into a certain block. Although this value varies slightly with the gas used by the particular transaction, it is aproximated as follows: if the block is full, it is the lowest transaction gas price found in that block. If the block is not full, it equals to gpomin. |
||||
|
||||
The base price is a moving value that is adjusted from block to block, up if it was lower than the lowest acceptable price, down otherwise. Note that there is a slight amount of randomness added to the correction factors so that your client will not behave absolutely predictable on the market. |
||||
|
||||
If you want to specify a constant for the default gas price and not use the oracle, set both `gpomin` and `gpomax` to the same value. |
||||
@ -1,397 +0,0 @@ |
||||
--- |
||||
title: Contracts and transactions (Japanese) |
||||
--- |
||||
THIS WIKI IS BEING EDITED AND REVIEWED NOW. PLEASE DO NOT RELY ON IT. |
||||
|
||||
# Account types and transactions |
||||
|
||||
There are two types of accounts in Ethereum state: |
||||
* Normal or externally controlled accounts and |
||||
* contracts, i.e., sinppets of code, think a class. |
||||
|
||||
Both types of accounts have an ether balance. |
||||
|
||||
Transactions can be fired from from both types of accounts, though contracts only fire transactions in response to other transactions that they have received. Therefore, all action on ethereum block chain is set in motion by transactions fired from externally controlled accounts. |
||||
|
||||
The simplest transactions are ether transfer transactions. But before we go into that you should read up on [accounts](../interface/managing-your-accounts) and perhaps on [mining](../legacy/mining). |
||||
|
||||
## Ether transfer |
||||
|
||||
Assuming the account you are using as sender has sufficient funds, sending ether couldn't be easier. Which is also why you should probably be careful with this! You have been warned. |
||||
|
||||
```js |
||||
eth.sendTransaction({from: '0x036a03fc47084741f83938296a1c8ef67f6e34fa', to: '0xa8ade7feab1ece71446bed25fa0cf6745c19c3d5', value: web3.toWei(1, "ether")}) |
||||
``` |
||||
|
||||
Note the unit conversion in the `value` field. Transaction values are expressed in weis, the most granular units of value. If you want to use some other unit (like `ether` in the example above), use the function `web3.toWei` for conversion. |
||||
|
||||
Also, be advised that the amount debited from the source account will be slightly larger than that credited to the target account, which is what has been specified. The difference is a small transaction fee, discussed in more detail later. |
||||
|
||||
Contracts can receive transfers just like externally controlled accounts, but they can also receive more complicated transactions that actually run (parts of) their code and update their state. In order to understand those transactions, a rudimentary understanding of contracts is required. |
||||
|
||||
# contract のコンパイル |
||||
|
||||
blockchain 上で有効となる contract は Ethereum 特別仕様の バイナリの形式で、EVM byte コード と呼ばれます。 |
||||
しかしながら、典型的には、contract は [solidity](https://github.com/ethereum/wiki/wiki/Solidity-Tutorial) のような高級言語で記述され、blockchain 上に upload するために、この byte コードへコンパイルされます。 |
||||
|
||||
flontier リリースでは、geth は Christian R. と Lefteris K が手がけた、コマンドライン [solidity コンパイラ](https://solidity.readthedocs.io/en/latest/installing-solidity.html) である `solc` をシステムコールで呼び出すことを通して、solidity コンパイルをサポートしています。 |
||||
以下もお試しください。 |
||||
* [Solidity realtime compiler](https://chriseth.github.io/cpp-ethereum/) (by Christian R) |
||||
* [Cosmo](https://github.com/cosmo-project/meteor-dapp-cosmo) |
||||
* [Mix]() |
||||
* [AlethZero]() |
||||
|
||||
|
||||
|
||||
Note that other languages also exist, notably [serpent]() and [lll](). |
||||
|
||||
If you start up your `geth` node, you can check if this option is immediately available. This is what happens, if it is not: |
||||
|
||||
```js |
||||
eth.getCompilers() |
||||
['' ] |
||||
> eth.compile.solidity("") |
||||
error: eth_compileSolidity method not implemented |
||||
Invalid JSON RPC response |
||||
``` |
||||
|
||||
After you found a way to install `solc`, you make sure it's in the path, if [`eth.getCompilers()`](https://github.com/ethereum/wiki/wiki/JavaScript-API#web3ethgetcompilers) still does not find it (returns an empty array), you can set a custom path to the `sol` executable on the command line using th `solc` flag. |
||||
|
||||
``` |
||||
geth --datadir ~/frontier/00 --solc /usr/local/bin/solc --natspec |
||||
``` |
||||
|
||||
You can also set this option at runtime via the console: |
||||
|
||||
```js |
||||
> admin.setSolc("/usr/local/bin/solc") |
||||
solc v0.9.13 |
||||
Solidity Compiler: /usr/local/bin/solc |
||||
Christian <c@ethdev.com> and Lefteris <lefteris@ethdev.com> (c) 2014-2015 |
||||
true |
||||
``` |
||||
|
||||
Let us take this simple contract source: |
||||
|
||||
```js |
||||
> source = "contract test { function multiply(uint a) returns(uint d) { return a * 7; } }" |
||||
``` |
||||
|
||||
This contract offers a unary method: called with a positive integer `a`, it returns `a * 7`. |
||||
Note that this document is not about writing interesting contracts or about the features of solidity. |
||||
|
||||
For more information on contract language, go through [solidity tutorial](https://github.com/ethereum/wiki/wiki/Solidity-Tutorial), browse the contracts in our [dapp-bin](https://github.com/ethereum/dapp-bin/wiki), see other solidity and dapp resources. |
||||
|
||||
You are ready to compile solidity code in the `geth` JS console using [`eth.compile.solidity`](https://github.com/ethereum/wiki/wiki/JavaScript-API#web3ethcompilesolidity): |
||||
|
||||
```js |
||||
> contract = eth.compile.solidity(source) |
||||
{ |
||||
code: '605280600c6000396000f3006000357c010000000000000000000000000000000000000000000000000000000090048063c6888fa114602e57005b60376004356041565b8060005260206000f35b6000600782029050604d565b91905056', |
||||
info: { |
||||
language: 'Solidity', |
||||
languageVersion: '0', |
||||
compilerVersion: '0.9.13', |
||||
abiDefinition: [{ |
||||
constant: false, |
||||
inputs: [{ |
||||
name: 'a', |
||||
type: 'uint256' |
||||
} ], |
||||
name: 'multiply', |
||||
outputs: [{ |
||||
name: 'd', |
||||
type: 'uint256' |
||||
} ], |
||||
type: 'function' |
||||
} ], |
||||
userDoc: { |
||||
methods: { |
||||
} |
||||
}, |
||||
developerDoc: { |
||||
methods: { |
||||
} |
||||
}, |
||||
source: 'contract test { function multiply(uint a) returns(uint d) { return a * 7; } }' |
||||
} |
||||
} |
||||
``` |
||||
|
||||
The compiler is also available via [RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC) and therefore via [web3.js](https://github.com/ethereum/wiki/wiki/JavaScript-API#web3ethcompilesolidity) to any in-browser Ðapp connecting to `geth` via RPC. |
||||
|
||||
The following example shows how you interface `geth` via JSON-RPC to use the compiler. |
||||
|
||||
``` |
||||
./geth --datadir ~/eth/ --loglevel 6 --logtostderr=true --rpc --rpcport 8100 --rpccorsdomain '*' --mine console 2>> ~/eth/eth.log |
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_compileSolidity","params":["contract test { function multiply(uint a) returns(uint d) { return a * 7; } }"],"id":1}' http://127.0.0.1:8100 |
||||
``` |
||||
|
||||
The compiler output is combined into an object representing a single contract and is serialised as json. It contains the following fields: |
||||
|
||||
* `code`: the compiled EVM code |
||||
* `source`: the source code |
||||
* `language`: contract language (Solidity, Serpent, LLL) |
||||
* `languageVersion`: contract language version |
||||
* `compilerVersion`: compiler version |
||||
* `abiDefinition`: [Application Binary Interface Definition](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI) |
||||
* `userDoc`: [NatSpec user Doc](https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format) |
||||
* `developerDoc`: [NatSpec developer Doc](https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format) |
||||
|
||||
The immediate structuring of the compiler output (into `code` and `info`) reflects the two very different **paths of deployment**. |
||||
The compiled EVM code is sent off to the blockchain with a contract creation transaction while the rest (info) will ideally live on the decentralised cloud as publicly verifiable metadata complementing the code on the blockchain. |
||||
|
||||
# Creating and deploying a contract |
||||
|
||||
Now that you got both an unlocked account as well as some funds, you can create a contract on the blockchain by [sending a transaction](https://github.com/ethereum/wiki/wiki/JavaScript-API#web3ethsendtransaction) to the empty address with the evm code as data. Simple, eh? |
||||
|
||||
```js |
||||
primaryAddress = eth.accounts[0] |
||||
contractAddress = eth.sendTransaction({from: primaryAddress, data: evmCode}) |
||||
``` |
||||
|
||||
All binary data is serialised in hexadecimal form. Hex strings always have a hex prefix `0x`. |
||||
|
||||
Note that this step requires you to pay for execution. Your balance on the account (that you put as sender in the `from` field) will be reduced according to the gas rules of the VM once your transaction makes it into a block. More on that later. After some time, your transaction should appear included in a block confirming that the state it brought about is a consensus. Your contract now lives on the blockchain. |
||||
|
||||
The asynchronous way of doing the same looks like this: |
||||
|
||||
```js |
||||
eth.sendTransaction({from: primaryAccount, data: evmCode}, function(err, address) { |
||||
if (!err) |
||||
console.log(address); |
||||
}); |
||||
``` |
||||
|
||||
# Gas and transaction costs |
||||
|
||||
So how did you pay for all this? Under the hood, the transaction specified a gas limit and a gasprice, both of which could have been specified directly in the transaction object. |
||||
|
||||
Gas limit is there to protect you from buggy code running until your funds are depleted. The product of `gasPrice` and `gas` represents the maximum amount of Wei that you are willing to pay for executing the transaction. What you specify as `gasPrice` is used by miners to rank transactions for inclusion in the blockchain. It is the price in Wei of one unit of gas, in which VM operations are priced. |
||||
|
||||
The gas expenditure incurred by running your contract will be bought by the ether you have in your account at a price you specified in the transaction with `gasPrice`. If you do not have the ether to cover all the gas requirements to complete running your code, the processing aborts and all intermediate state changes roll back to the pre-transaction snapshot. The gas used up to the point where execution stopped were used after all, so the ether balance of your account will be reduced. These parameters can be adjusted on the transaction object fields `gas` and `gasPrice`. The `value` field is used the same as in ether transfer transactions between normal accounts. In other words transferring funds is available between any two accounts, either normal (i.e. externally controlled) or contract. If your contract runs out of funds, you should see an insufficient funds error. Note that all funds on contract accounts will be irrecoverably lost, once we release Homestead. |
||||
|
||||
For testing and playing with contracts you can use the test network or set up a private node (or cluster) potentially isolated from all the other nodes. If you then mine, you can make sure that your transaction will be included in the next block. You can see the pending transactions with: |
||||
|
||||
```js |
||||
eth.getBlock("pending", true).transactions |
||||
``` |
||||
|
||||
You can retrieve blocks by number (height) or by their hash: |
||||
|
||||
```js |
||||
genesis = eth.getBlock(0) |
||||
eth.getBlock(genesis.hash).hash == genesis.hash |
||||
true |
||||
``` |
||||
|
||||
Use `eth.blockNumber` to get the current blockchain height and the "latest" magic parameter to access the current head (newest block). |
||||
|
||||
```js |
||||
currentHeight = eth.blockNumber() |
||||
eth.getBlock("latest").hash == eth.getBlock(eth.blockNumber).hash |
||||
true |
||||
``` |
||||
|
||||
# Contract info (metadata) |
||||
|
||||
In the previous sections we explained how you create a contract on the blockchain. Now we deal with the rest of the compiler output, the **contract metadata** or contract info. |
||||
The idea is that |
||||
|
||||
* contract info is uploaded somewhere identifiable by a `url` which is publicly accessible |
||||
* anyone can find out what the `url` is only knowing the contracts address |
||||
|
||||
These requirements are achieved very simply by using a 2 step blockchain registry. The first step registers the contract code (hash) with a content hash in a contract called `HashReg`. The second step registers a url with the content hash in the `UrlHint` contract. |
||||
These [simple registry contracts]() will be part of the frontier proposition. |
||||
|
||||
By using this scheme, it is sufficient to know a contract's address to look up the url and fetch the actual contract metadata info bundle. Read on to learn why this is good. |
||||
|
||||
So if you are a conscientious contract creator, the steps are the following: |
||||
|
||||
1. Get the contract info json file. |
||||
2. Deploy contract info json file to any url of your choice |
||||
3. Register codehash ->content hash -> url |
||||
4. Deploy the contract itself to the blockchain |
||||
|
||||
The JS API makes this process very easy by providing helpers. Call [`admin.contractInfo.register`]() to extract info from the contract, write out its json serialisation in the given file, calculates the content hash of the file and finally registers this content hash to the contract's code hash. |
||||
Once you deployed that file to any url, you can use [`admin.contractInfo.registerUrl`]() to register the url with your content hash on the blockchain as well. (Note that in case a fixed content addressed model is used as document store, the url-hint is no longer necessary.) |
||||
|
||||
```js |
||||
source = "contract test { function multiply(uint a) returns(uint d) { return a * 7; } }" |
||||
// compile with solc |
||||
contract = eth.compile.solidity(source) |
||||
// send off the contract to the blockchain |
||||
address = eth.sendTransaction({from: primaryAccount, data: contract.code}) |
||||
// extracts info from contract, save the json serialisation in the given file, |
||||
// calculates the content hash and registers it with the code hash in `HashReg` |
||||
// it uses address to send the transaction. |
||||
// returns the content hash that we use to register a url |
||||
hash = admin.contractInfo.register(primaryAccount, address, contract, "~/dapps/shared/contracts/test/info.json") |
||||
// here you deploy ~/dapps/shared/contracts/test/info.json to a url |
||||
admin.contractInfo.registerUrl(primaryAccount, hash, url) |
||||
``` |
||||
|
||||
# Interacting with contracts |
||||
|
||||
[`eth.contract`](https://github.com/ethereum/wiki/wiki/JavaScript-API#web3ethcontract) can be used to define a contract _class_ that will comply with the contract interface as described in its [ABI definition](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI). |
||||
|
||||
```js |
||||
var Multiply7 = eth.contract(contract.info.abiDefinition); |
||||
var multiply7 = new Multiply7(address); |
||||
``` |
||||
|
||||
Now all the function calls specified in the abi are made available on the contract instance. You can just call those methods on the contract instance and chain `sendTransaction({from: address})` or `call()` to it. The difference between the two is that `call` performs a "dry run" locally, on your computer, while `sendTransaction` would actually submit your transaction for inclusion in the block chain and the results of its execution will eventually become part of the global consensus. In other words, use `call`, if you are interested only in the return value and use `sendTransaction` if you only care about "side effects" on the state of the contract. |
||||
|
||||
In the example above, there are no side effects, therefore `sendTransaction` only burns gas and increases the entropy of the universe. All "useful" functionality is exposed by `call`: |
||||
|
||||
```js |
||||
multiply7.multiply.call(6) |
||||
42 |
||||
``` |
||||
|
||||
Now suppose this contract is not yours, and you would like documentation or look at the source code. |
||||
This is made possible by making available the contract info bundle and register it in the blockchain. |
||||
The `admin.contractInfo` API provides convenience methods to fetch this bundle for any contract that chose to register. |
||||
To see how it works, read about [Contract Metadata](https://github.com/ethereum/wiki/wiki/Contract-metadata) or read the contract info deployment section of this document. |
||||
|
||||
```js |
||||
// get the contract info for contract address to do manual verification |
||||
var info = admin.contractInfo.get(address) // lookup, fetch, decode |
||||
var source = info.source; |
||||
var abiDef = info.abiDefinition |
||||
``` |
||||
|
||||
```js |
||||
// verify an existing contract in blockchain (NOT IMPLEMENTED) |
||||
admin.contractInfo.verify(address) |
||||
``` |
||||
|
||||
# NatSpec |
||||
|
||||
This section will further elaborate what you can do with contracts and transactions building on a protocol NatSpec. Solidity implements smart comments doxigen style which then can be used to generate various facades meta documents of the code. One such use case is to generate custom messages for transaction confirmation that clients can prompt users with. |
||||
|
||||
So we now extend the `multiply7` contract with a smart comment specifying a custom confirmation message (notice). |
||||
|
||||
```js |
||||
contract test { |
||||
/// @notice Will multiply `a` by 7. |
||||
function multiply(uint a) returns(uint d) { |
||||
return a * 7; |
||||
} |
||||
} |
||||
``` |
||||
|
||||
The comment has expressions in between backticks which are to be evaluated at the time the transaction confirmation message is presented to the user. The variables that refer to parameters of method calls then are instantiated in accordance with the actual transaction data sent by the user (or the user's dapp). NatSpec support for confirmation notices is fully implemented in `geth`. NatSpec relies on both the abi definition as well as the userDoc component to generate the proper confirmations. Therefore in order to access that, the contract needs to have registered its contract info as described above. |
||||
|
||||
Let us see a full example. As a very conscientious smart contract dev, you first create your contract and deploy according to the recommended steps above: |
||||
|
||||
```js |
||||
source = "contract test { |
||||
/// @notice Will multiply `a` by 7. |
||||
function multiply(uint a) returns(uint d) { |
||||
return a * 7; |
||||
} |
||||
}" |
||||
contract = eth.compile.solidity(source) |
||||
contentHash = admin.contractInfo.register(contract, "~/dapps/shared/contracts/test/info.json") |
||||
// put it up on your favourite site: |
||||
admin.contractInfo.registerUrl(contentHash, "http://dapphub.com/test/info.json") |
||||
``` |
||||
|
||||
For the purposes of a painless example just simply use the file url scheme (not exactly the cloud, but will show you how it works) without needing to deploy. `admin.contractInfo.registerUrl(contentHash, "file:///home/nirname/dapps/shared/contracts/test/info.json")`. |
||||
|
||||
Now you are done as a dev, so swap seats as it were and pretend that you are a user who is sending a transaction to the infamous multiply7 contract. |
||||
|
||||
You need to start the client with the `--natspec` flag to enable smart confirmations and contractInfo fetching. You can also set it on the console with `admin.contractInfo.start()` and `admin.contractInfo.stop()`. |
||||
|
||||
``` |
||||
geth --natspec --unlock primary console 2>> /tmp/eth.log |
||||
``` |
||||
|
||||
Now at the console type: |
||||
|
||||
```js |
||||
// obtain the abi definition for your contract |
||||
var info = admin.contractInfo.get(address) |
||||
var abiDef = info.abiDefinition |
||||
// instantiate a contract for transactions |
||||
var Multiply7 = eth.contract(abiDef); |
||||
var multiply7 = new Multiply7(); |
||||
``` |
||||
|
||||
And now try to send an actual transaction: |
||||
|
||||
```js |
||||
> multiply7.multiply.sendTransaction(6) |
||||
NatSpec: Will multiply 6 by 7. |
||||
Confirm? [Y/N] y |
||||
> |
||||
``` |
||||
|
||||
When this transaction gets included in a block, somewhere on a lucky miner's computer, 6 will get multiplied by 7, with the result ignored. |
||||
|
||||
```js |
||||
// assume an existing unlocked primary account |
||||
primary = eth.accounts[0]; |
||||
|
||||
// mine 10 blocks to generate ether |
||||
admin.miner.start(); |
||||
admin.debug.waitForBlocks(eth.blockNumber+10); |
||||
admin.miner.stop() ; |
||||
|
||||
balance = web3.fromWei(eth.getBalance(primary), "ether"); |
||||
|
||||
admin.contractInfo.newRegistry(primary); |
||||
|
||||
source = "contract test {\n" + |
||||
" /// @notice will multiply `a` by 7.\n" + |
||||
" function multiply(uint a) returns(uint d) {\n" + |
||||
" return a * 7;\n" + |
||||
" }\n" + |
||||
"} "; |
||||
|
||||
contract = eth.compile.solidity(source); |
||||
|
||||
contractaddress = eth.sendTransaction({from: primary, data: contract.code}); |
||||
|
||||
eth.getBlock("pending", true).transactions; |
||||
|
||||
admin.miner.start() |
||||
// waits until block height is minimum the number given. |
||||
// basically a sleep function on variable block units of time. |
||||
|
||||
admin.debug.waitForBlocks(eth.blockNumber+1); |
||||
admin.miner.stop() |
||||
|
||||
code = eth.getCode(contractaddress); |
||||
|
||||
abiDef = JSON.parse('[{"constant":false,"inputs":[{"name":"a","type":"uint256"}],"name":"multiply","outputs":[{"name":"d","type":"uint256"}],"type":"function"}]'); |
||||
Multiply7 = eth.contract(abiDef); |
||||
multiply7 = new Multiply7(contractaddress); |
||||
|
||||
fortytwo = multiply7.multiply.call(6); |
||||
console.log("multiply7.multiply.call(6) => "+fortytwo); |
||||
multiply7.multiply.sendTransaction(6, {from: primary}) |
||||
|
||||
admin.miner.start(); |
||||
admin.debug.waitForBlocks(eth.blockNumber+1); |
||||
admin.miner.stop(); |
||||
|
||||
filename = "/tmp/info.json"; |
||||
contenthash = admin.contractInfo.register(primary, contractaddress, contract, filename); |
||||
|
||||
admin.contractInfo.registerUrl(primary, contenthash, "file://"+filename); |
||||
|
||||
admin.miner.start(); |
||||
admin.debug.waitForBlocks(eth.blockNumber+1); |
||||
admin.miner.stop(); |
||||
|
||||
info = admin.contractInfo.get(contractaddress); |
||||
|
||||
admin.contractInfo.start(); |
||||
abiDef = JSON.parse('[{"constant":false,"inputs":[{"name":"a","type":"uint256"}],"name":"multiply","outputs":[{"name":"d","type":"uint256"}],"type":"function"}]'); |
||||
Multiply7 = eth.contract(abiDef); |
||||
multiply7 = new Multiply7(contractaddress); |
||||
fortytwo = multiply7.multiply.sendTransaction(6, { from: primary }); |
||||
|
||||
``` |
||||
@ -1,199 +0,0 @@ |
||||
--- |
||||
title: Mobile / Account management |
||||
--- |
||||
To provide Ethereum integration for your mobile applications, the very first thing you should be interested in doing is account management. |
||||
|
||||
Although all current leading Ethereum implementations provide account management built in, it is ill advised to keep accounts in any location that is shared between multiple applications and/or multiple people. The same way you do not entrust your ISP (who is after all your gateway into the internet) with your login credentials; you should not entrust an Ethereum node (who is your gateway into the Ethereum network) with your credentials either. |
||||
|
||||
The proper way to handle user accounts in your mobile applications is to do client side account management, everything self-contained within your own application. This way you can ensure as fine grained (or as coarse) access permissions to the sensitive data as deemed necessary, without relying on any third party application's functionality and/or vulnerabilities. |
||||
|
||||
To support this, `go-ethereum` provides a simple, yet thorough accounts library that gives you all the tools to do properly secured account management via encrypted keystores and passphrase protected accounts. You can leverage all the security of the `go-ethereum` crypto implementation while at the same time running everything in your own application. |
||||
|
||||
## Encrypted keystores |
||||
|
||||
Although handling your users' accounts locally on their own mobile device does provide certain security guarantees, access keys to Ethereum accounts should never lay around in clear-text form. As such, we provide an encrypted keystore that provides the proper security guarantees for you without requiring a thorough understanding from your part of the associated cryptographic primitives. |
||||
|
||||
The important thing to know when using the encrypted keystore is that the cryptographic primitives used within can operate either in *standard* or *light* mode. The former provides a higher level of security at the cost of increased computational burden and resource consumption: |
||||
|
||||
* *standard* needs 256MB memory and 1 second processing on a modern CPU to access a key |
||||
* *light* needs 4MB memory and 100 millisecond processing on a modern CPU to access a key |
||||
|
||||
As such, *light* is more suitable for mobile applications, but you should be aware of the trade-offs nonetheless. |
||||
|
||||
*For those interested in the cryptographic and/or implementation details, the key-store uses the `secp256k1` elliptic curve as defined in the [Standards for Efficient Cryptography](http://www.secg.org/sec2-v2.pdf), implemented by the [`libsecp256k`](https://github.com/bitcoin-core/secp256k1) library and wrapped by [`github.com/ethereum/go-ethereum/accounts`](https://godoc.org/github.com/ethereum/go-ethereum/accounts). Accounts are stored on disk in the [Web3 Secret Storage](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) format.* |
||||
|
||||
### Keystores on Android (Java) |
||||
|
||||
The encrypted keystore on Android is implemented by the `KeyStore` class from the `org.ethereum.geth` package. The configuration constants (for the *standard* or *light* security modes described above) are located in the `Geth` abstract class, similarly from the `org.ethereum.geth` package. Hence to do client side account management on Android, you'll need to import two classes into your Java code: |
||||
|
||||
```java |
||||
import org.ethereum.geth.Geth; |
||||
import org.ethereum.geth.KeyStore; |
||||
``` |
||||
|
||||
Afterwards you can create a new encrypted keystore via: |
||||
|
||||
```java |
||||
KeyStore ks = new KeyStore("/path/to/keystore", Geth.LightScryptN, Geth.LightScryptP); |
||||
``` |
||||
|
||||
The path to the keystore folder needs to be a location that is writable by the local mobile application but non-readable for other installed applications (for security reasons obviously), so we'd recommend placing it inside your app's data directory. If you are creating the `KeyStore` from within a class extending an Android object, you will most probably have access to the `Context.getFilesDir()` method via `this.getFilesDir()`, so you could set the keystore path to `this.getFilesDir() + "/keystore"`. |
||||
|
||||
The last two arguments of the `KeyStore` constructor are the crypto parameters defining how resource-intensive the keystore encryption should be. You can choose between `Geth.StandardScryptN, Geth.StandardScryptP`, `Geth.LightScryptN, Geth.LightScryptP` or specify your own numbers (please make sure you understand the underlying cryptography for this). We recommend using the *light* version. |
||||
|
||||
### Keystores on iOS (Swift 3) |
||||
|
||||
The encrypted keystore on iOS is implemented by the `GethKeyStore` class from the `Geth` framework. The configuration constants (for the *standard* or *light* security modes described above) are located in the same namespace as global variables. Hence to do client side account management on iOS, you'll need to import the framework into your Swift code: |
||||
|
||||
```swift |
||||
import Geth |
||||
``` |
||||
|
||||
Afterwards you can create a new encrypted account manager via: |
||||
|
||||
```swift |
||||
let ks = GethNewKeyStore("/path/to/keystore", GethLightScryptN, GethLightScryptP); |
||||
``` |
||||
|
||||
The path to the keystore folder needs to be a location that is writable by the local mobile application but non-readable for other installed applications (for security reasons obviously), so we'd recommend placing it inside your app's document directory. You should be able to retrieve the document directory via `let datadir = NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true)[0]`, so you could set the keystore path to `datadir + "/keystore"`. |
||||
|
||||
The last two arguments of the `GethNewKeyStore` factory method are the crypto parameters defining how resource-intensive the keystore encryption should be. You can choose between `GethStandardScryptN, GethStandardScryptP`, `GethLightScryptN, GethLightScryptP` or specify your own numbers (please make sure you understand the underlying cryptography for this). We recommend using the *light* version. |
||||
|
||||
## Account lifecycle |
||||
|
||||
Having created an encrypted keystore for your Ethereum accounts, you can use this for the entire account lifecycle requirements of your mobile application. This includes the basic functionality of creating new accounts and deleting existing ones; as well as the more advanced functionality of updating access credentials, exporting existing accounts, and importing them on another device. |
||||
|
||||
Although the keystore defines the encryption strength it uses to store your accounts, there is no global master password that can grant access to all of them. Rather each account is maintained individually, and stored on disk in its [encrypted format](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) individually, ensuring a much cleaner and stricter separation of credentials. |
||||
|
||||
This individuality however means that any operation requiring access to an account will need to provide the necessary authentication credentials for that particular account in the form of a passphrase: |
||||
|
||||
* When creating a new account, the caller must supply a passphrase to encrypt the account with. This passphrase will be required for any subsequent access, the lack of which will forever forfeit using the newly created account. |
||||
* When deleting an existing account, the caller must supply a passphrase to verify ownership of the account. This isn't cryptographically necessary, rather a protective measure against accidental loss of accounts. |
||||
* When updating an existing account, the caller must supply both current and new passphrases. After completing the operation, the account will not be accessible via the old passphrase any more. |
||||
* When exporting an existing account, the caller must supply both the current passphrase to decrypt the account, as well as an export passphrase to re-encrypt it with before returning the key-file to the user. This is required to allow moving accounts between devices without sharing original credentials. |
||||
* When importing a new account, the caller must supply both the encryption passphrase of the key-file being imported, as well as a new passhprase with which to store the account. This is required to allow storing account with different credentials than used for moving them around. |
||||
|
||||
*Please note, there is no recovery mechanisms for losing the passphrases. The cryptographic properties of the encrypted keystore (if using the provided parameters) guarantee that account credentials cannot be brute forced in any meaningful time.* |
||||
|
||||
### Accounts on Android (Java) |
||||
|
||||
An Ethereum account on Android is implemented by the `Account` class from the `org.ethereum.geth` package. Assuming we already have an instance of a `KeyStore` called `ks` from the previous section, we can easily execute all of the described lifecycle operations with a handful of function calls. |
||||
|
||||
```java |
||||
// Create a new account with the specified encryption passphrase. |
||||
Account newAcc = ksm.newAccount("Creation password"); |
||||
|
||||
// Export the newly created account with a different passphrase. The returned |
||||
// data from this method invocation is a JSON encoded, encrypted key-file. |
||||
byte[] jsonAcc = ks.exportKey(newAcc, "Creation password", "Export password"); |
||||
|
||||
// Update the passphrase on the account created above inside the local keystore. |
||||
ks.updateAccount(newAcc, "Creation password", "Update password"); |
||||
|
||||
// Delete the account updated above from the local keystore. |
||||
ks.deleteAccount(newAcc, "Update password"); |
||||
|
||||
// Import back the account we've exported (and then deleted) above with yet |
||||
// again a fresh passphrase. |
||||
Account impAcc = ks.importKey(jsonAcc, "Export password", "Import password"); |
||||
``` |
||||
|
||||
*Although instances of `Account` can be used to access various information about specific Ethereum accounts, they do not contain any sensitive data (such as passphrases or private keys), rather act solely as identifiers for client code and the keystore.* |
||||
|
||||
### Accounts on iOS (Swift 3) |
||||
|
||||
An Ethereum account on iOS is implemented by the `GethAccount` class from the `Geth` framework. Assuming we already have an instance of a `GethKeyStore` called `ks` from the previous section, we can easily execute all of the described lifecycle operations with a handful of function calls. |
||||
|
||||
```swift |
||||
// Create a new account with the specified encryption passphrase. |
||||
let newAcc = try! ks?.newAccount("Creation password") |
||||
|
||||
// Export the newly created account with a different passphrase. The returned |
||||
// data from this method invocation is a JSON encoded, encrypted key-file. |
||||
let jsonKey = try! ks?.exportKey(newAcc!, passphrase: "Creation password", newPassphrase: "Export password") |
||||
|
||||
// Update the passphrase on the account created above inside the local keystore. |
||||
try! ks?.update(newAcc, passphrase: "Creation password", newPassphrase: "Update password") |
||||
|
||||
// Delete the account updated above from the local keystore. |
||||
try! ks?.delete(newAcc, passphrase: "Update password") |
||||
|
||||
// Import back the account we've exported (and then deleted) above with yet |
||||
// again a fresh passphrase. |
||||
let impAcc = try! ks?.importKey(jsonKey, passphrase: "Export password", newPassphrase: "Import password") |
||||
``` |
||||
|
||||
*Although instances of `GethAccount` can be used to access various information about specific Ethereum accounts, they do not contain any sensitive data (such as passphrases or private keys), rather act solely as identifiers for client code and the keystore.* |
||||
|
||||
## Signing authorization |
||||
|
||||
As mentioned above, account objects do not hold the sensitive private keys of the associated Ethereum accounts, but are merely placeholders to identify the cryptographic keys with. All operations that require authorization (e.g. transaction signing) are performed by the account manager after granting it access to the private keys. |
||||
|
||||
There are a few different ways one can authorize the account manager to execute signing operations, each having its advantages and drawbacks. Since the different methods have wildly different security guarantees, it is essential to be clear on how each works: |
||||
|
||||
* **Single authorization**: The simplest way to sign a transaction via the keystore is to provide the passphrase of the account every time something needs to be signed, which will ephemerally decrypt the private key, execute the signing operation and immediately throw away the decrypted key. The drawbacks are that the passphrase needs to be queried from the user every time, which can become annoying if done frequently; or the application needs to keep the passphrase in memory, which can have security consequences if not done properly; and depending on the keystore's configured strength, constantly decrypting keys can result in non-negligible resource requirements. |
||||
* **Multiple authorizations**: A more complex way of signing transactions via the keystore is to unlock the account via its passphrase once, and allow the account manager to cache the decrypted private key, enabling all subsequent signing requests to complete without the passphrase. The lifetime of the cached private key may be managed manually (by explicitly locking the account back up) or automatically (by providing a timeout during unlock). This mechanism is useful for scenarios where the user may need to sign many transactions or the application would need to do so without requiring user input. The crucial aspect to remember is that **anyone with access to the account manager can sign transactions while a particular account is unlocked** (e.g. device left unattended; application running untrusted code). |
||||
|
||||
*Note, creating transactions is out of scope here, so the remainder of this section will assume we already have a transaction to sign, and will focus only on creating an authorized version of it. Creating an actually meaningful transaction will be covered later.* |
||||
|
||||
### Signing on Android (Java) |
||||
|
||||
Assuming we already have an instance of a `KeyStore` called `ks` from the previous sections, we can create a new account to sign transactions with via it's already demonstrated `newAccount` method; and to avoid going into transaction creation for now, we can hard-code a random transaction to sign instead. |
||||
|
||||
```java |
||||
// Create a new account to sign transactions with |
||||
Account signer = ks.newAccount("Signer password"); |
||||
Transaction tx = new Transaction( |
||||
1, new Address("0x0000000000000000000000000000000000000000"), |
||||
new BigInt(0), new BigInt(0), new BigInt(1), null); // Random empty transaction |
||||
BigInt chain = new BigInt(1); // Chain identifier of the main net |
||||
``` |
||||
|
||||
With the boilerplate out of the way, we can now sign transaction using the authorization mechanisms described above: |
||||
|
||||
```java |
||||
// Sign a transaction with a single authorization |
||||
Transaction signed = ks.signTxPassphrase(signer, "Signer password", tx, chain); |
||||
|
||||
// Sign a transaction with multiple manually cancelled authorizations |
||||
ks.unlock(signer, "Signer password"); |
||||
signed = ks.signTx(signer, tx, chain); |
||||
ks.lock(signer.getAddress()); |
||||
|
||||
// Sign a transaction with multiple automatically cancelled authorizations |
||||
ks.timedUnlock(signer, "Signer password", 1000000000); |
||||
signed = ks.signTx(signer, tx, chain); |
||||
``` |
||||
|
||||
### Signing on iOS (Swift 3) |
||||
|
||||
Assuming we already have an instance of a `GethKeyStore` called `ks` from the previous sections, we can create a new account to sign transactions with via it's already demonstrated `newAccount` method; and to avoid going into transaction creation for now, we can hard-code a random transaction to sign instead. |
||||
|
||||
```swift |
||||
// Create a new account to sign transactions with |
||||
var error: NSError? |
||||
let signer = try! ks?.newAccount("Signer password") |
||||
|
||||
let to = GethNewAddressFromHex("0x0000000000000000000000000000000000000000", &error) |
||||
let tx = GethNewTransaction(1, to, GethNewBigInt(0), GethNewBigInt(0), GethNewBigInt(0), nil) // Random empty transaction |
||||
let chain = GethNewBigInt(1) // Chain identifier of the main net |
||||
``` |
||||
|
||||
*Note, although Swift usually rewrites `NSError` returns to throws, this particular instance seems to have been missed for some reason (possibly due to it being a constructor). It will be fixed in a later version of the iOS bindings when the appropriate fixed are implemented upstream in the `gomobile` project.* |
||||
|
||||
With the boilerplate out of the way, we can now sign transaction using the authorization methods described above: |
||||
|
||||
```swift |
||||
// Sign a transaction with a single authorization |
||||
var signed = try! ks?.signTxPassphrase(signer, passphrase: "Signer password", tx: tx, chainID: chain) |
||||
|
||||
// Sign a transaction with multiple manually cancelled authorizations |
||||
try! ks?.unlock(signer, passphrase: "Signer password") |
||||
signed = try! ks?.signTx(signer, tx: tx, chainID: chain) |
||||
try! ks?.lock(signer?.getAddress()) |
||||
|
||||
// Sign a transaction with multiple automatically cancelled authorizations |
||||
try! ks?.timedUnlock(signer, passphrase: "Signer password", timeout: 1000000000) |
||||
signed = try! ks?.signTx(signer, tx: tx, chainID: chain) |
||||
``` |
||||
|
||||
@ -1,125 +0,0 @@ |
||||
--- |
||||
title: Mobile / Introduction |
||||
--- |
||||
The Ethereum blockchain along with its two extension protocols Whisper and Swarm was originally conceptualized to become the supporting pillar of web3, providing the consensus, messaging and storage backbone for a new generation of distributed (actually, decentralized) applications called DApps. |
||||
|
||||
The first incarnation towards this dream of web3 was a command line client providing an RPC interface into the peer-to-peer protocols. The client was soon enough extended with a web-browser-like graphical user interface, permitting developers to write DApps based on the tried and proven HTML/CSS/JS technologies. |
||||
|
||||
As many DApps have more complex requirements than what a browser environment can handle, it became apparent that providing programmatic access to the web3 pillars would open the door towards a new class of applications. As such, the second incarnation of the web3 dream is to open up all our technologies for other projects as reusable components. |
||||
|
||||
Starting with the 1.5 release family of `go-ethereum`, we transitioned away from providing only a full blown Ethereum client and started shipping official Go packages that could be embedded into third party desktop and server applications. It took only a small leap from here to begin porting our code to mobile platforms. |
||||
|
||||
## Quick overview |
||||
|
||||
Similarly to our reusable Go libraries, the mobile wrappers also focus on four main usage areas: |
||||
|
||||
- Simplified client side account management |
||||
- Remote node interfacing via different transports |
||||
- Contract interactions through auto-generated bindings |
||||
- In-process Ethereum, Whisper and Swarm peer-to-peer node |
||||
|
||||
You can watch a quick overview about these in Peter's (@karalabe) talk titled "Import Geth: Ethereum from Go and beyond", presented at the Ethereum Devcon2 developer conference in September, 2016 (Shanghai). Slides are [available here](https://ethereum.karalabe.com/talks/2016-devcon.html). |
||||
|
||||
[](https://www.youtube.com/watch?v=R0Ia1U9Gxjg) |
||||
|
||||
## Library bundles |
||||
|
||||
The `go-ethereum` mobile library is distributed either as an Android `.aar` archive (containing binaries for `arm-7`, `arm64`, `x86` and `x64`); or as an iOS XCode framework (containing binaries for `arm-7`, `arm64` and `x86`). We do not provide library bundles for Windows phone the moment. |
||||
|
||||
### Android archive |
||||
|
||||
The simplest way to use `go-ethereum` in your Android project is through a Maven dependency. We provide bundles of all our stable releases (starting from v1.5.0) through Maven Central, and also provide the latest develop bundle through the Sonatype OSS repository. |
||||
|
||||
#### Stable dependency (Maven Central) |
||||
|
||||
To add an Android dependency to the **stable** library release of `go-ethereum`, you'll need to ensure that the Maven Central repository is enabled in your Android project, and that the `go-ethereum` code is listed as a required dependency of your application. You can do both of these by editing the `build.gradle` script in your Android app's folder: |
||||
|
||||
```gradle |
||||
repositories { |
||||
mavenCentral() |
||||
} |
||||
|
||||
dependencies { |
||||
// All your previous dependencies |
||||
compile 'org.ethereum:geth:1.5.2' // Change the version to the latest release |
||||
} |
||||
``` |
||||
|
||||
#### Develop dependency (Sonatype) |
||||
|
||||
To add an Android dependency to the current **develop** version of `go-ethereum`, you'll need to ensure that the Sonatype snapshot repository is enabled in your Android project, and that the `go-ethereum` code is listed as a required `SNAPSHOT` dependency of your application. You can do both of these by editing the `build.gradle` script in your Android app's folder: |
||||
|
||||
```gradle |
||||
repositories { |
||||
maven { |
||||
url "https://oss.sonatype.org/content/groups/public" |
||||
} |
||||
} |
||||
|
||||
dependencies { |
||||
// All your previous dependencies |
||||
compile 'org.ethereum:geth:1.5.3-SNAPSHOT' // Change the version to the latest release |
||||
} |
||||
``` |
||||
|
||||
#### Custom dependency |
||||
|
||||
If you prefer not to depend on Maven Central or Sonatype; or would like to access an older develop build not available any more as an online dependency, you can download any bundle directly from [our website](https://geth.ethereum.org/downloads/) and insert it into your project in Android Studio via `File -> New -> New module... -> Import .JAR/.AAR Package`. |
||||
|
||||
You will also need to configure `gradle` to link the mobile library bundle to your application. This can be done by adding a new entry to the `dependencies` section of your `build.gradle` script, pointing it to the module you just added (named `geth` by default). |
||||
|
||||
```gradle |
||||
dependencies { |
||||
// All your previous dependencies |
||||
compile project(':geth') |
||||
} |
||||
``` |
||||
|
||||
#### Manual builds |
||||
|
||||
Lastly, if you would like to make modifications to the `go-ethereum` mobile code and/or build it yourself locally instead of downloading a pre-built bundle, you can do so using a `make` command. This will create an Android archive called `geth.aar` in the `build/bin` folder that you can import into your Android Studio as described above. |
||||
|
||||
```bash |
||||
$ make android |
||||
[...] |
||||
Done building. |
||||
Import "build/bin/geth.aar" to use the library. |
||||
``` |
||||
|
||||
### iOS framework |
||||
|
||||
The simplest way to use `go-ethereum` in your iOS project is through a [CocoaPods](https://cocoapods.org/) dependency. We provide bundles of all our stable releases (starting from v1.5.3) and also latest develop versions. |
||||
|
||||
#### Automatic dependency |
||||
|
||||
To add an iOS dependency to the current stable or latest develop version of `go-ethereum`, you'll need to ensure that your iOS XCode project is configured to use CocoaPods. Detailing that is out of scope in this document, but you can find a guide in the upstream [Using CocoaPods](https://guides.cocoapods.org/using/using-cocoapods.html) page. Afterwards you can edit your `Podfile` to list `go-ethereum` as a dependency: |
||||
|
||||
```ruby |
||||
target 'MyApp' do |
||||
# All your previous dependencies |
||||
pod 'Geth', '1.5.4' # Change the version to the latest release |
||||
end |
||||
``` |
||||
|
||||
Alternatively, if you'd like to use the latest develop version, replace the package version `1.5.4` with `~> 1.5.5-unstable` to switch to pre-releases and to always pull in the latest bundle from a particular release family. |
||||
|
||||
#### Custom dependency |
||||
|
||||
If you prefer not to depend on CocoaPods; or would like to access an older develop build not available any more as an online dependency, you can download any bundle directly from [our website](https://geth.ethereum.org/downloads/) and insert it into your project in XCode via `Project Settings -> Build Phases -> Link Binary With Libraries`. |
||||
|
||||
Do not forget to extract the framework from the compressed `.tar.gz` archive. You can do that either using a GUI tool or from the command line via (replace the archive with your downloaded file): |
||||
|
||||
``` |
||||
tar -zxvf geth-ios-all-1.5.3-unstable-e05d35e6.tar.gz |
||||
``` |
||||
|
||||
#### Manual builds |
||||
|
||||
Lastly, if you would like to make modifications to the `go-ethereum` mobile code and/or build it yourself locally instead of downloading a pre-built bundle, you can do so using a `make` command. This will create an iOS XCode framework called `Geth.framework` in the `build/bin` folder that you can import into XCode as described above. |
||||
|
||||
```bash |
||||
$ make ios |
||||
[...] |
||||
Done building. |
||||
Import "build/bin/Geth.framework" to use the library. |
||||
``` |
||||
@ -1,122 +0,0 @@ |
||||
--- |
||||
title: Native / Account management |
||||
--- |
||||
To provide Ethereum integration for your native applications, the very first thing you should be interested in doing is account management. |
||||
|
||||
Although all current leading Ethereum implementations provide account management built in, it is ill advised to keep accounts in any location that is shared between multiple applications and/or multiple people. The same way you do not entrust your ISP (who is after all your gateway into the internet) with your login credentials; you should not entrust an Ethereum node (who is your gateway into the Ethereum network) with your credentials either. |
||||
|
||||
The proper way to handle user accounts in your native applications is to do client side account management, everything self-contained within your own application. This way you can ensure as fine grained (or as coarse) access permissions to the sensitive data as deemed necessary, without relying on any third party application's functionality and/or vulnerabilities. |
||||
|
||||
To support this, `go-ethereum` provides a simple, yet thorough accounts package that gives you all the tools to do properly secured account management via encrypted keystores and passphrase protected accounts. You can leverage all the security of the `go-ethereum` crypto implementation while at the same time running everything in your own application. |
||||
|
||||
## Encrypted keystores |
||||
|
||||
Although handling accounts locally to an application does provide certain security guarantees, access keys to Ethereum accounts should never lay around in clear-text form. As such, we provide an encrypted keystore that provides the proper security guarantees for you without requiring a thorough understanding from your part of the associated cryptographic primitives. |
||||
|
||||
The important thing to know when using the encrypted keystore is that the cryptographic primitives used within can operate either in *standard* or *light* mode. The former provides a higher level of security at the cost of increased computational burden and resource consumption: |
||||
|
||||
* *standard* needs 256MB memory and 1 second processing on a modern CPU to access a key |
||||
* *light* needs 4MB memory and 100 millisecond processing on a modern CPU to access a key |
||||
|
||||
As such, *standard* is more suitable for native applications, but you should be aware of the trade-offs nonetheless in case you you're targeting more resource constrained environments. |
||||
|
||||
*For those interested in the cryptographic and/or implementation details, the key-store uses the `secp256k1` elliptic curve as defined in the [Standards for Efficient Cryptography](http://www.secg.org/sec2-v2.pdf), implemented by the [`libsecp256k`](https://github.com/bitcoin-core/secp256k1) library and wrapped by [`github.com/ethereum/go-ethereum/accounts`](https://godoc.org/github.com/ethereum/go-ethereum/accounts). Accounts are stored on disk in the [Web3 Secret Storage](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) format.* |
||||
|
||||
### Keystores from Go |
||||
|
||||
The encrypted keystore is implemented by the [`accounts.Manager`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager) struct from the [`github.com/ethereum/go-ethereum/accounts`](https://godoc.org/github.com/ethereum/go-ethereum/accounts) package, which also contains the configuration constants for the *standard* or *light* security modes described above. Hence to do client side account management from Go, you'll need to import only the `accounts` package into your code: |
||||
|
||||
```go |
||||
import "github.com/ethereum/go-ethereum/accounts" |
||||
``` |
||||
|
||||
Afterwards you can create a new encrypted account manager via: |
||||
|
||||
```go |
||||
am := accounts.NewManager("/path/to/keystore", accounts.StandardScryptN, accounts.StandardScryptP); |
||||
``` |
||||
|
||||
The path to the keystore folder needs to be a location that is writable by the local user but non-readable for other system users (for security reasons obviously), so we'd recommend placing it either inside your user's home directory or even more locked down for backend applications. |
||||
|
||||
The last two arguments of [`accounts.NewManager`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#NewManager) are the crypto parameters defining how resource-intensive the keystore encryption should be. You can choose between [`accounts.StandardScryptN, accounts.StandardScryptP`, `accounts.LightScryptN, accounts.LightScryptP`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#pkg-constants) or specify your own numbers (please make sure you understand the underlying cryptography for this). We recommend using the *standard* version. |
||||
|
||||
## Account lifecycle |
||||
|
||||
Having created an encrypted keystore for your Ethereum accounts, you can use this account manager for the entire account lifecycle requirements of your native application. This includes the basic functionality of creating new accounts and deleting existing ones; as well as the more advanced functionality of updating access credentials, exporting existing accounts, and importing them on another device. |
||||
|
||||
Although the keystore defines the encryption strength it uses to store your accounts, there is no global master password that can grant access to all of them. Rather each account is maintained individually, and stored on disk in its [encrypted format](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) individually, ensuring a much cleaner and stricter separation of credentials. |
||||
|
||||
This individuality however means that any operation requiring access to an account will need to provide the necessary authentication credentials for that particular account in the form of a passphrase: |
||||
|
||||
* When creating a new account, the caller must supply a passphrase to encrypt the account with. This passphrase will be required for any subsequent access, the lack of which will forever forfeit using the newly created account. |
||||
* When deleting an existing account, the caller must supply a passphrase to verify ownership of the account. This isn't cryptographically necessary, rather a protective measure against accidental loss of accounts. |
||||
* When updating an existing account, the caller must supply both current and new passphrases. After completing the operation, the account will not be accessible via the old passphrase any more. |
||||
* When exporting an existing account, the caller must supply both the current passphrase to decrypt the account, as well as an export passphrase to re-encrypt it with before returning the key-file to the user. This is required to allow moving accounts between machines and applications without sharing original credentials. |
||||
* When importing a new account, the caller must supply both the encryption passphrase of the key-file being imported, as well as a new passhprase with which to store the account. This is required to allow storing account with different credentials than used for moving them around. |
||||
|
||||
*Please note, there is no recovery mechanisms for losing the passphrases. The cryptographic properties of the encrypted keystore (if using the provided parameters) guarantee that account credentials cannot be brute forced in any meaningful time.* |
||||
|
||||
### Accounts from Go |
||||
|
||||
An Ethereum account is implemented by the [`accounts.Account`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Account) struct from the [`github.com/ethereum/go-ethereum/accounts`](https://godoc.org/github.com/ethereum/go-ethereum/accounts) package. Assuming we already have an instance of an [`accounts.Manager`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager) called `am` from the previous section, we can easily execute all of the described lifecycle operations with a handful of function calls (error handling omitted). |
||||
|
||||
```go |
||||
// Create a new account with the specified encryption passphrase. |
||||
newAcc, _ := am.NewAccount("Creation password"); |
||||
|
||||
// Export the newly created account with a different passphrase. The returned |
||||
// data from this method invocation is a JSON encoded, encrypted key-file. |
||||
jsonAcc, _ := am.Export(newAcc, "Creation password", "Export password"); |
||||
|
||||
// Update the passphrase on the account created above inside the local keystore. |
||||
am.Update(newAcc, "Creation password", "Update password"); |
||||
|
||||
// Delete the account updated above from the local keystore. |
||||
am.Delete(newAcc, "Update password"); |
||||
|
||||
// Import back the account we've exported (and then deleted) above with yet |
||||
// again a fresh passphrase. |
||||
impAcc, _ := am.Import(jsonAcc, "Export password", "Import password"); |
||||
``` |
||||
|
||||
*Although instances of [`accounts.Account`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Account) can be used to access various information about specific Ethereum accounts, they do not contain any sensitive data (such as passphrases or private keys), rather act solely as identifiers for client code and the keystore.* |
||||
|
||||
## Signing authorization |
||||
|
||||
As mentioned above, account objects do not hold the sensitive private keys of the associated Ethereum accounts, but are merely placeholders to identify the cryptographic keys with. All operations that require authorization (e.g. transaction signing) are performed by the account manager after granting it access to the private keys. |
||||
|
||||
There are a few different ways one can authorize the account manager to execute signing operations, each having its advantages and drawbacks. Since the different methods have wildly different security guarantees, it is essential to be clear on how each works: |
||||
|
||||
* **Single authorization**: The simplest way to sign a transaction via the account manager is to provide the passphrase of the account every time something needs to be signed, which will ephemerally decrypt the private key, execute the signing operation and immediately throw away the decrypted key. The drawbacks are that the passphrase needs to be queried from the user every time, which can become annoying if done frequently; or the application needs to keep the passphrase in memory, which can have security consequences if not done properly; and depending on the keystore's configured strength, constantly decrypting keys can result in non-negligible resource requirements. |
||||
* **Multiple authorizations**: A more complex way of signing transactions via the account manager is to unlock the account via its passphrase once, and allow the account manager to cache the decrypted private key, enabling all subsequent signing requests to complete without the passphrase. The lifetime of the cached private key may be managed manually (by explicitly locking the account back up) or automatically (by providing a timeout during unlock). This mechanism is useful for scenarios where the user may need to sign many transactions or the application would need to do so without requiring user input. The crucial aspect to remember is that **anyone with access to the account manager can sign transactions while a particular account is unlocked** (e.g. application running untrusted code). |
||||
|
||||
*Note, creating transactions is out of scope here, so the remainder of this section will assume we already have a transaction hash to sign, and will focus only on creating a cryptographic signature authorizing it. Creating an actual transaction and injecting the authorization signature into it will be covered later.* |
||||
|
||||
### Signing from Go |
||||
|
||||
Assuming we already have an instance of an [`accounts.Manager`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager) called `am` from the previous sections, we can create a new account to sign transactions with via it's already demonstrated [`NewAccount`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.NewAccount) method; and to avoid going into transaction creation for now, we can hard-code a random [`common.Hash`](https://godoc.org/github.com/ethereum/go-ethereum/common#Hash) to sign instead. |
||||
|
||||
```go |
||||
// Create a new account to sign transactions with |
||||
signer, _ := am.NewAccount("Signer password"); |
||||
txHash := common.HexToHash("0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"); |
||||
``` |
||||
|
||||
With the boilerplate out of the way, we can now sign transaction using the authorization mechanisms described above: |
||||
|
||||
```go |
||||
// Sign a transaction with a single authorization |
||||
signature, _ := am.SignWithPassphrase(signer, "Signer password", txHash.Bytes()); |
||||
|
||||
// Sign a transaction with multiple manually cancelled authorizations |
||||
am.Unlock(signer, "Signer password"); |
||||
signature, _ = am.Sign(signer.Address, txHash.Bytes()); |
||||
am.Lock(signer.Address); |
||||
|
||||
// Sign a transaction with multiple automatically cancelled authorizations |
||||
am.TimedUnlock(signer, "Signer password", time.Second); |
||||
signature, _ = am.Sign(signer.Address, txHash.Bytes()); |
||||
``` |
||||
|
||||
You may wonder why [`SignWithPassphrase`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.SignWithPassphrase) takes an [`accounts.Account`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Account) as the signer, whereas [`Sign`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.Sign) takes only a [`common.Address`](https://godoc.org/github.com/ethereum/go-ethereum/common#Address). The reason is that an [`accounts.Account`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Account) object may also contain a custom key-path, allowing [`SignWithPassphrase`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.SignWithPassphrase) to sign using accounts outside of the keystore; however [`Sign`](https://godoc.org/github.com/ethereum/go-ethereum/accounts#Manager.Sign) relies on accounts already unlocked within the keystore, so it cannot specify custom paths. |
||||
|
||||
@ -1,43 +0,0 @@ |
||||
--- |
||||
title: Native / Introduction |
||||
--- |
||||
The Ethereum blockchain along with its two extension protocols Whisper and Swarm was originally conceptualized to become the supporting pillar of web3, providing the consensus, messaging and storage backbone for a new generation of distributed (actually, decentralized) applications called DApps. |
||||
|
||||
The first incarnation towards this dream of web3 was a command line client providing an RPC interface into the peer-to-peer protocols. The client was soon enough extended with a web-browser-like graphical user interface, permitting developers to write DApps based on the tried and proven HTML/CSS/JS technologies. |
||||
|
||||
As many DApps have more complex requirements than what a browser environment can handle, it became apparent that providing programmatic access to the web3 pillars would open the door towards a new class of applications. As such, the second incarnation of the web3 dream is to open up all our technologies for other projects as reusable components. |
||||
|
||||
Starting with the 1.5 release family of `go-ethereum`, we transitioned away from providing only a full blown Ethereum client and started shipping official Go packages that could be embedded into third party desktop and server applications. |
||||
|
||||
*Note, this guide will assume you are familiar with Go development. It will make no attempts to cover general topics about Go project layouts, import paths or any other standard methodologies. If you are new to Go, consider reading its [getting started guides](https://github.com/golang/go/wiki#getting-started-with-go) first.* |
||||
|
||||
## Quick overview |
||||
|
||||
Our reusable Go libraries focus on four main usage areas: |
||||
|
||||
- Simplified client side account management |
||||
- Remote node interfacing via different transports |
||||
- Contract interactions through auto-generated bindings |
||||
- In-process Ethereum, Whisper and Swarm peer-to-peer node |
||||
|
||||
You can watch a quick overview about these in Peter's (@karalabe) talk titled "Import Geth: Ethereum from Go and beyond", presented at the Ethereum Devcon2 developer conference in September, 2016 (Shanghai). Slides are [available here](https://ethereum.karalabe.com/talks/2016-devcon.html). |
||||
|
||||
[](https://www.youtube.com/watch?v=R0Ia1U9Gxjg) |
||||
|
||||
## Go packages |
||||
|
||||
The `go-ethereum` library is distributed as a collection of standard Go packages straight from our GitHub repository. The packages can be used directly via the official Go toolkit, without needing any third party tools. External dependencies are vendored locally into `vendor`, ensuring both self-containment as well as code stability. If you reuse `go-ethereum` in your own project, please follow these best practices and vendor it yourself too to avoid any accidental API breakages! |
||||
|
||||
The canonical import path for `go-ethereum` is `github.com/ethereum/go-ethereum`, with all packages residing underneath. Although there are [quite a number](https://godoc.org/github.com/ethereum/go-ethereum#pkg-subdirectories) of them, you'll only need to care about a limited subset, each of which will be properly introduced in their relevant section. |
||||
|
||||
You can download all our packages via: |
||||
|
||||
``` |
||||
$ go get -d github.com/ethereum/go-ethereum/... |
||||
``` |
||||
|
||||
You may also need Go's original context package. Although this was moved into the official Go SDK in Go 1.7, `go-ethereum` will depend on the original `golang.org/x/net/context` package until we officially drop support for Go 1.5 and Go 1.6. |
||||
|
||||
``` |
||||
$ go get -u golang.org/x/net/context |
||||
``` |
||||
@ -1,45 +0,0 @@ |
||||
--- |
||||
title: Provisional JS API |
||||
--- |
||||
The *provisional* JavaScript API is a purposed API for all things JavaScript. JavaScript technologies can be embedded within Qt(QML) technologies, local web and remote web and therefor the purposed API is written in a ASYNC fashion so that it may be used across all implementations. Hereby it should be known that all functions, unless explicitly specified, take a callback as last function argument which will be called when the operation has been completed. |
||||
|
||||
Please note that the provisional JavaScript API tries to leverage existing JS idioms as much as possible. |
||||
|
||||
## General API |
||||
|
||||
* `getBlock (number or string)` |
||||
Retrieves a block by either the address or the number. If supplied with a string it will assume address, number otherwise. |
||||
* `transact (sec, recipient, value, gas, gas price, data)` |
||||
Creates a new transaction using your current key. |
||||
* `create (sec, value, gas, gas price, init, body)` |
||||
Creates a new contract using your current key. |
||||
* `getKey (none)` |
||||
Retrieves your current key in hex format. |
||||
* `getStorage (object address, storage address)` |
||||
Retrieves the storage address of the given object. |
||||
* `getBalance (object address)` |
||||
Retrieves the balance at the current address |
||||
* `watch (string [, string])` |
||||
Watches for changes on a specific address' state object such as state root changes or value changes. |
||||
* `disconnect (string [, string])` |
||||
Disconnects from a previous `watched` address. |
||||
|
||||
## Events |
||||
|
||||
The provisional JavaScript API exposes certain events through a basic eventing mechanism inspired by jQuery. |
||||
|
||||
* `on (event)` |
||||
Subscribe to event which will be called whenever an event of type <event> is received. |
||||
* `off (event)` |
||||
Unsubscribe to the given event |
||||
* `trigger (event, data)` |
||||
Trigger event of type <event> with the given data. **note:** This function does not take a callback function. |
||||
|
||||
### Event Types |
||||
|
||||
All events are written in camel cased style beginning with a lowercase letter. Subevents are denoted by a colon `:`. |
||||
|
||||
* `block:new` |
||||
Fired when a new valid block has been found on the wire. The attached value of this call is a block. |
||||
* `object:changed` |
||||
Fired when a watched address, specified through `watch`, changes in value. |
||||
@ -1,57 +0,0 @@ |
||||
--- |
||||
title: Setting up monitoring on local cluster |
||||
--- |
||||
This page describes how to set up a monitoring site for your private network. It builds upon [this page](setting-up-private-network-or-local-cluster) and assumes you've created a local cluster using [this script (gethcluster.sh)](https://github.com/ethersphere/eth-utils). |
||||
|
||||
The monitoring system consists of two components: |
||||
|
||||
1. **eth-netstats** - the monitoring site which lists the nodes. |
||||
2. **eth-net-intelligence-api** - these are processes that communicate with the ethereum client using RPC and push the data to the monitoring site via websockets. |
||||
|
||||
#Monitoring site |
||||
Clone the repo and install dependencies: |
||||
|
||||
git clone https://github.com/cubedro/eth-netstats |
||||
cd eth-netstats |
||||
npm install |
||||
|
||||
Then choose a secret and start the app: |
||||
|
||||
WS_SECRET=<chosen_secret> npm start |
||||
|
||||
You can now access the (empty) monitoring site at `http://localhost:3000`. |
||||
|
||||
You can also choose a different port: |
||||
|
||||
PORT=<chosen_port> WS_SECRET=<chosen_secret> npm start |
||||
|
||||
#Client-side information relays |
||||
These processes will relay the information from each of your cluster nodes to the monitoring site using websockets. |
||||
|
||||
Clone the repo, install dependencies and make sure you have pm2 installed: |
||||
|
||||
git clone https://github.com/cubedro/eth-net-intelligence-api |
||||
cd eth-net-intelligence-api |
||||
npm install |
||||
sudo npm install -g pm2 |
||||
|
||||
Now, use [this script (netstatconf.sh)](https://github.com/ethersphere/eth-utils) to create an `app.json` suitable for pm2. |
||||
|
||||
Usage: |
||||
|
||||
bash netstatconf.sh <number_of_clusters> <name_prefix> <ws_server> <ws_secret> |
||||
|
||||
- `number_of_clusters` is the number of nodes in the cluster. |
||||
- `name_prefix` is a prefix for the node names as will appear in the listing. |
||||
- `ws_server` is the eth-netstats server. Make sure you write the full URL, for example: http://localhost:3000. |
||||
- `ws_secret` is the eth-netstats secret. |
||||
|
||||
For example: |
||||
|
||||
bash netstatconf.sh 5 mynode http://localhost:3000 big-secret > app.json |
||||
|
||||
Run the script and copy the resulting `app.json` into the `eth-net-intelligence-api` directory. Afterwards, `cd` into `eth-net-intelligence-api` and run the relays using `pm2 start app.json`. To stop the relays, you can use `pm2 delete app.json`. |
||||
|
||||
**NOTE**: The script assumes the nodes have RPC ports 8101, 8102, ... . If that's not the case, edit app.json and change it accordingly for each peer. |
||||
|
||||
At this point, open `http://localhost:3000` and your monitoring site should monitor all your nodes! |
||||
@ -1,119 +0,0 @@ |
||||
--- |
||||
title: Setting up private network or local cluster |
||||
--- |
||||
This page describes how to set up a local cluster of nodes, advise how to make it private, and how to hook up your nodes on the eth-netstat network monitoring app. |
||||
A fully controlled ethereum network is useful as a backend for network integration testing (core developers working on issues related to networking/blockchain synching/message propagation, etc or DAPP developers testing multi-block and multi-user scenarios). |
||||
|
||||
We assume you are able to build `geth` following the [build instructions](../install-and-build/build-from-source) |
||||
|
||||
## Setting up multiple nodes |
||||
|
||||
In order to run multiple ethereum nodes locally, you have to make sure: |
||||
- each instance has a separate data directory (`--datadir`) |
||||
- each instance runs on a different port (both eth and rpc) (`--port and --rpcport`) |
||||
- in case of a cluster the instances must know about each other |
||||
- the ipc endpoint is unique or the ipc interface is disabled (`--ipcpath or --ipcdisable`) |
||||
|
||||
You start the first node (let's make port explicit and disable ipc interface) |
||||
```bash |
||||
geth --datadir="/tmp/eth/60/01" -verbosity 6 --ipcdisable --port 30301 --rpcport 8101 console 2>> /tmp/eth/60/01.log |
||||
``` |
||||
|
||||
We started the node with the console, so that we can grab the enode url for instance: |
||||
|
||||
``` |
||||
> admin.nodeInfo.enode |
||||
enode://8c544b4a07da02a9ee024def6f3ba24b2747272b64e16ec5dd6b17b55992f8980b77938155169d9d33807e501729ecb42f5c0a61018898c32799ced152e9f0d7@9[::]:30301 |
||||
``` |
||||
|
||||
`[::]` will be parsed as localhost (`127.0.0.1`). If your nodes are on a local network check each individual host machine and find your ip with `ifconfig` (on Linux and MacOS): |
||||
|
||||
```bash |
||||
$ ifconfig|grep netmask|awk '{print $2}' |
||||
127.0.0.1 |
||||
192.168.1.97 |
||||
``` |
||||
|
||||
If your peers are not on the local network, you need to know your external IP address (use a service) to construct the enode url. |
||||
|
||||
Now you can launch a second node with: |
||||
|
||||
```bash |
||||
geth --datadir="/tmp/eth/60/02" --verbosity 6 --ipcdisable --port 30302 --rpcport 8102 console 2>> /tmp/eth/60/02.log |
||||
``` |
||||
|
||||
If you want to connect this instance to the previously started node you can add it as a peer from the console with `admin.addPeer(enodeUrlOfFirstInstance)`. |
||||
|
||||
You can test the connection by typing in geth console: |
||||
|
||||
```javascript |
||||
> net.listening |
||||
true |
||||
> net.peerCount |
||||
1 |
||||
> admin.peers |
||||
... |
||||
``` |
||||
|
||||
## Local cluster |
||||
|
||||
As an extention of the above, you can spawn a local cluster of nodes easily. It can also be scripted including account creation which is needed for mining. |
||||
See [`gethcluster.sh`](https://github.com/ethersphere/eth-utils) script, and the README there for usage and examples. |
||||
|
||||
## Private network |
||||
|
||||
See [[the Private Network Page|Private network]] for more information. |
||||
|
||||
### Setup bootnode |
||||
|
||||
The first time a node connects to the network it uses one of the predefined [bootnodes](https://github.com/ethereum/go-ethereum/blob/master/params/bootnodes.go). Through these bootnodes a node can join the network and find other nodes. In the case of a private cluster these predefined bootnodes are not of much use. Therefore go-ethereum offers a bootnode implementation that can be configured and run in your private network. |
||||
|
||||
It can be run through the command. |
||||
``` |
||||
> bootnode |
||||
Fatal: Use -nodekey or -nodekeyhex to specify a private key |
||||
``` |
||||
|
||||
As can be seen the bootnode asks for a key. Each ethereum node, including a bootnode is identified by an enode identifier. These identifiers are derived from a key. Therefore you will need to give the bootnode such key. Since we currently don't have one we can instruct the bootnode to generate a key (and store it in a file) before it starts. |
||||
|
||||
``` |
||||
> bootnode -genkey bootnode.key |
||||
I0216 09:53:08.076155 p2p/discover/udp.go:227] Listening, enode://890b6b5367ef6072455fedbd7a24ebac239d442b18c5ab9d26f58a349dad35ee5783a0dd543e4f454fed22db9772efe28a3ed6f21e75674ef6203e47803da682@[::]:30301 |
||||
``` |
||||
|
||||
(exit with CTRL-C) |
||||
|
||||
The stored key can be seen with: |
||||
``` |
||||
> cat bootnode.key |
||||
dc90f8f7324f1cc7ba52c4077721c939f98a628ed17e51266d01c9cd0294033a |
||||
``` |
||||
|
||||
To instruct geth nodes to use our own bootnode(s) use the `--bootnodes` flag. This is a comma separated list of bootnode enode identifiers. |
||||
|
||||
``` |
||||
geth --bootnodes "enode://890b6b5367ef6072455fedbd7a24ebac239d442b18c5ab9d26f58a349dad35ee5783a0dd543e4f454fed22db9772efe28a3ed6f21e75674ef6203e47803da682@[::]:30301" |
||||
``` |
||||
(what [::] means is explained previously) |
||||
|
||||
Since it is convenient to start the bootnode each time with the same enode we can give the bootnode program the just generated key on the next time it is started. |
||||
|
||||
``` |
||||
bootnode -nodekey bootnode.key |
||||
I0216 10:01:19.125600 p2p/discover/udp.go:227] Listening, enode://890b6b5367ef6072455fedbd7a24ebac239d442b18c5ab9d26f58a349dad35ee5783a0dd543e4f454fed22db9772efe28a3ed6f21e75674ef6203e47803da682@[::]:30301 |
||||
``` |
||||
|
||||
or |
||||
|
||||
``` |
||||
bootnode -nodekeyhex dc90f8f7324f1cc7ba52c4077721c939f98a628ed17e51266d01c9cd0294033a |
||||
I0216 10:01:40.094089 p2p/discover/udp.go:227] Listening, enode://890b6b5367ef6072455fedbd7a24ebac239d442b18c5ab9d26f58a349dad35ee5783a0dd543e4f454fed22db9772efe28a3ed6f21e75674ef6203e47803da682@[::]:30301 |
||||
``` |
||||
|
||||
|
||||
## Monitoring your nodes |
||||
|
||||
[This page](https://github.com/ethereum/wiki/wiki/Network-Status) describes how to use the [The Ethereum (centralised) network status monitor (known sometimes as "eth-netstats")](http://stats.ethdev.com) to monitor your nodes. |
||||
|
||||
[This page](../doc/setting-up-monitoring-on-local-cluster) or [this README](https://github.com/ethersphere/eth-utils) |
||||
describes how you set up your own monitoring service for a (private or public) local cluster. |
||||
@ -1,270 +0,0 @@ |
||||
--- |
||||
title: URL Scheme |
||||
--- |
||||
# URLs in DAPP browsers |
||||
|
||||
URLs should contain all allowable urls in browsers and _all_ `http(s)` urls that resolve in a usual browser must resolve the same way. |
||||
|
||||
All urls not conforming to the existing urls scheme must still resemble the current urls scheme. |
||||
|
||||
``` |
||||
<protocol>://<source>/<path> |
||||
``` |
||||
|
||||
Irrespective of the main protocol, `<source>` should be resolved with our version of DNS (`NameReg` (ename registration contract on ethereum) and/or via swarm signed version stream. |
||||
|
||||
In the special case of the bzz protocol, `<source>` must resolve to a Swarm hash of the content (in other words, the root key of the content). This content is assumed to be of mime type `application/bzz-sitemap+json` the only mime-type directly handled by Swarm. |
||||
|
||||
# Swarm manifests |
||||
|
||||
A Swarm manifest is a json formatted description of url routing. |
||||
The swarm manifest allows swarm documents to act as file systems or webservers. |
||||
Their mime type is `application/bzz-sitemap+json` |
||||
Manifest has the following attributes: |
||||
|
||||
- `entries`: an array of route configurations |
||||
- `host`: eth host name registered (or to register) with NameReg |
||||
- `number`: position index (increasing integers) of manifest within channel, |
||||
- `auth`: devp2p cryptohandshake public key(s), signed number |
||||
- `first`: root key of initial state of the stream |
||||
- `previous`: previous state of stream |
||||
|
||||
A route descriptor manifest entry json object has the following attributes: |
||||
|
||||
- `path`: a path relative to the url that resolved to the manifest (_optional, with empty default_) |
||||
- `hash`: key of the content to be looked up by swarm (_optional_) |
||||
- `link`: relative path or external link (_optional_) |
||||
- `contentType`: mime type of the content (_optional, `application/bzz-server` by default_) |
||||
- `status`: optional http status code to pass back to the server (_optional, 200 by default_) |
||||
- `cache`: cache entry, etag? and other header options (_optional_) |
||||
- `www`: alternative old web address that the route replicates: e.g., `http://eth:bzz@google.com` (_optional_) |
||||
|
||||
If `path` is an empty string or is missing, the path matches the _document-root_ of the DAPP. |
||||
If `contentType` is empty or missing, manifest if assumed by default. |
||||
|
||||
(NOTE: Unclear. When no path matches and there is no fallback path e.g. a root `/` path with hash specified, it should return a simple 404 status code) |
||||
|
||||
# Url resolution |
||||
|
||||
Given |
||||
|
||||
``` |
||||
bzz://<source>/<path> |
||||
``` |
||||
|
||||
in the browser, the following steps need to happen: |
||||
|
||||
- the browser sees that its bzz protocol `<source>/<path>` is passed to the *bzz protocol handler*, |
||||
- the handler checks if `<source>` is a hash. If not it resolves to a hash via NameReg and signed version table, see below |
||||
- the bzz protocol handler first retrieves the content for the hash (with integrity check) which it interprets as a manifest file (`application/bzz-sitemap+json`), |
||||
- this manifest file is then parsed, read and the json array element with the longest prefix `p` of `<path>` is looked up. I.e., `p` is the longest prefix such that `<path> == p'/p''`. (If the longest prefix is 0 length, the row with `<path> == ""` (or left out) is chosen.) |
||||
- as a special case, trailing forward slashes are ignored so all variants will match the directory, |
||||
- the protocol then looks up content for `p'` and serves it to the browser together with the status code and content type. |
||||
- if content is of type manifest, bzz retrieves it and repeats the steps using `p''` to match the manifest's `<path>` values against, |
||||
- the url relative path is set to `p''` |
||||
- if the url looked up is an old-world http site, then a standard http client call is sufficient. |
||||
|
||||
### Example 1 |
||||
|
||||
```js |
||||
{ |
||||
entries: [ |
||||
{ |
||||
"path": "cv.pdf", |
||||
"contentType": "document/pdf", |
||||
"hash": "sdfhsd76ftsd86ft76sdgf78h7tg", |
||||
} |
||||
] |
||||
} |
||||
``` |
||||
|
||||
where the hash is the hash of the actual file `cv.pdf`. |
||||
|
||||
If this manifest hashes to `dafghjfgsdgfjfgsdjfgsd`, then `bzz://dafghjfgsdgfjfgsdjfgsd/cv.pdf` will serve `cv.pdf` |
||||
|
||||
Now you can register the manifest hash with NameReg to resolve `my-website` the file as follows: |
||||
|
||||
``` |
||||
http://my-website/cv.pdf |
||||
``` |
||||
|
||||
serves `cv.pdf` |
||||
|
||||
### Example 2 |
||||
Imagine you have a DAPP called _chat_ and host it under |
||||
your local directory `<dir>` looks like this: |
||||
|
||||
``` |
||||
index.html |
||||
img/logo.gif |
||||
img/avatars/fefe.jpg |
||||
img/avatars/index.html |
||||
``` |
||||
|
||||
the webserver has the following routing rules: |
||||
|
||||
``` |
||||
-> <dir>/index.html |
||||
<unkwown> -> <dir>/index.html # where <unknown> != index.html |
||||
img/logo.gif -> <dir>/img/logo.gif |
||||
img/avatars -> <dir>img/avatars/index.html |
||||
img/avatars/fefe.jpg -> <dir>/img/avatars/fefe.jpg |
||||
img/avatars/<unknown>.jpg <dir>/img/avatars/index.html # where <unknown> != fefe.jpg |
||||
``` |
||||
|
||||
Now you can alternatively host your app in Swarm by creating the following manifest: |
||||
|
||||
```js |
||||
{ |
||||
"entries": [ |
||||
{ "hash": HASH(<dir>/index.html) }, |
||||
{ "path": "index.html", "hash": HASH(<dir>/index.html) }, |
||||
{ "path": "img/logo.gif", "hash": HASH(<dir>/img/logo.gif) }, |
||||
{ "path": "img/avatars/", "hash": HASH(<dir>/img/avatars/index.html) }, |
||||
{ "path": "img/avatars/fefe.jpg", "hash": HASH(img/avatars/fefe.jpg) } |
||||
] |
||||
} |
||||
``` |
||||
|
||||
# Swarm webservers |
||||
|
||||
Swarm webservers are simply bzz site manifest files routing relative paths to static assets. |
||||
Manifest route entries specify metadata: http header values, etag, redirects, links, etc. |
||||
|
||||
In a typical scenario, the developer has a website within a working copy directory on their dev environment and they want to create a decentralised version of their site. |
||||
|
||||
They then register the host domain with ethereum NameReg or swarm signed version stream, upload all desired static assets to swarm, and produce a site manifest. |
||||
|
||||
In order to facilitate the creation of the manifest file for existing web projects, a native API and a command line utility are provided to automatically generate manifest files from a directory. |
||||
|
||||
## ArcHive API |
||||
|
||||
A native API and a command line utility are provided to automatically swarmify document collections. |
||||
constructor parameters: |
||||
|
||||
- `template`: manifest template: the entries found in the directory scan are merged into this template to yield the resulting site-map. Note that this template can be considered a config file to the archiver. |
||||
|
||||
The archiver can be called multiple times scanning multiple directories. |
||||
|
||||
runtime parameters: |
||||
- `path`: path to directory relative routes in the template matched against directory paths under `path` (_optional_, '.' by default). |
||||
- `not-found`: errorchange to be used when asset is not found: for 404, (_optional_, `index.html`) |
||||
- `register-names` use eth NameReg to register public key and this version is pushed to swarm mutable store (_optional_, _false_) |
||||
- `without-scan` only consider paths given in template (_optional_, by default _false_: in template, scan directory and add/merge all readable content to manifest) |
||||
- `without-upload`: files are not uploaded, only hashes are calculated and manifest is created (_optional_, _false_, upload every asset to swarm) |
||||
|
||||
If both `without-scan` and `without-upload` are omitted then `path` is used to associate files, extend the manifest entries, and upload content. |
||||
|
||||
if `register-names` is set all named nodes. |
||||
|
||||
### Examples |
||||
```js |
||||
{ |
||||
"entries": [ |
||||
{ |
||||
"path": "chat", |
||||
"hash": "sdfhsd76ftsd86ft76sdgf78h7tg", |
||||
"status": 200, |
||||
"contentType": "document/pdf" |
||||
}, |
||||
... |
||||
] |
||||
} |
||||
``` |
||||
|
||||
## Without swarm, the zip fallback |
||||
|
||||
namereg resolution: |
||||
|
||||
`contentOf('eth/wallet') -> 324234kj23h4kj2h3kj423kj4h23` |
||||
|
||||
This name reg has also a `urlOf` where it can find the file (e.g. from a raw pastebin) |
||||
|
||||
It then downloads the file, extracts it and resolves all relative/absolute paths, based on the manifest it finds in it. |
||||
|
||||
For the developer, the upload mechanism in mix will be the same, as he chooses a folder and can provide a `serverconfig.json` (or manfiest) |
||||
|
||||
The only difference is the lookup and where it gets the files from. |
||||
|
||||
``` |
||||
swarm -> content hashes |
||||
before swarm -> zip file content |
||||
``` |
||||
|
||||
And both are resolved through the same manifest scheme |
||||
|
||||
## Server config examples: |
||||
|
||||
URL: bzz://dsf32f3cdsfsd/somefolder/other |
||||
Same as: eth://myname.reggae/somefolder/other |
||||
|
||||
We should also map folder with and without "/" so that the path lookup for path: "/something/myfolder" is the same as "/something/myfolder/" |
||||
|
||||
```js |
||||
{ |
||||
previous: 'jgjgj67576576576567ytjy', |
||||
first: 'ds564rh5656hhfghfg', |
||||
entries:[{ |
||||
// Custom error page |
||||
path: '/i18n/', |
||||
file: '/errorpages/404.html', |
||||
// parses "file" when processing the folder and add: hash: '7685trgdrreewr34f34', contentType: 'text/html' |
||||
status: 404 |
||||
|
||||
},{ |
||||
// custom fallback file for this folder: "/images/sdffsdfds/" |
||||
path: '/images/sdffsdfds/', |
||||
file: '/index.html', |
||||
// parses "file" when processing the folder and add: hash: '345678678678678678tryrty', contentType: 'text/html' |
||||
|
||||
},{ |
||||
// custom fallback file with custom header. |
||||
path: '/', |
||||
file: '/index.html', |
||||
// parses "file" when processing the folder and add: hash: '434534534f34k234234hrkj34hkjrh34', contentType: 'text/html' |
||||
status: 500 |
||||
|
||||
},{ |
||||
// redirect (changing url after?) |
||||
path: '/somefolder/', |
||||
redirect: 'http://google.com' |
||||
|
||||
},{ |
||||
// linking? |
||||
path: '/somefolder/other/', |
||||
link: 'bzz://43greg45gerg5t45gerge/chat/' // hash to another manifest |
||||
|
||||
},{ |
||||
// downloading a file by pointing to a folder |
||||
path: '/somefolder/other/', |
||||
file: '/mybook.pdf', |
||||
// parses "file" when processing the folder and add: hash: '645325ytrhfgdge4tgre43f34', BUT no contentType, as its already present |
||||
contentType: 'application/octet-stream' // trigger a download in the browser for this link) |
||||
|
||||
},{ |
||||
// downloading |
||||
path: '/test.html', |
||||
file: '/test.html', |
||||
// parses "file" when processing the folder and add: hash: '645325ytrhfgdge4tgre43f34', BUT no contentType, as its already present |
||||
contentType: 'application/octet-stream' // trigger a download in the browser for this link) |
||||
|
||||
// automatic generated files |
||||
},{ |
||||
path: '/i18n/app.en.json', |
||||
hash: '456yrtgfds43534t45', |
||||
contentType: 'text/json', |
||||
},{ |
||||
path: '/somefolder/other/image.png', |
||||
hash: '434534534f34khrkj34hkjrh34', |
||||
contentType: 'image/png', |
||||
},{ |
||||
path: '/somefolder/other/343242.png', |
||||
hash: '434534534f34k234234hrkj34hkjrh34', |
||||
contentType: 'image/png', |
||||
},{ |
||||
path: '/somefold/frau.png', |
||||
hash: 'sdfsdfsdfsdfsdfsdfsd', |
||||
contentType: 'image/png', |
||||
}] |
||||
} |
||||
``` |
||||
@ -0,0 +1,125 @@ |
||||
--- |
||||
title: Private Network Tutorial |
||||
sort_key: B |
||||
--- |
||||
|
||||
This page describes how to set up a local cluster of nodes, advise how to make it private, |
||||
and how to hook up your nodes on the eth-netstat network monitoring app. A fully |
||||
controlled ethereum network is useful as a backend for network integration testing (core |
||||
developers working on issues related to networking/blockchain synching/message |
||||
propagation, etc or DAPP developers testing multi-block and multi-user scenarios). |
||||
|
||||
We assume you are able to build `geth` following the [build instructions](../install-and-build/build-from-source) |
||||
|
||||
## Setting up multiple nodes |
||||
|
||||
In order to run multiple ethereum nodes locally, you have to make sure: |
||||
|
||||
- each instance has a separate data directory (`--datadir`) |
||||
- each instance runs on a different port (both eth and rpc) (`--port and --rpcport`) |
||||
- in case of a cluster the instances must know about each other |
||||
- the ipc endpoint is unique or the ipc interface is disabled (`--ipcpath or --ipcdisable`) |
||||
|
||||
You start the first node (let's make port explicit and disable ipc interface) |
||||
|
||||
geth --datadir="/tmp/eth/60/01" -verbosity 6 --ipcdisable --port 30301 --rpcport 8101 console 2>> /tmp/eth/60/01.log |
||||
|
||||
We started the node with the console, so that we can grab the enode url for instance: |
||||
|
||||
> admin.nodeInfo.enode |
||||
enode://8c544b4a07da02a9ee024def6f3ba24b2747272b64e16ec5dd6b17b55992f8980b77938155169d9d33807e501729ecb42f5c0a61018898c32799ced152e9f0d7@9[::]:30301 |
||||
|
||||
`[::]` will be parsed as localhost (`127.0.0.1`). If your nodes are on a local network |
||||
check each individual host machine and find your ip with `ifconfig` (on Linux and MacOS): |
||||
|
||||
$ ifconfig|grep netmask|awk '{print $2}' |
||||
127.0.0.1 |
||||
192.168.1.97 |
||||
|
||||
If your peers are not on the local network, you need to know your external IP address (use |
||||
a service) to construct the enode url. |
||||
|
||||
Now you can launch a second node with: |
||||
|
||||
geth --datadir="/tmp/eth/60/02" --verbosity 6 --ipcdisable --port 30302 --rpcport 8102 console 2>> /tmp/eth/60/02.log |
||||
|
||||
If you want to connect this instance to the previously started node you can add it as a |
||||
peer from the console with `admin.addPeer(enodeUrlOfFirstInstance)`. |
||||
|
||||
You can test the connection by typing in geth console: |
||||
|
||||
> net.listening |
||||
true |
||||
> net.peerCount |
||||
1 |
||||
> admin.peers |
||||
... |
||||
|
||||
## Local cluster |
||||
|
||||
As an extention of the above, you can spawn a local cluster of nodes easily. It can also |
||||
be scripted including account creation which is needed for mining. See |
||||
[`gethcluster.sh`](https://github.com/ethersphere/eth-utils) script, and the README there |
||||
for usage and examples. |
||||
|
||||
## Private network |
||||
|
||||
See [[the Private Network Page|Private network]] for more information. |
||||
|
||||
### Setup bootnode |
||||
|
||||
The first time a node connects to the network it uses one of the predefined |
||||
[bootnodes](https://github.com/ethereum/go-ethereum/blob/master/params/bootnodes.go). |
||||
Through these bootnodes a node can join the network and find other nodes. In the case of a |
||||
private cluster these predefined bootnodes are not of much use. Therefore go-ethereum |
||||
offers a bootnode implementation that can be configured and run in your private network. |
||||
|
||||
It can be run through the command. |
||||
|
||||
> bootnode |
||||
Fatal: Use -nodekey or -nodekeyhex to specify a private key |
||||
|
||||
As can be seen the bootnode asks for a key. Each ethereum node, including a bootnode is |
||||
identified by an enode identifier. These identifiers are derived from a key. Therefore you |
||||
will need to give the bootnode such key. Since we currently don't have one we can instruct |
||||
the bootnode to generate a key (and store it in a file) before it starts. |
||||
|
||||
> bootnode -genkey bootnode.key |
||||
I0216 09:53:08.076155 p2p/discover/udp.go:227] Listening, enode://890b6b5367ef6072455fedbd7a24ebac239d442b18c5ab9d26f58a349dad35ee5783a0dd543e4f454fed22db9772efe28a3ed6f21e75674ef6203e47803da682@ |
||||
|
||||
(exit with CTRL-C) |
||||
|
||||
The stored key can be seen with: |
||||
|
||||
> cat bootnode.key |
||||
dc90f8f7324f1cc7ba52c4077721c939f98a628ed17e51266d01c9cd0294033a |
||||
|
||||
To instruct geth nodes to use our own bootnode(s) use the `--bootnodes` flag. This is a |
||||
comma separated list of bootnode enode identifiers. |
||||
|
||||
geth --bootnodes "enode://890b6b5367ef6072455fedbd7a24ebac239d442b18c5ab9d26f58a349dad35ee5783a0dd543e4f454fed22db9772efe28a3ed6f21e75674ef6203e47803da682@[::]:30301" |
||||
|
||||
(what `[::]` means is explained previously) |
||||
|
||||
Since it is convenient to start the bootnode each time with the same enode we can give the |
||||
bootnode program the just generated key on the next time it is started. |
||||
|
||||
bootnode -nodekey bootnode.key |
||||
I0216 10:01:19.125600 p2p/discover/udp.go:227] Listening, enode://890b6b5367ef6072455fedbd7a24ebac239d442b18c5ab9d26f58a349dad35ee5783a0dd543e4f454fed22db9772efe28a3ed6f21e75674ef6203e47803da682@[::]:30301 |
||||
|
||||
or |
||||
|
||||
bootnode -nodekeyhex dc90f8f7324f1cc7ba52c4077721c939f98a628ed17e51266d01c9cd0294033a |
||||
I0216 10:01:40.094089 p2p/discover/udp.go:227] Listening, enode://890b6b5367ef6072455fedbd7a24ebac239d442b18c5ab9d26f58a349dad35ee5783a0dd543e4f454fed22db9772efe28a3ed6f21e75674ef6203e47803da682@[::]:30301 |
||||
|
||||
## Monitoring your nodes |
||||
|
||||
[This page](https://github.com/ethereum/wiki/wiki/Network-Status) describes how to use the |
||||
[The Ethereum (centralised) network status monitor](eth-stats). to monitor your nodes. |
||||
|
||||
[This page](monitoring) or [this README](https://github.com/ethersphere/eth-utils) |
||||
describes how you set up your own monitoring service for a (private or public) local |
||||
cluster. |
||||
|
||||
[eth-stats]: https://ethstats.org |
||||
[monitoring]: ../doc/setting-up-monitoring-on-local-cluster |
||||
@ -1,5 +1,7 @@ |
||||
--- |
||||
title: FAQ |
||||
permalink: docs/faq |
||||
sort_key: C |
||||
--- |
||||
|
||||
**Q.** I noticed my peercount slowly decrease, and now it is at 0. Restarting doesn't get any peers. |
||||
@ -1,77 +1,84 @@ |
||||
--- |
||||
title: JavaScript console |
||||
title: JavaScript Console |
||||
sort_key: B |
||||
--- |
||||
Ethereum implements a **javascript runtime environment** (JSRE) that can be used in either interactive (console) or non-interactive (script) mode. |
||||
|
||||
Ethereum's Javascript console exposes the full [web3 JavaScript Dapp API](https://github.com/ethereum/wiki/wiki/JavaScript-API) and the admin API. |
||||
The Geth JavaScript console exposes the full [web3 JavaScript Dapp |
||||
API](https://github.com/ethereum/wiki/wiki/JavaScript-API) and further administrative |
||||
APIs. |
||||
|
||||
## Interactive use: the JSRE REPL Console |
||||
## Interactive Use: The Console |
||||
|
||||
The `ethereum CLI` executable `geth` has a JavaScript console (a **Read, Evaluate & Print Loop** = REPL exposing the JSRE), which can be started with the `console` or `attach` subcommand. The `console` subcommands starts the geth node and then opens the console. The `attach` subcommand will not start the geth node but instead tries to open the console on a running geth instance. |
||||
The geth JavaScript console is started with the `console` or `attach` geth sub-commands. |
||||
The `console` subcommands starts the geth node and then opens the console. The `attach` |
||||
subcommand attaches to the console to an already-running geth instance. |
||||
|
||||
$ geth console |
||||
$ geth attach |
||||
geth console |
||||
geth attach |
||||
|
||||
The attach node accepts an endpoint in case the geth node is running with a non default ipc endpoint or you would like to connect over the rpc interface. |
||||
Attach mode accepts an endpoint in case the geth node is running with a non default |
||||
ipc endpoint or you would like to connect over the rpc interface. |
||||
|
||||
$ geth attach /some/custom/path.ipc |
||||
$ geth attach http://191.168.1.1:8545 |
||||
$ geth attach ws://191.168.1.1:8546 |
||||
geth attach /some/custom/path.ipc |
||||
eth attach http://191.168.1.1:8545 |
||||
geth attach ws://191.168.1.1:8546 |
||||
|
||||
Note that by default the geth node doesn't start the http and weboscket service and not all functionality is provided over these interfaces due to security reasons. These defaults can be overridden when the `--rpcapi` and `--wsapi` arguments when the geth node is started, or with [admin.startRPC](management-apis#admin_startrpc) and [admin.startWS](management-apis#admin_startws). |
||||
Note that by default the geth node doesn't start the HTTP and WebSocket servers and not |
||||
all functionality is provided over these interfaces for security reasons. These defaults |
||||
can be overridden when the `--rpcapi` and `--wsapi` arguments when the geth node is |
||||
started, or with [admin.startRPC](../rpc/ns-admin#admin_startrpc) and |
||||
[admin.startWS](../rpc/ns-admin#admin_startws). |
||||
|
||||
If you need log information, start with: |
||||
|
||||
$ geth --verbosity 5 console 2>> /tmp/eth.log |
||||
geth console --verbosity 5 2>> /tmp/eth.log |
||||
|
||||
Otherwise mute your logs, so that it does not pollute your console: |
||||
|
||||
$ geth console 2> /dev/null |
||||
geth console 2> /dev/null |
||||
|
||||
or |
||||
Geth has support to load custom JavaScript files into the console through the `--preload` |
||||
option. This can be used to load often used functions, or to setup web3 contract objects. |
||||
|
||||
$ geth --verbosity 0 console |
||||
geth console --preload "/my/scripts/folder/utils.js,/my/scripts/folder/contracts.js" |
||||
|
||||
Geth has support to load custom JavaScript files into the console through the `--preload` argument. This can be used to load often used functions, setup web3 contract objects, or ... |
||||
``` |
||||
geth --preload "/my/scripts/folder/utils.js,/my/scripts/folder/contracts.js" console |
||||
``` |
||||
## Non-interactive Use: Script Mode |
||||
|
||||
It's also possible to execute files to the JavaScript interpreter. The `console` and |
||||
`attach` subcommand accept the `--exec` argument which is a javascript statement. |
||||
|
||||
## Non-interactive use: JSRE script mode |
||||
|
||||
It's also possible to execute files to the JavaScript interpreter. The `console` and `attach` subcommand accept the `--exec` argument which is a javascript statement. |
||||
|
||||
$ geth --exec "eth.blockNumber" attach |
||||
geth attach --exec "eth.blockNumber" |
||||
|
||||
This prints the current block number of a running geth instance. |
||||
|
||||
Or execute a local script with more complex statements on a remote node over http: |
||||
|
||||
$ geth --exec 'loadScript("/tmp/checkbalances.js")' attach http://123.123.123.123:8545 |
||||
$ geth --jspath "/tmp" --exec 'loadScript("checkbalances.js")' attach http://123.123.123.123:8545 |
||||
geth attach http://geth.example.org:8545 --exec 'loadScript("/tmp/checkbalances.js")' |
||||
geth attach http://geth.example.org:8545 --jspath "/tmp" --exec 'loadScript("checkbalances.js")' |
||||
|
||||
Use the `--jspath <path/to/my/js/root>` to set a libdir for your js scripts. Parameters to `loadScript()` with no absolute path will be understood relative to this directory. |
||||
Use the `--jspath <path/to/my/js/root>` to set a library directory for your js scripts. |
||||
Parameters to `loadScript()` with no absolute path will be understood relative to this |
||||
directory. |
||||
|
||||
You can exit the console cleanly by typing `exit` or simply with `CTRL-C`. |
||||
You can exit the console by typing `exit` or simply with `CTRL-C`. |
||||
|
||||
## Caveat |
||||
## Caveats |
||||
|
||||
The go-ethereum JSRE uses the [Otto JS VM](https://github.com/robertkrimen/otto) which has some limitations: |
||||
go-ethereum uses the [Otto JS VM](https://github.com/robertkrimen/otto) which has some |
||||
limitations: |
||||
|
||||
* `"use strict"` will parse, but does nothing. |
||||
* The regular expression engine (re2/regexp) is not fully compatible with the ECMA5 specification. |
||||
|
||||
Note that the other known limitation of Otto (namely the lack of timers) is taken care of. Ethereum JSRE implements both `setTimeout` and `setInterval`. In addition to this, the console provides `admin.sleep(seconds)` as well as a "blocktime sleep" method `admin.sleepBlocks(number)`. |
||||
|
||||
Since `web3.js` uses the [`bignumber.js`](https://github.com/MikeMcl/bignumber.js) library (MIT Expat Licence), it is also autoloded. |
||||
|
||||
## Timers |
||||
|
||||
In addition to the full functionality of JS (as per ECMA5), the ethereum JSRE is augmented with various timers. It implements `setInterval`, `clearInterval`, `setTimeout`, `clearTimeout` you may be used to using in browser windows. It also provides implementation for `admin.sleep(seconds)` and a block based timer, `admin.sleepBlocks(n)` which sleeps till the number of new blocks added is equal to or greater than `n`, think "wait for n confirmations". |
||||
* The regular expression engine (re2/regexp) is not fully compatible with the ECMA5 |
||||
specification. |
||||
|
||||
# Management APIs |
||||
`web3.js` uses the [`bignumber.js`](https://github.com/MikeMcl/bignumber.js) library. |
||||
This library is auto-loaded into the console. |
||||
|
||||
Beside the official [DApp API](https://github.com/ethereum/wiki/wiki/JSON-RPC) interface the go ethereum node has support for additional management API's. These API's are offered using [JSON-RPC](http://www.jsonrpc.org/specification) and follow the same conventions as used in the DApp API. The go ethereum package comes with a console client which has support for all additional API's. |
||||
### Timers |
||||
|
||||
[The management API has its own page](management-apis). |
||||
In addition to the full functionality of JS (as per ECMA5), the ethereum JSRE is augmented |
||||
with various timers. It implements `setInterval`, `clearInterval`, `setTimeout`, |
||||
`clearTimeout` you may be used to using in browser windows. It also provides |
||||
implementation for `admin.sleep(seconds)` and a block based timer, `admin.sleepBlocks(n)` |
||||
which sleeps till the number of new blocks added is equal to or greater than `n`, think |
||||
"wait for n confirmations". |
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,160 @@ |
||||
--- |
||||
title: Mining |
||||
sort_key: B |
||||
--- |
||||
|
||||
This document explains how to set up geth for mining. The Ethereum wiki also has a [page |
||||
about mining](eth-wiki-mining), be sure to check that one as well. |
||||
|
||||
Mining is the process through which new blocks are created. Geth actually creates new |
||||
blocks all the time, but these blocks need to be secured through proof-of-work so they |
||||
will be accepted by other nodes. Mining is all about creating these proof-of-work values. |
||||
|
||||
The proof-of-work computation can be performed in multiple ways. Geth includes a CPU |
||||
miner, which does mining within the geth process. We discourage using the CPU miner with |
||||
the Ethereum mainnet. If you want to mine real ether, use GPU mining. Your best option for |
||||
doing that is the [ethminer](ethminer) software. |
||||
|
||||
Always ensure your blockchain is fully synchronised with the chain before starting to |
||||
mine, otherwise you will not be mining on the correct chain and your block rewards will |
||||
not be valueable. |
||||
|
||||
## GPU mining |
||||
|
||||
The ethash algorithm is memory hard and in order to fit the DAG into memory, it needs |
||||
1-2GB of RAM on each GPU. If you get `Error GPU mining. GPU memory fragmentation?` you |
||||
don't have enough memory. |
||||
|
||||
### Installing ethminer |
||||
|
||||
To get ethminer, you need to install the ethminer binary package or build it from source. |
||||
See <https://github.com/ethereum-mining/ethminer/#build> for the official ethminer |
||||
build/install instructions. At the time of writing, ethminer only provides a binary for |
||||
Microsoft Windows. |
||||
|
||||
### Using ethminer with geth |
||||
|
||||
First create an account to hold your block rewards. |
||||
|
||||
geth account new |
||||
|
||||
Follow the prompts and enter a good password. **DO NOT FORGET YOUR PASSWORD**. Also take |
||||
note of the public Ethereum address which is printed at the end of the account creation |
||||
process. In the following examples, we will use 0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10 |
||||
as the example address. |
||||
|
||||
Now start geth and wait for it to sync the blockchain. This will take quite a while. |
||||
|
||||
geth --rpc --etherbase 0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10 |
||||
|
||||
Now we're ready to start mining. In a new terminal session, run ethminer and connect it to geth: |
||||
|
||||
ethminer -G -P http://127.0.0.1:8545 |
||||
|
||||
`ethminer` communicates with geth on port 8545 (the default RPC port in geth). You can |
||||
change this by giving the [`--rpcport` option](../rpc/index) to `geth`. Ethminer will find |
||||
get on any port. You also need to set the port on `ethminer` with `-P |
||||
http://127.0.0.1:3301`. Setting up custom ports is necessary if you want several instances |
||||
mining on the same computer. If you are testing on a private cluster, we recommend you use |
||||
CPU mining instead. |
||||
|
||||
If the default for `ethminer` does not work try to specify the OpenCL device with: |
||||
`--opencl-device X` where X is 0, 1, 2, etc. When running `ethminer` with `-M` |
||||
(benchmark), you should see something like: |
||||
|
||||
Benchmarking on platform: { "platform": "NVIDIA CUDA", "device": "GeForce GTX 750 Ti", "version": "OpenCL 1.1 CUDA" } |
||||
|
||||
Benchmarking on platform: { "platform": "Apple", "device": "Intel(R) Xeon(R) CPU E5-1620 v2 @ 3.70GHz", "version": "OpenCL 1.2 " } |
||||
|
||||
**Note** hashrate info is not available in `geth` when GPU mining. Check your hashrate |
||||
with `ethminer`, `miner.hashrate` will always report 0. |
||||
|
||||
## CPU Mining with Geth |
||||
|
||||
When you start up your ethereum node with `geth` it is not mining by default. To start it |
||||
in mining mode, you use the `--mine` command-line flag. The `--minerthreads` parameter can |
||||
be used to set the number parallel mining threads (defaulting to the total number of |
||||
processor cores). |
||||
|
||||
geth --mine --minerthreads=4 |
||||
|
||||
You can also start and stop CPU mining at runtime using the |
||||
[console](../interface/javascript-console). `miner.start` takes an optional parameter for |
||||
the number of miner threads. |
||||
|
||||
> miner.start(8) |
||||
true |
||||
> miner.stop() |
||||
true |
||||
|
||||
Note that mining for real ether only makes sense if you are in sync with the network |
||||
(since you mine on top of the consensus block). Therefore the eth blockchain |
||||
downloader/synchroniser will delay mining until syncing is complete, and after that mining |
||||
automatically starts unless you cancel your intention with `miner.stop()`. |
||||
|
||||
In order to earn ether you must have your **etherbase** (or **coinbase**) address set. |
||||
This etherbase defaults to your [primary account](../interface/managing-your-accounts). If |
||||
you don't have an etherbase address, then `geth --mine` will not start up. |
||||
|
||||
You can set your etherbase on the command line: |
||||
|
||||
geth --etherbase '0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10' --mine 2>> geth.log |
||||
|
||||
You can reset your etherbase on the console too: |
||||
|
||||
> miner.setEtherbase(eth.accounts[2]) |
||||
|
||||
Note that your etherbase does not need to be an address of a local account, just an |
||||
existing one. |
||||
|
||||
There is an option [to add extra data](../interface/javascript-console) (32 bytes only) to |
||||
your mined blocks. By convention this is interpreted as a unicode string, so you can set |
||||
your short vanity tag. |
||||
|
||||
> miner.setExtra("ΞTHΞЯSPHΞЯΞ") |
||||
|
||||
You can check your hashrate with [miner.hashrate](../interface/javascript-console), the |
||||
result is in H/s (Hash operations per second). |
||||
|
||||
> miner.hashrate |
||||
712000 |
||||
|
||||
After you successfully mined some blocks, you can check the ether balance of your |
||||
etherbase account. Now assuming your etherbase is a local account: |
||||
|
||||
> eth.getBalance(eth.coinbase).toNumber(); |
||||
'34698870000000' |
||||
|
||||
You can check which blocks are mined by a particular miner (address) with the following |
||||
code snippet on the console: |
||||
|
||||
> function minedBlocks(lastn, addr) { |
||||
addrs = []; |
||||
if (!addr) { |
||||
addr = eth.coinbase |
||||
} |
||||
limit = eth.blockNumber - lastn |
||||
for (i = eth.blockNumber; i >= limit; i--) { |
||||
if (eth.getBlock(i).miner == addr) { |
||||
addrs.push(i) |
||||
} |
||||
} |
||||
return addrs |
||||
} |
||||
// scans the last 1000 blocks and returns the blocknumbers of blocks mined by your coinbase |
||||
// (more precisely blocks the mining reward for which is sent to your coinbase). |
||||
> minedBlocks(1000, eth.coinbase) |
||||
[352708, 352655, 352559] |
||||
|
||||
Note that it will happen often that you find a block yet it never makes it to the |
||||
canonical chain. This means when you locally include your mined block, the current state |
||||
will show the mining reward credited to your account, however, after a while, the better |
||||
chain is discovered and we switch to a chain in which your block is not included and |
||||
therefore no mining reward is credited. Therefore it is quite possible that as a miner |
||||
monitoring their coinbase balance will find that it may fluctuate quite a bit. |
||||
|
||||
The logs show locally mined blocks confirmed after 5 blocks. At the moment you may find it |
||||
easier and faster to generate the list of your mined blocks from these logs. |
||||
|
||||
[eth-wiki-mining]: https://github.com/ethereum/wiki/wiki/Mining |
||||
[ethminer]: https://github.com/ethereum-mining/ethminer |
||||
@ -1,121 +0,0 @@ |
||||
--- |
||||
title: Creating your own Ethereum apps using Eth go |
||||
--- |
||||
|
||||
**This page is heavily outdated** |
||||
|
||||
The modular nature of Go and the Ethereum Go implementation make it very easy to build your own Ethereum native applications. |
||||
|
||||
This post will cover the minimal steps required to build an native Ethereum application. |
||||
|
||||
Ethereum comes with a global config found in the ethutil package. The global config requires you to set a base path to store it's files (database, settings, etc). |
||||
|
||||
```go |
||||
func main() { |
||||
// Read config |
||||
ethutil.ReadConfig(".test", ethutil.LogStd, nil, "MyEthApp") |
||||
} |
||||
``` |
||||
|
||||
ReadConfig takes four arguments. The data folder to use, a log flag, a globalConf instance and an id string to identify your app to other nodes in the network. |
||||
|
||||
Once you've configured the global config you can set up and create your Ethereum node. The Ethereum Object, or Node, will handle all trafic from and to the Ethereum network as well as handle all incoming block and transactions. A new node can be created through the `new` method found in eth-go. |
||||
|
||||
```go |
||||
func main() { |
||||
// Read config |
||||
ethutil.ReadConfig(".test", ethutil.LogStd, nil, "MyEthApp") |
||||
|
||||
// Create a new ethereum node |
||||
ethereum, err := eth.New(eth.CapDefault, false) |
||||
if err != nil { |
||||
panic(fmt.Sprintf("Could not start node: %s\n", err)) |
||||
} |
||||
// Set the port (default 30303) |
||||
ethereum.Port = "10101" |
||||
// Once we reach max, bounce them off. |
||||
ethereum.MaxPeers = 10 |
||||
} |
||||
``` |
||||
|
||||
New requires two arguments; the capabilities of the node and whether or not to use UPNP for port-forwarding. If you don't want to fallback to client-only features set an Ethereum port and the max amount of peers this node can connect to. |
||||
|
||||
In order to identify the node to the network you'll be required to create a private key. The easiest way to create a new keypair is by using the `KeyRing` found in the `ethutil` package. |
||||
|
||||
```go |
||||
func main() { |
||||
// Read config |
||||
ethutil.ReadConfig(".test", ethutil.LogStd, nil, "MyEthApp") |
||||
|
||||
// Create a new ethereum node |
||||
ethereum, err := eth.New(eth.CapDefault, false) |
||||
if err != nil { |
||||
panic(fmt.Sprintf("Could not start node: %s\n", err)) |
||||
} |
||||
// Set the port (default 30303) |
||||
ethereum.Port = "10101" |
||||
// Once we reach max, bounce them off. |
||||
ethereum.MaxPeers = 10 |
||||
|
||||
keyRing := ethutil.GetKeyRing() |
||||
// Create a new key if non exist |
||||
if keyRing.Len() == 0 { |
||||
// Create a new keypair |
||||
keyPair, err := ethutil.GenerateNewKeyPair() |
||||
if err != nil { |
||||
panic(err) |
||||
} |
||||
|
||||
// Add the keypair to the key ring |
||||
keyRing.Add(keyPair) |
||||
} |
||||
} |
||||
``` |
||||
|
||||
Once the base Ethereum stack has been set up it's time to fire up its engines and connect to the main network. |
||||
|
||||
```go |
||||
package main |
||||
|
||||
import ( |
||||
"github.com/ethereum/eth-go" |
||||
"github.com/ethereum/eth-go/ethutil" |
||||
) |
||||
|
||||
func main() { |
||||
// Read config |
||||
ethutil.ReadConfig(".test", ethutil.LogStd, nil, "MyEthApp") |
||||
|
||||
// Create a new ethereum node |
||||
ethereum, err := eth.New(eth.CapDefault, false) |
||||
if err != nil { |
||||
panic(fmt.Sprintf("Could not start node: %s\n", err)) |
||||
} |
||||
// Set the port (default 30303) |
||||
ethereum.Port = "10101" |
||||
// Once we reach max, bounce them off. |
||||
ethereum.MaxPeers = 10 |
||||
|
||||
keyRing := ethutil.GetKeyRing() |
||||
// Create a new key if non exist |
||||
if keyRing.Len() == 0 { |
||||
// Create a new keypair |
||||
keyPair, err := ethutil.GenerateNewKeyPair() |
||||
if err != nil { |
||||
panic(err) |
||||
} |
||||
|
||||
// Add the keypair to the key ring |
||||
keyRing.Add(keyPair) |
||||
} |
||||
|
||||
ethereum.Start(true) |
||||
ethereum.WaitForShutdown() |
||||
} |
||||
``` |
||||
|
||||
`ethereum.Start()` takes one argument, whether or not we want to connect to one of the known seed nodes. If you want your own little testnet-in-a-box you can disable it else set it to true. |
||||
|
||||
Your node should now be catching up with the blockchain. From here on out you are on your own. You could create a reactor to listen to specific events or just dive into the chain state directly. If you want to look at some example code you can check [DNSEth here.](https://github.com/maran/dnseth) |
||||
|
||||
Have fun! |
||||
@ -0,0 +1,44 @@ |
||||
--- |
||||
title: Gas price oracle |
||||
--- |
||||
|
||||
The gas price oracle is a helper function of the Geth client that tries to find an |
||||
appropriate default gas price when sending transactions. It can be parametrized with the |
||||
following command line options: |
||||
|
||||
- `gpomin`: lower limit of suggested gas price. This should be set at least as high as the |
||||
`gasprice` setting usually used by miners so that your transactions will not be rejected |
||||
automatically because of a too low price. |
||||
|
||||
- `gpomax`: higher limit of suggested gas price. During load peaks when there is a |
||||
competition between transactions to get into the blocks, the price needs to be limited, |
||||
otherwise the oracle would eventually try to overbid everyone else at any price. |
||||
|
||||
- `gpofull`: a block is considered "full" when a certain percentage of the block gas limit |
||||
(specified in percents) is used up by transactions. If a block is not "full", that means |
||||
that a transaction could have been accepted even with a minimal price offered. |
||||
|
||||
- `gpobasedown`: an exponential ratio (specified in `1/1000ths`) by which the base price |
||||
decreases when the lowest acceptable price of the last block is below the last base |
||||
price. |
||||
|
||||
- `gpobaseup`: an exponential ratio (specified in `1/1000ths`) by which the base price |
||||
increases when the lowest acceptable price of the last block is over the last base |
||||
price. |
||||
|
||||
- `gpobasecf`: a correction factor (specified in percents) of the base price. The |
||||
suggested price is the corrected base price, limited by `gpomin` and `gpomax`. |
||||
|
||||
The lowest acceptable price is defined as a price that could have been enough to insert a |
||||
transaction into a certain block. Although this value varies slightly with the gas used by |
||||
the particular transaction, it is aproximated as follows: if the block is full, it is the |
||||
lowest transaction gas price found in that block. If the block is not full, it equals to |
||||
gpomin. |
||||
|
||||
The base price is a moving value that is adjusted from block to block, up if it was lower |
||||
than the lowest acceptable price, down otherwise. Note that there is a slight amount of |
||||
randomness added to the correction factors so that your client will not behave absolutely |
||||
predictable on the market. |
||||
|
||||
If you want to specify a constant for the default gas price and not use the oracle, set |
||||
both `gpomin` and `gpomax` to the same value. |
||||
@ -1 +0,0 @@ |
||||
see here https://github.com/ethersphere/go-ethereum/wiki/IPFS--SWARM |
||||
@ -1,295 +0,0 @@ |
||||
--- |
||||
title: Mining |
||||
--- |
||||
* [Introduction to Ethereum mining](https://github.com/ethereum/wiki/wiki/Mining#introduction) _(main wiki)_ |
||||
|
||||
**This page is heavily outdated** |
||||
|
||||
# CPU Mining with Geth |
||||
|
||||
At Frontier, the first release of Ethereum, you'll just need a) a GPU and b) an Ethereum client, Geth. CPU mining will be possible but too inefficient to hold any value. |
||||
|
||||
At the moment, Geth only includes a CPU miner, and the team is testing a GPU miner branch, but this won't be part of Frontier. |
||||
|
||||
The C++ implementation of Ethereum also offers a GPU miner, both as part of Eth (its CLI), AlethZero (its GUI) and EthMiner (the standalone miner). |
||||
|
||||
_**NOTE:** Ensure your blockchain is fully synchronised with the main chain before starting to mine, otherwise you will not be mining on the main chain._ |
||||
|
||||
When you start up your ethereum node with `geth` it is not mining by default. To start it in mining mode, you use the `--mine` [command line option](../interface/command-line-options). The `-minerthreads` parameter can be used to set the number parallel mining threads (defaulting to the total number of processor cores). |
||||
|
||||
`geth --mine --minerthreads=4` |
||||
|
||||
You can also start and stop CPU mining at runtime using the [console](../interface/javascript-console). `miner.start` takes an optional parameter for the number of miner threads. |
||||
|
||||
``` |
||||
> miner.start(8) |
||||
true |
||||
> miner.stop() |
||||
true |
||||
``` |
||||
|
||||
Note that mining for real ether only makes sense if you are in sync with the network (since you mine on top of the consensus block). Therefore the eth blockchain downloader/synchroniser will delay mining until syncing is complete, and after that mining automatically starts unless you cancel your intention with `miner.stop()`. |
||||
|
||||
In order to earn ether you must have your **etherbase** (or **coinbase**) address set. This etherbase defaults to your [primary account](../interface/managing-your-accounts). If you don't have an etherbase address, then `geth --mine` will not start up. |
||||
|
||||
You can set your etherbase on the command line: |
||||
|
||||
``` |
||||
geth --etherbase 1 --mine 2>> geth.log // 1 is index: second account by creation order OR |
||||
geth --etherbase '0xa4d8e9cae4d04b093aac82e6cd355b6b963fb7ff' --mine 2>> geth.log |
||||
``` |
||||
|
||||
You can reset your etherbase on the console too: |
||||
``` |
||||
miner.setEtherbase(eth.accounts[2]) |
||||
``` |
||||
|
||||
Note that your etherbase does not need to be an address of a local account, just an existing one. |
||||
|
||||
There is an option [to add extra Data](../interface/javascript-console) (32 bytes only) to your mined blocks. By convention this is interpreted as a unicode string, so you can set your short vanity tag. |
||||
|
||||
``` |
||||
miner.setExtra("ΞTHΞЯSPHΞЯΞ") |
||||
... |
||||
debug.printBlock(131805) |
||||
BLOCK(be465b020fdbedc4063756f0912b5a89bbb4735bd1d1df84363e05ade0195cb1): Size: 531.00 B TD: 643485290485 { |
||||
NoNonce: ee48752c3a0bfe3d85339451a5f3f411c21c8170353e450985e1faab0a9ac4cc |
||||
Header: |
||||
[ |
||||
... |
||||
Coinbase: a4d8e9cae4d04b093aac82e6cd355b6b963fb7ff |
||||
Number: 131805 |
||||
Extra: ΞTHΞЯSPHΞЯΞ |
||||
... |
||||
} |
||||
``` |
||||
|
||||
See also [this proposal](https://github.com/ethereum/wiki/wiki/Extra-Data) |
||||
|
||||
You can check your hashrate with [miner.hashrate](../interface/javascript-console), the result is in H/s (Hash operations per second). |
||||
|
||||
``` |
||||
> miner.hashrate |
||||
712000 |
||||
``` |
||||
|
||||
After you successfully mined some blocks, you can check the ether balance of your etherbase account. Now assuming your etherbase is a local account: |
||||
|
||||
``` |
||||
> eth.getBalance(eth.coinbase).toNumber(); |
||||
'34698870000000' |
||||
``` |
||||
|
||||
In order to spend your earnings you will need to have this account unlocked. |
||||
|
||||
``` |
||||
> personal.unlockAccount(eth.coinbase) |
||||
Password |
||||
true |
||||
``` |
||||
|
||||
You can check which blocks are mined by a particular miner (address) with the following code snippet on the console: |
||||
|
||||
``` |
||||
function minedBlocks(lastn, addr) { |
||||
addrs = []; |
||||
if (!addr) { |
||||
addr = eth.coinbase |
||||
} |
||||
limit = eth.blockNumber - lastn |
||||
for (i = eth.blockNumber; i >= limit; i--) { |
||||
if (eth.getBlock(i).miner == addr) { |
||||
addrs.push(i) |
||||
} |
||||
} |
||||
return addrs |
||||
} |
||||
// scans the last 1000 blocks and returns the blocknumbers of blocks mined by your coinbase |
||||
// (more precisely blocks the mining reward for which is sent to your coinbase). |
||||
minedBlocks(1000, eth.coinbase); |
||||
//[352708, 352655, 352559] |
||||
``` |
||||
|
||||
Note that it will happen often that you find a block yet it never makes it to the canonical chain. This means when you locally include your mined block, the current state will show the mining reward credited to your account, however, after a while, the better chain is discovered and we switch to a chain in which your block is not included and therefore no mining reward is credited. Therefore it is quite possible that as a miner monitoring their coinbase balance will find that it may fluctuate quite a bit. |
||||
|
||||
The logs show locally mined blocks confirmed after 5 blocks. At the moment you may find it easier and faster to generate the list of your mined blocks from these logs. |
||||
|
||||
Mining success depends on the set block difficulty. Block difficulty dynamically adjusts each block in order to regulate the network hashing power to produce a 12 second blocktime. Your chances of finding a block therefore follows from your hashrate relative to difficulty. The time you need to wait you are expected to find a block can be estimated with the following code: |
||||
|
||||
**INCORRECT...CHECKING** |
||||
``` |
||||
etm = eth.getBlock("latest").difficulty/miner.hashrate; // estimated time in seconds |
||||
Math.floor(etm / 3600.) + "h " + Math.floor((etm % 3600)/60) + "m " + Math.floor(etm % 60) + "s"; |
||||
// 1h 3m 30s |
||||
``` |
||||
|
||||
Given a difficulty of 3 billion, a typical CPU with 800KH/s is expected to find a block every ....? |
||||
|
||||
|
||||
# GPU mining |
||||
|
||||
*** |
||||
|
||||
## Hardware |
||||
|
||||
The algorithm is memory hard and in order to fit the DAG into memory, it needs 1-2GB of RAM on each GPU. If you get ` Error GPU mining. GPU memory fragmentation?` you havent got enough memory. |
||||
|
||||
The GPU miner is implemented in OpenCL, so AMD GPUs will be 'faster' than same-category NVIDIA GPUs. |
||||
|
||||
ASICs and FPGAs are relatively inefficient and therefore discouraged. |
||||
|
||||
To get openCL for your chipset and platform, try: |
||||
* [AMD SDK openCL](http://developer.amd.com/tools-and-sdks) |
||||
* [NVIDIA CUDA openCL](https://developer.nvidia.com/cuda-downloads) |
||||
|
||||
## On Ubuntu |
||||
### AMD |
||||
|
||||
* http://developer.amd.com/tools-and-sdks |
||||
|
||||
download: `ADL_SDK8.zip ` and `AMD-APP-SDK-v2.9-1.599.381-GA-linux64.sh` |
||||
|
||||
``` |
||||
./AMD-APP-SDK-v2.9-1.599.381-GA-linux64.sh |
||||
ln -s /opt/AMDAPPSDK-2.9-1 /opt/AMDAPP |
||||
ln -s /opt/AMDAPP/include/CL /usr/include |
||||
ln -s /opt/AMDAPP/lib/x86_64/* /usr/lib/ |
||||
ldconfig |
||||
reboot |
||||
``` |
||||
|
||||
``` |
||||
apt-get install fglrx-updates |
||||
// wget, tar, opencl |
||||
sudo aticonfig --adapter=all --initial |
||||
sudo aticonfig --list-adapters |
||||
* 0. 01:00.0 AMD Radeon R9 200 Series |
||||
|
||||
* - Default adapter |
||||
``` |
||||
|
||||
### Nvidia |
||||
The following instructions are, for the most part, relevant to any system with Ubuntu 14.04 and a Nvidia GPU. |
||||
[Setting up an EC2 instance for mining](https://forum.ethereum.org/discussion/comment/8889/#Comment_8889) |
||||
|
||||
## On MacOSx |
||||
|
||||
``` |
||||
wget http://developer.download.nvidia.com/compute/cuda/7_0/Prod/local_installers/cuda_7.0.29_mac.pkg |
||||
sudo installer -pkg ~/Desktop/cuda_7.0.29_mac.pkg -target / |
||||
brew update |
||||
brew tap ethereum/ethereum |
||||
brew reinstall cpp-ethereum --with-gpu-mining --devel --headless --build-from-source |
||||
``` |
||||
|
||||
You check your cooling status: |
||||
|
||||
aticonfig --adapter=0 --od-gettemperature |
||||
|
||||
## Mining Software |
||||
|
||||
The official Frontier release of `geth` only supports a CPU miner natively. We are working on a GPU miner, but it may not be available for the Frontier release. Geth however can be used in conjunction with `ethminer`, using the standalone miner as workers and `geth` as scheduler communicating via [JSON-RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC). |
||||
|
||||
The [C++ implementation of Ethereum](https://github.com/ethereum/cpp-ethereum/) (not officially released) however has a GPU miner. It can be used from `eth`, `AlethZero` (GUI) and `ethMiner` (the standalone miner). |
||||
|
||||
[You can install this](https://github.com/ethereum/cpp-ethereum/wiki/Installing-clients) via ppa on linux, brew tap on MacOS or from source. |
||||
|
||||
On MacOS: |
||||
``` |
||||
brew install cpp-ethereum --with-gpu-mining --devel --build-from-source |
||||
``` |
||||
|
||||
On Linux: |
||||
``` |
||||
apt-get install cpp-ethereum |
||||
``` |
||||
|
||||
On Windows: |
||||
https://github.com/ethereum/cpp-ethereum/wiki/Building-on-Windows |
||||
|
||||
## GPU mining with ethminer |
||||
To mine with `eth`: |
||||
|
||||
``` |
||||
eth -m on -G -a <coinbase> -i -v 8 // |
||||
``` |
||||
|
||||
To install `ethminer` from source: |
||||
|
||||
``` |
||||
cd cpp-ethereum |
||||
cmake -DETHASHCL=1 -DGUI=0 |
||||
make -j4 |
||||
make install |
||||
``` |
||||
|
||||
To set up GPU mining you need a coinbase account. It can be an account created locally or remotely. |
||||
|
||||
### Using ethminer with geth |
||||
|
||||
``` |
||||
geth account new |
||||
geth --rpc --rpccorsdomain localhost 2>> geth.log & |
||||
ethminer -G // -G for GPU, -M for benchmark |
||||
tail -f geth.log |
||||
``` |
||||
|
||||
`ethminer` communicates with geth on port 8545 (the default RPC port in geth). You can change this by giving the [`--rpcport` option](../interface/command-line-options) to `geth`. |
||||
Ethminer will find get on any port. Note that you need to set the CORS header with `--rpccorsdomain localhost`. You can also set port on `ethminer` with `-F http://127.0.0.1:3301`. Setting the ports is necessary if you want several instances mining on the same computer, although this is somewhat pointless. If you are testing on a private cluster, we recommend you use CPU mining instead. |
||||
|
||||
Also note that you do **not** need to give `geth` the `--mine` option or start the miner in the console unless you want to do CPU mining on TOP of GPU mining. |
||||
|
||||
If the default for `ethminer` does not work try to specify the OpenCL device with: `--opencl-device X` where X is 0, 1, 2, etc. |
||||
When running `ethminer` with `-M` (benchmark), you should see something like: |
||||
|
||||
Benchmarking on platform: { "platform": "NVIDIA CUDA", "device": "GeForce GTX 750 Ti", "version": "OpenCL 1.1 CUDA" } |
||||
|
||||
|
||||
Benchmarking on platform: { "platform": "Apple", "device": "Intel(R) Xeon(R) CPU E5-1620 v2 @ 3.70GHz", "version": "OpenCL 1.2 " } |
||||
|
||||
To debug `geth`: |
||||
|
||||
``` |
||||
geth --rpccorsdomain "localhost" --verbosity 6 2>> geth.log |
||||
``` |
||||
|
||||
To debug the miner: |
||||
|
||||
``` |
||||
make -DCMAKE_BUILD_TYPE=Debug -DETHASHCL=1 -DGUI=0 |
||||
gdb --args ethminer -G -M |
||||
``` |
||||
|
||||
**Note** hashrate info is not available in `geth` when GPU mining. Check your hashrate with `ethminer`, `miner.hashrate` will always report 0. |
||||
|
||||
|
||||
### ethminer and eth |
||||
|
||||
`ethminer` can be used in conjunction with `eth` via rpc |
||||
|
||||
``` |
||||
eth -i -v 8 -j // -j for rpc |
||||
ethminer -G -M // -G for GPU, -M for benchmark |
||||
tail -f geth.log |
||||
``` |
||||
|
||||
or you can use `eth` to GPU mine by itself: |
||||
|
||||
``` |
||||
eth -m on -G -a <coinbase> -i -v 8 // |
||||
``` |
||||
|
||||
# Further Resources: |
||||
|
||||
* [ether-proxy, a web interface for mining rigs](https://github.com/sammy007/ether-proxy) |
||||
(supports solo and pool mining proxy with web interface and rigs availability monitoring) |
||||
* [ethereum forum mining FAQ live update](https://forum.ethereum.org/discussion/197/mining-faq-live-updates) |
||||
* [yates randall mining video](https://www.youtube.com/watch?v=CnKnclkkbKg) |
||||
* https://blog.ethereum.org/2014/07/05/stake/ |
||||
* https://blog.ethereum.org/2014/10/03/slasher-ghost-developments-proof-stake/ |
||||
* https://blog.ethereum.org/2014/06/19/mining/ |
||||
* https://github.com/ethereum/wiki/wiki/Ethash |
||||
* [Benchmarking results for GPU mining](https://forum.ethereum.org/discussion/2134/gpu-mining-is-out-come-and-let-us-know-of-your-bench-scores) |
||||
* [historic moment](https://twitter.com/gavofyork/status/586623875577937922) |
||||
* [live mining statistic](https://ethstats.net/) |
||||
* [netstat ethereum network monitor](https://stats.ethdev.com) |
||||
@ -1,80 +0,0 @@ |
||||
--- |
||||
title: Swarm TODO |
||||
--- |
||||
# Sprint plan |
||||
|
||||
# scope |
||||
- forwarding only (no recursive lookup and no connecting to new nodes, only working with active peers) |
||||
|
||||
## TODO |
||||
|
||||
- integrate new p2p |
||||
- write unit tests for protocol and netstore (without protocol) |
||||
- rework protocol errors using errs after PR merged |
||||
- integrate new p2p or develop branch after p2p merge |
||||
- integrate cademlia into hive / peer pool with new p2p |
||||
- work out timeouts and timeout encoding |
||||
- cli tools |
||||
- url bar and proxy |
||||
|
||||
## CLI |
||||
- hooking into DPA local API |
||||
- running as a daemon accepting request via socket? |
||||
|
||||
### - |
||||
## Encryption |
||||
- encryption gateway to incentivise encryption of public content |
||||
- xor encryption with random chunks |
||||
- in-memory encryption keys |
||||
- originator encryption for private content |
||||
|
||||
|
||||
## APIs |
||||
- DAPP API - js integration (Fabian, Alex) |
||||
- mist dapp storage scheme, url->hash mapping (Fabian, Alex) [URL scheme](../doc/url-scheme) |
||||
|
||||
# Discuss alternatives |
||||
|
||||
I suggest we each pick 2/3 and read up on their project status, features, useability, objectives, etc |
||||
- Is it even worth it to reinvent/reimplement the wheel? |
||||
- what features do we want now and in future |
||||
- roadmap |
||||
|
||||
# Brainstorming |
||||
|
||||
- storage economy, incentivisation, examples: |
||||
-- content owner pays recurring ether fee for storage. |
||||
-- scheme to reward content owner each time content is accessed. i.e accessing content would requires fee. this would reward popular content. should be optional though. |
||||
- dht - chain interaction |
||||
- proof of custody https://docs.google.com/document/d/1F81ulKEZFPIGNEVRsx0H1gl2YRtf0mUMsX011BzSjnY/edit |
||||
- proof of resources http://systemdocs.maidsafe.net/content/system_components/proof_of_resources.html |
||||
- nonoutsourceable proofs of storage as mining criteria |
||||
- proof of storage capacity directly rewarded by contract |
||||
- streaming, hash chains |
||||
- routing and learning graph traversal |
||||
- minimising hops |
||||
- forwarding strategies, optimising dispersion of requests |
||||
- lifetime of requests, renewals (repeated retrieval requests), expiry, reposting (repeated storage request) |
||||
- redundancy - store same data in multiple nodes (e.g 4x) |
||||
- the more accessed a content is, the more available it should be, should increase performance for popular content. |
||||
|
||||
# Simulations |
||||
|
||||
- full table homogeneous nodes network size vs density vs table size expected row-sizes |
||||
- forwarding strategy vs latency vs traffic |
||||
- stable table, dropout rate vs routing optimisation by precalculating subtables for all peers. expected distance change (proximity delta) per hop |
||||
|
||||
|
||||
## Swarm |
||||
|
||||
How far does the analogy go? |
||||
|
||||
swarm of bees | a decentralised network of peers |
||||
-------|------------ |
||||
living in a hive | form a distributed preimage archive |
||||
where they | where they |
||||
gather pollen | gather data chunks which they |
||||
to produce honey | transform into a longer data stream (document) |
||||
they consume and store | they serve and store |
||||
buzzing bzz | using bzz as their communications protocol |
||||
|
||||
@ -1,69 +0,0 @@ |
||||
--- |
||||
title: Swarm - distributed preimage archive |
||||
--- |
||||
# Resources |
||||
|
||||
## Swarm, the name |
||||
- https://www.facebook.com/swarmcorp, http://swarm.fund/ |
||||
- https://bitcointalk.org/index.php?topic=650143.0 |
||||
- https://bitcoinmagazine.com/17956/swarm-1-rick-falkvinges-swarmops-project/ |
||||
- http://www.amazon.co.uk/Swarmwise-Tactical-Manual-Changing-World/dp/1463533152/ |
||||
|
||||
## Docs & specs |
||||
- [Swarm TODO](./swarm-todo) |
||||
- Dani & Viktor on public wiki: https://github.com/ethereum/wiki/wiki/Distributed-Preimage-Archive |
||||
- Dani on swarm hash: https://github.com/ethereum/wiki/wiki/Swarm-Hash |
||||
- Dani on incentive system: https://github.com/ethersphere/swarm/blob/master/doc/incentives.md |
||||
- The swarm smart contract |
||||
- gav on url-hint https://github.com/ethereum/wiki/wiki/URL-Hint-Protocol |
||||
- Gav on public wiki: https://github.com/ethereum/cpp-ethereum/wiki/Swarm |
||||
- network (DEVp2p) |
||||
- [Peer-to-Peer](../developers/peer-to-peer) |
||||
- on kademlia: https://github.com/ethereum/wiki/wiki/Cademlia-Peer-Selection |
||||
|
||||
## Talks |
||||
- https://twitter.com/ethereumproject/status/538030376858693633 |
||||
- Dr. Daniel Nagy: Ethereum ÐΞVcon-0: Keeping the Public Record Safe and Accessible - https://www.youtube.com/watch?v=QzYZQ03ON2o&list=PLJqWcTqh_zKEjpSej3ddtDOKPRGl_7MhS&index=7&spfreload=10 |
||||
|
||||
## Forum |
||||
- empty as of 01/2015: https://forum.ethereum.org/categories/swarm |
||||
- |
||||
|
||||
## Mentions, discussions |
||||
- http://www.reddit.com/r/ethereum/comments/2d4uyw/swarm_and_whisper/ |
||||
- http://www.reddit.com/r/ethereum/comments/2ityfz/ethereum_swarm/ |
||||
- https://www.maidsafe.org/t/ethereums-swarm-p2p-storage-and-whisper-p2p-messaging/1528 |
||||
- Vitalik's blogpost of 08/2014 - https://blog.ethereum.org/2014/08/16/secret-sharing-erasure-coding-guide-aspiring-dropbox-decentralizer/ |
||||
- Vitalik: 'Swarm is out-of-scope': https://www.reddit.com/r/ethereum/comments/2phvml/constructive_criticism_of_ethereum_project_not/cmwtfqq |
||||
- Vitalik on eth components, swarm at 4:00 http://www.naation.com/2015/02/02/ethereum-explained-with-vitalik-buterin-inventor-and-leader-of-the-ethereum-project/5764/ |
||||
- https://www.youtube.com/watch?v=zgkmQ-jQJHk&feature=youtu.be |
||||
|
||||
## Media |
||||
- https://twitter.com/jeffehh/status/565927366271467521 |
||||
- https://twitter.com/avsa/status/566255260713627648 |
||||
- https://twitter.com/zeligf/status/566042020909973504 |
||||
- https://www.reddit.com/r/ethereum/comments/2wryru/eli5_how_is_ethereum_supposed_to_be_a_dropbox |
||||
- https://forum.ethereum.org/discussion/comment/7593/#Comment_7593 |
||||
|
||||
## Code |
||||
- bzz PR: https://github.com/ethereum/go-ethereum/pull/255, |
||||
- repo https://github.com/ethersphere/go-ethereum/tree/bzz/ |
||||
- ethereum p2p: https://github.com/ethereum/go-ethereum/p2p |
||||
- peer selection, peer pool: https://github.com/ethereum/go-ethereum/pull/253 |
||||
- p2p cademlia branch (discontinued): https://github.com/ethersphere/go-ethereum/tree/kademlia |
||||
- Felix's node discovery code: https://github.com/ethereum/go-ethereum/tree/develop/p2p/discover |
||||
|
||||
# Alternatives |
||||
|
||||
- storj - http://storj.io/ |
||||
- maidsafe - http://maidsafe.net/ |
||||
- ipfs - http://ipfs.io/, https://www.youtube.com/watch?v=Fa4pckodM9g, http://static.benet.ai/t/ipfs.pdf, https://github.com/jbenet/go-ipfs, https://www.youtube.com/watch?v=8CMxDNuuAiQ, https://www.reddit.com/r/ethereum/comments/2wot2i/ipfs_alpha_demo/ |
||||
- filecoin - http://filecoin.io/ |
||||
- permacoin - https://www.cs.umd.edu/~elaine/docs/permacoin.pdf, https://bitcointalk.org/index.php?topic=640410.0, http://blog.dshr.org/2014/06/permacoin.html |
||||
- siacoin - http://www.siacoin.com/ |
||||
- riak - http://basho.com/riak/ |
||||
- BitTorrent http://www.bittorrent.com/ maelstrom http://blog.bittorrent.com/2014/12/10/project-maelstrom-the-internet-we-build-next/ |
||||
- Tahoe-LAFS https://www.tahoe-lafs.org/trac/tahoe-lafs |
||||
- retroshare http://retroshare.sourceforge.net/ |
||||
|
||||
|
||||
@ -1,105 +0,0 @@ |
||||
--- |
||||
title: Geth |
||||
--- |
||||
`geth` is the the command line interface for running a full ethereum node implemented in Go. |
||||
It is the main deliverable of the [Frontier Release](https://ethereum.gitbooks.io/frontier-guide/content/frontier.html) |
||||
|
||||
## Capabilities |
||||
|
||||
By installing and running `geth`, you can take part in the ethereum frontier live network and |
||||
* mine real ether |
||||
* transfer funds between addresses |
||||
* create contracts and send transactions |
||||
* explore block history |
||||
* and much much more |
||||
|
||||
## Install |
||||
|
||||
Supported Platforms are Linux, Mac Os and Windows. |
||||
|
||||
We support two types of installation: binary or scripted install for users. |
||||
See [Install instructions](../install-and-build/build-from-source) for binary and scripted installs. |
||||
|
||||
Developers and community enthusiast are advised to read the [Developers' Guide](../install-and-build/developers-guide), which contains detailed instructions for manual build from source (on any platform) as well as detailed tips on testing, monitoring, contributing, debugging and submitting pull requests on github. |
||||
|
||||
## Interfaces |
||||
|
||||
* Javascript Console: `geth` can be launched with an interactive console, that provides a javascript runtime environment exposing a javascript API to interact with your node. [Javascript Console API](../interface/javascript-console) includes the `web3` javascript Ðapp API as well as an additional admin API. |
||||
* JSON-RPC server: `geth` can be launched with a server that exposes the [JSON-RPC API](https://github.com/ethereum/wiki/wiki/JSON-RPC) |
||||
* [Command line options](../interface/command-line-options) documents command line parameters as well as subcommands. |
||||
|
||||
## Basic Use Case Documentation |
||||
|
||||
* [Managing accounts](../interface/managing-your-accounts) |
||||
* [Mining](../legacy/mining) |
||||
|
||||
**Note** buying and selling ether through exchanges is not discussed here. |
||||
|
||||
## License |
||||
|
||||
The Ethereum Core Protocol licensed under the [GNU Lesser General Public License](https://www.gnu.org/licenses/lgpl.html). All frontend client software (under [cmd](https://github.com/ethereum/go-ethereum/tree/master/cmd)) is licensed under the [GNU General Public License](https://www.gnu.org/copyleft/gpl.html). |
||||
|
||||
## Reporting |
||||
|
||||
Security issues are best sent to security@ethereum.org or shared in PM with devs on one of the channels (see Community and Suppport). |
||||
|
||||
Non-sensitive bug reports are welcome on github. Please always state the version (on master) or commit of your build (if on develop), give as much detail as possible about the situation and the anomaly that occurred. Provide logs or stacktrace if you can. |
||||
|
||||
## Contributors |
||||
|
||||
Ethereum is joint work of ETHDEV and the community. |
||||
|
||||
Name or blame = list of contributors: |
||||
* [go-ethereum](https://github.com/ethereum/go-ethereum/graphs/contributors) |
||||
* [cpp-ethereum](https://github.com/ethereum/cpp-ethereum/graphs/contributors) |
||||
* [web3.js](https://github.com/ethereum/web3.js/graphs/contributors) |
||||
* [ethash](https://github.com/ethereum/ethash/graphs/contributors) |
||||
* [netstats](https://github.com/cubedro/eth-netstats/graphs/contributors), |
||||
[netintelligence-api](https://github.com/cubedro/eth-net-intelligence-api/graphs/contributors) |
||||
|
||||
## Community and support |
||||
|
||||
### Ethereum on social media |
||||
|
||||
- Main site: https://www.ethereum.org |
||||
- Forum: https://forum.ethereum.org |
||||
- Github: https://github.com/ethereum |
||||
- Blog: https://blog.ethereum.org |
||||
- Wiki: http://wiki.ethereum.org |
||||
- Twitter: http://twitter.com/ethereumproject |
||||
- Reddit: http://reddit.com/r/ethereum |
||||
- Meetups: http://ethereum.meetup.com |
||||
- Facebook: https://www.facebook.com/ethereumproject |
||||
- Youtube: http://www.youtube.com/ethereumproject |
||||
- Google+: http://google.com/+EthereumOrgOfficial |
||||
|
||||
### IRC |
||||
|
||||
IRC Freenode channels: |
||||
* `#ethereum`: for general discussion |
||||
* `#ethereum-dev`: for development specific questions and discussions |
||||
* `##ethereum`: for offtopic and banter |
||||
* `#ethereumjs`: for questions related to web3.js and node-ethereum |
||||
* `#ethereum-markets`: Trading |
||||
* `#ethereum-mining` Mining |
||||
* `#dappdevs`: Dapp developers channel |
||||
* `#ethdev`: buildserver etc |
||||
|
||||
### Gitter |
||||
|
||||
* [go-ethereum Gitter](https://gitter.im/ethereum/go-ethereum) |
||||
* [cpp-ethereum Gitter](https://gitter.im/ethereum/cpp-ethereum) |
||||
* [web3.js Gitter](https://gitter.im/ethereum/web3.js) |
||||
* [ethereum documentation project Gitter](https://gitter.im/ethereum/frontier-guide) |
||||
|
||||
### Forum |
||||
|
||||
- [Forum](https://forum.ethereum.org/categories/geth) |
||||
|
||||
### Dapp developers' mailing list |
||||
|
||||
https://dapplist.net/ |
||||
|
||||
### Helpdesk |
||||
|
||||
On gitter, irc, skype or mail to helpdesk@ethereum.org |
||||
@ -1,145 +0,0 @@ |
||||
--- |
||||
title: eth_call |
||||
--- |
||||
|
||||
Executes a new message call immediately, without creating a transaction on the block chain. The `eth_call` method can be used to query internal contract state, to execute validations coded into a contract or even to test what the effect of a transaction would be without running it live. |
||||
|
||||
## Parameters |
||||
|
||||
The method takes 3 parameters: an unsigned transaction object to execute in read-only mode; the block number to execute the call against; and an optional state override-set to allow executing the call against a modified chain state. |
||||
|
||||
#### 1. `Object` - Transaction call object |
||||
|
||||
The *transaction call object* is mandatory and contains all the necessary parameters to execute a read-only EVM contract method. |
||||
|
||||
| Field | Type | Bytes | Optional | Description | |
||||
|:---:|:---:|:---:|:---:|:---| |
||||
| `from` | `Address` | 20 | Yes | Address the transaction is simulated to have been sent from. Defaults to first account in the local keystore or the `0x00..0` address if no local accounts are available. | |
||||
| `to` | `Address` | 20 | No | Address the transaction is sent to. | |
||||
| `gas` | `Quantity` | <8 | Yes | Maximum gas allowance for the code execution to avoid infinite loops. Defaults to `2^63` or whatever value the node operator specified via `--rpc.gascap`. | |
||||
| `gasPrice` | `Quantity` | <32 | Yes | Number of `wei` to simulate paying for each unit of gas during execution. Defaults to `1 gwei`. | |
||||
| `value` | `Quantity` | <32 | Yes | Amount of `wei` to simulate sending along with the transaction. Defaults to `0`. | |
||||
| `data` | `Binary` | any | Yes | Binary data to send to the target contract. Generally the 4 byte hash of the method signature followed by the ABI encoded parameters. For details please see the [Ethereum Contract ABI](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI). | |
||||
|
||||
Example: |
||||
|
||||
```json |
||||
{ |
||||
"from": "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3", |
||||
"to": "0xebe8efa441b9302a0d7eaecc277c09d20d684540", |
||||
"gas": "0x1bd7c", |
||||
"data": "0xd459fc46000000000000000000000000000000000000000000000000000000000046c650dbb5e8cb2bac4d2ed0b1e6475d37361157738801c494ca482f96527eb48f9eec488c2eba92d31baeccfb6968fad5c21a3df93181b43b4cf253b4d572b64172ef000000000000000000000000000000000000000000000000000000000000008c00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000002b85c0c828d7a98633b4e1b65eac0c017502da909420aeade9a280675013df36bdc71cffdf420cef3d24ba4b3f9b980bfbb26bd5e2dcf7795b3519a3fd22ffbb2000000000000000000000000000000000000000000000000000000000000000238fb6606dc2b5e42d00c653372c153da8560de77bd9afaba94b4ab6e4aa11d565d858c761320dbf23a94018d843772349bd9d92301b0ca9ca983a22d86a70628", |
||||
} |
||||
``` |
||||
|
||||
#### 2. `Quantity | Tag` - Block number or the string `latest` or `pending` |
||||
|
||||
The *block number* is mandatory and defines the context (state) against which the specified transaction should be executed. It is not possible to execute calls against reorged blocks; or blocks older than 128 (unless the node is an archive node). |
||||
|
||||
#### 3. `Object` - State override set |
||||
|
||||
The *state override set* is an optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call. Each address maps to an object containing: |
||||
|
||||
| Field | Type | Bytes | Optional | Description | |
||||
|:---:|:---:|:---:|:---:|:---| |
||||
| `balance` | `Quantity` | <32 | Yes | Fake balance to set for the account before executing the call. | |
||||
| `nonce` | `Quantity` | <8 | Yes | Fake nonce to set for the account before executing the call. | |
||||
| `code` | `Binary` | any | Yes | Fake EVM bytecode to inject into the account before executing the call. | |
||||
| `state` | `Object` | any | Yes | Fake key-value mapping to override **all** slots in the account storage before executing the call. | |
||||
| `stateDiff` | `Object` | any | Yes | Fake key-value mapping to override **individual** slots in the account storage before executing the call. | |
||||
|
||||
The goal of the *state override set* is manyfold: |
||||
|
||||
* It can be used by DApps to reduce the amount of contract code needed to be deployed on chain. Code that simply returns internal state or does pre-defined validations can be kept off chain and fed to the node on-demand. |
||||
* It can be used for smart contract analysis by extending the code deployed on chain with custom methods and invoking them. This avoids having to download and reconstruct the entire state in a sandbox to run custom code against. |
||||
* It can be used to debug smart contracts in an already deployed large suite of contracts by selectively overriding some code or state and seeing how execution changes. Specialized tooling will probably be necessary. |
||||
|
||||
Example: |
||||
|
||||
```json |
||||
{ |
||||
"0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3": { |
||||
"balance": "0xde0b6b3a7640000" |
||||
}, |
||||
"0xebe8efa441b9302a0d7eaecc277c09d20d684540": { |
||||
"code": "0x...", |
||||
"state": { |
||||
"" |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
## Returns |
||||
|
||||
The method returns a single `Binary` consisting the return value of the executed contract call. |
||||
|
||||
## Simple example |
||||
|
||||
With a synced Rinkeby node with RPC exposed on localhost (`geth --rinkeby --rpc`) we can make a call against the [Checkpoint Oracle](https://rinkeby.etherscan.io/address/0xebe8efa441b9302a0d7eaecc277c09d20d684540) to retrieve the list of administrators: |
||||
|
||||
``` |
||||
$ curl --data '{"method":"eth_call","params":[{"to":"0xebe8efa441b9302a0d7eaecc277c09d20d684540","data":"0x45848dfc"},"latest"],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545 |
||||
``` |
||||
|
||||
And the result is an Ethereum ABI encoded list of accounts: |
||||
|
||||
```json |
||||
{ |
||||
"id": 1, |
||||
"jsonrpc": "2.0", |
||||
"result": "0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000004000000000000000000000000d9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f300000000000000000000000078d1ad571a1a09d60d9bbf25894b44e4c8859595000000000000000000000000286834935f4a8cfb4ff4c77d5770c2775ae2b0e7000000000000000000000000b86e2b0ab5a4b1373e40c51a7c712c70ba2f9f8e" |
||||
} |
||||
``` |
||||
|
||||
Just for the sake of completeness, decoded the response is: |
||||
|
||||
``` |
||||
0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3, |
||||
0x78d1ad571a1a09d60d9bbf25894b44e4c8859595, |
||||
0x286834935f4a8cfb4ff4c77d5770c2775ae2b0e7, |
||||
0xb86e2b0ab5a4b1373e40c51a7c712c70ba2f9f8e |
||||
``` |
||||
|
||||
## Override example |
||||
|
||||
The above *simple example* showed how to call a method already exposed by an on-chain smart contract. What if we want to access some data not exposed by it? |
||||
|
||||
We can gut out the [original](https://github.com/ethereum/go-ethereum/blob/master/contracts/checkpointoracle/contract/oracle.sol) checkpoint oracle contract with one that retains the same fields (to retain the same storage layout), but one that includes a different method set: |
||||
|
||||
``` |
||||
pragma solidity ^0.5.10; |
||||
|
||||
contract CheckpointOracle { |
||||
mapping(address => bool) admins; |
||||
address[] adminList; |
||||
uint64 sectionIndex; |
||||
uint height; |
||||
bytes32 hash; |
||||
uint sectionSize; |
||||
uint processConfirms; |
||||
uint threshold; |
||||
|
||||
function VotingThreshold() public view returns (uint) { |
||||
return threshold; |
||||
} |
||||
} |
||||
``` |
||||
|
||||
With a synced Rinkeby node with RPC exposed on localhost (`geth --rinkeby --rpc`) we can make a call against the live [Checkpoint Oracle](https://rinkeby.etherscan.io/address/0xebe8efa441b9302a0d7eaecc277c09d20d684540), but override its byte code with our own version that has an accessor for the voting threshold field: |
||||
|
||||
``` |
||||
$ curl --data '{"method":"eth_call","params":[{"to":"0xebe8efa441b9302a0d7eaecc277c09d20d684540","data":"0x0be5b6ba"}, "latest", {"0xebe8efa441b9302a0d7eaecc277c09d20d684540": {"code":"0x6080604052348015600f57600080fd5b506004361060285760003560e01c80630be5b6ba14602d575b600080fd5b60336045565b60408051918252519081900360200190f35b6007549056fea265627a7a723058206f26bd0433456354d8d1228d8fe524678a8aeeb0594851395bdbd35efc2a65f164736f6c634300050a0032"}}],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545 |
||||
``` |
||||
|
||||
And the result is the Ethereum ABI encoded threshold number: |
||||
|
||||
```json |
||||
{ |
||||
"id": 1, |
||||
"jsonrpc": "2.0", |
||||
"result": "0x0000000000000000000000000000000000000000000000000000000000000002" |
||||
} |
||||
``` |
||||
|
||||
Just for the sake of completeness, decoded the response is: `2`. |
||||
@ -0,0 +1,226 @@ |
||||
--- |
||||
title: admin Namespace |
||||
sort_key: C |
||||
--- |
||||
|
||||
The `admin` API gives you access to several non-standard RPC methods, which will allow you to have |
||||
a fine grained control over your Geth instance, including but not limited to network peer and RPC |
||||
endpoint management. |
||||
|
||||
* TOC |
||||
{:toc} |
||||
|
||||
### admin_addPeer |
||||
|
||||
The `addPeer` administrative method requests adding a new remote node to the list of tracked static |
||||
nodes. The node will try to maintain connectivity to these nodes at all times, reconnecting every |
||||
once in a while if the remote connection goes down. |
||||
|
||||
The method accepts a single argument, the [`enode`](https://github.com/ethereum/wiki/wiki/enode-url-format) |
||||
URL of the remote peer to start tracking and returns a `BOOL` indicating whether the peer was accepted |
||||
for tracking or some error occurred. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|------------------------------------------------| |
||||
| Go | `admin.AddPeer(url string) (bool, error)` | |
||||
| Console | `admin.addPeer(url)` | |
||||
| RPC | `{"method": "admin_addPeer", "params": [url]}` | |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> admin.addPeer("enode://a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c@52.16.188.185:30303") |
||||
true |
||||
``` |
||||
|
||||
### admin_datadir |
||||
|
||||
The `datadir` administrative property can be queried for the absolute path the running Geth node |
||||
currently uses to store all its databases. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-----------------------------------| |
||||
| Go | `admin.Datadir() (string, error`) | |
||||
| Console | `admin.datadir` | |
||||
| RPC | `{"method": "admin_datadir"}` | |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> admin.datadir |
||||
"/home/john/.ethereum" |
||||
``` |
||||
|
||||
### admin_nodeInfo |
||||
|
||||
The `nodeInfo` administrative property can be queried for all the information known about the running |
||||
Geth node at the networking granularity. These include general information about the node itself as a |
||||
participant of the [ÐΞVp2p](https://github.com/ethereum/wiki/wiki/%C3%90%CE%9EVp2p-Wire-Protocol) P2P |
||||
overlay protocol, as well as specialized information added by each of the running application protocols |
||||
(e.g. `eth`, `les`, `shh`, `bzz`). |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-------------------------------------------| |
||||
| Go | `admin.NodeInfo() (*p2p.NodeInfo, error`) | |
||||
| Console | `admin.nodeInfo` | |
||||
| RPC | `{"method": "admin_nodeInfo"}` | |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> admin.nodeInfo |
||||
{ |
||||
enode: "enode://44826a5d6a55f88a18298bca4773fca5749cdc3a5c9f308aa7d810e9b31123f3e7c5fba0b1d70aac5308426f47df2a128a6747040a3815cc7dd7167d03be320d@[::]:30303", |
||||
id: "44826a5d6a55f88a18298bca4773fca5749cdc3a5c9f308aa7d810e9b31123f3e7c5fba0b1d70aac5308426f47df2a128a6747040a3815cc7dd7167d03be320d", |
||||
ip: "::", |
||||
listenAddr: "[::]:30303", |
||||
name: "Geth/v1.5.0-unstable/linux/go1.6", |
||||
ports: { |
||||
discovery: 30303, |
||||
listener: 30303 |
||||
}, |
||||
protocols: { |
||||
eth: { |
||||
difficulty: 17334254859343145000, |
||||
genesis: "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3", |
||||
head: "0xb83f73fbe6220c111136aefd27b160bf4a34085c65ba89f24246b3162257c36a", |
||||
network: 1 |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
### admin_peers |
||||
|
||||
The `peers` administrative property can be queried for all the information known about the connected |
||||
remote nodes at the networking granularity. These include general information about the nodes themselves |
||||
as participants of the [ÐΞVp2p](https://github.com/ethereum/wiki/wiki/%C3%90%CE%9EVp2p-Wire-Protocol) |
||||
P2P overlay protocol, as well as specialized information added by each of the running application |
||||
protocols (e.g. `eth`, `les`, `shh`, `bzz`). |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|------------------------------------------| |
||||
| Go | `admin.Peers() ([]*p2p.PeerInfo, error`) | |
||||
| Console | `admin.peers` | |
||||
| RPC | `{"method": "admin_peers"}` | |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> admin.peers |
||||
[{ |
||||
caps: ["eth/61", "eth/62", "eth/63"], |
||||
id: "08a6b39263470c78d3e4f58e3c997cd2e7af623afce64656cfc56480babcea7a9138f3d09d7b9879344c2d2e457679e3655d4b56eaff5fd4fd7f147bdb045124", |
||||
name: "Geth/v1.5.0-unstable/linux/go1.5.1", |
||||
network: { |
||||
localAddress: "192.168.0.104:51068", |
||||
remoteAddress: "71.62.31.72:30303" |
||||
}, |
||||
protocols: { |
||||
eth: { |
||||
difficulty: 17334052235346465000, |
||||
head: "5794b768dae6c6ee5366e6ca7662bdff2882576e09609bf778633e470e0e7852", |
||||
version: 63 |
||||
} |
||||
} |
||||
}, /* ... */ { |
||||
caps: ["eth/61", "eth/62", "eth/63"], |
||||
id: "fcad9f6d3faf89a0908a11ddae9d4be3a1039108263b06c96171eb3b0f3ba85a7095a03bb65198c35a04829032d198759edfca9b63a8b69dc47a205d94fce7cc", |
||||
name: "Geth/v1.3.5-506c9277/linux/go1.4.2", |
||||
network: { |
||||
localAddress: "192.168.0.104:55968", |
||||
remoteAddress: "121.196.232.205:30303" |
||||
}, |
||||
protocols: { |
||||
eth: { |
||||
difficulty: 17335165914080772000, |
||||
head: "5794b768dae6c6ee5366e6ca7662bdff2882576e09609bf778633e470e0e7852", |
||||
version: 63 |
||||
} |
||||
} |
||||
}] |
||||
``` |
||||
|
||||
### admin_startRPC |
||||
|
||||
The `startRPC` administrative method starts an HTTP based [JSON RPC](http://www.jsonrpc.org/specification) |
||||
API webserver to handle client requests. All the parameters are optional: |
||||
|
||||
* `host`: network interface to open the listener socket on (defaults to `"localhost"`) |
||||
* `port`: network port to open the listener socket on (defaults to `8545`) |
||||
* `cors`: [cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) header to use (defaults to `""`) |
||||
* `apis`: API modules to offer over this interface (defaults to `"eth,net,web3"`) |
||||
|
||||
The method returns a boolean flag specifying whether the HTTP RPC listener was opened or not. Please note, only one HTTP endpoint is allowed to be active at any time. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-----------------------------------------------------------------------------------------------| |
||||
| Go | `admin.StartRPC(host *string, port *rpc.HexNumber, cors *string, apis *string) (bool, error)` | |
||||
| Console | `admin.startRPC(host, port, cors, apis)` | |
||||
| RPC | `{"method": "admin_startRPC", "params": [host, port, cors, apis]}` | |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> admin.startRPC("127.0.0.1", 8545) |
||||
true |
||||
``` |
||||
|
||||
### admin_startWS |
||||
|
||||
The `startWS` administrative method starts an WebSocket based [JSON RPC](http://www.jsonrpc.org/specification) |
||||
API webserver to handle client requests. All the parameters are optional: |
||||
|
||||
* `host`: network interface to open the listener socket on (defaults to `"localhost"`) |
||||
* `port`: network port to open the listener socket on (defaults to `8546`) |
||||
* `cors`: [cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) header to use (defaults to `""`) |
||||
* `apis`: API modules to offer over this interface (defaults to `"eth,net,web3"`) |
||||
|
||||
The method returns a boolean flag specifying whether the WebSocket RPC listener was opened or not. Please note, only one WebSocket endpoint is allowed to be active at any time. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-----------------------------------------------------------------------------------------------| |
||||
| Go | `admin.StartWS(host *string, port *rpc.HexNumber, cors *string, apis *string) (bool, error)` | |
||||
| Console | `admin.startWS(host, port, cors, apis)` | |
||||
| RPC | `{"method": "admin_startWS", "params": [host, port, cors, apis]}` | |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> admin.startWS("127.0.0.1", 8546) |
||||
true |
||||
``` |
||||
|
||||
### admin_stopRPC |
||||
|
||||
The `stopRPC` administrative method closes the currently open HTTP RPC endpoint. As the node can only have a single HTTP endpoint running, this method takes no parameters, returning a boolean whether the endpoint was closed or not. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|---------------------------------| |
||||
| Go | `admin.StopRPC() (bool, error`) | |
||||
| Console | `admin.stopRPC()` | |
||||
| RPC | `{"method": "admin_stopRPC"` | |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> admin.stopRPC() |
||||
true |
||||
``` |
||||
|
||||
### admin_stopWS |
||||
|
||||
The `stopWS` administrative method closes the currently open WebSocket RPC endpoint. As the node can only have a single WebSocket endpoint running, this method takes no parameters, returning a boolean whether the endpoint was closed or not. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|--------------------------------| |
||||
| Go | `admin.StopWS() (bool, error`) | |
||||
| Console | `admin.stopWS()` | |
||||
| RPC | `{"method": "admin_stopWS"` | |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> admin.stopWS() |
||||
true |
||||
``` |
||||
@ -0,0 +1,564 @@ |
||||
--- |
||||
title: debug Namespace |
||||
sort_key: C |
||||
--- |
||||
|
||||
The `debug` API gives you access to several non-standard RPC methods, which will allow you |
||||
to inspect, debug and set certain debugging flags during runtime. |
||||
|
||||
* TOC |
||||
{:toc} |
||||
|
||||
### debug_backtraceAt |
||||
|
||||
Sets the logging backtrace location. When a backtrace location |
||||
is set and a log message is emitted at that location, the stack |
||||
of the goroutine executing the log statement will be printed to stderr. |
||||
|
||||
The location is specified as `<filename>:<line>`. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-------------------------------------------------------| |
||||
| Console | `debug.backtraceAt(string)` | |
||||
| RPC | `{"method": "debug_backtraceAt", "params": [string]}` | |
||||
|
||||
Example: |
||||
|
||||
``` javascript |
||||
> debug.backtraceAt("server.go:443") |
||||
``` |
||||
|
||||
### debug_blockProfile |
||||
|
||||
Turns on block profiling for the given duration and writes |
||||
profile data to disk. It uses a profile rate of 1 for most |
||||
accurate information. If a different rate is desired, set |
||||
the rate and write the profile manually using |
||||
`debug_writeBlockProfile`. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|----------------------------------------------------------------| |
||||
| Console | `debug.blockProfile(file, seconds)` | |
||||
| RPC | `{"method": "debug_blockProfile", "params": [string, number]}` | |
||||
|
||||
### debug_cpuProfile |
||||
|
||||
Turns on CPU profiling for the given duration and writes |
||||
profile data to disk. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|--------------------------------------------------------------| |
||||
| Console | `debug.cpuProfile(file, seconds)` | |
||||
| RPC | `{"method": "debug_cpuProfile", "params": [string, number]}` | |
||||
|
||||
### debug_dumpBlock |
||||
|
||||
Retrieves the state that corresponds to the block number and returns a list of accounts (including |
||||
storage and code). |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-------------------------------------------------------| |
||||
| Go | `debug.DumpBlock(number uint64) (state.World, error)` | |
||||
| Console | `debug.traceBlockByHash(number, [options])` | |
||||
| RPC | `{"method": "debug_dumpBlock", "params": [number]}` | |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> debug.dumpBlock(10) |
||||
{ |
||||
fff7ac99c8e4feb60c9750054bdc14ce1857f181: { |
||||
balance: "49358640978154672", |
||||
code: "", |
||||
codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", |
||||
nonce: 2, |
||||
root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", |
||||
storage: {} |
||||
}, |
||||
fffbca3a38c3c5fcb3adbb8e63c04c3e629aafce: { |
||||
balance: "3460945928", |
||||
code: "", |
||||
codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", |
||||
nonce: 657, |
||||
root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", |
||||
storage: {} |
||||
} |
||||
}, |
||||
root: "19f4ed94e188dd9c7eb04226bd240fa6b449401a6c656d6d2816a87ccaf206f1" |
||||
} |
||||
``` |
||||
|
||||
### debug_gcStats |
||||
|
||||
Returns GC statistics. |
||||
|
||||
See https://golang.org/pkg/runtime/debug/#GCStats for information about |
||||
the fields of the returned object. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|---------------------------------------------------| |
||||
| Console | `debug.gcStats()` | |
||||
| RPC | `{"method": "debug_gcStats", "params": []}` | |
||||
|
||||
### debug_getBlockRlp |
||||
|
||||
Retrieves and returns the RLP encoded block by number. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-------------------------------------------------------| |
||||
| Go | `debug.GetBlockRlp(number uint64) (string, error)` | |
||||
| Console | `debug.getBlockRlp(number, [options])` | |
||||
| RPC | `{"method": "debug_getBlockRlp", "params": [number]}` | |
||||
|
||||
References: [RLP](https://github.com/ethereum/wiki/wiki/RLP) |
||||
|
||||
### debug_goTrace |
||||
|
||||
Turns on Go runtime tracing for the given duration and writes |
||||
trace data to disk. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-----------------------------------------------------------| |
||||
| Console | `debug.goTrace(file, seconds)` | |
||||
| RPC | `{"method": "debug_goTrace", "params": [string, number]}` | |
||||
|
||||
### debug_memStats |
||||
|
||||
Returns detailed runtime memory statistics. |
||||
|
||||
See https://golang.org/pkg/runtime/#MemStats for information about |
||||
the fields of the returned object. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|---------------------------------------------------| |
||||
| Console | `debug.memStats()` | |
||||
| RPC | `{"method": "debug_memStats", "params": []}` | |
||||
|
||||
### debug_seedHash |
||||
|
||||
Fetches and retrieves the seed hash of the block by number |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|----------------------------------------------------| |
||||
| Go | `debug.SeedHash(number uint64) (string, error)` | |
||||
| Console | `debug.seedHash(number, [options])` | |
||||
| RPC | `{"method": "debug_seedHash", "params": [number]}` | |
||||
|
||||
### debug_setHead |
||||
|
||||
Sets the current head of the local chain by block number. **Note**, this is a |
||||
destructive action and may severely damage your chain. Use with *extreme* caution. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|---------------------------------------------------| |
||||
| Go | `debug.SetHead(number uint64)` | |
||||
| Console | `debug.setHead(number)` | |
||||
| RPC | `{"method": "debug_setHead", "params": [number]}` | |
||||
|
||||
References: |
||||
[Ethash](https://github.com/ethereum/wiki/wiki/Mining#the-algorithm) |
||||
|
||||
### debug_setBlockProfileRate |
||||
|
||||
Sets the rate (in samples/sec) of goroutine block profile |
||||
data collection. A non-zero rate enables block profiling, |
||||
setting it to zero stops the profile. Collected profile data |
||||
can be written using `debug_writeBlockProfile`. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|---------------------------------------------------------------| |
||||
| Console | `debug.setBlockProfileRate(rate)` | |
||||
| RPC | `{"method": "debug_setBlockProfileRate", "params": [number]}` | |
||||
|
||||
### debug_stacks |
||||
|
||||
Returns a printed representation of the stacks of all goroutines. |
||||
Note that the web3 wrapper for this method takes care of the printing |
||||
and does not return the string. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|---------------------------------------------------| |
||||
| Console | `debug.stacks()` | |
||||
| RPC | `{"method": "debug_stacks", "params": []}` | |
||||
|
||||
### debug_startCPUProfile |
||||
|
||||
Turns on CPU profiling indefinitely, writing to the given file. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-----------------------------------------------------------| |
||||
| Console | `debug.startCPUProfile(file)` | |
||||
| RPC | `{"method": "debug_startCPUProfile", "params": [string]}` | |
||||
|
||||
### debug_startGoTrace |
||||
|
||||
Starts writing a Go runtime trace to the given file. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|--------------------------------------------------------| |
||||
| Console | `debug.startGoTrace(file)` | |
||||
| RPC | `{"method": "debug_startGoTrace", "params": [string]}` | |
||||
|
||||
### debug_stopCPUProfile |
||||
|
||||
Stops an ongoing CPU profile. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|----------------------------------------------------| |
||||
| Console | `debug.stopCPUProfile()` | |
||||
| RPC | `{"method": "debug_stopCPUProfile", "params": []}` | |
||||
|
||||
### debug_stopGoTrace |
||||
|
||||
Stops writing the Go runtime trace. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|---------------------------------------------------| |
||||
| Console | `debug.startGoTrace(file)` | |
||||
| RPC | `{"method": "debug_stopGoTrace", "params": []}` | |
||||
|
||||
### debug_traceBlock |
||||
|
||||
The `traceBlock` method will return a full stack trace of all invoked opcodes of all transaction |
||||
that were included included in this block. **Note**, the parent of this block must be present or |
||||
it will fail. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|--------------------------------------------------------------------------| |
||||
| Go | `debug.TraceBlock(blockRlp []byte, config. *vm.Config) BlockTraceResult` | |
||||
| Console | `debug.traceBlock(tblockRlp, [options])` | |
||||
| RPC | `{"method": "debug_traceBlock", "params": [blockRlp, {}]}` | |
||||
|
||||
References: |
||||
[RLP](https://github.com/ethereum/wiki/wiki/RLP) |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> debug.traceBlock("0xblock_rlp") |
||||
{ |
||||
gas: 85301, |
||||
returnValue: "", |
||||
structLogs: [{ |
||||
depth: 1, |
||||
error: "", |
||||
gas: 162106, |
||||
gasCost: 3, |
||||
memory: null, |
||||
op: "PUSH1", |
||||
pc: 0, |
||||
stack: [], |
||||
storage: {} |
||||
}, |
||||
/* snip */ |
||||
{ |
||||
depth: 1, |
||||
error: "", |
||||
gas: 100000, |
||||
gasCost: 0, |
||||
memory: ["0000000000000000000000000000000000000000000000000000000000000006", "0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000060"], |
||||
op: "STOP", |
||||
pc: 120, |
||||
stack: ["00000000000000000000000000000000000000000000000000000000d67cbec9"], |
||||
storage: { |
||||
0000000000000000000000000000000000000000000000000000000000000004: "8241fa522772837f0d05511f20caa6da1d5a3209000000000000000400000001", |
||||
0000000000000000000000000000000000000000000000000000000000000006: "0000000000000000000000000000000000000000000000000000000000000001", |
||||
f652222313e28459528d920b65115c16c04f3efc82aaedc97be59f3f377c0d3f: "00000000000000000000000002e816afc1b5c0f39852131959d946eb3b07b5ad" |
||||
} |
||||
}] |
||||
``` |
||||
|
||||
### debug_traceBlockByNumber |
||||
|
||||
Similar to [debug_traceBlock](#debug_traceblock), `traceBlockByNumber` accepts a block number and will replay the |
||||
block that is already present in the database. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|--------------------------------------------------------------------------------| |
||||
| Go | `debug.TraceBlockByNumber(number uint64, config. *vm.Config) BlockTraceResult` | |
||||
| Console | `debug.traceBlockByNumber(number, [options])` | |
||||
| RPC | `{"method": "debug_traceBlockByNumber", "params": [number, {}]}` | |
||||
|
||||
References: |
||||
[RLP](https://github.com/ethereum/wiki/wiki/RLP) |
||||
|
||||
### debug_traceBlockByHash |
||||
|
||||
Similar to [debug_traceBlock](#debug_traceblock), `traceBlockByHash` accepts a block hash and will replay the |
||||
block that is already present in the database. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|---------------------------------------------------------------------------------| |
||||
| Go | `debug.TraceBlockByHash(hash common.Hash, config. *vm.Config) BlockTraceResult` | |
||||
| Console | `debug.traceBlockByHash(hash, [options])` | |
||||
| RPC | `{"method": "debug_traceBlockByHash", "params": [hash {}]}` | |
||||
|
||||
References: |
||||
[RLP](https://github.com/ethereum/wiki/wiki/RLP) |
||||
|
||||
### debug_traceBlockFromFile |
||||
|
||||
Similar to [debug_traceBlock](#debug_traceblock), `traceBlockFromFile` accepts a file containing the RLP of the block. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|----------------------------------------------------------------------------------| |
||||
| Go | `debug.TraceBlockFromFile(fileName string, config. *vm.Config) BlockTraceResult` | |
||||
| Console | `debug.traceBlockFromFile(fileName, [options])` | |
||||
| RPC | `{"method": "debug_traceBlockFromFile", "params": [fileName, {}]}` | |
||||
|
||||
References: |
||||
[RLP](https://github.com/ethereum/wiki/wiki/RLP) |
||||
|
||||
### debug_standardTraceBlockToFile |
||||
|
||||
|
||||
When JS-based tracing (see below) was first implemented, the intended usecase was to enable long-running tracers that could stream results back via a subscription channel. |
||||
This method works a bit differently. (For full details, see [PR](https://github.com/ethereum/go-ethereum/pull/17914)) |
||||
|
||||
- It streams output to disk during the execution, to not blow up the memory usage on the node |
||||
- It uses `jsonl` as output format (to allow streaming) |
||||
- Uses a cross-client standardized output, so called 'standard json' |
||||
* Uses `op` for string-representation of opcode, instead of `op`/`opName` for numeric/string, and other simlar small differences. |
||||
* has `refund` |
||||
* Represents memory as a contiguous chunk of data, as opposed to a list of `32`-byte segments like `debug_traceTransaction` |
||||
|
||||
This means that this method is only 'useful' for callers who control the node -- at least sufficiently to be able to read the artefacts from the filesystem after the fact. |
||||
|
||||
The method can be used to dump a certain transaction out of a given block: |
||||
``` |
||||
> debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {txHash:"0x4049f61ffbb0747bb88dc1c85dd6686ebf225a3c10c282c45a8e0c644739f7e9", disableMemory:true}) |
||||
["/tmp/block_0x0bbe9f14-14-0x4049f61f-099048234"] |
||||
``` |
||||
Or all txs from a block: |
||||
``` |
||||
> debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {disableMemory:true}) |
||||
["/tmp/block_0x0bbe9f14-0-0xb4502ea7-409046657", "/tmp/block_0x0bbe9f14-1-0xe839be8f-954614764", "/tmp/block_0x0bbe9f14-2-0xc6e2052f-542255195", "/tmp/block_0x0bbe9f14-3-0x01b7f3fe-209673214", "/tmp/block_0x0bbe9f14-4-0x0f290422-320999749", "/tmp/block_0x0bbe9f14-5-0x2dc0fb80-844117472", "/tmp/block_0x0bbe9f14-6-0x35542da1-256306111", "/tmp/block_0x0bbe9f14-7-0x3e199a08-086370834", "/tmp/block_0x0bbe9f14-8-0x87778b88-194603593", "/tmp/block_0x0bbe9f14-9-0xbcb081ba-629580052", "/tmp/block_0x0bbe9f14-10-0xc254381a-578605923", "/tmp/block_0x0bbe9f14-11-0xcc434d58-405931366", "/tmp/block_0x0bbe9f14-12-0xce61967d-874423181", "/tmp/block_0x0bbe9f14-13-0x05a20b35-267153288", "/tmp/block_0x0bbe9f14-14-0x4049f61f-606653767", "/tmp/block_0x0bbe9f14-15-0x46d473d2-614457338", "/tmp/block_0x0bbe9f14-16-0x35cf5500-411906321", "/tmp/block_0x0bbe9f14-17-0x79222961-278569788", "/tmp/block_0x0bbe9f14-18-0xad84e7b1-095032683", "/tmp/block_0x0bbe9f14-19-0x4bd48260-019097038", "/tmp/block_0x0bbe9f14-20-0x1517411d-292624085", "/tmp/block_0x0bbe9f14-21-0x6857e350-971385904", "/tmp/block_0x0bbe9f14-22-0xbe3ae2ca-236639695"] |
||||
|
||||
``` |
||||
Files are created in a temp-location, with the naming standard `block_<blockhash:4>-<txindex>-<txhash:4>-<random suffix>`. Each opcode immediately streams to file, with no in-geth buffering aside from whatever buffering the os normally does. |
||||
|
||||
On the server side, it also adds some more info when regenerating historical state, namely, the reexec-number if `required historical state is not avaiable` is encountered, so a user can experiment with increasing that setting. It also prints out the remaining block until it reaches target: |
||||
|
||||
``` |
||||
INFO [10-15|13:48:25.263] Regenerating historical state block=2385959 target=2386012 remaining=53 elapsed=3m30.990537767s |
||||
INFO [10-15|13:48:33.342] Regenerating historical state block=2386012 target=2386012 remaining=0 elapsed=3m39.070073163s |
||||
INFO [10-15|13:48:33.343] Historical state regenerated block=2386012 elapsed=3m39.070454362s nodes=10.03mB preimages=652.08kB |
||||
INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-0-0xfbbd6d91-715824834 |
||||
INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-1-0x71076194-187462969 |
||||
INFO [10-15|13:48:34.421] Wrote trace file=/tmp/block_0x14490c57-2-0x3f4263fe-056924484 |
||||
``` |
||||
|
||||
The `options` is as follows: |
||||
``` |
||||
type StdTraceConfig struct { |
||||
*vm.LogConfig |
||||
Reexec *uint64 |
||||
TxHash *common.Hash |
||||
} |
||||
``` |
||||
|
||||
### debug_standardTraceBadBlockToFile |
||||
|
||||
This method is similar to `debug_standardTraceBlockToFile`, but can be used to obtain info about a block which has been _rejected_ as invalid (for some reason). |
||||
|
||||
|
||||
### debug_traceTransaction |
||||
|
||||
**OBS** In most scenarios, `debug.standardTraceBlockToFile` is better suited for tracing! |
||||
|
||||
The `traceTransaction` debugging method will attempt to run the transaction in the exact same manner |
||||
as it was executed on the network. It will replay any transaction that may have been executed prior |
||||
to this one before it will finally attempt to execute the transaction that corresponds to the given |
||||
hash. |
||||
|
||||
In addition to the hash of the transaction you may give it a secondary *optional* argument, which |
||||
specifies the options for this specific call. The possible options are: |
||||
|
||||
* `disableStorage`: `BOOL`. Setting this to true will disable storage capture (default = false). |
||||
* `disableMemory`: `BOOL`. Setting this to true will disable memory capture (default = false). |
||||
* `disableStack`: `BOOL`. Setting this to true will disable stack capture (default = false). |
||||
* `tracer`: `STRING`. Setting this will enable JavaScript-based transaction tracing, described below. If set, the previous four arguments will be ignored. |
||||
* `timeout`: `STRING`. Overrides the default timeout of 5 seconds for JavaScript-based tracing calls. Valid values are described [here](https://golang.org/pkg/time/#ParseDuration). |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|----------------------------------------------------------------------------------------------| |
||||
| Go | `debug.TraceTransaction(txHash common.Hash, logger *vm.LogConfig) (*ExecutionResurt, error)` | |
||||
| Console | `debug.traceTransaction(txHash, [options])` | |
||||
| RPC | `{"method": "debug_traceTransaction", "params": [txHash, {}]}` | |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> debug.traceTransaction("0x2059dd53ecac9827faad14d364f9e04b1d5fe5b506e3acc886eff7a6f88a696a") |
||||
{ |
||||
gas: 85301, |
||||
returnValue: "", |
||||
structLogs: [{ |
||||
depth: 1, |
||||
error: "", |
||||
gas: 162106, |
||||
gasCost: 3, |
||||
memory: null, |
||||
op: "PUSH1", |
||||
pc: 0, |
||||
stack: [], |
||||
storage: {} |
||||
}, |
||||
/* snip */ |
||||
{ |
||||
depth: 1, |
||||
error: "", |
||||
gas: 100000, |
||||
gasCost: 0, |
||||
memory: ["0000000000000000000000000000000000000000000000000000000000000006", "0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000060"], |
||||
op: "STOP", |
||||
pc: 120, |
||||
stack: ["00000000000000000000000000000000000000000000000000000000d67cbec9"], |
||||
storage: { |
||||
0000000000000000000000000000000000000000000000000000000000000004: "8241fa522772837f0d05511f20caa6da1d5a3209000000000000000400000001", |
||||
0000000000000000000000000000000000000000000000000000000000000006: "0000000000000000000000000000000000000000000000000000000000000001", |
||||
f652222313e28459528d920b65115c16c04f3efc82aaedc97be59f3f377c0d3f: "00000000000000000000000002e816afc1b5c0f39852131959d946eb3b07b5ad" |
||||
} |
||||
}] |
||||
``` |
||||
|
||||
|
||||
#### JavaScript-based tracing |
||||
Specifying the `tracer` option in the second argument enables JavaScript-based tracing. In this mode, `tracer` is interpreted as a JavaScript expression that is expected to evaluate to an object with (at least) two methods, named `step` and `result`. |
||||
|
||||
`step`is a function that takes two arguments, log and db, and is called for each step of the EVM, or when an error occurs, as the specified transaction is traced. |
||||
|
||||
`log` has the following fields: |
||||
|
||||
- `pc`: Number, the current program counter |
||||
- `op`: Object, an OpCode object representing the current opcode |
||||
- `gas`: Number, the amount of gas remaining |
||||
- `gasPrice`: Number, the cost in wei of each unit of gas |
||||
- `memory`: Object, a structure representing the contract's memory space |
||||
- `stack`: array[big.Int], the EVM execution stack |
||||
- `depth`: The execution depth |
||||
- `account`: The address of the account executing the current operation |
||||
- `err`: If an error occured, information about the error |
||||
|
||||
If `err` is non-null, all other fields should be ignored. |
||||
|
||||
For efficiency, the same `log` object is reused on each execution step, updated with current values; make sure to copy values you want to preserve beyond the current call. For instance, this step function will not work: |
||||
|
||||
function(log) { |
||||
this.logs.append(log); |
||||
} |
||||
|
||||
But this step function will: |
||||
|
||||
function(log) { |
||||
this.logs.append({gas: log.gas, pc: log.pc, ...}); |
||||
} |
||||
|
||||
`log.op` has the following methods: |
||||
|
||||
- `isPush()` - returns true iff the opcode is a PUSHn |
||||
- `toString()` - returns the string representation of the opcode |
||||
- `toNumber()` - returns the opcode's number |
||||
|
||||
`log.memory` has the following methods: |
||||
|
||||
- `slice(start, stop)` - returns the specified segment of memory as a byte slice |
||||
- `length()` - returns the length of the memory |
||||
|
||||
`log.stack` has the following methods: |
||||
|
||||
- `peek(idx)` - returns the idx-th element from the top of the stack (0 is the topmost element) as a big.Int |
||||
- `length()` - returns the number of elements in the stack |
||||
|
||||
`db` has the following methods: |
||||
|
||||
- `getBalance(address)` - returns a `big.Int` with the specified account's balance |
||||
- `getNonce(address)` - returns a Number with the specified account's nonce |
||||
- `getCode(address)` - returns a byte slice with the code for the specified account |
||||
- `getState(address, hash)` - returns the state value for the specified account and the specified hash |
||||
- `exists(address)` - returns true if the specified address exists |
||||
|
||||
The second function, 'result', takes no arguments, and is expected to return a JSON-serializable value to return to the RPC caller. |
||||
|
||||
If the step function throws an exception or executes an illegal operation at any point, it will not be called on any further VM steps, and the error will be returned to the caller. |
||||
|
||||
Note that several values are Golang big.Int objects, not JavaScript numbers or JS bigints. As such, they have the same interface as described in the godocs. Their default serialization to JSON is as a Javascript number; to serialize large numbers accurately call `.String()` on them. For convenience, `big.NewInt(x)` is provided, and will convert a uint to a Go BigInt. |
||||
|
||||
Usage example, returns the top element of the stack at each CALL opcode only: |
||||
|
||||
debug.traceTransaction(txhash, {tracer: '{data: [], fault: function(log) {}, step: function(log) { if(log.op.toString() == "CALL") this.data.push(log.stack.peek(0)); }, result: function() { return this.data; }}'}); |
||||
|
||||
### debug_verbosity |
||||
|
||||
Sets the logging verbosity ceiling. Log messages with level |
||||
up to and including the given level will be printed. |
||||
|
||||
The verbosity of individual packages and source files |
||||
can be raised using `debug_vmodule`. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|---------------------------------------------------| |
||||
| Console | `debug.verbosity(level)` | |
||||
| RPC | `{"method": "debug_vmodule", "params": [number]}` | |
||||
|
||||
### debug_vmodule |
||||
|
||||
Sets the logging verbosity pattern. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|---------------------------------------------------| |
||||
| Console | `debug.vmodule(string)` | |
||||
| RPC | `{"method": "debug_vmodule", "params": [string]}` | |
||||
|
||||
|
||||
#### Examples |
||||
|
||||
If you want to see messages from a particular Go package (directory) |
||||
and all subdirectories, use: |
||||
|
||||
``` javascript |
||||
> debug.vmodule("eth/*=6") |
||||
``` |
||||
|
||||
If you want to restrict messages to a particular package (e.g. p2p) |
||||
but exclude subdirectories, use: |
||||
|
||||
``` javascript |
||||
> debug.vmodule("p2p=6") |
||||
``` |
||||
|
||||
If you want to see log messages from a particular source file, use |
||||
|
||||
``` javascript |
||||
> debug.vmodule("server.go=6") |
||||
``` |
||||
|
||||
You can compose these basic patterns. If you want to see all |
||||
output from peer.go in a package below eth (eth/peer.go, |
||||
eth/downloader/peer.go) as well as output from package p2p |
||||
at level <= 5, use: |
||||
|
||||
``` javascript |
||||
debug.vmodule("eth/*/peer.go=6,p2p=5") |
||||
``` |
||||
|
||||
### debug_writeBlockProfile |
||||
|
||||
Writes a goroutine blocking profile to the given file. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-------------------------------------------------------------| |
||||
| Console | `debug.writeBlockProfile(file)` | |
||||
| RPC | `{"method": "debug_writeBlockProfile", "params": [string]}` | |
||||
|
||||
### debug_writeMemProfile |
||||
|
||||
Writes an allocation profile to the given file. |
||||
Note that the profiling rate cannot be set through the API, |
||||
it must be set on the command line using the `--memprofilerate` |
||||
flag. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-------------------------------------------------------------| |
||||
| Console | `debug.writeMemProfile(file string)` | |
||||
| RPC | `{"method": "debug_writeBlockProfile", "params": [string]}` | |
||||
@ -0,0 +1,186 @@ |
||||
--- |
||||
title: eth Namespace |
||||
sort_key: C |
||||
--- |
||||
|
||||
Geth provides several extensions to the standard "eth" JSON-RPC namespace. |
||||
|
||||
* TOC |
||||
{:toc} |
||||
|
||||
### eth_subscribe, eth_unsubscribe |
||||
|
||||
These methods are used for real-time events through subscriptions. See the [subscription |
||||
documentation](./pubsub) for more information. |
||||
|
||||
### eth_call |
||||
|
||||
Executes a new message call immediately, without creating a transaction on the block |
||||
chain. The `eth_call` method can be used to query internal contract state, to execute |
||||
validations coded into a contract or even to test what the effect of a transaction would |
||||
be without running it live. |
||||
|
||||
#### Parameters |
||||
|
||||
The method takes 3 parameters: an unsigned transaction object to execute in read-only |
||||
mode; the block number to execute the call against; and an optional state override-set to |
||||
allow executing the call against a modified chain state. |
||||
|
||||
##### 1. `Object` - Transaction call object |
||||
|
||||
The *transaction call object* is mandatory and contains all the necessary parameters to |
||||
execute a read-only EVM contract method. |
||||
|
||||
| Field | Type | Bytes | Optional | Description | |
||||
|:-----------|:-----------|:------|:---------|:------------| |
||||
| `from` | `Address` | 20 | Yes | Address the transaction is simulated to have been sent from. Defaults to first account in the local keystore or the `0x00..0` address if no local accounts are available. | |
||||
| `to` | `Address` | 20 | No | Address the transaction is sent to. | |
||||
| `gas` | `Quantity` | <8 | Yes | Maximum gas allowance for the code execution to avoid infinite loops. Defaults to `2^63` or whatever value the node operator specified via `--rpc.gascap`. | |
||||
| `gasPrice` | `Quantity` | <32 | Yes | Number of `wei` to simulate paying for each unit of gas during execution. Defaults to `1 gwei`. | |
||||
| `value` | `Quantity` | <32 | Yes | Amount of `wei` to simulate sending along with the transaction. Defaults to `0`. | |
||||
| `data` | `Binary` | any | Yes | Binary data to send to the target contract. Generally the 4 byte hash of the method signature followed by the ABI encoded parameters. For details please see the [Ethereum Contract ABI](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI). | |
||||
|
||||
Example: |
||||
|
||||
```json |
||||
{ |
||||
"from": "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3", |
||||
"to": "0xebe8efa441b9302a0d7eaecc277c09d20d684540", |
||||
"gas": "0x1bd7c", |
||||
"data": "0xd459fc46000000000000000000000000000000000000000000000000000000000046c650dbb5e8cb2bac4d2ed0b1e6475d37361157738801c494ca482f96527eb48f9eec488c2eba92d31baeccfb6968fad5c21a3df93181b43b4cf253b4d572b64172ef000000000000000000000000000000000000000000000000000000000000008c00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000002b85c0c828d7a98633b4e1b65eac0c017502da909420aeade9a280675013df36bdc71cffdf420cef3d24ba4b3f9b980bfbb26bd5e2dcf7795b3519a3fd22ffbb2000000000000000000000000000000000000000000000000000000000000000238fb6606dc2b5e42d00c653372c153da8560de77bd9afaba94b4ab6e4aa11d565d858c761320dbf23a94018d843772349bd9d92301b0ca9ca983a22d86a70628", |
||||
} |
||||
``` |
||||
|
||||
##### 2. `Quantity | Tag` - Block number or the string `latest` or `pending` |
||||
|
||||
The *block number* is mandatory and defines the context (state) against which the |
||||
specified transaction should be executed. It is not possible to execute calls against |
||||
reorged blocks; or blocks older than 128 (unless the node is an archive node). |
||||
|
||||
##### 3. `Object` - State override set |
||||
|
||||
The *state override set* is an optional address-to-state mapping, where each entry |
||||
specifies some state to be ephemerally overridden prior to executing the call. Each |
||||
address maps to an object containing: |
||||
|
||||
| Field | Type | Bytes | Optional | Description | |
||||
|:------------|:-----------|:------|:---------|:------------| |
||||
| `balance` | `Quantity` | <32 | Yes | Fake balance to set for the account before executing the call. | |
||||
| `nonce` | `Quantity` | <8 | Yes | Fake nonce to set for the account before executing the call. | |
||||
| `code` | `Binary` | any | Yes | Fake EVM bytecode to inject into the account before executing the call. | |
||||
| `state` | `Object` | any | Yes | Fake key-value mapping to override **all** slots in the account storage before executing the call. | |
||||
| `stateDiff` | `Object` | any | Yes | Fake key-value mapping to override **individual** slots in the account storage before executing the call. | |
||||
|
||||
The goal of the *state override set* is manyfold: |
||||
|
||||
* It can be used by DApps to reduce the amount of contract code needed to be deployed on |
||||
chain. Code that simply returns internal state or does pre-defined validations can be |
||||
kept off chain and fed to the node on-demand. |
||||
* It can be used for smart contract analysis by extending the code deployed on chain with |
||||
custom methods and invoking them. This avoids having to download and reconstruct the |
||||
entire state in a sandbox to run custom code against. |
||||
* It can be used to debug smart contracts in an already deployed large suite of contracts |
||||
by selectively overriding some code or state and seeing how execution changes. |
||||
Specialized tooling will probably be necessary. |
||||
|
||||
Example: |
||||
|
||||
```json |
||||
{ |
||||
"0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3": { |
||||
"balance": "0xde0b6b3a7640000" |
||||
}, |
||||
"0xebe8efa441b9302a0d7eaecc277c09d20d684540": { |
||||
"code": "0x...", |
||||
"state": { |
||||
"" |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
#### Return Values |
||||
|
||||
The method returns a single `Binary` consisting the return value of the executed contract |
||||
call. |
||||
|
||||
#### Simple example |
||||
|
||||
With a synced Rinkeby node with RPC exposed on localhost (`geth --rinkeby --rpc`) we can |
||||
make a call against the [Checkpoint |
||||
Oracle](https://rinkeby.etherscan.io/address/0xebe8efa441b9302a0d7eaecc277c09d20d684540) |
||||
to retrieve the list of administrators: |
||||
|
||||
``` |
||||
$ curl --data '{"method":"eth_call","params":[{"to":"0xebe8efa441b9302a0d7eaecc277c09d20d684540","data":"0x45848dfc"},"latest"],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545 |
||||
``` |
||||
|
||||
And the result is an Ethereum ABI encoded list of accounts: |
||||
|
||||
```json |
||||
{ |
||||
"id": 1, |
||||
"jsonrpc": "2.0", |
||||
"result": "0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000004000000000000000000000000d9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f300000000000000000000000078d1ad571a1a09d60d9bbf25894b44e4c8859595000000000000000000000000286834935f4a8cfb4ff4c77d5770c2775ae2b0e7000000000000000000000000b86e2b0ab5a4b1373e40c51a7c712c70ba2f9f8e" |
||||
} |
||||
``` |
||||
|
||||
Just for the sake of completeness, decoded the response is: |
||||
|
||||
``` |
||||
0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3, |
||||
0x78d1ad571a1a09d60d9bbf25894b44e4c8859595, |
||||
0x286834935f4a8cfb4ff4c77d5770c2775ae2b0e7, |
||||
0xb86e2b0ab5a4b1373e40c51a7c712c70ba2f9f8e |
||||
``` |
||||
|
||||
#### Override example |
||||
|
||||
The above *simple example* showed how to call a method already exposed by an on-chain |
||||
smart contract. What if we want to access some data not exposed by it? |
||||
|
||||
We can gut out the |
||||
[original](https://github.com/ethereum/go-ethereum/blob/master/contracts/checkpointoracle/contract/oracle.sol) |
||||
checkpoint oracle contract with one that retains the same fields (to retain the same |
||||
storage layout), but one that includes a different method set: |
||||
|
||||
``` |
||||
pragma solidity ^0.5.10; |
||||
|
||||
contract CheckpointOracle { |
||||
mapping(address => bool) admins; |
||||
address[] adminList; |
||||
uint64 sectionIndex; |
||||
uint height; |
||||
bytes32 hash; |
||||
uint sectionSize; |
||||
uint processConfirms; |
||||
uint threshold; |
||||
|
||||
function VotingThreshold() public view returns (uint) { |
||||
return threshold; |
||||
} |
||||
} |
||||
``` |
||||
|
||||
With a synced Rinkeby node with RPC exposed on localhost (`geth --rinkeby --rpc`) we can |
||||
make a call against the live [Checkpoint |
||||
Oracle](https://rinkeby.etherscan.io/address/0xebe8efa441b9302a0d7eaecc277c09d20d684540), |
||||
but override its byte code with our own version that has an accessor for the voting |
||||
threshold field: |
||||
|
||||
``` |
||||
$ curl --data '{"method":"eth_call","params":[{"to":"0xebe8efa441b9302a0d7eaecc277c09d20d684540","data":"0x0be5b6ba"}, "latest", {"0xebe8efa441b9302a0d7eaecc277c09d20d684540": {"code":"0x6080604052348015600f57600080fd5b506004361060285760003560e01c80630be5b6ba14602d575b600080fd5b60336045565b60408051918252519081900360200190f35b6007549056fea265627a7a723058206f26bd0433456354d8d1228d8fe524678a8aeeb0594851395bdbd35efc2a65f164736f6c634300050a0032"}}],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545 |
||||
``` |
||||
|
||||
And the result is the Ethereum ABI encoded threshold number: |
||||
|
||||
```json |
||||
{ |
||||
"id": 1, |
||||
"jsonrpc": "2.0", |
||||
"result": "0x0000000000000000000000000000000000000000000000000000000000000002" |
||||
} |
||||
``` |
||||
|
||||
Just for the sake of completeness, decoded the response is: `2`. |
||||
@ -0,0 +1,72 @@ |
||||
--- |
||||
title: miner Namespace |
||||
sort_key: C |
||||
--- |
||||
|
||||
The `miner` API allows you to remote control the node's mining operation and set various |
||||
mining specific settings. |
||||
|
||||
* TOC |
||||
{:toc} |
||||
|
||||
### miner_getHashrate |
||||
|
||||
Get your hashrate in H/s (Hash operations per second). |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-------------------------------------------------------------| |
||||
| Console | `miner.getHashrate()` | |
||||
| RPC | `{"method": "miner_getHashrate", "params": []}` | |
||||
|
||||
### miner_setExtra |
||||
|
||||
Sets the extra data a miner can include when miner blocks. This is capped at |
||||
32 bytes. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|----------------------------------------------------| |
||||
| Go | `miner.setExtra(extra string) (bool, error)` | |
||||
| Console | `miner.setExtra(string)` | |
||||
| RPC | `{"method": "miner_setExtra", "params": [string]}` | |
||||
|
||||
### miner_setGasPrice |
||||
|
||||
Sets the minimal accepted gas price when mining transactions. Any transactions that are |
||||
below this limit are excluded from the mining process. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-------------------------------------------------------| |
||||
| Go | `miner.setGasPrice(number *rpc.HexNumber) bool` | |
||||
| Console | `miner.setGasPrice(number)` | |
||||
| RPC | `{"method": "miner_setGasPrice", "params": [number]}` | |
||||
|
||||
### miner_start |
||||
|
||||
Start the CPU mining process with the given number of threads and generate a new DAG |
||||
if need be. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-----------------------------------------------------| |
||||
| Go | `miner.Start(threads *rpc.HexNumber) (bool, error)` | |
||||
| Console | `miner.start(number)` | |
||||
| RPC | `{"method": "miner_start", "params": [number]}` | |
||||
|
||||
### miner_stop |
||||
|
||||
Stop the CPU mining operation. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|----------------------------------------------| |
||||
| Go | `miner.Stop() bool` | |
||||
| Console | `miner.stop()` | |
||||
| RPC | `{"method": "miner_stop", "params": []}` | |
||||
|
||||
### miner_setEtherbase |
||||
|
||||
Sets the etherbase, where mining rewards will go. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-------------------------------------------------------------| |
||||
| Go | `miner.SetEtherbase(common.Address) bool` | |
||||
| Console | `miner.setEtherbase(address)` | |
||||
| RPC | `{"method": "miner_setEtherbase", "params": [address]}` | |
||||
@ -0,0 +1,187 @@ |
||||
--- |
||||
title: personal Namespace |
||||
sort_key: C |
||||
--- |
||||
|
||||
The personal API manages private keys in the key store. |
||||
|
||||
* TOC |
||||
{:toc} |
||||
|
||||
### personal_importRawKey |
||||
|
||||
Imports the given unencrypted private key (hex string) into the key store, |
||||
encrypting it with the passphrase. |
||||
|
||||
Returns the address of the new account. |
||||
|
||||
| Client | Method invocation | |
||||
| :--------| ----------------------------------------------------------------- | |
||||
| Console | `personal.importRawKey(keydata, passphrase)` | |
||||
| RPC | `{"method": "personal_importRawKey", "params": [string, string]}` | |
||||
|
||||
### personal_listAccounts |
||||
|
||||
Returns all the Ethereum account addresses of all keys |
||||
in the key store. |
||||
|
||||
| Client | Method invocation | |
||||
| :--------| --------------------------------------------------- | |
||||
| Console | `personal.listAccounts` | |
||||
| RPC | `{"method": "personal_listAccounts", "params": []}` | |
||||
|
||||
#### Example |
||||
|
||||
``` javascript |
||||
> personal.listAccounts |
||||
["0x5e97870f263700f46aa00d967821199b9bc5a120", "0x3d80b31a78c30fc628f20b2c89d7ddbf6e53cedc"] |
||||
``` |
||||
|
||||
### personal_lockAccount |
||||
|
||||
Removes the private key with given address from memory. |
||||
The account can no longer be used to send transactions. |
||||
|
||||
| Client | Method invocation | |
||||
| :--------| -------------------------------------------------------- | |
||||
| Console | `personal.lockAccount(address)` | |
||||
| RPC | `{"method": "personal_lockAccount", "params": [string]}` | |
||||
|
||||
### personal_newAccount |
||||
|
||||
Generates a new private key and stores it in the key store directory. |
||||
The key file is encrypted with the given passphrase. |
||||
Returns the address of the new account. |
||||
|
||||
At the geth console, `newAccount` will prompt for a passphrase when |
||||
it is not supplied as the argument. |
||||
|
||||
| Client | Method invocation | |
||||
| :--------| --------------------------------------------------- | |
||||
| Console | `personal.newAccount()` | |
||||
| RPC | `{"method": "personal_newAccount", "params": [string]}` | |
||||
|
||||
#### Example |
||||
|
||||
``` javascript |
||||
> personal.newAccount() |
||||
Passphrase: |
||||
Repeat passphrase: |
||||
"0x5e97870f263700f46aa00d967821199b9bc5a120" |
||||
``` |
||||
|
||||
The passphrase can also be supplied as a string. |
||||
|
||||
``` javascript |
||||
> personal.newAccount("h4ck3r") |
||||
"0x3d80b31a78c30fc628f20b2c89d7ddbf6e53cedc" |
||||
``` |
||||
|
||||
### personal_unlockAccount |
||||
|
||||
Decrypts the key with the given address from the key store. |
||||
|
||||
Both passphrase and unlock duration are optional when using the JavaScript console. |
||||
If the passphrase is not supplied as an argument, the console will prompt for |
||||
the passphrase interactively. |
||||
|
||||
The unencrypted key will be held in memory until the unlock duration expires. |
||||
If the unlock duration defaults to 300 seconds. An explicit duration |
||||
of zero seconds unlocks the key until geth exits. |
||||
|
||||
The account can be used with `eth_sign` and `eth_sendTransaction` while it is unlocked. |
||||
|
||||
| Client | Method invocation | |
||||
| :--------| -------------------------------------------------------------------------- | |
||||
| Console | `personal.unlockAccount(address, passphrase, duration)` | |
||||
| RPC | `{"method": "personal_unlockAccount", "params": [string, string, number]}` | |
||||
|
||||
#### Examples |
||||
|
||||
``` javascript |
||||
> personal.unlockAccount("0x5e97870f263700f46aa00d967821199b9bc5a120") |
||||
Unlock account 0x5e97870f263700f46aa00d967821199b9bc5a120 |
||||
Passphrase: |
||||
true |
||||
``` |
||||
|
||||
Supplying the passphrase and unlock duration as arguments: |
||||
|
||||
``` javascript |
||||
> personal.unlockAccount("0x5e97870f263700f46aa00d967821199b9bc5a120", "foo", 30) |
||||
true |
||||
``` |
||||
|
||||
If you want to type in the passphrase and stil override the default unlock duration, |
||||
pass `null` as the passphrase. |
||||
|
||||
``` |
||||
> personal.unlockAccount("0x5e97870f263700f46aa00d967821199b9bc5a120", null, 30) |
||||
Unlock account 0x5e97870f263700f46aa00d967821199b9bc5a120 |
||||
Passphrase: |
||||
true |
||||
``` |
||||
|
||||
### personal_sendTransaction |
||||
|
||||
Validate the given passphrase and submit transaction. |
||||
|
||||
The transaction is the same argument as for `eth_sendTransaction` and contains the `from` address. If the passphrase can be used to decrypt the private key belogging to `tx.from` the transaction is verified, signed and send onto the network. The account is not unlocked globally in the node and cannot be used in other RPC calls. |
||||
|
||||
| Client | Method invocation | |
||||
| :--------| -----------------------------------------------------------------| |
||||
| Console | `personal.sendTransaction(tx, passphrase)` | |
||||
| RPC | `{"method": "personal_sendTransaction", "params": [tx, string]}` | |
||||
|
||||
*Note, prior to Geth 1.5, please use `personal_signAndSendTransaction` as that was the |
||||
original introductory name and only later renamed to the current final version.* |
||||
|
||||
#### Examples |
||||
|
||||
``` javascript |
||||
> var tx = {from: "0x391694e7e0b0cce554cb130d723a9d27458f9298", to: "0xafa3f8684e54059998bc3a7b0d2b0da075154d66", value: web3.toWei(1.23, "ether")} |
||||
undefined |
||||
> personal.sendTransaction(tx, "passphrase") |
||||
0x8474441674cdd47b35b875fd1a530b800b51a5264b9975fb21129eeb8c18582f |
||||
``` |
||||
|
||||
### personal_sign |
||||
|
||||
The sign method calculates an Ethereum specific signature with: |
||||
`sign(keccack256("\x19Ethereum Signed Message:\n" + len(message) + message)))`. |
||||
|
||||
By adding a prefix to the message makes the calculated signature recognisable as an Ethereum specific signature. This prevents misuse where a malicious DApp can sign arbitrary data (e.g. transaction) and use the signature to impersonate the victim. |
||||
|
||||
See ecRecover to verify the signature. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-------------------------------------------------------| |
||||
| Console | `personal.sign(message, account, [password])` | |
||||
| RPC | `{"method": "personal_sign", "params": [message, account, password]}` | |
||||
|
||||
|
||||
#### Examples |
||||
|
||||
``` javascript |
||||
> personal.sign("0xdeadbeaf", "0x9b2055d370f73ec7d8a03e965129118dc8f5bf83", "") |
||||
"0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b" |
||||
``` |
||||
|
||||
### personal_ecRecover |
||||
|
||||
`ecRecover` returns the address associated with the private key that was used to calculate the signature in `personal_sign`. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-------------------------------------------------------| |
||||
| Console | `personal.ecRecover(message, signature)` | |
||||
| RPC | `{"method": "personal_ecRecover", "params": [message, signature]}` | |
||||
|
||||
|
||||
#### Examples |
||||
|
||||
``` javascript |
||||
> personal.sign("0xdeadbeaf", "0x9b2055d370f73ec7d8a03e965129118dc8f5bf83", "") |
||||
"0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b" |
||||
> personal.ecRecover("0xdeadbeaf", "0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b") |
||||
"0x9b2055d370f73ec7d8a03e965129118dc8f5bf83" |
||||
``` |
||||
@ -0,0 +1,228 @@ |
||||
--- |
||||
title: txpool Namespace |
||||
sort_key: C |
||||
--- |
||||
|
||||
The `txpool` API gives you access to several non-standard RPC methods to inspect the contents of the |
||||
transaction pool containing all the currently pending transactions as well as the ones queued for |
||||
future processing. |
||||
|
||||
* TOC |
||||
{:toc} |
||||
|
||||
### txpool_content |
||||
|
||||
The `content` inspection property can be queried to list the exact details of all the transactions |
||||
currently pending for inclusion in the next block(s), as well as the ones that are being scheduled |
||||
for future execution only. |
||||
|
||||
The result is an object with two fields `pending` and `queued`. Each of these fields are associative |
||||
arrays, in which each entry maps an origin-address to a batch of scheduled transactions. These batches |
||||
themselves are maps associating nonces with actual transactions. |
||||
|
||||
Please note, there may be multiple transactions associated with the same account and nonce. This can |
||||
happen if the user broadcast mutliple ones with varying gas allowances (or even complerely different |
||||
transactions). |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-------------------------------------------------------------------------| |
||||
| Go | `txpool.Content() (map[string]map[string]map[string][]*RPCTransaction)` | |
||||
| Console | `txpool.content` | |
||||
| RPC | `{"method": "txpool_content"}` | |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> txpool.content |
||||
{ |
||||
pending: { |
||||
0x0216d5032f356960cd3749c31ab34eeff21b3395: { |
||||
806: [{ |
||||
blockHash: "0x0000000000000000000000000000000000000000000000000000000000000000", |
||||
blockNumber: null, |
||||
from: "0x0216d5032f356960cd3749c31ab34eeff21b3395", |
||||
gas: "0x5208", |
||||
gasPrice: "0xba43b7400", |
||||
hash: "0xaf953a2d01f55cfe080c0c94150a60105e8ac3d51153058a1f03dd239dd08586", |
||||
input: "0x", |
||||
nonce: "0x326", |
||||
to: "0x7f69a91a3cf4be60020fb58b893b7cbb65376db8", |
||||
transactionIndex: null, |
||||
value: "0x19a99f0cf456000" |
||||
}] |
||||
}, |
||||
0x24d407e5a0b506e1cb2fae163100b5de01f5193c: { |
||||
34: [{ |
||||
blockHash: "0x0000000000000000000000000000000000000000000000000000000000000000", |
||||
blockNumber: null, |
||||
from: "0x24d407e5a0b506e1cb2fae163100b5de01f5193c", |
||||
gas: "0x44c72", |
||||
gasPrice: "0x4a817c800", |
||||
hash: "0xb5b8b853af32226755a65ba0602f7ed0e8be2211516153b75e9ed640a7d359fe", |
||||
input: "0xb61d27f600000000000000000000000024d407e5a0b506e1cb2fae163100b5de01f5193c00000000000000000000000000000000000000000000000053444835ec580000000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", |
||||
nonce: "0x22", |
||||
to: "0x7320785200f74861b69c49e4ab32399a71b34f1a", |
||||
transactionIndex: null, |
||||
value: "0x0" |
||||
}] |
||||
} |
||||
}, |
||||
queued: { |
||||
0x976a3fc5d6f7d259ebfb4cc2ae75115475e9867c: { |
||||
3: [{ |
||||
blockHash: "0x0000000000000000000000000000000000000000000000000000000000000000", |
||||
blockNumber: null, |
||||
from: "0x976a3fc5d6f7d259ebfb4cc2ae75115475e9867c", |
||||
gas: "0x15f90", |
||||
gasPrice: "0x4a817c800", |
||||
hash: "0x57b30c59fc39a50e1cba90e3099286dfa5aaf60294a629240b5bbec6e2e66576", |
||||
input: "0x", |
||||
nonce: "0x3", |
||||
to: "0x346fb27de7e7370008f5da379f74dd49f5f2f80f", |
||||
transactionIndex: null, |
||||
value: "0x1f161421c8e0000" |
||||
}] |
||||
}, |
||||
0x9b11bf0459b0c4b2f87f8cebca4cfc26f294b63a: { |
||||
2: [{ |
||||
blockHash: "0x0000000000000000000000000000000000000000000000000000000000000000", |
||||
blockNumber: null, |
||||
from: "0x9b11bf0459b0c4b2f87f8cebca4cfc26f294b63a", |
||||
gas: "0x15f90", |
||||
gasPrice: "0xba43b7400", |
||||
hash: "0x3a3c0698552eec2455ed3190eac3996feccc806970a4a056106deaf6ceb1e5e3", |
||||
input: "0x", |
||||
nonce: "0x2", |
||||
to: "0x24a461f25ee6a318bdef7f33de634a67bb67ac9d", |
||||
transactionIndex: null, |
||||
value: "0xebec21ee1da40000" |
||||
}], |
||||
6: [{ |
||||
blockHash: "0x0000000000000000000000000000000000000000000000000000000000000000", |
||||
blockNumber: null, |
||||
from: "0x9b11bf0459b0c4b2f87f8cebca4cfc26f294b63a", |
||||
gas: "0x15f90", |
||||
gasPrice: "0x4a817c800", |
||||
hash: "0xbbcd1e45eae3b859203a04be7d6e1d7b03b222ec1d66dfcc8011dd39794b147e", |
||||
input: "0x", |
||||
nonce: "0x6", |
||||
to: "0x6368f3f8c2b42435d6c136757382e4a59436a681", |
||||
transactionIndex: null, |
||||
value: "0xf9a951af55470000" |
||||
}, { |
||||
blockHash: "0x0000000000000000000000000000000000000000000000000000000000000000", |
||||
blockNumber: null, |
||||
from: "0x9b11bf0459b0c4b2f87f8cebca4cfc26f294b63a", |
||||
gas: "0x15f90", |
||||
gasPrice: "0x4a817c800", |
||||
hash: "0x60803251d43f072904dc3a2d6a084701cd35b4985790baaf8a8f76696041b272", |
||||
input: "0x", |
||||
nonce: "0x6", |
||||
to: "0x8db7b4e0ecb095fbd01dffa62010801296a9ac78", |
||||
transactionIndex: null, |
||||
value: "0xebe866f5f0a06000" |
||||
}], |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
### txpool_inspect |
||||
|
||||
The `inspect` inspection property can be queried to list a textual summary of all the transactions |
||||
currently pending for inclusion in the next block(s), as well as the ones that are being scheduled |
||||
for future execution only. This is a method specifically tailored to developers to quickly see the |
||||
transactions in the pool and find any potential issues. |
||||
|
||||
The result is an object with two fields `pending` and `queued`. Each of these fields are associative |
||||
arrays, in which each entry maps an origin-address to a batch of scheduled transactions. These batches |
||||
themselves are maps associating nonces with transactions summary strings. |
||||
|
||||
Please note, there may be multiple transactions associated with the same account and nonce. This can |
||||
happen if the user broadcast mutliple ones with varying gas allowances (or even complerely different |
||||
transactions). |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|----------------------------------------------------------------| |
||||
| Go | `txpool.Inspect() (map[string]map[string]map[string][]string)` | |
||||
| Console | `txpool.inspect` | |
||||
| RPC | `{"method": "txpool_inspect"}` | |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> txpool.inspect |
||||
{ |
||||
pending: { |
||||
0x26588a9301b0428d95e6fc3a5024fce8bec12d51: { |
||||
31813: ["0x3375ee30428b2a71c428afa5e89e427905f95f7e: 0 wei + 500000 × 20000000000 gas"] |
||||
}, |
||||
0x2a65aca4d5fc5b5c859090a6c34d164135398226: { |
||||
563662: ["0x958c1fa64b34db746925c6f8a3dd81128e40355e: 1051546810000000000 wei + 90000 × 20000000000 gas"], |
||||
563663: ["0x77517b1491a0299a44d668473411676f94e97e34: 1051190740000000000 wei + 90000 × 20000000000 gas"], |
||||
563664: ["0x3e2a7fe169c8f8eee251bb00d9fb6d304ce07d3a: 1050828950000000000 wei + 90000 × 20000000000 gas"], |
||||
563665: ["0xaf6c4695da477f8c663ea2d8b768ad82cb6a8522: 1050544770000000000 wei + 90000 × 20000000000 gas"], |
||||
563666: ["0x139b148094c50f4d20b01caf21b85edb711574db: 1048598530000000000 wei + 90000 × 20000000000 gas"], |
||||
563667: ["0x48b3bd66770b0d1eecefce090dafee36257538ae: 1048367260000000000 wei + 90000 × 20000000000 gas"], |
||||
563668: ["0x468569500925d53e06dd0993014ad166fd7dd381: 1048126690000000000 wei + 90000 × 20000000000 gas"], |
||||
563669: ["0x3dcb4c90477a4b8ff7190b79b524773cbe3be661: 1047965690000000000 wei + 90000 × 20000000000 gas"], |
||||
563670: ["0x6dfef5bc94b031407ffe71ae8076ca0fbf190963: 1047859050000000000 wei + 90000 × 20000000000 gas"] |
||||
}, |
||||
0x9174e688d7de157c5c0583df424eaab2676ac162: { |
||||
3: ["0xbb9bc244d798123fde783fcc1c72d3bb8c189413: 30000000000000000000 wei + 85000 × 21000000000 gas"] |
||||
}, |
||||
0xb18f9d01323e150096650ab989cfecd39d757aec: { |
||||
777: ["0xcd79c72690750f079ae6ab6ccd7e7aedc03c7720: 0 wei + 1000000 × 20000000000 gas"] |
||||
}, |
||||
0xb2916c870cf66967b6510b76c07e9d13a5d23514: { |
||||
2: ["0x576f25199d60982a8f31a8dff4da8acb982e6aba: 26000000000000000000 wei + 90000 × 20000000000 gas"] |
||||
}, |
||||
0xbc0ca4f217e052753614d6b019948824d0d8688b: { |
||||
0: ["0x2910543af39aba0cd09dbb2d50200b3e800a63d2: 1000000000000000000 wei + 50000 × 1171602790622 gas"] |
||||
}, |
||||
0xea674fdde714fd979de3edf0f56aa9716b898ec8: { |
||||
70148: ["0xe39c55ead9f997f7fa20ebe40fb4649943d7db66: 1000767667434026200 wei + 90000 × 20000000000 gas"] |
||||
} |
||||
}, |
||||
queued: { |
||||
0x0f6000de1578619320aba5e392706b131fb1de6f: { |
||||
6: ["0x8383534d0bcd0186d326c993031311c0ac0d9b2d: 9000000000000000000 wei + 21000 × 20000000000 gas"] |
||||
}, |
||||
0x5b30608c678e1ac464a8994c3b33e5cdf3497112: { |
||||
6: ["0x9773547e27f8303c87089dc42d9288aa2b9d8f06: 50000000000000000000 wei + 90000 × 50000000000 gas"] |
||||
}, |
||||
0x976a3fc5d6f7d259ebfb4cc2ae75115475e9867c: { |
||||
3: ["0x346fb27de7e7370008f5da379f74dd49f5f2f80f: 140000000000000000 wei + 90000 × 20000000000 gas"] |
||||
}, |
||||
0x9b11bf0459b0c4b2f87f8cebca4cfc26f294b63a: { |
||||
2: ["0x24a461f25ee6a318bdef7f33de634a67bb67ac9d: 17000000000000000000 wei + 90000 × 50000000000 gas"], |
||||
6: ["0x6368f3f8c2b42435d6c136757382e4a59436a681: 17990000000000000000 wei + 90000 × 20000000000 gas", "0x8db7b4e0ecb095fbd01dffa62010801296a9ac78: 16998950000000000000 wei + 90000 × 20000000000 gas"], |
||||
7: ["0x6368f3f8c2b42435d6c136757382e4a59436a681: 17900000000000000000 wei + 90000 × 20000000000 gas"] |
||||
} |
||||
} |
||||
} |
||||
``` |
||||
|
||||
### txpool_status |
||||
|
||||
The `status` inspection property can be queried for the number of transactions currently pending for |
||||
inclusion in the next block(s), as well as the ones that are being scheduled for future execution only. |
||||
|
||||
The result is an object with two fields `pending` and `queued`, each of which is a counter representing |
||||
the number of transactions in that particular state. |
||||
|
||||
| Client | Method invocation | |
||||
|:--------|-----------------------------------------------| |
||||
| Go | `txpool.Status() (map[string]*rpc.HexNumber)` | |
||||
| Console | `txpool.status` | |
||||
| RPC | `{"method": "txpool_status"}` | |
||||
|
||||
#### Example |
||||
|
||||
```javascript |
||||
> txpool.status |
||||
{ |
||||
pending: 10, |
||||
queued: 7 |
||||
} |
||||
``` |
||||
@ -0,0 +1,84 @@ |
||||
--- |
||||
title: JSON-RPC Server |
||||
sort_key: A |
||||
--- |
||||
|
||||
Geth supports all standard web3 JSON-RPC APIs. You can find documentation for |
||||
these APIs on the [Ethereum Wiki JSON-RPC page](web3-rpc). |
||||
|
||||
JSON-RPC is provided on multiple transports. Geth supports JSON-RPC over HTTP, |
||||
WebSocket and Unix Domain Sockets. Transports must be enabled through |
||||
command-line flags. |
||||
|
||||
Ethereum JSON-RPC APIs use a name-space system. RPC methods are grouped into |
||||
several categories depending on their purpose. All method names are composed of |
||||
the namespace, an underscore, and the actual method name within the namespace. |
||||
For example, the `eth_call` method resides in the `eth` namespace. |
||||
|
||||
Access to RPC methods can be enabled on a per-namespace basis. Find |
||||
documentation for individual namespaces in the sidebar. |
||||
|
||||
### HTTP Server |
||||
|
||||
To enable the HTTP server, use the `--rpc` flag. |
||||
|
||||
geth --rpc |
||||
|
||||
By default, geth accepts connections from the loopback interface (127.0.0.1). |
||||
The default listening port is 8545. You can customize address and port using the |
||||
`--rpcport` and `--rpcaddr` flags. |
||||
|
||||
geth --rpc --rpcport 3334 |
||||
|
||||
JSON-RPC method namespaces must be whitelisted in order to be available through |
||||
the HTTP server. The default whitelist allows access to the "eth" and "shh" |
||||
namespaces. To enable access to other APIs like account management ("personal") |
||||
and debugging ("debug"), they must be configured via the `--rpcapi` flag. We do |
||||
not recommend enabling such APIs over HTTP, however, since access to these |
||||
methods increases the attack surface. |
||||
|
||||
geth --rpc --rpcapi personal,eth,net,web3b |
||||
|
||||
Since the HTTP server is reachable from any local application, additional |
||||
protection is built into the server to prevent misuse of the API from web pages. |
||||
If you want enable access to the API from a web page, you must configure the |
||||
server to accept Cross-Origin requests with the `--rpccorsdomain` flag. |
||||
|
||||
Example: if you want to use [Remix](remix) with geth, allow requests from the |
||||
remix domain. |
||||
|
||||
geth --rpc --rpccorsdomain https://remix.ethereum.org |
||||
|
||||
Use `--rpccorsdomain '*'` to enable access from any origin. |
||||
|
||||
### WebSocket Server |
||||
|
||||
Configuration of the WebSocket endpoint is similar to the HTTP transport. To |
||||
enable WebSocket access, use `--ws` flag. The default WebSocket port is 8546. |
||||
The `--wsaddr`, `--wsport` and `--wsapi` flags can be used to customize settings |
||||
for the WebSocket server. |
||||
|
||||
geth --ws --wsport 3334 --wsapi eth,net,web3 |
||||
|
||||
Cross-Origin request protection also applies to the WebSocket server. Use the |
||||
`--wsorigins` flag to allow access to the server from web pages: |
||||
|
||||
geth --ws --wsorigins http://myapp.example.com |
||||
|
||||
As with `--rpccorsdomain`, using `--wsorigins '*'` allows access from any origin. |
||||
|
||||
### IPC Server |
||||
|
||||
JSON-RPC APIs are also provided on a UNIX domain socket. This server is enabled |
||||
by default and has access to all JSON-RPC namespaces. |
||||
|
||||
The listening socket is placed into the data directory by default. On Linux, the |
||||
default location of the geth socket is |
||||
|
||||
~/.ethereum/geth.ipc |
||||
|
||||
You can configure the location of the socket using the `--ipcpath` flag. IPC can |
||||
be disabled using the `--ipcdisable` flag. |
||||
|
||||
[web3-rpc]: https://github.com/ethereum/wiki/wiki/JSON-RPC |
||||
[remix]: https://remix.ethereum.org |
||||
@ -1,21 +1,24 @@ |
||||
--- |
||||
title: Documentation |
||||
title: Geth Documentation |
||||
root: .. |
||||
--- |
||||
* User documentation can be found at our [Ethereum User Guide and reference manual](http://ethereum.gitbooks.io/frontier-guide/content/). |
||||
* For the API reference and developer documentation head over to the auto generated [GoDoc](https://godoc.org/github.com/ethereum/go-ethereum) documentation. |
||||
|
||||
This is the documentation for the official Ethereum golang implementation. For generic Ethereum-related information (whitepaper, yellow paper, protocol and interface specs, APIs, DAPP development guides, etc) see the [Ethereum main wiki](https://github.com/ethereum/wiki/wiki). |
||||
|
||||
Main entry points: |
||||
You have found the user manual for geth, the Go language implementation of Ethereum. |
||||
|
||||
* [Getting Started Guide](./getting-started) |
||||
* [Installation Instructions](./install-and-build/installing-geth) |
||||
* [Management APIs](./interface/management-apis) |
||||
* [Managing Accounts](./interface/managing-your-accounts) |
||||
* [Command Line Options](./interface/command-line-options) |
||||
* [JSON-RPC Server](./rpc/server) |
||||
* [JavaScript Console](./interface/javascript-console) |
||||
* [Private Network](./doc/private-network) |
||||
* [Developers' Guide](./install-and-build/developers-guide) |
||||
* [Whisper v6](./whisper/whisper-overview) |
||||
|
||||
Sidebar lists all pages. |
||||
For the Go API reference and developer documentation head over to |
||||
[GoDoc](https://godoc.org/github.com/ethereum/go-ethereum). |
||||
|
||||
### Other Ethereum Documentation |
||||
|
||||
For generic Ethereum-related information, check the **[Ethereum |
||||
Wiki](https://github.com/ethereum/wiki/wiki)**. |
||||
|
||||
* [Ethereum Whitepaper](https://github.com/ethereum/wiki/wiki/White-Paper) |
||||
* [Ethereum Yellow Paper](https://ethereum.github.io/yellowpaper/paper.pdf) |
||||
* [Ethereum Improvement Proposals (EIPs)](https://eips.ethereum.org) |
||||
* [Peer-to-peer Networking Specifications](https://github.com/ethereum/devp2p/blob/master/README.md) |
||||
|
||||
Loading…
Reference in new issue