lumi-check 0.0.0-stage → 0.1.0

package/FUNDING_XRPL.md

@@ -0,0 +1,59 @@
+# Funding a small XRPL test wallet
+
+Use a dedicated wallet, never your main one. Values were checked on 2026-10-23 against xrpl.org
+(<https://xrpl.org/docs/concepts/accounts/reserves>). Reserves are set by validator vote and can change, so look up the
+live values with the `server_state` or `fee` API before you rely on them.
+
+## 1. Reserves (Mainnet)
+
+| Item | XRP locked |
+|---|---|
+| Base reserve per account | 1 XRP |
+| Owner reserve per ledger object (each trust line, offer, ...) | 0.2 XRP |
+
+These are the values in force since the December 2024 fee vote, which lowered them from 10 and 2 XRP.
+
+Reserved XRP cannot be sent, but it can pay transaction fees. An account with one RLUSD trust line needs
+**1.2 XRP** locked.
+
+**Suggested funding:** about **2 XRP** for a test wallet. That is 1.2 XRP of reserve plus about 0.8 XRP of headroom
+for fees (about 0.00001 XRP each) and XRP-priced buys. Add a small amount of RLUSD (for example 0.10 RLUSD) for
+RLUSD-priced buys.
+
+## 2. Create and activate
+
+1. Generate a wallet offline (for example with `xrpl.js` `Wallet.generate()`) and store the seed in a file with mode 600.
+   Never paste it into chats, logs or the kit's command line.
+2. Send at least 1 XRP (2 XRP suggested) to the new address from an exchange or another wallet. The account exists
+   once that payment validates. Note which wallet funded it: Lumi counts **funding sources**, so wallets funded from the
+   same source count as one for per-endpoint caps and for confirming negative findings.
+
+## 3. RLUSD trust line
+
+RLUSD (Ripple USD) on XRPL Mainnet:
+
+- issuer `rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De`
+- currency code `RLUSD` (hex `524C555344000000000000000000000000000000`)
+
+Submit a `TrustSet`:
+
+```json
+{
+  "TransactionType": "TrustSet",
+  "Account": "<your test wallet>",
+  "LimitAmount": { "currency": "524C555344000000000000000000000000000000", "issuer": "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De", "value": "10" }
+}
+```
+
+A low limit (here 10 RLUSD) is a safety cap on what the wallet can hold. The trust line adds 0.2 XRP to the reserve.
+Then buy or receive a little RLUSD.
+
+## 4. Register with Lumi
+
+Give Lumi the wallet **address** (never the seed) when your contributor key is issued. Set
+`LUMI_KIT_XRPL_SEED_FILE=/path/to/wallet.json` for `lumi-scan report` or `lumi-scan buy --live`.
+
+## 5. Getting the reserve back
+
+Deleting an account (`AccountDelete`) returns the base reserve minus the deletion fee (currently 0.2 XRP). You must
+remove trust lines first, which needs a zero RLUSD balance.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,14 @@
+Lumi Check
+Copyright 2026 Lumi Trades
+
+This product (the Lumi Check client code in this directory) is licensed under the Apache License,
+Version 2.0. See LICENSE.
+
+Scope. The license covers only the client source code distributed in this package. It does NOT grant any
+rights in, and does not license:
+  - Lumi's pooled dataset of submissions, observations and test results;
+  - Lumi's scoring, selection, anti-fraud logic and verification server;
+  - contributor keys issued by Lumi (they are revocable credentials, not property);
+  - the names "Lumi", "Lumi Trades" and "Tested by Lumi", and Lumi's badges and logos.
+Use of Lumi's API and contributor program is governed by Lumi's terms (TERMS.md, DRAFT), not by this license.
+Apache-2.0 section 6 (Trademarks) applies: no permission is granted to use Lumi's trade names or marks.

package/README.md

@@ -1,3 +1,177 @@
-# Temporary Holding Version
+# Lumi Check
 
-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.
+`npm install lumi-check` (Node >= 20). CLI: `npx lumi-check` or, once installed, `lumi-scan`.
+
+A thin client for checking an x402 seller **before you pay** and, if you choose, contributing **signed,
+on-ledger-verifiable delivery receipts** to Lumi ("Tested by Lumi"). Scoring, verification, the catalog and anti-fraud
+stay on Lumi's server.
+
+> **License scope.** This client code is open source under **Apache-2.0** (see `LICENSE`; it was chosen for the
+> patent grant). The license covers **only the code in this package**. It does **not** cover Lumi's pooled dataset,
+> scoring, verification server, contributor keys, the "Tested by Lumi" name or badges. Those stay Lumi's and are not
+> licensed. See `NOTICE` and `TERMS.md`.
+
+## Pre-pay trust check
+
+Free. Returns `allow`, `warn` or `block` with reasons, the seller's current Lumi score and a link to the live report.
+Every verdict is **signed by Lumi** (ed25519) and verified locally before it is used. Only the URL's origin + path is
+sent (query strings are dropped). Paying Lumi never changes any score, tier, ranking or badge.
+
+```js
+import { createLumiCheck, x402BeforePaymentHook, mcpOnPaymentRequiredHook, withOutcomeReporting } from "lumi-check";
+
+const lumi = createLumiCheck();             // fail-open, 2.5 s timeout; pin keys with { publicKeys: ["<hex>"] }
+
+// From code
+const r = await lumi.check({ url: "https://seller.example/x402/data", payTo: "0x...", amountUsd: 0.01, network: "eip155:8453" });
+// r.decision, r.reasons, r.score, r.link, r.verified
+
+// x402 client (@x402/core / @x402/fetch): abort the payment when Lumi says "block"
+client.onBeforePaymentCreation(x402BeforePaymentHook(lumi));           // { blockOnWarn: true } to be stricter
+
+// MCP client (@x402/mcp): tool payments are checked by payTo
+mcpClient.onPaymentRequired(mcpOnPaymentRequiredHook(lumi));
+
+// Optional: one tier-1 delivery outcome per paid call, only once the user has said yes (see "What is shared")
+const paidFetch = withOutcomeReporting(wrapFetchWithPayment(fetch, client), lumi);
+```
+
+CLI: `lumi-scan check https://seller.example/x402/data --pay-to 0x... --amount 0.01`.
+
+**Fail mode (defaults):** `fail_mode: "open"` with `timeout_ms: 2500`. If Lumi is slow,
+unreachable, or returns a verdict whose signature does not verify, the result is `warn` (`lumi_unreachable` /
+`lumi_unverified`) and the payment goes ahead. Set `"fail_mode": "closed"` in the config (or `failMode: "closed"`) to
+block instead. The detailed paid check (`/v1/trust/check`, x402) adds reason details and a signed `lumi_receipt`.
+
+Verify any Lumi-signed response yourself: `verifyLumiSigned(response, { publicKeys })`, keys at
+`/v1/check/keys` (or `/.well-known/lumi-keys.json`).
+
+## What is shared
+
+**Nothing is shared until you say yes.** Right after your first `lumi-scan check` has printed its result, the CLI asks
+once (Enter means yes):
+
+```text
+Shares only the seller's host, delivered yes/no and status class after paid calls. No wallet addresses, amounts, tx hashes or URL paths. Turn off any time: lumi-scan telemetry off
+Share your results to help improve Lumi's public trust list? [Y/n]
+```
+
+- Your answer is saved on your machine in `~/.lumi-scanner-kit/config.json` (`"telemetry": true|false` and
+  `"share_answered_at"`; `LUMI_KIT_CONFIG` changes the path) and the question never shows again.
+- Change it any time: `lumi-scan telemetry on` / `lumi-scan telemetry off`, env `LUMI_CHECK_TELEMETRY=on|off`, or edit
+  `"telemetry"` in the config. `lumi-scan setup` shows the full disclosure and asks again.
+- Runs where the kit cannot ask (no terminal, CI, `LUMI_NO_PROMPT=1`, the MCP server, or the library used from code)
+  never assume yes: sharing stays off and one hint on how to turn it on is printed to stderr.
+- Your answer only controls what is shared. It never changes a check, a verdict or how any score is computed.
+
+| | Default | What is sent | Reward |
+|---|---|---|---|
+| **Tier 1: delivery outcomes ("share your results")** | **OFF until you say yes** | After each paid call: seller host (or Lumi vendor id), delivered yes/no, coarse status class (`2xx`/`4xx`/`5xx`/`timeout`), and a fresh random token per report. **No** wallet address, amount, tx hash, URL path or query, payload, or stable ID. | nothing |
+| **Tier 2: signed receipts** | **OFF** (opt-in) | Full signed delivery receipts (below), including the payment's chain and transaction ID, which is **public on-chain and can be linked to your wallet**. Nothing is sent unless you turn it on. | a public badge (nothing of monetary value) |
+
+- Tier 1 on/off (any one): `lumi-scan telemetry on|off`, env `LUMI_CHECK_TELEMETRY=on|off`, or `"telemetry": true|false` in
+  `~/.lumi-scanner-kit/config.json`.
+- Tier 2 on/off: `lumi-scan sharing on|off`, `"share_receipts": true|false`, or env `LUMI_SHARE_RECEIPTS=1|0`.
+- **What a tier-2 receipt shares about the payment:** only the chain and the transaction ID (tx hash). There is no
+  amount, price, asset or wallet field in it. A transaction ID is public on its blockchain: anyone who has it can look
+  it up and link it to the wallet that paid and the amount. Lumi uses it to confirm on the public ledger that the
+  wallet that signed the receipt paid the seller. Lumi does not store the amount. It keeps the paying wallet address
+  (read from the ledger) with the submission only for the anti-gaming checks (caps, funding clusters, near-duplicates);
+  it is never published or shown by any public route, and is removed on account deletion.
+- Env always wins over the config file. `lumi-scan telemetry status` / `sharing status` show the effective setting.
+- Retention: raw data (tier-1 outcome counters, tier-2 submissions) is kept for 90 days, then deleted, and a raw day is
+  deleted only after it has been rolled up. The daily per-seller summaries (delivered, failed, status-class counts; no
+  wallet, amount, tx, query or client id) are kept long-term. Contributor accounts are kept while active (a verified
+  receipt in the last 12 months). Tier-1 outcomes are never a scoring input.
+
+### Deleting your account
+
+`lumi-scan account delete` (asks you to type your key id; `--confirm <key_id>` when not in a terminal) calls the signed
+`DELETE /v1/contrib/me`. You can also email hello@lumitrades.io and Lumi deletes it for you the same way.
+
+- Deleted at once: your key (it can never sign again), label, public key, registered wallets and the funding wallet
+  recorded for each, own domains, demand opt-in, last-activity date, your badge, and every tier-2 receipt you shared
+  (including the stored copy), except receipts Lumi has already cited in a published, dated test result.
+  Kept, with no link to you: those cited receipts, with your wallet signature, paying-wallet link, kit details and key id
+  removed (the transaction hash, seller and delivery result stay because the published result cites them; they still
+  fall under the 90-day raw retention), and the anonymous per-seller daily summaries and tier-1 counters, which never
+  had a link to you. What remains of the key is a tombstone (the random key id, status "deleted" and dates) so it cannot
+  be reused. Payments on a public blockchain cannot be deleted by anyone.
+
+## How contributing works (tier 2, opt-in)
+
+1. **Passive (default).** You already buy from x402 sellers. After a purchase, `lumi-scan report` looks the payment
+   up on-ledger, builds a `counterparty_delivery_receipt` and signs it with the **paying wallet**. You submit it,
+   signed with your **contributor key**. There is no new spend.
+2. **Optional test-buy.** `lumi-scan wanted` shows what Lumi would like tested next (chosen server-side).
+   `lumi-scan buy <url>` is a **dry run** unless you add `--live`. It is capped locally at 0.01 per buy, 0.05 per day
+   per asset and 3 buys per day by default. Hard ceilings cannot be raised: 0.05, 0.5 and 10. Live buys are XRPL-only
+   in v0.
+3. Lumi checks every receipt **on-ledger** before it counts. It rejects self-tests (your own endpoints or wallets) and
+   caps receipts per key, per endpoint and per funding source. A negative finding counts only once a second,
+   independent contributor (or a Lumi re-buy) confirms it, and sellers can dispute a finding.
+4. **What counts.** Lumi looks up who first funded each registered wallet (Base explorer, XRPL activation, Stellar
+   `create_account`) and groups wallets with the same funder into one cluster. A cluster counts at most once per seller
+   per UTC day, however many keys it uses. Receipts from a wallet funded by the seller's pay-to wallet (or the seller's
+   own funder) count for nothing, as do receipts from wallets without a wallet-control proof. A second receipt from the
+   same paying wallet to the same seller within two minutes of another is refused as a near-duplicate even with a new tx
+   hash. Zero-weight receipts are stored and shown to you with `weight: 0` and the reason, but do not count toward your
+   badge and can't confirm anyone's negative finding. Exchange and faucet wallets Lumi lists are ignored as funders.
+5. **Badge only.** Verified receipts earn a public contributor badge (`GET /v1/contrib/badge/<handle>`), optionally
+   with a count of verified contributions (one per unique seller per day; self-tests and duplicates do not count).
+   There are no credits, money, perks, rankings or rate-limit changes, and contributing never changes how any score is
+   computed.
+
+## Quick start
+
+```bash
+cd packages/scanner-kit && npm install          # Node >= 20
+node bin/lumi-scan.js check https://seller.example/x402/data   # free check; after the first one, asks once whether to share results
+node bin/lumi-scan.js setup                     # shows what is shared; choose tier 1 / tier 2
+node bin/lumi-scan.js keygen                    # writes ~/.lumi-scanner-kit/contributor_key.json (mode 600) and prints the PUBLIC key
+node bin/lumi-scan.js prove-wallet --network xrpl:0           # signs a wallet-control proof locally (needs the wallet secret env below)
+# Send Lumi the public key, the wallet address(es) you pay from and one proof per wallet. Lumi issues a key_id: add it to
+# the key file as "key_id". Wallets registered without a proof do not count until you run `prove-wallet --submit`.
+
+node bin/lumi-scan.js quote https://seller.example/x402/data   # free: 402 quote, latency, price per chain
+node bin/lumi-scan.js wanted --limit 5                          # what to test next (server-chosen)
+
+# Passive: report a purchase you already made (the wallet secret is read from env or a file and never printed)
+export LUMI_KIT_XRPL_SEED_FILE=/path/to/wallet.json             # {"seed": "..."}; or LUMI_KIT_STELLAR_SECRET(_FILE) / LUMI_KIT_EVM_KEY(_FILE)
+node bin/lumi-scan.js report --endpoint https://seller.example/x402/data --network xrpl:0 \
+  --tx <TX_HASH> --status 200 --outcome delivered               # prints the signed receipt
+node bin/lumi-scan.js sharing on                               # tier 2 opt-in (required before --submit)
+node bin/lumi-scan.js report ... --submit                       # sends it to Lumi
+
+node bin/lumi-scan.js buy https://seller.example/x402/data      # dry run: shows what would be paid, against your caps
+node bin/lumi-scan.js me                                        # your own submissions and badge
+node bin/lumi-scan.js share-demand on                           # opt in to aggregate demand stats (off by default)
+```
+
+Outcomes: `delivered`, `no_data`, `empty_result`, `error_status`, `timeout`, `wrong_data`, `other`, `inconclusive`.
+
+Extra test data recorded with each receipt (all optional): latency, HTTP status, response size, response SHA-256,
+schema fingerprint (field names and types, not values), data freshness, facilitator and settlement time. No prices
+or amounts. Response bodies are never uploaded, only their hash and shape.
+
+MCP: the `lumi-trades-mcp` branch build adds `lumi_scan_seller` (quote + dry-run plan) and `lumi_report_receipt`
+(passive report; set `LUMI_CONTRIB_KEY_FILE`).
+
+## What you get back
+
+- Your own submissions, with their status and findings, and your badge (`lumi-scan me`).
+- Normal Lumi API access.
+- **Not** the raw pooled database.
+
+## Files
+
+- `RECEIPT_FORMAT.md`: the receipt, its mapping to ARS `counterparty_delivery_receipt` v0.1, and request signing.
+- `FUNDING_XRPL.md`: funding a small XRPL test wallet (reserve, RLUSD trustline).
+- `TERMS.md`: contributor terms (DRAFT).
+- `LICENSE` (Apache-2.0) and `NOTICE` (what is not licensed).
+
+## Security
+
+- Wallet secrets come from env or files only. They are never logged or sent; output passes through a redactor.
+- The contributor key signs API requests only and cannot move funds. Lumi can revoke it instantly.
+- Use a dedicated low-balance wallet for test-buys.

package/RECEIPT_FORMAT.md

@@ -0,0 +1,84 @@
+# Receipt format: `counterparty_delivery_receipt` v0.1 plus `x_lumi_contrib`
+
+Contributor receipts use the same body Lumi uses for its own signed test-buy receipts: the proposed AgenticRiskStandard
+(ARS) evidence type `counterparty_delivery_receipt`, version `ars-evidence/0.1`. Kit-specific data goes in one
+extension block, `x_lumi_contrib`. ARS consumers can ignore it, but it is covered by the hash.
+
+## Body
+
+```json
+{
+  "type": "counterparty_delivery_receipt",
+  "version": "ars-evidence/0.1",
+  "receipt_id": "contrib-xrpl-<tx_hash>",
+  "issued_at": "2026-10-23T21:00:00.000Z",
+  "issuer": { "name": "Lumi Check contributor", "methodology_url": "https://api.lumitrades.io/v1/trust/methodology", "methodology_version": "v0" },
+  "seller": { "endpoint": "https://seller.example/x402/data", "domain": "seller.example", "pay_to": "r..." },
+  "payment": { "network": "xrpl:0", "tx_hash": "<64 hex>" },
+  "delivery": { "observed_at": "2026-10-23T20:59:58Z", "http_status": 200, "data_returned": true, "outcome": "delivered", "latency_ms": 840, "source": "contributor" },
+  "x_lumi_contrib": {
+    "format": "lumi-contrib/0.1",
+    "kit": { "name": "lumi-scanner-kit", "version": "0.1.0" },
+    "mode": "passive",
+    "measurements": { "latency_ms": 840, "http_status": 200, "response_bytes": 1834, "response_sha256": "<64 hex>",
+                      "schema_fingerprint": "<32 hex>", "data_timestamp": "...", "freshness_s": 42, "quote_latency_ms": 120,
+                      "facilitator": "...", "settlement_ms": 2100 }
+  },
+  "receipt_hash": "<sha256 hex>",
+  "signer": { "key_type": "ripple-keypairs", "address": "r...", "public_key": "...", "message": "lumi-receipt:xrpl:0:<tx>:<hash>", "signature": "..." }
+}
+```
+
+## Payment block: chain and transaction ID only
+
+`payment` carries exactly two fields, `network` and `tx_hash`. The server refuses a contributed receipt with any other
+payment field (HTTP 422 `receipt_payment_fields_not_allowed`). The amount, asset and paying wallet are not in the
+receipt; the server reads the public ledger to confirm that the signing wallet paid `seller.pay_to` a non-zero amount.
+The server does not store the amount. Measurements carry no prices, amounts or addresses: a receipt whose
+`x_lumi_contrib.measurements` has a `quotes`, `amount`, `price`, `asset`, `pay_to` or `payer` key is refused the same way.
+
+A transaction ID is public: anyone who has it can look it up on the blockchain and link it to the paying wallet. The
+kit's tier-2 opt-in says so before sharing is turned on.
+
+## Hash and signature
+
+- `receipt_hash` is the SHA-256 of the canonical JSON of the body without `receipt_hash` and `signer`. Canonical JSON
+  means keys sorted and no whitespace, in the RFC 8785 style.
+- The **paying wallet** signs `lumi-receipt:<network>:<tx_hash>:<receipt_hash>`:
+  - XRPL: `ripple-keypairs` over the UTF-8 hex
+  - Base: EIP-191 `personal_sign`
+  - Stellar: ed25519 over the UTF-8 message, base64-encoded
+- The signer must be the wallet that sent the payment on-ledger. The kit checks this locally before signing (the
+  ledger's payer is passed to `signReceipt(body, signer, { payer })` and not written into the body), and the server
+  checks it again on-ledger.
+- Anyone can verify a receipt offline, or on-ledger with `POST /v1/trust/receipts/verify?ledger=1`.
+
+## Mapping to ARS `counterparty_delivery_receipt` v0.1
+
+| ARS field | Kit value |
+|---|---|
+| `type`, `version` | Unchanged |
+| `receipt_id` | `contrib-<chain>-<tx_hash>`. Lumi's own receipts use `lumi-<chain>-<tx>`. |
+| `issuer` | The contributor, described generically. Contributor identity is held server-side by key id and never put in the receipt. |
+| `seller.*` | Same. `vendor_id` is omitted; the server resolves it. |
+| `payment.network` | `xrpl:0`, `eip155:8453` and **`stellar:pubnet`**. Stellar extends the v0.1 enum and is documented here. |
+| `payment.*` | Only `network` and `tx_hash`. ARS's `asset`, `amount`, `payer` and `ledger_result` are left out on purpose (data minimisation); the server reads them from the ledger to verify and does not store the amount. |
+| `delivery.outcome` | Same 8-value enum. `data_returned` is `null` for `inconclusive`. |
+| `delivery.source` | `"contributor"`. Lumi's own receipts use a descriptive string such as `"Lumi daily test-buy (XRPL)"`. |
+| `x_lumi_contrib` | Extension. `format` versions the block; `kit.version` lets the server retire old kits (HTTP 426). |
+| `receipt_hash`, `signer` | Same scheme as Lumi's receipts |
+
+## Submission request
+
+`POST /v1/contrib/submissions` with body `{"mode":"passive"|"test_buy","receipt":{...}}`. It is signed with the
+**contributor key** (ed25519), not the wallet.
+
+```
+Lumi-Contributor-Key: lck_<16 hex>
+Lumi-Timestamp: <unix ms>            (must be within 5 minutes)
+Lumi-Signature: base64(ed25519("lumi-contrib/v0\n<METHOD>\n<path+query>\n<ts>\n<sha256 hex of body>"))
+Lumi-Kit: lumi-scanner-kit/0.1.0
+```
+
+A seller dispute (`POST /v1/contrib/disputes`) is signed by the seller's `pay_to` wallet over
+`lumi-dispute:<tx_hash>:<sha256(reason)>`.

package/TERMS.md

@@ -0,0 +1,97 @@
+# Lumi Check: Contributor Terms (DRAFT, not in effect)
+
+> **DRAFT for review. Not legal advice and not yet offered to anyone.** v0 is a private dry run with Lumi's own
+> agents (Lumi and Lumi Scout) as the first two contributors.
+
+## 1. What these terms cover
+
+These terms cover taking part in Lumi's contributor program: submitting receipts with a Lumi-issued contributor key.
+The kit's **client code** is licensed separately under Apache-2.0 (`LICENSE`). That license covers only the client
+code. It does not cover Lumi's pooled dataset, scoring, verification server, contributor keys, the "Tested by Lumi"
+name or badges. Those remain Lumi's, and nothing here or in the license grants rights in them.
+
+## 2. Contributor keys
+
+- Lumi issues keys at its discretion and can **revoke a key instantly**, with or without notice, for example for
+  suspected self-testing, boosting, collusion, false reports or abuse.
+- A key is a revocable credential tied to the wallets you register. It is not transferable and has no value of its own.
+- On revocation for abuse, Lumi may remove your badge and refuse future keys for the same wallets.
+
+## 3. What you submit
+
+- Only **test data** about purchases from x402 sellers: the payment's chain and transaction ID (checked on-ledger),
+  HTTP status, timing, response size, response hash, schema fingerprint, freshness, facilitator and settlement time.
+  No amounts or prices, no response bodies and no personal data. A transaction ID is public on its blockchain: anyone
+  who has it can look it up and link it to the wallet that paid.
+- You prove control of each wallet you register by signing a message bound to your contributor key. Wallets without a
+  proof do not count toward a badge.
+- Wallets funded from the same source count as one contributor: at most one counted receipt per seller per UTC day
+  across all of them. Receipts from wallets funded by the seller (its pay-to wallet or that wallet's funder) do not count.
+  Lumi looks up and caches each wallet's first funder from public ledger data for this.
+- You confirm that you actually made each payment from a wallet you control, and that it reflects a real
+  interaction. Self-testing (your own endpoints, domains or wallets) is not allowed and is rejected.
+- Lumi verifies each receipt on-ledger before it counts. It may reject, hold, down-weight or remove any submission,
+  including negative findings that are not independently confirmed or that a seller disputes.
+- You grant Lumi a perpetual, irrevocable, worldwide, royalty-free licence to use, combine, analyse and publish your
+  submissions, including in aggregate scores and badges.
+
+## 4. Recognition (badge only)
+
+- Contributors with a **verified** tier-2 receipt get a public, pseudonymous **contributor badge**, optionally shown
+  with a count of verified contributions. One receipt per unique seller per UTC day counts; self-tests, duplicates,
+  unconfirmed negatives and disputed findings do not. Tier-1 anonymous outcomes earn nothing.
+- That is the only reward. There are **no** credits, money, payments, prizes, discounts, rankings, early access,
+  rate-limit changes or other perks, and the badge has no monetary value.
+- Contributing never changes how any score is computed. Lumi may remove a badge for abuse.
+- Nothing in these terms is an employment, partnership or agency relationship.
+
+## 5. Sharing tiers
+
+- **Tier 1 (off until you say yes):** nothing is sent before you agree. After your first check, the CLI asks once:
+  "Share your results to help improve Lumi's public trust list? [Y/n]". If you say yes, after each paid call the kit
+  sends an anonymous delivery outcome: seller host (or Lumi vendor id), delivered yes/no, and a coarse status class. No
+  wallet address, amount, tx hash, URL path or query, payload, or stable identifier. Your answer is stored only on your
+  machine. Runs where the kit cannot ask (no terminal, CI, MCP server, code) stay off. Change it any time with
+  `lumi-scan telemetry on|off`, `LUMI_CHECK_TELEMETRY=on|off`, or `"telemetry": true|false`. Sharing never changes how
+  any score is computed.
+- **Tier 2 (off by default, opt-in):** full signed receipts. Nothing is sent unless you turn it on (`lumi-scan sharing on`).
+  Each receipt shares the payment's chain and transaction ID, which is public on-chain and can be linked to the wallet
+  that paid. The receipt has no amount or wallet field. Lumi confirms the payment on the public ledger and does not
+  store the amount. It keeps the paying wallet address (read from the ledger) only for the anti-gaming checks in
+  section 3; it is never published or shown publicly, and is removed if you delete your account.
+- **Retention.** Raw data (tier-1 outcome counters and tier-2 submissions, including the stored receipt copy) is kept for
+  90 days, then deleted. A raw tier-1 day is deleted only after it has been summarised. The summaries, one row per seller
+  per UTC day with delivered, failed and status-class counts (no wallet, amount, tx hash, URL query, payload or identifier
+  of you), are kept long-term.
+- Your contributor account (key id, public key, registered wallets) is kept while it is active, meaning you submitted a
+  verified receipt in the last 12 months. It is not deleted at 90 days.
+- **Deleting your account.** You can delete it at any time yourself (`lumi-scan account delete`, which calls the signed
+  `DELETE /v1/contrib/me`) or by emailing hello@lumitrades.io. Deletion cannot be undone.
+  Deleted at once: your key (it can never sign again), label, public key, registered wallets and the funding wallet
+  recorded for each, own domains, demand opt-in, last-activity date, your badge, and every tier-2 receipt you shared
+  (including the stored copy), except receipts Lumi has already cited in a published, dated test result.
+  Kept, with no link to you: those cited receipts, with your wallet signature, paying-wallet link, kit details and key id
+  removed (the transaction hash, seller and delivery result stay because the published result cites them; they still
+  fall under the 90-day raw retention), and the anonymous per-seller daily summaries and tier-1 counters, which never
+  had a link to you. What remains of the key is a tombstone (the random key id, status "deleted" and dates) so it cannot
+  be reused. Payments on a public blockchain cannot be deleted by anyone.
+
+## 6. Demand data
+
+- Off by default. If you opt in (`share-demand on`), Lumi may use your passive purchases in **aggregate demand
+  statistics only**, at domain level, with at least two contributors per row and no key ids or wallets. You can opt
+  out at any time; opting out applies to future submissions.
+
+## 7. What you get
+
+- Your own submissions back, with status and findings, and your badge (`/v1/contrib/me`), plus normal Lumi API access.
+- **Not** access to the raw pooled database.
+
+## 8. Sellers
+
+Sellers can dispute a finding by signing with their pay-to wallet. Lumi reviews disputes and may uphold or clear them.
+
+## 9. No warranty; limits
+
+The kit is provided "as is" (see `LICENSE`). Test-buys spend real funds: you are responsible for your wallets, caps
+and any losses. Lumi is not liable for seller behaviour. These terms may change, and the current DRAFT is not in effect.