# tachyon-payments > Private-retrieval (PIR) services for the Tachyon payment protocol on Zcash, built by Zcash Labs. ## Architecture `tachyon-payments` implements the server-side Private Information Retrieval (PIR) layer of the Tachyon payment protocol on Zcash, as outlined in the Tachyon Book's *Payment Protocol* design. ### Why PIR is Needed Traditional shielded Zcash wallets discover incoming payments by downloading every encrypted note on chain and running **linear trial decryption** against their incoming viewing key (`ivk`). As throughput scales, linear scanning becomes too slow for bandwidth-limited mobile wallets and leaks sync metadata. Tachyon makes this even sharper by adopting **post-quantum ML-KEM** for note transmission: * In Orchard, diversified addresses share one elliptic-curve `ivk`, which is convenient for scanning but not quantum-private (a future quantum adversary who recovers `ivk` exposes every past and future note). * In Tachyon, each sender gets a freshly sampled payment address `addr = (pk, ek)` where `(ek, dk) ← ML-KEM.KeyGen()`. Without a single shared `ivk`, linear trial decryption would multiply by the number of per-sender `dk` keys in the wallet. **Tags + PIR solve both problems:** every encrypted memo is published on chain with a fresh, unlinkable **tag** predictable only to the sender and recipient. Instead of scanning the chain, the wallet queries a single-server PIR database directly by tag—retrieving its encrypted memo in constant online queries without revealing which tag it queried. Because single-server PIR scales as `O(√N)` per table, the protocol splits state into **four bounded databases**: ```mermaid flowchart TB subgraph Setup["1. Address Discovery (Off-chain PKI)"] R1["Recipient mints addr = (pk, ek)"] -->|"PoW Write API"| Reg["Registry PIR: H(addr) => pk || ek"] Reg -->|"Private PIR lookup"| S1["Sender fetches full (pk, ek)"] end subgraph Chain["2. On-Chain V7 Tachyon Transaction"] S1 -->|"Creates note + TPM1 memo"| Tx["Zakura Node (NuTachyon)"] Tx -->|"Proof stamps (tachygrams)"| TG["Tachygram PIR: tg => (height, ordinal)"] Tx -->|"TPM1 0x02 (first-contact)"| FC["First-contact PIR: tag => KEM.c || ct"] Tx -->|"TPM1 0x01 (follow-up)"| Memo["Memo PIR: tag => ct"] end subgraph Sync["3. Private Wallet Discovery & Spendability"] FC -->|"Private lookup"| W["Recipient Wallet"] Memo -->|"Private lookup"| W TG -->|"Inclusion (cm) & Exclusion (nf)"| W end ``` ### Two-Host Deployment Topology ```mermaid flowchart LR node["Zakura Node"] -->|"JSON-RPC (getblock 2)"| pub["tachyon-pir-publisher"] pub -->|"127.0.0.1:9400..9403"| edge["HTTPS TLS Edge"] edge -->|"HTTPS Pull (/provider/*)"| qs["tachyon-pir-query-server"] w_reg["Wallets (register)"] -->|"HTTPS POST /registry/v1"| edge w_q["Wallets (queries)"] <-->|"HTTPS POST //v1/query"| qs ``` 1. **`tachyon-pir-publisher`**: Follows a [Zakura](https://github.com/zakura-core/zakura) node over JSON-RPC (`getblockchaininfo`, `getblockcount`, `getblockhash`, `getblock 2`), ingests Tachyon proof stamps and `vMemoTachyon` envelopes, accepts PoW-gated address registrations, deterministically builds `tachyon-4k8` bucket-row PIR tables, and serves them as content-addressed publications. It never contacts query servers. 2. **HTTPS TLS Edge**: Terminates TLS in front of the publisher's private listeners, routing service discovery (`/.well-known/pir-service-discovery`), publication pull endpoints (`/provider//v1/*`), and the public registry write API (`/registry/v1/*`). 3. **`tachyon-pir-query-server`**: Pulls publications from the publisher over HTTPS, verifies digests, network identity, and scope bindings, holds resident PIR tables in memory, and answers encrypted row queries from wallets on a single public listener. ### The Four Products | Product | Mapping | Scope | Mount | | -------------------------------------------- | --------------------------------------------------- | ------------------------------------------------- | ------------------- | | **[Memo](/products/memo)** | `tag => ciphertext(128)` | One Tachyon epoch | `/memo/v1` | | **[First-contact](/products/first-contact)** | `tag => kem_ct(1088) \|\| ciphertext(128)` | Span of epochs (up to 3,072 entries or 64 epochs) | `/first-contact/v1` | | **[Tachygram](/products/tachygram)** | `tg(32) => blk_height(u32) \|\| stamp_ordinal(u32)` | One Tachyon epoch | `/tachygram/v1` | | **[Registry](/products/registry)** | `H(addr) => pk(32) \|\| ek(1184)` | Chunk of 3,072 registrations | `/registry/v1` | Every product also accepts the legacy alias `/v1/`. ### Dependency Boundaries & Determinism CI (`tools/ci/boundary.py`) enforces two strict architectural invariants across the Cargo workspace: * **Serving code never depends on chain or ingestion code.** `tachyon-pir-protocol`, `tachyon-pir-table`, and `tachyon-pir-query-server` cannot reach `tachyon-chain`, any product store/publisher, or `pir-node-rpc`. * **Product families never depend on each other.** The memo (including first-contact), tachygram, and registry crates are isolated from one another. Sealed tables are a pure function of the chain (or registration log) and the protocol constants: rebuilding from scratch or across restarts produces byte-identical tables and digests. ### Specification The normative contract for wire formats, table geometry, placement hashing, and operational rules is [`docs/spec/spec-tachyon-payment-pir.md`](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md). ## Local Regtest Quickstart This guide runs the full PIR stack — a local `NuTachyon` Zakura node, `tachyon-pir-publisher`, an HTTPS edge, `tachyon-pir-query-server`, and `tachyon-pir-cli` — on your machine. ### What This Starts ```mermaid flowchart TB subgraph THS["thus-spoke-zakura (ths start --native)"] zakurad["zakurad (NuTachyon Regtest RPC)"] lwd["lightwalletd (V7 parser)"] thssrv["ths-server (Dashboard & Faucet)"] zakurad --> lwd --> thssrv end subgraph PIR["tachyon-payments"] pub["tachyon-pir-publisher\n:9400 mgmt | :9401 memo+fc\n:9402 tachygram | :9403 registry"] edge["Local HTTPS TLS Edge\nhttps://127.0.0.1:9443"] qs["tachyon-pir-query-server\n:9500 mgmt | :9510 public PIR"] pub --> edge -->|"HTTPS pull"| qs end cli["tachyon-pir-cli (Probe Client)"] zakurad -->|"JSON-RPC (getblock 2)"| pub cli -->|"Anchor check (JSON-RPC)"| zakurad cli <-->|"Encrypted PIR queries"| qs cli -.->|"Registry PoW writes"| edge ``` ### 1. Start a local `NuTachyon` regtest node Use the `tachyon-payments` branch of [`zcashlabs/thus-spoke-zakura`](https://github.com/zcashlabs/thus-spoke-zakura/tree/tachyon-payments) (`ths`), which runs a disposable `NuTachyon`-enabled Zakura node, `lightwalletd`, and a wallet-backed faucet/dashboard natively: ```console git clone -b tachyon-payments https://github.com/zcashlabs/thus-spoke-zakura.git cd thus-spoke-zakura ths start --native ``` Once ready, print the instance's endpoints in another terminal: ```console ths endpoints --env ``` Note `THS_ZAKURA_RPC_URL` (for example `http://127.0.0.1:40445`) and fetch the regtest genesis hash: ```console ths rpc getblockhash 0 # e.g. 029f11d80ef9765602235e1bc9727e3eb6ba20839319f761fee920d63401e327 ``` Confirm `NuTachyon` (`fffffffc`) is active: ```console ths rpc getblockchaininfo ``` ### 2. Build the PIR binaries In `tachyon-payments`: ```console cargo build --profile release-fast -p tachyon-pir-publisher --features memo,first-contact,tachygram,registry cargo build --profile release-fast -p tachyon-pir-query-server --features memo,first-contact,tachygram,registry cargo build --profile release-fast -p tachyon-pir-cli ``` ### 3. Generate a local CA and leaf TLS certificate `tachyon-pir-query-server` requires an HTTPS publisher origin and rejects a CA certificate used directly as a leaf certificate (`CaUsedAsEndEntity`), so generate a local CA plus a leaf cert for `127.0.0.1`: ```console mkdir -p .local-pir/regtest openssl req -x509 -newkey rsa:2048 -nodes \ -keyout .local-pir/regtest/ca.key -out .local-pir/regtest/ca.pem \ -days 365 -subj "/CN=tachyon-local-ca" \ -addext "basicConstraints=critical,CA:TRUE" \ -addext "keyUsage=critical,keyCertSign,cRLSign" openssl req -newkey rsa:2048 -nodes \ -keyout .local-pir/regtest/server.key -out .local-pir/regtest/server.csr \ -subj "/CN=127.0.0.1" printf "basicConstraints=CA:FALSE\nsubjectAltName=IP:127.0.0.1,DNS:localhost\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n" \ > .local-pir/regtest/server.ext openssl x509 -req -in .local-pir/regtest/server.csr \ -CA .local-pir/regtest/ca.pem -CAkey .local-pir/regtest/ca.key -CAcreateserial \ -out .local-pir/regtest/server.pem -days 365 -extfile .local-pir/regtest/server.ext ``` ### 4. Configure and start the publisher Create `.local-pir/regtest/publisher.json` (replace `rpc_url` and absolute `state_dir` paths for your machine): ```json { "management_listen": "127.0.0.1:9400", "chain": { "rpc_url": "http://127.0.0.1:40445", "no_auth": true, "poll_ms": 500, "epoch_length": 64 }, "memo": { "enabled": true, "settings": { "listen": "127.0.0.1:9401", "state_dir": "/abs/path/to/tachyon-payments/.local-pir/regtest/pub-memo" } }, "first_contact": { "enabled": true, "settings": {} }, "tachygram": { "enabled": true, "settings": { "listen": "127.0.0.1:9402", "state_dir": "/abs/path/to/tachyon-payments/.local-pir/regtest/pub-tachygram" } }, "registry": { "enabled": true, "settings": { "listen": "127.0.0.1:9403", "state_dir": "/abs/path/to/tachyon-payments/.local-pir/regtest/pub-registry", "difficulty_bits": 8 } } } ``` Validate offline and start: ```console ./target/release-fast/tachyon-pir-publisher --config .local-pir/regtest/publisher.json --check ./target/release-fast/tachyon-pir-publisher --config .local-pir/regtest/publisher.json ``` Start your HTTPS reverse proxy on `https://127.0.0.1:9443` routing `/.well-known/`, `/provider/memo/`, `/provider/first-contact/`, `/provider/tachygram/`, `/provider/registry/`, and `/registry/` to ports `9400`–`9403` (see [TLS Edge & Routing](/operator/tls-edge)). ### 5. Configure and start the query server Create `.local-pir/regtest/query.json` (using the genesis hash from step 1 and `activation_height: 1`, `epoch_length: 64` for chain products; `registry` omits both): ```json { "management_listen": "127.0.0.1:9500", "public_listen": "127.0.0.1:9510", "memo": { "enabled": true, "settings": { "publisher": "https://127.0.0.1:9443", "publisher_ca": "/abs/path/to/tachyon-payments/.local-pir/regtest/ca.pem", "state_dir": "/abs/path/to/tachyon-payments/.local-pir/regtest/query-memo", "role": "combined", "publisher_network": "test", "publisher_genesis": "029f11d80ef9765602235e1bc9727e3eb6ba20839319f761fee920d63401e327", "activation_height": 1, "epoch_length": 64, "poll_ms": 500 } }, "first_contact": { "enabled": true, "settings": { "publisher": "https://127.0.0.1:9443", "publisher_ca": "/abs/path/to/tachyon-payments/.local-pir/regtest/ca.pem", "state_dir": "/abs/path/to/tachyon-payments/.local-pir/regtest/query-first-contact", "role": "combined", "publisher_network": "test", "publisher_genesis": "029f11d80ef9765602235e1bc9727e3eb6ba20839319f761fee920d63401e327", "activation_height": 1, "epoch_length": 64, "poll_ms": 500 } }, "tachygram": { "enabled": true, "settings": { "publisher": "https://127.0.0.1:9443", "publisher_ca": "/abs/path/to/tachyon-payments/.local-pir/regtest/ca.pem", "state_dir": "/abs/path/to/tachyon-payments/.local-pir/regtest/query-tachygram", "role": "combined", "publisher_network": "test", "publisher_genesis": "029f11d80ef9765602235e1bc9727e3eb6ba20839319f761fee920d63401e327", "activation_height": 1, "epoch_length": 64, "poll_ms": 500 } }, "registry": { "enabled": true, "settings": { "publisher": "https://127.0.0.1:9443", "publisher_ca": "/abs/path/to/tachyon-payments/.local-pir/regtest/ca.pem", "state_dir": "/abs/path/to/tachyon-payments/.local-pir/regtest/query-registry", "role": "combined", "publisher_network": "test", "publisher_genesis": "029f11d80ef9765602235e1bc9727e3eb6ba20839319f761fee920d63401e327", "poll_ms": 500 } } } ``` Validate offline and start: ```console ./target/release-fast/tachyon-pir-query-server --config .local-pir/regtest/query.json --check ./target/release-fast/tachyon-pir-query-server --config .local-pir/regtest/query.json ``` ### 6. Probe with `tachyon-pir-cli` Verify readiness and fetch anchor-checked maps for all four products: ```console curl -fsS http://127.0.0.1:9400/ready curl -fsS http://127.0.0.1:9500/ready ./target/release-fast/tachyon-pir-cli --origin http://127.0.0.1:9510 --product memo --node http://127.0.0.1:40445 map ./target/release-fast/tachyon-pir-cli --origin http://127.0.0.1:9510 --product first-contact --node http://127.0.0.1:40445 map ./target/release-fast/tachyon-pir-cli --origin http://127.0.0.1:9510 --product tachygram --node http://127.0.0.1:40445 map ./target/release-fast/tachyon-pir-cli --origin http://127.0.0.1:9510 --product registry map ``` See [Probe Client (CLI)](/operator/cli) for running encrypted `lookup` and `dummy` queries. ## Shared Table & Wire Protocol All four PIR products share one bucket-row table format, one PIR cryptographic profile, and one HTTP serving protocol. The normative contract is [`spec-tachyon-payment-pir.md`](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md). ### Bucket-row table Every table uses the `tachyon-4k8` geometry ([spec §6.1](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#61-geometry)): **4,096 rows × 8,192 bytes** (32 MiB raw). * Each row holds `floor(8192 / ENTRY_BYTES)` fixed-size slots. * Occupied entries come first, sorted ascending by `(key, ordinal)`, followed by zero-filled unused slots and tail padding. * Every key starts with a non-zero prefix, so an all-zero slot unambiguously marks the end of occupied entries. * Both server and client validate canonical row ordering and zero padding. #### Overflow & segments If a bucket cannot place all its entries into 4,096 rows within `MAX_SEEDS = 64` deterministic seed retries, the bucket splits into up to `MAX_SEGMENTS = 8` segments ([spec §6.4](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#64-seeds-overflow-and-segments)). A client looking up a key in a multi-segment bucket queries every segment of that bucket. ```mermaid flowchart LR key["Key (key16 or tg32)"] --> hash["SHA-256(domain || genesis || scope || seed || key)"] hash -->|"h[4..8] mod n_buckets"| bkt["Bucket b"] hash -->|"h[0..4] mod 4096"| row["Row r (8,192 bytes)"] bkt --> seg0["Segment 0 (4,096 rows)"] bkt -.->|"if seed 0..63 overflows"| seg1["Segment 1..7"] seg0 --> slots["Sorted entries + zero-padded tail"] ``` #### Open vs. sealed scopes * **Open scopes** (current epoch, open first-contact span, open registry chunk) are rebuilt on each publication as new data arrives. * **Sealed scopes** (epochs past `SEAL_DEPTH = 100` blocks, full registry chunks) are immutable and deterministic: rebuilding from the same chain or log produces identical bytes and SHA-256 digests ([spec §6.5](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#65-open-and-sealed-tables)). ### PIR profile All tables use `wallet-pir`'s native 8-bit PIR profile (`P8`, `D = 2048`, `Q = 2^64 - 2^32 + 1`) ([spec §6.6](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#66-pir-profile)). One query retrieves a full 8,192-byte row with an identical transcript whether the key is present or absent. ### HTTP routes Every enabled product is mounted on `tachyon-pir-query-server`'s `public_listen` at `//v1` (with legacy alias `/v1/`) ([spec §10](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#10-wallet-facing-protocol)): | Route | Purpose | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `GET map` | Returns the map head JSON (`network`, `genesis_hash`, anchor or `log_sequence`, `generation`, open scopes, and sealed chunk references) | | `GET map/chunks/` | Immutable sealed map chunk (up to 32 scopes per chunk) | | `GET public/` | Immutable PIR public setup bytes for a table | | `POST query` | Encrypted PIR row query (`magic(4) \|\| session_id(32) \|\| nonce(16) \|\| payload`; max 512 KiB). The 52-byte header is echoed in the response | ### Byte-order & trust rules * All protocol integers are **little-endian**. * Block hashes and txids are held in **protocol order** (reversed RPC hex) for all hash inputs, and printed in **display order** in JSON ([spec §3](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#3-chain-facts-this-spec-relies-on)). Tachygrams, anchors, tags, and digests are never reversed. * Wallets must verify the map's `genesis_hash` and `anchor_hash` against a trusted chain view before trusting query results ([spec §12.1](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#121-what-the-wallet-must-do)). ## Tachygram The **tachygram** database lets a wallet privately verify two things per epoch: **inclusion** of a note commitment (returning the block height and stamp ordinal needed to fetch its creation stamp) and **exclusion** of a nullifier (proving a note remains unspent over the covered heights). ```mermaid flowchart LR W["Recipient Wallet"] -->|"PIR lookup: cm (32B)"| Q["Query Server (/tachygram/v1)"] W -->|"PIR lookup: nf (32B)"| Q Q -->|"Hit: (blk_height, stamp_ordinal)"| Inc["Fetch creation proof stamp from chain"] Q -->|"Miss: canonical row without nf"| Exc["Note confirmed unspent over covered heights"] ``` | Property | Value | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Scope | One Tachyon epoch (`scope_id = epoch`) | | Source | `tachygrams[]` of every on-chain **proof** stamp; pointer stamps contribute nothing ([spec §8.2](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#82-scope-and-source)) | | Entry layout | `tg (32) \|\| blk_height (u32 LE) \|\| stamp_ordinal (u32 LE)` = **40 bytes** | | Slots per row | 204 (`floor(8192 / 40)`), target load 124 (\~507,904 entries per `tachyon-4k8` table) | | Protocol string | `tachyon-tachygram-pir-v1` | | Query magic | `TGQ1` | | Mount | `/tachygram/v1` (legacy alias `/v1/tachygram`) | | Default retention | 64 epochs | ### Placement & uniqueness Keys are full 32-byte tachygrams (not truncated): ```text h = SHA-256("tachyon-pir/tachygram/v1/place\0" || genesis_hash(32) || epoch(u64 LE) || seed(u32 LE) || tg(32)) bucket = u32_le(h[4..8]) mod n_buckets row = u32_le(h[0..4]) mod rows ``` Consensus requires tachygrams to be unique within a block and across the current and preceding epoch. Within a row, tachygrams are sorted in strictly ascending byte order. An all-zero or duplicate tachygram within an epoch is treated as an integrity fault ([spec §8.3](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#83-uniqueness)). ### Lookup semantics * **Hit**: returns `(blk_height, stamp_ordinal)`, where `stamp_ordinal` is the zero-based index of the proof stamp among proof stamps in `blk_height`. * **Miss**: returns a canonical row that does not contain `tg`, proving absence across the epoch heights covered by the map's verified anchor ([spec §8.4](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#84-lookup-semantics)). Tachygram lookups are private hints; spendability is ultimately enforced by the wallet's proof and consensus. ### Wire protocol & operations * Common table geometry, map format, and query framing: [Shared Table & Wire Protocol](/reference/shared) and [spec §8](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#8-product-tachygram). * Configuration and deployment: [Publisher Configuration](/operator/publisher) and [Query Server Configuration](/operator/query-server). ## Registry The **registry** is an off-chain address directory (`H(addr) => pk || ek`) that lets a sender expand a recipient's short address `(chunk_id, digest)` into a full Tachyon payment address privately over PIR. ```mermaid sequenceDiagram participant R as Recipient Wallet participant P as Registry Publisher participant Q as Query Server participant S as Sender Wallet R->>P: GET /registry/v1/challenge P-->>R: Stateless HMAC challenge + difficulty_bits R->>R: Solve PoW bound to H(pk || ek) R->>P: POST /registry/v1/register (challenge || nonce || pk || ek) P-->>R: 200 { chunk_id, digest, visible_after_sequence } P->>Q: Publish chunk PIR table R-->>S: Share short address (chunk_id, digest) S->>Q: Encrypted PIR query for row(digest[0..16]) Q-->>S: Encrypted 8 KiB row -> verify H(pk || ek) == digest ``` | Property | Value | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Scope | Append-only chunk of `3,072` registrations (`scope_id = chunk_id`, from `0`) | | Source | Public PoW-gated write API on the publisher ([spec §9.3](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#93-write-api)) | | Entry layout | `key16 (16) \|\| pk (32) \|\| ek (1184)` = **1,232 bytes** | | Slots per row | 6 (`floor(8192 / 1232)`), target load 1 (\~4,096 entries per `tachyon-4k8` table) | | Protocol string | `tachyon-registry-pir-v1` | | Query magic | `TRQ1` | | Mount | `/registry/v1` (legacy alias `/v1/registry`) | | Default retention | All chunks | ### Address & digest ```text addr = pk(32) || ek(1184) // 1,216 bytes (ML-KEM-768, provisional) digest = SHA-256("tachyon-pir/registry/v1/addr\0" || addr) key16 = digest[0..16] ``` After decoding a PIR row, the sender finds the entry matching `key16` and accepts it only if `SHA-256("tachyon-pir/registry/v1/addr\0" || pk || ek) == digest` ([spec §9.1](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#91-address-and-digest)). ### Placement `n_buckets` is always `1` for registry chunks: ```text h = SHA-256("tachyon-pir/registry/v1/place\0" || genesis_hash(32) || chunk_id(u64 LE) || seed(u32 LE) || key16(16)) row = u32_le(h[0..4]) mod rows ``` Once a chunk reaches `3,072` entries it seals immediately (there are no chain reorgs). Entries are append-only and never modified or deleted. ### Write API Served on the registry publisher listener (routed through your HTTPS edge at `/registry/v1`): 1. **`GET /registry/v1/challenge`** — returns a stateless HMAC-signed challenge: ```json { "challenge": "<64 hex>", "difficulty_bits": 20, "expires_unix": 1794670000 } ``` 2. **`POST /registry/v1/register`** — raw 1,256-byte body `challenge(32) || nonce(8 LE) || addr(1216)`: * Proof of work: `SHA-256("tachyon-pir/registry/v1/pow\0" || challenge || nonce || digest)` must have at least `difficulty_bits` leading zero bits. * Validates `pk` (canonical Pasta field element), `ek` (ML-KEM-768 encapsulation-key modulus check), and non-zero `key16`. * Returns HTTP `200` only after fsync: ```json { "chunk_id": 0, "digest": "<64 hex>", "created": true, "visible_after_sequence": 42 } ``` * Idempotent: re-registering an existing address returns its existing `chunk_id` with `"created": false`. ### Wire protocol & operations * Registry maps carry `log_sequence` instead of `activation_height`, `epoch_length`, `anchor_height`, and `anchor_hash`. * Common table geometry and query framing: [Shared Table & Wire Protocol](/reference/shared) and [spec §9](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#9-product-registry). * Configuration and rate-limit settings: [Publisher Configuration](/operator/publisher) and [Query Server Configuration](/operator/query-server). ## Memo The **memo** database lets a wallet privately fetch follow-up payment memos (`tag => ciphertext`) for an established sender–recipient pair, scoped per Tachyon epoch. ```mermaid sequenceDiagram participant S as Sender Wallet participant Z as Zakura Chain participant P as Publisher participant Q as Query Server participant R as Recipient Wallet Note over S,R: Shared secret & next per-note tag already established S->>Z: Broadcast V7 tx with TPM1 kind 0x01 (tag || ct) Z->>P: Block ingested (epoch E) P->>Q: Publish epoched memo PIR table R->>Q: Encrypted PIR query for row(tag[0..16]) Q-->>R: Encrypted 8 KiB row (server learns nothing) R->>R: Filter matching key16, AEAD-decrypt note opening ``` | Property | Value | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Scope | One Tachyon epoch (`scope_id = epoch`) | | Source | On-chain `vMemoTachyon` envelopes, kind `0x01` ([spec §5](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#5-on-chain-envelope-provisional)) | | Entry layout | `key16 (16) \|\| ciphertext (128)` = **144 bytes** | | Slots per row | 56 (`floor(8192 / 144)`), target load 34 (\~139,264 entries per `tachyon-4k8` table) | | Protocol string | `tachyon-memo-pir-v1` | | Query magic | `TMQ1` | | Mount | `/memo/v1` (legacy alias `/v1/memo`) | | Default retention | 64 epochs | ### On-chain envelope (`TPM1`) Each Tachyon bundle carries an opaque `vMemoTachyon` blob. The provisional payment-protocol envelope ([spec §5.1](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#51-envelope)) packs 1 to 16 entries: ```text envelope = "TPM1" || entry_count (u8, 1..=16) || entry* entry = kind (u8) || tag (32) || body ``` * `kind = 0x01` (follow-up memo): `ciphertext` (128 bytes) — indexed in **memo**. * `kind = 0x02` (first-contact): `kem_ciphertext (1088) || ciphertext (128)` — indexed in **[first-contact](/products/first-contact)**. * `kind = 0x03` (wallet state): `len (u16 LE) || ciphertext` (`len <= 1024`) — counted and ignored. Invalid or truncated envelopes are skipped whole and counted (`tachyon_memo_envelopes_invalid_total`); they never halt ingestion. ### Placement & duplicate tags Entries are keyed by `key16 = tag[0..16]` (all-zero `key16` is rejected): ```text h = SHA-256("tachyon-pir/memo/v1/place\0" || genesis_hash(32) || epoch(u64 LE) || seed(u32 LE) || key16(16)) bucket = u32_le(h[4..8]) mod n_buckets row = u32_le(h[0..4]) mod rows ``` Because tags are visible in the mempool, anyone can publish a colliding entry for the same tag. The publisher keeps **every** entry for a tag in deterministic ordinal order `(height, tx_index, entry_index)` ([spec §5.3](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#53-duplicate-tags)), and the wallet authenticates candidates by AEAD decryption. ### Wire protocol & operations * Common table geometry, map format, and query framing: [Shared Table & Wire Protocol](/reference/shared) and [spec §7.1](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#71-memo-epoched). * Configuration and deployment: [Publisher Configuration](/operator/publisher) and [Query Server Configuration](/operator/query-server). ## First-contact The **first-contact** database lets a wallet privately discover initial payments from new senders (`tag => KEM.c || ciphertext`), carrying the ML-KEM-768 encapsulation ciphertext alongside the encrypted note opening. ```mermaid sequenceDiagram participant S as Sender Wallet participant Z as Zakura Chain participant P as Publisher participant Q as Query Server participant R as Recipient Wallet S->>S: (KEM.c, ss) <- ML-KEM.Encaps(ek) S->>Z: Broadcast V7 tx with TPM1 kind 0x02 (tag_fc || KEM.c || ct) Z->>P: Block ingested into open span P->>Q: Publish first-contact PIR table R->>Q: Encrypted PIR query for row(tag_fc[0..16]) Q-->>R: Encrypted 8 KiB row R->>R: ss <- ML-KEM.Decaps(dk, KEM.c), decrypt note & derive follow-up tags ``` | Property | Value | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Scope | Contiguous span of epochs (`scope_id = first_epoch`), closing at 3,072 entries or 64 epochs | | Source | On-chain `vMemoTachyon` envelopes, kind `0x02` ([spec §5](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#5-on-chain-envelope-provisional)) | | Entry layout | `key16 (16) \|\| kem_ct (1088) \|\| ciphertext (128)` = **1,232 bytes** | | Slots per row | 6 (`floor(8192 / 1232)`), target load 1 (\~4,096 entries per `tachyon-4k8` table) | | Protocol string | `tachyon-first-contact-pir-v1` | | Query magic | `TFQ1` | | Mount | `/first-contact/v1` (legacy alias `/v1/first-contact`) | | Default retention | All spans | ### Span boundaries First-contact traffic is much lower volume than follow-up memos, so scopes group multiple epochs into spans ([spec §7.2](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#72-first-contact)): * Span boundaries are decided deterministically at epoch boundaries and depend only on the chain. * The open span closes at the first epoch boundary where it holds at least `FC_SPAN_TARGET = 3,072` entries or has spanned `FC_SPAN_MAX_EPOCHS = 64` epochs. * A span seals once its last epoch reaches `SEAL_DEPTH = 100` blocks past the end of that epoch. ### Placement & duplicate tags Entries are keyed by `key16 = tag[0..16]`: ```text h = SHA-256("tachyon-pir/first-contact/v1/place\0" || genesis_hash(32) || scope_id(u64 LE) || seed(u32 LE) || key16(16)) bucket = u32_le(h[4..8]) mod n_buckets row = u32_le(h[0..4]) mod rows ``` Every entry for a tag is retained in ordinal order `(height, tx_index, entry_index)` so front-runners cannot censor a handshake ([spec §5.3](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#53-duplicate-tags)). ### Wire protocol & operations * First-contact runs inside the `memo` publisher and shares its listener and `state_dir` (enable both `memo` and `first_contact` in [Publisher Configuration](/operator/publisher)). * Common table geometry, map format, and query framing: [Shared Table & Wire Protocol](/reference/shared) and [spec §7.2](https://github.com/zcashlabs/tachyon-payments/blob/master/docs/spec/spec-tachyon-payment-pir.md#72-first-contact). ## Building & Testing ### Prerequisites * **Rust**: toolchain pinned in `rust-toolchain.toml` (`1.97.1`, with `rustfmt` and `clippy`) * **`git`**, **`make`**, and **Python 3.11+** (for CI boundary and test-budget scripts) * Network access to fetch the pinned `valargroup/wallet-pir` and `valargroup/ipir-sp` git dependencies (use `OFFLINE=1` once fetched) Verify your environment: ```console make doctor ``` ### Building the binaries Both host binaries select which products to compile via Cargo features. The default build enables **no** products, and a configuration section for a product not compiled in is rejected at startup. | Feature | Config section | Notes | | --------------- | --------------- | --------------------------------------------------- | | `memo` | `memo` | Epoched `tag => memo` database | | `first-contact` | `first_contact` | Implies `memo`; shares its listener and `state_dir` | | `tachygram` | `tachygram` | Epoched tachygram inclusion/exclusion database | | `registry` | `registry` | Off-chain address registry + PoW write API | #### Deploy binaries (`release`, fat LTO) ```console cargo build --locked --release -p tachyon-pir-publisher --features memo,first-contact,tachygram,registry cargo build --locked --release -p tachyon-pir-query-server --features memo,first-contact,tachygram,registry cargo build --locked --release -p tachyon-pir-cli ``` #### Fast local iteration (`release-fast`, no LTO) ```console cargo build --locked --profile release-fast -p tachyon-pir-publisher --features memo,first-contact,tachygram,registry cargo build --locked --profile release-fast -p tachyon-pir-query-server --features memo,first-contact,tachygram,registry cargo build --locked --profile release-fast -p tachyon-pir-cli ``` ### Verification gates | Command | What it runs | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `make check-package PACKAGE= [TEST=]` | `fmt`, dependency boundary check, `clippy -D warnings`, and `release-fast` tests for one crate | | `make check-fast BASE=` | Same gates for crates changed since `BASE` and their dependents | | `make check-correctness` | Every workspace test and doctest under `release-fast`, timed per test (30 s) and total (300 s) | | `make check-full` | CI tool tests, `fmt`, boundary check, workspace `clippy -D warnings`, and workspace tests | | `make fmt` | `cargo fmt --all` | Fast tests run completely offline against synthetic chains and the node double in `tools/fixtures`. Slow full-geometry and live-testnet tests live behind `--features qualification-tests`. ## Probe Client (CLI) `tachyon-pir-cli` is a diagnostic probe client for inspecting maps and executing real encrypted PIR lookups against a query host. It prints one JSON document to stdout and exits `0` on success or `1` on error (also formatted as JSON). ### Global options ```console tachyon-pir-cli --origin --product [OPTIONS] ``` | Flag | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `--origin ` | Query host origin, e.g. `https://pir.example` or `http://127.0.0.1:9510` | | `--product ` | One of `memo`, `first-contact`, `tachygram`, `registry` | | `--ca ` | Custom PEM CA certificate to trust instead of system roots | | `--node ` | Zakura JSON-RPC URL; verifies the map's `genesis_hash` and `anchor_hash` against the node before querying (chain products only) | | `--legacy-mount` | Use `/v1/` instead of `//v1` | ### Commands #### `map` Fetch, validate, and summarize the product's map and scopes: ```console tachyon-pir-cli \ --origin http://127.0.0.1:9510 \ --product tachygram \ --node http://127.0.0.1:40445 \ map ``` #### `lookup` Execute an encrypted PIR lookup for a key in a specific scope (`--scope ` or `--scope-id `): ```console # Memo (32-byte tag or 16-byte key16 hex) tachyon-pir-cli --origin http://127.0.0.1:9510 --product memo --node http://127.0.0.1:40445 \ lookup --scope 1 --key <64-hex-tag> # First-contact (span index 0) tachyon-pir-cli --origin http://127.0.0.1:9510 --product first-contact --node http://127.0.0.1:40445 \ lookup --scope 0 --key <64-hex-tag> # Tachygram (32-byte tachygram hex) tachyon-pir-cli --origin http://127.0.0.1:9510 --product tachygram --node http://127.0.0.1:40445 \ lookup --scope 1 --key <64-hex-tachygram> # Registry (32-byte address digest hex, chunk 0) tachyon-pir-cli --origin http://127.0.0.1:9510 --product registry \ lookup --scope 0 --key <64-hex-digest> ``` A successful lookup returns `"result": "found"` with the decoded `entries` (plus `answer.queries` metadata), or `"result": "absent"` when the canonical row proves the key is not present in the scope. #### `dummy` Send a dummy PIR query to a scope, wire-indistinguishable from a real lookup: ```console tachyon-pir-cli --origin http://127.0.0.1:9510 --product memo dummy --scope 0 ``` ## Observability & Alerts Both hosts expose operational endpoints on their loopback `management_listen` addresses and never log or label metrics with client-supplied bytes. ### Endpoints | Host | Listener | Endpoints | | -------------------------- | --------------------- | --------------------------------------------------------------------- | | `tachyon-pir-publisher` | `management_listen` | `GET /health`, `GET /ready`, `GET /.well-known/pir-service-discovery` | | `tachyon-pir-publisher` | each product `listen` | `GET /metrics` (Prometheus text format) | | `tachyon-pir-query-server` | `management_listen` | `GET /health`, `GET /ready`, `GET /metrics` | `/ready` returns HTTP `200` with per-product `"phase": "running", "ready": true` once initial sync/publication has committed, and `503` while starting or degraded. ### Publisher metrics * **Memo (`tachyon_memo_*`)**: `ingested_height`, `anchor_height`, `entries_total`, `open_scope_entries`, `segments_overflow_total`, `publication_seconds`, `sessions_revoked_total`, `envelopes_invalid_total`, `state_entries_total`. * **First-contact (`tachyon_first_contact_*`)**: `open_span_entries`, `open_span_epochs`, `segments_overflow_total`, `publication_seconds`, `sessions_revoked_total`. * **Tachygram (`tachyon_tachygram_*`)**: `ingested_height`, `anchor_height`, `entries_total`, `open_scope_entries`, `segments_overflow_total`, `publication_seconds`, `sessions_revoked_total`. * **Registry (`tachyon_registry_*`)**: `log_sequence`, `open_chunk_entries`, `registrations_total`, `registrations_duplicate_total`, `registrations_rejected_total`, `rate_limited_total`, `publication_seconds`, `sessions_revoked_total`. ### Key alerts * **Ingestion stalled**: `ingested_height` falling behind the Zakura node tip, or ingestion halted by a duplicate/all-zero tachygram integrity fault. * **Segment overflow**: any publication failing because a bucket exceeded `MAX_SEGMENTS` (`8`). The previous publication continues serving while operators investigate. * **Query host staleness**: a query server failing to confirm publisher authority within `max_unconfirmed_seconds` (default `600` s) transitions out of ready. * **Registry write abuse**: spikes in `tachyon_registry_rate_limited_total` or `tachyon_registry_registrations_rejected_total`. ## Publisher Configuration `tachyon-pir-publisher` is a single process that follows one Zakura node, builds deterministic PIR tables for every enabled product, and serves content-addressed publications on per-product private listeners. ### Command line ```console tachyon-pir-publisher --config /etc/tachyon-pir/publisher.json --check tachyon-pir-publisher --config /etc/tachyon-pir/publisher.json tachyon-pir-publisher --contract-info ``` * `--config `: path to the JSON configuration file. Unknown fields are refused. * `--check`: validates the configuration offline (opens no sockets, stores, or RPC connections) and exits `0` on success. * `--contract-info`: prints the service-discovery contract and compiled products as JSON. ### Complete example ```json { "management_listen": "127.0.0.1:9400", "chain": { "rpc_url": "http://127.0.0.1:18232", "rpc_cookie": "/var/lib/zakura/.cookie", "poll_ms": 1000, "epoch_length": 4096 }, "memo": { "enabled": true, "settings": { "listen": "127.0.0.1:9401", "state_dir": "/var/lib/tachyon-pir/memo" } }, "first_contact": { "enabled": true, "settings": {} }, "tachygram": { "enabled": true, "settings": { "listen": "127.0.0.1:9402", "state_dir": "/var/lib/tachyon-pir/tachygram" } }, "registry": { "enabled": true, "settings": { "listen": "127.0.0.1:9403", "state_dir": "/var/lib/tachyon-pir/registry", "difficulty_bits": 20, "per_client_concurrent": 2, "per_client_per_minute": 6, "global_per_minute": 600, "upload_ms": 15000, "publish_ms": 1000 } } } ``` ### Field reference #### Top-level | Field | Required | Description | | ------------------------------------------------ | --------------------------- | ------------------------------------------------------------------------------------------ | | `management_listen` | Yes | Loopback `host:port` serving `/health`, `/ready`, and `/.well-known/pir-service-discovery` | | `chain` | When any product is enabled | Node RPC settings and `epoch_length` | | `memo`, `first_contact`, `tachygram`, `registry` | No | Each is `{ "enabled": bool, "settings": { ... } }` | #### `chain` | Field | Default | Description | | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------- | | `rpc_url` | — | `http://` or `https://` Zakura JSON-RPC endpoint without embedded credentials | | `rpc_cookie` | — | Absolute path to Zakura cookie file (mutually exclusive with `no_auth: true`) | | `no_auth` | `false` | Explicitly allow unauthenticated RPC (mutually exclusive with `rpc_cookie`) | | `poll_ms` | `1000` | Chain tip poll interval in milliseconds (nonzero) | | `epoch_length` | — | Blocks per Tachyon epoch (`>= 2`; `4096` on alpha testnet). Bound into every chain journal and distribution scope | The publisher uses only `getblockchaininfo`, `getblockcount`, `getblockhash`, and `getblock 2`. It refuses to start if `NuTachyon` is absent from `getblockchaininfo.upgrades`. #### Product sections * **`memo.settings`**: `listen` (private `host:port` serving `/provider/memo/v1/`, `/provider/first-contact/v1/`, and `/metrics`) and absolute `state_dir`. * **`first_contact.settings`**: must be `{}`. Requires `memo` to be enabled; shares its listener and `state_dir`. * **`tachygram.settings`**: `listen` (private `host:port` serving `/provider/tachygram/v1/` and `/metrics`) and absolute `state_dir`. * **`registry.settings`**: `listen` (serves `/provider/registry/v1/`, `/registry/v1/`, `/v1/registry/`, and `/metrics`), absolute `state_dir`, plus optional abuse/cadence limits: `difficulty_bits` (default `20`), `per_client_concurrent` (`2`), `per_client_per_minute` (`6`), `global_per_minute` (`600`), `upload_ms` (`15000`), `publish_ms` (`1000`). All product `listen` addresses must be private/loopback with distinct fixed ports, and all `state_dir` paths must be absolute and disjoint. ## Query Server Configuration `tachyon-pir-query-server` pulls published PIR tables from the publisher over HTTPS, verifies digests and scope bindings, holds resident tables in memory, and answers encrypted wallet queries on a single `public_listen` address. ### Command line ```console tachyon-pir-query-server --config /etc/tachyon-pir/query.json --check tachyon-pir-query-server --config /etc/tachyon-pir/query.json ``` ### Complete example ```json { "management_listen": "127.0.0.1:9500", "public_listen": "127.0.0.1:9510", "memo": { "enabled": true, "settings": { "publisher": "https://publisher.example", "publisher_ca": "/etc/tachyon-pir/publisher-ca.pem", "state_dir": "/var/lib/tachyon-pir-query/memo", "role": "combined", "publisher_network": "test", "publisher_genesis": "029f11d80ef9765602235e1bc9727e3eb6ba20839319f761fee920d63401e327", "activation_height": 8, "epoch_length": 4096, "retain_scopes": 64, "max_unconfirmed_seconds": 600, "poll_ms": 1000, "admission": { "executing": 2, "waiting": 8, "wait_ms": 2000, "per_client": 2, "upload_ms": 15000 } } }, "first_contact": { "enabled": true, "settings": { "publisher": "https://publisher.example", "state_dir": "/var/lib/tachyon-pir-query/first-contact", "role": "combined", "publisher_network": "test", "publisher_genesis": "029f11d80ef9765602235e1bc9727e3eb6ba20839319f761fee920d63401e327", "activation_height": 8, "epoch_length": 4096 } }, "tachygram": { "enabled": true, "settings": { "publisher": "https://publisher.example", "state_dir": "/var/lib/tachyon-pir-query/tachygram", "role": "combined", "publisher_network": "test", "publisher_genesis": "029f11d80ef9765602235e1bc9727e3eb6ba20839319f761fee920d63401e327", "activation_height": 8, "epoch_length": 4096 } }, "registry": { "enabled": true, "settings": { "publisher": "https://publisher.example", "state_dir": "/var/lib/tachyon-pir-query/registry", "role": "combined", "publisher_network": "test", "publisher_genesis": "029f11d80ef9765602235e1bc9727e3eb6ba20839319f761fee920d63401e327" } } } ``` ### Field reference #### Top-level | Field | Required | Description | | ------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------- | | `management_listen` | Yes | Loopback `host:port` serving `/health`, `/ready`, and `/metrics` | | `public_listen` | Yes | Wallet-facing listener (put behind your public HTTPS edge) mounting `//v1` and `/v1/` | | `memo`, `first_contact`, `tachygram`, `registry` | No | Each is `{ "enabled": bool, "settings": { ... } }` | #### Product `settings` | Field | Required | Default | Description | | ------------------------- | ------------------- | --------------- | -------------------------------------------------------------------------------- | | `publisher` | Yes | — | Publisher HTTPS origin (`https://host[:port]`) | | `publisher_ca` | No | system roots | PEM CA certificate for verifying the publisher's TLS leaf certificate | | `state_dir` | Yes | — | Absolute, disjoint directory for local object cache, floor, and lock | | `role` | Yes | — | Must be `"combined"` in v1 | | `publisher_network` | Yes | — | Expected `network` string from the node (e.g. `"test"`, `"main"`) | | `publisher_genesis` | Yes | — | Expected genesis block hash in display order (64 hex chars) | | `activation_height` | Chain products only | — | `NuTachyon` activation height (omitted for `registry`) | | `epoch_length` | Chain products only | — | Blocks per epoch matching publisher config (omitted for `registry`) | | `retain_scopes` | No | product default | Number of newest scopes to keep resident (`64` for `memo`/`tachygram`) | | `max_unconfirmed_seconds` | No | `600` | Maximum time to keep serving after the last successful publisher authority check | | `poll_ms` | No | `1000` | Interval between successful sync passes in milliseconds | | `admission` | No | see below | Per-product concurrency and upload limits | #### `admission` | Field | Default | Description | | ------------ | ------- | ------------------------------------------------------------------- | | `executing` | `2` | Maximum queries evaluated concurrently | | `waiting` | `8` | Maximum queries queued waiting for an evaluation slot | | `wait_ms` | `2000` | Maximum time a query waits for a slot before `503` | | `per_client` | `2` | Maximum concurrent in-flight queries per client | | `upload_ms` | `15000` | Maximum upload duration before `408` (body cap is fixed at 512 KiB) | ### Memory sizing Each resident `tachyon-4k8` table costs roughly **160 MiB** of RAM (planning bound). Retaining 64 epochs at one table per epoch is \~10 GiB per chain product per query host; tune `retain_scopes` according to available memory and history window. ## TLS Edge & Routing Both `tachyon-pir-publisher` and `tachyon-pir-query-server` bind plaintext HTTP on loopback or private interfaces and expect a TLS-terminating reverse proxy (Caddy, Nginx, Envoy, or a cloud load balancer) in front of them. ### Publisher edge routes `tachyon-pir-query-server` discovers each product via `/.well-known/pir-service-discovery` and pulls objects over HTTPS from a single publisher origin. Route prefixes to the publisher's listeners as follows: | Path prefix | Upstream listener | Purpose | | ------------------------------------ | --------------------------------------------------- | ------------------------------------------------------------ | | `/.well-known/pir-service-discovery` | `management_listen` (e.g. `127.0.0.1:9400`) | Service discovery | | `/provider/memo/` | `memo.settings.listen` (e.g. `127.0.0.1:9401`) | Memo publications | | `/provider/first-contact/` | `memo.settings.listen` (e.g. `127.0.0.1:9401`) | First-contact publications | | `/provider/tachygram/` | `tachygram.settings.listen` (e.g. `127.0.0.1:9402`) | Tachygram publications | | `/provider/registry/` | `registry.settings.listen` (e.g. `127.0.0.1:9403`) | Registry publications | | `/registry/v1/` and `/v1/registry/` | `registry.settings.listen` (e.g. `127.0.0.1:9403`) | Public registry write API (`GET challenge`, `POST register`) | Keep `/health`, `/ready`, and `/metrics` private — do not expose them on the public edge. For the registry write API, forward the client's IP in `X-Forwarded-For` so per-client rate limits apply per caller rather than globally to the proxy. #### Example Caddyfile (publisher edge) ```caddyfile publisher.example { handle /.well-known/pir-service-discovery { reverse_proxy 127.0.0.1:9400 } handle /provider/memo/* { reverse_proxy 127.0.0.1:9401 } handle /provider/first-contact/* { reverse_proxy 127.0.0.1:9401 } handle /provider/tachygram/* { reverse_proxy 127.0.0.1:9402 } handle /provider/registry/* { reverse_proxy 127.0.0.1:9403 } handle /registry/v1/* { reverse_proxy 127.0.0.1:9403 } handle /v1/registry/* { reverse_proxy 127.0.0.1:9403 } } ``` ### Query-server edge Terminate public HTTPS in front of `tachyon-pir-query-server`'s `public_listen` (e.g. `127.0.0.1:9510`). All enabled products are mounted on that single listener at: * `/memo/v1/*` (alias `/v1/memo/*`) * `/first-contact/v1/*` (alias `/v1/first-contact/*`) * `/tachygram/v1/*` (alias `/v1/tachygram/*`) * `/registry/v1/*` (alias `/v1/registry/*`) Ensure the proxy allows request bodies up to at least **512 KiB** (the PIR query body limit). ### Certificate note for private CAs `tachyon-pir-query-server` uses `rustls`, which rejects a CA certificate (`CA:TRUE`) presented directly as the server leaf certificate (`CaUsedAsEndEntity`). When using a private CA (`publisher_ca`), always sign a separate leaf certificate (`basicConstraints=CA:FALSE`, `extendedKeyUsage=serverAuth`, matching SAN) with your CA.