github.com/ethw3/go-ethereuma@v0.0.0-20221013053120-c14602a4c23c/node/doc.go (about)

     1  // Copyright 2016 The go-ethereum Authors
     2  // This file is part of the go-ethereum library.
     3  //
     4  // The go-ethereum library is free software: you can redistribute it and/or modify
     5  // it under the terms of the GNU Lesser General Public License as published by
     6  // the Free Software Foundation, either version 3 of the License, or
     7  // (at your option) any later version.
     8  //
     9  // The go-ethereum library is distributed in the hope that it will be useful,
    10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
    11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    12  // GNU Lesser General Public License for more details.
    13  //
    14  // You should have received a copy of the GNU Lesser General Public License
    15  // along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
    16  
    17  /*
    18  Package node sets up multi-protocol Ethereum nodes.
    19  
    20  In the model exposed by this package, a node is a collection of services which use shared
    21  resources to provide RPC APIs. Services can also offer devp2p protocols, which are wired
    22  up to the devp2p network when the node instance is started.
    23  
    24  
    25  Node Lifecycle
    26  
    27  The Node object has a lifecycle consisting of three basic states, INITIALIZING, RUNNING
    28  and CLOSED.
    29  
    30  
    31      ●───────┐
    32           New()
    33              │
    34              ▼
    35        INITIALIZING ────Start()─┐
    36              │                  │
    37              │                  ▼
    38          Close()             RUNNING
    39              │                  │
    40              ▼                  │
    41           CLOSED ◀──────Close()─┘
    42  
    43  
    44  Creating a Node allocates basic resources such as the data directory and returns the node
    45  in its INITIALIZING state. Lifecycle objects, RPC APIs and peer-to-peer networking
    46  protocols can be registered in this state. Basic operations such as opening a key-value
    47  database are permitted while initializing.
    48  
    49  Once everything is registered, the node can be started, which moves it into the RUNNING
    50  state. Starting the node starts all registered Lifecycle objects and enables RPC and
    51  peer-to-peer networking. Note that no additional Lifecycles, APIs or p2p protocols can be
    52  registered while the node is running.
    53  
    54  Closing the node releases all held resources. The actions performed by Close depend on the
    55  state it was in. When closing a node in INITIALIZING state, resources related to the data
    56  directory are released. If the node was RUNNING, closing it also stops all Lifecycle
    57  objects and shuts down RPC and peer-to-peer networking.
    58  
    59  You must always call Close on Node, even if the node was not started.
    60  
    61  
    62  Resources Managed By Node
    63  
    64  All file-system resources used by a node instance are located in a directory called the
    65  data directory. The location of each resource can be overridden through additional node
    66  configuration. The data directory is optional. If it is not set and the location of a
    67  resource is otherwise unspecified, package node will create the resource in memory.
    68  
    69  To access to the devp2p network, Node configures and starts p2p.Server. Each host on the
    70  devp2p network has a unique identifier, the node key. The Node instance persists this key
    71  across restarts. Node also loads static and trusted node lists and ensures that knowledge
    72  about other hosts is persisted.
    73  
    74  JSON-RPC servers which run HTTP, WebSocket or IPC can be started on a Node. RPC modules
    75  offered by registered services will be offered on those endpoints. Users can restrict any
    76  endpoint to a subset of RPC modules. Node itself offers the "debug", "admin" and "web3"
    77  modules.
    78  
    79  Service implementations can open LevelDB databases through the service context. Package
    80  node chooses the file system location of each database. If the node is configured to run
    81  without a data directory, databases are opened in memory instead.
    82  
    83  Node also creates the shared store of encrypted Ethereum account keys. Services can access
    84  the account manager through the service context.
    85  
    86  
    87  Sharing Data Directory Among Instances
    88  
    89  Multiple node instances can share a single data directory if they have distinct instance
    90  names (set through the Name config option). Sharing behaviour depends on the type of
    91  resource.
    92  
    93  devp2p-related resources (node key, static/trusted node lists, known hosts database) are
    94  stored in a directory with the same name as the instance. Thus, multiple node instances
    95  using the same data directory will store this information in different subdirectories of
    96  the data directory.
    97  
    98  LevelDB databases are also stored within the instance subdirectory. If multiple node
    99  instances use the same data directory, opening the databases with identical names will
   100  create one database for each instance.
   101  
   102  The account key store is shared among all node instances using the same data directory
   103  unless its location is changed through the KeyStoreDir configuration option.
   104  
   105  
   106  Data Directory Sharing Example
   107  
   108  In this example, two node instances named A and B are started with the same data
   109  directory. Node instance A opens the database "db", node instance B opens the databases
   110  "db" and "db-2". The following files will be created in the data directory:
   111  
   112     data-directory/
   113          A/
   114              nodekey            -- devp2p node key of instance A
   115              nodes/             -- devp2p discovery knowledge database of instance A
   116              db/                -- LevelDB content for "db"
   117          A.ipc                  -- JSON-RPC UNIX domain socket endpoint of instance A
   118          B/
   119              nodekey            -- devp2p node key of node B
   120              nodes/             -- devp2p discovery knowledge database of instance B
   121              static-nodes.json  -- devp2p static node list of instance B
   122              db/                -- LevelDB content for "db"
   123              db-2/              -- LevelDB content for "db-2"
   124          B.ipc                  -- JSON-RPC UNIX domain socket endpoint of instance B
   125          keystore/              -- account key store, used by both instances
   126  */
   127  package node