quorum/docs/How-To-Guides/adding_nodes.md

# Adding nodes to the network

Adding new nodes to an existing network can range from a common occurence to never happening.
In public blockchains, such as the Ethereum Mainnet, new nodes continuously join and talk to the existing network.
In permissioned blockchains, this may not happen as often, but it still an important task to achieve as your network 
evolves.

When adding new nodes to the network, it is important understand that the Quorum network and Private Transaction 
Manager network are distinct and do not overlap in any way. Therefore, options applicable to one are not applicable to 
the other. In some cases, they may have their own options to achieve similar tasks, but must be specified separately.

## Prerequisites

- [Quorum installed](/Getting%20Started/Installing.md)
- [Tessera/Constellation installed](/Getting%20Started/Installing.md) if using private transactions
- A running network (see [Creating a Network From Scratch](/Getting%20Started/Creating-A-Network-From-Scratch))

## Adding Quorum nodes

Adding a new Quorum node is the most common operation, as you can choose to run a Quorum node with or without a Private 
Transaction Manager, but rarely will one do the opposite.

### Raft

1. On an *existing* node, add the new peer to the raft network
    ```
    > raft.addPeer("enode://239c1f044a2b03b6c4713109af036b775c5418fe4ca63b04b1ce00124af00ddab7cc088fc46020cdc783b6207efe624551be4c06a994993d8d70f684688fb7cf@127.0.0.1:21006?discport=0&raftport=50407")
    7
    ```
    
    So in this example, our new node has a Raft ID of `7`.

2. If you are using permissioning, or discovery for Ethereum p2p, please refer [here](#extra-options).

3. We now need to initialise the new node with the network's genesis configuration.

    !!! note
        Where you obtain this from will be dependent on the network. You may get it from an existing peer, or a network operator, or elsewhere entirely.

    Initialising the new node is exactly the same an the original nodes.
    ```bash
    $ geth --datadir qdata/dd7 init genesis.json
    ```

4. Now we can start up the new node and let it sync with the network. The main difference now is the use of the 
`--raftjoinexisting` flag, which lets the node know that it is joining an existing network, which is handled 
differently internally. The Raft ID obtained in step 1 is passed as a parameter to this flag.

    ```bash
    $ PRIVATE_CONFIG=ignore geth --datadir qdata/dd7 ... OTHER ARGS ... --raft --raftport 50407 --rpcport 22006 --port 21006 --raftjoinexisting 7
    ```
   
   The new node is now up and running, and will start syncing the blockchain from existing peers. Once this has 
   completed, it can send new transactions just as any other peer.

### IBFT/Clique

Adding nodes to an IBFT/Clique network is a bit simpler, as it only needs to configure itself rather then be 
pre-allocated on the network (permissioning aside).

1. Initialise the new node with the network's genesis configuration.
    
    !!! note
        Where you obtain this from will be dependent on the network. You may get it from an existing peer, or a network operator, or elsewhere entirely.

    Initialising the new node is exactly the same an the original nodes.
    ```bash
    $ geth --datadir qdata/dd7 init genesis.json
    ```

2. If you are using permissioning or discovery for Ethereum peer-to-peer, please refer [here](#extra-options).

3. Start the new node, pointing either to a `bootnode` or listing an existing peer in the `static-nodes.json` file. 
Once a connection is established, the node will start syncing the blockchain, after which transactions can be sent.

### Extra options

Some options take effect regardless of the consensus mechanism used.

#### Permissioned nodes

If using the `permissioned-nodes.json` file for permissioning, then you must make sure this file is updated on all 
nodes before the new node is able to communicate with existing nodes. You do not need to restart any nodes in 
order for the changes to take effect.

#### Static node connections

If not using peer-to-peer node discovery (i.e. you have specified `--nodiscover`), then the only connections a node 
made will be to peers defined in the `static-nodes.json` file. When adding a new node, you should make sure you have 
peers defined in its `static-nodes.json` file. The more peers you have defined here, the better network connectivity 
and fault tolerance you have.

!!! note
    * You do not need to update the existing peers static nodes for the connection to be established, although it is good practise to do so.
    * You do not need to specify every peer in your static nodes file if you do not wish to connect to every peer directly.

#### Peer-to-peer discovery

If you are using discovery, then more options *in addition* to static nodes become available.

- Any nodes that are connected to your peers, which at the start will be ones defined in the static node list, will 
then be visible by you, allowing you to connect to them; this is done automatically.

- You may specify any number of bootnodes, defined by the `--bootnodes` parameter. This takes a commas separated list 
of enode URIs, similar to the `static-nodes.json` file. These act in the same way as static nodes, letting you connect 
to them and then find out about other peers, whom you then connect to.

!!! note
    If you have discovery disabled, this means you will not try to find other nodes to connect to, but others can still find and connect to you.

## Adding Private Transaction Managers

In this tutorial, there will be no focus on the advanced features of adding a new Private Transaction Manager (PTM).
This tutorial uses [Tessera](https://github.com/jpmorganchase/tessera) for any examples.

Adding a new node to the PTM is relatively straight forward, but there are a lot of extra options that can be used, 
which is what will be explained here.

### Adding a new PTM node

In a basic setting, adding a new PTM node is as simple as making sure you have one of the existing nodes listed in your 
peer list.

In Tessera, this would equate to the following in the configuration file:
```json
{
  "peers": [
    {
      "url": "http://existingpeer1.com:8080"
    }
  ]
}
```

From there, Tessera will connect to that peer and discover all the other PTM nodes in the network, connecting to each 
of them in turn.

!!! note
    You may want to include multiple peers in the peer list in case any of them are offline/unreachable.
    
### IP whitelisting

The IP Whitelist that Tessera provides allows you restrict connections much like the `permissioned-nodes.json` file 
does for Quorum. Only IP addresses/hostnames listed in your peers list will be allowed to connect to you.

See the [Tessera configuration page](/Privacy/Tessera/Configuration/Configuration%20Overview#whitelist) for details on setting it up.

In order to make sure the new node is accepted into the network:

1. You will need to add the new peer to each of the existing nodes before communication is allowed.
    Tessera provides a way to do this without needing to restart an already running node:
    ```bash
    $ java -jar tessera.jar admin -configfile /path/to/existing-node-config.json -addpeer http://newpeer.com:8080
    ```
   
2. The new peer can be started, setting the `peers` configuration to mirror the existing network.
    e.g. if there are 3 existing nodes in the network, then the new nodes configuration will look like this:
    ```json
    {
      "peers": [
        {
          "url": "http://existingpeer1.com:8080"
        },
        {
          "url": "http://existingpeer2.com:8080"
        },
        {
          "url": "http://existingpeer3.com:8080"
        }
      ]
    }
    ```

    The new node will allow incoming connections from the existing peers, and then existing peers will allow incoming 
    connections from the new peer!
    
### Discovery

Tessera discovery is very similar to the IP whitelist. The difference being that the IP whitelist blocks 
communications between nodes, whereas disabling discovery only affects which public keys we keep track of.

See the [Tessera configuration page](/Privacy/Tessera/Configuration/Configuration%20Overview#disabling-peer-discovery) for 
details on setting it up.
   
When discovery is disabled, Tessera will only allow keys that are owned by a node in its peer list to be available to 
the users. This means that if any keys are found that are owned by a node NOT in our peer list, they are discarded and 
private transactions cannot be sent to that public key.

!!! note
    This does not affect incoming transactions. Someone not in your peer list can still send transactions to your node, unless you also enable the IP Whitelist option.
    
    
    
In order to make sure the new node is accepted into the network:

1. You will need to add the new peer to each of the existing nodes before they will accept public keys that are linked 
to the new peer.
    Tessera provides a way to do this without needing to restart an already running node:
    ```bash
    $ java -jar tessera.jar admin -configfile /path/to/existing-node-config.json -addpeer http://newpeer.com:8080
    ```
    
2. The new peer can be started, setting the `peers` configuration to mirror the existing network.
    e.g. if there are 3 existing nodes in the network, then the new nodes configuration will look like this:
    ```json
    {
      "peers": [
        {
          "url": "http://existingpeer1.com:8080"
        },
        {
          "url": "http://existingpeer2.com:8080"
        },
        {
          "url": "http://existingpeer3.com:8080"
        }
      ]
    }
    ```
    
    The new node will now record public keys belonging to the existing peers, and then existing peers will record 
    public keys belonging to the new peer; this allows private transactions to be sent both directions!
    
    
## Examples

For a walkthrough of some examples that put into action the above, check out [this guide](/How-To-Guides/add_node_examples)!