Merge pull request #6 from xch-dev/new-release

New release

Author: Rigidity

docs/bindings.md

@@ -40,5 +40,5 @@ fn main(num: Int) -> Int {
 This should be used sparingly, since it can come with either a performance hit, an increase in compiled output size, or both.
 
 :::tip
-The compiler will automatically inline `let` bindings if they are only referenced a single time. You almost never need to explicitly mark them as `inline`.
+The compiler will automatically inline `let` bindings if they are only referenced a single time.
 :::

docs/builtins.md

@@ -14,53 +14,55 @@ You can click on each of these types to go to their corresponding page and learn
 2. [**Bytes**](/docs/type-system/atoms.md#bytes)
 3. [**Bytes32**](/docs/type-system/atoms.md#bytes32)
 4. [**PublicKey**](/docs/type-system/atoms.md#publickey)
-5. [**Int**](/docs/type-system/atoms.md#int)
-6. [**Bool**](/docs/type-system/atoms.md#bool)
-7. [**Any**](/docs/type-system/pairs.md#any)
-8. [**List**](/docs/type-system/pairs.md#lists)
+5. [**Signature**](/docs/type-system/atoms.md#signature)
+6. [**K1PublicKey**](/docs/type-system/atoms.md#k1publickey)
+7. [**K1Signature**](/docs/type-system/atoms.md#k1signature)
+8. [**R1PublicKey**](/docs/type-system/atoms.md#r1publickey)
+9. [**R1Signature**](/docs/type-system/atoms.md#r1signature)
+10. [**Int**](/docs/type-system/atoms.md#int)
+11. [**Bool**](/docs/type-system/atoms.md#bool)
+12. [**Any**](/docs/type-system/pairs.md#any)
+13. [**List**](/docs/type-system/pairs.md#lists)
+14. [**AlternatingList**](/docs/type-system/pairs.md#alternating-lists)
 
 ## Functions
 
 ### `sha256`
 
-Calculates the [SHA-256](https://en.wikipedia.org/wiki/SHA-2) hash of the bytes provided. This hash is calculated at runtime.
+Calculates the [SHA-256](https://en.wikipedia.org/wiki/SHA-2) hash of the bytes provided. While this hashes the value at runtime, there is also a `sha256_inline` builtin that allows you to hash a constant value at compile time and insert the result into the program. Its use is discouraged (because hard coding 32 bytes is costly in CLVM) unless you have a very large constant value that you want to avoid hashing multiple times.
 
 For example:
 
 ```rue
 let hash = sha256("hello");
 ```
 
-### `sha256_inline`
-
-The same as `sha256`, except the value will be calculated at compile time and inserted into the program. In some rare scenario, this may be an important optimization to avoid hashing the same large constant value many times. However, in most cases, you should just use the regular `sha256` function.
-
-For example:
+There's also a variant with the spread syntax that allows you to hash a list of arguments that is computed at runtime (rather than a static list):
 
 ```rue
-let hash = sha256_inline("hello");
+let hash = sha256(...list);
 ```
 
+Note that this prevents the compiler from being able to fold the arguments into a constant at compile time. However, it saves CLVM cost by not having to recursively concatenate the arguments.
+
 ### `keccak256`
 
-Calculates the [Keccak-256](https://en.wikipedia.org/wiki/SHA-3) hash of the bytes provided. This hash is calculated at runtime.
+Calculates the [Keccak-256](https://en.wikipedia.org/wiki/SHA-3) hash of the bytes provided. While this hashes the value at runtime, there is also a `keccak256_inline` builtin that allows you to hash a constant value at compile time and insert the result into the program. Its use is discouraged (because hard coding 32 bytes is costly in CLVM) unless you have a very large constant value that you want to avoid hashing multiple times.
 
 For example:
 
 ```rue
 let hash = keccak256("hello");
 ```
 
-### `keccak256_inline`
-
-The same as `keccak256`, except the value will be calculated at compile time and inserted into the program. In some rare scenario, this may be an important optimization to avoid hashing the same large constant value many times. However, in most cases, you should just use the regular `keccak256` function.
-
-For example:
+There's also a variant with the spread syntax that allows you to hash a list of arguments that is computed at runtime (rather than a static list):
 
 ```rue
-let hash = keccak256_inline("hello");
+let hash = keccak256(...list);
 ```
 
+Note that this prevents the compiler from being able to fold the arguments into a constant at compile time. However, it saves CLVM cost by not having to recursively concatenate the arguments.
+
 ### `coinid`
 
 A builtin CLVM opcode for hashing the parent coin id, puzzle hash, and amount of a coin into its coin id. See the [Security](/docs/security.md#untrusted-values) section for an explanation of why this opcode exists. Essentially, it adds runtime checks to make sure that the length of the parent coin id and puzzle hash are 32.
@@ -83,18 +85,12 @@ substr("hello", 1, 4)
 
 This would return `"ell"`
 
-### `substr_start`
-
-Returns a substring of a byte value, given a starting index. Note that if the index is out of bounds, this will raise an error.
-
-For example:
+The end index is optional, and defaults to the length of the string:
 
 ```rue
-substr_start("hello", 1)
+substr("hello", 1)
 ```
 
-This would return `"ello"`
-
 ### `g1_map`
 
 Hashes the data to a BLS public key, with sha256 and ExpandMsgXmd.
@@ -105,14 +101,10 @@ For example:
 g1_map("hello")
 ```
 
-### `g1_map_dist`
-
-Hashes the data to a BLS public key, with sha256 and ExpandMsgXmd. This function allows you to add a DST.
-
-For example:
+You can also specify an optional DST parameter:
 
 ```rue
-g1_map_dst("hello", "dst")
+g1_map("hello", "dst")
 ```
 
 ### `g2_map`
@@ -125,14 +117,10 @@ For example:
 g2_map("hello")
 ```
 
-### `g2_map_dst`
-
-Hashes the data to a BLS signature, with sha256 and ExpandMsgXmd. This function allows you to add a DST.
-
-For example:
+You can also specify an optional DST parameter:
 
 ```rue
-g2_map_dst("hello", "dst")
+g2_map("hello", "dst")
 ```
 
 ### `pubkey_for_exp`
@@ -155,6 +143,31 @@ For example:
 modpow(5, 50, 45)
 ```
 
+### `divmod`
+
+Computes both `numerator / denominator` and `numerator % denominator` and returns a pair of the results.
+
+For example:
+
+```rue
+let (quotient, remainder) = divmod(50, 3);
+```
+
+## Operator Optimizations
+
+Similarly to [sha256](#sha256) and [keccak256](#keccak256), the following builtin functions are provided to optimize the use of operators on lists of arguments:
+
+1. `concat` (the `+` operator on bytes)
+2. `sum` (the `+` operator on integers)
+3. `difference` (the `-` operator on integers)
+4. `product` (the `*` operator on integers)
+5. `any` (the `|` operator on booleans)
+6. `all` (the `&` operator on booleans)
+7. `g1_sum` (the `+` operator on BLS public keys)
+8. `g1_difference` (the `-` operator on BLS public keys)
+9. `g2_sum` (the `+` operator on BLS signatures)
+10. `g2_difference` (the `-` operator on BLS signatures)
+
 ## Verifications
 
 The following CLVM operators return `nil` on success, and raise if they fail:
@@ -164,16 +177,12 @@ The following CLVM operators return `nil` on success, and raise if they fail:
 3. `secp256k1_verify`
 4. `secp256r1_verify`
 
-As such, they would be difficult to use if they were implemented as builtin functions. Instead, Rue provides verification **statements**, which can be called similarly to functions but can't directly be used as an expression. You can think of these like specialized `assert` statements, since they will raise if the verification fails, and continue on if not.
+You can think of these like specialized `assert` statements, since they will raise if the verification fails, and continue on if not. Rue provides these as builtin functions that can be called as a statement.
 
 These are automatically optimized such that ordinary references to `nil` after the verification statements in the block are replaced with the verification expression (since it returns `nil` anyways). If there aren't any possible substitutions, the rest of the block will be wrapped in a cons pair, with the verifications happening first, and then unwrapped back into the expression value of the block. And finally, if multiple verifications need to be done in a group, the `all` operator will be used, since it will always return `nil` as well.
 
 All of this is to say that the compiler will pick the most efficient way to insert these verifications into your program without disrupting its behavior at runtime.
 
-:::note
-It's not currently possible to dynamically construct the arguments to these verifications from a list at runtime. This is a limitation that seems to exist in Chialisp as well. This may be possible in the future.
-:::
-
 ### `bls_pairing_identity`
 
 Accepts a flattened sequence of public key and signature pairs, and verifies that the pairing of all pairs is the identity. Otherwise, this will raise.
@@ -193,6 +202,8 @@ bls_pairing_identity(
 );
 ```
 
+You can use the spread syntax to verify a list of pairs.
+
 ### `bls_verify`
 
 Accepts a signature followed by a flattened sequence of public key and message pairs, and verifies that the aggregate signature is valid. Otherwise, this will raise.
@@ -207,6 +218,8 @@ bls_verify(
 );
 ```
 
+You can use the spread syntax to verify a list of pairs.
+
 ### `secp256k1_verify`
 
 Verifies a signature that uses the secp256r1 curve against its message hash and signature.

docs/constants.md

@@ -35,5 +35,5 @@ fn main(person_a: Bytes, person_b: Bytes) -> (Bytes, Bytes) {
 This should be used sparingly, since it can come with either a performance hit, an increase in compiled output size, or both.
 
 :::tip
-The compiler will automatically inline constants if they are only referenced a single time. You almost never need to explicitly mark them as `inline`.
+The compiler will automatically inline constants if they are only referenced a single time.
 :::

docs/functions.md

@@ -20,9 +20,9 @@ And they can be called by other functions:
 add(42, 34)
 ```
 
-## Main
+## Entrypoints
 
-The `main` function is special, in that it's the entrypoint to every compiled program. It's used to determine which symbols are used in the program, and its body is compiled verbatim (along with any functions and constants it depends on) rather than being called.
+The `main` function is the primary entrypoint to your program. It's used to determine which symbols are used and its body is compiled verbatim (along with any functions and constants it depends on) rather than being called.
 
 For example, the following program:
 
@@ -34,6 +34,32 @@ fn main() -> Int {
 
 Will compile to the CLVM `(q . 42)`.
 
+### Test Functions
+
+Another form of entrypoint (which behaves like `main`) is a test function.
+
+This lets you write unit tests directly in your Rue code:
+
+```rue
+test fn verify() {
+    assert main() == 42;
+}
+```
+
+When you run `rue test`, all of the tests in the file will be executed. If they raise an error, the line number of the assertion will be included in the error message.
+
+### Exported Functions
+
+The last kind of entrypoint is any function that is marked with `export`:
+
+```rue
+export fn puzzle() -> List<Condition> {
+    nil
+}
+```
+
+If you run `rue build -e puzzle`, it will build this export as if it were the main function. This lets you include multiple programs inside of a single file.
+
 ## Inline Functions
 
 You can mark a function as `inline`. This will change the behavior of the compiler to insert the function body everywhere it's referenced, substituting each of the parameters with the corresponding arguments in the function call, instead of defining the function separately and calling it.
@@ -55,17 +81,31 @@ This should be used sparingly, since it can come with either a performance hit,
 A recursive function cannot be marked as `inline`.
 
 :::tip
-The compiler will automatically inline functions if they are referenced a single time and their parameters are referenced a single time. You almost never need to explicitly mark them as `inline`.
+The compiler will automatically inline functions if they are referenced a single time and their parameters are referenced a single time.
 :::
 
-## Spread Syntax
+## Extern Functions
+
+Function parameters are optimized into an efficient binary tree structure, as long as the function is neither an entrypoint, nor used as a closure. This binary tree optimization is not allowed for those because it's an implementation detail of the compiler and hard to rely on as a public interface. For example, if you accept a function as an argument, its arguments must be in the expected layout.
+
+The compiler will pick the optimized parameter layout automatically when it can, but you can opt out of this with the `extern` keyword:
+
+```rue
+extern fn add(a: Int, b: Int) -> Int {
+    a + b
+}
+```
+
+Just keep in mind that this can increase the size of the generated program, as well as its runtime CLVM cost.
 
-Typically, there is a fixed number of arguments in a function. However, if you want to allow a variable number of arguments, or extend the argument list with another type, you can use the spread operator.
+### Spread Syntax
 
-For example, the following function accepts any number of arguments:
+Although it's not very useful for optimized functions (since the parameter layout is managed by the compiler anyways), you can remove the nil terminator from the parameter list in an extern function by using the spread operator. You can think of this as binding a parameter to the "rest" of the parameters in CLVM.
+
+For example:
 
 ```rue
-fn sum(...numbers: List<Int>) -> Int {
+extern fn sum(...numbers: List<Int>) -> Int {
     if numbers is nil {
         0
     } else {
@@ -74,18 +114,16 @@ fn sum(...numbers: List<Int>) -> Int {
 }
 ```
 
-And can be called as such:
+However, Rue does not allow you to specify an arbitrary number of arguments, and will force you to use the spread syntax on a list manually.
 
-```rue
-let zero = sum();
-let added = sum(42, 34);
+So, this can be called like this:
 
-// You can spread arguments too
+```rue
 let list = [1, 2, 3, 4, 5];
-let total = sum(42, ...list);
+let total = sum(...list);
 ```
 
-It's also possible to use the spread operator with non-list types, which allows for compatibility with arbitrary functions:
+It's also possible to use the spread syntax with non-list types, which allows for flexibility with external functions:
 
 ```rue
 fn main(
@@ -105,16 +143,16 @@ struct Solution {
 }
 
 fn main(...solution: Solution) -> List<Condition> {
-    let message = tree_hash(solution.conditions as Any);
+    let message = tree_hash(solution.conditions);
     let agg_sig = AggSigMe {
         public_key: solution.public_key,
-        message: message,
+        message,
     };
     [agg_sig, ...solution.conditions]
 }
 ```
 
-## Lambdas
+## Closures
 
 Because functions can be passed around as values, it's sometimes useful to be able to write a function inline.
 
@@ -125,7 +163,11 @@ let adder = fn(a: Int, b: Int) => a + b;
 let sum = adder(42, 34);
 ```
 
-### Closures
+:::warning
+Creating and calling function values limits the compiler's ability to optimize the generated bytecode, since they are forced to be compatible with external programs. You should use lambdas and closures sparingly, if at all.
+:::
+
+### Captures
 
 Lambdas can automatically capture values that are defined in their parent scope, much like how functions in general capture other functions or constants that are defined externally.