floonet-rs/README.md

floonet-rs

A hardened Floonet relay for the Grin community Nostr network, forked from nostr-rs-relay.

Floonet is a network of Nostr relays for the Grin community: anyone can run one, and anyone can run a name authority on it so people can claim (and optionally pay for) a name@domain identity. floonet-rs keeps the upstream relay core intact and adds four configurable, modular features:

• An event kind whitelist (the keystone): default-deny admission. The relay accepts ONLY the kinds it is configured to allow and rejects everything else. The shipped set is 0, 3, 5, 13, 1059, 10002, 10050, 27235.
• Authentication: NIP-42, with optional require-auth-to-write and an author whitelist.
• A built-in name authority: name@domain NIP-05 identities with NIP-98 authenticated self-service registration, served in-process on the relay's own subdomain — no separate hostname to run. Optionally paid in GRIN through GoblinPay.
• A co-located mixnet exit (config toggle): wallets can reach this relay over the mixnet, with no public DNS on the payment path.

The public relay metadata stays neutral on purpose: the NIP-11 document and landing page never mention payments. The relay only ever sees opaque gift-wrapped ciphertext, so payment wording would be both inaccurate and an operational liability.

Deploy

Pick your comfort level. All three paths end with the same relay.

1. Docker Compose (recommended)

Brings up the relay plus a Caddy TLS proxy in one command:

cp config.toml my-config.toml
# edit my-config.toml: info.relay_url, and [network] address = "0.0.0.0"
echo 'FLOONET_DOMAIN=relay.example.com' > .env
docker compose up -d

The relay container is non-root with a read-only root filesystem; Caddy obtains certificates automatically and forwards the real client IP.

2. Binary + installer + systemd

From an unpacked release archive (or a source checkout after building), the installer drops the binary, a default config, and a hardened systemd unit; no toolchain needed at install time:

sudo sh deploy/install.sh
sudo $EDITOR /etc/floonet-rs/config.toml   # set info.relay_url
sudo systemctl start floonet-rs

Put a TLS proxy in front (see deploy/Caddyfile). The unit runs as a dynamic unprivileged user with a read-only system view (ProtectSystem=strict, NoNewPrivileges, MemoryDenyWriteExecute, syscall filtering); only /var/lib/floonet-rs is writable.

3. Source build

cargo build --release
./target/release/floonet-rs --config config.toml --db .

Requires a protobuf compiler (protoc) for the gRPC extension point.

The whitelist (keystone)

[limits]
event_kind_allowlist = [0, 3, 5, 13, 1059, 10002, 10050, 27235]

Fail-closed semantics, enforced in the write path before anything is queued for persistence:

• The listed kinds are accepted; everything else is rejected with an OK false / blocked: message.
• Removing the line keeps the built-in Floonet set. There is no allow-all: an empty list denies everything.
• To add a kind, add it to the list and restart. Never narrow the list below what your users' wallets already depend on.

Authentication (NIP-42)

[authorization]
nip42_auth = true             # send AUTH challenges
require_auth_to_write = true  # refuse writes until the client AUTHs
nip42_dms = true              # gift wraps only to their recipients
#pubkey_whitelist = ["<hex>"] # restrict authors entirely

Unauthenticated writes are refused with an auth-required: prefixed OK message, so compliant clients authenticate and resend.

Name authority

Enable the built-in authority to serve name@yourdomain identities:

[name_authority]
enabled = true
domain = "example.com"
base_url = "https://example.com"   # must match what clients reach

Endpoints, all on the relay's own listener:

Endpoint	Purpose
GET /.well-known/nostr.json?name=<name>	NIP-05 resolution
POST /api/v1/register	claim a name (NIP-98 auth)
DELETE /api/v1/register/{name}	release a name (NIP-98 auth)
GET /api/v1/name/{name}	availability
GET /api/v1/profile/{name}	name to pubkey
GET /api/v1/by-pubkey/{pubkey}	reverse lookup
GET /api/v1/health	liveness

Rules carried over from goblin-nip05d: lowercase [a-z0-9._-] names (3 to 20 characters, alphanumeric at both ends), a built-in reserved list plus your own domain labels with look-alike folding (g0blin cannot impersonate goblin), one active name per key enforced by the database, NIP-98 verification with a bounded replay window, per-IP rate limits, and a release-armed rename cooldown. Claims live in the relay's own SQLite database (name_claims table).

Charge GRIN for your relay

Paid use is one switch plus a price. Point the relay at your GoblinPay server and pick a mode:

[goblinpay]
pay_mode = "name"                  # or "write", or "off"
url = "https://pay.example.com"
api_token = "<GP_API_TOKEN>"
name_price_grin = 1.0

Or keep secrets out of the file entirely and use the environment: FLOONET_PAY_MODE, FLOONET_GOBLINPAY_URL, FLOONET_GOBLINPAY_TOKEN, FLOONET_NAME_PRICE_GRIN.

• pay_mode = "name": claiming a name answers 402 {"error":"payment_required","pay_url":...} with a hosted GoblinPay page (GoblinPay, manual slatepack, or a grin1 address if the operator enabled that method). Once the payment confirms on chain, the same register call succeeds. Clients have everything they need to send the user straight to the pay page and retry.
• pay_mode = "write": publishing requires a paid admission; the relay reuses its pay-to-relay account model with GoblinPay as the payment processor.
• A GoblinPay webhook may POST {"invoice_id": ...} to /goblinpay to speed things up; the relay always re-verifies the invoice with the GoblinPay server before admitting anything, so a forged webhook cannot fake a payment.

Payments admit the pubkey, not the request: after one confirmed payment a key can claim, release, and re-claim its single name without paying again (the rename cooldown still applies).

Prices are plain config values; edit and restart to change them. The public relay metadata stays payment-free regardless of mode.

Mixnet exit

Flip one toggle and this relay also runs a co-located mixnet exit, so wallets can reach it over the mixnet:

[exit]
enabled = true
binary = "/usr/local/bin/floonet-mixexit"
data_dir = "/var/lib/floonet-rs/mixexit"
upstream = "relay.example.com:443"   # your public TLS endpoint

The exit (bundled in mixexit/) is an ordinary unbonded mixnet client: no node registration, no tokens, no directory listing. It forwards every accepted stream to the ONE configured upstream, never a caller-chosen target, so it is structurally not an open proxy and you carry no exit liability. Wallets run hostname-validated TLS end to end through the pipe; the exit only ever sees ciphertext.

The exit's mixnet address is stable across restarts (the identity persists in data_dir; back it up). It is printed at startup and written to <data_dir>/nym_address.txt; publish it, for example in the Floonet relay pool exit field, so wallets prefer your exit and fall back to the public mixnet route when it is down.

Build the exit binary separately (it pulls the mixnet SDK tree):

cargo build --release --manifest-path mixexit/Cargo.toml

The path dependency expects the Goblin nym checkout (branch goblin) two directories up; adjust mixexit/Cargo.toml for your layout. Verify with floonet-mixexit --selftest, which joins the mixnet, prints the stable address, and exits.

Extending: policies and paid resources

Admission is a small ordered pipeline in src/admission.rs. Each check implements one trait:

pub trait AdmissionPolicy: Send + Sync {
    fn check(&self, event: &Event, authed_pubkey: Option<&str>) -> Decision;
}

To add a policy (a paid gate, a spam filter, a tag rule), implement the trait and append it in Admission::from_settings; the first denial wins. To add a kind, edit the config; no code change needed. The gRPC event_admission_server extension point from upstream also remains available for out-of-process policies.

Paid uses follow the same pattern as names: quote a price, hand the client a GoblinPay pay page, verify the confirmed invoice, then grant the resource. Names are the first paid resource; paid media storage for GRIN (NIP-96 HTTP file storage or Blossom content-addressed blobs, advertised with a kind 10063 server list, priced per upload or per MB) is the designed-for next example: the same 402 pay_url -> confirm -> grant gate applied to an upload endpoint.

Operational notes

• Reverse proxy: terminate TLS at Caddy or nginx and forward X-Real-IP (remote_ip_header in the config). All per-IP rate limiting keys off it.
• Event size: keep max_event_bytes at its default (256 KB) or larger; gift-wrapped payloads can be big.
• Database: SQLite by default; the schema migrates automatically at startup (this fork adds name_claims at version 19). The name authority requires the sqlite engine; postgres remains available for the plain relay.
• Secrets: nothing in this repository; the GoblinPay token comes from the config file (0600) or the environment.
• Multiple identities, one wallet: a Goblin wallet can hold several Nostr identities. If you pay for a name and want to keep it, load the same wallet and switch to (or add) that npub; different identities share one wallet.

Upstream documentation for the inherited features lives in docs/ (database maintenance, gRPC extensions, reverse proxies, and more) and in docs/upstream/README.md.

Development

cargo build --release       # build the relay
cargo test                  # unit + integration tests

The integration tests stand up real relays on loopback and cover the whitelist end to end (allowed kind accepted, disallowed kind rejected), the name authority round trip (register, resolve, reverse lookup, conflicts, reserved names, release, cooldown), the paid-name flow against a stub GoblinPay server, and the payment-free NIP-11 rule.

License

MIT, same as upstream. The upstream relay is by Greg Heartsfield and contributors; the Floonet additions are by the Floonet developers.

🤖 Built with AI pair-programming assistance (Claude)