{"id":26233681,"url":"https://github.com/docknetwork/verifiable-claims-engine","last_synced_at":"2025-10-08T10:02:06.215Z","repository":{"id":104958030,"uuid":"212443879","full_name":"docknetwork/verifiable-claims-engine","owner":"docknetwork","description":"Python reference implementation of a verifiable claims issuing engine.","archived":false,"fork":false,"pushed_at":"2023-05-01T20:18:59.000Z","size":1237,"stargazers_count":5,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T15:01:40.178Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/docknetwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-02T21:22:41.000Z","updated_at":"2025-02-06T15:09:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"433ad68e-e506-4b1e-9dee-b033695e4a69","html_url":"https://github.com/docknetwork/verifiable-claims-engine","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docknetwork%2Fverifiable-claims-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docknetwork%2Fverifiable-claims-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docknetwork%2Fverifiable-claims-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docknetwork%2Fverifiable-claims-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/docknetwork","download_url":"https://codeload.github.com/docknetwork/verifiable-claims-engine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250237832,"owners_count":21397401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-13T01:17:04.836Z","updated_at":"2025-10-08T10:02:06.114Z","avatar_url":"https://github.com/docknetwork.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Verifiable Claims Engine\n![](https://github.com/docknetwork/verifiable-claims-engine/workflows/pytest/badge.svg)\n\nPython reference implementation of a verifiable claims issuing engine.\n\n## Motivation\n\nCredentials are a part of our daily lives: from driver's licenses used to assert that we are capable of operating a vehicle, to university degrees used to assert our level of education. This repo provides a Rest API to issue digital verifiable claims or credentials in a way that is cryptographically secure, privacy respecting, and machine-verifiable.\n\nAdditionally, this application contains modules for bidding and cost calculation, which are essential capabilities of a full *issuing node* in the [Dock Network](http://dock.io).\n\nAlthough much of the issuing-related code was initially forked off the original `cert-tools` and `cert-issuer` repos, it has been significantly modified to achieve two core improvements:\n1. In-memory issuing: the original code relies heavily on filesystem usage for intermediate files, which causes race conditions and concurrency issues.\n1. Trustless anchoring: the anchoring process no longer needs to go through a third party API, you can now use your own Ethereum node for increased security.\n\nAdditionally, the code has been composed into a dockerized, easy to use and well-tested application which exposes an endpoint that summarizes all the different steps needed across different repos in order to perform standards-compliant verifiable claims issuing.\n\n## Module-specific Readmes\n\n- [Claims issuing](blockcerts/README.md)\n- [Cost](cost/README.md)\n- [Bidding](bidding/README.md)\n\n## Development info\n\nThis is a [flask](https://flask.palletsprojects.com/en/1.1.x/)-based REST API that has been [Docker](https://www.docker.com/)ized for easier development work and deployments.\n\nAnchoring to Ethereum (the only fully-tested blockchain option for anchoring) is done using [web3py](https://web3py.readthedocs.io/en/stable/).\n\n\n### Build image\nBefore you can try this code out you will want to *build* a docker image with it, you can achieve that by running:\n```bash\ndocker build -t verifiable-claims-engine --build-arg DEV=1 .\n```\nThis process will take a few minutes depending on various factors like your internet connection's download speed.\n\n### Run tests\nOnce the image has been built you may want to run the unittests to make sure everything is working properly. To do that from outside the container you can run the following command:\n```bash\ndocker run -it --rm --name verifiable-claims-engine  --mount type=bind,source=$(pwd),target=/app verifiable-claims-engine pytest tests\n```\n\n### Bash inside container\nHaving a built image you may also want to run a container with that image and then access bash inside it. That's easily achieved by running:\n```bash\ndocker run -it --rm --name verifiable-claims-engine  --mount type=bind,source=$(pwd),target=/app verifiable-claims-engine bash\n```\nOnce inside the running container you can execute unittests with `pytest tests`, edit the environment or spawn a python cli for example; all in a linux box setup and configured the way a full issuing node would be.\n\n\n#### Instantiate app in python cli\nDuring your development work, you may need to try things out inside a running application. To do that first bash into the container and then execute `python`. Once inside the python CLI you can run:\n```python\nimport os\nfrom flaskapp.app import create_app\napp = create_app(config_data=os.environ)\n```\nwhich gives you a running application (in `app`) so you can access all the methods and data structures that the full running application has access to.\n\n\n## Run the Verifiable Claims Engine\nIf you want to try issuing verifiable claims directly, you first need to run the container and the `verifiable-claims-engine` application exposing a port from the container to the outside world. \n\nIn the following example command we're doing just that, and exposing the container's port 80 as port 8080\n```bash\ndocker run -it --rm --name verifiable-claims-engine --mount type=bind,source=$(pwd),target=/app -p 8080:80 verifiable-claims-engine\n```\nTo verify the application is running try doing a GET request to the address http://127.0.0.1:8080/ping .\n\n## Issue your own verifiable claims!\nOnce you have your `verifiable-claims-engine` application running in a local container over at http://127.0.0.1:8080 issuing can be achieved by doing a POST call to http://127.0.0.1:8080/issue. \n\nAs you may have guessed, the information contained in the payload you submit to this endpoint will be used as the basis to manufacture the final verifiable claims, so let's examine its structure.\n\n### Issuing payload structure\n\nThe `/issue` endpoint expects a JSON payload (so remember setting the `Content-Type: application/json` header). The payload should be a JSON object (python dict) with the following structure (all keys are **required**):\n```\n{\n\t\"issuer\":{},\n\t\"template\":{},\n\t\"recipients\":[]\n}\n```\n\n#### Issuer\nThe `issuer` key contains a JSON object with information about the issuing organization or authority claiming something about each of the given recipients or *subjects*. Here's a list of the accepted keys:\n- name\n- main_url\n- id\n- email\n- logo_file\n- revocation_list\n- intro_url\n- signature_lines\n- signature_file\n\nFor more info please visit the [specs](https://www.imsglobal.org/sites/default/files/Badges/OBv2p0Final/index.html).\n\n#### Template\nThe `template` key contains a JSON object with info about the assertion or *claim* being made by the *issuer* about each recipient or *subject*. It may contain the following keys:\n- id\n- title\n- description\n- criteria_narrative\n- image\n- additional_global_fields\n- additional_per_recipient_fields\n- display_html\n- blockchain\n- gas_price\n- gas_limit\n\nFor more info please visit the [specs](https://www.imsglobal.org/sites/default/files/Badges/OBv2p0Final/index.html).\n\n\n#### Recipients\nThe `recipients` key contains an array of JSON objects, each with info about specific recipient or *subject* of the *claim* made by the *issuer*. Each recipient object may contain the following keys:\n- name\n- identity\n- pubkey\n- additional_fields\n\nFor more info please visit the [specs](https://www.imsglobal.org/sites/default/files/Badges/OBv2p0Final/index.html).\n\n### Issuing payload sample\nThe following is a sample curl call to the `/issue` endpoint that should result in fully standards compliant verifiable claims (please note that strings representing base64-encoded images or html code have been truncated to improve readability):\n```bash\ncurl -X POST \\\n  http://127.0.0.1:8080/issue \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n  \"issuer\":{\n        \"name\": \"Verifiable\",\n        \"main_url\": \"https://verifiable.com\",\n        \"id\": \"https://gist.githubusercontent.com/faustow/98db76b26b4d297d0eb98d499e733f77/raw/30610aa20c28297e0c5c82490676bf9b354877c6/newissuer.json\",\n        \"email\": \"hello@verifiable.com\",\n        \"logo_file\": \"data:image/png;base64,iVBORw0...\",\n        \"revocation_list\": \"https://gist.githubusercontent.com/faustow/07a66855d713409067ff28e10778e2dd/raw/e08bb6d6f1350367d3f6d4f805ab3b1466b584d7/revocation-list-testnet.json\",\n        \"intro_url\": \"https://verifiable.com\",\n        \"signature_lines\": [\n            {\n                \"job_title\": \"University Issuer\",\n                \"signature_image\": \"data:image/png;base64,iVBORw0...\",\n                \"name\": \"Your signature\"\n            }\n        ],\n        \"signature_file\": \"data:image/png;base64,iVBORw0...\"\n    },\n  \"template\":{\n        \"id\": \"123Y-UI12-3YUI\",\n        \"title\": \"Nuclear Powerplant Operator\",\n        \"description\": \"Operators know how to run the plant.\",\n        \"criteria_narrative\": \"Candidates are tested on...\",\n        \"image\": \"data:image/png;base64,iVBORw....\",\n        \"additional_global_fields\": [\n            {\"path\": \"$.displayHtml\", \"value\": \"\"},\n            {\n                \"path\": \"$.@context\",\n                \"value\": [\n                    \"https://w3id.org/openbadges/v2\",\n                    \"https://w3id.org/blockcerts/v2\",\n                    {\"displayHtml\": {\"@id\": \"schema:description\"}}\n                ]\n            }\n        ],\n        \"additional_per_recipient_fields\": [{\"path\": \"$.displayHtml\", \"value\": \"*|FOO|*\", \"csv_column\": \"displayHtml\"}],\n        \"display_html\": \"\u003cdiv class=...\",\n        \"blockchain\": \"ethereum_ropsten\",\n        \"gas_price\": 20000000000,\n        \"gas_limit\": 25000\n    },\n  \"recipients\":[\n        {\n            \"name\": \"Fausto\",\n            \"identity\": \"phaws@mail.com\",\n            \"pubkey\": \"ecdsa-koblitz-pubkey:123ghj123ghj123\",\n            \"additional_fields\": {\"displayHtml\":\"\"}\n        },\n        {\n            \"name\": \"John\",\n            \"identity\": \"john@mail.com\",\n            \"pubkey\": \"ecdsa-koblitz-pubkey:123ghj123ghj123\",\n            \"additional_fields\": {\"displayHtml\":\"\"}\n        },\n        {\n            \"name\": \"Ben\",\n            \"identity\": \"ben@mail.com\",\n            \"pubkey\": \"ecdsa-koblitz-pubkey:123ghj123ghj123\",\n            \"additional_fields\": {\"displayHtml\":\"\"}\n        }\n    ]\n}'\n```\nProvided that you changed the truncated strings by valid base64-encoded images or HTML where required, this call should produce a JSON response with three standards-compliant verifiable claims. \n\nPlease note that whether these credentials pass a validation process depends heavily on the input data (for example eventual `200` for any given url). This documentation won't dive further into the verification process, for more info about that please refer to the [specs](https://www.imsglobal.org/sites/default/files/Badges/OBv2p0Final/index.html).\n\n\n***\n\n## Bugs and feature requests\n\nFor bugs and feature requests please contact [Fausto Woelflin](https://github.com/faustow) at the [Dock Foundation](http://dock.io).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocknetwork%2Fverifiable-claims-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocknetwork%2Fverifiable-claims-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocknetwork%2Fverifiable-claims-engine/lists"}