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: Compartment

The settlement compartment of meshnode (NIP-61 Nutzap & Lightning hold-invoices).

name: str | None = 'settle'
attr: str | None = 'settlement'
DB: str = 'settlements.sqlite'
reads: tuple[str, ...] = ('settlement', 'compute')
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.

Parameters:
Return type:

None

show_cmd()[source]
Return type:

SettleShowDict

create_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

hold_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

bool

settle_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

bool

reconcile_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

stream_pay_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

cancel_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

bool

nutzap_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Any

expand_grant_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

nwc_pay_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

cashu_swap_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

cashu_melt_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

abstract: ClassVar[bool] = False
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'}}
live: tuple[str, ...] = ()
stop()[source]

Anything that must be said before the node goes. Must not raise.

Return type:

Any

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.

Parameters:

tier (str)

Return type:

Mapping[str, Any]

class fleetmesh_node.planes.services.settle.engine.SettlementEngine[source]

Bases: object

Manages 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]
Parameters:
  • db_path (str)

  • clock (Any | None)

  • mint_url (str | None)

  • mint_privkey_hex (str | None)

  • nwc_uri (str | None)

  • use_live_cashu (bool)

  • node_pk (str | None)

  • allow_unverified_proofs (bool)

  • db (Any | None)

Return type:

None

register_rail(rail_id, rail)[source]
Parameters:
  • rail_id (str)

  • rail (PaymentRail)

Return type:

None

get_rail(rail_id)[source]
Parameters:

rail_id (str)

Return type:

PaymentRail

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.

Parameters:
  • ask_id (str)

  • buyer_pk (str)

  • seller_pk (str)

  • amount_msat (int)

  • payment_hash (str)

  • rail_id (str)

Return type:

Mapping[str, Any]

hold_escrow(ask_id, token_or_proof=None)[source]

Lock funds into escrow.

Parameters:
  • ask_id (str)

  • token_or_proof (Any)

Return type:

bool

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.

Parameters:
Return type:

bool

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.

Parameters:
Return type:

bool

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.

Parameters:
  • ask_id (str)

  • actual_cost_msat (int)

  • preimage (str)

Return type:

Mapping[str, Any]

stream_micropayment(ask_id, delta_tokens, rate_msat_per_token, cashu_token=None)[source]

Process Pay-As-You-Stream micropayment milestone (Cashu Nutzap).

Parameters:
  • ask_id (str)

  • delta_tokens (int)

  • rate_msat_per_token (int)

  • cashu_token (str | None)

Return type:

Mapping[str, Any]

get_escrow(ask_id)[source]

Retrieve escrow record by ask_id.

Parameters:

ask_id (str)

Return type:

EscrowRowDict | None

list_escrows(limit=50)[source]
Parameters:

limit (int)

Return type:

list[EscrowRowDict]

close()[source]

Safely close underlying settlement database.

Return type:

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.

Parameters:
Return type:

Mapping[str, Any]

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.

Parameters:
Return type:

Sidecar

class fleetmesh_node.planes.services.sidecars.compartment.ProbeResult[source]

Bases: NamedTuple

What one check said. status is the HTTP status when there was one.

name: str

Alias for field number 0

ok: bool

Alias for field number 1

status: int | None

Alias for field number 2

why: str

Alias for field number 3

static __new__(_cls, name, ok, status, why)

Create new instance of ProbeResult(name, ok, status, why)

Parameters:
fleetmesh_node.planes.services.sidecars.compartment.run_check(fetch, endpoint, check)[source]

One check against one endpoint, never raising.

Parameters:
Return type:

ProbeResult

class fleetmesh_node.planes.services.sidecars.compartment.Sidecars[source]

Bases: Compartment

Declares one capability per sidecar whose self-tests pass, and keeps testing the sidecars behind them. See module docstring for what it does not do.

name: str | None = 'sidecars'
reads: tuple[str, ...] = ('sidecars', 'grasp', 'ncontainer', 'magpie')
live: tuple[str, ...] = ('grasp', 'ncontainer', 'magpie')
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

block(name)[source]
Parameters:

name (str)

Return type:

SidecarEntry

enabled(name)[source]
Parameters:

name (str)

Return type:

bool

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]

manifest(name)[source]
Parameters:

name (str)

Return type:

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

grasp_enabled()[source]
Return type:

bool

ncontainer_enabled()[source]
Return type:

bool

magpie_enabled()[source]
Return type:

bool

verified(name)[source]

Enabled now AND its last self-test passed.

Parameters:

name (str)

Return type:

bool

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.

Return type:

list[str]

descriptor_tags()[source]

<name>-endpoint, only for a verified sidecar - see schema/kinds.json’s note on kind 11801.

Return type:

list[list[str]]

test(name, now=None)[source]

Run one sidecar’s checks now. Records the verdict; does not redeclare.

Parameters:
Return type:

list[ProbeResult]

test_all(now=None, only=None)[source]
Parameters:
  • now (int | None)

  • only (str | None)

Return type:

dict[str, list[ProbeResult]]

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:

bool

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

tick(now)[source]

Periodic work. Runs due EVERY jobs when not overridden.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

Mapping[str, Any]

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.

Return type:

list[str]

list_sidecars()[source]
Return type:

Mapping[str, Any]

run_sidecar_test(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

stop()[source]

Anything that must be said before the node goes. Must not raise.

Return type:

Any

abstract: ClassVar[bool] = False
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

optional: bool = True
enabled_by: str | None = 'compute'

The compute/1.0 compartment of meshnode.

name: str | None = 'compute'
piuris: tuple[str, ...] = ('https://fleetmesh.org/compute/1.0', 'https://fleetmesh.org/compute/1.1')
reads: tuple[str, ...] = ('compute', 'executors', 'relays')
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]
Parameters:
Return type:

None

handle(inbound)[source]

Answer an inbound wire protocol message according to HANDLERS declarations.

Parameters:

inbound (Any)

Return type:

tuple[Any, …] | None

index_offer(offer)[source]
Parameters:

offer (NostrEvent)

Return type:

bool

index_ask(ask)[source]
Parameters:

ask (NostrEvent)

Return type:

bool

find_offers_for_ask(ask, trust_weights=None)[source]
Parameters:
Return type:

list[Mapping[str, Any]]

find_asks_for_offer(offer)[source]
Parameters:

offer (NostrEvent | Mapping[str, Any] | str)

Return type:

list[Mapping[str, Any]]

state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

Mapping[str, Any]

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.

Return type:

list[str]

receipts_cmd()[source]
Return type:

list[Mapping[str, Any]]

book_cmd()[source]
Return type:

Mapping[str, Any]

index_offer_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

bool

index_ask_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

bool

match_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

list[Any]

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.

Parameters:
Return type:

Mapping[str, Any]

abstract: ClassVar[bool] = False
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'}}
live: tuple[str, ...] = ()

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: object

Registry managing available compute runtime execution drivers.

__init__(blob_store=None, mock_mode=False, media_cache_dir=None, provider_router=None)[source]
Parameters:
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:
Return type:

None

register(executor, *aliases)[source]
Parameters:
  • executor (ExecutorProtocol)

  • aliases (str)

Return type:

None

get(engine_id)[source]
Parameters:

engine_id (str)

Return type:

ExecutorProtocol | 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.

Return type:

list[str]

select_for_job(job_payload)[source]
Parameters:

job_payload (Mapping[str, Any])

Return type:

ExecutorProtocol

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: object

Runtime execution context provided to tools during an agent reasoning step.

task: str
delegation: Mapping[str, Any]
budget_cap_msat: int = 0
budget_spent_msat: int = 0
blob_store: Any | None = None
blossom_servers: list[str]
sub_ask_dispatcher: Callable[[Mapping[str, Any]], Mapping[str, Any]] | None = None
fuel_cap: int = 100000
fuel_used: int = 0
sub_asks_dispatched: list[AgentSubAsk]
depth: int = 0
harness_profile: AgentProfileSpec | None = None
domain_context: Mapping[str, Any]
get_remaining_budget()[source]

Remaining msat budget permitted for child sub-delegation asks.

Return type:

int

deduct_delegation(amount_msat)[source]

Atomically deduct allocated msat from remaining budget and return granted amount.

Parameters:

amount_msat (int)

Return type:

int

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: TypedDict

Result returned by an agent tool execution.

output: Any
error: str | None
fuel_consumed: int
sub_ask_id: str | None
class fleetmesh_node.planes.services.compute.executors.agent.AgentToolProtocol[source]

Bases: Protocol

Interface for agent-invocable tools.

name: str
description: str
parameters_schema: Mapping[str, Any]
execute(params, context)[source]
Parameters:
Return type:

AgentToolResult

__init__(*args, **kwargs)
class fleetmesh_node.planes.services.compute.executors.agent.AgentDecision[source]

Bases: object

Action decision formulated by an agent reasoning backend.

thought: str
action: str
action_input: Any
is_finish: bool = False
final_answer: str | None = None
__init__(thought, action, action_input=<factory>, is_finish=False, final_answer=None)
Parameters:
  • thought (str)

  • action (str)

  • action_input (Any)

  • is_finish (bool)

  • final_answer (str | None)

Return type:

None

class fleetmesh_node.planes.services.compute.executors.agent.AgentBackendProtocol[source]

Bases: Protocol

Reasoning backend providing Thought and Action generation for the ReAct loop.

is_live_runnable()[source]
Return type:

bool

decide_step(task, trace, tools, context)[source]
Parameters:
Return type:

AgentDecision

__init__(*args, **kwargs)
class fleetmesh_node.planes.services.compute.executors.agent.CalculatorTool[source]

Bases: object

Safe arithmetic expression evaluator using AST inspection (no arbitrary code execution).

name: str = 'calc'
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:
Return type:

AgentToolResult

class fleetmesh_node.planes.services.compute.executors.agent.Sha256Tool[source]

Bases: object

Cryptographic SHA-256 hash calculator.

name: str = 'sha256'
description: str = 'Computes SHA-256 digest of input text or binary hex.'
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:
Return type:

AgentToolResult

class fleetmesh_node.planes.services.compute.executors.agent.RegexSearchTool[source]

Bases: object

Safe regular expression pattern search and extraction tool.

name: str = 'regex_search'
description: str = 'Searches text using a regular expression pattern and returns matches.'
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:
Return type:

AgentToolResult

class fleetmesh_node.planes.services.compute.executors.agent.FetchBlobTool[source]

Bases: object

Blossom CAS blob retrieval tool.

name: str = 'fetch_blob'
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:
Return type:

AgentToolResult

class fleetmesh_node.planes.services.compute.executors.agent.SubAskTool[source]

Bases: object

Recursive child-Ask mesh delegation tool.

name: str = 'sub_ask'
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:
Return type:

AgentToolResult

class fleetmesh_node.planes.services.compute.executors.agent.FinishTool[source]

Bases: object

Terminal tool to conclude the ReAct loop and return the final synthesized answer.

name: str = 'finish'
description: str = 'Concludes execution and provides 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:
Return type:

AgentToolResult

class fleetmesh_node.planes.services.compute.executors.agent.ScriptedAgentBackend[source]

Bases: object

Deterministic ReAct reasoning backend for testing, fixtures, and scripted workflows.

__init__(scripted_steps=None)[source]
Parameters:

scripted_steps (Sequence[AgentDecision] | None)

Return type:

None

is_live_runnable()[source]
Return type:

bool

decide_step(task, trace, tools, context)[source]
Parameters:
Return type:

AgentDecision

class fleetmesh_node.planes.services.compute.executors.agent.LlmAgentBackend[source]

Bases: object

Live 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]
Parameters:
  • endpoint (str)

  • model (str)

  • timeout_seconds (float)

  • api_key (str)

  • cashu_token (str)

  • provider_id (str)

  • provider_router (Any | None)

Return type:

None

is_live_runnable()[source]
Return type:

bool

decide_step(task, trace, tools, context)[source]
Parameters:
Return type:

AgentDecision

class fleetmesh_node.planes.services.compute.executors.agent.AgentExecutor[source]

Bases: ComputeExecutor

Autonomous ReAct agent harness (Reasoning + Action loop with tool dispatch).

engine_id: str = 'agent'
wasi_profile_digest: str = 'fleetmesh-react-v1'
__init__(max_steps_default=25, mock_mode=False, backend=None, tools=None, sub_ask_dispatcher=None, harness_registry=None)[source]
Parameters:
Return type:

None

tools: dict[str, AgentToolProtocol]
is_live_runnable()[source]

Returns True if the executor is capable of servicing live compute requests.

Return type:

bool

register_tool(tool)[source]

Register a new tool into the agent harness.

Parameters:

tool (AgentToolProtocol)

Return type:

None

quote(module_spec, input_spec, limits)[source]

Estimate fuel and return price quote.

Parameters:
Return type:

ComputeQuote

execute(job_payload, fuel_cap)[source]

Execute a verified module with metered fuel limits.

Parameters:
Return type:

ComputeExecutionResult

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: ComputeExecutor

Zero-Knowledge Groth16 proof verifier runtime (compute:zk-verify-groth16/1.0).

engine_id: str = 'zk-verify-groth16'
wasi_profile_digest: str = 'b9ff4b513efb50d3ce3ca68c9758a35804f444ba3b20a174c4af5469a05abd1d'
is_live_runnable()[source]

Groth16 verification is pure cryptographic evaluation and is always operational.

Return type:

bool

quote(module_spec, input_spec, limits)[source]

Estimate fuel and return price quote.

Parameters:
Return type:

ComputeQuote

execute(job_payload, fuel_cap)[source]

Execute a verified module with metered fuel limits.

Parameters:
Return type:

ComputeExecutionResult

class fleetmesh_node.planes.services.compute.executors.zk.ZkVmReceiptResult[source]

Bases: NamedTuple

Result of validating a STARK / SNARK zkVM receipt.

valid: bool

Alias for field number 0

image_id: str

Alias for field number 1

journal: bytes

Alias for field number 2

journal_hash: str

Alias for field number 3

proof_system: str

Alias for field number 4

cycles: int

Alias for field number 5

error: str

Alias for field number 6

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)

Parameters:
class fleetmesh_node.planes.services.compute.executors.zk.ZkVmVerifierProtocol[source]

Bases: Protocol

Protocol 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.

Parameters:
Return type:

ZkVmReceiptResult

is_available()[source]

Check whether the verifier backend is operational on this host.

Return type:

bool

__init__(*args, **kwargs)
class fleetmesh_node.planes.services.compute.executors.zk.ZkVmReceiptVerifier[source]

Bases: object

Production zkVM receipt verifier supporting STARK-to-Groth16 wrapping.

__init__(pinned_control_ids=None)[source]
Parameters:

pinned_control_ids (Sequence[str] | None)

Return type:

None

is_available()[source]

Receipt verification over BN254 Groth16 is always available via pure-Python pairing.

Return type:

bool

verify_receipt(image_id, journal, seal, proof_system='risc0-groth16', custom_vk=None)[source]
Parameters:
Return type:

ZkVmReceiptResult

class fleetmesh_node.planes.services.compute.executors.zk.MockZkVmVerifier[source]

Bases: object

Deterministic test double for zkVM receipt verification.

__init__(simulate_failure=False)[source]
Parameters:

simulate_failure (bool)

Return type:

None

verified_receipts: list[ZkVmReceiptResult]
is_available()[source]
Return type:

bool

verify_receipt(image_id, journal, seal, proof_system='risc0-groth16', custom_vk=None)[source]
Parameters:
Return type:

ZkVmReceiptResult

class fleetmesh_node.planes.services.compute.executors.zk.ZkVmExecutor[source]

Bases: ComputeExecutor

Zero-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.

engine_id: str = 'zkvm-risc0'
wasi_profile_digest: str = '36e343dfb9d70a15156de1cd2c8d2f3595d0b4d94a6ef1811feae51451f33770'
__init__(mock_mode=False, verifier=None)[source]
Parameters:
Return type:

None

is_live_runnable()[source]

Check whether zkVM verification can execute on this node.

Return type:

bool

quote(module_spec, input_spec, limits)[source]

Estimate fuel and return price quote.

Parameters:
Return type:

ComputeQuote

execute(job_payload, fuel_cap)[source]

Execute a verified module with metered fuel limits.

Parameters:
Return type:

ComputeExecutionResult

class fleetmesh_node.planes.services.compute.executors.zk.ZkProverResult[source]

Bases: NamedTuple

Result of generating a zero-knowledge proof.

proof: Mapping[str, Any] | bytes

Alias for field number 0

public_inputs: Sequence[Any]

Alias for field number 1

journal: bytes

Alias for field number 2

cycles_used: int

Alias for field number 3

static __new__(_cls, proof, public_inputs, journal, cycles_used)

Create new instance of ZkProverResult(proof, public_inputs, journal, cycles_used)

Parameters:
  • proof (Mapping[str, Any] | bytes)

  • public_inputs (Sequence[Any])

  • journal (bytes)

  • cycles_used (int)

class fleetmesh_node.planes.services.compute.executors.zk.ZkProverProtocol[source]

Bases: Protocol

Protocol 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.

Parameters:
Return type:

ZkProverResult

is_available()[source]

Check whether the prover backend is operational.

Return type:

bool

__init__(*args, **kwargs)
class fleetmesh_node.planes.services.compute.executors.zk.MockZkProverClient[source]

Bases: object

Test double for off-chain zero-knowledge prover service.

__init__(simulate_failure=False)[source]
Parameters:

simulate_failure (bool)

Return type:

None

generated_proofs: list[ZkProverResult]
is_available()[source]
Return type:

bool

generate_proof(program_spec, private_inputs, public_inputs=())[source]
Parameters:
Return type:

ZkProverResult

class fleetmesh_node.planes.services.compute.executors.zk.ZkProverExecutor[source]

Bases: ComputeExecutor

Off-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.

engine_id: str = 'zk-prove-groth16'
wasi_profile_digest: str = 'a3339ec77a36fa5f66202aeb3a74eacf6aad1ef488e473c27d3f99f8a4c9a7b8'
__init__(mock_mode=False, prover_client=None)[source]
Parameters:
Return type:

None

is_live_runnable()[source]

Check whether the prover service is active and ready.

Return type:

bool

quote(module_spec, input_spec, limits)[source]

Estimate fuel and return price quote.

Parameters:
Return type:

ComputeQuote

execute(job_payload, fuel_cap)[source]

Execute a verified module with metered fuel limits.

Parameters:
Return type:

ComputeExecutionResult

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: NamedTuple

Result of staging Blossom CAS input blobs into container mount points.

staged_paths: list[str]

Alias for field number 0

total_bytes: int

Alias for field number 1

files: dict[str, bytes]

Alias for field number 2

source_cids: list[str]

Alias for field number 3

static __new__(_cls, staged_paths, total_bytes, files, source_cids)

Create new instance of BlossomStagingResult(staged_paths, total_bytes, files, source_cids)

Parameters:
class fleetmesh_node.planes.services.compute.executors.bacalhau.BlossomUploadResult[source]

Bases: NamedTuple

Result of packaging and committing container outputs to Blossom CAS.

result_cid: str

Alias for field number 0

result_hash: str

Alias for field number 1

output_bytes: bytes

Alias for field number 2

mounted_outputs: list[str]

Alias for field number 3

static __new__(_cls, result_cid, result_hash, output_bytes, mounted_outputs)

Create new instance of BlossomUploadResult(result_cid, result_hash, output_bytes, mounted_outputs)

Parameters:
class fleetmesh_node.planes.services.compute.executors.bacalhau.BacalhauTaskSpec[source]

Bases: TypedDict

Specification of a single Bacalhau container task.

name: str
engine: str
image: str
entrypoint: list[str]
parameters: list[str]
env: dict[str, str]
input_sources: list[Mapping[str, Any]]
result_paths: list[Mapping[str, Any]]
resources: Mapping[str, Any]
timeouts: dict[str, int]
class fleetmesh_node.planes.services.compute.executors.bacalhau.BacalhauClientProtocol[source]

Bases: Protocol

Interface required for Bacalhau orchestrator connectors.

submit_job(job_payload, timeout_seconds=300)[source]

Submit a batch job specification and return assigned JobID.

Parameters:
Return type:

str

get_job_status(job_id)[source]

Query execution lifecycle state for the given job_id.

Parameters:

job_id (str)

Return type:

Mapping[str, Any]

get_job_results(job_id)[source]

Fetch outputs, logs, and artifacts for a completed job.

Parameters:

job_id (str)

Return type:

Mapping[str, Any]

cancel_job(job_id, reason='')[source]

Abort or terminate a running Bacalhau job.

Parameters:
Return type:

bool

is_alive()[source]

Check if the Bacalhau daemon/orchestrator endpoint is reachable.

Return type:

bool

__init__(*args, **kwargs)
class fleetmesh_node.planes.services.compute.executors.bacalhau.BacalhauRestClient[source]

Bases: object

Live Bacalhau REST API v1 connector using Fleetmesh netfetch.

__init__(endpoint='http://127.0.0.1:1234', timeout_seconds=30.0)[source]
Parameters:
  • endpoint (str)

  • timeout_seconds (float)

Return type:

None

endpoint: str
timeout_seconds: float
is_alive()[source]

Check if the Bacalhau daemon endpoint responds to health probes.

Return type:

bool

build_bacalhau_job_spec(job_payload)[source]

Convert Fleetmesh job descriptor into standard Bacalhau v1 format.

Parameters:

job_payload (Mapping[str, Any])

Return type:

Mapping[str, Any]

submit_job(job_payload, timeout_seconds=300)[source]

Submit a job specification to the Bacalhau orchestrator.

Parameters:
Return type:

str

get_job_status(job_id)[source]

Fetch current state of a Bacalhau job.

Parameters:

job_id (str)

Return type:

Mapping[str, Any]

get_job_results(job_id)[source]

Fetch results and output references for a completed job.

Parameters:

job_id (str)

Return type:

Mapping[str, Any]

cancel_job(job_id, reason='')[source]

Cancel an in-flight Bacalhau job.

Parameters:
Return type:

bool

class fleetmesh_node.planes.services.compute.executors.bacalhau.MockBacalhauClient[source]

Bases: object

Test double implementing BacalhauClientProtocol for isolated and mock tests.

__init__(simulate_failure=False)[source]
Parameters:

simulate_failure (bool)

Return type:

None

submitted_jobs: list[Mapping[str, Any]]
cancelled_jobs: list[str]
simulate_failure: bool
call_history: list[str]
is_alive()[source]
Return type:

bool

submit_job(job_payload, timeout_seconds=300)[source]
Parameters:
Return type:

str

get_job_status(job_id)[source]
Parameters:

job_id (str)

Return type:

Mapping[str, Any]

get_job_results(job_id)[source]
Parameters:

job_id (str)

Return type:

Mapping[str, Any]

cancel_job(job_id, reason='')[source]
Parameters:
Return type:

bool

class fleetmesh_node.planes.services.compute.executors.bacalhau.BlossomMountBridge[source]

Bases: object

Manages 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.

Parameters:
Return type:

BlossomStagingResult

package_and_upload_outputs(raw_output_or_files, output_mounts, blob_store=None, blossom_servers=None)[source]

Hash, persist, and register job output artifacts into Blossom CAS.

Parameters:
Return type:

BlossomUploadResult

class fleetmesh_node.planes.services.compute.executors.bacalhau.BacalhauExecutor[source]

Bases: ComputeExecutor

Compute-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).

engine_id: str = 'bacalhau'
wasi_profile_digest: str = ''
__init__(endpoint='http://127.0.0.1:1234', mock_mode=False, client=None, mount_bridge=None)[source]
Parameters:
Return type:

None

is_live_runnable()[source]

Check whether Bacalhau execution can succeed on this node.

Return type:

bool

quote(module_spec, input_spec, limits)[source]

Estimate fuel and return price quote.

Parameters:
Return type:

ComputeQuote

execute(job_payload, fuel_cap, progress_callback=None, cancellation_token=None)[source]

Execute a verified module with metered fuel limits.

Parameters:
Return type:

ComputeExecutionResult

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: ComputeExecutor

Non-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.

engine_id: str = 'llm'
wasi_profile_digest: str = ''
__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]
Parameters:
Return type:

None

is_live_runnable()[source]

Check whether LLM inference can execute on this node.

Return type:

bool

quote(module_spec, input_spec, limits)[source]

Estimate fuel and return price quote.

Parameters:
Return type:

ComputeQuote

execute(job_payload, fuel_cap)[source]

Execute a verified module with metered fuel limits.

Parameters:
Return type:

ComputeExecutionResult

class fleetmesh_node.planes.services.compute.executors.nondet.BacalhauExecutor[source]

Bases: ComputeExecutor

Compute-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).

engine_id: str = 'bacalhau'
wasi_profile_digest: str = ''
__init__(endpoint='http://127.0.0.1:1234', mock_mode=False, client=None, mount_bridge=None)[source]
Parameters:
Return type:

None

is_live_runnable()[source]

Check whether Bacalhau execution can succeed on this node.

Return type:

bool

quote(module_spec, input_spec, limits)[source]

Estimate fuel and return price quote.

Parameters:
Return type:

ComputeQuote

execute(job_payload, fuel_cap, progress_callback=None, cancellation_token=None)[source]

Execute a verified module with metered fuel limits.

Parameters:
Return type:

ComputeExecutionResult

class fleetmesh_node.planes.services.compute.executors.nondet.AgentExecutor[source]

Bases: ComputeExecutor

Autonomous ReAct agent harness (Reasoning + Action loop with tool dispatch).

engine_id: str = 'agent'
wasi_profile_digest: str = 'fleetmesh-react-v1'
__init__(max_steps_default=25, mock_mode=False, backend=None, tools=None, sub_ask_dispatcher=None, harness_registry=None)[source]
Parameters:
Return type:

None

tools: dict[str, AgentToolProtocol]
is_live_runnable()[source]

Returns True if the executor is capable of servicing live compute requests.

Return type:

bool

register_tool(tool)[source]

Register a new tool into the agent harness.

Parameters:

tool (AgentToolProtocol)

Return type:

None

quote(module_spec, input_spec, limits)[source]

Estimate fuel and return price quote.

Parameters:
Return type:

ComputeQuote

execute(job_payload, fuel_cap)[source]

Execute a verified module with metered fuel limits.

Parameters:
Return type:

ComputeExecutionResult

class fleetmesh_node.planes.services.compute.executors.nondet.AgentExecutionContext[source]

Bases: object

Runtime execution context provided to tools during an agent reasoning step.

task: str
delegation: Mapping[str, Any]
budget_cap_msat: int = 0
budget_spent_msat: int = 0
blob_store: Any | None = None
blossom_servers: list[str]
sub_ask_dispatcher: Callable[[Mapping[str, Any]], Mapping[str, Any]] | None = None
fuel_cap: int = 100000
fuel_used: int = 0
sub_asks_dispatched: list[AgentSubAsk]
depth: int = 0
harness_profile: AgentProfileSpec | None = None
domain_context: Mapping[str, Any]
get_remaining_budget()[source]

Remaining msat budget permitted for child sub-delegation asks.

Return type:

int

deduct_delegation(amount_msat)[source]

Atomically deduct allocated msat from remaining budget and return granted amount.

Parameters:

amount_msat (int)

Return type:

int

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: Protocol

Interface for agent-invocable tools.

name: str
description: str
parameters_schema: Mapping[str, Any]
execute(params, context)[source]
Parameters:
Return type:

AgentToolResult

__init__(*args, **kwargs)
class fleetmesh_node.planes.services.compute.executors.nondet.AgentToolResult[source]

Bases: TypedDict

Result returned by an agent tool execution.

output: Any
error: str | None
fuel_consumed: int
sub_ask_id: str | None
class fleetmesh_node.planes.services.compute.executors.nondet.AgentDecision[source]

Bases: object

Action decision formulated by an agent reasoning backend.

thought: str
action: str
action_input: Any
is_finish: bool = False
final_answer: str | None = None
__init__(thought, action, action_input=<factory>, is_finish=False, final_answer=None)
Parameters:
  • thought (str)

  • action (str)

  • action_input (Any)

  • is_finish (bool)

  • final_answer (str | None)

Return type:

None

class fleetmesh_node.planes.services.compute.executors.nondet.AgentBackendProtocol[source]

Bases: Protocol

Reasoning backend providing Thought and Action generation for the ReAct loop.

is_live_runnable()[source]
Return type:

bool

decide_step(task, trace, tools, context)[source]
Parameters:
Return type:

AgentDecision

__init__(*args, **kwargs)
class fleetmesh_node.planes.services.compute.executors.nondet.CalculatorTool[source]

Bases: object

Safe arithmetic expression evaluator using AST inspection (no arbitrary code execution).

name: str = 'calc'
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:
Return type:

AgentToolResult

class fleetmesh_node.planes.services.compute.executors.nondet.Sha256Tool[source]

Bases: object

Cryptographic SHA-256 hash calculator.

name: str = 'sha256'
description: str = 'Computes SHA-256 digest of input text or binary hex.'
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:
Return type:

AgentToolResult

class fleetmesh_node.planes.services.compute.executors.nondet.RegexSearchTool[source]

Bases: object

Safe regular expression pattern search and extraction tool.

name: str = 'regex_search'
description: str = 'Searches text using a regular expression pattern and returns matches.'
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:
Return type:

AgentToolResult

class fleetmesh_node.planes.services.compute.executors.nondet.FetchBlobTool[source]

Bases: object

Blossom CAS blob retrieval tool.

name: str = 'fetch_blob'
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:
Return type:

AgentToolResult

class fleetmesh_node.planes.services.compute.executors.nondet.SubAskTool[source]

Bases: object

Recursive child-Ask mesh delegation tool.

name: str = 'sub_ask'
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:
Return type:

AgentToolResult

class fleetmesh_node.planes.services.compute.executors.nondet.FinishTool[source]

Bases: object

Terminal tool to conclude the ReAct loop and return the final synthesized answer.

name: str = 'finish'
description: str = 'Concludes execution and provides 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:
Return type:

AgentToolResult

class fleetmesh_node.planes.services.compute.executors.nondet.ScriptedAgentBackend[source]

Bases: object

Deterministic ReAct reasoning backend for testing, fixtures, and scripted workflows.

__init__(scripted_steps=None)[source]
Parameters:

scripted_steps (Sequence[AgentDecision] | None)

Return type:

None

is_live_runnable()[source]
Return type:

bool

decide_step(task, trace, tools, context)[source]
Parameters:
Return type:

AgentDecision

class fleetmesh_node.planes.services.compute.executors.nondet.LlmAgentBackend[source]

Bases: object

Live 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]
Parameters:
  • endpoint (str)

  • model (str)

  • timeout_seconds (float)

  • api_key (str)

  • cashu_token (str)

  • provider_id (str)

  • provider_router (Any | None)

Return type:

None

is_live_runnable()[source]
Return type:

bool

decide_step(task, trace, tools, context)[source]
Parameters:
Return type:

AgentDecision

class fleetmesh_node.planes.services.compute.executors.nondet.ProviderPreset[source]

Bases: object

ProviderPreset(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>)

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]
__init__(provider_id, label, endpoint, default_model, models, auth_scheme, wire_format, env_key, rate_msat_per_token, extra_headers=<factory>)
Parameters:
Return type:

None

class fleetmesh_node.planes.services.compute.executors.nondet.LinkedProviderConfig[source]

Bases: object

Operator-linked configuration for a single inference provider.

provider_id: str
endpoint: str
default_model: str
models: tuple[str, ...] = ()
api_key: str = ''
cashu_token: str = ''
cashu_mint: str = ''
auth_scheme: str = 'bearer'
wire_format: str = 'openai'
rate_msat_per_token: int = 12
enabled: bool = True
label: str = ''
extra_headers: dict[str, str]
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:
  • provider_id (str)

  • endpoint (str | None)

  • default_model (str | None)

  • models (Sequence[str] | None)

  • api_key (str | None)

  • cashu_token (str | None)

  • cashu_mint (str | None)

  • rate_msat_per_token (int | None)

  • enabled (bool)

  • extra_headers (Mapping[str, str] | None)

Return type:

LinkedProviderConfig

has_credentials()[source]
Return type:

bool

is_runnable()[source]
Return type:

bool

build_headers(per_query_cashu_token=None)[source]
Parameters:

per_query_cashu_token (str | None)

Return type:

dict[str, str]

format_request(*, messages, model=None, max_tokens=512, temperature=0.7, top_p=1.0, seed=None, grammar=None, stream=False)[source]
Parameters:
Return type:

tuple[str, dict[str, Any]]

parse_response(resp_data, default_prompt_tokens=1)[source]
Parameters:
Return type:

tuple[str, int, int]

to_public_dict()[source]

Serialize provider metadata without exposing secret API keys or Cashu tokens.

Return type:

dict[str, Any]

__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>)
Parameters:
Return type:

None

class fleetmesh_node.planes.services.compute.executors.nondet.OperatorProviderRouter[source]

Bases: object

Registry of operator-linked LLM providers on a FleetMesh node.

__init__(providers=None, default_provider=None)[source]
Parameters:
Return type:

None

default_provider: str | None
register_provider(config, set_default=False)[source]
Parameters:
Return type:

None

remove_provider(provider_id)[source]
Parameters:

provider_id (str)

Return type:

bool

get_provider(provider_id=None)[source]
Parameters:

provider_id (str | None)

Return type:

LinkedProviderConfig | None

resolve_for_job(job_payload)[source]
Parameters:

job_payload (Mapping[str, Any])

Return type:

LinkedProviderConfig | None

runnable_providers()[source]
Return type:

list[LinkedProviderConfig]

list_public_providers()[source]
Return type:

list[dict[str, Any]]

classmethod from_env()[source]

Auto-discover any operator-configured providers from environment variables.

Return type:

OperatorProviderRouter

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.wasmtime_available()[source]
Return type:

bool

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).

Parameters:
Return type:

tuple[bytes, int]

class fleetmesh_node.planes.services.compute.executors.wasm.WasmExecutor[source]

Bases: ComputeExecutor

Deterministic WASI runtime driver (fleetmesh-wasi-v1 profile).

engine_id: str = 'wasmtime'
wasi_profile_digest: str = 'bf0dcd1c516cc57b2bc25dac81dffbb5520ecc7bfbf36bf79a5936c45636f0bf'
is_live_runnable()[source]

Check whether wasmtime engine is installed and available on this host.

Return type:

bool

quote(module_spec, input_spec, limits)[source]

Estimate fuel and return price quote.

Parameters:
Return type:

ComputeQuote

execute(job_payload, fuel_cap)[source]

Execute a verified module with metered fuel limits.

Parameters:
Return type:

ComputeExecutionResult

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: WireProtocol

The compute/1.0 and compute/1.1 wire transport compartment for meshnode.

optional: bool = True
enabled_by: str | None = 'compute'
name: str = 'compute_wire'
reads: tuple[str, ...] = ('compute', 'relays', 'transport')
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),)
__init__(node=None, ks=None)[source]
Parameters:
Return type:

None

pinned_vk_digests()[source]

Operator-pinned Groth16 verification-key digests (cfg compute.zk_pinned_vks).

Return type:

list[str]

state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

ComputeWireStateReport

list_sessions()[source]
Return type:

dict[str, ComputeSessionSummary]

list_disputes()[source]
Return type:

list[ComputeDisputeRecord]

open_buyer_session(ask_id, peer_pk, job_payload=None)[source]
Parameters:
Return type:

ComputeSession

open_seller_session(ask_id, peer_pk)[source]
Parameters:
Return type:

ComputeSession

handle_quote(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

handle_accept(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

handle_sealed(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

handle_settled(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

handle_refute(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

handle_stream(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

handle_progress(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

handle_cancel(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

abstract: ClassVar[bool] = False
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'}}
live: tuple[str, ...] = ()

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

optional: bool = True
enabled_by: str | None = 'dvm'

The NIP-90 Data Vending Machine Gateway compartment.

name: str = 'dvm'
uses: tuple[str, ...] = ('compute', 'bridge')
reads: tuple[str, ...] = ('compute', 'dvm')
config_cls

alias of DVMConfig

live: tuple[str, ...] = ('dvm',)
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=()),)
recent_jobs: Ring[tuple[Any, ...]]
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=()))
start()[source]

Everything that needs the rest of the node to exist already.

Return type:

None

stop()[source]

Anything that must be said before the node goes. Must not raise.

Return type:

None

__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]
Parameters:
Return type:

None

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.

Return type:

list[str]

process_request(request_ev, signer_sk=None)[source]

Process a NIP-90 request, returning (response_event_or_None, feedback_event).

Parameters:
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]

abstract: ClassVar[bool] = False
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

delegate_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Any

process_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

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: WireProtocol

The group-topic gossip/1.0 compartment: graft/prune mesh + flood publish.

name: str = 'gossip'
piuris: tuple[str, ...] = ('https://fleetmesh.org/gossip/1.0',)
optional: bool = True
enabled_by: str | None = 'gossip'
requires: tuple[str, ...] = ()
reads: tuple[str, ...] = ('gossip',)
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).

Parameters:

event (Mapping[str, Any])

Return type:

str | None

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.

Parameters:
Return type:

None

topic_id(name)[source]

The coordinate of a topic this node administers: <node_pk>:<name>.

Parameters:

name (str)

Return type:

str

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:

NostrEvent

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.

Parameters:
Return type:

TopicCreationResult

static members_of(event)[source]
Parameters:

event (Mapping[str, Any])

Return type:

set[str]

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.

Parameters:

event (Mapping[str, Any])

Return type:

str

leave(topic)[source]

Drop a roster and prune every mesh peer on it. Returns peers pruned.

Parameters:

topic (str)

Return type:

int

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.

Parameters:
Return type:

OriginateResult

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.

Parameters:
Return type:

str | None

i_am_member(topic)[source]
Parameters:

topic (str)

Return type:

bool

handle_graft(peer, body)[source]
Parameters:
Return type:

tuple[Any, …]

handle_prune(peer, body)[source]
Parameters:
Return type:

tuple[Any, …]

graft(topic, peer)[source]

This node asks peer to add it to their mesh for topic.

Parameters:
Return type:

bool

prune(topic, peer, reason='degree')[source]
Parameters:
Return type:

bool

handle_publish(peer, body)[source]
Parameters:
Return type:

tuple[Any, …]

publish(topic, event_id, envelope)[source]

Originate a publish into this topic’s mesh. Returns peers flooded to.

Parameters:
Return type:

list[str]

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.

Parameters:

topic (str)

Return type:

list[tuple[Any, …]]

handle_ihave(peer, body)[source]
Parameters:
Return type:

tuple[Any, …]

handle_iwant(peer, body)[source]
Parameters:
Return type:

tuple[Any, …]

wire_graft(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

wire_prune(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

wire_publish(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

wire_ihave(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

wire_iwant(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

tick(now)[source]

Periodic work. Runs due EVERY jobs when not overridden.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

expire_seen(now=None)[source]
Parameters:

now (int | None)

Return type:

list[tuple[Any, …]]

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.

Return type:

list[str]

topics_cmd()[source]
Return type:

list[TopicView]

create_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

admit_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

leave_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

publish_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

stop()[source]

Anything that must be said before the node goes. Must not raise.

Return type:

Any

abstract: ClassVar[bool] = False
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'}}
live: tuple[str, ...] = ()

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.

fleetmesh_node.planes.services.nsite.compartment.site_key(ref)[source]
Parameters:

ref (SiteRef)

Return type:

str

fleetmesh_node.planes.services.nsite.compartment.ref_from_key(key)[source]
Parameters:

key (str)

Return type:

SiteRef

class fleetmesh_node.planes.services.nsite.compartment.NsiteStore[source]

Bases: BaseSqliteStore

The 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))
manifest(key)[source]
Parameters:

key (str)

Return type:

tuple[NostrEvent, int] | None

remember_manifest(key, ev, now)[source]
Parameters:
Return type:

None

forget_manifest(key)[source]
Parameters:

key (str)

Return type:

None

domain(domain)[source]
Parameters:

domain (str)

Return type:

DomainBinding | None

set_domain(domain, key, status, why, now)[source]
Parameters:
Return type:

None

drop_domain(domain)[source]
Parameters:

domain (str)

Return type:

bool

domains()[source]
Return type:

list[DomainBinding]

note_bytes(key, sha, size)[source]
Parameters:
Return type:

None

site_bytes(key)[source]
Parameters:

key (str)

Return type:

int

totals()[source]
Return type:

dict[str, int]

class fleetmesh_node.planes.services.nsite.compartment.NsiteGateway[source]

Bases: Compartment

The compartment. Mounted on the relay face’s HTTP fallthrough.

name: str = 'nsite'
optional: bool = True
enabled_by: str | None = 'nsite'
requires: tuple[str, ...] = ()
uses: tuple[str, ...] = ('bridge',)
reads: tuple[str, ...] = ('nsite', 'relays')
live: tuple[str, ...] = ('nsite',)
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=()),)
recent_requests: Ring[tuple[Any, ...]]
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

ks: Any | None
face: Any | None
blossom_url: str | None
cfg: NsiteConfig
relays: tuple[str, ...]
served: int
bytes_served: int
start()[source]

Everything that needs the rest of the node to exist already.

Return type:

None

stop()[source]

Anything that must be said before the node goes. Must not raise.

Return type:

None

state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

NsiteState

snapshot_state()[source]
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.

Return type:

list[str]

domains_cmd()[source]
Return type:

Mapping[str, Any]

sites_cmd()[source]
Return type:

Mapping[str, Any]

verify_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

forget_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

publish_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

PublishResult

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.

Parameters:

args (Mapping[str, Any])

Return type:

PublishResult

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.

Parameters:
Return type:

bool

route(host)[source]

Host header -> site, or None when the host is not a site here.

Parameters:

host (str)

Return type:

SiteRef | None

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.

Parameters:

host (str)

Return type:

bool

serve(ref, path)[source]

(status line, body, content type, extra headers).

Parameters:
Return type:

tuple[str, bytes, str, dict[str, str]]

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

blob(ref, ev, sha)[source]
Parameters:
Return type:

bytes | None

abstract: ClassVar[bool] = False
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

Parameters:
Return type:

DomainBinding

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: object

Canonical intermediate representation of a social microblog post.

text: str
author: str = ''
created_at: int = 0
attachments: list[str]
reply_to: str | None = None
root: str | None = None
tags: list[str]
extra: Mapping[str, Any]
__init__(text, author='', created_at=0, attachments=<factory>, reply_to=None, root=None, tags=<factory>, extra=<factory>)
Parameters:
Return type:

None

fleetmesh_node.planes.services.gateway.translate.unix_to_iso(ts)[source]

Format unix seconds to ISO 8601 UTC string.

Parameters:

ts (int)

Return type:

str

fleetmesh_node.planes.services.gateway.translate.iso_to_unix(iso_str)[source]

Parse ISO 8601 string to unix seconds.

Parameters:

iso_str (str)

Return type:

int

fleetmesh_node.planes.services.gateway.translate.strip_html(text)[source]

Strip HTML tags, scripts, and unescape HTML entities for clean text representation.

Parameters:

text (str)

Return type:

str

fleetmesh_node.planes.services.gateway.translate.text_to_html(text)[source]

Convert plain text to safe HTML paragraphs and line breaks.

Parameters:

text (str)

Return type:

str

fleetmesh_node.planes.services.gateway.translate.nostr_to_unified(event)[source]

Translate a Nostr Kind 1 event to UnifiedPost.

Parameters:

event (Mapping[str, Any])

Return type:

UnifiedPost

fleetmesh_node.planes.services.gateway.translate.unified_to_nostr(post, pubkey=None)[source]

Translate UnifiedPost to a Nostr Kind 1 event structure.

Parameters:
Return type:

Mapping[str, Any]

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:

UnifiedPost

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:

Mapping[str, Any]

fleetmesh_node.planes.services.gateway.translate.activitypub_to_unified(doc)[source]

Translate an ActivityPub Note or Create activity to UnifiedPost.

Parameters:

doc (Mapping[str, Any])

Return type:

UnifiedPost

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)).

Parameters:
Return type:

Mapping[str, Any]

fleetmesh_node.planes.services.gateway.translate.ssb_to_unified(msg)[source]

Translate an SSB message document or post content to UnifiedPost.

Parameters:

msg (Mapping[str, Any])

Return type:

UnifiedPost

fleetmesh_node.planes.services.gateway.translate.unified_to_ssb(post)[source]

Translate UnifiedPost to an SSB post content structure.

Parameters:

post (UnifiedPost)

Return type:

Mapping[str, Any]

fleetmesh_node.planes.services.gateway.translate.p2panda_to_unified(doc)[source]

Translate a p2panda operation dict or payload mapping to UnifiedPost.

Parameters:

doc (Mapping[str, Any])

Return type:

UnifiedPost

fleetmesh_node.planes.services.gateway.translate.unified_to_p2panda(post)[source]

Translate UnifiedPost to a p2panda operation payload structure.

Parameters:

post (UnifiedPost)

Return type:

Mapping[str, Any]

fleetmesh_node.planes.services.gateway.translate.rhio_to_unified(doc)[source]

Translate a Rhio cluster envelope or payload mapping to UnifiedPost.

Parameters:

doc (Mapping[str, Any])

Return type:

UnifiedPost

fleetmesh_node.planes.services.gateway.translate.unified_to_rhio(post, subject='fleetmesh.posts')[source]

Translate UnifiedPost to a Rhio JetStream publication envelope.

Parameters:
Return type:

Mapping[str, Any]

class fleetmesh_node.planes.services.gateway.translate.ProtocolTranslator[source]

Bases: object

Dispatches 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.

Parameters:
Return type:

UnifiedPost

classmethod from_unified(target_protocol, post, **kwargs)[source]

Format UnifiedPost into target protocol payload.

Parameters:
Return type:

Mapping[str, Any]

classmethod translate(source_protocol, target_protocol, payload, **kwargs)[source]

Direct translation between any two supported protocols.

Parameters:
Return type:

Mapping[str, Any]

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: FleetmeshError

Raised on settlement or quota verification failures.

class fleetmesh_node.planes.services.gateway.settle.CrossProtocolPeer[source]

Bases: object

A tracked peer communicating across any supported wire protocol.

protocol: str
peer_id: str
bucket: TokenBucket
balance_sat: int = 0
total_consumed_tokens: int = 0
total_settled_sat: int = 0
penalty_score: float = 0.0
created_at: int
__init__(protocol, peer_id, bucket, balance_sat=0, total_consumed_tokens=0, total_settled_sat=0, penalty_score=0.0, created_at=<factory>)
Parameters:
Return type:

None

class fleetmesh_node.planes.services.gateway.settle.PaymentChallenge[source]

Bases: object

Standardized payment challenge issued when a peer exceeds quota.

protocol: str
peer_id: str
required_sat: int
mint_url: str | None
memo: str
to_http_402()[source]

Format as HTTP 402 Payment Required with Cashu challenge header & body.

Return type:

tuple[int, Mapping[str, str], bytes]

to_nostr_notice()[source]

Format as Nostr NOTICE message content.

Return type:

str

to_muxrpc_error()[source]

Format as SSB MuxRPC error message.

Return type:

str

__init__(protocol, peer_id, required_sat, mint_url, memo)
Parameters:
  • protocol (str)

  • peer_id (str)

  • required_sat (int)

  • mint_url (str | None)

  • memo (str)

Return type:

None

class fleetmesh_node.planes.services.gateway.settle.SettlementReceipt[source]

Bases: object

Proof of completed ecash settlement credit.

protocol: str
peer_id: str
credited_sat: int
new_balance_sat: int
proof_count: int
timestamp: int
__init__(protocol, peer_id, credited_sat, new_balance_sat, proof_count, timestamp=<factory>)
Parameters:
  • protocol (str)

  • peer_id (str)

  • credited_sat (int)

  • new_balance_sat (int)

  • proof_count (int)

  • timestamp (int)

Return type:

None

class fleetmesh_node.planes.services.gateway.settle.CrossProtocolSettlementGateway[source]

Bases: object

Unified 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]
Parameters:
  • default_capacity (float)

  • default_refill_per_sec (float)

  • price_per_topup_sat (int)

  • tokens_per_topup (int)

  • mint_url (str | None)

  • max_penalty_score (float)

mint_url: str | None
get_or_create_peer(protocol, peer_id, capacity=None, refill_rate=None)[source]

Fetch or initialize a tracked peer record.

Parameters:
  • protocol (str)

  • peer_id (str)

  • capacity (float | None)

  • refill_rate (float | None)

Return type:

CrossProtocolPeer

record_penalty(protocol, peer_id, penalty=1.0)[source]

Increase penalty score for bad behavior (e.g. invalid signatures, flooding).

Parameters:
Return type:

float

check_access(protocol, peer_id, cost=1)[source]

Authorize a request or issue a payment challenge.

Returns:

(True, None) if permitted under current token bucket or satoshi balance. (False, PaymentChallenge) if dry and requires payment.

Parameters:
Return type:

Tuple[bool, PaymentChallenge | None]

settle_cashu(protocol, peer_id, token_str)[source]

Parse, validate, and credit Cashu ecash payment (V3 cashuA or V4 cashuB).

Parameters:
  • protocol (str)

  • peer_id (str)

  • token_str (str)

Return type:

SettlementReceipt

stats()[source]

Aggregate cross-protocol accounting statistics.

Return type:

Mapping[str, Any]