diff --git a/doc/Plume_How_to_run_a_node.md b/doc/Plume_How_to_run_a_node.md new file mode 100644 index 00000000..56d2c8af --- /dev/null +++ b/doc/Plume_How_to_run_a_node.md @@ -0,0 +1,205 @@ +## Nightfall 4 — Proposer and Client Deployment Guide on Plume Testnet + +The following sections explain how to run either a `proposer` or a `client` node on the Plume testnet. Please go through the nightfall_4 documentation https://github.com/EYBlockchain/nightfall_4_CE/blob/master/doc/nf_4, for more details. The below assumes you use docker compose to orchestrate your containers, but anything else that works is fine. + +### How to run a proposer node + +Do not forget that the `proposer` will need to run on a large server (144 cores, 750GB RAM is a good size). Moreover, expose the port `3001` of that large server, so the clients nodes can reach you. + +## 1) Get the source + +```bash +git clone https://github.com/EYBlockchain/nightfall_4_CE.git +cd nightfall_4_CE +git checkout plume_testnet_proposer +``` + +--- + +## 2) Stop & clean previous Docker state + +```bash +docker compose --profile indie-proposer down -v +# DANGER: removes images, containers, networks, and volumes +docker system prune -a --volumes +``` + +--- + +## 3) Generate proving keys + +This will download a large file (approximately 12GB): +```bash +cargo run --release --bin key_generation +``` + +or you can get the keys using the configuartion url, `curl -v http://35.225.105.10:8080/ -o configuration/bin/ +where you need to it for following keys `base_bn254_pk` `decider_pk` `deposit_proving_key` `merge_grumpkin_pk` `proving_key` +`base_grumpkin_pk` and `merge_bn254_pk_0`. + +--- + +## 4) Wallet setup: MetaMask + Plume testnet + +1. Install the MetaMask browser extension: [https://metamask.io/en-GB](https://metamask.io/en-GB) +2. Create a **new network** in MetaMask for **Plume testnet** using the parameters published here: [https://thirdweb.com/plume-testnet](https://thirdweb.com/plume-testnet) +3. Import or create an account and ensure it has **≥ 10 PLUME** for fees (test funds). + +--- + +## 5) Create `local.env` + +Create a file named `local.env` in the repo root with the following content. Replace placeholders (`0x....`) with your values where indicated. + +```bash +CLIENT_SIGNING_KEY= +CLIENT2_SIGNING_KEY= +CLIENT_ADDRESS= +CLIENT2_ADDRESS= +PROPOSER_SIGNING_KEY="0x......." # your private key +PROPOSER_2_SIGNING_KEY= +DEPLOYER_SIGNING_KEY= +NIGHTFALL_ADDRESS= +WEBHOOK_URL= +AZURE_VAULT_URL= +DEPLOYER_SIGNING_KEY_NAME= +PROPOSER_SIGNING_KEY_NAME= +PROPOSER_2_SIGNING_KEY_NAME= +CLIENT_SIGNING_KEY_NAME= +CLIENT2_SIGNING_KEY_NAME= +AZURE_CLIENT_ID= +AZURE_CLIENT_SECRET= +AZURE_TENANT_ID= +``` + +--- + +## 6) Build and run the Nightfall client + +From the repo root: + +```bash +docker compose --profile indie-proposer build + +docker compose --profile indie-proposer --env-file local.env up -d + +docker compose --profile indie-proposer --env-file local.env logs -f +``` + +--- + +## 7) Register as a Proposer + +Now since you started as a proposer, you need to register as a proposer with the url `http://:3001` using the following api + +POST /v1/register + +```sh +curl -i --request POST 'http://localhost:3000/v1/register' \ + --json '{ "url": "http://:3001" }' +``` +--- + +## 8) Rotate Proposer +If you want create blocks as a proposer, you can call rotate proposer api + +GET v1/rotate + +```sh +curl -i 'http://localhost:3001/v1/rotate' +``` + +Returns: on success `200 OK` if the active `proposer` was rotated, `423 LOCKED` if proposer rotation was not allowed by the smart contract. +This endpoint will rotate the proposers if the current `proposer` has been active for more than the number of Layer 1 blocks that a `proposer` is allowed to propose for (ROTATION_BlOCKS) (currently set as 4 blocks). This value is set in the construction of RoundRobin.sol. + +--- + + +### How to run a client node + +Make sure you have tokens in an ERC20|721|1155|3525 contract that you can access or you can follow the last step to do a mock deployement. + +## 1) Get the source + +```bash +git clone https://github.com/EYBlockchain/nightfall_4_CE.git +cd nightfall_4_CE +git checkout plume_testnet_client +``` + +Make sure you pulled the latest changes. + +--- + +## 2) Stop & clean previous Docker state + +```bash +docker compose --profile indie-client down +# DANGER: removes images, containers, networks, and volumes +docker system prune -a --volumes +``` + +--- + +## 3) Wallet setup: MetaMask + Plume testnet + +1. Install the MetaMask browser extension: [https://metamask.io/en-GB](https://metamask.io/en-GB) +2. Create a **new network** in MetaMask for **Plume testnet** using the parameters published here: [https://thirdweb.com/plume-testnet](https://thirdweb.com/plume-testnet) +3. Import or create an account and ensure it has **≥ 10 PLUME** for fees (test funds). + +--- + +## 4) Create `local.env` + +Create a file named `local.env` in the repo root with the following content. Replace placeholders (`0x....`) with your values where indicated. + +```bash +CLIENT_SIGNING_KEY="0x......." # your private key +CLIENT2_SIGNING_KEY= +CLIENT_ADDRESS="0x......." # your public address +CLIENT2_ADDRESS= +PROPOSER_SIGNING_KEY= +PROPOSER_2_SIGNING_KEY= +DEPLOYER_SIGNING_KEY= +NIGHTFALL_ADDRESS= +NF4_SIGNING_KEY= +WEBHOOK_URL= +AZURE_VAULT_URL= +DEPLOYER_SIGNING_KEY_NAME= +PROPOSER_SIGNING_KEY_NAME= +PROPOSER_2_SIGNING_KEY_NAME= +CLIENT_SIGNING_KEY_NAME= +CLIENT2_SIGNING_KEY_NAME= +AZURE_CLIENT_ID= +AZURE_CLIENT_SECRET= +AZURE_TENANT_ID= +``` + +Please remove all comments (beginning with `#`) in your local.env file. + +--- + +## 5) Build and run the Nightfall client + +From the repo root: + +```bash +docker compose --profile indie-client build + +docker compose --profile indie-client --env-file local.env up +``` + +## 6) Deployment script for mock ERC contracts + +You can also deploy your own ERC-20/721/1155/3525 contracts using the following script: `blockchain_assets/script/mock_deployment.s.sol` + +Mock ERC deployments + +1. Please add the `NIGHTFALL_ADDRESS` and `NF4_SIGNING_KEY` to `local.env`. +2. To get the `NIGHTFALL_ADDRESS`, run `curl http://35.225.105.10:8080/configuration/toml/addresses.toml` and `NF4_SIGNING_KEY` is your signing key from metamask. +3. `forge build` +4. `export $(grep -v '^#' local.env | xargs)` +5. `forge script blockchain_assets/script/mock_deployment.s.sol:MockDeployer --rpc-url https://testnet-rpc.plume.org --broadcast --legacy --slow` + + +You can then interact with those contract using the APIs: https://github.com/EYBlockchain/nightfall_4_CE/blob/master/doc/nf_4.md#client-apis diff --git a/doc/Plume_deployment_guide.md b/doc/Plume_deployment_guide.md new file mode 100644 index 00000000..15bbff80 --- /dev/null +++ b/doc/Plume_deployment_guide.md @@ -0,0 +1,95 @@ +## Deployment on a Plume testnet for beta testing + +Following documentation can be used to do testnet deployment. + +### Preliminaries + +You must be able to access a blockchain client that can accept websocket connections (`ws://` or `wss://`). NF_4 subscribes to blockchain events and therefore an `http://` endpoint *will not work*. For plume testnet, `wss://testnet-rpc.plume.org` url is used. + +### Setup the Configuration file + +Add a stanza to the `nightfall.toml` file for your testnet configuration, if it doesn't already exist. The `[base_sepolia]` section can be used as a guide. The testnet-dependent items are: + +- `genesis_block`: If you are deploying contracts for the first time, set this to roughly the current layer 1 blocknumber for the testnet. This will make responses faster because nightfall will not look for events prior to this block when synchronising. +- `chain_id`: The chain id of the testnet. This is useful because deployments will be logged under a folder with the same name as the chain id. This allows one to distinguish from Anvil deploys, for example. +- `contracts.contract_addresses`: If you have already deployed the contracts then their addresses can be placed here so that nightfall knows where to find the contracts. Otherwise it will attempt to read the latest deployment log file, which is less reliable (e.g. you may not have deployed the contracts so your log file won't contain the correct information). If you don't want this to happen, leave the values blank (empty strings). These values will be ignored if you've told nightfall to deploy contracts via the `deploy_contracts` configuration item. +- `deploy_contracts`: If true, deployer will deploy new contracts, otherwise it will run and set up keys but won't deploy contracts before exiting. It's often convenient to override this value with an environment variable (see later) to save rebuilding the containers. +- `proposer_url` : If you are running a proposer node, you need to expose the port 3001 from the large server. Replace the `proposer_url` with that, e.g `http://:3001` +- `configuration_url`: You need to expose the port 8080 or any other port and replace the `configuration_url` with that, add that port to `docker-compose.yml` as under `configuration` service as well. + +## Create `local.env` + +Create a file named `local.env` in the repo root with the following content. Replace placeholders (`0x....`) with your values where indicated. + +```bash +CLIENT_SIGNING_KEY= +CLIENT2_SIGNING_KEY= +CLIENT_ADDRESS= +CLIENT2_ADDRESS= +PROPOSER_SIGNING_KEY= +PROPOSER_2_SIGNING_KEY= +DEPLOYER_SIGNING_KEY="0x......." # your private key +NIGHTFALL_ADDRESS= +WEBHOOK_URL= +AZURE_VAULT_URL= +DEPLOYER_SIGNING_KEY_NAME= +PROPOSER_SIGNING_KEY_NAME= +PROPOSER_2_SIGNING_KEY_NAME= +CLIENT_SIGNING_KEY_NAME= +CLIENT2_SIGNING_KEY_NAME= +AZURE_CLIENT_ID= +AZURE_CLIENT_SECRET= +AZURE_TENANT_ID= +``` + +### Deploying contracts + +You should only need to do this once and will probably only redeploy if there is an update to the Smart Contracts themselves. Do not forget that you will need to run on a large server (144 cores, 750GB RAM is a good size), to generate the keys. + +--- + +## Get the source + +All the changes for deployment on plume testnet are made on the branch `plume_testnet_deployer` + +```bash +git clone https://github.com/EYBlockchain/nightfall_4_CE.git +cd nightfall_4_CE +git checkout plume_testnet_deployer +``` + +--- + +## Generate proving keys + +This will download a large file (approximately 12GB): +```bash +cargo run --release --bin key_generation + +``` + +This will save all the keys in `configuration/bin/` +--- + +## Generate proving keys + +```bash +docker compose --profile indie-deployer build +docker compose --profile indie-deployer --env-file local.env up +``` + +This should deploy all the Nightfall contracts. Their addresses will have been written to `configuration/toml/addresses.toml` and will also be in the deployment logs `blockchain_assets/logs`. Provide these addresses to the `client` and `proposer` via either the configuration server, their `addresses.toml` file or by adding them to their `nightfall.toml` file (in the latter case don't forget to set `deploy_contracts=false` or they'll be ignored). Use whichever method is most appropriate for your infrastructure. + +As usual, a `Code 0` exit indicates a successful outcome. + +## Configuration for Proposer and Clients + +We need to expose some configurations like the keys generated and the deployed contract addresses. + +## Build and Run the Configuration + +```bash +docker compose --profile configuration build +docker compose --profile configuration --env-file local.env up -d +docker compose --profile configuration --env-file local.env logs -f +``` \ No newline at end of file