Update PRG interface and implementation

CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [email protected]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to the random-coin-toss repo
+
+The following is a set of guidelines for contributing to this Flow repository. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
+
+#### Table Of Contents
+
+[How Can I Contribute?](#how-can-i-contribute)
+
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Enhancements](#suggesting-enhancements)
+- [Pull Requests](#pull-requests)
+
+[Styleguides](#styleguides)
+
+- [Git Commit Messages](#git-commit-messages)
+
+[Additional Notes](#additional-notes)
+
+
+## How Can I Contribute?
+
+You are free to contribute however you want! You can submit a bug report in an issue, suggest an enhancement, or even just make a PR for us to review. We just ask that you are clear in your communication and documentation of all your work so we can understand how you are trying to help.
+
+### Reporting Bugs
+
+#### Before Submitting A Bug Report
+
+- **Search existing issues** to see if the problem has already been reported. If it has **and the issue is still open**, add a comment to the existing issue instead of opening a new one.
+
+#### How Do I Submit A (Good) Bug Report?
+
+Explain the problem and include additional details to help maintainers reproduce the problem:
+
+- **Use a clear and descriptive title** for the issue to identify the problem.
+- **Describe the exact steps which reproduce the problem** in as many details as possible. When listing steps, **don't just say what you did, but explain how you did it**.
+- **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
+- **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior.
+- **Explain which behavior you expected to see instead and why.**
+- **Include screenshots and animated GIFs** which show you following the described steps and clearly demonstrate the problem. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux.
+
+Provide more context by answering these questions:
+
+- **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens.
+
+Include details about your configuration and environment:
+
+- **What's the name and version of the OS you're using**?
+- **What's the name and version of the flow-cli that you are using**?
+
+### Suggesting Enhancements
+
+#### Before Submitting An Enhancement Suggestion
+
+- **Perform a cursory search** to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
+
+#### How Do I Submit A (Good) Enhancement Suggestion?
+
+Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). Create an issue and provide the following information:
+
+- **Use a clear and descriptive title** for the issue to identify the suggestion.
+- **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
+- **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
+- **Describe the current behavior** and **explain which behavior you expected to see instead** and why.
+- **Include screenshots and animated GIFs**. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux.
+- **Explain why this enhancement would be useful** to be included in the standard.
+
+### Pull Requests
+
+The process described here has several goals:
+
+- Maintain code quality
+- Fix problems that are important to users
+
+Please follow the [styleguides](#styleguides) to have your contribution considered by the maintainers.
+Reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
+
+## Styleguides
+
+Before contributing, make sure to examine the project to get familiar with the patterns and style already being used.
+
+### Git Commit Messages
+
+- Use the present tense ("Add feature" not "Added feature")
+- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
+- Limit the first line to 72 characters or less
+- Reference issues and pull requests liberally after the first line
+
+
+### Additional Notes
+
+Thank you for your interest in contributing to the Flow Token Standards!

LICENSE.md

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

README.md

@@ -0,0 +1,32 @@
+# [WIP] Random Coin Toss
+
+> :warning: This repo is still a work in progress
+
+## Overview
+
+The contracts contained in this repo demonstrate how to use Flow's onchain randomness safely - safe randomness here
+meaning non-revertible randomness.
+
+Random sources are committed to the [`RandomBeaconHistory` contract](./contracts/RandomBeaconHistory.cdc) by the service
+account at the end of every block. These random sources are catalogued chronologically, extending historically for every
+associated block height to the initial commitment height.
+
+Used on their own, these random sources are not safe. In other words, using the random source in your contract without
+the framing of a commit-reveal mechanism would enable non-trusted callers to condition their interactions with your contract on the
+random result. In the context of a random coin toss, I could revert my transaction if I didn't win - not a very fair
+game.
+
+To achieve non-revertible randomness, the contract should be structured to resolve in two phases:
+
+1. Commit - Caller commits to the resolution of their bet with some yet unknown source of randomness (i.e. in the
+   future)
+2. Reveal - Caller can then reveal the result of their bet
+
+Though a caller could still condition the revealing transaction on the coin flip result, they've already incurred the
+cost of their bet and would gain nothing by doing so.
+
+## References
+
+- [Secure Random Number Generator Forum Post](https://forum.onflow.org/t/secure-random-number-generator-for-flow-s-smart-contracts/5110)
+- [RandomBeaconHistory PR - flow-core-contracts](https://github.com/onflow/flow-core-contracts/pull/375)
+- [FLIP: On-Chain randomness history for commit-reveal schemes](https://github.com/onflow/flips/pull/123)

SECURITY.md

@@ -0,0 +1,11 @@
+# Responsible Disclosure Policy
+
+Flow was built from the ground up with security in mind. Our code, infrastructure, and development methodology helps us keep our users safe.
+
+We really appreciate the community's help. Responsible disclosure of vulnerabilities helps to maintain the security and privacy of everyone.
+
+If you care about making a difference, please follow the guidelines below.
+
+# **Guidelines For Responsible Disclosure**
+
+We ask that all researchers adhere to these guidelines [here](https://docs.onflow.org/bounties/responsible-disclosure/)

contracts/CoinToss.cdc

@@ -1,13 +1,29 @@
+import "FungibleToken"
 import "FlowToken"
+
 import "RandomBeaconHistory"
-import "PseudoRandomGenerator"
+import "Xorshift128plus"
 
+/// CoinToss is a simple game contract showcasing the safe use of onchain randomness by way of a commit-reveal sheme.
+///
+/// See FLIP 123 for more details: https://github.com/onflow/flips/blob/main/protocol/20230728-commit-reveal.md
+/// And the onflow/random-coin-toss repo for implementation context: https://github.com/onflow/random-coin-toss
+///
 access(all) contract CoinToss {
 
+    /// The Vault used by the contract to store funds.
     access(self) let reserve: @FlowToken.Vault
 
-    access(self) let ReceiptStoragePath: StoragePath
+    /// The canonical path for common Receipt storage
+    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)
 
+    /// The Receipt resource is used to store the bet amount and block height at which the bet was committed.
+    ///
     access(all) resource Receipt {
         access(all) let betAmount: UFix64
         access(all) let commitBlock: UInt64
@@ -18,53 +34,75 @@ access(all) contract CoinToss {
         }
     }
 
-    // PRG implementation is not provided by the FLIP, we assume this contract
-    // imports a suitable PRG implementation
-
-    access(all) fun commitCointoss(bet: @FlowToken.Vault): @Receipt {
+    /* --- Commit --- */
+    //
+    /// 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 {
         let receipt <- create Receipt(
                 betAmount: bet.balance
             )
-        // commit the bet
-        // `self.reserve` is a `@FlowToken.Vault` field defined on the app contract
-        //  and represents a pool of funds
         self.reserve.deposit(from: <-bet)
+
+        emit CoinTossBet(betAmount: receipt.betAmount, commitBlock: receipt.commitBlock, receiptID: receipt.uuid)
+
         return <- receipt
     }
 
-    access(all) fun revealCointoss(receipt: @Receipt): @FlowToken.Vault {
-        let currentBlock = getCurrentBlock().height
-        if receipt.commitBlock >= currentBlock {
-            panic("cannot reveal yet")
+    /* --- 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
+    /// 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 {
+        pre {
+            receipt.commitBlock <= getCurrentBlock().height: "Cannot reveal before commit block"
         }
 
-        let winnings = receipt.betAmount * 2.0
+        let betAmount = receipt.betAmount
+        let commitBlock = receipt.commitBlock
+        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)
+
         destroy receipt
 
         if coin == 1 {
-            return <- (FlowToken.createEmptyVault() as! @FlowToken.Vault)
+            emit CoinTossReveal(betAmount: betAmount, winningAmount: 0.0, commitBlock: commitBlock, receiptID: receiptID)
+            return <- FlowToken.createEmptyVault()
         }
-
-        return <- (self.reserve.withdraw(amount: winnings) as! @FlowToken.Vault)
+
+        let reward <- self.reserve.withdraw(amount: betAmount * 2.0)
+
+        emit CoinTossReveal(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.
+    ///
     access(all) fun randomCoin(atBlockHeight: UInt64, salt: UInt64): UInt8 {
-        // query the Random Beacon history core-contract.
-        // if `blockHeight` is the current block height, `sourceOfRandomness` errors.
+        // 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: "RandomSource block height mismatch")
 
-        // instantiate a PRG object using external `createPRG` that takes a `seed` 
-        // and `salt` and returns a pseudo-random-generator object.
-        let prg <- PseudoRandomGenerator.createPRG(
+        // 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
+                salt: salt.toBigEndianBytes()
             )
 
-        // derive a 64-bit random using the object `prg`
+        // derive a 64-bit random using the PRG object and reduce to a UInt8 value of 1 or 0
         let rand = prg.nextUInt64()
-        destroy prg
 
         return UInt8(rand & 1)
     }
@@ -73,9 +111,9 @@ access(all) contract CoinToss {
         self.reserve <- (FlowToken.createEmptyVault() as! @FlowToken.Vault)
         let seedVault = self.account.borrow<&FlowToken.Vault>(from: /storage/flowTokenVault)!
         self.reserve.deposit(
-            from: <-seedVault.withdraw(amount: 100.0)
+            from: <-seedVault.withdraw(amount: 1000.0)
         )
 
-        self.ReceiptStoragePath = /storage/CoinTossReceipt
+        self.ReceiptStoragePath = StoragePath(identifier: "CoinTossReceipt_".concat(self.account.address.toString()))!
     }
 }