Use MockNetworkProvider in examples

Author: rkalis

examples/announcement.ts

@@ -1,19 +1,26 @@
-import { Contract, ElectrumNetworkProvider, Output, TransactionBuilder } from 'cashscript';
+import { Contract, Output, randomUtxo, TransactionBuilder } from 'cashscript';
 import { compileFile } from 'cashc';
 import { stringify } from '@bitauth/libauth';
 import { URL } from 'url';
+import { MockNetworkProvider } from 'cashscript/dist';
 
 // Compile the Announcement contract to an artifact object
 const artifact = compileFile(new URL('announcement.cash', import.meta.url));
 
 // Initialise a network provider for network operations on MAINNET
 const addressType = 'p2sh20';
-const provider = new ElectrumNetworkProvider();
+
+// Once you're ready to send transactions on a real network (like chipnet or mainnet), use the ElectrumNetworkProvider
+// const provider = new ElectrumNetworkProvider();
+const provider = new MockNetworkProvider();
 
 // Instantiate a new contract using the compiled artifact and network provider
 // AND providing the constructor parameters (none)
 const contract = new Contract(artifact, [], { provider, addressType });
 
+// Add a mock UTXO to the mock network provider
+provider.addUtxo(contract.address, randomUtxo());
+
 // Get contract balance & output address + balance
 console.log('contract address:', contract.address);
 const contractUtxos = await contract.getUtxos();

examples/hodl_vault.cash

@@ -11,7 +11,7 @@ contract HodlVault(
     int minBlock,
     int priceTarget
 ) {
-    function spend(sig ownerSig, datasig oracleSig, bytes oracleMessage) {
+    function spend(sig ownerSig, datasig oracleSig, bytes8 oracleMessage) {
         // message: { blockHeight, price }
         bytes4 blockHeightBin, bytes4 priceBin = oracleMessage.split(4);
         int blockHeight = int(blockHeightBin);

examples/hodl_vault.ts

@@ -1,5 +1,5 @@
 import { stringify } from '@bitauth/libauth';
-import { Contract, SignatureTemplate, ElectrumNetworkProvider, TransactionBuilder, Output } from 'cashscript';
+import { Contract, SignatureTemplate, TransactionBuilder, Output, MockNetworkProvider, randomUtxo } from 'cashscript';
 import { compileFile } from 'cashc';
 import { URL } from 'url';
 
@@ -14,14 +14,18 @@ import {
 // Compile the HodlVault contract to an artifact object
 const artifact = compileFile(new URL('hodl_vault.cash', import.meta.url));
 
-// Initialise a network provider for network operations on CHIPNET
-const provider = new ElectrumNetworkProvider('chipnet');
+// Once you're ready to send transactions on a real network (like chipnet or mainnet), use the ElectrumNetworkProvider
+// const provider = new ElectrumNetworkProvider();
+const provider = new MockNetworkProvider();
 
 // Instantiate a new contract using the compiled artifact and network provider
 // AND providing the constructor parameters
 const parameters = [alicePub, oraclePub, 100000n, 30000n];
 const contract = new Contract(artifact, parameters, { provider });
 
+// Add a mock UTXO to the mock network provider
+provider.addUtxo(contract.address, randomUtxo());
+
 // Get contract balance & output address + balance
 console.log('contract address:', contract.address);
 const contractUtxos = await contract.getUtxos();

examples/mecenas.ts

@@ -1,5 +1,5 @@
 import { stringify } from '@bitauth/libauth';
-import { Contract, ElectrumNetworkProvider, Output, TransactionBuilder } from 'cashscript';
+import { Contract, MockNetworkProvider, Output, randomUtxo, TransactionBuilder } from 'cashscript';
 import { compileFile } from 'cashc';
 import { URL } from 'url';
 
@@ -9,15 +9,19 @@ import { aliceAddress, alicePkh, bobPkh } from './common.js';
 // Compile the Mecenas contract to an artifact object
 const artifact = compileFile(new URL('mecenas.cash', import.meta.url));
 
-// Initialise a network provider for network operations on CHIPNET
-const provider = new ElectrumNetworkProvider('chipnet');
+// Once you're ready to send transactions on a real network (like chipnet or mainnet), use the ElectrumNetworkProvider
+// const provider = new ElectrumNetworkProvider();
+const provider = new MockNetworkProvider();
 
 // Instantiate a new contract using the compiled artifact and network provider
 // AND providing the constructor parameters:
 // (recipient: alicePkh, funder: bobPkh, pledge: 10000)
 const pledgeAmount = 10_000n;
 const contract = new Contract(artifact, [alicePkh, bobPkh, pledgeAmount], { provider });
 
+// Add a mock UTXO to the mock network provider
+provider.addUtxo(contract.address, randomUtxo());
+
 // Get contract balance & output address + balance
 console.log('contract address:', contract.address);
 const contractUtxos = await contract.getUtxos();

examples/p2pkh.js

@@ -1,6 +1,6 @@
 import { URL } from 'url';
 import { compileFile } from 'cashc';
-import { ElectrumNetworkProvider, Contract, SignatureTemplate, TransactionBuilder } from 'cashscript';
+import { Contract, SignatureTemplate, TransactionBuilder, MockNetworkProvider, randomUtxo } from 'cashscript';
 import { stringify } from '@bitauth/libauth';
 
 // Import Alice's keys from common.ts
@@ -9,13 +9,17 @@ import { alicePkh, alicePriv, aliceAddress, alicePub } from './common.js';
 // Compile the P2PKH contract to an artifact object
 const artifact = compileFile(new URL('p2pkh.cash', import.meta.url));
 
-// Initialise a network provider for network operations on CHIPNET
-const provider = new ElectrumNetworkProvider('chipnet');
+// Once you're ready to send transactions on a real network (like chipnet or mainnet), use the ElectrumNetworkProvider
+// const provider = new ElectrumNetworkProvider();
+const provider = new MockNetworkProvider();
 
 // Instantiate a new contract using the compiled artifact and network provider
 // AND providing the constructor parameters (pkh: alicePkh)
 const contract = new Contract(artifact, [alicePkh], { provider });
 
+// Add a mock UTXO to the mock network provider
+provider.addUtxo(contract.address, randomUtxo());
+
 // Get contract balance & output address + balance
 console.log('contract address:', contract.address);
 const contractUtxos = await contract.getUtxos();
@@ -52,4 +56,4 @@ if (changeAmount > 1000n) transactionBuilder.addOutput(changeOutput);
 
 const tx = await transactionBuilder.send();
 
-console.log('transaction details:', stringify(tx));
+console.log('transaction details:', stringify(tx));

examples/p2pkh.ts

@@ -1,6 +1,6 @@
 import { stringify } from '@bitauth/libauth';
 import { compileFile } from 'cashc';
-import { ElectrumNetworkProvider, SignatureTemplate, Contract, TransactionBuilder, Output } from 'cashscript';
+import { SignatureTemplate, Contract, TransactionBuilder, Output, MockNetworkProvider, randomUtxo } from 'cashscript';
 import { URL } from 'url';
 
 // Import Alice's keys from common.ts
@@ -9,13 +9,17 @@ import { alicePkh, alicePriv, aliceAddress, alicePub } from './common.js';
 // Compile the P2PKH contract to an artifact object
 const artifact = compileFile(new URL('p2pkh.cash', import.meta.url));
 
-// Initialise a network provider for network operations on CHIPNET
-const provider = new ElectrumNetworkProvider('chipnet');
+// Once you're ready to send transactions on a real network (like chipnet or mainnet), use the ElectrumNetworkProvider
+// const provider = new ElectrumNetworkProvider();
+const provider = new MockNetworkProvider();
 
 // Instantiate a new contract using the compiled artifact and network provider
 // AND providing the constructor parameters (pkh: alicePkh)
 const contract = new Contract(artifact, [alicePkh], { provider });
 
+// Add a mock UTXO to the mock network provider
+provider.addUtxo(contract.address, randomUtxo());
+
 // Get contract balance & output address + balance
 console.log('contract address:', contract.address);
 const contractUtxos = await contract.getUtxos();

examples/transfer_with_timeout.ts

@@ -1,6 +1,6 @@
 import { stringify } from '@bitauth/libauth';
 import { compileFile } from 'cashc';
-import { Contract, ElectrumNetworkProvider, Output, SignatureTemplate, TransactionBuilder } from 'cashscript';
+import { Contract, MockNetworkProvider, Output, randomUtxo, SignatureTemplate, TransactionBuilder } from 'cashscript';
 import { URL } from 'url';
 
 // Import Bob and Alice's keys from common.ts
@@ -14,14 +14,18 @@ import {
 // Compile the TransferWithTimeout contract
 const artifact = compileFile(new URL('transfer_with_timeout.cash', import.meta.url));
 
-// Initialise a network provider for network operations on CHIPNET
-const provider = new ElectrumNetworkProvider('chipnet');
+// Once you're ready to send transactions on a real network (like chipnet or mainnet), use the ElectrumNetworkProvider
+// const provider = new ElectrumNetworkProvider();
+const provider = new MockNetworkProvider();
 
 // Instantiate a new contract using the compiled artifact and network provider
 // AND providing the constructor parameters:
 // { sender: alicePk, recipient: bobPk, timeout: 1000000 } - timeout is a past block
 const contract = new Contract(artifact, [alicePub, bobPub, 100000n], { provider });
 
+// Add a mock UTXO to the mock network provider
+provider.addUtxo(contract.address, randomUtxo());
+
 // Get contract balance & output address + balance
 console.log('contract address:', contract.address);
 const contractUtxos = await contract.getUtxos();

website/docs/basics/getting-started.md

@@ -119,7 +119,6 @@ For a code example of how to generate key-pairs with Libauth, see the [CashScrip
 
 With the instantiated contract, we can now get the contract address and get the contract balance and UTXOs in the following way:
 
-
 ```javascript
 import { ElectrumNetworkProvider, Contract } from 'cashscript';
 import artifact from './TransferWithTimeout.json' with { type: 'json' };

website/docs/sdk/examples.md

@@ -14,7 +14,8 @@ We will break up the development of the smart contract application in 4 manageab
 
 ### Creating the keypairs
 
-To put the `HodlVault.cash` contract to use in a TypeScript application, we have to use the CashScript SDK in combination with a BCH library such as [Libauth][libauth], [Mainnetjs][mainnetjs] or [BCHJS][bchjs]. These libraries are used to generate public/private keys for the contract participants.
+To put the `HodlVault.cash` contract to use in a TypeScript application, we have to use the CashScript SDK in combination with a BCH library such as [Libauth][libauth] or [Mainnetjs][mainnetjs]. These libraries are used to generate public/private keys for the contract participants.
+
 In this example we'll use [Libauth][libauth] to generate the keys `alicePriv`, `alicePub`, `oracle` & `oraclePub`. Then we can use these keys to create the smart contract.
 
 :::caution
@@ -57,11 +58,11 @@ export const oracleAddress = encodeCashAddress('bchtest', 'p2pkhWithTokens', ora
 
 ### Generating a Contract
 
-For the networkprovider, we'll use the `ElectrumNetworkProvider` from the SDK and for `Simple Transaction Builder` for this example. Once you have a smart contract address you can send funds to it. To spend the Bitcoin cash locked in the contract you will have to satisfy the spending conditions on the contract.
+For development purposes, we'll use the `MockNetworkProvider` so you can simulate transactions in a 'mock' network environment. To do proper testing, you also need to add "mock" UTXOs to the `MockNetworkProvider`.
 
 ```ts title="hodl_vault.ts"
 import { stringify } from '@bitauth/libauth';
-import { Contract, SignatureTemplate, ElectrumNetworkProvider } from 'cashscript';
+import { Contract, SignatureTemplate, MockNetworkProvider, randomUtxo } from 'cashscript';
 import { compileFile } from 'cashc';
 import { URL } from 'url';
 
@@ -74,14 +75,17 @@ import {
 // Compile the HodlVault contract to an artifact object
 const artifact = compileFile(new URL('hodl_vault.cash', import.meta.url));
 
-// Initialise a network provider for network operations on CHIPNET
-const provider = new ElectrumNetworkProvider('chipnet');
+// Initialise a network provider for network operations on MockNet
+const provider = new MockNetworkProvider();
 
 // Instantiate a new contract using the compiled artifact and network provider
 // AND providing the constructor parameters
 const parameters = [alicePub, oraclePub, 100000n, 30000n];
 const contract = new Contract(artifact, parameters, { provider });
 
+// Add a mock UTXO to the network provider
+provider.addUtxo(contract.address, randomUtxo());
+
 // Get contract balance & output address + balance
 console.log('contract address:', contract.address);
 console.log('contract balance:', await contract.getBalance());
@@ -121,7 +125,7 @@ Finally, we can put all of this together to create a working smart contract appl
 
 ```ts title="hodl_vault.ts"
 import { stringify } from '@bitauth/libauth';
-import { Contract, SignatureTemplate, ElectrumNetworkProvider } from 'cashscript';
+import { Contract, SignatureTemplate, MockNetworkProvider } from 'cashscript';
 import { compileFile } from 'cashc';
 import { URL } from 'url';
 
@@ -136,14 +140,17 @@ import {
 // Compile the HodlVault contract to an artifact object
 const artifact = compileFile(new URL('hodl_vault.cash', import.meta.url));
 
-// Initialise a network provider for network operations on CHIPNET
-const provider = new ElectrumNetworkProvider('chipnet');
+// Initialise a network provider for network operations on MockNet
+const provider = new MockNetworkProvider();
 
 // Instantiate a new contract using the compiled artifact and network provider
 // AND providing the constructor parameters
 const parameters = [alicePub, oraclePub, 100000n, 30000n];
 const contract = new Contract(artifact, parameters, { provider });
 
+// Add a mock UTXO to the network provider
+provider.addUtxo(contract.address, randomUtxo());
+
 // Fetch contract utxos
 const contractUtxos = await contract.getUtxos();
 
@@ -177,7 +184,6 @@ const transferDetails = await new TransactionBuilder({ provider })
 console.log(transferDetails);
 ```
 
-[bchjs]: https://bchjs.fullstack.cash/
 [mainnetjs]: https://mainnet.cash/
 [libauth]: https://libauth.org/
 [github-examples]: https://github.com/CashScript/cashscript/tree/master/examples