Running an Ethereum Cardstack Hub Application

How to wrap a smart contract in a RESTful API

Hassan Abdel-Rahman
Aug 29, 2018 · 11 min read

Create an Ember Application

The Cardstack Hub is ideally suited to be consumed by an Ember.js application (albeit, it doesn’t have to be). Since Ember.js applications are easy to setup and have great tooling, let’s start there.

curl -o- -L | bash
yarn global add ember-cli
ember new smart-contract-example
cd smart-contract-example
ember serve
Output of the ember serve command
A running Ember.js application

Installing Cardstack Hub

OK, now that you have a vanilla Ember.js application running, let’s install and configure a Cardstack Hub for the Ember.js application.

ember install @cardstack/hub
yarn add @cardstack/ethereum @cardstack/jsonapi @cardstack/test-support @cardstack/eslint-config eslint-plugin-node
.eslintrc.js file
mkdir cardstack/data-sources
touch cardstack/data-sources/card-token.js
card-token.js data source configuration file

External Dependencies

The Cardstack Hub has a few external dependencies it requires in order to operate correctly. Let’s go through them.


Docker is not a required dependency, but we highly recommend it. Docker is a great way to bundle services in simple and composable packages. For the examples below, we will assume that you have Docker installed. You can find installation instructions for Docker here.


The Cardstack Hub uses a PostgreSQL database to persist the content index. Additionally, the PostgreSQL DB is used to orchestrate job queues used for indexing.

docker run -d -p 5432:5432 --rm cardstack/pg-test


For the purpose of this blog post, we’ll be setting up a Cardstack application that will use an Ethereum smart contract as its data source. The Cardstack Hub uses Geth as the interface to Ethereum. Geth is a Go implementation of an Ethereum client, and probably the most popular Ethereum client used today.

mkdir ~/ethereum
docker run -d --name ethereum-node -v /Users/hassan/ethereum:/root -p 8545:8545 -p 8546:8546 -p 30303:30303 ethereum/client-go:stable --rinkeby --rpc --rpcapi eth,net,web3 --rpcaddr --ws --wsaddr --wsorigins '*' --wsapi eth,net,web3 --cache 4096
docker logs -f ethereum-node


The Cardstack Hub server is hosted by Node.js, a JavaScript-based server. The Cardstack Hub will automatically run on the Node.js server that hosts your Ember.js application when you execute ember serve. Additionally, if you prefer your Cardstack Hub to run on a separate Node.js server, you can start your Cardstack Hub with the command:

ember hub:start
ember serve
Output of ember serve command while the Cardstack Hub starts

Running the Cardstack Hub

Once the Cardstack Hub starts up, it will discover the data sources that you have configured in the cardstack/ folder of your project and begin indexing those data sources.

The RESTful response for the Rinkeby CARD token
The RESTful response for the Rinkeby CARD token balances
The RESTful response for the Rinkeby CARD token balance of token holder 0x88e1d504fd6551a7b7b19e1aa6881de1a9f18ca7
The RESTful response for the Rinkeby CARD token Transfer events where the token holder 0x88e1d504fd6551a7b7b19e1aa6881de1a9f18ca7 is a recipient of a token transfer

Tools for the Next Generation

In this blog post, we have demonstrated how to wrap an Ethereum smart contract in a RESTful API. Applications that consume these RESTful API’s do not need any specialized libraries in order to communicate with your Ethereum smart contract.

Taking It Further

This example just scratches the surface of what is possible with a Cardstack application.

Get Involved

Join the discussion about Cardstack on our official Telegram channel:

Important Reminders

  • We will never, under any circumstances, solicit funds from you via email, private message, or social media.
  • If you are in doubt or notice any suspicious activity, please message the admins in our official Telegram group:


The experience layer of the decentralized Internet.

Hassan Abdel-Rahman

Written by

Developer at Cardstack



The experience layer of the decentralized Internet.