Add Cadence random in range & commit-reveal helper contract + Cadence tests

contracts/CoinToss.cdc

@@ -1,8 +1,8 @@
+import "Burner"
 import "FungibleToken"
 import "FlowToken"
 
-import "RandomBeaconHistory"
-import "Xorshift128plus"
+import "RandomConsumer"
 
 /// CoinToss is a simple game contract showcasing the safe use of onchain randomness by way of a commit-reveal sheme.
 ///
@@ -12,28 +12,37 @@ import "Xorshift128plus"
 /// NOTE: This contract is for demonstration purposes only and is not intended to be used in a production environment.
 ///
 access(all) contract CoinToss {
-
+    /// The multiplier used to calculate the winnings of a successful coin toss
+    access(all) let multiplier: UFix64
     /// The Vault used by the contract to store funds.
     access(self) let reserve: @FlowToken.Vault
+    /// The RandomConsumer.Consumer resource used to request & fulfill randomness
+    access(self) let consumer: @RandomConsumer.Consumer
 
     /// The canonical path for common Receipt storage
     /// Note: production systems would consider handling path collisions
     access(all) let ReceiptStoragePath: StoragePath
 
     /* --- Events --- */
     //
-    access(all) event CoinTossBet(betAmount: UFix64, commitBlock: UInt64, receiptID: UInt64)
-    access(all) event CoinTossReveal(betAmount: UFix64, winningAmount: UFix64, commitBlock: UInt64, receiptID: UInt64)
+    access(all) event CoinFlipped(betAmount: UFix64, commitBlock: UInt64, receiptID: UInt64)
+    access(all) event CoinRevealed(betAmount: UFix64, winningAmount: UFix64, commitBlock: UInt64, receiptID: UInt64)
 
-    /// The Receipt resource is used to store the bet amount and block height at which the bet was committed.
+    /// The Receipt resource is used to store the bet amount and the associated randomness request. By listing the
+    /// RandomConsumer.RequestWrapper conformance, this resource inherits all the default implementations of the
+    /// interface. This is why the Receipt resource has access to the getRequestBlock() and popRequest() functions
+    /// without explicitly defining them.
     ///
-    access(all) resource Receipt {
+    access(all) resource Receipt : RandomConsumer.RequestWrapper {
+        /// The amount bet by the user
         access(all) let betAmount: UFix64
-        access(all) let commitBlock: UInt64
+        /// The associated randomness request which contains the block height at which the request was made
+        /// and whether the request has been fulfilled.
+        access(all) var request: @RandomConsumer.Request?
 
-        init(betAmount: UFix64) {
+        init(betAmount: UFix64, request: @RandomConsumer.Request) {
             self.betAmount = betAmount
-            self.commitBlock = getCurrentBlock().height
+            self.request <- request
         }
     }
 
@@ -42,97 +51,88 @@ access(all) contract CoinToss {
     /// In this method, the caller commits a bet. The contract takes note of the block height and bet amount, returning a
     /// Receipt resource which is used by the better to reveal the coin toss result and determine their winnings.
     ///
-    access(all) fun commitCoinToss(bet: @{FungibleToken.Vault}): @Receipt {
+    access(all) fun flipCoin(bet: @{FungibleToken.Vault}): @Receipt {
         pre {
             bet.balance > 0.0:
             "Provided vault.balance=0.0 - must deposit a non-zero amount to commit to a coin toss"
             bet.getType() == Type<@FlowToken.Vault>():
             "Invalid vault type=".concat(bet.getType().identifier).concat(" - must provide a FLOW vault")
         }
+        let request <- self.consumer.requestRandomness()
         let receipt <- create Receipt(
-                betAmount: bet.balance
+                betAmount: bet.balance,
+                request: <-request
             )
         self.reserve.deposit(from: <-bet)
 
-        emit CoinTossBet(betAmount: receipt.betAmount, commitBlock: receipt.commitBlock, receiptID: receipt.uuid)
+        emit CoinFlipped(betAmount: receipt.betAmount, commitBlock: receipt.getRequestBlock()!, receiptID: receipt.uuid)
 
         return <- receipt
     }
 
     /* --- Reveal --- */
     //
     /// Here the caller provides the Receipt given to them at commitment. The contract then "flips a coin" with
-    /// randomCoin(), providing the committed block height and salting with the Receipts unique identifier.
-    /// If result is 1, user loses, if it's 0 the user doubles their bet. Note that the caller could condition the
+    /// _randomCoin(), providing the Receipt's contained Request.
+    ///
+    /// If result is 1, user loses, but if it's 0 the user doubles their bet. Note that the caller could condition the
     /// revealing transaction, but they've already provided their bet amount so there's no loss for the contract if
     /// they do.
     ///
-    access(all) fun revealCoinToss(receipt: @Receipt): @{FungibleToken.Vault} {
+    access(all) fun revealCoin(receipt: @Receipt): @{FungibleToken.Vault} {
         pre {
-            receipt.commitBlock <= getCurrentBlock().height:
-            "Provided receipt committed at block height=".concat(receipt.commitBlock.toString()).concat(
+            receipt.request != nil: 
+            "The provided receipt has already been revealed"
+            receipt.getRequestBlock()! <= getCurrentBlock().height:
+            "Provided receipt committed at block height=".concat(receipt.getRequestBlock()!.toString()).concat(
                 " - must wait until at least the following block to reveal"
             )
         }
-
         let betAmount = receipt.betAmount
-        let commitBlock = receipt.commitBlock
+        let commitBlock = receipt.getRequestBlock()!
         let receiptID = receipt.uuid
 
-        // self.randomCoin() errors if commitBlock <= current block height in call to
-        // RandomBeaconHistory.sourceOfRandomness()
-        let coin = self.randomCoin(atBlockHeight: receipt.commitBlock, salt: receipt.uuid)
+        let coin = self._randomCoin(request: <-receipt.popRequest())
 
-        destroy receipt
+        Burner.burn(<-receipt)
 
-        if coin == 1 {
-            emit CoinTossReveal(betAmount: betAmount, winningAmount: 0.0, commitBlock: commitBlock, receiptID: receiptID)
-            return <- FlowToken.createEmptyVault(vaultType: Type<@FlowToken.Vault>())
+        // Deposit the reward into a reward vault if the coin toss was won
+        let reward <- FlowToken.createEmptyVault(vaultType: Type<@FlowToken.Vault>())
+        if coin == 0 {
+            let winningsAmount = betAmount * self.multiplier
+            let winnings <- self.reserve.withdraw(amount: winningsAmount)
+            reward.deposit(
+                from: <-winnings
+            )
         }
 
-        let reward <- self.reserve.withdraw(amount: betAmount * 2.0)
-
-        emit CoinTossReveal(betAmount: betAmount, winningAmount: reward.balance, commitBlock: commitBlock, receiptID: receiptID)
+        emit CoinRevealed(betAmount: betAmount, winningAmount: reward.balance, commitBlock: commitBlock, receiptID: receiptID)
 
         return <- reward
     }
 
-    /// Helper method using RandomBeaconHistory to retrieve a source of randomness for a specific block height and the
-    /// given salt to instantiate a PRG object. A randomly generated UInt64 is then reduced by bitwise operation to
-    /// UInt8 value of 1 or 0 and returned.
+    /// Returns a random number between 0 and 1 using the RandomConsumer.Consumer resource contained in the contract.
     ///
-    access(all) fun randomCoin(atBlockHeight: UInt64, salt: UInt64): UInt8 {
-        // query the Random Beacon history core-contract - if `blockHeight` <= current block height, panic & revert
-        let sourceOfRandomness = RandomBeaconHistory.sourceOfRandomness(atBlockHeight: atBlockHeight)
-        assert(
-            sourceOfRandomness.blockHeight == atBlockHeight,
-            message: "Invalid response: Requested blockHeight=".concat(atBlockHeight.toString()).concat(
-                " but received random source block height=".concat(sourceOfRandomness.blockHeight.toString())
-            )
-        )
-
-        // instantiate a PRG object, seeding a source of randomness with `salt` and returns a pseudo-random
-        // generator object.
-        let prg = Xorshift128plus.PRG(
-                sourceOfRandomness: sourceOfRandomness.value,
-                salt: salt.toBigEndianBytes()
-            )
-
-        // derive a 64-bit random using the PRG object and reduce to a UInt8 value of 1 or 0
-        let rand = prg.nextUInt64()
-
-        return UInt8(rand & 1)
+    access(self) fun _randomCoin(request: @RandomConsumer.Request): UInt8 {
+        return UInt8(self.consumer.fulfillRandomInRange(request: <-request, min: 0, max: 1))
     }
 
-    init() {
+    init(multiplier: UFix64) {
+        // Initialize the contract with a multiplier for the winnings
+        self.multiplier = multiplier
+        // Create a FlowToken.Vault to store the contract's funds
         self.reserve <- FlowToken.createEmptyVault(vaultType: Type<@FlowToken.Vault>())
         let seedVault = self.account.storage.borrow<auth(FungibleToken.Withdraw) &FlowToken.Vault>(
                 from: /storage/flowTokenVault
             )!
         self.reserve.deposit(
             from: <-seedVault.withdraw(amount: 1000.0)
         )
+        // Create a RandomConsumer.Consumer resource
+        self.consumer <-RandomConsumer.createConsumer()
 
+        // Set the ReceiptStoragePath to a unique path for this contract - appending the address to the identifier
+        // prevents storage collisions with other objects in user's storage
         self.ReceiptStoragePath = StoragePath(identifier: "CoinTossReceipt_".concat(self.account.address.toString()))!
     }
 }