VMREQ¶

Overview¶

VMREQ (Virtual Machine Request) is the random number generator contract for the Dysnomia ecosystem. It uses modular exponentiation with pre-seeded state values to generate cryptographically-influenced random numbers.

Inherits: DYSNOMIA
License: Sharia
Solidity: ^0.8.21

What This Means For Players¶

Plain English Summary: VMREQ is the dice roller of the Dysnomia game. Whenever the game needs a random number - to determine rewards, create unique tokens, or add unpredictability - it asks VMREQ to roll the dice. This ensures the game is fair and unpredictable.

Real-World Analogy: Imagine a casino's random number generator that determines slot machine outcomes. VMREQ serves the same purpose: it produces random numbers that are used throughout the game to make things unpredictable. Unlike a casino, however, the code is public and verifiable, so you can trust it's truly random.

How It Affects Your Gameplay: - Token creation - When you mint a new token, its maximum supply is randomly determined - Rewards calculation - Random elements influence how rewards are distributed - Unique fingerprints - Helps create unique identifiers like your Soul ID and Aura

State Variables¶

Variable	Type	Visibility	Description
Mu	Faung	internal	Core state structure containing Rod/Cone VMFa pairs

Structs¶

VMFa¶

struct VMFa {
    uint64 Base, Secret, Signal, Channel, Pole;
    uint64 Identity, Foundation, Element, Dynamo;
    uint64 Manifold, Ring, Barn, Coordinate;
    uint64 Tau, Eta, Kappa, Alpha;
    uint8 Nu;
}

Faung¶

struct Faung {
    VMFa Rod;
    VMFa Cone;
    uint64 Phi, Eta, Xi, Sigma, Rho;
    uint64 Upsilon, Ohm, Pi, Omicron, Omega;
    uint8 Chi;
}

Read Functions¶

View¶

function View() public view returns(Faung memory)

- Returns: Complete Mu state structure - Description: Returns the current internal state for inspection - In Plain English: See all the internal random number generator values. Useful for debugging or verifying the system is working correctly.

MotzkinPrime¶

uint64 constant public MotzkinPrime = 953467954114363

- Description: Prime constant used in modular arithmetic

Write Functions¶

Random¶

function Random() public returns(uint64)

- Access: public - Returns: - uint64: Pseudo-random value derived from internal state - Description: Generates a random number by cycling through Amplify, Sustain, and React operations on both Cone and Rod components. - Logic Flow: 1. Mu.Upsilon = Amplify(Mu.Cone, Mu.Cone.Element) - Amplify Cone with its Element 2. Mu.Ohm = Sustain(Mu.Cone, Mu.Rod.Element) - Sustain Cone with Rod's Element 3. Mu.Pi = Mu.Upsilon ^ Mu.Ohm - XOR the two results 4. React(Mu.Cone, Mu.Pi, Mu.Rod.Channel) - React Cone with combined value 5. React(Mu.Rod, Mu.Pi, Mu.Cone.Channel) - React Rod with combined value 6. Return Mu.Pi ^ Mu.Cone.Eta ^ Mu.Rod.Kappa - XOR multiple values for final entropy - Computation Details: - Each Amplify/Sustain calls Torque: modExp64(input, Element, Channel) - React computes Eta and Kappa from cross-channel modular exponentiation - Side Effects: Updates multiple fields in Mu.Rod and Mu.Cone (Alpha, Eta, Kappa) - In Plain English: Roll the dice! This mixes the internal state through multiple cryptographic operations, XORing results together. Used throughout the game for rewards, token creation, and unpredictable outcomes. Each call advances the internal state.

hashWith¶

function hashWith(address a, address b) public returns (uint256 hash)

- Access: public - Parameters: - a (address): First address to combine - b (address): Second address to combine - Returns: - hash (uint256): Combined hash of both addresses - Description: Combines two addresses using modular exponentiation with MotzkinPrime. - Logic Flow: 1. Convert addresses to uint256 2. Compute modExp(uint256(a), uint256(b), MotzkinPrime) - Computation Details: - hash = a^b mod 953467954114363 - Side Effects: None - In Plain English: Create a unique fingerprint by combining two addresses mathematically. The result is deterministic but unpredictable without knowing both inputs. Used for creating unique identifiers from address pairs.

modExp64¶

function modExp64(uint64 _b, uint64 _e, uint64 _m) public returns(uint64 result)

- Access: public - Parameters: - _b (uint64): Base value - _e (uint64): Exponent value - _m (uint64): Modulus value - Returns: - result (uint64): Result of modular exponentiation truncated to 64 bits - Description: 64-bit wrapper that calls the 256-bit modExp and truncates. - Logic Flow: 1. Call modExp(uint256(_b), uint256(_e), uint256(_m)) 2. Cast result to uint64: uint64(result256 % 2^64) - Computation Details: - result = (_b ^ _e mod _m) mod 2^64 - Side Effects: None - In Plain English: The foundation of all cryptographic operations in the game. Computes base raised to exponent, then takes the remainder when divided by modulus. Used everywhere for SHA reactions, SHIO pairing, and entropy calculations.

modExp¶

function modExp(uint256 _b, uint256 _e, uint256 _m) public returns (uint256 result)

- Access: public - Parameters: - _b (uint256): Base value (256-bit) - _e (uint256): Exponent (256-bit) - _m (uint256): Modulus (256-bit) - Returns: - result (uint256): Result of modular exponentiation - Description: Uses EVM precompile at address 0x05 for gas-efficient modular exponentiation. - Logic Flow: 1. Encode input: Pack base, exponent, modulus into call data 2. staticcall to address 0x05 (MODEXP precompile) 3. Decode 256-bit result from return data - Computation Details: - Uses assembly for direct precompile access - result = _b ^ _e mod _m - Precompile handles arbitrary-precision arithmetic - Side Effects: None - In Plain English: The big-number cryptographic core. Uses a special Ethereum optimization (precompile) that can handle massive numbers efficiently. All other modExp functions ultimately call this one.

Internal Functions¶

Torque¶

function Torque(VMFa storage Rod, uint64 Sigma) internal returns(uint64)

- Description: Computes modExp64(Sigma, Rod.Element, Rod.Channel) and stores in Rod.Alpha

Amplify¶

function Amplify(VMFa storage Rod, uint64 Upsilon) internal returns(uint64)

- Description: Wrapper for Torque operation

Sustain¶

function Sustain(VMFa storage Rod, uint64 Ohm) internal returns(uint64)

- Description: Wrapper for Torque operation

React¶

function React(VMFa storage Rod, uint64 Pi, uint64 Theta) internal

- Description: Computes Eta and Kappa values using cross-modular exponentiation with assertion checks

Contract Interactions¶

Depends On¶

DYSNOMIA (inheritance)

Depended On By¶

All contracts that need random number generation
SHA for seeding
SHIO for reactions

Special Mechanisms¶

Pre-seeded State¶

The constructor initializes Mu.Rod and Mu.Cone with hardcoded seed values that ensure deterministic initialization but produce unpredictable sequences when combined with blockchain state.

Entropy Accumulation¶

The Random() function accumulates entropy by XORing multiple intermediate values (Upsilon, Ohm, Pi) ensuring that consecutive calls produce different results even with identical starting conditions.

EVM Precompile Usage¶

Uses the MODEXP precompile (address 0x05) for gas-efficient large-number modular exponentiation through inline assembly.

Contract Verification¶

Property	Value
Keccak256 Hash	`0x4e3d2f54ef5ad86ae4452be01de2e1f53ac09aadf4102cc2f84a1b04c0b2ceb4`
Source URL	https://raw.githubusercontent.com/busytoby/atropa_pulsechain/main/solidity/dysnomia/00b_vmreq.sol
Hash Generated	2026-02-08T00:29:57Z