add TypeScript SDK page & improve other pages (#383)

Author: mr-zwets

website/docs/basics/about-bch.md

@@ -8,14 +8,14 @@ Bitcoin Cash (ticker BCH) is one of the biggest cryptocurrencies. Bitcoin Cash i
 Bitcoin Cash shares many of the same fundamentals as Bitcoin (BTC) like the *Proof-of-Work* consensus algorithm and the *UTXO data-model*. However regarding smart contract programmability, Bitcoin Cash has significantly diverged from Bitcoin (BTC). We will go over the main differences between BCH and BTC, and then delve into the smart contract capabilities of Bitcoin Cash!
 
 :::info
-To learn more about the Bitcoin Basics refer to the book ['Mastering Bitcoin'](https://github.com/bitcoinbook/bitcoinbook). The core of Bitcoin's design is still very much the same in Bitcoin Cash. To learn more about BCH's transaction lifecycle, see the dedicated guide ['Transaction Lifecycle'](/docs/guides/lifecycle).
+To learn more about the Bitcoin Basics refer to the book ['Mastering Bitcoin'][Mastering Bitcoin]. The core of Bitcoin's design is still very much the same in Bitcoin Cash. To learn more about BCH's transaction lifecycle, see the dedicated guide ['Transaction Lifecycle'](/docs/guides/lifecycle).
 :::
 
 ## 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.
 
-So part that **has** significantly diverged between BTC and BCH is the *virtual machine* (VM), the environment in which smart contracts are evaluated. So the greatly improved VM specifically is what makes it possible to write powerful smart contracts on BCH in the first place!
+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.
 
 ## 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.
@@ -39,7 +39,7 @@ Bitcoin Cash has had many script upgrades, including transaction introspection a
 Smart contracts on Bitcoin Cash only have access to the current transaction context, which enables 'local state'. This model allows transactions to be verified independently and efficiently. Because there is no global state that can impact the execution of these smart contracts, the results are deterministic and predictable.
 
 :::tip
-The UTXO model where transactions only have access to the local transaction context enables parallel transaction validation and is the reason why Bitcoin Cash is hugely scalable!
+The UTXO model where transactions only have access to the local transaction context enables parallel transaction validation and is the reason why Bitcoin Cash is hugely scalable with low fees!
 :::
 
 ### Bitcoin Cash Script
@@ -48,10 +48,13 @@ The locking and unlocking scripts of regular transactions and smart contracts on
 
 ### CashScript
 
-CashScript is a high-level programming language for smart contracts on Bitcoin Cash that offers a strong abstraction for a smoother development experience. CashScript fully abstracts the management of items on the 'stack' from developers, allowing them to focus on their application logic instead of low-level details.
+CashScript is a high-level programming language for smart contracts on Bitcoin Cash that offers a strong abstraction for a smoother development experience. CashScript fully abstracts the management of items on the 'stack' from contract developers, allowing them to focus on their application logic instead of low-level details.
 
 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.
 
 :::info
-Bitcoin's "Local State" versus Ethereum's "Global State" requires a very different mental model and way to structure smart contract applications!
+Bitcoin Cash's "Local State" versus Ethereum's "Global State" requires a very different mental model and way to structure smart contract applications!
 :::
+
+[Mastering Bitcoin]: https://github.com/bitcoinbook/bitcoinbook
+[BCH upgrades]: https://upgradespecs.bitcoincashnode.org/

website/docs/compiler/compiler.md

@@ -5,6 +5,10 @@ title: Compiler
 The CashScript compiler is called `cashc` and is used to compile CashScript `.cash` contract files into `.json` (or `.ts`) artifact files.
 These artifact files can be used to instantiate a CashScript contract with the help of the CashScript SDK. For more information on this artifact format refer to [Artifacts](/docs/compiler/artifacts).
 
+:::info
+Because of the separation of the compiler and the SDK, CashScript contracts can be integrated into other programming languages in the future.
+:::
+
 ## Command Line Interface
 
 The `cashc` command line interface is used to compile CashScript `.cash` files into `.json` (or `.ts`) artifact files.

website/docs/guides/covenants.md

@@ -147,7 +147,7 @@ Covenants can also use 'simulated state', where state is kept in the contract sc
 
 To demonstrate the concept of 'local state' we consider the Mecenas contract again, and focus on a drawback of this contract: you have to claim the funds at exactly the right moment or you're leaving money on the table. Every time you claim money from the contract, the `this.age` counter is reset, so the next claim is possible 30 days after the previous claim. So if we wait a few days to claim, **these days are basically wasted**.
 
-Besides these wasted days it can also be inconvenient to claim at set intervals, rather than the "streaming" model that the Ethereum project [Sablier](https://www.sablier.finance/) employs. Instead of set intervals, you should be able to claim funds at any time during the "money stream". Using local state, we can approach a similar system with BCH.
+Besides these wasted days it can also be inconvenient to claim at set intervals, rather than the "streaming" model that the Ethereum project [Sablier][Sablier] employs. Instead of set intervals, you should be able to claim funds at any time during the "money stream". Using local state, we can approach a similar system with BCH.
 
 ```solidity
 // Mutable NFT Commitment contract state
@@ -328,3 +328,4 @@ We have discussed the main uses for covenants as they exist on Bitcoin Cash toda
 Keeping local state in NFTs and issuing NFTs as receipts are two strategies which can be used to create much more sophisticated decentralized applications. You can read more of these advanced CashTokens use cases in our [dedicated guide](/docs/guides/cashtokens#cashtokens-use-cases)!
 
 [bitcoin-covenants]: https://fc16.ifca.ai/bitcoin/papers/MES16.pdf
+[Sablier]: https://www.sablier.finance/

website/docs/guides/lifecycle.md

@@ -37,7 +37,7 @@ The "first-seen rule" is a default mempool inclusion and relay rule for full nod
 On BTC the mempool node default policy got changed to replace-by-fee, and tooling to submit your non-standard transaction directly to mining pools has become commonplace with ordinals.
 :::
 
-The first-seen rule is subjective based on time, because of this different parts of the network might enforce this rule for conflicting transactions in case of a race condition. For P2PKH transactions a trustless notification system was developed called [double-spend-proofs](https://docs.bitcoincashnode.org/doc/dsproof-implementation-notes/) (DSPs). However DSPs unfortunately do not work for smart contract transactions.
+The first-seen rule is subjective based on time, because of this different parts of the network might enforce this rule for conflicting transactions in case of a race condition. For P2PKH transactions a trustless notification system was developed called [double-spend-proofs][double-spend-proofs] (DSPs). However DSPs unfortunately do not work for smart contract transactions.
 
 ## Unconfirmed Transaction Chains
 
@@ -81,7 +81,7 @@ A "Chain Reorganization" or reorg for short is when the full nodes discard the c
 
 
 :::tip
-A great resource to learn more details about reorgs is the ['Chain Reorganization'](https://learnmeabitcoin.com/technical/blockchain/chain-reorganization/) page on the info website learn-me-a-bitcoin.
+A great resource to learn more details about reorgs is the ['Chain Reorganization'][chain-reorganization] page on the info website learn-me-a-bitcoin.
 :::
 
 :::note
@@ -90,3 +90,6 @@ Many exchanges however use a 6-block confirmation policy for Bitcoin Cash deposi
 :::
 
 Chain reorgs don't always include all the same transactions, so some transactions can get un-included from the blockchain with a reorg. In this scenario, if no competing transaction was mined then the un-included transaction will just return to the mempool waiting for inclusion in a next block.
+
+[double-spend-proofs]: https://docs.bitcoincashnode.org/doc/dsproof-implementation-notes/
+[chain-reorganization]: https://learnmeabitcoin.com/technical/blockchain/chain-reorganization/

website/docs/guides/optimization.md

@@ -139,25 +139,29 @@ contract Example(){
 
 In Cashscript, when defining multiple functions, a `selectorIndex` parameter is added under-the-hood to select which of the contract's functions you want to use, this wraps your functions in big `if-else` cases. However when combining multiple functions in one cases you will have to think about the function conditions and `if-else` branching yourself.
 
-## Hand-optimizing Bytecode
+## Advanced: Hand-optimizing Bytecode
+
+You can still use the CashScript TypeScript SDK while using a hand-optimized or hand-written contract, although this is considered advanced functionality.
+
+There's two ways to go about this, either you create a custom `Artifact` so you can still use the `Contract` class or you create a custom `Unlocker` to use in the transaction building directly.
+
+### Note on Premature Optimizations
 
 It's worth considering whether hand-optimizing the contract is necessary at all. If the contract works and there is no glaring inefficiency in the bytecode, perhaps the best optimization is to not to obsess prematurely about the transaction size with Bitcoin Cash's negligible fees.
 
 >We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil. Yet we should not pass up our opportunities in that critical 3%.
 
 ### Optimizing with the BitauthIDE
 
-When optimizing the bytecode of your contract to ensure it is the smallest possible bytesize you'll likely want to use the [BitauthIDE](https://ide.bitauth.com) so you can see the stack changes for each executed OpCode. Low-level understanding can also give good intuition about the [optimization tips](#optimization-tips) for the CashScript code.
+When optimizing the bytecode of your contract to ensure it is the smallest possible bytesize you'll likely want to use the [BitauthIDE][BitauthIDE] so you can see the stack changes for each executed OpCode. Low-level understanding can also give good intuition about the [optimization tips](#optimization-tips) for the CashScript code.
 
-### Overwriting the Artifact
+### Method 1) Custom Artifact
 
 To manually optimize a CashScript contract's bytecode, you need to overwrite the `bytecode` key of your contract artifact.
 
 If you manually overwrite the `bytecode` in the artifact, the auto generated 2-way-mapping generated by the compiler becomes obsolete. You are no longer compiling high-level CashScript code into BCH script, instead you are writing BCH script by hand.
 This causes the link of the BCH opcodes to your original CashScript code will be entirely lost for debugging.
 
-You can still use the CashScript TypeScript SDK while using a hand-optimized or hand-written contract.
-
 
 ```typescript
 interface Artifact {
@@ -172,7 +176,33 @@ If you use hand-optimized `bytecode` in your Contract's artifact, the `debug` in
 :::
 
 :::tip
-You can create an `Artifact` for a fully hand-written contract so it becomes possible to use the contract with the nice features of the CashScript SDK! An example of this is [Cauldron_Swap_Test](https://github.com/mr-zwets/Cauldron_Swap_Test) which uses `Artifact bytecode` not produced by `cashc` at all but still uses the CashScript SDK.
+You can create an `Artifact` for a fully hand-written contract so it becomes possible to use the contract with the nice features of the CashScript SDK! An example of this is [Cauldron_Swap_Test][Cauldron_Swap_Test] which uses `Artifact bytecode` not produced by `cashc` at all but still uses the CashScript SDK.
 :::
 
+### Method 2) Custom Unlockers
+
+In the [addInput() method][addInput()] on the TransactionBuilder you can provide a custom `Unlocker`
+
+```ts
+transactionBuilder.addInput(utxo: Utxo, unlocker: Unlocker, options?: InputOptions): this
+```
+
+the `Unlocker` interface is the following:
+
+```ts
+interface Unlocker {
+  generateLockingBytecode: () => Uint8Array;
+  generateUnlockingBytecode: (options: GenerateUnlockingBytecodeOptions) => Uint8Array;
+}
+
+interface GenerateUnlockingBytecodeOptions {
+  transaction: Transaction;
+  sourceOutputs: LibauthOutput[];
+  inputIndex: number;
+}
+```
+
+
 [BitauthIDE]: https://ide.bitauth.com
+[Cauldron_Swap_Test]: https://github.com/mr-zwets/Cauldron_Swap_Test
+[addInput()]: /docs/sdk/transaction-builder#addinput

website/docs/language/examples.md

@@ -2,7 +2,7 @@
 title: Examples
 ---
 
-An extensive collection of examples is available in the [GitHub repository](https://github.com/CashScript/cashscript/tree/master/examples). Below we discuss a few of these examples in more details and go through their functionality. This example page focuses on the CashScript syntax, while the [SDK Examples page](/docs/sdk/examples) in the SDK section focuses on use of the SDK to build an application.
+An extensive collection of examples is available in the [GitHub repository][GitHub-CashScript-Examples]. Below we discuss a few of these examples in more details and go through their functionality. This example page focuses on the CashScript syntax, while the [SDK Examples page](/docs/sdk/examples) in the SDK section focuses on use of the SDK to build an application.
 
 ## HodlVault
 For better or worse, HODLing and waiting for price increases is one of the main things people want to do with their cryptocurrency. But it can be difficult to hold on to your cryptocurrency when the price is going down. So to prevent weak hands from getting the best of you, it's better to store your stash in a smart contract that enforces HODLing for you.
@@ -90,7 +90,7 @@ contract Mecenas(bytes20 recipient, bytes20 funder, int pledge, int period) {
 
 ## AMM DEX
 
-AMM DEX contract based on [the Cauldron DEX contract](https://www.cauldron.quest/_files/ugd/ae85be_b1dc04d2b6b94ab5a200e3d8cd197aa3.pdf), you can read more details about the contract design there.
+AMM DEX contract based on [the Cauldron DEX contract][Cauldron-Whitepaper], you can read more details about the contract design there.
 
 The CashScript contract code has the big advantage of abstracting away any stack management, having variable names, explicit types and a logical order of operations (compared to the 'reverse Polish notation' of raw script).
 
@@ -135,6 +135,9 @@ contract DexContract(bytes20 poolOwnerPkh) {
 }
 ```
 
-Compared to the manually written and hand-optimized opcodes version of the contract, the CashScript compiled bytecode has just 5 extra opcodes overhead (7 extra bytes). Furthermore, even contracts with hand-optimized bytecode can still be used with the CashScript SDK, [find out more in the optimization guide](/docs/guides/optimization#hand-optimizing-bytecode).
+Compared to the manually written and hand-optimized opcodes version of the contract, the CashScript compiled bytecode has just 5 extra opcodes overhead (7 extra bytes). Furthermore, even contracts with hand-optimized bytecode can still be used with the CashScript SDK, [find out more in the optimization guide](/docs/guides/optimization#advanced-hand-optimizing-bytecode).
 
 More advanced examples on covenants, using NFTs to keep local state and issuing NFTs as receipts can be found in the [Covenants & Introspection Guide](/docs/guides/covenants).
+
+[GitHub-CashScript-Examples]: https://github.com/CashScript/cashscript/tree/master/examples
+[Cauldron-Whitepaper]: https://www.cauldron.quest/_files/ugd/ae85be_b1dc04d2b6b94ab5a200e3d8cd197aa3.pdf

website/docs/releases/release-notes.md

@@ -24,6 +24,10 @@ title: Release Notes
 - :hammer_and_wrench: Improve libauth template generation.
 - :bug: Fix bug where `SignatureTemplate` would not accept private key hex strings as a signer.
 
+---
+
+https://x.com/CashScriptBCH/status/1973692336782876974
+
 ## v0.11.5
 
 #### CashScript SDK

website/docs/sdk/electrum-network-provider.md

@@ -2,11 +2,17 @@
 title: Electrum Network Provider
 ---
 
-The CashScript SDK needs to connect to the BCH network to perform certain operations, like retrieving the contract's balance, or sending transactions. By default the network provider is an `ElectrumNetworkProvider`.
+The CashScript SDK needs to connect to the BCH network to perform certain operations, like retrieving the contract's balance, or sending transactions. The recommended network provider is the `ElectrumNetworkProvider`.
 
-## ElectrumNetworkProvider
+## Creating an ElectrumNetworkProvider
 
-The ElectrumNetworkProvider uses [@electrum-cash/network][electrum-cash] to connect to the BCH network. Both `network` and `options` parameters are optional, and they default to mainnet with the `bch.imaginary.cash` electrum server.
+The ElectrumNetworkProvider uses [@electrum-cash/network][electrum-cash] library to connect to the configured electrum server. The connection uses a single, trusted electrum server so it does no have any fallback logic and does not validate SPV proofs for chain inclusion.
+
+By default the `ElectrumNetworkProvider` creates a short-lived connection only when requests are pending. To configure this see the section on '[Manual Connection Management](#manual-connection-management)'.
+
+### Constructor
+
+Both `network` and `options` parameters are optional, and they default to `mainnet` with the `bch.imaginary.cash` electrum server.
 
 ```ts
 new ElectrumNetworkProvider(network?: Network, options?: Options)
@@ -44,6 +50,9 @@ const hostname = 'chipnet.bch.ninja';
 const provider = new ElectrumNetworkProvider('chipnet', { hostname });
 ```
 
+## ElectrumNetworkProvider Methods
+
+
 ### getUtxos()
 ```ts
 async provider.getUtxos(address: string): Promise<Utxo[]>;
@@ -143,5 +152,27 @@ provider.disconnect(): Promise<boolean>;
 
 Disconnects from the electrum client, returns `true` if the client was connected, `false` if it was already disconnected.
 
+## Using electrum-cash functionality
+
+To use more of the electrum-specific functionality which is not exposed in the `ElectrumNetworkProvider` you can simply call the methods on the electrum Client itself.
+
+### Custom Electrum Client
+
+When initializing an `ElectrumNetworkProvider` you have the option in the constructor to provide a custom electrum client. This way you can use one and the same indexer server for blockchain information but use it through two different interfaces. This allows you to access all underlying functionality of the [@electrum-cash/network][electrum-cash] library like address and blockHeight subscriptions.
+
+If intending to use electrum-cash subscriptions, make sure to set `manualConnectionManagement` to true, so the `ElectrumNetworkProvider` does not disconnect after each request.
+
+#### example
+
+```ts
+import { ElectrumClient } from '@electrum-cash/network';
+import { ElectrumNetworkProvider } from 'cashscript';
+
+const electrum = new ElectrumClient('CashScript Application', '1.4.1', 'chipnet.bch.ninja');
+const provider = new ElectrumNetworkProvider(Network.CHIPNET, {
+  electrum, manualConnectionManagement: true
+});
+await electrum.connect();
+```
 
 [electrum-cash]: https://www.npmjs.com/package/@electrum-cash/network