Community infrastructure · October 25, 2026
Host your own Handshake SPV helper
Yes, you can host an independent replacement for the old HandshakeAPI helper. You need your own server and hostname; you do not need control of the former operator’s domain.
What are you hosting?
Bob LearnHNS → HTTPS /hsd → restricted gateway → private indexed HSD The wallet runs locally. The server supplies indexed chain and name information that its SPV mode needs. The backend must be a fully synced, non-pruned mainnet HSD full node with both transaction and address indexes enabled from the beginning.
This is separate from a DNS resolver, an hnsd lightweight resolver, a peer-discovery seed, or the ShakeScape Rust rendezvous relay. None of those alone replaces this API.
The helper does not need wallet seeds, private keys, or signing authority. It can observe addresses and names requested through it, so choose an operator you trust with that metadata. The current LearnHNS gateway also accepts a narrowly limited relay of already-signed transactions for Shake Wallet; this does not grant wallet access.
1. Plan the server and its responsibilities
Use a Linux server with Docker Engine and Compose v2, a stable hostname, reliable outbound networking, and persistent SSD storage. Plan capacity for the full chain plus both indexes and future growth. Measure current disk use and sync performance before choosing a plan; a fixed storage figure or a guaranteed monthly price would quickly become misleading.
- Keep enough RAM and CPU for initial sync and historical address queries; benchmark your intended load before opening the service to everyone.
- Budget for storage, bandwidth, monitoring, patching, and recovery—not only a running container.
- Use a fresh dedicated database. Adding flags to an existing unindexed database is not proof that historical indexes are complete.
- If your only goal is to avoid a third-party helper for your own wallet, consider Bob’s full-node mode instead of operating a public API.
2. Obtain and review the software
Start with HSD’s public source and the Bob SPV Helper API v1 contract. A reverse proxy that exposes unrestricted HSD RPC is not a compatible security boundary.
Clone the public starter, review its README and pinned HSD revision, then enter the self-host directory. The remaining setup commands run from there.
git clone https://github.com/shadstoneofficial/handshake-spv-helper.git
cd handshake-spv-helper/deploy/self-host If implementing your own gateway, preserve the contract’s JSON envelopes, integer dollary amounts, block/transaction/coin lookups, address-history response shape, and name-state semantics. Compare the public v1 documentation with the current implementation before claiming support for newer header, name-resource, or signed-transaction-relay extensions.
3. Configure a private indexed node
The reference starter creates three services: HSD, the gateway, and Caddy for HTTPS. HSD data persists in a Docker volume. Its node flags include:
--network=main
--index-tx=true
--index-address=true
--spv=false
--prune=false
--no-wallet Generate two different secrets on your own server:
umask 077
cp .env.example .env
openssl rand -hex 32
openssl rand -hex 32 Edit .env: set HELPER_HOST to your hostname (for example spv.example.com), and use the generated values for HSD_API_KEY and METRICS_TOKEN. Never share this file or credential-bearing container inspection output.
The gateway’s private upstream is http://hsd:12037. Only the gateway receives the HSD credential. Clients receive the HTTPS helper URL, never that key.
4. Add DNS and HTTPS, then synchronize
Point an A record at your server. Add AAAA only if the server’s IPv6 path works. Allow inbound TCP 80 and 443 for Caddy and certificate issuance. Restrict SSH to your management network. Do not publish HSD RPC port 12037, wallet RPC port 12039, or the gateway’s port 3000.
docker compose config --quiet
docker compose up -d --build
docker compose logs --tail=100 hsd The starter uses outbound HSD peer connections. Caddy is the direct internet-facing proxy and sanitizes forwarded client headers. Adding a CDN or another proxy requires reviewing trusted-IP handling; otherwise rate limits may be bypassed or all users may share one limit.
Wait for chain synchronization and index readiness. This can take substantial time; container startup is not completion. A 503 readiness response during synchronization is expected. Never run docker compose down -v unless you intentionally want to delete the persistent data.
5. Verify compatibility before sharing
curl -fsS https://spv.example.com/healthz
curl -fsS https://spv.example.com/hsd Require all readiness checks to pass and compare chain height with an independent synced node. The progress estimate alone cannot prove that you are at the current network tip.
From the reference repository root, with Node.js 20 or newer:
HELPER_URL=https://spv.example.com/hsd npm run audit:provider The default audit is a useful smoke test, not full certification. Opt into address-history checks with AUDIT_ADDRESS using a dedicated test address with known history. Use AUDIT_REGISTER_NAME for a known unregistered CLOSED auction. Check every required REST route and RPC method, and confirm that wallet, mining, and administrative calls are rejected.
Test with a small dedicated Bob wallet: synchronization, historical transactions, name state, and the workflows you intend to support. Keep amounts in integer dollary on the wire. In particular, a REGISTER’s auction value must come from info.value, not the highest bid.
6. Point Bob LearnHNS at your helper
Open Settings → Network & Connection → SPV Helper API in Bob LearnHNS. Enter https://spv.example.com/hsd, confirm the Active Helper, and wait for synchronization. Original Bob 2.1.0 does not have a custom-helper setting. See the migration announcement for the supported upgrade path.
Other people can choose your compatible endpoint too. A new hostname does not automatically redirect old installed wallets or transfer management of the old service.
7. Keep it useful after launch
- Monitor chain lag, disk headroom, peers, request latency, timeouts, and recent error rates.
- Keep rate limits, bounded request sizes, and upstream timeouts. The reference limits are per process; multiple replicas need a shared abuse boundary.
- Keep metrics authenticated and avoid access logs containing addresses, names, hashes, RPC parameters, or transaction bodies—including at the proxy.
- Maintain TLS renewal, security updates, a tested restore procedure, and a contact for outages. Preserve a working revision for rollback.
Different operators, hosts, and regions reduce dependence on one service. Publish your compatibility checks and limitations so users can make an informed choice.