Skip to content

Commit 7bd9ba5

Browse files
mr-zwetsmr-zwets
authored
improve docs (#216)
- improved getting started - added Cauldron DEX to examples, remove transferWithTimeout - moved operators section to types page - improved notice on pragma usage - improved optimization guide - added a guide page for walletconnect - add SignatureAlgorithm to the SignatureTemplate docs - separated the SignatureTemplate docs to a separate page - Improved the 'Contract Instantiation' page sub titles
1 parent 0dd95d5 commit 7bd9ba5

File tree

10 files changed

+318
-141
lines changed

10 files changed

+318
-141
lines changed

Diff for: ‎website/docs/basics/getting-started.md

+14-7
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,22 @@ title: Getting Started
66

77
To get started with writing CashScript smart contracts quickly, it is recommended to try out the [CashScript Playground](https://playground.cashscript.org/), a web application which lets you easily write and create contracts!
88

9-
Here you will learn what a CashScript contract looks like through the `TransferWithTimeout` example contract. Then you can compile the contract and provide the contract arguments to create a smart contract address. To actually create the smart contract itself, you fund the address so that it has a UTXO on the contract address. After setting up the smart contract, you can try spending from the smart contract by invoking a contract function!
9+
The Playground supports 'Mocknet', allowing you to create virtual UTXOs for development without having to get Testnet coins and set up a Testnet wallet.
1010

1111
:::tip
12-
The [CashScript Playground](https://playground.cashscript.org/) is a great way to get started without doing any JavaScript coding to set up wallets, fetch balances and invoke contract functions. This way you can focus on learning one thing at a time!
12+
The [CashScript Playground](https://playground.cashscript.org/) is a great way to get started without doing any JavaScript/TypeScript coding to set up wallets, fetch balances and invoke contract functions. This way you can focus on learning just CashScript!
1313
:::
1414

15-
## Creating a CashScript Smart Contract
15+
Here are the 5 simple steps for creating your first smart contract transaction with the Playground:
16+
1. Compile a contract, for example the default `TransferWithTimeout` contract.
17+
2. Create a new contract in the 'New Contract' tab by providing the contract arguments.
18+
3. Add UTXOs to the smart contract address and the wallets used for testing.
19+
4. Next, go to the TansactionBuilder select the contract and the function to invoke
20+
5. Finally, specify the in- and outputs for the transaction and click 'Send'!
1621

17-
With the CashScript playground there's a nice integrated editor to get started, as well as an integrated compiler to change your CashScript contract into a Contract `Artifact` behind the scenes. Now, to get started we will have to set up a CashScript editor — outside of the Playground — and learn how to work with the `cashc` compiler to create CashScript contract artifacts.
22+
## Creating a CashScript Contract
23+
24+
To get started coding locally we will use a code editor and learn how to work with the `cashc` compiler to create CashScript contract artifacts.
1825

1926
### Prerequisites
2027

@@ -37,7 +44,7 @@ The command line CashScript compiler `cashc` can be installed from NPM.
3744
npm install -g cashc
3845
```
3946

40-
### Writing your first smart contract
47+
### Writing your first contract
4148

4249
Open your code editor to start writing your first CashScript smart contract.
4350
We can start from a basic `TransferWithTimeout` smart contract. Create a new file `TransferWithTimeout.cash`.
@@ -65,7 +72,7 @@ contract TransferWithTimeout(pubkey sender, pubkey recipient, int timeout) {
6572
There are some other examples available on the [Examples page](/docs/language/examples) that can be used to take inspiration from. Further examples of the TypeScript and JavaScript integration can be found on [GitHub](https://github.com/CashScript/cashscript/tree/master/examples).
6673
:::
6774

68-
### Compiling your smart contract
75+
### Compiling your contract
6976

7077
The next step after writing your smart contract is using the command line compiler to create a contract artifact, so that it can be imported into the CashScript SDK.
7178

@@ -81,7 +88,7 @@ OP_3 OP_PICK OP_0 OP_NUMEQUAL OP_IF OP_4 OP_ROLL OP_ROT OP_CHECKSIG OP_NIP OP_NI
8188

8289
## Creating a CashScript Transaction
8390

84-
After creating a contract artifact, we can now use the TypeScript SDK to initialise the smart contract and to invoke spending functions on the smart contract UTXOs. We'll continue with the `TransferWithTimeout` artifact generated in the previous steps.
91+
After creating a contract artifact, we can now use the TypeScript SDK to initialise the smart contract and to invoke spending functions on the smart contract UTXOs. We'll continue with the `TransferWithTimeout` artifact generated earlier.
8592

8693
:::info
8794
The CashScript SDK is written in TypeScript meaning that you can either use TypeScript or vanilla JavaScript to use the SDK.

Diff for: ‎website/docs/guides/optimization.md

+34-42
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,26 @@ sidebar_label: Optimization
55

66
CashScript contracts are transpiled from a solidity syntax to [BCH Script](https://reference.cash/protocol/blockchain/script) by the `cashc` compiler. BCH Script is a lower level language (a list of stack-based operations) where each available operation is mapped to a single byte.
77

8-
Depending on the complexity of the contract or system design, it may sometimes be useful to optimize the Bitcoin Script by tweaking the contract in CashScript before it is compiled. Below are some ideas to get started.
8+
Depending on the complexity of the contract or system design, it may be useful to optimize the Bitcoin Script by tweaking the contract in CashScript before it is compiled because the minimum fees on the Bitcoin Cash network are based on the bytesize of a transaction (including your contract).
9+
10+
## Example Workflow
11+
12+
When optimizing your contract, you will need to compare the contract size to see if the changes have a positive impact.
13+
With the compiler CLI, you can easily check the opcode count and bytesize directly from the generated contract artifact.
14+
15+
```bash
16+
cashc ./contract.cash --opcount --size
17+
```
18+
19+
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.
20+
21+
:::note
22+
The compiler opcount and bytesize outputs are still helpful to compare the effect of changes to the smart contract code on the compiled output, given that the contract constructor arguments stay the same.
23+
:::
24+
25+
:::tip
26+
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`.
27+
:::
928

1029
## Optimization Tips & Tricks
1130

@@ -73,52 +92,25 @@ The concept of having NFT functions was first introduced by the [Jedex demo](htt
7392
By using function NFTs you can use a modular contract design where the contract functions are offloaded to different UTXOs, each identifiable by the main contract by using the same tokenId.
7493
:::
7594

76-
## Example Workflow
77-
78-
When trying to optimize your contract, you will need to compare the contract size to see if the changes have a positive impact.
79-
With the compiler CLI, you can easily check the opcode count and bytesize directly from the contract (without creating a new artifact).
80-
It's important to know the minimum fees on the Bitcoin Cash network are based on the bytesize of a transaction (including your contract).
81-
82-
```bash
83-
cashc ./contract.cash --opcount --size
84-
```
85-
86-
:::caution
87-
The size output of the `cashc` compiler will always be an underestimate, as the contract hasn't been initialized with contract arguments.
88-
:::
89-
90-
The `cashc` compiler only knows the opcount and bytesize of a contract before it is initialised with function arguments. Because of this, to get an accurate view of a contracts size, initialise the contract instance first, then get the size from there. This means you will have to re-compile the artifact before checking the contract size through the TypeScript SDK.
95+
## Hand-optimizing Bytecode
9196

92-
```javascript
93-
import { ElectrumNetworkProvider, Contract, SignatureTemplate } from 'cashscript';
94-
import { alicePub, bobPriv, bobPub } from './keys.js';
95-
import { compileFile } from 'cashc';
97+
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 things like transaction size.
9698

97-
// compile contract code on the fly
98-
const artifact = compileFile(new URL('contract.cash', import.meta.url));
99+
>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%.
99100
100-
// Initialise a network provider for network operations
101-
const provider = new ElectrumNetworkProvider('chipnet');
101+
### Overwriting the Artifact
102102

103-
// Instantiate a new TransferWithTimeout contract
104-
const contractArguments = [alicePub, bobPub, 100000n]
105-
const options = { provider }
106-
const contract = new Contract(artifact, contractArguments, options);
103+
To manually change the contract bytecode, you need to overwrite the `bytecode` key of your contract artifact.
107104

108-
console.log(contract.opcount);
109-
console.log(contract.bytesize);
105+
```typescript
106+
interface Artifact {
107+
bytecode: string // Compiled Script without constructor parameters added (in ASM format)
108+
}
110109
```
111110

112-
With this workflow, you can make changes to the contract and the run the JavaScript program to
113-
get an accurate measure of how the bytesize of your contract changes with different optimizations.
114-
115-
## To optimize or not to optimize?
116-
117-
In the context of optimizing contract bytecode, there's an important remark to consider:
118-
119-
### OP_NOP
120-
121-
>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%.
122-
123-
It's worth considering whether optimizing the redeem script is necessary at all. If the contract is accepted by the network, and there is no glaring inefficiency in the bytecode, perhaps the best optimization is to not to obsess prematurely about things like block size.
111+
This way you can still use the CashScript TypeScript SDK while using a hand-optimized contract.
124112

113+
:::caution
114+
If you manually overwite the `bytecode` in the artifact, this will make the auto generated 2-way-mapping to become obsolete.
115+
This result of this is that the dubugging functionality will no longer work for the contract.
116+
:::

Diff for: ‎website/docs/guides/walletconnect.md

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: WalletConnect
3+
---
4+
5+
The BCH WalletConnect specification was created in July of 2023 and has become popular since. The standard integrates nicely with CashScript contract development as it was designed with CashScript contract usage in mind.
6+
7+
You can find a full list of Bitcoin Cash dapps supporting WalletConnect on [Tokenaut.cash](https://tokenaut.cash/dapps?filter=walletconnect).
8+
9+
:::tip
10+
The specification is called ['wc2-bch-bcr'](https://github.com/mainnet-pat/wc2-bch-bcr) and has extra discussion and info on the [BCH research forum](https://bitcoincashresearch.org/t/wallet-connect-v2-support-for-bitcoincash/).
11+
:::
12+
13+
## signTransaction Interface
14+
15+
Most relevant for smart contract usage is the BCH-WalletConnect `signTransaction` interface.
16+
17+
> This is a most generic interface to propose a bitcoincash transaction to a wallet which reconstructs it and signs it on behalf of the wallet user.
18+
19+
```typescript
20+
signTransaction: (
21+
options: {
22+
transaction: string | TransactionBCH,
23+
sourceOutputs: (Input | Output | ContractInfo)[],
24+
broadcast?: boolean,
25+
userPrompt?: string
26+
}
27+
) => Promise<{ signedTransaction: string, signedTransactionHash: string } | undefined>;
28+
```
29+
30+
Important to note is how the wallet knows which inputs to sign:
31+
32+
>To signal that the wallet needs to sign an input, the app sets the corresponding input's `unlockingBytecode` to empty Uint8Array.
33+
34+
## signTransaction Example
35+
36+
### Create wcTransactionObj
37+
38+
Example code from the 'Cash-Ninjas' minting dapp repository, [link to source code](https://github.com/cashninjas/ninjas.cash/blob/main/js/mint.js).
39+
40+
```javascript
41+
import { Contract } from "cashscript";
42+
import { hexToBin, decodeTransaction } from "@bitauth/libauth";
43+
44+
async function transactionWalletConnect(){
45+
// use the CashScript SDK to build a transaction
46+
const rawTransactionHex = await transaction.build();
47+
const decodedTransaction = decodeTransaction(hexToBin(rawTransactionHex));
48+
49+
// set input unlockingBytecode to empty Uint8Array for wallet signing
50+
decodedTransaction.inputs[1].unlockingBytecode = Uint8Array.from([]);
51+
52+
// construct list SourceOutputs, see source code
53+
const listSourceOutputs = constructSourceOuputs(decodedTransaction, utxoInfo, contract)
54+
55+
// wcTransactionObj to pass to signTransaction endpoint
56+
const wcTransactionObj = {
57+
transaction: decodedTransaction,
58+
sourceOutputs: listSourceOutputs,
59+
broadcast: true,
60+
userPrompt: "Mint Cash-Ninja NFT"
61+
};
62+
63+
// pass wcTransactionObj to WalletConnect client
64+
const signResult = await signTransaction(wcTransactionObj);
65+
66+
// Handle signResult success / failure
67+
}
68+
```
69+
70+
### signTransaction Client interaction
71+
72+
Below is an implementation of `signTransaction` used earlier, this is where the communication with the client for 'signTransaction' takes place. See the source code for `signClient`, `connectedChain` and `session` details.
73+
74+
```javascript
75+
import SignClient from '@walletconnect/sign-client';
76+
import { stringify } from "@bitauth/libauth";
77+
78+
async function signTransaction(options){
79+
try {
80+
const result = await signClient.request({
81+
chainId: connectedChain,
82+
topic: session.topic,
83+
request: {
84+
method: "bch_signTransaction",
85+
params: JSON.parse(stringify(options)),
86+
},
87+
});
88+
return result;
89+
} catch (error) {
90+
return undefined;
91+
}
92+
}
93+
```

Diff for: ‎website/docs/language/contracts.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,10 @@ title: Contract Structure
55
Contracts in CashScript are somewhat similar to classes in object-oriented languages. A notable difference is that there is no mutable state. So once a contract is instantiated with certain parameters, these values cannot change. Instead, functions can be called on the contract that act on the contract's values to spend money from the contract. The extension of CashScript source code files is `.cash`, and the structure of these source files is explained below.
66

77
## Pragma
8-
A contract file may start with a pragma directive to indicate the CashScript version the contract was written for. This ensures that a contract is not compiled with an unsupported compiler version, which could cause unintended side effects.
8+
A contract file may start with a pragma directive to indicate the CashScript version the contract was written for. This ensures that a contract is not compiled with an unsupported compiler version. The pragma directive follows regular [semantic versioning (SemVer)](https://semver.npmjs.com/) rules.
99

10-
:::note
11-
The pragma directive follows regular [semantic versioning rules](https://semver.npmjs.com/).
10+
:::caution
11+
Contract authors should be careful when allowing a range of versions to check that no breaking changes to the compiler were introduced in these versions which would result in different bytecode and smart contract address.
1212
:::
1313

1414
#### Example
@@ -82,7 +82,7 @@ contract P2PKH(bytes20 pkh) {
8282
### Variable declaration
8383
Variables can be declared by specifying their type and name. All variables need to be initialised at the time of their declaration, but can be reassigned later on — unless specifying the `constant` keyword. Since CashScript is strongly typed and has no type inference, it is not possible to use keywords such as `var` or `let` to declare variables.
8484

85-
:::caution
85+
:::note
8686
CashScript disallows variable shadowing and unused variables.
8787
:::
8888

0 commit comments

Comments
 (0)