structs.sol

Overview

This Solidity source file defines several struct data types designed to represent core entities related to message verification, staking mechanisms, and license management within a decentralized system. The structs encapsulate data attributes crucial for tracking the state and properties of messages, stakes, licenses, and locking mechanisms used in the application’s business logic. These data structures provide a foundational layer for contract modules that manage reputation, stake delegation, and license status control.

Detailed Descriptions of Structs

MessageInfo

Represents information about a message including its unique identifier and expiration.

• Properties:

  • messageHash (uint256): A cryptographic hash uniquely identifying the message.

  • expireAt (uint32): A timestamp or block number indicating when the message expires and is no longer valid.

• Usage Example:

MessageInfo memory msgInfo = MessageInfo({
    messageHash: keccak256(abi.encodePacked(messageData)),
    expireAt: uint32(block.timestamp + 3600) // expires in one hour
});

MessageInfo is typically used for message validation processes where expiration and integrity checks are necessary.

Stake

Captures staking information related to a participant, including sequence numbers and cryptographic keys.

• Properties:

  • stake (uint256): The amount of tokens or value staked.

  • seqNoStart (uint64): The starting sequence number for a staking period or event.

  • seqNoFinish (uint64): The finishing sequence number for the staking period.

  • bls_key (bytes): A BLS (Boneh-Lynn-Shacham) signature key used for cryptographic validation.

  • status (uint8): Numeric status code representing the stake’s state.

  • signerIndex (uint16): Index of the signer associated with this stake.

• Usage Example:

Stake memory newStake = Stake({
    stake: 1000 ether,
    seqNoStart: 1,
    seqNoFinish: 100,
    bls_key: blsPublicKey,
    status: 1,
    signerIndex: 42
});

Stake is fundamental in handling validator or participant stakes, especially in consensus or slashing mechanisms.

LicenseData

Holds detailed license-related information, including reputation, status, privileges, and stake locking parameters.

• Properties:

  • reputationTime (uint128): Timestamp or measure of accumulated reputation time.

  • status (uint8): Numeric code representing license status (e.g., active, suspended).

  • isPrivileged (bool): Flag indicating if the license has privileged status.

  • stakeController (optional(address)): Optional Ethereum address controlling staking for this license.

  • last_touch (uint64): Timestamp of the last update or interaction.

  • balance (uint128): Current balance associated with the license.

  • lockStake (uint128): Amount of stake locked.

  • lockContinue (uint128): Amount of stake continuation locked.

  • lockCooler (uint128): Amount locked for cooling period.

  • isLockToStake (bool): Flag indicating if locking is enforced to stake.

  • coolerCount (uint32): Count of cooling periods active.

  • isLockToStakeByWallet (bool): Indicates if locking is enforced by wallet ownership.

  • isLockBecauseOfSlashing (bool): Indicates if the lock is due to slashing penalties.

• Usage Example:

LicenseData memory license = LicenseData({
    reputationTime: 100000,
    status: 2,
    isPrivileged: true,
    stakeController: optional(addressStakeController),
    last_touch: uint64(block.timestamp),
    balance: 5000 ether,
    lockStake: 1000 ether,
    lockContinue: 500 ether,
    lockCooler: 200 ether,
    isLockToStake: true,
    coolerCount: 3,
    isLockToStakeByWallet: false,
    isLockBecauseOfSlashing: false
});

This struct supports license lifecycle management, reputation tracking, and enforcement of stake-related constraints.

LicenseStake

Represents the numerical identifier and stake amount associated with a license.

• Properties:

  • num (uint256): Identifier or count related to the license stake.

  • stake (uint128): Amount of stake allocated to the license.

• Usage Example:

LicenseStake memory licStake = LicenseStake({
    num: 12345,
    stake: 2000 ether
});

Used when associating stake data with licenses in accounting or staking modules.

LockStake

Encapsulates stake locking information including the stake value and the finishing timestamp of the lock.

• Properties:

  • value (uint256): The amount of stake locked.

  • timeStampFinish (uint32): The timestamp when the lock expires and stake is releasable.

• Usage Example:

LockStake memory lock = LockStake({
    value: 1000 ether,
    timeStampFinish: uint32(block.timestamp + 86400) // lock expires in 24 hours
});

Critical for enforcing time-based restrictions on stake withdrawals or transfers.

Implementation Details and Algorithms

• The use of uint256, uint128, uint64, uint32, uint16, and uint8 types optimizes storage by matching field size to expected data range, which is a common practice in Solidity to reduce gas costs.

• BLS cryptographic keys in the Stake struct indicate the use of advanced signature schemes, likely supporting threshold signatures or multi-signature validation in consensus algorithms.

• The LicenseData struct uses optional types (e.g., optional(address)) to handle nullable or non-mandatory fields, enabling flexible control over the presence of related addresses.

• Multiple lock-related fields within LicenseData and the separate LockStake struct suggest a layered locking mechanism for stakes, possibly to implement cooldown periods, penalties (slashing), or multi-stage stake release workflows.

Interaction with Other Parts of the System

• The MessageInfo struct is expected to interact with message validation or communication modules, providing expiry control and cryptographic hash verification.

• Stake and LockStake structs are likely used in staking, slashing, and validator management contracts, interacting with reputation and consensus modules.

• LicenseData and LicenseStake play a key role in license management systems, potentially interfacing with reputation tracking, stake delegation, and privilege control components.

• The bls_key field in Stake connects with cryptographic validation libraries or signature verification modules.

• Time-based fields such as expireAt, last_touch, and timeStampFinish indicate that contract logic involves temporal conditions, possibly checked in transaction validation or state update functions.

Visual Diagram: Struct Relationships and Primary Attributes

classDiagram
class MessageInfo {
+uint256 messageHash
+uint32 expireAt
}
class Stake {
+uint256 stake
+uint64 seqNoStart
+uint64 seqNoFinish
+bytes bls_key
+uint8 status
+uint16 signerIndex
}
class LicenseData {
+uint128 reputationTime
+uint8 status
+bool isPrivileged
+optional(address) stakeController
+uint64 last_touch
+uint128 balance
+uint128 lockStake
+uint128 lockContinue
+uint128 lockCooler
+bool isLockToStake
+uint32 coolerCount
+bool isLockToStakeByWallet
+bool isLockBecauseOfSlashing
}
class LicenseStake {
+uint256 num
+uint128 stake
}
class LockStake {
+uint256 value
+uint32 timeStampFinish
}

This diagram illustrates the main structs within the file with their key properties, emphasizing their role as data carriers in the staking and licensing domain.

For further understanding of topics like staking mechanisms, licensing models, and cryptographic key handling, refer to the relevant Staking Fundamentals, License Management, and Cryptography documentation.