From 2ff7724fa6fd975ef220afb136121f5e6541a7e8 Mon Sep 17 00:00:00 2001 From: lash Date: Wed, 24 May 2023 08:45:02 +0100 Subject: [PATCH] Move documentation to texinfo, add makefiles, rename Cert to Attestation (python) --- .gitignore | 4 + Makefile | 4 + README.md | 96 ++++++++++-------- doc/texinfo/Makefile | 4 + doc/texinfo/attestations.texi | 20 ++++ doc/texinfo/index.texi | 28 +++++ doc/texinfo/location.texi | 9 ++ doc/texinfo/nft.texi | 22 ++++ doc/texinfo/overview.texi | 29 ++++++ python/Makefile | 3 + python/cic_schema/__init__.py | 2 +- .../__pycache__/__init__.cpython-310.pyc | Bin 209 -> 202 bytes .../__pycache__/cert.cpython-310.pyc | Bin 1642 -> 1670 bytes python/cic_schema/cert.py | 2 +- python/cic_schema/error.py | 2 + python/cic_schema/nft.py | 64 ++++++++++++ python/run_tests.sh | 14 +++ python/tests/test_nft.py | 6 +- 18 files changed, 261 insertions(+), 48 deletions(-) create mode 100644 doc/texinfo/Makefile create mode 100644 doc/texinfo/attestations.texi create mode 100644 doc/texinfo/index.texi create mode 100644 doc/texinfo/location.texi create mode 100644 doc/texinfo/nft.texi create mode 100644 doc/texinfo/overview.texi create mode 100644 python/cic_schema/error.py create mode 100644 python/cic_schema/nft.py create mode 100644 python/run_tests.sh diff --git a/.gitignore b/.gitignore index 1e79a01..aca5fb6 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,5 @@ cic.json +build/ +*.egg-info +*.pyc +__pycache__ diff --git a/Makefile b/Makefile index 4cf77f7..ef4cb02 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/README.md b/README.md index af76a00..d58be9d 100644 --- a/README.md +++ b/README.md @@ -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 from `requirements.txt`: -To build json schemas and run tests, please install the python dependencies in `requirements.txt`: - -`pip install -r 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. diff --git a/doc/texinfo/Makefile b/doc/texinfo/Makefile new file mode 100644 index 0000000..3eaff13 --- /dev/null +++ b/doc/texinfo/Makefile @@ -0,0 +1,4 @@ +doc: + makeinfo --html -o build index.texi +readme: + makeinfo --docbook -o build/docbook.xml index.texi diff --git a/doc/texinfo/attestations.texi b/doc/texinfo/attestations.texi new file mode 100644 index 0000000..9fe1000 --- /dev/null +++ b/doc/texinfo/attestations.texi @@ -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. diff --git a/doc/texinfo/index.texi b/doc/texinfo/index.texi new file mode 100644 index 0000000..05990f9 --- /dev/null +++ b/doc/texinfo/index.texi @@ -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 diff --git a/doc/texinfo/location.texi b/doc/texinfo/location.texi new file mode 100644 index 0000000..0a2b039 --- /dev/null +++ b/doc/texinfo/location.texi @@ -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) -> diff --git a/doc/texinfo/nft.texi b/doc/texinfo/nft.texi new file mode 100644 index 0000000..a50bd96 --- /dev/null +++ b/doc/texinfo/nft.texi @@ -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. diff --git a/doc/texinfo/overview.texi b/doc/texinfo/overview.texi new file mode 100644 index 0000000..475b0db --- /dev/null +++ b/doc/texinfo/overview.texi @@ -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. diff --git a/python/Makefile b/python/Makefile index d36928e..682c816 100644 --- a/python/Makefile +++ b/python/Makefile @@ -1,3 +1,6 @@ .PHONY: all all: + python setup.py sdist +test: + bash run_tests.sh diff --git a/python/cic_schema/__init__.py b/python/cic_schema/__init__.py index 8c2723c..726e702 100644 --- a/python/cic_schema/__init__.py +++ b/python/cic_schema/__init__.py @@ -1 +1 @@ -from .cert import Cert +from .cert import Attestation diff --git a/python/cic_schema/__pycache__/__init__.cpython-310.pyc b/python/cic_schema/__pycache__/__init__.cpython-310.pyc index 069c1ad844fae4e40f99f6c90debd58f5b61fb07..88617c1e8843d1a7466b5f0af32eeb9945900ac9 100644 GIT binary patch delta 73 zcmcb}c#4rXpO=@50SF%N&rOk=$ZKuD?O0NhT3nJ?l9`|9r^yt>lAKypQp5yQvXY^Q V8AySNU#|MaMP>TwnI#kJg8=KX6rBJ7 delta 80 zcmX@bc#)AepO=@50SLTia;At+D_B1x bKQ~oBC$Ts~zqlw_KRG|Iq$o3KVnq-D91Rvj diff --git a/python/cic_schema/__pycache__/cert.cpython-310.pyc b/python/cic_schema/__pycache__/cert.cpython-310.pyc index 14303e29cfb12a625debd50676a37805487d505c..656d7f8f54a4c447845a2fe057607f216f2a876f 100644 GIT binary patch delta 255 zcmaFG)5go2&&$ij00f`+=cc^b$h(%2(^0>;s7yaSvt;r`#+5wWjwL0j#U+U)nfZB> z>zV3!M34oTn0*+dCi^oh@Jhxbi8P6_}3 delta 231 zcmZqUeZ|9@&&$ij00ePAxKf^OfqLRrKOm(chU=|az596)L{>%z&Lh)dM8fH&cJ}~Pd^9)Ae$yqEhtU_S^B^Ga? zTg(-?IYmN1>ol2*c!AWd$@;9$tlVG)b*wrPl0dN{QIG_4ab@u>w&IeM{L+#lmC1f= x;*)Q(D(S0%k;z(YF#zt3MBM-Y diff --git a/python/cic_schema/cert.py b/python/cic_schema/cert.py index 102df74..970997c 100644 --- a/python/cic_schema/cert.py +++ b/python/cic_schema/cert.py @@ -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() diff --git a/python/cic_schema/error.py b/python/cic_schema/error.py new file mode 100644 index 0000000..a549cbf --- /dev/null +++ b/python/cic_schema/error.py @@ -0,0 +1,2 @@ +class InvalidCertificationError(Exception): + pass diff --git a/python/cic_schema/nft.py b/python/cic_schema/nft.py new file mode 100644 index 0000000..badade3 --- /dev/null +++ b/python/cic_schema/nft.py @@ -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 diff --git a/python/run_tests.sh b/python/run_tests.sh new file mode 100644 index 0000000..b8e4beb --- /dev/null +++ b/python/run_tests.sh @@ -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 diff --git a/python/tests/test_nft.py b/python/tests/test_nft.py index e3c7a38..4d1579d 100644 --- a/python/tests/test_nft.py +++ b/python/tests/test_nft.py @@ -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):