Architecture

The technical flow on the platform for the player using Chainlink-integrated chains (ZKasino uses the Subscription method) happens in two transaction and goes as follows:

Transaction 1: Wager and VRF request

The first transaction consists of placing the wager, paying the VRF fee, receiving a VRF refund and initiating the VRF request:

1. Wager

   • A player calls the Game_Play function on any Game Contract and places a wager. The wager (bet token) is transferred to the Game Contract.

2. VRF fee

   • An estimation of the VRF fee is charged upfront in the native token for regular play.

3. VRF refund

   • In the same transaction a partial refund of the VRF fee is sent to the player when the player has initially overpaid for the VRF cost.

     • Randomizer allows an extra refund the next time you play on the same contract if the cost of the callback was superior to the cost estimation.

4. VRF request

   • The VRF fee is transferred to the Game Contract (or to the Randomizer VRF contract) and the Game Contract (consumer) calls the requestRandomWords function on the VRFCoordinator contract. The VRFCoordinator emits an event to indicate that a VRF callback should be made.

Architecture diagram

Transaction 2: VRF callback and payout

1. The Chainlink node listens to the request randomness events from the VRFCoordinator, generates randomness by mixing the private key with the blockhash of the request and calls the fulfillRandomWords (callback VRF function) on the VRFCoordinator. If there are multiple pending requests the BatchVRFCoordinator is called instead with multiple fulfilments and forwards those to the VRFCoordinator. The Chainlink node waits for requestConfirmations (number in blocks) before responding. ZKasino has set the number of blocks at 3 for Polygon and 1 for Arbitrum.

2. The VRFCoordinator calls the rawFulfillRandomWords on the Game contract.

3. The Game Contract determines the outcome and transfers the wager to the Diamond Contract (bankroll).

4. When the player draws or wins, the bankroll sends the payout to the player at the same time. When the player loses, there is no payout and the bankroll keeps the wager.

Notes

The infrastructure is non-custodial. Player's funds are never at risk. If the VRF request fails or if the bankroll can't payout, the transaction either reverts or the wager gets stuck in the Game Contract. The player can then remove their bet with the refund function at Pending VRF Requests on their profile page.

While there is a refund mechanism, it is not possible to frontrun transactions for illicit gain. For example, one could try scanning the mempool for losses, frontrunning those transactions to refund them and then only keeping wins. However, this is not possible. On Polygon it is not possible, because refunds only become available when the VRF callback has already become invalid. Furthermore, Arbitrum does not have a mempool.

For more information on the Chainlink VRF, read the Chainlink docs: https://docs.chain.link/vrf/v2/subscription. Chainlink's VRF contracts can be found here: https://github.com/smartcontractkit/chainlink/tree/develop/contracts/src/v0.8/vrf.