@handlepay/resolve 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,80 @@
1
- # Temporary Holding Version
1
+ # @handlepay/resolve
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Turn a name like `sani@lycanforge.com.ng` into the Bitcoin Cash address it has **proven** it
4
+ controls, or into the reason it hasn't.
5
+
6
+ This is the verification code behind [HandlePay](https://handlepay.lycanforge.com.ng),
7
+ packaged so any wallet, shop or app can pay people by name. There's no HandlePay server in
8
+ the loop: it reads the name's domain, public Nostr relays, and the BCH chain directly.
9
+
10
+ ```bash
11
+ npm install @handlepay/resolve
12
+ ```
13
+
14
+ ## Use it
15
+
16
+ ```ts
17
+ import { resolve } from "@handlepay/resolve";
18
+
19
+ const r = await resolve("sani@lycanforge.com.ng", { network: "mainnet" });
20
+
21
+ switch (r.status) {
22
+ case "verified": // every check passed: safe to pay r.address
23
+ console.log("Pay", r.address);
24
+ break;
25
+ case "claimed": // signed claim, but control of the address isn't proven
26
+ case "changed": // verified, but different from what you pinned last time
27
+ console.log("Ask the user first:", r.reason, r.address);
28
+ break;
29
+ case "not_found": // no such name, no binding, or revoked
30
+ console.log("Can't pay:", r.reason);
31
+ }
32
+ ```
33
+
34
+ `r.checks` lists every check in order with `ok`, a plain-language `label`, and a `detail`
35
+ explaining any failure. It's ready to show to users as "how we checked".
36
+
37
+ Works in browsers and in Node 22 or later, which has built-in `fetch` and `WebSocket`.
38
+ In a browser, some domains block cross-origin NIP-05 requests; pass a proxy through
39
+ `fetchNip05`, or set `VITE_NIP05_PROXY` in a Vite app.
40
+
41
+ ## What "verified" means
42
+
43
+ Three facts that point at each other:
44
+
45
+ 1. `https://domain/.well-known/nostr.json` lists the name's Nostr key (NIP-05).
46
+ 2. That key signed a binding event naming the BCH address and a proof transaction.
47
+ 3. The proof transaction was **spent from that address**, and its `OP_RETURN` names the same
48
+ Nostr key. It has at least 1 confirmation.
49
+
50
+ Someone who copies your address into their own profile can't make fact 3, so their claim
51
+ stays `claimed`. The proof and its parent transactions are re-hashed from raw bytes, so a
52
+ chain server can withhold data but can't fake it. Full protocol:
53
+ [HPAY-BIND v1](https://github.com/Lycan-Xx/handlepay/blob/main/docs/SPEC.md). Threat model:
54
+ [THREAT-MODEL.md](https://github.com/Lycan-Xx/handlepay/blob/main/docs/THREAT-MODEL.md).
55
+
56
+ ## Remember what you saw (trust on first use)
57
+
58
+ ```ts
59
+ const pinned = loadFromYourStorage(name); // { pubkey, address } | null
60
+ const r = await resolve(name, { network: "mainnet", pinned });
61
+ if (r.status === "verified") saveToYourStorage(name, { pubkey: r.pubkey!, address: r.address! });
62
+ if (r.status === "changed") warnUser(r.previous, r.address);
63
+ ```
64
+
65
+ ## Other exports
66
+
67
+ | Export | What it does |
68
+ |---|---|
69
+ | `resolveHandle(name, network, deps, pinned?)` | The same as `resolve`, with every network lookup injectable, for tests or your own servers |
70
+ | `liveDeps(network)` | The default lookups: NIP-05, relays, and Fulcrum (via CashScript) |
71
+ | `paymentGate(result)` | `"allowed"`, `"confirm_unverified"`, `"acknowledge_change"` or `"blocked"` |
72
+ | `checkProof(input)` | The four BCH checks on a proof transaction, from raw bytes |
73
+ | `parseBindingEvent`, `buildBindingEvent`, `buildRevokeEvent`, `buildPaytoEvent` | Read and write the Nostr events |
74
+ | `proofOpReturnChunks`, `parseProofOutput` | Write and read the `OP_RETURN "HPAY" 01 <pubkey>` proof output |
75
+ | `createChallenge`, `buildAuthTemplate`, `verifyAuthEvent` | Sign-in with a name (challenge–response, kind 22242) |
76
+ | `parseHandle`, `fetchNip05`, `queryIdentityEvents` | The lower-level lookups |
77
+
78
+ ## License
79
+
80
+ MIT