Python Executor

Responsibilities and boundaries

Python Executor runs user functions inside the CPython host process. It receives function execution work from the Worker and routes suspended backend operations through the host bridge. EVM queries carry the chain and block supplied by the function. Use Write EVM data functions for the programming workflow. This page describes the execution component.

Code location

Source in the BlockX repository	Responsibility
`pyhost/src/main.c`, `pyhost/src/embed.c`	Host startup and embedded interpreter
`pyhost/src/sched.c`, `pyhost/src/coro.c`	Host scheduling and coroutine support
`pyhost/src/bridge.c`, `pyhost/src/proto.c`	Host bridge and wire handling
`python/blockx_runtime/`	Function entry, module loading, and backend bridges
`python/blockx_audit/`	Static source auditing and capability tables
`internal/worker/adapters/executor/`	Worker-side host processes and connections

Core types and interfaces

Interface	Role
`bxpy_coro`	Owns one native stack and `PyThreadState` for a resident call
`bxpy_coro_park` / `bxpy_coro_resume`	Suspend a crossing and resume on the owning interpreter thread
`bxpy_cross`	Carries bridge operation inputs, output, and failure while parked
`execute` / `release_task` / `release_tasks`	Run one request and release completed tasks’ namespaces
`CallContext` / `call_scope`	Track call identity, debug state, arguments, and balanced context entry/exit
`ModuleRegistry.load_callable`	Load source by digest and return the resolved entry from its namespace
`resolve_entry_name`	Share entry selection between source auditing and runtime loading
`HostProvider`	Implement SDK reads, writes, subcalls, and cooperative sleep over the host bridge
`host.io_value` / `host.io_json` / `host.io_rpc`	Carry backend requests through the host boundary
`host.fetch_source` / `host.subcall`	Fetch function source and dispatch child calls
`wire.pack`	Apply Python return-value conversions before host encoding
`NodeRPCBridgeProvider`	Routes EVM node requests through `host.io_rpc`
`EVM`	Function-visible object carrying chain and block context
`install_noderpc_bridge`	Installs the runtime’s per-chain bridge providers

python/blockx_runtime/host.py defines the Python-facing host bridge. Capability names available to audited code are maintained in python/blockx_audit/tables.py.

Data flow / execution flow

The Worker dispatches a function and its arguments to the Executor host.
The runtime loads the function definition and invokes its entry point.
State reads and contract queries pass through NodeRPCBridgeProvider with chain and request parameters.
Worker IO serves the backend request and the host resumes the computation.
The function returns its output; the Worker collects it for the selected Writer Plugin.

The function’s EVM object supplies the read context. A task’s function-code snapshot fixes definitions separately from the block used by data reads.

Function loading and entry resolution

ModuleRegistry caches compiled source by digest and maintains per-task namespaces. It can fetch missing source through host.fetch_source. Releasing a task drops its namespaces; function identity and version selection are described in Function Code View. resolve_entry_name in python/blockx_audit/tables.py supplies the shared selection rule. The runtime applies it to entrySelector:

Use the selector’s final segment when it names an eligible top-level function.
Otherwise use _, defined as a function or as an alias to a top-level function.
Otherwise use the first eligible public top-level function in source order.
If none exists, resolve to _ and report the missing callable during loading.

Names beginning with __ and dangerous builtin names cannot be selected by the named-entry rule. The public fallback skips names beginning with _ and dangerous builtin names. Audit binding checks reject an alias that rebinds an existing _ definition.

Return-value serialization

python/blockx_runtime/wire.py converts Python values before the host packs them into a value program. The Worker converts that program to the JSON carried in results.

Python value	Output behavior
`int`, including `2**256 - 1`	Preserves the integer without narrowing to a floating-point value
`datetime`	RFC 3339; naive values and `timezone.utc` use `Z`, other aware values retain their offset; nonzero microseconds are preserved
`date`	ISO date string
Dataclass instance	Converts through `dataclasses.asdict`; prefer returning a plain dictionary
Non-finite `float`	JSON `null`
Unsupported value, such as `set`	Encoding fails with `terminal_encode_failed`, marked non-retryable

Keep EVM uint256 values as Python integers through the computation. Consumers must also decode JSON integers without precision loss. Wire conversion does not grant audited functions additional imports or capabilities.

State and lifecycle

The Worker manages Executor host processes and their connections. Runtime initialization installs bridges and prepares function execution. Function source loading and version identity are coordinated with Function Code View.

Suspension and resume invariants

The native host keeps multiple calls resident on one interpreter thread and runs one coroutine at a time. Preserve these invariants when changing scheduling or bridges:

Invariant	Enforcement
A call retains its own native stack and `PyThreadState` throughout execution	`bxpy_coro_resume` requires the owning OS thread and the interpreter GIL
A parked request remains valid until resume	`bxpy_cross` and its borrowed inputs remain on the preserved coroutine stack
Backend waits return control to the scheduler	IO, source fetches, subcalls, and sleep park the coroutine; budget reads, checkpoints, and logging execute in place
A response resumes only its current wait	`handle_resume` checks call state and request ID; stale responses are ignored
Call context is balanced	`call_scope` pushes and pops the same `CallContext`; an unbalanced stack raises an error
Reuse cannot inherit the previous call’s execution state	`bxpy_coro_reset` clears per-call state, checks that execution has unwound, and assigns a fresh identity

The scheduler tracks CS_QUEUED, CS_RUNNABLE, CS_RUNNING, CS_WAIT_IO, CS_WAIT_FUNCTION_CODE, CS_WAIT_SUBCALL, CS_WAIT_SLEEP, and CS_DONE. Cancellation and deadline decisions belong to the host scheduler; the runtime encodes their terminal outcomes. An EVM backend response resumes the waiting function with its existing call context.

Configuration

Setting	Role
`EXECUTOR_HOST_BIN`	Host executable; default `blockx-pyhost`
`PYTHON_BIN`	Interpreter used for the audit process
`PYTHONPATH`	Runtime modules and installed function dependencies
`EXECUTOR_COUNT`	Number of Executor processes

The host embeds CPython 3.14 or later. Follow the Quickstart to build it and supply the virtual environment’s package directory.

Extension points

Add function-visible capabilities through the runtime bridge and the owning backend adapter. Update audit capability tables when changing the allowed function interface. Verify that chain and block context reach the backend request unchanged.

Testing

The following tests in the BlockX repository cover bridge integration, entry selection, module namespaces, and return-value conversion, using host doubles where needed:

cd python
.venv/bin/python -m unittest \
  tests.test_runtime_leafage tests.test_noderpc_bridge \
  tests.test_runtime_entry tests.test_runtime_module_registry tests.test_runtime_wire

Host and process tests also cover the native execution boundary. Their shared environment setup is in internal/testutil/pyhost.go.

Design reference in the BlockX repository: docs/specs/function-code-python-whitelist.md.

Get started

Core concepts

Guides

Reference

Architecture

Components

Development guide

Responsibilities and boundaries

Code location

Core types and interfaces

Data flow / execution flow

Function loading and entry resolution

Return-value serialization

State and lifecycle

Suspension and resume invariants

Configuration

Extension points

Testing

​Responsibilities and boundaries

​Code location

​Core types and interfaces

​Data flow / execution flow

​Function loading and entry resolution

​Return-value serialization

​State and lifecycle

​Suspension and resume invariants

​Configuration

​Extension points

​Testing

​Related docs

Responsibilities and boundaries

Code location

Core types and interfaces

Data flow / execution flow

Function loading and entry resolution

Return-value serialization

State and lifecycle

Suspension and resume invariants

Configuration

Extension points

Testing

Related docs