fleetmesh-node 0.2.0__py3-none-any.whl

node/config/protocols.py

@@ -0,0 +1,274 @@
+"""Protocol suite and host multiplexer configuration blocks."""
+from __future__ import annotations
+
+import dataclasses
+from typing import Any, Mapping, Optional
+
+from .base import Block, Problems, is_http_url, is_relay_url, opt, positive_int
+
+__all__ = [
+    'HostMultiplexerConfig',
+    'NostrProtocolConfig',
+    'ATProtoProtocolConfig',
+    'ActivityPubProtocolConfig',
+    'SSBProtocolConfig',
+    'P2PandaProtocolConfig',
+    'RhioProtocolConfig',
+    'ProtocolSuitesConfig',
+]
+
+
+@dataclasses.dataclass(frozen=True)
+class HostMultiplexerConfig(Block):
+    listen: str = '127.0.0.1'
+    port: int = 0
+    public_url: Optional[str] = None
+    bind_wait: float = 10.0
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('protocols.host must be an object'); return
+        opt(raw, 'listen', lambda v: isinstance(v, str) and len(v) > 0, p, 'protocols.host.listen must be a non-empty string')
+        opt(raw, 'port', lambda v: isinstance(v, int) and 0 <= v <= 65535, p, 'protocols.host.port must be 0..65535')
+        opt(raw, 'public_url', is_http_url, p, 'protocols.host.public_url must be an http or https URL')
+        opt(raw, 'bind_wait', lambda v: isinstance(v, (int, float)) and v >= 0, p, 'protocols.host.bind_wait must be non-negative')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'HostMultiplexerConfig':
+        if not isinstance(raw, Mapping):
+            return cls()
+        return cls(
+            listen=str(raw.get('listen', '127.0.0.1')),
+            port=int(raw.get('port', 0)),
+            public_url=str(raw['public_url']) if raw.get('public_url') else None,
+            bind_wait=float(raw.get('bind_wait', 10.0)),
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class NostrProtocolConfig(Block):
+    enabled: bool = True
+    relays: tuple[str, ...] = ()
+    require_auth: bool = False
+    future_seconds: int = 900
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('protocols.nostr must be an object'); return
+        opt(raw, 'enabled', lambda v: isinstance(v, bool), p, 'protocols.nostr.enabled must be a boolean')
+        opt(raw, 'relays', lambda v: isinstance(v, (list, tuple)) and all(is_relay_url(u) for u in v), p,
+            'protocols.nostr.relays must be a list of relay URLs (wss:// or ws://)')
+        opt(raw, 'require_auth', lambda v: isinstance(v, bool), p, 'protocols.nostr.require_auth must be a boolean')
+        opt(raw, 'future_seconds', positive_int, p, 'protocols.nostr.future_seconds must be a positive integer')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'NostrProtocolConfig':
+        if not isinstance(raw, Mapping):
+            return cls()
+        return cls(
+            enabled=bool(raw.get('enabled', True)),
+            relays=tuple(str(u) for u in (raw.get('relays') or ())),
+            require_auth=bool(raw.get('require_auth', False)),
+            future_seconds=int(raw.get('future_seconds', 900)),
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class ATProtoProtocolConfig(Block):
+    enabled: bool = False
+    handle: Optional[str] = None
+    service_did: Optional[str] = None
+    pds_enabled: bool = True
+    firehose_subscribe: bool = False
+    firehose_publish: bool = True
+    relay_upstream: Optional[str] = None
+    metered_peering: bool = True
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('protocols.atproto must be an object'); return
+        opt(raw, 'enabled', lambda v: isinstance(v, bool), p, 'protocols.atproto.enabled must be a boolean')
+        opt(raw, 'handle', lambda v: isinstance(v, str) and len(v) > 0, p, 'protocols.atproto.handle must be a string')
+        opt(raw, 'service_did', lambda v: isinstance(v, str) and v.startswith('did:'), p, 'protocols.atproto.service_did must be a did: URI')
+        opt(raw, 'pds_enabled', lambda v: isinstance(v, bool), p, 'protocols.atproto.pds_enabled must be a boolean')
+        opt(raw, 'firehose_subscribe', lambda v: isinstance(v, bool), p, 'protocols.atproto.firehose_subscribe must be a boolean')
+        opt(raw, 'firehose_publish', lambda v: isinstance(v, bool), p, 'protocols.atproto.firehose_publish must be a boolean')
+        opt(raw, 'relay_upstream', is_relay_url, p, 'protocols.atproto.relay_upstream must be a websocket URL')
+        opt(raw, 'metered_peering', lambda v: isinstance(v, bool), p, 'protocols.atproto.metered_peering must be a boolean')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'ATProtoProtocolConfig':
+        if not isinstance(raw, Mapping):
+            return cls()
+        return cls(
+            enabled=bool(raw.get('enabled', False)),
+            handle=str(raw['handle']) if raw.get('handle') else None,
+            service_did=str(raw['service_did']) if raw.get('service_did') else None,
+            pds_enabled=bool(raw.get('pds_enabled', True)),
+            firehose_subscribe=bool(raw.get('firehose_subscribe', False)),
+            firehose_publish=bool(raw.get('firehose_publish', True)),
+            relay_upstream=str(raw['relay_upstream']) if raw.get('relay_upstream') else None,
+            metered_peering=bool(raw.get('metered_peering', True)),
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class ActivityPubProtocolConfig(Block):
+    enabled: bool = False
+    domain: Optional[str] = None
+    summary: str = 'Fleetmesh Sovereign Edge Node'
+    rate_limit_per_inbox: int = 60
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('protocols.activitypub must be an object'); return
+        opt(raw, 'enabled', lambda v: isinstance(v, bool), p, 'protocols.activitypub.enabled must be a boolean')
+        opt(raw, 'domain', lambda v: isinstance(v, str) and len(v) > 0, p, 'protocols.activitypub.domain must be a string')
+        opt(raw, 'summary', lambda v: isinstance(v, str), p, 'protocols.activitypub.summary must be a string')
+        opt(raw, 'rate_limit_per_inbox', positive_int, p, 'protocols.activitypub.rate_limit_per_inbox must be a positive integer')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'ActivityPubProtocolConfig':
+        if not isinstance(raw, Mapping):
+            return cls()
+        return cls(
+            enabled=bool(raw.get('enabled', False)),
+            domain=str(raw['domain']) if raw.get('domain') else None,
+            summary=str(raw.get('summary', 'Fleetmesh Sovereign Edge Node')),
+            rate_limit_per_inbox=int(raw.get('rate_limit_per_inbox', 60)),
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class SSBProtocolConfig(Block):
+    enabled: bool = False
+    port: int = 8008
+    caps: str = 'd4a1da283c1e443e022da12bc6139952b324e4001f40fa38ba5754035a49807f'
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('protocols.ssb must be an object'); return
+        opt(raw, 'enabled', lambda v: isinstance(v, bool), p, 'protocols.ssb.enabled must be a boolean')
+        opt(raw, 'port', lambda v: isinstance(v, int) and 0 <= v <= 65535, p, 'protocols.ssb.port must be 0..65535')
+        opt(raw, 'caps', lambda v: isinstance(v, str) and len(v) == 64, p, 'protocols.ssb.caps must be a 64-char hex string')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'SSBProtocolConfig':
+        if not isinstance(raw, Mapping):
+            return cls()
+        return cls(
+            enabled=bool(raw.get('enabled', False)),
+            port=int(raw.get('port', 8008)),
+            caps=str(raw.get('caps', 'd4a1da283c1e443e022da12bc6139952b324e4001f40fa38ba5754035a49807f')),
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class P2PandaProtocolConfig(Block):
+    enabled: bool = False
+    port: int = 9102
+    network_id: str = 'fleetmesh-default'
+    discovery: bool = True
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('protocols.p2panda must be an object'); return
+        opt(raw, 'enabled', lambda v: isinstance(v, bool), p, 'protocols.p2panda.enabled must be a boolean')
+        opt(raw, 'port', lambda v: isinstance(v, int) and 0 <= v <= 65535, p, 'protocols.p2panda.port must be 0..65535')
+        opt(raw, 'network_id', lambda v: isinstance(v, str) and len(v) > 0, p, 'protocols.p2panda.network_id must be a string')
+        opt(raw, 'discovery', lambda v: isinstance(v, bool), p, 'protocols.p2panda.discovery must be a boolean')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'P2PandaProtocolConfig':
+        if not isinstance(raw, Mapping):
+            return cls()
+        return cls(
+            enabled=bool(raw.get('enabled', False)),
+            port=int(raw.get('port', 9102)),
+            network_id=str(raw.get('network_id', 'fleetmesh-default')),
+            discovery=bool(raw.get('discovery', True)),
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class RhioProtocolConfig(Block):
+    enabled: bool = False
+    nats_endpoint: str = 'localhost:4222'
+    s3_endpoint: str = 'http://localhost:9000'
+    network_id: str = 'rhio-default-network-1'
+    bind_port: int = 9102
+    http_bind_port: int = 3000
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('protocols.rhio must be an object'); return
+        opt(raw, 'enabled', lambda v: isinstance(v, bool), p, 'protocols.rhio.enabled must be a boolean')
+        opt(raw, 'nats_endpoint', lambda v: isinstance(v, str) and len(v) > 0, p, 'protocols.rhio.nats_endpoint must be a string')
+        opt(raw, 's3_endpoint', lambda v: isinstance(v, str) and len(v) > 0, p, 'protocols.rhio.s3_endpoint must be a string')
+        opt(raw, 'network_id', lambda v: isinstance(v, str) and len(v) > 0, p, 'protocols.rhio.network_id must be a string')
+        opt(raw, 'bind_port', lambda v: isinstance(v, int) and 0 <= v <= 65535, p, 'protocols.rhio.bind_port must be 0..65535')
+        opt(raw, 'http_bind_port', lambda v: isinstance(v, int) and 0 <= v <= 65535, p, 'protocols.rhio.http_bind_port must be 0..65535')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'RhioProtocolConfig':
+        if not isinstance(raw, Mapping):
+            return cls()
+        return cls(
+            enabled=bool(raw.get('enabled', False)),
+            nats_endpoint=str(raw.get('nats_endpoint', 'localhost:4222')),
+            s3_endpoint=str(raw.get('s3_endpoint', 'http://localhost:9000')),
+            network_id=str(raw.get('network_id', 'rhio-default-network-1')),
+            bind_port=int(raw.get('bind_port', 9102)),
+            http_bind_port=int(raw.get('http_bind_port', 3000)),
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class ProtocolSuitesConfig(Block):
+    host: HostMultiplexerConfig = HostMultiplexerConfig()
+    nostr: NostrProtocolConfig = NostrProtocolConfig()
+    atproto: ATProtoProtocolConfig = ATProtoProtocolConfig()
+    activitypub: ActivityPubProtocolConfig = ActivityPubProtocolConfig()
+    ssb: SSBProtocolConfig = SSBProtocolConfig()
+    p2panda: P2PandaProtocolConfig = P2PandaProtocolConfig()
+    rhio: RhioProtocolConfig = RhioProtocolConfig()
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('protocols must be an object'); return
+        if 'host' in raw:
+            HostMultiplexerConfig.check(raw['host'], p)
+        if 'nostr' in raw:
+            NostrProtocolConfig.check(raw['nostr'], p)
+        if 'atproto' in raw:
+            ATProtoProtocolConfig.check(raw['atproto'], p)
+        if 'activitypub' in raw:
+            ActivityPubProtocolConfig.check(raw['activitypub'], p)
+        if 'ssb' in raw:
+            SSBProtocolConfig.check(raw['ssb'], p)
+        if 'p2panda' in raw:
+            P2PandaProtocolConfig.check(raw['p2panda'], p)
+        if 'rhio' in raw:
+            RhioProtocolConfig.check(raw['rhio'], p)
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'ProtocolSuitesConfig':
+        if not isinstance(raw, Mapping):
+            return cls()
+        return cls(
+            host=HostMultiplexerConfig.from_dict(raw.get('host')),
+            nostr=NostrProtocolConfig.from_dict(raw.get('nostr')),
+            atproto=ATProtoProtocolConfig.from_dict(raw.get('atproto')),
+            activitypub=ActivityPubProtocolConfig.from_dict(raw.get('activitypub')),
+            ssb=SSBProtocolConfig.from_dict(raw.get('ssb')),
+            p2panda=P2PandaProtocolConfig.from_dict(raw.get('p2panda')),
+            rhio=RhioProtocolConfig.from_dict(raw.get('rhio')),
+        )

node/config/records.py

@@ -0,0 +1,171 @@
+"""The records config.json carries in lists and maps: an endpoint, a peer to
+pull from, a coverage claim, a trust decision, a retention rule, and the two
+small objects the node itself reads (face, policy).
+
+These are read in many places - `peers` in five compartments, `coverage` in
+four - and before this each reader implied its own shape. One dataclass per
+record is the shape.
+"""
+from __future__ import annotations
+
+import dataclasses
+from typing import Any, Mapping, Optional
+
+from .base import Block, Problems, all_str, is_hex64, is_int, non_negative_int, opt, positive_int
+
+TIERS: tuple[str, ...] = ('probation', 'member', 'trusted', 'anchor')
+CLASSES: tuple[str, ...] = ('leaf', 'edge', 'anchor')
+COMPLETENESS: tuple[str, ...] = ('asserted', 'best-effort')
+HANDOVER: tuple[str, ...] = ('offer', 'never')
+
+
+@dataclasses.dataclass(frozen=True)
+class Endpoint(Block):
+    """One way to reach this node: `{transport, address[, priority]}`."""
+    transport: str
+    address: str
+    priority: int = 50
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        # The list check names the whole list once; see NodeConfig.
+        pass
+
+    @staticmethod
+    def well_formed(e: Any) -> bool:
+        return isinstance(e, Mapping) and isinstance(e.get('transport'), str) and isinstance(e.get('address'), str)
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'Endpoint':
+        return cls(transport=raw['transport'], address=raw['address'], priority=int(raw.get('priority', 50)))
+
+
+@dataclasses.dataclass(frozen=True)
+class PeerPull(Block):
+    """A peer this node pulls a shard from: `{pubkey, shard, filter[, pull_every, window]}`."""
+    pubkey: str
+    shard: str
+    filter: Mapping[str, Any]
+    pull_every: int = 900
+    window: Optional[int] = None          # the peering manifest's budget.window, seconds
+
+    @staticmethod
+    def check_one(i: int, e: Any, p: Problems) -> None:
+        if not isinstance(e, Mapping) or not is_hex64(e.get('pubkey')) or not isinstance(e.get('shard'), str) \
+                or not isinstance(e.get('filter'), dict):
+            p.add('peers[%d] must be {pubkey (64 hex), shard, filter (object)[, pull_every]}' % i)
+        elif 'pull_every' in e and not positive_int(e['pull_every']):
+            p.add('peers[%d].pull_every must be a positive integer' % i)
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'PeerPull':
+        return cls(pubkey=raw['pubkey'], shard=raw['shard'], filter=dict(raw['filter']),
+                   pull_every=int(raw.get('pull_every', 900)), window=raw.get('window'))
+
+
+@dataclasses.dataclass(frozen=True)
+class CoverageClaim(Block):
+    """A shard this node tells the mesh it holds, as a kind 30803 claim."""
+    shard: str
+    filter: Mapping[str, Any]
+    completeness: str = 'best-effort'
+    since: Optional[int] = None
+    until: Optional[int] = None
+
+    @staticmethod
+    def check_one(i: int, e: Any, p: Problems) -> None:
+        if not isinstance(e, Mapping) or not isinstance(e.get('shard'), str) or not isinstance(e.get('filter'), dict) \
+                or e.get('completeness', 'best-effort') not in COMPLETENESS:
+            p.add('coverage[%d] must be {shard, filter (object)[, completeness asserted|best-effort]}' % i)
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'CoverageClaim':
+        return cls(shard=raw['shard'], filter=dict(raw['filter']), completeness=raw.get('completeness', 'best-effort'),
+                   since=raw.get('since'), until=raw.get('until'))
+
+
+@dataclasses.dataclass(frozen=True)
+class TrustDecision(Block):
+    """An operator's out-of-band decision about a peer: a tier, and when."""
+    tier: str
+    at: int = 0
+
+    @staticmethod
+    def check_one(pk: Any, e: Any, p: Problems) -> None:
+        tier = e.get('tier') if isinstance(e, Mapping) else e
+        if not is_hex64(pk) or tier not in TIERS or (isinstance(e, Mapping) and not is_int(e.get('at', 0))):
+            p.add('trust[%s] must be a tier name or {tier, at}' % str(pk)[:16])
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'TrustDecision':
+        if isinstance(raw, Mapping):
+            return cls(tier=raw['tier'], at=int(raw.get('at', 0)))
+        return cls(tier=raw)
+
+
+# How far in the future the relay face accepts an event. The face constant
+# (node/relayserver.py) is defined from this one: the config layer imports
+# nothing that reaches a crypto dependency, so a tool that only reads config
+# needs none.
+FACE_FUTURE_MAX_SECONDS: int = 900
+
+
+@dataclasses.dataclass(frozen=True)
+class FaceConfig(Block):
+    """The relay face: where it listens and how far in the future it accepts."""
+    key = 'face'
+    host: str = '127.0.0.1'
+    port: int = 0
+    future_seconds: int = FACE_FUTURE_MAX_SECONDS
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping) or not isinstance(raw.get('host', '127.0.0.1'), str) \
+                or not is_int(raw.get('port', 0)) or not 0 <= raw.get('port', 0) <= 65535:
+            p.add('face must be {host, port} with a port from 0 to 65535')
+        elif 'future_seconds' in raw and not non_negative_int(raw['future_seconds']):
+            p.add('face.future_seconds must be a non-negative integer')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'FaceConfig':
+        return cls(host=raw.get('host', '127.0.0.1'), port=int(raw.get('port', 0)),
+                   future_seconds=int(raw.get('future_seconds', FACE_FUTURE_MAX_SECONDS)))
+
+
+from .parameter import Parameter, ParamBlock
+
+
+@dataclasses.dataclass(frozen=True)
+class PolicyConfig(ParamBlock):
+    """Whether strangers may enrol, and which protocols a peer must speak."""
+    key = 'policy'
+    open_enrolment: bool = True
+    protocols: tuple[str, ...] = ()
+    DERIVED: bool = False
+    PARAMS = (
+        Parameter(
+            key='open_enrolment', name='Open Enrolment',
+            description='Whether strangers may enrol without prior grant',
+            type=bool, default=True, tags=('peering', 'policy'),
+        ),
+        Parameter(
+            key='protocols', name='Required Protocols',
+            description='Protocols a peer must speak to peer with this node',
+            type=list, item=str, default=(), tags=('peering', 'policy'),
+        ),
+    )
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping) or not isinstance(raw.get('open_enrolment', True), bool):
+            p.add('policy must be an object with a boolean open_enrolment')
+        else:
+            opt(raw, 'protocols', all_str, p, 'policy.protocols must be a list of identifiers')
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> 'PolicyConfig':
+        return cls(open_enrolment=bool(raw.get('open_enrolment', True)), protocols=tuple(raw.get('protocols') or ()))
+
+
+__all__ = ['Endpoint', 'PeerPull', 'CoverageClaim', 'TrustDecision', 'FaceConfig', 'PolicyConfig',
+           'TIERS', 'CLASSES', 'COMPLETENESS', 'HANDOVER']

node/examples/__init__.py

@@ -0,0 +1 @@
+"""Programs that use a node from outside it; each is run by a test."""

node/examples/demo.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""The MVP, end to end, in one run.
+
+    python3 node/demo.py
+
+Three nodes and one public relay, all in this process. A client posts to node
+A over ordinary NIP-01. A and B find each other's descriptors on the relay,
+peer over DIDComm, publish their grants, and negentropy moves the events to B.
+Receipts flow, a window closes clean, and the grant is amended. Then the
+reference's bad peer is pointed at A and a kind 30802 comes out.
+
+Nothing is mocked and nothing is stubbed: real BIP-340 signatures, real
+NIP-44 envelopes, real gift wraps, real websockets, real SQLite. The clock is
+the only thing driven by hand, because a window is an hour long.
+"""
+from __future__ import annotations
+
+import functools
+import json
+import os
+import sys
+import tempfile
+import time
+from typing import Any, Callable, Mapping, cast
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), '..')))
+from node import app as app_mod  # noqa: E402
+from node.protocols.nostr import relayserver  # noqa: E402
+from node.storage import grants  # noqa: E402
+from node.protocols.nostr import client as relay  # noqa: E402
+from fleetmesh_core.accounting import accounting, window  # noqa: E402
+from fleetmesh_core.crypto import crypto  # noqa: E402
+from fleetmesh_core.peering import badpeer, reports  # noqa: E402
+from fleetmesh_core.storage import store  # noqa: E402
+from fleetmesh_core.wire.interfaces import WindowEvaluationDetail  # noqa: E402
+
+W: int = 3600
+NOW: int = (1787100000 // W) * W + 100
+T: list[int] = [NOW]
+clock: Callable[[], int] = lambda: T[0]
+OPERATOR: str = crypto.pubkey('33' * 32)
+BRISTOL: Mapping[str, Any] = {'kinds': [1], '#t': ['bristol']}
+STEP: list[int] = [0]
+
+
+def say(line: str = '') -> None:
+    print(line)
+
+
+def step(title: str) -> None:
+    STEP[0] += 1
+    print('\n\033[1m%d. %s\033[0m' % (STEP[0], title))
+
+
+def wait_for(pred: Callable[[], bool], seconds: float = 20.0) -> bool:
+    """Poll until `pred` holds or the clock runs out. The demo asserts its
+    own steps rather than sleeping past them."""
+    deadline = time.time() + seconds
+    while time.time() < deadline and not pred():
+        time.sleep(0.05)
+    return pred()
+
+
+def main() -> None:
+    tmp = tempfile.mkdtemp(prefix='fleetmesh-demo-')
+    public = relayserver.RelayServer(clock=clock, name='public-relay').start()
+    relays = [public.url]
+
+    def node(name: str, **over: Any) -> app_mod.NodeApp:
+        cfg = dict(app_mod.defaults(), **{'relays': relays, 'operator': OPERATOR, 'pow_bits': 8,
+                                          'name': name, 'tick_seconds': 1})
+        cfg.update(over)
+        d = os.path.join(tmp, name)
+        app_mod.save_config(d, {k: v for k, v in cfg.items() if not k.startswith('_')})
+        return app_mod.NodeApp(d, cfg, clock=clock).start()
+
+    step('Two nodes start. Each mines a descriptor and publishes it.')
+    A, B = node('alpha'), node('beta')
+    time.sleep(0.5)
+    for n in (A, B):
+        say('   %-6s %s' % (n.cfg['name'], n.ks.did))
+        say('          relay face %s   descriptor %s' % (n.face.url, n._descriptor()['id'][:16]))
+    found = relay.query_all(relays, [{'kinds': [11801]}])
+    say('   the public relay holds %d descriptors; neither node was told the other exists' % len(found))
+
+    step('A client posts to A over ordinary NIP-01. A is just a relay to it.')
+    client = relay.Relay(A.face.url, timeout=5)
+    posted = []
+    for i in range(6):
+        ev = store.make_signed_event('77' * 32, NOW - 100 + i, 1, [['t', 'bristol']], 'bristol note %d' % i)
+        accepted, note = client.publish(ev)
+        posted.append(ev)
+    off = store.make_signed_event('77' * 32, NOW - 90, 1, [['t', 'cardiff']], 'a note from elsewhere')
+    client.publish(off)
+    say('   posted 6 events tagged bristol and 1 tagged cardiff; A accepted all 7')
+
+    step('B resolves A from the relay, peers with it, and pulls the shard.')
+    B.cfg['peers'] = [{'pubkey': A.ks.node_pk, 'shard': 'bristol', 'filter': BRISTOL, 'pull_every': 600}]
+    app_mod.save_config(B.dir, {k: v for k, v in B.cfg.items() if not k.startswith('_')})
+    did = B.tick()
+    for d in did:
+        say('   %s' % ' '.join(str(x)[:24] for x in d))
+    held = B.grants.get(A.ks.node_pk, grants.RECEIVED)
+    assert held is not None, 'B took no grant from A'      # the peering above must have landed
+    g = held['payload']
+    say('   B holds a grant from A: tier %s, events_in %d, window %ds' % (g['tier'], g['limits']['events_in'], g['window']))
+    env = relay.query_all(relays, [{'ids': [held['envelope_id']]}])[0]
+    say('   its kind 30801 on the relay shows only %s' % ', '.join(sorted({t[0] for t in env['tags']})))
+    say('   B now holds %d events; the cardiff one did not cross' % len(B.store._all()))
+    say('   both stores fingerprint the shard as %s' % A.store.fingerprint_range(BRISTOL, 0, 2 ** 31, T[0]))
+
+    step('B accounts for what it used. A acknowledges.')
+    T[0] += 700
+    for d in B.tick():
+        say('   %s' % ' '.join(str(x)[:24] for x in d))
+    wait_for(lambda: B.budget.acks.get(A.ks.node_pk) is not None)
+    E0 = accounting.epoch(NOW, W)
+    r = A.budget.receipts_in[B.ks.node_pk][E0][0]
+    say('   receipt seq %d: %s' % (r['seq'], ', '.join('%s=%s' % kv for kv in sorted(r['counters'].items()))))
+    say('   A answers: %s' % B.budget.acks[A.ks.node_pk]['status'])
+
+    step('The window closes. A evaluates it and amends the grant.')
+    T[0] = (E0 + 1) * W + 100
+    B.tick()
+    wait_for(lambda: len(A.budget.receipts_in.get(B.ks.node_pk, {}).get(E0, [])) >= 2)
+    T[0] = (E0 + 1) * W + 400
+    A.tick()
+    rec = [x for x in A.budget.evaluations if x.peer == B.ks.node_pk][0]
+    say('   window %d: measured against B\'s last receipt, severity %s' % (rec.epoch, rec.severity))
+    say('   remedy: %s, in force from window %s' % (rec.note, rec.effective_from))
+    T[0] = (E0 + 2) * W + 5
+    A.tick()
+    issued = A.grants.get(B.ks.node_pk, grants.ISSUED)
+    assert issued is not None, 'A holds no grant for B'
+    new_env = issued['envelope_id']
+    wait_for(lambda: (r := B.grants.get(A.ks.node_pk, grants.RECEIVED)) is not None and r.get('envelope_id') == new_env)
+    say('   at the boundary A published it and B took it up: %s' % new_env[:16])
+    say('   A published nothing else about it: a clean window is not an event')
+
+    step('A bad peer joins. It floods A with events A already holds.')
+    Flood = functools.partial(badpeer.BadPeer, offence='duplicate-flood', flood=8)
+    D = node('delta', _session_cls=Flood)
+    time.sleep(0.5)
+    dclient = relay.Relay(D.face.url, timeout=5)
+    for i in range(10):
+        dclient.publish(store.make_signed_event('88' * 32, NOW - 50 + i, 1, [['t', 'bristol']], 'flood %d' % i))
+    A.propose(D.ks.node_pk, 'bristol', BRISTOL, timeout=20)
+    wait_for(lambda: D.grants.get(A.ks.node_pk, grants.RECEIVED) is not None)
+    epoch_now = accounting.epoch(T[0], W)
+    say('   A peered with it and asked for 10 events')
+    res = A.pull(D.ks.node_pk, 'bristol', BRISTOL, timeout=40)
+    say('   it sent %d, of which %d were duplicates: a ratio of %.3f against a ceiling of %s'
+        % (res['counters']['events_in'], res['counters']['dups_sent'], res['dup_ratio'],
+           window.C['tier_limits']['dup_ratio']['all_tiers']))
+    say('   it never sent a receipt for any of it')
+
+    step('A prices that window, and keeps the finding to itself.')
+    T[0] = (epoch_now + 1) * W + int(W * 0.1) + 1
+    A.tick()
+    rec = [x for x in A.budget.evaluations if x.peer == D.ks.node_pk][0]
+    say('   window %d: %s, %s' % (rec.epoch, rec.state, rec.severity))
+    dup = cast(WindowEvaluationDetail, rec.detail['dup_ratio'])
+    say('   priced on the ratio alone: overrun %.2f over the ceiling' % dup['overrun'])
+    say('   remedy: %s' % rec.note)
+    unpub = [u for u in A.reporter.unpublishable if u[0] == D.ks.node_pk]
+    say('   A holds an S3 against D and will not publish it:')
+    for reason in unpub[0][3]:
+        say('       %s' % reason)
+    say('   D sent no receipt, so D signed nothing this window that A could quote.')
+    say('   Silence is the one case with no evidence to have: neither half of the claim')
+    say('   is checkable by a reader, so A says nothing in public and zeroes the grant.')
+
+    step('An offence that leaves something signed behind.')
+    Push = functools.partial(badpeer.BadPeer, offence='out-of-scope-push')
+    E = node('epsilon', _session_cls=Push)
+    time.sleep(0.5)
+    someone_else = store.make_signed_event('aa' * 32, T[0] - 20, 1, [['t', 'cardiff']], 'a note E did not write')
+    E.store.insert_event(someone_else, T[0])
+    eclient = relay.Relay(E.face.url, timeout=5)
+    for i in range(2):
+        eclient.publish(store.make_signed_event('99' * 32, T[0] - 30 + i, 1, [['t', 'bristol']], 'shard note %d' % i))
+    A.propose(E.ks.node_pk, 'bristol', BRISTOL, timeout=20)
+    wait_for(lambda: E.grants.get(A.ks.node_pk, grants.RECEIVED) is not None)
+    res2 = A.pull(E.ks.node_pk, 'bristol', BRISTOL, timeout=40)
+    say('   E served the shard and slipped in an event tagged cardiff, written by somebody else')
+    say('   A refused it: %s' % (res2['findings'][0][1][:76] if res2['findings'] else 'nothing refused'))
+    say('   E wrote no part of that event, but it signed the hop that carried it,')
+    say('   and the report carries that envelope whole, so a reader checks it against E\'s key')
+    published = [p for p in A.reporter.published if any(t[:2] == ['d', E.ks.node_pk] for t in p['tags'])]
+    if published:
+        report = published[0]
+        say('   kind 30802 %s, signed by A, on the public relay:' % report['id'][:16])
+        for t in report['tags']:
+            say('       %s' % ' '.join(t)[:96])
+        inline = reports.inline_evidence(report)
+        say('   its content carries the cited artefact, %d bytes, resolving nothing:' % len(report['content']))
+        say('       %s' % json.dumps(list(inline.values())[0])[:92])
+
+    step('What a third party makes of it.')
+    C = node('gamma')
+    time.sleep(0.5)
+    about = C.reporter.reports_about(E.ks.node_pk)
+    say('   C finds %d report(s) about E; admissible: %s' % (len(about), [a['admissible'] for a in about]))
+    view, weights = C.reporter.view(E.ks.node_pk)
+    if weights:
+        say('   C holds no grant to A, so A weighs %.1f and C\'s view of E stays %s' % (weights[0]['weight'], view))
+        for e in range(168):
+            C.reporter.ledger.record(A.ks.node_pk, 496000 + e, 'S0', 'anchor')
+        view, weights = C.reporter.view(E.ks.node_pk)
+        say('   after a week of clean windows with A, A weighs %.1f and C\'s view of E becomes %s'
+            % (weights[0]['weight'], view))
+        say('   nobody imported anybody\'s ban: C ran the arithmetic itself')
+
+    say()
+    say('\033[1mThe whole protocol, once, over a wire.\033[0m')
+    say('  %d nodes, %d relay, %d events stored at A, %d grants issued, %d report published, %d withheld'
+        % (5, 1, len(A.store._all()), len(A.grants.list(grants.ISSUED)), len(A.reporter.published),
+           len(A.reporter.unpublishable)))
+    say('  state in %s' % tmp)
+    for n in (A, B, C, D, E):
+        n.stop()
+    public.stop()
+
+
+if __name__ == '__main__':
+    main()