Build and test a Keystone bolt-on

Bolting onto the Keystone should be small. algovoi-keystone-connect is an open (Apache-2.0) toolkit with two halves: build a data-plane connector from a declarative spec, and test any bolt-on at any stage of the chain, fully offline. Every reference reduces to one primitive, ref = "sha256:" + SHA-256(RFC 8785 JCS(payload)), so there is no AlgoVoi software in your trust base and nothing new to learn.

algovoi-keystone-connect is pure Python and readable on purpose: the whole binding is about thirty inspectable lines. It installs from the Keystone control panel (the integrity path, from the AlgoVoi index) and, like the connectors, is also available from PyPI for those not using the panel. Its output is byte-identical to the hand-written connectors, so records drop straight into algovoi-keystone-validate.

Install

pip install algovoi-keystone-connect

CPython 3.10 to 3.13 on Linux (x86_64 / aarch64) or Windows (AMD64). Prerequisites, the AlgoVoi-index integrity path, control-panel setup, and keystone doctor verification are documented once on the Keystone install hub.

Build a connector

A connector binds each real write on a data plane to the decision_ref that authorised it. With the toolkit that is a spec, not a class:

from algovoi_keystone_connect import connector

keystone_s3 = connector("s3", writes={
    "put_object":    ("put",    lambda call: f"{call.kwargs['Bucket']}/{call.kwargs['Key']}"),
    "delete_object": ("delete", lambda call: f"{call.kwargs['Bucket']}/{call.kwargs['Key']}"),
})

client = keystone_s3(boto3_s3, decision_ref=decision_ref)
client.put_object(Bucket="receipts", Key="2026/r1.json", Body=b"{}")   # bound
ref = client.execution_ref

That is a complete connector. writes maps each write method to (action, scope_fn). The scope_fn(call) receives a Call(args, kwargs, client), so it reads call.kwargs or call.args for per-call values and call.client for fixed context such as a container name or a queue entity. Reads pass through unbound; a write that raises is recorded FAILED and re-raised. The emitted execution_ref is byte-identical to the hand-written algovoi-keystone-s3, so the short way and the long-hand way are provably the same.

Test a bolt-on at any stage

You do not need a live gateway or real payments to know a bolt-on is correct. synth_ref(stage) gives a content-addressed stand-in for whatever precedes your bolt-on, and the check battery verifies the keystone properties.

Execution stage (a connector)
Any stage (a ref-builder)

from algovoi_keystone_connect import check_connector

report = check_connector(keystone_s3, FakeS3(), [
    ("put_object", {"Bucket": "receipts", "Key": "r1"}),
])
assert report.ok
print(report)

from algovoi_keystone_connect import check_ref_builder, synth_ref, keystone_ref

def mandate_ref(payload):
    return keystone_ref(payload)

report = check_ref_builder(
    mandate_ref,
    {"passport_ref": synth_ref("passport"), "cap": "500USD", "scope": "payments"},
    prev_field="passport_ref",
)
assert report.ok

check_ref_builder works at any stage of the chain, passport through trust_query, because every stage is the same primitive over its own payload.

The conformance battery

Both checks return a Report with an ok roll-up. Between them they assert:

Property	Meaning
Recompute	the recorded fields reproduce the claimed `execution_ref` byte for byte
Decision-bound	swap the `decision_ref` and every reference changes
Tamper-evident	mutate the scope and the reference no longer recomputes
Self-describing	each record carries the fields a verifier needs, with no mapping
Predecessor-bound	a ref-builder binds to its upstream stage

A connector that ignores its decision_ref, or a ref-builder that is not content-addressed, fails report.ok. The harness never crashes on a broken bolt-on; it reports the failure.

Package and publish

For internal use the connector(...) value is enough: wrap your client and go. To share a connector, wrap it in a small module and publish it like any other Keystone bolt-on, per Publishing a Keystone bolt-on. Consumers get the same one-line ergonomics and can self-certify with the same check_connector battery, so coverage of new data planes becomes the ecosystem’s job, not a bottleneck.

One primitive

Everything above is one function:

from algovoi_keystone_connect import keystone_ref

keystone_ref(payload)   # "sha256:" + SHA-256(RFC 8785 JCS(payload))

Any party recomputes any reference with a stock RFC 8785 implementation and standard SHA-256, with no AlgoVoi software involved. That is what lets a developer build on the Keystone without adopting it into their trust base. See the connector catalogue and the Keystone chain.

Get started

Platform

Concepts

Keystone

Agent Mesh

Substrate 2

Commercial

Open substrate

Payment protocols

Chains

Integrations

Help

Company

Build and test a Keystone bolt-on

Install

Build a connector

Test a bolt-on at any stage

The conformance battery

Package and publish

One primitive

​Install

​Build a connector

​Test a bolt-on at any stage

​The conformance battery

​Package and publish

​One primitive

Install

Build a connector

Test a bolt-on at any stage

The conformance battery

Package and publish

One primitive