SmartCheq · Module Specification

Corridor Operations System

The operational control centre for managing bilateral CBDC liquidity corridors between African Union member states. Covers reserve pool management, lock lifecycle, FX rates, rebalancing, governance escalation, and emergency actions.

Version 1.0

Scope 54 AU Member Corridors

Updated April 2026

Status Production Reference

§1

System Overview

An operator at a central bank uses Corridor Ops to allocate reserve funds into locked pools that back cross-border digital cash issuance, monitor real-time liquidity positions, enforce risk limits, reconcile ledger state, and escalate anomalies to governance.

Left Pane — Identity

Select active corridor
Set operating mode
View FX snapshot
View liquidity summary
View corridor metadata

Middle Pane — Operations

Lock / release reserve funds
Rebalance pool allocation
View active locks table
Registry & audit log

Right Pane — Controls

Corridor limits & safety
FX configuration
Liquidity position
Registry sync & reconciliation
Governance escalation
Emergency actions

Key Concepts

Concept	Definition	Example
Corridor	Bilateral arrangement between two central banks enabling CBDC transfers	GHA → MLI denominated in XOF
Reserve Pool	Named sub-account within a corridor holding pledged central bank funds. Three pools per corridor.	BCEAO-XOF-RESERVE-01
Lock	Immutable ledger entry reserving a specific amount from a reserve pool for a defined duration	50,000 XOF locked for 24h
Linked Issuance	A CVIB batch issued against the backing of one or more active locks	CVIB batch backed by LK-E0E7A9E1
Net Position	Domestic available liquidity minus linked outstanding issuance	50,000 − 0 = 50,000 XOF

§2

Data Model

Corridor

Field	Type	Req	Description
id	uuid	✓	Primary key
code	string	✓	Human identifier e.g. `GHA-MLI`
source_country	iso3	✓	ISO 3166-1 alpha-3 of sending country
target_country	iso3	✓	ISO 3166-1 alpha-3 of receiving country
asset_code	string	✓	ISO 4217 currency denomination
status	enum	✓	`active` \| `paused` \| `frozen` \| `inactive`
mode	enum		`pilot` \| `supervised` \| `production`
daily_cap	decimal		Maximum total issuance per calendar day
velocity_limit	decimal		Maximum rolling 1-hour issuance volume
per_transaction_cap	decimal		Hard ceiling per individual transfer

LiquidityLock

Field	Type	Req	Description
id	uuid	✓	Primary key
lock_id	string	✓	Human reference e.g. `LK-E0E7A9E1-20260407142828`
corridor_id	uuid FK	✓	References Corridor
amount	decimal	✓	Value in corridor asset currency
reserve_pool	string		Pool tag. NULL = pool-01 by convention
status	enum	✓	`active` \| `released` \| `expired`
duration	string		e.g. `24h`, `48h`, `custom`
expires_at	timestamp		When lock auto-expires (UTC)
release_reason	string		Operator note on manual release

ReservePoolEvent (virtual accounting)

Field	Type	Description
event_id	string	Idempotency key: `RBL-{hex}-{timestamp}`
corridor_id	uuid FK	References Corridor
source_pool	string	Pool funds moved from
dest_pool	string	Pool funds moved to
amount	decimal	Virtual amount transferred
currency	string	ISO 4217 currency code

§3

Left Pane — Corridor Selector

Corridor Dropdown

Editable QComboBox with QCompleter (MatchContains, CaseInsensitive). Populated from GET /api/v2/corridors. Display format: {flag} {SRC} → {flag} {DST}. Fires on activated signal only — not on each keystroke.

On Change — Full Reload Cascade

Load corridor identity

GET /corridors/:id → ID, Code, Asset Code, Status, Agreement ID, Source, Target

Load FX rate

GET /corridors/:id/fx_rate → sets current rate and FX snapshot labels

Load liquidity position

GET /corridors/:id/liquidity_position → Domestic, Linked, Net labels

Load reserve pools

GET /corridors/:id/reserve_pools → populates pool selector dropdown

Load active locks

GET /api/v2/liquidity_locks?corridor_id=:id → populates active locks table

Load limits + apply status style

GET /corridors/:id/limits → Risk Limits panel. applyCorridorStatusStyle() updates Danger Zone button.

Mode Selector

Mode	Daily Cap	Per-Tx Cap	Velocity	Governance Required
Pilot	500,000 XOF	10,000 XOF	100,000/hr	All lock operations
Supervised	2,500,000 XOF	500,000 XOF	1,000,000/hr	Locks > 1M, FX changes
Production	Per corridor config	Per corridor config	Per corridor config	FX changes, limit changes

§4

Middle Pane — Operations

Intent Action Bar

Intent	Visible	Button
Lock Liquidity	Reserve Pool, Amount, 10M/50M/100M/MAX, Duration	Execute (blue)
Release Liquidity	Lock ID selector, read-only Amount, Release Reason	Release Selected
Update FX Rate	New Rate input, live % comparison, Effective Time	Propose Change (purple)
Adjust Risk Limits	Daily Cap, Velocity, Per-Tx cap inputs	Propose Change (purple)

Lock Liquidity — Validation Rules

amount > 0

amount ≤ pool_available

amount ≤ per_transaction_cap

daily_total + amount ≤ daily_cap

hourly_total + amount ≤ velocity_limit

corridor.status == 'active'

Lock States

ACTIVE RELEASED EXPIRED

State	Meaning	Transition
ACTIVE	Funds committed. Backs linked issuances.	→ RELEASED (manual) or → EXPIRED (timer)
RELEASED	Funds returned to reserve pool. Audit record written.	Terminal
EXPIRED	Duration elapsed. System auto-marks. Funds need reconciliation.	Terminal

Active Locks Table

Column	Source	Notes
✓ Checkbox	Qt::CheckStateRole col 0	Enables batch release. Full row clickable.
Corridor	lock.corridor.code	e.g. GHA-MLI
Lock ID	lock.lock_id	Truncated for display. DB UUID in UserRole+2.
Amount	lock.amount	Formatted with currency. UserRole+3 for combo auto-fill.
Expiry	lock.expires_at	YYYY-MM-DD HH:MM truncated
Status	lock.status	Coloured capsule pill: green=ACTIVE, blue=RELEASED, red=EXPIRED

Rebalance Reserve Pools

Dialog

Source Pool, Destination Pool (cannot equal), Amount. Preview panel shows projected balances before confirm.

POST /api/v2/liquidity_locks/rebalance

corridor_id, source_pool, dest_pool, amount, rebalanced_at

Physical retag attempt

Server selects locks on source_pool smallest-first. Resets reserve_pool column to dest_pool until amount exhausted.

Virtual event fallback

If no individual lock ≤ remaining, writes ReservePoolEvent. reserve_pools endpoint applies as virtual adjustment.

§5

Right Pane — Controls & Governance

Corridor Limits & Safety

Limit	Enforcement	Default
Per-Transaction Cap	Server + client guardrail	500,000 XOF
Daily Corridor Cap	Server + client warning + utilisation bar	2,500,000 XOF
Monthly Cap	Server monthly sum check	25,000,000 XOF
Velocity Limit	Server rolling 1h window	4,000,000 XOF/hr

ℹ

Client-side validation provides real-time UX feedback only. The Rails server re-validates on every lock creation and returns HTTP 422 with a structured error if any limit is exceeded.

Liquidity Position (read-only)

Field	Calculation
Domestic Available	SUM of all active lock amounts for this corridor
Linked Outstanding	SUM of denominations of active + issued CVIB notes backed by this corridor
Net Position	Domestic Available − Linked Outstanding
Position Status	Surplus (net > 0) \| Balanced (net = 0) \| Deficit (net < 0) \| At Risk (net < −10% daily cap)

Emergency Actions

Button	Action	Auth
Manual Recon	Full ledger reconciliation with operator reason. No funds moved.	Standard token
System Override	Forced sync bypassing validation. Reason + 4-digit PIN. Dialog stays open until server confirms.	PIN + ENV['OVERRIDE_PIN'] in production
Request Support	Pre-filled support ticket with corridor snapshot. Generates SUP-{code}-{timestamp}.	Standard token
Deactivate / Reactivate	Dynamic button. Red when active. Green when paused/frozen. Two-step confirm + reason for deactivation.	Standard token + mandatory reason

⛔

The Deactivate / Reactivate button must always live in the Emergency Actions group box (grpEmergencyActions), behind a visual "⚠ Danger Zone" divider. It must never appear in the Action bar or alongside routine operations.

§6

Button-Level Behaviour

Execute (Lock Liquidity)Middle Pane

Inputs

Amount, Reserve Pool, Duration

API

POST /api/v2/liquidity_locks {corridor_id, amount, reserve_pool, duration, expires_at}

Success

New ACTIVE row in locks table. Pool balance decremented. Liquidity position updated.

Failure

HTTP 422 → critical dialog with server error message.

Release SelectedMiddle Pane

Inputs

Checked rows in locks table OR selected Lock ID from Release Liquidity panel

API

POST /api/v2/liquidity_locks/:id/release {reason?} — one call per lock

Success

Rows show RELEASED. Pool balance restored. Lock ID combo refreshed after 600ms.

Failure

Warning dialog listing all failed lock IDs.

Rebalance PoolsMiddle Pane

Inputs

Source Pool, Destination Pool (≠ source), Amount

API

POST /api/v2/liquidity_locks/rebalance

Success

Physical lock retag if lock ≤ amount. Virtual ReservePoolEvent if no lock fits.

Propose Change — FX RateMiddle Pane

Inputs

New FX Rate (high-precision decimal), Effective Time (Immediate | Scheduled)

API

POST /api/v2/corridors/:id/fx_rate {rate, effective_time}

Success

Returns pending_four_eyes. Rate unchanged until approved by second operator.

Escalate to GovernanceRight Pane

Inputs

Reason (mandatory dropdown), Proposal ID (auto-generated)

API

POST /api/v2/escalations {corridor_id, reason, proposal_id}

Rule

Proposing operator cannot self-approve. Four-Eyes enforced server-side.

Deactivate / Reactivate CorridorRight Pane · Danger Zone

Deactivate

Two-step dialog. Reason combo (6 options, mandatory). POST /corridors/:id/deactivate {reason} → status=paused

Reactivate

Routes to onCreateCorridor. Detects already_exists (HTTP 200) and offers reactivation.

§7

System Rules & Edge Cases

Liquidity = 0

⚠

Execute button disabled with tooltip "Waiting for pool balance". Operator must rebalance from another pool or create a new lock. Issuance blocked. Corridor remains functional for FX and governance actions.

Cap Exceeded

Client: validateAmountGuardrail() shows red warning. Execute disabled.

Server: HTTP 422 {code: cap_exceeded}. QMessageBox::critical shown.

Partial cap: MAX button fills to remaining headroom automatically.

Corridor Status Capability Matrix

Status	Lock Create	Lock Release	Issuance	FX Update
ACTIVE	✓	✓	✓	Via governance
PAUSED	✗	✓	✗	Via governance
FROZEN	✗	✗	✗	Via governance only
INACTIVE	✗	✗	✗	Must reactivate first

Rebalance with No Fitting Lock

If rebalance amount < every individual lock: physical retag = 0. ReservePoolEvent written for full amount.

reserve_pools endpoint: dest_pool += event.amount, source_pool -= event.amount (floored at 0).

§8

End-to-End Flow

Complete walkthrough: GHA → MLI corridor from selection through limit breach, governance escalation, and reconciliation.

Select corridor

Type "GHA" in corridor selector. GHA → MLI activates. Full reload fires. FX=50.5425, Pool BCEAO-XOF-RESERVE-01 Available=49,000 XOF (Low).

Lock liquidity

Intent=Lock Liquidity. Click 10M → guardrail fires "Exceeds daily cap". Reduce to 2,000,000. Duration=24h. Execute. Lock LK-BF0B… ACTIVE created.

Issuance linked

CVIB batch 1,800,000 XOF issued from Issuance tab, linked to new lock. Net Position = 200,000 XOF.

Limit reached

Second lock attempt for 1,000,000 XOF. "Daily cap reached: 0 remaining today." Execute disabled.

Escalate to governance

Reason="Temporary cap increase". Proposal GOV-2026040922 created. Supervisor approves in Governance tab. daily_cap raised to 5,000,000.

Reconcile

Reconciliation Report POST /reconcile. Returns "2 active locks, 1 linked issuance, no discrepancies". Sync status: In Sync ✓.

✓

End state: 2 active locks on BCEAO-XOF-RESERVE-01, 1 linked CVIB batch, net position positive, all limits within bounds, full audit trail recorded.

Corridor Operations System

System Overview

Left Pane — Identity

Middle Pane — Operations

Right Pane — Controls

Key Concepts

Data Model

Corridor

LiquidityLock

ReservePoolEvent (virtual accounting)

Left Pane — Corridor Selector

Corridor Dropdown

On Change — Full Reload Cascade

Load corridor identity

Load FX rate

Load liquidity position

Load reserve pools

Load active locks

Load limits + apply status style

Mode Selector

Middle Pane — Operations

Intent Action Bar

Lock Liquidity — Validation Rules

Lock States

Active Locks Table

Rebalance Reserve Pools

Dialog

POST /api/v2/liquidity_locks/rebalance

Physical retag attempt

Virtual event fallback

Right Pane — Controls & Governance

Corridor Limits & Safety

Liquidity Position (read-only)

Emergency Actions

Button-Level Behaviour

System Rules & Edge Cases

Liquidity = 0

Cap Exceeded

Corridor Status Capability Matrix

Rebalance with No Fitting Lock

End-to-End Flow

Select corridor

Lock liquidity

Issuance linked

Limit reached

Escalate to governance

Reconcile

My Digital Cash

Pay or Send Money

Remove Digital Cash?

Remove Saved Contact?

Confirm Giving Cash

📱 Your Saved Digital Cash

📷 Scan Cash Code

Already Transferred

Get Your Cash Code

All Set!

Get Your Cash Code

📱 Your Digital Cash Code QR

My Payments

💰 Money I Received

💸 Money I Sent

No payments yet

💵 Save Digital Cash

Your Nigerian Naira Notes

Trade Claim Submission

Claiming Institution

Trade Details

Compliance & Limits

Beneficiary Information

Supporting Documents

Declarations

Trade Claim Submitted!

Draft Saved!

Issuance Desk

Administrator Console

Latest Trade Claim Activity

Corridor Volume

Active Issuance Queue

Corridor Quota Limits