Totem Digital Asset System

The Totem Digital Asset System is Shamwari Network's protocol-native for issuing, managing, trading, and governing digital assets, equities, debt instruments, non-fungible tokens (NFTs), and Real-World Assets (RWAs).

Unlike legacy smart contract platforms that rely on EVM/WASM code execution—introducing multi-billion-dollar reentrancy risks and costly audit cycles—Shamwari embeds the full lifecycle of digital assets, multi-currency limit-order book trading, non-dilutive asset splits, and governance phasing directly into the blockchain consensus runtime.

1. System Architecture & Core Concepts

A Totem is a protocol-enforced digital representation of ownership bound to a specific sovereign BetaChain (e.g., $ZWG$ , $ZAR$ ).

                       +-----------------------------------------+
                       |               TOTEM ASSET               |
                       |  (Name, Description, Decimals, Types)   |
                       +-----------------------------------------+
                                            |
         +----------------------------------+----------------------------------+
         |                                  |                                  |
         v                                  v                                  v
 +------------------+             +--------------------+            +--------------------+
 |  TotemType Rules |             | Multi-Currency DEX |            |  TotemControl      |
 |  - NON_FUNGIBLE  |             |  - Native Orderbook|            |  - Phased Voting   |
 |  - NON_SPLITTABLE|             |  - Tax Withholding |            |  - Whitelist Rules |
 +------------------+             +--------------------+            +--------------------+

Core Data Model (`Totem.java`)

Each Totem record maintains the following immutable and mutable properties on-chain:

Parameter	Type	Description
`totemId`	`long`	Unique 64-bit integer identifier generated from the issuance transaction hash.
`issuerId`	`long`	Account ID of the entity that created the Totem.
`betaChain`	`BetaChain`	The specific sovereign child-chain where the asset resides and trades.
`name`	`String`	Human-readable identifier (unique indexed).
`description`	`String`	Asset description (up to 1000 characters).
`type`	`int`	Bitmask defining Totem capabilities (`TotemType`).
`quantityQNT`	`long`	Current circulating supply in base Quantum Units (QNT).
`maxQuantityQNT`	`long`	Maximum allowable total supply cap (QNT).
`decimals`	`byte`	Divisibility precision (0 to 8).
`hasPhasingControl`	`boolean`	Flag indicating if operations require governance poll approvals.

2. Totem Types & Classification (`TotemType.java`)

Shamwari strictly validates asset behavior based on strict protocol-enforced bitmasks. Assets must adhere to mutually exclusive classification rules:

A. Non-Fungible Assets (`NON_FUNGIBLE = 0x01`)

Quantity Constraints: Initial supply must be exactly 1 QNT, maxQuantityQNT must be 1, and decimals must be 0.
Operational Rules: Supply cannot be increased (TOTEM_INCREASE is prohibited). Metadata properties can only be modified or set by the original issuer.
Use Cases: Titles of land, vehicle registrations, identity certificates, physical real-world asset (RWA) tokens.

B. Non-Splittable Fixed Assets (`NON_SPLITTABLE = 0x02`)

Quantity Constraints: maxQuantityQNT must equal the initial quantityQNT.
Operational Rules: Supply increases (TOTEM_INCREASE) are structurally blocked by consensus.
Use Cases: Fixed-cap corporate bond issuances, fixed-supply utility tokens, capped equity rounds.

C. Splittable Assets (`SPLITTABLE = 0x04`)

Quantity Constraints: maxQuantityQNT must be strictly greater than initial quantityQNT.
Operational Rules: Allows proportional non-dilutive share increases across all existing holders based on snapshot block heights.
Use Cases: Public equities, fund units, tokenized real-estate trusts.

3. Protocol-Native Order-Book Exchange Engine (`OrderHome.java` & `TradeHome.java`)

The Totem Exchange Engine eliminates Automated Market Makers (AMMs) and liquidity provider impermanent loss by embedding a high-throughput, deterministic limit-order book directly into each sovereign BetaChain.

Order Matching Algorithm

Trading orders are paired automatically during block execution using a deterministic Price-Time Priority matching engine:

Ask Sorting: ORDER BY price ASC, creation_height ASC, transaction_height ASC, transaction_index ASC
Bid Sorting: ORDER BY price DESC, creation_height ASC, transaction_height ASC, transaction_index ASC
Execution Price: Determined by the resting order (maker price).

[Ask Order (Seller)] ---\
                          +---> [Order Matching Loop] ---> [Capital Gains Tax Engine] ---> [Balance Settlement]
[Bid Order (Buyer)]  ---/

Protocol-Level Tax Withholding

When an Ask order and Bid order match, the chain automatically calculates and deducts regulatory withholding tax before settling funds:

\text{Tax}_{\text{total}} = \text{TaxCalculator.computeTotalTax}(\text{TOTEM\_ASK\_ORDER\_PLACEMENT}, \text{TaxPolicy}, \text{Amount}_{\text{QNT}}) \text{NetSellerAmount}_{\text{QNT}} = \text{Amount}_{\text{QNT}} - \text{Tax}_{\text{total}}

Seller Settlement: Receives NetSellerAmount in target currency.
Tax Collector Settlement: Tax_total is immediately credited to the sovereign tax collector account (CurrencyTaxRecord.creditTaxAccount) specified by the BetaChain tax policy.
Buyer Settlement: Receives exact filled Totem QNT quantity without incurring additional hidden slippage.

4. Corporate Actions & Asset Lifecycle

Proportional Non-Dilutive Supply Increases (`increaseTotem`)

For SPLITTABLE Totems, issuers can increase circulating supply (e.g., executing stock splits or capitalization issues) without diluting existing shareholder ratios:

A snapshot height H_snap is specified.
The system queries account holdings at H_snap via Account.getTotemAccounts.
For each holder i with holding Q_i, the additional allocation is calculated:

Q_{i, \text{new}} = \text{Convert.unitRateToAmount}(Q_i, \text{decimals}, \text{increasePerShareQNT}, \text{decimals})

Total supply increases by sum of Q_i_new, maintaining exact relative equity ownership percentages across all shareholders.

Dividend Distributions (`dividendPayment`)

Totem issuers can distribute currency dividends directly to all asset holders. Payments are calculated proportionally based on snapshot account balances and dispatched via protocol ledger events (TOTEM_DIVIDEND_PAYMENT).

Asset Deletion & Burning (`deleteTotem`)

Holders can permanently decrease circulating supply by deleting Totems from their balance. Deletions are logged immutably in TotemHistory with a negative quantity change (-QNT).

5. Metadata & Provenance Properties (`TotemProperty`)

Totems support dynamic key-value property attachments, enabling enterprise metadata management linked to post-quantum digital certificates:

+-------------------------------------------------------------------------+
|                              TOTEM PROPERTY                             |
|  (Property Key, Value, Setter Account ID, PQC Certificate ID Anchor)    |
+-------------------------------------------------------------------------+

System Standard Properties

Freeze (TOTEM_FREEZE_HEIGHT_PROPERTY): Height at which trading and transfers are frozen by regulatory order.
Migrate (TOTEM_MIGRATE_HEIGHT_PROPERTY): Block height specifying mandatory cross-chain or asset migration.
certificateId: Links property attestations directly to a NIST FIPS 204 (ML-DSA-2) PQC digital identity certificate.

6. Governance & Phasing Control (`TotemControl.java`)

Sensitive operations on high-value Totems can be gated behind protocol-enforced governance policies via TotemControl.

Controlled Transaction Types

When phasing control is enabled on a Totem, the following transaction types require formal poll execution before taking effect:

TOTEM_TRANSFER
TOTEM_DELETE
ASK_ORDER_PLACEMENT / BID_ORDER_PLACEMENT
DIVIDEND_PAYMENT
TOTEM_INCREASE
TOTEM_PROPERTY_SET / TOTEM_PROPERTY_DELETE
SHUFFLING_CREATION

Voting Models & Sub-Polls

TotemControl supports complex approval rules:

Whitelist Models: Only pre-approved account addresses can vote or sign off.
Property-Weighted Voting: Voting power proportional to specific account property claims.
Sub-Poll Expressions: Conditional logical trees (PhasingOnlySubPoll) requiring multi-factor stakeholder consensus.

Summary Matrix

Feature	EVM Smart Contract Equivalent	Shamwari Totem Native Advantage
Asset Security	Custom ERC-20 / ERC-1155 code	Consensus-layer execution; immune to reentrancy.
Trading Engine	Uniswap / AMM Smart Contracts	Built-in order book with Price-Time priority matching.
Tax Withholding	Manual contract fee hooks	Automatic regulatory tax calculation & collector dispatch.
Asset Splits	Manual rebase contracts / Dilutive mints	Non-dilutive, snapshot-based proportional share increases.
Governance	Compound DAO smart contracts	On-chain `TotemControl` phasing & sub-poll voting engine.

issueTotem - Create new Totem
transferTotem - Transfer ownership
placeAskOrder / placeBidOrder - Trade on order book
dividendPayment - Distribute dividends
getTotem / getTotems - Query Totem data
getAccountTotems - Get account holdings

1. System Architecture & Core Concepts​

Core Data Model (Totem.java)​

2. Totem Types & Classification (TotemType.java)​

A. Non-Fungible Assets (NON_FUNGIBLE = 0x01)​

B. Non-Splittable Fixed Assets (NON_SPLITTABLE = 0x02)​

C. Splittable Assets (SPLITTABLE = 0x04)​

3. Protocol-Native Order-Book Exchange Engine (OrderHome.java & TradeHome.java)​

Order Matching Algorithm​

Protocol-Level Tax Withholding​

4. Corporate Actions & Asset Lifecycle​

Proportional Non-Dilutive Supply Increases (increaseTotem)​

Dividend Distributions (dividendPayment)​

Asset Deletion & Burning (deleteTotem)​

5. Metadata & Provenance Properties (TotemProperty)​

System Standard Properties​

6. Governance & Phasing Control (TotemControl.java)​

Controlled Transaction Types​

Voting Models & Sub-Polls​

Summary Matrix​

Related APIs​