Payment Router & Ledger System Architecture

System Architecture & Event-Driven Pipeline

This section illustrates the decoupled architecture between upstream instruction creation, the dynamic Payment Orchestration Router, the double-entry Ledger Engine, and execution providers. By decoupling routing policy from execution rails, the engine evaluates real-time telemetry (latency, gas fees, liquidity) to select the optimal path before committing financial state changes.

Stage 1 👤

Client / Upstream

Issues payment instruction with target constraints.

Create Instruction ➔

Stage 2 🧠

Router Engine

Evaluates bindings, constraints, & scores candidate rails.

Resolve Route ➔

Stage 3 ⚖️

Ledger Engine

Locks balances & executes double-entry journal templates.

Encumber & Post ➔

Stage 4 🏛️

Circle API Provider

Executes on-chain or fiat mint/burn transactions.

Dispatch Transfer ➔

Stage 5 ⛓️

External Blockchain

Finalizes transfer on Base / Polygon / Ethereum.

Terminal Finality ✔

🔍 Component Inspector: Select a Stage Above

Overview Mode

PRIMARY RESPONSIBILITY

Click any component card above to view its detailed API contracts, event triggers, and state transitions during a transaction lifecycle.

INTERFACING & STATE HASHS

Exposes REST/gRPC interfaces, publishes async Kafka events, and manipulates specific balance buckets in the database.

OUTPUT TRIGGER EVENT

route_resolved | pending_provider | confirmed

Deterministic Scoring & Route Selection Engine

The router evaluates eligible execution capabilities by applying normalized scoring math clamped to $[0, 1]$. Adjust the policy weight sliders below to simulate how real-time strategy shifts (e.g., prioritizing low cost vs. high speed) re-rank executable rails in real-time.

Policy Weight Tuning (RP_GLOBAL_USDC_V3)

Cost Weight ($w_c$) 0.35

Lower cost increases normalized candidate score ($N_{cost}$).

Latency Weight ($w_l$) 0.25

Lower p95 latency increases normalized candidate score ($N_{lat}$).

Liquidity Weight ($w_q$) 0.25

Higher available balance increases normalized candidate score ($N_{liq}$).

Reliability Weight ($w_r$) 0.15

Lower 1h failure rate increases reliability score ($R$).

💡 Formula: $Final(c) = Base(c) \times P_{health}(c) \times P_{lat}(c)$ where Base is the weighted normalized sum.

Candidate Score Ranking Chart Winner: RC_CIRCLE_ONCHAIN_BASE

Route Code	Est. Cost	Latency	Health	Final Score

Ledger Accounting Paths & Double-Entry Templates

The Payment Router's selected capability dynamically maps to specific General Ledger (GL) and Subledger account templates. Select a real-world scenario below to inspect how double-entry journal entries debit and credit liability, transit, receivable, and asset buckets.

Route: RC_INTERNAL_LEDGER

Internal Customer-to-Customer Settlement

Rail Type: internal_ledger

Double-Entry Journal Posting Sequence

Step / Event	General Ledger Account Name	Account Type	Debit ($)	Credit ($)

Architectural Takeaway: By selecting an internal rail, the Router instructs the Ledger to bypass the Settlement Transit Liability and Circle Custody Asset accounts entirely, achieving instant, zero-cost settlement without external blockchain exposure.

Subledger Balance Bucket Lifecycle

Customer funds move through four distinct subledger balance buckets during an external USDC payment ($Available \rightarrow Reserved \rightarrow Transit \rightarrow Custody$). Use the interactive stepper below to visualize how total customer ownership is preserved during encumbrance.

Transaction Stage Stepper Total Customer Balance: $10,000.00 USDC

Available Balance $10,000.00

Deployable liquidity available for new transactions.

Reserved Balance $0.00

Encumbered funds locked during route resolution.

Settlement Transit $0.00

In-flight on blockchain / pending provider webhook.

Platform Custody $10,000.00

Physical USDC held in platform Circle wallet.

📌

Stage 1: Instruction Created (`created`) The instruction is received by the Payment Instruction API. No route is assigned yet, so balances remain 100% available in the source Account of Digital Asset (ADA).

Shadow Mode & Replay Drift Inspector

Shadow mode runs proposed routing policy versions in parallel against historical production telemetry (`vw_router_decision_replay`). Search and inspect decision records below to detect winner matches and score drift prior to policy promotion.

🔍

Show Winner Mismatches Only

Instruction ID	Persisted Winner	Replay Winner (Shadow)	Score Delta	Winner Match?	Action