# Cyberspace §7 — opening a region bag _Written 2026-09-22, after DECK-0003 (SNO) shipped its reader and left `kind 33330` closed. This is the plan for opening it._ Source: [`CYBERSPACE_V2.md`](https://github.com/arkin0x/cyberspace/blob/master/CYBERSPACE_V2.md) §2 (coordinates), §4 (Cantor trees), §7 (location-based encryption and discovery), §8.6 (the bag event). Reference implementations: `arkin0x/cyberspace-cli` (Python) and `arkin0x/cyberspace-cli-js` (TypeScript, published as `cyberspace-core`), plus `arkin0x/ONOSENDAI` as the only client that does this today. Decisions taken up front: **all three layers ship** (protocol, CLI, UI), and **every sweep is a tap** — no background CPU is ever spent on a stranger's puzzle, however cheap it looks. --- ## 1. What this reverses `amethyst/plans/2026-09-21-deck-0003-sno.md` deferred bags as decision D2, on a reason that turned out to be wrong twice over. The first version said opening a bag needs "§7.4 discovery scanning", and leaned on Amethyst having no position in cyberspace to scan from. §7.7 says the opposite in as many words: > The seeker's own position never enters this cost, because §7.1 makes looking and > walking equivalent: a region key can be computed for any coordinate without > traveling there. Scanning your own neighbourhood is the opportunistic half, and §7.7 is blunt about what it is worth alone: "a bag is found only by intentionally deep scanning and/or wandering. With no additional information, any given bag is equally likely to be at any point in the full 2^256 coordinate space: an impossibly hardened secret." ONOSENDAI's own code agrees — `destinationKeys.ts` opens with "Things are hidden in cubes, so that key almost never fits a lock." What finds a bag is a **hint**: the hider publishes an aligned box, and a seeker sweeps the candidate regions inside it. A client with no avatar, no position and no movement chain can do that. The second wrong reason was that it would cost too much. It does not, at the heights anyone actually hides at. §3 measures it. ## 2. What a bag is, end to end 1. A hider picks a coordinate and a height `h`, and derives the region key: three per-axis Cantor roots of the aligned subtrees at `h` (§4.5, §4.6), combined by nested Cantor pairing into `region_n` (§4.7), then `key = sha256(region_n)` and `lookup_id = sha256(key)` (§7.2). 2. They encrypt everything they have hidden in that region — a JSON array of nostr events — with AES-256-GCM under that key, and publish it as a `kind 33330` addressable by `d = lookup_id` (§7.6, §8.6). 3. They MAY attach a `hint` tag naming an aligned box the region lies in, one height per axis (§7.7). 4. A seeker sweeps the box: for each candidate region derive the key, hash to the `lookup_id`, and ask a relay for a bag with that `d`. Found, decrypt, verify the items, render by inner kind. The two-layer hash is the whole trick: `lookup_id` is safe to publish because it is a hash *of* the key, so seeing it buys nothing without the region preimage. ## 3. What it costs, measured A region key is three `O(2^h)` folds of BigInts that double in width at every level, plus one combine. Measured on this JVM against the same leaf-by-leaf fold `cyberspace-core` uses: | bag height `h` | one axis root | one combine + 2 SHA-256 | |---:|---:|---:| | 5 | 0.03 ms | 0.033 ms | | 8 | 0.18 ms | 0.48 ms | | 12 | 9.2 ms | 32 ms | | 16 | 555 ms | 1,873 ms | Per key (three axes plus a combine) that is 1.2 ms at h8 and 2.1 s at h16, against the spec's own figures in §7.7 of 1.3 ms and 816 ms on one desktop core — within 2 to 3x, which is what a JVM `BigInteger` (Karatsuba and Toom-Cook, no FFT) should give against C. **A sweep decomposes per axis.** The axes are independent all the way to the combine (§4.7), so a box of gap `G` costs `3 · 2^(G/3)` tree builds and `2^G` combines, not `2^G` full keys. The combine term dominates above h8: | | gap 0 | gap 6 | gap 12 | gap 18 | |---|---|---|---|---| | **h5** | instant | 2 ms | 0.14 s | 9 s | | **h8** | 2 ms | 31 ms | 2 s | 2 min | | **h12** | 60 ms | 2 s | 2 min | 2.3 h | | **h16** | 3.5 s | 2 min | 2 h | — | This agrees with §7.7's own table (gap 12 at h≤8 is "seconds", gap 24 is "hours"), and it says the affordable corner is most of the corner anyone uses. Android will be slower — measure it before quoting a number in the UI. **The growth ratio is ~2.2x per height, not 2x**, in the spec's figures and in the measurement, because a pairing doubles the leaf count *and* the operand width. A `GROWTH_RATIO_FLOOR` of that shape is what ONOSENDAI's own calibration fits. ## 4. Layer 1 — quartz, protocol only New package `quartz/.../cyberspace/`, beside the `CyberspaceScale` and `CyberspaceCoordinate` the SNO work already put there. | Piece | What | Pinned by | | --- | --- | --- | | `CyberspaceCoordinate` | §2.2 in full: interleave and de-interleave X/Y/Z/plane. Fixed 256 bits, so a `ByteArray(32)`; no bignum, no allocation per axis | §9.8's six vectors round-tripped, §7.7's three hint vectors | | `CantorTree` | §4.5/§4.6: `cantorPair`, `alignedBase`, `subtreeRoot(base, height)`, with the reference's `maxComputeHeight` refusal | `cyberspace-cli`'s own roots, through the CLI harness | | `RegionKey` | §7.2's two hashes over `int_to_bytes_be_min` | the same | | `CyberspaceHint` | §7.7 tag parse with every MUST: arity, lowercase hex, aligned base, `H` in `[0,85]`, canonical integers, `H >= h`, sector-tag agreement — and a malformed hint is **absent**, never a rejection of the bag | §7.7's three golden vectors | | `CyberspaceBagEvent` | kind 33330: `d`/`h`/`encrypted`/`hint`/sector tags, AES-256-GCM open, §7.6's plaintext rules | round trip against the reference CLI's `encrypt` | | `RegionSweep` | the axis-decomposed enumeration, as a cold sequence a caller pulls with its own budget | a unit test that a gap-0 hint is one candidate and equals the direct derivation | Two things need an `expect`/`actual`: arbitrary-precision integers (`java.math.BigInteger` on `jvmAndroid`) and AES-256-GCM (`javax.crypto`). iOS gets neither for now and the module declares it. **The rules that are easy to get wrong**, all normative, all worth a test each: - A failed decryption "MUST NOT be treated as an error in the bag" (§7.6) — it means only that this reader lacks the key. - Items MAY be unsigned. A signed item must have the canonical id and a verifying signature or it is dropped, **and only it**: "one corrupt or forged item says nothing about the others". An unsigned item's `pubkey` is a claim and MUST NOT be shown as verified authorship. - Placement is attributable to the bag's author; authorship of an item only to the item's own pubkey, and only when signed. - An item's `C` tag must lie inside the bag's region, and a reader MAY drop one that does not. - A reader that does not understand an item's kind skips it and renders the rest. ## 5. Layer 2 — `amy` Thin assembly over Layer 1, which is where interop is proven. The SNO conformance harness already runs 11 of 11 against the reference implementations; these extend it. ``` amy cyberspace coord # x, y, z, plane amy cyberspace region # region_n, key, lookup_id amy cyberspace hint # box, candidates, estimated cost amy cyberspace sweep [--budget] # the lookup_ids, or the key when found amy cyberspace open --key # decrypt, verify items, dump ``` `region` and `open` are directly diffable against `cyberspace-cli`; `hint` against `hint-reference.py`'s golden vectors. No UI decision touches any of it. ## 6. Layer 3 — Amethyst Only for a bag someone put in front of you: quoted in a note, or in a thread. Nothing sweeps the network on its own, and nothing sweeps on arrival. A `kind 33330` in a feed renders a card that has already parsed its hint and priced it, and says so: *"Hidden in a 4,096-region box — about 2 minutes of searching."* A button starts it. While it runs, progress and a cancel. Found, the items render through the cards that already exist: `3330` through `SnoObjectCard`, `1` as a note, anything else skipped. **Every sweep is a tap, including a gap-0 hint** that the spec itself calls "a destination the seeker can compute or walk to directly, not a search" and which costs 60 ms. The consistency is the point: a reader never learns that some bags open themselves, so a hostile bag cannot hide inside that expectation. **Price before you spend.** The budget comes from the `hint` tag and the `h` tag before a single tree is built, and it is a hard cap, because a bag can carry a gap-30 hint precisely to burn a day of a reader's battery. A sweep that would exceed the cap is not offered as a button at all — it is reported as out of reach. ## 7. Not in scope - §7.4 position scanning. We have nowhere to stand, and §7.7 says it is not how things are found. - §4–§6 movement chains, §8.3 spawn, DECK-0001 hyperspace. That is a client *for* cyberspace; this is a Nostr client reading an event. - Publishing, hiding, or holding a region (§7.8). Read-only, like the rest of SNO. - §9.7's GPS mapping: 96-digit decimal arithmetic with a hand-rolled deterministic trig series, carried so every client agrees where a place on Earth is. Amethyst has no Earth to agree about. ## 8. Order 1. **Coordinates.** `CyberspaceCoordinate` in full, §9.8 and §7.7 vectors. No bignum and no new dependency: an 85-bit axis splits at 64 into a 21-bit high half and an unsigned low Long, which is enough for the bit layout, the plane, the sector shift of §10 and `alignedBase` — and `alignedBase` is exactly what a sweep enumerates, so this is the foundation the rest stands on. **Done**, 8 tests, every vector the spec publishes. It does *not* improve the shard card, which was the claim when this was written. The thought was to upgrade the `C` tag line from a plane to a place, but the only human-readable thing a decode adds is the sector triple, and at 55 bits an axis that is a fifty-character string for a 12 cm cube — worse than the abbreviated coordinate already there, which at least copies. Two shards in one sector would be worth saying; there are 21 reachable `3330`s and one author, so there is nothing to compare. Revisit when there is. 2. **Cantor + region key**, with the big integer and the height refusal. `amy cyberspace region`, diffed against `cyberspace-cli`. **Done** — see §9. 3. **Hints.** Parse, validate, price. `amy cyberspace hint`. The three golden vectors. **Done** — see §10. 4. **The bag.** AES-256-GCM, plaintext shapes, item verification. `amy cyberspace open`, round-tripped against the reference CLI's `encrypt`. **Done** — see §11. 5. **The sweep**, as a budgeted cold sequence. `amy cyberspace sweep`. **Done** — see §11. 6. **The card**, last, once every number it quotes is measured on a device. **Done** — see §12, which measures them on the device at the tap rather than baking in a constant. Steps 1 to 5 have no product risk and every one of them is diffable against a reference implementation. Step 6 is the only judgement call, and it is small. ## 9. Step 2 as built `CantorTree`, `RegionKey`, `UBigInt`, `amy cyberspace coord|region`. The conformance harness is now 12 of 12, the new section comparing **16 region keys and their coordinate decodes** against `cyberspace-cli` — four coordinates (§9.8's london, nyc and origin, plus §7.7's ideaspace point) at heights 0, 1, 4 and 8. Amethyst derives the keys the rest of the network derives. ### The big integer, and why there are two of them The plan said "an `expect`/`actual` over `java.math.BigInteger`". The first attempt went the other way — one portable implementation everywhere — on the argument that a region key is a **consensus value**, since §7.2 turns it into an AES key, so two implementations is two chances to disagree and an object that opens on a desktop and not on a phone. Measurement reversed that. Portable Kotlin came in **3 to 10 times slower** than `java.math.BigInteger` on the operands a Cantor tree reaches, because `BigInteger.multiplyToLen` is a HotSpot intrinsic and the JDK adds Toom-Cook above a few hundred limbs. §7's whole feasibility is a number, and that factor is the difference between a search a reader waits for and one they abandon. So: `UBigInt` is an `expect class`, aliased through a thin wrapper to `java.math.BigInteger` on `jvmAndroid`, and backed by `PortableUBigInt` on `nativeMain` — which covers Apple and Linux together, so there are two actuals and not three. A wrapper rather than a `typealias` for one reason: `toMinimalBytes`. The reference hashes `int_to_bytes_be_min`, and `BigInteger.toByteArray()` is two's complement, so it grows a `0x00` sign byte whenever the top bit is set — half of all numbers — and aliasing would have put that byte into a SHA-256 and produced a key nobody else derives. **What makes two implementations safe is that the disagreement is testable, and tested.** `PortableUBigIntDifferentialTest` runs every operation against `java.math.BigInteger` over random inputs at fifteen widths from 0 to 352,000 bits, straddling the Karatsuba threshold in both directions, and a ninth test asserts the two *actuals* agree with each other on the same inputs — including the bytes, which is the one place aliasing would have gone wrong silently. `CantorTreeBenchmark` then folds a whole subtree both ways and compares the roots, which is where an off-by-one in the fold's stack would live rather than in the arithmetic. ### What it costs, on the shipped path The §3 table was measured on `java.math.BigInteger`, which is what now ships on JVM and Android, so it stands. Apple and Linux pay the portable multiplier on top; nothing there opens a bag yet. ### Corrections to §3 worth carrying forward The earlier measurement said a sweep decomposes per axis, `3 · 2^(G/3)` tree builds and `2^G` combines. Building it confirmed the decomposition and also that **the combine dominates above about height 8** — a combine at height 12 is roughly ten times an axis root at the same height, because it multiplies two numbers the size of the root rather than folding up to one. A budget model that prices a sweep by its tree builds will under-quote badly; price it by `2^G` combines and add the trees. ## 10. Step 3 as built `CyberspaceHint`, `amy cyberspace hint`, and a harness section that runs §7.7's three golden vectors through the CLI and diffs them against the spec's own `hint-reference.py`. The harness is 13 of 13. The vectors pin more than a parser. Each states a point, a bag height and three hint heights, then gives the coordinate the aligned base must come out as and the sector tags the bag must carry — so building a hint from the point has to reproduce the published tag byte for byte, and `london_h5_box11`, `london_h5_x_exact` and `ideaspace_h8_y_open` all do. ### What the type says, and why A hint is the hider's **difficulty knob**, so the number that matters is `gapBits` — `(Hx - h) + (Hy - h) + (Hz - h)` — and it is reported as an exponent rather than a count because it runs to 255 when all three axes are left open and nothing holds `2^255`. §7.7's own table reads in those terms: 12 is seconds, 24 is hours, 30 or more is "days to never". `axisTrees` is reported apart from `candidates`, and the asymmetry is the point. A sweep needs one Cantor tree per distinct base *per axis* and then one combine per candidate, so a sector-only hint on a height-5 bag is a hundred million trees against `2^75` combines: both say hopeless, only one of them can say it with a number. A budget that prices a sweep by its trees under-quotes by the same margin §9 warned about. ### The rule that shapes the API §7.7: "A `hint` tag that breaks any rule above MUST be treated as absent... A bad hint never invalidates the bag, because hints are advisory metadata about where to look; whether a bag is valid is decided by §7.2 and §7.6 alone." So `read` returns null and never throws, for every one of: wrong arity, bad hex, uppercase hex, an unaligned base, a height outside `[0, 85]`, a non-canonical integer (`"011"` is not `"11"`), a height below the bag's `h`, and — the one the spec states as a publisher rule without saying what a reader does — more than one `hint` tag, which is read the same way because a bag whose author cannot be read literally is exactly the case §7.7's remedy is for. The canonical-integer rule is worth keeping for the same reason the aligned base is: both exist so that two hiders who hint the same box publish the same bytes, and a reader that accepts `"05"` alongside `"5"` lets one box have two spellings and breaks comparison by equality. ## 11. Steps 4 and 5 as built `CyberspaceBagEvent` and `RegionSweep` in quartz, `amy cyberspace open` and `amy cyberspace sweep` over them, and two more harness sections. The harness is **15 of 15**. ### What the two new sections actually prove Everything before this diffed a *number* against the reference — a key, a lookup id, a hint tag. These diff a **ciphertext**, which is the only test that catches a chain that agrees at every step and still cannot open a bag. `cyberspace-cli` derives the region key with `location_encryption`, seals the plaintext with `encrypt_with_location_key`, and writes the §8.6 tags with `make_encrypted_content_event`. `amy` is handed the event and a coordinate and has to reach the same 32 bytes: §2.2's interleave, §4.7's three Cantor roots, §7.2's two hashes, §7.6's `nonce || ciphertext || tag`. Section 8 then takes the coordinate away and makes it find the same bag from its hint box alone. The box in section 8 comes from the reference's own `coord_to_xyz` / `xyz_to_coord` rather than from ours, so a disagreement about alignment shows up as a bag that is not in the box we were handed — not as a test grading its own arithmetic. ### The two design decisions worth recording **`open` exits 0 on the wrong key.** §7.6: "A failed decryption therefore means only that the reader does not hold this region's key; it MUST NOT be treated as an error in the bag." So a wrong key is a verdict (`opened: false`), the way `sno parse` reports an invalid payload, and the harness asserts the exit code as well as the field. What *does* fail is a bag that cannot be attempted at all: an unknown `version` (§8.6 says ignore it) or no `aes-256-gcm` payload to try. **`sweep` refuses before it spends.** The gap is read from the `hint` and `h` tags and checked against `--max-gap` (default 20) before a single tree is built, and the refusal quotes the exponent and names the flag that would buy it. A harness case pins it: a gap-33 hint is declined rather than swept. This is the same shape the card needs, which is why it lives in the CLI first — a budget that can be tested in a shell script is a budget that can be trusted in a feed. ### A shell trap worth remembering `jq`'s `//` treats `false` as empty, so `.opened // "null"` turns a correct `false` into `"null"` and fails a passing test. Read booleans with a plain `jq -r .field`. ## 12. Step 6 as built `BagSweep` in `commons/cyberspace/` (headless: the quote, the budget and the cold flow) and `RenderCyberspaceBag` in `amethyst/ui/note/types/` (the card), wired into `NoteCompose` and `ThreadFeedView`, with kind 33330 routed through `EventCache`'s addressable path. Nine tests in `commons`. ### Pricing without a constant §3 of this plan ended with "Android will be slower — measure it before quoting a number in the UI". What shipped measures it **at the moment of the tap, on the device that is about to pay**, which is the same answer without a constant that goes stale on the next handset. The order is: 1. **Free, while the row composes.** `BagSweep.quote` reads two tags and does three subtractions. A box past `MAX_GAP_BITS` (20) or a bag deeper than `MAX_BAG_HEIGHT` (12, the ceiling ONOSENDAI puts on its own discovery scan) is reported as out of reach and never becomes a button. No Cantor tree is built for a hint the reader has already declined — a test pins that the flow emits nothing at all in that case. 2. **One candidate, timed.** On the tap, the box's own base region is derived and the elapsed time recorded. That candidate is never wasted work: a gap-0 hint names exactly it, so the measurement *is* the search for a destination hint. 3. **The estimate, then the rest.** `perCandidate × candidates` against a two-minute budget. It over-quotes — the first candidate is three axis roots plus a combine and every later one is a combine, so by about 4x at shallow heights and 2x at deep ones — and over-quoting is the safe direction for a number whose only job is to decide whether to spend somebody's battery. A slower phone therefore refuses boxes a faster one accepts. That asymmetry is correct: the cost is the reader's, so the reader's hardware should decide. ### What the card says, and what it never does Every sweep is a tap, **including a gap-0 hint**, which §7.7 itself calls "a destination the seeker can compute or walk to directly, not a search" and which costs about a frame. A reader who learned that some bags open themselves would have learned an expectation a hostile bag could hide inside, so the one candidate is offered exactly like the million. A test pins it. Scrolling the row away cancels: the flow is cold over a cold sequence and the card disposes its job, so a sweep never outlives the card that asked for it. Items render through the cards that already exist — a `3330` shard through `SnoObjectCard` (palette fetched by `WithSnoPalette`, as a standalone object would be), a `kind 1` as its text, anything else named and skipped, because §7.6 says a reader that does not understand an item's kind "skips it and renders the rest". The attribution is the non-obvious part and §7.6 fixes it: placement belongs to the bag's author, authorship only to a signed item's own pubkey. An unsigned item therefore carries a line saying its author is a claim, rather than borrowing either name. ### One correction carried back into quartz `SnoShardEvent`'s KDoc said Amethyst "implements none of it" and that a reader without the key sees base64 and nothing else. Both were true when it was written. The class now points at `RegionSweep` and says what actually decides whether a bag opens — whether its own hint prices the search into reach.