SmartCheq · Module Specification
CBDC Issuance System
The Issuance Tab is the central bank operator's interface for creating, authorising, and dispatching CVIB (CBDC Voucher in Bearer) batches. It covers the complete lifecycle from draft configuration through governance approval, note minting, vault encryption, and ownership transfer to commercial banks.
§1
System Overview
The Issuance system orchestrates the creation of Central Bank Digital Currency notes (CBDCNotes) backed by real central bank reserves locked in the Corridor Ops module. A batch of notes is minted, cryptographically signed with the issuing bank's Ed25519 key, packaged into a vault-encrypted bundle, and transferred to a commercial bank — the "Claiming Institution".
Key Concepts
| Concept | Definition | Example from UI |
|---|---|---|
| Draft Issuance | Initial configuration record. Country, central bank, currency, denomination and corridor are selected. Not yet submitted to governance. | IA-E0E7A9E144D8-20260407 |
| Authorization | Governance-gated approval that links the issuance to a backing liquidity lock. Requires a second operator (Four-Eyes). | 50d5ed31-f072-4018-b4e5-9fe883004208 |
| Minting | The act of generating individual CBDCNotes with serial numbers, denominations, and issuer signatures within a MintBatch. | 5 notes, L-XOF |
| Batch Generation | The MintBatch record grouping all notes: serial range, asset code, holder ID, issuer key, expiry. | 70f75f6f-9164-4ae3-ae38-f347732cdc9d |
| Ownership Transfer | Cryptographically signed handoff of the note bundle from the issuing central bank to the claiming commercial bank via email or SFTP. | BANQUE ATLANTIQUE DU BENIN — ATBJBJBJ |
| Manifest | A hash-signed inventory of all notes in the bundle. Used by the receiving institution to verify bundle integrity before accepting notes. | Manifest Hash field (empty until generated) |
Left Pane — Configuration
- Issuance config draft
- Country / Central Bank / Governor
- Asset code & currency details
- Corridor identity
- Denomination selector
- Refresh / Edit Plan
Middle Pane — Activity
- Issuance flow stepper (5 stages)
- Issuance registry activity feed
- Per-note table with status
- Refresh / Import Metadata / Download Manifest
Right Pane — Controls
- Authorization snapshot
- Governance approval banner
- Authorize mint batch
- Transfer destination
- Transfer readiness checklist
- Vault authentication
- Batch configuration
- Claiming institution
- Packaging options
- Transfer Ownership
§2
Data Model
IssuanceDraft
| Field | Type | Example | Description |
|---|---|---|---|
| id | string | IA-E0E7A9E144D8-20260407 | Composite: IA-{hex}-{YYYYMMDD} |
| country | string | Mali | Issuing country (target country of corridor) |
| central_bank | string | BCEAO | Central bank name |
| governor | string | Jean-Claude Kassi Brou | Signing authority name |
| city | string | COTONOU | Central bank city |
| branch | string | — | Optional branch designation |
| asset_code | string | L-XOF | Prefixed ISO 4217: L-{currency} |
| swift_bic | string | BCAOBJBJ | SWIFT/BIC of issuing central bank |
| symbol | string | FCFA | Currency symbol |
| serial_pattern | string | N11A1 | Typed segments: N=numeric, A=alpha. Drives serial number generation. |
| currency_no | string | 952 | ISO 4217 numeric code |
| iban | string | — | IBAN if applicable |
| country_code | string | ML | ISO 3166-1 alpha-2 |
| coin_symbol | string | c | Subunit symbol (centime) |
| iso_4217 | string | XOF | ISO 4217 alphabetic code |
| coin_name | string | centime | Name of subunit |
| currency_name | string | West African CFA Franc | Full currency name |
| denomination | decimal | 10,000 | Face value per note |
| pieces_per_unit | integer | 1 | Notes per unit (usually 1) |
| denomination_type | enum | Linked | Domestic | Linked — determines corridor vs domestic issuance |
| asset_type | string | — | Populated from corridor config |
| status | enum | draft | draft | preview | authorization | generation | minted |
IssuanceAuthorization
| Field | Type | Example | Description |
|---|---|---|---|
| authorization_id | string | IA-E0E7A9E144D8-20260407 | Same as draft ID — authorization inherits draft reference |
| asset_code | string | L-XOF | Asset being authorized |
| total_amount | decimal | 50000.0 | Total face value of the authorization (denomination × notes) |
| backing_lock_id | string | 50d5ed31-f072-4018-b4e5-9fe883004208 | References LiquidityLock.id from Corridor Ops. Must be ACTIVE. |
| corridor | string | GHA → MLI | Source and target country of the corridor |
| approved_by | string | (governor operator identity) | Doorkeeper token owner who approved |
| status | enum | Approved | pending | approved | rejected |
| timestamp | timestamp | 2026-04-07 | Approval timestamp (UTC) |
MintBatch
| Field | Type | Example | Description |
|---|---|---|---|
| batch_id | uuid | 70f75f6f-9164-4ae3-ae38-f347732cdc9d | UUID generated at batch creation |
| asset_code | string | L-XOF | From authorization |
| serial_range | string | L-XOF-00000000001 → L-XOF-00000000005 | First and last serial in batch |
| number_of_notes | integer | 5 | Total notes in batch |
| denomination | decimal | 10,000 | Face value per note (XOF) |
| issue_date | date | 07.04.2026 | Date notes were minted |
| expiry_date | date | None | Optional expiry — "None" means perpetual |
| holder_id | string | Bank of Ghana (long hash) | Initial holder — the issuing central bank |
| issuer_key | string | Bank of Ghana — BOG Primary Key | Ed25519 key reference used to sign notes |
| authorization_id | string | IA-E0E7A9E144D8-20260407 | Parent authorization |
| status | enum | minted | pending | minted | transferred |
CBDCNote
| Field | Type | Example | Description |
|---|---|---|---|
| serial_number | string | L-XOF-00000000001 | Unique serial. Format: {asset_code}-{serial_pattern} |
| asset_code | string | L-XOF | From parent batch |
| denomination | decimal | 10,000 | Face value (XOF) |
| status | enum | ACTIVE | ACTIVE | TRANSFERRED | REDEEMED | BURNED |
| country | string | Mali | Issuing country |
| currency_name | string | West African CFA Franc | Full currency name |
| central_bank | string | Central Bank of West Africa | Issuing institution |
| issuance_date | datetime | 07.04.2026 10:28 | Creation timestamp (UTC) |
| tender | string | Banknotes | Tender type designation |
| denomination_value | string | 10000 FCFA | Display value with symbol |
| denomination_nominal | string | 10000fr | Nominal display value |
| holder | string | Bank of Ghana | Current holder (changes on transfer) |
| issuer | string | Bank of Ghana — BOG Primary Key | Signing issuer — never changes |
TransferRequest
| Field | Type | Example | Description |
|---|---|---|---|
| target_institution | string | BANQUE ATLANTIQUE DU BENIN | Full name of claiming commercial bank |
| bic_swift | string | ATBJBJBJ | SWIFT code of claiming bank |
| method | enum | Email | SFTP | |
| destination | string | info@towerpointgroup.com | Email address or SFTP host for delivery |
| verification_status | enum | Pending | Pending | Verified | Failed |
| sftp_host | string | — | SFTP hostname (if method = SFTP) |
| sftp_directory | string | — | Remote directory for SFTP delivery |
| sftp_username | string | — | SFTP login username |
| sftp_password | string | — | SFTP password (encrypted at rest) |
| transfer_status | enum | — | pending | in_progress | completed | failed |
Manifest
| Field | Type | Description |
|---|---|---|
| manifest_hash | string | SHA-256 hash of the bundle contents. Displayed in right pane Manifest Hash field. Empty until batch is generated. |
| authorization_id | string | References IssuanceAuthorization |
| batch_id | uuid | References MintBatch |
| integrity_status | enum | unverified | verified | mismatch |
| generated_at | timestamp | When manifest was created |
VaultConfig
| Field | Type | Description |
|---|---|---|
| vault_name | string | Selected from "Select Vault" dropdown. Vault must be pre-configured. |
| password | string | Vault encryption password (not stored — used only at runtime) |
| output_path | string | Filesystem path where encrypted bundle is written |
| tender | string | Auto-populated from issuance draft |
| mode | enum | Encryption mode (e.g. AES-256-GCM) |
| key_length | integer | Encryption key size in bits |
| block_size | string | Encryption block/padding size |
§3
Left Pane — Issuance Configuration
Issuance Config Draft section
Read-only display panel populated when a corridor is loaded. Shows the identity of the issuing (target) central bank — in the mockup, Mali / BCEAO — since the CBDC notes are denominated in the target country's currency.
| Field | Value (mockup) | Source / Validation |
|---|---|---|
| Country | Mali | Resolved from corridor's target_country ISO3 via kIso3Names map |
| Central bank | s de l'Afrique de l'Ouest, BCEAO | Resolved from kCbMap target entry |
| Governor | Jean-Claude Kassi Brou | Stored in IssuerKey or central bank metadata record |
| City | COTONOU | Central bank city from metadata |
| Branch | — | Optional. Empty if not applicable. |
| Governance | — | Populated with governance approval status after authorization |
Asset Code & Currency section
All fields are read-only, derived from the loaded corridor and its target currency. The asset code L-XOF = "Linked" prefix + ISO 4217 code. "Linked" means the issuance is backed by a cross-border corridor lock (as opposed to "Domestic" which would be a single-country issuance).
| Field | Value | Rule |
|---|---|---|
| SWIFT/BIC | BCAOBJBJ | From IssuerKey.swift_bic for the target central bank |
| Symbol | FCFA | Currency symbol from currency metadata |
| Serial pattern | N11A1 | Drives SerialAllocationService. N=numeric(11 digits), A=alpha(1 char), 1=literal. Must match corridor config. |
| Currency no. | 952 | ISO 4217 numeric code |
| IBAN | — | Optional — not applicable for XOF |
| Country code | ML | ISO 3166-1 alpha-2 of issuing country |
| Coin symbol | c | Subunit (centime) |
| ISO 4217 | XOF | Alphabetic ISO currency code |
| Coin name | centime | Name of the subunit denomination |
| Currency name | West African CFA Franc | Full English currency name |
Corridor Identity section
Mirrors the selected corridor from Corridor Ops. Drives the authorization's backing lock reference.
| Field | Value | Description |
|---|---|---|
| Country | Ghana | Source country of the corridor (the funder) |
| Central Bank | Bank of Ghana | Source central bank |
| Currency | GHS | Source currency ISO code |
| Governor | Dr. Johnson Pandit Asiama | Governor of the source central bank |
| Total auth. | 50,000 L-XOF | Total authorized issuance amount for this corridor |
| FX rate | 1 GHS = 50.5425 XOF | Exchange rate used to calculate corridor value equivalence. From GET /api/v2/corridors/:id/fx_rate. Used in issuance valuation display only — does not change note denomination. |
| Liquidity | Bank of Ghana Reserve Pool | Which reserve pool backs this issuance |
| Funding lock | LOCK-GHA-04208 | Short reference to the LiquidityLock in Corridor Ops. The full UUID is shown in the Authorization panel on the right (50d5ed31-…). This lock must be ACTIVE for authorization to proceed. |
Select count denomination section
| Control | Value | Behaviour |
|---|---|---|
| Domestic / Linked radio | Linked (selected) | Domestic: notes are backed by local central bank funds only. Linked: notes are backed by a cross-border corridor lock. Linked is required when issuance spans two countries (e.g. GHA funding → MLI notes). Selection changes the asset_code prefix (Domestic = D-, Linked = L-). |
| Asset type | — | Read-only. Populated from corridor asset configuration. |
| Denomination | 10,000 × | Dropdown of allowed denominations for the currency. Selection determines face value per note. Validation: must be a valid denomination for the ISO 4217 currency. |
| Pieces/unit | 1 | Numeric stepper. How many physical notes per bundle unit. Default 1. Used to calculate total_notes = count × pieces_per_unit. |
| Active auths | 🇬🇭 GHA → 🇲🇱 MLI | L-XOF | | Read-only chips showing all active authorizations for the current corridor. Clicking an auth chip loads it into the right pane. |
Total issuance calculation: total_amount = denomination × pieces_per_unit × note_count. In the mockup: 10,000 × 1 × 5 = 50,000 XOF (matching the Authorization total_amount).
Left Pane Buttons
RefreshLeft Pane
Action
Reloads corridor identity and active authorizations from API. Useful when another operator has updated the corridor since the tab was opened.
API
GET /api/v2/corridors/:id, GET /api/v2/corridors/:id/fx_rate, GET /api/v2/issuance_authorizations/latest
Success
Left pane fields repopulated. Active auths chips refreshed. FX rate updated.
Failure
Toast error if API unreachable. Fields remain at last-known state.
Edit PlanLeft Pane
Action
Opens the issuance draft for editing. Unlocks denomination selector, pieces/unit, and domestic/linked toggle. Only available when status = draft or preview (not after authorization).
Precondition
issuance status must be
draft or preview. If status ≥ authorization, button is disabled.State change
Draft record becomes editable. Save triggers recalculation of total_amount.
§4
Middle Pane — Issuance Activity & Lifecycle
A. Issuance Flow Stepper (top bar)
A horizontal 5-stage pipeline showing the progression of the issuance. Each stage is a card with key identifiers. The active stage is highlighted. Current status shown in top-right corner: Approved (green badge).
| Stage | Display | Entry Condition | Exit Condition | State |
|---|---|---|---|---|
| Draft | IA-E0E7A9E144D8-20260407 | Corridor selected + denomination configured | Operator submits for preview | issuance.status = draft |
| Preview | 🇬🇭 GHA → 🇲🇱 MLI / 10,000 × 5 / 50000.0 | Draft saved | Submitted to authorization queue | issuance.status = preview |
| Authorization | IA-E0E7A9… / 50d5ed31-… / L-XOF-00000000001 → L-XOF-00000000005 / — | Preview reviewed | Second operator approves (Four-Eyes) | issuance.status = authorization, auth.status = approved |
| Generation | 70f75f6f-9164-… / L-XOF / — | Authorization approved | Mint batch button clicked and batch created | issuance.status = generation |
| Minted | 5 notes | Batch generated successfully | Transfer Ownership completed | issuance.status = minted |
B. Issuance Registry Activity Feed table
Displays all CBDCNotes generated in the current batch. Rows are populated after minting. Each row represents one note.
| Column | Source | Example | Notes |
|---|---|---|---|
| Row # | Display index | 1–5 | Not a DB field — display row counter |
| Radio button | UI only | ○ | Single-select row for note detail view |
| Serial | CBDCNote.serial_number | L-XOF-00000000001 | Clickable — opens note detail. Format: asset_code + serialized pattern |
| Asset | CBDCNote.asset_code | L-XOF | Same for all notes in batch |
| Denomination | CBDCNote.denomination | 10,000 | Face value. Sortable. |
| Status | CBDCNote.status | ● ACTIVE | Green dot = ACTIVE. Color-coded pill. States: ACTIVE, TRANSFERRED, REDEEMED, BURNED. |
| Country | CBDCNote.country | Mali | Issuing country |
| Currency Name | CBDCNote.currency_name | West African CFA Franc | Full currency name |
| Central Bank | CBDCNote.central_bank | Central Bank of We... | Truncated for display. Full name on hover/click. |
| Issuance Date | CBDCNote.issuance_date | 07.04.2026 10:28 | Format: DD.MM.YYYY HH:MM |
| Tender | CBDCNote.tender | Banknotes | Tender type — from vault config. Values: Banknotes, Coins, Electronic. |
| Denomination Value | CBDCNote.denomination_value | 10000 FCFA | Amount with currency symbol |
| Denomination Nominal | CBDCNote.denomination_nominal | 10000fr | Nominal display value with coin symbol |
Table interactions
Rows are read-only. No in-table editing.
Radio button on each row enables single-select for note inspection.
Table is populated after MintBatch status = minted. Empty before that stage.
Horizontal scroll enabled — table has more columns than visible area.
C. Middle Pane Buttons
RefreshMiddle Pane
Action
Reloads the registry activity feed table. Fetches latest note statuses from API.
API
GET /api/v2/cvib/batches/:batch_id/notes (or equivalent notes endpoint)
Success
Table rows refreshed. Status pills updated (e.g. ACTIVE → TRANSFERRED after ownership transfer).
Import MetadataMiddle Pane
Action
Opens a file picker. Operator selects a metadata JSON/CSV file previously exported from another system. Populates issuance draft fields from the file.
API
POST /api/v2/cvib/batches/:id/import_metadata with file payload
Validation
File must match expected schema. Corridor and asset code must match current selection. Duplicate serials rejected.
Success
Draft fields pre-populated. Stepper advances to Preview stage.
Failure
Schema mismatch → error dialog listing invalid fields. No partial import.
Download / Verify ManifestMiddle Pane
Action
Downloads the manifest file for the current batch AND verifies its hash. The manifest is a signed inventory of all notes. Button is disabled (greyed out in mockup) until a batch has been generated.
API
GET /api/v2/cvib/batches/:batch_id/manifest → returns manifest file + hash
Verification
System recomputes hash of downloaded manifest. Compares to stored Manifest.manifest_hash. Updates Manifest.integrity_status.
Success
File saved locally. integrity_status → verified. Manifest Hash field on right pane populated.
Failure (mismatch)
integrity_status → mismatch. Transfer Ownership button blocked. Critical alert shown.
Disabled when
issuance.status < generation OR no batch exists
§5
Right Pane — Authorization, Transfer & Controls
A. Authorization Snapshot (top dropdown)
Dropdown at top of right pane reads "Bank of Ghana — BOG Primary Key". Selecting a key loads the authorization snapshot for that issuer key. All fields below are read-only snapshots.
| Field | Value | Description |
|---|---|---|
| Issuance Authorization ID | IA-E0E7A9E144D8-20260407 | Matches draft ID. Read-only. |
| Asset Code | L-XOF | From authorization record |
| Total Amount | 50000.0 | Authorized total face value |
| Backing Lock ID | 50d5ed31-f072-4018-b4e5-9fe883004208 | Full UUID of LiquidityLock from Corridor Ops. Dropdown — selectable if multiple locks available. |
| Corridor | 🇬🇭 GHA → 🇲🇱 MLI | Visual corridor indicator with flags |
B. Governance Approval Banner
Large green "Approved" banner with text "Read-only snapshot of the request". Below it, a locked text area shows the authorization notes (read-only). This banner only shows when auth.status = approved. When pending, it shows a waiting spinner.
C. Authorize mint batch section
Authorize packageRight Pane (disabled)
State in mockup
Greyed out / disabled. Already authorized — cannot re-authorize.
When enabled
Only when issuance.status = preview AND no existing authorization exists for this draft.
Action when clicked
Creates IssuanceAuthorization record with status=pending. Notifies second operator. Stepper advances to Authorization stage.
API
POST /api/v2/issuance_authorizations {corridor_id, draft_id, backing_lock_id, asset_code, total_amount}
Authorize mint batchRight Pane (active)
Preconditions
auth.status = approved. issuance.status = authorization. Backing lock must be ACTIVE. No existing MintBatch for this authorization.
Action
Creates MintBatch record. Generates all CBDCNotes with serial numbers allocated by SerialAllocationService. Signs each note with IssuerKey. Sets issuance.status = generation → minted.
API
POST /api/v2/cvib/batches {authorization_id, issuer_key_id, denomination, note_count, holder_id, expiry_date}
Success
MintBatch created. Notes appear in registry table with status=ACTIVE. Stepper advances to Minted. Export send bundle button enables.
Failure
Lock expired → error "Backing lock is no longer active". Serial collision → "Serial range already allocated". Either blocks minting.
Export send bundleRight Pane
Preconditions
issuance.status = minted. Vault authenticated. Manifest verified. Transfer destination configured. All Transfer Readiness checks green.
Action
Packages all notes into an encrypted vault bundle. Generates manifest. Writes bundle to output_path. Does NOT yet send — staging step before Transfer Ownership.
API
POST /api/v2/cvib/batches/:id/export_bundle {vault_config, output_path}
Success
Bundle file created at output_path. Manifest hash populated in right pane. Ready for Transfer Ownership.
D. Transfer Destination section
Configures where and how the note bundle is delivered to the claiming commercial bank.
| Field | Value | Description |
|---|---|---|
| Target (read-only) | BANQUE ATLANTIQUE DU BENIN - ATBJBJBJ | Populated from Claiming Institution selection. Full name + SWIFT code. |
| BIC/SWIFT (read-only) | ATBJBJBJ | SWIFT code of claiming bank |
| Method dropdown | Select Email or SFTP. Changes visible sub-fields. | |
| Destination (read-only) | info@towerpointgroup.com | Auto-populated from claiming institution's registered email |
| Verification | Pending (orange) | Status of destination verification. Pending = not yet confirmed reachable. System attempts to verify on bundle export. |
| Email field | info@towerpointgroup.com | Editable if method = Email. Must be valid email format. |
| Host (SFTP) | Select SFTP Host | Visible only when method = SFTP |
| Directory (SFTP) | Select Directory | Remote path — visible when method = SFTP |
| Username (SFTP) | — | SFTP login — visible when method = SFTP |
| Password (SFTP) | •••••••• (masked) | SFTP password — visible when method = SFTP. Stored encrypted. |
E. Transfer Readiness Checklist
Four system checks that must all be green before Transfer Ownership is permitted. Each is a checkbox — green tick = passed, empty = not yet checked.
| Check | Status (mockup) | System check |
|---|---|---|
| Vault Authenticated | ☐ (unchecked) | Vault password entered and validated against vault_name. Vault file accessible at output_path. |
| Manifest Verified | ☐ (unchecked) | Manifest hash recomputed and matches stored hash. integrity_status = verified. |
| Target Host Reachable | ✅ (green) | System ping/connectivity test to destination email server or SFTP host succeeded. |
| Claiming Institution Verified | ✅ (green) | Claiming institution's SWIFT code validated against institution registry. BIC/SWIFT = ATBJBJBJ confirmed. |
⛔
Transfer Ownership button remains disabled until ALL four checks show green ticks. No partial transfer is permitted.
F. Vault Authentication section
| Field | Type | Description |
|---|---|---|
| *Password | Password input (masked) | Vault encryption password. Required. Used to decrypt/encrypt the vault bundle. NOT stored. |
| *Confirm Password | Password input (masked) | Must match Password field. Validation: exact character match. |
| *Vault Name | Dropdown "Select Vault" | Required. Pre-configured vault identifiers. Selection loads vault metadata (mode, key length, block size). |
| Output path | Text "Select vault above..." | Auto-populated from vault config. Filesystem path where bundle is written. Read-only until vault is selected. |
| *Tender | — | Auto-populated from issuance tender type (Banknotes). Read-only display. |
| *Mode | Dropdown "Select Mode" | Encryption mode — e.g. AES-256-GCM. Required. Loaded from vault config on vault selection. |
| *Key Length | Dropdown "Select Key Length" | Encryption key length in bits — e.g. 256. Required. |
| *Block Size | Dropdown "Select Padding" | Block/padding size for the cipher. Required. |
When vault name is selected, Mode, Key Length, and Block Size are auto-populated from the vault configuration record. The operator must still enter Password and Confirm Password manually — these are never stored.
G. Batch Configuration section (Authorization Snapshot lower half)
| Field | Value | Description |
|---|---|---|
| Issuance Authorization ID | IA-E0E7A9E144D8-20260407 | Read-only. Links batch to authorization. |
| Asset Code | L-XOF | Read-only. From authorization. |
| Backing Lock ID | 50d5ed31-f072-4018-b4e5-9fe883004208 | Dropdown. Active Corridor Ops lock selected here — must match authorization's backing_lock_id. |
| Allocated Serial Block | L-XOF-00000000001 → L-XOF-00000000005 | Read-only after generation. SerialAllocationService output. |
| Batch ID | 70f75f6f-9164-4ae3-ae38-f347732cdc9d | Read-only UUID generated when batch is created. |
| Corridor | 🇬🇭 GHA → 🇲🇱 MLI | Read-only corridor indicator. |
| Initial Holder | Bank of Ghana | Read-only. The issuing central bank is always the initial holder. |
| Holder ID | BANQUE ATLANTIQUE DU BENIN (long hash) | The claiming institution's DID/holder identifier. This is set to the target bank — the holder AFTER transfer. The long hash (3a42dbe76594bf…) is the cryptographic holder identity. |
| Issuer Key | Bank of Ghana — BOG Primary Key (dropdown) | Ed25519 key used to sign notes. Must be an active IssuerKey for the source central bank. |
| Expiry Date | None | Optional note expiry. "None" = perpetual validity. |
| Authorization ID | IA-E0E7A9E144D8-20260407 | Repeated reference for clarity. |
| Manifest Hash | (empty) | Populated after Export send bundle. SHA-256 of bundle contents. Used for integrity verification by claiming institution. |
H. Claiming Institution section
| Field | Value | Description |
|---|---|---|
| Commercial Bank | BANQUE ATLANTIQUE DU BENIN - ATBJBJBJ | Name and SWIFT of receiving bank. Populated from institution registry. |
| City | — | City of claiming bank. Optional — from registry. |
| Branch | — | Branch of claiming bank. Optional. |
| BIC / SWIFT Code | ATBJBJBJ | Machine-readable SWIFT identifier. Used for verification check. |
| Public key section label | "Please use this section to select the public key" | Instructional label for key selection |
| Public key | Select Public Key (dropdown) | The claiming institution's Ed25519 public key. Used to encrypt the bundle so only they can decrypt it. Must be selected before Transfer Ownership. |
I. Packaging Options section
| Field | Value | Effect on notes |
|---|---|---|
| Watermark | Simulation Only (dropdown) | Embeds a visible watermark text on generated note documents. "Simulation Only" marks notes as non-production. Production deployments use "None" or a custom watermark. |
| Marking | None (Original) (dropdown) | Visual marking applied to note images/PDFs. "None (Original)" = unmodified. Other options may include color overlays or stamps. |
| Note Size | Original (100%) (dropdown) | Size scaling of note document output. 100% = full size. Reduced size options for preview/specimen purposes. |
| Print Barcode checkbox | ☑ Print barcode on note | When checked, a Code 128 barcode encoding the serial number is printed on each note. Used by validation desk for scanning. Barcode is the sole machine-readable identifier — QR codes are not used. |
J. Transfer Ownership button
Transfer OwnershipRight Pane — Primary Action
Preconditions (ALL required)
1. issuance.status = minted
2. All 4 Transfer Readiness checks = green
3. Vault authenticated (password + vault name set)
4. Manifest verified (integrity_status = verified)
5. Claiming Institution public key selected
6. Transfer destination configured (email or SFTP credentials)
2. All 4 Transfer Readiness checks = green
3. Vault authenticated (password + vault name set)
4. Manifest verified (integrity_status = verified)
5. Claiming Institution public key selected
6. Transfer destination configured (email or SFTP credentials)
Step-by-step
1. Client validates all preconditions locally. Shows error for any failed check.
2. Bundle encrypted with vault key + claiming institution's public key.
3. POST /api/v2/cvib/batches/:id/send_bundle_email OR SFTP delivery via sshpass batch file executed in QtConcurrent background thread.
4. On delivery success: all CBDCNotes.holder updated to claiming institution's holder_id.
5. All notes.status → TRANSFERRED.
6. issuance.status → transferred.
7. Corridor Ops linked_outstanding updated.
8. Audit log entry created: transferred_by, transferred_at, target_institution, delivery_method.
2. Bundle encrypted with vault key + claiming institution's public key.
3. POST /api/v2/cvib/batches/:id/send_bundle_email OR SFTP delivery via sshpass batch file executed in QtConcurrent background thread.
4. On delivery success: all CBDCNotes.holder updated to claiming institution's holder_id.
5. All notes.status → TRANSFERRED.
6. issuance.status → transferred.
7. Corridor Ops linked_outstanding updated.
8. Audit log entry created: transferred_by, transferred_at, target_institution, delivery_method.
Ledger impact
CBDCNote.holder = claiming institution holder_id. CBDCNote.status = TRANSFERRED. Corridor linked_outstanding += total_amount.
Failure: delivery error
Email bounce or SFTP timeout → notes remain ACTIVE, holder unchanged. Error dialog with retry option. issuance.status stays minted.
Failure: vault error
Wrong password → bundle encryption fails. "Vault authentication failed." Notes unchanged.
Failure: mid-transfer
If delivery fails after partial send (network cut): system rolls back CBDCNote status changes. Idempotent retry is safe — delivery_reference prevents double-send.
§6
Button-Level Summary
| Button | Pane | Enabled when | API call | Success effect |
|---|---|---|---|---|
| Refresh (left) | Left | Always | GET /corridors/:id, GET /fx_rate, GET /issuance_authorizations/latest | Left pane repopulated |
| Edit Plan | Left | status ∈ {draft, preview} | PATCH /issuance_drafts/:id | Fields editable, recalculates total |
| Refresh (middle) | Middle | Always | GET /cvib/batches/:id/notes | Registry table refreshed |
| Import Metadata | Middle | status = draft | POST /cvib/batches/:id/import_metadata | Draft pre-populated from file |
| Download/Verify Manifest | Middle | status ≥ generation | GET /cvib/batches/:id/manifest | File saved, hash verified |
| Authorize package | Right | status = preview, no auth exists | POST /issuance_authorizations | Auth created, notifies second operator |
| Authorize mint batch | Right | auth.status = approved, status = authorization | POST /cvib/batches | Batch + notes created, status → minted |
| Export send bundle | Right | status = minted, vault configured | POST /cvib/batches/:id/export_bundle | Bundle written, manifest hash populated |
| Transfer Ownership | Right | All 4 readiness checks green | POST /cvib/batches/:id/send_bundle_email | Notes → TRANSFERRED, holder updated |
§7
System Rules & Edge Cases
Authorization missing
Authorize mint batch button remains disabled. issuance.status cannot advance past authorization stage.
If authorization expires (no second operator action within TTL): auth.status → expired. Operator must re-submit via Authorize package.
Backing lock insufficient or expired
⛔
If the LiquidityLock referenced in backing_lock_id has status != active at the time Authorize mint batch is clicked, the server returns HTTP 422 {code: "lock_insufficient", message: "..."}. Minting is blocked. Operator must return to Corridor Ops and create a new lock.
Duplicate serial numbers
SerialAllocationService maintains a per-corridor sequence counter. Serials are allocated atomically in a DB transaction. Duplicate serial → HTTP 409 Conflict. Batch creation rolled back entirely.
Import Metadata: if uploaded file contains a serial that already exists → entire import rejected. No partial import.
Transfer fails mid-process
Email bounce after send: notes remain ACTIVE. Retry is safe — email delivery uses an idempotent delivery_reference token to prevent double-send.
SFTP connection dropped mid-transfer: sshpass script detects partial upload. Status not updated. Full retry required.
Manifest mismatch
Manifest.integrity_status → mismatch. Transfer Ownership button blocked. Manifest Verified readiness check → unchecked (red).
Operator must re-export bundle (Export send bundle) which regenerates the manifest and recomputes the hash.
Vault authentication failure
Wrong password → "Vault authentication failed." error. Vault Authenticated readiness check → unchecked.
Vault name not found → "Vault not found." error. Output path field remains empty.
Password mismatch (password ≠ confirm password): client-side validation prevents vault authentication attempt.
Simulation vs Production watermark
Packaging Options watermark = "Simulation Only" is the default and safe value. Notes generated with this watermark are visually marked and cannot be mistaken for production notes.
Production deployments must explicitly change watermark to "None" or a custom value. This is a mandatory operator action — no auto-promotion.
§8
End-to-End Flow
Complete walkthrough using the values visible in the mockup: GHA → MLI corridor, 5 × 10,000 XOF notes, claiming institution BANQUE ATLANTIQUE DU BENIN.
Operator creates issuance draft
Selects GHA → MLI corridor. Left pane auto-populates with BCEAO metadata, L-XOF asset code, serial pattern N11A1. Selects "Linked", denomination 10,000, pieces 1. Status = draft.
System generates preview
Operator clicks Edit Plan → saves. Preview stage card shows: 🇬🇭 GHA → 🇲🇱 MLI / 10,000 × 5 / 50000.0. Status = preview.
Authorization submitted
Operator clicks "Authorize package". POST /issuance_authorizations creates auth with status=pending, backing_lock_id=50d5ed31-…. Governor/second operator sees pending item in Governor Desk. Status = authorization.
Authorization approved (Four-Eyes)
Second operator (Dr. Johnson Pandit Asiama) approves in Governor Desk. auth.status → approved. Green "Approved" banner appears in right pane. Stepper authorization card shows IDs. "Authorize mint batch" button enables.
Mint batch created
Operator clicks "Authorize mint batch". POST /cvib/batches. SerialAllocationService allocates L-XOF-00000000001 through L-XOF-00000000005. 5 CBDCNote records created, all status=ACTIVE. Batch ID 70f75f6f-… generated. Registry table populates with 5 rows. Status = minted. Stepper shows "5 notes".
Transfer configured
Operator selects target institution BANQUE ATLANTIQUE DU BENIN, method Email, enters destination info@towerpointgroup.com. Selects Bank of Ghana BOG Primary Key as issuer. Selects vault, enters password. Claiming Institution Verified and Target Host Reachable checks turn green.
Bundle exported and manifest verified
Operator clicks "Export send bundle". Bundle encrypted and written to output path. Manifest hash generated and shown in Manifest Hash field. Operator clicks "Download/Verify Manifest" — integrity_status = verified. Manifest Verified check turns green.
Ownership transferred
All 4 readiness checks green. Operator clicks "Transfer Ownership". Bundle emailed to info@towerpointgroup.com. All 5 notes.holder → BANQUE ATLANTIQUE DU BENIN holder_id. All notes.status → TRANSFERRED. issuance.status → transferred. Corridor linked_outstanding += 50,000. Audit trail written.
✓
End state: 5 TRANSFERRED notes on L-XOF, holder = BANQUE ATLANTIQUE DU BENIN, corridor GHA→MLI linked_outstanding = 50,000 XOF, full audit trail from draft through transfer recorded, manifest verified by claiming institution.