Source code for fleetmesh_core.accounting.accounting

"""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


[docs]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'})
[docs]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
[docs]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
[docs]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}
[docs]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
[docs]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)
[docs]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'}
[docs]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
[docs]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)
[docs]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
[docs]def window_bounds(epoch_index: int, window_seconds: int) -> tuple[int, int]: return (epoch_index * window_seconds, (epoch_index + 1) * window_seconds)
[docs]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'])