Skip to main content

​
Core Concepts

WizPay operates on four primitives: batch, execution, settlement, and orchestration. Every payment flow in the system reduces to these concepts.

​
Batch

A batch is a set of payment instructions grouped into a single processing unit.
  • The frontend composes a list of recipients (address, amount, token).
  • The backend validates the list and splits it into TaskUnit records — one per batch.
  • Each unit is processed independently. A task with 3 batches produces 3 units.
Batching is not optional. Even a single-recipient payment creates one unit. The system always operates in batch mode. Data shape:

​
Execution

Execution is the process of converting a TaskUnit into one or more on-chain transactions.
  • The orchestrator picks up a queued task and routes it to an agent (Payroll, Swap, Bridge, FX, Liquidity).
  • The agent calls the appropriate adapter (Circle API, viem, Solana) to submit the transaction.
  • For async operations (payroll), each submitted transfer is tracked as a TaskTransaction record and polled separately.
Execution is not synchronous by default. Payroll tasks submit transfers and return immediately. Settlement is confirmed asynchronously via the tx_poll queue.

​
Settlement

Settlement is the on-chain confirmation that a transaction has been included in a block and reached a terminal state. Two settlement models exist: Terminal states for a TaskTransaction:
  • completed — On-chain confirmation received, txHash populated.
  • failed — Transfer rejected or timed out, errorReason populated.

​
Orchestration

The orchestration layer is the coordination logic between HTTP ingestion, queue dispatch, agent execution, and state persistence. Key components:
  • OrchestratorService — The single entry point. Exposes handleTask() (called by HTTP) and executeTask() (called by workers). No other component creates or executes tasks.
  • ExecutionRouterService — Checks walletMode (W3S vs PASSKEY) and dispatches to the correct execution engine.
  • AgentRouterService — Dispatches to the remaining type-specific agents. Legacy bridge task execution is rejected.
  • QueueService — Enqueue-only. Never processes jobs.
Architectural invariant: Workers never call agents directly. The call chain is always:
This ensures all execution passes through the orchestrator’s idempotency guard, logging, and error handling.