Quickstart

BlockDB exposes only gRPC services. This quickstart drives them directly with grpcurl and JSON — no SDK required. gRPC reflection is enabled, so grpcurl discovers the schema itself.

0. Prerequisites

A running BlockDB instance (default service address localhost:19002).
grpcurl installed.

Verify the connection and list the services:

grpcurl -plaintext localhost:19002 list

You should see blockdb.v1.TableReadService, blockdb.v1.BlockReadService, and the other services.

Step 1 — Write to a regular table

Use TableWriteService/UpsertRows. Every Value is a JSON object holding the one field you set (stringValue, intValue, doubleValue, boolValue).

grpcurl -plaintext -d '{
  "tableId": "demo.event_log",
  "rows": [
    {
      "fields": {
        "id":    { "stringValue": "evt_001" },
        "name":  { "stringValue": "login" },
        "value": { "intValue": "1" }
      }
    }
  ]
}' localhost:19002 blockdb.v1.TableWriteService/UpsertRows

A successful write returns a job ID:

{ "result": { "affectedRows": "1", "jobId": "..." } }

Writes are asynchronous. The returned jobId does not mean the data is already committed.

Step 2 — Read a row

grpcurl -plaintext -d '{
  "tableId": "demo.event_log",
  "rowId":   { "stringValue": "evt_001" }
}' localhost:19002 blockdb.v1.TableReadService/GetRow

You get back a schema plus a positional array:

{
  "result": {
    "columns": [ { "name": "id", "logicalType": "STRING" }, { "name": "value", "logicalType": "INT" } ],
    "rows": [ { "values": [ { "stringValue": "evt_001" }, { "intValue": "1" } ] } ]
  }
}

Step 3 — Write to a Block State Table

For on-chain state, use BlockWriteService/UpsertBlock with a block anchor (the example table token.token.eth is a Block State table):

grpcurl -plaintext -d '{
  "tableId": "token.token.eth",
  "block": {
    "blockId": "0x0c76b9c84c58c1d77cd4d6bd70c3cf27d7b7ae151a26c00403191f3be18114a0",
    "height":  "18000000",
    "timestamp": "2024-06-08T00:00:00Z"
  },
  "rows": [
    { "fields": { "id": { "stringValue": "acct_1" }, "balance": { "intValue": "1000" } } },
    { "fields": { "id": { "stringValue": "acct_2" }, "balance": { "intValue": "2000" } } }
  ]
}' localhost:19002 blockdb.v1.BlockWriteService/UpsertBlock

Step 4 — Read state at a block height

Anchor the read with currentBlock; BlockDB injects height ≤ target height:

grpcurl -plaintext -d '{
  "tableId": "token.token.eth",
  "stateId": { "stringValue": "acct_1" },
  "currentBlock": {
    "blockId": "0x0c76...",
    "height":  "18000000",
    "timestamp": "2024-06-08T00:00:00Z"
  }
}' localhost:19002 blockdb.v1.BlockReadService/GetState

BlockSubscribeService/Subscribe is a server-streaming call. It stays open and streams an event per block write:

grpcurl -plaintext -d '{"tableIds": ["token.token.eth"]}' \
  localhost:19002 blockdb.v1.BlockSubscribeService/Subscribe

Each event looks like:

{
  "tableId": "token.token.eth",
  "block": { "blockId": "0x...", "height": "18000001", "timestamp": "..." },
  "createdAt": "1720000000"
}

Next steps

API overview — full reference with proto, JSON, and grpcurl for every method.
Read and write data — the same operations through the blockdb-py SDK.
Write architecture — batch writes and the asynchronous model.
High-concurrency compute with BlockX

Getting started

Core concepts

Architecture

Guides

Reference

Quickstart

Quickstart

0. Prerequisites

Step 1 — Write to a regular table

Step 2 — Read a row

Step 3 — Write to a Block State Table

Step 4 — Read state at a block height

Next steps

​Quickstart

​0. Prerequisites

​Step 1 — Write to a regular table

​Step 2 — Read a row

​Step 3 — Write to a Block State Table

​Step 4 — Read state at a block height

​Step 5 — Subscribe to block write events

​Next steps

Quickstart

0. Prerequisites

Step 1 — Write to a regular table

Step 2 — Read a row

Step 3 — Write to a Block State Table

Step 4 — Read state at a block height

Step 5 — Subscribe to block write events

Next steps