Skip to main content

Module ilp_dispatcher

qualia_core_db::services

Module ilp_dispatcher 

Source
Expand description

ILP Micropayment Dispatcher

Executes a TaxDispatchPlan as a sequence of ILP STREAM micropayments. Each instruction in the plan is sent as an independent payment to its designated ILP Payment Pointer, with optional Nym mixnet routing.

§Transport stack (in order of preference)

  1. SPSP / ILP-over-HTTP — RFC-compliant, resolves $pointer → HTTPS endpoint, opens a STREAM connection, sends the exact µ-cent amount, collects a receipt.
  2. Nym mixnet proxy — when instruction.use_nym == true, traffic is wrapped in a Sphinx packet and routed through the Nym gateway before hitting the ILP endpoint. This hides the sender’s IP from the recipient’s ILP connector.
  3. Offline queue — if neither transport is available (no network, Nym offline), the instruction is queued to pending_payments.ndjson in the Qualia data dir and retried on the next payment cycle.

§Payment pointer resolution

$ilp.qualia.coop/account → GET https://ilp.qualia.coop/.well-known/pay/account → SPSP JSON { “destination_account”: “…”, “shared_secret”: “…” } → Open ILP STREAM connection → send amount → get PaymentReceipt

§Stablecoin fallback

If the address starts with did:wallet: or a bare hex/bech32 address, the dispatcher emits an on-chain stablecoin transfer instruction instead of ILP STREAM. Supported stablecoins: USDC (ERC-20), XRPL IOU.

§Audit trail

Every dispatched or queued payment is written as an N-Quad to the .q42 graph:

<<:payment_<id> :amount_micro_cents <N>>> :dispatched_at "<ISO8601>" .
<<:payment_<id> :recipient_ilp    "$addr">> :tax_cycle "<cycle_id>" .

Structs§

DispatchResult
The full result of executing a TaxDispatchPlan.
HttpIlpTransport
Resolves an ILP Payment Pointer and sends via HTTP STREAM. In full production, this uses the interledger crate or a sidecar connector. For now it performs the SPSP resolution GET and logs the intent — full STREAM requires a running ILP connector on the local daemon (roadmap item).
IlpDispatcher
MockTransport
PaymentReceipt

Enums§

PaymentStatus

Traits§

IlpTransport
Low-level transport interface. Implemented for HTTP, Nym, and a mock stub.

Functions§

generate_energy_of_logic_invoice
Converts the accumulated ATOMIC_FLOPS_COUNT into an ILP MicropaymentInstruction. Standard ratio: 10,000 FLOPs = 1 Satoshi
resolve_payment_pointer
Resolves $provider.example/account → https://provider.example/.well-known/pay/account