Ideologi

We express our gratitude to the Ideologi team for the collaborative engagement that enabled the execution of this Smart Contract Security Assessment.

Hyperlogue allows for brainstorming tournaments (Funded, Unfunded, or TokenExchange) where participants join during a configured time window, optionally paying tokens, and outcomes are finalized by posting a signed Merkle root that drives payouts/refunds. An upgradeable HyperlogueCreator contract enforces backend-signed actions and configurable platform fees, while type-specific libraries handle lifecycle rules, fee accounting, and token/ETH movements for each hyperlogue variant.

The system users should acknowledge all the risks summed up in the risks section of the report

Documentation quality

• Functional requirements are provided.

• • The business logic and the aim of the project are specified.

• Technical description is provided.

Code quality

• The development environment is configured.

• NatSpec covers the code and is detailed.

Test coverage

Code coverage of the project is 80.13% (branch coverage).

• Deployment and basic user interactions are covered with tests.

• Negative cases coverage is present.

• 364 of 364 tests passed.

HyperlogueCreator - Main upgradeable entrypoint contract (UUPS + AccessControl + EIP-712). It validates backend signatures (create/join/post-root), stores all hyperlogue state in a single storage layout, and routes each action to the correct per-type library (Funded, Unfunded, TokenExchange). Also exposes admin/maintainer setters for platform fees/limits and view helpers to query hyperlogues, roots, participants, and config.

FundedHyperlogue - Library implementing the Funded hyperlogue lifecycle: create, join (with optional participant fee), increase max participants, increase creator contribution, reject, refund (batch), post payout merkle root, and claim payouts. Handles ERC20 transfers + fee accounting (contribution fee to treasury; agency fee to creator), enforces timing/participant constraints, and uses a bitmap to prevent double-claims per hyperlogue id.

UnfundedHyperlogue - Library implementing the Unfunded hyperlogue lifecycle: create, join, increase max participants, reject, and post payout merkle root. No token claim flow; instead, it focuses on participant management plus an ETH-based payment model for increasing max participants beyond a configured free tier.

TokenExchangeHyperlogue - Library implementing the Token Exchange hyperlogue lifecycle where creator deposits a payout token, participants contribute a different participant token, and participants later claim payout-token rewards via a merkle root (after a configured reward-claim date). Tracks and distributes dual-token fees (creator-side contribution fee in payout token + participant-side contribution fee in participant token to treasury) and routes the accumulated participant tokens to the creator as “agencyFee/reward”.

SafeERC20WithTaxCheck - Small helper library wrapping safeTransferFrom() to compute the actual amount received (by balance delta) and revert if it’s below a required minimum—useful for fee-on-transfer / taxed tokens.

Structs - Defines the core data model: Hyperlogue, the shared Storage struct (all mappings/sets/bitmaps + configs + signer/treasury/relayer), HyperlogueType, and the config structs used during initialization and fee/limit enforcement.

Events - Central list of emitted events for hyperlogue creation/join/refund/rejection, payout root posting, claims, and config/admin changes.

Errors - Central list of custom errors used across the contract and libraries (signature/timing/role/type/fee/participant-limit validation, refund/claim gating, etc.).

Privileged roles

HyperlogueCreator uses OpenZeppelin AccessControlUpgradeable (and UUPSUpgradeable for upgrades) as its access control mechanism. It defines the following roles with the following capabilities:

• DEFAULT_ADMIN_ROLE can:

• • setSigner()

  • setResultPostRelayer()

  • setTreasury()

  • setAgencyFeePercentageThresholdForFundedHyperlogues()

  • setMaxContributionFeePercentage()

  • authorize upgrades via _authorizeUpgrade() (upgrade the implementation)

• MAINTAINER_ROLE can:

• • setContributionFeePercentage()

  • setInitiatorPlatformFee()

  • setParticipantPlatformFee()

  • setInitiatorPeripheryPlatformFee()

  • setFreeParticipantsForUnfundedHyperlogues()

  • setPerParticipantFeeForUnfundedHyperlogues()

  • setMinOffsetForSubmissionStart()

  • setDefaultPostResultsGraceOffset()

  • setMaxPostResultsGraceOffset()

  • setMinimumMaxParticipants()

  • setMaxRewardClaimOffsetForTokenExchangeHyperlogues()

• MODERATOR_ROLE can:

• • rejectHyperlogue()

It also relies on privileged addresses (not roles) that gate critical actions:

• signer (backend EIP-712 signer) effectively authorizes:

• • createHyperlogue()

  • joinHyperlogue()

  • postPayoutRoot()

• resultPostRelayer can (depending on time window enforced in the libraries):

• • postPayoutRoot() after maxReleaseTimeByAgent

• treasury:

• • receives protocol fees; claimEth() (callable by anyone) transfers all ETH balance to treasury

FundedHyperlogue is a library and does not define AccessControl roles; privileged behavior is enforced via actor/time checks:

• Hyperlogue creator can:

• • increaseMaxParticipants()

  • increaseCreatorContribution()

  • postPayoutRoot() before maxReleaseTimeByAgent

• resultPostRelayer can:

• • postPayoutRoot() after maxReleaseTimeByAgent

• Moderator (MODERATOR_ROLE on HyperlogueCreator) can:

• • rejectHyperlogue() (via HyperlogueCreator routing into the library)

Other flows are generally permissionless (but condition-gated), e.g.:

• refundHyperlogue() (batch refunds when minimum participants not reached)

• claimFeesFromHyperlogue() (once root is posted and minimum participants reached)

UnfundedHyperlogue is a library and does not define AccessControl roles; privileged behavior is enforced via actor/time checks:

• Hyperlogue creator can:

• • increaseMaxParticipants()

  • postPayoutRoot() before maxReleaseTimeByAgent

• resultPostRelayer can:

• • postPayoutRoot() after maxReleaseTimeByAgent

• Moderator (MODERATOR_ROLE on HyperlogueCreator) can:

• • rejectHyperlogue() (via HyperlogueCreator routing into the library)

TokenExchangeHyperlogue is a library and does not define AccessControl roles; privileged behavior is enforced via actor/time checks:

• Hyperlogue creator can:

• • increaseMaxParticipants()

  • increaseCreatorContribution()

  • postPayoutRoot() before maxReleaseTimeByAgent

• resultPostRelayer can:

• • postPayoutRoot() after maxReleaseTimeByAgent

• Moderator (MODERATOR_ROLE on HyperlogueCreator) can:

• • rejectHyperlogue() (via HyperlogueCreator routing into the library)

Other flows are permissionless (but condition-gated), e.g.:

• claimFromHyperlogue() (requires rewardClaimDate reached, valid merkle proof, and minimum participants)

• claimFeesFromHyperlogue() (once root is posted and minimum participants reached)

The scope of the project includes the following smart contracts from the provided repository:

Assets in Scope