From f56ff240bbe567e0a7869957093c9e6a1e550c0f Mon Sep 17 00:00:00 2001 From: Tarak Ben Youssef Date: Thu, 26 Oct 2023 12:34:45 -0600 Subject: [PATCH 1/8] doc for revertible random function --- docs/cadence/language/built-in-functions.mdx | 42 +++++++++++--------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/docs/cadence/language/built-in-functions.mdx b/docs/cadence/language/built-in-functions.mdx index 375ebc7976..225edbb2aa 100644 --- a/docs/cadence/language/built-in-functions.mdx +++ b/docs/cadence/language/built-in-functions.mdx @@ -29,39 +29,43 @@ Use this function for internal sanity checks. The message argument is optional. -## `unsafeRandom` +## `revertibleRandom` ```cadence -fun unsafeRandom(): UInt64 +fun revertibleRandom(): UInt64 ``` + +`unsafeRandom()` function currently behaves the same way as `revertibleRandom()`. +`unsafeRandom` will be deprecated in the next release of Cadence. + + Returns a pseudo-random number. - -Smart contract developers should be mindful about the limitations of unsafeRandom. -The stream of random numbers produced is potentially unsafe in the following two regards: +The random number returned is safe as it is backed by a distributed source of randomness, +that is unbiased, unpredictable and verifiable. -1. The sequence of random numbers is potentially predictable by transactions within the same block -and by other smart contracts calling into your smart contract. -2. A transaction calling into your smart contract can potentially bias the sequence of random numbers which -your smart contract internally generates. +The random number cannot be biased or predicted by miners or by other transactions or code +running before a call to `revertibleRandom`. -The Flow project is working towards removing these limitations incrementally. -Once Flow addressed these points and randomness is safe, -the "unsafe" qualifier is going to get removed. +Moreover, the sequence of returned random numbers is different per block, and per transaction +within the same block. -Nevertheless, there is an additional safety-relevant aspect that developers need to be mindful about: + +There is an additional safety-relevant aspect that developers need to be mindful about. + +The function is not immune to post-selection manipulation by a non-trusted party where +a random number is sampled and then rejected. -A transaction can atomically revert all its actions at any time. +A transaction can atomically revert all its actions. Therefore, it is possible for a transaction calling into a smart contract to post-select favorable results and revert the transaction for unfavorable results. +The function remains totally safe when called by a trusted party. + This limitation is inherent to any smart contract platform that allows transactions to roll back atomically -and cannot be solved through safe randomness alone. -Providing additional Cadence language primitives to simplify this challenge for developers is on the roadmap. -Nevertheless, with safe randomness, points 1 and 2 above resolved, -developers can prevent clients from post-select favorable outcomes using approaches such as described in the -[Smart Contract Security Best Practices](https://consensys.github.io/smart-contract-best-practices/development-recommendations/general/public-data/). +and cannot be solved through safe randomness alone. Flow protocol has suggested a [solution to implement safe +commit-reveal schemes](https://github.com/onflow/flips/pull/123) and address this limitation. ## `RLP` From 61255e69c38ea8bc70104d0175218c6a9704374b Mon Sep 17 00:00:00 2001 From: Tarak Ben Youssef Date: Mon, 6 Nov 2023 14:17:29 -0600 Subject: [PATCH 2/8] add unsafeRandom and update revertibleRandom content --- docs/cadence/language/built-in-functions.mdx | 47 +++++++++++++------- 1 file changed, 31 insertions(+), 16 deletions(-) diff --git a/docs/cadence/language/built-in-functions.mdx b/docs/cadence/language/built-in-functions.mdx index 225edbb2aa..9cd7494fe7 100644 --- a/docs/cadence/language/built-in-functions.mdx +++ b/docs/cadence/language/built-in-functions.mdx @@ -36,36 +36,51 @@ fun revertibleRandom(): UInt64 ``` -`unsafeRandom()` function currently behaves the same way as `revertibleRandom()`. -`unsafeRandom` will be deprecated in the next release of Cadence. +`unsafeRandom()` function currently behaves the same way as `revertibleRandom()`, +and will be deprecated in the next Cadence release. Returns a pseudo-random number. -The random number returned is safe as it is backed by a distributed source of randomness, -that is unbiased, unpredictable and verifiable. +The sequence of returned random numbers is independent for +every transaction in each block. -The random number cannot be biased or predicted by miners or by other transactions or code -running before a call to `revertibleRandom`. +Under the hood, Cadence instantiates a cryptographically-secure pseudo-random number +generator (CSPRG) for each transaction independently, where the seeds of any two transactions +are different with near certainty. -Moreover, the sequence of returned random numbers is different per block, and per transaction -within the same block. +The random numbers returned are unpredictable +(unpredictable for miners at block construction time, +and unpredictable for cadence logic at time of call), +verifiable, as well as unbiasable by miners and previously-running Cadence code. - -There is an additional safety-relevant aspect that developers need to be mindful about. +Nevertheless, developers need to be mindful to use `revertibleRandom()` correctly. -The function is not immune to post-selection manipulation by a non-trusted party where -a random number is sampled and then rejected. + -A transaction can atomically revert all its actions. -Therefore, it is possible for a transaction calling into a smart contract +A transaction can atomically revert all its action. +It is possible for a transaction submitted by an untrusted party to post-select favorable results and revert the transaction for unfavorable results. -The function remains totally safe when called by a trusted party. + + +The function usage remains safe when called by a trusted party that does not +perform post-selection on the returned random numbers. This limitation is inherent to any smart contract platform that allows transactions to roll back atomically -and cannot be solved through safe randomness alone. Flow protocol has suggested a [solution to implement safe +and cannot be solved through safe randomness alone. +Flow protocol has suggested a [solution to implement safe commit-reveal schemes](https://github.com/onflow/flips/pull/123) and address this limitation. + + +## `unsafeRandom` + +This function is superseded by `revertibleRandom()`. +`unsafeRandom` has the same interface and implementation as `revertibleRandom()` although +it is called unsafe. + + +`unsafeRandom` will be deprecated in the next Cadence release. Use `revertibleRandom()` instead. ## `RLP` From 5a34b03397e9e3e724c97101c81824b1e13dfd8e Mon Sep 17 00:00:00 2001 From: Tarak Ben Youssef Date: Mon, 6 Nov 2023 14:20:27 -0600 Subject: [PATCH 3/8] add FLIP120 link --- docs/cadence/language/built-in-functions.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/cadence/language/built-in-functions.mdx b/docs/cadence/language/built-in-functions.mdx index 9cd7494fe7..bc47a982d9 100644 --- a/docs/cadence/language/built-in-functions.mdx +++ b/docs/cadence/language/built-in-functions.mdx @@ -53,6 +53,7 @@ The random numbers returned are unpredictable (unpredictable for miners at block construction time, and unpredictable for cadence logic at time of call), verifiable, as well as unbiasable by miners and previously-running Cadence code. +See [FLIP120](https://github.com/onflow/flips/pull/120) for more details. Nevertheless, developers need to be mindful to use `revertibleRandom()` correctly. From 516d33154dc4ed872fe5b5c9c34a19a1fc194d29 Mon Sep 17 00:00:00 2001 From: Tarak Ben Youssef Date: Mon, 6 Nov 2023 16:42:11 -0600 Subject: [PATCH 4/8] add forum post link --- docs/cadence/language/built-in-functions.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/cadence/language/built-in-functions.mdx b/docs/cadence/language/built-in-functions.mdx index bc47a982d9..b52197336c 100644 --- a/docs/cadence/language/built-in-functions.mdx +++ b/docs/cadence/language/built-in-functions.mdx @@ -53,7 +53,8 @@ The random numbers returned are unpredictable (unpredictable for miners at block construction time, and unpredictable for cadence logic at time of call), verifiable, as well as unbiasable by miners and previously-running Cadence code. -See [FLIP120](https://github.com/onflow/flips/pull/120) for more details. +See [Secure random number generator for Flow’s smart contracts](https://forum.flow.com/t/secure-random-number-generator-for-flow-s-smart-contracts/5110) +and [FLIP120](https://github.com/onflow/flips/pull/120) for more details. Nevertheless, developers need to be mindful to use `revertibleRandom()` correctly. From fd81707a7d8376846da967828caae84a57fd7114 Mon Sep 17 00:00:00 2001 From: Tarak Ben Youssef Date: Mon, 6 Nov 2023 16:58:45 -0600 Subject: [PATCH 5/8] add link to commit-reveal example --- docs/cadence/language/built-in-functions.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/cadence/language/built-in-functions.mdx b/docs/cadence/language/built-in-functions.mdx index b52197336c..a136af4795 100644 --- a/docs/cadence/language/built-in-functions.mdx +++ b/docs/cadence/language/built-in-functions.mdx @@ -71,8 +71,12 @@ perform post-selection on the returned random numbers. This limitation is inherent to any smart contract platform that allows transactions to roll back atomically and cannot be solved through safe randomness alone. + Flow protocol has suggested a [solution to implement safe commit-reveal schemes](https://github.com/onflow/flips/pull/123) and address this limitation. +In cases where a non-trusted party can interact with smart contracts generating +random numbers through their own transactions, please **use a commit-reveal scheme** +as described in ~[this tutorial]()~ this [rudimentary example](https://github.com/onflow/flips/blob/main/protocol/20230728-commit-reveal.md#tutorials-and-examples) ## `unsafeRandom` From 914d2b364defd7cd9cec85b5c0a1314f5761540d Mon Sep 17 00:00:00 2001 From: Tarak Ben Youssef Date: Mon, 6 Nov 2023 17:03:25 -0600 Subject: [PATCH 6/8] update cadence 1.0 and current version docs --- docs/cadence/language/built-in-functions.mdx | 18 +---- .../cadence/language/built-in-functions.mdx | 70 +++++++++++++------ 2 files changed, 50 insertions(+), 38 deletions(-) diff --git a/docs/cadence/language/built-in-functions.mdx b/docs/cadence/language/built-in-functions.mdx index a136af4795..e6d0b92d68 100644 --- a/docs/cadence/language/built-in-functions.mdx +++ b/docs/cadence/language/built-in-functions.mdx @@ -35,11 +35,6 @@ The message argument is optional. fun revertibleRandom(): UInt64 ``` - -`unsafeRandom()` function currently behaves the same way as `revertibleRandom()`, -and will be deprecated in the next Cadence release. - - Returns a pseudo-random number. The sequence of returned random numbers is independent for @@ -50,7 +45,7 @@ generator (CSPRG) for each transaction independently, where the seeds of any two are different with near certainty. The random numbers returned are unpredictable -(unpredictable for miners at block construction time, +(unpredictable for miners at block construction time, and unpredictable for cadence logic at time of call), verifiable, as well as unbiasable by miners and previously-running Cadence code. See [Secure random number generator for Flow’s smart contracts](https://forum.flow.com/t/secure-random-number-generator-for-flow-s-smart-contracts/5110) @@ -78,17 +73,6 @@ In cases where a non-trusted party can interact with smart contracts generating random numbers through their own transactions, please **use a commit-reveal scheme** as described in ~[this tutorial]()~ this [rudimentary example](https://github.com/onflow/flips/blob/main/protocol/20230728-commit-reveal.md#tutorials-and-examples) - -## `unsafeRandom` - -This function is superseded by `revertibleRandom()`. -`unsafeRandom` has the same interface and implementation as `revertibleRandom()` although -it is called unsafe. - - -`unsafeRandom` will be deprecated in the next Cadence release. Use `revertibleRandom()` instead. - - ## `RLP` Recursive Length Prefix (RLP) serialization allows the encoding of arbitrarily nested arrays of binary data. diff --git a/versioned_docs/version-stable/cadence/language/built-in-functions.mdx b/versioned_docs/version-stable/cadence/language/built-in-functions.mdx index 82c61fc5b9..c83802e1ff 100644 --- a/versioned_docs/version-stable/cadence/language/built-in-functions.mdx +++ b/versioned_docs/version-stable/cadence/language/built-in-functions.mdx @@ -30,37 +30,65 @@ fun assert(_ condition: Bool, message: String) The message argument is optional. -## unsafeRandom +## `revertibleRandom` ```cadence -fun unsafeRandom(): UInt64 +fun revertibleRandom(): UInt64 ``` - Returns a pseudo-random number. + +`unsafeRandom()` function currently behaves the same way as `revertibleRandom()`, +and will be deprecated in the next Cadence release. + - NOTE: - Smart contract developers should be mindful about the limitations of unsafeRandom. - The stream of random numbers produced is potentially unsafe in the following two regards: +Returns a pseudo-random number. - 1. The sequence of random numbers is potentially predictable by transactions within the same block - and by other smart contracts calling into your smart contract. - 2. A transaction calling into your smart contract can potentially bias the sequence of random numbers which - your smart contract internally generates. +The sequence of returned random numbers is independent for +every transaction in each block. - We are working towards removing these limitations incrementally. Once these points are addressed, - Flow’s randomness is safe and we will remove the "unsafe" qualifier. +Under the hood, Cadence instantiates a cryptographically-secure pseudo-random number +generator (CSPRG) for each transaction independently, where the seeds of any two transactions +are different with near certainty. - Nevertheless, there is an additional safety-relevant aspect that developers need to be mindful about: +The random numbers returned are unpredictable +(unpredictable for miners at block construction time, +and unpredictable for cadence logic at time of call), +verifiable, as well as unbiasable by miners and previously-running Cadence code. +See [Secure random number generator for Flow’s smart contracts](https://forum.flow.com/t/secure-random-number-generator-for-flow-s-smart-contracts/5110) +and [FLIP120](https://github.com/onflow/flips/pull/120) for more details. - * A transaction can atomically revert all its action at any time. Therefore, it is possible for a transaction calling into - your smart contract to post-select favourable results and revert the transaction for unfavourable results. - ([example](https://consensys.github.io/smart-contract-best-practices/development-recommendations/general/public-data/)) +Nevertheless, developers need to be mindful to use `revertibleRandom()` correctly. - This limitation is inherent to any smart contract platform that allows transactions to roll back atomically and cannot be - solved through safe randomness alone. Providing additional Cadence language primitives to simplify this challenge for - developers is on our roadmap as well. Nevertheless, with safe randomness (points 1 and 2 above resolved), developers can prevent - clients from post-select favourable outcomes using approaches such as described in the - [example](https://consensys.github.io/smart-contract-best-practices/development-recommendations/general/public-data/). + + +A transaction can atomically revert all its action. +It is possible for a transaction submitted by an untrusted party +to post-select favorable results and revert the transaction for unfavorable results. + + + +The function usage remains safe when called by a trusted party that does not +perform post-selection on the returned random numbers. + +This limitation is inherent to any smart contract platform that allows transactions to roll back atomically +and cannot be solved through safe randomness alone. + +Flow protocol has suggested a [solution to implement safe +commit-reveal schemes](https://github.com/onflow/flips/pull/123) and address this limitation. +In cases where a non-trusted party can interact with smart contracts generating +random numbers through their own transactions, please **use a commit-reveal scheme** +as described in ~[this tutorial]()~ this [rudimentary example](https://github.com/onflow/flips/blob/main/protocol/20230728-commit-reveal.md#tutorials-and-examples) + + +## `unsafeRandom` + +This function is superseded by `revertibleRandom()`. +`unsafeRandom` has the same interface and implementation as `revertibleRandom()` although +it is called unsafe. + + +`unsafeRandom` will be deprecated in the next Cadence release. Use `revertibleRandom()` instead. + ## RLP From 5347cac58bbf51a567a2d4d57203625c089183ce Mon Sep 17 00:00:00 2001 From: Tarak Ben Youssef Date: Mon, 6 Nov 2023 18:23:36 -0600 Subject: [PATCH 7/8] update reveal-commit mention --- docs/cadence/language/built-in-functions.mdx | 4 ++-- .../version-stable/cadence/language/built-in-functions.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/cadence/language/built-in-functions.mdx b/docs/cadence/language/built-in-functions.mdx index e6d0b92d68..76d0cff20d 100644 --- a/docs/cadence/language/built-in-functions.mdx +++ b/docs/cadence/language/built-in-functions.mdx @@ -70,8 +70,8 @@ and cannot be solved through safe randomness alone. Flow protocol has suggested a [solution to implement safe commit-reveal schemes](https://github.com/onflow/flips/pull/123) and address this limitation. In cases where a non-trusted party can interact with smart contracts generating -random numbers through their own transactions, please **use a commit-reveal scheme** -as described in ~[this tutorial]()~ this [rudimentary example](https://github.com/onflow/flips/blob/main/protocol/20230728-commit-reveal.md#tutorials-and-examples) +random numbers through their own transactions, **use a commit-reveal scheme** +as described in this [rudimentary example](https://github.com/onflow/flips/blob/main/protocol/20230728-commit-reveal.md#tutorials-and-examples) ## `RLP` diff --git a/versioned_docs/version-stable/cadence/language/built-in-functions.mdx b/versioned_docs/version-stable/cadence/language/built-in-functions.mdx index c83802e1ff..4cda941e40 100644 --- a/versioned_docs/version-stable/cadence/language/built-in-functions.mdx +++ b/versioned_docs/version-stable/cadence/language/built-in-functions.mdx @@ -76,8 +76,8 @@ and cannot be solved through safe randomness alone. Flow protocol has suggested a [solution to implement safe commit-reveal schemes](https://github.com/onflow/flips/pull/123) and address this limitation. In cases where a non-trusted party can interact with smart contracts generating -random numbers through their own transactions, please **use a commit-reveal scheme** -as described in ~[this tutorial]()~ this [rudimentary example](https://github.com/onflow/flips/blob/main/protocol/20230728-commit-reveal.md#tutorials-and-examples) +random numbers through their own transactions, **use a commit-reveal scheme** +as described in this [rudimentary example](https://github.com/onflow/flips/blob/main/protocol/20230728-commit-reveal.md#tutorials-and-examples) ## `unsafeRandom` From fa8421654ec29c5e9823d4d7b3e750daeb5405b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20M=C3=BCller?= Date: Tue, 7 Nov 2023 09:18:05 -0800 Subject: [PATCH 8/8] Update versioned_docs/version-stable/cadence/language/built-in-functions.mdx --- .../version-stable/cadence/language/built-in-functions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-stable/cadence/language/built-in-functions.mdx b/versioned_docs/version-stable/cadence/language/built-in-functions.mdx index 4cda941e40..6bebe636e1 100644 --- a/versioned_docs/version-stable/cadence/language/built-in-functions.mdx +++ b/versioned_docs/version-stable/cadence/language/built-in-functions.mdx @@ -87,7 +87,7 @@ This function is superseded by `revertibleRandom()`. it is called unsafe. -`unsafeRandom` will be deprecated in the next Cadence release. Use `revertibleRandom()` instead. +`unsafeRandom` is deprecated and will be removed in an upcoming release of Cadence. Use `revertibleRandom()` instead.