wiki/MoC-new.md

# ~~not-so~~ Easy steps to create a new network
(for the Master of Ceremony)

Prerequisites:
1. Plenty of time
2. Patience
3. New network's `NetworkID`
4. New network's `NetworkName`

## Chapter I - in which MoC creates his secret keys and never shows them to others

You will need to generate ethereum address and keystore file for the `owner`.  
One way is to download `etherwallet-v*.*.*.*.zip` archive of the latest release from myetherwallet github repo https://github.com/kvhnuke/etherwallet/releases/
then unplug your computer from the Internet, extract zip archive and open `index.html` in your browser.
Please be sure to use strong password, download keystore file `UTC--*--*`, your private key and keep them in a safe place.

## Chapter II - in which MoC forks first portion of repos and replaces some text

There are quite a few repositories that are used to run the network. You will need to fork them and later update parameters.
Please be consistent with naming of branches and use `NetworkName`.

### Configs on azure
https://github.com/poanetwork/deployment-azure/tree/dev-mainnet
1. Create a separate branch named `NetworkName`
```
git checkout dev-mainnet
git checkout -b NetworkName dev-mainnet
```
2. Don't change anything else, this repository is used only for configs now

### POA Network Consensus contract
https://github.com/poanetwork/poa-network-consensus-contracts
1. Create a separate branch named `NetworkName`
Steps 2-6 should be done if there are no files in `flat/` folder  
2. Clone it to your local machine
3. Install `python3`, `pip3`, `solc`: **make sure to use binary package for solc, not the one from npm** http://solidity.readthedocs.io/en/develop/installing-solidity.html#binary-packages
4. Install `pip3 install solidity-flattener`
5. Run `npm install`
6. Run `./make_flat.sh` to generate flat versions of contracts. They will be saved to `flat/`

7. Open [Remix](http://remix.ethereum.org/) in your browser, copy-paste code from `flat/PoaNetworkConsensus_flat.sol`, press "Start to compile".
8. On "Run" tab select "Javascript VM" as environment, "PoaNetworkConsensus" as your contract, in "Create" field paste MoC's address "0x..." and click "Create"
9. After the contract is compiled click "Details" button and copy it's bytecode

### Chain.json
https://github.com/poanetwork/poa-chain-spec
1. Create a separate branch named `NetworkName`

2. Change "name" to `NetworkName`.

3. In "params" block, change networkID to your `NetworkID` in hex.

**NOTE**: When creating Core and Sokol, there are additional steps:  
3.a. in "params" block change `stepDuration` to `5` (number)
```
"stepDuration": 5,
```
3.b. in "params" block add the following lines to swith unlces off:
```
    "maximumUncleCountTransition": 0,
    "maximumUncleCount": 0
```
3.c make sure all unnecessary contracts are removed from "accounts" block, only the one in "safeContract" should be left.

4. Scroll down to "accounts" block and replace constructor for "0xf472e0e43570b9afaab67089615080cf7c20018d" with bytecode you obtained from POA Network Consensus contract "0x606060..."

5. Replace address of account with huge amount of money with your MoC address

6. Open `bootnodes.txt` and remove all lines from this file

### Ansible playbook
https://github.com/poanetwork/deployment-playbooks
1. Create a separate branch named `NetworkName`
2. Open `group_vars/all.network` and replace the following variables with corresponding branch names (should be `NetworkName` mostly)
* `SCRIPTS_MOC_BRANCH`
* `SCRIPTS_VALIDATOR_BRANCH`
* `TEMPLATES_BRANCH`
* `GENESIS_BRANCH`
* `GENESIS_NETWORK_NAME` - **make sure it matches `name` in `spec.json`**
3. Replace `MOC_ADDRESS` with your MoC address
4. If you forked repos to your own github account, also replace the `MAIN_REPO_FETCH` value with your account name.
5. You may also want to replace
* `NODE_SOURCE_DEB` - node.js version
* `PARITY_BIN_LOC` - url to parity binary
* change `region`
* change `image` (see https://cloud-images.ubuntu.com/locator/ec2/)
* select a better `*_instance_type` (t2.large?) (see https://aws.amazon.com/ec2/pricing/on-demand/)

## Chapter III - in which MoC takes a deep breath and creates first nodes of the network
### Configuring AWS
1. register (if you haven't already) and login to the AWS management console https://aws.amazon.com/console/

2. to create credentials for cli, open IAM home https://console.aws.amazon.com/iam/home then click "Add user" pick a username, and check "Programmatic access" for "Access type". Click "Next"

3. you can choose any of the available options, but "Attach existing policies directly" is the simplest one. In the list of policy types check "AmazonEC2FullAccess". Review your account and click "Create user" to proceed.

4. it is very important that you copy "Access Key ID" and "Secret Access Key" without leaving this page, because there is no other way to retrieve "Secret Access Key" later and you will have to start again and create another user.

5. when you've copied and saved your AWS secret keys, next step is to upload your SSH public key. In the top left corner of the page select "Services > EC2". On the left sidebar select "Network & Security" > "Key Pairs". Click "Import Key Pair". Browse your filesystem for the public key. You can give a name to this keypair, otherwise base name of the file will be used (by default `id_rsa`).

6. configure aws cli:
```
aws configure
```
provide your credentials, choose region for your account (e.g. `us-east-2`) and output format (`json` is recommended).

7. check that keypair was correctly imported:
```
aws ec2 describe-key-pairs
```
you should see your keypair name in the list.

8. to list available subnets:
```
aws ec2 describe-subnets
```

### Run ansible playbooks
1. Install ansible, `boto` and `boto3` packages
```
pip install boto
pip install boto3
```
2. Clone https://github.com/poanetwork/deployment-playbooks and `git checkout` to the correct branch.
3. Prepare files with your ssh public keys, e.g.
```
cat ~/.ssh/id_rsa.pub > files/admins.pub
cp files/admins.pub files/ssh_netstat.pub
cp files/admins.pub files/ssh_bootnode.pub
cp files/admins.pub files/ssh_explorer.pub
cp files/admins.pub files/ssh_moc.pub
cp files/admins.pub files/ssh_validator.pub
```

### Start with netstat server
1. Create a file with a full config for this node type:
```
cat group_vars/all.network group_vars/netstat.example > group_vars/all
```
2. Open this file and fill missing values at the end
3. Create an instance
```
ansible-playbook netstat.yml
```
Wait till the command completes, extract from logs and write down IP address and AWS InstanceID of the new node.

4. Create file `hosts` with the following content (assuming new node's IP is 192.0.2.1)
```
[netstat]
192.0.2.1
```

5. Configure the instance
```
ansible-playbook -i hosts site.yml -l 192.0.2.1
```
If this command fails because host is unreachable over ssh, wait a minute and start again, it takes some time to reboot.

6. Login as root and edit site config for nginx - uncomment the following lines in `/etc/nginx/conf.d/default.conf`:
```
    add_header Access-Control-Allow-Origin "*";
    add_header Access-Control-Allow-Headers "Origin, X-Requested-With, Content-Type, Accept";
```

7. If you plan on using Cloudflare and/or SSL Certificates for netstat, it's time to configure them. Then
```
ssh root@192.0.2.1
```
stop nginx
```
service nginx stop
```
backup current certificates:
```
cp -R /etc/nginx/ssl /etc/nginx/ssl.orig
```
then replace the content of `/etc/nginx/ssl/server.crt` and `/etc/nginx/ssl/server.key` with your certificate and private key. Then start nginx again
```
service nginx start
```
and check if it's running
```
ps aux | grep nginx
```

### Spawn bootnodes
1. Create a file with a full config for this node:
```
cat group_vars/all.network group_vars/bootnode.example > group_vars/all
```

2. Fill missing values in the end of the file. Use `https://netstat.example.com` for `NETSTAT_SERVER` if you installed valid SSL certificates, or `http://192.0.2.1:3000` if you haven't.

**Don't forget to update NODE_FULL_NAME and NODE_ADMIN_EMAIL**

3. Create an instance
```
ansible-playbook bootnode.yml
```
Wait till the command completes, extract from logs and write down IP address and AWS InstanceID of the new node.

4. Create/add to file `hosts` the following content (assuming new node's IP is 192.0.2.1)
```
[bootnode]
192.0.2.1
```

5. Configure the instance
```
ansible-playbook -i hosts site.yml -l 192.0.2.1
```

6. When creating first few bootnodes, you need to update `bootnodes.txt` file in your branch of chain-spec repository, as it will contain enodes of "public" bootnodes. To get enode, ssh to the node and grep logs:
```
grep enode /home/bootnode/logs/parity.log
```
then open bootnodes.txt in chain-spec repository and insert enode on a new line at the end of file. If enode is not found, restart parity
```
systemctl restart poa-parity
```
and try again.

7. When you're done creating as many public bootnodes as necessary, it is recommended to login as root to each one of them, update local version of `/home/bootnode/bootnodes.txt` and restart parity with
```
systemctl restart poa-parity
```

8. You may also create a number of "decoy" bootnodes, that will serve to connect nodes of the network, but will not be listed in the public file.

9. If you need to do this, select a number of bootnodes and configure Cloudflare balancer on them.

**NOTE**: if you notice that nodes quickly appear and disappear in netstat's dashboard, do the following:
```
ssh root@netstat.ip
systemctl restart poa-dashboard
```
This should fix the problem from now on. 

### Create a node for Explorer
1. Create a file with a full config for this node:
```
cat group_vars/all.network group_vars/explorer.example > group_vars/all
```

2. Fill missing values in the end of the file.

3. Create an instance
```
ansible-playbook explorer.yml
```
Wait till the command completes, extract from logs and write down IP address and AWS InstanceID of the new node.

4. Create/replace file `hosts` with the following content (assuming new node's IP is 192.0.2.1)
```
[explorer]
192.0.2.1
```

5. Configure the instance
```
ansible-playbook -i hosts site.yml -l 192.0.2.1
```

6. Login as root and edit site config for nginx - uncomment the following lines in `/etc/nginx/conf.d/default.conf`:
```
    add_header Access-Control-Allow-Origin "*";
    add_header Access-Control-Allow-Headers "Origin, X-Requested-With, Content-Type, Accept";
```

7. If you plan on using Cloudflare/SSL Certificates for the explorer, this is the time to do it. Follow the procedure analogous to netstat server.

### Create MoC's instance, finish the deployment of consensus contracts and generate initial keys
1. Create a file with a full config for this node:
```
cat group_vars/all.network group_vars/moc.example > group_vars/all
```

2. Fill missing values in the end of the file. When setting `MOC_KEYFILE`, paste the entire json content of the keystore file and make sure it's enclosed in single quotes:
```
MOC_KEYFILE: '{"address": ... }'
```
Use `https://netstat.example.com` for `NETSTAT_SERVER` if you installed valid SSL certificates, or `http://192.0.2.1:3000` if you haven't.

3. If you want to close external access to your node, set:
```
allow_moc_ssh: false
allow_moc_p2p: false
```
If this is the first time you create moc's node, don't set `allow_moc_ssh` to `false`, because you will need to connect to it later.

**Don't forget to update NODE_FULL_NAME and NODE_ADMIN_EMAIL**

3. Create an instance
```
ansible-playbook moc.yml
```
Wait till the command completes, extract from logs and write down IP address and AWS InstanceID of the new node.

4. Create/replace file `hosts` with the following content (assuming new node's IP is 192.0.2.1)
```
[moc]
192.0.2.1
```

5. Configure the instance
```
ansible-playbook -i hosts site.yml -l 192.0.2.1
```
6. After node was created, connect to it via `ssh root@...` first, edit `node.toml` and uncomment `unlock=...` line
```
nano /home/moc/node.toml
systemctl restart poa-parity
```

7. Then relogin as unpriviledged  user `moc` and clone (via https) POA Network Consensus contract repository
```
su moc
git clone https://github.com/poanetwork/poa-network-consensus-contracts.git
git checkout  <correct branch name>
cd poa-network-consensus-contracts
npm install
```
and run the following command to deploy other contracts from the consensus (change `POA_NETWORK_CONSENSUS_ADDRESS` accordingly if you changed `safeContract` in spec.json):
```
POA_NETWORK_CONSENSUS_ADDRESS=0xf472e0e43570b9afaab67089615080cf7c20018d MASTER_OF_CEREMONY=<MOC_ADDRESS> ./node_modules/.bin/truffle migrate --reset --network sokol
```
copy and save the output as it contains addresses to which other contracts were deployed.

8. To distribute initial tokens, go to (you are under `moc` user, not `root`!)
```
cd ~/poa-scripts-moc/distributeTokens
```
Upload csv file with `wallet,tokens` list, then edit `.env` file: replace `FAT_BALANCE` with your MoC address and `FILENAME_CSV_INVESTORS` with the csv file name. Run 
```
node distribute.js
```
to distribute tokens.

9. **To generate initial keys** go to
```
cd ~/poa-scripts-owner
```
open `config.json` and under "contracts.KeysManager" block replace "addr" with KeysManager contract's address that you obtained while deploying other contracts from the consensus. Don't change ABI unless you've updated contract's code. Then do
```
cd generateInitialKey
node generateInitialKey
```
Script will output initial key's address, password and location of keystore file.

Repeat this step as many times as necessary.

10. Relogin back as `root`, edit `node.toml` to comment out the `unlock=["0x...]` line, then restart parity:
```
exit
nano node.toml
systemctl restart poa-parity
```
11. You may also have to restart `pm2` if it disconnects while parity restarts:
```
su moc
pm2 restart all
pm2 list
```
12. (optional) To close external access to MoC's node: edit `group_vars/all` and set
```
allow_moc_ssh: false
allow_moc_p2p: false
```
then rerun
```
ansible-playbook -i hosts site.yml
```

## Chapter IV - in which MoC prepares other repositories

### DApp - Keys generation  
https://github.com/poanetwork/poa-dapps-keys-generation/tree/mainnet

1. in `src/getWeb3.js` change number to `NetworkID`
    switch (netId) {

2. in `src/keysManager.js` change `KEYS_MANAGER_ADDRESS` to the one you obtained when deploying other contracts of consensus

### DApp - other DApps?


### Repository with scripts for `moc` node
https://github.com/poanetwork/poa-scripts-moc/tree/master
(same steps as you did manually on moc's node):
1. Create a branch named `NetworkName` from master branch.
2. Update `contracts.KeysManager.addr` in `config.json` to the one you obtained when deploying other contracts of consensus 
3. Update `FAT_BALANCE` to MoC's address.

### Repository with scripts for `validator` node
https://github.com/poanetwork/poa-scripts-validator/tree/master
1. Create a branch named `NetworkName` from mainnet branch.
2. Update `contracts.KeysManager.addr` in `config.json` to the one you obtained when deploying other contracts of consensus (same thing as you did manually on moc's node).

## Chapter VI - in which MoC changes links in Validator's README
1. Supply the validator's README with the correct Keys Exchange DApp url: https://github.com/poanetwork/wiki/blob/master/validator-guide-new.md#exchange-your-initial-keys-for-mining-payout-and-voting-keys

## Chapter VII - in which MoC gives initial keys to first validators and hopes for the best
For each validator, you will need to provide:
* initial key's address
* initial key's keystore file
* initial key's password
* netstats server url
* netstats password
* link to the correct validator's README
* link to the KeysGenerator DApp