research: validate parallel cash currencies in Southern Africa

[okjodom]

Context

PR #24 adds national-currency cash channels for Angola, Botswana, Eswatini, Lesotho, Mozambique, Namibia, and Zambia as a regional batch under #21.

Initial review found authoritative indications that the South African rand is also legal tender in:

• Lesotho, alongside the loti: https://centralbank.org.ls/about-the-kingdom-of-lesotho/
• Namibia, alongside the Namibia dollar: https://www.bon.com.na/Informations/Media/Media-Releases/2025-Media-Releases/Articles/Inflation-Target.aspx
• Eswatini, alongside the lilangeni: https://www.centralbank.org.sz/currency/

Issue #21 intentionally distinguishes legal-tender status from documented ordinary physical-cash circulation. A Southern African market expert should therefore validate the practical market coverage before these additional schemas are added.

Research scope

• Confirm whether physical ZAR notes and coins circulate for ordinary payments in Lesotho, Namibia, and Eswatini, not merely whether the currencies are pegged or exchangeable.
• Confirm whether cash_ls_zar, cash_na_zar, and cash_sz_zar belong in the built-in registry.
• Check the full PR feat: add Southern Africa regional cash channels. #24 regional batch for any other official, parallel, or shared cash currencies that meet feat: add cash channels for every African country and currency #21's inclusion criteria.
• Record authoritative sources, exclusions, ambiguous cases, and an as of date.
• Note any operational nuance that belongs in research documentation, while keeping the schemas themselves declarative and market-neutral.

Proposed implementation if validated

• Add one market-qualified schema per accepted country/currency pair using createCashPaymentChannel.
• Preserve the existing PR feat: add Southern Africa regional cash channels. #24 IDs and behavior; the new channel IDs and exports should be additive.
• For countries with multiple cash currencies, use unambiguous source filenames such as cash_lsl.ts and cash_zar.ts, and update the source-layout contract deliberately.
• Register and export the new schemas and update registry tests and README coverage.

Acceptance criteria

• A Southern African market expert reviews the country/currency findings.
• Each accepted or excluded pair has an authoritative source and verification date.
• Ordinary physical-cash circulation is distinguished from a peg, convertibility, or tolerated foreign-currency use.
• Any validated schemas are added without changing existing stable IDs.
• Registry tests cover every accepted pair and reject omissions or duplicates.
• npm run check, npm pack --dry-run, and npm run verify:pack pass.

Related: #21, #24

[altradits]

Southern Africa Cash Circulation Research & Proposed Matrix (as of Sep 2026)

Following up on the PR #24 batch and the requirements of #21 and #25, here is the market validation for parallel physical cash circulation in the Southern Africa region.

---

1. In-Scope: Common Monetary Area (CMA) Dual-Currency Markets

Under the Multilateral Monetary Agreement (MMA) establishing the Common Monetary Area (CMA) between South Africa, Lesotho, Namibia, and Eswatini:

A. Lesotho (LS)

• Official National Currency: Lesotho Loti (LSL)
• Parallel Legal Tender: South African Rand (ZAR)
• Status & Physical Circulation: Under Section 25 of the Central Bank of Lesotho Act 2000 and the CMA agreement, the South African Rand is legal tender throughout Lesotho at par (1:1 with Loti). Both LSL and ZAR banknotes and coins circulate freely in everyday retail transactions across the country.
• Proposed Schemas:
  • cash_ls_lsl (existing)
  • cash_ls_zar (additive)

B. Namibia (NA)

• Official National Currency: Namibia Dollar (NAD)
• Parallel Legal Tender: South African Rand (ZAR)
• Status & Physical Circulation: Under the Bilateral Monetary Agreement between Namibia and South Africa and Bank of Namibia Currency Policy, the South African Rand circulates as legal tender alongside the Namibia Dollar at 1:1. ZAR banknotes are freely used and accepted by retailers for physical cash transactions throughout Namibia.
• Proposed Schemas:
  • cash_na_nad (existing)
  • cash_na_zar (additive)

C. Eswatini (SZ)

• Official National Currency: Swazi Lilangeni (SZL)
• Parallel Legal Tender: South African Rand (ZAR)
• Status & Physical Circulation: Under the Central Bank of Eswatini Currency Framework, the Lilangeni is pegged 1:1 with the Rand, and South African Rand notes are accepted as legal tender and circulate widely alongside Emalangeni in day-to-day trade throughout the kingdom.
• Proposed Schemas:
  • cash_sz_szl (existing)
  • cash_sz_zar (additive)

---

2. Excluded from Parallel Cash: Non-CMA PR #24 Markets

The remaining markets in the PR #24 batch were verified as single physical cash currency jurisdictions:

• Angola (AO - AOA): Banco Nacional de Angola — Law on Foreign Exchange mandates all domestic cash transactions be settled exclusively in Angolan Kwanza (AOA). Foreign physical cash (e.g. USD) does not have legal tender status for domestic transactions.
• Botswana (BW - BWP): Bank of Botswana — Botswana withdrew from the Rand Monetary Area in 1976. Only Botswana Pula (BWP) notes and coins are legal tender for domestic retail payments.
• Mozambique (MZ - MZN): Banco de Moçambique — Only the Mozambican Metical (MZN) is legal tender for domestic cash settlement.
• Zambia (ZM - ZMW): Bank of Zambia — Under SI 33 and the Bank of Zambia Act, quoting and settling domestic cash payments must be done in Zambian Kwacha (ZMW).
• South Africa (ZA - ZAR): South African Reserve Bank — Only ZAR is legal tender. Note that LSL, NAD, and SZL do not circulate in South Africa (the peg is unilateral).

---

3. Source Layout & Implementation Plan

To support multiple cash currencies within a single country directory without breaking existing stable IDs or imports:

1. Source Layout:
   • For multi-currency countries, use unambiguous source filenames:
     • src/channels/ls/cash_lsl.ts and src/channels/ls/cash_zar.ts
     • src/channels/na/cash_nad.ts and src/channels/na/cash_zar.ts
     • src/channels/sz/cash_szl.ts and src/channels/sz/cash_zar.ts
2. Layout Contract Test:
   • Update test/payment-channels.test.mjs (channel source files are grouped by country and match stable channel IDs test) so that a country with multiple cash currencies matches cash_${currency.toLowerCase()}.ts while single-currency countries continue to match cash.ts.
3. Additive Exports:
   • Register cash_ls_zar, cash_na_zar, and cash_sz_zar in builtinPaymentChannels and re-export them from src/index.ts.
   • Existing stable IDs (cash_ls_lsl, cash_na_nad, cash_sz_szl) and export names remain completely unchanged.

[altradits]

Implemented in #33 with dual-currency cash channels for Lesotho, Namibia, and Eswatini, complete with contract tests and docs update.