Skip to content

Getting started

Install

Not yet on PyPI — install from source (Python ≥ 3.12). uv recommended:

git clone https://github.com/starling-foundries/Burin.git
cd Burin
uv sync                      # or:  pip install -e .

To depend on it from another project, add an editable path source:

# your project's pyproject.toml
[project]
dependencies = ["burin"]

[tool.uv.sources]
burin = { path = "../burin-public", editable = true }

Fingerprint a region and prove its cells

The everyday tool: a polygon becomes a deterministic 32-byte fingerprint, and you can prove which equal-area cells it covers against the root.

from shapely.geometry import box
from burin.coverage import fingerprint_polygon_hex, SpatialMerkleTree

# Same polygon + resolution → the same 32 bytes, computed by anyone, anywhere.
fp = fingerprint_polygon_hex(box(-0.13, 51.50, -0.10, 51.52), resolution=10)
print(fp)   # 27a7de10...f8a53695

# Commit a set of cells; prove one is covered and another is not.
tree = SpatialMerkleTree.from_suids([("Q", 4, 5, 3), ("Q", 4, 5, 7)], max_depth=4)
assert tree.membership_proof(("Q", 4, 5, 3)).verify(tree.root_hash, 4)       # covered
assert tree.non_membership_proof(("Q", 4, 5, 0)).verify(tree.root_hash, 4)   # absent

A cell is an rHEALPix SUID: a base cell N,O,P,Q,R,S followed by digits 0..8, one per resolution level. ("Q", 4, 5, 3) is the path root → Q → 4 → 5 → 3.

Seal what + where + when

The kernel signs an opaque 32-byte commitment together with an optional cell and time into one seal that verifies offline — recompute the composite and check the signature, no server.

from burin.kernel import make_seal, verify_seal, Identity

me = Identity.generate()   # a signing key (software here; a secure element in production)
seal = make_seal(me, commitment=b"\x11" * 32, cell=("Q", 4, 5), time_us=1_000_000)
assert verify_seal(seal).ok

The same operations are available on the command line:

uv run python -m burin.kernel seal --cells cells.json --depth 4 --cell Q,4,5 --time 1000000 \
    --key me.json --ledger log.json --out seal.json
uv run python -m burin.kernel verify --seal seal.json
uv run python -m burin.kernel detect-fraud a.json b.json     # equivocation / backdating → exit 1
uv run python -m burin.kernel words  --seal seal.json        # 24 BIP-39 words
uv run python -m burin.kernel burst  --seal seal.json        # 70-byte satellite burst

Where next