Update casting docs, release & migration notes and other related docs

Author: rkalis

website/docs/guides/covenants.md

@@ -143,7 +143,11 @@ Smart contracts which persist for multiple transactions might want to keep data
 Covenants can also use 'simulated state', where state is kept in the contract script and the contract enforces a new P2SH locking bytecode of the contract with a different state update. This method causes the contract address to change with each state update.
 :::
 
-### Keeping local State in NFTs
+### Keeping local state in NFTs
+
+When we want to share local state between multiple transactions or contracts, we can use the NFT commitment field in an NFT. This state is accessible in any transaction that includes the NFT.
+
+#### Example: Streaming Mecenas
 
 To demonstrate the concept of 'local state' we consider the Mecenas contract again, and focus on a drawback of this contract: you have to claim the funds at exactly the right moment or you're leaving money on the table. Every time you claim money from the contract, the `this.age` counter is reset, so the next claim is possible 30 days after the previous claim. So if we wait a few days to claim, **these days are basically wasted**.
 
@@ -194,7 +198,7 @@ contract StreamingMecenas(
             require(tx.outputs[1].lockingBytecode == tx.inputs[0].lockingBytecode);
 
             // Update the block height of the previous pledge, kept in the NFT commitment
-            bytes blockHeightNewPledge = bytes8(tx.locktime);
+            bytes blockHeightNewPledge = toPaddedBytes(tx.locktime, 8);
             require(tx.outputs[1].nftCommitment == blockHeightNewPledge);
         }
     }
@@ -212,6 +216,21 @@ Instead of having a pledge per 30 day period, we define a pledge per block. At a
 We use `tx.locktime` to introspect the value of the timelock, and to write the value to the contract local state: the NFT commitment field.
 :::
 
+#### Integer padding for local state
+
+Padding an integer to a fixed-size byte-length is a very important when storing local state in an nftCommitment. We can use the `toPaddedBytes(int, length)` function to pad the integer to the desired length. When casting a script number to bytes, developers need to consider what the preferable fixed-size length is for each individual case depending on the integer range. Below we add a table with info on the maximum integer size for common cases:
+
+| Integer Type    | Max integer value                  | Max Byte Size in Script Number Format  |
+| --------------  | -----------------------------------| ---------------------------------------|
+| Satoshis        | 2.1 quadrillion (21,000,000 BCH)   | 7 bytes                                |
+| CashTokens      | 9.2 quintillion (`2^63 - 1`)       | 8 bytes for max supply token           |
+| Locktime        | 4 bytes uInt (`2^32 - 1`)          | 5 bytes                                |
+| SequenceNumber  | 4 bytes uInt (`2^32 - 1`)          | 5 bytes                                |
+
+:::info
+VM numbers follow Script Number format (A.K.A. CSCriptNum), to convert VM number to bytes or the reverse, it's recommended to use helper functions for these conversions from libraries like Libauth.
+:::
+
 ### Issuing NFTs as receipts
 
 A covenant that manages funds (BCH + fungible tokens of a certain category) which are pooled together from different people often wants to enable its participants to also exit the covenants with their funds. It would be incredibly hard continuously updating a data structure to keep track of which address contributed how much in the local state of the contract. A much better solution is to issue receipts each time funds are added to the pool! This way the contract does not have a 'global view' of who owns what at any time, but it can validate the receipts when invoking a withdrawal.
@@ -251,12 +270,12 @@ contract PooledFunds(
         if (amountTokensAdded > 0) {
             // Require 1000 sats to pay for future withdrawal fee
             require(amountSatsAdded == 1000);
-            receiptCommitment = 0x01 + bytes8(amountTokensAdded);
+            receiptCommitment = 0x01 + toPaddedBytes(amountTokensAdded, 8);
         } else {
             // Place a minimum on the amount of funds that can be added
             // Implicitly requires tx.outputs[0].value > tx.inputs[0].value
             require(amountSatsAdded > 10000);
-            receiptCommitment = 0x00 + bytes8(amountSatsAdded);
+            receiptCommitment = 0x00 + toPaddedBytes(amountSatsAdded, 8);
         }
 
         // Require there to be at most three outputs so no additional NFTs can be minted

website/docs/language/functions.md

@@ -113,4 +113,19 @@ bool checkDataSig(datasig s, bytes msg, pubkey pk)
 
 Checks that sig `s` is a valid signature for message `msg` and matches with public key `pk`.
 
+## Other functions
+
+### toPaddedBytes()
+```solidity
+bytes toPaddedBytes(int value, int length)
+```
+
+Pads the integer `value` with zeros to the specified `length`. This is most useful when storing integer values in local state (see [local state guide][local-state-guide]).
+
+:::tip
+Using `bytes20 placeholderPkh = toPaddedBytes(0, 20)` will generate a 20 byte zero-array at runtime, whereas
+`bytes20 placeholderPkh = 0x0000000000000000000000000000000000000000` will actually take 20 bytes of space in your contract.
+:::
+
 [bip146]: https://github.com/bitcoin/bips/blob/master/bip-0146.mediawiki
+[local-state-guide]: /docs/guides/covenants#keeping-local-state-in-nfts

website/docs/language/types.md

@@ -70,7 +70,7 @@ Members:
 - `reverse()`: Reverses the string.
 
 :::caution
-The script will fail if `split()`or `slice()` is called with an index that is out of bounds.
+The script will fail if `split()` or `slice()` is called with an index that is out of bounds.
 :::
 
 ## Bytes
@@ -167,7 +167,7 @@ Type casting can be done both explicitly and implicitly depending on the type. `
 ```solidity
 pubkey pk = pubkey(0x0000);
 bytes editedPk = bytes(pk) + 0x1234;
-bytes4 zeroBytes = bytes4(0); // 0x00000000
+bool b = bool(5); // true
 ```
 
 ### Casting Table
@@ -179,45 +179,39 @@ See the following table for information on which types can be cast to other whic
 | int     |                        | bytes, bool                        |
 | bool    |                        | int                                |
 | string  |                        | bytes                              |
-| bytes   |                        | sig, pubkey, int                   |
+| bytes   |                        | sig, datasig, pubkey, int          |
 | pubkey  | bytes                  | bytes                              |
 | sig     | bytes                  | bytes                              |
 | datasig | bytes                  | bytes                              |
 
-### Int to Byte Casting
-
-When casting integer types to bytes of a certain size, the integer value is padded with zeros, e.g. `bytes4(0) == 0x00000000`. It is also possible to pad with a variable number of zeros by passing in a `size` parameter, which indicates the size of the output, e.g. `bytes(0, 4 - 2) == 0x0000`.
-
-:::tip
-Using `bytes20 placeholderPkh= bytes20(0)` will generate a 20 byte zero-array programmatically, whereas
-`bytes20 placeholderPkh= 0x0000000000000000000000000000000000000000` will actually take 20 bytes of space in your contract.
-:::
-
-Casting an integer to a fixed-size byte-length can be a very important when storing local state in an nftCommitment. When casting a script number to bytes, developers need to consider what the preferable fixed-size length is for each individual case depending on the integer range. Below we add a table with info on the maximum integer size for common cases:
-
-| Integer Type    | Max integer value                  | Max Byte Size in Script Number Format  |
-| --------------  | -----------------------------------| ---------------------------------------|
-| Satoshis        | 2.1 quadrillion (21,000,000 BCH)   | 7 bytes                                |
-| CashTokens      | 9.2 quintillion (`2^63 - 1`)       | 8 bytes for max supply token           |
-| Locktime        | 4 bytes uInt (`2^32 - 1`)          | 5 bytes                                |
-| SequenceNumber  | 4 bytes uInt (`2^32 - 1`)          | 5 bytes                                |
-
-:::info
-VM numbers follow Script Number format (A.K.A. CSCriptNum), to convert VM number to bytes or the reverse, it's recommended to use helper functions for these conversions from libraries like Libauth.
-:::
-
-### Semantic Byte Casting
+### Semantic Bytes Casting
 
-When casting unbounded `bytes` types to bounded `bytes` types (such as `bytes20` or `bytes32`), this is a purely semantic cast. The bytes are not padded with zeros, and no checks are performed to ensure the cast bytes are of the correct length. This can be helpful in certain cases, such as `LockingBytecode`, which expects a specific length input.
+When casting unbounded `bytes` types to bounded `bytes` types (such as `bytes20` or `bytes32`), this is a purely semantic cast. The bytes are not padded with zeros, and no checks are performed to ensure the cast bytes are of the correct length. This is why this cast is marked with the `unsafe_` prefix. This can be helpful in certain cases, such as `LockingBytecode`, which expects a specific length input.
 
 #### Example
 ```solidity
 bytes pkh = tx.inputs[0].nftCommitment; // (type = bytes, content = 20 bytes)
 // Typecast the variable to be able to use it for 'new LockingBytecodeP2PKH()'
-bytes20 bytes20Pkh = bytes20(pkh); // (type = bytes20, content = 20 bytes)
+bytes20 bytes20Pkh = unsafe_bytes20(pkh); // (type = bytes20, content = 20 bytes)
 bytes25 lockingBytecode = new LockingBytecodeP2PKH(bytes20Pkh);
 ```
 
+### Other Semantic Casting
+When casting a `bytes` to an `int` or when casting an `int` to a `bool`, opcodes are added to the script to perform a conversion between the two types. If you are an advanced user and want to perform these casts without the added opcodes, you can use the `unsafe_` prefix.
+
+#### Example
+```solidity
+bytes bytesValue = 0x123456000000; // not a valid minimally encoded integer
+
+int(bytesValue); // (type = int, content = 0x123456)
+unsafe_int(bytesValue); // (type = int, content = 0x123456000000)
+
+int intValue = 25;
+
+bool(intValue); // (type = bool, content = true / 0x01)
+unsafe_bool(intValue); // (type = bool, content = 25 / 0x19)
+```
+
 ## Operators
 An overview of all supported operators and their precedence is included below. Notable is a lack of exponentiation, since these operations are not supported by the underlying Bitcoin Script.
 

website/docs/releases/migration-notes.md

@@ -2,6 +2,56 @@
 title: Migration Notes
 ---
 
+## v0.12 to v0.13
+
+### cashc compiler
+
+#### bounded bytes casting
+
+To indicate that `bytes4(bytes)` casting is purely semantic (and does not offer any type safety), we have renamed it to `unsafe_bytes4(bytes)`. We have also disallowed `bytes4(int)` casting (see section *int to padded bytes casting*).
+
+```solidity
+bytes x = 0x12345678;
+
+// before
+bytes4(x); // => 0x12345678 (correct semantic cast)
+bytes5(x); // => 0x12345678 (incorrect semantic cast)
+
+// after
+// marked as unsafe to indicate that this is a purely semantic cast
+unsafe_bytes4(x); // => 0x12345678 (correct semantic cast)
+unsafe_bytes5(x); // => 0x12345678 (incorrect semantic cast)
+```
+
+#### int to padded bytes casting
+
+In the past, `bytes4(int)` or `bytes(int, 4)` would perform a `NUM2BIN` operation, padding the value to 4 bytes, while `bytes4(bytes)` was a purely semantic type cast. This caused confusion, so instead you can now use the `toPaddedBytes(int, length)` function to perform the same padding (`NUM2BIN`) operation.
+
+```solidity
+// before
+bytes4(5); // => 0x05000000
+bytes(5, 4); // => 0x05000000
+
+// after
+toPaddedBytes(5, 4); // => 0x05000000
+```
+
+#### bool casting
+
+The `bool()` casting function now correctly changes the value of the argument to `true` for non-zero values and `false` for zero values, instead of only semantically treating the value as a boolean. This worked correctly when using the boolean directly inside `require` or `if` statements, but not when using it in a comparison.
+
+```solidity
+// before
+require(bool(5)); // => true
+require(bool(5) == true); // => false || compiles to 0x05 0x01 OP_NUMEQUALVERIFY
+
+// after
+require(bool(5)); // => still true
+require(bool(5) == true); // => true || compiles to 0x05 OP_0NOTEQUAL 0x01 OP_NUMEQUALVERIFY
+```
+
+If you want to keep the old behaviour (without added opcodes), you can use the `unsafe_bool()` casting function instead.
+
 ## v0.11 to v0.12
 
 There are several breaking changes to the SDK in this release.

website/docs/releases/release-notes.md

@@ -2,11 +2,17 @@
 title: Release Notes
 ---
 
-## v0.13.0-next.2
+## v0.13.0-next.3
+
+This release contains several breaking changes, please refer to the [migration notes](/docs/releases/migration-notes) for more information.
 
 #### cashc compiler
 - :sparkles: Add support for `do {} while ()` loops.
 - :sparkles: Add support for bitwise and arithmetic shift operators (`<<`, `>>`) and bitwise inversion (`~`).
+- :sparkles: Add `unsafe_bool()` and `unsafe_int()` casting for semantic-only casts.
+- :bug: **BREAKING**: Fix issue where `bool()` casting did not change the value of the argument.
+- :boom: **BREAKING**: Rename `bytes4(int)` and `bytes(int, 4)` to `toPaddedBytes(int, 4)`.
+- :boom: **BREAKING**: Rename `bytes4(bytes)` to `unsafe_bytes4(bytes)`.
 - :racehorse: Add optimisations for negated number comparisons.
 
 #### CashScript SDK
@@ -15,13 +21,22 @@ title: Release Notes
 - :hammer_and_wrench: Update default VM target to `BCH_2026_05`.
 - :hammer_and_wrench: Improve package size by tidying up dependencies.
 
+#### Testing Suite
+
+- :hammer_and_wrench: Add README.md to help guide users on how to use the testing suite.
+- :hammer_and_wrench: Compile all contracts in the `contracts/` directory and save the artifacts in the `artifacts/` directory.
+- :hammer_and_wrench: Compile TS artifacts as well as JSON artifacts.
+- :hammer_and_wrench: Add key management utilities for testing.
+
 ## v0.12.1
 
 #### CashScript SDK
 - :sparkles: Add Vitest extensions for automated testing.
 
 ## v0.12.0
 
+This release contains several breaking changes, please refer to the [migration notes](/docs/releases/migration-notes) for more information.
+
 #### CashScript SDK
 - :sparkles: Add `getVmResourceUsage` method to `TransactionBuilder`.
 - :sparkles: Add `maximumFeeSatsPerByte` and `allowImplicitFungibleTokenBurn` options to `TransactionBuilder` constructor.