Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cancelchain/cancelchain

A Blockchain of Accountability, Forgiveness, and Support
https://github.com/cancelchain/cancelchain

blockchain blockchain-network blockchain-platform blockchain-projects flask python python-blockchain

Last synced: about 2 months ago
JSON representation

A Blockchain of Accountability, Forgiveness, and Support

Awesome Lists containing this project

README 

        
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:



.. code-block:: console



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



.. code-block:: console



  # 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`_:



.. code-block:: console



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



.. 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 `_ 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



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



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



.. _account page: 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

.. _FLASK_SECRET_KEY: https://docs.cancelchain.org/en/latest/usage.html#SECRET_KEY

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

.. _dotenv documentation: https://docs.cancelchain.org/en/latest/usage.html#dotenv

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

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