DYSNOMIA¶

Overview¶

DYSNOMIA is the abstract base token contract for the entire ecosystem. It implements ERC20-like functionality with multi-owner governance, market rate exchange system, and utility functions for string/hex conversion.

Inherits: MultiOwnable
License: Sharia
Solidity: ^0.8.21
Type: Abstract Contract

What This Means For Players¶

Plain English Summary: DYSNOMIA is the "gold coin" that everything in the game is built upon. Every token, currency, and reward in the Dysnomia ecosystem inherits from this base contract. It's not a token you directly hold - it's the foundation that makes all other tokens work.

Real-World Analogy: Think of DYSNOMIA like the "rules of money" in a video game. Just like how all currencies in a game (gold, gems, credits) follow the same basic rules for how they're counted, transferred, and exchanged, DYSNOMIA defines those rules for every token in this ecosystem.

Key Features For Players: - Token exchanges built-in - You can swap any DYSNOMIA-based token for another using Purchase/Redeem, without needing an external exchange - Random supply - Each token has a randomly-determined maximum supply, making every token unique - Multi-owner control - Tokens can have multiple managers, enabling shared control of game resources

State Variables¶

Variable	Type	Visibility	Description
_balances	mapping(address => uint256)	private	Token balances per address
_allowances	mapping(address => mapping(address => uint256))	private	Spending allowances
_totalSupply	uint256	private	Total token supply
__name	string	internal	Token name
__symbol	string	internal	Token symbol
MotzkinPrime	uint64	public constant	953467954114363 - Prime for cryptographic operations
Xiao	atropaMath	public	Reference to math contract (VMREQ)
maxSupply	uint256	public	Maximum mintable supply
_marketRates	mapping(address => uint256)	private	Exchange rates for token pairs

Read Functions¶

name¶

function name() public view virtual returns (string memory)

- Returns: Token name - In Plain English: Get the full name of this token, like "Dysnomia Gold" or "Player Bank Token".

symbol¶

function symbol() public view virtual returns (string memory)

- Returns: Token symbol - In Plain English: Get the ticker symbol like "DYS" or "YUE" - the short code used to identify this token.

decimals¶

function decimals() public view virtual returns (uint8)

- Returns: 18 (standard ERC20 decimals) - In Plain English: How many decimal places this token uses. 18 means 1 token = 1000000000000000000 in raw units (like cents to dollars, but more precise).

totalSupply¶

function totalSupply() public view virtual returns (uint256)

- Returns: Current total supply - In Plain English: How many tokens exist in total right now. This number grows when tokens are minted and stays below maxSupply.

balanceOf¶

function balanceOf(address account) public view virtual returns (uint256)

- Parameters: account - Address to query - Returns: Token balance of the account - In Plain English: Check how many tokens any address holds. Like checking someone's bank balance.

allowance¶

function allowance(address owner, address spender) public view virtual returns (uint256)

- Parameters: - owner - Token owner address - spender - Approved spender address - Returns: Approved spending amount - In Plain English: Check how much a spender is authorized to use from an owner's balance. Like checking the spending limit on a credit card.

GetMarketRate¶

function GetMarketRate(address _a) public view returns(uint256)

- Parameters: _a - Token address - Returns: Exchange rate for the specified token - In Plain English: Check the exchange rate between this token and another. Like checking "how many dollars per euro" at a currency exchange.

Write Functions¶

transfer¶

function transfer(address to, uint256 value) public virtual returns (bool)

- Parameters: - to - Recipient address - value - Amount to transfer - Returns: Success boolean - Description: Standard ERC20 transfer - In Plain English: Send tokens from your wallet to someone else. Like Venmo or PayPal but on the blockchain.

approve¶

function approve(address spender, uint256 value) public virtual returns (bool)

- Parameters: - spender - Address to approve - value - Amount to approve - Returns: Success boolean - Description: Approve spending allowance - In Plain English: Give permission for another address (like a game contract) to spend up to a certain amount of your tokens. Required before most game interactions.

transferFrom¶

function transferFrom(address from, address to, uint256 value) public virtual returns (bool)

- Parameters: - from - Source address - to - Destination address - value - Amount to transfer - Returns: Success boolean - Description: Transfer using approved allowance - In Plain English: Move tokens from one address to another using prior approval. This is how game contracts move your tokens after you've approved them.

Rename¶

function Rename(string memory newName, string memory newSymbol) public onlyOwners

- Access: onlyOwners - Description: Updates token name and symbol - In Plain English: Change the display name and symbol of this token. Only owners can do this - useful for personalizing your YUE or LAU.

mintToCap¶

function mintToCap() public onlyOwners

- Access: onlyOwners - Description: Mints 1 token to contract if below maxSupply - In Plain English: Create one new token (if there's room under the cap). Used to slowly grow the token supply for game rewards.

Purchase¶

function Purchase(address _t, uint256 _a) public

- Parameters: - _t - Token to spend - _a - Amount to purchase - Description: Buy this token using another token at market rate - In Plain English: Buy this token by paying with a different token at the set exchange rate. Like exchanging dollars for euros at a bank.

Redeem¶

function Redeem(address _t, uint256 _a) public

- Parameters: - _t - Token to receive - _a - Amount to redeem - Description: Sell this token for another token at market rate - In Plain English: Sell this token to get a different token at the set exchange rate. The reverse of Purchase - cash out for another currency.

Events¶

Event	Parameters	Description
Transfer	from (indexed), to (indexed), value	Token transfer event
Approval	owner (indexed), spender (indexed), value	Approval event

Errors¶

Error	Parameters	Description
DysnomiaInsufficientBalance	origin, sender, from, to, what, balance, needed	Insufficient balance for transfer
DysnomiaInsufficientAllowance	origin, sender, owner, spender, what, allowance, needed	Insufficient allowance
MarketRateNotFound	asset	No market rate set for token

Internal Functions¶

AddMarketRate¶

function AddMarketRate(address _a, uint256 _r) internal

- Description: Sets exchange rate for a token pair

_mintToCap¶

function _mintToCap() internal

- Description: Mints 1 token to contract if below maxSupply

_mint¶

function _mint(address account, uint256 value) internal

- Description: Creates new tokens

_update¶

function _update(address from, address to, uint256 value) internal virtual

- Description: Core transfer logic with supply tracking

Utility Functions¶

log10(uint256) - Compute log base 10
String(uint256) - Convert number to string
Hex(address/uint256/bytes32/bytes) - Convert to hex string

Contract Interactions¶

Depends On¶

MultiOwnable - Access control
VMREQ via atropaMath interface - Random number generation

Depended On By¶

All token contracts in the ecosystem inherit from DYSNOMIA

Special Mechanisms¶

Market Rate System¶

Enables token-to-token exchanges without external AMM. Each contract can set internal exchange rates for other tokens, allowing direct Purchase/Redeem operations.

Random Max Supply¶

Constructor uses Xiao.Random() % 111111 to set a randomized maximum supply, with initial mint being 10% of that maximum.

Multi-Owner Governance¶

Inherits from MultiOwnable allowing multiple addresses to have administrative privileges.

Contract Verification¶

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