10/16/18: This repository has been deprecated in favor of a different back-end repository which will likely not be made open-source. This repository has been archived for reference, but should not be considered up to date or useable by any means.

Node API for Codex Registry

This is the Node API that serves as the off-chain backend for the Codex Viewer. Among various other tasks, this API handles user authentication via JSON Web Tokens, processes blockchain events via EEL & Agenda, manages MongoDB interactions via Mongoose, and manages socket connections from the front end via socket.io & Redis.

Table of Contents

• Security
• Install
  • Clone & Set Up Required Repositories
  • Dependencies
  • Configure
• Usage
• Maintainers
• Contribute
• License

Security

This project requires the use of some "secret" variables that should be tailored to your development environment and never committed to the repository. These variables are read by dotenv and should be defined in a file called .env in the project root.

After cloning the repository, duplicate and rename .env.example to .env, then tailor the variables to your local environment accordingly:

$ cp .env.example .env
$ vi .env

.env.example has suitable local development defaults for most variables, so you should only have to set any missing values (i.e. JWT_SECRET & SIGNER_PRIVATE_KEY.) Descriptions for each variable are listed in .env.example.

Install

There's a lot involved in setting up this project, so bear with us.

Clone & Set Up Required Repositories

1. First, clone this repository and all dependency repositories (see Dependencies below for more details):

   • service.codex-registry-api
   • contract.codex-registry
   • npm.ethereum-service
   • service.eel

   $ git clone https://github.com/codex-protocol/service.codex-registry-api
   $ git clone https://github.com/codex-protocol/contract.codex-registry
   $ git clone https://github.com/codex-protocol/npm.ethereum-service
   $ git clone https://github.com/codex-protocol/service.eel

   IMPORTANT NOTE: It's necessary to have all of these repositories in the same directory, since our npm scripts assume this is the case.

2. Then install all npm packages in each repository:

   $ cd service.codex-registry-api
   $ npm install
   
   $ cd ../contract.codex-registry
   $ npm install
   
   $ cd ../npm.ethereum-service
   $ npm install
   
   $ cd ../service.eel
   $ npm install

3. After you've installed all npm packages, you will also need to npm link the ethereum-service repository so that the API & EEL can use your locally-deployed smart contracts:

   $ cd npm.ethereum-service
   $ npm link
   
   $ cd ../service.codex-registry-api
   $ npm link @codex-protocol/ethereum-service
   
   $ cd ../service.eel
   $ npm link @codex-protocol/ethereum-service

   Now when you deploy the smart contracts locally, the API will be able to pull the ABIs from the linked ethereum-service repository.

   IMPORTANT NOTE: every time you run npm install in the API or EEL repositories, you will need to re-link the ethereum-service repository. For convenience, you can simply run the npm script npm run link-all to link, or npm run install-and-link to install and link in one step. (You re-link in the API & EEL repositories, not the ethereum-service repository.)

Dependencies

Now you will need to install & set up some dependencies.

1. MongoDB

   MongoDB is where off-chain data (e.g. Codex Record metadata) is stored by the API. It's also used by Agenda to track jobs.

   On MacOS, MongoDB can be installed via Homebrew:

   $ brew install mongodb

   For other platforms, MongoDb can be downloaded directly from the MongoDB website.

2. Redis

   Redis is required for socket.io to emit events and track sockets in a multi-instance environment (for example cluster mode via PM2). While Redis isn't really necessary for local development, at the moment it's required to run the application.

   On MacOS, Redis can be installed via Homebrew:

   $ brew install redis

   For other platforms, Redis can be downloaded directly from the Redis website.

3. Ganache

   Ganache is a blockchain development application that allows you to deploy & test contracts locally.

   You can download Ganache directly from the Truffle Framework website.

4. Create an AWS Account

   This API currently uses S3 to store files for Codex Record metadata, so you will need an AWS account that has access to write to an S3 bucket. You can sign up for a free AWS account on the AWS website.

   After you've set up your account, you will need to save your credentials to ~/.aws/credentials. See these instructions for further details.

5. Link the ethereum-service Repository

   Make sure you've cloned the ethereum-service repository and have npm linked it so that the API will be able to use your locally-deployed smart contracts (see Clone & Set Up Required Repositories above).

   For more information on this repository, see the README.

6. Deploy Codex Registry Smart Contracts

   After you've set up Ganache and linked the ethereum-service repository, you will need to deploy the Codex Registry smart contracts. Make sure Ganache is running, and then run:

   $ cd contract.codex-registry
   $ npm run migrate:reset

   This will make Truffle deploy the contracts to Ganache and copy over the built contract JSON files to the ethereum-service repository, where the API will be able to read them.

7. EEL

   This repository indexes blockchain events and stores them in MongoDB so the API can process them.

   Make sure you've cloned the ethereum-service repository and have npm linked it so that EEL will be able to use your locally-deployed smart contracts (see Clone & Set Up Required Repositories above).

Wow, that was a lot. Give yourself a pat on the back if you made it this far!

Configure

After you've installed & set up all dependencies, you should now update your .env file to match your local environment (for example, change the MongoDB or Redis ports if you're not using the defaults.) See the Security section for more details on the .env file.

Usage

1. Start EEL:

   $ cd service.eel
   $ npm start

2. Start the API:

   $ cd service.codex-registry-api
   $ npm start

Now you should be able to make requests to the API! To check and see if it's responding to requests, try and hit http://localhost:3001/etc/health-check. You should receive an HTTP 200 response.

Maintainers

• John Forrest (@johnhforrest)
• Colin Wood (@Anaphase)
• Shawn Price (@sprice)

Contribute

If you have any questions, feel free to reach out to one of the repository maintainers or simply open an issue here on GitHub. If you have questions about Codex Protocol in general, feel free to reach out to us Telegram!

Pull Requests are not only allowed, but highly encouraged! All Pull Requests must pass CI checks (if applicable) and be approved by at least one repository maintainer before being considered for merge.

Codex Labs, Inc follows the Contributor Covenant Code of Conduct.

License

GNU Affero General Public License v3.0 or later © Codex Labs, Inc