Onetappy Session

This contract is a decentralized decision-making/lottery settlement contract. It is created by a configuration contract.

Key Concepts

Name	Type	Description
factory	CommitRevealFactory	Parent contract that creates sessions, responsible for deploying Sessions and creating the associated Treasury (not directly referenced by this contract).
treasury	CommitRevealTreasury	Funds vault bound to the session, responsible for payments, refunds, deposit freeze/unlock/slash, and batch payouts.
admin	address	Platform administrator, has final forced settlement authority only when the creator is absent.
creator	address	Session creator (partner), responsible for submitting the commitment and revealing the result in the Reveal phase.
sessionCommitment	bytes32	Hash commitment submitted by the creator at deployment, used to verify the authenticity of Reveal data.
playerCommitment	bytes32	Global random factor formed by XOR-accumulating each player's secret with the previous block hash.
ticketToPlayer	address[]	Ticket index → player address mapping, used to locate the final winner.
nextTicketIndex	uint256	The next assignable ticket index (i.e., current number of tickets sold).
ticketCounts	mapping(address => uint256)	Tracks the number of tickets purchased by each player.

---

Security & Design Guarantees

• Commit-Reveal Lock

  • The creator cannot change the result after seeing player inputs

• Multi-source Randomness

  • Creator's revealData

  • All players' secret values

  • Previous block hash

• Strong Deposit Constraints

  • Unsold tickets → deposit compensation

  • Creator does not reveal → deposit fully slashed

• One-way Settlement

  • _settle() prevents any duplicate settlement

  • All paths are mutually exclusive

---

Session Configuration (SessionConfig)

struct SessionConfig {
    address admin;                                // Administrator address
    address creator;                              // Session creator
    address treasury;                             // Treasury contract address
    bytes32 sessionCommitment;                    // Creator hash commitment
    address paymentToken;                         // Payment token (address(0) for ETH)
    uint256 ticketPrice;                          // Price per ticket
    uint256 totalTickets;                         // Total tickets (also the length of ticketToPlayer)
    uint16 partnerShareBps;                       // Partner revenue share (BPS)
    uint16 platformFeeBps;                        // Platform fee ratio (BPS)
    uint16 unsoldTicketsPartnerDepositSlashBps;   // Deposit slash ratio for unsold tickets
    uint16 creatorAbsentPartnerDepositSlashBps;   // Deposit slash ratio if creator is absent
    uint256 commitDurationSeconds;                // Duration of the Commit phase
    uint256 revealDurationSeconds;                // Duration of the Reveal phase
    uint256 unlockTimestamp;                      // Session start timestamp
}

Constructor Constraints

• admin and creator cannot be zero addresses

• totalTickets > 0

• partnerShareBps + platformFeeBps ≤ 10000

---

Buy and Commit Ticket (playerBuyAndCommitTicket)

Description

Players purchase a specified number of tickets during the Commit phase and submit a random secret secret. The secret is mixed with the previous block hash into the global playerCommitment to ensure unpredictability.

Solidity Interface

function playerBuyAndCommitTicket(
    uint256 quantity,
    bytes32 secret,
    bool useBalance
) external payable

Parameters

Parameter	Type	Description
quantity	uint256	Number of tickets to purchase
secret	bytes32	Random factor provided by the player
useBalance	bool	Whether to prioritize using Treasury balance for payment

Behavior

1. Only callable within [unlockTimestamp, unlockTimestamp + commitDurationSeconds]

2. Validates inventory to prevent overselling

3. Supports:

   • Direct ETH payment

   • Using Treasury balance

4. Writes player address into ticketToPlayer for each ticket

5. Updates:

   playerCommitment ^= secret ^ blockhash(block.number - 1)

6. Emits:

   event TicketsPurchased(address indexed player, uint256 quantity, uint256 nextIndex);

---

Reveal and Settle (reveal)

Description

Only callable by the creator. Submits raw data and salt, verifies the commitment, calculates the winner, and completes the payout.

Solidity Interface

function reveal(bytes calldata revealData, bytes32 salt)
    external
    onlyCreator

Settlement Flow

1. Verify:

   keccak256(revealData, salt) == sessionCommitment

2. Mark session settlement state as Normal

3. Calculate random result:

   keccak256(revealData, playerCommitment);winnerIndex = result % totalTickets;

4. Unfreeze all creator deposits

5. Call Treasury batch payout:

   1. Creator receives share per partnerShareBps

   2. Platform receives operating fee per platformFeeBps

   3. Winning player receives all remaining ticket revenue

6. Emits:

   event WinnerSelected(winner, ticketIndex)event SessionSettled(Normal)

---

Unsold Tickets Handling

1. Creator Triggers Settlement

function finalizeTicketsUnsoldSettlement()
    external
    onlyCreator

Conditions:

• Commit phase has ended

• nextTicketIndex < totalTickets

Behavior:

• Marks settlement state as UnsoldTickets

• Deducts deposit proportional to sold tickets per unsoldTicketsPartnerDepositSlashBps (to compensate ticket buyers)

• Unlocks remaining deposit

---

2. Player Claims Principal and Compensation

function creditPrincipalAndPenaltyIfTicketsUnsold()
    external

Behavior:

• Player claims per ticket held:

  • Full principal

  • Compensation from creator deposit per creatorAbsentPartnerDepositSlashBps

  • Each player claims independently

• Repeated calls are rejected

Event:

event RefundClaimed(player, totalAmount)

---

Creator Absent Settlement

1. Admin Force Settlement

function finalizeCreatorAbsentSettlement()
    external
    onlyAdmin

Conditions:

• All tickets sold

• Reveal phase ended with no reveal

Consequences:

• Marks settlement state as CreatorAbsent

• Compensates users per creatorAbsentPartnerDepositSlashBps; forfeits all remaining creator deposit

• Portion of deposit transferred to Treasury as player compensation pool

• Portion transferred to Admin address as forfeiture penalty

---

2. Player Claims Principal + High Compensation

function creditPrincipalAndCompensationIfCreatorAbsent()
    external

Behavior:

• Player claims per ticket held:

  • Principal

  • Higher punitive compensation per creatorAbsentPartnerDepositSlashBps

  • Compensation sourced from creator deposit

---

Settlement Types (SettlementType)

Enum Value	Description
Normal	Normal reveal with a winner selected
UnsoldTickets	Tickets not fully sold; refunds + small compensation
CreatorAbsent	Creator absent; refunds + high compensation