Docs improvements

.cspell.json

@@ -50,6 +50,7 @@
         "cryptocurrency",
         "collateralized",
         "datasig",
+        "defi",
         "deserialisation",
         "docblock",
         "electroncash",

website/docs/basics/about-bch.md

@@ -13,9 +13,9 @@ To learn more about the Bitcoin Basics refer to the book ['Mastering Bitcoin'][M
 
 ## How BCH differs from BTC
 
-Although BCH and BTC share the same Bitcoin fundamentals, both projects have significantly diverged in some areas since 2017. For example, Bitcoin Cash does not have Segwit or Taproot, instead Bitcoin Cash has had multiple upgrades specifically focused on improving the smart contract capabilities. Bitcoin Cash has re-enabled many useful opcodes, has introduce native introspection, has added CashTokens, has reworked the script limits and introduced BigInts.
+Although BCH and BTC share the same Bitcoin fundamentals, both projects have significantly diverged in some areas since 2017. For example, Bitcoin Cash does not have Segwit or Taproot, instead Bitcoin Cash has had multiple upgrades specifically focused on improving the smart contract capabilities. Bitcoin Cash has re-enabled many useful opcodes, has introduced native introspection, has added CashTokens, has reworked the script limits and introduced BigInts.
 
-So part that **has** significantly diverged between BTC and BCH is the *virtual machine* (VM), the environment in which smart contracts are evaluated. The Bitcoin Cash VM is also referred to as the **CashVM**. The greatly improved VM specifically is what makes it possible to write powerful smart contracts on BCH in the first place! On the overview of [all the BCH network upgrades][BCH upgrades], you'll notice the recent years have been fully focused on VM improvements.
+So the part that **has** significantly diverged between BTC and BCH is the *virtual machine* (VM), the environment in which smart contracts are evaluated. The Bitcoin Cash VM is also referred to as the **CashVM**. The greatly improved VM specifically is what makes it possible to write powerful smart contracts on BCH in the first place! On the overview of [all the BCH network upgrades][BCH upgrades], you'll notice the recent years have been fully focused on VM improvements.
 
 ## UTXO model
 Bitcoin Cash transactions work with in- and outputs. All current balances are so called *Unspent Transaction Outputs (UTXOs)*, which simply means they can be used as inputs for future spending transactions.
@@ -44,7 +44,7 @@ The UTXO model where transactions only have access to the local transaction cont
 
 ### Bitcoin Cash Script
 
-The locking and unlocking scripts of regular transactions and smart contracts on Bitcoin Cash are written using Bitcoin Cash' transaction scripting language, referred to as BCH Script (or Bitcoin Cash Script in full). BCH Script is a stack based assembly-like language, because it is a low-level language and requires stack management it is hard to write complex smart contract in Script directly.
+The locking and unlocking scripts of regular transactions and smart contracts on Bitcoin Cash are written using Bitcoin Cash's transaction scripting language, referred to as BCH Script (or Bitcoin Cash Script in full). BCH Script is a stack based assembly-like language, because it is a low-level language and requires stack management it is hard to write complex smart contracts in Script directly.
 
 ### CashScript
 

website/docs/basics/about.md

@@ -3,11 +3,11 @@ title: What is CashScript?
 sidebar_label: About CashScript
 ---
 
-CashScript is a high-level programming language for smart contracts on Bitcoin Cash. It offers a strong abstraction layer over Bitcoin Cash' native virtual machine, BCH Script. CashScript was created in 2019 and has seen major upgrades over the years, thereby supporting new script functionalities enabled with the different Bitcoin Cash network upgrades — including native introspection and CashTokens.
+CashScript is a high-level programming language for smart contracts on Bitcoin Cash. It offers a strong abstraction layer over Bitcoin Cash's native virtual machine, BCH Script. CashScript was created in 2019 and has seen major upgrades over the years, thereby supporting new script functionalities enabled with the different Bitcoin Cash network upgrades — including native introspection and CashTokens.
 
 The CashScript syntax is based on Ethereum's smart contract language Solidity, but its functionality is very different since smart contracts on Bitcoin Cash differ greatly from smart contracts on Ethereum. You can read more on these differences on the ['About Bitcoin Cash' page](./about-bch.md).
 
-CashScript comes with a powerful TypeScript SDK for creating, debugging and testing smart contract transactions on BCH. The SDK has an integrated networkProvider API to fetch data from the BCH blockchain. With all this functionality, the Typescript SDK makes it easy to use CashScript contracts in applications in the browser or on the server in a type-safe way.
+CashScript comes with a powerful TypeScript SDK for creating, debugging and testing smart contract transactions on BCH. The SDK has an integrated networkProvider API to fetch data from the BCH blockchain. With all this functionality, the TypeScript SDK makes it easy to use CashScript contracts in applications in the browser or on the server in a type-safe way.
 
 CashScript aims to make building smart contract apps on Bitcoin Cash accessible to a wide range of developers and to power the next-generation of UTXO smart contract applications.
 

website/docs/basics/getting-started.md

@@ -70,7 +70,7 @@ contract TransferWithTimeout(pubkey sender, pubkey recipient, int timeout) {
 
 Let's take some time to understand the contract structure.
 At the top, the smart contract declares the CashScript language version it's using with `pragma`.
-Then a `TransferWithTimeout` is declare which takes in 3 contract arguments and has 2 contract functions: `transfer` and `timeout`.
+Then a `TransferWithTimeout` is declared which takes in 3 contract arguments and has 2 contract functions: `transfer` and `timeout`.
 These contract functions both have `require` statements necessary to be met to be able to spend BCH from the contract.
 
 :::tip
@@ -97,7 +97,7 @@ After creating a contract artifact, we can now use the TypeScript SDK to initial
 
 :::info
 The CashScript SDK is written in TypeScript meaning that you can either use TypeScript or vanilla JavaScript to use the SDK.
-It's recommended to use TypeScript for full type-safety of all you contract logic.
+It's recommended to use TypeScript for full type-safety of all your contract logic.
 :::
 
 ### Installing the TypeScript SDK
@@ -180,4 +180,4 @@ console.log(transferDetails);
 
 Congrats 🎉! You've successfully created a transaction spending from a Bitcoin Cash smart contract!
 
-To use the `timeout` function you need to use Alice as signer for the spending condition. Secondly you also need get to use `.setLocktime()` with a valid argument during the transaction building to pass the `tx.time` check of the `timeout` function.
+To use the `timeout` function you need to use Alice as signer for the spending condition. Secondly you also need to use `.setLocktime()` with a valid argument during the transaction building to pass the `tx.time` check of the `timeout` function.

website/docs/community-sdks/python-sdk.md

@@ -39,7 +39,7 @@ The usage of the 4 classes in your code is as follows: before using the SDK you
 
 For more complete examples of the SDK flow, refer to the [runnable examples][examples] in the Python SDK repository.
 
-#### example
+#### Example
 
 ```python
 from cashscript_py import Contract, ElectrumNetworkProvider, Output, SignatureTemplate, TransactionBuilder

website/docs/compiler/artifacts.md

@@ -26,8 +26,10 @@ interface Artifact {
     sourceMap: string // see documentation for `generateSourceMap`
     logs: LogEntry[] // log entries generated from `console.log` statements
     requires: RequireStatement[] // messages for failing `require` statements
+    sourceTags?: string // semantic tags for opcodes (e.g. loop update/condition ranges)
   }
   updatedAt: string // Last datetime this artifact was updated (in ISO format)
+  fingerprint?: string // SHA256 of the normalized bytecode pattern (BCH bytecode fingerprinting standard)
 }
 
 interface AbiInput {
@@ -56,10 +58,11 @@ interface StackItem {
 interface RequireStatement {
   ip: number; // instruction pointer
   line: number; // line in the source code
-  message: string; // custom message for failing `require` statement
+  message?: string; // custom message for failing `require` statement
 }
 
 interface CompilerOptions {
   enforceFunctionParameterTypes?: boolean; // Enforce function parameter types (default: true)
+  enforceLocktimeGuard?: boolean; // Enforce the tx.locktime guard (default: true)
 }
 ```

website/docs/compiler/grammar.md

@@ -35,7 +35,11 @@ contractDefinition
     ;
 
 functionDefinition
-    : 'function' Identifier parameterList '{' statement* '}'
+    : 'function' Identifier parameterList functionBody
+    ;
+
+functionBody
+    : '{' statement* '}'
     ;
 
 parameterList

website/docs/compiler/script-limits.md

@@ -6,7 +6,7 @@ sidebar_label: Script & Transaction Limits
 Bitcoin Cash imposes various constraints on scripts and transactions to ensure efficient contract execution and network stability. We'll categorize these limits into 2 types: 'Contract-related limits' and 'General transaction limits'.
 
 :::note
-Some of the limits below are hard BCH consensus rules, others are standardness relay rules which are still present significant practical barriers. These relay rules however are only enforced on network propagation. You can read more about the [BCH standardness rules here][standardness-docs].
+Some of the limits below are hard BCH consensus rules, others are standardness relay rules which still present significant practical barriers. These relay rules however are only enforced on network propagation. You can read more about the [BCH standardness rules here][standardness-docs].
 :::
 
 ## Contract-related limits
@@ -76,7 +76,7 @@ For ease of development, it is standard practice to use `1,000` satoshis as dust
 
 :::note
 The standard practice of 1,000 satoshis as dust amount for outputs is for the `P2PKH`, `P2SH20` and `P2SH32` output types.
-For custom locking bytecode outputs a higher dust limits may be required, you can [find more info here][info-dust-limit].
+For custom locking bytecode outputs a higher dust limit may be required, you can [find more info here][info-dust-limit].
 :::
 
 ### Minimum Relay Fee

website/docs/guides/adversarial.md

@@ -3,7 +3,7 @@ title: Adversarial Analysis
 sidebar_label: Adversarial Analysis
 ---
 
-In this guide we'll dive into "adversarial analysis" for smart contract systems. Adversarial analysis means to analyze your system from the point of a potential malicious 3rd party which might want to hamper or attack your system. This guide will build further on knowledge from the [the transaction lifecycle guide](/docs/guides/lifecycle).
+In this guide we'll dive into "adversarial analysis" for smart contract systems. Adversarial analysis means to analyze your system from the point of a potential malicious 3rd party which might want to hamper or attack your system. This guide will build further on knowledge from the [transaction lifecycle guide](/docs/guides/lifecycle).
 
 ## The Happy Case
 
@@ -21,7 +21,7 @@ The adversarial case is where 3rd parties intentionally double spend unconfirmed
 In an adversarial environment where double spends occur, user-created transactions interacting with public are not certain to be confirmed. This means waiting for block confirmations is required to be sure the transaction isn't cancelled.
 :::
 
-There is 2 categories to consider for adversarial double spends:
+There are 2 categories to consider for adversarial double spends:
 
 1) Race-condition double spends (no miner help required)
 
@@ -37,7 +37,7 @@ For an adversarial attack to pull off this time-sensitive attack, he would requi
 
 ### Late Double Spends
 
-In the case of a late double spend (which does not try to exploit a race condition) the adversarial actor need help from a miner.
+In the case of a late double spend (which does not try to exploit a race condition) the adversarial actor needs help from a miner.
 Either the adversarial actor needs to convince the miners to abandon their first seen rule or he needs to be mining himself to be able to construct his own block.
 
 :::caution
@@ -100,7 +100,7 @@ Adversarial analysis should take into account that "first-seen rule" is just a c
 ### Specialized Block-Builders
 
 
-As described in the section on "stale-state arbitrage" economic actors may be incentivized to strategically create a competing transaction chain which takes advantage of an older price state/ratio which has not yet been confirmed in the blockchain. Although miners are not specialized in the optimal construction of DeFi transactions in a block, miner would over time be likely to team up with teams/companies creating this type of software for them.
+As described in the section on "stale-state arbitrage" economic actors may be incentivized to strategically create a competing transaction chain which takes advantage of an older price state/ratio which has not yet been confirmed in the blockchain. Although miners are not specialized in the optimal construction of DeFi transactions in a block, miners would over time be likely to team up with teams/companies creating this type of software for them.
 
 :::note
 Ethereum with its large amount of MEV has already seen the emergence of specialized 'block builder' as a new class of relevant economic actors separate from the block proposer (who signs the block).
@@ -120,7 +120,7 @@ This strategy of batching same-block trades (or "joint-execution") is the key co
 
 ### Centralized Co-signing
 
-For contract systems relying on a continuously update on-chain oracle price feed, the problem of 'stale-state arbitrage' reappears.
+For contract systems relying on a continuously updated on-chain oracle price feed, the problem of 'stale-state arbitrage' reappears.
 However in this context the only known solution to adversarial actors exploiting stale state with a late double spend is to require centralized co-signing in the contract system.
 
 The drawback of this approach is that it introduces a central party to enforce honest, sequential actions to prevent late double spends. The approach introduces the need for interactivity and assumes that the central signing service does not collude or cannot be bribed, additionally it also introduces new possible security concerns.

website/docs/guides/cashtokens.md

@@ -38,7 +38,7 @@ The maximum size for a fungible token `amount` is the max signed 64-bit integer
 
 ### Non-Fungible Tokens
 
-The `nft` info on a UTXO will only be present if the UTXO contains an NFT. The `nft` object has 2 properties: the `capability` and the `commitment`. The `commitment` is the data field for the NFT which can is allowed to be up to 128 bytes.
+The `nft` info on a UTXO will only be present if the UTXO contains an NFT. The `nft` object has 2 properties: the `capability` and the `commitment`. The `commitment` is the data field for the NFT which is allowed to be up to 128 bytes.
 
 Capability `none` then refers to an immutable NFT where the commitment cannot be changed. The `mutable` capability means the `commitment` field can change over time, usually to contain smart contract state. Lastly the `minting` capability means that the NFT can create new NFTs from the same `category`.
 
@@ -91,7 +91,7 @@ bytes tx.inputs[i].tokenCategory
 
 When accessing the `tokenCategory` through introspection the result returns `0x` (empty byte string) when that specific item does not contain tokens. If the item does have tokens it returns the `bytes32 tokenCategory`. When the item contains an NFT with a capability, the 32-byte `tokenCategory` is concatenated together with `0x01` for a mutable NFT and `0x02` for a minting NFT.
 
-If you want to check for an NFT using introspection, you have either split the `tokenCategory` from the `capability` or check the concatenation of the `tokenCategory` and `capability`.
+If you want to check for an NFT using introspection, you have to either split the `tokenCategory` from the `capability` or check the concatenation of the `tokenCategory` and `capability`.
 
 ```solidity
   // Constructor parameters: providedCategory
@@ -162,8 +162,11 @@ The easiest way to prevent issues with "junk" empty NFTs is to check that only N
 The `tokenCategory` introspection variable returns the tokenCategory in the original unreversed order, this is unlike wallets and explorers which use the reversed byte-order. So be careful about the byte-order of `tokenCategory` when working with BCH smart contracts.
 
 ```ts
-// when using a standard encoded tokenId, reverse the hex before using it in your contract
-const contract = new Contract(artifact, [reverseHex(tokenId)], { provider })
+import { swapEndianness } from '@bitauth/libauth';
+import { Contract } from 'cashscript';
+
+// when using a standard encoded tokenId, swap the endianness of the hex before using it in your contract
+const contract = new Contract(artifact, [swapEndianness(tokenId)], { provider })
 ```
 
 #### Combined BCH + CashTokens UTXOs
@@ -186,7 +189,7 @@ Signing for CashTokens inputs is designed in such a way that pre-CashTokens wall
 
 ## CashTokens Genesis transactions
 
-A CashTokens genesis transaction is a transaction which creates a new `category` of CashTokens. To create a CashTokens genesis transaction you need a `vout0` UTXO because the txid of the UTXO will be you newly created `category`.
+A CashTokens genesis transaction is a transaction which creates a new `category` of CashTokens. To create a CashTokens genesis transaction you need a `vout0` UTXO because the txid of the UTXO will be your newly created `category`.
 
 The requirement for a `vout0` UTXO can mean that you might need to create a setup transaction "pre-genesis" which will create this output. The "pre-genesis" txid then is your token's `category`.