Skip to main content

The flows a run observes

Two transfer topologies live in core/lukaot/flow/: real HTTP between real processes, every participant declaring its own vocabulary, and every arrow in the diagrams below drawn from what the service observed of one execution rather than from a document.

This page annotates the diagrams leg by leg, so they can be read against the code that produced them. The declaration reference is the pattern guide, what the library is at all is the concept, and why the identity is declared rather than derived is the rationale.

These flows are a demonstration​

They are demonstration fixtures for the vocabulary. They are not an implementation of Mojaloop, not a payment system, and not a model of how settlement should be built. Their purpose is to generate realistic multi-service traffic — real HTTP between real processes, real failure paths, records read back out of each participant's own cache — so that the behaviour can be watched, asserted and drawn.

They are loosely based on two published Mojaloop features:

FlowBased on
single — cross-currency, one schemeForeign Exchange — currency conversion: a Payer DFSP obtains a conversion rate from an FXP and then executes the transfer in the target currency
inter — cross-border, two schemesInterscheme: two schemes joined by a proxy participant that routes for adjacent DFSPs/FXPs in the other scheme

What is simplified or omitted, deliberately​

In the Mojaloop flowIn these fixtures
An Oracle resolves the party identifier, and GET /parties is answered with a PUT /parties/{ID}Three generic POST routes — /parties, /quotes, /transfers — with no directory; the payee answers directly
Two POST /quotes rounds (liquidity cover from the FXP, then the transfer terms from the payee), plus the Payer's own confirmation stepOne quote round: the provider's rate is threaded through the payee and returned to the payer once
An FX marketplace: several FXPs bid for the conversion and the DFSP selects oneOne provider for the corridor, by configuration
Real ILP cryptographic conditions and fulfilment preimagesPlaceholder strings (sha256:condition, sha256:preimage); nothing is cryptographically verified
Two-phase reserve/commit across ledgers, atomic settlement, clearing accountsA single withhold and its release on failure — which is the observability the fixture needs to demonstrate
Abort flowsA refusal status (409, 422, 503) and an error record
Inter-scheme discovery by broadcast, cached identifiers, stale-cache self-healing, proxy registration through an admin API, and GET /transfers resolved locallyAbsent: the corridor is configured rather than discovered, and the proxy's routing decision is a single recorded decision
Non-repudiation: the proxy routes but takes no part in the agreement of termsPreserved — the proxy forwards /quotes unchanged and adds no terms of its own

The rates, amounts and identifiers are invented. No participant holds state that survives a run, and nothing here is a statement about how a real scheme should behave.

How to read the annotations​

Every arrow is a call a record declared, and every label is the leg id the source declares — transfer.deliver in a diagram is a literal in flow/hub.ts, and the table under each diagram names the file and line that declares it. That is what makes a picture of a run lead its reader back to the code without guessing.

Each diagram uses mermaid's autonumber, which numbers arrows only — the Note over … lines carry no number. The table is the diagram in full, and it says what a picture cannot:

ColumnMeaning
callthe leg id, as declared in the code
caller → receiverwho declared the call, and who they declared it to — the receiver the caller named, not one inferred from who answered
phasethe step the call was observed in (discovery, quote, transfer)
positionthe counter path the caller assigned: 2.2.1 is the first call made while answering 2.2
declaredhow many declarations were observed — one per execution, so a chatty call site is still one call
answeredof those, how many had their receiver observed too. 0 is the interesting case: the call was made and nothing answered
declared inthe file and line that declares the id

An arrow drawn with a cross (--x) is a call the caller declared that nothing answered — a receiver that is missing, failing, or wired to the wrong address. An arrow drawn dashed (-->>) is the receiver's own record of the leg: the answer on its way back, under the same id, drawn where it arrived — after everything that call itself called has been answered. A call that never leaves its own participant is the one call drawn without a pair, because the answer to it would repeat the same caller, the same label and the same step.

A branch is an alt/else block whose arms are named for the candidates the code declared. Here the arm labels come from a declared decision (proxyVocabulary.decision.routeSelection), so the block names the choice the code makes rather than a phrase somebody typed.

Regenerate both blocks with:

cd core/lukaot
LUKAOT_UPDATE_DIAGRAMS=1 node test/flow/observedFlows.test.ts

Cross-currency (single scheme)​

Four participants: payer, hub, fxp (the FX provider), payee. Wired by startFlow('single') in flow/flows.ts; each is created with its own vocabulary — payerVocabulary, hubVocabulary, payeeVocabulary, fxpVocabulary — so a record's identity names the declaration the participant made.

Relative to the published exchange, this fixture:

  • collapses the two quote rounds into one — the payer sends one POST /quotes that carries both the FX request and the main quote, and the hub threads the provider's rate through the payee and merges both answers into the single reply;
  • does not model the FX provider's transfer legs — the provider is consulted in the quote phase only, and the hub settles directly with the payee. A second settlement participant would add no new observability, so its absence is a decision rather than an oversight;
  • keeps the liquidity reservations out of the wire — the hub's withhold({liquidity}) is retained in the record and never transmitted, which is why no leg carries it;
  • records its branches — the payer's quoteAcceptable and the provider's rateWithinLimit are decided inside the participant that owns them, so the rationale lands on that participant's next record.

Participants: payer, hub, payee, fxp. 7 calls observed across 1 execution(s).

callcaller → receiverphasepositiondeclaredanswereddeclared in
discovery.partiespayer → hubdiscovery111flow/payer.ts:116
discovery.payeehub → payeediscovery1.111flow/hub.ts:114
quote.ratespayer → hubquote211flow/payer.ts:127
quote.fxhub → fxpquote2.111flow/hub.ts:115
quote.payeehub → payeequote2.211flow/hub.ts:116
transfer.submitpayer → hubtransfer311flow/payer.ts:166
transfer.deliverhub → payeetransfer3.111flow/hub.ts:117

Inter-scheme cross-currency​

Six participants: payer, hubA, proxy, hubB, payee, fxp. Wired by startFlow('inter'). One provider sits on the corridor and the receiving scheme's hub asks it; the originating hub quotes nothing locally, so the corridor's price is the only price the run records — the shape the published flow has.

Relative to the published exchange, this fixture:

  • routes the corridor through a proxy participant — hub A holds no directory of its own, so discovery.proxy is a real hop to a real participant rather than a URL change;
  • carries each phase end to end — one leg per hop per phase, which is what makes the counter paths read as a depth-first walk of the corridor (1.1.1.1, 2.1.1.2, 3.1.1.1);
  • records the routing decision where it is made — the proxy's routeSelection decision has two arms, hubB (reachable, so the call is forwarded) and hold (no corridor configured, so the call is held with 503 rather than lost). The happy run takes hubB, which is why the block shows the other arm as not weighed.

Participants: payer, hubA, proxy, hubB, payee, fxp. 13 calls observed across 1 execution(s).

callcaller → receiverphasepositiondeclaredanswereddeclared in
discovery.partiespayer → hubAdiscovery111flow/payer.ts:116
discovery.proxyhubA → proxydiscovery1.111flow/hubA.ts:93
proxy.discovery.corridorproxy → hubBdiscovery1.1.111flow/proxy.ts:82
discovery.payeehubB → payeediscovery1.1.1.111flow/hub.ts:114
quote.ratespayer → hubAquote211flow/payer.ts:127
quote.proxyhubA → proxyquote2.111flow/hubA.ts:125
proxy.quote.corridorproxy → hubBquote2.1.111flow/proxy.ts:83
quote.fxhubB → fxpquote2.1.1.111flow/hub.ts:115
quote.payeehubB → payeequote2.1.1.211flow/hub.ts:116
transfer.submitpayer → hubAtransfer311flow/payer.ts:166
transfer.proxyhubA → proxytransfer3.111flow/hubA.ts:157
proxy.transfer.corridorproxy → hubBtransfer3.1.111flow/proxy.ts:84
transfer.deliverhubB → payeetransfer3.1.1.111flow/hub.ts:117

What the diagrams do not draw​

The generated blocks draw what the service observed; three things the fixtures carry are absent from them, and each is deliberate:

AdditionWhereWhy it is there
The proxy's hold armproxy.ts (ROUTES, reachable)a proxy whose receiving link is not configured has no route and must hold (503) rather than forward into an address it was never given. Reachability is derived from the deployment, so the arm is real and not a guard against something that never happens
Two identity headers on every hopparticipant.ts (hop)x-semantic-trace (causal correlation) and the execution id it carries — the diagram draws the protocol, not the observability envelope
The optional service sinkparticipant.ts, flows.tswith --service, each participant's records are shipped beside the local cache; without it the run is complete and offline

What the flow code demonstrates​

Every item below happens where a real service would do it — these are calls a service makes at that point, not demonstration code — and each is pinned by a test rather than by this page.

FeatureWhere the fixture does itPinned by
One real process per participant, over real HTTPparticipant.ts (createParticipant, listen, hop)the artifact test runs both topologies end to end
A vocabulary per participant, composed at creationflows.ts (VOCABULARY), participant.ts (compose(runtime, participant))src/decide.test.ts and the fixture's own records
The identity on a record is the declared namesignal?.<id>?.(…) in every participantthe declared in column resolves each label to its source
A branch records its arms and the one takendecide(vocabulary.decision.…) in the payer, the provider and the proxythe alt blocks in the diagrams above
A decision switched off still decides, and records nothingdecide returns the arm's result before it stages any rationalesrc/decide.test.ts — "a decision switched off still decides…"
Calls are declared by both endshop carries the identity headers; each participant adopts the inbound legthe paired arrows, answered = declared in every row
Withheld detail belongs to the execution that withheld itparticipant.logger.withhold(…) inside the switcheach participant's own store, read back after the run
A refusal stops the chain and travels as a statusevery route sets reply.status(result.status), never returns the envelopethe payee's 422 and the proxy's 503 in a fault run
Faults are deployment properties, not test branchesstartFlow(kind, {faults}) → install* optionsthe runner's flag parsing; fixture-level fault assertions are pending
Offline: nothing needs to be runningno serviceUrl → readable output, references and the local cache alonethe runner's default mode
A service sink is a second destinationserviceUrl → createServiceWriter, beside the local cachethe artifact test, which reads its diagrams from that sink
The last record is flushed before the cache closesclose() flushes loggers, then sinks, then the cacheevery read-back in the artifact test

Faults​

A fault is a deployment property handed to startFlow, never a branch a test steers a participant into. The runner accepts them as flags:

FaultConfigurationWhat it makes reachable
F1 payee refusesfaults.blockTransfersthe far end is the origin of a failure; withheld detail is released on it
F2 payer retriesfaults.retries = 40one execution per attempt, and one identity for unchanged code
F4 payee stallsfaults.stallTransfersthe last step reached is recorded, so a stalled flow says where it stopped
F5 provider declinesfaults.declineRatethe declined arm of a decision is what the record shows, not just the failure

A fifth fault, F3 — "the hub's liquidity message is reworded, as a deploy would" — no longer exists: a message belongs to a declaration now, so the only place a reword can happen is the vocabulary file, and nothing about the record's identity moves with it.

Some of these were exercised end to end by the previous package's fixture suites, which were not ported with the artifact. The flags are wired and the runner accepts them; the assertions that read each participant's records back per fault are still to come.

Running and testing the flows​

node flow/run.ts --flow single|inter runs a flow by hand; see the pattern guide for the runner's flags.

Links to the package's sources are given as paths rather than hyperlinks: the docs site is built from docs/blong/docs/ alone, so a link escaping this tree would be a broken link in the published site.