Metadata-Version: 2.1
Name: cancelchain
Version: 1.3.2
Summary: A Blockchain of Accountability, Forgiveness, and Support
Project-URL: Homepage, https://cancelchain.org
Project-URL: Documentation, https://docs.cancelchain.org
Project-URL: Source, https://github.com/cancelchain/cancelchain
Project-URL: Tracker, https://github.com/cancelchain/cancelchain/issues
Author-email: Thomas Bohmbach Jr <tom@cancelchain.org>
License-Expression: MIT
License-File: LICENSE
Keywords: blockchain,flask
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Flask
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Sociology
Requires-Python: >=3.9
Requires-Dist: base58check>=1.0
Requires-Dist: blinker>=1.6
Requires-Dist: celery>=5.2
Requires-Dist: click>=8.1
Requires-Dist: flask-caching>=2.0
Requires-Dist: flask-sqlalchemy>=3.0
Requires-Dist: flask>=2.3
Requires-Dist: gunicorn>=20.1
Requires-Dist: humanfriendly>=10.0
Requires-Dist: marshmallow>=3.19
Requires-Dist: millify>=0.1
Requires-Dist: passlib[argon2]>=1.7
Requires-Dist: pg8000>=1.29
Requires-Dist: pycryptodome>=3.17
Requires-Dist: pyjwt>=2.6
Requires-Dist: pymerkle>=4.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.29
Requires-Dist: rich>=13.3
Requires-Dist: sqlalchemy<2.0
Description-Content-Type: text/x-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

Installation
------------

Install CancelChain using pip:

.. code-block:: console

  $ pip install cancelchain

It is recommended that a `python virtual environment`_ is used for `all <https://realpython.com/python-virtual-environments-a-primer/#avoid-system-pollution>`__ `the <https://realpython.com/python-virtual-environments-a-primer/#sidestep-dependency-conflicts>`__ `usual <https://realpython.com/python-virtual-environments-a-primer/#minimize-reproducibility-issues>`__ `reasons <https://realpython.com/python-virtual-environments-a-primer/#dodge-installation-privilege-lockouts>`_.


Configuration
-------------

Create a `python-dotenv`_ ``.env`` file. Here is an example minimal configuration:

.. code-block:: console

  # Flask Settings
  FLASK_APP=cancelchain
  FLASK_RUN_HOST=0.0.0.0

  # CancelChain Settings
  CC_SECRET_KEY=0b6ceaa3b10d3e7a5dc53194
  CC_SQLALCHEMY_DATABASE_URI=sqlite:///cc.sqlite

The `CC_SECRET_KEY <https://docs.cancelchain.org/en/latest/usage.html#SECRET_KEY>`_ value should be a unique random string.

See the `Configuration Documentation`_ for more configuration settings.

The ``cancelchain`` command loads a ``.env`` file by default if it is located either in the current working directory or in the ``cancelchain`` `instance folder`_. Use the ``--env-file`` parameter to specify an alternate file path.

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

.. code-block:: console

  $ 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.

The following ``cancelchain`` command examples assume that the ``.env`` file is loaded by default.

Initialize
----------

Create a local database by running the `init command`_:

.. code-block:: console

  $ cancelchain init

The `CC_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).

Next, run the `import command`_, passing it the location of the downloaded file:

.. code-block:: console

  $ 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:

.. code-block:: console

  $ cancelchain run

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

Home Page (Current Chain)
^^^^^^^^^^^^^^^^^^^^^^^^^

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

Block Page
^^^^^^^^^^

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

Transaction Page
^^^^^^^^^^^^^^^^

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

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:

  .. code-block:: console

    # Network 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

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:

.. code-block:: console

  $ 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 contact@cancelchain.org 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.


.. _Account: https://thecancelbutton.com/account
.. _API access: https://docs.cancelchain.org/en/latest/api.html#api-roles
.. _API Documentation: https://docs.cancelchain.org/en/latest/api.html
.. _Blog: https://blog.cancelchain.org
.. _CancelChain data: https://storage.googleapis.com/blocks.cancelchain.org/cancelchain.jsonl
.. _CC_SECRET_KEY: https://docs.cancelchain.org/en/latest/usage.html#SECRET_KEY
.. _CC_SQLALCHEMY_DATABASE_URI: https://docs.cancelchain.org/en/latest/usage.html#SQLALCHEMY_DATABASE_URI
.. _Command Line Interface Documentation: https://docs.cancelchain.org/en/latest/usage.html#command-line-interface
.. _Configuration Documentation: https://docs.cancelchain.org/en/latest/usage.html#configuration
.. _documentation: https://docs.cancelchain.org
.. _Documentation: https://docs.cancelchain.org
.. _Download Account Key: https://thecancelbutton.com/pem
.. _import command: https://docs.cancelchain.org/en/latest/usage.html#import
.. _init command: https://docs.cancelchain.org/en/latest/usage.html#init
.. _instance folder: https://flask.palletsprojects.com/en/2.2.x/config/#instance-folders
.. _JSON Lines: https://jsonlines.org/
.. _miller: https://docs.cancelchain.org/en/latest/api.html#miller
.. _PEM: https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail
.. _Project Home Page: https://cancelchain.org
.. _python virtual environment: https://docs.python.org/3/library/venv.html
.. _python-dotenv: https://pypi.org/project/python-dotenv/
.. _reader: https://docs.cancelchain.org/en/latest/api.html#reader
.. _Register for an account: https://thecancelbutton.com/register
.. _running milling processes: https://docs.cancelchain.org/en/latest/usage.html#mill
.. _shell command: https://flask.palletsprojects.com/en/2.2.x/cli/#open-a-shell
.. _sock puppet accounts: https://en.wikipedia.org/wiki/Sock_puppet_account
.. _SQLite: https://sqlite.org/index.html
.. _sync command: https://docs.cancelchain.org/en/latest/usage.html#sync
.. _The Cancel Button: https://thecancelbutton.com
.. _transactor: https://docs.cancelchain.org/en/latest/api.html#transactor
