search

Chia-Network / cadt

Climate Action Data Trust
Apache License 2.0
35 stars 12 forks source link
chia-blockchain

readme

Climate Action Data Trust

Please review the CAD Trust Terms and Conditions and CAD Trust User Terms and Conditions.

​This project provides the Climate Action Data Trust (CADT) API that integrates with the Chia Blockchain. For a user interface, see the CADT UI project, which will connect to the CADT API.

This project was formerly known as the Climate Warehouse, and you may see this term used interchangeably with CADT.

Pagination is now strongly recommended on the units, projects, and issuances API endpoints and will be mandatory in the future. Please adjust your API calls accordingly.

User Guide

The CADT application is designed to run 24/7, much like any other API. While it is possible to run it on-demand only when API requests need to be made, this guide assumes a permanently running solution.

The simplest way to run the CADT application is to use the same machine the Chia Full Node, Wallet, Datalayer, and Datalayer HTTP services reside on. CADT communicates with the Chia services over an RPC interface. The RPC interface uses certificates to authenticate, which will work automatically when the CADT application is run as the same user on the same machine as the Chia services. To run CADT on a separate machine from Chia, a public certificate from the Chia node must be used to authenticate (not yet documented).

For Chia installation instructions, please see the Chia docs site. For most CADT setups, we recommend the installing the headless chia-blockchain-cli package via the apt repo and using systemd.

How to use the API

Please see the CADT RPC API Guide.

Installation

Releases are tagged in Github, and binaries are built for Windows, macOS, and Linux. ARM binaries are available for Debian versions of Linux only.

System Requirements

CADT and Chia system usage will depend on many factors, including how busy the blockchain is, how much data is being mirrored by DataLayer, and how much data CADT is ingesting and processing. The current minimum requirements for running CADT and Chia together on a system are:

ARM and x86 systems are supported. While Windows, MacOS, and all versions of Linux are supported, Ubuntu Linux is the recommended operating system as it is used most in testing and our internal hosting.

Linux

A binary file that can run on all Linux distributions on x86 hardware can be found for each tagged release named cadt-linux-x64-<version>.zip. This zip file will extract to the cadt-linux-64 directory by default, where the cadt file can be executed to run the API.

Debian-based Linux Distros (Ubuntu, Mint, etc)

The CADT API can be installed with apt. Both ARM and x86 versions can be installed this way.

  1. Start by updating apt and allowing repository download over HTTPS:
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
  1. Add Chia's official GPG Key (if you have installed Chia with apt, you'll have this key already and will get a message about overwriting the existing key, which is safe to do):
curl -sL https://repo.chia.net/FD39E6D3.pubkey.asc | sudo gpg --dearmor -o /usr/share/keyrings/chia.gpg
  1. Use the following command to set up the repository.
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/chia.gpg] https://repo.chia.net/cadt/debian/ stable main" | sudo tee /etc/apt/sources.list.d/cadt.list > /dev/null
  1. Install CADT
sudo apt-get update
sudo apt-get install cadt
  1. Start CADT with systemd
sudo systemctl start cadt@<USERNAME>

For <USERNAME>, enter the user that Chia runs as (the user with the .chia directory in their home directory). For example, if the ubuntu is where Chia runs, start CADT with systemctl start cadt@ubuntu.

  1. Set CADT to run at boot
sudo systemctl enable cadt@<USERNAME>

Installation from Source

You'll need: ​

To install from source:

git clone git@github.com:Chia-Network/cadt.git
cd cadt
nvm install 18.16
nvm use 18.16
npm run start

Ports, Networking, and Security

By default, the CADT API will listen on localhost only on port 31310. If running a node with READ_ONLY set to false, it is highly recommended that CADT is run on a private network or with access limited by IP address. To allow remote connections to CADT, set the BIND_ADDRESS (see the Configuration section below) to the IP to listen on, or 0.0.0.0 to listen on all interfaces. The port for the CADT API can be set with the parameter CW_PORT. The default port is 31310. In many cases, users will need to access the API from their workstations for either the CADT UI or to integrate with existing tools and scripts. To add authentication to the API, use the CADT_API_KEY parameter. Alternatively, the API can be served behind an authentication proxy to restrict access and the CADT_API_KEY can be left blank. If running an observer node with READ_ONLY set to true, the CADT API will only share data from the public blockchain, and running without authentication is usually safe. If READ_ONLY is set to false, authentication must be used to prevent unauthorized writes to the blockchain.

Adding Encryption to the CADT API

The CADT API uses HTTP and is unencrypted. To add encryption, use a reverse proxy like Nginx with an SSL certificate. In this scenario, the CADT application can be set to listen only on localhost, and Nginx (on the same server) will proxy incoming requests to port 31310.

Configuration

In the CHIA_ROOT directory (usually ~/.chia/mainnet on Linux), CADT will add a directory called cadt/v1 when the application is first run (in fact, this directory could be deleted at any time and CADT will recreate it next time it is started). The main CADT configuration file is called config.yaml and can be found in this directory. The options in this file are as follows (the full list of available options can be seen in the config template):

​ Note that the CADT application will need to be restarted after any changes to the config.yaml file.

Developer Guide

A development environment for CADT assumes a synced Chia wallet running locally. Node version manager (nvm) is used to switch node environments quickly. The repo contains a .nvmrc file that specifies the node version the CADT is expected to use and developers can do nvm use to switch to the version in the .nvmrc.

Contributing

All branches should be created from the develop branch and not from main. All pull requests should be made against the develop branch unless it is a new release. The develop branch will be merged into the main branch to create a release. Automation in the CI will create the release and attach the installation files to it automatically whenever code is merged to main. Additionally, the changelog will automatically be updated in the main branch. Therefore, the main branch should always be a representation of the latest released code.

​This repo uses a commit convention. A typical commit message might read: ​

    fix: correct home screen layout

​ The first part of this is the commit "type". The most common types are "feat" for new features and "fix" for bugfixes. Using these commit types helps us correctly manage our version numbers and changelogs. Since our release process calculates new version numbers from our commits, getting this right is very important. ​

Versioning

This project mostly adheres to semantic versioning. The version specified in package.json will be used by the ci to create the new release in Github, so it is important to set that correctly. The major version (version 1.0, 2.0, etc) should only be changed when the data model changes and the API goes from v1 to v2. Minor version changes (version 1.2 to 1.3, etc.) are for breaking or substantial changes, usually requiring some action on the user's part.
​

Commit linting

​ Each time you commit the message will be checked against these standards in a pre-commit hook. Additionally, all the commits in a PR branch will be linted before it can be merged to master.

To set up the pre-commit hooks on your local, run the following: ​

npm install -g @babel/cli husky prettier lint-staged cross-env
npm set-script prepare "husky install"
npm run prepare
​
// If you are on linux or mac run
chmod ug+x .husky/*
chmod ug+x .git/hooks/*

Build Binaries

After running the "Installation from Source" steps above, do the following: 

// transcompile project to es5
npm run build
​
// Output binaries to dist folder
npm run create-win-x64-dist
npm run create-mac-x64-dist
npm run create-linux-x64-dist

Sequelize Generator

​

Creating Model and Migration Script

​ Use the following command to create a model and a migration script ​ npx sequelize-cli model:generate --name User --attributes firstName:string,lastName:string,email:string ​

Running Migrations

​ Migrations run automatically when you run the software. There is no manual tool that needs to be used. ​

Making changes to Migrations without rolling back

​ If you want to alter, drop, or add a column or add a foreign key or anything with the table. Use the following command to create a barebones migration script ​ npx sequelize-cli migration:generate --name ​

Running Full Text Search Queries

​ To run an FTS query on a supported table, you can use the MATCH operator. A virtual column rank is also available for sorting purposes. ​ Example: ​

SELECT rank, * FROM projects_fts WHERE projects_fts MATCH "PartialMatch*" ORDER BY rank
​
The '*' in the match is needed for wildcard

​ More info: https://www.sqlite.org/fts5.html ​

Connecting to the WebSocket

  1. Open a WebSocket connection to http://localhost:31310/v1/ws
    1. Once subscribed, emit either emit ...['subscribe', 'units'] or ['subscribe', 'projects']. You can emit both on the same connection
  2. You will receive frames that look like ...[change:units, {orgUid: '123'}], letting you know that there has been an update to a record Coll