Phiên Onetappy

Hợp đồng này là hợp đồng quyết định/giải quyết xổ số phi tập trung. Nó được tạo bởi một hợp đồng cấu hình.

Khái niệm chính

Tên	Loại	Mô tả
nhà máy	CommitRevealFactory	Hợp đồng cha tạo các phiên, chịu trách nhiệm triển khai các Phiên và tạo Kho bạc liên quan (không được tham chiếu trực tiếp bởi hợp đồng này).
kho bạc	CommitRevealTreasury	Kho chứa quỹ gắn với phiên, chịu trách nhiệm thanh toán, hoàn tiền, đóng băng/mở khóa/cắt tiền gửi, và thanh toán hàng loạt.
quản trị	địa chỉ	Quản trị nền tảng, có quyền quyết định giải quyết cưỡng chế cuối cùng chỉ khi người tạo vắng mặt.
người tạo	địa chỉ	Người tạo phiên (đối tác), chịu trách nhiệm gửi cam kết và tiết lộ kết quả trong pha Reveal.
sessionCommitment	bytes32	Cam kết băm do người tạo nộp khi triển khai, dùng để xác minh tính xác thực của dữ liệu Reveal.
playerCommitment	bytes32	Yếu tố ngẫu nhiên toàn cục được hình thành bằng tích lũy XOR mỗi người chơi bí mật với băm khối trước đó.
ticketToPlayer	address[]	Lập chỉ mục vé → ánh xạ địa chỉ người chơi, dùng để xác định người thắng cuối cùng.
nextTicketIndex	uint256	Chỉ số vé tiếp theo có thể phân bổ (tức là số vé đã bán hiện tại).
ticketCounts	mapping(address => uint256)	Theo dõi số vé mỗi người chơi đã mua.

---

Đảm bảo An ninh & Thiết kế

• Khóa Cam kết-Tiết lộ

  • Người tạo không thể thay đổi kết quả sau khi thấy dữ liệu đầu vào của người chơi

• Ngẫu nhiên đa nguồn

  • của người tạo revealData

  • Tất cả người chơi bí mật giá trị

  • Băm khối trước đó

• Ràng buộc tiền gửi chặt chẽ

  • Vé chưa bán → bồi thường từ tiền gửi

  • Người tạo không tiết lộ → tiền gửi bị tịch thu hoàn toàn

• Giải quyết một chiều

  • _settle() ngăn chặn bất kỳ việc giải quyết trùng lặp nào

  • Tất cả đường dẫn loại trừ lẫn nhau

---

Cấu hình Phiên (SessionConfig)

struct SessionConfig {
    address admin;                                // Địa chỉ quản trị
    address creator;                              // Người tạo phiên
    address treasury;                             // Địa chỉ hợp đồng Kho bạc
    bytes32 sessionCommitment;                    // Cam kết băm của người tạo
    address paymentToken;                         // Token thanh toán (address(0) cho ETH)
    uint256 ticketPrice;                          // Giá mỗi vé
    uint256 totalTickets;                         // Tổng số vé (cũng là độ dài của ticketToPlayer)
    uint16 partnerShareBps;                       // Phần doanh thu đối tác (BPS)
    uint16 platformFeeBps;                        // Tỷ lệ phí nền tảng (BPS)
    uint16 unsoldTicketsPartnerDepositSlashBps;   // Tỷ lệ cắt tiền gửi cho vé chưa bán
    uint16 creatorAbsentPartnerDepositSlashBps;   // Tỷ lệ cắt tiền gửi nếu người tạo vắng mặt
    uint256 commitDurationSeconds;                // Thời lượng pha Commit
    uint256 revealDurationSeconds;                // Thời lượng pha Reveal
    uint256 unlockTimestamp;                      // Dấu thời gian bắt đầu phiên
}

Ràng buộc của Hàm khởi tạo

• quản trị và người tạo không thể là địa chỉ không hợp lệ

• totalTickets > 0

• partnerShareBps + platformFeeBps ≤ 10000

---

Mua và Cam kết Vé (playerBuyAndCommitTicket)

Mô tả

Người chơi mua một số lượng vé xác định trong pha Commit và gửi một bí mật ngẫu nhiên bí mật. Bí mật được trộn với băm khối trước đó vào yếu tố toàn cục playerCommitment để đảm bảo tính không thể dự đoán.

Giao diện Solidity

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

Tham số

Tham số	Loại	Mô tả
quantity	uint256	Số vé cần mua
bí mật	bytes32	Yếu tố ngẫu nhiên do người chơi cung cấp
useBalance	bool	Có ưu tiên sử dụng số dư Kho bạc để thanh toán hay không

Hành vi

1. Chỉ được gọi trong [unlockTimestamp, unlockTimestamp + commitDurationSeconds]

2. Xác thực tồn kho để ngăn bán quá số vé

3. Hỗ trợ:

   • Thanh toán trực tiếp bằng ETH

   • Sử dụng số dư Kho bạc

4. Ghi địa chỉ người chơi vào ticketToPlayer cho mỗi vé

5. Cập nhật:

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

6. Phát sự kiện:

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

---

Tiết lộ và Giải quyết (reveal)

Mô tả

Chỉ được gọi bởi người tạo. Gửi dữ liệu thô và salt, xác minh cam kết, tính toán người chiến thắng và hoàn tất việc chi trả.

Giao diện Solidity

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

Luồng Giải quyết

1. Xác minh:

   keccak256(revealData, salt) == sessionCommitment

2. Đánh dấu trạng thái giải quyết phiên là Bình thường

3. Tính kết quả ngẫu nhiên:

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

4. Mở khóa tất cả tiền gửi của người tạo

5. Gọi Kho bạc để chi trả hàng loạt:

   1. Người tạo nhận phần theo partnerShareBps

   2. Nền tảng nhận phí hoạt động theo platformFeeBps

   3. Người chơi trúng thưởng nhận toàn bộ doanh thu vé còn lại

6. Phát sự kiện:

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

---

Xử lý Vé Chưa Bán

1. Người tạo Kích hoạt Giải quyết

function finalizeTicketsUnsoldSettlement()
    external
    onlyCreator

Điều kiện:

• Pha Commit đã kết thúc

• nextTicketIndex < totalTickets

Hành vi:

• Đánh dấu trạng thái giải quyết là VéChưaBán

• Khấu trừ tiền gửi tỷ lệ với vé đã bán theo unsoldTicketsPartnerDepositSlashBps (để bồi thường cho người mua vé)

• Mở khóa phần còn lại của tiền gửi

---

2. Người chơi Yêu cầu Hoàn gốc và Bồi thường

function creditPrincipalAndPenaltyIfTicketsUnsold()
    external

Hành vi:

• Người chơi yêu cầu cho mỗi vé nắm giữ:

  • Toàn bộ gốc

  • Bồi thường từ tiền gửi của người tạo theo creatorAbsentPartnerDepositSlashBps

  • Mỗi người chơi yêu cầu một cách độc lập

• Các cuộc gọi lặp lại bị từ chối

Sự kiện:

event RefundClaimed(player, totalAmount)

---

Giải quyết khi Người tạo Vắng mặt

1. Quản trị Viên Ép Giải quyết

function finalizeCreatorAbsentSettlement()
    external
    onlyAdmin

Điều kiện:

• Tất cả vé đã bán

• Pha Reveal kết thúc mà không có tiết lộ

Hệ quả:

• Đánh dấu trạng thái giải quyết là NgườiTạoVắngMặt

• Bồi thường cho người dùng theo creatorAbsentPartnerDepositSlashBps; tịch thu tất cả phần còn lại của tiền gửi của người tạo

• Phần tiền gửi chuyển sang Kho bạc làm quỹ bồi thường cho người chơi

• Phần chuyển cho địa chỉ Quản trị như là hình phạt tịch thu

---

2. Người chơi Yêu cầu Gốc + Bồi thường Cao

function creditPrincipalAndCompensationIfCreatorAbsent()
    external

Hành vi:

• Người chơi yêu cầu cho mỗi vé nắm giữ:

  • Gốc

  • Bồi thường trừng phạt cao hơn theo creatorAbsentPartnerDepositSlashBps

  • Bồi thường lấy từ tiền gửi của người tạo

---

Loại Giải quyết (SettlementType)

Giá trị Enum	Mô tả
Bình thường	Tiết lộ bình thường với một người thắng được chọn
VéChưaBán	Vé chưa bán hết; hoàn tiền + bồi thường nhỏ
NgườiTạoVắngMặt	Người tạo vắng mặt; hoàn tiền + bồi thường cao