123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127 |
- // Copyright 2016 The go-ethereum Authors
- // This file is part of the go-ethereum library.
- //
- // The go-ethereum library is free software: you can redistribute it and/or modify
- // it under the terms of the GNU Lesser General Public License as published by
- // the Free Software Foundation, either version 3 of the License, or
- // (at your option) any later version.
- //
- // The go-ethereum library is distributed in the hope that it will be useful,
- // but WITHOUT ANY WARRANTY; without even the implied warranty of
- // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- // GNU Lesser General Public License for more details.
- //
- // You should have received a copy of the GNU Lesser General Public License
- // along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
- /*
- Package node sets up multi-protocol Ethereum nodes.
- In the model exposed by this package, a node is a collection of services which use shared
- resources to provide RPC APIs. Services can also offer devp2p protocols, which are wired
- up to the devp2p network when the node instance is started.
- Node Lifecycle
- The Node object has a lifecycle consisting of three basic states, INITIALIZING, RUNNING
- and CLOSED.
- ●───────┐
- New()
- │
- ▼
- INITIALIZING ────Start()─┐
- │ │
- │ ▼
- Close() RUNNING
- │ │
- ▼ │
- CLOSED ◀──────Close()─┘
- Creating a Node allocates basic resources such as the data directory and returns the node
- in its INITIALIZING state. Lifecycle objects, RPC APIs and peer-to-peer networking
- protocols can be registered in this state. Basic operations such as opening a key-value
- database are permitted while initializing.
- Once everything is registered, the node can be started, which moves it into the RUNNING
- state. Starting the node starts all registered Lifecycle objects and enables RPC and
- peer-to-peer networking. Note that no additional Lifecycles, APIs or p2p protocols can be
- registered while the node is running.
- Closing the node releases all held resources. The actions performed by Close depend on the
- state it was in. When closing a node in INITIALIZING state, resources related to the data
- directory are released. If the node was RUNNING, closing it also stops all Lifecycle
- objects and shuts down RPC and peer-to-peer networking.
- You must always call Close on Node, even if the node was not started.
- Resources Managed By Node
- All file-system resources used by a node instance are located in a directory called the
- data directory. The location of each resource can be overridden through additional node
- configuration. The data directory is optional. If it is not set and the location of a
- resource is otherwise unspecified, package node will create the resource in memory.
- To access to the devp2p network, Node configures and starts p2p.Server. Each host on the
- devp2p network has a unique identifier, the node key. The Node instance persists this key
- across restarts. Node also loads static and trusted node lists and ensures that knowledge
- about other hosts is persisted.
- JSON-RPC servers which run HTTP, WebSocket or IPC can be started on a Node. RPC modules
- offered by registered services will be offered on those endpoints. Users can restrict any
- endpoint to a subset of RPC modules. Node itself offers the "debug", "admin" and "web3"
- modules.
- Service implementations can open LevelDB databases through the service context. Package
- node chooses the file system location of each database. If the node is configured to run
- without a data directory, databases are opened in memory instead.
- Node also creates the shared store of encrypted Ethereum account keys. Services can access
- the account manager through the service context.
- Sharing Data Directory Among Instances
- Multiple node instances can share a single data directory if they have distinct instance
- names (set through the Name config option). Sharing behaviour depends on the type of
- resource.
- devp2p-related resources (node key, static/trusted node lists, known hosts database) are
- stored in a directory with the same name as the instance. Thus, multiple node instances
- using the same data directory will store this information in different subdirectories of
- the data directory.
- LevelDB databases are also stored within the instance subdirectory. If multiple node
- instances use the same data directory, opening the databases with identical names will
- create one database for each instance.
- The account key store is shared among all node instances using the same data directory
- unless its location is changed through the KeyStoreDir configuration option.
- Data Directory Sharing Example
- In this example, two node instances named A and B are started with the same data
- directory. Node instance A opens the database "db", node instance B opens the databases
- "db" and "db-2". The following files will be created in the data directory:
- data-directory/
- A/
- nodekey -- devp2p node key of instance A
- nodes/ -- devp2p discovery knowledge database of instance A
- db/ -- LevelDB content for "db"
- A.ipc -- JSON-RPC UNIX domain socket endpoint of instance A
- B/
- nodekey -- devp2p node key of node B
- nodes/ -- devp2p discovery knowledge database of instance B
- static-nodes.json -- devp2p static node list of instance B
- db/ -- LevelDB content for "db"
- db-2/ -- LevelDB content for "db-2"
- B.ipc -- JSON-RPC UNIX domain socket endpoint of instance B
- keystore/ -- account key store, used by both instances
- */
- package node
|