Add scoping information to docs and clarify mutability of function/contract parameters

Author: rkalis

website/docs/language/contracts.md

@@ -31,7 +31,7 @@ contract HTLC(pubkey sender, pubkey recipient, int expiration, bytes32 hash) {
 
 ### Constructor Arguments
 
-The constructor arguments are provided when initializing a specific instance of a smart contract. The provided constructor arguments are added to the start of the contract's script before the opcode logic. Because the constructor arguments are part of the full smart contract script, they are conceptually similar to hard-coded constants in your contract logic. Constructor arguments are a way to create 'global constants' accessible from different functions inside your contract.
+The constructor arguments are provided when initializing a specific instance of a smart contract. The provided constructor arguments are added to the start of the contract's script before the opcode logic. Because the constructor arguments are part of the full smart contract script, they are conceptually similar to hard-coded values in your contract logic. Constructor arguments are a way to create 'global variables' accessible from different functions inside your contract. Note that constructor arguments are variables and can be reassigned inside the contract functions.
 
 :::info
 The typings for the constructor arguments are only semantic and used when initializing the contract with the SDK. This means when not using the SDK you could still pass a different byte length item to `bytes32 hash`.
@@ -61,18 +61,20 @@ contract TransferWithTimeout(pubkey sender, pubkey recipient, int timeout) {
 
 ### Function Arguments
 
-The function arguments are provided when attempting to spend from the contract. This means that these arguments can be crafted in a specific way by anyone to see if they can exploit the contract logic. Because of this it is important to realize these are 'untrusted arguments'.
+Function arguments are provided by the user in the unlocking script of the transaction inputs when spending from the contract. Note that function arguments are variables and can be reassigned inside the function body.
+
+Because the arguments are provided by the user when spending from the contract, these are 'untrusted arguments'. This means that these arguments can be crafted in a specific way by anyone to see if they can exploit the contract logic.
+
+:::note
+Function parameters are passed in the reversed order of their declaration. This can be important when debugging, optimizing or when creating transactions manually.
+:::
 
 In CashScript the types for the function arguments are **not** enforced automatically at the contract level. This can be especially relevant for types like `bool`, `bytesX` and other semantic bytes types. Instead this type information is only used by the SDK to check whether these arguments match the expected type during transaction building.
 
 :::caution
 The typings for the function arguments are only semantic, this means the length of bounded bytes types like `bytes20` are **not** contract enforced automatically. Instead add an explicit length check `require(item.length == 20)`.
 :::
 
-:::note
-Function parameters are passed in the reversed order of their declaration. This can be important when debugging, optimizing or when creating transactions manually.
-:::
-
 ## Statements
 CashScript functions are made up of a collection of statements that determine whether money may be spent from the contract.
 
@@ -172,6 +174,51 @@ contract P2PKH(bytes20 pkh) {
 }
 ```
 
+## Scope
+
+CashScript uses nested scopes for parameters, variables and global functions. There cannot be two identical names within the same scope or within a nested scope.
+
+There are the following scopes in the nesting order:
+
+- **Global scope** - contains global functions and global variables (e.g. `sha256`, `hash160`, `checkSig`, etc.)
+- **Contract scope** - contains contract parameters
+- **Function scope** - contains function parameters and local variables
+- **Local scope** - contains local variables introduced by control flow blocks (e.g. `if`, `else`)
+
+#### Example
+```solidity
+// Global scope (contains global functions and global variables like sha256, hash160, checkSig, etc.)
+
+// Contract scope (contains contract parameters - sender, recipient, timeout)
+contract TransferWithTimeout(
+    pubkey sender,
+    pubkey recipient,
+    int timeout
+) {
+    // Function scope (contains function parameters - recipientSig)
+    function transfer(sig recipientSig) {
+        require(checkSig(recipientSig, recipient));
+    }
+
+    // Function scope (contains function parameters - senderSig)
+    function timeout(sig senderSig) {
+        require(checkSig(senderSig, sender));
+
+        // Local scope (contains local variable - newTimeout)
+        // This is just an example local scope, not a real contract
+        if (timeout > 100_000) {
+            int newTimeout = 100_000;
+            require(tx.time >= newTimeout);
+        } else {
+            require(tx.time >= timeout);
+        }
+
+        // After the local scope, 'newTimeout' is no longer accessible
+    }
+}
+
+```
+
 ## Comments
 Comments can be added anywhere in the contract file. Comment semantics are similar to languages like JavaScript or C. This means that single-line comments can be added with `// ...`, while multiline comments can be added with `/* ... */`.