REGULATORY PRIMITIVES

Compliance
by Design

On general-purpose chains, compliance is a front-end filter that application code can bypass. On Shamwari, regulatory status is a consensus primitive — enforced by every node, every block, for every transaction. There is no configuration, no middleware, and no operator that can circumvent it.

TOTEMAPPROVAL 13 TAX TYPES KYC AT CONSENSUS JURISDICTION CHAINS IMMUTABLE AUDIT AML CONTROLS
6
TotemApproval regulatory states
5
Embedded authority types per jurisdiction chain
13
Programmable tax rate types
0
Smart contracts — all compliance at protocol layer
01
ASSET COMPLIANCE
TotemApproval — the regulatory primitive

The TotemApproval system implements a full securities-regulator workflow as first-class protocol primitives. Regulators interact directly with the blockchain through signed transactions. Every state transition is atomic, immutable, and independently verifiable by any counterparty in real time.

PENDING
Issuer submits TOTEM_ISSUANCE. On-chain but not tradeable. Awaits regulator action.
UNDER_REVIEW
Regulator actively reviewing issuer documentation and legal structure.
APPROVED
Asset listed and tradeable. Transfers enabled. May carry an expirationHeight requiring re-approval.
SUSPENDED
All transfers rejected at protocol level. Reversible — regulator can reinstate.
COMPLIANCE_HOLD
Investigation mode. Asset frozen without permanent revocation. Preserves issuer recourse.
REJECTED
Permanent denial. Asset cannot be listed on this chain. Permanently recorded on-chain.

  Each state transition requires a signed consensus transaction from the designated Securities Regulator authority account. The chain of transitions constitutes a court-admissible, tamper-proof regulatory audit record.

HOW IT WORKS
Regulator is the gatekeeper
The Securities Regulator account is hardcoded at chain genesis. Only this account can execute TotemApproval state transitions. No application operator — and no other chain participant — can change the approval status of any asset, regardless of what front-end software they run.
Transfer validation at every node
When a TOTEM_TRANSFER is submitted, every validating node independently checks the asset's current approval status. A SUSPENDED or REJECTED totem transfer is rejected at the attachment validation gate — before it ever enters the mempool. There is no way to transfer a suspended asset.
Expiring approvals
Approvals can carry an expirationHeight. When the chain reaches that block, the AFTER_BLOCK_APPLY handler automatically transitions the asset to PENDING — requiring the issuer to seek re-approval. This enforces periodic regulatory review without manual regulator intervention.
TotemHistory — full provenance
Every supply change, transfer, dividend, and approval event is recorded in the immutable TotemHistory table. A complete provenance record for every unit of every asset exists from issuance to present holder — queryable at any past block height without replaying transactions.
TRANSACTION TYPE DETAIL

TOTEM_APPROVAL Transaction

A single transaction type handles all approval state transitions. The attachment encodes the target state and an optional expiration height. Only transactions signed by the designated Securities Regulator account ID are accepted — validated at consensus before processing.

  • Sender must be Securities Regulator account (validated at consensus)
  • Target state: UNDER_REVIEW, APPROVED, SUSPENDED, COMPLIANCE_HOLD, or REJECTED
  • APPROVED state may include expirationHeight for periodic re-approval
  • All transitions create immutable TotemApproval record in blockchain state

Capital Gains Tax at Execution

When an APPROVED totem is traded and the transaction executes, capital gains tax is automatically calculated and withheld in the same atomic operation. The tax is credited to the Tax Collector account before net proceeds reach the seller.

  • CGT rate: 0–3500 basis points, set by Tax Collector authority
  • Formula: (saleAmount × rateBps) / 10,000
  • Withheld atomically at trade execution — cannot be separated
  • Permanent CurrencyTaxRecord created per collection event
02
EMBEDDED AUTHORITIES
Five regulatory authorities embedded at genesis. Immutable.

Every jurisdiction BetaChain is created with five designated regulatory authority accounts embedded in the genesis block. Their account IDs are hardcoded into the chain configuration and validated at the consensus layer. No transaction, no admin, and no upgrade can change them after genesis.

IMMUTABLE AT GENESIS
MONETARY AUTHORITY
Central Bank
The Central Bank authority account is the sole issuer of CBDC on the jurisdiction chain. It controls currency issuance parameters, reserve requirements, and monetary policy settings. The only account that can exercise the CONTROLLABLE currency type veto — blocking any individual transfer that violates monetary policy.
CURRENCY_ISSUANCETRANSFER VETOSUPPLY MANAGEMENTRESERVE CONTROLMINTABLE CURRENCY
IMMUTABLE AT GENESIS
SECURITIES AUTHORITY
Securities Regulator
Controls the entire TotemApproval lifecycle for every digital asset on the chain. Only the Securities Regulator account can approve, suspend, or permanently reject a Totem asset. All 6 state transitions require a transaction signed by this account — protocol-enforced, no bypass possible.
TOTEM_APPROVALSUSPENSIONCOMPLIANCE_HOLDPERMANENT REJECTIONEXPIRY CONTROL
IMMUTABLE AT GENESIS
PRUDENTIAL AUTHORITY
Insurance Regulator
Approves insurance products before they can accept applications. Initiates suspension and delisting of products that fail solvency requirements. When an insurer is delisted, this account's action triggers automatic reserve redistribution to policyholders — without court proceedings.
INSURANCE_APPROVALSUSPENSIONDELISTINGREDISTRIBUTION TRIGGERSOLVENCY ENFORCEMENT
IMMUTABLE AT GENESIS
REVENUE AUTHORITY
Tax Collector
The designated Tax Collector account receives automatic tax withholding from every taxable transaction on the chain. Up to 13 tax rate types configured via a single SET_TAX_RATES transaction. The protocol withholds tax at source — atomically with the transaction — before any net proceeds flow.
SET_TAX_RATES13 RATE TYPESWITHHOLDING AT SOURCEREAL-TIME COLLECTIONAUDIT RECORDS
IMMUTABLE AT GENESIS
ACCESS AUTHORITY
Permission Master Admin
Controls the entire 6-level permission hierarchy. Grants and revokes CHAIN_ADMIN status, which manages CHAIN_USER (KYC-approved) participant accounts. Cascading revocation ensures revoking a CHAIN_ADMIN automatically invalidates every permission they granted — no orphaned access possible.
GRANT_PERMISSIONREVOKE_PERMISSIONCHAIN_ADMIN MGMTCASCADING REVOCATIONBLOCKED_USER
PROTOCOL PROPERTY
INTEGRITY GUARANTEE
Immutable Audit Trail
Every regulatory action creates a permanent, timestamped, cryptographically-signed record in the blockchain state. Approval decisions, suspension orders, tax collections, and permission grants are all part of the chain's immutable history — independently verifiable by any node operator without requiring operator cooperation.
BLOCKCHAIN NATIVEDILITHIUM-SIGNEDCOURT-ADMISSIBLEINDEPENDENTLY VERIFIABLE
THE IMMUTABILITY GUARANTEE
All five authority account IDs are written into the chain's genesis block as immutable configuration parameters. There is no administrative transaction that can change them after deployment. The Shamwari network operator cannot replace a nation's Central Bank, reassign the Securities Regulator, or redirect tax collection to a different account. This is not policy — it is structural.
03
KNOW YOUR CUSTOMER & ANTI-MONEY LAUNDERING
KYC and AML enforced at the consensus layer

Shamwari embeds KYC and AML controls directly into the transaction validation pipeline. No application-layer middleware, no operator-dependent enforcement. Permission status is blockchain state — consistent, permanent, and independently verifiable by any node.

KYC-Gated Access
Permissioned chains require CHAIN_USER status for all transactions. Only CHAIN_ADMIN-approved accounts can transact after the policy switch height. Enforced at gate 3 of the 7-gate consensus pipeline.
CONTROLLABLE Currency
CBDC and AML-regulated currencies can have individual transfers vetoed by the Central Bank authority account before confirmation — structural transfer-blocking without chain-wide impact.
Encrypted KYC On-Chain
KYC documentation references are Kyber-encrypted and stored permanently in each BetaChainPermission record. Ciphertext on-chain, readable only by the granting institution's custody system.
NON_SHUFFLEABLE Currency
CBDC currencies can be marked NON_SHUFFLEABLE — preventing use in mixing operations at attachment validation. Traceability structurally guaranteed by the currency type bitmask.
KYC ONBOARDING FLOW
1
Off-chain KYC Verification
CHAIN_ADMIN conducts KYC/AML checks through their standard processes — identity documents, PEP screening, sanctions checks. Off-chain procedures, on-chain record.
2
Encrypted Permission Record
CHAIN_ADMIN submits GRANT_PERMISSION with an EncryptedData payload — Kyber-encrypted blob referencing KYC documentation identifiers and compliance attestation hashes.
GRANT_PERMISSION tx + EncryptedData payload
3
CHAIN_USER Permission Active
From the next block onwards, the account holds CHAIN_USER status. Every transaction validation checks this in real-time. No caching, no eventual consistency — permission state is blockchain state.
PermissionPolicy.check(sender) → CHAIN_USER ✓
4
Ongoing Monitoring
CHAIN_ADMIN can apply BLOCKED_CHAIN_USER at any time — effective at the next block. The original CHAIN_USER grant record is preserved in the versioned permission table for regulatory audit.
BLOCKED_CHAIN_USER → instant freeze
5
Cascading Revocation
If a CHAIN_ADMIN is removed, every permission they granted is automatically revoked from the specified height. No manual cleanup — the protocol enforces referential integrity across the entire hierarchy.
REVOKE_PERMISSION → cascades to all granted users
AML CURRENCY CONTROLS
CONTROLLABLE Currency Type
Any currency issued with the CONTROLLABLE bitmask flag enables transfer-veto by the issuer. The Central Bank can block any specific transfer before it is confirmed. This enables AML freeze orders, sanctions compliance, and targeted asset restraint without chain-wide impact.
NON_SHUFFLEABLE Flag
Setting this bit on a CBDC currency structurally prevents its use in mixing operations. The protocol rejects SHUFFLING_CREATION transactions that reference NON_SHUFFLEABLE currencies at attachment validation — before the transaction reaches the mempool.
Account Type Restrictions
CURRENCY_PAYMENT transactions — the primary CBDC payment mechanism — are restricted to SAVINGS-type recipients by default. This ensures retail CBDC flows only to verified consumer accounts without additional middleware.
BLOCKED_CHAIN_USER for Sanctions
The BLOCKED_CHAIN_USER permission type is a positive denial — it hard-blocks a CHAIN_USER even if the CHAIN_USER grant is also present. Targeted sanctions enforcement with immediate effect, while preserving the full historical permission record for compliance.
PERMISSION HIERARCHY
MASTER_ADMIN
Root authority. Hardcoded at genesis. Cannot be changed.
CHAIN_BINDER
Transaction processor. Granted by MASTER_ADMIN only.
CHAIN_ADMIN
KYC operator. Grants CHAIN_USER after verification.
CHAIN_USER
KYC-approved participant. Required post-policy switch.
BLOCKED_CHAIN_USER
Positive sanction. Overrides CHAIN_USER. Full audit history preserved.
04
PROGRAMMABLE TAXATION
13 tax rate types. Zero evasion. Atomic withholding.

Shamwari's on-chain taxation is the most comprehensive protocol-native tax system deployed on any blockchain. Tax is withheld at source, atomically with the triggering transaction, credited to the designated Tax Collector account — without off-chain reporting, operator cooperation, or periodic reconciliation.

TRANSACTION
0–3500 bps
General levy on all transfers
VALUE ADDED
0–3500 bps
Goods & services transactions
CAPITAL GAINS
0–3500 bps
Asset sales on the DEX
SALES TAX
0–3500 bps
Store purchase transactions
INSURANCE LEVY
0–3500 bps
Policy application events
CURRENCY TRANSFER
0–3500 bps
Payments & lending flows
LOAN INTEREST
0–3500 bps
Withholding at loan repayment
SUBSCRIPTION
0–3500 bps
Recurring billing cycles
EXCHANGE / FX
0–3500 bps
Foreign exchange operations
TOTEM ISSUANCE
0–3500 bps
Digital asset stamp duty
DIVIDEND
0–3500 bps
Dividend withholding tax
STORE REFUND
0–3500 bps
Refund transaction levy
INSURANCE PREMIUM
0–3500 bps
Premium payment levy

Basis-Point Precision with Threshold Control

Every tax rate is configured in basis points (1 bps = 0.01%). Formula: taxAmount = (amount × rateBps) / 10,000 using integer arithmetic — no floating-point rounding errors. Each rate type supports independent minimum and maximum taxable thresholds.

  • Zero-rate disables a tax type without removing the configuration record
  • Multi-tax transactions: each applicable type calculated independently — no compounding
  • Up to 13 rate entries updated in a single atomic SET_TAX_RATES transaction
  • Per-collection audit receipt via computeTaxBreakdown()

Withholding-at-Source

LOAN_INTEREST_TAX and DIVIDEND_WITHHOLDING_TAX implement structural tax evasion prevention. Tax is deducted before income reaches the recipient — at the same moment the underlying transaction executes.

  • Loan interest tax withheld at each LOAN_REPAYMENT transaction
  • Dividend withholding applied at DIVIDEND_PAYMENT execution
  • Capital gains withheld atomically at DEX trade execution
  • All withholding events create immutable CurrencyTaxRecord
TAX COLLECTOR SYSTEM
Embedded Tax Collector Account
Each jurisdiction chain has a dedicated Tax Collector account set at genesis. Every taxable transaction credits withheld tax directly in real time. The Tax Collector balance is the live, auditable record of all tax revenues — no reconciliation with external systems required.
Immutable CurrencyTaxRecord
Every tax collection event writes a permanent CurrencyTaxRecord: originating transaction hash, taxpayer account, Tax Collector account, currency, and amount withheld. Part of the immutable blockchain state — admissible as a primary tax collection record by revenue authorities.
Real-Time Regulatory Reporting
TaxPolicy.toJSON() returns a machine-readable snapshot of all 13 configured rates with effective block heights. Regulators query independently at any time to verify rates — no operator cooperation required.
Structural Tax Evasion Prevention
Tax collection is enforced at gate 5 (attachment validation) of the 7-gate consensus pipeline — before balance changes occur. A transaction resulting in underpayment is rejected by every node. No race condition, no replay attack, no bypass through direct API submission.
05
INSURANCE REGULATION
Protocol-enforced solvency and consumer protection

Shamwari's insurance compliance system implements actuarial solvency requirements and policyholder protection at the consensus layer. When an insurer fails, policyholders are protected automatically — without court proceedings, liquidators, or regulatory intervention delays.

9-STATE COMPLIANCE LIFECYCLE
PENDING APPROVAL
Registered on-chain. Awaits Insurance Authority approval.
WAITING
Approved but before effectiveHeight. Not yet active.
ACTIVE
Fully operational. Applications, premiums, and claims permitted.
UNDER REVIEW
Supervisory watch. New applications suspended.
SUSPENDED
Operations halted. 90-day redistribution clock starts.
DELISTED
Immediate cessation. Reserve redistribution at next block.
LAPSED
Expired without renewal. No new transactions.
CANCELLED
Protocol-set after redistribution completes.
EXPIRED
Natural end of policy term reached.

  At DELISTED status, or after 90 days of SUSPENDED status, the AFTER_BLOCK_APPLY handler automatically distributes the actuarial reserve pool to active policyholders — proportional to coverage amount, at the next block. No court order required.

ACTUARIAL RESERVE REQUIREMENTS
Live Loss Ratio Engine
Required reserve computed from actual on-chain payout data every block: reserve = lossRatio × safetyMultiplier × totalCoverage. No static actuarial tables — the reserve requirement reflects real claims experience in real time.
Three Reserve Plan Types
STANDARD (1.2×), PREMIUM (1.5×), and BASIC (1.0×) safety multipliers determine required reserve levels. The protocol automatically blocks new policy issuance when the insurer's actual reserve falls below the required level.
Automatic Policyholder Protection
On DELISTED status: the AFTER_BLOCK_APPLY handler immediately distributes the insurer's reserve pool to all active policyholders at the next block. On 90 days of SUSPENDED: the same redistribution triggers automatically. Policyholders are paid first.
Insurance Authority as Regulator
Only the Insurance Authority account (hardcoded at genesis) can approve products, initiate suspensions, and trigger delisting. This authority also controls redistribution parameters and can override the 90-day clock for emergency consumer protection.
06
JURISDICTION-SPECIFIC COMPLIANCE
Three distinct regulatory regimes. One network.

Each Shamwari BetaChain is a completely isolated regulatory environment with its own compliance configuration, authority accounts, tax rates, and permission policy. A single node serves all three jurisdictions simultaneously — each operating under its own legal framework, enforced independently at the consensus layer.

🇨🇼
ZIMBABWE
ZWG · RESERVE BANK OF ZIMBABWE · IPEC
Reserve Bank of Zimbabwe — CBDC issuance authority
Securities & Exchange Commission — TotemApproval
IPEC (Insurance & Pensions Commission)
ZIMRA (Zimbabwe Revenue Authority) — Tax Collector
Compliance Features Active
ZWG CBDCCONTROLLABLENON_SHUFFLEABLEPermissioned13 tax ratesFull insuranceAML transfer veto
🇿🇦
SOUTH AFRICA
ZAR · SARB · FSCA · SARS
SARB (SA Reserve Bank) — Monetary authority
FSCA (Financial Sector Conduct Authority)
Prudential Authority — Insurance regulation
SARS (SA Revenue Service) — Tax withholding
Compliance Features Active
ZAR digital currencyCONTROLLABLENON_SHUFFLEABLEPermissionedSARS tax ratesTotem ExchangeInsurance marketplace
🌎
CAPITAL
CAPITAL · GLOBAL ASSET CHAIN
Global Securities Regulator — Totem listing approval
Capital Tax Collector — Exchange & issuance taxes
Permission Admin — Developer & institutional access
Certificate Authority — Digital certificate issuance
Compliance Features Active
Open permission policyTotemApprovalDigital certificatesApp StoreExchange taxesDeveloper registry
WHAT EACH JURISDICTION CONTROLS INDEPENDENTLY
  • Its own currency (ZWG, ZAR, or CAPITAL) with independent monetary policy
  • Its own permission policy — open, permissioned, or custom threshold
  • Its own 13 tax rates — set by its own Tax Collector authority account
  • Its own TotemApproval workflow — different assets approved per chain
  • Its own insurance marketplace — independent actuarial reserve requirements
  • Its own KYC/AML onboarding — CHAIN_ADMIN operators per jurisdiction
WHAT ALL JURISDICTIONS SHARE
  • The same proof-of-stake consensus — all blocks confirmed together
  • The same post-quantum cryptography — ML-DSA + ML-KEM across all chains
  • The same 7-gate validation pipeline — identical security guarantees
  • The same Binder Protocol — unified fee abstraction for all users
  • FxtChain settlement layer — cross-jurisdiction finality anchor
  • The same MIT-licensed open-source codebase — auditable by any party
07
IMMUTABLE AUDIT TRAIL
The blockchain is the compliance record

Every regulatory action, tax collection, permission grant, asset approval, insurance state change, and claim event creates a permanent, Dilithium-signed entry in blockchain state. No separate compliance database. No audit trail that depends on operator integrity. The blockchain is the evidence.

Event TypeAuthority AccountRecord CreatedIndependently VerifiableModifiable
TotemApproval state changeSecurities RegulatorTotemApproval entity at blockHeight✓ Any node✗ Never
Tax withholding eventProtocol (automatic)CurrencyTaxRecord per transaction✓ Any node✗ Never
Permission grantCHAIN_ADMINBetaChainPermission + EncryptedData✓ Any node✗ Never
Permission revocationCHAIN_ADMINVersioned revocation at blockHeight✓ Any node✗ Never
Insurance product approvalInsurance AuthorityInsuranceApproval record + timestamp✓ Any node✗ Never
Insurance suspensionInsurance AuthorityStatus change + suspensionHeight✓ Any node✗ Never
Reserve redistributionProtocol (automatic)Redistribution event + per-policyholder credits✓ Any node✗ Never
Insurance claim filingPolicyholderInsuranceClaim with 13-state lifecycle✓ Any node✗ Never
CURRENCY_ISSUANCECentral BankCurrency entity + issuance parameters✓ Any node✗ Never
Tax rate configurationTax CollectorTaxPolicy snapshot + effective blockHeight✓ Any node✗ Never
VERSIONED STATE ARCHITECTURE
Point-in-Time Queries
All compliance state is stored in versioned entity tables keyed by (id, height). Auditors query the approval status of any asset at any specific block height — without replaying transactions. Historical compliance snapshots always available.
Cryptographic Finality
Every block is signed with ML-DSA-2 (Dilithium, NIST FIPS 204). Once confirmed, contents are cryptographically sealed. No block can be modified without invalidating the signature of every subsequent block. The audit trail is not just immutable — it is quantum-resistant.
Independent Verification
Any party — regulator, auditor, counterparty, court — can independently verify any compliance event by running their own node. No need to subpoena the operator or trust any intermediary. The proof is the blockchain itself.
AUDIT CAPABILITIES BY STAKEHOLDER

For Regulators

  • Query current and historical approval status of any listed asset
  • Verify tax collection amounts and rates against legislated levels
  • Review complete permission grant and revocation history per institution
  • Audit insurance reserve levels and redistribution events in real time
  • Run an independent node — no access request to the operator required

For Issuers & Institutions

  • Complete TotemHistory provenance for every unit of every issued asset
  • Full dividend distribution record with per-holder allocations
  • Immutable KYC onboarding timestamps and permission grant records
  • Tax collection receipts via CurrencyTaxRecord per transaction
  • Insurance policy history — applications, claims, payments, and lifecycle events
08
COMPLIANCE COMPARISON
Protocol compliance vs application compliance

On Shamwari, compliance is a property of the consensus engine. On general-purpose chains and traditional systems, compliance is a property of the application — subject to bugs, operator decisions, and the risk of bypass.

TRADITIONAL & SMART CONTRACT APPROACH
Compliance rules in application layer — bypassable with direct API calls
Tax collection by exchange operator — evasion possible without consequences
KYC data in operator database — not cryptographically verifiable
Regulatory approvals in separate system — not linked to live blockchain state
Audit trail requires operator cooperation to reconstruct
Smart contract upgrades can silently change compliance rules
Insurance solvency monitored off-chain — reactive, not proactive
VS
SHAMWARI PROTOCOL APPROACH
Compliance at consensus — rejected by every node, no bypass structurally possible
Tax withheld atomically at execution — non-separable from the payment
KYC data Kyber-encrypted on-chain — cryptographically anchored to permission record
Regulatory state is blockchain state — consistent, real-time, always accurate
Audit trail is the blockchain — independently verifiable by any node operator
Protocol compliance logic requires full network upgrade to change — transparent
Insurance reserves computed every block — proactive, automatic enforcement
Compliance PropertyShamwariEthereum + DeFiPermissioned BlockchainTraditional Finance
Compliance enforcementProtocol consensus layerSmart contract (bypassable)Chaincode / middlewareApplication layer
Tax withholdingAutomatic, atomic, 13 typesNoneNoneManual / periodic
KYC data storageEncrypted on-chain, permanentOff-chain / noneOff-chain MSPOperator database
Asset regulatory approval6-state TotemApproval at consensusNone nativeAdmin functionExternal registry
AML transfer blockingCONTROLLABLE currency typeNone nativeChaincode ruleSWIFT / correspondent bank
Insurance solvencyLive reserve computation, auto-redistributionSmart contract onlyNoneRegulator inspection
Regulatory authorityHardcoded at genesis, immutableNone nativeAdmin keyExternal regulator
Audit trailBlockchain state — immutable, quantum-resistantEvent logs (limited)Ledger (operator-controlled)Database (modifiable)
Post-quantum readinessML-DSA + ML-KEM from genesisECDSA — migration pendingRSA/ECDSA — not PQCPKI — migration underway
BUILD COMPLIANT APPLICATIONS

Regulatory compliance is a protocol property.

Build financial applications that are compliant by construction — not by policy. Every transaction, every asset, every payment governed by the same consensus rules that secure the entire chain.

Architecture Deep-Dive View Solutions Developer Hub