SmartCheq · Module Specification

Validation Desk

Inbound CBDC verification pipeline. QR and barcode parsing, Ed25519 signature verification, registry lookup, duplicate detection, and compliance actions including approve, reject, freeze, and flag.

Version Draft
Updated April 2026
Status In Progress
§1

System Overview

⚠
Full specification in progress. Content below documents current implementation from routes.rb and validation API endpoints.

The Validation Desk is where received CBDC notes are authenticated before they can be accepted, redeemed, or transferred. A commercial bank or settlement agent submits a scanned QR code or barcode payload to the ingest endpoint. The system parses the note, verifies the issuing central bank's Ed25519 signature, checks the registry for authenticity, and screens for duplicates.

The operator then takes a compliance action: approve, reject, or freeze. Each action is immutably logged. The validation API is part of the /api/v2/validation namespace.

Ingest Queue

  • Submitted note payloads
  • QR / barcode source
  • Submission timestamp
  • Submitting institution

Verification Results

  • Signature check result
  • Registry match
  • Duplicate status
  • Note metadata

Compliance Actions

  • Approve
  • Reject
  • Freeze
  • Flag for review
  • Audit log export
§2

Data Model

Validation Ingest Record

FieldTypeDescription
serialstringCBDC note serial number (unique identifier)
raw_payloadstringRaw QR or barcode string submitted via POST /validation/ingest
parsed_datajsonbDecoded note metadata: denomination, issuer, corridor, issued_at
signature_validbooleanResult of Ed25519 signature verification
registry_matchbooleanWhether serial exists in the issued notes registry
duplicate_detectedbooleanWhether serial has been presented before
statusenumpending | approved | rejected | frozen | flagged
action_bystringOperator who took the compliance action
action_attimestampWhen compliance action was taken
§3

Validation Pipeline

Ingest

POST /api/v2/validation/ingest — raw QR/barcode payload submitted. System extracts serial number and note metadata.

Parse QR

POST /api/v2/validation/parse_qr — structured extraction of denomination, issuer country, corridor code, issued_at timestamp.

Signature verification

POST /api/v2/validation/verify_signature — Ed25519 signature checked against the issuing central bank's registered public key from IssuerKey table.

Registry lookup

GET /api/v2/validation/registry_lookup/:serial — confirms the serial was issued by a known central bank and is in ISSUED or ACTIVE state.

Duplicate check

GET /api/v2/validation/duplicate_check/:serial — verifies the serial has not been presented before. Duplicate = potential fraud.

Compliance action

Operator reviews results and takes action: approve (clear for settlement), reject (return to submitter), freeze (hold pending investigation), or flag (escalate to supervisor).

Duplicate Detection Logic

A serial number may be presented once and once only.
On first presentation: record is created with presented_at timestamp.
On subsequent presentation: duplicate_detected = true. Operator must freeze and investigate.
⛔
A duplicate serial number is the primary indicator of CBDC counterfeiting or double-spend. The freeze action must always be taken automatically when duplicate_detected = true. The operator may not approve a duplicate note.
§4

Compliance Actions

ActionAPI EndpointEffectAvailable when
ApprovePOST /validation/approveNote cleared for settlement. Status → approved.signature_valid AND registry_match AND NOT duplicate
RejectPOST /validation/rejectNote returned to submitter. Status → rejected.Any state
FreezePOST /validation/freezeNote held pending investigation. Status → frozen. Alert raised.Any state — mandatory for duplicates
FlagPOST /validation/flagNote flagged for supervisor review. Duplicate flag record created.Any state
§5

API Reference

MethodPathDescription
POST/api/v2/validation/ingestSubmit raw CBDC note payload for validation
POST/api/v2/validation/parse_qrParse QR/barcode string into structured note metadata
GET/api/v2/validation/inboxList pending validation items
POST/api/v2/validation/verify_signatureVerify Ed25519 signature against issuer's public key
GET/api/v2/validation/registry_lookup/:serialCheck serial in issued notes registry
GET/api/v2/validation/duplicate_check/:serialCheck if serial has been previously presented
POST/api/v2/validation/approveApprove note for settlement
POST/api/v2/validation/rejectReject note
POST/api/v2/validation/freezeFreeze note pending investigation
POST/api/v2/validation/flagFlag note for supervisor review
GET/api/v2/validation/logs/:serialFull audit log for a specific serial number
GET/api/v2/validation/logs/:serial/exportExport audit log as CSV
SmartCheq · Validation Desk Specification · TowerPoint Group · April 2026
🗑️

Remove Saved Contact?

Contact Name
abc123...xyz789

⚠️ You will need their Cash Code again to send them money in the future.

CBDC Preview
Status Valid
Currency -
Amount -
Serial Number -
Uploading files...
Please wait
💸
Confirm Giving Cash
Check the details below
Amount GHS 0.00
To Cash Code ...
Cash Notes 0
⚠️

Already Transferred

The following CBDC notes have already been transferred and cannot be used again.

📱 Your Digital Cash Code QR

Let others scan this to send you money

How to use: The sender opens "Send Digital Cash" and taps the scan icon to read this QR code.

Trade Claim Submission

Submit verified trade to request cross-border liquidity.

Claiming Institution

Select Country...

Trade Details

Select Corridor first...

Select a corridor to load destination-country institutions.

Beneficiary Information

Supporting Documents

Click to upload or drag and drop

PDF, PNG, or JPG (max 10MB each)

Declarations

Confirm Trade Claim
Please review the details before submitting
Amount
Corridor
Institution
Beneficiary
Invoice Ref
Direction
⚠️

Once submitted, this trade claim will enter the supervisory review queue and cannot be edited. Please verify all details are correct.

Trade Claim Submitted!

Your trade claim has been successfully submitted and is now pending
review for pre-clearance by regulators.

Trade Claim ID:
TC-20260215-000000

An initial pre-clearance review shows your trade appears compliant.
It will now be routed for final approval.

Pre-cleared trade is pending review by regulators for approval.
Beneficiary funds will be held while the trade is being finalized.
Track status any time via the Issuance → Desk section.
📊 Trade Summary:
Trade Amount KES 1,000,000
Trade Direction Import into Nigeria
Beneficiary Kenya Exports Ltd
Help & Docs · Contact Support · Dashboard

Draft Saved!

Your trade claim has been saved as a draft.
You can continue editing it anytime.

Draft Reference:
TC-00000000

Your draft has been saved and can be accessed from your dashboard.
Complete the submission when you're ready.

Draft saved securely to your account.
Continue editing anytime from your dashboard.
Submit when ready via Drafts section.
📋 Draft Summary:
Amount KES 0
Direction -
Status Draft
Help & Docs · Contact Support · Dashboard

Issuance Desk

Manage and review recent cross-border trade claims.

Claim ID
Direction
Destination Corridor
Amount
Status
View

Loading trade claims...

No trade claims found

Showing 0 of 0
Help & Docs · Contact Support · Dashboard
SmartCheq
Admin Console
SA
Admin Console v1.2.3

Administrator Console

System management and monitoring dashboard.

Total Corridor Volume
USD Equivalent
—
Pending Claims
— ⏳ Pending
Daily Limit Utilization
USD Equivalent
—
Non-Compliance Alerts
—
Admin viewed trade claims. Today at —

Latest Trade Claim Activity

Read-only monitoring view. No transactional authority.

ID Institution Amount Corridor Status Risk
Loading claims...

Corridor Volume

0

Active Issuance Queue

0 Pending requests

Corridor Quota Limits

Corridor Corridor Limit Remaining Daily Limit Remaining Compliance Status
Loading corridor data...
Admin Console v1.2.3
🔒 System Admin