DEVELOPMENT.md

We use yarn workspaces + lerna for monorepo management. So to get started, clone this repository and run yarn in the root directory to install all dependencies for all packages.

When updating code in one package, you can run yarn build in the root directory to build all packages so the changes get propagated to the other packages as well. If you're already in a package directory, you can run the following command to do so:

pushd ../.. && yarn build && popd

Publishing a release

To publish a new release, we use yarn update-version 'x.x.x' in the root directory to bump the version before release, and then yarn publish-all in the root directory to publish the release. In case of a tagged release (such as next), we use TESTS_USE_MOCKNET=true yarn publish-all --dist-tag <tag name> to publish the release with the specified tag.

cashc

Prerequisites

In order to use the antlr command line tool when updating CashScript's grammar file, you need to have it installed.

On macOS you can install it using Homebrew:

brew install antlr

On Linux you can install it using apt:

sudo apt install antlr4

For other platforms, refer to the Antlr website.

Updating the grammar

When updating the grammar file in src/grammar/CashScript.g4, we also need to make sure that the generated parser is updated. To do this, run the following command in the packages/cashc directory:

yarn antlr

Running cashproof

Most of the bytecode optimisations that the cashc compiler uses can be verified for correctness using the cashproof tool. This tool needs to be installed separately by installing its dependencies using pip and cloning its repository from GitHub.

From there, you can run python <cashproof_path> [filenames] to verify that the optimisations contained in these files are provably correct.

Example:

python <cashproof_path> packages/cashc/test/cashproof/0.1.2=0.2.0.equiv

Note that if you want to run cashproof on the "main" CashScript optimisations file, you need to first extract the optimisations from the cashc compiler and save them in a separate file. This can be done using the following commands:

cp packages/utils/src/cashproof-optimisations.ts opt.equiv && sed -i '' '/`/d' opt.equiv
python <cashproof_path> opt.equiv

cashscript

Running tests

By default, running tests in the cashscript package uses chipnet contracts, which requires the test accounts to have some chipnet BCH. To run the tests against a local "mock network", you can use the TESTS_USE_MOCKNET environment variable.

# Run all tests using the mock network
TESTS_USE_MOCKNET=true yarn test

To run specific tests, you can use the -t flag to match the name mentioned in the it or describe block:

# Run all tests in the 'Transaction Builder' describe block (test/e2e/transaction-builder/TransactionBuilder.test.ts)
yarn test -t 'Transaction Builder'