Skip to main content
A Keystone bolt-on is a small package that declares an algovoi.keystone.steps entry point. Once it is installed, it is discovered automatically by any Keystone control panel or conformance verifier, with no catalogue edit and no coordination required. This guide takes a bolt-on from an idea to a published, installable package.

​
1. Create the package

The quickest way is the control panel: install it and open the Create a Keystone bolt-on card. 
pip install algovoi-keystone-control
algv-keystone
Enter a name, choose the canonical ref you want to alias onto, and download the zip. (The keystone-alias scaffolder in the AlgoVoi verifier toolkit produces the same skeleton from the command line.) Either way you get: 
<name>/
  pyproject.toml            # declares the algovoi.keystone.steps entry point
  <module>.py               # your ref() builder + keystone_step() descriptor
  tests/test_conformance.py # determinism + descriptor checks (passes out of the box)
  NOTICE

​
2. Make it yours

  • In <module>.py, set the fields your reference commits to inside <name>_ref(payload). Keep the construction as "sha256:" + SHA-256(RFC 8785 JCS(payload)) so anyone can recompute and verify it with the two open standards, no special software.
  • In keystone_step(), set order (the position in the chain) and a one line posture.
  • Leave alias_of pointing at the canonical Keystone ref you are extending.

​
3. Build the wheel

Bolt-ons are pure Python, so the wheel builds anywhere and installs on any platform: 
python -m pip install build
python -m build --wheel
# -> dist/<name>-0.1.0-py3-none-any.whl

​
4. Publish

python -m pip install twine
twine upload dist/*

​
5. Verify and confirm discovery

pip install <name>
keystone-verify <name>     # checks the descriptor + recompute
A pass means the bolt-on recomputes its reference deterministically and declares a valid alias onto a canonical layer. From that point on it appears in the Keystone control panel and is picked up by any conformance verifier automatically, because discovery runs through the entry point rather than a fixed list.

​
Versioning

To ship an update, bump version in pyproject.toml, rebuild the wheel, and publish it alongside the previous version. Consumers pin with <name>==x.y.z for reproducible installs.