# deadhop

> Accept on-chain bitcoin payments without exposing a server.

**Nothing to reach. Nothing to spend.**

deadhop creates bitcoin invoices, watches the chain and reports payments. Customers and operators reach it only through Nostr relays. It opens no ports and holds no spending keys.

## How a payment flows

### Nothing to connect to

The service only dials out, to Nostr relays. There is no listening socket, HTTP endpoint or login form, so there is nothing to port-scan, nothing to DDoS by IP and no web stack to exploit.

### Relays carry ciphertext

Requests and responses are ContextVM (MCP over Nostr), NIP-44 encrypted and gift-wrapped (NIP-59). Relays forward them without being able to read or alter them. Plaintext requests are refused.

### Proof of work on public invoices

A non-operator who creates an invoice must mine NIP-13 proof of work into the signed request. The work is bound to the caller’s key, to this service and to one use. Rate limits and daily caps apply after it.

### Watch-only: it cannot spend

The service holds only an account public key (xpub). It derives a fresh native segwit address for every invoice. Taking over the server does not move funds already received.

### Confirmed by your own node

Payments are read from your Electrum server (Fulcrum or electrs). The service re-hashes every transaction it is given, counts confirmations itself, and pins the chain’s genesis block on every reconnect.

## Security benefits

- **No IP address to attack.** Outbound connections only. Run it behind a VPN or Tor and relays see the exit, not you.
- **End-to-end encryption.** NIP-44 with NIP-59 gift wrap. Relays can see that someone talks to the service key, when and how much, but not what is said.
- **No passwords or accounts.** Callers are identified by the Nostr key that signed the request. Operators are a list of public keys.
- **Strictly typed interface.** Every tool has published JSON schemas. Unknown fields are rejected; the dashboard validates every response with strict schemas.
- **Proof of work and rate limits.** NIP-13 work for public invoice creation, per-key and global budgets, open-invoice and daily caps.
- **Replay protection.** Every invoice request must be fresh, addressed to this service and never seen before, operators included.
- **Cannot spend.** Watch-only BIP-84 wallet. A compromised host cannot move funds already received.
- **Verified payment data.** Transactions are re-hashed against their ids, sums are capped, and one bad invoice cannot stall the others.
- **Small, tested code.** One Rust binary, no HTTP stack, SQLite. 100% line and function coverage, plus end-to-end tests on regtest.
- **Remote control without remote risk.** Operators manage relays, proxy, limits and keys from the dashboard. Every change is one-time, audited, and can never touch the wallet or the Electrum server.
- **Hardened dashboard.** Static Svelte page with a strict Content-Security-Policy, frame refusal and text-only rendering of server data.

## What it does not protect against

- Your Electrum server is trusted. Run your own and keep it on a private network.
- Public invoicing slows abuse down but a determined attacker can still degrade it. A shop back end can hold an operator key instead.
- Relays see metadata: timing, sizes and the IP that connects. Use a VPN or Tor.
- Only “confirmed” means paid. Use more confirmations for larger amounts.

## What you run

- **Service:** Rust. One binary, SQLite, watch-only wallet.
- **Dashboard:** Svelte. Checkout, plus health, statistics, settings and backups for operators. Sign in with a Nostr key.
- **Your node:** Any Electrum server: Fulcrum or electrs next to Bitcoin Core.

**Price:** Self-hosted software. No fees, no custodian, no account.

## Questions

**Who can create an invoice?**

By default only operators, identified by the Nostr public keys you list. You can also allow the public to create invoices; each public request then has to carry proof of work and is rate limited.

**Do I log in?**

No accounts or passwords. The dashboard signs each request with your Nostr key, from a browser extension or a pasted key.

**Can a compromised server spend my bitcoin?**

No. The service holds only an account public key (xpub), so it can derive addresses but cannot sign transactions.

**What do I need to run it?**

The deadhop binary, a few Nostr relays, and an Electrum server (Fulcrum or electrs) on your own Bitcoin node. The dashboard is a static page you can host anywhere.

## Documentation

- [Quick start](/docs/quickstart.md): Run the full stack on regtest and pay an invoice.
- [How it works](/docs/how-it-works.md): Architecture, invoice states, who can create invoices.
- [Configuration](/docs/configuration.md): Every environment variable and its default.
- [Deployment](/docs/deployment.md): Service, dashboard and network placement.
- [Tools API](/docs/api.md): Invoicing and operator tools: inputs, outputs and errors.
- [Security](/docs/security.md): Threat model, findings and the risks you accept.
