Mathematical Foundations

Shamwari Network's security rests on NIST-standardized post-quantum cryptographic primitives built on lattice-based hardness problems, protecting against both classical and quantum computing threats.

Post-Quantum Threat Model

Classical public-key cryptography (RSA, ECDSA, ECDH) relies on the hardness of integer factorization and discrete logarithms, which will be completely broken by Cryptographically Relevant Quantum Computers (CRQCs) executing Shor's Algorithm. Additionally, Grover's Algorithm provides quadratic speedups for brute-force symmetric key and hash searches.

Financial platforms face an immediate operational risk from "Harvest Now, Decrypt Later" (HNDL) attacks, where adversarial entities capture encrypted traffic today to decrypt once quantum capabilities become available.

NIST PQC Standards (Finalized August 2024)

Shamwari natively integrates NIST's finalized post-quantum standards:

Standard	Algorithm Family	Scheme Type	Shamwari Parameter Set	OID / Standard Identifier
FIPS 203	Module-Lattice (MLWE)	ML-KEM	ML-KEM-512 (Kyber-512)	2.16.840.1.101.3.4.4.1
FIPS 204	Module-Lattice (MLWE / SIS)	ML-DSA	ML-DSA-2 (Dilithium Level 2)	1.3.6.1.4.1.22554.5.7.1
FIPS 205	Hash-Based	SLH-DSA	Researched / Future Agility	N/A

Lattice-Based Cryptography

Lattice-based cryptography derives its security from the mathematical hardness of high-dimensional lattice problems, which remain intractable for both classical and quantum computers.

Learning With Errors (LWE)

Given a matrix $A \in \mathbb{Z}_q^{m \times n}$ and a vector $b = A \cdot s + e \pmod q$, where $s \in \mathbb{Z}_q^n$ is a secret vector and $e \in \mathbb{Z}_q^m$ is a small error vector drawn from an error distribution, the LWE problem states that it is computationally infeasible to recover $s$ or distinguish $b$ from a uniform random vector.

Module Learning With Errors (MLWE)

MLWE generalizes LWE by replacing integers with polynomial rings $R_q = \mathbb{Z}_q[X]/(X^n + 1)$, operating over modules of rank $k$. This structure offers:

• Dramatically reduced key sizes
• Optimized polynomial multiplication via Number Theoretic Transform (NTT)
• High performance suitable for production financial workloads

Shamwari leverages MLWE for key encapsulation (ML-KEM-512, $k=2$) and digital signatures (ML-DSA-2, Level 2).

Key Derivation & Domain Separation Mathematics

Shamwari derives deterministic master seeds from human-readable passphrases using PBKDF2-HMAC-SHA512 with $100{,}000$ iterations and domain-separated application salts:

$S = \text{PBKDF2}\Big(\text{Password}, \text{Salt} = \text{"ShamwariBlockchain-seed-v1"}, \text{Iterations} = 100000, \text{Len} = 256 \text{ bits}\Big)$

From the derived 32-byte seed $S$, domain separation is applied using SHA3-256 to generate non-overlapping sub-seeds for the Kyber (ML-KEM) and Dilithium (ML-DSA) key generators:

$S_{\text{kyber}} = \text{SHA3-256}(0\text{x}01 \parallel S)$

$S_{\text{dilithium}} = \text{SHA3-256}(0\text{x}02 \parallel S)$

Cryptographic Key Structure: ShamwariQKP

Shamwari introduces ShamwariQKP (Quantum Key Pair) as a composite key primitive pairing functionally distinct post-quantum keys:

1. ML-KEM-512 (Kyber-512): Used for key encapsulation, symmetric session-key establishment, and payload confidentiality.
2. ML-DSA Level 2 (Dilithium-2): Used for digital signatures across transactions, block generation, and identity certificates.

ShamwariQKP
 ├── ML-KEM-512 Key Pair  (Confidentiality / Key Encapsulation)
 └── ML-DSA-2 Key Pair    (Authentication / Digital Signatures)

Key Sizes and Binary Representation

Component Primitive	Public Key Size	Secret Key Size	Signature / Ciphertext Size
ML-KEM-512	800 bytes ($\rho \parallel t$)	1632 bytes ($s \parallel pk \parallel H(pk) \parallel z$)	768 bytes (Ciphertext)
ML-DSA-2	1312 bytes	2528 bytes	2420 bytes (Signature)
Combined (ShamwariQKP)	2112 bytes	4160 bytes	N/A

All public components are encoded using standard ASN.1 X.509 SubjectPublicKeyInfo DER structures, while private components use ASN.1 PKCS#8 PrivateKeyInfo DER structures.

Symmetric Payload Encryption (HKDF-SHA256 & AES-256-GCM)

Confidential payloads (e.g., encrypted messages, private asset metadata) combine ML-KEM-512 key encapsulation with AES-256-GCM symmetric encryption.

The 32-byte symmetric key $K_{\text{AES}}$ is derived from the ML-KEM shared secret $ss$ using HKDF-SHA256, bound directly to the Kyber ciphertext $C_{\text{Kyber}}$ as salt:

$K_{\text{AES}} = \text{HKDF-SHA256}\Big(\text{ikm} = ss, \, \text{salt} = C_{\text{Kyber}}, \, \text{info} = \text{"shamwari-enc-v2"}, \, \text{len} = 32\Big)$

The resulting payload wire format is:

$\text{Payload Wire Format} = \big[ \, \text{Nonce (12 B)} \, \parallel \, \text{Ciphertext} \, \parallel \, \text{GCM Tag (16 B)} \, \parallel \, C_{\text{Kyber}} \text{ (768 B)} \, \big]$

Consensus Mathematics: Balance-Weighted PoS

Shamwari uses a balance-weighted Proof-of-Stake (PoS) consensus mechanism ("forging") operating at a target block time of ~12 seconds ($\Delta t_{\text{target}} \approx 12\text{ s}$). The algorithm deterministically selects block generators based on an account's effective guaranteed balance and a cryptographic hit value derived from the prior block signature.

Hit Value Derivation

For each candidate forging account, a 64-bit unsigned Hit Value ($H$) is derived by hashing the previous block's generation signature and the candidate's composite public key using SHA-256:

$\text{Digest} = \text{SHA-256}\big(\text{GenerationSignature}_{\text{prev}} \parallel \text{PublicKey}_{\text{forger}}\big)$

The hit $H$ is extracted from the first 8 bytes (bytes $0$ through $7$) of $\text{Digest}$, converted from little-endian byte ordering to a 64-bit unsigned integer:

$H = \sum_{i=0}^{7} \text{Digest}[i] \cdot 2^{8i}$

Target & Hit Time Calculation

The effective target $T_{\text{effective}}$ scales linearly with the forger's guaranteed effective FXT balance ($B_{\text{effective}}$) and the network's current base target ($T_{\text{base}}$):

$T_{\text{effective}} = B_{\text{effective}} \cdot T_{\text{base}}$

The deterministic Hit Time ($t_{\text{hit}}$)—the point in time when a candidate forger becomes eligible to produce a block—is computed relative to the previous block's timestamp $t_{\text{prev}}$:

$t_{\text{hit}} = t_{\text{prev}} + \left\lfloor \frac{H}{B_{\text{effective}} \cdot T_{\text{base}}} \right\rfloor$

A block produced at timestamp $t$ is mathematically valid if and only if:

$H < B_{\text{effective}} \cdot T_{\text{base}} \cdot \Delta t$

where $\Delta t = t - t_{\text{prev}} > 0$ represents the elapsed time in seconds since the previous block.

Dynamic Base Target Adjustment

To maintain the target block time of ~12 seconds, the base target $T_{\text{base}}$ adjusts dynamically every two blocks based on the 3-block moving average block time ($\Delta t_{\text{avg}}$):

• If $\Delta t_{\text{avg}} > 12\text{ s}$, $T_{\text{base}}$ increases, making block forging easier for all participants.
• If $\Delta t_{\text{avg}} < 12\text{ s}$, $T_{\text{base}}$ decreases, tightening the target threshold.

The adjustment is constrained within protocol boundary parameters:

$\text{MIN\_BASE\_TARGET} \le T_{\text{base}} \le \text{MAX\_BASE\_TARGET}$

Step adjustments per recalculation are bounded between $\text{MIN\_BLOCKTIME\_DELTA}$ and $\text{MAX\_BLOCKTIME\_DELTA}$ to suppress volatility and prevent dramatic swings in block interval timing.

Cumulative Difficulty & Fork Resolution

Each generated block contributes to the network's total cumulative difficulty:

$\text{Difficulty}_{\text{block}} = \frac{2^{64}}{T_{\text{base}}}$

The canonical chain is determined by the fork branch exhibiting the highest cumulative difficulty ($\sum \text{Difficulty}_{\text{block}}$).

Resource-Aware Forging Guard

To preserve node stability during periods of intense transaction throughput, Shamwari enforces a resource-aware guard function in Generator.java. The compute resources required to forge scale dynamically with mempool volume ($U = \text{unconfirmedTransactionCount}$):

$\text{CPU}_{\text{req}} = \text{CPU}_{\text{min}} + \max\left(0, \left\lfloor \frac{U - 10}{100} \right\rfloor\right)$

$\text{RAM}_{\text{req}} = \text{RAM}_{\text{min}} + \max\left(0, (U - 10) \cdot 256 \text{ KB}\right)$

where baseline thresholds are $\text{CPU}_{\text{min}} = 2\text{ cores}$ and $\text{RAM}_{\text{min}} = 1\text{ GB}$. If host resources satisfy $\text{CPU}_{\text{avail}} < \text{CPU}_{\text{req}}$ or $\text{RAM}_{\text{free}} < \text{RAM}_{\text{req}}$, block generation is skipped for that 500ms forging cycle to protect system stability.

Pop-Off Mechanics & Reorganization

If a forger calculates a hit time $t_{\text{hit}}$ earlier than the current tip block's timestamp $t_{\text{last}}$, a block pop-off is triggered:

1. The tip block is removed from the blockchain.
2. Its transactions are returned to the unconfirmed mempool for re-evaluation.
3. The forger generates the replacement block anchored directly to $t_{\text{prev}}$, ensuring the canonical chain continuously reflects optimal global forger ordering.

Cryptographic Hashes & Standards

Algorithm	Provider / Class	Usage	Output Size
SHA-256	MessageDigest	Block hashing, transaction IDs, Hit generation	256 bits
SHA-512	PBKDF2WithHmacSHA512	Seed key derivation (100,000 iterations)	512 bits
SHA3-256	Keccak.Digest256 / SHA3_256	Domain separation ($S_{\text{kyber}}, S_{\text{dilithium}}$) & $H(pk)$ digest	256 bits
RIPEMD-160	RIPEMD160.Digest	Legacy address compatibility	160 bits
HKDF-SHA256	HKDFBytesGenerator	Key derivation for AES-256-GCM symmetric encryption	256 bits
AES-256-GCM	GCMBlockCipher	Authenticated payload encryption (12-byte IV, 16-byte tag)	Variable

Zero-Knowledge & Selective Disclosure

Shamwari incorporates privacy-preserving commitments and selective disclosure mechanisms:

• Phasing & Multi-Party Control: Time-locked puzzles and multi-signature threshold expressions ($M$-of-$N$) executed via protocol-native voting.
• W3C Verifiable Credentials: Selective disclosure of account identity and KYC attributes without exposing underlying personal data.