Clarity and its accompanying toolset are in early release. If you encounter issues with or have feature requests regarding Clarity, please create an issue on the blockstack/stacks-blockchain repository. To read previous or join ongoing discussions about smart contracts in general and Clarity in particular, visit the Smart Contracts topic in the Blockstack Forum. +
+
+Note that we're importing modules form the `@blockstack/clarity` package:
-The `marf` directory defines a data structure that handles key-value lookups in the presence of blockchain forks. These structures are not intended for use in debugging, they simply support the implementation.
-
-
-## Task 5: Execute a public function
-
-In this section, you use the public `mint!` function in the `tokens` contract to mint some new tokens.
-
-1. Get the current balance of your new address.
-
- ```bash
- # echo "(get-balance '$DEMO_ADDRESS)" | clarity-cli eval $DEMO_ADDRESS.tokens /data/db
- Program executed successfully! Output:
- 0
- ```
-
- This command uses the private `get-balance` function in the `tokens` contract and pipes the result to the `eval` subcommand. The `eval` subcommand lets you evaluate both public and _private_ functions of a contract in read-only mode.
-
-2. Try minting some tokens and sending them to an address we'll use for our demo.
-
- ```bash
- # clarity-cli execute /data/db $DEMO_ADDRESS.tokens mint! $DEMO_ADDRESS u100000
- Transaction executed and committed. Returned: 100000
- ```
+```js
+import { Client, Provider, ProviderRegistry, Result } from "@blockstack/clarity";
+```
- This executes the public `mint!` function defined in the tokens contract, sending 100000 tokens to you `$DEMO_ADDRESS`.
+### Initiliazing a client
-3. Use the `clarity-cli eval` command to check the result of this call.
+At the test start, we are initializing contract instance `helloWorldClient` and a provider that forwards commands to the Rust CLI in order to interact with the Stack2.0 blockchain.
- ```bash
- # echo "(get-balance '$DEMO_ADDRESS)" | clarity-cli eval $DEMO_ADDRESS.tokens /data/db
- Program executed successfully! Output:
- 100000
- ```
+ ```js
+ let helloWorldClient: Client;
+let provider: Provider;
-## Task 6: Spend tokens by registering a name
+...
-Now, let's register a name using the `names.clar` contract. Names can _only_ be integers in this sample contract, so you'll register the name 10 in this environment.
+provider = await ProviderRegistry.createProvider();
+helloWorldClient = new Client("SP3GWX3NE58KXHESRYE4DYQ1S31PQJTCRXB3PE9SB.hello-world", "sample/hello-world", provider);
+```
-1. Compute the hash of the name we want to register.
+Take a look at the client initialization. It requires a contract id and name in the following format: `{contract_id}.{contract_name}`. The second parameter indicates the location of the smart contract file, without the `.clar` suffix. By default, the location is assuming to be relative to the `contracts` folder.
- You'll _salt_ the hash with the salt `8888`:
+### Checking syntax
- ```bash
- # echo "(hash160 (xor 10 8888))" | clarity-cli eval $DEMO_ADDRESS.names /data/db
- Program executed successfully! Output:
- 0xb572fb1ce2e9665f1efd0994fe077b50c3a48fde
- ```
+Next, we check the contract for valid syntax with:
- The value of the name hash is:
+```js
+ await helloWorldClient.checkContract();
+```
- ```
- 0xb572fb1ce2e9665f1efd0994fe077b50c3a48fde
- ```
+Note that the `checkContract()` method returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). The `await` command makes sure JavaScript is not executing the next lines until the contract check completes.
-2. Preorder the name using the _execute_ command:
+### Deploying contract
- ```bash
- # clarity-cli execute /data/db $DEMO_ADDRESS.names preorder $DEMO_ADDRESS 0xb572fb1ce2e9665f1efd0994fe077b50c3a48fde u1000
- e077b50c3a48fde 1000
- Transaction executed and committed. Returned: 0
- ```
+Further down in the file, you find a contract deployment:
- This executes the public `preorder` function defined in the `names.clar` contract. The function reserves a name by paying the name fee (in this case, 1000 tokens).
+```js
+await helloWorldClient.deployContract();
+```
-3. Check the demo address' new balance:
+### Run public methods
- ```bash
- # echo "(get-balance '$DEMO_ADDRESS)" | clarity-cli eval $DEMO_ADDRESS.tokens /data/db
- Program executed successfully! Output:
- 99000
- ```
+Finally, you will find snippets that call the public `say-hi` method of the contract:
-4. Register the name by executing the _register_ function:
+```js
+const query = helloWorldClient.createQuery({ method: { name: "say-hi", args: [] } });
+const receipt = await helloWorldClient.submitQuery(query);
+const result = Result.unwrapString(receipt);
+```
- ```bash
- # clarity-cli execute /data/db $DEMO_ADDRESS.names register $DEMO_ADDRESS \'$DEMO_ADDRESS 10 8888
- Transaction executed and committed. Returned: 0
- ```
+As you see, smart contract calls are realized through query definitions. The `createQuery` method defines the name and arguments passed to the smart contract function. With `submitQuery`, the method executed and the response is wrapped into a `Result` object. To obtain the readable result, we use the `unwrapString` method, which should return `hello world`.
-5. Lookup the "owner address" for the name:
+Now, review the last test `should echo number` on your own and try to understand how arguments are passed to the `echo-number` smart contract.
- ```bash
- # echo "(get owner (map-get name-map (tuple (name 10))))" | clarity-cli eval $DEMO_ADDRESS.names /data/db
- Program executed successfully! Output:
- (some 'SP2Y8T8RWWXFR8S1XBP6K0MHCQF01D552FSWD9M4E)
- ```
+With that, you have completed the first Clarity tutorial! Congratulations!
## Where to go next
+
{:.no_toc}
-* Clarity Language Reference
-* clarity-cli command line
+* Next tutorial: Writing your first smart contract
+* Clarity language reference
diff --git a/_data/navigation_core.yml b/_data/navigation_core.yml
index 00298d54..070aecbf 100644
--- a/_data/navigation_core.yml
+++ b/_data/navigation_core.yml
@@ -2,6 +2,7 @@
docs:
- core/smart/overview
- core/smart/tutorial
+ - core/smart/tutorial-counter
- core/smart/principals
- core/smart/functions
- core/smart/clarityRef