Usage

Running A Node

A node consists of deploying and/or running the CancelChain flask application. The node must also have access to a database indicated with the required configuration value, SQLALCHEMY_DATABASE_URI. The only other required setting is SECRET_KEY. However, to allow the node to do useful work, additional configuration values are usually needed.

Most nodes will want to configure a WALLET_DIR to contain wallets used for API Authorization with other nodes and/or to sign transactions.

The remote nodes that a local node will communicate with are defined using the configuration list PEERS. Most nodes will want to indicate at least one peer with which to share new blocks and transactions.

Incoming authorized remote nodes are configured using the MILLER_ADDRESSES, TRANSACTOR_ADDRESSES, and READER_ADDRESSES lists. See API Roles for more information.

If at least one PEERS entry is defined, the NODE_HOST should also be configured to indicate the hostname and default wallet address of the local node.

In addition to exposing the API used for node-to-node communication, a simple web-based ledger data browser is also provided.

Database

CancelChain requires a relational database and uses Flask SQLAlchemy to interact with it. Any supported database should work.

New databases must be initialized before running a node or miller using the init command:

$ cancelchain init

Configuration

CancelChain can be configured like any other Flask application including a few custom options:

The environment variable CANCELCHAIN_SETTINGS can be set to the location of a python config file.
Most Flask and CancelChain settings can be configured from environment variables. CancelChain-specific environment variables are prefixed with CC_ and are documented below. All other Flask-specific environment variables are prefixed with FLASK_ and loaded with the built-in flask method, from_prefixed_env().

Dotenv

Environment variables can be set using a python-dotenv .env file. A .env file is loaded by default if it is located either in the current working directory or in the instance folder. Use the --env-file parameter to specify an alternate file path when running commands.

You can find the location of the instance folder by running the shell command:

$ cancelchain --env-file path/to/.env shell
Python 3.10.11 (main, Apr  8 2023, 14:38:50) [GCC 11.3.0] on linux
App: cancelchain
Instance: /home/arlo/.pyenv/versions/3.10.11/envs/my-cancelchain/var/cancelchain-instance

By default, it is the directory $PREFIX/var/cancelchain-instance where $PREFIX is the prefix of the Python installation.

Flask

All built-in Flask Configuration values can be set.

The following setting is required:

SECRET_KEY: This value can also be set using the environment variable FLASK_SECRET_KEY.

Flask SQLAlchemy

All Flask SQLAlchemy Configuration values can be set.

The following setting is required:

SQLALCHEMY_DATABASE_URI: This value can also be set using the environment variable FLASK_SQLALCHEMY_DATABASE_URI.

Celery

Celery Task Queue is used to optionally enable asynchronous processing of new blocks and transactions (desireable for nodes with many PEERS).

All Celery Configuration values can be set.

The following setting is required to enable asynchronous processing of new blocks and transactions:

CELERY_BROKER_URL

This value can also be set using the environment variable FLASK_CELERY_BROKER_URL.

Default: None

Note

If you configure a Celery Broker, API_ASYNC_PROCESSING must also be True to enable asynchronous processing.

When running the Celery worker server, set the application to cancelchain.tasks:

$ celery -A cancelchain.tasks worker

Flask Caching

All Flask Caching Configuration values can be set.

No settings are required, but the following has a default and can be configured via an environment variable:

CACHE_TYPE

This value can also be set using the environment variable FLASK_CACHE_TYPE.

Default: NullCache (i.e. no caching).

CancelChain

PEERS

The list of peer nodes that this node will forward blocks and transactions to and synchronize its chain with. Each peer not only defines its host URL but also the wallet address that should be used for authentication and authorization.

A peer node is represented as a URL with the following format:

https://WALLET_ADDRESS@HOST[:PORT]

The WALLET_ADDRESS should be an address that matches a wallet file (i.e. a .pem file) in the WALLET_DIR. For the nodes to successfully communicate, the WALLET_ADDRESS must also be in the peer node’s MILLER_ADDRESSES, TRANSACTOR_ADDRESSES, or READER_ADDRESSES config lists. In addition, the WALLET_ADDRESS must have initiated at least one successful transaction so the peer node can access the WALLET_ADDRESS’s public key for use in authentication.

This value can also be set using the environment variable CC_PEERS with a list of of peers in JSON array format.

Default: list()

NODE_HOST

This node’s host URL including wallet address component (see PEERS). This will be the host URL/wallet address used to perform background processing on the node. In addition, the host URL (sans wallet address) is used to identify the node on the network.

This value can also be set using the environment variable CC_NODE_HOST.

Default: None

API_CLIENT_TIMEOUT

The timeout in seconds for calls using the API client.

This value can also be set using the environment variable CC_API_CLIENT_TIMEOUT.

Default: 10

API_ASYNC_PROCESSING

A boolean indicating whether processing of incoming blocks and transactions should be handled asynchronously.

This value can also be set using the environment variable CC_API_ASYNC_PROCESSING with a JSON boolean string (true or false).

Default: False

Warning

If True, CELERY_BROKER_URL must also be configured or incoming blocks and transactions will not be processed.

DEFAULT_COMMAND_HOST

The default host URL (with optional auth wallet address (see PEERS)) for CLI commands to use for API calls.

This value can also be set using the environment variable CC_DEFAULT_COMMAND_HOST.

Default: None

WALLET_DIR

The directory path where wallet (i.e. .pem) files are stored.

This value can also be set using the environment variable CC_WALLET_DIR.

Default: None

ADMIN_ADDRESSES

The list of wallet addresses and/or regular expressions that when matched and authenticated are granted the role of ADMIN. See API Roles for more information.

This value can also be set using the environment variable CC_ADMIN_ADDRESSES with a list of wallet addresses in JSON array format.

Default: list()

MILLER_ADDRESSES

The list of wallet addresses and/or regular expressions that when matched and authenticated are granted the role of MILLER. See API Roles for more information.

This value can also be set using the environment variable CC_MILLER_ADDRESSES with a list of wallet addresses in JSON array format.

Default: list()

TRANSACTOR_ADDRESSES

The list of wallet addresses and/or regular expressions that when matched and authenticated are granted the role of TRANSACTOR. See API Roles for more information.

This value can also be set using the environment variable CC_TRANSACTOR_ADDRESSES with a list of wallet addresses in JSON array format.

Default: list()

READER_ADDRESSES

The list of wallet addresses and/or regular expressions that when matched and authenticated are granted the role of READER. See API Roles for more information.

This value can also be set using the environment variable CC_READER_ADDRESSES with a list of wallet addresses in JSON array format.

Default: list()

Command Line Interface

Administrative interactions with the CancelChain application are conducted through its Command Line Interface (CLI).

Usage:

$ cancelchain [OPTIONS] COMMAND [ARGS]...

Options:

--version: Show the version and exit.
--help: Show the help message and exit.

CancelChain registers its own cancelchain command that can be used as a drop-in replacement for the standard flask CLI and inherits all of the built-in Flask Command Line Interface commands (e.g. run and shell).

CLI Commands

export

Export the block chain to file.

Usage:

$ cancelchain export FILE

Args:

FILE:: The file path to export the blocks to. If the file already exists, it will be appended to.

import

Import the block chain from file.

Usage:

$ cancelchain import FILE

Args:

FILE:: The file path from which to import the blocks.

A recent JSON Lines export of the CancelChain block data can be downloaded here.

init

Initialize the database.

Usage:

$ cancelchain init

mill

Start a milling process.

Usage:

$ cancelchain mill [OPTIONS] ADDRESS

Args:

ADDRESS:: The wallet address to use for milling coinbase rewards.

Options:

-m, --multi: Use python multiprocessing when calculating hashes.
-r, --rounds INTEGER: Number of rounds of milling between new block checks. (default 1)
-s, --size INTEGER: Number of hashes to calculate per round (per CPU if multiprocessing is enabled) (default 100000)
-w, --wallet PATH: Wallet file to use for milling coinbase rewards.
-p, --peer TEXT: Peer node to poll before checking for new blocks and transactions.
-b, --blocks INTEGER: Stop after this many blocks. (default 0 (run forever))

Note

Many CLI commands will make API calls to a CancelChain node. If the command’s specified API host (or the default specified by DEFAULT_COMMAND_HOST) does not specify a wallet address, or the CLI does not have access to the address’ wallet (i.e. it is not in WALLET_DIR), a wallet file must be specified for API auth.

subject-balance

Get the balance (i.e. subject transactions minus forgiveness transactions) in CCG for a subject.

Usage:

$ cancelchain subject balance [OPTIONS] SUBJECT

Args:

SUBJECT:: The raw (unencoded) subject string.

Options:

-h, --host TEXT: The API host to use (default: DEFAULT_COMMAND_HOST).
-w, --wallet PATH: Wallet file to use for API auth.

subject-support

Get the support total in CCG for a subject.

Usage:

$ cancelchain subject support [OPTIONS] SUBJECT

Args:

SUBJECT:: The raw (unencoded) subject string.

Options:

-h, --host TEXT: The API host to use (default: DEFAULT_COMMAND_HOST).
-w, --wallet PATH: Wallet file to use for API auth.

sync

Synchronize the node’s block chain to that of its peers.

Usage:

$ cancelchain sync

txn-transfer

Create and post a transfer transaction.

Usage:

$ cancelchain txn transfer [OPTIONS] FROM_ADDRESS AMOUNT TO_ADDRESS

Args:

FROM_ADDRESS:: The transaction source address.
AMOUNT:: The amount (as a float) of CCG to transfer.
TO_ADDRESS:: The transaction destination address.

Options:

-t, --txn-wallet PATH: Wallet file to use for transaction source.
-h, --host TEXT: The API host to use (default: DEFAULT_COMMAND_HOST).
-w, --wallet PATH: Wallet file to use for API auth.
-y, --yes: Assume “yes” as answer to all prompts and run non-interactively.

txn-subject

Create and post a subject (i.e. “cancel”) transaction.

Usage:

$ cancelchain txn subject [OPTIONS] ADDRESS AMOUNT SUBJECT

Args:

ADDRESS:: The transaction source address.
AMOUNT:: The amount (as a float) of CCG to apply.
SUBJECT:: The raw (unencoded) subject string.

Options:

-t, --txn-wallet PATH: Wallet file to use for transaction source.
-h, --host TEXT: The API host to use (default: DEFAULT_COMMAND_HOST).
-w, --wallet PATH: Wallet file to use for API auth.
-y, --yes: Assume “yes” as answer to all prompts and run non-interactively.

txn-forgive

Create and post a forgiveness transaction.

Usage:

$ cancelchain txn forgive [OPTIONS] ADDRESS AMOUNT SUBJECT

Args:

ADDRESS:: The transaction source address.
AMOUNT:: The amount (as a float) of CCG to apply.
SUBJECT:: The raw (unencoded) subject string.

Options:

-t, --txn-wallet PATH: Wallet file to use for transaction source.
-h, --host TEXT: The API host to use (default: DEFAULT_COMMAND_HOST).
-w, --wallet PATH: Wallet file to use for API auth.
-y, --yes: Assume “yes” as answer to all prompts and run non-interactively.

txn-support

Create and post a support transaction.

Usage:

$ cancelchain txn support [OPTIONS] ADDRESS AMOUNT SUBJECT

Args:

ADDRESS:: The transaction source address.
AMOUNT:: The amount (as a float) of CCG to apply.
SUBJECT:: The raw (unencoded) subject string.

Options:

-t, --txn-wallet PATH: Wallet file to use for transaction source.
-h, --host TEXT: The API host to use (default: DEFAULT_COMMAND_HOST).
-w, --wallet PATH: Wallet file to use for API auth.
-y, --yes: Assume “yes” as answer to all prompts and run non-interactively.

validate

Validate the node’s block chain.

Usage:

$ cancelchain validate

wallet-balance

Get the wallet balance in CCG for an address.

Usage:

$ cancelchain wallet balance [OPTIONS] ADDRESS

Args:

ADDRESS:: The wallet address.

Options:

-h, --host TEXT: The API host to use (default: DEFAULT_COMMAND_HOST).
-w, --wallet PATH: Wallet file to use for API auth.

wallet-create

Create a new wallet file.

Usage:

$ cancelchain wallet create [OPTIONS]

Options:

-d, --walletdir PATH: Parent directory for the wallet file (default: WALLET_DIR).

Running A Miller

The CancelChain block milling is performed by a permissioned (i.e. private) network. If you are interested in joining the network, email us.

Note

CCG is not a cryptocurrency. By design, it has an inflationary, never-decreasing coinbase reward. It also lacks rewards for address-to-address transfers compared to large rewards for other ledger transactions. It is intended to have no value other than being a ticket for creating subject, forgiveness, and support transactions on the blockchain ledger.