CCD Explorer Fundamentals
This repository hosts the shared code used by many of the other repositories in the CCD Explorer Universe. The only way I knew how to make this work (locally and in Docker containers), is by publishing this repo as a Python package.
Most important modules in the repo are:
- GRPCClient: this is the partial Python SDK that contains all relevant GRPC types and methods to request information from the GRPC endpoint from a node.
- MongoDB: this module contains the connection to the MongoDB instance (or replicaset). See the Mongo Type Docs for more information.
- Tooter: this module is a light wrapper around Apprise, used to send notifications.
- CIS: this module contains logic to decode CIS-2 events according to the CIS-2 Specifications. This module is used in token accounting. See the CIS Type Docs for more information.
Modules
GRPCClient
This module is implemented as a partial Python SDK for the GRPC endpoint for a node. As such, it needs to be updated regularly whenever new types and methods are added to the GRPC Protocol Documentation. It relies heavily on BetterProto, however only version 2.0.0b6 seems to work. Hence, run
pip install "betterproto[compiler]"==2.0.0b6
to install this version.
BetterProto takes the .proto files from the Concordium GRPC Api Repo and converts this into the neccesary classes. When an update is performed on the Concordium GRPC Api Repo, copy the new files to the same location and run the following command:
python -m grpc_tools.protoc -I. --python_out=. --pyi_out=. --grpc_python_out=. --python_betterproto_out=. service.proto
This will generate the new _pb2.py(i) files.
CCD_Types
When I started with this project, I didn't know the first thing about Protobuf. To be honest, I still don't, but I have found a way to manage this by creating my own classes, mirroring the classes as generated by the types.proto file . These classes are stored in a submodule called CCD_Types. This contains 165 classes and 55 type aliases. See the GRPC Type Docs for more information.
Queries
The services in the service.proto file are mirrored in the queries submodule, where all relevant GRPC calls are built. These are the methods that other services call to retrieve specific information from the node.
For every call to the node, it calls grpc.channel_ready_future to check if the service is ready (the node is able to respond to queries). Is this somehow fails, the module tries to connect to a different node (as supplied in the ENV variables).
Getting Started
Almost none of the modules in this repo as useful as a standalone package, with the exception of the GRPC SDK.
ENV variables
NOTIFIER_API_TOKEN (API token for notifier bot)
API_TOKEN (API token for actual bot)
FASTMAIL_TOKEN (I use Fastmail to send email, leave blank, won't send email)
MONGO_URI (MongoDB URI)
ADMIN_CHAT_ID (Telegram admin chat ID)
MAILTO_LINK (I use Fastmail to send email, leave blank, won't send email)
MAILTO_USER (I use Fastmail to send email, leave blank, won't send email)
GRPC_MAINNET (A list of dicts with GPRC hosts) (Example: [{"host": "localhost", "port": 20000}, {"host": "my.validator.com", "port": 20000}])
GRPC_TESTNET (Same as GPRC_MAINNET)
Tests
The CIS module and GRPC module have associated tests.
Authors
- explorer.ccd - Everything
License
This project is licensed under the Apache 2.0 License - see the LICENSE.md file for details.
1 maintainer
Metadata
1 maintainer
Release files for ccdexplorer-fundamentals 0.3.20
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ccdexplorer_fundamentals-0.3.20.tar.gz | 194.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ccdexplorer_fundamentals-0.3.20-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 436.4 kB
Release files / ccdexplorer_fundamentals-0.3.20.tar.gz
| Download URL | ccdexplorer_fundamentals-0.3.20.tar.gz |
|---|---|
| Size | 194.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
91121aa182a8f528485438c6c5addb7bc5c8fb2278d6cb18e038d3a119886dec
|
|
BLAKE2b-256 checksum How to use checksums |
f49bf0f5e3c9512d3bab46387ad2281e6596339958a2ed72faf40224f2c4d32b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2025.
Transparency logRelease files / ccdexplorer_fundamentals-0.3.20-py3-none-any.whl
| Download URL | ccdexplorer_fundamentals-0.3.20-py3-none-any.whl |
|---|---|
| Size | 242.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
56cd703fe6bb3139d1be6fc42c028db2239c7ac882efb394c6ec4116b1d3a857
|
|
BLAKE2b-256 checksum How to use checksums |
603ae53529fc7e77c83b582eb119c21960b3b490b9111f2d63e63eaf04b8db71
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2025.
Transparency log
