Quickstart

Run a local task and inspect its returned values. This smoke test uses an in-process sample backend. After it works, follow Write EVM data functions to add chain and block context with real node access.

Prerequisites

Go 1.26.4, a C compiler, Make, and pkg-config.
CPython 3.14 or later with embedding development files, and uv.
Access to the BlockX repository and its private dependencies.

Prepare the checkout

git clone git@github.com:Chaintable/blockx.git
cd blockx
go mod download
uv sync --project python

The dependency versions come from python/pyproject.toml. See Local development for contributor workflows.

Build the Worker and Executor host

go build -o /tmp/blockx-worker ./cmd/worker
make -C pyhost PYTHON="$PWD/python/.venv/bin/python"

The Executor host embeds CPython. Its module path must include both the repository’s runtime and the virtual environment’s packages.

Start the Worker

Run from the BlockX repository root:

BLOCKX_SITE_PACKAGES="$(python/.venv/bin/python -c 'import sysconfig; print(sysconfig.get_path("purelib"))')"
WORKER_LISTEN=127.0.0.1:9221 \
WORKER_ADDR=127.0.0.1:9221 \
EXECUTOR_COUNT=1 \
EXECUTOR_HOST_BIN=$PWD/pyhost/bin/blockx-pyhost \
PYTHON_BIN=$PWD/python/.venv/bin/python \
PYTHONPATH=$PWD/python:$BLOCKX_SITE_PACKAGES \
ETCD_ENDPOINTS=none \
ICEBERG_NAMESPACE=chaintable_test \
BLOCKX_USAGE_DISABLED=true \
BLOCKDB_TIME_WRITE_ADDR=127.0.0.1:1 \
STUB_BLOCKDB_DELAY_MS=0 \
/tmp/blockx-worker

Wait for worker listening and executor started in the log. The local example skips etcd registration and uses a stub read backend. The time-write address satisfies startup configuration; this example does not write to it.

Start the proxy and submit

In another terminal, from the same repository root:

python/.venv/bin/python examples/local_test_service/local_proxy.py

Keep that process running. In a third terminal, submit the sample task:

python/.venv/bin/python examples/local_test_service/submit.py

[{'message': 'hello, ct2'}, {'message': 'hello, blockx'}]

The two records can appear in either order. The sample uses InputsCallConfig and ReturnValueHandler; it returns values without writing a table.

If you get stuck

Symptom	Check
Host build fails	CPython version, embedding headers, compiler, and `pkg-config`
Executor cannot import a package	`PYTHONPATH` includes the virtual environment’s site-packages
Worker rejects startup configuration	The variables in the start command are present
Proxy connection fails	The proxy is running and `PROXY_SOCKET_PATH` matches its socket

Next steps

EVM computation model: choose a chain, block, and data source.
Write EVM data functions: read contract state.
Run once: submit your own arguments.
Compute per block: produce derived table data.

Get started

Core concepts

Guides

Reference

Architecture

Components

Development guide

Prerequisites

Prepare the checkout

Build the Worker and Executor host

Start the Worker

Start the proxy and submit

If you get stuck

Next steps

​Prerequisites

​Prepare the checkout

​Build the Worker and Executor host

​Start the Worker

​Start the proxy and submit

​If you get stuck

​Next steps

Prerequisites

Prepare the checkout

Build the Worker and Executor host

Start the Worker

Start the proxy and submit

If you get stuck

Next steps