# Bitflash `.btf` Rendezvous Protocol This is the specification of how Bitflash nodes reach each other, and how miners reach pools, without revealing an IP address and without any central directory. It documents the protocol as implemented in `src/btfaddr.cpp`, `src/btfchan.cpp`, `src/btfrv.cpp`, `src/btftunnel.cpp` and `src/nostr.cpp`. The design is ported from the Itzal hidden service design. A `.btf` address names a public key, a node proves ownership of that key by signing a service descriptor, other nodes find the descriptor over Nostr, and the two sides then meet through an untrusted relay over an end to end encrypted tunnel. The relay carries ciphertext only and never learns the plaintext. ## 1. Overview A connection to a `.btf` service has three layers: 1. **Discovery (Nostr).** The service publishes a signed descriptor as a Nostr event. A caller fetches it by the service public key and verifies the signature. The descriptor says which rendezvous relay the service is waiting at, which encryption key to use, and optionally which Tor hidden service can be dialed directly. 2. **Rendezvous (TCP).** Caller and service both connect out to the same relay and are paired by public key. Neither needs an inbound port or a public IP. After pairing the relay is a blind byte pipe. 3. **Direct onion fallback bypass.** If the descriptor carries a valid signed `.onion:port` endpoint and the caller is running with Tor mode, the caller tries that endpoint before using rendezvous. This removes the rendezvous relay from the data path for peers that choose to run hidden services. 4. **Encrypted channel (X25519 + XChaCha20-Poly1305).** Over the paired pipe the caller and service run an ephemeral to static handshake and then exchange authenticated frames. The relay sees only ciphertext. The caller ends up holding an ordinary local socket that behaves like a direct TCP connection to the peer. The node treats it exactly like any other peer socket. ## 2. Identities and keys A node holds two independent keypairs. - **Signing / identity key**: a secp256k1 x-only key (BIP340 Schnorr). This is the `.btf` identity and also the node's Nostr identity. Persisted in `nostr.key`. - **Encryption key**: an X25519 (Curve25519) keypair. Persisted in `btf_enc.key`. Its public half is published in the descriptor as `enc` and is used for the tunnel key agreement. The identity key names the service and authenticates the descriptor. The encryption key secures the tunnel. They are separate so the long term identity never performs Diffie-Hellman and the encryption key can be rotated in a new signed descriptor. ## 3. The `.btf` address An address is the identity public key plus a short checksum, Base32 encoded, with the suffix `.btf`. ``` label = Base32( pubkey[32] || checksum[2] ) address = label + ".btf" ``` - `pubkey` is the 32 byte secp256k1 x-only public key. - `checksum` is the first two bytes of `SHA256(".btf-checksum-v1" || pubkey)`. - Base32 uses the lowercase alphabet `abcdefghijklmnopqrstuvwxyz234567`, no padding. The 34 byte payload encodes to 55 characters. - Parsing is case insensitive, trims surrounding whitespace, and strips a trailing dot. A wrong checksum is rejected. The address is self certifying: it *is* the public key, so no registry has to be trusted to map a name to a key. ## 4. Discovery over Nostr Nodes publish and read three kinds of parameterized replaceable Nostr events. Parameterized replaceable means the newest event for a given author and `d` tag supersedes the older one, so a descriptor is always the latest state. | Purpose | kind | `d` tag | |---|---|---| | Service descriptor | 38501 | `btf-descriptor-2` | | Rendezvous relay announcement | 38502 | `btf-relay-2` | | Pool announcement | 38503 | `btf-pool-2` | The Nostr event is signed with the node's identity key, so the event author equals the `.btf` public key. That binds the descriptor to the address at the Nostr layer, and the descriptor is *also* signed inside its own content (see below), so a relay operator cannot forge or swap a descriptor for an address it does not control. **Resolving an address.** To reach `X.btf`, a caller parses the address to the 32 byte key and sends a Nostr `REQ` filtered by `authors = [X]`, `kinds = [38501]`, `#d = ["btf-descriptor-2"]`, `limit = 1`. It verifies the returned descriptor and uses its `meeting_node` and `enc`. **Relay auto discovery.** A relay operator runs a rendezvous relay and publishes a kind 38502 event carrying `host:port`. Every node that reads it adds the relay to the set it can register at and dial through. No seed list edit or maintainer approval is needed. A small curated seed list is still shipped for bootstrap: ``` 92.246.128.180:8434 31.44.4.249:8434 90.156.222.107:8434 ``` The default rendezvous port is `8434`. ## 5. The service descriptor The descriptor is a JSON object, signed with the identity key over a domain separated digest of its own fields. Legacy descriptor: ```json { "v": 2, "pubkey": "", "enc": "", "meeting_node": "host:port", "created": , "sig": "" } ``` Onion-capable descriptor: ```json { "v": 3, "pubkey": "", "enc": "", "meeting_node": "host:port", "onion": "<56-char-v3-name>.onion:8433", "created": , "sig": "", "sig3": "" } ``` The legacy signed digest is: ``` digest = SHA256( ".btf-descriptor-v2" || pubkey[32] || enc (raw bytes of the string) || meeting_node (raw bytes of the string) || created (8 bytes, big endian) ) ``` `sig` is kept on v3 descriptors so old nodes can still resolve and dial through the rendezvous relay. The onion-capable digest is: ``` digest3 = SHA256( ".btf-descriptor-v3-onion" || pubkey[32] || enc (raw bytes of the string) || meeting_node (raw bytes of the string) || onion (raw bytes of the normalized string) || created (8 bytes, big endian) ) ``` `sig` and `sig3` are deterministic BIP340 Schnorr signatures (no auxiliary randomness) over their respective digests by the identity key. **Verification** (untrusted input, must never throw): parse the JSON, require all fields with the right types, confirm `pubkey` equals the address being resolved, recompute the digest, and verify the Schnorr signature. Any failure rejects the descriptor. If `onion` is present, readers accept it only when it is a normalized v3 onion endpoint and `sig3` verifies. A bad or tampered onion field is ignored; the v2 descriptor can still be used for rendezvous fallback if `sig` verifies. `created` lets a reader prefer the freshest descriptor when more than one is seen. A node without a direct onion endpoint only publishes a descriptor once it has actually registered at a `meeting_node`, so it never advertises a relay it cannot be reached at. A node with a direct onion endpoint may publish before rendezvous registration using `meeting_node = "rendezvous-pending"`; Tor peers can still dial the signed onion endpoint, and rendezvous becomes fallback once registration succeeds. ## 6. Rendezvous transport The relay is a small TCP server. Every connection opens with a fixed 33 byte header: ``` byte 0 role: 'S' (service) or 'C' (client) bytes 1..32 target public key (the .btf identity, 32 bytes) ``` **Service registration (`S`).** The service connects out to the relay and sends `'S' || own_pubkey`. The relay stores the connection in a table keyed by the public key and leaves it open, waiting. There is one slot per key: a new registration for the same key replaces and closes the old one. The service does not block waiting to be paired at registration time; it is considered registered the moment the relay reads the header, which is what lets it publish a descriptor pointing at this relay. **Client dial (`C`).** The caller connects out to the same relay and sends `'C' || target_pubkey`. The relay looks up the waiting service: - If present, it removes it from the table, writes a single `0x01` byte to both sockets, and then forwards raw bytes in both directions until either side closes. From this point the relay is a blind pipe. - If absent, it writes `0x00` to the caller and closes. Both sides connect *outbound* to the relay, so neither needs a public IP or an open inbound port. The relay never sees the identity of the caller (the caller sends no key of its own, only the target it wants). **Liveness.** A registration socket is idle by design and can outlive the network path that created it (a NAT drops the idle mapping, the relay restarts, a route changes) with no FIN and nothing readable. TCP keepalive was measured and does not reliably detect this. The service therefore imposes its own timeout on the wait for the pairing byte and re-registers on expiry. Expiring is not a failure; it costs one reconnect per interval and returns the loop to a known state. ## 7. The encrypted channel Once paired through the relay, the caller and service run an end to end handshake and then exchange authenticated frames. The primitive is libsodium `crypto_box_curve25519xchacha20poly1305` (X25519 key agreement, XChaCha20-Poly1305 AEAD), the same construction as Rust's `crypto_box` ChaChaBox. **Handshake (ephemeral to static).** 1. The caller generates a fresh ephemeral X25519 keypair, computes `shared = X25519(eph_sk, service_enc_pub)` reduced to a box key (`crypto_box_beforenm`), and sends the 32 byte ephemeral public key over the paired pipe. 2. The service reads the ephemeral public key and computes the same `shared = X25519(enc_sk, eph_pub)`. Because the caller uses a new ephemeral key per connection, each session has an independent key and forward secrecy against later compromise of the service encryption key. **Framing.** Every message is length prefixed: ``` frame = len[4] (big endian, length of the body that follows) body = nonce[24] || ciphertext || mac[16] ``` The nonce is 24 random bytes per frame (XChaCha20), the MAC is 16 bytes (Poly1305). A body shorter than `nonce + mac` or larger than 1 MiB is rejected. Decryption that fails authentication drops the frame and tears the tunnel down. The tunnel is transparent: the application is handed a local socket pair end and reads and writes plaintext. Two pump threads move data between that socket and the relay socket, encrypting outbound and decrypting inbound. ## 8. End to end connection flow To dial `X.btf`: 1. Parse `X.btf` to the 32 byte identity key. 2. Fetch and verify the descriptor over Nostr (kind 38501). Obtain `meeting_node` and `enc`. 3. Connect to `meeting_node`, send `'C' || X`, and wait for `0x01`. 4. Generate an ephemeral X25519 key, derive the shared key against `enc`, send the ephemeral public key. 5. Exchange XChaCha20-Poly1305 frames. Hand the application a local socket that speaks the ordinary peer protocol. A service, symmetrically: registers at a relay (`'S' || own_pubkey`), publishes a descriptor pointing at that relay, waits for `0x01`, reads the caller ephemeral public key, derives the shared key with its encryption secret, and serves the tunnel. ## 9. Security properties - **Address unforgeability.** The address is the identity key and the descriptor is Schnorr signed by it, and the Nostr event is signed by it. A relay or Nostr operator cannot publish a working descriptor for an address it does not own. - **Relay confidentiality.** The relay forwards ciphertext and never holds the channel key. It cannot read or modify traffic undetected; a tampered frame fails the Poly1305 tag and the tunnel closes. - **Caller anonymity to the service and relay.** The caller presents no identity key, only the target it wants to reach. It connects outbound, so its address is not published anywhere. - **Forward secrecy.** The caller's per connection ephemeral key means a later compromise of the service encryption key does not decrypt past sessions. - **IP privacy.** Neither side needs a public IP or an inbound port for rendezvous. With a signed `.onion` endpoint, the reachable side exposes only a Tor hidden service and the relay is not in the peer connection path. ## 10. Threat model and limitations - **The relay is trusted for availability, not for confidentiality.** It can refuse to pair, drop a connection, or go offline. This is why relays are plural, auto discovered, and re-registration is periodic. It cannot read traffic. - **Traffic analysis is not addressed.** A network observer, or the relay, can see connection timing and byte volumes. There is no padding or mixing. - **Single slot registration causes churn.** One waiting slot per key per relay means a race or a stale registration can briefly make a service unreachable at that relay. Multiple relays and the wait timeout bound the damage, but this is a known source of connection churn. - **Descriptor freshness is best effort.** `created` is a self reported timestamp; readers prefer the newest descriptor they have seen but there is no global clock. - **Discovery depends on public Nostr relays.** If the relays a node uses are all unreachable, discovery stalls until one is reachable again. Relay TLS is verified, which closes a man in the middle path on discovery, but availability still rests on the relay set. - **Direct onion needs Tor.** With `-managedtor`, Bitflash starts a Tor process, writes a local hidden-service config, and advertises the generated onion endpoint. With `-onionservice`, an operator can still run Tor manually and provide the endpoint. In both cases Tor owns the hidden-service private key and uptime. ## 11. Wire reference | Item | Value | |---|---| | `.btf` Base32 alphabet | `abcdefghijklmnopqrstuvwxyz234567`, no padding | | Address payload | `pubkey[32] || checksum[2]`, 55 Base32 chars | | Address checksum | `SHA256(".btf-checksum-v1" || pubkey)[0..2]` | | Descriptor domain sep | `.btf-descriptor-v2`; optional onion sep `.btf-descriptor-v3-onion` | | Descriptor version | `2`; `3` when a signed onion endpoint is present | | Descriptor signature | BIP340 Schnorr, deterministic (no aux rand), v3 keeps `sig` plus `sig3` | | Nostr descriptor event | kind `38501`, `d = btf-descriptor-2` | | Nostr relay event | kind `38502`, `d = btf-relay-2` | | Nostr pool event | kind `38503`, `d = btf-pool-2` | | Rendezvous port (default) | `8434` | | Rendezvous header | `role[1] ('S'/'C') || pubkey[32]`, 33 bytes | | Rendezvous pairing byte | `0x01` paired, `0x00` no service | | Channel primitive | `crypto_box_curve25519xchacha20poly1305` | | Nonce / MAC / key sizes | 24 / 16 / 32 bytes | | Frame | `len[4 big endian] || nonce[24] || ct || mac[16]` | | Max frame body | 1 MiB |