Merge pull request #247 from onflow/built-in-functions-environment-info

Edit Built-in Functions and Environment Information articles

Author: briandoyle81

docs/language/access-control.md

@@ -1,6 +1,6 @@
 ---
 title: Access Control
-sidebar_position: 10
+sidebar_position: 12
 ---
 
 Access control allows making certain parts of a program accessible/visible and making other parts inaccessible/invisible.

docs/language/accounts/_category_.json

@@ -1,3 +1,3 @@
 {
-    "position": 16
+    "position": 6
 }

docs/language/attachments.mdx

@@ -1,6 +1,6 @@
 ---
 title: Attachments
-sidebar_position: 17
+sidebar_position: 18
 ---
 
 Attachments are a feature of Cadence designed to allow developers to extend a struct or resource type (even one that they did not create) with new functionality, without requiring the original author of the type to plan or account for the intended behavior.

docs/language/built-in-functions.mdx

@@ -1,17 +1,17 @@
 ---
 title: Built-in Functions
-sidebar_position: 23
+sidebar_position: 8
 ---
 
+The following describes Cadence's built in functions. Examples are also provided.
+
 ## `panic`
-#
 
 ```cadence
 view fun panic(_ message: String): Never
 ```
 
-Terminates the program unconditionally
-and reports a message which explains why the unrecoverable error occurred.
+Terminates the program unconditionally and reports a message, which explains why the unrecoverable error occurred.
 
 ```cadence
 panic("something went wrong: ...")
@@ -23,9 +23,7 @@ panic("something went wrong: ...")
 view fun assert(_ condition: Bool, message: String)
 ```
 
-Terminates the program if the given condition is false,
-and reports a message which explains how the condition is false.
-Use this function for internal sanity checks.
+Terminates the program if the given condition is false, and reports a message that explains how the condition is false. Use this function for internal sanity checks.
 
 The message argument is optional.
 
@@ -36,48 +34,25 @@ view fun revertibleRandom<T: FixedSizeUnsignedInteger>(modulo: T): T
 ```
 Returns a pseudo-random integer.
 
-`T` can be any fixed-size unsigned integer type (`FixedSizeUnsignedInteger`, i.e.
-(`UInt8`, `UInt16`, `UInt32`, `UInt64`, `UInt128`, `UInt256`, 
-`Word8`, `Word16`, `Word32`, `Word64`, `Word128`, `Word256`).
-
-The modulo argument is optional. 
-If provided, the returned integer is between `0` and `modulo -1`.
-If not provided, the returned integer is between `0` and the maximum value of `T`.
-The function errors if `modulo` is equal to 0.
+`T` can be any fixed-size unsigned integer type (`FixedSizeUnsignedInteger`, i.e., `UInt8`, `UInt16`, `UInt32`, `UInt64`, `UInt128`, `UInt256`, `Word8`, `Word16`, `Word32`, `Word64`, `Word128`, or `Word256`).
 
+The modulo argument is optional. If provided, the returned integer is between `0` and `modulo -1`. If not provided, the returned integer is between `0` and the maximum value of `T`. The function errors if `modulo` is equal to 0.
 
-The sequence of returned random numbers is independent for
-every transaction in each block.
-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.
+The sequence of returned random numbers is independent for every transaction in each block. 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.
 
-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.
+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] and [FLIP120] for more details.
 
-Nevertheless, developers need to be mindful to use `revertibleRandom()` correctly:
+Nevertheless, developers need to be mindful to use `revertibleRandom()` correctly.
 
-:::warning
+:::danger
 
-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.
+A transaction can atomically revert all of its action. This means that if you're letting users submit transactions, as opposed to you submitting them on your backend with a wallet you control, those users can submit the transaction in such a way that it reverts if the user doesn't like the outcome.
 
 :::
 
-The function usage remains safe when called by a trusted party that does not
-perform post-selection on the returned random numbers.
+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.
-In cases where a non-trusted party can interact through their own transactions
-with smart contracts generating random numbers,
-it is recommended to use [commit-reveal schemes](https://github.com/onflow/flips/pull/123)
-as outlined in this [tentative example](https://github.com/onflow/flips/blob/main/protocol/20230728-commit-reveal.md#tutorials-and-examples) (full tutorial coming soon).
+This limitation is inherent to any smart contract platform that allows transactions to roll back atomically and cannot be solved through safe randomness alone. In cases where a non-trusted party can interact through their own transactions with smart contracts generating random numbers, it is recommended to use [commit-reveal schemes].
 
 ## `RLP`
 
@@ -91,10 +66,10 @@ Cadence provides RLP decoding functions in the built-in `RLP` contract, which do
 view fun decodeString(_ input: [UInt8]): [UInt8]
 ```
 
-Decodes an RLP-encoded byte array. RLP calls this a "string."
-The byte array should only contain of a single encoded value for a string.
-If the encoded value type does not match, or it has trailing unnecessary bytes, the program aborts.
-If the function encounters any error while decoding, the program aborts.
+Decodes an RLP-encoded byte array. RLP calls this a _string_. The byte array should only contain a single encoded value for a string.
+
+- If the encoded value type does not match or if it has trailing unnecessary bytes, the program aborts.
+- If the function encounters any error while decoding, the program aborts.
 
 ### `decodeList`
 
@@ -104,7 +79,15 @@ view fun decodeList(_ input: [UInt8]): [[UInt8]]`
 
 Decodes an RLP-encoded list into an array of RLP-encoded items.
 
-Note that this function does not recursively decode, so each element of the resulting array is RLP-encoded data.
-The byte array should only contain of a single encoded value for a list.
-If the encoded value type does not match, or it has trailing unnecessary bytes, the program aborts.
-If the function encounters any error while decoding, the program aborts.
+Note that this function does not recursively decode, so each element of the resulting array is RLP-encoded data. The byte array should only contain a single encoded value for a list.
+
+- If the encoded value type does not match or if it has trailing unnecessary bytes, the program aborts.
+- If the function encounters any error while decoding, the program aborts.
+
+<!-- Relative links. Will not render on the page -->
+
+[Secure random number generator for Flow’s smart contracts]: https://forum.flow.com/t/secure-random-number-generator-for-flow-s-smart-contracts/5110
+[FLIP120]: https://github.com/onflow/flips/pull/120
+[commit-reveal schemes]: https://developers.flow.com/tutorials/native-vrf/commit-reveal-cadence
+[tentative example]: https://github.com/onflow/flips/blob/main/protocol/20230728-commit-reveal.md#tutorials-and-examples
+

docs/language/capabilities.md

@@ -1,6 +1,6 @@
 ---
 title: Capabilities
-sidebar_position: 11
+sidebar_position: 13
 ---
 
 Cadence supports [capability-based security] through the [object-capability model].

docs/language/contract-updatability.md

@@ -1,6 +1,6 @@
 ---
 title: Contract Updatability
-sidebar_position: 19
+sidebar_position: 20
 ---
 
 A [contract] is a collection of data (its state) and code (its functions) that lives in the contract storage area of an account. When a contract is _updated_, it is important to make sure that the changes introduced do not lead to runtime inconsistencies for already stored data.

docs/language/contracts.mdx

@@ -1,6 +1,6 @@
 ---
 title: Contracts
-sidebar_position: 18
+sidebar_position: 19
 ---
 
 A contract is a collection of type definitions, data (its state), and code (its functions) that is stored in the contract storage area of an account.

docs/language/control-flow.md

@@ -1,6 +1,6 @@
 ---
 title: Control Flow
-sidebar_position: 7
+sidebar_position: 9
 ---
 
 Control flow statements control the flow of execution in a function.

docs/language/core-events.md

@@ -1,6 +1,6 @@
 ---
 title: Core Events
-sidebar_position: 22
+sidebar_position: 23
 ---
 
 Core events are events emitted directly from the Flow Virtual Machine (FVM). The events have the same name on all networks and do not follow the standard naming (they have no address).

docs/language/enumerations.md

@@ -1,6 +1,6 @@
 ---
 title: Enumerations
-sidebar_position: 13
+sidebar_position: 15
 ---
 
 Enumerations are sets of symbolic names bound to unique, constant values, which can be compared by identity.