Skip to content

Local RPC node

In addition to the option of setting up an isolated local DBChain instance, as described in the local DBChain setup guide, you can also run a DBChain node locally with an execution client connected to and synchronized with an existing network (e.g., the Kaolin Testnet). This guide explains how to do that. The process is useful not only for experimentation and development but also for setting up new nodes within the network to enhance its robustness and validity.

Prerequisites

The easiest way to run a local instance of synchronized DBChain is by using our predefined docker-compose.yml file, available in a dedicated repository containing a collection of Docker Compose configurations for each publicly available network.

To use these files, both Docker and Docker Compose must be installed. The simplest way to install both is by using Docker Desktop. You can follow the official installation guide here:
https://docs.docker.com/compose/install/

Next, clone the repository mentioned above:

git clone git@github.com:Golem-Base/compose-files.git

Run DBChain Connected to a Chosen Network

Navigate to the cloned repository:

cd ./compose-files

Choose the network you want to connect to from your local machine. For example, l3-kaolin is our current testnet. To start a local node synchronized with the Kaolin network, run:

cd l3-kaolin
docker-compose up

This will launch the Rollup Node and the execution client (golembase-op-geth). If everything is working correctly, you should see logs similar to the following:

l3-kaolin-op-node-1       | t=2025-07-07T12:34:28+0000 lvl=info msg="Rollup node started"
l3-kaolin-op-node-1       | t=2025-07-07T12:34:28+0000 lvl=info msg="State loop started"

Verify Local Setup

Once you launch the local node with the execution client, the synchronization process will begin. By default, the synchronization uses a snapshot mechanism, which significantly speeds up the process. At the time of writing this guide, full synchronization with the Kaolin network takes approximately 5 minutes.

To verify that your local node is fully synchronized with the remote network, you can run the following RPC query using curl:

curl http://localhost:8545 \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"eth_getBlockByNumber","params":["latest",false],"id":1,"jsonrpc":"2.0"}'

This command queries the latest block data. The block number is provided in the number field of the response. As long as this number is "0x0", the synchronization process is still ongoing. Once synchronization is complete, you should see a non-zero value, for example:

{"jsonrpc":"2.0","id":1,"result":{"baseFeePerGas":"0xfb","blobGasUsed":"0x0","difficulty":"0x0","excessBlobGas":"0x0","extraData":"0x00000000fa00000006","gasLimit":"0x3938700","gasUsed":"0xb626","hash":"0xb5245d6cd224e03ce321fedb3061c1c398ad925d02a3d9e075cc08c605710ad8","logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000","miner":"0x4200000000000000000000000000000000000011","mixHash":"0xbec8e818086c8fc0d6aa934b9c699f1878db841008471ca220909854eb2cfbc2","nonce":"0x0000000000000000","number":"0xf1e6d","parentBeaconBlockRoot":"0x2111218d29e1b0cb833169a9e34472184cbceda6ed715efb171540c35fa927fd","parentHash":"0x6fdc44b11df2739aa8f81685bafcc2027387a520c58b96cdfe6e215dbfcda365","receiptsRoot":"0xae46db03566301934bb741f7b5364c5dbbbf379eb77cee25536ccbb99e324f88","sha3Uncles":"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347","size":"0x350","stateRoot":"0x18c3965cba2732f0d38d44ed4a97d200bd4f8157579d2bf0061e02b28f66e1d4","timestamp":"0x6867bcde","transactions":["0x21838a12d257ef075775202d60d3ef20543dadd162ed9f5b0f5acb1dece89576"],"transactionsRoot":"0x6d00c0d300699668039ca855356e3e8c8d4a9b514ff4ce8ce6c4c3a1d40db235","uncles":[],"withdrawals":[],"withdrawalsRoot":"0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421"}}

At this point, your local DBChain node is fully synchronized. You can now query the network for stored entities using standard DBChain queries via json-rpc:

curl http://localhost:8545 \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"golembase_getAllEntityKeys","params":[],"id":1,"jsonrpc":"2.0"}'
  >>>{"jsonrpc":"2.0","id":1,"result":[(...<non-empty list of keys>)]}