GumptionChain

GumptionChain 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.12

Install

Install GumptionChain using pip:

$ pip install gumptionchain

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

For development on the project itself, use uv to manage the environment and dependencies:

$ git clone https://github.com/gumptionthomas/gumptionchain.git
$ cd gumptionchain
$ uv sync --group dev
$ uv run gumptionchain --help

Configure

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

A minimal .env configuration file:

# Flask Settings
FLASK_APP=gumptionchain
FLASK_SECRET_KEY=0b6ceaa3b10d3e7a5dc53194

# Flask-SQLAlchemy Settings
FLASK_SQLALCHEMY_DATABASE_URI=sqlite:///gc.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:

$ gumptionchain init

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

Import

The import command bulk-loads blocks from a JSON Lines export — for example, a file produced by the gumptionchain export command on another node.

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

$ gumptionchain import path/to/gumptionchain.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 gumptionchain application by issuing the run command:

$ gumptionchain 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 gumptionchain 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 gumptionchain commands for interacting with the blockchain. See the Command Line Interface Documentation for more information or run gumptionchain --help.

Joining The GumptionChain Network

The GumptionChain is run by a permissioned network of nodes. A GumptionChain 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 GumptionChain.

API access to a node is granted by that node's operator. Once your wallet address is on a node's role allowlist (see below to request access), configure your instance to use that node as a peer. Replace GCYourWalletAddressGC with your wallet address, peer.example.com with the host of the node you've been granted access to, and /path/to/wallets with the path to a directory containing your key (PEM) file:

# GumptionChain Settings
GC_NODE_HOST=http://GCYourWalletAddressGC@localhost:5000
GC_PEERS=["https://GCYourWalletAddressGC@peer.example.com"]
GC_DEFAULT_COMMAND_HOST=https://GCYourWalletAddressGC@peer.example.com
GC_WALLET_DIR=/path/to/wallets

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:

$ gumptionchain 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 GumptionChain network, send an email to contact@gumption.com 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.