Skip to content
Switch branches/tags


Failed to load latest commit information.

Cardstack App Suite

This is the main repo for Cardstack, an open source application architecture for building cohesive experiences, including payments, on open, decentralized infrastructure.

Join the discussion around developing on the Cardstack framework on Discord, and read our documentation on (Note: documentation refers to Cardstack v2. The main branch of this respository has in-progress work on v3 of Cardstack.)


This is a monorepo. Each directory under packages and cards is distributed as a standalone NPM package under the @cardstack NPM namespace. More information is available in the within each package.

Developing and Testing within this Repo

Local host names

Set up app.cardstack.test and app-assets.cardstack.test to resolve to localhost ( There are a variety of ways to accomplish this, with the most direct being to edit your /etc/hosts file.

Hub environment variables

See the README in the hub package for environment variables that you'll need to setup.

Javascript dependencies & Typescript compilation

We use volta to manage our global javascript dependencies. In this case, specifically, we use it to manage node and yarn. To use it simply install it following the instructions here:

In development, we use lerna to manage the inter-dependencies of all the packages. To get started:

  1. Install node and yarn via volta.
  2. yarn global add lerna (use >= 2.0.0 for yarn workspaces integration)
  3. lerna bootstrap
  4. Launch the typescript compiler with yarn compile --watch
  5. Start ember-cli and the hub node server with yarn start and/or run tests with yarn test

Understanding the respositories under the Cardstack organization

The following summary offers an overview of where development is currently ongoing at Cardstack. (Note: any projects linked below that are not currently public will become public soon.)


  • The Layer 2 contracts for the card protocol live here including
    • PrepaidCardManager contract
    • RevenuePool contract
    • L2 Token contract
    • SPEND token contract
    • BridgeUtilities contract (facilitates token bridge contract)


  • The home bridge and foreign bridge token contracts

  • our gnosis relay service, forked to provide additional prepaid card manager API's that support gasless interactions with our PrepaidCardManager contract


  • our gnosis transaction service, this was forked to provide transaction service for Sokol (xDai uses the gnosis hosted transaction service)


  • this one! It is our monorepo that contains our CardPay Dapp (as well as eventually cardstack hub runtime). Work on the "card compiler" is also occurring in PRs of this repository. A proof-of-concept for the dapp was developed here:


  • our rainbow wallet fork that supplies our mobile client experience. Currently it is focused around interacting with Layer 1 contracts, eventually we see it as interacting with the Layer2 protocol as well. A proof-of-concept was developed here:


  • Holds our terraform scripts to provision AWS and cloudflare (and eventually GCP) services for our infrastructure.


  • our web UI component library


  • our planned Javascript build tooling and CDN that eliminates the need for running npm/yarn and eliminates the need to maintain a node_modules folder in your web projects


  • proof of concept for an animation library that works well with Ember and meets Boxel's motion needs

Project-wide Policy and Community Governance

Cardstack follows semantic versioning. As a young, pre-1.0 project, this means you can continue to expect breaking changes in minor releases. Each package should endeavor to include a once it begins to have a non-trivial number of external users.

We intend to adopt a community RFC governance process for public API changes, based on the Rust and Ember projects. At this pre-1.0 stage, RFCs are optional and changes may still be fast and furious.

Cardstack follows the Ember Community Guidelines, both because we are a proper subset of the existing Ember community and because we wholeheartedly endorse the same values.