Build on blindrange — Python

1Install

Python 3.10 or newer. Upgrade pip inside the venv first — a fresh venv seeds whatever pip the system Python bundles, and anything older than pip 21 predates the packaging standard used here and fails with a message about a missing setup.py.

git clone https://github.com/alviso/blindrange && cd blindrange
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .

You can point at the public demo network and write nothing yourself:

# bootstrap seed.blindrange.dev:7501, secret "blindrange-public"
.venv/bin/python examples/quickstart.py

2Describe your data

A schema names the fields you want to query and how precisely. This is the only place in the whole system where you make a privacy decision, so it is worth thirty seconds.

schema = {
    "amount": {"type": "int", "bits": 20, "leaf_width": 64},
    "day":    {"type": "int", "bits": 16, "leaf_width": 16},
    "status": {"type": "str", "bits": 30, "chars": 6, "leaf_width": 16},
}

Starting points for the fields most applications actually have:

Fields you do not list are still stored and returned — they are simply not queryable, and nothing about them is indexed. In the example, customer is carried along and never appears on any node.

3Create the database

db = Owner.create(
    "orders.brdb",                        # state_path
    "correct horse battery staple",       # passphrase
    schema,                                # from step 2
    bootstrap=["seed.blindrange.dev:7501"],  # any live peer
    network_secret="blindrange-public",      # which network
)

Reopening takes neither the schema nor the secret — both live in the state file:

db = Owner.open(state_path, passphrase, bootstrap=bootstrap)

Then say local-first once — the SQL layer and the npm package default it, the raw API asks:

db.enable_mirror()

Reads — including proving something absent — now answer from a complete encrypted mirror beside the state file; only writes touch the network.

Both calls are exercised by quickstart.py, which takes these as command-line arguments so you can point it at your own network.

4Create — writing records

db.insert_many(rows)
db.drain()

insert_many returns once a quorum of replicas holds each key; drain() waits for the rest. Call it before you measure anything, and before the process exits — not after every insert, which would throw away the batching.

5Read — range, prefix, AND, ordering

hits = db.query("amount", 300, 500)
prefix = db.query_prefix("status", "ref")
both = db.query_multi([{"field": "amount", "lo": 300, "hi": 500},
                       {"field": "day", "lo": 200, "hi": 210}])

For large or unbounded results, stream in bounded memory:

newest = list(db.query_stream([{"field": "day", "lo": 0, "hi": 65535}],
                              limit=5, order="-day"))

order="-day" asks for the newest matches; ascending with a limit answers with the oldest, which is a different question.

6Read without decrypting anything

These are answered from index metadata alone. Nothing is fetched, nothing is decrypted, and the cost does not grow with the number of matches.

est, err, n = db.approx_sum("amount", 0, 1023)

# count(amount 300..500)   → 35
# histogram                → [(0, 22), (256, 35), (512, 35), (768, 28)]
approx_sum(amount)       → 64,644 ± 3,840 over 120 rows

7Update — why there isn't one

There is no update call. A record is one sealed blob under a random handle, and editing in place would mean asking a node to modify ciphertext it cannot read. So:

db.delete_many([victim["_rid"]])
db.insert_many([changed])
db.drain()

Delete first, then insert. A crash between the two costs you a duplicate rather than a hole, and a duplicate is something you can notice and fix.

8Delete — and actually reclaiming space

db.delete_many(doomed)
db.drain()

The rows stop being returned immediately. But a delete writes a tombstone: the index entries are still out there and still counted, which is why count() can exceed what queries return.

# deleted 12 rows — gone from queries immediately
# count() still says       → 12  (tombstoned, not yet reclaimed)
compact()                → kept 5,616 index entries, dropped 676
# count() now says         → 0

stats = db.compact()

9Going further

Other machines, same database

invite = db.invite()          # hand this to the other device
other = Owner.accept(path, passphrase, invite)

Multiple writers work concurrently; each owns its own append chains, so they never collide.

When one client is not enough

Data shards across nodes automatically — the ring handles that, and adding nodes adds capacity. The client is what runs out first, because compaction rewrites an epoch in memory. When that bites, split across independent master keys:

from blindrange.sharded import ShardedOwner
db = ShardedOwner.create(path, passphrase, schema, bootstrap, shards=4)

Same API. Measured at 4 shards: compaction peak memory 28.4 MB → 7.9 MB. Every range query visits every shard, so keep the count low.

What it costs

A record costs one blob plus one index entry per dyadic level per indexed field, times the replication factor. Coarse leaf_width means fewer levels. There is a calculator on the front page with the real numbers.

Check the claims yourself

Step 8 of the quickstart prints what a node actually holds for the data you just wrote:

I:0003444dfc39de14496d98436571a361  →  S/4cP9LvVoA=
I:0018472b150a157133733359a041a84e  →  F6QGdxhzbFg=
# no field names, no values, no ordering — and none of the
# customer ids appear anywhere on any node

The attack harness runs the real attacks from the literature against this design and prints the numbers, including the ones that work. Read the threat model before deciding this fits: it is explicit that this is not for healthcare or high-stakes PII, and why.