# 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. --- Source: https://deadhop.run/docs/ # deadhop documentation > deadhop accepts on-chain bitcoin payments from a service that has no public address. Clients reach it only through Nostr relays using ContextVM. deadhop creates on-chain bitcoin invoices, watches the chain and reports payments, like a BTCPay-style server does for simple invoicing. It never listens on a port. Customers and operators reach it only through Nostr relays, using [ContextVM](https://contextvm.org) (MCP over Nostr), so an attacker has no IP address, HTTP endpoint or login form to aim at. ## What you get - **A fresh address per invoice**, derived from a watch-only BIP-84 account key. The service cannot spend. - **Payment detection and confirmation tracking** against your own Electrum server. - **A static Svelte dashboard** for checkout and for operators. Sign in with a Nostr key; there are no accounts. - **Strictly typed tools** over end-to-end encrypted Nostr messages: five for invoicing, twelve for operators (health, statistics, settings, keys, control, backups). ## Components | Part | Technology | Role | | --- | --- | --- | | Service (`server/`) | Rust, one binary (about 8 MB), SQLite | Issues invoices, polls the chain, answers requests | | Dashboard (`dashboard/`) | Svelte 5 static page | Checkout for customers, overview for operators | | Chain backend | Fulcrum or electrs | Reports transactions for each invoice address | | Transport | Any Nostr relays | Carries encrypted requests and responses | ``` customer / operator relays your machine ┌──────────────────┐ wss ┌────────────┐ wss ┌──────────────────────────┐ │ Svelte dashboard ├──────►│ Nostr │◄──────┤ deadhop (Rust) │ │ Nostr identity │ │ relay(s) │ │ outbound only │ │ NIP-44 + NIP-13 │ │ ciphertext │ │ watch-only xpub, SQLite │ └──────────────────┘ └────────────┘ └────────────┬─────────────┘ │ Electrum protocol ┌───────▼────────┐ │ Fulcrum/electrs│ └────────────────┘ ``` ## Where to go next - [Quick start](./quickstart.md): run everything on regtest and pay an invoice. - [How it works](./how-it-works.md): data flow, invoice states, who can create invoices. - [Configuration](./configuration.md) and [Deployment](./deployment.md): run it for real. - [Integrate into your app](./integrate.md): pay buttons and invoices, with a guide each for [React](./integrate-react.md), [Solid](./integrate-solid.md), [Svelte 5](./integrate-svelte5.md), [Svelte 4](./integrate-svelte4.md), [plain JavaScript](./integrate-javascript.md) and your [backend](./integrate-backend.md). - [Tools API](./api.md): invoicing and operator tools, for building your own client. - [Security](./security.md): threat model, findings and the risks you accept. --- Source: https://deadhop.run/docs/quickstart.html # Quick start > Run deadhop, its dashboard, bitcoind, Fulcrum and a private relay on a local regtest chain, then create and pay an invoice. Run the whole system on a throwaway regtest chain, on loopback only. ## Requirements - Rust 1.88 or newer - Node 22 or newer - Docker - [`just`](https://github.com/casey/just) ## Start it ```sh just up # regtest bitcoind + Fulcrum + private relay, a funded "miner" and a "merchant" wallet just server # builds and runs deadhop; writes dashboard/public/config.json just dashboard # serves the dashboard at http://127.0.0.1:4173 ``` Run `npm install` in `dashboard/` once before `just dashboard`. ## Pay an invoice 1. Open http://127.0.0.1:4173 and choose **Continue as guest**. 2. Enter an amount and choose **Create invoice**. The page mines proof of work, then shows the QR code and address. 3. Pay it from the regtest miner wallet. This also mines one block: ```sh just pay
``` 4. The page moves to *Payment seen* and then *Paid* on its own. 5. Sign in as the operator by pasting the key in `data/dev/operator.nsec` to see the operator dashboard. To use your own key instead, add it under **Settings → Operators**, or put `DEADHOP_ADMINS=npub1…` in `.env.local` (gitignored; the dev scripts read it on every run). Any other key only gets the invoice form. ## Stop it ```sh just down # removes the stack and its chain data ``` The development stack uses unpinned images and no authentication. Never use it as a production deployment; see [Deployment](./deployment.md). --- Source: https://deadhop.run/docs/how-it-works.html # How it works > How deadhop receives requests over Nostr, checks proof of work, derives addresses, detects payments and moves invoices between states. ## Request path 1. A client (the dashboard, or your own) builds an MCP request and signs it as a Nostr event of kind 25910 (ContextVM). 2. The event is NIP-44 encrypted to the service's key and gift-wrapped (NIP-59), then published to the relays the service listens on. 3. The service, which holds open outbound websocket connections to those relays, receives it, unwraps it and identifies the caller by the key that signed the inner event. 4. The service checks admission (see below), runs the tool, and sends back an encrypted, gift-wrapped response the same way. Plaintext requests are refused. The service never accepts an inbound connection. | Concern | Mechanism | | --- | --- | | Reachability | Only outbound websocket connections to relays | | Confidentiality | NIP-44 encryption with NIP-59 gift wrap on every message | | Identity | The Nostr key that signed the request; operators are a configured list of keys | | Typed interface | MCP tools with published JSON schemas (five for invoicing, twelve for operators); unknown fields are rejected | | Abuse resistance | NIP-13 proof of work for public invoice creation, then rate limits and caps | | Funds | Watch-only account public key; one fresh native segwit address per invoice | | Payment detection | Polls an Electrum server per open invoice, re-hashes every transaction, counts confirmations | ## Who can create invoices You choose with `DEADHOP_PUBLIC_INVOICING`. **Off (the default): operators only.** An operator is a Nostr public key listed in `DEADHOP_ADMINS` (hex, `npub` or `nprofile`), or added from the dashboard by another operator. There is no account or password: the dashboard signs each request with the operator's key, and the service checks the signature against the list. Use this when you hand out invoices yourself, or when a shop back end holds an operator key and creates invoices for customers. **On: anyone can request one.** The dashboard's **Continue as guest** creates a throwaway key in the browser. Each public `create_invoice` must carry proof of work (`DEADHOP_POW_BITS`, default 20) and is subject to per-key and global rate limits, a cap on open invoices and a daily cap. The public cannot request a lifetime longer than the default. In both modes: - `list_invoices` and `get_stats` are operator-only. - `get_invoice` works for anyone who holds the invoice's 128-bit random id. The id is the capability, so customers see only the invoices they were given. - Paying never touches the service: the customer sends bitcoin to the address. ## Proof of work The client mines a NIP-13 `nonce` tag into the request event itself before signing it. The tag commits to the target difficulty. The service accepts the event only if all of these hold: - it is signed by the caller and is of the ContextVM kind; - it is addressed to this service (`p` tag); - it is fresh, within `DEADHOP_POW_WINDOW_SECS` (default 600 s); - it has never been used before; - it meets the difficulty, both the committed target and the required one. Operators skip only the difficulty check. The others apply to them too, so a captured operator request cannot be replayed. ## Addresses `DEADHOP_XPUB` is a BIP-84 account key (`xpub`/`zpub`, or `tpub`/`vpub` on test networks). Leave it unset under Compose and the offline `wallet` service generates a 24-word wallet, keeps the phrase to itself (no network, its own volume) and passes only the account key on; `deadhop wallet export` prints the phrase so the funds can be spent from any wallet app. Invoice *n* gets the P2WPKH address at `0/n` on that account. Index allocation is atomic in SQLite, so two invoices never share an address. ## Payment detection Every `DEADHOP_POLL_SECS` (default 10 s) the service asks the Electrum server for the history of each open invoice's script, plus the chain tip. For each transaction it: - checks that the raw transaction hashes to the txid it was given; - counts each transaction once, even if the server lists it twice; - sums outputs to the invoice address, capped at the bitcoin supply; - computes confirmations from the transaction's height and the tip. Each invoice is evaluated on its own. One that cannot be read keeps its last known amounts and is counted in `watch_errors`, and the others carry on. On every reconnection the service checks the Electrum server's genesis block against `DEADHOP_NETWORK`. ## Invoice states | State | Meaning | | --- | --- | | `pending` | Waiting for payment | | `detected` | The full amount has been seen, not yet with enough confirmations | | `confirmed` | The full amount has at least `DEADHOP_MIN_CONFIRMATIONS` confirmations. Final. | | `expired` | The lifetime passed before the full amount was seen | An unconfirmed payment that disappears (replaced or double-spent) moves a `detected` invoice back. Expired invoices are still watched for `DEADHOP_LATE_GRACE_SECS` (default one day), so a late payment that covers the amount still moves the invoice to `detected` and then `confirmed`. `detected` means *seen*, not *paid*. Release goods only on `confirmed`. --- Source: https://deadhop.run/docs/configuration.html # Configuration > Every deadhop environment variable, its default and what it controls, plus the startup checks the service performs. All configuration is environment variables. Nothing has a network-reaching default. | Variable | Default | Meaning | | --- | --- | --- | | `DEADHOP_RELAYS` | required | Comma-separated `wss://` relay URLs | | `DEADHOP_ELECTRUM` | required | Electrum server: `host:port` (plain TCP) or `tls://host:port` | | `DEADHOP_ELECTRUM_CERT_SHA256` | none | Pin the server's TLS certificate: SHA-256 fingerprint(s), comma-separated | | `DEADHOP_XPUB` | see below | Your wallet's BIP-84 **account** key (`xpub`/`zpub`, or `tpub`/`vpub` on test networks). Unset: one is generated (Compose) | | `DEADHOP_XPUB_FILE` | none | Read the account key from this file when `DEADHOP_XPUB` is unset (the wallet service writes it) | | `DEADHOP_NETWORK` | `bitcoin` | `bitcoin`, `testnet`, `signet` or `regtest` | | `DEADHOP_ADMINS` | none | Comma-separated operator public keys (hex or `npub`) | | `DEADHOP_PUBLIC_INVOICING` | `false` | Let non-operators create invoices (with proof of work) | | `DEADHOP_POW_BITS` | `20` | NIP-13 difficulty for non-operators | | `DEADHOP_POW_WINDOW_SECS` | `600` | Accepted age and clock skew of a request event | | `DEADHOP_MIN_CONFIRMATIONS` | `1` | Confirmations before `confirmed` | | `DEADHOP_DEFAULT_EXPIRY_SECS` | `3600` | Invoice lifetime when none is requested | | `DEADHOP_MAX_EXPIRY_SECS` | `86400` | Longest lifetime an operator may request | | `DEADHOP_MIN_AMOUNT_SAT` | `1000` | Smallest invoice | | `DEADHOP_MAX_AMOUNT_SAT` | `100000000` | Largest invoice | | `DEADHOP_MAX_OPEN_INVOICES` | `500` | Open invoices before the public is refused | | `DEADHOP_MAX_INVOICES_PER_DAY` | `2000` | Invoices (address indices) per 24 h before the public is refused | | `DEADHOP_RATE_GLOBAL_PER_MIN` | `30` | Public invoice creations per minute, all callers | | `DEADHOP_RATE_PER_KEY_PER_MIN` | `6` | Public invoice creations per minute, per key | | `DEADHOP_RATE_REQUESTS_PER_MIN` | `1200` | Public tool calls per minute, all callers | | `DEADHOP_RATE_REQUESTS_PER_KEY_PER_MIN` | `120` | Public tool calls per minute, per key | | `DEADHOP_POLL_SECS` | `10` | Chain polling interval | | `DEADHOP_LATE_GRACE_SECS` | `86400` | How long expired invoices are still watched | | `DEADHOP_DATA_DIR` | `data` | Database and the service's Nostr key (created `0700`) | | `DEADHOP_ANNOUNCE` | `false` | Publish public ContextVM discovery announcements | | `DEADHOP_NAME` | `deadhop` | Name shown in the dashboard | | `DEADHOP_PROXY` | none | Proxy for relay connections only: `socks5://`, `https://` or `http://`, optionally `user:pass@` | | `DEADHOP_PROXY_LOCKED` | `false` | Refuse proxy changes from the dashboard | | `DEADHOP_LOG` | `warn,deadhop=info,contextvm_sdk=off,rmcp=off` | Log filter | At least one of `DEADHOP_ADMINS` or `DEADHOP_PUBLIC_INVOICING=true` is required. `DEADHOP_ADMINS` accepts hex, `npub` and `nprofile` keys, with or without `nostr:`. ## Changing settings from the dashboard Operators can change the relays, proxy, proof of work, rate limits, amount and lifetime limits, confirmations, caps, polling, the late-payment grace and the PayJoin/CoinJoin policy at runtime, and add or remove operator keys. Changes are stored in the database as overrides on top of the environment and survive restarts. *Reset to environment* drops them all. - A new relay list or proxy reconnects the service. If no relay connects within 30 seconds, the previous ones are restored. - Values are checked against the same bounds as the environment. - If the environment later changes so that stored overrides no longer fit, they are ignored and a warning is shown. - These stay host-only: `DEADHOP_XPUB`, `DEADHOP_NETWORK`, `DEADHOP_ELECTRUM`, `DEADHOP_DATA_DIR`, `DEADHOP_ANNOUNCE` and the keys in `DEADHOP_ADMINS`. With `DEADHOP_PROXY_LOCKED=true` the proxy is host-only too. ## Electrum over TLS For an Electrum server that is not on this machine, use its TLS port and pin its certificate: ```sh deadhop fingerprint node.lan:50002 # prints the certificate's SHA-256 and the settings below export DEADHOP_ELECTRUM=tls://node.lan:50002 export DEADHOP_ELECTRUM_CERT_SHA256= ``` - The command trusts whatever answers, so compare the fingerprint with the certificate on the node, for example `openssl x509 -in -noout -fingerprint -sha256`. - A pinned certificate is accepted whatever its name, issuer or expiry, which suits self-signed Fulcrum certificates. The server must still prove it holds the certificate's private key, on every connection. - List two fingerprints, comma-separated, while rotating a certificate. - Without a pin, `tls://` checks the certificate against the public authorities (and the service warns that it is not pinned). - A certificate that does not match stops the service at startup and fails every reconnection. ## Proxy Only connections to Nostr relays go through the proxy; the Electrum server is always reached directly. | Form | Use | | --- | --- | | `socks5://127.0.0.1:9050` | Tor or a VPN's SOCKS server; host names are resolved by the proxy, so `.onion` relays work | | `https://user:pass@proxy.example:443` | An HTTPS proxy (TLS to the proxy, checked against the public web roots, then `CONNECT`) | | `http://127.0.0.1:3128` | A plain HTTP `CONNECT` proxy on this machine or a private network | Operators are exempt from proof of work and rate limits. The public cannot request a lifetime longer than `DEADHOP_DEFAULT_EXPIRY_SECS`. ## Startup checks - **Identity.** On first start the service creates its Nostr key in `/server.nsec` (mode `0600`) and writes the public key to `/server.pubkey`. It refuses to start if the key file is readable by others. - **Chain.** It refuses to start if the Electrum server's genesis block does not match `DEADHOP_NETWORK`. - **Warnings.** It logs a warning for a remote Electrum server, weak proof of work with public invoicing on, and `ws://` relays on mainnet. - **First address.** It logs the receive address at index 0. Confirm that your wallet shows that exact address before taking real payments. A wrong account key (for example BIP-49 instead of BIP-84) still produces valid addresses, but your wallet will not show payments to them. ## Example ```sh export DEADHOP_RELAYS=wss://relay.one.example,wss://relay.two.example export DEADHOP_ELECTRUM=127.0.0.1:50001 export DEADHOP_XPUB=zpub... # BIP-84 account key, public only export DEADHOP_ADMINS=npub1... # your operator key export DEADHOP_MIN_CONFIRMATIONS=2 deadhop ``` --- Source: https://deadhop.run/docs/deployment.html # Deployment > Run deadhop in production. Supervise the service, host the static dashboard with security headers, and place it behind a VPN or Tor with your own Electrum server. ## 1. The service 1. Build it: `cargo build --release` in `server/` produces `target/release/deadhop`. 2. Configure it with environment variables (see [Configuration](./configuration.md)). 3. Run it as its own user under a supervisor such as systemd with `Restart=always`. If the request loop ever stops, the process exits with an error instead of staying up while answering nobody. 4. Back up the data directory with its permissions intact. It holds the SQLite database and the service's Nostr key. Example systemd unit: ```ini [Unit] Description=deadhop After=network-online.target Wants=network-online.target [Service] User=deadhop EnvironmentFile=/etc/deadhop/env WorkingDirectory=/var/lib/deadhop ExecStart=/usr/local/bin/deadhop Restart=always NoNewPrivileges=true ProtectSystem=strict ProtectHome=true ReadWritePaths=/var/lib/deadhop PrivateTmp=true [Install] WantedBy=multi-user.target ``` ## 2. The dashboard ```sh cd dashboard && npm ci && npm run build ``` Serve `dashboard/dist/` from any static host, with a `config.json` next to `index.html` (see `public/config.example.json`) holding the service's public key and the relay list. The page ships a strict Content-Security-Policy and makes no requests other than `config.json` and the relay websockets. It refuses to run inside a frame and shows the service key it is talking to in its footer, so it can be compared with the one you publish. Have the web server add these headers (a `` policy cannot express the first): ``` Content-Security-Policy: frame-ancestors 'none' X-Content-Type-Options: nosniff Referrer-Policy: no-referrer ``` ## 3. Network placement - **Hide the service's address.** Run it behind a VPN or Tor so relays see the exit, not you: route the whole host, or set `DEADHOP_PROXY` (for example `socks5://127.0.0.1:9050` for Tor) for relay connections. Add `DEADHOP_PROXY_LOCKED=true` so that an operator key cannot swap in a proxy that reveals your address. The service needs outbound access to the relays and the Electrum server only; drop all inbound traffic. - **Use your own Electrum server.** Fulcrum or electrs on your node, on the same host or a private network; across a network, use `tls://` with a pinned certificate (see [Configuration](./configuration.md#electrum-over-tls)). A third-party server learns every address you issue and decides what you believe was paid. - **Use more than one relay**, prefer relays you run, and use `wss://` only. ## Checklist - [ ] Electrum server is your own and reachable only locally or over a private network - [ ] If it is not on the same machine: `tls://` with a pinned `DEADHOP_ELECTRUM_CERT_SHA256` - [ ] Either `DEADHOP_XPUB` is your wallet's BIP-84 account key and the first receive address logged at startup appears in that wallet, or the wallet was generated and its recovery phrase has been exported (`deadhop wallet export`) and stored offline - [ ] Wallet gap limit raised if public invoicing is on - [ ] Public invoicing off unless you need it; `DEADHOP_POW_BITS` at 20 or more if on - [ ] `DEADHOP_MIN_CONFIRMATIONS` chosen for your amounts - [ ] Service runs as its own user, behind a VPN or Tor, with inbound traffic dropped - [ ] A supervisor restarts the process if it exits - [ ] Two or more relays, at least one you control, all `wss://` - [ ] Data directory backed up with its permissions intact - [ ] Dashboard served over HTTPS with the headers above - [ ] Operators use a browser extension and a key made only for this service - [ ] Someone watches for `chain_ok = false` and `watch_errors > 0` in the operator view - [ ] `DEADHOP_PROXY` and `DEADHOP_PROXY_LOCKED=true` set on the host if the service's location must stay hidden even from someone holding an operator key - [ ] Backups in `/backups` are copied off the host regularly ## Testing against a real Electrum server A read-only smoke test asks a server for its genesis hash and chain tip. Put the host in the gitignored `.env.local`: ```sh # .env.local: DEADHOP_TEST_ELECTRUM_HOST=... [DEADHOP_TEST_ELECTRUM_PORT=50001] just live-electrum ``` --- Source: https://deadhop.run/docs/api.html # Tools API > Reference for the deadhop MCP tools served over ContextVM, for invoicing and for operator management, with inputs, outputs and error codes. deadhop is an MCP server reached over Nostr with [ContextVM](https://contextvm.org). Any MCP client that speaks the ContextVM transport can call it. Results come back as MCP `structuredContent` that matches each tool's published output schema. ## Connecting You need the service's public key (`/server.pubkey`) and its relay list. With the TypeScript SDK: ```ts import { Client } from '@contextvm/mcp-sdk/client/index.js'; import { EncryptionMode, NostrClientTransport, PrivateKeySigner } from '@contextvm/sdk'; const transport = new NostrClientTransport({ signer: new PrivateKeySigner(myHexSecretKey), relayHandler: ['wss://relay.one.example'], serverPubkey: SERVICE_PUBKEY_HEX, encryptionMode: EncryptionMode.REQUIRED, // the service refuses plaintext }); const client = new Client({ name: 'my-shop', version: '1.0.0' }); await client.connect(transport); const info = await client.callTool({ name: 'get_info', arguments: {} }); ``` A non-operator calling `create_invoice` must mine NIP-13 proof of work into the signed request event: add a `["nonce", "", ""]` tag and vary the counter until the event id has at least `pow_bits` leading zero bits. The dashboard's `src/lib/pow.ts` is a working implementation that wraps any signer. ## Tools All inputs reject unknown fields. ### `get_info` Anyone. No arguments. Returns the service parameters for this caller. | Field | Type | Meaning | | --- | --- | --- | | `name`, `version` | string | Service name and version | | `network` | string | `bitcoin`, `testnet`, `signet` or `regtest` | | `public_invoicing` | boolean | Whether non-operators may create invoices | | `pow_bits` | integer | Required proof of work for non-operators | | `pow_window_secs` | integer | Accepted age of a request event | | `min_confirmations` | integer | Confirmations before `confirmed` | | `default_expiry_secs` | integer | Lifetime when none is requested | | `max_expiry_secs` | integer | Longest lifetime this caller may request | | `min_amount_sat`, `max_amount_sat` | integer | Amount bounds | | `is_admin` | boolean | Whether the caller is an operator | ### `create_invoice` Operators, and the public when `public_invoicing` is on (with proof of work). | Argument | Type | Meaning | | --- | --- | --- | | `amount_sat` | integer, required | Amount in satoshis, within the bounds above | | `memo` | string, optional | Note stored with the invoice, at most 200 characters, no control or invisible characters | | `expiry_secs` | integer, optional | Lifetime in seconds, from 60 up to `max_expiry_secs` | Returns an **Invoice**: | Field | Type | Meaning | | --- | --- | --- | | `id` | string | 32 lowercase hex characters (128 random bits). Whoever holds it can read the invoice. | | `address` | string | Fresh native segwit address | | `amount_sat` | integer | Requested amount | | `memo` | string | Note, empty if none | | `status` | string | `pending`, `detected`, `confirmed` or `expired` | | `received_sat` | integer | Total seen, confirmed or not | | `confirmed_sat` | integer | Total with enough confirmations | | `created_at`, `expires_at` | integer | Unix seconds | | `settled_at` | integer or null | When it became `confirmed` | | `bip21` | string | `bitcoin:` URI with address and amount | | `confirmations_required` | integer | Confirmations this invoice needs | ### `get_invoice` Anyone holding the id. Argument: `id` (32 lowercase hex characters). Returns an Invoice. ### `list_invoices` Operators only. Newest first. | Argument | Type | Meaning | | --- | --- | --- | | `status` | string, optional | Only invoices in this state | | `before` | integer, optional | Only derivation indices below this (pagination cursor) | | `limit` | integer, optional | Page size, 1 to 200, default 50 | Returns `{ invoices, next_before }`. Each entry is an Invoice plus `index` (derivation index) and `creator` (hex key that created it). Pass `next_before` as `before` for the next page; it is absent on the last page. ### `get_stats` Operators only. No arguments. | Field | Type | Meaning | | --- | --- | --- | | `pending`, `detected`, `confirmed`, `expired` | integer | Invoice counts per state | | `confirmed_sat`, `detected_sat` | integer | Amounts in those states | | `next_index` | integer | Next derivation index | | `tip_height` | integer or null | Last chain tip seen | | `last_poll_at` | integer or null | Unix seconds of the last poll | | `chain_ok` | boolean | Whether the last poll reached the chain backend | | `watch_errors` | integer | Invoices that could not be read in the last poll | ## Management tools Operators only. Every tool that changes something needs a fresh request event addressed to this service that was never used before (ids are remembered across restarts) and is recorded in the audit log. | Tool | Arguments | Returns | | --- | --- | --- | | `get_health` | none | `service` (version, start, uptime, online since, paused, restarts), `relays` (url, status, connected), `proxy` (password hidden), `chain`, `database` (integrity, size, invoices, backups), `warnings` | | `get_metrics` | none | `addresses_created`, `invoices`, `payments`, `received_sat`, `windows` for `24h`, `7d`, `30d`, `365d` with `available` (false until the service has been online that long), `sweep` status | | `get_payment_series` | `range`: `day`, `week`, `month` or `year` | `points` of `{ start, count, sat }`: 24 hourly, 7 or 30 daily, or 52 weekly buckets, gap-filled | | `get_settings` | none | `settings` (live), `defaults` (environment), `overridden` (names), `fixed` (host-only values), `operators`, `restart_pending`, `warnings` | | `update_settings` | `patch`: only the settings to change; `sweep` may be partial; `proxy: ""` turns the proxy off | Same as `get_settings` | | `reset_settings` | none | Same as `get_settings` | | `add_operator` | `pubkey` (hex, `npub` or `nprofile`), optional `label` | Same as `get_settings` | | `remove_operator` | `pubkey` | Same as `get_settings`; environment keys are refused | | `control_service` | `action`: `stop` (refuse new invoices), `start`, `restart` (reconnect relays in-process) | `{ paused, restart_pending }` | | `backup_database` | none | `{ file, size_bytes, created_at }`, written to `/backups` | | `wipe_database` | `confirm: "WIPE"`, optional `include_settings`, `force` | `{ deleted, backup }` | | `get_audit_log` | optional `limit` (1 to 200) | `entries` of `{ at, actor, action, detail }` | Settings that can be patched: `name`, `relays`, `public_invoicing`, `pow_bits`, `pow_window_secs`, `min_confirmations`, `default_expiry_secs`, `max_expiry_secs`, `min_amount_sat`, `max_amount_sat`, `max_open_invoices`, `max_invoices_per_day`, `rate_global_per_min`, `rate_per_key_per_min`, `rate_requests_per_min`, `rate_requests_per_key_per_min`, `poll_secs`, `late_grace_secs`, `proxy` and `sweep` (`enabled`, `mode` = `payjoin` or `coinjoin`, `threshold_sat`, `max_fee_rate_sat_vb`, `min_anonymity_set`). Unknown fields are refused. A request sent while the service is reconnecting is not answered; clients should time out and retry. ## Errors Errors are JSON-RPC errors with a stable `data.code`. Internal error text never reaches the caller. | JSON-RPC code | `data.code` | Meaning | | --- | --- | --- | | -32602 | `invalid_params` | Arguments out of range or malformed | | -32001 | `unauthorized` | Operator-only tool, or public invoicing is off | | -32002 | `not_found` | No invoice with that id | | -32003 | `pow_rejected` | Missing or insufficient work, stale, replayed or not addressed to this service | | -32004 | `rate_limited` | A rate limit was hit; retry later | | -32005 | `capacity` | Open-invoice or daily cap reached | | -32006 | `paused` | Invoicing is stopped by an operator | | -32603 | `internal` | Something failed on the service side | Arguments that do not match the input schema at all (wrong types, unknown fields) come back as a tool result with `isError: true` rather than a JSON-RPC error. --- Source: https://deadhop.run/docs/integrate.html # Integrate payments into your app > What every deadhop integration shares (the service, who creates invoices, checking payments, proof of work) and the guide for each client. A client package and one component package per framework put deadhop into an app you already have. This page covers what every integration shares. For code, pick your client under [Choose your client](#choose-your-client). | Package | What it is | Where | | --- | --- | --- | | `@deadhop/client` | Framework-agnostic client: connect, create and look up invoices, a headless checkout, QR codes | npm and JSR (the notemine adapter: npm only) | | `@deadhop/react` | `PayButton`, `InvoiceForm`, `Invoice` and `useCheckout` for React | npm and JSR | | `@deadhop/solid` | The same for Solid | npm and JSR | | `@deadhop/svelte` | The same for Svelte 5, and for Svelte 4 at `@deadhop/svelte/svelte4` | npm only (JSR can't host `.svelte` files) | ## What your app talks to Your app never calls an HTTP API. It sends encrypted messages to a deadhop service over Nostr relays. Two values identify the service: | Value | Where it comes from | | --- | --- | | `serverPubkey` | The service's public key (hex or `npub`). On the host: `deadhop pubkey`, or the `server.pubkey` file in its data directory. Behind the homelab tooling: `./homelab cvmpay pubkey`. It is also the `serverPubkey` in the dashboard's `config.json`. | | `relays` | Relays the service listens on (`DEADHOP_RELAYS`, or as changed in the dashboard). Your page needs **at least one** of them. | The service can be your own (self-hosted) or run by someone else (remote): the code is the same either way, only these two values change. With a remote service, you trust its operator to report payments truthfully. You can check its addresses against your own wallet only if it uses your xpub. ```ts import { createDeadhop } from '@deadhop/client'; export const deadhop = createDeadhop({ serverPubkey: 'npub1…', // the service's public key relays: ['wss://relay.example.com'], // shared with the service }); ``` `createDeadhop` connects only when it is first used and keeps one connection, so create it once per page (or per process) and pass it to every component. ## Two ways to create invoices ### 1. The browser creates them (public invoicing) The customer's browser creates the invoice itself. A `PayButton` does this in one click. - On the service: `DEADHOP_PUBLIC_INVOICING=true` (or *Public invoicing* in the dashboard's Settings). - The browser signs with a throwaway key made in memory: customers need no Nostr account and see no extension prompt. - Each invoice costs the browser a proof of work (`DEADHOP_POW_BITS`, default 20 bits). The built-in miner took 5.3 s on average for 20 bits in desktop Chrome, and a phone is slower; it is shown as *Preparing invoice…*. The service also rate-limits public invoices. Good for tips, donations, a fixed-price product, or any page without a backend. Nothing to configure in your app: the service tells each client how much work it wants (`pow_bits` in `get_info`), and the client mines exactly that before each new invoice. Operators owe none. To make it faster, see [Faster proof of work](#faster-proof-of-work-notemine). ### 2. Your backend creates them (operator key) Your server creates the invoice with an operator key and hands its id to the page. The page only watches it with ``, which any key may do: the id is the capability. - On the service: add the backend's public key to `DEADHOP_ADMINS` (or Settings → Operators). Public invoicing can stay off. - No proof of work, and you decide the amount and memo on the server, not the customer. - **An operator key can also manage the service** (settings, relays, wipe). Keep it on the server, never in a browser bundle, and use a key made only for this. See [Backend](./integrate-backend.md) for the code. ## Fulfil orders only after your backend has checked `onPaid` runs in the customer's browser, and the customer controls the browser. Use it to update the page, never to release goods. Before you ship, ask the service yourself: [Backend](./integrate-backend.md#check-before-you-fulfil) shows the check. - `detected` means the payment was seen, not that it is final. An unconfirmed payment can still disappear. Wait for `confirmed` (`DEADHOP_MIN_CONFIRMATIONS`). - An `expired` invoice can still become `confirmed`: the service keeps watching for late payments (`DEADHOP_LATE_GRACE_SECS`), and the components keep polling. - Check that `invoice.amount_sat` is what you asked for. ## Choose your client Every client gets the same three components, with the same props and events: | Component | Does | | --- | --- | | `PayButton` | A button for a fixed `amount` (sats). On click it creates the invoice and shows it: QR code, address, copy button, countdown, then the payment's progress. | | `InvoiceForm` | Amount and optional note fields. Creates the invoice and shows it, with *New invoice* to start over. | | `Invoice` | Shows an existing invoice by `id` and follows it until paid. Use it with invoices your backend created. | | Your app | Import from | Guide | | --- | --- | --- | | React 18 or 19 (Next.js too) | `@deadhop/react` | [React](./integrate-react.md) | | Solid 1.8+ (SolidStart too) | `@deadhop/solid` | [Solid](./integrate-solid.md) | | Svelte 5 (SvelteKit too) | `@deadhop/svelte` | [Svelte 5](./integrate-svelte5.md) | | Svelte 4, or Svelte 5 in legacy mode | `@deadhop/svelte/svelte4` | [Svelte 4](./integrate-svelte4.md) | | Any other framework, or none | `@deadhop/client` | [Plain JavaScript](./integrate-javascript.md) | | A server (Node, Deno, Bun) | `@deadhop/client` | [Backend](./integrate-backend.md) | Props every component takes: | Prop | Type | Meaning | | --- | --- | --- | | `client` | `Deadhop` | From `createDeadhop`; required | | `pollMs` | `number` | How often to check for news (default 5000) | | `labels` | `Partial` | Replace any text, for example for another language | | `class` (React: `className`) | `string` | Extra class on the outer element | | `copy` | `(text) => Promise` | Copies the address (default: the browser clipboard) | | `onCreated(invoice)` | function | An invoice exists | | `onDetected(invoice)` | function | The full amount was seen, not yet confirmed | | `onPaid(invoice)` | function | The full amount is confirmed (verify on your backend) | | `onError(error)` | function | An `ApiError` with a `code` such as `unauthorized`, `rate_limited`, `timeout` | `PayButton` also takes `amount`, `memo`, `expirySecs` and its label (`children` in React and Solid, `label` in Svelte). `InvoiceForm` takes `defaultAmount`, `defaultMemo`, `showMemo` and `expirySecs`. `Invoice` takes `id`. ## Faster proof of work (notemine) The built-in miner hashes on the page's main thread, and gives up after 25 seconds. Mining time varies a lot from one invoice to the next, so at the default 20 bits a slow phone will sometimes run out of time. [notemine](https://github.com/sandwichfarm/notemine) mines in WebAssembly across several Web Workers. In headless Chrome on a 16-core machine, 20 bits took 0.4 s on average with notemine and 5.3 s with the built-in miner. ```sh npm install @notemine/wrapper @notemine/core rxjs ``` ```ts import { createDeadhop } from '@deadhop/client'; import { notemineMiner } from '@deadhop/client/notemine'; export const deadhop = createDeadhop({ serverPubkey: 'npub1…', relays: ['wss://relay.example.com'], miner: notemineMiner(), // pass to every component as usual }); ``` - npm only: `@deadhop/client/notemine` is not on JSR. - `@notemine/wrapper` is an optional peer dependency: install it only if you use this. `@notemine/core` and `rxjs` are its own peer dependencies. npm installs them by itself, some other package managers don't. Without them, the built-in miner quietly takes over. Its code (about 500 KB) is a separate chunk that loads when the first invoice needs work, not with the page. - A page with a Content-Security-Policy must allow notemine's worker and WebAssembly: `worker-src blob:` and `script-src 'self' 'wasm-unsafe-eval'`. - Where notemine cannot run (a stricter policy, no Web Workers, server-side), the built-in miner takes over. Pass `notemineMiner({ fallback: false })` to fail instead. `workers` sets how many Web Workers it uses (default: one less than the device's cores, at most 8). - Whichever miner runs, the client checks the result before it signs anything: the same request, a `nonce` tag and enough leading zero bits. A broken miner can't make the client send something the service would refuse. - `@notemine/wrapper` is MIT, but it includes notemine's WebAssembly core, and `@notemine/core` is GPL-3.0. Check that this suits your app before you ship it. To use a different miner, pass any function of type `Miner` (exported from `@deadhop/client`). ## Styling and page security - `styles.css` (`@deadhop/react/styles.css`, `@deadhop/solid/styles.css` or `@deadhop/svelte/styles.css`; the same file in each) is optional. It uses only `deadhop-` classes and custom properties (`--deadhop-accent`, `--deadhop-radius`, `--deadhop-qr-size`, …) that you can override. Without it, the components are unstyled semantic HTML. The defaults inherit your page's font and text colour and use a graphite button; if your page sets `color-scheme: dark`, the button turns light on its own (browsers with `light-dark()`). To match your shop instead, set for example `.deadhop { --deadhop-accent: #your-colour; }`. - No inline styles or injected scripts: the components run under a strict Content-Security-Policy. Your page needs `connect-src` to allow `wss:` (the relays), and `img-src data:` only if you add images of your own that need it. With notemine, also `worker-src blob:` and `'wasm-unsafe-eval'` (see above). - The QR code is an SVG drawn from the invoice's `bitcoin:` URI. The client checks that the URI pays exactly the address and amount shown. - The memo is written by whoever created the invoice. The components show it as plain text under *Note from the invoice creator*. - Importing a component never touches `window` or opens a connection. Nothing happens until it mounts, so server-side rendering works (tested for every framework). ## Installing ```sh npm install @deadhop/client @deadhop/react # or @deadhop/solid, @deadhop/svelte; plus your framework npx jsr add @deadhop/client @deadhop/react # JSR: the client, React and Solid deno add jsr:@deadhop/client ``` `@deadhop/svelte` is only on npm: JSR can't host `.svelte` files. Every framework package re-exports `createDeadhop`, so the client needs no separate import. ## Checklist for agents and developers 1. Get the service's `serverPubkey` and a relay it listens on. 2. Decide who creates invoices. In the browser: turn on public invoicing. On your backend: give it an operator key that stays on the server. 3. `createDeadhop({ serverPubkey, relays })` once, and pass it as `client`. 4. Render `PayButton`, `InvoiceForm` or `Invoice` from the subpath for your framework. 5. Allow `wss:` in `connect-src` if your page has a Content-Security-Policy. Optionally, for faster proof of work on phones, use `notemineMiner()`. With a Content-Security-Policy, that also needs `worker-src blob:` and `'wasm-unsafe-eval'`. 6. Fulfil an order only after your backend's `getInvoice(id)` returns `confirmed` for the right amount. ## How it is tested - **Unit tests:** `@deadhop/client` and every framework's components, at 100% coverage. - **Svelte 4:** the components also run on the real Svelte 4 runtime. - **Server-side rendering:** every framework renders to a string. - **Real stack:** on regtest, the built client and each framework's `PayButton` (in headless Chrome, under a strict CSP) pay real invoices through a real relay and service. So does a page using notemine, once with a policy that allows it and once with the strict policy, where the built-in miner takes over. - **Packaging:** `just packages` packs all four packages, installs them into fresh React, Solid, Svelte 5 and Svelte 4 projects, and builds and type-checks each one. It also checks tree shaking (notemine stays out of apps that don't use it, and loads lazily in apps that do), then runs publint, Are the Types Wrong and a JSR dry run. --- Source: https://deadhop.run/docs/integrate-react.html # React > Add deadhop pay buttons, invoice forms and invoices to a React 18 or 19 app (Next.js App Router too), or build your own UI with the useCheckout hook. React 18 and 19 are supported (tested with 19). Read [Integrate payments into your app](./integrate.md) first: it explains the service values, who creates invoices, and why `onPaid` is not proof of payment. ## Install ```sh npm install @deadhop/client @deadhop/react react react-dom ``` ## Create the client once ```ts // src/deadhop.ts import { createDeadhop } from '@deadhop/react'; // same as '@deadhop/client' export const deadhop = createDeadhop({ serverPubkey: 'npub1…', // the service's public key relays: ['wss://relay.example.com'], // a relay the service listens on }); ``` `createDeadhop` connects on first use and keeps one connection. Create it at module level, not inside a component, so every render and component shares it. ## A pay button ```tsx import { PayButton } from '@deadhop/react'; import '@deadhop/react/styles.css'; import { deadhop } from './deadhop'; export function Tip() { return ( console.log('paid', inv.id)}> Tip 5,000 sats ); } ``` The button text is `children`; without it the button reads *Pay 5,000 sats*. Needs [public invoicing](./integrate.md#_1-the-browser-creates-them-public-invoicing) on the service. ## An invoice form ```tsx import { InvoiceForm } from '@deadhop/react'; saveOrder(inv.id)} /> ``` ## An invoice your backend created ```tsx import { Invoice } from '@deadhop/react'; export function Checkout({ invoiceId }: { invoiceId: string }) { return router.refresh()} />; } ``` Your server creates the invoice with an operator key (see [Backend](./integrate-backend.md)) and sends the page its id. The page only watches it, so public invoicing can stay off. ## Your own markup: `useCheckout` ```tsx import { useCheckout, InvoiceCard } from '@deadhop/react'; import { LABELS } from '@deadhop/client'; export function Buy() { const [state, checkout] = useCheckout(deadhop, { onPaid: (inv) => console.log(inv.id) }); if (state.phase === 'idle') { return ; } return ; } ``` `state.phase` is one of `idle`, `creating`, `loading`, `pending`, `detected`, `confirmed`, `expired` or `error`. `InvoiceCard` draws any state; replace it with your own markup if you like, using `invoiceView(state.invoice, state.now)` from `@deadhop/client` for the labels and the QR path. Event callbacks always see the latest props. ## Next.js and server rendering - The built files start with `'use client'`, so you can import the components straight into App Router pages. - Importing a component never touches `window` or opens a connection; it renders to HTML on the server and connects only after it mounts. - Create invoices on the server with `@deadhop/client` in a route handler or server action, never with an operator key in client code (see [Backend](./integrate-backend.md)). ## Language and styling - `labels` replaces any text, for example for another language: ```tsx `${sats} sats zahlen`, copy: 'Adresse kopieren' }} /> ``` - `className` adds a class to the outer element. The stylesheet is optional; see [Styling and page security](./integrate.md#styling-and-page-security). - For faster proof of work on phones, pass `miner: notemineMiner()` to `createDeadhop` (see [Faster proof of work](./integrate.md#faster-proof-of-work-notemine)). --- Source: https://deadhop.run/docs/integrate-solid.html # Solid > Add deadhop pay buttons, invoice forms and invoices to a Solid 1.8+ app (SolidStart too), or build your own UI with the useCheckout primitive. Solid 1.8 and later 1.x are supported (tested with 1.9); Solid 2 is not supported yet. Read [Integrate payments into your app](./integrate.md) first: it explains the service values, who creates invoices, and why `onPaid` is not proof of payment. ## Install ```sh npm install @deadhop/client @deadhop/solid solid-js ``` ## Create the client once ```ts // src/deadhop.ts import { createDeadhop } from '@deadhop/solid'; // same as '@deadhop/client' export const deadhop = createDeadhop({ serverPubkey: 'npub1…', relays: ['wss://relay.example.com'], }); ``` ## A pay button ```tsx import { PayButton } from '@deadhop/solid' import '@deadhop/solid/styles.css'; import { deadhop } from './deadhop'; export const Tip = () => ( console.log('paid', inv.id)}> Tip 5,000 sats ); ``` The button text is `children`; without it the button reads *Pay 5,000 sats*. Needs [public invoicing](./integrate.md#_1-the-browser-creates-them-public-invoicing) on the service. ## An invoice form ```tsx import { InvoiceForm } from '@deadhop/solid'; export const Shop = () => ; ``` ## An invoice your backend created ```tsx import { Invoice } from '@deadhop/solid'; export const Checkout = (props: { invoiceId: string }) => ; ``` See [Backend](./integrate-backend.md) for creating the invoice on your server. ## Your own markup: `useCheckout` ```tsx import { Show } from 'solid-js'; import { useCheckout, InvoiceCard } from '@deadhop/solid'; import { LABELS } from '@deadhop/client'; export function Buy() { const [state, checkout] = useCheckout(deadhop, { onPaid: (inv) => console.log(inv.id) }); return ( checkout.create({ amount_sat: 5000 })}>Buy}> ); } ``` `state` is an accessor. The checkout stops polling when the owning component is disposed. To keep callbacks current, pass the component's `props` object (or getters) as the options. ## SolidStart and server rendering The package ships a compiled build and, under the `solid` export condition, JSX that SolidStart and other SSR setups compile themselves. Rendering on the server never opens a connection. ## Language and styling `labels` replaces any text, `class` adds a class to the outer element, and the stylesheet is optional; see [Styling and page security](./integrate.md#styling-and-page-security). For faster proof of work on phones, see [Faster proof of work](./integrate.md#faster-proof-of-work-notemine). --- Source: https://deadhop.run/docs/integrate-svelte5.html # Svelte 5 > Add deadhop pay buttons, invoice forms and invoices to a Svelte 5 or SvelteKit app, or build your own UI with useCheckout. These components use runes and need Svelte 5. For Svelte 4, or Svelte 5 in legacy mode, use [Svelte 4](./integrate-svelte4.md). Read [Integrate payments into your app](./integrate.md) first: it explains the service values, who creates invoices, and why `onPaid` is not proof of payment. ## Install ```sh npm install @deadhop/client @deadhop/svelte svelte ``` npm only: JSR can't host `.svelte` files. ## Create the client once ```ts // src/lib/deadhop.ts import { createDeadhop } from '@deadhop/svelte'; // same as '@deadhop/client' export const deadhop = createDeadhop({ serverPubkey: 'npub1…', relays: ['wss://relay.example.com'], }); ``` ## A pay button ```svelte console.log('paid', inv.id)} /> ``` Events are callback props (`onPaid`), as usual in Svelte 5. Needs [public invoicing](./integrate.md#_1-the-browser-creates-them-public-invoicing) on the service. ## An invoice form ```svelte ``` ## An invoice your backend created ```svelte invalidateAll()} /> ``` Create the invoice in `+page.server.ts` with an operator key; see [Backend](./integrate-backend.md). ## Your own markup: `useCheckout` ```svelte {#if buy.state.phase === 'idle'} {:else} {/if} ``` `buy.state` is reactive. Call `useCheckout` during component setup (or inside `$effect.root`); the checkout stops when the component is destroyed. `events` is a getter, so callbacks that depend on props stay current. ## SvelteKit and server rendering Importing a component never touches `window` or opens a connection: pages render on the server and connect only in the browser. ## Language and styling `labels` replaces any text, `class` adds a class to the outer element, and the stylesheet is optional; see [Styling and page security](./integrate.md#styling-and-page-security). For faster proof of work on phones, see [Faster proof of work](./integrate.md#faster-proof-of-work-notemine). --- Source: https://deadhop.run/docs/integrate-svelte4.html # Svelte 4 > Add deadhop pay buttons, invoice forms and invoices to a Svelte 4 app (or Svelte 5 in legacy mode), or build your own UI with the checkout store. These components use Svelte 4 syntax, so they also run under Svelte 5 in legacy mode. They are tested on the real Svelte 4 runtime. Read [Integrate payments into your app](./integrate.md) first: it explains the service values, who creates invoices, and why `onPaid` is not proof of payment. ## Install ```sh npm install @deadhop/client @deadhop/svelte svelte@4 ``` npm only: JSR can't host `.svelte` files. ## Create the client once ```js // src/lib/deadhop.js import { createDeadhop } from '@deadhop/svelte/svelte4'; // same as '@deadhop/client' export const deadhop = createDeadhop({ serverPubkey: 'npub1…', relays: ['wss://relay.example.com'], }); ``` ## A pay button ```svelte console.log('paid', inv.id)} /> ``` Events are callback props (`onPaid`, `onDetected`, …), not `on:` events. Needs [public invoicing](./integrate.md#_1-the-browser-creates-them-public-invoicing) on the service. ## An invoice form ```svelte ``` ## An invoice your backend created ```svelte ``` See [Backend](./integrate-backend.md) for creating the invoice on your server. ## Your own markup: the checkout store ```svelte {#if $checkout.phase === 'idle'} {:else} {/if} ``` A checkout follows the Svelte store contract, so `$checkout` works directly. Destroy it when the component goes away to stop polling. ## TypeScript The package ships types for every component. In `