mirror of https://github.com/lukechilds/docs.git
Patrick Gray
4 years ago
committed by
Patrick Gray
Patrick Gray
3 changed files with 205 additions and 5 deletions
@ -0,0 +1,198 @@ |
|||
--- |
|||
title: Developing with Clarinet |
|||
description: Develop smart contracts locally with the Clarinet REPL and testing harness |
|||
--- |
|||
|
|||
## Introduction |
|||
|
|||
[Clarinet][] is a local Clarity runtime packaged as a command-line application. It's designed to facilitate rapid smart |
|||
contract development, testing, and deployment. Clarinet consists of a Clarity REPL and a testing harness, which, when |
|||
used together, allow you to rapidly develop and test a Clarity smart contract, without the need to deploy the contract |
|||
to a local mocknet or testnet. |
|||
|
|||
The local Clarity REPL is advantageous, because when learning Clarity or when developing a new smart contract, it's |
|||
useful to be able to exercise a contract without needing to wait for block times in a live blockchain. Clarinet allows |
|||
you to instantly initialize wallets and populate them with tokens, so that you can interactively or programmatically |
|||
test the behavior of the smart contract. Blocks are mined instantly, and you can control the number of blocks that |
|||
are mined between testing transactions. |
|||
|
|||
Clarinet is a useful tool for developing smart contracts, and should be used as part of a larger development strategy |
|||
that involves building and testing the contract locally, deploying the final draft contract to a testnet environment |
|||
and testing on a live blockchain, and deploying the final contract to the mainnet. |
|||
|
|||
## Installing Clarinet |
|||
|
|||
The best way to install Clarinet is through the Rust package manager, Cargo. If you have a working installation of |
|||
[Rust](https://www.rust-lang.org/tools/install), use the following command to install Clarinet. |
|||
|
|||
```sh |
|||
cargo install clarinet --locked |
|||
``` |
|||
|
|||
## Developing a Clarity smart contract |
|||
|
|||
Once you have installed Clarinet, you can begin a new Clarinet project with the command: |
|||
|
|||
```sh |
|||
clarinet new my-contract && cd my-project |
|||
``` |
|||
|
|||
This command creates a new directory and populates it with boilerplate configuration and testing files. The `toml` files |
|||
located in the `settings` directory control the Clarinet environment. For example, the `Development.toml` file contains |
|||
definitions for wallets in the local REPL environment, and their starting balances (in STX). |
|||
|
|||
```toml |
|||
... |
|||
[accounts.deployer] |
|||
mnemonic = "fetch outside black test wash cover just actual execute nice door want airport betray quantum stamp fish act pen trust portion fatigue scissors vague" |
|||
balance = 1_000_000 |
|||
|
|||
[accounts.wallet_1] |
|||
mnemonic = "spoil sock coyote include verify comic jacket gain beauty tank flush victory illness edge reveal shallow plug hobby usual juice harsh pact wreck eight" |
|||
balance = 1_000_000 |
|||
|
|||
[accounts.wallet_2] |
|||
mnemonic = "arrange scale orient half ugly kid bike twin magnet joke hurt fiber ethics super receive version wreck media fluid much abstract reward street alter" |
|||
balance = 1_000_000 |
|||
... |
|||
``` |
|||
|
|||
You can create a new contract in the project with the command: |
|||
|
|||
```sh |
|||
clarinet contract new my-contract |
|||
``` |
|||
|
|||
This command creates a new `my-contract.clar` file in the `contracts` directory, and a `my-contract_test.ts` in the |
|||
`test` directory. Additionally, it adds the contract to the `Clarinet.toml` configuration file. |
|||
|
|||
```toml |
|||
[contracts.my-contract] |
|||
path = "contracts/my-contract.clar" |
|||
depends_on = [] |
|||
``` |
|||
|
|||
At this point, you can begin editing your smart contract in the `contracts` directory. At any point while you are |
|||
developing, you can use the command `clarinet check` to check the syntax of your smart contract. |
|||
|
|||
## Testing with Clarinet |
|||
|
|||
Clarinet provides several powerful methods to test and interact with your smart contracts. As mentioned in the previous |
|||
section, you can always check your Clarity syntax using the `clarinet check` command. This validates any smart contracts |
|||
you are currently developing in the active project. |
|||
|
|||
There are two methods in Clarinet you can use to test smart contracts: the [console][], an interactive Clarity REPL, and |
|||
the [test harness][], a testing framework written in Typescript. |
|||
|
|||
### Testing with the console |
|||
|
|||
The Clarinet console is an interactive Clarity REPL that runs in-memory. Any contracts configured in the current project |
|||
are automatically loaded into memory. Additionally, wallets defined in the `settings/Development.toml` file are |
|||
initialized with STX tokens for testing purposes. When the console runs, it provides a summary of the deployed |
|||
contracts, their public functions, as well as wallet addresses and balances. |
|||
|
|||
``` |
|||
clarity-repl v0.11.0 |
|||
Enter "::help" for usage hints. |
|||
Connected to a transient in-memory database. |
|||
Initialized contracts |
|||
+-------------------------------------------------------+-------------------------+ |
|||
| Contract identifier | Public functions | |
|||
+-------------------------------------------------------+-------------------------+ |
|||
| ST1HTBVD3JG9C05J7HBJTHGR0GGW7KXW28M5JS8QE.my-contract | (echo-number (val int)) | |
|||
| | (say-hi) | |
|||
+-------------------------------------------------------+-------------------------+ |
|||
|
|||
Initialized balances |
|||
+------------------------------------------------------+---------+ |
|||
| Address | STX | |
|||
+------------------------------------------------------+---------+ |
|||
| ST1HTBVD3JG9C05J7HBJTHGR0GGW7KXW28M5JS8QE (deployer) | 1000000 | |
|||
+------------------------------------------------------+---------+ |
|||
| ST1J4G6RR643BCG8G8SR6M2D9Z9KXT2NJDRK3FBTK (wallet_1) | 1000000 | |
|||
+------------------------------------------------------+---------+ |
|||
... |
|||
``` |
|||
|
|||
You can use the `::help` command for valid console commands. |
|||
|
|||
``` |
|||
>> ::help |
|||
::help Display help |
|||
::list_functions Display all the native functions available in Clarity |
|||
::describe_function <function> Display documentation for a given native function fn-name |
|||
::mint_stx <principal> <amount> Mint STX balance for a given principal |
|||
::set_tx_sender <principal> Set tx-sender variable to principal |
|||
::get_assets_maps Get assets maps for active accounts |
|||
::get_costs <expr> Display the cost analysis |
|||
::get_contracts Get contracts |
|||
::get_block_height Get current block height |
|||
::advance_chain_tip <count> Simulate mining of <count> blocks |
|||
``` |
|||
|
|||
The console commands control the state of the REPL chain, and let you get information about it and advance the chain |
|||
tip. Additionally, you can enter Clarity commands into the console and observe the result of the command. The |
|||
`::list_functions` console command prints a cheat sheet of Clarity commands. For example, in the example contract, |
|||
you could use the REPL to call the `echo-number` function in the contract with the following command: |
|||
|
|||
``` |
|||
>> (contract-call? .my-contract echo-number 42) |
|||
(ok 42) |
|||
``` |
|||
|
|||
Note that by default commands are always executed as the `deployer` address, which means you can use the shorthand |
|||
`.my-contract` without specifying a full address to the contract. If you changed the transaction address with the |
|||
`::set_tx_sender` command, you would need to provide the full address to the contract in the contract call |
|||
(`ST1HTBVD3JG9C05J7HBJTHGR0GGW7KXW28M5JS8QE.my-contract`). |
|||
|
|||
You can refer to the [Clarity language reference][] for a complete overview of all Clarity functions. |
|||
|
|||
### Testing with the test harness |
|||
|
|||
The test harness is a Deno testing library that can simulate the blockchain, exercise functions of the contract, and |
|||
make testing assertions about the state of the contract or chain. |
|||
|
|||
You can run any tests configured in the `tests` directory with the command |
|||
|
|||
```sh |
|||
clarinet test |
|||
``` |
|||
|
|||
When you create a new contract, a test suite is automatically created for it. You can populate the test suite with |
|||
unit tests as you develop the contract. |
|||
|
|||
An example unit test for the `echo-number` function is provided below: |
|||
|
|||
```ts |
|||
Clarinet.test({ |
|||
name: 'the echo-number function returns the input value ok', |
|||
async fn(chain: Chain) { |
|||
const testNum = '42'; |
|||
let block = chain.mineBlock([ |
|||
Tx.contractCall( |
|||
'ST1HTBVD3JG9C05J7HBJTHGR0GGW7KXW28M5JS8QE.my-contract', |
|||
'echo-number', |
|||
[testNum], |
|||
'ST1HTBVD3JG9C05J7HBJTHGR0GGW7KXW28M5JS8QE' |
|||
), |
|||
]); |
|||
assertEquals(block.receipts.length, 1); // assert that the block received a single tx |
|||
assertEquals(block.receipts[0].result, `(ok ${testNum})`); // assert that the result of the tx was ok and the input number |
|||
assertEquals(block.height, 2); // assert that only a single block was mined |
|||
}, |
|||
}); |
|||
``` |
|||
|
|||
For more information on assertions, review [asserts][] in the Deno standard library. For more information on the available |
|||
Clarity calls in Deno, review the [Deno Clarity library][]. |
|||
|
|||
## Additional reading |
|||
|
|||
- [Clarinet README](https://github.com/hirosystems/clarinet#clarinet) |
|||
|
|||
[clarinet]: https://github.com/hirosystems/clarinet |
|||
[console]: #testing-with-the-console |
|||
[test harness]: #testing-with-the-test-harness |
|||
[clarity language reference]: http://localhost:3000/references/language-functions |
|||
[asserts]: https://deno.land/std@0.90.0/testing/asserts.ts |
|||
[Deno Clarity library]: https://deno.land/x/clarinet@v0.6.0/index.ts |
|||
Loading…
Reference in new issue