Running a Lens Node

Learn how to run a Lens node.

Prerequisites

Setup Instructions

Clone the Lens Node Repository

git clone https://github.com/lens-network/lens-node && cd lens-node

Start the Node

For a Testnet instance:

docker-compose --file testnet-external-node.yml up -d

Mainnet coming soon

Verify the Node Is Running

docker ps -f "name=lens-node-external-node"

The status of the container should be Up.

Make Youur First Request

To make a request to the API, you can use the following command:

curl --request POST \  --url http://localhost:3060/ \  --header 'Content-Type: application/json' \  --data '{      "jsonrpc": "2.0",      "id": 1,      "method": "zks_getMainContract",      "params": []    }'

Example response:

{  "jsonrpc": "2.0",  "result": "0x9cff734c0529e89e2294b592d9f4d310754ec8ca",  "id": 1}

Checking the Node State

You can check the logs of the Docker container to see if there are any errors:

docker logs -f --tail 100 lens-node-external-node-1

You can also check the healthcheck endpoint to see if the node is healthy:

curl http://localhost:3081/health

Example response:

{  "status": "ready",  "components": {    "tree": {      "status": "ready",      "details": {        "leaf_count": 5135,        "min_l1_batch_number": 0,        "mode": "lightweight",        "next_l1_batch_number": 3454,        "root_hash": "0xef63592d85ef5cd1986af2af0ba4040fc13392c1c5639b2cd7347fd6793adea7",        "stage": "main_loop"      }    },    "prometheus_exporter": { "status": "ready" },    "consistency_checker": {      "status": "ready",      "details": { "first_checked_batch": 3431 }    },    "commitment_generator": {      "status": "ready",      "details": { "l1_batch_number": 3453 }    },    "batch_status_updater": {      "status": "ready",      "details": {        "last_committed_l1_batch": 3430,        "last_executed_l1_batch": 3430,        "last_proven_l1_batch": 3430      }    },    "ws_api": { "status": "ready" },    "http_api": { "status": "ready" },    "main_node_http_rpc": { "status": "ready" },    "reorg_detector": {      "status": "ready",      "details": {        "last_correct_l1_batch": 3453,        "last_correct_l2_block": 14072      }    }  }}

Resetting the Node State

docker-compose --file <network>-external-node.yml down --volumes

API Access

The HTTP JSON-RPC API will be exposed on port 3060 (localhost:3060).
The WebSocket API will be exposed on port 3061 (localhost:3061).

System Requirements

The following are minimal requirements:

CPU: A relatively modern CPU is recommended.
RAM: 32 GB
Storage:
- Testnet Nodes: 30 GB
- Mainnet Nodes: 300 GB, with the state growing.
Network: 100 Mbps connection (1 Gbps+ recommended)

Advanced Setup

For additional configurations like monitoring, backups, recovery from DB dump or snapshot, and custom PostgreSQL settings, please refer to the ansible-en-role repository.