feeless402 0.2.2__tar.gz → 0.2.3__tar.gz

{feeless402-0.2.2 → feeless402-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feeless402
-Version: 0.2.2
+Version: 0.2.3
 Summary: Feeless x402 micropayments for AI agents — self-custodied XNO wallet, pay-per-call client, merchant server with railHint, faucet, and MCP server
 License: MIT
 Project-URL: Homepage, https://feeless402.com

{feeless402-0.2.2 → feeless402-0.2.3}/feeless402.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feeless402
-Version: 0.2.2
+Version: 0.2.3
 Summary: Feeless x402 micropayments for AI agents — self-custodied XNO wallet, pay-per-call client, merchant server with railHint, faucet, and MCP server
 License: MIT
 Project-URL: Homepage, https://feeless402.com

{feeless402-0.2.2 → feeless402-0.2.3}/nano_pay/__init__.py

@@ -1,6 +1,6 @@
 """nano-pay: self-custodied Nano (XNO) wallet + x402 payment client for AI agents."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 RAW_PER_XNO = 10**30
 

{feeless402-0.2.2 → feeless402-0.2.3}/nano_pay/cli.py

@@ -225,9 +225,21 @@ def _claim_one(base, w):
         if ch.get("pow_required"):
             import nanopy
 
+            # Deliberately local: the faucet's challenge is meant to cost the
+            # claimant real CPU, which is what stops a farm claiming in bulk.
+            # It cannot be handed to a work service without giving that away.
+            # It can, however, say so — running silent for minutes on the
+            # first command anyone tries reads as a hang.
+            print("solving the faucet's proof-of-work on this machine — "
+                  "usually 30s to a few minutes. This is what keeps the "
+                  "faucet from being drained; it only happens once.",
+                  file=sys.stderr, flush=True)
+            t0 = time.time()
             payload["work"] = (
                 f"{nanopy.ext.work_generate(bytes.fromhex(ch['root']), int(ch['difficulty'], 16), __import__('os').urandom(128)):016x}"
             )
+            print(f"proof-of-work solved in {time.time() - t0:.0f}s — claiming…",
+                  file=sys.stderr, flush=True)
     except Exception:
         pass  # no challenge endpoint — plain claim
     r = rq.post(f"{base}/faucet", json=payload, timeout=240)
@@ -270,21 +282,64 @@ def cmd_claim(args):
                 if got:
                     break
                 time.sleep(1.5)
-            if got:
-                w.prework(got[-1][0], rpc)   # warm the next block off the hash
             acct = w.synced_account(rpc)
-            out(
-                {
-                    "claimed_from": base,
-                    "result": res,
-                    "received": [
-                        {"hash": h, "amount_xno": raw_to_xno(a)}
-                        for h, a in got
-                    ],
-                    "balance_xno": raw_to_xno(acct.raw_bal),
-                    "attempts": attempts,
-                }
-            )
+            payload = {
+                "claimed_from": base,
+                "result": res,
+                "received": [
+                    {"hash": h, "amount_xno": raw_to_xno(a)}
+                    for h, a in got
+                ],
+                "balance_xno": raw_to_xno(acct.raw_bal),
+                "attempts": attempts,
+            }
+            # Report the grant BEFORE warming the next block. Pre-computing
+            # takes minutes on a modest machine, and doing it first left the
+            # user staring at a blank terminal wondering whether the claim
+            # worked — on the very first command they ever run. Same order
+            # and same guard as send()/pay().
+            if got:
+                print(json.dumps(payload, indent=2, default=str), flush=True)
+                print("claimed — that was the slow part, and it is over. "
+                      "Pre-computing the proof-of-work for your next block "
+                      "now, and again after every transaction, so payments "
+                      "from here are near-instant. Safe to Ctrl-C.",
+                      file=sys.stderr, flush=True)
+                try:
+                    w.prework(got[-1][0], rpc)
+                except Exception:
+                    pass
+                sys.exit(0)
+            out(payload)
+    # An already-claimed address is not a broken faucet: the money was
+    # granted earlier (possibly to a client that gave up before the reply).
+    # Pocket anything still pending and report the balance instead of a
+    # hard error — exit 0 when the wallet is funded, since the agent can
+    # proceed straight to paying.
+    already = [
+        a for a in attempts
+        if a["status"] == 429
+        and "already claimed" in str(a["result"].get("error", ""))
+    ]
+    if already:
+        rpc = RPC()
+        got = w.receive_all(rpc, prework=False)
+        acct = w.synced_account(rpc)
+        bal = raw_to_xno(acct.raw_bal)
+        out(
+            {
+                "status": "already_claimed",
+                "message": f"this address already received its starter XNO — "
+                           f"balance {bal} XNO, nothing more to claim here; "
+                           f"generate a fresh wallet if you need a new grant",
+                "balance_xno": bal,
+                "received_now": [
+                    {"hash": h, "amount_xno": raw_to_xno(a)} for h, a in got
+                ],
+                "attempts": attempts,
+            },
+            code=0 if acct.raw_bal else 1,
+        )
     out({"error": "no faucet granted a claim", "attempts": attempts}, code=1)
 
 

{feeless402-0.2.2 → feeless402-0.2.3}/nano_pay/mcp_remote.py

@@ -24,7 +24,7 @@ from .rpc import RPC
 from .x402 import collect_offers, compare_rails, offer_amount_raw, parse_quote, pick_nano_offer
 
 FAUCET_ADDR = "nano_1hk1cu3773u5r39e75mtqrauzro75j3hwdzyewz8izokzur66semy739w14h"
-FAUCET_CLAIM_XNO = "0.005"
+FAUCET_CLAIM_XNO = "0.0005"
 
 INSTRUCTIONS = """Read-only demo of the Feeless402 rail: price any x402
 (HTTP 402 Payment Required) API across payment rails and see what the
@@ -156,7 +156,7 @@ def faucet_info() -> str:
             "rules": "one claim per address ever; 3 per IP per day; proof-of-work required",
             "how_to_claim": "pip install feeless402; nano-pay claim https://feeless402.com "
             "(or the faucet_claim tool of the LOCAL MCP server: nano-pay mcp)",
-            "donations": f"send XNO to {FAUCET_ADDR} — every 0.005 onboards another agent",
+            "donations": f"send XNO to {FAUCET_ADDR} — every 0.0005 onboards another agent",
         }
     )
 

{feeless402-0.2.2 → feeless402-0.2.3}/nano_pay/rpc.py

@@ -1,7 +1,18 @@
 """Nano node RPC client with public-node failover."""
 
+import os
+
 import requests
 
+# Optional dedicated proof-of-work service, tried before the public nodes.
+# Public nodes serve work in ~5s and many refuse outright, which caps how
+# fast a faucet or merchant can sign blocks. Set:
+#   F402_WORK_URLS  comma-separated work endpoints
+#   F402_WORK_KEY   sent as {"key": ...} and as a Bearer header (services differ)
+WORK_URLS = [u.strip() for u in os.environ.get("F402_WORK_URLS", "").split(",")
+             if u.strip()]
+WORK_KEY = os.environ.get("F402_WORK_KEY", "")
+
 DEFAULT_RPCS = [
     "https://rpc.nano.to",
     "https://node.somenano.com/proxy",
@@ -19,9 +30,11 @@ class RPCError(Exception):
 
 
 class RPC:
-    def __init__(self, urls=None, timeout=20):
+    def __init__(self, urls=None, timeout=20, work_urls=None, work_key=None):
         self.urls = urls or list(DEFAULT_RPCS)
         self.timeout = timeout
+        self.work_urls = work_urls if work_urls is not None else list(WORK_URLS)
+        self.work_key = work_key if work_key is not None else WORK_KEY
 
     def call(self, payload: dict) -> dict:
         last_err = None
@@ -91,18 +104,22 @@ class RPC:
         return res["hash"]
 
     def work_generate(self, root: str, difficulty: str):
-        """Ask nodes for work; many public nodes refuse — return None then."""
-        for url in self.urls:
+        """Ask a work service first, then nodes; many public nodes refuse.
+
+        Returns None if nobody will do it, and the caller falls back to
+        local PoW.
+        """
+        payload = {"action": "work_generate", "hash": root,
+                   "difficulty": difficulty}
+        for url in list(self.work_urls) + list(self.urls):
+            body = dict(payload)
+            headers = {}
+            if url in self.work_urls and self.work_key:
+                body["key"] = self.work_key            # BoomPoW-style
+                headers["Authorization"] = f"Bearer {self.work_key}"
             try:
-                r = requests.post(
-                    url,
-                    json={
-                        "action": "work_generate",
-                        "hash": root,
-                        "difficulty": difficulty,
-                    },
-                    timeout=self.timeout,
-                )
+                r = requests.post(url, json=body, headers=headers,
+                                  timeout=self.timeout)
                 data = r.json()
                 if isinstance(data, dict) and data.get("work"):
                     return data["work"]

{feeless402-0.2.2 → feeless402-0.2.3}/nano_pay/server.py

@@ -32,8 +32,15 @@ DOCS_URL = os.environ.get(
     "F402_DOCS_URL", "https://github.com/feeless402/feeless402"
 )
 PRICE_XNO = os.environ.get("F402_PRICE_XNO", "0.0001")
-FAUCET_XNO = os.environ.get("F402_FAUCET_XNO", "0.005")
+FAUCET_XNO = os.environ.get("F402_FAUCET_XNO", "0.0005")
+FAUCET_TOPUP_XNO = os.environ.get("F402_FAUCET_TOPUP_XNO", "0.0045")
+# Kept as a string for xno_to_raw's Decimal path; parsed separately so the
+# "is it switched on" test can't trip over a str/int comparison.
+FAUCET_TOPUP_ON = float(FAUCET_TOPUP_XNO or 0) > 0
+# When the grant size last changed, so dispensed-history math stays honest.
+FAUCET_RATE_CHANGES = [(0.0, 0.005), (1786021000.0, float(FAUCET_XNO))]
 FAUCET_PER_IP_PER_DAY = int(os.environ.get("F402_FAUCET_PER_IP_PER_DAY", "3"))
+FAUCET_GLOBAL_PER_HOUR = int(os.environ.get("F402_FAUCET_GLOBAL_PER_HOUR", "12"))
 FAUCET_POW = os.environ.get("F402_FAUCET_POW", "0") == "1"
 # Sibling faucets advertised in railHint — the federation list. Comma-sep.
 FAUCET_FEDERATION = [
@@ -115,6 +122,51 @@ def _count_paid_call(payer: str, demo_address: str) -> None:
         pass
 
 
+def _maybe_graduate(payer: str) -> None:
+    """First real x402 payment from a faucet claimant quietly tops their
+    starter grant up to a full allowance. Never raises, never blocks the
+    payment response; the send runs in its own thread under FAUCET_LOCK.
+
+    Deliberately unadvertised on every user-facing surface: the paid call
+    itself is the proof of a real integration.
+
+    ⚠️ Aug 7 2026: SET TO ZERO (disabled). The premise — that paying proves
+    a real integration — held for about sixteen hours. A farm started paying
+    the 0.0001 premium fee to unlock the 0.0045 top-up, a 45x return, and
+    took 11 of 12 grants in a day. Any unlock that costs far less than the
+    prize is just a price, not a proof. Re-enable by setting
+    F402_FAUCET_TOPUP_XNO above zero if the economics ever change.
+    """
+    try:
+        if not FAUCET_TOPUP_ON:
+            return
+        if payer == demo_wallet.address or payer in _self_addresses():
+            return
+        led = _ledger()
+        if payer not in led["addresses"] or payer in led.get("graduated", {}):
+            return
+
+        def _send():
+            try:
+                with FAUCET_LOCK:
+                    led2 = _ledger()
+                    if payer in led2.setdefault("graduated", {}):
+                        return
+                    faucet_wallet.load()
+                    faucet_wallet.receive_all(rpc, prework=False)
+                    faucet_wallet.send(
+                        rpc, payer, xno_to_raw(FAUCET_TOPUP_XNO),
+                        prework=False)
+                    led2["graduated"][payer] = time.time()
+                    _save_ledger(led2)
+            except Exception:
+                pass
+
+        threading.Thread(target=_send, daemon=True).start()
+    except Exception:
+        pass
+
+
 def _faucet_funding() -> dict:
     """Who has put XNO INTO the faucet, read straight off the chain.
 
@@ -358,7 +410,10 @@ def _stats_data():
             "claims_total": len(ext_times),
             "claims_24h": sum(1 for t in ext_times if t > day_ago),
             "self_test_claims": len(claims) - len(ext_times),
-            "xno_dispensed": round(len(claims) * per_claim, 6),
+            "xno_dispensed": round(sum(
+                next(rate for start, rate in reversed(FAUCET_RATE_CHANGES)
+                     if t >= start)
+                for t in ts_list), 6),
             "xno_per_claim": per_claim,
             "balance_xno": faucet_bal,
             "claims_remaining": (
@@ -582,6 +637,16 @@ def create_app() -> FastAPI:
     def stats_json():
         return _stats_data()
 
+    # Liveness for uptime monitors and integrators (real users probed for
+    # both spellings) — cheap on purpose: no RPC, no wallet, no state writes.
+    start_unix = time.time()
+
+    @app.get("/health")
+    @app.get("/status")
+    def health():
+        return {"ok": True, "service": "feeless402", "version": __version__,
+                "uptime_s": int(time.time() - start_unix)}
+
     @app.get("/stats", response_class=HTMLResponse)
     def stats_page():
         return STATS_HTML
@@ -643,6 +708,7 @@ def create_app() -> FastAPI:
             )
             receipt = settle_block(block, rpc)
             _count_paid_call(payer, demo_wallet.address)
+            _maybe_graduate(payer)
         except PaymentInvalid as e:
             return JSONResponse(
                 {"error": f"payment invalid: {e}"}, status_code=402
@@ -1081,6 +1147,35 @@ def create_app() -> FastAPI:
                 headers={"Retry-After": str(max(1, int(frees_at - time.time())))},
             )
 
+        # Global budget: the faucet as a whole serves at most N claims per
+        # rolling hour, regardless of who is asking. Per-IP and per-address
+        # rules rotate away for free against a proxy pool (Aug 6 farm:
+        # 100+ claims/hour from unique IPs, identical UA); this is the one
+        # limit that can't. Counted straight from ledger timestamps, so it
+        # needs no extra state and survives restarts.
+        hour_ago = time.time() - 3600
+        hour_claims = sorted(
+            t for t in led["addresses"].values() if t > hour_ago)
+        if len(hour_claims) >= FAUCET_GLOBAL_PER_HOUR:
+            # Honest Retry-After: the moment the in-window count drops BELOW
+            # the cap — not when the single oldest claim ages out, which
+            # after a burst frees no capacity at all.
+            frees_at = hour_claims[len(hour_claims) - FAUCET_GLOBAL_PER_HOUR] + 3600
+            wait = max(1, int(frees_at - time.time()))
+            return JSONResponse(
+                {"error": "faucet hourly budget used up — try again shortly",
+                 "limit_per_hour_global": FAUCET_GLOBAL_PER_HOUR,
+                 "retry_after_seconds": wait,
+                 "retry_at_utc": time.strftime(
+                     "%Y-%m-%dT%H:%M:%SZ", time.gmtime(frees_at)),
+                 "note": "shared across all users; separately, each address "
+                         "may claim once ever",
+                 "building_something": "if the budget keeps blocking a real "
+                                       f"integration, ask: {DOCS_URL}/issues"},
+                status_code=429,
+                headers={"Retry-After": str(wait)},
+            )
+
         amount = xno_to_raw(FAUCET_XNO)
 
         def _locked_claim():
@@ -1092,6 +1187,16 @@ def create_app() -> FastAPI:
                 led2 = _ledger()
                 if address in led2["addresses"]:
                     return None
+                # Re-check the global budget now that we hold the lock: a
+                # burst can push many requests past the pre-lock check while
+                # earlier sends are still queued here (Aug 6: 5 claims slipped
+                # through a 3/hour cap exactly this way).
+                cutoff = time.time() - 3600
+                inwin = sorted(t for t in led2["addresses"].values()
+                               if t > cutoff)
+                if len(inwin) >= FAUCET_GLOBAL_PER_HOUR:
+                    return ("budget",
+                            inwin[len(inwin) - FAUCET_GLOBAL_PER_HOUR] + 3600)
                 faucet_wallet.load()
                 # pocket any pending refills first
                 faucet_wallet.receive_all(rpc, prework=False)
@@ -1117,6 +1222,17 @@ def create_app() -> FastAPI:
                 {"error": "address already claimed its starter XNO"},
                 status_code=429,
             )
+        if isinstance(h, tuple) and h[0] == "budget":
+            wait = max(1, int(h[1] - time.time()))
+            return JSONResponse(
+                {"error": "faucet hourly budget used up — try again shortly",
+                 "limit_per_hour_global": FAUCET_GLOBAL_PER_HOUR,
+                 "retry_after_seconds": wait,
+                 "note": "shared across all users; separately, each address "
+                         "may claim once ever"},
+                status_code=429,
+                headers={"Retry-After": str(wait)},
+            )
         # Wait briefly for the send to confirm before answering. Clients
         # typically ask for their pending block the moment we reply, and if
         # it hasn't propagated they see "received nothing" and a zero

{feeless402-0.2.2 → feeless402-0.2.3}/nano_pay/wallet.py

@@ -13,6 +13,8 @@ Design notes:
 
 import json
 import os
+import tempfile
+import threading
 from pathlib import Path
 
 import nanopy
@@ -34,6 +36,7 @@ class Wallet:
     def __init__(self, path: Path = None):
         self.path = Path(path) if path else DEFAULT_DIR / "wallet.json"
         self.data = None
+        self._save_lock = threading.Lock()
 
     # ---------- persistence ----------
 
@@ -65,10 +68,26 @@ class Wallet:
         return self
 
     def _save(self):
-        tmp = self.path.with_suffix(".tmp")
-        tmp.write_text(json.dumps(self.data, indent=2))
-        os.chmod(tmp, 0o600)
-        tmp.replace(self.path)
+        # Concurrent saves (send path + work-precompute thread) once interleaved
+        # on a shared .tmp name and promoted a mangled file — lock the whole
+        # write and give each save its own temp file.
+        with self._save_lock:
+            fd, tmp = tempfile.mkstemp(
+                dir=self.path.parent, prefix=self.path.name + ".", suffix=".tmp"
+            )
+            try:
+                with os.fdopen(fd, "w") as f:
+                    f.write(json.dumps(self.data, indent=2))
+                    f.flush()
+                    os.fsync(f.fileno())
+                os.chmod(tmp, 0o600)
+                os.replace(tmp, self.path)
+            except BaseException:
+                try:
+                    os.unlink(tmp)
+                except OSError:
+                    pass
+                raise
 
     # ---------- account / state ----------
 

{feeless402-0.2.2 → feeless402-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "feeless402"
-version = "0.2.2"
+version = "0.2.3"
 description = "Feeless x402 micropayments for AI agents — self-custodied XNO wallet, pay-per-call client, merchant server with railHint, faucet, and MCP server"
 readme = "README.md"
 license = { text = "MIT" }