github.com/klaytn/klaytn@v1.10.2/node/doc.go (about)

     1  // Copyright 2018 The klaytn Authors
     2  // Copyright 2016 The go-ethereum Authors
     3  // This file is part of the go-ethereum library.
     4  //
     5  // The go-ethereum library is free software: you can redistribute it and/or modify
     6  // it under the terms of the GNU Lesser General Public License as published by
     7  // the Free Software Foundation, either version 3 of the License, or
     8  // (at your option) any later version.
     9  //
    10  // The go-ethereum library is distributed in the hope that it will be useful,
    11  // but WITHOUT ANY WARRANTY; without even the implied warranty of
    12  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    13  // GNU Lesser General Public License for more details.
    14  //
    15  // You should have received a copy of the GNU Lesser General Public License
    16  // along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
    17  //
    18  // This file is derived from node/doc.go (2018/06/04).
    19  // Modified and improved for the klaytn development.
    20  
    21  /*
    22  Package node sets up multi-protocol Klaytn nodes.
    23  
    24  In the model exposed by this package, a node is a collection of services which use shared
    25  resources to provide RPC APIs. Services can also offer devp2p protocols, which are wired
    26  up to the devp2p network when the node instance is started.
    27  
    28  
    29  Resources Managed By Node
    30  
    31  All file-system resources used by a node instance are located in a directory called the
    32  data directory. The location of each resource can be overridden through additional node
    33  configuration. The data directory is optional. If it is not set and the location of a
    34  resource is otherwise unspecified, package node will create the resource in memory.
    35  
    36  To access to the devp2p network, Node configures and starts p2p.Server. Each host on the
    37  devp2p network has a unique identifier, the node key. The Node instance persists this key
    38  across restarts. Node also loads static and trusted node lists and ensures that knowledge
    39  about other hosts is persisted.
    40  
    41  JSON-RPC servers which run HTTP, WebSocket or IPC can be started on a Node. RPC modules
    42  offered by registered services will be offered on those endpoints. Users can restrict any
    43  endpoint to a subset of RPC modules. Node itself offers the "debug", "admin" and "web3"
    44  modules.
    45  
    46  Service implementations can open LevelDB databases through the service context. Package
    47  node chooses the file system location of each database. If the node is configured to run
    48  without a data directory, databases are opened in memory instead.
    49  
    50  Node also creates the shared store of encrypted Klaytn account keys. Services can access
    51  the account manager through the service context.
    52  
    53  
    54  Sharing Data Directory Among Instances
    55  
    56  Multiple node instances can share a single data directory if they have distinct instance
    57  names (set through the Name config option). Sharing behaviour depends on the type of
    58  resource.
    59  
    60  devp2p-related resources (node key, static/trusted node lists, known hosts database) are
    61  stored in a directory with the same name as the instance. Thus, multiple node instances
    62  using the same data directory will store this information in different subdirectories of
    63  the data directory.
    64  
    65  LevelDB databases are also stored within the instance subdirectory. If multiple node
    66  instances use the same data directory, openening the databases with identical names will
    67  create one database for each instance.
    68  
    69  The account key store is shared among all node instances using the same data directory
    70  unless its location is changed through the KeyStoreDir configuration option.
    71  
    72  
    73  Data Directory Sharing Example
    74  
    75  In this example, two node instances named A and B are started with the same data
    76  directory. Mode instance A opens the database "db", node instance B opens the databases
    77  "db" and "db-2". The following files will be created in the data directory:
    78  
    79     data-directory/
    80          A/
    81              nodekey            -- devp2p node key of instance A
    82              nodes/             -- devp2p discovery knowledge database of instance A
    83              db/                -- LevelDB content for "db"
    84          A.ipc                  -- JSON-RPC UNIX domain socket endpoint of instance A
    85          B/
    86              nodekey            -- devp2p node key of node B
    87              nodes/             -- devp2p discovery knowledge database of instance B
    88              static-nodes.json  -- devp2p static node list of instance B
    89              db/                -- LevelDB content for "db"
    90              db-2/              -- LevelDB content for "db-2"
    91          B.ipc                  -- JSON-RPC UNIX domain socket endpoint of instance A
    92          keystore/              -- account key store, used by both instances
    93  
    94  Source Files
    95  
    96  Functions and variables related to Node are defined in the files listed below
    97    - config.go            : Define the Config type for node creation
    98    - config_test.go       : Functions for testing the Config type
    99    - defaults.go          : Defines default values used in node package
   100    - errors.go            : Defines errors used in node package
   101    - node.go              : Defines a p2p node and functions for the node operation
   102    - node_example_test.go : Functions for testing the sample Service
   103    - node_test.go         : Test functions for testing the Node type
   104    - service.go           : Defines Service, Service is an individual protocol that can be registered into a node
   105    - service_test.go      : Functions for testing the Service
   106    - api.go               : Administrative APIs
   107    - utils_test.go        : Define InstrumentedService type for node test
   108  */
   109  package node