Monetary System

The Shamwari Monetary System (nxt.ms / ShamwariPay) is a protocol-native framework for creating, issuing, controlling, and exchanging custom digital currencies directly on the blockchain ledger.

By executing monetary primitives natively within the core runtime—rather than through virtual machine smart contracts—Shamwari eliminates VM execution risks, reentrancy vulnerabilities, and gas-fee friction while delivering high-throughput compliance controls, velocity limits, bulk payment processing, time-locked commitments, and atomic cross-currency trading across BetaChains.

---

Core Capabilities & Architecture

• Protocol-Native Execution: Currency operations run directly inside nxt.ms, removing VM overhead and gas dependencies.
• Bitmask Programmability: Currencies inherit composite capabilities via bitmask flags (EXCHANGEABLE, CONTROLLABLE, MINTABLE, NON_SHUFFLEABLE, SOVEREIGN, PRIVATE).
• Sovereign Fee Settlement: Built-in support for chain-native fee-settlement tokens (SOVEREIGN) tied directly to sovereign BetaChains (e.g., domestic fiat stablecoins or central bank digital currencies).
• Issuer Velocity Controls: Real-time per-transaction (transactionLimitQNT) and daily total limits (dailyLimitQNT) to prevent capital flight and protect account security.
• Batched Payment Settlement: Efficient multi-recipient settlement via CurrencyBulkPayment with automatic tax aggregation and proportional fee allocation.
• Immutable Tax Audit Ledger: Protocol-enforced tax deductions recorded in an append-only audit table (CurrencyTaxRecord) linked directly to transaction hashes and tax collector accounts.
• Goal & Time-Locked Financial Products: Native primitives for goal-based accumulation (CurrencySavings) and block-height time-locked commitments (VaultCurrency).
• Supply Burning & Cash Redemptions: Permanent unit destruction via CurrencyWithdraw for cash redemption or off-chain asset balancing.
• On-Chain Order-Book Exchange: Decentralized currency-to-currency trading pairs processed by ExchangeHome and ExchangeOfferHome.
• Granular Account Guardrails: Enforces compliance checks based on recipient account classifications (e.g., restricting payments to SAVINGS or AUTONOMOUS AI agent accounts).

---

Currency Types & Bitmask Capabilities

Currencies derive operational behavior from a composite bitmask constructed from nxt.ms.CurrencyType flag values:

Flag	Value	Enum	Description
EXCHANGEABLE	0x01	CurrencyType.EXCHANGEABLE	Enables open order-book trading against other EXCHANGEABLE currencies.
CONTROLLABLE	0x02	CurrencyType.CONTROLLABLE	Permits the issuer to set dynamic per-transaction and daily transfer caps.
MINTABLE	0x04	CurrencyType.MINTABLE	Allows additional supply generation up to maxSupplyQNT using proof-of-work hash functions.
NON_SHUFFLEABLE	0x08	CurrencyType.NON_SHUFFLEABLE	Prohibits inclusion in privacy coin-shuffling operations to maintain strict regulatory auditability.
SOVEREIGN	0x10	CurrencyType.SOVEREIGN	Permanently binds the currency as the primary fee-settlement token for a BetaChain. Cannot be deleted or shuffled.
PRIVATE	0x20	CurrencyType.PRIVATE	Restricts transfers, exchange offers, and dividend distributions to involve or be routed through the issuer account.

---

Data Model & Relational Schema

Currency metadata, supply changes, velocity parameters, transaction logs, and immutable tax records are maintained in versioned relational database tables indexed by block height and full transaction hashes.

1. Primary Currency & Protocol Entities

Table	Primary / Composite Key	Entity Class	Description
public.currency	id	Currency	Master currency definitions, decimals, minting parameters, and issuer settings.
public.currency_supply	id, height	CurrencySupply	Versioned record tracking dynamic circulating supply for minting and withdrawals.
public.currency_control	id, height	CurrencyControl	Mutable per-transaction and 24-hour daily velocity limits.
public.currency_transfer	full_hash, id	CurrencyTransfer	Peer-to-peer transfers with associated tax units ($QNT$).
public.currency_payment	full_hash, id	CurrencyPayment	Direct merchant and business institutional payment entries.
public.currency_bulk_payment	full_hash, recipient_id	CurrencyBulkPayment	Multi-recipient batched payment entries sharing a single transaction hash.
public.currency_savings	full_hash, id	CurrencySavings	Goal-based savings deposits removed from liquid balances.
public.vault_currency	full_hash, id	VaultCurrency	Time-locked commitments scheduled for block-height release.
public.currency_withdraw	full_hash, id	CurrencyWithdraw	Supply destruction / cash redemption records.
public.currency_tax_record	transaction_full_hash, transaction_id	CurrencyTaxRecord	Immutable, append-only tax audit trail for protocol revenue collection.

2. Primary Currency Record (public.currency)

Field	Type	Description
id	long	Transaction ID of initial currency issuance (globally unique handle).
issuerId	long	Account ID of the issuing authority.
chain	BetaChain	Target BetaChain context hosting the currency.
name	String	Full currency identifier (min $3$ characters).
code	String	Ticker symbol (3–10 uppercase ASCII characters).
type	int	Bitmask combination of CurrencyType codes.
initialSupplyQNT	long	Initial supply minted at issuance in atomic units ($QNT$).
maxSupplyQNT	long	Hard upper bound on total supply in atomic units ($QNT$).
decimals	byte	Decimal resolution ($0$ to $8$ places, where $1 \text{ Unit} = 10^{\text{decimals}} \text{ QNT}$).
algorithm	byte	Hash function ID used if MINTABLE (e.g., SHA-256, SHA3-256).
minDifficulty	byte	Minimum proof-of-work mining difficulty ($1$ to $255$).
maxDifficulty	byte	Maximum proof-of-work mining difficulty ($1$ to $255$).
whitelistProperty	String	Optional account property key required for non-issuers to hold or transfer units.
isDeleted	boolean	Flag set when a currency is purged from active circulation.

3. Dynamic Supply Formula

For MINTABLE and burnable currencies, the circulating supply is updated dynamically during block execution:

$\text{Current Supply } (QNT) = \text{initialSupplyQNT} + \sum \text{MintedQNT} - \sum \text{WithdrawnQNT}$

---

Currency Lifecycle & Operations

                   ┌──────────────────────────────────────┐
                   │    betaChainCurrency() / Issuance    │
                   └──────────────────┬───────────────────┘
                                      │
                                      ▼
                        ┌───────────────────────────┐
                        │      Active Currency      │
                        │   (is_deleted == false)   │
                        └─────┬───────────┬───┬─────┘
                              │           │   │
           Minting (PoW)      │           │   │  Velocity Limits
           & Supply Adjust    │           │   │  (CONTROLLABLE)
                              ▼           │   ▼
                        ┌───────────┐     │ ┌───────────────────┐
                        │ Dynamic   │     │ │ Transaction/Daily │
                        │  Supply   │     │ │  Cap Enforcement  │
                        └───────────┘     │ └───────────────────┘
                              │           │
           Redemption/Burn    │           │  Issuer Purge
           (CurrencyWithdraw) │           │  (Prohibited if SOVEREIGN)
                              ▼           ▼
                        ┌───────────┐ ┌───────────┐
                        │ Supply    │ │ Deleted   │
                        │ Burned    │ │ (is_del)  │
                        └───────────┘ └───────────┘

1. Issuance & Sovereign Currency Registration

A standard currency is created using a CURRENCY_ISSUANCE transaction, specifying the bitmask flags, supply parameters, and decimal precision.

For sovereign BetaChains, fee currencies are initialized programmatically at genesis or fork activation via Currency.betaChainCurrency():

// Registering a sovereign fiat currency for a regional BetaChain
Currency.betaChainCurrency(
    betaChain,           // Target BetaChain instance
    currencyId,          // Static numeric ID
    issuerAccountId,     // Central Bank / Authority Account ID
    "Zimbabwe Gold",     // Full Name
    "ZWG",               // Code / Ticker
    "Sovereign Reserve Currency", 
    CurrencyType.SOVEREIGN.getCode(), // SOVEREIGN bitmask forced internally
    100_000_000_000L,    // Initial Supply QNT
    1_000_000_000_000L,  // Max Supply QNT
    (byte) 0,            // Algorithm (0 = None)
    (byte) 2             // Decimals (2 decimal places)
);

2. Batched Bulk Payments (CurrencyBulkPayment)

To optimize payroll, disbursement, and dividend workflows, Shamwari supports multi-recipient transactions. A single CURRENCY_BULK_PAYMENT transaction expands into individual recipient payment logs while executing unified tax deduction logic:

• Row Key Uniqueness: Rows in public.currency_bulk_payment are keyed by (full_hash, recipient_id).
• Proportional Tax Calculation: The total transaction tax ($T_{\text{total}}$) is calculated on aggregate volume, stored in full on the first recipient entry (tax_units), and proportionally calculated per recipient entry:

$\text{taxUnitsQNT}_i = \left\lfloor \frac{\text{unitsQNT}_i}{\text{totalUnitsQNT}} \times T_{\text{total}} \right\rfloor$

• Event Notification: Emits CurrencyBulkPayment.Event.BULK_PAYMENT upon commit.

3. Supply Redemptions & Burning (CurrencyWithdraw)

When currency holders redeem digital tokens for physical fiat or bank deposits, the tokens are permanently destroyed rather than transferred to a reserve account:

// Security validation prior to executing withdrawal/burn logic
SecurityManager sm = System.getSecurityManager();
if (sm != null) {
    sm.checkPermission(new BlockchainPermission("withdrawCurrency"));
}

• Supply Impact: Reduces circulating supply in public.currency_supply without altering maxSupplyQNT.
• Record Persistence: Recorded in public.currency_withdraw and triggers CurrencyWithdraw.Event.CURRENCY_WITHDRAWAL.

4. Deletion Rules

A currency can be purged using a CURRENCY_DELETION transaction if and only if:

1. isSovereign() == false (Sovereign fee currencies can never be deleted).
2. The sender account holds $100\%$ of the active circulating supply ($QNT$).

---

Velocity Controls & Compliance Safeguards

Daily and Per-Transaction Limits

When transferring a CONTROLLABLE currency, the protocol enforces velocity guardrails prior to executing ledger balance updates:

$\text{TransferUnits} \le \text{transactionLimitQNT}$

$\text{DailySpent} + \text{TransferUnits} \le \text{dailyLimitQNT}$

If a non-corporate account attempts a transfer exceeding these bounds, CurrencyType.CONTROLLABLE.validate() rejects the transaction with a NotValidException.

// Adjusting velocity limits (Issuer only)
Currency.changeTransactionLimits(
    currencyId, 
    newTransactionLimitQNT, 
    newDailyLimitQNT
);

Account Type Restrictions

To protect institutional and retail workflows, CURRENCY_PAYMENT transactions enforce strict destination account filtering:

• Prohibited Destinations: Payments cannot be sent directly to NONE, AUTONOMOUS (uncontrolled AI agent), or PERSONAL default accounts without explicit merchant capability.
• Savings Guard: Accounts typed as SAVINGS can only receive currency payments originating from verified BUSINESS accounts.

---

Immutable Tax Architecture (CurrencyTaxRecord)

Shamwari incorporates an automated, append-only fiscal tax collection framework managed by CurrencyTaxRecord. Tax is deducted directly during settlement of transfers, payments, exchange trades, and loan repayments.

       ┌────────────────────────────────────────────────────────┐
       │ Taxable Event (Transfer / Payment / Trade / Repayment)  │
       └───────────────────────────┬────────────────────────────┘
                                   │
                                   ▼
       ┌────────────────────────────────────────────────────────┐
       │   CurrencyTaxRecord.creditTaxAccount(transactionId,   │
       │     fullHash, event, payerId, taxAccountId, units)     │
       └───────────────────────────┬────────────────────────────┘
                                   │
                                   ▼
       ┌────────────────────────────────────────────────────────┐
       │  1. Credit taxAccountId balance via AccountLedger       │
       │  2. INSERT/MERGE into public.currency_tax_record       │
       │  3. Fire Event.TAX_COLLECTED listener                  │
       └────────────────────────────────────────────────────────┘

Persistence and Audit Trail

• Primary Key: (transaction_full_hash, transaction_id).
• SQL Persistence: Uses atomic merge operations to guarantee idempotency and prevent duplicate tax credits:

  MERGE INTO currency_tax_record 
  (transaction_id, transaction_full_hash, currency_id, payer_id, tax_collector_id, units, timestamp, height, latest) 
  KEY (transaction_full_hash, transaction_id) 
  VALUES (?, ?, ?, ?, ?, ?, ?, ?, TRUE)

• Append-Only Integrity: Tax records can never be deleted, updated, or rolled back by issuers or node operators.

---

Time-Locks and Goal-Based Accumulation

Goal-Based Savings (CurrencySavings)

Allows accounts to lock units into designated goal targets tracked in public.currency_savings. Locked funds are isolated from liquid currency balances until goal criteria are satisfied. Emits CurrencySavings.Event.SAVINGS.

Time-Locked Vaults (VaultCurrency)

Provides native programmatic timelocks. Deposited units are recorded in public.vault_currency and remain locked in account_currency_vault until the target block height is reached:

$\text{IsReleased}(\text{height}) = \begin{cases} \text{true} & \text{if } \text{currentHeight} \ge \text{releaseHeight} \\ \text{false} & \text{otherwise} \end{cases}$

Vault releases are processed automatically in the core ledger's AFTER_BLOCK_APPLY phase without requiring user-initiated unlock transactions. Emits VaultCurrency.Event.VAULT.

---

Order-Book Decentralized Exchange (ExchangeHome)

Currencies flagged as EXCHANGEABLE can be traded peer-to-peer on the native order-book engine managed by ExchangeHome and ExchangeOfferHome.

                    ┌──────────────────────────────────┐
                    │     publishExchangeOffer()       │
                    │  (BUY / SELL Offer Created)      │
                    └────────────────┬─────────────────┘
                                     │
                                     ▼
                    ┌──────────────────────────────────┐
                    │       Order Matching Engine      │
                    │  (Rate & Quantity Validation)    │
                    └────────────────┬─────────────────┘
                                     │
                                     ▼
                    ┌──────────────────────────────────┐
                    │      Atomic Exchange Executed    │
                    │   Seller Units <──> Buyer Base   │
                    └──────────────────────────────────┘

Pair Validation

To execute an order or publish an exchange offer, both the base currency and quote currency must satisfy:

$\text{IsExchangeable}(C_{\text{target}}) \land \text{IsExchangeable}(C_{\text{base}}) = \text{True}$

Atomic Settlement

When a buy or sell offer matches an incoming offer:

1. ExchangeOfferHome validates balance availability.
2. Units are transferred atomically between seller and buyer accounts.
3. Applicable network taxes ($\text{taxQNT}$) are calculated via TaxCalculator, recorded in CurrencyTaxRecord, and processed in the same block execution phase.
4. An immutable Exchange event record is logged to the child-chain schema (public.exchange).

---

Event Listener Matrix

The Monetary System exposes strongly-typed event listeners across all entity classes to support real-time indexers, analytics, and external service hooks:

Entity Class	Event Enum	Listener Trigger
CurrencyTransfer	Event.TRANSFER	Single peer-to-peer unit transfer processed.
CurrencyPayment	Event.PAYMENT	Institutional or business payment completed.
CurrencyBulkPayment	Event.BULK_PAYMENT	Batched multi-recipient payment executed.
CurrencySavings	Event.SAVINGS	Goal-based deposit logged into savings bucket.
VaultCurrency	Event.VAULT	Time-locked vault commitment established.
CurrencyWithdraw	Event.CURRENCY_WITHDRAWAL	Units permanently burned / withdrawn from circulation.
CurrencyTaxRecord	Event.TAX_COLLECTED	Tax deduction credited to designated governance tax collector account.

---

Related APIs

API	Description
IssueCurrency	Create new currency
DeleteCurrency	Delete currency
AdjustCurrencyLimits	Set velocity limits
TransferCurrency	Transfer currency
CurrencyBulkPayment	Batched payments
CurrencyPayment	Single payment
CurrencySavings	Goal-based savings
VaultCurrency	Time-locked vaults
CurrencyWithdraw	Burn/redeem currency
PublishExchangeOffer	Post exchange offer
LendCurrency	Lend currency
LoanApplication	Create loan application
LoanRepayment	Repay loan
RescueLoan	Rescue defaulted loan

Institutional & Regional Use Cases

• Central Bank Digital Currencies (CBDC): Central monetary authorities issue SOVEREIGN currencies bound to dedicated BetaChains, guaranteeing zero-gas end-user transactions and instant settlement.
• Automated Tax Collection: Revenue authorities configure chain-level tax collector accounts, receiving verifiable receipts logged continuously in public.currency_tax_record.
• Targeted Social Subsidies: Governments deploy PRIVATE + CONTROLLABLE currencies with whitelist restrictions, ensuring subsidy funds can only be spent at approved food and agricultural merchants.
• Cross-Border Trade Liquidity Pools: Financial service providers (FSPs) run order-book trading pairs between regional stablecoins (ZWG, ZAR, KES, BRL) to reduce FX trade settlement latency across emerging markets.