This application can run in 4 modes, each providing a separate application with a distinct use case:
- Chia Climate Tokenization:
- Mode: Registry
- Use case: A registry would use this to tokenize carbon credits onto the Chia blockchain
- Port: 31312
- Application Name: climate-tokenization-chia
- Only listens on localhost for connections from the Climate Tokenization Engine
- Climate Explorer:
- Mode: Explorer
- Use case: A registry (or interested observer) would use this to track all on-chain activity related to tokenized carbon credits
- Port: 31313
- Application Name: climate-explorer
- Climate Token Driver:
- Mode: Client
- Use case: A carbon token holder could use this in conjunction with the Climate Wallet to manage their tokenized carbon credits
- Port: 31314
- Application Name: climate-token-driver
- Dev Mode (for developers only!):
- Mode: Dev
- Use case: Developers are able to test the software without having to communicate with the blockchain
- Port: 31999
- Application Name: Only available from source builds
When compiling from source, the "mode" is controlled by the .env
file. Each application, or mode, is offered as precompiled binaries, appropriate for most users.
- Chia Blockchain
- Climate Tokenization Engine
- Climate Tokenization Engine User Interface
- Climate Explorer UI
- Climate Wallet
- Climate Action Data Trust
- Climate Action Data Trust UI
app
:api
: API layer implementationscore
: service layer implementationscrud
: repository layer implementationsdb
: database utilitiesmodels
: database modelsschemas
: schemas shared by all the layers
tests
: pytest suites
Precompiled executables are available for Mac, Windows, and Linux (both ARM and x86) on the releases page.
For users of Debian, Ubuntu, Mint, PopOS, and other Debian-based distributions, a .deb file is provided on the releases page. This can be installed with
dpkg -i package-filename.deb
The Chia Climate Tokenization and Climate Explorer applications are also available via apt:
- Start by updating apt and allowing repository download over HTTPS:
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
- 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
- Use the following command to setup the repository.
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/chia.gpg] https://repo.chia.net/climate-tokenization/debian/ stable main" | sudo tee /etc/apt/sources.list.d/climate-tokenization.list > /dev/null
- Install Chia Clmate Tokenization and Climate Explorer
sudo apt-get update
sudo apt-get install climate-tokenization-chia
sudo apt-get install climate-explorer-chia
- Start Chia Climate Tokenization and Climate Explorer with systemd
sudo systemctl start climate-tokenization-chia@<USERNAME>
sudo systemctl start climate-explorer-chia@<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 Chia Climate Tokenization with systemctl start climate-tokenization-chia@ubuntu
.
- Set the Chia Climate Tokenization and Climate Explorer to run at boot
sudo systemctl enable climate-tokenization-chia@<USERNAME>
sudo systemctl enable climate-explorer-chia@<USERNAME>
-
Clone this repo.
git clone --recurse-submodules https://github.com/Chia-Network/climate-token-driver.git
or, using SSH...
git clone --recurse-submodules git@github.com:Chia-Network/climate-token-driver.git
-
Note that
chia-blockchain
is used as a submodule of this repo to involve its test suites from the source file. Includechia-blockchain
in python search path with:export PYTHONPATH=.:./chia-blockchain:$PYTHONPATH
-
Make a
.env
file for your environment variables. See the section below for setting up a correct.env
file.cp .env.example .env # then change variable in .env
Note there are two steps the application loads the configurations:
-
The application will first look for any environment variables set on the host machine for
MODE
,CHIA_ROOT
, andCONFIG_PATH
. Any variables not set on the host system will be loaded from the.env
environment file, which is opened viapython-dotenv
, where${CHIA_ROOT}
and${CONFIG_PATH}
are pre-loaded. This file is not visible to end users in packaged binaries, and are suitable for binary builders to change the default flavor for the binary (though it is overridden by system environment variables). -
Then, a
config.yaml
file located at${CHIA_ROOT}/${CONFIG_PATH}
is loaded, which adds to the configurations after.env
. This part of the configuration is free to change by end binary users. When the application is closed and reopened, the new configurable would automatically apply.
The whole list of configurable variables are detailed in config.py, and below we provide brief explanations:
MODE (environment variable)
: one ofdev
,registry
,client
, andexplorer
. Indev
mode, the application essentially enables all functionalities (endpoints), while in the rest, some select endpoints will be allowed. Each mode has installers and executable binaries built and available on the releases page.CHIA_ROOT (environment variable)
: the root of Chia wallets on the local machine, typically~/.chia/mainnet
.CONFIG_PATH (environment variable)
: the path of theconfig.yaml
file, relative to${CHIA_ROOT}
. Rarely needs to be changed.LOG_PATH
: the path this application write logs to, relative to${CHIA_ROOT}
.CADT_API_SERVER_HOST
: the CADT API URL in the format ofscheme://domain:port/path
.CADT_API_KEY
: the CADT API key.
Only when in registry
(Chia Climate Tokenization) and client
(Climate Token Driver) modes, the following configurations are relevant:
DEFAULT_FEE
: the fee, in mojos, for token-related transactions.CHIA_HOSTNAME
: the Chia service to connect to.CHIA_FULL_NODE_RPC_PORT
: the Chia full node RPC port.CHIA_WALLET_RPC_PORT
: the Chia wallet RPC port.
Only in registry
mode (Chia Climate Tokenization), the following configurations are relevant:
CLIMATE_TOKEN_REGISTRY_PORT
: 31312 by default.
There is no option to set the SERVER_HOST
in registry mode as this is designed to only integrate with the Climate Tokenization Engine or other tokenization engines on localhost and will therefore only listen on 127.0.0.1.
Only in client
mode (Climate Token Driver) are the following configurations relevant:
CLIMATE_TOKEN_CLIENT_PORT
: 31314 by default.
As with registry
mode, client
mode is only designed to integrate with other tools (such as the Climate Wallet) on localhost and therefore only listens on 127.0.0.1.
Only when in explorer
mode, the following configurations are relevant:
CLIMATE_EXPLORER_SERVER_HOST
: Network interface to bind the climate explorer to. Default is0.0.0.0
as the Climate Explorer is intended to be a publicly available interface. Can be set to127.0.0.1
to be privately available only on localhost.CLIMATE_EXPLORER_PORT
: 31313 by default.DB_PATH
: the database this application writes to, relative to${CHIA_ROOT}
.BLOCK_START
: the block to start scanning for climate token activities.BLOCK_RANGE
: the number of blocks to scan for climate token activities at a time.MIN_DEPTH
: the minimum number of blocks an activity needs to be on chain to be recorded.LOOKBACK_DEPTH
: this number of latest blocks are always rescanned to ensure all latest token activities are picked up for newly created tokens.
-
Optionally create virtual environment, and install dependencies.
python -m virtualenv venv && source venv/bin/activate poetry install
-
Run the main script for development.
python app/main.py
-
Package the app.
# first ensure the `MODE` is set to the intended mode, then python -m PyInstaller --clean pyinstaller.spec
-
Run the binary.
./dist/main
- Invoke
pytest
with:# first ensure the `MODE` is set to the `dev` for all tests to be discoverable, then python -m pytest ./tests
Signed commits are required.
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 it is very important to get this right.
feat
is for introducing a new featurefix
is for bug fixesdocs
for documentation only changesstyle
is for code formatting onlyrefactor
is for changes to code which should not be detectable by users or testersperf
is for a code change that improves performancetest
is for changes which only touch test files or related toolingbuild
is for changes which only touch our develop/release toolsci
is for changes to the continuous integration files and scriptschore
is for changes that don't modify code, like a version bumprevert
is for reverting a previous commit
After the type and scope there should be a colon.
The "subject" of the commit follows. It should be a short indication of the change. The commit convention prefers that this is written in the present-imperative tense.
All pull requests should be made against the develop
branch. Commits to the main
branch will trigger a release, so the main
branch is always the code in the latest release.