Skip to content

Commit 6cad4dc

Browse files
mr-zwetsmr-zwets
committed
improve TypeScript SDK docs
1 parent 522d154 commit 6cad4dc

3 files changed

Lines changed: 53 additions & 35 deletions

File tree

‎website/docs/compiler/compiler.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ title: Compiler
55
The CashScript compiler is called `cashc` and is used to compile CashScript `.cash` contract files into `.json` (or `.ts`) artifact files.
66
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).
77

8+
:::info
9+
Because of the separation of the compiler and the SDK, CashScript contracts can be integrated into other programming languages in the future.
10+
:::
11+
812
## Command Line Interface
913

1014
The `cashc` command line interface is used to compile CashScript `.cash` files into `.json` (or `.ts`) artifact files.

‎website/docs/guides/optimization.md‎

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,13 @@ contract Example(){
139139

140140
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.
141141

142-
## Hand-optimizing Bytecode
142+
## Advanced: Hand-optimizing Bytecode
143+
144+
You can still use the CashScript TypeScript SDK while using a hand-optimized or hand-written contract, although this is considered advanced functionality.
145+
146+
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.
147+
148+
### Note on Premature Optimizations
143149

144150
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.
145151

@@ -149,15 +155,13 @@ It's worth considering whether hand-optimizing the contract is necessary at all.
149155

150156
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.
151157

152-
### Overwriting the Artifact
158+
### Method 1) Custom Artifact
153159

154160
To manually optimize a CashScript contract's bytecode, you need to overwrite the `bytecode` key of your contract artifact.
155161

156162
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.
157163
This causes the link of the BCH opcodes to your original CashScript code will be entirely lost for debugging.
158164

159-
You can still use the CashScript TypeScript SDK while using a hand-optimized or hand-written contract.
160-
161165

162166
```typescript
163167
interface Artifact {
@@ -175,4 +179,28 @@ If you use hand-optimized `bytecode` in your Contract's artifact, the `debug` in
175179
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.
176180
:::
177181

182+
### Method 2) Custom Unlockers
183+
184+
In the [addInput() method](./transaction-builder#addInput()) on the TransactionBuilder you can provide a custom `Unlocker`
185+
186+
```ts
187+
transactionBuilder.addInput(utxo: Utxo, unlocker: Unlocker, options?: InputOptions): this
188+
```
189+
190+
the `Unlocker` interface is the following:
191+
192+
```ts
193+
interface Unlocker {
194+
generateLockingBytecode: () => Uint8Array;
195+
generateUnlockingBytecode: (options: GenerateUnlockingBytecodeOptions) => Uint8Array;
196+
}
197+
198+
interface GenerateUnlockingBytecodeOptions {
199+
transaction: Transaction;
200+
sourceOutputs: LibauthOutput[];
201+
inputIndex: number;
202+
}
203+
```
204+
205+
178206
[BitauthIDE]: https://ide.bitauth.com

‎website/docs/sdk/typescript-sdk.md‎

Lines changed: 17 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,26 @@
22
title: TypeScript SDK
33
---
44

5-
CashScript offers a TypeScript SDK, which makes it easy to build smart contract transactions, both in browser or on the server. By offering full type-safety, developers can be confident in the quality and reliability of their applications. The SDK can also be used easily in vanilla JavaScript codebases, although the benefits of the type-safety will be lost.
5+
CashScript offers a TypeScript SDK, which makes it easy to build smart contract transactions, both in browser or on the server.
6+
The CashScript SDK enables advanced debugging tooling for CashScript contracts, standardized network providers to get BCH blockchain information and a simple API for transaction building when using smart contracts.
7+
8+
The TypeScript SDK has [full TypeScript integration](#full-typescript-integration) with the CashScript smart contract language.
9+
The full type-safety enables clear APIs which communicates info about the expected argument to each function and method.
10+
This in turn speeds up development time and allows for higher code quality with better safety guarantees.
611

712
:::info
8-
Because of the separation of the compiler and the SDK, CashScript contracts can be integrated into other programming languages in the future.
13+
The SDK can also be used easily in vanilla JavaScript codebases, although the benefits of the type-safety will be lost.
914
:::
1015

11-
## SDK Classes
16+
## When to use the SDK
17+
18+
The CashScript TypeScript SDK is designed to make it as easy as possible to create smart contract transactions for contracts written in CashScript (the smart contract language). So we highly recommend using the SDK when using CashScript to write your smart contracts.
19+
20+
If you are not using the CashScript contract language, you can still use the CashScript SDK for transaction building and BCH networking functionality! This can be especially useful if you are familiar with the CashScript classes and want manual control over the input and outputs in a transaction. The SDK makes it easy to spend from P2PKH inputs and send to different types of outputs, including OP_RETURN data outputs.
21+
22+
It's also possible the use the CashScript SDK for hand-optimized contract **not** written with the CashScript contract language, but this is considered [advanced usage](#advanced-non-cashscript-contracts).
23+
24+
## The 4 SDK Classes
1225

1326
The CashScript SDK consists of 4 classes, together they form one cohesive structure to build BCH smart contract applications.
1427
The documentation also follows the structure of these 4 classes:
@@ -51,31 +64,4 @@ The constructor of the `Contract` class takes in an `Artifact`, this is the outp
5164

5265
You can also use the CashScript SDK without relying on the CashScript contract language and compiler. This way you can still leverage the a lot of the tooling while having full control over the raw BCH script so this can be hand-written or hand-optimized.
5366

54-
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.
55-
56-
### Custom Artifacts
57-
58-
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.
59-
60-
### Custom Unlockers
61-
62-
In the [addInput() method](./transaction-builder#addInput()) on the TransactionBuilder you can provide a custom `Unlocker`
63-
64-
```ts
65-
transactionBuilder.addInput(utxo: Utxo, unlocker: Unlocker, options?: InputOptions): this
66-
```
67-
68-
the `Unlocker` interface is the following:
69-
70-
```ts
71-
interface Unlocker {
72-
generateLockingBytecode: () => Uint8Array;
73-
generateUnlockingBytecode: (options: GenerateUnlockingBytecodeOptions) => Uint8Array;
74-
}
75-
76-
interface GenerateUnlockingBytecodeOptions {
77-
transaction: Transaction;
78-
sourceOutputs: LibauthOutput[];
79-
inputIndex: number;
80-
}
81-
```
67+
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. These two methods for using hand optimized contract bytecode are discussed in the [optimization guide](../guides/optimization#hand-optimizing-bytecode).

0 commit comments

Comments
 (0)