laantungir/amethyst
1
0
Fork 0
mirror of https://github.com/vitorpamplona/amethyst.git synced 2026-10-06 19:53:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(cli): document graperank operator keys + publish reconciliation

Browse Source 
README + amy usage: add the `graperank operator [status|relay|providers]`
sub-verb, update the `graperank --publish` description to the per-observer
service-key model (sign with a derived key, publish to the operator relay,
reconcile new/changed/skip/retract, cutoff rank>=2, NIP-09-drop retracted
reports), and add a 'Publishing GrapeRank scores' section explaining the
operator master, deterministic per-observer key derivation, and the kind:10040
discovery wiring.
This commit is contained in:
Claude
2026-07-07 14:39:32 +00:00
parent 840f8f3153
commit be6ff5456d
2 changed files with 41 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cli/README.md
+32 -1
View File
@@ -384,10 +384,41 @@ HTTP endpoint. Reuses quartz's `Nip86Client` and the shared `Nip86Retriever`
| `amy profile show [USER]` | Print kind:0 metadata. USER accepts npub/nprofile/hex/NIP-05; defaults to self. |
| `amy profile edit --name … --about … --picture URL …` | Patch and re-publish your kind:0. |
| `amy follow USER` / `amy unfollow USER` | Add/remove USER from your kind:3 contact list (fetches the freshest list first). |
| `amy graperank [OBSERVER] [--offline] [--publish]` | Compute GrapeRank web-of-trust scores (0..1) over the follow/mute/report graph. Exhaustively crawls each user's kind:10002 outbox for their latest kind:3/10000/1984 until every discovered user is checked (no user cap); optionally publishes results as NIP-85 kind:30382 cards (unchanged ranks are skipped). |
| `amy graperank [OBSERVER] [--offline] [--publish] [--min-rank N] [--publish-relay URL]` | Compute GrapeRank web-of-trust scores (0..1) over the follow/mute/report graph. Exhaustively crawls each user's kind:10002 outbox for their latest kind:3/10000/1984 until every discovered user is checked (no user cap), dropping reports the author retracted via NIP-09. With `--publish`, reconciles NIP-85 kind:30382 cards signed by a per-observer **service key**: publishes changed/new ranks (cutoff `--min-rank`, default 2), skips unchanged, and **retracts** (kind:5) any card whose target left the graph or fell below the cutoff. |
| `amy graperank operator [status \| relay <url>… \| providers]` | Manage the machine's operator keys (independent of any account, under `~/.amy/operator/`). `relay` sets where cards + retractions publish; `status` shows the master pubkey and relays; `providers` lists the observer → service-pubkey map. |
| `amy graperank register [PROVIDER] [--service KIND:TAG] [--relay URL]` | Declare a NIP-85 provider in your kind:10040 so clients can discover it (default: self as the `30382:rank` provider). |
| `amy graperank providers [USER]` | List a user's declared NIP-85 trusted providers (public + your own private entries). |
#### Publishing GrapeRank scores (NIP-85)
Ranks are published as kind:30382 cards, but **not** under your account key. A
machine holds one **operator master** seed (`~/.amy/operator/`, stored via the
same `--secret-backend` as accounts, independent of any account). From it a
distinct, deterministic **service key** is derived per observer:
```
serviceKey(observer) = sha256(masterPriv ‖ "graperank-provider:" ‖ observerHex)
```
Because kind:30382 is addressable (`pubkey + d-tag`), the stable per-observer key
means re-publishing **replaces** a target's card instead of orphaning it — and
losing everything but the master seed still re-derives every key. Set up once and
publish:
```bash
amy graperank operator relay wss://relay.example.com # where all cards live
amy graperank <observer> --publish # sign with the observer's service key
```
Each publish **reconciles** against what the service key already published: new or
changed ranks (≥ `--min-rank`, default 2) are signed and sent; unchanged ranks are
skipped (no new event id); and any card whose target dropped out of the graph or
fell below the cutoff is **retracted** with a kind:5. When the observer is your
own account (we hold the key), Amy also writes their kind:10040 pointing
`30382:rank → serviceKey @ operator relay` to their outbox, so clients can find
the cards. For a third-party observer, `graperank operator providers` prints the
`observer → service-pubkey` mapping to wire their kind:10040 out-of-band.
### Direct messages (NIP-17)
| Command | What it does |
cli/src/main/kotlin/com/vitorpamplona/amethyst/cli/Main.kt
+9 -3
View File
@@ -537,9 +537,15 @@ private fun printUsage() {
| --diagnose logs slow/failed relays on timeout).
| [--publish] [--min-rank N] OBSERVER: npub|nprofile|hex|name@domain (default:
| [--publish-limit N] [--publish-relay URL] active account). --offline scores from the local
| store only. --publish writes NIP-85 kind:30382
| cards (rank = round(score*100)) for each user at
| or above --min-rank (unchanged ranks skipped).
| store only. --publish reconciles NIP-85 kind:30382
| cards signed by a per-observer service key: sends
| new/changed ranks >= --min-rank (default 2), skips
| unchanged, and retracts (kind:5) any card whose
| target left the graph or fell below the cutoff.
| graperank operator [status|relay <url>… manage the machine's operator keys (~/.amy/operator/,
| |providers] independent of accounts): relay sets where cards +
| retractions publish; status shows master + relays;
| providers lists observer -> service-pubkey.
| graperank register [PROVIDER] declare a NIP-85 provider in your kind:10040 so
| [--service KIND:TAG] [--relay URL] clients can discover it (default: self as the
| [--private] 30382:rank provider at your first outbox relay).