Account System & Identity Framework

The Shamwari Account System & Identity Framework (nxt.account.Account) provides the core identity, access control, balance management, and cryptographic primitives built directly into the Shamwari ledger runtime.

By housing identity management, account properties, forging lease balance transfers, and domain resolution directly within nxt.account—rather than relying on external virtual machine contracts—Shamwari achieves post-quantum cryptographic security, human-readable domain naming, granular institutional account typing, and zero-overhead account state tracking across BetaChains.

---

Core Capabilities & Architecture

• Post-Quantum Cryptographic Identity: Hybrid public key infrastructure (ShamwariPublicKey) combining CRYSTALS-Kyber lattice-based key encapsulation (KyberPublicKey) and CRYSTALS-Dilithium digital signatures (DilithiumPublicKey).
• Multi-Tier Account Categorization: Native account profiling (AccountType) with 16 distinct operational designations (e.g., BANK, MERCHANT, SAVINGS, AUTONOMOUS, GOVERNMENT).
• Protocol-Native Domain Registry (.shamwari.network): Human-readable domain name registration, transfer, renewal, and search indexed directly on-chain (public.account_domain).
• Autonomous Account Control & Recursive Delegation: Enables programmatic AI agents (AUTONOMOUS) to act under controller account permissions, featuring cycle-protected effective type resolution.
• Forging Balance Leasing (AccountLease): Allows accounts to lease forging weight to pool operators or lessees without transferring balance ownership or spending rights.
• Scoped Account Property Registry (AccountProperty): On-chain key-value tagging mechanism allowing account owners and third-party setters to attach verifiable metadata to target accounts.
• Multi-Holding Balance Management: Dual-layer balance engines for digital assets/tokens (AccountTotem) and monetary units (AccountCurrency), tracking both confirmed and unconfirmed balances.

---

Cryptographic Identity & Public Key Infrastructure

Shamwari accounts bypass traditional ECDSA/secp256k1 curves in favor of post-quantum lattice cryptography.

       ┌────────────────────────────────────────────────────────┐
       │                 ShamwariPublicKey                      │
       ├───────────────────────────┬────────────────────────────┤
       │     KyberPublicKey        │    DilithiumPublicKey      │
       │ (Key Encapsulation / KEM) │ (Quantum-Resistant Sign)   │
       └─────────────┬─────────────┴──────────────┬─────────────┘
                     │                            │
                     └─────────────┬──────────────┘
                                   │
                                   ▼
                      Combined Public Key Bytes
                                   │
                                   ▼
                            SHA-256 Digest
                                   │
                                   ▼
                      64-bit Long Account ID

1. Account ID Derivation Formula

An account's globally unique 64-bit integer identifier ($AccountId$) is derived deterministically from its combined quantum-resistant public key bytes:

$AccountId = \text{Convert.fullHashToId}\Big(\text{SHA-256}(\text{ShamwariPublicKey.getCombinedPublicKey}())\Big)$

Where:

• $\text{ShamwariPublicKey.getCombinedPublicKey}() = \text{KyberPublicKey.getY}() \parallel \text{DilithiumPublicKey.getPublicKey}()$.
• $\text{fullHashToId}()$ extracts the first 8 bytes of the 32-byte digest into a signed 64-bit integer representation.

---

Account Classifications & Autonomous Control (AccountType)

Shamwari enforces native account classifications via AccountType codes, enabling the ledger to restrict or allow specific operations (such as merchant payment processing or savings deposits) based on account roles:

1. Classification Matrix

Code	Enum Value	Description & Purpose
1	NONE	Unclassified standard account. Default state upon initial key publication.
2	BANK	Regulated banking institution authorized for fiat issuer and clearing operations.
3	FSP	Financial Service Provider handling remittance, micro-credit, and brokerage.
4	MFI	Microfinance Institution focused on micro-credit and rural group lending.
5	MERCHANT	Verified point-of-sale or online merchant permitted to receive business payments.
6	BUSINESS	Commercial corporate account with bulk payroll and supply chain capabilities.
7	SAVINGS	Restricted accumulation account subject to deposit filtering and vault time-locks.
8	DEVELOPER	Software architect or smart contract deployer profile.
9	PERSONAL	Individual retail user account.
10	AUTONOMOUS	Programmatic AI agent or automated service account operating under delegated control.
11	NGO	Non-Governmental Organization driving targeted social subsidy distribution.
12	GOVERNMENT	Sovereign state entity, tax collector, or municipal treasury authority.
13	ACADEMIC	Educational institution issuing digital certificates and credentials.
14	ORGANIZATION	Co-operative, industry association, or non-profit body.
15	SOLE_TRADER	Registered individual business operator or informal vendor.
16	AGENT	Cash-in / cash-out liquidity agent or banking representative.

2. Recursive Effective Type Resolution

When an account is flagged as AUTONOMOUS, its operational capabilities default to its controlling account's effective type. To prevent infinite loops in nested control chains, Account.resolveEffectiveType() uses a visitation set ($V$) to detect cyclic delegation:

private AccountType resolveEffectiveType(Set<Long> visited) {
    if (!visited.add(this.id)) return AccountType.AUTONOMOUS; // Cycle guard
    AutonomousAccountControl ctrl = AutonomousAccountControl.get(this.id);
    if (ctrl == null) return AccountType.AUTONOMOUS;
    Account controller = Account.getAccount(ctrl.getControlAccountId());
    if (controller == null) return AccountType.AUTONOMOUS;
    AccountInfo controllerInfo = controller.getAccountInfo();
    AccountType controllerRaw = (controllerInfo == null) ? AccountType.NONE : controllerInfo.getAccountType();
    if (controllerRaw != AccountType.AUTONOMOUS) return controllerRaw;
    return controller.resolveEffectiveType(visited);
}

---

Data Model & Relational Schema

Account identity, public keys, holdings, leased forging weights, properties, and domain names are indexed in versioned relational database tables.

1. Primary Account Entities

Table	Primary / Composite Key	Entity Class	Description
public.account	id, height	Account	Master account state, active lessee IDs, and height markers.
public.public_key	account_id, height	PublicKey	Cryptographic public key repository storing Kyber and Dilithium public keys.
public.account_info	account_id, height	AccountInfo	Profile metadata (URLs, README, gender, DOB, nationality, peer address).
public.account_domain	domain, height	AccountDomain	Protocol-native .shamwari.network domain handles and expiration records.
public.account_property	id, height	AccountProperty	Key-value properties assigned to accounts by recipient or external setters.
public.account_lease	lessor_id, height	AccountLease	Active and scheduled forging balance lease parameters.
public.account_totem	account_id, totem_id	AccountTotem	Confirmed and unconfirmed digital asset/token holdings ($QNT$).
public.account_currency	account_id, currency_id	AccountCurrency	Confirmed and unconfirmed monetary unit holdings ($QNT$).
public.account_subscription	account_id, service_id	AccountSubscription	Validated subscription entitlement records and expiry heights.

---

2. Public Key Record (public.public_key)

Field	Type	Description
account_id	long	Unique 64-bit account identifier.
kyber_public_key	byte[]	Public key byte array for CRYSTALS-Kyber key encapsulation.
dilithium_public_key	byte[]	Public key byte array for CRYSTALS-Dilithium quantum-safe digital signatures.
height	int	Block height at which the public key was published.
latest	boolean	Flag indicating the current active version.

---

3. Account Information Schema (public.account_info)

Field	Type	Description
account_id	long	Associated account ID.
website	VARCHAR	Official website URL.
display	VARCHAR	Public display handle or name.
read_me	VARBINARY	Encrypted or plain text account overview payload.
type	byte	Numerical code mapping to AccountType enum ($1 \text{ to } 16$).
gender	VARCHAR	Optional profile gender string.
date_of_birth	VARCHAR	ISO date string (YYYY-MM-DD) for age verification.
nationality	VARCHAR	ISO country code or nationality description.
peer_address	VARCHAR	IP address or hostname of dedicated network node.
height	int	Block height of profile update.

---

4. Account Domain Schema (public.account_domain)

Field	Type	Description
domain	VARCHAR	Unique domain prefix (e.g., "treasury" for "treasury.shamwari.network").
domain_lower	VARCHAR	Lowercase normalized domain string for case-insensitive lookup.
account_id	long	Current owning account ID bound to the domain.
timestamp	int	Epoch timestamp of last domain registration, transfer, or renewal.
expiration_height	int	Block height at which the domain ownership expires unless renewed.
height	int	Block height of record update.

---

5. Account Property Schema (public.account_property)

Field	Type	Description
id	long	Unique transaction ID of the property creation.
chain	int	BetaChain identifier context where the property was set.
recipient_id	long	Account ID receiving the property tag.
setter_id	long	Account ID that authored the property (equals recipient_id if self-set).
property	VARCHAR	Property key name (max $32 \text{ bytes}$).
value	VARCHAR	Property string value (max $160 \text{ bytes}$).
height	int	Block height when property was established or modified.

---

Domain Registration & Lifecycle (.shamwari.network)

Accounts can register human-readable handles ending in .shamwari.network. Domains function as aliases for 64-bit account IDs across transaction forms and API endpoints.

              ┌─────────────────────────────────────────────────┐
              │  registerDomain() / Initial Name Claim          │
              └────────────────────────┬────────────────────────┘
                                       │
                                       ▼
              ┌─────────────────────────────────────────────────┐
              │                 ACTIVE DOMAIN                   │
              │  expirationHeight = currentHeight + 2,628,000   │
              └────────┬───────────────┬───────────────┬────────┘
                       │               │               │
       renewDomain()   │               │               │   transferDomain()
     (Extends Height)  │               │               │   (Reassigns Owner)
                       ▼               │               ▼
              ┌────────────────┐       │       ┌────────────────┐
              │ Height Extended│       │       │  New Owner ID  │
              └────────────────┘       │       └────────────────┘
                                       │
                       Height Reached  │
                    (height >= expiry) │
                                       ▼
              ┌─────────────────────────────────────────────────┐
              │                EXPIRED DOMAIN                   │
              │         (Available for New Name Claim)          │
              └─────────────────────────────────────────────────┘

1. Domain Validity & Expiration Formula

Domains are granted for fixed block windows equivalent to 1 calendar year ($365 \text{ days}$ assuming $12 \text{ second}$ block time):

$\text{DOMAIN\_VALIDITY\_BLOCKS} = 7,200 \times 365 = 2,628,000 \text{ blocks}$

When a domain is initialised or renewed, its new expiration height is computed as:

$\text{ExpirationHeight}_{\text{new}} = \text{ExpirationHeight}_{\text{current}} + 2,628,000 \text{ blocks}$

---

Consensus Balance Leasing Engine (AccountLease)

To support proof-of-stake consensus without forcing accounts to move funds into custody or cold-storage pools, Shamwari provides native balance leasing via AccountLease.

1. Leasing Parameters

• Lessor: Account granting forging weight.
• Lessee: Account receiving forging weight to generate blocks on BetaChains.
• Leasing Period: Defined by current_leasing_height_from and current_leasing_height_to.

2. State Transitions

The core ledger processor evaluates leasing transitions at the start of each block during AFTER_BLOCK_APPLY:

$\text{ActiveLesseeId}(\text{height}) = \begin{cases} \text{currentLesseeId} & \text{if } \text{currentLeasingHeightFrom} \le \text{height} \le \text{currentLeasingHeightTo} \\ \text{nextLesseeId} & \text{if } \text{height} = \text{nextLeasingHeightFrom} \\ \text{null} & \text{if } \text{height} > \text{currentLeasingHeightTo} \land \text{nextLesseeId} = \text{null} \end{cases}$

---

Profile Mathematics & Calculations

1. Age Calculation from Date of Birth

For compliant user accounts (AccountInfo), age is calculated dynamically using ISO calendar periods:

$\text{Age} = \text{Period.between}(\text{LocalDate.parse}(\text{dateOfBirth}), \text{LocalDate.now}()).\text{getYears}()$

If dateOfBirth is null or unparseable, getAge() returns $-1$.

---

2. Double-Spending Guard

When modifying account balances (AccountTotem or AccountCurrency), the engine verifies that confirmed and unconfirmed quantities satisfy positivity constraints:

$\text{checkBalance}(AccountId, Q_{\text{confirmed}}, Q_{\text{unconfirmed}}): \quad Q_{\text{confirmed}} \ge 0 \land Q_{\text{unconfirmed}} \ge 0$

If either value drops below zero, a DoubleSpendingException is raised, rolling back the transaction.

---

Event Listener Matrix

The Account System exposes event listeners across identity, domain, leasing, subscription, and loan modules:

Event Enum	Trigger Condition
TOTEM_BALANCE	Confirmed asset balance updated for an account.
UNCONFIRMED_TOTEM_BALANCE	Unconfirmed pending asset balance adjusted.
CURRENCY_BALANCE	Confirmed currency balance modified.
UNCONFIRMED_CURRENCY_BALANCE	Unconfirmed pending currency balance adjusted.
LEASE_SCHEDULED	Future forging balance lease scheduled by lessor.
LEASE_STARTED	Scheduled lease height reached; forging weight transferred.
LEASE_ENDED	Leasing period expired; forging weight restored to lessor.
SET_PROPERTY	Account property assigned or modified.
DELETE_PROPERTY	Account property deleted.
ACCOUNT_DOMAIN_REGISTRATION	New .shamwari.network domain handle registered.
ACCOUNT_DOMAIN_DEREGISTRATION	Domain handle revoked or deregistered.
ACCOUNT_DOMAIN_TRANSFER	Domain handle transferred to recipient account ID.
ACCOUNT_DOMAIN_RENEWAL	Domain handle renewed for $2,628,000 \text{ blocks}$.
ACCOUNT_DOMAIN_EXPIRATION	Domain handle expired and returned to available registry.
ACCOUNT_SUBSCRIPTION_CREATION	Access entitlement extended or created for service ID.

---

Related APIs

API	Description
GetAccount	Get account details
GetBalance	Get account balance
GetEffectiveBalance	Get effective balance
GetGuaranteedBalance	Get guaranteed balance
GetAccountPublicKey	Get account public key
RegisterAccountDomain	Register domain
RenewAccountDomain	Renew domain
TransferAccountDomain	Transfer domain
DeregisterAccountDomain	Deregister domain
SetAccountProperty	Set account property
DeleteAccountProperty	Delete account property
AddAccountPermission	Add account permission
RemoveAccountPermission	Remove account permission
GetAccountTotems	Get account Totems
GetAccountCurrencyLoans	Get account currency loans

Primary Institutional Use Cases

• Post-Quantum Treasury Management: Enterprise treasuries and central banks operate accounts protected against quantum computing attacks using hybrid Kyber/Dilithium keys.
• Human-Readable Banking Handles: Users send fiat and platform assets directly to human-readable domain handles (e.g., payroll.shamwari.network) instead of cryptographic public key hashes.
• Delegated AI Agent Commerce: Financial institutions deploy AUTONOMOUS accounts for AI trading bots and automated agents, binding them to corporate account policies while isolating risk.
• Non-Custodial Consensus Staking: High-net-worth accounts and institutional holders lease forging weight (AccountLease) to validator nodes, earning block rewards without transferring token custody.