README.rst

CancelChain

CancelChain is an open-source python project that implements a custom blockchain ledger. The ledger protocol allows for the assigning of tokens to subjects (utf-8 strings of less than 80 characters) as indications of either opposition or support. Opposition entries are allowed to be rescinded later. Support is forever.

• Project Home Page
• Documentation
• Blog

Quick Start

Requirements

Python >= 3.9

Install

Install CancelChain using pip:

$ pip install cancelchain

It is recommended that a python virtual environment is used for all the usual reasons.

Configure

Create a python-dotenv .env file. The cancelchain command loads a .env file in the current working directory by default. See dotenv documentation to locate the file elsewhere. The following cancelchain command examples assume that the .env file is loaded by default.

A minimal .env configuration file:

# Flask Settings
FLASK_APP=cancelchain
FLASK_SECRET_KEY=0b6ceaa3b10d3e7a5dc53194

# Flask-SQLAlchemy Settings
FLASK_SQLALCHEMY_DATABASE_URI=sqlite:///cc.sqlite

The FLASK_SECRET_KEY value should be a unique random string.

See the Configuration Documentation for more configuration settings.

Initialize

Create a local database by running the init command:

$ cancelchain init

The FLASK_SQLALCHEMY_DATABASE_URI value in the example configuration above specifies a SQLite database called cc.sqlite with a file path relative to the cancelchain instance folder.

Import

Download the most recent export of CancelChain data. This JSON Lines file is updated at every blockchain epoch (2016 blocks or approximately every two weeks).

Run the import command, passing it the location of the downloaded file:

$ cancelchain import path/to/cancelchain.jsonl

This command could take a while to run depending on your computer and the number of blocks imported. A progress bar will display with estimated time remaining. You can run the import command multiple times and it will only import new blocks that are not yet in the database.

Run

Run the cancelchain application by issuing the run command:

$ cancelchain run

Open http://localhost:5000 in a browser to explore the local copy of the blockchain.

Home Page (Current Chain)

Block Page

Transaction Page

Running the cancelchain application also exposes a set of web service endpoints that comprise the communications layer of the blockchain. See the API Documentation for more information.

There are other cancelchain commands for interacting with the blockchain. See the Command Line Interface Documentation for more information or run cancelchain --help.

Joining The CancelChain Network

The CancelChain is run by a permissioned network of nodes. A CancelChain instance requires miller or transactor role API access to a node in the network in order to have locally milled blocks or submitted transactions propagate to the official CancelChain.

The Cancel Button allows reader role API access to any account that completes at least one transaction on the blockchain:

1. Register for an account.
2. Submit a successful transaction for any subject. Access won't be granted until the sentiment transaction successfully completes.
3. Click Download Account Key on the account page to download the account's key (PEM) file.
4. Create a directory called wallets and copy the downloaded key file into it.
5. Add the following settings to the .env configuration file. Replace CCTheCancelButtonAddressCC with the address on the account page and /path/to/wallet with the path to the wallets directory created above:

# CancelChain Settings
CC_NODE_HOST=http://CCTheCancelButtonAddressCC@localhost:5000
CC_PEERS=["https://[email protected]"]
CC_DEFAULT_COMMAND_HOST=https://[email protected]
CC_WALLET_DIR=/path/to/wallets

6. Restart to load the new configuration.

See Configuration Documentation for more detailed information about these settings.

The reader role API access allows the sync command to update to the most recent peer block data:

$ cancelchain sync

This command could take a while to run depending on your computer, internet access, and the number of blocks synchronized. A progress bar will display with estimated time remaining. You can run the sync command multiple times and it will only synchronize new blocks that are not yet in the database.

Reader access also allows querying data (i.e. subject counts and balances) using the CLI. See Command Line Interface Documentation for more information.

If you would like to be granted other API access to a node in the CancelChain network, send an email to [email protected] including what kind of role you'd like (e.g. reader, transactor, or miller) and how you intend to use it (e.g. research, business, non-profit, hobby).

See the documentation for some potential development ideas.