blockx-py

BlockX combines compute functions with triggers, inputs, and result writes. Use these driver interfaces in Notebooks by default; function.call() also supports reuse inside a Function. See the source for full implementations and low-level interfaces.

Synchronous Function calls

`function.call(function_id, *args, timeout=5)`

from blockx import function

amount = function.call('demo.usdc_amount', 1500000)
print(amount)

function_id is a saved Function ID, and *args are positional arguments passed as given, not converted to the Function’s declared parameter types. This example returns 1.5 after you create the example function in Create a Function. timeout is in seconds and defaults to 5, which is also the maximum; larger values are rejected. In a Notebook, you can set a shorter deadline. Inside a Function, nested calls are bounded by the parent’s remaining deadline; increasing a child timeout cannot extend the whole execution. Failures raise FunctionInvokeError, with commonly used attributes code, message, retryable, call_id, and origin. origin says where the failure belongs: FAILURE_ORIGIN_USER for an error in the function’s own code, FAILURE_ORIGIN_CAPACITY when no compute capacity is available, and FAILURE_ORIGIN_SYSTEM for a platform-side failure.

Function descriptor

`Function(source_code=None, function_id='', name='', mode='inline')`

Parameter	Description
`source_code`	Inline Python source with `_` as the entry point
`function_id`	Saved Function ID
`name`	Optional name
`mode`	Currently supports `inline`

Provide source code or a Function ID. This object describes a function for task configuration; constructing it does not execute or save the function. Block and bundle tasks accept a saved Function ID only; DirectCallConfig is the one that also accepts inline source.

Pipelines and triggers

`Pipeline(sources, target, requires=None, condition=None, readiness=None)`

Parameter	Description
`sources`	Trigger sources, at least one; each is a dictionary whose keys are listed below
`target`	Target table ID or object, whose kind decides how results are written
`requires`	Dependency tables: they trigger nothing and are not passed as arguments, but their data must be ready at a height before it is processed
`condition`	Conditional update when writing a Normal Table; ignored for other target kinds
`readiness`	Readiness rule for the realtime phase; for its values, see block subscriptions in blockdb-py

Keys of a trigger-source dictionary:

Key	Description
`table_id`	Source table ID or object
`func_id`	Saved Function ID
`args_tmpl`	Positional argument list; use `ROW` for the source record. `UINT256` fields in the source record arrive as Python `int`; other fixed values pass through unchanged
`operator`	Optional filter expression built with `filter()` from `blockdb.operator`

Method	Parameters	Behavior and return value
`backfill(start, end=None, *, progress=None)`	Inclusive height range; without an end, uses available upstream progress	Backfills and returns `BackfillResult`
`update(lookback=100)`	Blocks to replay when resubscribing	Fills target gaps from the table’s start height, then continuously processes new events

If a new block table has no start height, update() fills block by block from height 0, which takes a long time. Set the start height first if you only need recent data, or run backfill() first for history. The same table may appear in both sources and requires: as a source it supplies candidate heights, and as a dependency it requires that height to be fully processed. Common BackfillResult attributes:

Attribute	Meaning
`ok`	Whether every submission stage succeeded
`done_blocks`	Number of blocks processed successfully
`written_rows`	Counted rows written
`failed_ranges`	Failed ranges as `(start_height, end_height, code, message)`

Batch writes in a large backfill may run asynchronously, so confirm the target table’s write jobs and consensus progress separately. For a runnable configuration, see Build a Pipeline.

Custom tasks

`DirectCallConfig(func_id=None, args_list=None)`

func_id accepts a Function ID, a callable, or a Function object. args_list is a list of positional-argument lists, and each sublist triggers one call.

from blockx import DirectCallConfig, ReturnValueHandler, TaskBuilder

config = DirectCallConfig(
    func_id='demo.usdc_amount',
    args_list=[[1500000], [2000000]],
)
task = TaskBuilder.build(config, ReturnValueHandler())
result = task.submit(timeout=30)
if not result.task_result.success:
    raise RuntimeError(result.error)
print(sorted(result.handler_result))

A successful run prints [1.5, 2.0]. Raw result order is not guaranteed to match input order; carry a business ID in the return value when you need to correlate them.

`TaskBuilder.build(call_config, handler)`

Returns an unsubmitted Task. task.submit(timeout=None) submits and waits, returning TaskResult; timeout is in seconds and defaults to the server’s own value. Asynchronous Python code can use await task.submit_async(timeout=...).

`TaskResult` attribute	Meaning
`task_result.success`	Whether the task succeeded
`task_result.failure_code`	Failure code
`task_result.retryable`	Whether the failure is marked retryable
`handler_result`	Content returned by the result handler
`error`	Error identifier, usually `None` on success

Block task inputs

Configuration object	Parameters and purpose
`BlockCallConfig(block_id=None, sources=None)`	Reads source tables at one block; `block_id` is the block ID string
`BundleCallConfig(bundle_id=None, sources=None)`	Reads by block bundle; `bundle_id` is the bundle number
`BundleCallConfigTemplate(sources=None)`	Holds the trigger sources only; `for_bundle(n)` produces that bundle’s configuration

sources uses the same keys as a Pipeline’s trigger sources, and ROW marks the argument position of the source record.

Result handlers

Handler	Parameters	Write contract
`ReturnValueHandler()`	None	Collects function return values and hands them back to the Notebook
`NormalTableWriteHandler(target, condition=None)`	Target Normal Table and optional condition	Returned records should include the primary key and business fields
`TimeTableWriteHandler(target)`	Target Time Table	Returned records contain `id`, `time_at`, and `value`, and one task shares one `time_at`
`BlockTableWriteHandler(target)`	Target block table	Writes results and the matching block progress; returned records must include `block_id`, `block_height`, and `block_timestamp`

The block handler carries no block or bundle of its own: the write position comes from the same task’s input configuration, so the two cannot disagree. It therefore requires a BlockCallConfig or a BundleCallConfig. A standard Pipeline picks the handler from the target table’s kind. Per-block writes have the server fill in the three block fields. Bundle writes do not: a bundle whose records lack them fails to write, while the backfill result still reports success. The full bundles within backfill() and every backfill_block_bundles() run are written by bundle, so copy the three fields from the source record and return them.

Backfill helpers

backfill_block_bundles(start_bundle_id, end_bundle_id, config, handler, *, retry=2, timeout=None, progress=None, abort_if_first_fails=True)

runs a custom bundle backfill: pass a BundleCallConfigTemplate as config and a write handler as handler. The range is inclusive on both ends, and it returns a BackfillSummary.

`BackfillSummary` attribute	Meaning
`ok`	Whether no bundle failed
`total` / `succeeded` / `failed`	Bundles in this run, and how many succeeded and failed
`failed_bundles`	Numbers of the failed bundles
`written_rows`	Counted rows written
`wall_seconds`	Duration of this run

retry is the number of on-the-spot retries per bundle. When the first bundle still fails after its retries, the whole run aborts by default, because that is usually a configuration problem. Omitting progress prints progress by completion percentage; pass a callable to handle it yourself. bundle_height_range(bundle_id) returns the height range a bundle covers. For low-level configuration and the LocalTestService testing interface, see GitHub.

Overview

Quickstart

Guides

Reference