Move documentation to texinfo, add makefiles, rename Cert to Attestation (python)

This commit is contained in:
lash 2023-05-24 08:45:02 +01:00
parent d4a1df3ec9
commit 2ff7724fa6
Signed by: lash
GPG Key ID: 21D2E7BB88C2A746
18 changed files with 261 additions and 48 deletions

4
.gitignore vendored
View File

@ -1 +1,5 @@
cic.json
build/
*.egg-info
*.pyc
__pycache__

View File

@ -15,3 +15,7 @@ python:
install: python
make -C schema/json install
make -C schema/rdf install
readme:
make -C doc/texinfo readme
pandoc -f docbook -t gfm doc/texinfo/build/docbook.xml > README.md

View File

@ -1,77 +1,87 @@
# CIC schemas
# Overview
This project aims to contain sufficient tools for generation, validation and packaging of metadata describing impacts and externalities from the use of Community Inclusion Currencies (CICs).
This project aims to contain sufficient tools for generation, validation
and packaging of metadata describing impacts and externalities from the
use of Community Inclusion Currencies (CICs).
The expression of impacts and externalities will henceforth be referred to as _certifications_.
The expression of impacts and externalities will henceforth be referred
to as *attestations*.
_This is a work in process. It is in alpha state, and may radically change at any time._
**This is a work in process. It is in alpha state, and may radically
change at any time.**
## Getting started
## Using the project
To build json schemas and run tests, please install the python dependencies in `requirements.txt`:
To build json schemas and run tests, please install the python
dependencies from `requirements.txt`:
`pip install -r requirements.txt`
(You may want to use a virtual environment)
## Structure
## Project Structure
Each unit of metadata consists of two parts:
1. RDF documents the certifications of vouchers, accounts and transactions.
1. RDF documents the certifications of vouchers, accounts and
transactions.
2. A JSON metadata structure bundlinf certficiations as tradeable NFTs.
2. A JSON metadata structure bundlinf certficiations as tradeable NFTs.
NFT tooling is at the current time intended for EVM blockchains only.
# Attestations
## Certification vocaularies
## Attestation vocaularies
Four base vocabularies are used to define the certifications.
* [`foaf`](http://xmlns.com/foaf/0.1/) - well-known library used to describe human resources and relationships.
* `evm` - EVM specific resources like transactions and account addresses.
* `cic` - concepts specific to CICs, e.g. _Unit of Account_, _voucher validity_ and other parameters decribing kinds of economic activity.
* `ge` - subject Impact types and areas of interest, according to Grassroots Economics - the organization pioneering this work.
Four base vocabularies are used to define the attestations.
\* `http://xmlns.com/foaf/0.1/` - well-known library used to describe
human resources and relationships. \* `evm` - EVM specific resources
like transactions and account addresses. \* `cic` - concepts specific to
CICs, e.g. *Unit of Account*, *voucher validity* and other parameters
decribing kinds of economic activity. \* `ge` - subject impact types,
areas of interest and inter-currency relations according to Grassroots
Economics - the organization pioneering this work.
### Including other vocabularies
Authors of certifications may express impacts and externalities in vocuabularies managed by themselves or other interested parties.
Authors of attestations may express impacts and externalities in
vocuabularies managed by themselves or other interested parties.
For example, Grassroots Economics can author a certification with the fictious **We Do Good NGO** as intended recipient. When doing so, elements from the `wedogood` vocabulary is used to reference specific points of interest in terms recognized by the recipient's systems.
For example, Grassroots Economics can author a attestation with the
fictious **We Do Good NGO** as intended recipient. When doing so,
elements from the `wedogood` vocabulary is used to reference specific
points of interest in terms recognized by the systems of the recipient.
`wedogood` can furthermore be a vocabulary that systems of the fictious **We Do More Good NGO** trusts and recognizes, which in turn can improve reliability and confidence for them.
`wedogood` can furthermore be a vocabulary that systems of the fictious
**We Do More Good NGO** trusts and recognizes, which in turn can improve
reliability and confidence for them.
# EVM NFT
### Files
The JSON metadata implements the ERC721 standard, as well as parts of
the Opensea metadata standard.
Example certification files used for initial development are (`test_tx.rdf` and `test_voucher.rdf`).
It also contains immutable references to one or more certifications
which the NFT represents.
Note these schemas are not yet defined. They only exist as fictious references in the example files.
Apart from the `certifications` field, data in the JSON structure is
only intended for purposes of displaying the NFT in a user interface.
## Files
## EVM NFT
Current state of the JSON schema can be found in `dist/cic.json`. It is
composed by the `build.py` script from `*.in.json`.
The JSON metadata implements the **ERC721** standard, as well as parts of the **Opensea** metadata standard.
`test_valid.json` is a single example data file used to test the JSON
schema. `make test` builds the schema and runs the corresponding tests.
It also contains immutable references to one or more certifications which the NFT represents.
## The attribute property
Apart from the `certifications` field, data in the JSON structure is only intended for purposes of displaying the NFT in a user interface.
The `attributes` property may contain one or more values that represents
parameters within certifications. However, it does not represent the
autoritative data.
### Files
Current state of the JSON schema can be found in `dist/cic.json`. It is composed by the `build.py` script from `*.in.json`.
`test_valid.json` is a single example data file used to test the JSON schema. `make test` builds the schema and runs the
### The attribute property
The `attributes` property may contain one or more values that represents parameters within certifications. However, it does not represent the autoritative data.
Care must be taken to make sure the display parameters does not conflict with the data defined in the certification itself.
Care must be taken to make sure the display parameters does not conflict
with the data defined in the certification itself.

4
doc/texinfo/Makefile Normal file
View File

@ -0,0 +1,4 @@
doc:
makeinfo --html -o build index.texi
readme:
makeinfo --docbook -o build/docbook.xml index.texi

View File

@ -0,0 +1,20 @@
@node attestations
@chapter Attestations
@section Attestation vocaularies
Four base vocabularies are used to define the attestations.
* @code{@url{foaf, http://xmlns.com/foaf/0.1/}} - well-known library used to describe human resources and relationships.
* @code{evm} - EVM specific resources like transactions and account addresses.
* @code{cic} - concepts specific to CICs, e.g. @emph{Unit of Account}, @emph{voucher validity} and other parameters decribing kinds of economic activity.
* @code{ge} - subject impact types, areas of interest and inter-currency relations according to Grassroots Economics - the organization pioneering this work.
@subsection Including other vocabularies
Authors of attestations may express impacts and externalities in vocuabularies managed by themselves or other interested parties.
For example, Grassroots Economics can author a attestation with the fictious @strong{We Do Good NGO} as intended recipient. When doing so, elements from the @code{wedogood} vocabulary is used to reference specific points of interest in terms recognized by the systems of the recipient.
@code{wedogood} can furthermore be a vocabulary that systems of the fictious @strong{We Do More Good NGO} trusts and recognizes, which in turn can improve reliability and confidence for them.

28
doc/texinfo/index.texi Normal file
View File

@ -0,0 +1,28 @@
\input texinfo
@settitle CIC Schema
@copying
Documentation released 2023 under Creative Commons Attribution-Sharealike 4.0 (CC BY-SA 4.0)
@end copying
@titlepage
@title CIC Schema
@author Louis Holbrook
@end titlepage
@c
@contents
@ifnottex
@node Top
@top Introduction
@end ifnottex
@menu
* overview ::
* instructions :
@end menu
@include overview.texi
@include attestations.texi
@include nft.texi

View File

@ -0,0 +1,9 @@
In the context of CIC, The URI of NFT contract metadata will always be expressed in terms of a content-addressed string.
The string may point to a specific location in the web, or may point to the content address itself, for which the location must be determined by the caller.
The difference between the three methods can be illustrated by two examples:
@itemize
@item
tokenURI(foo) ->

22
doc/texinfo/nft.texi Normal file
View File

@ -0,0 +1,22 @@
@node nft
@chapter EVM NFT
The JSON metadata implements the @dfn{ERC721} standard, as well as parts of the @dfn{Opensea} metadata standard.
It also contains immutable references to one or more certifications which the NFT represents.
Apart from the @code{certifications} field, data in the JSON structure is only intended for purposes of displaying the NFT in a user interface.
@section Files
Current state of the JSON schema can be found in @file{dist/cic.json}. It is composed by the @file{build.py} script from @file{*.in.json}.
@file{test_valid.json} is a single example data file used to test the JSON schema. @code{make test} builds the schema and runs the corresponding tests.
@section The attribute property
The @code{attributes} property may contain one or more values that represents parameters within certifications. However, it does not represent the autoritative data.
Care must be taken to make sure the display parameters does not conflict with the data defined in the certification itself.

29
doc/texinfo/overview.texi Normal file
View File

@ -0,0 +1,29 @@
@node overview
@chapter Overview
This project aims to contain sufficient tools for generation, validation and packaging of metadata describing impacts and externalities from the use of Community Inclusion Currencies (CICs).
The expression of impacts and externalities will henceforth be referred to as @emph{attestations}.
@strong{This is a work in process. It is in alpha state, and may radically change at any time.}
@section Getting started
To build json schemas and run tests, please install the python dependencies from @file{requirements.txt}:
@code{pip install -r requirements.txt}
(You may want to use a virtual environment)
@section Project Structure
Each unit of metadata consists of two parts:
@enumerate
@item RDF documents the certifications of vouchers, accounts and transactions.
@item A JSON metadata structure bundlinf certficiations as tradeable NFTs.
@end enumerate
NFT tooling is at the current time intended for EVM blockchains only.

View File

@ -1,3 +1,6 @@
.PHONY: all
all:
python setup.py sdist
test:
bash run_tests.sh

View File

@ -1 +1 @@
from .cert import Cert
from .cert import Attestation

View File

@ -13,7 +13,7 @@ class CIC(enum.Enum):
voucherTransfer = URIRef('https://defalsify.org/rdf-eth/0.1/voucherTransfer')
class Cert:
class Attestation:
def __init__(self):
self.g = Graph()

View File

@ -0,0 +1,2 @@
class InvalidCertificationError(Exception):
pass

64
python/cic_schema/nft.py Normal file
View File

@ -0,0 +1,64 @@
# standard imports
import os
import json
from urllib.request import urlopen
#import binascii.error
# external imports
from jsonschema import validate as json_validate
# local imports
from .error import InvalidCertificationError
script_dir = os.path.realpath(os.path.dirname(__file__))
data_dir = os.path.join(script_dir, 'data')
__f = open(os.path.join(data_dir, 'cic.json'), 'r')
schema = __f.read()
__f.close()
class NFT:
def __init__(self):
self.name = None
self.description = None
self.image = None
self.attachments = []
self.attributes = {}
self.certifications = []
@classmethod
def from_path(cls, path):
f = open(path, 'r')
o = json.load(f)
f.close()
json_validate(schema, o)
c = cls()
c.name = o['name']
c.description = o['description']
c.image = o['image']
c.attributes = o['attributes']
c.attachments = o['attachments']
c.certifications = o['certifications']
def __decode_certification(self):
for v in self.certiciations:
try:
r = self.__try_data_uri(v)
except:
pass
def __try_data_uri(self, data):
r = None
try:
r = urllib.request.urlopen(data)
#except binascii.error:
# raise InvalidCertificationError()
except Exception:
raise InvalidCertificationError()
#return None
return r

14
python/run_tests.sh Normal file
View File

@ -0,0 +1,14 @@
#!/bin/bash
set -a
set -e
set -x
default_pythonpath=$PYTHONPATH:.
export PYTHONPATH=${default_pythonpath:-.}
>&2 echo using pythonpath $PYTHONPATH
for f in `ls tests/*.py`; do
python $f
done
set +x
set +e
set +a

View File

@ -9,7 +9,7 @@ from rdflib import Graph
#from hypothesis import given, strategies
# local imports
from cic_schema import Cert
from cic_schema import Attestation
test_dir = os.path.realpath(os.path.dirname(__file__))
testdata_dir = os.path.join(test_dir, 'testdata')
@ -20,9 +20,9 @@ class TestNft(unittest.TestCase):
def setUp(self):
#fp = os.path.join(testdata_dir, 'test_voucher.rdf')
#self.graph_voucher = Cert.from_path(fp)
#self.graph_voucher = Attestation.from_path(fp)
fp = os.path.join(testdata_dir, 'test_tx2.rdf')
self.graph_tx = Cert.from_path(fp)
self.graph_tx = Attestation.from_path(fp)
def test_simplest(self):