Run Waterfall Node RC1 v2 in Docker

Testnet7 has been stopped. Use our other testnets

Install Docker

You need to install Docker, which will allow you to perform further steps consistently across any operating system. You can install Docker for your operating system using the following links:

• on Debian
• on Mac
• on Windows

Requirements

Windows

• For the Windows operating system, you need to use all of the commands in the PowerShell terminal.

MacOS on arm

We recommend enabling the following settings:

Login to private registry

The source code for Waterfall is currently closed (it will be opened after a security audit), so the source code and images are stored in a private repository. To access the private Docker image registry, you need to log in. Execute the following command in the terminal:

docker login -u public -p glpat-XvZ6bPe48rFGZ5z14Fxz registry.waterfall.network

Pull image

Download image from the private registry, where you logged in on the previous step. Use the latest Docker image that contains all the necessary software to run the node. To do this, you need to execute the following command in the terminal:

docker pull registry.waterfall.network/waterfall/protocol/docker:2-rc1

Run Node

Execute the following command in the terminal:

cd ~

Executing the following command in the terminal:

docker run --platform linux/amd64 --name wf -d --rm -p 4000:4000 -p 13000:13000 -p 12000:12000/udp -p 30303:30303 -p 9545:9545 -p 9546:9546 -v $PWD/.wf/logs:/opt/wf/data/logs -v $PWD/.wf/gwat:/opt/wf/data/gwat -v $PWD/.wf/coordinator:/opt/wf/data/coordinator registry.waterfall.network/waterfall/protocol/docker:2-rc1

This leads to the following:

• the generation of coordinator and validator keys
• keys are imported into the node wallets
• the node starts up
• The database data is stored in the home directory ~/.wf

Check status

You can check the status of the node by executing the following command in the terminal:

docker exec -it wf /opt/wf/sh/status.sh

The script may return any of the following answers:

• Main:
  • The Coordinator Node isn't running - the Coordinator node is not running, it is still starting
  • The Coordinator node is syncing. Distance: 9294 - the Coordinator node is synchronizing, synchronization occurs when Distance will be equal to 0
  • The Validator Node isn't running - the Validator node is synchronizing
  • The Validator node is synchronizing:

    The Validator node is syncing. Status {
      currentBlock: 0,
      currentSlot: 15738,
      finalizedSlot: 0,
      highestBlock: 0,
      knownStates: 0,
      maxDagSlot: 0,
      pulledStates: 0,
      startingBlock: 0
    }
    

  • The node is synchronized. - the node is synchronized.
  • Node ID: 3b12ddb05c50ff9fee329f64a8b2a23561fd9847d24e847cdd0011785a1f9973 - Node ID
  • Coordinator peers: 5 - number of connected nodes with coordinators
  • Validator peers: 10 - number of connected nodes with validators
  • Keys weren't generated - this means that the keys are still being generated and the node has not yet started
• Worker #<workers index>
  • Coordinator public key: 0xad7aac64a8ab9507a3b06ac46a30d48d89c8bfb4f36d402cfa4e5817ecc37cb01dfd339295f99565367af78aa727a2c1 - the coordinator's public key, which holds the stake and earns in the coordinating network.
  • Validator address: 0x2cd4289d5d5246ccb557a493e65a2ac94914b8b0 - the validator's address, that creates blocks in the BlockDAG network and gets rewards for it.
  • Withdrawal address: 0x2cd4289d5d5246ccb557a493e65a2ac94914b8b0 - The address that can send a deactivation transaction and take the rewards and stake of the coordinator and validator.
  • The coordinator has not been activated - indicates that either the transaction with the stake has not been sent, or this transaction has not yet been processed.
  • Coordinator status: active_ongoing - coordinator status:
    • pending_initialized - When the first deposit is processed, but not enough funds are available (or it is not yet the end of the first epoch) to get the coordinator into the activation queue.
    • pending_queued - When the coordinator is waiting to get activated, and it has enough funds, etc. While in the queue, the coordinator activation epoch keeps changing until it gets to the front and makes it through (finalization is a requirement here too).
    • active_ongoing - When the coordinator is still attesting, and has not initiated any exit.
    • active_exiting - When the coordinator is still active, but has filed a voluntary request to exit.
    • active_slashed - When the coordinator is still active, but has a slashed status and is scheduled to exit.
    • exited_unslashed - When the coordinator has reached a regular exit epoch, not being slashed, and no longer has to attest, but cannot withdraw yet.
    • exited_slashed - When the coordinator has reached a regular exit epoch, but was slashed, and has to wait for a longer withdrawal period.
    • withdrawal_possible - After the coordinator has exited, and is later permitted to move funds, and is truly out of the system.
    • withdrawal_done - funds have actually been moved
  • Stake: 3200.000000000 WATER - the stake that was sent
  • Coordinator balance: 3200.038794846 WATER - the coordinator balance, along with the stake
  • Validator balance: 0.000000000000000000 WATER - the validator balance

Onboarding

If the node is running and synchronized (See the result of the status command – The node is synchronized), you can add and activate the worker by taking the following steps:

1. Install Metamask according to the instructions
2. Add a new network in Metamask by specifying the following parameters:
   • Network Name: Waterfall RC1 Network
   • RPC URL: https://rpc.rc1.waterfall.network/
   • Chain ID: 8601151
   • Currency symbol: WATER
   • Block Explorer URL: https://explorer.rc1.waterfall.network
3. In the advanced settings of Metamask, enable the display of the data field when sending a transaction:
4. Create an account address in Metamask if you don't have one already
5. On the faucet page, get 4000 WATER for your account.
6. Generate keys and add a new worker to your node by running the following command in the terminal:

   docker exec -it wf /opt/wf/sh/add.sh <withdrawals address>
   

   Example 1:

   docker exec -it wf /opt/wf/sh/add.sh
   

   In response, you will get the following result:

   Generated new Worker #0:
     Coordinator public key: 0xaf0558f9814d8ff52b15904bc76fcde0d4b694e5f01b5ffeab025bab6edc168422a1164d45cf4a9d58653ff3be4d4866
     Validator address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
     Withdrawal address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
   
   Send tx by Metamask to activate Worker:
     To: 0x0cEF9cA60360F957b65ecE8B1CB716718229277f
     Value: 3200 WATER
     Data: 0xf401af0558f9814d8ff52b15904bc76fcde0d4b694e5f01b5ffeab025bab6edc168422a1164d45cf4a9d58653ff3be4d4866072cb086a41ad80e13946aa8767cd9077e60115a072cb086a41ad80e13946aa8767cd9077e60115a86b45006fffc948a0f00aa32346c2e34bfc0e17355bac46a112fe1df3d3d30b2b2aff5fe39e0a1ba7e4791c062015da00baa85b394ab485d815ea7036694fbe5e73d4008ff68fc5afb219c62f778d94a1e5e7eda2b6db32c76dc9d7833c8378d
   

   Example 2:

   docker exec -it wf /opt/wf/sh/add.sh 0x30c35895FE0f7768A261b5326e4332cBb4556Ba3
   

   In response, you will get the following result:

   Generated new Worker #1:
     Coordinator public key: 0xb8db9f749d0cb517cc3613860a3026479497e7799111629581a2cc0bcfa9ef51985fed8d7fa3e53b0e1b35ba9663e2d3
     Validator address: 0x4d76c92aa070c5fbdef46b309737cf1b42eb07ca
     Withdrawal address: 0x30c35895fe0f7768a261b5326e4332cbb4556ba3
   
   Send tx by Metamask to activate Worker:
     To: 0x0cEF9cA60360F957b65ecE8B1CB716718229277f
     Value: 3200 WATER
     Data: 0xf401b8db9f749d0cb517cc3613860a3026479497e7799111629581a2cc0bcfa9ef51985fed8d7fa3e53b0e1b35ba9663e2d34d76c92aa070c5fbdef46b309737cf1b42eb07ca30c35895fe0f7768a261b5326e4332cbb4556ba3a0171c80334272cd9da8ce5cbe23248a8e1896c0390483c22a6c691b771211ce108c0cceff46ad7897424a73aab710980e854a8f380521ff69a32eb3b09582191ef5fc79ba6fde52e42e036cd9841d752b78727ded36dd8d35b84b2fe141707f
   

7. Generate data for the transaction by running the following command in the terminal, or use the information from the previous step:

   docker exec -it wf /opt/wf/sh/deposit.sh <workers index>
   

   Example:

   docker exec -it wf /opt/wf/sh/deposit.sh 0
   

   In response, you will get the following result:

   Send tx by Metamask to activate Worker:
     To: 0x0cEF9cA60360F957b65ecE8B1CB716718229277f
     Value: 3200 WATER
     Data: 0xf401af0558f9814d8ff52b15904bc76fcde0d4b694e5f01b5ffeab025bab6edc168422a1164d45cf4a9d58653ff3be4d4866072cb086a41ad80e13946aa8767cd9077e60115a072cb086a41ad80e13946aa8767cd9077e60115a86b45006fffc948a0f00aa32346c2e34bfc0e17355bac46a112fe1df3d3d30b2b2aff5fe39e0a1ba7e4791c062015da00baa85b394ab485d815ea7036694fbe5e73d4008ff68fc5afb219c62f778d94a1e5e7eda2b6db32c76dc9d7833c8378d
   

8. Using MetaMask, send a transaction to the address, with the amount and data obtained in the previous step
9. After this, execute the status command in the terminal to determine that your worker is running.
   Example:

   docker exec -it wf /opt/wf/sh/status.sh
   

   In response, you will get the following result:

   Main:
     The node is synchronized.
     Node ID: d8a45dfbe783c61942aa124623be1e828cc76900c4a8c91f29d491ca9258b6d0
     Coordinator peers: 10
     Validator peers: 7
   
   Worker #0:
     Coordinator public key: 0xaf0558f9814d8ff52b15904bc76fcde0d4b694e5f01b5ffeab025bab6edc168422a1164d45cf4a9d58653ff3be4d4866
     Validator address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
     Withdrawal address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
     Coordinator status: active_ongoing
     Stake: 3200.000000000 WATER
     Coordinator balance: 3203.709291628 WATER
     Validator balance: 0.000116544466171 WATER
   
   Worker #1:
     Coordinator public key: 0xb8db9f749d0cb517cc3613860a3026479497e7799111629581a2cc0bcfa9ef51985fed8d7fa3e53b0e1b35ba9663e2d3
     Validator address: 0x4d76c92aa070c5fbdef46b309737cf1b42eb07ca
     Withdrawal address: 0x30c35895fe0f7768a261b5326e4332cbb4556ba3
     The coordinator has not been activated
     Validator balance: 0 WATER
   

Offboarding

Withdraw

To withdraw your rewards, run the following command:

docker exec -it wf /opt/wf/sh/withdraw.sh <workers index> <amount in WATTER>

Example:

docker exec -it wf /opt/wf/sh/status.sh

Main:
  The node is synchronized.
  Node ID: d8a45dfbe783c61942aa124623be1e828cc76900c4a8c91f29d491ca9258b6d0
  Coordinator peers: 10
  Validator peers: 8

Worker #0:
  Coordinator public key: 0xaf0558f9814d8ff52b15904bc76fcde0d4b694e5f01b5ffeab025bab6edc168422a1164d45cf4a9d58653ff3be4d4866
  Validator address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Withdrawal address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Coordinator status: active_ongoing
  Stake: 3200.000000000 WATER
  Coordinator balance: 3204.786024880 WATER
  Validator balance: 0.001281989127881 WATER

Worker #1:
  Coordinator public key: 0xb8db9f749d0cb517cc3613860a3026479497e7799111629581a2cc0bcfa9ef51985fed8d7fa3e53b0e1b35ba9663e2d3
  Validator address: 0x4d76c92aa070c5fbdef46b309737cf1b42eb07ca
  Withdrawal address: 0x30c35895fe0f7768a261b5326e4332cbb4556ba3
  Coordinator status: active_ongoing
  Stake: 3200.000000000 WATER
  Coordinator balance: 4203.589382720 WATER
  Validator balance: 0 WATER

docker exec -it wf /opt/wf/sh/withdraw.sh 0 4.786024880

TxHash: "0x1f85fbd5311d1b879464ea253adddd937449220d1b1545ba592c863fc9c5b6b7"

docker exec -it wf /opt/wf/sh/withdraw.sh 1 3.589382720

Send tx by Metamask:
  From: 0x30c35895fe0f7768a261b5326e4332cbb4556ba3
  To: 0x0cEF9cA60360F957b65ecE8B1CB716718229277f
  Value: 0 WATER
  Data: 0xf4064d76c92aa070c5fbdef46b309737cf1b42eb07ca31d00c9104868000

docker exec -it wf /opt/wf/sh/status.sh

Main:
  The node is synchronized.
  Node ID: d8a45dfbe783c61942aa124623be1e828cc76900c4a8c91f29d491ca9258b6d0
  Coordinator peers: 10
  Validator peers: 8

Worker #0:
  Coordinator public key: 0xaf0558f9814d8ff52b15904bc76fcde0d4b694e5f01b5ffeab025bab6edc168422a1164d45cf4a9d58653ff3be4d4866
  Validator address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Withdrawal address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Coordinator status: active_ongoing
  Stake: 3200.000000000 WATER
  Coordinator balance: 3202.399658920 WATER
  Validator balance: 4.788490650641493 WATER

Worker #1:
  Coordinator public key: 0xb8db9f749d0cb517cc3613860a3026479497e7799111629581a2cc0bcfa9ef51985fed8d7fa3e53b0e1b35ba9663e2d3
  Validator address: 0x4d76c92aa070c5fbdef46b309737cf1b42eb07ca
  Withdrawal address: 0x30c35895fe0f7768a261b5326e4332cbb4556ba3
  Coordinator status: active_ongoing
  Stake: 3200.000000000 WATER
  Coordinator balance: 4202.393012440 WATER
  Validator balance: 0 WATER

Transfer

To transfer the rewards to yourself, run the following command:

docker exec -it wf /opt/wf/sh/transfer.sh <workers index> <to address> <amount in WATTER>

Example:

docker exec -it wf /opt/wf/sh/status.sh

Main:
  The node is synchronized.
  Node ID: d8a45dfbe783c61942aa124623be1e828cc76900c4a8c91f29d491ca9258b6d0
  Coordinator peers: 10
  Validator peers: 8

Worker #0:
  Coordinator public key: 0xaf0558f9814d8ff52b15904bc76fcde0d4b694e5f01b5ffeab025bab6edc168422a1164d45cf4a9d58653ff3be4d4866
  Validator address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Withdrawal address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Coordinator status: active_ongoing
  Stake: 3200.000000000 WATER
  Coordinator balance: 3202.399658920 WATER
  Validator balance: 4.788490650641493 WATER

Worker #1:
  Coordinator public key: 0xb8db9f749d0cb517cc3613860a3026479497e7799111629581a2cc0bcfa9ef51985fed8d7fa3e53b0e1b35ba9663e2d3
  Validator address: 0x4d76c92aa070c5fbdef46b309737cf1b42eb07ca
  Withdrawal address: 0x30c35895fe0f7768a261b5326e4332cbb4556ba3
  Coordinator status: active_ongoing
  Stake: 3200.000000000 WATER
  Coordinator balance: 4202.393012440 WATER
  Validator balance: 0 WATER

docker exec -it wf /opt/wf/sh/transfer.sh 0 0x4d76c92aa070c5fbdef46b309737cf1b42eb07ca 4

TxHash: "0xc013095da3dd7d476346a07ad1ab9a45ce5186559e26b8c37376df6e0fa78a22"

docker exec -it wf /opt/wf/sh/status.sh

Main:
  The node is synchronized.
  Node ID: d8a45dfbe783c61942aa124623be1e828cc76900c4a8c91f29d491ca9258b6d0
  Coordinator peers: 10
  Validator peers: 8

Worker #0:
  Coordinator public key: 0xaf0558f9814d8ff52b15904bc76fcde0d4b694e5f01b5ffeab025bab6edc168422a1164d45cf4a9d58653ff3be4d4866
  Validator address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Withdrawal address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Coordinator status: active_ongoing
  Stake: 3200.000000000 WATER
  Coordinator balance: 3202.638932976 WATER
  Validator balance: 0.7886701951076646 WATER

Worker #1:
  Coordinator public key: 0xb8db9f749d0cb517cc3613860a3026479497e7799111629581a2cc0bcfa9ef51985fed8d7fa3e53b0e1b35ba9663e2d3
  Validator address: 0x4d76c92aa070c5fbdef46b309737cf1b42eb07ca
  Withdrawal address: 0x30c35895fe0f7768a261b5326e4332cbb4556ba3
  Coordinator status: active_ongoing
  Stake: 3200.000000000 WATER
  Coordinator balance: 4202.632286496 WATER
  Validator balance: 4 WATER

Exit

To deactivate the worker, run the following command:

docker exec -it wf /opt/wf/sh/exit.sh <workers index>

Example:

docker exec -it wf /opt/wf/sh/status.sh 

Main:
  The node is synchronized.
  Node ID: d8a45dfbe783c61942aa124623be1e828cc76900c4a8c91f29d491ca9258b6d0
  Coordinator peers: 10
  Validator peers: 9

Worker #0:
  Coordinator public key: 0xaf0558f9814d8ff52b15904bc76fcde0d4b694e5f01b5ffeab025bab6edc168422a1164d45cf4a9d58653ff3be4d4866
  Validator address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Withdrawal address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Coordinator status: active_ongoing
  Stake: 3200.000000000 WATER
  Coordinator balance: 3202.758570004 WATER
  Validator balance: 0.7886701951076646 WATER

Worker #1:
  Coordinator public key: 0xb8db9f749d0cb517cc3613860a3026479497e7799111629581a2cc0bcfa9ef51985fed8d7fa3e53b0e1b35ba9663e2d3
  Validator address: 0x4d76c92aa070c5fbdef46b309737cf1b42eb07ca
  Withdrawal address: 0x30c35895fe0f7768a261b5326e4332cbb4556ba3
  Coordinator status: active_ongoing
  Stake: 3200.000000000 WATER
  Coordinator balance: 4202.751923524 WATER
  Validator balance: 4 WATER

docker exec -it wf /opt/wf/sh/exit.sh 0

TxHash: "0x185b22f512b81b0dc0dd454fcedad87e41a398834915db1da892cbcb2cac5050"

docker exec -it wf /opt/wf/sh/exit.sh 1

Send tx by Metamask:
  From: 0x30c35895fe0f7768a261b5326e4332cbb4556ba3
  To: 0x0cEF9cA60360F957b65ecE8B1CB716718229277f
  Value: 0 WATER
  Data: 0xf403b8db9f749d0cb517cc3613860a3026479497e7799111629581a2cc0bcfa9ef51985fed8d7fa3e53b0e1b35ba9663e2d34d76c92aa070c5fbdef46b309737cf1b42eb07ca

docker exec -it wf /opt/wf/sh/status.sh

Main:
  The node is synchronized.
  Node ID: d8a45dfbe783c61942aa124623be1e828cc76900c4a8c91f29d491ca9258b6d0
  Coordinator peers: 10
  Validator peers: 9

Worker #0:
  Coordinator public key: 0xaf0558f9814d8ff52b15904bc76fcde0d4b694e5f01b5ffeab025bab6edc168422a1164d45cf4a9d58653ff3be4d4866
  Validator address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Withdrawal address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Coordinator status: active_exiting
  Stake: 3200.000000000 WATER
  Coordinator balance: 3203.476392172 WATER
  Validator balance: 0.7895337192562741 WATER

Worker #1:
  Coordinator public key: 0xb8db9f749d0cb517cc3613860a3026479497e7799111629581a2cc0bcfa9ef51985fed8d7fa3e53b0e1b35ba9663e2d3
  Validator address: 0x4d76c92aa070c5fbdef46b309737cf1b42eb07ca
  Withdrawal address: 0x30c35895fe0f7768a261b5326e4332cbb4556ba3
  Coordinator status: active_exiting
  Stake: 3200.000000000 WATER
  Coordinator balance: 4204.666387852 WATER
  Validator balance: 4 WATER

docker exec -it wf /opt/wf/sh/status.sh

Main:
  The node is synchronized.
  Node ID: d8a45dfbe783c61942aa124623be1e828cc76900c4a8c91f29d491ca9258b6d0
  Coordinator peers: 10
  Validator peers: 9

Worker #0:
  Coordinator public key: 0xaf0558f9814d8ff52b15904bc76fcde0d4b694e5f01b5ffeab025bab6edc168422a1164d45cf4a9d58653ff3be4d4866
  Validator address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Withdrawal address: 0x072cb086a41ad80e13946aa8767cd9077e60115a
  Coordinator status: exited_unslashed
  Stake: 3200.000000000 WATER
  Coordinator balance: 3204.912308388 WATER
  Validator balance: 0.7897668081886162 WATER

Worker #1:
  Coordinator public key: 0xb8db9f749d0cb517cc3613860a3026479497e7799111629581a2cc0bcfa9ef51985fed8d7fa3e53b0e1b35ba9663e2d3
  Validator address: 0x4d76c92aa070c5fbdef46b309737cf1b42eb07ca
  Withdrawal address: 0x30c35895fe0f7768a261b5326e4332cbb4556ba3
  Coordinator status: active_exiting
  Stake: 3200.000000000 WATER
  Coordinator balance: 4204.905661908 WATER
  Validator balance: 4 WATER

Stop Node

To stop the node, execute the following command in the terminal:

docker stop wf

Reinstall Node

1. Stop Node (see instructions above)
2. Remove data in home directory ~/.wf by executing the following command in the terminal:

   rm -R ~/.wf
   

3. Pull image (see instructions above)
4. Run Node (see instructions above) and other steps in instructions above

Upgrade from version 1

If you used our old instructions https://hackmd.io/@waterfall/BJOJd0Y62, we recommend upgrading to the new version

1. Stop Node

   docker stop wf
   

2. Pull image

   docker pull registry.waterfall.network/waterfall/protocol/docker:2-rc1
   

3. Run Node

   docker run --platform linux/amd64 --name wf -d --rm -p 4000:4000 -p 13000:13000 -p 12000:12000/udp -p 30303:30303 -p 9545:9545 -p 9546:9546 -v $PWD/.wf/logs:/opt/wf/data/logs -v $PWD/.wf/gwat:/opt/wf/data/gwat -v $PWD/.wf/coordinator:/opt/wf/data/coordinator registry.waterfall.network/waterfall/protocol/docker:2-rc1
   

Deploy Smart-Contract

To deploy smart-contract read instructions

Common Issues and Solutions

1. If the peers of the Coordinating node disappeared during synchronization, please restart the Docker