Skip to content

Safebox wallet discovery

The additive GET /.well-known/safebox.json?name=alice endpoint publishes a version-1 wallet directory entry for a claimed handle. It identifies the Acorn key, public wallet relay hints and enabled cash/Clear receipt capabilities. The response contains no private keys, balances or recovery data. There is no recipient login requirement. Publishing the wallet directory itself needs no database migration; the optional social-npub preference has its own nullable-column migration.

NIP-05 at /.well-known/nostr.json keeps its existing default mapping and Clear extensions when no social npub is chosen. A social override publishes only the social key. Cash and Clear payment readers now prefer safebox.json. Wallet messaging and sender attribution also use this directory. Social NIP-05 lookups remain unchanged. Preferences now accepts an optional social npub, separately from the Acorn binding.

Which lookup serves which purpose?

NIP-05 identifies a social identity. Safebox discovery identifies the Acorn for wallet operations. Record transfer descriptors carry their own transfer information.

Purpose Resolution Meaning
Social identity /.well-known/nostr.json?name=handle Chosen social key; defaults to the Acorn public key when no social preference is set
Direct cash payment /.well-known/safebox.json?name=handle with acorn-ecash-transfer Acorn destination key and wallet relay hints
Clear payment The same wallet directory with clear-token-transfer and a compatible unit Acorn destination, subject to the existing Clear routing restrictions
Ordinary Lightning payment /.well-known/lnurlp/handle and its invoice callback Lightning invoice; no social-key resolution is needed
Wallet message addressed by name Wallet directory with safebox-wallet-message Acorn key and message relays; sender-address claims are checked against the wallet directory too
Current record sharing or presentation Acorn-generated transfer descriptor, carried in a QR code or link Transfer-specific retrieval information; no recipient-address directory lookup

Safebox Web implements wallet-message delivery and attribution. OakGate does not yet have a messaging interface and does not advertise that capability. Explicit npub/public-key message destinations retain their meaning. Local wallet recipients resolve from the instance's Acorn registration, preserving private community relay routes without consulting social NIP-05.

Cash routing and fallback

The migrated application readers look for the explicit acorn-ecash-transfer capability in safebox.json. They do not use the older LNURL safebox=true flag to select this direct-transfer path. The older Acorn transport associated with that flag is a separate legacy flow, not this version-1 directory contract.

If the directory advertises a usable direct route and local routing policy permits it, cash is delivered as ecash through Acorn. When no usable direct route is advertised, an ordinary cash payment may use LNURL and Lightning instead. An ordinary external Lightning address does not need Safebox or NIP-05 support. Clear payments, continuity-only transfers and wallet messages do not fall back to Lightning.

A 404 or missing cash capability may permit ordinary Lightning for cash. NIP-05 is never a wallet fallback, including for previously configured legacy domains. Clear and wallet messages require their advertised wallet capability. Malformed data, unsupported versions, timeouts and non-404 HTTP errors stop preparation rather than silently switching to Lightning or a social key. Once a send has begun, an uncertain outcome never triggers an automatic second payment by another route.

Record sharing is not address discovery

Reading one's own records uses the connected Acorn. Current sharing and presentation create an Acorn transfer descriptor and display its QR code or link; the recipient imports or presents that descriptor through the corresponding Acorn methods. These flows do not look up a social address or call safebox.json to choose a recipient. OpenETR checks and record-signature verification are separate from wallet address resolution.

Future record delivery addressed to handle@domain should resolve the wallet through safebox.json, with an explicitly defined supported delivery capability. It must not infer record-delivery support from a cash capability or use the social npub as the Acorn destination. This is a design rule, not an implemented address-based record delivery feature.

Set SAFEBOX_NIP05_EXTERNAL_RELAYS to the publicly reachable wallet relays for dual publication. The new endpoint intentionally returns 404 when none are configured; it never substitutes the internal home relay. Clear advertising follows SAFEBOX_CLEAR_RECEIVE_ENABLED and SAFEBOX_CLEAR_UNITS. The directory introduces no mint allowlist. Wallet messaging advertises safebox-wallet-message (nip17, kind 14).

Responses use public CORS, no-store and nosniff headers. Missing, duplicate or invalid name parameters return 400; absent/unadvertised handles return 404; invalid configuration or unavailable directory dependencies return 503. Errors contain a stable code rather than private implementation details.

First publish the Acorn commit containing acorn.safebox_discovery, then run poetry update safebox-acorn, review/commit the lockfile and test the installed revision before deploying. The payment reader requires this published Acorn API; deploy the committed lockfile rather than an older Acorn installation. Do not claim discovery readiness until a real handle resolves successfully.

Verify both endpoint responses for the same handle. Keep NIP-05 mapping to the existing Acorn key until all supported legacy clients have migrated. The older safebox.json/<name> transport is not reintroduced.

Payment compatibility policy

Legacy NIP-05 wallet fallback has been retired. SAFEBOX_LEGACY_DOMAINS is ignored, including values left in existing deployments. A 404 or absent cash capability can use ordinary Lightning for cash; Clear, continuity transfers and wallet messages require wallet discovery. Malformed directories, unknown versions, network failures, redirects and other HTTP errors stop preparation.

Lightning fallback obtains and validates an LNURL invoice and calls Acorn's pay_multi_invoice only. It does not call pay_multi, follow safebox=true, or enter the older safebox.json/<name> transport. Invoice requests omit unsupported comments and the legacy safebox query parameter. Public HTTPS requests validate DNS, pin the connection, reject redirects and bound response size; the invoice must match the requested amount, Bitcoin network and expiry requirements.

Local recipients use the instance's wallet registration directly, preserving private relay support. Clear scope restrictions and Acorn's mint acceptance policy are unchanged. External wallet discovery uses Acorn's bounded resolver.

See the family contract and migration plan.

Wallet messages

Wallet-address delivery and claimed-sender verification use the messaging capability, independently of social NIP-05, with no legacy fallback. Missing capability, a 404, malformed discovery or network failure never becomes a social DM. Explicit npub/public-key destinations retain their meaning. Local messages use the registered wallet and home relay.

See private messaging for verification limits, compatibility and deployment details. OakGate does not yet have a messaging interface and continues to omit this capability.

Social npub preference

Claim a handle, then set its public social npub in Preferences. No proof-of-control step is required; Nostr clients compare the signed profile's nip05 value with this directory. Clearing the field restores the Acorn-based default. Public social preferences persist with the handle; browser display settings remain in cookies. Wallet discovery and messaging never substitute the social key. See the handle directory guide for the database migration, backups and legacy-client limitations.