At-home watchtowers

Steps to run a Witness Chain watchtower client to validate location claims

The PoL Watchtower Client Node participates in the Proof-of-Location (PoL) protocol by verifying location claims made by DePIN (Decentralized Physical Infrastructure Network) Nodes.

You can read about DePIN networks here

Watchtower nodes can run on community members' laptops, desktops, or cloud instances. Nodes are selected to participate in PoL challenges via a probabilistic algorithm.

Prerequisites

• Docker: Version 23.0.0 or higher (Install Docker).

• Instance: Minimum t2.micro equivalent (1 vCPU, 1GB RAM, 5GB disk). Recommended: 2 cores, 4GB RAM, 10GB disk.

• ECDSA KeyPair ( This video demonstrates how you can use MetaMask to export one ). This will be used for registration & signing purposes.

• Ports to Open (for public IP only)

  • Incoming (TCP & UDP): 11112, 22223, 33334-33336, 44445-44447, 55556

  • Outgoing: Allow all.

Witness Chain Explorer: https://blue-orangutan-blockscout.eu-north-2.gateway.fm/

Our chain is gasless, so you do NOT have to fund either or the operator or watchtower account with tokens.

Running the Watchtower Client

1. Installing and registering the Watchtower Key

Download and install the witness CLI:

curl -sSfL https://witnesschain-com.github.io/install-dcl-cli | bash

After the installation is completed, register your watchtower key on WitnessChain's Layer 2 Chain: Use the KeyPair that you would have exported or created using Metamask or any other wallet.

witness-cli registerWatchtower --testnet --watchtower-private-key <your-watchtower-private-key-without-0x-prefix>

Why should I register?

Registration helps with identification of your watchtower inside Witness Chain's watchtower network

2. Configuring watchtower.env File

• Create a watchtower.env configuration file with the following example entries.

• If you are running this at home and DON'T have a public IP, you need to change the following entries only in the watchtower.env file

  • latitude, longitude, country, region, city, privateKey, walletPublicKey

latitude=37.0151
longitude=-79.0392
country=US
region=Virginia
city=Ashburn
radius=1000
privateKey=<your_private_key>
walletPublicKey=<your_public_key>
saveResultsInDatabase=false
submitResultsToContract=true
rpcUrl=https://blue-orangutan-rpc.eu-north-2.gateway.fm

You can get detailed explanation about these parameters here

3. Running the Watchtower Client

Start the challenger client:

docker run -d \
  --network=host \
  --name pol-challenger \
  --env-file ./watchtower.env \
  witnesschain/pol-challenger:0.3.4-alpha

Verify the client is running:

docker ps

If you see an error about "registration required on DCL contract," make sure to complete the watchtower key registration.

Post-Setup

Check logs using:

docker logs pol-challenger

Once the client is ready, you're part of Witness Chain's Watchtower family!

Troubleshooting

The days might be rainy or snowy, but we've got umbrellas and sweaters!. For support, join our Discord or reach out on Telegram.

FAQs

What do the parameters in watchtower.env mean ?

 
latitude=37.015, // Required. Latitude of the machine running the challenger client
longitude=-79.039, // Required. Longitude of the machine running the challenger client
    
country=US, // Optional. Country in which the machine is located
region=Virginia, // Optional. State/Region in which the machine is located
city=Ashburn, // Optional. City in which the machine is located
radius=1000 // Optional. Accuracy in meters


privateKey= //  PoL signing key (Watchtower Key)
walletPublicKey= //  Ethereum Wallet addresses where your contributions go (Operator Key)

saveResultsInDatabase=true // Saves the login, session, and challenge related data in a .sqlite file within the container
rpcUrl=https://blue-orangutan-rpc.eu-north-2.gateway.fm // Witness chain's Layer 2 Chain which holds the proofs of location

What do the parameters in the docker run mean?

docker run -d: Runs the container in detached mode (in the background).

• --network=host
  Uses the host's network stack.

• --name pol-challenger
  Names the container as 'pol-challenger'.

• --env-file ./watchtower.env
  The container's environment is set using the attributes specified in 'watchtower.env' file

• witnesschain/pol-challenger:0.3.4-alpha: The name of the Docker image to run.

---