Simple off-chain applications framework for Ethereum.

statechannels is a simple off-chain framework for building state channel applications on top of the Ethereum blockchain. It aims to make it simpler to build permissionless applications that have instant finality with zero-fee transactions.

You can learn more about what state channels are by reading one or other of the whitepapers underpinning the project, or a less technical written description.

• Packages
• Contributing
  • Installing dependencies
  • Building packages
  • Clean
  • Lint
  • Tests
  • Authoring conventional commits
  • Publishing packages
    • Fixing a failed publish
• Typescript doc comments
• API reports
• Community

Packages

This repository is a monorepo, and contains the following packages maintained with lerna and yarn workspaces:

• docs-website : Documentation website
• client-api-schema : JSON-RPC based schema definitions for the Client API with TypeScript typings
• devtools : Developer tooling
• jest-gas-reporter : Reports the gas used by various calls to ethereum contracts
• nitro-protocol : Smart contracts and typescript support
• wallet-core : Core wallet code that works in node-js and browser contexts
• wire-format : Format of messages that are sent over the wire between wallets

Contributing

• Create a new issue to report bugs
• Fix an issue. statechannels is an Open Source Project!

Installing dependencies

• yarn - version 1.22.4, for easy management of specific Yarn versions, we recommend using Yarn Version Manager (YVM).
• node - version 12.16.3, for easy management of specific versions, we recommend using n.
• postgres - we recommend the postgres app. If you choose this installation, make sure you follow the following steps to add postgres tools to you $PATH, better verify commands like 'createdb', 'dropdb' runs correctly in your terminal before proceeding.

sudo mkdir -p /etc/paths.d &&
echo /Applications/Postgres.app/Contents/Versions/latest/bin | sudo tee /etc/paths.d/postgresap

The rest of the dependencies can be installed by running

yarn

from the monorepo root.

Building packages

To build all packages:

yarn build

Clean

To clean all packages:

yarn clean

Lint

To lint all packages:

yarn lint:check

To also apply automatic fixes:

yarn lint:write

Tests

To create and migrate test db:

cd ./packages/server-wallet/
./src/test_db.sh server_wallet_test

To run all tests:

yarn test

Authoring conventional commits

We follow the convention at https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional. Your commits will be linted against this convention. You can do this yourself locally by running

yarn commitlint --from=HEAD~1 --verbose

For help authoring commits, you can check out https://commitizen.github.io/cz-cli/.

Publishing packages

To publish you will need to trigger a github action:

1. Select the actions tab
2. Select whether you want to do a regular publish (Publish Packages) or a pre-release (Publish Packages (canary))
3. Click on Run workflow
4. Select the branch (regular publishes will fail unless on master)
5. For regular publishes, a PR will be created to get the updated version and changelog info back into master. You should merge this immediately!

Fixing a failed publish

Sometimes things will go wrong on CI and the git tags will be created but the package will not be published. To fix this you can do the following locally:

# fetch down any publish tags
git fetch --tags

# push packages to the registries, without creating new releases
npx lerna publish from-package

You might need a npm login --registry https://testnet.thegraph.com/npm-registry/ if you don't already have an access token in your .npmrc.

Typescript doc comments

These should adhere to the TSDoc standard. You can try the TSDoc playground.

Doc comments will appear in our documentation at https://docs.statechannels.org.

API reports

We use api-extractor to help us track changes to the API of some of the packages in this repo. The tool is run via yarn lerna run generate-api during our continuous integration suite, and generates an api report. If you make changes to the external API of a package, you should run this command locally and check in the reports to source control, else you will get a test failure.

The checked-in report helps faciliate PR review.

Community

State Channels Forums: https://research.statechannels.org/