Skip to content

Local standalone DBChain

DBChain operates on Layer 3 of the GolemBase architecture, as shown in the figure below:

Architecture

Each layer plays an important role in the overall ecosystem:

  • Layer 1 is responsible for security,
  • Layer 2 handles coordination and commitment of Layer 3 activities,
  • Layer 3 is the actual DBChain layer that users interact with in order to store data.

Each layer consists of several components working together to ensure the system functions as intended.

For local development and experimentation, it is possible to launch only the execution client of DBChain (indicated by the red rectangle in the diagram). This allows developers to simulate DBChain on a local machine, covering the full interface between the user and DBChain. In this setup, only the Layer 3 is used (and only one component), and an unlimited faucet is available for testing purposes.

Prerequisites

The easiest way to run a local, isolated instance of DBChain is by using our predefined Dockerfile and docker-compose.yml. Therefore, both Docker and Docker Compose need to be installed.

The simplest way to install both is by installing Docker Desktop. Please refer to the official installation guide:
https://docs.docker.com/compose/install/

Run Local DBChain

The core of DBChain currently resides in a modified op-geth execution client. To run this component locally, first clone the repository:

git clone git@github.com:Golem-Base/golembase-op-geth.git

Then navigate to the cloned directory and launch the containers using Docker Compose. The docker-compose.yml file located in the root of the repository will be used by default:

cd golembase-op-geth
docker-compose up

If you're running this for the first time, Docker will build the necessary images before starting the containers. This process may take some time.

Verify Local Setup

After completing the steps above (git clone, docker-compose up), you should see logs appearing in the terminal — especially messages like the following:

golembase-op-geth-op-geth-1      | INFO [07-02|08:05:35.501] Started P2P networking                   self=enode://bac3f4a788c67483b16610303b91194980d2c66a37791713439a402c0b1babf22c22e0896125dbfc4e5f02f72f015d2fc9f4cac92e248f14088ec4c2ea8d340a@127.0.0.1:0
golembase-op-geth-op-geth-1      | INFO [07-02|08:05:35.502] IPC endpoint opened                      url=/geth_data/geth.ipc
golembase-op-geth-op-geth-1      | INFO [07-02|08:05:35.502] WebSocket enabled                        url=ws://[::]:8545
golembase-op-geth-op-geth-1      | INFO [07-02|08:05:35.502] HTTP server started                      endpoint=[::]:8545 auth=false prefix= cors=* vhosts=*
golembase-op-geth-op-geth-1      | INFO [07-02|08:05:35.503] Started log indexer

To ensure everything is running properly, open a new terminal tab and run:

docker ps

This command lists all running containers. You should see five containers listed:

c0f5cf9d9f23   golembase-op-geth-mongodb-etl   "/usr/local/bin/mong…"   56 seconds ago   Up 43 seconds             8545-8546/tcp, 30303/tcp, 30303/udp                      golembase-op-geth-mongodb-etl-1
2bf66d112a4c   mongo:8.0.6                     "docker-entrypoint.s…"   56 seconds ago   Up 54 seconds (healthy)   0.0.0.0:27017->27017/tcp                                 mongodb
ef851064efe3   golembase-op-geth-sqlite-etl    "/usr/local/bin/sqli…"   56 seconds ago   Up 48 seconds             8545-8546/tcp, 30303/tcp, 30303/udp                      golembase-op-geth-sqlite-etl-1
374ca4451a06   dmilhdef/rpcplorer:v0.0.1       "/app/service"           56 seconds ago   Up 48 seconds             0.0.0.0:8080->8080/tcp                                   golembase-op-geth-rpcplorer-1
ed941090650f   golembase-op-geth-op-geth       "geth --dev --http -…"   56 seconds ago   Up 54 seconds (healthy)   8546/tcp, 0.0.0.0:8545->8545/tcp, 30303/tcp, 30303/udp   golembase-op-geth-op-geth-1

The most important container is golembase-op-geth-op-geth, which runs the core execution client.

Another useful container is rpcplorer, a simple block explorer that allows you to verify that everything is functioning correctly by monitoring block creation and transactions inside. To access rpcplorer, open http://localhost:8080/ in your browser.

You’ll also notice two ETL containers, which feed external databases with data stored in GolemBase, and a mongo container used for testing one of the ETL pipelines. One ETL process feeds MongoDB, while the other feeds SQLite. However, the ETL components and external databases are outside the scope of this guide.

Using the Local DBChain

You can now interact with this standalone local instance using any of the GolemBase SDKs (refer to getting-started section) or directly via curl from the command line. The RPC API is exposed on localhost at port 8545.

For example, to verify that everything is working correctly, you can run the following command:

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

This will return a list of all stored entity keys. On a freshly started instance, the result should be an empty list:

{"jsonrpc":"2.0","id":1,"result":[]}

For a complete description of the JSON-RPC API, refer to the API documentation.

Whether you're using an SDK or curl to store entities, you'll want to send transactions to your local standalone DBChain instance (in order to add/update/delete entities). This requires native ETH to cover gas fees. To top up your local wallet, run the following commands:

docker exec golembase-op-geth-op-geth-1 golembase account create
docker exec golembase-op-geth-op-geth-1 golembase account fund
docker exec golembase-op-geth-op-geth-1 golembase account balance

These commands will:

  1. Create a new managed account.
  2. Fund it with 100 ETH.
  3. Verify the balance.

The golembase CLI tool is built into the golembase-op-geth Docker container. It can be used to manage accounts, transfer funds, and interact with DBChain storage—serving as an alternative to curl or SDKs.

For more details, see the CLI section of the Getting Started guide.