Skip to content

Latest commit

 

History

History
152 lines (91 loc) · 6.87 KB

quickstart.rst

File metadata and controls

152 lines (91 loc) · 6.87 KB
Raw

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 :ref:`dotenv documentation <Dotenv>` 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 :py:data:`FLASK_SECRET_KEY <SECRET_KEY>` value should be a unique random string.

See the :ref:`Configuration Documentation <Configuration>` for more configuration settings.

Initialize

Create a local database by running the :ref:`init command <Init>`:

$ cancelchain init

The :py:data:`FLASK_SQLALCHEMY_DATABASE_URI <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 Data

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 :ref:`import command <Import>`, 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)

https://github.com/cancelchain/cancelchain/blob/7a4fab66dfe6026e56c79df3e147b1ecbdbb6158/readme-assets/browser-chain.png?raw=true

Block Page

https://github.com/cancelchain/cancelchain/blob/7a4fab66dfe6026e56c79df3e147b1ecbdbb6158/readme-assets/browser-block.png?raw=true

Transaction Page

https://github.com/cancelchain/cancelchain/blob/7a4fab66dfe6026e56c79df3e147b1ecbdbb6158/readme-assets/browser-txn.png?raw=true

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

There are other cancelchain commands for interacting with the blockchain. See the :ref:`Command Line Interface Documentation <Command Line Interface>` 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 :ref:`miller <Miller>` or :ref:`transactor <Transactor>` role :ref:`API access <API Roles>` 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 :ref:`reader <Reader>` role :ref:`API access <API Roles>` 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://CCTheCancelButtonAddressCC@thecancelbutton.com"]
CC_DEFAULT_COMMAND_HOST=https://CCTheCancelButtonAddressCC@thecancelbutton.com
CC_WALLET_DIR=/path/to/wallets
  1. Restart to load the new configuration.

See :ref:`Configuration Documentation <Configuration>` for more detailed information about these settings.

The :ref:`reader <Reader>` role :ref:`API access <API Roles>` allows the :ref:`sync command <Sync>` 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 :ref:`sync command <Sync>` 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 :ref:`Command Line Interface Documentation <Command Line Interface>` for more information.

If you would like to be granted other :ref:`API access <API Roles>` to a node in the CancelChain network, send an email to contact@cancelchain.org including what kind of role you'd like (e.g. :ref:`reader <Reader>`, :ref:`transactor <Transactor>`, or :ref:`miller <Miller>`) and how you intend to use it (e.g. research, business, non-profit, hobby).

See the :ref:`documentation <The Ledger>` for some potential development ideas.