Clarity JS SDK

A development environment, testing framework, and deployment tool for Clarity smart contracts.

Features:

TypeScript / JavaScript framework for building smart contracts using test driven development.
[WIP] Library for interacting with smart contracts from a dapp (a web3 equivalent).
[WIP] Type declaration generation (.d.ts) for easy and safer interactions with smart contracts.
[roadmap] Language-server-protocol implementation.
[roadmap] Code coverage generation.

Usage

Smart Contract Development

TypeScript

Quick Start:

npm init clarity-starter
npm test

See create-clarity-starter for more details.

JavaScript

Quick Start:

Not yet available

clarity-cli

npm install -g @blockstack/clarity-cli
clarity help

See clarity-cli/README.md for detailed usage.

clarity-tutorials

TODO: Determine and document intended usage of this package.

npm install @blockstack/clarity-tutorials

Local Development

Repo structure and project build instructions for contributors.

Requirements

Node.js v10 or higher is required.
Several packages require the native clarity-cli binary -- distributes are automatically installed on MacOS, Windows (64-bit), and Linux (64-bit).

It will be compiled from source if using an OS or architecture not listed. This requires the Rust toolchain -- rustup is the recommended installer. A C compiler must also be available (gcc, clang, and msvc are supported). See clarity-native-bin for more details.

Build Instructions

Open terminal / command prompt to the root project directory containg the top-level package.json.
Run npm install. This automatically triggers lerna bootstrap to configure local packages in the repo.

Pulling Updates

Run npm run rebuild when pulling repo changes to an already setup local environment. This ensures the local environment is setup correctly after any changes to cross-dependencies or new libs.

Rebuild does the following:

Removes node_modules directories, removes the compiled packages/*/lib directories, removes the *.tsbuildinfo cached build metadata.

Runs lerna bootstrap to install dependencies and configures cross-dependency symlinks.

Runs tsc --build [...] on all packages.

Project Structure

This is a multi-package monorepo.

TypeScript module path mapping is used for packages with cross-dependencies. These paths are specified in the default tsconfig.json files. This is the config picked up by an editor/IDE/debugger for mapping absolute package names back to their source code in the monorepo.
TypeScript project references are used for npm build and package publishing. This is configured in the tsconfig.build.json files.
Lerna is used to manage multiple packages in the monorepo.

The Lerna features in use:

lerna bootstrap - Setup packages in the current Lerna repo; installs all of their dependencies and links any cross-dependencies.

lerna run [npm script] - Run an npm script in each package that contains that script, e.g. lerna run lint.

lerna version - Identify packages that have been updated since last release, increment package.json versions, commit to git. See docs for details.

lerna publish - Publish packages that have been updated since the last time a release was made.

File Tree

.
├── package.json
├── lerna.json
├── tsconfig.json
├── tsconfig.build.json
└── packages/
    ├── lib-a/
    │   ├── package.json
    │   ├── tsconfig.json
    │   ├── tsconfig.build.json
    │   ├── src/
    │   │   └── index.ts
    │   └── test/
    │       ├── **/*.ts [test source files]
    │       └── mocha.opts
    └── lib-a/
        ├── package.json
        ├── tsconfig.json
        ├── tsconfig.build.json
        ├── src/
        │   └── index.ts
        └── test/
            ├── **/*.ts [test source files]
            └── mocha.opts

Publishing

Publishing happens automatically upon commit or merge into the master branch.

0xtortoise/clarity-js-sdk