Skip to content

Commit 8bbad29

Browse files
rkalisrkalis
committed
Update documentation
- Add README and LICENSE to the individual packages - Update main README to include both packages - Update exitsing documentation to reflect changes
1 parent 79b144e commit 8bbad29

8 files changed

Lines changed: 225 additions & 87 deletions

File tree

‎README.md‎

Lines changed: 54 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,43 +6,83 @@
66
[![NPM Monthly Downloads](https://img.shields.io/npm/dm/cashscript.svg)](https://www.npmjs.com/package/cashscript)
77
[![NPM License](https://img.shields.io/npm/l/cashscript.svg)](https://www.npmjs.com/package/cashscript)
88

9-
CashScript is a high level language enabling basic smart contract functionality on Bitcoin Cash. We love the Ethereum development ecosystem, and with CashScript we want to bring part of that workflow into the Bitcoin Cash ecosystem.
9+
CashScript is a high level language enabling basic smart contract functionality on Bitcoin Cash. While these cash contracts are less powerful than Ethereum's smart contracts, CashScript was in many ways inspired by Ethereum's development ecosystem. Ethereum has always had one of the most accessible development ecosystems in terms of tooling, and with CashScript we want to bring that accessibility to Bitcoin Cash.
10+
11+
---
1012

1113
**Attention:** CashScript is in active development, and is currently in a `beta` phase. While CashScript is in `beta` stage, its APIs and usage is subject to change, so be sure to check the documentation. During the `beta` phase it is possible that the library still contains bugs, so for now the CashScript SDK can only be used on the `testnet` network.
1214

13-
## Installation
14-
The CashScript SDK can be installed through `yarn` or `npm`:
15+
This repository contains the code for the CashScript compiler & command line tool under [`packages/cashc`](/packages/cashc). This repository also contains the code for the CashScript JavaScript SDK under [`packages/cashscript`](/packages/cashscript). This README includes the basic documentation for both of these packages, but their respective package directories go into a bit more detail.
16+
17+
## The CashScript Language
18+
CashScript is a high-level language that allows you to write Cash Contracts in a straightforward and familiar way. It is inspired by Ethereum's Solidity, but it is not the same, and cash contracts work very differently from Ethereum's smart contracts. See the [Language documentation](/docs/language.md) for a full reference of the language.
19+
20+
## The CashScript Compiler
21+
CashScript features a compiler as a standalone command line tool, called `cashc`. It can be installed through npm and used to compile `.cash` files into `.json` artifact files. These artifact files can be imported into the CashScript JavaScript SDK (or other SDKs in the future). Note that the CashScript SDK also has a fnuction to import and compile `.cash` files directly, so it is not required to use the `cashc` command line tool.
1522

23+
For more information on `cashc`, refer to its [README](/packages/cashc).
24+
25+
### Installation
1626
```bash
17-
yarn add cashscript
27+
npm install -g cashc
1828
```
29+
30+
### Usage
1931
```bash
20-
npm install cashscript
32+
Usage: cashc [options] [source_file]
33+
34+
Options:
35+
--output, -o Specify a file to output the generated artifact.
36+
[string] [required]
37+
--help Show help [boolean]
38+
--version Show version number [boolean]
2139
```
2240

23-
From here it can be imported into your TypeScript or JavaScript projects:
41+
## The CashScript SDK
42+
The main way to interact with cash contracts and integrate them into applications is using the CashScript SDK. This SDK allows you to compile `.cash` files or import `.json` artifact files, and convert them to `Contract` objects. These objects are used to create new contract instances. These instances are used to interact with the contracts using the functions that were implemented in the `.cash` file. For more information on the CashScript SDK, refer to its [README](/packages/cashscript) or the [full SDK documentation](/docs/sdk.md).
43+
44+
### Installation
45+
```bash
46+
npm install cashscript
47+
```
2448

49+
### Usage
2550
```ts
26-
import { ... } from 'cashscript';
51+
import { Contract, ... } from 'cashscript';
2752
```
2853

2954
```js
30-
const { ... } = require('cashscript');
55+
const { Contract, ... } = require('cashscript');
3156
```
3257

33-
## The CashScript Language
34-
CashScript is a high-level language that allows you to write Cash Contracts in a straightforward and familiar way. It is inspired by Ethereum's Solidity, but it is not the same, and cash contracts work very differently from Ethereum's smart contracts. See the [Language documentation](/docs/language.md) for a full reference of the language.
58+
Using the CashScript SDK, you can import / compile existing cash contract files, create new instances of these contracts, and interact with these instances:
3559

36-
## The CashScript SDK
37-
The CashScript SDK allows you to easily integrate cash contracts written with CashScript into your JavaScript or TypeScript applications. It allows you to compile contracts, instantiate them, and use their functions as defined in the `.cash` file. See the [SDK documentation](/docs/sdk.md) for a full reference of the SDK.
60+
```ts
61+
...
62+
// Compile the P2PKH Cash Contract
63+
const P2PKH: Contract = Contract.fromCashFile('p2pkh.cash', 'testnet');
64+
65+
// Instantiate a new P2PKH contract with constructor arguments: { pkh: pkh }
66+
const instance: Instance = P2PKH.new(pkh);
67+
68+
// Get contract balance & output address + balance
69+
const contractBalance: number = await instance.getBalance();
70+
console.log('contract address:', instance.address);
71+
console.log('contract balance:', contractBalance);
72+
73+
// Call the spend function with the owner's signature
74+
// And use it to send 0. 000 100 00 BCH back to the contract's address
75+
const tx: TxnDetailsResult = await instance.functions.spend(pk, new Sig(keypair, 0x01))
76+
.send(instance.address, 10000);
77+
console.log('transaction details:', tx);
78+
...
79+
```
3880

3981
## Examples
4082
If you want to see CashScript in action and check out its usage, there are several example contracts in the [`examples/`](/examples) directory. The `.cash` files contain example contracts, and the `.ts` files contain example usage of the CashScript SDK to interact with these contracts.
4183

4284
The "Hello World" of cash contracts is defining the P2PKH pattern inside a cash contract, which can be found under [`examples/p2pkh.cash`](/examples/p2pkh.cash). Its usage can be found under [`examples/p2pkh.ts`](/examples/p2pkh.ts) or [`examples/p2pkh-artifact.ts`](/examples/p2pkh-artifact.ts).
4385

44-
Note that not all of these examples have been tested to work, and are also still a work in progress.
45-
4686
### Running the examples
4787
To run the examples, clone this repository and navigate to the `examples/` directory. Since the examples depend on the SDK, be sure to run `npm install` or `yarn` inside the `examples/` directory, which installs all required packages.
4888

‎docs/language.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -224,3 +224,40 @@ See the following table for information on which types can be cast to other whic
224224
| pubkey | bytes | bytes |
225225
| sig | bytes | bytes, datasig |
226226
| datasig | bytes | bytes |
227+
228+
## Artifacts
229+
Compiled cash contracts can be represented by so-called artifacts. These artifacts can be stored in `.json` files so they can be shared and stored for later usage without recompilation. These artifacts allow any third-party SDKs to be developed, as they only need to be able to import and use an artifact file, while leaving the compilation to the `cashc` command line tool.
230+
231+
### Artifact specification
232+
```ts
233+
interface Artifact {
234+
contractName: string; // Contract name
235+
constructorInputs: AbiInput[]; // Arguments required to instantiate a contract
236+
abi: AbiFunction[]; // functions that can be called
237+
bytecode: string; // Compiled Script without constructor parameters added (in ASM format)
238+
source: string; // Source code of the CashScript contract
239+
networks: { // Dictionary per network (testnet / mainnet)
240+
[network: string]: { // Dictionary of contract addresses with the corresponding compiled script (in ASM format)
241+
[address: string]: string;
242+
};
243+
};
244+
compiler: {
245+
name: string; // Compiler used to compile this contract
246+
version: string; // Compiler version used to compile this contract
247+
}
248+
updatedAt: string; // Last datetime this artifact was updated (in ISO format)
249+
}
250+
251+
interface AbiInput {
252+
name: string; // Input name
253+
type: string; // Input type (see language documentation)
254+
}
255+
256+
interface AbiFunction {
257+
name: string; // Function name
258+
inputs: AbiInput[]; // Function inputs / parameters
259+
}
260+
```
261+
262+
## Examples
263+
For example real world uses of these functions and cash contracts check out the [examples folder](/examples/). This folder contains several example contracts as `.cash` files, and example SDK usage in the `.ts` files.

‎docs/sdk.md‎

Lines changed: 9 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# The CashScript SDK
22
## Contract
3-
The `Contract` class allows you to compile CashScript files into `Contract` objects, from which these contracts can be instantiated and interacted with. These `Contract` objects can also be imported from a JSON Artifact file, and exported to one, which allows you to store and transfer the contract definition in JSON format, so you don't need to recompile the contract every time you use it. For more information on Artifacts, see [Artifacts](#artifacts).
3+
The `Contract` class allows you to compile CashScript files into `Contract` objects, from which these contracts can be instantiated and interacted with. These `Contract` objects can also be imported from a JSON Artifact file, and exported to one, which allows you to store and transfer the contract definition in JSON format, so you don't need to recompile the contract every time you use it. For more information on Artifacts, see the [Language Documentation](/docs/language.md).
44

55
### Creating a Contract object
66
Before instantiating a contract, first you need to create a new `Contract` object. This can be done by compiling a CashScript file, or by importing an Artifact file that was exported previously.
@@ -13,14 +13,14 @@ const P2PKH: Contract = Contract.fromCashFile('p2pkh.cash', 'testnet');
1313
```
1414

1515
##### `Contract.fromArtifact(fn: string, network?: string): Contract`
16-
Imports an Artifact file that was compiled and exported previously. This file is found at the path specified by argument `fn`. Optionally specify a network string (`'testnet'` or `'mainnet'`) to connect with. Returns a `Contract` object that can be further used to instantiate new instances of this contract.
16+
Imports an Artifact file that was compiled previously. This file is found at the path specified by argument `fn`. Optionally specify a network string (`'testnet'` or `'mainnet'`) to connect with. Returns a `Contract` object that can be further used to instantiate new instances of this contract.
1717

1818
```ts
1919
const P2PKH: Contract = Contract.fromArtifact('p2pkh.json', 'testnet');
2020
```
2121

2222
### Exporting a contract
23-
This `Contract` object can be exported to an Artifact file to be imported at a later moment, so it can be stored or transfered more easily, and can be used without recompilation. If the object is exported after one or more new contracts have been instantiated, their details will be stored in the file as well so they can be easily accessed later on.
23+
A `Contract` object can be exported to an Artifact file to be imported at a later moment, so it can be stored or transfered more easily, and can be used without recompilation. If the object is exported after one or more new contracts have been instantiated, their details will be stored in the file as well so they can be easily accessed later on.
2424

2525
##### `contract.export(fn: string): void`
2626
Writes the contract's details to an Artifact file found at the location specified by argument `fn`, so it can be retrieved later. If the file does not exist yet, it is created. If the file already exists, **it is overwritten**.
@@ -48,11 +48,15 @@ const instance: Instance = P2PKH.deployed('bchtest:ppzllwzk775qk86zfskzyzae7pa9h
4848
```
4949

5050
## Instance
51-
After instantiating a new contract or retrieving a previously deployed one, this instance can be interacted with using the functions that are defined on the contract in your CashScript file.
51+
After instantiating a new contract or retrieving a previously deployed one, this instance can be interacted with using the functions implemented in the `.cash` file.
5252

5353
##### `instance.address`
5454
An instance's address can be retrieved through the `address` member field.
5555

56+
```ts
57+
console.log(instance.address);
58+
```
59+
5660
##### `async instance.getBalance(): Promise<number>`
5761
Returns the total balance of the contract in satoshis. This incudes confirmed and unconfirmed balance.
5862

@@ -70,7 +74,7 @@ const tx = await instance.functions.spend(pk, new Sig(keypair, 0x01))
7074

7175
**A note on transaction signatures:**
7276

73-
Some cash contract functions require a signature parameter, which needs to be a valid transaction signature for the current transaction, which is unknown at the time of calling a contract function. This is why we have a separate `Sig` class made up of a keypair and hashtype, that represents these signatures.
77+
Some cash contract functions require a signature parameter, which needs to be a valid transaction signature for the current transaction. The current transaction details are unknown at the time of calling a contract function. This is why we have a separate `Sig` class made up of a keypair and hashtype, that represents a placeholder for these signatures. These placeholders are automatically replaced by the correct signature during the transaction building phase.
7478

7579
##### `new Sig(keypair: ECPair, hashtype: number)`
7680
Creates a placeholder for a transaction signature of the current transaction. During the transaction building phase this placeholder is replaced by the actual signature.
@@ -120,61 +124,3 @@ await instance.functions.spend(pk, new Sig(keypair, 0x01)).meep([
120124

121125
## Examples
122126
For example real world uses of these functions and cash contracts check out the [examples folder](/examples/). This folder contains several example contracts as `.cash` files, and example SDK usage in the `.ts` files.
123-
124-
---
125-
126-
## Advanced usage
127-
The `Contract` class satisfies all expected needs for creating and interacting with cash contracts. If you do wish to compile CashScript manually, or if you wish to access specific Artifact fields for your own custom usage, you can use the compilation and Artifact functions directly.
128-
129-
### CashScript compilation
130-
The SDK offers two separate functions for compilation that both compile CashScript code to an Artifact object. This Artifact object can then be used to instantiate contracts and interact with them. See [Application Blockchain Interface](#application-blockchain-interface) for more information on the Artifact format.
131-
132-
##### `compileFile(codeFile: string): Artifact`
133-
Reads a file found at the path specified by argument `codeFile`. Returns an Artifact object.
134-
135-
##### `compile(code: string): Artifact`
136-
Reads a CashScript contract in string format. For most use cases `compileFile` will be used instead, as it is usual to write cash contracts in separate files. `compile` might be used when storing contracts in JSON files or databases instead, but this is not likely to be common. Returns an Artifact object.
137-
138-
### Artifacts
139-
Compiled cash contracts are represented using Artifacts. These Artifacts contain all the details that are required to create new contract instances and use their functions.
140-
141-
It is not necessary to understand the way these Artifacts work, because they are used under the hood to generate more accessible interfaces. If you want to manually use Artifacts though, you can use the functions and interface specified below.
142-
143-
##### `importArtifact(artifactFile: string): Artifact`
144-
Reads a JSON file containing an Artifact specfication at the path specified by argument `artifactFile`. Returns the processed Artifact specification as an Artifact object.
145-
146-
##### `exportArtifact(artifact: Artifact, targetFile: string): void`
147-
Writes argument `artifact` to a file at the path specified by argument `targetFile` in JSON format. This JSON file can be imported again using the `importArtifact` function.
148-
149-
### Artifact specification
150-
```ts
151-
interface Artifact {
152-
contractName: string; // Contract name
153-
constructorInputs: AbiInput[]; // to instantiate a contract
154-
abi: AbiFunction[]; // functions that can be called
155-
uninstantiatedScript: Script; // Compiled Script without constructor parameters added
156-
source: string; // Source code of the CashScript contract
157-
networks: { // Dictionary per network (testnet / mainnet)
158-
[network: string]: { // Dictionary of contract addresses with the corresponding compiled Script
159-
[address: string]: Script;
160-
};
161-
};
162-
compiler: {
163-
name: string; // Compiler used to compile this contract
164-
version: string; // Compiler version used to compile this contract
165-
}
166-
updatedAt: string; // Last date time this artifact was updated
167-
}
168-
169-
interface AbiInput {
170-
name: string; // Input name
171-
type: string; // Input type (see language documentation)
172-
}
173-
174-
interface AbiFunction {
175-
name: string; // Function name
176-
inputs: AbiInput[]; // Function inputs / parameters
177-
}
178-
179-
type Script = Buffer | number;
180-
```

‎packages/cashc/LICENSE‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Copyright 2019 Rosco Kalis
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4+
5+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6+
7+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

0 commit comments

Comments
 (0)