update docs for VM Limits & BigInts

Author: mr-zwets

website/docs/compiler/vmlimits.md

@@ -0,0 +1,42 @@
+---
+title: Bitcoin Cash VM Limits
+sidebar_label: VM Limits
+---
+
+Bitcoin Cash enforces VM limits to ensure secure and efficient contract execution. When developing with CashScript, keep these limits in mind to ensure your contracts run smoothly without encountering transaction errors due to size or computational constraints.
+
+## Maximum Contract Size
+
+The Bitcoin Cash VM has a **maximum size for smart contracts** which limits the length of input bytecode to **1,650 bytes**. While typical contracts stay well below this, complex contracts with extensive logic might require adjustments to fit within this constraint.
+
+### Modular Contract Design
+
+If your contract includes multiple functions, consider a modular design. Separating contract logic into independent components allows each function to be deployed as a smaller contract, reducing the overall transaction size. This approach can naturally divide complex contracts without impacting functionality. For more on this, see the guide on [Contract Optimization](/docs/guides/optimization).
+
+## Operation Cost Limit
+
+Bitcoin Cash also enforces an **operation cost limit** (op-cost) on each transaction input. The op-cost limit controls the computational budget available for operations in a contract and is calculated based on the input length, with each byte allowing for a higher maximum opereraction cost.
+
+```ts
+function maxOperationCost(unlockingBytecodeLength) {
+  return (41n + unlockingBytecodeLength) * 800n;
+}
+```
+
+With this formula, increasing your input length allows for a larger compute budget. You can view specific op-costs for each operation in the [op-cost-table][op-cost-table], which outlines the compute cost of operation.
+
+### Buying Compute Budget
+
+To increase your contract's compute budget for resource-intensive operations (e.g., cryptographic hashing or large number calculations), you can use zero-padding to extend the input length. By adding non-essential, zero-value bytes, you effectively buy more computation power for your contract without adding functional complexity. This technique could be useful for contracts requiring a higher operation budget, allowing them to meet the contract's computational demands without exceeding the op-cost limit.
+
+## Other Limits
+
+For completeness, here are additional Bitcoin Cash VM limits relevant to CashScript development:
+
+- **Signature Operation Count** (SigChecks) Limits the number of signature verifications (e.g. `OP_CHECKSIG`, `OP_CHECKDATASIG`) per transaction to ensure efficient validation. 
+
+- **Hashing Limit**: Limits the number of hashing operations (e.g. `OP_SHA256`, `OP_HASH160`) allowed per transaction to prevent excessive resource usage.
+
+- **Stack Element Byte Length**: Each stack element has a maximum length of 10,000 bytes. This limit also affects the size of Pay-to-Script-Hash (P2SH) contracts which are pushed as an element to the stack on spending.
+
+[op-cost-table]: https://github.com/bitjson/bch-vm-limits/blob/master/operation-costs.md

website/docs/guides/optimization.md

@@ -13,7 +13,7 @@ When optimizing your contract, you will need to compare the contract size to see
 With the compiler CLI, you can easily check the opcode count and bytesize directly from the generated contract artifact.
 
 ```bash
-cashc ./contract.cash --opcount --size
+cashc ./contract.cash --size --opcount
 ```
 
 The size outputs of the `cashc` compiler are based on the bytecode without constructor arguments. This means they will always be an underestimate, as the contract hasn't been initialized with contract arguments.
@@ -23,7 +23,7 @@ The compiler opcount and bytesize outputs are still helpful to compare the effec
 :::
 
 :::tip
-To get the exact contract opcount and bytesize including constructor parameters, initialise the contract with the TypScript SDK and check the values of `contract.opcount` and `contract.bytesize`.
+To get the exact contract bytesize including constructor parameters, initialise the contract with the TypScript SDK and check the value of `contract.bytesize`.
 :::
 
 ## Optimization Tips & Tricks

website/docs/language/types.md

@@ -20,7 +20,7 @@ The operators `||` and `&&` don't apply common short-circuiting rules. This mean
 :::
 
 ## Integer
-`int`: Signed integer of 64 bit size.
+`int`: Signed integer of arbitrary size (BigInt).
 
 Operators:
 
@@ -33,14 +33,6 @@ Note the lack of the `**` (exponentiation) operator as well as any bitwise opera
 
 Underscores can be used to separate the digits of a numeric literal to aid readability, e.g. `1_000_000`. Numbers can also be formatted in scientific notation, e.g. `1e6` or `1E6`. These can also be combined, e.g. `1_000e6`.
 
-#### Over- & Underflows
-
-The maximum range for 64-bit integers is `-9223372036854775807` to `9223372036854775807`, operations exceeding these limits will fail the transaction. So operations like summation, subtraction and multiplication should take into account these boundary cases with over- or underflows.
-
-:::caution
-Contract authors should always consider whether `+`, `-` and `*` operations can cause under- or overflows and how this would impact contract security.
-:::
-
 #### Division by Zero
 
 The script will fail when the right hand side of division or modulo operations is zero.

website/docs/sdk/instantiation.md

@@ -91,23 +91,27 @@ console.log(contract.tokenAddress)
 contract.opcount: number
 ```
 
-The number of opcodes in the contract's bytecode can be retrieved through the `opcount` member field. This is useful to ensure that the contract is not too big, since Bitcoin Cash smart contracts can contain a maximum of 201 opcodes.
+The number of opcodes in the contract's bytecode can be retrieved through the `opcount` member field.
 
 #### Example
 ```ts
-assert(contract.opcount <= 201)
+console.log(contract.opcount)
 ```
 
 ### bytesize
 ```ts
 contract.bytesize: number
 ```
 
-The size of the contract's bytecode in bytes can be retrieved through the `bytesize` member field. This is useful to ensure that the contract is not too big, since Bitcoin Cash smart contracts can be 520 bytes at most.
+The size of the contract's bytecode in bytes can be retrieved through the `bytesize` member field. This is useful to ensure that the contract is not too big, since Bitcoin Cash smart contracts can be 1,650 bytes at most.
+
+:::info
+The size outputs of the `cashc` compiler are based on the bytecode without constructor arguments. This means they will always be an underestimate, as the contract hasn't been initialized with contract arguments.
+:::
 
 #### Example
 ```ts
-console.log(contract.bytesize)
+assert(contract.bytesize <= 1650)
 ```
 
 ### bytecode

website/sidebars.js

@@ -25,6 +25,7 @@ module.exports = {
       label: 'Compiler',
       items: [
         'compiler/compiler',
+        'compiler/vmlimits',
         'compiler/artifacts',
         'compiler/grammar',
       ],