GumptionChain is an open-source Python project that implements a custom proof-of-work blockchain ledger. The ledger lets tokens be assigned to subjects (UTF-8 strings of 1–79 characters) as indications of either opposition or support. Either kind of stake can be rescinded later.
Tokens are denominated in GRIT (1 GRIT = 100 grains). GumptionChain runs as
both a Flask web application (a browser explorer plus a JSON API) and a
gumptionchain command-line tool. The network is permissioned: API access
is gated by role (READER < TRANSACTOR < MILLER < ADMIN).
- HTTP API reference — endpoints, roles, payloads.
- CLI reference — the
gumptionchaincommand tree. - Configuration reference —
FLASK_*/GC_*settings and role allowlists. - API authentication protocol — the
gc-sig-v1per-request signing scheme. - Full index:
docs/.
Python >= 3.12
Install GumptionChain using pip:
$ pip install gumptionchainIt is recommended that a Python virtual environment is used.
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 --helpSee CONTRIBUTING.md for the development workflow and quality gates.
Create a python-dotenv .env file
in the working directory. A minimal configuration:
# Flask Settings
FLASK_APP=gumptionchain
FLASK_SECRET_KEY=change-me-to-a-random-string
# Flask-SQLAlchemy Settings
FLASK_SQLALCHEMY_DATABASE_URI=sqlite:///gc.sqliteFLASK_SECRET_KEY should be a unique random string. See the
configuration reference for all available settings.
Create a local database (this applies all schema migrations):
$ gumptionchain initThe example FLASK_SQLALCHEMY_DATABASE_URI above specifies a
SQLite database called gc.sqlite, relative
to the gumptionchain
instance folder.
The import command bulk-loads blocks from a JSON Lines
export — for example, a file produced by gumptionchain export on another node:
$ gumptionchain import path/to/gumptionchain.jsonlThis can take a while depending on your machine and the number of blocks; a progress bar shows estimated time remaining. The command is idempotent — run it again and only new blocks are imported.
Run the application with the run command:
$ gumptionchain runOpen http://localhost:5000 in a browser to explore the local copy of the blockchain.
Running the application also exposes the JSON API that forms the communications
layer of the blockchain — see the API reference. For
the other commands, see the CLI reference or run
gumptionchain --help.
GumptionChain is run by a permissioned network of nodes. To have locally milled blocks or submitted transactions propagate to the official chain, a node needs miller or transactor role access to a node in the network.
API access is granted by a node's operator. Once your signing-key address is on
a node's role allowlist, configure that node as a peer. Replace
GCYourAddressGC with your signing-key address, peer.example.com with the
node's host, and /path/to/signing_keys with the directory containing your key
(PEM) file:
# GumptionChain Settings
GC_NODE_HOST=http://GCYourAddressGC@localhost:5000
GC_PEERS=["https://GCYourAddressGC@peer.example.com"]
GC_DEFAULT_COMMAND_HOST=https://GCYourAddressGC@peer.example.com
GC_SIGNING_KEY_DIR=/path/to/signing_keysRestart to load the new configuration. See the configuration reference for details.
With READER access, the sync command updates your
chain to the most recent peer block data:
$ gumptionchain syncLike import, sync is idempotent and only fetches blocks you don't yet have.
Reader access also allows querying data (subject totals and balances) via the
CLI.
To request access to a node in the GumptionChain network, email thomas@gumption.com with the role you'd like (reader, transactor, or miller) and how you intend to use it (e.g. research, business, non-profit, hobby).
GumptionChain is released under the MIT License.