CHO¶

Overview¶

CHO is the primary login and user authentication contract. It manages user delegation, entropy tracking, and system address registry. CHO serves as the gateway between user tokens (LAU) and the domain contract system.

Inherits: DYSNOMIA V2
License: Sharia
Solidity: ^0.8.21

What This Means For Players¶

Plain English Summary: CHO is the login gate - it verifies you are who you say you are. When you want to interact with the game, CHO checks that you own your LAU token and registers you as an active player. It's the bouncer that makes sure only legitimate players get access.

Real-World Analogy: Think of CHO like the login screen of a multiplayer game combined with a passport control checkpoint. You present your credentials (LAU token), CHO verifies them, and then you're allowed into the game world. It also maintains a directory of all registered players.

How It Affects Your Gameplay: - Authentication - CHO verifies you own your LAU before letting you play - User registry - Your Soul ID and wallet address are linked here - WITHOUT ban - Holders of the WITHOUT token are permanently blocked - Entropy tracking - CHO evolves system randomness with each interaction - System addresses - Important game contracts are registered here by name

Constants¶

Constant	Value	Description
Gua	1652929763764148448182513644633101239607891671119935657884642	Universe constant for Luo generation

State Variables¶

Variable	Type	Visibility	Description
Type	string	public constant	"CHO"
Void	VOID	public	Reference to session manager
Saat	uint64[3]	public	CHO's own Saat values
On	Bao	public	CHO's Bao state
Entropy	uint64	public	Current system entropy
Delegates	mapping(address => User)	private	Wallet → User mapping
DelegateAddresses	mapping(uint64 => address)	private	Soul → Wallet mapping
Addresses	mapping(string => address)	public	Named system addresses
Qu	mapping(uint256 => address)	public	Luo → creator mapping
Aliases	string[]	public	List of registered aliases

Read Functions¶

GetUserSoul¶

function GetUserSoul() public view returns(uint64)

- Returns: Soul ID of tx.origin - In Plain English: Get your unique player number. This is your permanent ID in the game - like your account number that identifies you across all interactions.

GetAddressBySoul¶

function GetAddressBySoul(uint64 soul) public view returns(address)

- Returns: Wallet address for Soul ID - In Plain English: Look up any player's wallet address using their Soul ID. Useful for finding which wallet belongs to a player you met in the game.

GetUserTokenAddress¶

function GetUserTokenAddress(address wallet) public view returns(address)

- Returns: LAU token address for wallet - In Plain English: Find the LAU player token for any wallet address. The LAU is the player's identity contract - this helps you find it if you only know their wallet.

Reactor¶

function Reactor() public view returns(LIBCOREREACTIONS)

- Returns: Reference to core reactions library - In Plain English: Get the address of the reactions engine. This is the cryptographic system that generates randomness and processes game operations.

Write Functions¶

Enter¶

function Enter(address UserToken) public returns(User memory)

- Access: public - Parameters: - UserToken (address): Address of the user's LAU token contract - Returns: - User: Populated User struct with Soul, Bao, Username, and Entropy - Description: Authenticates user via LAU ownership and registers them in the delegate mappings. - Logic Flow: 1. Check NOT banned: assert(WITHOUT.balanceOf(tx.origin) == 0) 2. Verify LAU permissions: VerifyUserTokenPermissions(UserToken) 3. Check ownership: if(!UserLau.owner(tx.origin)) revert InvalidOwnership 4. Create User struct from LAU data 5. Register in Delegates[tx.origin] = Alpha 6. Register in DelegateAddresses[Alpha.Soul] = tx.origin 7. Return User - Side Effects: Updates Delegates and DelegateAddresses mappings; may revert if banned or unauthorized - In Plain English: Log into the game by presenting your LAU token. CHO verifies you own the token, aren't banned (no WITHOUT tokens), and have proper permissions. Then it registers you as an active player so other contracts can look you up.

GetUser¶

function GetUser() public returns(User memory Alpha)

- Access: public - Returns: - Alpha (User): Current user's data from delegate mapping - Description: Retrieves current user and triggers entropy evolution via Recall. - Logic Flow: 1. Look up: Alpha = Delegates[tx.origin] 2. Evolve entropy: Alpha.Entropy = Recall(Alpha) 3. Return Alpha - Side Effects: Updates system entropy via reaction; mints tokens - In Plain English: Get your current player data including Soul, username, Bao, and entropy. As a side effect, this evolves the system's randomness, so calling it twice produces different entropy values.

GetUserBySoul¶

function GetUserBySoul(uint64 Soul) public returns (User memory Alpha)

- Access: public - Parameters: - Soul (uint64): The Soul ID to look up - Returns: - Alpha (User): User data for the specified Soul ID - Description: Looks up user by Soul ID and evolves their entropy. - Logic Flow: 1. Get wallet: DelegateAddresses[Soul] 2. Get user: Alpha = Delegates[wallet] 3. Evolve: Alpha.Entropy = Recall(Alpha) 4. Return Alpha - Side Effects: Updates user entropy; mints tokens - In Plain English: Look up any player's full profile using their Soul ID. Returns their username, Bao, and other player data with freshly calculated entropy.

React¶

function React(uint64 Eta) public returns (uint64, uint64)

- Access: public - Parameters: - Eta (uint64): Input value for reaction - Returns: - uint64: Omicron output - uint64: Omega output - Description: Reacts CHO's Bao with input value via the reactions library. - Logic Flow: 1. React: (On.Omicron, On.Omega) = Reactor().ReactShioRod(On.Shio, Eta) 2. Update entropy: Entropy = Entropy ^ On.Omega 3. Return (On.Omicron, On.Omega) - Side Effects: Updates On.Omicron, On.Omega, and Entropy; mints tokens - In Plain English: Process a cryptographic reaction. The output is deterministic for the same input but changes system state, so subsequent calls with the same input give different results.

ReactUser¶

function ReactUser(uint64 Soul, uint64 Epsilon) public returns (uint64 Omicron)

- Access: public - Parameters: - Soul (uint64): User's Soul ID - Epsilon (uint64): Input value for reaction - Returns: - Omicron (uint64): User-specific reaction output - Description: Reacts using a specific user's SHIO Rod. - Logic Flow: 1. Get user: Alpha = GetUserBySoul(Soul) 2. React: Omicron = Reactor().ReactShioRod(Alpha.On.Shio, Epsilon ^ Alpha.Entropy) 3. Return Omicron - Side Effects: Triggers GetUserBySoul effects; mints tokens - In Plain English: Run a reaction tied to a specific player. The input is XORed with their entropy, making the result unique to that player. Used for player-specific calculations in chat and territory systems.

Luo¶

function Luo() public onlyOwners returns (uint256 De)

- Access: onlyOwners - Returns: - De (uint256): Unique Luo value for new QING creation - Description: Generates a guaranteed-unique Luo using reaction and modExp. - Logic Flow: 1. Loop until unique: while(De == 0 || Qu[De] != address(0x0)) 2. React: React(On.Omicron) 3. Compute: De = modExp(On.Omega, On.Omicron, Gua) 4. Register: Qu[De] = msg.sender 5. Return De - Computation Details: - De = Omega^Omicron mod Gua where Gua is the universe constant - Loop ensures no collisions with existing Luos - Side Effects: Registers Luo in Qu mapping; updates On via React - In Plain English: Generate a unique identifier for creating a new venue. Uses cryptographic reactions to ensure uniqueness. The Luo becomes the venue's permanent position ID on the map.

AddSystemAddress¶

function AddSystemAddress(string memory Alias, address Address) public onlyOwners

- Access: onlyOwners - Parameters: - Alias (string): Name to register (e.g., "MAP", "WORLD") - Address (address): Contract address - Description: Registers a named system address in the Addresses mapping. - Logic Flow: 1. Check not already registered: if(Addresses[Alias] != address(0x0)) revert SystemAddress 2. Store: Addresses[Alias] = Address 3. Record alias: Aliases.push(Alias) - Side Effects: Updates Addresses mapping and Aliases array - In Plain English: Register an important game contract by name. Creates a directory entry so other contracts can find addresses by name (e.g., Addresses["MAP"]) instead of hardcoding.

AddContractOwner¶

function AddContractOwner(address Contract, address Owner) public onlyOwners

- Access: onlyOwners - Parameters: - Contract (address): Target contract address - Owner (address): Address to grant ownership - Description: Adds an owner to any MultiOwnable contract. - Logic Flow: 1. Call DYSNOMIA(Contract).addOwner(Owner) - Side Effects: Modifies target contract's owner list - In Plain English: Grant admin access to someone on any contract in the ecosystem. Used for system setup and permission management. Only CHO owners can do this.

VerifyUserTokenPermissions¶

function VerifyUserTokenPermissions(address UserToken) public

- Access: public - Parameters: - UserToken (address): LAU token address to verify - Description: Validates that a LAU has proper owner chain setup. - Logic Flow: 1. Check LAU owns its SHIO 2. Check LAU owns its Rod 3. Revert InvalidUserToken if checks fail - Side Effects: None (reverts on failure) - In Plain English: Check that a LAU token is properly set up with all required SHIO and Rod ownership. This prevents malformed player tokens from interacting with the game.

Errors¶

Error	Parameters	Description
InvalidUserToken	Asset	LAU lacks required ownership
InvalidOwnership	UserToken, User	Caller doesn't own LAU
UserNotEntered	User	User not registered
SoulNotEntered	Soul	Soul ID not found
SystemAddress	Address, Alias	Alias already registered

Contract Interactions¶

Depends On¶

DYSNOMIA V2 - Base functionality
VOID - Session management
COREREACTIONSLIB - Reaction library

Depended On By¶

MAP - Uses CHO for Luo generation
QING - User verification
Domain contracts using user authentication

Special Mechanisms¶

User Authentication¶

function Enter(address UserToken) public returns(User memory) {
    // Verify WITHOUT token holder is banned
    assert(DYSNOMIA(WITHOUTContract).balanceOf(tx.origin) == 0);

    // Verify LAU permissions
    VerifyUserTokenPermissions(UserToken);

    // Verify caller owns LAU
    if(!UserLau.owner(tx.origin)) revert InvalidOwnership(...);

    // Create user entry
    Alpha.Soul = UserLau.Saat(1);
    Alpha.On = UserLau.On();
    Alpha.Username = LAU(Alpha.On.Phi).Username();

    // Register
    Delegates[tx.origin] = Alpha;
    DelegateAddresses[Alpha.Soul] = tx.origin;
}

Luo Generation¶

function Luo() public onlyOwners returns (uint256 De) {
    De = 0;
    while(De == 0 || Qu[De] != address(0x0)) {
        React(On.Omicron);
        De = Xiao.modExp(On.Omega, On.Omicron, Gua);
    }
    Qu[De] = msg.sender;
}

Entropy Evolution¶

Each operation updates the system entropy:

function Recall(User memory Alpha) public returns (uint64) {
    (On.Omicron, On.Omega) = Reactor().ReactToLai(On, Entropy ^ Alpha.On.Omicron, ...);
    Entropy = On.Omega;
    return On.Omicron;
}

Contract Verification¶

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