add 'setBlockHeight' method to MockNetworkProvider & add to docs

packages/cashscript/src/network/MockNetworkProvider.ts

@@ -13,6 +13,7 @@ export default class MockNetworkProvider implements NetworkProvider {
   private utxoMap: Record<string, Utxo[]> = {};
   private transactionMap: Record<string, string> = {};
   public network: Network = Network.MOCKNET;
+  public blockHeight: number = 133700;
 
   constructor() {
     for (let i = 0; i < 3; i += 1) {
@@ -27,8 +28,12 @@ export default class MockNetworkProvider implements NetworkProvider {
     return this.utxoMap[lockingBytecode] ?? [];
   }
 
+  setBlockHeight(newBlockHeight: number): void {
+    this.blockHeight = newBlockHeight;
+  }
+
   async getBlockHeight(): Promise<number> {
-    return 133700;
+    return this.blockHeight;
   }
 
   async getRawTransaction(txid: string): Promise<string> {

website/docs/guides/debugging.md

@@ -49,7 +49,7 @@ const uri = await transactionBuilder.bitauthUri();
 ```
 
 :::caution
-It is unsafe to debug transactions on mainnet as private keys will be exposed to BitAuth IDE and transmitted over the network.
+It is unsafe to debug transactions on mainnet using the BitAuth IDE as private keys will be exposed to BitAuth IDE and transmitted over the network.
 :::
 
 The Bitauth IDE will show you the two-way mapping between the CashScript contract code generated opcodes. Here is [a Bitauth IDE link][BitauthIDE] for the basic `TransferWithTimeout` contract as an example:

website/docs/releases/release-notes.md

@@ -19,6 +19,7 @@ This release also contains several breaking changes, please refer to the [migrat
   - Output BitAuth IDE URI for debugging when transaction is rejected.
   - Libauth template generation and debugging for multi-contract transactions
 - :sparkles: Debugging now supports using the optimised contract bytecode (when compiled with `cashc@0.11.0` or later).
+- :sparkles: Add `setBlockHeight()` method to `MockNetworkProvider`
 - :sparkles: Config-free usage of the CashScript SDK with Vite or Webpack
 - :hammer_and_wrench: Update debug tooling to use the new `BCH_2025_05` instruction set.
 - :hammer_and_wrench: Deprecate the simple transaction builder. You can still use the simple transaction builder with the current SDK, but this support will be removed in a future release.

website/docs/sdk/other-network-providers.md

@@ -9,7 +9,10 @@ The CashScript SDK needs to connect to the BCH network to perform certain operat
 new MockNetworkProvider()
 ```
 
-The `MockNetworkProvider` is a special network provider that allows you to evaluate transactions locally without interacting with the Bitcoin Cash network. This is useful when writing automated tests for your contracts, or when debugging your contract locally. You can read more about the `MockNetworkProvider` and automated tests on the [testing setup](/docs/sdk/testing-setup) page.
+The `MockNetworkProvider` is a special network provider that allows you to evaluate transactions locally without interacting with the Bitcoin Cash network. This is useful when writing automated tests for your contracts, or when debugging your contract locally. 
+
+The `MockNetworkProvider` has extra methods to enable this local emulation such as `.addUtxo()` and `.setBlockHeight()`.
+You can read more about the `MockNetworkProvider` and automated tests on the [testing setup](/docs/sdk/testing-setup) page.
 
 #### Example
 ```ts
@@ -18,7 +21,7 @@ const newUtxo = randomUtxo({satoshis: 10_000n})
 provider.addUtxo(contractAddress, newUtxo);
 ```
 
-The network type of the `MockNetworkProvider`.
+The network type of the `MockNetworkProvider` is `'mocknet'`.
 
 ## Other NetworkProviders
 

website/docs/sdk/testing-setup.md

@@ -10,7 +10,9 @@ For a quick start with a CashScript testing setup, check out the [example testin
 
 ## MockNetworkProvider
 
-The `MockNetworkProvider` is a special network provider that allows you to evaluate transactions locally without interacting with the Bitcoin Cash network. This is useful when writing automated tests for your contracts, or when debugging your contract locally. To create a new virtual UTXO use `provider.addUtxo()`.
+The `MockNetworkProvider` is a special network provider that allows you to evaluate transactions locally without interacting with the Bitcoin Cash network. This is useful when writing automated tests for your contracts, or when debugging your contract locally.
+
+To create a new virtual UTXO use `provider.addUtxo(address, uxto)`. You can use the helper functions `randomUtxo()`, `randomToken()` and `randomNFT()` to generate random partial Utxo info which you can be overwritten with custom values. 
 
 #### Example
 
@@ -27,7 +29,7 @@ const aliceUtxo = provider.addUtxo(aliceAddress, randomUtxo({
 ```
 
 :::note
-The `MockNetworkProvider` only evaluates the transactions locally, so any UTXOs added to a transaction still count as "unspent", even after mocking a `sendTransaction` using the provider.
+The `MockNetworkProvider` evaluates transactions locally but does not process the transaction updates. This means no UTXOs are consumed and no new UTXOs are created when mocking a transaction `send` using the provider.
 :::
 
 ## Automated testing

website/docs/sdk/transaction-builder.md

@@ -247,7 +247,7 @@ If you prefer a lower-level debugging experience, you can call the `bitauthUri()
 You can read more about debugging transactions on the [debugging page](/docs/guides/debugging).
 
 :::caution
-It is unsafe to debug transactions on mainnet as private keys will be exposed to BitAuth IDE and transmitted over the network.
+It is unsafe to debug transactions on mainnet using the BitAuth IDE as private keys will be exposed to BitAuth IDE and transmitted over the network.
 :::
 
 ## Transaction errors

website/docs/sdk/transactions.md

@@ -257,7 +257,7 @@ If you prefer a lower-level debugging experience, you can call the `bitauthUri()
 You can read more about debugging transactions on the [debugging page](/docs/guides/debugging).
 
 :::caution
-It is unsafe to debug transactions on mainnet as private keys will be exposed to BitAuth IDE and transmitted over the network.
+It is unsafe to debug transactions on mainnet using the BitAuth IDE as private keys will be exposed to BitAuth IDE and transmitted over the network.
 :::
 
 ## Transaction errors