fleetmesh-core 0.2.0__py3-none-any.whl

fleetmesh_core/__init__.py

@@ -0,0 +1,10 @@
+"""fleetmesh executable reference implementation.
+
+Standard library only, no I/O, no clock, no network, and every constant read
+from schema/. Contains reference mechanisms for Nostr event storage,
+reconciliation, peering, accounting, capacity management, and reporting.
+"""
+from __future__ import annotations
+
+__version__ = '0.2.0'
+

fleetmesh_core/accounting/__init__.py

@@ -0,0 +1,7 @@
+"""Accounting, capacity limits, settlement, Cashu, and strain."""
+from __future__ import annotations
+
+from . import accounting
+
+__all__ = ['accounting']
+

fleetmesh_core/accounting/accounting.py

@@ -0,0 +1,215 @@
+"""Receipts, their hash chain, and telling a dead peer from a lying one.
+
+The chain is what stops a subject rewriting an earlier claim once it learns what
+the issuer measured. The issuer keeps the head, which is 32 bytes per window,
+and the most recent body, because that body is the claim the window is
+evaluated against and the evidence any report about it must carry.
+"""
+from __future__ import annotations
+
+import hashlib
+from typing import Any, Mapping, Optional, Sequence
+
+from ..crypto import crypto
+
+from ..wire import schema_files
+from ..wire.interfaces import ReceiptBody
+
+CONSTANTS = schema_files.load_constants()
+
+ZERO: str = '00' * 32
+
+
+def canonical(receipt: Mapping[str, Any]) -> bytes:
+    """constants.json canonical.form: keys sorted by code point, no whitespace -
+    crypto.canonical, with one difference:
+
+    `sig` is excluded, because it is a signature over this. Excluding it means
+    the chain link is the same value whether or not the receipt has been signed
+    yet, so signing changes no head and breaks no chain.
+    """
+    return crypto.canonical({k: v for k, v in receipt.items() if k != 'sig'})
+
+
+def link(receipt: Mapping[str, Any]) -> str:
+    return hashlib.sha256(canonical(receipt)).hexdigest()
+
+
+def sign_receipt(body: ReceiptBody, sk_hex: str) -> ReceiptBody:
+    """The subject signs its own claim. BIP-340 over the chain link, which is
+    already SHA-256 of the canonical body, so no second construction is defined
+    and the head the issuer acknowledges is the message that was signed.
+
+    This is what makes a receipt evidence. Without it a report about divergence
+    cites a number only the reporter has ever seen the subject state, which is
+    hearsay; with it the subject's half of the disagreement is pinned and the
+    reporter is trusted only for its own measurement.
+    """
+    signed: ReceiptBody = {**body, 'sig': crypto.schnorr_sign(bytes.fromhex(link(body)), sk_hex)}
+    return signed
+
+
+def verify_receipt(body: Mapping[str, Any], subject_pubkey: str) -> bool:
+    """True when this receipt carries the subject's signature over its own link."""
+    sig = body.get('sig')
+    if not sig:
+        return False
+    try:
+        return crypto.schnorr_verify(bytes.fromhex(link(body)), subject_pubkey, sig)
+    except (ValueError, TypeError):
+        return False
+
+
+def build_chain(grant_id: str, window: int, counter_series: Sequence[Mapping[str, int]], start_at: int = 1787000000, step: int = 600) -> Mapping[str, Any]:
+    """Produce a well-formed chain. Counters are cumulative and monotonic."""
+    chain = []
+    prev = ZERO
+    for seq, counters in enumerate(counter_series):
+        body = {'grant': grant_id, 'window': window, 'seq': seq, 'prev': prev,
+                                'counters': dict(counters), 'at': start_at + seq * step}
+        h = link(body)
+        chain.append({'receipt': body, 'canonical': canonical(body).decode(), 'sha256': h})
+        prev = h
+    return {'chain': chain, 'head': prev}
+
+
+def verify_chain(chain: Sequence[Mapping[str, Any]], head: Optional[str] = None) -> list[str]:
+    """Check every link, sequence number and monotonicity claim.
+
+    Returns a list of failures; empty means the chain holds. A subject that
+    rewrote seq 3 after the fact cannot also produce a matching seq 4.
+
+    This is strict about sequence, and stays strict, because what it checks is
+    a *complete* chain carried as evidence: a report cites what its subject
+    signed, and a chain with a hole in it is not the artefact it claims to be.
+    Live intake is the other case and is deliberately not this one -
+    `node.budget.on_receipt` tolerates a gap, because there the missing link is
+    the wire rather than the subject, and refusing it costs a whole window.
+    """
+    out: list[str] = []
+    prev = ZERO
+    last: Optional[Mapping[str, int]] = None
+    for i, entry in enumerate(chain):
+        r = entry['receipt']
+        if r.get('seq') != i:
+            out.append('link %d: seq is %s' % (i, r.get('seq')))
+        if r.get('prev') != prev:
+            out.append('link %d: prev does not chain' % i)
+        if entry.get('canonical') is not None and entry['canonical'] != canonical(r).decode():
+            out.append('link %d: canonical form does not match the body' % i)
+        h = link(r)
+        if entry.get('sha256') and entry['sha256'] != h:
+            out.append('link %d: stated hash is wrong' % i)
+        if last is not None:
+            for k, v in r.get('counters', {}).items():
+                if k in last and v < last[k]:
+                    out.append('link %d: counter %s went backwards' % (i, k))
+        last = r.get('counters', {})
+        prev = h
+    if head is not None and prev != head:
+        out.append('head does not match the final link')
+    return out
+
+
+def admissible_prefix(receipts: Sequence[Mapping[str, Any]]) -> tuple[list[Mapping[str, Any]], bool]:
+    """The longest gap-free, chain-verified prefix of a stored receipt list,
+    and whether anything was cut.
+
+    Live intake (`node.budget.on_receipt`) tolerates a lost link: a receipt
+    at seq 5 after seq 3 is stored, because the hole is the wire's and
+    refusing it costs a window. `verify_chain` is strict for the same reason
+    in the opposite direction: a chain cited as evidence must be the artefact
+    the subject signed, whole. Reporter used to attach every stored body, so
+    an S2 about a peer that lost one receipt on the wire carried a chain a
+    verifier would reject on sight - and a report with inadmissible evidence
+    is discarded unread. This keeps what verifies, from seq 0 up to the first
+    hole or broken link, so what is published is always admissible; partial
+    is reported so the caller can say so.
+    """
+    kept: list[Mapping[str, Any]] = []
+    prev = ZERO
+    last: Optional[Mapping[str, int]] = None
+    for i, r in enumerate(receipts):
+        if r.get('seq') != i or r.get('prev') != prev:
+            break
+        if last is not None and any(k in last and v < last[k] for k, v in r.get('counters', {}).items()):
+            break
+        kept.append(dict(r))
+        prev = link(r)
+        last = r.get('counters', {})
+    return kept, len(kept) != len(receipts)
+
+
+def silence(measured: Mapping[str, int]) -> Mapping[str, Any]:
+    """Active or inactive silence, per the partition-tolerance rule.
+
+    Receipts missing while the peer moved bytes is a misreport. Receipts missing
+    while it moved nothing is a partition, and FLP says you cannot tell a dead
+    node from a quiet one - so the protocol does not try, and prices only the
+    case where physical traffic contradicts the silence.
+    """
+    egress = sum(v for k, v in measured.items()
+                 if k in ('events_in', 'bytes_in', 'bytes_out', 'req', 'sync_ranges'))
+    if egress > 0:
+        return {'state': 'active-silence', 'severity': 'S2',
+                'remedy': 'limit x %s, tier to probation, report published'
+                          % CONSTANTS['grant']['aimd_decrease_s2']}
+    return {'state': 'inactive-silence', 'severity': None,
+            'remedy': 'not evaluated, streak neither advanced nor broken, no penalty, no report'}
+
+
+def window_claim(receipts: Sequence[Mapping[str, Any]], measured: Mapping[str, int]) -> tuple[str, Optional[dict[str, int]]]:
+    """What a window is evaluated against, per constants.json grant.window_evaluation.
+
+    receipts are the bodies received this window, in order. The most recent one
+    is the claim: counters are cumulative, so it already states the whole window,
+    and the chain makes it binding. A subject that sent receipts and then went
+    quiet is evaluated on what it last said against what was measured after -
+    which is how a leaf that syncs and then sleeps produces no finding, and a
+    peer that kept moving bytes after its last receipt is priced by divergence.
+    Returns (state, counters): ('claim', counters), ('active-silence', None) or
+    ('not-evaluated', None).
+
+    None means there is no claim, not that there is nothing to evaluate. A
+    window measured with no receipt is still evaluated - against the empty
+    claim, which is what vectors/window.json's "no receipt at all" case does -
+    and active silence is a *floor* of S2 on top of that. Skipping the
+    arithmetic would price a peer that overran and said nothing below the same
+    peer reporting it honestly, which is the inversion docs/mechanisms.md § 9
+    describes for divergence, in its other form.
+    """
+    if receipts:
+        return 'claim', dict(receipts[-1]['counters'])
+    return ('active-silence' if silence(measured)['severity'] else 'not-evaluated'), None
+
+
+def close_is_final(close_at: int, window_end: int, window_seconds: int) -> bool:
+    """A close arriving within the grace period is accepted as the window's final
+    receipt; later than that it is evaluated like any other receipt.
+
+    The grace span is half-open like the window itself: [window_end,
+    window_end + grace). The evaluator fires once `now >= window_end + grace`
+    (node budget/windows.py), so a close stamped at exactly that instant
+    arrives at or after evaluation and is late, not final."""
+    return close_at < window_end + window_grace(window_seconds)
+
+
+def epoch(unix_seconds: int, window_seconds: int) -> int:
+    """floor(t / window). Derived from the clock, so it cannot pause.
+
+    A dormant span advances the epoch counter and simply is not evaluated:
+    the streak neither advances nor breaks, and the next active window starts
+    a fresh chain at seq 0. The window is [epoch * window, (epoch+1) * window).
+    """
+    return unix_seconds // window_seconds
+
+
+def window_bounds(epoch_index: int, window_seconds: int) -> tuple[int, int]:
+    return (epoch_index * window_seconds, (epoch_index + 1) * window_seconds)
+
+
+def window_grace(window_seconds: int) -> int:
+    """Clock-skew allowance at window close, in whole seconds (floored, so
+    the allowance never exceeds the published fraction)."""
+    return int(window_seconds * CONSTANTS['grant']['window_grace_fraction'])
+

fleetmesh_core/accounting/capacity.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Reference implementation of the node's own ceiling and the shed ladder.
+
+Standard library only. Every constant is read from schema/constants.json rather
+than hardcoded, so this file and the protocol version digest cannot disagree.
+
+A grant bounds one peer. Nothing bounded the node. `Meter` is per peer and the
+tick loops them, so twenty anchor peerings each perfectly inside its grant is
+960,000 events an hour with nobody at fault anywhere: every branch within its
+limit, and the trunk with none. That is the fragility this file answers.
+
+Two decisions worth stating here rather than leaving to a reader.
+
+**The total is the operator's number and this file states no default.** The
+specification says connectivity and not capability is what separates one
+deployment from another, so a Raspberry Pi and a forty-core gateway both declare
+anchor and no per-class table could be honest about either. What is normative is
+the ladder. A node with no declared total measures its pressure and reports it
+and sheds nothing, because refusing an honest peer against a limit nobody chose
+is worse than the overload it would be avoiding. `suggest` exists so an operator
+has a number to start from rather than a blank.
+
+**Shedding is announced, and it is not adverse.** Every rung says what it is
+doing - a decline code, a republished coverage claim, an amend carrying
+`cause: capacity`. A node that shed quietly would be read as partitioned, which
+is the one conclusion this protocol keeps having to unlearn, and a subject that
+read a capacity shed as a remedy would price its issuer for owning a small
+machine.
+"""
+from __future__ import annotations
+
+from typing import Iterable, Mapping, Optional, Sequence
+
+from . import window
+
+from ..wire import schema_files# window.as_limits: a grant carries integers
+from ..wire.interfaces import CapacitySummary
+
+C = schema_files.load_constants()['capacity']
+
+COUNTERS: tuple[str, ...] = tuple(C['counters'])
+LADDER: tuple[tuple[float, str], ...] = tuple((r['at'], r['action']) for r in C['shed'])
+ACTIONS: tuple[str, ...] = tuple(a for _, a in LADDER)
+
+
+def pressure(measured: Mapping[str, int | float], total: Mapping[str, int | float]) -> tuple[float, Optional[str]]:
+    """(fraction, binding counter) for one window's aggregate against a total.
+
+    The fraction is the max over counters, not a mean: a node that has run out
+    of one thing has run out. `total` is a dict of the same counter names; a
+    counter the operator did not declare is not measured, and a total of zero or
+    less is not a declaration.
+    """
+    worst: float = 0.0
+    binding: Optional[str] = None
+    for name in COUNTERS:
+        cap = total.get(name)
+        if not cap or cap <= 0:
+            continue
+        share = measured.get(name, 0) / float(cap)
+        if share > worst:
+            worst, binding = share, name
+    return worst, binding
+
+
+def rungs(p: float) -> list[str]:
+    """Every shed action engaged at pressure p, in ladder order."""
+    return [a for at, a in LADDER if p >= at]
+
+
+def engaged(p: float, held: Sequence[str] = ()) -> list[str]:
+    """The rungs a node should be holding now, given what it holds already.
+
+    Rungs engage each at its own threshold and release together below
+    `restore_below`. Releasing each at the threshold that engaged it would flap
+    a node sitting on a boundary, and each flap costs its peers an amend.
+    """
+    if p < C['restore_below']:
+        return []
+    now = set(rungs(p)) | set(held)
+    return [a for a in ACTIONS if a in now]
+
+
+def shed_floor(probation: Mapping[str, int | float]) -> dict[str, int]:
+    """The lowest a capacity shed may take a limit, from the probation ceilings.
+
+    Deliberately not the probation ceiling itself. A peering opens at that
+    ceiling, so a floor there would make the amend_down rung do nothing at all
+    for exactly the peers a busy node has most of - declared and never read,
+    which is a shape this specification keeps finding in itself. Deliberately
+    not zero either: zero for 24 hours is what S3 does to an offender, and a
+    shed is not a remedy. What is left is enough for a receipt and a trickle,
+    which is what keeps a small peering accountable rather than silent.
+    """
+    f: float = C['shed_floor_fraction']
+    # Floored, like every other limit. A fractional floor and an integer result
+    # do not compare the way anyone expects: max(335544.3, x) written into a
+    # grant becomes 335544, which is below the floor it was just held to.
+    return window.as_limits({k: v * f for k, v in probation.items()})
+
+
+def reduce(limits: Mapping[str, int | float], floor: Mapping[str, int | float], fraction: Optional[float] = None) -> dict[str, int]:
+    """Scale a grant's limits for a capacity shed, never below the floor.
+
+    A capacity shed makes a peer smaller and never makes it a stranger: the tier
+    does not move and the peering is not ended. That is what separates it from
+    an S2, which is the ladder's business and not this file's. Pass the floor
+    from `shed_floor`.
+    """
+    f = C['amend_down_fraction'] if fraction is None else fraction
+    return window.as_limits({k: max(floor.get(k, 0), v * f) if k in floor else v * f
+                             for k, v in limits.items()})
+
+
+def suggest(windows: Iterable[Mapping[str, int | float]]) -> dict[str, int | float]:
+    """A total to start from, per counter: the largest window observed.
+
+    `windows` is an iterable of aggregate measurements, one per closed window.
+    This is a report of what the machine has already carried and not a claim
+    about what it can. An operator raises it deliberately or lowers it after
+    watching the box, and either way the number is theirs.
+    """
+    out: dict[str, int | float] = {}
+    for w in windows:
+        for name in COUNTERS:
+            v = w.get(name, 0)
+            if v > out.get(name, 0):
+                out[name] = v
+    return out
+
+
+def summary(measured: Mapping[str, int | float], total: Mapping[str, int | float]) -> CapacitySummary:
+    """What the health block prints. Undeclared is a state, not a zero."""
+    if not any(total.get(n) for n in COUNTERS):
+        return {'declared': False, 'pressure': None, 'binding': None,
+                'rungs': [], 'measured': {k: measured.get(k, 0) for k in COUNTERS
+                                          if measured.get(k)}}
+    p, binding = pressure(measured, total)
+    return {'declared': True, 'pressure': round(p, 4), 'binding': binding,
+            'rungs': rungs(p),
+            'measured': {k: measured.get(k, 0) for k in COUNTERS if measured.get(k)}}
+