feat: add cash channels for every African country and currency

[okjodom]

Problem

The built-in registry covers only a subset of African cash-using markets. Cash is a generic, non-automatable payment channel, and the package already exposes createCashPaymentChannel, but consumers in other African markets must create their own schemas.

This is the Africa cash-only companion to #20. That issue covers broader mobile-money, bank, card, and market expansion; this issue should not wait for provider-specific channel research. Cash-channel coverage outside Africa is tracked separately in #29.

Goal

Add a built-in cash_<country>_<currency> channel for every currently valid African country/territory and currency pairing in which physical cash is documented as circulating for ordinary payments.

Use the United Nations M49 Africa region as the geographic boundary. This includes Northern Africa and Sub-Saharan Africa, including countries and areas such as Western Sahara (EH) that have active ISO 3166-1 codes. Record disputed or otherwise ambiguous country/currency cases for maintainer review rather than silently omitting them.

“Every” means a source-backed African market matrix, not one guessed currency per country. Include:

• all active ISO 3166-1 countries and territories in the UN M49 Africa region where physical cash is used;
• each official/legal-tender currency that circulates there as physical cash;
• officially documented parallel or shared legal tender where it is genuinely usable as cash; and
• distinct country/currency pairs for shared currencies, such as every applicable XOF or XAF market.

Exclude:

• countries and territories outside the United Nations M49 Africa region, which are tracked by feat: add cash channels for every cash-using market outside Africa #29;
• ISO 4217 fund, precious-metal, test, and “no currency” codes;
• obsolete currencies;
• cryptocurrencies, account-only settlement units, and currencies with no physical cash form;
• merely tolerated foreign notes without a reliable source showing ordinary circulation; and
• assumptions based only on a country/currency lookup table when cash-circulation status is unclear.

Record ambiguous cases on this issue for maintainer review rather than inventing coverage.

Implementation guidance

• First post or commit the proposed African country/currency matrix with authoritative sources and an “as of” date. Prefer ISO-maintained country/currency data plus central-bank, government, or similarly authoritative sources for multi-currency and exceptional markets.
• Use the existing createCashPaymentChannel helper. Do not duplicate the shared cash definition or change its current schema version (2).
• Follow the stable ID and file conventions exactly: cash_<country>_<currency> in src/channels/<country>/cash.ts when a country has one cash currency.
• A country with multiple cash currencies needs one schema per country/currency pair. Because the repository requires one channel per source file, use unambiguous filenames such as cash_<currency>.ts where necessary and update the source-layout test deliberately.
• Register and export every schema through the existing public entry points.
• Keep cash declarative: no provider calls, ownership claims, limits, fees, exchange rates, or implication that cash settlement can be automated.
• Split the work into reviewable African regional or alphabetical PRs. Each PR must state which rows of the agreed matrix it completes; the issue remains open until the matrix is exhausted.

Acceptance criteria

• A reviewable, source-backed matrix defines all in-scope African country/territory and physical-currency pairs, its sources, exclusions, ambiguous cases, and verification date.
• The matrix has no overlap with the non-African scope tracked by feat: add cash channels for every cash-using market outside Africa #29.
• Every accepted matrix row has exactly one built-in, market-qualified cash schema.
• Every schema uses createCashPaymentChannel, retains schema version 2, has automation: none, and has no collection fields.
• Stable IDs, exports, registry entries, and country-grouped source files follow repository conventions, including a documented convention for multi-currency countries.
• Tests prove the African cash registry matches the accepted matrix exactly, with no missing or duplicate country/currency pairs.
• README.md describes the expanded cash coverage without implying provider integration or guaranteed local acceptance.
• Existing IDs and behavior remain unchanged, including cash_ke_kes, cash_mw_mwk, and cash_za_zar.
• npm run check, npm pack --dry-run, and npm run verify:pack pass.

Contributor notes

This is intentionally a large African coverage issue and should be completed through focused PRs. Before starting a batch, comment with the countries/territories you plan to cover to avoid duplicate work. Do not add speculative validation or automation: the schema describes in-person cash settlement only and does not prove that a particular merchant must accept that currency.

[altradits]

I would like to contribute the East Africa regional batch for cash channels:

1. Ethiopia (ET / ETB): Ethiopian Birr (National Bank of Ethiopia)
2. Uganda (UG / UGX): Uganda Shilling (Bank of Uganda)
3. Tanzania (TZ / TZS): Tanzanian Shilling (Bank of Tanzania)
4. Rwanda (RW / RWF): Rwanda Franc (National Bank of Rwanda)
5. Burundi (BI / BIF): Burundi Franc (Bank of the Republic of Burundi)
6. South Sudan (SS / SSP): South Sudanese Pound (Bank of South Sudan)

Working on this batch now.

[altradits]

I would like to claim the Southern Africa regional batch for the following cash channels:

1. Angola (AO / AOA): Angolan Kwanza (Banco Nacional de Angola)
2. Botswana (BW / BWP): Botswana Pula (Bank of Botswana)
3. Eswatini (SZ / SZL): Swazi Lilangeni (Central Bank of Eswatini)
4. Lesotho (LS / LSL): Lesotho Loti (Central Bank of Lesotho)
5. Mozambique (MZ / MZN): Mozambican Metical (Banco de Moçambique)
6. Namibia (NA / NAD): Namibia Dollar (Bank of Namibia)
7. Zambia (ZM / ZMW): Zambian Kwacha (Bank of Zambia)

Working on this batch now.

[altradits]

I would like to claim the North Africa regional batch for the following cash channels:

1. Algeria (DZ / DZD): Algerian Dinar (Bank of Algeria)
2. Egypt (EG / EGP): Egyptian Pound (Central Bank of Egypt)
3. Libya (LY / LYD): Libyan Dinar (Central Bank of Libya)
4. Morocco (MA / MAD): Moroccan Dirham (Bank Al-Maghrib)
5. Sudan (SD / SDG): Sudanese Pound (Central Bank of Sudan)
6. Tunisia (TN / TND): Tunisian Dinar (Central Bank of Tunisia)

Working on this batch now.

[MrNyamu]

I would like to claim the remaining African cash channels, covering Eastern, Middle and Western Africa:

Eastern Africa

1. Comoros (KM / KMF): Comorian Franc (Central Bank of the Comoros)
2. Djibouti (DJ / DJF): Djiboutian Franc (Central Bank of Djibouti)
3. Eritrea (ER / ERN): Eritrean Nakfa (Bank of Eritrea)
4. Madagascar (MG / MGA): Malagasy Ariary (Central Bank of Madagascar)
5. Mayotte (YT / EUR): Euro (European Central Bank)
6. Réunion (RE / EUR): Euro (European Central Bank)
7. Seychelles (SC / SCR): Seychelles Rupee (Central Bank of Seychelles)
8. Somalia (SO / SOS): Somali Shilling (Central Bank of Somalia)
9. Zimbabwe (ZW / ZWG): Zimbabwe Gold (Reserve Bank of Zimbabwe)

Middle Africa

1. Cameroon (CM / XAF): Central African CFA Franc (BEAC)
2. Central African Republic (CF / XAF): Central African CFA Franc (BEAC)
3. Chad (TD / XAF): Central African CFA Franc (BEAC)
4. Congo (CG / XAF): Central African CFA Franc (BEAC)
5. DR Congo (CD / CDF): Congolese Franc (Central Bank of the Congo)
6. Equatorial Guinea (GQ / XAF): Central African CFA Franc (BEAC)
7. Gabon (GA / XAF): Central African CFA Franc (BEAC)
8. São Tomé and Príncipe (ST / STN): Dobra (Central Bank of São Tomé and Príncipe)

Western Africa

1. Benin (BJ / XOF): West African CFA Franc (BCEAO)
2. Burkina Faso (BF / XOF): West African CFA Franc (BCEAO)
3. Cabo Verde (CV / CVE): Cape Verdean Escudo (Bank of Cabo Verde)
4. Côte d'Ivoire (CI / XOF): West African CFA Franc (BCEAO)
5. Gambia (GM / GMD): Gambian Dalasi (Central Bank of The Gambia)
6. Ghana (GH / GHS): Ghana Cedi (Bank of Ghana)
7. Guinea (GN / GNF): Guinean Franc (Central Bank of the Republic of Guinea)
8. Guinea-Bissau (GW / XOF): West African CFA Franc (BCEAO)
9. Liberia (LR / LRD): Liberian Dollar (Central Bank of Liberia)
10. Mali (ML / XOF): West African CFA Franc (BCEAO)
11. Mauritania (MR / MRU): Mauritanian Ouguiya (Central Bank of Mauritania)
12. Niger (NE / XOF): West African CFA Franc (BCEAO)
13. Saint Helena (SH / SHP): Saint Helena Pound (Saint Helena Government)
14. Senegal (SN / XOF): West African CFA Franc (BCEAO)
15. Sierra Leone (SL / SLE): Leone (Bank of Sierra Leone)
16. Togo (TG / XOF): West African CFA Franc (BCEAO)

[altradits]

African Secondary / Parallel USD Cash Channels Claim & Research Matrix (as of Sep 2026)

Following the completion of single-currency cash channels in #32 and the multi-currency convention established in #33, I would like to claim the documented secondary legal tender cash currencies (USD) in Africa:

---

In-Scope Multi-Currency African Markets

1. Zimbabwe (ZW)

• Primary Cash: Zimbabwe Gold (ZWG / cash_zw_zwg)
• Secondary Legal Tender: United States Dollar (USD / cash_zw_usd)
• Authoritative Basis: Reserve Bank of Zimbabwe — Under Statutory Instrument 218 of 2023, Zimbabwe's multi-currency regime is legally extended through December 2030, establishing US Dollar banknotes as official legal tender circulating alongside the national currency for all physical cash payments.

2. Liberia (LR)

• Primary Cash: Liberian Dollar (LRD / cash_lr_lrd)
• Secondary Legal Tender: United States Dollar (USD / cash_lr_usd)
• Authoritative Basis: Central Bank of Liberia — Section 19 of the Central Bank of Liberia Act explicitly mandates a dual-currency legal tender regime where physical US Dollar banknotes circulate freely alongside Liberian Dollar notes for everyday retail and domestic settlement.

3. Somalia (SO)

• Primary Cash: Somali Shilling (SOS / cash_so_sos)
• Secondary Legal Tender: United States Dollar (USD / cash_so_usd)
• Authoritative Basis: Central Bank of Somalia — The Central Bank of Somalia's monetary framework and economic reports document an official dual-currency physical cash system where US Dollar banknotes circulate as legal payment tender alongside the Somali Shilling for domestic trade.

---

Implementation Details

• Uses the src/channels/<country>/cash_<currency>.ts layout convention established in feat(channels): add CMA parallel cash channels for Lesotho, Namibia, and Eswatini #33:
  • src/channels/zw/cash_zwg.ts and src/channels/zw/cash_usd.ts
  • src/channels/lr/cash_lrd.ts and src/channels/lr/cash_usd.ts
  • src/channels/so/cash_sos.ts and src/channels/so/cash_usd.ts
• Uses createCashPaymentChannel (schema version 2, automation: none, no collection fields).
• Preserves existing channel IDs (cash_zw_zwg, cash_lr_lrd, cash_so_sos) and adds additive exports for cash_zw_usd, cash_lr_usd, and cash_so_usd.
• Adds regression and discovery contract tests asserting dual cash resolution for ZW, LR, and SO.

Working on this batch now.

[altradits]

Submitted implementation in #35 with contract tests and full verification suite passing.

[altradits]

Claim: British Indian Ocean Territory & French Southern Territories (UN M49: 014 Eastern Africa) Cash Channels

To complete 100% full territory coverage under the United Nations M49 Africa boundary (Region 002, Sub-region Eastern Africa 014) for Issue #21, I would like to claim the remaining two ISO 3166-1 territories:

1. British Indian Ocean Territory (IO / USD): United States Dollar
2. French Southern Territories (TF / EUR): Euro

Starting implementation now.

[altradits]

Opened PR #52 to complete cash channel coverage for the remaining two ISO 3166-1 territories in the UN M49 Africa boundary (Region 002, Sub-region Eastern Africa 014):

• British Indian Ocean Territory (IO / USD): United States Dollar (cash_io_usd)
• French Southern Territories (TF / EUR): Euro (cash_tf_eur)

With PR #52, all 60 ISO 3166-1 entities within the UN M49 Africa region (54 sovereign nations and 6 non-sovereign territories: EH, YT, RE, SH, IO, TF) have market-qualified physical cash channel schemas.