Skip to content

Registry

Overview

Registry is a flexible key-value storage contract supporting multiple data types. It provides a generic storage mechanism with type conversion utilities and ordered key tracking.

What This Means For Players

Plain English Summary: Registry is a general-purpose database that can store any type of data. It's like a universal key-value storage locker where you can save information by name (key) and retrieve it later. The game uses it for various internal bookkeeping.

Real-World Analogy: Think of Registry like a safe deposit box facility at a bank. Each box has a unique number (key), and you can store whatever you want inside (value). You can check if a box exists, count how many boxes are used, and retrieve contents by box number.

How It Affects Your Gameplay: - System storage - The game uses registries to store internal data - No overwrites - Once data is stored, it can only be removed (not changed) - Type flexible - Can store strings, numbers, or addresses with the same interface

State Variables

Variable Type Visibility Description
_values mapping(bytes => bytes) private Key-value storage
_inserted mapping(bytes => bool) private Tracks if key exists
_indexOf mapping(bytes => uint256) private Key position in array
_keys bytes[] private Ordered list of all keys

Read Functions

Get (by key)

function Get(bytes memory key) public view returns (bytes memory)
- Access: public view - Parameters: - key (bytes): Key bytes to look up - Returns: - bytes: Value stored under that key - Description: Direct mapping lookup of _values[key]. - In Plain English: Look up a stored value by its name (key). Like opening a safe deposit box with its number to see what's inside.

Get (by index)

function Get(uint256 idx) public view returns (bytes memory)
- Access: public view - Parameters: - idx (uint256): Index in the _keys array - Returns: - bytes: Value at _values[_keys[idx]] - Description: Accesses value by array index for enumeration. - Logic Flow: 1. Get key at index: _keys[idx] 2. Return value: _values[_keys[idx]] - In Plain English: Retrieve a stored value by its position number. Useful for iterating through all stored items in order.

Inserted (multiple overloads)

function Inserted(bytes memory what) public view returns (bool)
function Inserted(string memory what) public view returns (bool)
function Inserted(uint64 what) public view returns (bool)
function Inserted(uint256 what) public view returns (bool)
function Inserted(address what) public view returns (bool)
- Access: public view - Parameters: - what (various types): Key to check existence for - Returns: - bool: True if key exists in _inserted mapping - Description: Type-specific wrappers that convert to bytes and check _inserted mapping. - In Plain English: Verify whether data has already been registered before adding new entries. Use this to avoid duplicates or confirm something exists without fetching its contents.

Count

function Count() public view returns (uint256)
- Access: public view - Returns: - uint256: Length of _keys array (number of registered entries) - In Plain English: Get the total number of items stored in the registry. Useful for knowing how many entries exist before iterating through them.

GetHashByIndex

function GetHashByIndex(uint256 index) public view returns (bytes memory)
- Access: public view - Parameters: - index (uint256): Array index to look up - Returns: - bytes: Key stored at _keys[index] - In Plain English: Get the key name at a specific position. Useful when you want to iterate through all stored keys and their values.

Write Functions

Register (many overloads)

function Register(bytes memory key, bytes memory value) public onlyOwners
function Register(string memory key, string memory value) public onlyOwners
function Register(string memory key, uint64 value) public onlyOwners
function Register(string memory key, uint256 value) public onlyOwners
function Register(string memory key, address value) public onlyOwners
function Register(uint64 key, string memory value) public onlyOwners
// ... and many more combinations
- Access: onlyOwners - Parameters: - key (various types): Key to store under - value (various types): Value to store - Description: Registers a new key-value pair if key doesn't already exist. - Logic Flow: 1. Convert key/value to bytes (if needed) 2. If !_inserted[key]: - Set _inserted[key] = true - Store index: _indexOf[key] = _keys.length - Store value: _values[key] = value - Add to array: _keys.push(key) - Side Effects: Updates _inserted, _indexOf, _values mappings and _keys array - In Plain English: Store a new piece of data under a name (key). Works with different data types - strings, numbers, or addresses. Note: you can only add new keys, not overwrite existing ones.

Remove (multiple overloads)

function Remove(bytes memory key) public onlyOwners
function Remove(string memory key) public onlyOwners
function Remove(uint64 key) public onlyOwners
function Remove(uint256 key) public onlyOwners
function Remove(address key) public onlyOwners
- Access: onlyOwners - Parameters: - key (various types): Key to remove - Description: Removes a key-value pair using swap-and-pop for array efficiency. - Logic Flow: 1. Convert key to bytes (if needed) 2. Delete from mappings: _inserted, _values 3. Swap with last element: _keys[index] = _keys[length-1] 4. Update swapped element's index: _indexOf[lastKey] = index 5. Pop array: _keys.pop() - Side Effects: Updates all mappings and shrinks _keys array - In Plain English: Delete a stored entry by its key. The data is permanently removed from the registry, and the key can potentially be reused later.

Utility Functions

Uint64ToBytes

function Uint64ToBytes(uint64 what) public pure returns (bytes memory)
- Description: Converts uint64 to 8-byte representation - In Plain English: Prepare a 64-bit number for storage by converting it to the registry's internal format. Required when storing Soul IDs or other numeric identifiers that need to be looked up later.

Uint256ToBytes

function Uint256ToBytes(uint256 what) public pure returns (bytes memory)
- Description: Converts uint256 to 32-byte representation - In Plain English: Prepare a large number (like token amounts or Waat positions) for storage by converting it to the registry's internal format.

AddressToBytes

function AddressToBytes(address what) public pure returns (bytes memory)
- Description: Converts address to 20-byte representation - In Plain English: Prepare a contract or wallet address for storage by converting it to the registry's internal format. Useful when indexing data by who owns it or where it came from.

Contract Interactions

Depends On

Depended On By

  • Any contract needing generic storage

Special Mechanisms

No Overwrites

Register only adds new keys - it won't overwrite existing values: 

if(!_inserted[key]) {
    _inserted[key] = true;
    _indexOf[key] = _keys.length;
    _values[key] = value;
    _keys.push(key);
}

Efficient Removal

Remove uses swap-and-pop pattern to maintain array without gaps: 

bytes memory lastKey = _keys[_keys.length - 1];
_indexOf[lastKey] = index;
_keys[index] = lastKey;
_keys.pop();

Type Agnostic Storage

Everything is stored as bytes internally. Type-specific overloads handle conversion: - strings → bytes directly - uint64 → 8 bytes (little-endian) - uint256 → 32 bytes (little-endian) - address → 20 bytes

Usage Pattern

Registry registry = new Registry();

// Store values
registry.Register("myKey", "myValue");
registry.Register("userId", uint64(12345));
registry.Register(someAddress, "Alice");

// Check existence
bool exists = registry.Inserted("myKey");

// Retrieve
bytes memory value = registry.Get("myKey");

// Iterate
uint256 count = registry.Count();
for(uint256 i = 0; i < count; i++) {
    bytes memory key = registry.GetHashByIndex(i);
    bytes memory val = registry.Get(i);
}

// Remove
registry.Remove("myKey");

Gas Considerations

  • Insert: O(1) plus mapping writes
  • Get: O(1)
  • Remove: O(1) due to swap-and-pop
  • Count: O(1)
  • Enumeration: O(n)

Contract Verification

Property Value
Keccak256 Hash 0xcb6c1fa88f25cc768a872653807808641d3e699291a176cdf5b1586ee06ff665
Source URL https://raw.githubusercontent.com/busytoby/atropa_pulsechain/main/solidity/dysnomia/lib/registry.sol
Hash Generated 2026-02-08T00:29:08Z