ethereum

README

go-ethereum-chinese

此源码被清华学神尹成大魔王专业翻译分析并修改

尹成QQ77025077

尹成微信18510341407

尹成所在QQ群721929980

尹成邮箱 yinc13@mails.tsinghua.edu.cn

尹成毕业于清华大学,微软区块链领域全球最有价值专家

https://mvp.microsoft.com/zh-cn/PublicProfile/4033620

Go Ethereum

Official golang implementation of the Ethereum protocol.

Automated builds are available for stable releases and the unstable master branch. Binary archives are published at https://geth.ethereum.org/downloads/.

Building the source

For prerequisites and detailed build instructions please read the Installation Instructions on the wiki.

Building geth requires both a Go (version 1.9 or later) and a C compiler. You can install them using your favourite package manager. Once the dependencies are installed, run

make geth

or, to build the full suite of utilities:

make all

Executables

The go-ethereum project comes with several wrappers/executables found in the cmd directory.

Command	Description
geth	Our main Ethereum CLI client. It is the entry point into the Ethereum network (main-, test- or private net), capable of running as a full node (default), archive node (retaining all historical state) or a light node (retrieving data live). It can be used by other processes as a gateway into the Ethereum network via JSON RPC endpoints exposed on top of HTTP, WebSocket and/or IPC transports. geth --help and the CLI Wiki page for command line options.
abigen	Source code generator to convert Ethereum contract definitions into easy to use, compile-time type-safe Go packages. It operates on plain Ethereum contract ABIs with expanded functionality if the contract bytecode is also available. However it also accepts Solidity source files, making development much more streamlined. Please see our Native DApps wiki page for details.
bootnode	Stripped down version of our Ethereum client implementation that only takes part in the network node discovery protocol, but does not run any of the higher level application protocols. It can be used as a lightweight bootstrap node to aid in finding peers in private networks.
evm	Developer utility version of the EVM (Ethereum Virtual Machine) that is capable of running bytecode snippets within a configurable environment and execution mode. Its purpose is to allow isolated, fine-grained debugging of EVM opcodes (e.g. evm --code 60ff60ff --debug).
gethrpctest	Developer utility tool to support our ethereum/rpc-test test suite which validates baseline conformity to the Ethereum JSON RPC specs. Please see the test suite's readme for details.
rlpdump	Developer utility tool to convert binary RLP (Recursive Length Prefix) dumps (data encoding used by the Ethereum protocol both network as well as consensus wise) to user friendlier hierarchical representation (e.g. rlpdump --hex CE0183FFFFFFC4C304050583616263).
swarm	Swarm daemon and tools. This is the entrypoint for the Swarm network. swarm --help for command line options and subcommands. See Swarm README for more information.
puppeth	a CLI wizard that aids in creating a new Ethereum network.

Running geth

Going through all the possible command line flags is out of scope here (please consult our CLI Wiki page), but we've enumerated a few common parameter combos to get you up to speed quickly on how you can run your own Geth instance.

Full node on the main Ethereum network

By far the most common scenario is people wanting to simply interact with the Ethereum network: create accounts; transfer funds; deploy and interact with contracts. For this particular use-case the user doesn't care about years-old historical data, so we can fast-sync quickly to the current state of the network. To do so:

$ geth console

This command will:

• Start geth in fast sync mode (default, can be changed with the --syncmode flag), causing it to download more data in exchange for avoiding processing the entire history of the Ethereum network, which is very CPU intensive.
• Start up Geth's built-in interactive JavaScript console, (via the trailing console subcommand) through which you can invoke all official web3 methods as well as Geth's own management APIs. This tool is optional and if you leave it out you can always attach to an already running Geth instance with geth attach.

Full node on the Ethereum test network

Transitioning towards developers, if you'd like to play around with creating Ethereum contracts, you almost certainly would like to do that without any real money involved until you get the hang of the entire system. In other words, instead of attaching to the main network, you want to join the test network with your node, which is fully equivalent to the main network, but with play-Ether only.

$ geth --testnet console

The console subcommand have the exact same meaning as above and they are equally useful on the testnet too. Please see above for their explanations if you've skipped to here.

Specifying the --testnet flag however will reconfigure your Geth instance a bit:

• Instead of using the default data directory (~/.ethereum on Linux for example), Geth will nest itself one level deeper into a testnet subfolder (~/.ethereum/testnet on Linux). Note, on OSX and Linux this also means that attaching to a running testnet node requires the use of a custom endpoint since geth attach will try to attach to a production node endpoint by default. E.g. geth attach <datadir>/testnet/geth.ipc. Windows users are not affected by this.
• Instead of connecting the main Ethereum network, the client will connect to the test network, which uses different P2P bootnodes, different network IDs and genesis states.

Note: Although there are some internal protective measures to prevent transactions from crossing over between the main network and test network, you should make sure to always use separate accounts for play-money and real-money. Unless you manually move accounts, Geth will by default correctly separate the two networks and will not make any accounts available between them.

Full node on the Rinkeby test network

The above test network is a cross client one based on the ethash proof-of-work consensus algorithm. As such, it has certain extra overhead and is more susceptible to reorganization attacks due to the network's low difficulty / security. Go Ethereum also supports connecting to a proof-of-authority based test network called Rinkeby (operated by members of the community). This network is lighter, more secure, but is only supported by go-ethereum.

$ geth --rinkeby console

Configuration

As an alternative to passing the numerous flags to the geth binary, you can also pass a configuration file via:

$ geth --config /path/to/your_config.toml

To get an idea how the file should look like you can use the dumpconfig subcommand to export your existing configuration:

$ geth --your-favourite-flags dumpconfig

Note: This works only with geth v1.6.0 and above.

Docker quick start

One of the quickest ways to get Ethereum up and running on your machine is by using Docker:

docker run -d --name ethereum-node -v /Users/alice/ethereum:/root \
           -p 8545:8545 -p 30303:30303 \
           ethereum/client-go

This will start geth in fast-sync mode with a DB memory allowance of 1GB just as the above command does. It will also create a persistent volume in your home directory for saving your blockchain as well as map the default ports. There is also an alpine tag available for a slim version of the image.

Do not forget --rpcaddr 0.0.0.0, if you want to access RPC from other containers and/or hosts. By default, geth binds to the local interface and RPC endpoints is not accessible from the outside.

Programatically interfacing Geth nodes

As a developer, sooner rather than later you'll want to start interacting with Geth and the Ethereum network via your own programs and not manually through the console. To aid this, Geth has built-in support for a JSON-RPC based APIs (standard APIs and Geth specific APIs). These can be exposed via HTTP, WebSockets and IPC (unix sockets on unix based platforms, and named pipes on Windows).

The IPC interface is enabled by default and exposes all the APIs supported by Geth, whereas the HTTP and WS interfaces need to manually be enabled and only expose a subset of APIs due to security reasons. These can be turned on/off and configured as you'd expect.

HTTP based JSON-RPC API options:

• --rpc Enable the HTTP-RPC server
• --rpcaddr HTTP-RPC server listening interface (default: "localhost")
• --rpcport HTTP-RPC server listening port (default: 8545)
• --rpcapi API's offered over the HTTP-RPC interface (default: "eth,net,web3")
• --rpccorsdomain Comma separated list of domains from which to accept cross origin requests (browser enforced)
• --ws Enable the WS-RPC server
• --wsaddr WS-RPC server listening interface (default: "localhost")
• --wsport WS-RPC server listening port (default: 8546)
• --wsapi API's offered over the WS-RPC interface (default: "eth,net,web3")
• --wsorigins Origins from which to accept websockets requests
• --ipcdisable Disable the IPC-RPC server
• --ipcapi API's offered over the IPC-RPC interface (default: "admin,debug,eth,miner,net,personal,shh,txpool,web3")
• --ipcpath Filename for IPC socket/pipe within the datadir (explicit paths escape it)

You'll need to use your own programming environments' capabilities (libraries, tools, etc) to connect via HTTP, WS or IPC to a Geth node configured with the above flags and you'll need to speak JSON-RPC on all transports. You can reuse the same connection for multiple requests!

Note: Please understand the security implications of opening up an HTTP/WS based transport before doing so! Hackers on the internet are actively trying to subvert Ethereum nodes with exposed APIs! Further, all browser tabs can access locally running webservers, so malicious webpages could try to subvert locally available APIs!

Operating a private network

Maintaining your own private network is more involved as a lot of configurations taken for granted in the official networks need to be manually set up.

Defining the private genesis state

First, you'll need to create the genesis state of your networks, which all nodes need to be aware of and agree upon. This consists of a small JSON file (e.g. call it genesis.json):

{
  "config": {
        "chainId": 0,
        "homesteadBlock": 0,
        "eip155Block": 0,
        "eip158Block": 0
    },
  "alloc"      : {},
  "coinbase"   : "0x0000000000000000000000000000000000000000",
  "difficulty" : "0x20000",
  "extraData"  : "",
  "gasLimit"   : "0x2fefd8",
  "nonce"      : "0x0000000000000042",
  "mixhash"    : "0x0000000000000000000000000000000000000000000000000000000000000000",
  "parentHash" : "0x0000000000000000000000000000000000000000000000000000000000000000",
  "timestamp"  : "0x00"
}

The above fields should be fine for most purposes, although we'd recommend changing the nonce to some random value so you prevent unknown remote nodes from being able to connect to you. If you'd like to pre-fund some accounts for easier testing, you can populate the alloc field with account configs:

"alloc": {
  "0x0000000000000000000000000000000000000001": {"balance": "111111111"},
  "0x0000000000000000000000000000000000000002": {"balance": "222222222"}
}

With the genesis state defined in the above JSON file, you'll need to initialize every Geth node with it prior to starting it up to ensure all blockchain parameters are correctly set:

$ geth init path/to/genesis.json

Creating the rendezvous point

With all nodes that you want to run initialized to the desired genesis state, you'll need to start a bootstrap node that others can use to find each other in your network and/or over the internet. The clean way is to configure and run a dedicated bootnode:

$ bootnode --genkey=boot.key
$ bootnode --nodekey=boot.key

With the bootnode online, it will display an enode URL that other nodes can use to connect to it and exchange peer information. Make sure to replace the displayed IP address information (most probably [::]) with your externally accessible IP to get the actual enode URL.

Note: You could also use a full fledged Geth node as a bootnode, but it's the less recommended way.

Starting up your member nodes

With the bootnode operational and externally reachable (you can try telnet <ip> <port> to ensure it's indeed reachable), start every subsequent Geth node pointed to the bootnode for peer discovery via the --bootnodes flag. It will probably also be desirable to keep the data directory of your private network separated, so do also specify a custom --datadir flag.

$ geth --datadir=path/to/custom/data/folder --bootnodes=<bootnode-enode-url-from-above>

Note: Since your network will be completely cut off from the main and test networks, you'll also need to configure a miner to process transactions and create new blocks for you.

Running a private miner

Mining on the public Ethereum network is a complex task as it's only feasible using GPUs, requiring an OpenCL or CUDA enabled ethminer instance. For information on such a setup, please consult the EtherMining subreddit and the Genoil miner repository.

In a private network setting however, a single CPU miner instance is more than enough for practical purposes as it can produce a stable stream of blocks at the correct intervals without needing heavy resources (consider running on a single thread, no need for multiple ones either). To start a Geth instance for mining, run it with all your usual flags, extended by:

$ geth <usual-flags> --mine --minerthreads=1 --etherbase=0x0000000000000000000000000000000000000000

Which will start mining blocks and transactions on a single CPU thread, crediting all proceedings to the account specified by --etherbase. You can further tune the mining by changing the default gas limit blocks converge to (--targetgaslimit) and the price transactions are accepted at (--gasprice).

Contribution

Thank you for considering to help out with the source code! We welcome contributions from anyone on the internet, and are grateful for even the smallest of fixes!

If you'd like to contribute to go-ethereum, please fork, fix, commit and send a pull request for the maintainers to review and merge into the main code base. If you wish to submit more complex changes though, please check up with the core devs first on our gitter channel to ensure those changes are in line with the general philosophy of the project and/or get some early feedback which can make both your efforts much lighter as well as our review and merge procedures quick and simple.

Please make sure your contributions adhere to our coding guidelines:

• Code must adhere to the official Go formatting guidelines (i.e. uses gofmt).
• Code must be documented adhering to the official Go commentary guidelines.
• Pull requests need to be based on and opened against the master branch.
• Commit messages should be prefixed with the package(s) they modify.
  • E.g. "eth, rpc: make trace configs optional"

Please see the Developers' Guide for more details on configuring your environment, managing project dependencies and testing procedures.

License

The go-ethereum library (i.e. all code outside of the cmd directory) is licensed under the GNU Lesser General Public License v3.0, also included in our repository in the COPYING.LESSER file.

The go-ethereum binaries (i.e. all code inside of the cmd directory) is licensed under the GNU General Public License v3.0, also included in our repository in the COPYING file.

Documentation

Overview

包以太坊定义了与以太坊交互的接口。

Index

• Variables
• type CallMsg
• type ChainReader
• type ChainStateReader
• type ChainSyncReader
• type ContractCaller
• type FilterQuery
• type GasEstimator
• type GasPricer
• type LogFilterer
• type PendingContractCaller
• type PendingStateEventer
• type PendingStateReader
• type Subscription
• type SyncProgress
• type TransactionReader
• type TransactionSender

Variables

var NotFound = errors.New("not found")

如果请求的项不存在，则API方法将返回NotFound。

Types

type CallMsg

type CallMsg struct {
	From     common.Address  //“交易”的发送方
	To       *common.Address //目的地合同（合同创建为零）
	Gas      uint64          //如果为0，则调用以接近无穷大的气体执行。
	GasPrice *big.Int        //气体交换率
	Value    *big.Int        //随呼叫发送的wei数量
	Data     []byte          //输入数据，通常是ABI编码的合同方法调用
}

callmsg包含合同调用的参数。

type ChainReader

type ChainReader interface {
	BlockByHash(ctx context.Context, hash common.Hash) (*types.Block, error)
	BlockByNumber(ctx context.Context, number *big.Int) (*types.Block, error)
	HeaderByHash(ctx context.Context, hash common.Hash) (*types.Header, error)
	HeaderByNumber(ctx context.Context, number *big.Int) (*types.Header, error)
	TransactionCount(ctx context.Context, blockHash common.Hash) (uint, error)
	TransactionInBlock(ctx context.Context, blockHash common.Hash, index uint) (*types.Transaction, error)

	//此方法订阅有关
	//规范链。
	SubscribeNewHead(ctx context.Context, ch chan<- *types.Header) (Subscription, error)
}

ChainReader提供对区块链的访问。此接口中的方法访问原始 来自规范链（按块号请求时）或任何 以前由节点下载和处理的区块链分支。街区 number参数可以为nil以选择最新的规范块。读取块头 应尽可能优先于全块。

如果请求的项不存在，则找不到返回的错误。

type ChainStateReader

type ChainStateReader interface {
	BalanceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (*big.Int, error)
	StorageAt(ctx context.Context, account common.Address, key common.Hash, blockNumber *big.Int) ([]byte, error)
	CodeAt(ctx context.Context, account common.Address, blockNumber *big.Int) ([]byte, error)
	NonceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (uint64, error)
}

ChainStateReader包装对规范区块链的状态trie的访问。注意 接口的实现可能无法返回旧块的状态值。 在许多情况下，使用CallContract比读取原始合同存储更可取。

type ChainSyncReader

type ChainSyncReader interface {
	SyncProgress(ctx context.Context) (*SyncProgress, error)
}

ChainSyncReader将访问打包到节点的当前同步状态。如果没有 同步当前正在运行，它返回零。

type ContractCaller

type ContractCaller interface {
	CallContract(ctx context.Context, call CallMsg, blockNumber *big.Int) ([]byte, error)
}

A ContractCaller provides contract calls, essentially transactions that are executed by EVM，但没有挖掘到区块链中。ContractCall是用于 执行此类调用。对于围绕特定合同构建的应用程序， AbigEn工具提供了一种更好的、正确类型的执行调用的方法。

type FilterQuery

type FilterQuery struct {
	BlockHash *common.Hash     //used by eth_getLogs, return logs only from block with this hash
	FromBlock *big.Int         //查询范围的开始，零表示Genesis块
	ToBlock   *big.Int         //范围结束，零表示最新块
	Addresses []common.Address //restricts matches to events created by specific contracts

	//主题列表限制与特定事件主题的匹配。每个事件都有一个列表
	//话题。Topics matches a prefix of that list. An empty element slice matches any
	//话题。非空元素表示与
	//包含的主题。
	//
	//实例：
	//或零匹配任何主题列表
	//{{A}}              matches topic A in first position
	//，b匹配第一位置的任何主题，B匹配第二位置的任何主题
	//A，B匹配第一位置的主题A，第二位置的主题B
	//A，B，C，D匹配第一位置的主题（A或B），第二位置的主题（C或D）
	Topics [][]common.Hash
}

filterquery包含用于合同日志筛选的选项。

type GasEstimator

type GasEstimator interface {
	EstimateGas(ctx context.Context, call CallMsg) (uint64, error)
}

GasEstimator包装EstimateGas，它试图估计执行 基于未决状态的特定事务。不能保证这是 真正的天然气限制要求，因为其他交易可能由矿工添加或删除，但 它应为设定合理违约提供依据。

type GasPricer

type GasPricer interface {
	SuggestGasPrice(ctx context.Context) (*big.Int, error)
}

Gasparicer包装了天然气价格甲骨文，甲骨文监控区块链以确定 在当前收费市场条件下的最优天然气价格。

type LogFilterer

type LogFilterer interface {
	FilterLogs(ctx context.Context, q FilterQuery) ([]types.Log, error)
	SubscribeFilterLogs(ctx context.Context, q FilterQuery, ch chan<- types.Log) (Subscription, error)
}

LogFilter提供使用一次性查询或连续查询访问合同日志事件的权限 事件订阅。

Logs received through a streaming query subscription may have Removed set to true, 指示由于链重组而恢复日志。

type PendingContractCaller

type PendingContractCaller interface {
	PendingCallContract(ctx context.Context, call CallMsg) ([]byte, error)
}

PendingContractCaller可用于对挂起状态执行调用。

type PendingStateEventer

type PendingStateEventer interface {
	SubscribePendingTransactions(ctx context.Context, ch chan<- *types.Transaction) (Subscription, error)
}

PendingStateEventer提供对 悬而未决的状态。

type PendingStateReader

type PendingStateReader interface {
	PendingBalanceAt(ctx context.Context, account common.Address) (*big.Int, error)
	PendingStorageAt(ctx context.Context, account common.Address, key common.Hash) ([]byte, error)
	PendingCodeAt(ctx context.Context, account common.Address) ([]byte, error)
	PendingNonceAt(ctx context.Context, account common.Address) (uint64, error)
	PendingTransactionCount(ctx context.Context) (uint, error)
}

一个PungStuteReDead提供对挂起状态的访问，这是所有结果的结果。 尚未包含在区块链中的已知可执行交易。它是 通常用于显示“未确认”操作的结果（例如钱包价值 传输）由用户启动。PendingNoncoat操作是一种很好的方法 检索特定帐户的下一个可用事务。

type Subscription

type Subscription interface {
	//Unsubscribe cancels the sending of events to the data channel
	//关闭错误通道。
	Unsubscribe()
	//err返回订阅错误通道。错误通道接收
	//如果订阅存在问题（例如网络连接）的值
	//传递活动已关闭）。将只发送一个值。
	//通过退订来关闭错误通道。
	Err() <-chan error
}

订阅表示事件订阅，其中 通过数据通道传送。

type SyncProgress

type SyncProgress struct {
	StartingBlock uint64 //Block number where sync began
	CurrentBlock  uint64 //同步所在的当前块号
	HighestBlock  uint64 //链中最高的声称块数
	PulledStates  uint64 //已下载的状态trie条目数
	KnownStates   uint64 //已知的State Trie条目的总数
}

当节点与 以太坊网络。

type TransactionReader

type TransactionReader interface {
	//TransactionByHash除了检查
	//块链。ISPUPDATE返回值指示事务是否已被关闭。
	//开采了。请注意，事务可能不是规范链的一部分，即使
	//它没有挂起。
	TransactionByHash(ctx context.Context, txHash common.Hash) (tx *types.Transaction, isPending bool, err error)
	//TransactionReceipt返回挖掘的事务的收据。请注意
	//事务可能不包括在当前规范链中，即使收据
	//存在。
	TransactionReceipt(ctx context.Context, txHash common.Hash) (*types.Receipt, error)
}

TransactionReader提供对过去事务及其收据的访问。 实施可能会对以下交易和收据施加任意限制： can be retrieved. Historic transactions may not be available.

尽可能避免依赖此接口。合同日志（通过日志过滤器 接口）更可靠，在有链条的情况下通常更安全。 重组。

如果请求的项不存在，则找不到返回的错误。

type TransactionSender

type TransactionSender interface {
	SendTransaction(ctx context.Context, tx *types.Transaction) error
}

TransactionSender包装事务发送。sendTransaction方法注入 已将事务签名到挂起的事务池中以供执行。如果交易 是合同创建的，TransactionReceipt方法可用于检索 挖掘交易记录后的合同地址。

必须对该事务进行签名并包含一个有效的nonce。消费者 API可以使用包帐户来维护本地私钥，并且需要检索 下一个可用的nonce使用pendingnonceat。