diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index b1e643b71..db35b54b3 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -6,6 +6,10 @@ on: - main - develop - rc/next + paths-ignore: + - '**/CHANGELOG.md' + - 'docs/**' + workflow_dispatch: jobs: diff --git a/README.md b/README.md index 5e4d97b95..de5d8e3b0 100644 --- a/README.md +++ b/README.md @@ -139,7 +139,7 @@ For a detailed video description on how you can create a new project, please see Clarinet can handle adding a new contract and its configuration to your project with the following command: ```bash -$ clarinet contract new bbtc +clarinet contract new bbtc ``` Clarinet will add 2 files to your project: the contract file in the `contracts` directory, and the contract test file @@ -175,7 +175,7 @@ to `Clarinet.toml` in order for Clarinet to recognize the contracts. Clarinet provides syntax and semantics checkers for Clarity, which enable you to check if the Clarity code in your project is valid by using the following command: ```bash -$ clarinet check +clarinet check ``` This command uses the `Clarinet.toml` file to locate and analyze all of the contracts in the project. If the Clarity code is valid, the command will indicate success with the following message: @@ -189,7 +189,7 @@ The checker may also report warnings that indicate the code is valid; however, y You may also perform syntax-check on a single file by using the following command. ```bash -$ clarinet check +clarinet check ``` If there are no syntax errors, the output of the command will be a success message similar to the example below. @@ -354,7 +354,7 @@ This annotation tells the check-checker to consider the specified variables to b Clarinet provides a testing harness based on Deno that can enable you to create automated unit tests or pseudo-integration tests using Typescript. ```bash -$ clarinet test +clarinet test ``` For more information on how to create unit tests using Typescript, see the [Writing Unit Tests Using Typescript](https://www.youtube.com/watch?v=Z4YEHUxHWuE&list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb&index=7) YouTube video. @@ -378,15 +378,15 @@ See the [billboard example](examples/billboard/tests/billboard_test.ts) for samp To help maximize a smart contract's test coverage, Clarinet can produce a `lcov` report, using the following option: ```bash -$ clarinet test --coverage +clarinet test --coverage ``` From there, you can use the `lcov` tooling suite to produce HTML reports: ```bash -$ brew install lcov -$ genhtml --branch-coverage -o coverage coverage.lcov -$ open coverage/index.html +brew install lcov +genhtml --branch-coverage -o coverage coverage.lcov +open coverage/index.html ``` ![lcov](docs/images/lcov.png) @@ -396,7 +396,7 @@ $ open coverage/index.html Clarinet can also be used to optimize costs. When executing a test suite, Clarinet will keep track of all the costs being computed when executing the `contract-call`, and display the most expensive ones in a table: ```bash -$ clarinet test --cost +clarinet test --cost ``` The `--cost` option can be used in conjunction with `--watch` and filters to maximize productivity, as illustrated here: @@ -409,7 +409,7 @@ The Clarinet console is an interactive Clarity REPL environment that runs in-mem automatically loaded into memory. ```bash -$ clarinet console +clarinet console ``` You can use the `::help` command in the console for a list of valid commands, which can control the state of the @@ -427,7 +427,7 @@ You can use Clarinet to deploy your contracts to your own local offline environm evaluation on a blockchain by using the following command: ```bash -$ clarinet integrate +clarinet integrate ``` **Note** Make sure you have a working installation of Docker running locally. @@ -513,7 +513,7 @@ trusted_caller = false callee_filter = false ``` -As a next step we can generate a deployment plan for this project. If you are running `$ clarinet integrate` for the first time, this file should be created by Clarinet. In addition, you can run `$ clarinet deployment generate --devnet` to create or overwrite the file. +As a next step we can generate a deployment plan for this project. If you are running `clarinet integrate` for the first time, this file should be created by Clarinet. In addition, you can run `clarinet deployment generate --devnet` to create or overwrite the file. ```yaml --- @@ -562,13 +562,13 @@ You can use Clarinet to publish your contracts to Devnet / Testnet / Mainnet env The first step to deploy a contract is to generate a deployment plan, with the following command: ```bash -$ clarinet deployment generate --mainnet +clarinet deployment generate --mainnet ``` After **cautiously** reviewing (and updating if needed) the generated plan, you can use the command to handle the deployments of your contract, according to your deployment plan: ```bash -$ clarinet deployment apply -p +clarinet deployment apply -p ``` ### Use Clarinet in your CI workflow as a GitHub Action @@ -615,7 +615,7 @@ Clarinet can easily be extended by community members: open source contributions Extensions are run with the following syntax: ``` -$ clarinet run --allow-write https://deno.land/x/clarinet@v0.29.0/ext/stacksjs-helper-generator.ts +clarinet run --allow-write https://deno.land/x/clarinet@v0.29.0/ext/stacksjs-helper-generator.ts ``` An extension can be deployed as a standalone plugin on Deno, or may also be a local file if it includes sensitive / private setup informations. @@ -740,7 +740,7 @@ This same file may also be used for customizing the subnet-node (miner, etc). When running the command: ```bash -$ clarinet integrate +clarinet integrate ``` Clarinet will spin-up a subnet node. More documentation on how to use and interact with this incoming L2 can be found on the [Hyperchain repository](https://github.com/hirosystems/stacks-subnets). @@ -792,23 +792,23 @@ To start contributing: Here is an example of a bad message response: ```bash - $ git commit -m "bad message" - $ ⧗ input: bad message - $ ✖ subject may not be empty [subject-empty] - $ ✖ type may not be empty [type-empty] - $ - $ ✖ found 2 problems, 0 warnings - $ ⓘ Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint - $ - $ husky - commit-msg hook exited with code 1 (error) + git commit -m "bad message" + ⧗ input: bad message + ✖ subject may not be empty [subject-empty] + ✖ type may not be empty [type-empty] + + ✖ found 2 problems, 0 warnings + ⓘ Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint + + husky - commit-msg hook exited with code 1 (error) ``` Here is an example of a good message response: ```bash - $ git commit -m "fix: added missing dependency" - $ [my-branch 4c028af] fix: added missing dependency - $ 1 file changed, 50 insertions(+) + git commit -m "fix: added missing dependency" + [my-branch 4c028af] fix: added missing dependency + 1 file changed, 50 insertions(+) ``` 5. After making your changes, ensure the following: diff --git a/components/clarinet-cli/examples/cbtc/README.md b/components/clarinet-cli/examples/cbtc/README.md index bbc2ee2f0..adf3c8a18 100644 --- a/components/clarinet-cli/examples/cbtc/README.md +++ b/components/clarinet-cli/examples/cbtc/README.md @@ -1,10 +1,10 @@ # cBTC example -In this example we are exploring a naive and centralized but yet functional approach for wrapping / unwrapping BTC to SIP10 tokens. +In this example we are exploring a naive and centralized but, yet functional approach for wrapping / unwrapping BTC to SIP10 tokens. By sending BTC to the `authority` address, a party would see an equivalent amount of cBTC being minted on the Stacks Blockchain. -When burning cBTC, a token owner will see some Bitcoin being transfered to his Bitcoin address. +When burning cBTC, a token owner will see some Bitcoin being transferred to his Bitcoin address. This protocol was meant to illustrate possible interactions between Bitcoin and Stacks using a mechanism called `chainhooks`. The design of this protocol is limited (proofs not being checked, central trustee, etc) and should not be used in production. @@ -13,28 +13,29 @@ This protocol was meant to illustrate possible interactions between Bitcoin and Start a local Devnet with the command: ```bash -$ clarinet integrate +clarinet integrate ``` In another console, change the directory to `./serverless/`. After running ```bash -$ cd serverless -$ yarn global add serverless # Install serverless globally -$ yarn add --dev serverless-plugin-typescript@latest -$ yarn # Install dependencies +cd serverless +yarn global add serverless # Install serverless globally +yarn add --dev serverless-plugin-typescript@latest +yarn # Install dependencies ``` and making sure that the command `serverless` is available in your `$PATH`, the lambda functions can be started locally with the following command: ```bash -$ serverless offline --verbose +serverless offline --verbose ``` Once the message `Protocol deployed` appears on the screen, transfers tokens back and forth between the Bitcoin Blockchain and the Stacks Blockchain can be performed thanks to the deployment plans: - `deployments/wrap-btc.devnet-plan.yaml`: a BTC transaction is being performed, using the following parameters: + ```yaml - btc-transfer: expected-sender: mjSrB3wS4xab3kYqFktwBzfTdPg367ZJ2d @@ -42,7 +43,9 @@ thanks to the deployment plans: sats-amount: 100000000 sats-per-byte: 10 ``` + A chainhook predicate, specified in `chainhooks/wrap-btc.json` is observing BTC transfers being performed to the address `mr1iPkD9N3RJZZxXRk7xF9d36gffa6exNC` thanks to the following configuration: + ```json "if_this": { "scope": "outputs", @@ -57,10 +60,12 @@ A chainhook predicate, specified in `chainhooks/wrap-btc.json` is observing BTC } } ``` + In this protocol, this transaction assumes usage of p2pkh addresses, and sends the change back to the sender, using the same address. When minting the `cBTC` tokens, the authority is converting the 2nd output of the transaction to a Stacks address, and sending the minted tokens to this address. - `deployments/unwrap-btc.devnet-plan.yaml`: a contract call is being issued, using the following settings: + ```yaml - contract-call: contract-id: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.cbtc-token @@ -70,7 +75,9 @@ the 2nd output of the transaction to a Stacks address, and sending the minted to - u100000 cost: 5960 ``` + Another chainhook predicate, specified in `chainhooks/unwrap-btc.json` is observing cBTC burn events occuring on the Stacks blockchain, thanks to the following configuration: + ```json "if_this": { "scope": "ft_event", @@ -86,17 +93,17 @@ Another chainhook predicate, specified in `chainhooks/unwrap-btc.json` is observ } } ``` + When the authority process this chainhook occurences, it sends BTC from its reserve to `cBTC` burner, by assuming that a p2pkh is being used. The wrap / unwrap deployment plans can both be respectively performed with the commands: ```bash -$ clarinet deployment apply -p deployments/wrap-btc.devnet-plan.yaml +clarinet deployment apply -p deployments/wrap-btc.devnet-plan.yaml ``` -and +and ```bash -$ clarinet deployment apply -p deployments/unwrap-btc.devnet-plan.yaml +clarinet deployment apply -p deployments/unwrap-btc.devnet-plan.yaml ``` - diff --git a/components/clarinet-deno/ext/stacksjs-helper-generator.ts b/components/clarinet-deno/ext/stacksjs-helper-generator.ts index d52943e4d..5c0bba2ad 100644 --- a/components/clarinet-deno/ext/stacksjs-helper-generator.ts +++ b/components/clarinet-deno/ext/stacksjs-helper-generator.ts @@ -5,7 +5,7 @@ // can use in their frontend code. // // When running: -// $ clarinet run --allow-write scripts/stacksjs-helper-generator.ts +// clarinet run --allow-write scripts/stacksjs-helper-generator.ts // // This script will write a file at the path artifacts/contracts.ts: // diff --git a/docs/faq.md b/docs/faq.md index 858a4e666..b6ec3e232 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -28,7 +28,7 @@ Clarinet integrate uses Docker to run Bitcoin, Stacks nodes, and other services. #### **Where can I find the logs for Clarinet Integrate?** -If you're using Docker desktop, you can open the UI and select `stacks-node` container to see its logs. +If you're using Docker desktop, you can open the UI and select `stacks-node` container to see its logs. If you are not using the Docker desktop, use the following command in your terminal: diff --git a/docs/feature-guides/analyze-with-check-checker.md b/docs/feature-guides/analyze-with-check-checker.md index 0d0beb7d5..c8d47939c 100644 --- a/docs/feature-guides/analyze-with-check-checker.md +++ b/docs/feature-guides/analyze-with-check-checker.md @@ -11,6 +11,7 @@ The check-checker is a static analysis pass you can use to help find potential v * [Annotations](#annotations) ## Enable static analysis pass + To enable the static analysis pass, add the following lines to your Clarinet.toml file: ```toml diff --git a/docs/feature-guides/chainhooks.md b/docs/feature-guides/chainhooks.md index c8ac92b53..aab4fbdda 100644 --- a/docs/feature-guides/chainhooks.md +++ b/docs/feature-guides/chainhooks.md @@ -4,7 +4,7 @@ title: Chainhooks ## Overview -Chainhooks are a powerful feature that enables you to automatically trigger an action based upon a predicate event occurring. Adhering to an event-based architecture, chainhooks allow you to pre-determine an underlying set of events that, when triggered, set into motion a logical series of follow-on steps and actions to address the specific event that was triggered. +Chainhooks are a powerful feature that enables you to automatically trigger an action based upon a predicate event occurring. Adhering to an event-based architecture, chainhooks allow you to pre-determine an underlying set of events that, when triggered, set into motion a logical series of follow-on steps and actions to address the specific event that was triggered. *Topics covered in this guide*: @@ -12,7 +12,6 @@ Chainhooks are a powerful feature that enables you to automatically trigger an a * [Use chainhooks](#using-chainhooks) * [References](#references) - ## Design Chainhooks were designed with a very specific set of requirements and limitations to make them easy to work with in a development environment. These constraints include portability and performance. diff --git a/docs/feature-guides/clarinet-deploy.md b/docs/feature-guides/clarinet-deploy.md index 6063917c1..88b1fdcab 100644 --- a/docs/feature-guides/clarinet-deploy.md +++ b/docs/feature-guides/clarinet-deploy.md @@ -12,7 +12,6 @@ Deployment Plans are reproducible deployment steps that publish a collection of * [Plan primitives](#deployment-plan-primitives) * [References](#references) - ## Design The default deployment plan of every Clarinet project is contained within specifications set inside certain files. In addition to this default deployment plan, the user can manually configure each plan, adding additional transactions or contract calls, across multiple Stacks or Bitcoin blocks. @@ -29,7 +28,6 @@ You can commit, audit, and test contracts without including any secrets in the D | wait for block | - Test or automate contract deployment across multiple Stacks or Bitcoin blocks | | send STX | - send stacks to an address or contract | - ## References For a more detailed discussion of how to use Deployment Plans, please see the following resources: diff --git a/docs/feature-guides/extend-clarinet.md b/docs/feature-guides/extend-clarinet.md index 00a792936..80e900640 100644 --- a/docs/feature-guides/extend-clarinet.md +++ b/docs/feature-guides/extend-clarinet.md @@ -4,13 +4,13 @@ title: Extend Clarinet Extend Clarinet to integrate clarity contracts with your own tooling and workflow. - *Topics covered in this guide*: * [Use clarinet run command](#clarinet-run) * [Standalone plugin deployment](#standalone-plugin) ## Clarinet run + | Name | wallet access | disk write | disk read | Deployment | Description | | ------------------------- | ------------- | ---------- | --------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | stacksjs-helper-generator | no | yes | no | https://deno.land/x/clarinet@v0.29.0/ext/stacksjs-helper-generator.ts | Facilitates contract integration by generating some typescript constants that can be used with stacks.js. Never hard code a stacks address again! | @@ -19,10 +19,11 @@ Extend Clarinet to integrate clarity contracts with your own tooling and workflo Extensions are run with the following syntax: ``` -$ clarinet run --allow-write https://deno.land/x/clarinet@v0.29.0/ext/stacksjs-helper-generator.ts +clarinet run --allow-write https://deno.land/x/clarinet@v0.29.0/ext/stacksjs-helper-generator.ts ``` ## Standalone plugin -An extension can be deployed as a standalone plugin on [Deno](https://deno.land/), or can also just be a local file if it includes sensitive / private setup informations. + +An extension can be deployed as a standalone plugin on [Deno](https://deno.land/), or can also just be a local file if it includes sensitive / private setup information. As illustrated in the example above, permissions (wallet / disk read / disk write) are declared using command flags. If at runtime, the Clarinet extension is trying to write to disk, read disk, or access wallets without permission, the script will end up failing. diff --git a/docs/how-to-guides/how-to-add-contract.md b/docs/how-to-guides/how-to-add-contract.md index 68271658a..d57f58a67 100644 --- a/docs/how-to-guides/how-to-add-contract.md +++ b/docs/how-to-guides/how-to-add-contract.md @@ -14,7 +14,7 @@ Clarinet can handle adding a new contract and its configuration to your project. You can use the command below to add a new contract. ```bash -$ clarinet contract new bbtc +clarinet contract new bbtc ``` Clarinet will add two files to your project: @@ -47,4 +47,3 @@ epoch = 2.4 You can add contracts to your project by adding the files manually; however, you must make sure to add the appropriate configuration to `Clarinet.toml` for Clarinet to recognize the contracts. - diff --git a/docs/how-to-guides/how-to-check-contract.md b/docs/how-to-guides/how-to-check-contract.md index faa0b7145..d0d06e134 100644 --- a/docs/how-to-guides/how-to-check-contract.md +++ b/docs/how-to-guides/how-to-check-contract.md @@ -13,7 +13,7 @@ Clarinet provides syntax and semantics checkers for Clarity. You can verify if the Clarity code in your project is valid with the command listed below. ```bash -$ clarinet check +clarinet check ``` This command uses the `Clarinet.toml` file to locate and analyze all the contracts in the project. @@ -28,7 +28,7 @@ The command may also report warnings indicating the code is valid. You may also perform a syntax-check on a single file by using the command below. ```bash -$ clarinet check +clarinet check ``` The command output will be a success message if there are no syntax errors. @@ -39,4 +39,3 @@ The command output will be a success message if there are no syntax errors. Any syntactical errors in the Clarity code will be reported, but type-checking and other semantic checks are not performed. This is because Clarinet is only looking at this one contract and needs the full context to perform a complete check. - diff --git a/docs/how-to-guides/how-to-deploy-contracts.md b/docs/how-to-guides/how-to-deploy-contracts.md index 5e08610f7..50a3acd24 100644 --- a/docs/how-to-guides/how-to-deploy-contracts.md +++ b/docs/how-to-guides/how-to-deploy-contracts.md @@ -14,7 +14,7 @@ You can use Clarinet to publish your contracts to the public testnet or mainnet The first step is to generate a deployment plan with the command below (note: replace `--mainnet` with `--testnet` to deploy to the latter). Please specify a cost strategy to incentivize miners to carry your transaction (either `--low-cost`, `--medium-cost`, `--high-cost`, or `--manual-cost`). The final command might look like: ```bash -$ clarinet deployment generate --mainnet --medium-cost +clarinet deployment generate --mainnet --medium-cost ``` # Deploy @@ -22,5 +22,5 @@ $ clarinet deployment generate --mainnet --medium-cost After **carefully** reviewing (and updating if needed) the generated deployment plan, you can use the command below to handle the deployments of your contracts. ```bash -$ clarinet deployment apply --mainnet +clarinet deployment apply --mainnet ``` diff --git a/docs/how-to-guides/how-to-deploy-with-subnets.md b/docs/how-to-guides/how-to-deploy-with-subnets.md index b5c59ee98..eecb94bec 100644 --- a/docs/how-to-guides/how-to-deploy-with-subnets.md +++ b/docs/how-to-guides/how-to-deploy-with-subnets.md @@ -24,7 +24,7 @@ You can use the `Devnet.toml` to customize the subnet-node (miner, etc). Spin up your subnet node with the command below. ```bash -$ clarinet integrate +clarinet integrate ``` You can find more information on using and interacting with Subnets in the [subnets repository](https://github.com/hirosystems/stacks-subnets). diff --git a/docs/how-to-guides/how-to-test-contract.md b/docs/how-to-guides/how-to-test-contract.md index b255790c6..559e11836 100644 --- a/docs/how-to-guides/how-to-test-contract.md +++ b/docs/how-to-guides/how-to-test-contract.md @@ -41,7 +41,7 @@ Our `counter` application keeps track of an initialized value, allows for increm ### Unit tests for `counter` example -When you created your Clarity contract with `$ clarinet contract new `, Clarinet automatically created a test file for the contract within the tests directory: `tests/my-projects_test.ts`. Other files under the `tests/` directory following the Deno test naming convention will also be included: +When you created your Clarity contract with `clarinet contract new `, Clarinet automatically created a test file for the contract within the tests directory: `tests/my-projects_test.ts`. Other files under the `tests/` directory following the Deno test naming convention will also be included: - named test.{ts, tsx, mts, js, mjs, jsx, cjs, cts}, - or ending with .test.{ts, tsx, mts, js, mjs, jsx, cjs, cts}, @@ -84,7 +84,7 @@ Clarinet.test({ We run this test with ```zsh -$ clarinet test +clarinet test ``` For a complete list of classes, objects, and interfaces available, see [Deno's Clarinet module index](https://deno.land/x/clarinet/index.ts). @@ -168,15 +168,15 @@ Here, variously, we: To help developers maximizing their test coverage, Clarinet can produce a `lcov` report, using the following option: ```bash -$ clarinet test --coverage +clarinet test --coverage ``` From there, you can use the `lcov` tooling suite to produce HTML reports. ```bash -$ brew install lcov -$ genhtml --branch-coverage -o coverage coverage.lcov -$ open coverage/index.html +brew install lcov +genhtml --branch-coverage -o coverage coverage.lcov +open coverage/index.html ``` ![lcov](../images/lcov.png) @@ -186,7 +186,7 @@ $ open coverage/index.html Clarinet can also be used for optimizing costs. When you execute a test suite, Clarinet keeps track of all costs being computed when executing the `contract-call`, and display the most expensive ones in a table: ```bash -$ clarinet test --cost +clarinet test --cost ``` The `--cost` option can be used in conjunction with `--watch` and filters to maximize productivity, as illustrated here: @@ -199,7 +199,7 @@ The Clarinet console is an interactive Clarity Read, Evaluate, Print, Loop (REPL automatically loaded into memory. ```bash -$ clarinet console +clarinet console ``` You can use the `::help` command in the console for a list of valid commands, which can control the state of the REPL chain, and let you advance the chain tip. Additionally, you may enter Clarity commands into the console and observe @@ -216,7 +216,7 @@ You can use Clarinet to deploy your contracts to your own local offline environm Use the following command: ```bash -$ clarinet integrate +clarinet integrate ``` Make sure that you have a working installation of Docker running locally. @@ -300,9 +300,9 @@ callee_filter = false As a next step, we may generate a deployment plan for this project. -If running `$ clarinet integrate` for the first time, this file should be created by Clarinet. +If running `clarinet integrate` for the first time, this file should be created by Clarinet. -In addition, you may run `$ clarinet deployment generate --devnet` to create or overwrite. +In addition, you may run `clarinet deployment generate --devnet` to create or overwrite. ```yaml --- diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index a34be5420..62d210f6f 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -5,7 +5,7 @@ title: Troubleshooting This page answers some common issues you may encounter when using Clarinet. Updates will be made to this page regularly as we receive feedback and comments from our developer community. -## I am unable to run Clarinet after installation. +## I am unable to run Clarinet after installation. > **_NOTE:_** > @@ -20,7 +20,7 @@ To manually add the directory to your path: 1. Open "System Properties." 2. Click the "Environment Variables" button under "System variables." -3. Select "Path" and then click "Edit." +3. Select "Path" and then click "Edit." 4. Click the "New" button and add "C:\Program Files\clarinet\bin." 5. Follow the on-screen prompts and click "OK" after each prompt. 6. Restart your shell/VSCode. @@ -55,8 +55,6 @@ If you have trouble setting up docker on your Linux machine, follow the steps be ``` 2. Install docker-desktop by following the steps [here](https://docs.docker.com/desktop/install/ubuntu/#install-docker-desktop). - 3. You will need to update the settings in the Clarinet project. You can do this by navigating to the Clarinet/components/clarinet-cli/examples/simple-nft/settings/Devnet.toml file. In the `[Devnet]` settings, add the following setting and replace `username` with your username: - `docker_host = "/home//.docker/desktop/docker.sock"` 4. Save the `Devnet.toml` and run docker now.