> For the complete documentation index, see [llms.txt](https://onetappy.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onetappy.gitbook.io/docs/onetappy-docs/onetappy-factory.md).

# Onetappy Factory

This contract is a parent contract used to create Commit-Reveal sessions and manage partners and the session treasury.

### Key Concepts

| Name                                  | Type                       | Description                                                                                                                                  |
| ------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `treasury`                            | `CommitRevealTreasury`     | Treasury created and associated internally by the factory contract, used to manage platform and partner deposits, earnings, and other funds. |
| `admin`                               | `address`                  | Administrator address (the account that deployed the contract), with global configuration and emergency permissions.                         |
| `platformFeeBps`                      | `uint16`                   | Platform fee in basis points (bps).                                                                                                          |
| `creatorAbsentPartnerDepositSlashBps` | `uint16`                   | Penalty ratio (bps) applied to partner deposits when the Creator is absent.                                                                  |
| `_isPartner`                          | `mapping(address => bool)` | Partner whitelist mapping, marks whether an address is a registered partner.                                                                 |
| `BPS_DENOMINATOR`                     | `uint256`                  | Basis point denominator constant, fixed at `10_000`.                                                                                         |

***

### Check Partner (`isPartner`)

Checks whether a specified address is a registered partner.

```solidity
function isPartner(address account) public view returns (bool)
```

**Parameters:**

| Parameter | Type      | Description          |
| --------- | --------- | -------------------- |
| `account` | `address` | The address to check |

**Return Value:**

* `true`: The address is a partner
* `false`: The address is not a partner

***

### Set Partner (`setPartner`)

Adds or removes a partner. Only callable by the administrator (`admin`).

```solidity
function setPartner(address partner, bool enabled) external onlyAdmin
```

**Parameters:**

| Parameter | Type      | Description                                      |
| --------- | --------- | ------------------------------------------------ |
| `partner` | `address` | Partner address (cannot be zero address)         |
| `enabled` | `bool`    | `true` to add partner, `false` to remove partner |

**Events Emitted:**

* `PartnerAdded` emitted when a partner is added
* `PartnerRemoved` emitted when a partner is removed

***

### Set Platform Fee (`setPlatformFeeBps`)

Sets the platform fee ratio in basis points (bps). Only callable by the administrator.

```solidity
function setPlatformFeeBps(uint16 bps) external onlyAdmin
```

**Parameters:**

| Parameter | Type     | Description                      |
| --------- | -------- | -------------------------------- |
| `bps`     | `uint16` | Platform fee ratio (0 \~ 10,000) |

***

### Set Creator Absent Slash Ratio (`setCreatorAbsentPartnerDepositSlashBps`)

Sets the penalty ratio applied to partner deposits when the Creator is absent (bps). Only callable by the administrator.

```solidity
function setCreatorAbsentPartnerDepositSlashBps(uint16 bps) external onlyAdmin
```

**Parameters:**

| Parameter | Type     | Description                 |
| --------- | -------- | --------------------------- |
| `bps`     | `uint16` | Penalty ratio (0 \~ 10,000) |

***

### Create Session (`createSession`)

Creates a new Commit-Reveal session by a partner. The function validates fee ratios and partner deposit balances, and locks the corresponding deposit in the Treasury.

```solidity
function createSession(
    SessionConfig memory partialConfig
) external onlyPartner returns (address)
```

**Parameters:**

`partialConfig`:

```solidity
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
}
```

Selected field descriptions:

| Field                                 | Type      | Description                                            |
| ------------------------------------- | --------- | ------------------------------------------------------ |
| `sessionCommitment`                   | `bytes32` | Session commitment value (required, cannot be 0)       |
| `paymentToken`                        | `address` | Payment token address; `address(0)` indicates ETH      |
| `ticketPrice`                         | `uint256` | Price per ticket                                       |
| `totalTickets`                        | `uint256` | Total number of tickets                                |
| `commitDurationSeconds`               | `uint256` | Duration of the Commit phase (seconds)                 |
| `revealDurationSeconds`               | `uint256` | Duration of the Reveal phase (seconds)                 |
| `unlockTimestamp`                     | `uint256` | Session unlock timestamp                               |
| `partnerShareBps`                     | `uint16`  | Partner revenue share (bps)                            |
| `unsoldTicketsPartnerDepositSlashBps` | `uint16`  | Deposit penalty ratio for unsold tickets (bps)         |
| `creatorAbsentPartnerDepositSlashBps` | `uint16`  | Deposit penalty ratio if partner does not reveal (bps) |

**Validation Logic:**

* `sessionCommitment` cannot be empty
* `partnerShareBps + platformFeeBps ≤ 10,000`
* Partner's available deposit in Treasury ≥ `ticketPrice * totalTickets`

**Return Value:**

* Address of the newly created `CommitRevealSession` contract

**Events Emitted:**

* `SessionCreated`

***

### Emergency Unlock Partner Deposit (`emergencyUnlockPartnerDeposit`)

Admin emergency unlock of a partner's deposit in a specific Session. Only callable by the administrator. The deposit is unlocked and transferred to the partner address that created the contract.

```solidity
function emergencyUnlockPartnerDeposit(
    address session,
    address partner
) external onlyAdmin
```

***

### Events

#### `SessionCreated`

```solidity
event SessionCreated(
    address indexed creator,
    address indexed session,
    SessionConfig config
);
```

Triggered when a new Commit-Reveal session is successfully created and registered in the Treasury.

***

#### `PartnerAdded`

```solidity
event PartnerAdded(address partner);
```

Triggered when a new partner is added.

***

#### `PartnerRemoved`

```solidity
event PartnerRemoved(address partner);
```

Triggered when a partner is removed.
