3.1.4. Services Plane (fleetmesh_node.planes.services)
The Services Plane hosts higher-level application services: value transfers, paid resource fetching, sidecars, compute execution, DVM translation, gossip, and decentralized hosting.
3.1.4.1. Settlement Compartment
Experimental
In the code and tested, but not supported in this alpha: it may change or go away. See Experimental features.
The Settlement compartment: the operator verbs over the engine and the rails. Built from the operator’s settlement config block.
- class fleetmesh_node.planes.services.settle.compartment.Settlement[source]
Bases:
CompartmentThe settlement compartment of meshnode (NIP-61 Nutzap & Lightning hold-invoices).
- config_cls
alias of
SettlementConfig
- SCHEMA: tuple[Any, ...] = (Table(name='escrows', columns=(Column(name='ask_id', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='buyer', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='seller', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='amount_msat', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='payment_hash', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='preimage', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='status', type='TEXT', nullable=False, primary_key=False, default="'CREATED'", unique=False), Column(name='rail', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='created_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='settled_at', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False)), primary_key=(), indices=(Index(name='idx_escrows_hash', columns=('payment_hash',), table='escrows', unique=False),), without_rowid=False), Table(name='spent_proofs', columns=(Column(name='secret', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='keyset_id', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='amount', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False), Column(name='spent_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False))
- STORES: tuple[Store, ...] = (Store(key='escrows', description='settlement escrows held in sqlite database', kind='ring', shape=<class 'dict'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()),)
- NEEDS: tuple[Any, ...] = (Need(key='db_path', source=None, block=None, late=False, getter=False, path='DB', field=None), Need(key='node_pk', source='pubkey', block=None, late=False, getter=False, path=None, field=None), Need(key='settings', source=None, block=<class 'fleetmesh_node.config.compartments.SettlementConfig'>, late=False, getter=False, path=None, field=None), Need(key='ks', source='ks', block=None, late=False, getter=False, path=None, field=None), Need(key='grants', source='stores.grants', block=None, late=False, getter=False, path=None, field=None))
- CHANNELS: tuple[Any, ...] = (Channel(name='escrow_created', description='A settlement escrow was created for a compute ask', level='info', wire=None, say='created escrow {ask} for {amount_msat} msat (rail: {rail})', tags=('settle', 'escrow')), Channel(name='escrow_held', description='A settlement escrow was locked in held state', level='info', wire=None, say='escrow {ask} held', tags=('settle', 'escrow')), Channel(name='escrow_settled', description='A settlement escrow was settled upon preimage disclosure', level='info', wire=None, say='escrow {ask} settled', tags=('settle', 'escrow')), Channel(name='escrow_cancelled', description='A settlement escrow was cancelled and released', level='note', wire=None, say='escrow {ask} cancelled (reason: {reason})', tags=('settle', 'escrow')), Channel(name='grant_expanded', description='Peer rate-bucket grant limits expanded with Nutzap', level='info', wire=None, say='grant expanded for peer {peer} via nutzap', tags=('settle', 'nutzap')))
- METRICS: tuple[Any, ...] = (Metric(name='settlement_escrows_created', description='Escrows created for compute tasks.', kind='counter', unit='', labels=(), counts='escrow_created', sample=None, buckets=(), tags=('settle', 'escrow')), Metric(name='settlement_escrows_held', description='Escrows locked into held state.', kind='counter', unit='', labels=(), counts='escrow_held', sample=None, buckets=(), tags=('settle', 'escrow')), Metric(name='settlement_escrows_settled', description='Escrows settled with preimage.', kind='counter', unit='', labels=(), counts='escrow_settled', sample=None, buckets=(), tags=('settle', 'escrow')), Metric(name='settlement_escrows_cancelled', description='Escrows cancelled.', kind='counter', unit='', labels=(), counts='escrow_cancelled', sample=None, buckets=(), tags=('settle', 'escrow')), Metric(name='settlement_grants_expanded', description='Grants expanded via ecash Nutzap.', kind='counter', unit='', labels=(), counts='grant_expanded', sample=None, buckets=(), tags=('settle', 'nutzap')))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='Settlement Status', description='display active settlement rails and escrows', tags=('settle', 'status'), parameters=(), permission='settle/show', process=(), run='show_cmd', reply='dict', reads=(), writes=()), Command(key='create', name='Create Escrow', description='create conditional hold escrow for a compute ask', tags=('settle', 'escrow'), parameters=(Parameter(key='ask', name='ask', description='ask identifier', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='buyer', name='buyer', description='buyer public key', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='seller', name='seller', description='seller public key', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='amount_msat', name='amount_msat', description='escrow amount in millisatoshis', type=<class 'int'>, default=0, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='hash', name='hash', description='payment hash', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='rail', name='rail', description='settlement rail name', type=<class 'str'>, default='lightning', must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='settle/create', process=(), run='create_cmd', reply='dict', reads=(), writes=()), Command(key='hold', name='Hold Escrow', description='transition escrow to HELD state upon locked payment', tags=('settle', 'hold'), parameters=(Parameter(key='ask', name='ask', description='ask identifier', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='proof', name='proof', description='proof or token payload', type=<class 'object'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='settle/hold', process=(), run='hold_cmd', reply='bool', reads=(), writes=()), Command(key='settle', name='Settle Escrow', description='settle escrow upon disclosed preimage', tags=('settle', 'settle'), parameters=(Parameter(key='ask', name='ask', description='ask identifier', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='preimage', name='preimage', description='payment preimage hex', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='settle/settle', process=(), run='settle_cmd', reply='bool', reads=(), writes=()), Command(key='reconcile', name='Reconcile Escrow', description='reconcile variable token escrow with delta refund', tags=('settle', 'reconcile'), parameters=(Parameter(key='ask', name='ask', description='ask identifier', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='cost_msat', name='cost_msat', description='actual cost in millisatoshis', type=<class 'int'>, default=0, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='preimage', name='preimage', description='payment preimage hex', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='settle/reconcile', process=(), run='reconcile_cmd', reply='dict', reads=(), writes=()), Command(key='stream_pay', name='Stream Payment', description='record pay-as-you-stream Nutzap token milestone', tags=('settle', 'stream'), parameters=(Parameter(key='ask', name='ask', description='ask identifier', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='tokens', name='tokens', description='delta tokens', type=<class 'int'>, default=0, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='rate', name='rate', description='millisatoshis per token', type=<class 'int'>, default=0, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='proof', name='proof', description='cashu token proof', type=<class 'object'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='settle/stream_pay', process=(), run='stream_pay_cmd', reply='dict', reads=(), writes=()), Command(key='cancel', name='Cancel Escrow', description='cancel escrow and refund locked funds', tags=('settle', 'cancel'), parameters=(Parameter(key='ask', name='ask', description='ask identifier', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='reason', name='reason', description='cancellation reason', type=<class 'str'>, default='', must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='settle/cancel', process=(), run='cancel_cmd', reply='bool', reads=(), writes=()), Command(key='nutzap', name='Create Nutzap', description='create signed NIP-61 Kind 9321 Nutzap event', tags=('settle', 'nutzap'), parameters=(Parameter(key='recipient', name='recipient', description='recipient public key', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='amount_msat', name='amount_msat', description='payment amount in millisatoshis', type=<class 'int'>, default=0, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='proofs', name='proofs', description='Cashu proofs list or json', type=<class 'object'>, default=<class 'list'>, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='mint', name='mint', description='mint url', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='target_event', name='target_event', description='target event id', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='settle/nutzap', process=(), run='nutzap_cmd', reply='dict', reads=(), writes=()), Command(key='expand_grant', name='Expand Grant', description='expand peer rate-bucket limits with verified Nutzap proofs', tags=('settle', 'grants'), parameters=(Parameter(key='peer', name='peer', description='peer public key', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='nutzap', name='nutzap', description='nutzap event dict or json', type=<class 'object'>, default=<class 'dict'>, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='settle/expand_grant', process=(), run='expand_grant_cmd', reply='dict', reads=(), writes=()), Command(key='nwc_pay', name='Pay NWC Invoice', description='pay a Lightning invoice via NWC to unlock escrow', tags=('settle', 'nwc'), parameters=(Parameter(key='hash', name='hash', description='payment hash hex', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='bolt11', name='bolt11', description='bolt11 payment invoice', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='settle/nwc_pay', process=(), run='nwc_pay_cmd', reply='dict', reads=(), writes=()), Command(key='cashu_swap', name='Swap Cashu Proofs', description='swap held Cashu proofs for fresh blinded tokens at the live mint', tags=('settle', 'cashu'), parameters=(Parameter(key='hash', name='hash', description='payment hash hex', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='outputs', name='outputs', description='blinded outputs list or json', type=<class 'object'>, default=<class 'list'>, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='settle/cashu_swap', process=(), run='cashu_swap_cmd', reply='dict', reads=(), writes=()), Command(key='cashu_melt', name='Melt Cashu Proofs', description='melt held Cashu proofs to pay an external Lightning invoice', tags=('settle', 'cashu'), parameters=(Parameter(key='hash', name='hash', description='payment hash hex', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='bolt11', name='bolt11', description='bolt11 payment invoice', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='settle/cashu_melt', process=(), run='cashu_melt_cmd', reply='dict', reads=(), writes=()))
- __init__(node=None, db_path=None, node_pk=None, settings=None, clock=None, ks=None, grants=None, db=None)[source]
Built by from_context in a node. Settlement() and Settlement(node=fake) still work: what is not passed is read off node (dir, ks, cfg[‘settlement’]) when it has it, else defaulted.
settings is the operator’s settlement config block: nwc_uri, live_cashu, mint_url.
- commands: Mapping[str, CommandSpec] = {'cancel': {'args': {'ask': 'required', 'reason': 'optional'}, 'does': 'cancel escrow and refund locked funds', 'reply': 'bool', 'subsystem': 'settle'}, 'cashu_melt': {'args': {'bolt11': 'required', 'hash': 'required'}, 'does': 'melt held Cashu proofs to pay an external Lightning invoice', 'reply': 'dict', 'subsystem': 'settle'}, 'cashu_swap': {'args': {'hash': 'required', 'outputs': 'required'}, 'does': 'swap held Cashu proofs for fresh blinded tokens at the live mint', 'reply': 'dict', 'subsystem': 'settle'}, 'create': {'args': {'amount_msat': 'required', 'ask': 'required', 'buyer': 'required', 'hash': 'required', 'rail': 'optional', 'seller': 'required'}, 'does': 'create conditional hold escrow for a compute ask', 'reply': 'dict', 'subsystem': 'settle'}, 'expand_grant': {'args': {'nutzap': 'required', 'peer': 'required'}, 'does': 'expand peer rate-bucket limits with verified Nutzap proofs', 'reply': 'dict', 'subsystem': 'settle'}, 'hold': {'args': {'ask': 'required', 'proof': 'optional'}, 'does': 'transition escrow to HELD state upon locked payment', 'reply': 'bool', 'subsystem': 'settle'}, 'nutzap': {'args': {'amount_msat': 'required', 'mint': 'optional', 'proofs': 'required', 'recipient': 'required', 'target_event': 'optional'}, 'does': 'create signed NIP-61 Kind 9321 Nutzap event', 'reply': 'dict', 'subsystem': 'settle'}, 'nwc_pay': {'args': {'bolt11': 'required', 'hash': 'required'}, 'does': 'pay a Lightning invoice via NWC to unlock escrow', 'reply': 'dict', 'subsystem': 'settle'}, 'reconcile': {'args': {'ask': 'required', 'cost_msat': 'required', 'preimage': 'required'}, 'does': 'reconcile variable token escrow with delta refund', 'reply': 'dict', 'subsystem': 'settle'}, 'settle': {'args': {'ask': 'required', 'preimage': 'required'}, 'does': 'settle escrow upon disclosed preimage', 'reply': 'bool', 'subsystem': 'settle'}, 'show': {'args': {}, 'does': 'display active settlement rails and escrows', 'reply': 'dict', 'subsystem': 'settle'}, 'stream_pay': {'args': {'ask': 'required', 'proof': 'optional', 'rate': 'required', 'tokens': 'required'}, 'does': 'record pay-as-you-stream Nutzap token milestone', 'reply': 'dict', 'subsystem': 'settle'}}
3.1.4.2. Settlement Engine
Experimental
In the code and tested, but not supported in this alpha: it may change or go away. See Experimental features.
SettlementEngine: multi-rail escrow lifecycle (create / hold / settle / reconcile / cancel / stream), and the one asymmetric-settlement write - expanding a peer’s grant with a verified nutzap, bounded by the paid ceiling for its tier.
- fleetmesh_node.planes.services.settle.engine.paid_ceilings(tier)[source]
The most a paid grant at tier may hold on each limit.
- class fleetmesh_node.planes.services.settle.engine.SettlementEngine[source]
Bases:
objectManages multi-rail escrow lifecycle and proof persistence.
- __init__(db_path=':memory:', clock=None, mint_url=None, mint_privkey_hex=None, nwc_uri=None, use_live_cashu=False, node_pk=None, allow_unverified_proofs=False, db=None)[source]
- register_rail(rail_id, rail)[source]
- Parameters:
rail_id (str)
rail (PaymentRail)
- Return type:
None
- cashu_rail()[source]
The cashu rail, or a clear error when an operator registered something under that name that is not one.
- Return type:
CashuPaymentRail
- create_escrow(ask_id, buyer_pk, seller_pk, amount_msat, payment_hash, rail_id='lightning')[source]
Create a new escrow entry across chosen settlement rail.
- settle_escrow(ask_id, preimage)[source]
Settle escrow upon disclosure of verified preimage.
Under the engine lock and one sqlite transaction: the row is moved to SETTLED first, then the rail; a rail refusal raises inside the transaction so the row rolls back. The rail only changes state after the DB write has succeeded, so a crash between the two leaves at worst a SETTLED row for an escrow the (in-memory) rail will rebuild from it, never a settled rail with a HELD row.
- cancel_escrow(ask_id, reason='')[source]
Cancel escrow and refund locked funds. Same lock + transaction discipline as settle_escrow; a rail that refuses the cancel (already settled under us) rolls the row back.
- reconcile_escrow(ask_id, actual_cost_msat, preimage)[source]
Reconcile a variable-length token escrow (Pre-Funded Escrow with Delta Refund).
The seller claims actual metered cost (N_tokens * rate <= amount_msat) using preimage k, and the remainder (amount_msat - actual_cost_msat) is refunded to the buyer.
- stream_micropayment(ask_id, delta_tokens, rate_msat_per_token, cashu_token=None)[source]
Process Pay-As-You-Stream micropayment milestone (Cashu Nutzap).
- get_escrow(ask_id)[source]
Retrieve escrow record by ask_id.
- Parameters:
ask_id (str)
- Return type:
EscrowRowDict | None
- expand_grant_with_nutzap(grant_store, peer_pk, nutzap_event, conversion_rate=None)[source]
Asymmetric settlement: expand peer grant rate-buckets upon receiving verified Nutzap.
Spec reference: spec.html line 7268 (Bridge 4: NIP-61 Cashu Nutzap Asymmetric Settlement).
Order matters: the nutzap is verified (recipient, amount, proofs) and the grant is found and clamped BEFORE any secret is marked spent, so a refused expansion never burns the payer’s proofs. The spent check, the grant read, the clamp and the two writes all happen under self._lock: two threads presenting the same nutzap used to both pass the check outside the lock and both credit the grant.
Custody caveat: the proofs are VERIFIED (mint key or NUT-07 check-state), not SWAPPED. Until a swap is wired in, the payer still holds proofs the mint considers unspent and could spend them elsewhere after this node credited the grant; the spent-secret ledger only protects this node from being paid twice with them. A rail that cannot verify at all (no mint key, no verifier, no explicit allow_unverified_proofs) is refused up front.
3.1.4.3. Paid Fetch Compartment
Experimental
In the code and tested, but not supported in this alpha: it may change or go away. See Experimental features.
Paid fetch: what a blob costs, who pays nothing, and how a Cashu payment is turned into finality before a byte is served.
Three pieces, each replaceable on its own:
Pricing (below) answers “what does this fetch cost?” from operator config, per-item prices in SQLite and the free allowance. It knows nothing about money moving.
MintBackend is the trust and settlement seam. AllowlistBackend is the one shipped: a list of mints the operator chose, tokens accepted only from those, finality by NUT-03 swap at that mint, earnings kept as fresh proofs in SQLite and swept to Lightning by NUT-05 melt above a threshold. A self-hosted nutshell, cdk-mintd or a Fedimint gateway is another MintBackend; the 402 and the verify path do not change.
PaidFetch is the subsystem: it owns both, builds the 402, checks a payment and records every refusal with its reason.
Every amount is msat inside the node. Cashu quotes in sat, so the edge rounds up: a 1 msat price costs 1 sat. That is the price of not carrying fractions of a sat as debt.
- Pricing rules (plan §3.4), first match wins:
fetcher is a partner or grantee and free_for_partners → 0
per-item operator price on this blob
first matching rule: min_bytes / content_type glob / uploader
default_msat (default 0)
A free allowance free_bytes_per_day, keyed by the fetcher’s key alone (anonymous fetches share one pool), is spent before any of these. Unset (None) means no free tier.
- class fleetmesh_node.planes.services.paidfetch.compartment.ProofStore[source]
Bases:
BaseSqliteStoreThe node’s own Cashu proofs (its earnings) and every proof it has taken in payment, by Y, so a token replayed after the swap is refused without a round trip to the mint.
- SCHEMA: tuple[Any, ...] = (Table(name='cashu_proofs', columns=(Column(name='y', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='mint', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='unit', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='keyset', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='amount', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='secret', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='c', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='state', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='received_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='spent_at', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False), Column(name='melted_at', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False)), primary_key=(), indices=(Index(name='idx_cashu_proofs_state', columns=('mint', 'state'), table='cashu_proofs', unique=False),), without_rowid=False), Table(name='cashu_taken', columns=(Column(name='y', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='mint', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='sha256', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='taken_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False), Table(name='account_proofs', columns=(Column(name='y', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='account', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='mint', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='proof_json', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(Index(name='idx_account_proofs_account', columns=('account',), table='account_proofs', unique=False),), without_rowid=False), Table(name='sales', columns=(Column(name='id', type='INTEGER', nullable=False, primary_key=True, default=None, unique=False), Column(name='subject', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='buyer', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='msat', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='mint', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='rail', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(Index(name='idx_sales_at', columns=('at',), table='sales', unique=False),), without_rowid=False), Table(name='melts', columns=(Column(name='quote', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='mint', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='amount_sat', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='fee_sat', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='bolt11', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='preimage', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='state', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False))
- MIGRATIONS: tuple[Migration | tuple[int, str], ...] = (Migration(version=1, up=('ALTER TABLE cashu_proofs ADD COLUMN melted_at INTEGER',), down=None, name='cashu_proofs_melted_at'),)
- add_proofs(mint, unit, proofs, now)[source]
- Parameters:
mint (str)
unit (str)
proofs (Sequence[CashuProof])
now (int)
- Return type:
None
- fleetmesh_node.planes.services.paidfetch.compartment.paidfetch_subject_is_blob(subject)[source]
A quote’s subject is a blob’s sha256 or a sidecar session’s ‘<name>:<id>’; the sales ledger labels the former ‘blob:<sha256>’.
- class fleetmesh_node.planes.services.paidfetch.compartment.AllowlistBackend[source]
Bases:
objectPlan §3.5 option (a): mints the operator chose, and nobody else’s IOUs.
verify() is the security boundary of the whole feature. It accepts a token only when: the mint is on the list, the unit matches, the amount covers the item, no proof was taken before, and the mint swaps the proofs for fresh ones this node blinded. After the swap the payer’s proofs are dead at the mint and the node’s are live: that is finality. A mint that is down is an Unpaid(‘mint unreachable’), never a pass.
- rail = 'cashu'
- class fleetmesh_node.planes.services.paidfetch.compartment.PriceStore[source]
Bases:
BaseSqliteStoreblob_prices(sha256, account, msat, set_by, at) and the daily allowance counters.
- SCHEMA: tuple[Any, ...] = (Table(name='blob_prices', columns=(Column(name='sha256', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='account', type='TEXT', nullable=False, primary_key=False, default="''", unique=False), Column(name='msat', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='set_by', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('sha256', 'account'), indices=(), without_rowid=False), Table(name='fetch_allowance', columns=(Column(name='fetcher', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='day', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='bytes', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('fetcher', 'day'), indices=(), without_rowid=False), Table(name='served_day', columns=(Column(name='who', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='day', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='bytes', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('who', 'day'), indices=(), without_rowid=False))
- class fleetmesh_node.planes.services.paidfetch.compartment.SessionStore[source]
Bases:
BaseSqliteStoreSidecar sessions let through the forward_auth check in front of a session-priced sidecar. A session has a start - the check passed - and no end the node can see: the proxy serves the rest of the protocol and never reports back. ended_at is therefore NULL today and the column is kept for the day a sidecar reports a close.
- SCHEMA: tuple[Any, ...] = (Table(name='sidecar_sessions', columns=(Column(name='id', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='sidecar', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='subject', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='peer', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='started_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='ended_at', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False), Column(name='msat', type='INTEGER', nullable=False, primary_key=False, default='0', unique=False)), primary_key=('sidecar', 'id'), indices=(Index(name='idx_sidecar_sessions_started', columns=('started_at',), table='sidecar_sessions', unique=False),), without_rowid=False),)
- class fleetmesh_node.planes.services.paidfetch.compartment.Pricing[source]
Bases:
object§3.4 as a function of (blob stat, fetcher, account).
- account_msat(stat, account)[source]
The fee an account put on its own upload, capped by the operator. Bound to (account, sha256), and only when the fetch names the account.
- class fleetmesh_node.planes.services.paidfetch.compartment.PaidFetch[source]
Bases:
CompartmentPrices fetches, issues 402s, verifies payment. Consulted by BlossomServer.
- config_cls
alias of
FetchPricingConfig
- SCHEMA: tuple[Any, ...] = (Table(name='blob_prices', columns=(Column(name='sha256', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='account', type='TEXT', nullable=False, primary_key=False, default="''", unique=False), Column(name='msat', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='set_by', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('sha256', 'account'), indices=(), without_rowid=False), Table(name='fetch_allowance', columns=(Column(name='fetcher', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='day', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='bytes', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('fetcher', 'day'), indices=(), without_rowid=False), Table(name='served_day', columns=(Column(name='who', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='day', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='bytes', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('who', 'day'), indices=(), without_rowid=False))
- STORE_CLS
alias of
PriceStore
- STORES: tuple[Store, ...] = (Store(key='receipts', description='recent fetch payment receipts', kind='ring', shape=<class 'dict'>, bound=1024, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()),)
- CHANNELS: tuple[Any, ...] = (Channel(name='fetch_paid', description='Blob fetch payment verified and settled', level='info', wire=None, say='fetch payment settled for {sha256} ({amount_msat} msat)', tags=('paidfetch', 'settle')), Channel(name='payment_refused', description='Blob fetch payment refused', level='note', wire=None, say='fetch payment refused: {reason}', tags=('paidfetch', 'payment')))
- METRICS: tuple[Any, ...] = (Metric(name='paidfetch_fetches_paid', description='Times fetches were paid.', kind='counter', unit='', labels=(), counts='fetch_paid', sample=None, buckets=(), tags=('paidfetch', 'settle')), Metric(name='paidfetch_payments_refused', description='Times fetch payments were refused.', kind='counter', unit='', labels=(), counts='payment_refused', sample=None, buckets=(), tags=('paidfetch', 'payment')))
- NEEDS: tuple[Any, ...] = (Need(key='cfg', source='cfg', block=None, late=False, getter=True, path=None, field=None), Need(key='db_path', source=None, block=None, late=False, getter=False, path='PRICES_DB', field=None), Need(key='grant_store', source='stores.grants', block=None, late=False, getter=False, path=None, field=None), Need(key='node_pk', source='pubkey', block=None, late=False, getter=False, path=None, field=None), Need(key='persist_cfg', source='persist_cfg', block=None, late=False, getter=False, path=None, field=None), Need(key='face', source='face', block=None, late=False, getter=False, path=None, field=None))
- COMMANDS: tuple[Any, ...] = (Command(key='price_set', name='Set Price', description='price one blob for fetching (account: a fee that account adds to its own upload)', tags=('paidfetch', 'price'), parameters=(Parameter(key='sha256', name='sha256', description='hex digest of blob to price', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='msat', name='msat', description='price in millisatoshis', type=<class 'int'>, default=0, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='account', name='account', description='a fee that account adds to its own upload', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='paidfetch/price_set', process=(), run='price_set_cmd', reply='dict', reads=(), writes=()), Command(key='price_get', name='Get Price', description='what one blob costs by rule and by item', tags=('paidfetch', 'price'), parameters=(Parameter(key='sha256', name='sha256', description='hex digest of blob', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='paidfetch/price_get', process=(), run='price_get_cmd', reply='dict', reads=(), writes=()), Command(key='price_clear', name='Clear Price', description='remove a per-item price', tags=('paidfetch', 'price'), parameters=(Parameter(key='sha256', name='sha256', description='hex digest of blob', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='account', name='account', description='account override to clear', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='paidfetch/price_clear', process=(), run='price_clear_cmd', reply='bool', reads=(), writes=()), Command(key='prices', name='List Prices', description='every per-item price set on this node', tags=('paidfetch', 'prices'), parameters=(), permission='paidfetch/prices', process=(), run='prices_cmd', reply='list', reads=(), writes=()), Command(key='rails', name='Payment Rails', description='the payment rails this node offers in a 402', tags=('paidfetch', 'rails'), parameters=(), permission='paidfetch/rails', process=(), run='rails_cmd', reply='dict', reads=(), writes=()), Command(key='wallet', name='Wallet Balance', description="this node's earnings held as ecash, by mint", tags=('paidfetch', 'wallet'), parameters=(), permission='paidfetch/wallet', process=(), run='wallet_cmd', reply='dict', reads=(), writes=()), Command(key='sweep', name='Sweep Wallet', description='move earnings above the threshold out to Lightning now', tags=('paidfetch', 'sweep'), parameters=(), permission='paidfetch/sweep', process=(), run='sweep_cmd', reply='dict', reads=(), writes=()), Command(key='grasp_price_set', name='Set GRASP Price', description='flat price for one GRASP git clone/fetch session (0: free)', tags=('paidfetch', 'grasp'), parameters=(Parameter(key='msat', name='msat', description='session price in millisatoshis', type=<class 'int'>, default=0, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='paidfetch/grasp_price_set', process=(), run='grasp_price_set_cmd', reply='dict', reads=(), writes=()), Command(key='grasp_price_get', name='Get GRASP Price', description='the current GRASP session price', tags=('paidfetch', 'grasp'), parameters=(), permission='paidfetch/grasp_price_get', process=(), run='grasp_price_get_cmd', reply='dict', reads=(), writes=()))
- __init__(cfg, db_path=':memory:', partners=None, node_pk=None, backend=None, clock=None, node=None, client_factory=None, persist_cfg=None, grant_store=None, face=None)[source]
- backend: MintBackend
- quote(stat, fetcher, account)[source]
None when the fetch is free (no 402, no headers). Otherwise the itemised price with one offer per item from the backend.
- session_msat(name)[source]
The flat per-session price for sidecar name (0: free). grasp_session_msat is the older spelling for grasp and wins.
- quote_session(subject, fetcher)[source]
A sidecar session (a GRASP git clone/fetch is the model), priced as one flat operator item - the proxy in front of a many-request protocol cannot meter individual objects, so the whole session is the billable unit. subject is <sidecar name>:<stable string> (repo pubkey and identifier is typical for git); the name picks the price (session_msat), the whole string stands in for a blob’s sha256 in the 402 and in settle(). It is never hashed or validated here, only quoted against and carried through to the backend.
- settle(quote, tokens, buyer=None)[source]
One token per item, in item order. Every item must verify; the first failure is the answer and nothing later is touched. An operator item that swapped before a later item fails stays swapped: the node was paid for it, and a refusal is recorded so the operator can see it.
Every operator item that verified is a row in the sales ledger, buyer being the fetcher’s pubkey when the request named one.
- note_session(subject, fetcher, msat)[source]
A sidecar session passed the forward_auth check: free, or paid msat through settle() just before this.
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- trouble()[source]
What an operator should be told without having to ask for it.
Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.
- descriptor_tags()[source]
What the kind 11801 says: the mints this node takes and that it prices fetches.
- commands: Mapping[str, CommandSpec] = {'grasp_price_get': {'args': {}, 'does': 'the current GRASP session price', 'reply': 'dict', 'subsystem': 'paidfetch'}, 'grasp_price_set': {'args': {'msat': 'required'}, 'does': 'flat price for one GRASP git clone/fetch session (0: free)', 'reply': 'dict', 'subsystem': 'paidfetch'}, 'price_clear': {'args': {'account': 'optional', 'sha256': 'required'}, 'does': 'remove a per-item price', 'reply': 'bool', 'subsystem': 'paidfetch'}, 'price_get': {'args': {'sha256': 'required'}, 'does': 'what one blob costs by rule and by item', 'reply': 'dict', 'subsystem': 'paidfetch'}, 'price_set': {'args': {'account': 'optional', 'msat': 'required', 'sha256': 'required'}, 'does': 'price one blob for fetching (account: a fee that account adds to its own upload)', 'reply': 'dict', 'subsystem': 'paidfetch'}, 'prices': {'args': {}, 'does': 'every per-item price set on this node', 'reply': 'list', 'subsystem': 'paidfetch'}, 'rails': {'args': {}, 'does': 'the payment rails this node offers in a 402', 'reply': 'dict', 'subsystem': 'paidfetch'}, 'sweep': {'args': {}, 'does': 'move earnings above the threshold out to Lightning now', 'reply': 'dict', 'subsystem': 'paidfetch'}, 'wallet': {'args': {}, 'does': "this node's earnings held as ecash, by mint", 'reply': 'dict', 'subsystem': 'paidfetch'}}
3.1.4.4. Sidecars Bridge Compartment
Sidecars: fronting off-the-shelf projects the node does not reimplement.
This compartment does not speak git smart-http, the OCI distribution protocol or Magpie’s media API itself - ngit-grasp, an ncontainer-compatible gateway and magpie already do, and reimplementing any of them (Option B, considered and rejected each time) buys nothing a sidecar does not already give for less code and less to keep current with upstream. What this compartment owns is the bridge:
which capabilities this node declares, and the endpoint tags a leaf reads to find the sidecar - all opt-in, all carried on the kind 11801 descriptor the same way mint/price already are (see PaidFetch.descriptor_tags).
whether the sidecar actually speaks its protocol. Every sidecar ships its own self-tests (a git info/refs, an OCI /v2/, a magpie files route): they run when the compartment starts, on the usual cadence after that, and on demand through the sidecar_test verb. A capability is declared ONLY while the tests pass - a config flag alone declares nothing - and when the verified set changes the compartment rebuilds the descriptor there and then, so a kind 11801 never advertises a protocol nothing behind this node can answer. A failing sidecar is trouble() the way every other mechanism here is.
nothing about payment: PaidFetch.quote_session (GRASP, coarse per clone/fetch session) and PaidFetch.quote (ncontainer and magpie, per blob - a resolved OCI digest or a Magpie file sha256 is priced exactly like any other Blossom fetch) are the payment surface, called from the reverse proxy in front of each sidecar, not from here.
What a sidecar IS lives in a manifest (fleetmesh_node/sidecar_manifest.py), not here: the node ships three in fleetmesh_node/planes/services/sidecars/manifests/ (grasp, ncontainer, magpie); an operator adds a fourth with sidecars.<name>.manifest; a plugin may declare more. This compartment reads the sidecars config block, resolves each entry to a manifest, runs the manifest’s checks and declares what passes. Adding a sidecar is a JSON file - not a change to this one.
A node with no sidecars block behaves exactly as before: no capability tag, no endpoint tag, nothing to test, nothing in trouble().
- fleetmesh_node.planes.services.sidecars.compartment.resolve_manifest(name, entry, extra={})[source]
The manifest a config entry stands for: inline or @file when given, else a built-in or plugin-declared manifest of that name. A manifest’s name must match the entry key it is configured under - the key is the systemd unit and the Caddy route, the manifest the protocol.
- class fleetmesh_node.planes.services.sidecars.compartment.ProbeResult[source]
Bases:
NamedTupleWhat one check said. status is the HTTP status when there was one.
- fleetmesh_node.planes.services.sidecars.compartment.run_check(fetch, endpoint, check)[source]
One check against one endpoint, never raising.
- class fleetmesh_node.planes.services.sidecars.compartment.Sidecars[source]
Bases:
CompartmentDeclares one capability per sidecar whose self-tests pass, and keeps testing the sidecars behind them. See module docstring for what it does not do.
- config_cls
alias of
SidecarsConfig
- STORES: tuple[Store, ...] = (Store(key='probes', description='recent sidecar probe results', kind='ring', shape=<class 'dict'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()),)
- CHANNELS: tuple[Any, ...] = (Channel(name='sidecar_verified', description='Sidecar self-tests passed and capability declared', level='info', wire=None, say='sidecar {name} verified and declared', tags=('sidecars', 'probe')), Channel(name='sidecar_failed', description='Sidecar self-test failed and capability retracted', level='note', wire=None, say='sidecar {name} self-test failed: {why}', tags=('sidecars', 'probe')))
- METRICS: tuple[Any, ...] = (Metric(name='sidecars_verified_total', description='Times sidecars verified.', kind='counter', unit='', labels=(), counts='sidecar_verified', sample=None, buckets=(), tags=('sidecars', 'probe')), Metric(name='sidecars_failed_total', description='Times sidecar probes failed.', kind='counter', unit='', labels=(), counts='sidecar_failed', sample=None, buckets=(), tags=('sidecars', 'probe')))
- NEEDS: tuple[Any, ...] = (Need(key='cfg', source='cfg', block=None, late=False, getter=True, path=None, field=None), Need(key='descriptor', source='descriptor', block=None, late=False, getter=False, path=None, field=None), Need(key='redescribe', source='redescribe', block=None, late=False, getter=False, path=None, field=None))
- EVERY: tuple[Any, ...] = (Every(seconds=300, run='_check_endpoints', name='_check_endpoints', report=None),)
- COMMANDS: tuple[Any, ...] = (Command(key='sidecars', name='Configured Sidecars', description='each configured sidecar, its endpoint, whether it is verified and its last self-test', tags=('sidecars', 'status'), parameters=(), permission='sidecars/sidecars', process=(), run='list_sidecars', reply='dict', reads=(), writes=()), Command(key='sidecar_test', name='Sidecar Self-Test', description='run the self-tests of one sidecar (or all) now and redeclare if the result changed', tags=('sidecars', 'test'), parameters=(Parameter(key='name', name='name', description='test: only this sidecar (default all enabled)', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='sidecars/sidecar_test', process=(), run='run_sidecar_test', reply='{name: {verified, checks: [{name, ok, status, why}], at}}', reads=(), writes=()))
- __init__(cfg, clock=None, checker=None, node=None, fetch=<function _http>, descriptor=None, redescribe=None)[source]
- Parameters:
- Return type:
None
- registry()[source]
Every sidecar this node knows of, in descriptor order: the built-ins, then plugin-declared ones, then any the operator named only by manifest. A configured entry whose manifest does not resolve is remembered as a manifest problem (trouble()) and skipped - a bad manifest declares nothing, same as a failing check.
- Return type:
list[Sidecar]
- declare(sidecar)[source]
A plugin (or test) adds a manifest the node did not ship. Refused under the reserved origin, like any other third-party manifest.
- Parameters:
sidecar (Sidecar)
- Return type:
None
- capability_protocols()[source]
Extra c protocol identifiers this node’s descriptor should carry, alongside the required ones descriptor.build always adds. Only the sidecars whose self-tests pass: enabling one declares nothing until it answers.
- descriptor_tags()[source]
<name>-endpoint, only for a verified sidecar - see schema/kinds.json’s note on kind 11801.
- test(name, now=None)[source]
Run one sidecar’s checks now. Records the verdict; does not redeclare.
- Parameters:
- Return type:
- redeclare_if_changed()[source]
Rebuild the descriptor when what should be declared differs from what the current one says. True when it was rebuilt.
- Return type:
- start()[source]
Test every enabled sidecar before anything is declared, and bring the descriptor into agreement at once rather than a cadence later.
- Return type:
None
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- trouble()[source]
What an operator should be told without having to ask for it.
Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.
- commands: Mapping[str, CommandSpec] = {'sidecar_test': {'args': {'name': 'optional'}, 'does': 'run the self-tests of one sidecar (or all) now and redeclare if the result changed', 'reply': '{name: {verified, checks: [{name, ok, status, why}], at}}', 'subsystem': 'sidecars'}, 'sidecars': {'args': {}, 'does': 'each configured sidecar, its endpoint, whether it is verified and its last self-test', 'reply': 'dict', 'subsystem': 'sidecars'}}
3.1.4.5. Compute Sandbox Compartment
Experimental
In the code and tested, but not supported in this alpha: it may change or go away. See Experimental features.
The Compute subsystem: node-side lifecycle, offer publication and job handling.
Owns its wire half: compute/wire/ (ComputeWire, ComputeSession, the compute/1.0 and /1.1 messages) is constructed here, and wire imports executors/jobs from this package - one direction, no cycle.
- class fleetmesh_node.planes.services.compute.compartment.Compute[source]
Bases:
Compartment- piuris: tuple[str, ...] = ('https://fleetmesh.org/compute/1.0', 'https://fleetmesh.org/compute/1.1')
- config_cls
alias of
ComputeConfig
- NEEDS: tuple[Any, ...] = (Need(key='ks', source='ks', block=None, late=False, getter=False, path=None, field=None), Need(key='blobs', source='stores.blobs', block=None, late=False, getter=False, path=None, field=None))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='Compute Status', description='display active compute offers, asks, and receipts', tags=('compute', 'status'), parameters=(), permission='compute/show', process=(), run='state', reply='dict', reads=(), writes=()), Command(key='offer', name='Publish Offer', description='publish a kind 11803 compute offer', tags=('compute', 'offer'), parameters=(Parameter(key='engine', name='engine', description='execution engine', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='msat_per_mfuel', name='msat_per_mfuel', description='price in msat per megabytes fuel', type=<class 'object'>, default=0, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='compute/offer', process=(), run='_cmd_offer', reply='dict', reads=(), writes=()), Command(key='ask', name='Publish Ask', description='publish a kind 30810 confidential compute ask', tags=('compute', 'ask'), parameters=(Parameter(key='id', name='id', description='ask id', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='job', name='job', description='job payload', type=<class 'dict'>, default=<class 'dict'>, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='bid', name='bid', description='bid amount', type=<class 'object'>, default=0, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='executor', name='executor', description='executor type', type=<class 'str'>, default='wasm', must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='verify', name='verify', description='verification mode', type=<class 'str'>, default='none', must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='compute/ask', process=(), run='_cmd_ask', reply='dict', reads=(), writes=()), Command(key='run', name='Run Job', description='execute a job payload and return signed kind 30811 receipt', tags=('compute', 'run'), parameters=(Parameter(key='job', name='job', description='job payload', type=<class 'dict'>, default=<class 'dict'>, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='buyer', name='buyer', description='buyer public key', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='preimage', name='preimage', description='payment preimage', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='paid_msat', name='paid_msat', description='paid amount in millisatoshis', type=<class 'int'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='payment_hash', name='payment_hash', description='payment hash', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='compute/run', process=(), run='_cmd_run', reply='dict', reads=(), writes=()), Command(key='submit', name='Submit or Reflect Job', description='execute a job locally when CPU headroom permits or reflect to a less-loaded mesh peer', tags=('compute', 'submit', 'reflection'), parameters=(Parameter(key='job', name='job', description='job payload', type=<class 'dict'>, default=<class 'dict'>, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='buyer', name='buyer', description='buyer public key', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='bid', name='bid', description='maximum bid in msat per mfuel', type=<class 'int'>, default=0, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='force_reflect', name='force_reflect', description='force reflection to a remote peer if available', type=<class 'bool'>, default=False, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='compute/submit', process=(), run='_cmd_submit', reply='dict', reads=(), writes=()), Command(key='load', name='Compute Load Snapshot', description='display live host CPU utilization, active worker slots, and reflection status', tags=('compute', 'load', 'metrics'), parameters=(), permission='compute/load', process=(), run='_cmd_load', reply='dict', reads=(), writes=()), Command(key='receipts', name='Job Receipts', description='list compute job receipts held', tags=('compute', 'receipts'), parameters=(), permission='compute/receipts', process=(), run='receipts_cmd', reply='list', reads=(), writes=()), Command(key='book', name='Order Book', description='display active order book offers and asks', tags=('compute', 'book'), parameters=(), permission='compute/book', process=(), run='book_cmd', reply='dict', reads=(), writes=()), Command(key='match', name='Match Orders', description='find matching counterparties in order book', tags=('compute', 'match'), parameters=(Parameter(key='ask', name='ask', description='ask id or event', type=<class 'object'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='offer', name='offer', description='offer id or event', type=<class 'object'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='compute/match', process=(), run='match_cmd', reply='list', reads=(), writes=()), Command(key='index_offer', name='Index Offer', description='index an external kind 11803 offer', tags=('compute', 'offer'), parameters=(Parameter(key='offer', name='offer', description='kind 11803 offer to index', type=<class 'object'>, default=<class 'dict'>, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='compute/index_offer', process=(), run='index_offer_cmd', reply='bool', reads=(), writes=()), Command(key='index_ask', name='Index Ask', description='index an external kind 30810 ask', tags=('compute', 'ask'), parameters=(Parameter(key='ask', name='ask', description='kind 30810 ask to index', type=<class 'object'>, default=<class 'dict'>, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='compute/index_ask', process=(), run='index_ask_cmd', reply='bool', reads=(), writes=()), Command(key='models', name='Compute Models', description='list available AI/LLM models and inference features', tags=('compute', 'models'), parameters=(), permission='compute/models', process=(), run='_cmd_models', reply='dict', reads=(), writes=()), Command(key='stream', name='Stream Inference', description='run a streaming AI/LLM inference query and return token deltas', tags=('compute', 'stream'), parameters=(Parameter(key='prompt', name='prompt', description='prompt text', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='model', name='model', description='model identifier', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='compute/stream', process=(), run='_cmd_stream', reply='dict', reads=(), writes=()), Command(key='link_provider', name='Link AI Provider', description='link an external or local AI/LLM inference provider to this meshnode', tags=('compute', 'models'), parameters=(Parameter(key='provider_id', name='provider_id', description='provider preset id (openrouter, claude, openai, gemini, copilot, routstr, payperquery, ollama, vllm)', type=<class 'str'>, default='openrouter', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='endpoint', name='endpoint', description='custom base endpoint URL', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='default_model', name='default_model', description='default model ID', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='api_key', name='api_key', description='operator API key or bearer secret', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='cashu_token', name='cashu_token', description='operator Cashu token for Routstr/PPQ', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='rate_msat_per_token', name='rate_msat_per_token', description='msat rate per token', type=<class 'int'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='enabled', name='enabled', description='whether provider is active', type=<class 'bool'>, default=True, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='set_default', name='set_default', description='set as primary provider', type=<class 'bool'>, default=True, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='compute/link_provider', process=(), run='_cmd_link_provider', reply='dict', reads=(), writes=()))
- STORES: tuple[Store, ...] = (Store(key='offers', description='offers published by this node, newest last', kind='ring', shape=None, bound=1024, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='asks', description='active asks placed by this node, by ask_id', kind='table', shape=None, bound=1024, evict='lru', keyed_by='ask', persist='memory', sensitive=False, tags=()), Store(key='order_book_offers', description='indexed offers from mesh peers, by offer_id', kind='table', shape=None, bound=4096, evict='lru', keyed_by='offer', persist='memory', sensitive=False, tags=()), Store(key='order_book_asks', description='indexed asks from mesh peers, by ask_id', kind='table', shape=None, bound=4096, evict='lru', keyed_by='ask', persist='memory', sensitive=False, tags=()), Store(key='receipts_held', description='job completion receipts held by this node, newest last', kind='ring', shape=None, bound=1024, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()))
- CHANNELS: tuple[Any, ...] = (Channel(name='job_executed', description='A compute task execution completed and receipt signed', level='note', wire=None, say='compute job {job_id} executed for buyer {buyer}', tags=('compute', 'execution')), Channel(name='job_reflected', description='A compute task was reflected to a less-loaded mesh peer', level='info', wire=None, say='compute job {job_id} reflected to peer {peer} ({reason})', tags=('compute', 'reflection')), Channel(name='offer_published', description='A compute engine capability offer was published', level='note', wire=None, say='compute offer published for engine {engine}', tags=('compute', 'market')), Channel(name='ask_published', description='A confidential compute ask was published to the mesh', level='note', wire=None, say='compute ask {ask_id} published bid {bid}', tags=('compute', 'market')))
- METRICS: tuple[Any, ...] = (Metric(name='compute_jobs_executed', description='Compute task executions completed.', kind='counter', unit='', labels=(), counts='job_executed', sample=None, buckets=(), tags=('compute', 'execution')), Metric(name='compute_jobs_reflected', description='Compute jobs reflected to less-loaded mesh peers.', kind='counter', unit='', labels=(), counts='job_reflected', sample=None, buckets=(), tags=('compute', 'reflection')), Metric(name='compute_offers_published', description='Compute engine offers published.', kind='counter', unit='', labels=(), counts='offer_published', sample=None, buckets=(), tags=('compute', 'market')), Metric(name='compute_asks_published', description='Compute asks published to mesh.', kind='counter', unit='', labels=(), counts='ask_published', sample=None, buckets=(), tags=('compute', 'market')))
- __init__(node=None, registry=None, ks=None, blobs=None, clock=None, load_monitor=None, remote_dispatcher=None)[source]
- handle(inbound)[source]
Answer an inbound wire protocol message according to HANDLERS declarations.
- index_offer(offer)[source]
- Parameters:
offer (NostrEvent)
- Return type:
- index_ask(ask)[source]
- Parameters:
ask (NostrEvent)
- Return type:
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- trouble()[source]
What an operator should be told without having to ask for it.
Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.
- submit_or_reflect(job, buyer_pk, *, bid_msat=0, force_reflect=False, remote_dispatcher=None)[source]
Execute a job locally if CPU/slot headroom permits, or reflect it to the least-loaded mesh peer.
- commands: Mapping[str, CommandSpec] = {'ask': {'args': {'bid': 'required', 'executor': 'optional', 'id': 'required', 'job': 'required', 'verify': 'optional'}, 'does': 'publish a kind 30810 confidential compute ask', 'reply': 'dict', 'subsystem': 'compute'}, 'book': {'args': {}, 'does': 'display active order book offers and asks', 'reply': 'dict', 'subsystem': 'compute'}, 'index_ask': {'args': {'ask': 'required'}, 'does': 'index an external kind 30810 ask', 'reply': 'bool', 'subsystem': 'compute'}, 'index_offer': {'args': {'offer': 'required'}, 'does': 'index an external kind 11803 offer', 'reply': 'bool', 'subsystem': 'compute'}, 'link_provider': {'args': {'api_key': 'optional', 'cashu_token': 'optional', 'default_model': 'optional', 'enabled': 'optional', 'endpoint': 'optional', 'provider_id': 'required', 'rate_msat_per_token': 'optional', 'set_default': 'optional'}, 'does': 'link an external or local AI/LLM inference provider to this meshnode', 'reply': 'dict', 'subsystem': 'compute'}, 'load': {'args': {}, 'does': 'display live host CPU utilization, active worker slots, and reflection status', 'reply': 'dict', 'subsystem': 'compute'}, 'match': {'args': {'ask': 'optional', 'offer': 'optional'}, 'does': 'find matching counterparties in order book', 'reply': 'list', 'subsystem': 'compute'}, 'models': {'args': {}, 'does': 'list available AI/LLM models and inference features', 'reply': 'dict', 'subsystem': 'compute'}, 'offer': {'args': {'engine': 'required', 'msat_per_mfuel': 'required'}, 'does': 'publish a kind 11803 compute offer', 'reply': 'dict', 'subsystem': 'compute'}, 'receipts': {'args': {}, 'does': 'list compute job receipts held', 'reply': 'list', 'subsystem': 'compute'}, 'run': {'args': {'buyer': 'required', 'job': 'required', 'paid_msat': 'optional', 'payment_hash': 'optional', 'preimage': 'optional'}, 'does': 'execute a job payload and return signed kind 30811 receipt', 'reply': 'dict', 'subsystem': 'compute'}, 'show': {'args': {}, 'does': 'display active compute offers, asks, and receipts', 'reply': 'dict', 'subsystem': 'compute'}, 'stream': {'args': {'model': 'optional', 'prompt': 'required'}, 'does': 'run a streaming AI/LLM inference query and return token deltas', 'reply': 'dict', 'subsystem': 'compute'}, 'submit': {'args': {'bid': 'optional', 'buyer': 'required', 'force_reflect': 'optional', 'job': 'required'}, 'does': 'execute a job locally when CPU headroom permits or reflect to a less-loaded mesh peer', 'reply': 'dict', 'subsystem': 'compute'}}
3.1.4.6. Compute Execution Engines & Registry
Experimental
In the code and tested, but not supported in this alpha: it may change or go away. See Experimental features.
ExecutorRegistry: which runtime answers which job kind, and the default set.
- class fleetmesh_node.planes.services.compute.executors.registry.ExecutorRegistry[source]
Bases:
objectRegistry managing available compute runtime execution drivers.
- __init__(blob_store=None, mock_mode=False, media_cache_dir=None, provider_router=None)[source]
- Parameters:
blob_store (Any | None)
mock_mode (bool)
media_cache_dir (str | None)
provider_router (OperatorProviderRouter | None)
- Return type:
None
- configure_llm_provider(config, set_default=True)[source]
Link or update an external/local LLM provider for both LLM and Agent executors.
- Parameters:
config (LinkedProviderConfig)
set_default (bool)
- Return type:
None
- register(executor, *aliases)[source]
- Parameters:
executor (ExecutorProtocol)
aliases (str)
- Return type:
None
- runnable_engines()[source]
Engine ids that can actually complete a job on this node.
Queries is_live_runnable() polymorphically across all registered executors. Executors reporting False (e.g. unconfigured backends outside mock_mode, or WasmExecutor when wasmtime is not installed) are excluded so Kind 11803 compute offers only advertise truly runnable capabilities.
Autonomous ReAct agent harness: Reasoning + Action loop with tool dispatch and recursive delegation.
Architecture: - AgentExecutionContext: State container holding task, budget caps, blob store, and delegation dispatcher. - AgentToolProtocol & Standard Tools: Calculator, Regex, Sha256, FetchBlob, SubAsk, and Finish. - AgentBackendProtocol: Decides next step (Thought, Action, Action Input) via LLM or scripted plan. - ReAct Loop: Bounded by max_steps and fuel_cap, with step-level telemetry and honesty gate.
- class fleetmesh_node.planes.services.compute.executors.agent.AgentExecutionContext[source]
Bases:
objectRuntime execution context provided to tools during an agent reasoning step.
- get_remaining_budget()[source]
Remaining msat budget permitted for child sub-delegation asks.
- Return type:
- deduct_delegation(amount_msat)[source]
Atomically deduct allocated msat from remaining budget and return granted amount.
- record_sub_ask(sub_ask)[source]
Record dispatched child ask into session telemetry.
- Parameters:
sub_ask (AgentSubAsk)
- Return type:
None
- __init__(task, delegation=<factory>, budget_cap_msat=0, budget_spent_msat=0, blob_store=None, blossom_servers=<factory>, sub_ask_dispatcher=None, fuel_cap=100000, fuel_used=0, sub_asks_dispatched=<factory>, depth=0, harness_profile=None, domain_context=<factory>)
- Parameters:
- Return type:
None
- class fleetmesh_node.planes.services.compute.executors.agent.AgentToolResult[source]
Bases:
TypedDictResult returned by an agent tool execution.
- class fleetmesh_node.planes.services.compute.executors.agent.AgentToolProtocol[source]
Bases:
ProtocolInterface for agent-invocable tools.
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- __init__(*args, **kwargs)
- class fleetmesh_node.planes.services.compute.executors.agent.AgentDecision[source]
Bases:
objectAction decision formulated by an agent reasoning backend.
- class fleetmesh_node.planes.services.compute.executors.agent.AgentBackendProtocol[source]
Bases:
ProtocolReasoning backend providing Thought and Action generation for the ReAct loop.
- decide_step(task, trace, tools, context)[source]
- Parameters:
task (str)
trace (Sequence[AgentTraceStep])
tools (Mapping[str, AgentToolProtocol])
context (AgentExecutionContext)
- Return type:
- __init__(*args, **kwargs)
- class fleetmesh_node.planes.services.compute.executors.agent.CalculatorTool[source]
Bases:
objectSafe arithmetic expression evaluator using AST inspection (no arbitrary code execution).
- description: str = 'Safely evaluates basic arithmetic expressions (+, -, *, /, //, %, **, abs, round, min, max).'
- parameters_schema: Mapping[str, Any] = {'properties': {'expression': {'description': 'Mathematical expression to evaluate', 'type': 'string'}}, 'required': ['expression'], 'type': 'object'}
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.agent.Sha256Tool[source]
Bases:
objectCryptographic SHA-256 hash calculator.
- parameters_schema: Mapping[str, Any] = {'properties': {'data': {'description': 'Input string or hex string', 'type': 'string'}, 'is_hex': {'description': 'True if data is hex-encoded', 'type': 'boolean'}}, 'required': ['data'], 'type': 'object'}
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.agent.RegexSearchTool[source]
Bases:
objectSafe regular expression pattern search and extraction tool.
- parameters_schema: Mapping[str, Any] = {'properties': {'pattern': {'description': 'Regex pattern to match', 'type': 'string'}, 'text': {'description': 'Target text to search', 'type': 'string'}}, 'required': ['pattern', 'text'], 'type': 'object'}
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.agent.FetchBlobTool[source]
Bases:
objectBlossom CAS blob retrieval tool.
- description: str = 'Retrieves a content-addressed blob by SHA-256 hash or CID from the local store or Blossom network.'
- parameters_schema: Mapping[str, Any] = {'properties': {'sha256': {'description': 'SHA-256 hex digest of the blob', 'type': 'string'}}, 'required': ['sha256'], 'type': 'object'}
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.agent.SubAskTool[source]
Bases:
objectRecursive child-Ask mesh delegation tool.
- description: str = 'Dispatches a delegated sub-computation ask (Kind 30810) to peer nodes across the mesh.'
- parameters_schema: Mapping[str, Any] = {'properties': {'budget_msat': {'description': 'Maximum msat budget allocated to child ask', 'type': 'integer'}, 'engine': {'description': 'Target execution engine (e.g. wasm, llm, zkvm)', 'type': 'string'}, 'task': {'description': 'Sub-task description or prompt', 'type': 'string'}}, 'required': ['task'], 'type': 'object'}
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.agent.FinishTool[source]
Bases:
objectTerminal tool to conclude the ReAct loop and return the final synthesized answer.
- parameters_schema: Mapping[str, Any] = {'properties': {'answer': {'description': 'Final synthesized answer or output', 'type': 'string'}}, 'required': ['answer'], 'type': 'object'}
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.agent.ScriptedAgentBackend[source]
Bases:
objectDeterministic ReAct reasoning backend for testing, fixtures, and scripted workflows.
- __init__(scripted_steps=None)[source]
- Parameters:
scripted_steps (Sequence[AgentDecision] | None)
- Return type:
None
- decide_step(task, trace, tools, context)[source]
- Parameters:
task (str)
trace (Sequence[AgentTraceStep])
tools (Mapping[str, AgentToolProtocol])
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.agent.LlmAgentBackend[source]
Bases:
objectLive LLM-driven reasoning backend querying OpenAI/Anthropic/Routstr-compatible endpoints.
- __init__(endpoint='http://127.0.0.1:8000/v1', model='meta-llama/Llama-3.3-70B-Instruct', timeout_seconds=30.0, api_key='', cashu_token='', provider_id='vllm', provider_router=None)[source]
- decide_step(task, trace, tools, context)[source]
- Parameters:
task (str)
trace (Sequence[AgentTraceStep])
tools (Mapping[str, AgentToolProtocol])
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.agent.AgentExecutor[source]
Bases:
ComputeExecutorAutonomous ReAct agent harness (Reasoning + Action loop with tool dispatch).
- __init__(max_steps_default=25, mock_mode=False, backend=None, tools=None, sub_ask_dispatcher=None, harness_registry=None)[source]
- tools: dict[str, AgentToolProtocol]
- is_live_runnable()[source]
Returns True if the executor is capable of servicing live compute requests.
- Return type:
- register_tool(tool)[source]
Register a new tool into the agent harness.
- Parameters:
tool (AgentToolProtocol)
- Return type:
None
Zero-knowledge executors: Groth16 verification, zkVM receipt verifier, and prover drivers.
- Implements Phase 3 of the compute roadmap:
ZkVmReceiptResult: Structured output from zkVM receipt verification.
ZkVmVerifierProtocol: Abstract interface for STARK/SNARK zkVM verifiers.
ZkVmReceiptVerifier: Production verifier supporting RISC Zero & SP1 STARK-to-Groth16.
MockZkVmVerifier: Deterministic test double for testing and fixtures.
ZkVmExecutor: Full zkVM executor driving receipt verification with honesty gating.
ZkProverProtocol: Interface for off-chain ZK prover services.
MockZkProverClient: Test double for prover order-book simulation.
ZkProverExecutor: Order-book executor driver for proof generation asks.
- class fleetmesh_node.planes.services.compute.executors.zk.ZkGroth16Executor[source]
Bases:
ComputeExecutorZero-Knowledge Groth16 proof verifier runtime (compute:zk-verify-groth16/1.0).
- is_live_runnable()[source]
Groth16 verification is pure cryptographic evaluation and is always operational.
- Return type:
- class fleetmesh_node.planes.services.compute.executors.zk.ZkVmReceiptResult[source]
Bases:
NamedTupleResult of validating a STARK / SNARK zkVM receipt.
- static __new__(_cls, valid, image_id, journal, journal_hash, proof_system, cycles=0, error='')
Create new instance of ZkVmReceiptResult(valid, image_id, journal, journal_hash, proof_system, cycles, error)
- class fleetmesh_node.planes.services.compute.executors.zk.ZkVmVerifierProtocol[source]
Bases:
ProtocolProtocol interface for zkVM receipt verifier engines.
- verify_receipt(image_id, journal, seal, proof_system='risc0-groth16', custom_vk=None)[source]
Verify the cryptographic validity of a zkVM execution receipt.
- is_available()[source]
Check whether the verifier backend is operational on this host.
- Return type:
- __init__(*args, **kwargs)
- class fleetmesh_node.planes.services.compute.executors.zk.ZkVmReceiptVerifier[source]
Bases:
objectProduction zkVM receipt verifier supporting STARK-to-Groth16 wrapping.
- class fleetmesh_node.planes.services.compute.executors.zk.MockZkVmVerifier[source]
Bases:
objectDeterministic test double for zkVM receipt verification.
- verified_receipts: list[ZkVmReceiptResult]
- class fleetmesh_node.planes.services.compute.executors.zk.ZkVmExecutor[source]
Bases:
ComputeExecutorZero-Knowledge Virtual Machine (zkVM) execution and receipt verification engine.
Supports RISC Zero, Succinct SP1, and STARK-to-Groth16 wrapped receipts. Enforces the honesty gate: unconfigured live instances refuse rather than selling unverified trace assertions.
- __init__(mock_mode=False, verifier=None)[source]
- Parameters:
mock_mode (bool)
verifier (ZkVmVerifierProtocol | None)
- Return type:
None
- class fleetmesh_node.planes.services.compute.executors.zk.ZkProverResult[source]
Bases:
NamedTupleResult of generating a zero-knowledge proof.
- class fleetmesh_node.planes.services.compute.executors.zk.ZkProverProtocol[source]
Bases:
ProtocolProtocol interface for zero-knowledge prover backends.
- generate_proof(program_spec, private_inputs, public_inputs=())[source]
Generate a zero-knowledge proof for the given program and witness inputs.
- __init__(*args, **kwargs)
- class fleetmesh_node.planes.services.compute.executors.zk.MockZkProverClient[source]
Bases:
objectTest double for off-chain zero-knowledge prover service.
- generated_proofs: list[ZkProverResult]
- class fleetmesh_node.planes.services.compute.executors.zk.ZkProverExecutor[source]
Bases:
ComputeExecutorOff-chain zero-knowledge prover service (compute:zk-prove-groth16/1.0).
Generates Groth16 or zkVM proofs for compute market Asks. Enforces the honesty gate: unconfigured live instances refuse rather than selling simulated proofs as paid cryptographic assertions.
- __init__(mock_mode=False, prover_client=None)[source]
- Parameters:
mock_mode (bool)
prover_client (ZkProverProtocol | None)
- Return type:
None
Bacalhau REST client connector and Blossom CAS compute-over-data mounting bridge.
- Implements Phase 2 of the compute roadmap:
BacalhauClientProtocol: abstract interface for Bacalhau daemon orchestrators.
BacalhauRestClient: native HTTP/REST connector for Bacalhau v1 orchestrator API.
MockBacalhauClient: test double for deterministic testing and dry-run fixtures.
BlossomMountBridge: Blossom CAS input resolution and output packaging/uploading.
- class fleetmesh_node.planes.services.compute.executors.bacalhau.BlossomStagingResult[source]
Bases:
NamedTupleResult of staging Blossom CAS input blobs into container mount points.
- class fleetmesh_node.planes.services.compute.executors.bacalhau.BlossomUploadResult[source]
Bases:
NamedTupleResult of packaging and committing container outputs to Blossom CAS.
- class fleetmesh_node.planes.services.compute.executors.bacalhau.BacalhauTaskSpec[source]
Bases:
TypedDictSpecification of a single Bacalhau container task.
- class fleetmesh_node.planes.services.compute.executors.bacalhau.BacalhauClientProtocol[source]
Bases:
ProtocolInterface required for Bacalhau orchestrator connectors.
- submit_job(job_payload, timeout_seconds=300)[source]
Submit a batch job specification and return assigned JobID.
- __init__(*args, **kwargs)
- class fleetmesh_node.planes.services.compute.executors.bacalhau.BacalhauRestClient[source]
Bases:
objectLive Bacalhau REST API v1 connector using Fleetmesh netfetch.
- build_bacalhau_job_spec(job_payload)[source]
Convert Fleetmesh job descriptor into standard Bacalhau v1 format.
- submit_job(job_payload, timeout_seconds=300)[source]
Submit a job specification to the Bacalhau orchestrator.
- class fleetmesh_node.planes.services.compute.executors.bacalhau.MockBacalhauClient[source]
Bases:
objectTest double implementing BacalhauClientProtocol for isolated and mock tests.
- class fleetmesh_node.planes.services.compute.executors.bacalhau.BlossomMountBridge[source]
Bases:
objectManages input staging from Blossom CAS and output artifact publishing.
- resolve_and_stage_inputs(storage_mounts, blob_store=None, blossom_servers=None)[source]
Resolve inputs from Blossom CAS or local storage, staging them for execution.
- class fleetmesh_node.planes.services.compute.executors.bacalhau.BacalhauExecutor[source]
Bases:
ComputeExecutorCompute-over-data batch driver backed by Bacalhau / Docker containers.
- Integrates Phase 2 capabilities:
Mounts Blossom CAS CIDs directly into container volume mounts.
Dispatches jobs to Bacalhau orchestrator or local sandbox.
Emits 5-state lifecycle progress heartbeats (compute/1.1/progress).
Honors cooperative cancellation tokens (compute/1.1/cancel).
- __init__(endpoint='http://127.0.0.1:1234', mock_mode=False, client=None, mount_bridge=None)[source]
- Parameters:
endpoint (str)
mock_mode (bool)
client (BacalhauClientProtocol | None)
mount_bridge (BlossomMountBridge | None)
- Return type:
None
Non-deterministic executors: LLM inference, Bacalhau jobs and agent runs.
These call out over HTTP (or run in mock mode) and are settled on evidence rather than reproduction; see docs/non-deterministic-compute.md.
- class fleetmesh_node.planes.services.compute.executors.nondet.LlmExecutor[source]
Bases:
ComputeExecutorNon-deterministic AI/LLM inference driver with grammar-guided decoding.
Supports OpenAI-compatible and Anthropic HTTP endpoints (OpenRouter, Claude, OpenAI, Gemini, Copilot, Routstr, PayPerQuery, vLLM, Ollama, llama-server) with CFG grammar constraints and fallback offline simulation.
- __init__(endpoint='http://127.0.0.1:8000/v1', default_model='meta-llama/Llama-3.3-70B-Instruct', timeout_seconds=30.0, mock_mode=False, provider_router=None, api_key='', cashu_token='', provider_id='vllm', rate_msat_per_token=12)[source]
- class fleetmesh_node.planes.services.compute.executors.nondet.BacalhauExecutor[source]
Bases:
ComputeExecutorCompute-over-data batch driver backed by Bacalhau / Docker containers.
- Integrates Phase 2 capabilities:
Mounts Blossom CAS CIDs directly into container volume mounts.
Dispatches jobs to Bacalhau orchestrator or local sandbox.
Emits 5-state lifecycle progress heartbeats (compute/1.1/progress).
Honors cooperative cancellation tokens (compute/1.1/cancel).
- __init__(endpoint='http://127.0.0.1:1234', mock_mode=False, client=None, mount_bridge=None)[source]
- Parameters:
endpoint (str)
mock_mode (bool)
client (BacalhauClientProtocol | None)
mount_bridge (BlossomMountBridge | None)
- Return type:
None
- class fleetmesh_node.planes.services.compute.executors.nondet.AgentExecutor[source]
Bases:
ComputeExecutorAutonomous ReAct agent harness (Reasoning + Action loop with tool dispatch).
- __init__(max_steps_default=25, mock_mode=False, backend=None, tools=None, sub_ask_dispatcher=None, harness_registry=None)[source]
- tools: dict[str, AgentToolProtocol]
- is_live_runnable()[source]
Returns True if the executor is capable of servicing live compute requests.
- Return type:
- register_tool(tool)[source]
Register a new tool into the agent harness.
- Parameters:
tool (AgentToolProtocol)
- Return type:
None
- class fleetmesh_node.planes.services.compute.executors.nondet.AgentExecutionContext[source]
Bases:
objectRuntime execution context provided to tools during an agent reasoning step.
- get_remaining_budget()[source]
Remaining msat budget permitted for child sub-delegation asks.
- Return type:
- deduct_delegation(amount_msat)[source]
Atomically deduct allocated msat from remaining budget and return granted amount.
- record_sub_ask(sub_ask)[source]
Record dispatched child ask into session telemetry.
- Parameters:
sub_ask (AgentSubAsk)
- Return type:
None
- __init__(task, delegation=<factory>, budget_cap_msat=0, budget_spent_msat=0, blob_store=None, blossom_servers=<factory>, sub_ask_dispatcher=None, fuel_cap=100000, fuel_used=0, sub_asks_dispatched=<factory>, depth=0, harness_profile=None, domain_context=<factory>)
- Parameters:
- Return type:
None
- class fleetmesh_node.planes.services.compute.executors.nondet.AgentToolProtocol[source]
Bases:
ProtocolInterface for agent-invocable tools.
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- __init__(*args, **kwargs)
- class fleetmesh_node.planes.services.compute.executors.nondet.AgentToolResult[source]
Bases:
TypedDictResult returned by an agent tool execution.
- class fleetmesh_node.planes.services.compute.executors.nondet.AgentDecision[source]
Bases:
objectAction decision formulated by an agent reasoning backend.
- class fleetmesh_node.planes.services.compute.executors.nondet.AgentBackendProtocol[source]
Bases:
ProtocolReasoning backend providing Thought and Action generation for the ReAct loop.
- decide_step(task, trace, tools, context)[source]
- Parameters:
task (str)
trace (Sequence[AgentTraceStep])
tools (Mapping[str, AgentToolProtocol])
context (AgentExecutionContext)
- Return type:
- __init__(*args, **kwargs)
- class fleetmesh_node.planes.services.compute.executors.nondet.CalculatorTool[source]
Bases:
objectSafe arithmetic expression evaluator using AST inspection (no arbitrary code execution).
- description: str = 'Safely evaluates basic arithmetic expressions (+, -, *, /, //, %, **, abs, round, min, max).'
- parameters_schema: Mapping[str, Any] = {'properties': {'expression': {'description': 'Mathematical expression to evaluate', 'type': 'string'}}, 'required': ['expression'], 'type': 'object'}
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.nondet.Sha256Tool[source]
Bases:
objectCryptographic SHA-256 hash calculator.
- parameters_schema: Mapping[str, Any] = {'properties': {'data': {'description': 'Input string or hex string', 'type': 'string'}, 'is_hex': {'description': 'True if data is hex-encoded', 'type': 'boolean'}}, 'required': ['data'], 'type': 'object'}
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.nondet.RegexSearchTool[source]
Bases:
objectSafe regular expression pattern search and extraction tool.
- parameters_schema: Mapping[str, Any] = {'properties': {'pattern': {'description': 'Regex pattern to match', 'type': 'string'}, 'text': {'description': 'Target text to search', 'type': 'string'}}, 'required': ['pattern', 'text'], 'type': 'object'}
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.nondet.FetchBlobTool[source]
Bases:
objectBlossom CAS blob retrieval tool.
- description: str = 'Retrieves a content-addressed blob by SHA-256 hash or CID from the local store or Blossom network.'
- parameters_schema: Mapping[str, Any] = {'properties': {'sha256': {'description': 'SHA-256 hex digest of the blob', 'type': 'string'}}, 'required': ['sha256'], 'type': 'object'}
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.nondet.SubAskTool[source]
Bases:
objectRecursive child-Ask mesh delegation tool.
- description: str = 'Dispatches a delegated sub-computation ask (Kind 30810) to peer nodes across the mesh.'
- parameters_schema: Mapping[str, Any] = {'properties': {'budget_msat': {'description': 'Maximum msat budget allocated to child ask', 'type': 'integer'}, 'engine': {'description': 'Target execution engine (e.g. wasm, llm, zkvm)', 'type': 'string'}, 'task': {'description': 'Sub-task description or prompt', 'type': 'string'}}, 'required': ['task'], 'type': 'object'}
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.nondet.FinishTool[source]
Bases:
objectTerminal tool to conclude the ReAct loop and return the final synthesized answer.
- parameters_schema: Mapping[str, Any] = {'properties': {'answer': {'description': 'Final synthesized answer or output', 'type': 'string'}}, 'required': ['answer'], 'type': 'object'}
- execute(params, context)[source]
- Parameters:
params (Any)
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.nondet.ScriptedAgentBackend[source]
Bases:
objectDeterministic ReAct reasoning backend for testing, fixtures, and scripted workflows.
- __init__(scripted_steps=None)[source]
- Parameters:
scripted_steps (Sequence[AgentDecision] | None)
- Return type:
None
- decide_step(task, trace, tools, context)[source]
- Parameters:
task (str)
trace (Sequence[AgentTraceStep])
tools (Mapping[str, AgentToolProtocol])
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.nondet.LlmAgentBackend[source]
Bases:
objectLive LLM-driven reasoning backend querying OpenAI/Anthropic/Routstr-compatible endpoints.
- __init__(endpoint='http://127.0.0.1:8000/v1', model='meta-llama/Llama-3.3-70B-Instruct', timeout_seconds=30.0, api_key='', cashu_token='', provider_id='vllm', provider_router=None)[source]
- decide_step(task, trace, tools, context)[source]
- Parameters:
task (str)
trace (Sequence[AgentTraceStep])
tools (Mapping[str, AgentToolProtocol])
context (AgentExecutionContext)
- Return type:
- class fleetmesh_node.planes.services.compute.executors.nondet.ProviderPreset[source]
Bases:
objectProviderPreset(provider_id: ‘str’, label: ‘str’, endpoint: ‘str’, default_model: ‘str’, models: ‘tuple[str, …]’, auth_scheme: ‘str’, wire_format: ‘str’, env_key: ‘str’, rate_msat_per_token: ‘int’, extra_headers: ‘Mapping[str, str]’ = <factory>)
- __init__(provider_id, label, endpoint, default_model, models, auth_scheme, wire_format, env_key, rate_msat_per_token, extra_headers=<factory>)
- class fleetmesh_node.planes.services.compute.executors.nondet.LinkedProviderConfig[source]
Bases:
objectOperator-linked configuration for a single inference provider.
- classmethod from_preset(provider_id, *, endpoint=None, default_model=None, models=None, api_key=None, cashu_token=None, cashu_mint=None, rate_msat_per_token=None, enabled=True, extra_headers=None)[source]
- Parameters:
- Return type:
- format_request(*, messages, model=None, max_tokens=512, temperature=0.7, top_p=1.0, seed=None, grammar=None, stream=False)[source]
- to_public_dict()[source]
Serialize provider metadata without exposing secret API keys or Cashu tokens.
- __init__(provider_id, endpoint, default_model, models=(), api_key='', cashu_token='', cashu_mint='', auth_scheme='bearer', wire_format='openai', rate_msat_per_token=12, enabled=True, label='', extra_headers=<factory>)
- class fleetmesh_node.planes.services.compute.executors.nondet.OperatorProviderRouter[source]
Bases:
objectRegistry of operator-linked LLM providers on a FleetMesh node.
- __init__(providers=None, default_provider=None)[source]
- Parameters:
providers (Sequence[LinkedProviderConfig] | None)
default_provider (str | None)
- Return type:
None
- register_provider(config, set_default=False)[source]
- Parameters:
config (LinkedProviderConfig)
set_default (bool)
- Return type:
None
- get_provider(provider_id=None)[source]
- Parameters:
provider_id (str | None)
- Return type:
LinkedProviderConfig | None
- resolve_for_job(job_payload)[source]
- Parameters:
- Return type:
LinkedProviderConfig | None
fleetmesh-wasi-v1: the WASI preview1 runner on wasmtime-py, and WasmExecutor.
wasmtime is optional. Everything the deterministic profile fixes (clock, random, NaN canonicalisation, no filesystem, no network) is set up in run_wasi_module.
- fleetmesh_node.planes.services.compute.executors.wasm.run_wasi_module(module_bytes, input_bytes, fuel_cap, memory_bytes=268435456, seed='', args=())[source]
Run a WASI command module under fleetmesh-wasi-v1. Returns (stdout, fuel).
- class fleetmesh_node.planes.services.compute.executors.wasm.WasmExecutor[source]
Bases:
ComputeExecutorDeterministic WASI runtime driver (fleetmesh-wasi-v1 profile).
- is_live_runnable()[source]
Check whether wasmtime engine is installed and available on this host.
- Return type:
3.1.4.7. Compute Wire Protocol
Experimental
In the code and tested, but not supported in this alpha: it may change or go away. See Experimental features.
ComputeWire: the subsystem that routes compute/1.0 envelopes to ComputeSession.
Separate so the subsystem wiring stays a thin adapter over the session and message modules.
- class fleetmesh_node.planes.services.compute_wire.compartment.ComputeWire[source]
Bases:
WireProtocolThe compute/1.0 and compute/1.1 wire transport compartment for meshnode.
- config_cls
alias of
ComputeConfig
- piuris: tuple[str, ...] = ('https://fleetmesh.org/compute/1.0', 'https://fleetmesh.org/compute/1.1')
- OUTBOUND: tuple[Outbound, ...] = (Outbound('quote', reply=('accept', 'cancel')), Outbound('accept', reply=('sealed', 'cancel')), Outbound('sealed', reply=('settled', 'refute')), Outbound('settled'), Outbound('refute'), Outbound('stream'), Outbound('progress'), Outbound('cancel'))
- COMMANDS: tuple[Any, ...] = (Command(key='sessions', name='Compute Sessions', description='list active bilateral compute sessions', tags=('compute', 'sessions'), parameters=(), permission='compute_wire/sessions', process=(), run='list_sessions', reply='dict', reads=(), writes=()), Command(key='disputes', name='Compute Disputes', description='list compute refutations and dispute reports filed', tags=('compute', 'disputes'), parameters=(), permission='compute_wire/disputes', process=(), run='list_disputes', reply='list', reads=(), writes=()))
- HANDLERS: tuple[Handler, ...] = (Handler(kind='quote', run='handle_quote', schema=None, doc='receive compute quotation', exact=False, reads=(), writes=()), Handler(kind='accept', run='handle_accept', schema=None, doc='receive compute job acceptance', exact=False, reads=(), writes=()), Handler(kind='sealed', run='handle_sealed', schema=None, doc='receive sealed compute payload', exact=False, reads=(), writes=()), Handler(kind='settled', run='handle_settled', schema=None, doc='receive compute settlement preimage', exact=False, reads=(), writes=()), Handler(kind='refute', run='handle_refute', schema=None, doc='receive compute refutation dispute', exact=False, reads=(), writes=('disputes',)), Handler(kind='stream', run='handle_stream', schema=None, doc='receive real-time streaming output chunk', exact=False, reads=(), writes=()), Handler(kind='progress', run='handle_progress', schema=None, doc='receive long-running progress heartbeat', exact=False, reads=(), writes=()), Handler(kind='cancel', run='handle_cancel', schema=None, doc='receive compute job cancellation', exact=False, reads=(), writes=()))
- DISPUTES_KEPT = 256
- STORES: tuple[Store, ...] = (Store(key='disputes', description='refutes received, as {peer, refute}, newest last', kind='ring', shape=<class 'dict'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()),)
- CHANNELS: tuple[Any, ...] = (Channel(name='refute_received', description='A compute refutation dispute was received from a peer', level='trouble', wire=None, say='compute dispute from {peer} for receipt {receipt}', tags=('compute', 'wire', 'dispute')), Channel(name='quote_received', description='A compute quotation was received from an executor peer', level='note', wire=None, say='compute quote from {peer} price {price} msat', tags=('compute', 'wire')))
- METRICS: tuple[Any, ...] = (Metric(name='compute_wire_disputes', description='Compute disputes and refutations received.', kind='counter', unit='', labels=(), counts='refute_received', sample=None, buckets=(), tags=('compute', 'wire', 'disputes')), Metric(name='compute_wire_quotes', description='Compute quotes received from peers.', kind='counter', unit='', labels=(), counts='quote_received', sample=None, buckets=(), tags=('compute', 'wire', 'quotes')))
- NEEDS: tuple[Any, ...] = (Need(key='ks', source='ks', block=None, late=False, getter=False, path=None, field=None),)
- pinned_vk_digests()[source]
Operator-pinned Groth16 verification-key digests (cfg compute.zk_pinned_vks).
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- Return type:
ComputeWireStateReport
- commands: Mapping[str, CommandSpec] = {'disputes': {'args': {}, 'does': 'list compute refutations and dispute reports filed', 'reply': 'list', 'subsystem': 'compute_wire'}, 'sessions': {'args': {}, 'does': 'list active bilateral compute sessions', 'reply': 'dict', 'subsystem': 'compute_wire'}}
3.1.4.8. Data Vending Machine (DVM) Compartment
Experimental
In the code and tested, but not supported in this alpha: it may change or go away. See Experimental features.
The DVM gateway compartment: takes a NIP-90 request off the relay face, runs (or delegates) the job, answers with feedback and a result.
- class fleetmesh_node.planes.services.dvm.gateway.DVMGateway[source]
Bases:
Compartment- STORES: tuple[Store, ...] = (Store(key='recent_jobs', description='recent DVM job results, newest last', kind='ring', shape=<class 'tuple'>, bound=128, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()),)
- CHANNELS: tuple[Any, ...] = (Channel(name='job_received', description='A NIP-90 DVM request event was received for processing', level='info', wire=None, say='received DVM job {job_id} (kind {kind})', tags=('dvm', 'job')), Channel(name='job_succeeded', description='A NIP-90 DVM job completed successfully', level='info', wire=None, say='completed DVM job {job_id} using {fuel} fuel', tags=('dvm', 'job')), Channel(name='job_failed', description='A NIP-90 DVM job failed during execution', level='trouble', wire=None, say='DVM job {job_id} failed: {error}', tags=('dvm', 'job')), Channel(name='job_delegated', description='A NIP-90 DVM job was delegated to compute order book', level='info', wire=None, say='delegated DVM job {job_id} to compute order book', tags=('dvm', 'delegate')))
- METRICS: tuple[Any, ...] = (Metric(name='dvm_jobs_received', description='DVM job requests received.', kind='counter', unit='', labels=(), counts='job_received', sample=None, buckets=(), tags=('dvm', 'job')), Metric(name='dvm_jobs_succeeded', description='DVM jobs completed successfully.', kind='counter', unit='', labels=(), counts='job_succeeded', sample=None, buckets=(), tags=('dvm', 'job')), Metric(name='dvm_jobs_failed', description='DVM jobs that failed.', kind='counter', unit='', labels=(), counts='job_failed', sample=None, buckets=(), tags=('dvm', 'job')), Metric(name='dvm_jobs_delegated', description='DVM jobs delegated to compute order book.', kind='counter', unit='', labels=(), counts='job_delegated', sample=None, buckets=(), tags=('dvm', 'delegate')))
- WORKERS: tuple[Any, ...] = (Worker(run='_dvm_worker_loop', name='dvm_requests', timeout=1.0, daemon=True, when=None),)
- NEEDS: tuple[Any, ...] = (Need(key='cfg', source=None, block=<class 'fleetmesh_node.config.compartments.DVMConfig'>, late=False, getter=False, path=None, field=None), Need(key='ks', source='ks', block=None, late=False, getter=False, path=None, field=None), Need(key='face', source='face', block=None, late=False, getter=False, path=None, field=None), Need(key='blob_store', source='stores.blobs', block=None, late=False, getter=False, path=None, field=None), Need(key='order_book', source='compute', block=None, late=False, getter=False, path=None, field=None), Need(key='bridge', source='bridge', block=None, late=False, getter=False, path=None, field=None))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='DVM Gateway Status', description='display DVM gateway state, supported kinds, and job counters', tags=('dvm', 'status'), parameters=(), permission='dvm/show', process=(), run='state', reply='dict', reads=(), writes=()), Command(key='delegate', name='Delegate DVM Request', description='delegate a NIP-90 request to the compute order book', tags=('dvm', 'delegate'), parameters=(Parameter(key='request', name='request', description='NIP-90 request event dictionary', type=<class 'dict'>, default=<class 'dict'>, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='dvm/delegate', process=(), run='delegate_cmd', reply='dict', reads=(), writes=()), Command(key='process', name='Process DVM Request', description='execute a NIP-90 request locally or via delegated runner', tags=('dvm', 'process'), parameters=(Parameter(key='request', name='request', description='NIP-90 request event dictionary', type=<class 'dict'>, default=<class 'dict'>, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='dvm/process', process=(), run='process_cmd', reply='dict', reads=(), writes=()))
- __init__(node=None, cfg=None, custom_runner=None, blob_store=None, registry=None, order_book=None, bridge=None, ks=None, face=None, clock=None, payment_rail=None, settlement=None)[source]
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- Return type:
DVMStateReport
- trouble()[source]
What an operator should be told without having to ask for it.
Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.
- process_request(request_ev, signer_sk=None)[source]
Process a NIP-90 request, returning (response_event_or_None, feedback_event).
- Parameters:
request_ev (NostrEvent)
signer_sk (str | None)
- Return type:
tuple[NostrEvent | None, NostrEvent]
- create_payment_required_feedback(request_ev, amount_msat, signer_sk=None, payment_hash=None, preimage=None)[source]
Build and fan out a Kind 7000 payment-required feedback event with a Lightning hold invoice.
- Parameters:
request_ev (NostrEvent)
amount_msat (int)
signer_sk (str | None)
payment_hash (str | None)
preimage (str | None)
- Return type:
tuple[NostrEvent, Any | None, str]
- commands: Mapping[str, CommandSpec] = {'delegate': {'args': {'request': 'required'}, 'does': 'delegate a NIP-90 request to the compute order book', 'reply': 'dict', 'subsystem': 'dvm'}, 'process': {'args': {'request': 'required'}, 'does': 'execute a NIP-90 request locally or via delegated runner', 'reply': 'dict', 'subsystem': 'dvm'}, 'show': {'args': {}, 'does': 'display DVM gateway state, supported kinds, and job counters', 'reply': 'dict', 'subsystem': 'dvm'}}
- delegate_request(request_ev)[source]
Delegate a NIP-90 request to the mesh compute order book.
- Parameters:
request_ev (NostrEvent)
- Return type:
DVMDelegationResult
- on_event(ev)[source]
Callback to handle events observed on the local face or relay bridge.
- Parameters:
ev (NostrEvent)
- Return type:
None
3.1.4.9. Gossip Mesh Compartment
Experimental
In the code and tested, but not supported in this alpha: it may change or go away. See Experimental features.
GossipMesh: the gossip/1.0 compartment.
A true epidemic fanout for group topics, independent of any single relay. Membership in a topic is explicit: an admin-signed kind 30804 (addressable, republish-supersedes) naming every member pubkey, not ambient trust. A node only grafts into, or accepts a graft for, a topic it holds a current membership event naming its own pubkey for - and only toward a peer it already shares a peering grant with, so this invents no new authorization and rides the budget/grant model everyone else already accounts against.
The payload gossiped is the NIP-59 seal+wrap this node would otherwise have sent over the 1:1 transport-ladder path - one sealed envelope per recipient, exactly as DMs ship today - so gossip never sees plaintext: it floods already-encrypted bytes keyed by the wrap’s own event id. 1:1 DMs are untouched; this is purely an additional fanout substrate for group topics of 3+ members, which is where a single relay going down costs everyone their only path.
Loop prevention is strict: a seen-id store (sqlite, TTL + size bounded) keyed (topic, event_id) is checked before flooding, and an id is never re-sent back toward the peer it arrived from. graft/prune build and prune a bounded mesh per topic, degree DEFAULT_MESH_DEGREE (gossipsub’s D), maintained by tick().
ihave/iwant is the lazy half (gossipsub’s “gossip” proper): every tick, each topic’s recent event ids are offered to a few members outside this node’s mesh, and a member that is missing one asks for it by id and is sent the sealed envelope directly. That is what carries a publish across a mesh that is partitioned - a member whose grafts all failed, a topic larger than D where two cliques formed, a node that was down for the flood - without any relay in the path. Envelopes to answer an iwant with come from a short in-memory message cache; the durable seen store stays the only thing loop prevention relies on.
- class fleetmesh_node.planes.services.gossip.core.GossipMesh[source]
Bases:
WireProtocolThe group-topic gossip/1.0 compartment: graft/prune mesh + flood publish.
- config_cls
alias of
GossipConfig
- HANDLERS: tuple[Handler, ...] = (Handler(kind='graft', run='wire_graft', schema=None, doc='receive gossip mesh graft', exact=False, reads=(), writes=()), Handler(kind='prune', run='wire_prune', schema=None, doc='receive gossip mesh prune', exact=False, reads=(), writes=()), Handler(kind='publish', run='wire_publish', schema=None, doc='receive epidemic flood publish', exact=False, reads=(), writes=()), Handler(kind='ihave', run='wire_ihave', schema=None, doc='receive lazy gossip ihave offer', exact=False, reads=(), writes=()), Handler(kind='iwant', run='wire_iwant', schema=None, doc='receive lazy gossip iwant request', exact=False, reads=(), writes=()))
- OUTBOUND: tuple[Outbound, ...] = (Outbound('graft', reply=('graft', 'prune')), Outbound('prune'), Outbound('publish'), Outbound('ihave', reply=('iwant',)), Outbound('iwant', reply=('publish',)))
- COMMANDS: tuple[Any, ...] = (Command(key='show', name='Gossip Status', description='topics this node gossips, mesh size per topic, and seen-store size', tags=('gossip', 'status'), parameters=(), permission='gossip/show', process=(), run='state', reply='{topics, mesh, seen}', reads=(), writes=()), Command(key='topics', name='Gossip Topics', description='every roster held: admin, members, mesh peers, expiry', tags=('gossip', 'topics'), parameters=(), permission='gossip/topics', process=(), run='topics_cmd', reply='[{topic, admin, members, mesh, expires, roster_id}]', reads=(), writes=()), Command(key='create', name='Create Topic', description='sign a kind 30804 roster for <node_pk>:<name>, admit it, publish it to the relays', tags=('gossip', 'create'), parameters=(Parameter(key='name', name='name', description='topic name', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='members', name='members', description='initial member pubkeys', type=<class 'list'>, default=<class 'list'>, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='ttl_seconds', name='ttl_seconds', description='roster time-to-live in seconds', type=<class 'int'>, default=2592000, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='no_relay', name='no_relay', description='do not publish to relays', type=<class 'bool'>, default=False, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='gossip/create', process=(), run='create_cmd', reply='{topic, event, relays}', reads=(), writes=()), Command(key='admit', name='Admit Topic', description='admit a kind 30804 roster another admin signed that names this node', tags=('gossip', 'admit'), parameters=(Parameter(key='event', name='event', description='kind 30804 roster event', type=<class 'dict'>, default=<class 'dict'>, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='gossip/admit', process=(), run='admit_cmd', reply='{topic}', reads=(), writes=()), Command(key='leave', name='Leave Topic', description='drop a roster and prune every mesh peer on it', tags=('gossip', 'leave'), parameters=(Parameter(key='topic', name='topic', description='topic to leave', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='gossip/leave', process=(), run='leave_cmd', reply='{topic, pruned}', reads=(), writes=()), Command(key='publish', name='Publish Message', description='flood a sealed NIP-59 wrap into a topic mesh', tags=('gossip', 'publish'), parameters=(Parameter(key='topic', name='topic', description='target topic id', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='envelope', name='envelope', description='sealed NIP-59 wrap event', type=<class 'dict'>, default=<class 'dict'>, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='gossip/publish', process=(), run='publish_cmd', reply='{topic, event_id, sent_to, mesh}', reads=(), writes=()))
- STORES: tuple[Store, ...] = (Store(key='members', description='the roster held for each topic', kind='table', shape=<class 'fleetmesh_node.planes.services.gossip.core.Roster'>, bound=1024, evict='refuse', keyed_by='topic', persist='memory', sensitive=False, tags=()), Store(key='peers', description="the pubkeys in this node's mesh, per topic", kind='table', shape=<class 'set'>, bound=1024, evict='oldest', keyed_by='topic', persist='memory', sensitive=False, tags=()), Store(key='grafted_at', description='when each mesh peer was grafted, per topic', kind='table', shape=<class 'int'>, bound=65536, evict='oldest', keyed_by='topic and peer', persist='memory', sensitive=False, tags=()), Store(key='mcache', description='sealed envelopes kept to answer an iwant, with when they were cached', kind='table', shape=<class 'tuple'>, bound=8192, evict='oldest', keyed_by='topic and event', persist='memory', sensitive=False, tags=()), Store(key='totals', description='gossip events this node took part in, since it started', kind='counters', shape=<class 'fleetmesh_node.planes.services.gossip.types.GossipTotals'>, bound=0, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='published', description='events this node originated, as (topic, event id), newest last', kind='ring', shape=<class 'tuple'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='delivered', description='events delivered from a mesh peer, as (topic, event id, from), newest last', kind='ring', shape=<class 'tuple'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='offered', description='ihave offers sent, as (topic, peer, ids), newest last', kind='ring', shape=<class 'tuple'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='wanted', description='iwant requests sent, as (topic, peer, ids), newest last', kind='ring', shape=<class 'tuple'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='served', description='iwant answers sent, as (topic, event id, to), newest last', kind='ring', shape=<class 'tuple'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='auto_admitted', description='rosters admitted from a relay, as (topic, roster id), newest last', kind='ring', shape=<class 'tuple'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()))
- CHANNELS: tuple[Any, ...] = (Channel(name='event_published', description='A gossip event was originated and flooded to the topic mesh', level='info', wire=None, say='published gossip event {event_id} to topic {topic}', tags=('gossip', 'publish')), Channel(name='event_delivered', description='A gossip event was delivered from a mesh peer', level='info', wire=None, say='delivered gossip event {event_id} on topic {topic} from {peer}', tags=('gossip', 'deliver')), Channel(name='graft_established', description="A peer was grafted into this node's topic mesh", level='info', wire=None, say='grafted peer {peer} on topic {topic}', tags=('gossip', 'mesh')), Channel(name='prune_executed', description="A peer was pruned from this node's topic mesh", level='note', wire=None, say='pruned peer {peer} on topic {topic} (reason: {reason})', tags=('gossip', 'mesh')))
- METRICS: tuple[Any, ...] = (Metric(name='gossip_events_published', description='Events originated and flooded to topic mesh.', kind='counter', unit='', labels=(), counts='event_published', sample=None, buckets=(), tags=('gossip', 'publish')), Metric(name='gossip_events_delivered', description='Events received from mesh peers and delivered.', kind='counter', unit='', labels=(), counts='event_delivered', sample=None, buckets=(), tags=('gossip', 'deliver')), Metric(name='gossip_peers_grafted', description='Peers added to local gossip mesh.', kind='counter', unit='', labels=(), counts='graft_established', sample=None, buckets=(), tags=('gossip', 'mesh')), Metric(name='gossip_peers_pruned', description='Peers removed from local gossip mesh.', kind='counter', unit='', labels=(), counts='prune_executed', sample=None, buckets=(), tags=('gossip', 'mesh')))
- NEEDS: tuple[Any, ...] = (Need(key='keystore', source='ks', block=None, late=False, getter=False, path=None, field=None), Need(key='transport', source='transport', block=None, late=False, getter=False, path=None, field=None), Need(key='grant_store', source='stores.grants', block=None, late=False, getter=False, path=None, field=None), Need(key='cfg', source=None, block=<class 'fleetmesh_node.config.compartments.GossipConfig'>, late=False, getter=False, path=None, field=None), Need(key='seen_path', source=None, block=None, late=False, getter=False, path='gossip_seen.sqlite', field=None), Need(key='roster_path', source=None, block=None, late=False, getter=False, path='gossip_rosters.sqlite', field=None), Need(key='relays', source='relays', block=None, late=False, getter=False, path=None, field=None))
- EVERY: tuple[Any, ...] = (Every(seconds=3600, run='expire_seen', name='expire_seen', report=None),)
- WORKERS: tuple[Any, ...] = (Worker(run='_listen', name='gossip-rosters', timeout=1.0, daemon=True, when='relays'),)
- __init__(keystore, transport, grant_store, clock=None, node=None, mesh_degree=6, seen_ttl_seconds=86400, max_topics=64, seen_path=':memory:', roster_path=None, relays=None, cfg=None)[source]
- Parameters:
- Return type:
None
- on_roster(event)[source]
A roster read from a relay: admit it if it names this node and is from a granted peer; the topic admitted, or None (refusal recorded).
- admit_membership(topic, event, member_pubkeys)[source]
Record a current admin-signed kind 30804 membership event for a topic.
A republish of the same d (topic) supersedes the one held, matching the addressable-event convention every other control event here uses. The roster is read from the event’s own member tags; the caller’s member_pubkeys is accepted only when it matches them, so a caller cannot admit a roster the admin did not sign.
- make_roster(name, members, ttl_seconds=2592000)[source]
Sign a kind 30804 roster for a topic this node administers.
This node is always on its own roster: an admin that is not a member would hold a topic it can never graft into. Signing is the slow pure- Python curve, so this is an operator action, not something on a tick.
- Parameters:
- Return type:
- create_topic(name, members, ttl_seconds=2592000, publish_to_relays=True)[source]
Sign, admit, and (optionally) publish a roster. Returns {topic, event, relays}.
Publishing to the configured relays is how the other members learn the roster before any of them has a gossip mesh to learn it over - the one place a relay is in the path, and only as a bulletin board.
- admit(event)[source]
Admit a roster another admin signed (fetched from a relay, pasted by the operator). The topic is the event’s own d; returns it.
- originate(topic, envelope)[source]
Flood an already-sealed NIP-59 wrap (kind 1059/13/21059) into a topic.
The compartment carries ciphertext only; a plaintext kind here is a refusal, not a convenience, because the mesh is every member’s peers.
- check_membership(topic, event, member_pubkeys)[source]
Why this event is not a current kind 30804 roster for topic, or None.
Kind, signature, d coordinate scoped to the signing admin, a roster that is what the tags say, and a NIP-40 expiration still ahead - in that order, cheapest refusal first.
- publish(topic, event_id, envelope)[source]
Originate a publish into this topic’s mesh. Returns peers flooded to.
- emit_gossip(topic)[source]
Offer this topic’s recent ids to up to GOSSIP_LAZY_DEGREE members that are not in this node’s mesh (the mesh already got the flood). Only members with a grant: an ihave is a promise to answer iwant.
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- Return type:
GossipStateReport
- trouble()[source]
What an operator should be told without having to ask for it.
Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.
- commands: Mapping[str, CommandSpec] = {'admit': {'args': {'event': 'required'}, 'does': 'admit a kind 30804 roster another admin signed that names this node', 'reply': '{topic}', 'subsystem': 'gossip'}, 'create': {'args': {'members': 'optional', 'name': 'required', 'no_relay': 'optional', 'ttl_seconds': 'optional'}, 'does': 'sign a kind 30804 roster for <node_pk>:<name>, admit it, publish it to the relays', 'reply': '{topic, event, relays}', 'subsystem': 'gossip'}, 'leave': {'args': {'topic': 'required'}, 'does': 'drop a roster and prune every mesh peer on it', 'reply': '{topic, pruned}', 'subsystem': 'gossip'}, 'publish': {'args': {'envelope': 'required', 'topic': 'required'}, 'does': 'flood a sealed NIP-59 wrap into a topic mesh', 'reply': '{topic, event_id, sent_to, mesh}', 'subsystem': 'gossip'}, 'show': {'args': {}, 'does': 'topics this node gossips, mesh size per topic, and seen-store size', 'reply': '{topics, mesh, seen}', 'subsystem': 'gossip'}, 'topics': {'args': {}, 'does': 'every roster held: admin, members, mesh peers, expiry', 'reply': '[{topic, admin, members, mesh, expires, roster_id}]', 'subsystem': 'gossip'}}
3.1.4.10. nsite Decentralized Web Compartment
Experimental
In the code and tested, but not supported in this alpha: it may change or go away. See Experimental features.
nsite: the node as a NIP-5A static-site host, reachable from the plain web.
Two kinds of hostname reach a site here:
- npub1….<suffix> v<snapshot>.<suffix> <base36 pubkey><d>.<suffix>
the NIP’s own grammar under each configured suffixes entry;
- www.example.com
a CUSTOM DOMAIN the owner pointed here: a CNAME (or A) to the gateway plus a TXT at _nsite.example.com naming the site. With require_domain_tag (the default) the site’s manifest must also carry [“domain”, “example.com”], so a DNS record someone else controls cannot put a well-known pubkey’s site behind a look-alike name.
The compartment holds no site state of its own beyond two small sqlite tables (manifest cache, domain bindings) in the node’s blob store database directory. Blobs it fetches are verified against their sha256 and kept in the node’s BlobStore, which makes this node a Blossom mirror for every site it serves; the store’s own LRU quota bounds that, with a per-site cap on top.
Anything the outside world gets wrong - unknown label, no manifest, hash mismatch, blob too big, unbound domain - is a refusal: counted, kept with detail, and answered to the browser with a short status. Only our own bugs are errors.
TLS for custom domains is not this process’s job. The Ansible role’s Caddy asks GET /nsite/_ask?domain= before issuing a certificate; 200 means the domain is verified here, anything else means Caddy must not. See ops/roles/meshnode/templates/Caddyfile.j2.
- class fleetmesh_node.planes.services.nsite.compartment.NsiteStore[source]
Bases:
BaseSqliteStoreThe three tables: resolved manifests, domain bindings, cached bytes.
On BaseSqliteStore like every other store in the node. It was not, until storage step 4 asked what still imported sqlite3 and found this one keeping its own connection - the subclass census had counted classes on the base, not connections, so it was invisible. Being on the base is what lets a second dialect reach it (docs/storage-backends.md).
- SCHEMA: tuple[Any, ...] = (Table(name='nsite_manifest', columns=(Column(name='site_key', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='event_id', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='json', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='aggregate', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='fetched_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False), Table(name='nsite_domain', columns=(Column(name='domain', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='site_key', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='status', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='why', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='checked_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False), Table(name='nsite_site_bytes', columns=(Column(name='site_key', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='sha256', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='size', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('site_key', 'sha256'), indices=(), without_rowid=False))
- class fleetmesh_node.planes.services.nsite.compartment.NsiteGateway[source]
Bases:
CompartmentThe compartment. Mounted on the relay face’s HTTP fallthrough.
- config_cls
alias of
NsiteConfig
- SCHEMA: tuple[Any, ...] = (Table(name='nsite_manifest', columns=(Column(name='site_key', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='event_id', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='json', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='aggregate', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='fetched_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False), Table(name='nsite_domain', columns=(Column(name='domain', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='site_key', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='status', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='why', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='checked_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False), Table(name='nsite_site_bytes', columns=(Column(name='site_key', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='sha256', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='size', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('site_key', 'sha256'), indices=(), without_rowid=False))
- STORE_CLS
alias of
NsiteStore
- STORES: tuple[Store, ...] = (Store(key='recent_requests', description='recent HTTP requests served, newest last', kind='ring', shape=<class 'tuple'>, bound=128, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()),)
- CHANNELS: tuple[Any, ...] = (Channel(name='site_served', description='A static site resource was served to an HTTP client', level='info', wire=None, say='served {path} for site {site_key} ({bytes_sent} bytes)', tags=('nsite', 'http')), Channel(name='site_published', description='A NIP-5A nsite manifest was signed and published', level='info', wire=None, say='published nsite manifest {event_id} for site {site}', tags=('nsite', 'publish')), Channel(name='domain_verified', description='A custom domain was verified via DNS TXT and site manifest', level='info', wire=None, say='verified custom domain {domain} -> {site_key}', tags=('nsite', 'dns')), Channel(name='domain_refused', description='A custom domain verification was refused', level='trouble', wire=None, say='refused custom domain {domain}: {why}', tags=('nsite', 'dns')))
- METRICS: tuple[Any, ...] = (Metric(name='nsite_requests_served', description='Static site HTTP requests served.', kind='counter', unit='', labels=(), counts='site_served', sample=None, buckets=(), tags=('nsite', 'http')), Metric(name='nsite_sites_published', description='Static sites published.', kind='counter', unit='', labels=(), counts='site_published', sample=None, buckets=(), tags=('nsite', 'publish')), Metric(name='nsite_domains_verified', description='Custom domains verified.', kind='counter', unit='', labels=(), counts='domain_verified', sample=None, buckets=(), tags=('nsite', 'dns')), Metric(name='nsite_domains_refused', description='Custom domain verification failures.', kind='counter', unit='', labels=(), counts='domain_refused', sample=None, buckets=(), tags=('nsite', 'dns')))
- NEEDS: tuple[Any, ...] = (Need(key='events', source='stores.events', block=None, late=False, getter=False, path=None, field=None), Need(key='blobs', source='stores.blobs', block=None, late=False, getter=False, path=None, field=None), Need(key='cfg', source=None, block=<class 'fleetmesh_node.config.compartments.NsiteConfig'>, late=False, getter=False, path=None, field=None), Need(key='relays', source='relays', block=None, late=False, getter=False, path=None, field=None), Need(key='db_path', source=None, block=None, late=False, getter=False, path='nsite.db', field=None), Need(key='bridge', source='bridge', block=None, late=False, getter=False, path=None, field=None), Need(key='ks', source='ks', block=None, late=False, getter=False, path=None, field=None), Need(key='face', source='face', block=None, late=False, getter=False, path=None, field=None))
- COMMANDS: tuple[Any, ...] = (Command(key='domains', name='Custom Domains', description='list custom-domain bindings and their state', tags=('nsite', 'domains'), parameters=(), permission='nsite/domains', process=(), run='domains_cmd', reply='domains', reads=(), writes=()), Command(key='sites', name='Sites Summary', description='cached manifests, verified domains and bytes', tags=('nsite', 'sites'), parameters=(), permission='nsite/sites', process=(), run='sites_cmd', reply='totals', reads=(), writes=()), Command(key='verify', name='Verify Domain', description='re-check one custom domain now', tags=('nsite', 'verify'), parameters=(Parameter(key='domain', name='domain', description='domain to verify', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='nsite/verify', process=(), run='verify_cmd', reply='binding', reads=(), writes=()), Command(key='forget', name='Forget Domain', description='drop a binding; it is re-resolved on the next request', tags=('nsite', 'forget'), parameters=(Parameter(key='domain', name='domain', description='domain binding to drop', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='nsite/forget', process=(), run='forget_cmd', reply='dropped', reads=(), writes=()), Command(key='publish', name='Publish Site', description="sign this node's own site manifest from blobs already uploaded and publish it", tags=('nsite', 'publish'), parameters=(Parameter(key='paths', name='paths', description='mapping of paths to sha256', type=<class 'dict'>, default=<class 'dict'>, must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=False), Parameter(key='site', name='site', description='d tag (named site)', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='snapshot', name='snapshot', description='also publish immutable kind-5128 copy', type=<class 'bool'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='domains', name='domains', description='domains claimed for custom-domain proof', type=<class 'list'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='--domain-claim', positional=False, nargs='', cli=True), Parameter(key='servers', name='servers', description='Blossom URLs the blobs are on', type=<class 'list'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='--server', positional=False, nargs='', cli=True), Parameter(key='title', name='title', description='site title', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='nsite/publish', process=(), run='publish_cmd', reply='manifest (+ snapshot) event ids and the site labels', reads=(), writes=()))
- __init__(events, blobs, cfg=None, relays=(), store=None, bridge=None, clock=None, node=None, query_relays=None, fetch_blob=None, lookup_txt=None, ks=None, face=None, blossom_url=None, db_path=None)[source]
- Parameters:
- Return type:
None
- cfg: NsiteConfig
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- Return type:
NsiteState
- trouble()[source]
What an operator should be told without having to ask for it.
Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.
- publish(args)[source]
The node’s own site: a manifest signed with the node key.
The blobs are already on a Blossom server (the CLI PUTs them to this node’s face before asking) - the control socket carries hashes, never file bodies. Every path must be absolute and every hash 64 hex chars; the blobs this node holds are checked to exist so a typo in a hash cannot publish a site with holes in it.
- handle_request(conn, req)[source]
The face’s hook: True if this was ours (answered), False to let the rest of the face have it.
- under_suffix(host)[source]
True for any name under a suffix - the zone this gateway owns, where a host that is neither a site label nor a bound custom domain is still our 404, never the relay’s NIP-11 document.
- manifest(ref)[source]
- Parameters:
ref (SiteRef)
- Return type:
NostrEvent | None
- user_servers(pubkey)[source]
The author’s kind-10063 server list, local then relays.
- Parameters:
pubkey (str)
- Return type:
NostrEvent | None
- bind_domain(domain, force=False)[source]
The binding for domain, re-checked when older than the TTL.
- verified TXT names a site we can see and (when required) the
manifest claims the domain
unbound no _nsite.<domain> TXT, or not parseable unclaimed TXT points at a site whose manifest does not list the domain denied operator deny list, or not on the allow list of a closed gateway
- commands: Mapping[str, CommandSpec] = {'domains': {'args': {}, 'does': 'list custom-domain bindings and their state', 'reply': 'domains', 'subsystem': 'nsite'}, 'forget': {'args': {'domain': 'required'}, 'does': 'drop a binding; it is re-resolved on the next request', 'reply': 'dropped', 'subsystem': 'nsite'}, 'publish': {'args': {'domains': 'optional', 'paths': 'required', 'servers': 'optional', 'site': 'optional', 'snapshot': 'optional', 'title': 'optional'}, 'does': "sign this node's own site manifest from blobs already uploaded and publish it", 'reply': 'manifest (+ snapshot) event ids and the site labels', 'subsystem': 'nsite'}, 'sites': {'args': {}, 'does': 'cached manifests, verified domains and bytes', 'reply': 'totals', 'subsystem': 'nsite'}, 'verify': {'args': {'domain': 'required'}, 'does': 're-check one custom domain now', 'reply': 'binding', 'subsystem': 'nsite'}}
3.1.4.11. Cross-Protocol Translation & Settlement Gateway
Cross-protocol translation engine for Fleetmesh.
Provides bidirectional translation across the four supported social protocols: - Nostr (NIP-01 Kind 1 / e-tag threading) - AT Protocol (app.bsky.feed.post) - ActivityPub (ActivityStreams 2.0 Create / Note) - Secure Scuttlebutt (post)
Uses UnifiedPost as the canonical intermediate representation for maximum fidelity.
- class fleetmesh_node.planes.services.gateway.translate.UnifiedPost[source]
Bases:
objectCanonical intermediate representation of a social microblog post.
- __init__(text, author='', created_at=0, attachments=<factory>, reply_to=None, root=None, tags=<factory>, extra=<factory>)
- fleetmesh_node.planes.services.gateway.translate.unix_to_iso(ts)[source]
Format unix seconds to ISO 8601 UTC string.
- fleetmesh_node.planes.services.gateway.translate.iso_to_unix(iso_str)[source]
Parse ISO 8601 string to unix seconds.
- fleetmesh_node.planes.services.gateway.translate.strip_html(text)[source]
Strip HTML tags, scripts, and unescape HTML entities for clean text representation.
- fleetmesh_node.planes.services.gateway.translate.text_to_html(text)[source]
Convert plain text to safe HTML paragraphs and line breaks.
- fleetmesh_node.planes.services.gateway.translate.nostr_to_unified(event)[source]
Translate a Nostr Kind 1 event to UnifiedPost.
- Parameters:
- Return type:
- fleetmesh_node.planes.services.gateway.translate.unified_to_nostr(post, pubkey=None)[source]
Translate UnifiedPost to a Nostr Kind 1 event structure.
- Parameters:
post (UnifiedPost)
pubkey (str | None)
- Return type:
- fleetmesh_node.planes.services.gateway.translate.atproto_to_unified(record, author='')[source]
Translate an ATProto app.bsky.feed.post record to UnifiedPost.
- Parameters:
- Return type:
- fleetmesh_node.planes.services.gateway.translate.unified_to_atproto(post)[source]
Translate UnifiedPost to an ATProto app.bsky.feed.post record.
- Parameters:
post (UnifiedPost)
- Return type:
- fleetmesh_node.planes.services.gateway.translate.activitypub_to_unified(doc)[source]
Translate an ActivityPub Note or Create activity to UnifiedPost.
- Parameters:
- Return type:
- fleetmesh_node.planes.services.gateway.translate.unified_to_activitypub(post, domain='node.fleetmesh.local', wrap_in_create=True)[source]
Translate UnifiedPost to an ActivityPub Note (or Create(Note)).
- fleetmesh_node.planes.services.gateway.translate.ssb_to_unified(msg)[source]
Translate an SSB message document or post content to UnifiedPost.
- Parameters:
- Return type:
- fleetmesh_node.planes.services.gateway.translate.unified_to_ssb(post)[source]
Translate UnifiedPost to an SSB post content structure.
- Parameters:
post (UnifiedPost)
- Return type:
- fleetmesh_node.planes.services.gateway.translate.p2panda_to_unified(doc)[source]
Translate a p2panda operation dict or payload mapping to UnifiedPost.
- Parameters:
- Return type:
- fleetmesh_node.planes.services.gateway.translate.unified_to_p2panda(post)[source]
Translate UnifiedPost to a p2panda operation payload structure.
- Parameters:
post (UnifiedPost)
- Return type:
- fleetmesh_node.planes.services.gateway.translate.rhio_to_unified(doc)[source]
Translate a Rhio cluster envelope or payload mapping to UnifiedPost.
- Parameters:
- Return type:
- fleetmesh_node.planes.services.gateway.translate.unified_to_rhio(post, subject='fleetmesh.posts')[source]
Translate UnifiedPost to a Rhio JetStream publication envelope.
- Parameters:
post (UnifiedPost)
subject (str)
- Return type:
- class fleetmesh_node.planes.services.gateway.translate.ProtocolTranslator[source]
Bases:
objectDispatches bidirectional translations across all supported protocols.
- INGEST_MAP = {'activitypub': <function activitypub_to_unified>, 'atproto': <function atproto_to_unified>, 'nostr': <function nostr_to_unified>, 'p2panda': <function p2panda_to_unified>, 'rhio': <function rhio_to_unified>, 'ssb': <function ssb_to_unified>}
- EMIT_MAP = {'activitypub': <function unified_to_activitypub>, 'atproto': <function unified_to_atproto>, 'nostr': <function unified_to_nostr>, 'p2panda': <function unified_to_p2panda>, 'rhio': <function unified_to_rhio>, 'ssb': <function unified_to_ssb>}
- classmethod to_unified(source_protocol, payload, **kwargs)[source]
Parse source protocol payload into UnifiedPost.
Unified peering capacity, rate-limiting, and Cashu ecash settlement.
Enforces bilateral resource quotas and Cashu NUT-18 / NUT-24 ecash settlement across all four protocol boundaries: - Nostr relays & paid filters - ATProto XRPC & Firehose sync - ActivityPub S2S federation & media delivery - Secure Scuttlebutt MuxRPC & Blob sync
- exception fleetmesh_node.planes.services.gateway.settle.GatewaySettlementError[source]
Bases:
FleetmeshErrorRaised on settlement or quota verification failures.
- class fleetmesh_node.planes.services.gateway.settle.CrossProtocolPeer[source]
Bases:
objectA tracked peer communicating across any supported wire protocol.
- bucket: TokenBucket
- __init__(protocol, peer_id, bucket, balance_sat=0, total_consumed_tokens=0, total_settled_sat=0, penalty_score=0.0, created_at=<factory>)
- class fleetmesh_node.planes.services.gateway.settle.PaymentChallenge[source]
Bases:
objectStandardized payment challenge issued when a peer exceeds quota.
- class fleetmesh_node.planes.services.gateway.settle.SettlementReceipt[source]
Bases:
objectProof of completed ecash settlement credit.
- class fleetmesh_node.planes.services.gateway.settle.CrossProtocolSettlementGateway[source]
Bases:
objectUnified resource accounting, rate limiting, and ecash settlement gateway.
- __init__(default_capacity=30.0, default_refill_per_sec=0.5, price_per_topup_sat=21, tokens_per_topup=100, mint_url=None, max_penalty_score=10.0)[source]
- get_or_create_peer(protocol, peer_id, capacity=None, refill_rate=None)[source]
Fetch or initialize a tracked peer record.
- Parameters:
- Return type:
- record_penalty(protocol, peer_id, penalty=1.0)[source]
Increase penalty score for bad behavior (e.g. invalid signatures, flooding).