Developer guide

Events, ledger and reconciliation

3 min read

How a change of state becomes an event the Partner can trust, a ledger entry that cannot be rewritten, and a fact verified against the chain.

PostgreSQL as the durable source

PostgreSQL stores identity, wallets, configuration, idempotency, operations, steps, legs, ledger, outbox, inbox, events, audit and projections.

jsonb is used for payloads whose shape varies by network. The financial invariants and the critical relationships stay in explicit SQL structures, because a constraint the database enforces is worth more than a rule the application remembers to check.

Transactional Outbox and Inbox

The business change and the pending event are written in the same transaction. A publisher reads the Outbox and publishes to the bus. Each consumer records in its Inbox the message identifiers it has already processed.

flowchart LR
    API[B2B API] -->|1| TX[(PostgreSQL transaction)]
    TX -->|2| OP[Operation]
    TX -->|2| OUT[Outbox]
    OUT -->|3| BUS[Event bus]
    BUS -->|4| W[Workers]
    BUS -->|4| O[Observers]
    BUS -->|4| R[Reconciler]
    BUS -->|4| WH[Webhook Dispatcher]
    W -->|5| IN[Inbox / dedup]
    O -->|5| IN
    R -->|5| IN
    WH -->|5| IN

What each step does

  1. API → PostgreSQL transaction. Everything the request changes happens inside one transaction.
  2. Transaction → Operation and Outbox. The state change and its event are committed together. There is no window in which the operation changed but the event was lost, and none in which an event exists for a change that was rolled back.
  3. Outbox → event bus. A publisher reads committed rows and publishes them. If it crashes, the rows are still there.
  4. Bus → workers, observers, reconciler, webhook dispatcher. Each consumer receives what concerns it.
  5. Consumers → Inbox / dedup. Each one records the message identifiers it has processed. Delivery may be at-least-once, so the same message can arrive twice; the Inbox is what makes the financial effect happen once.

Operational ledger

The ledger is append-only and records the internal financial impact of each operation. It does not hold or custody the crypto assets themselves: those stay in the blockchain accounts.

Reference entries: reservation; debit sent; credit received; service fee; provider fee; actual gas; refund; release of a reservation; compensating adjustment.

A correction never overwrites the original movement. It adds a linked compensating entry, so the history shows both what was recorded and what corrected it.

Reconciliation

Reconciliation crosses three related sources:

  • Blockchain or provider — the external facts that were observed.
  • Operation — the intent and the workflow.
  • Ledger — the internal financial impact.

The reconciler checks the amount, the recipient, the asset, the chain, the transaction hash, the receipt, the logs or inputs and outputs, the fees, the confirmations or finality, and the provider state.

Where they disagree, the difference is resolved with an explicit adjustment or sent to manual_review. It is never closed by trusting one source over the others.