Function code

A user function is a piece of Python source code. It is compiled, cached, and invoked inside the Python Executor process on the Worker’s own machine: each call invokes the entry function once, and the entry function’s return value is the output of that call. The function is responsible only for “computing”, not for “writing”.

Entry point conventions

The Executor picks the entry point among the top-level defs in the source by the following priority (resolve_entry_name in python/blockx_audit/tables.py):

The last segment of functionId. For example, the entry point of the registered function token.trace_to_token_transfer is def trace_to_token_transfer.
A top-level def named _, or an alias line _ = <function name>. When blockx-py packages a Python callable into source, it adds this alias line automatically.
The first top-level def in source order whose name does not start with _.

The simplest way to write inline source is to define _ directly:

def _(chain_id, record):
    value = float(record.get("value") or 0)
    if value <= 0 or not record.get("tx_id"):
        return None
    return {
        "id": record["id"],
        "chain_id": chain_id,
        "from_addr": record["from_addr"],
        "to_addr": record["to_addr"],
        "value": value,
    }

The function body must be self-contained: module-level constants and helper functions go inside the function body, and the modules you use are imported inside the function body.

Arguments and return values

Arguments are passed by position and come from the call’s args:

Call Builder	Where the arguments come from
`InputsCallConfig`	Each row of `callList` is the argument array of one invocation
`BlockTableCallConfig` / `BlockBundleCallConfig`	Assembled from the `params` template: the position holding `"${<table>}"` is replaced with one row of the trigger table (a dict), and the other positions are passed through as is; when `params` is empty, the whole row is the only argument

The keys of the row dict are the column names of the source table, and the values are the JSON-decoded values. In blockx-py, the SOURCE_ROW constant replaces the hand-written "${<table>}". Return values must be JSON serializable:

Return value	Meaning
`dict`	One row. Table-writing plugins project only the columns that belong to the target table; extra keys are ignored
`list[dict]`	Multiple rows
`None`	This invocation produces nothing. Table-writing plugins skip it; `ReturnValueHandler` records it as `null`

Where functions come from

Source	How it is declared	Identity
Inline source	Submitted with the task: `code.sourceCode`; in blockx-py, use `Function(source_code=...)` or pass a callable directly	The Worker generates `inline-<first 8 chars of the digest>` from the SHA-256 of the source
Registered function	Only `functionId` is given (in the form `space.name`); the source comes from the function table	`functionId` plus the digest in the snapshot

The source of registered functions is maintained by the Worker’s Function Code View: it subscribes to the system.function table in BlockDB, or periodically does a full refresh from a Redis hash (FUNCTION_CODE_REDIS_URL), and publishes a complete new snapshot on every change. Local development uses an in-memory function library (devstub).

Version pinning

A snapshot epoch is pinned when the task is activated; all calls and sub-calls of that task resolve functions against the same snapshot, and hot updates only affect tasks submitted afterwards.
Only the source digest is dispatched to the Executor. The Executor caches compiled artifacts by digest, and on a miss pulls the source back from the Worker by digest.
Within one task, binding the same functionId to different source, or an inline function colliding by name with a snapshot function, makes that ID fail deterministically.

What a function can do

Capability	How to write it	What happens
Read BlockDB	`Table` / `BlockTable` / `TimeTable` from blockdb-py	The gRPC channel is replaced with a BridgeChannel when the Executor starts; requests go back over UDS to the Worker’s IO subsystem and benefit from caching, singleflight, and admission control
Call a chain node	leafage-py (`ChainState` and others)	Likewise patched back to the Worker’s NodeRPC adapter
Call other functions	`from blockx import function`, `function.call("space.name", *args)`	Becomes a sub-call inside the Executor: same task tree, same code snapshot, same IO scope; depth limit `MaxSubcallDepth = 8`
Capability backends	Classes such as `LocalTestService` and `Router` in blockx-py	Ordinary gRPC clients; intercepted and dispatched inside the Worker process
`time.sleep`	stdlib	Patched into a local timer that yields the greenlet, without occupying the Executor

What a function cannot do:

Write BlockDB directly. All writes go through the Writer Plugin the task declares.
Access external services bypassing the SDK. When auditing is enabled, import only gives you whitelisted modules.
Share state across calls. Module namespaces are isolated per task, and there is no ordering between calls.

Execution budget

A single call’s execution budget is CallDeadlineMs = 5000, counting only CPU and IO backend time, not queueing; exceeding it fails that call.
Pure CPU loops are preempted by the Executor’s SIGALRM timer, and the greenlet yields while waiting on IO.
The call budget and the task timeout are independent of each other; a task timeout converges the whole task to TIMED_OUT.

Static auditing

The Worker’s FUNCTION_CODE_AUDIT_MODE decides whether source goes through static auditing before dispatch:

Mode	Behavior
`off` (default)	No auditing; the function runs in an ordinary namespace
`enforce`	A failed audit or an unavailable auditor both refuse dispatch; the call fails with `function_code_audit_rejected` and is not retryable; code that passes runs in a restricted namespace
`dark`	Audits and logs, but does not block

The audit only does ast.parse and does not execute code. It checks that syntax nodes, imports, and attribute accesses are within the whitelist, and does type tracking on return values and capability boundaries; the restricted namespace provides only SAFE_BUILTINS and facades of whitelisted modules. The Sync Invoker’s Precheck uses the same auditor, auditing without executing, which is suited to showing authors the violations before submission. See docs/specs/function-code-python-whitelist.md in the blockx repository for the full whitelist.

Summary

The entry point is looked up first by the last segment of functionId, then _, and finally the first public def.
Arguments are passed by position; scanning Builders use the "${<table>}" (SOURCE_ROW) placeholder to slot in the row dict; return dict / list[dict] / None.
Functions are read-only; all IO is intercepted through the SDK back to the Worker; writes are done by the Writer Plugin.
Each task pins one code snapshot; a single call has a 5-second budget; audit enforce mode fails closed.

Continue reading:

Function Code View: the implementation of snapshots, epochs, the syncer, and the audit chain.
Python Executor: the user function programming model, greenlet suspension, and SDK interception points.
Call Builder and Writer Plugin: how the params template and return values land in tables.
Submit a task: examples: a complete runnable function and task.

Get started

Core concepts

Architecture

Components

Development guide

Entry point conventions

Arguments and return values

Where functions come from

Version pinning

What a function can do

Execution budget

Static auditing

Summary

​Entry point conventions

​Arguments and return values

​Where functions come from

​Version pinning

​What a function can do

​Execution budget

​Static auditing

​Summary

Entry point conventions

Arguments and return values

Where functions come from

Version pinning

What a function can do

Execution budget

Static auditing

Summary