📕Αναλυτική λίστα μεθόδων & μεταβλητών (Reference)

Μία-προς-μία όλες οι μεταβλητές και λειτουργίες του συστήματος Bluechain SSI, και τεκμηρίωση.

Λίστα δομών και μεθόδων:

1. struct Passport

Αποτελεί βασική δομή αποτύπωσης ενός Διαβατηρίου, γεμάτο με έγγραφα Ταυτοποίησης, και που ανήκει/διαχειρίζεται από έναν Χρήστη. Περιέχει τις εξής μεταβλητές:

string flair_name: Ένα βοηθητικό ψευδώνυμο για το εκάστοτε Passport object. Δεν είναι απαραίτητο να συμπληρωθεί. Εν αρχή, λαμβάνει ψευδώνυμο ίδιο με το όνομα του Χρήστη.
address controller: Ο διαχειριστής του Διαβατηρίου, που έχει δικαιώματα αλλαγών πάνω του. Αποτυπώνεται ως blockchain address (διεύθυνση του Χρήστη). Εν αρχή, θέτεται να δείχνει στον αρχικό δημιουργό του Διαβατηρίου. Αν και αυτό συνήθως παραμένει έτσι κατά τη λειτουργία του Bluechain SSI, δίνουμε την δυνατότητα να παρέλθει ο έλεγχος σε άλλο Χρήστη.
mapping(bytes32 => uint) identity_files: Ένα hashmap array που περιέχει όλα τα σχετικά με το συγκεκριμένο Διαβατήριο Έγγραφα Ταυτοποίησης. Το (key, value) ζευγάρι σε κάθε θέση είναι μορφής bytes32 (32 byte string, επίτηδες έτσι ώστε να μπορεί να φιλοξενήσει SoliditySha3()output του Web3 library, keccak256 outputs, ή ακόμα και απλά sha3-256 checksums ενός εγγράφου) σε uint (unsigned integer, όπου αποθηκεύεται ως ένας απλός ακέραιος αριθμός το trust score ενός εγγράφου.

Υπενθυμίζουμε ότι η υλοποίηση της δομής αποθήκευσης εγγράφων ως hashmap με associated trust scores ακολουθεί την προτεινόμενη δομή του CALYPSO paper των Eleftherios Kokoris-Kogias et al (2020) όπως αυτό μελετήθηκε, μεταξύ άλλων προσεγγίσεων, στην πρώτη Μελέτη Χαρτογράφησης της ομάδας μας κατά το 1ο παραδοτέο του έργου. Η μελέτη μας είναι διαθέσιμη εδώ: https://blockchainehealth.page.link/study

mapping(bytes32 => bytes32) identity_files_LUT: Βοηθητικό hashmap array που δρα ως Lookup Table (LUT) stην προηγούμενη δομή identity_files. Τα hashmaps δεν επιτρέπουν αναζήτηση/iteration των keys τους, έτσι η λύση είναι να χρησιμοποιούμε δύο δομές δεδομένων, πλάι-πλάι: ένα hashmap και ένα hashmap LUT για την αναζήτηση των "γεμισμένων" ζευγαριών του πρώτου.
Οι επιπρόσθετες δομές για γρήγορη Ο(1) αναζήτηση, καθώς και οι λίστες για delegates (εκπροσώπους) παραμένουν αδρανείς προς το παρόν στην έκδοση 0.3.0, για οικονομία πόρων κατά τη χρήση του συστήματος.

2. mapping user_passports & mapping user_passports_LUT

H κύρια βάση δεδομένων Διαβατηρίων & Ταυτοτήτων των Χρηστών στο σύστημά μας. Σε αυτή τη δομή δεδομένων έγγειται η "καρδία" του έξυπνου συμβολαίου (smart contract) του Bluechain SSI. Αποθηκεύει και αντιστοιχίζει διευθύνσεις/πορτοφόλια Χρηστών σε ενεργά Διαβατήρια, που περιέχουν έγγραφα Ταυτοποίησης και Ισχυρισμών (Claims).

Τύπος: mapping (hashmap) ζευγαριών μορφής <address → struct Passport>

3. event PassportInitialized, AddedIDFileToPassport, Voted

Τα events (συμβάντα) είναι διευκολύνσεις ώστε να αφήνουν ιστορικό (logs) των πράξεών τους τα smart contracts, προς το "γενικό", non-blockchain internet. Τα πυροδοτούμε και τα στέλνουμε σε κατάλληλα σημεία στον κώδικα του συστήματος του Bluechain SSI, συνήθως ακριβώς όταν έχει ολοκληρωθεί μια λειτουργία, ώστε να σημάνουμε την επιτυχή της εκτέλεση. Έτσι, τα events που χτίζουμε και εκπέμπουμε, ανά τον κώδικα, είναι τρία (3):

event PassportInitialized, όταν αρχικοποιείται επιτυχώς ένα νέο Διαβατήριο, έπειτα από request νέου Χρήστη. Μαζί, εκπέμπουμε το αναγνωριστικό του νέου Διαβατηρίου και ποιος (ποια διεύθυνση) το ζήτησε.
event AddedIDFileToPassport, όταν προστίθεται επιτυχώς ένα Έγγραφο Ταυτοποίησης σε υπάρχον Διαβατήριο κάποιου Χρήστη. Μαζί, εκπέμπουμε το αναγνωριστικό του Διαβατηρίου όπου μόλις προστέθηκε το Έγγραφο, και το ίδιο το fingerprint του Εγγράφου.
event Voted, όταν ένας Χρήστης ψηφίζει για την αύξηση του σκορ εμπιστοσύνης (trust score) ενός Εγγράφου σε Διαβατήριο κάποιου άλλου Χρήστη. Μαζί, εκπέμπουμε το αναγνωριστικό του Διαβατηρίου στο οποίο μόλις επιδράσαμε, και ποιος (ποια διεύθυνση) έριξε την ψήφο εμπιστοσύνης.

Τύπος: event, που πυροδοτείται μέσα από τον κώδικα του έξυπνου συμβολαίου και μπορεί να ανιχνευθεί από οποιοδήποτε online πρόγραμμα που κοιτάει προς το blockchain του Bluechain SSI.

4. function hasInitializedPassport

Λειτουργία: Βοηθητική, ελέγχει αν ένας Χρήστης έχει όντως ένα ενεργό, αρχικοποιημένο Διαβατήριο.

Παράμετροι: address addr, η διεύθυνση/πορτοφόλι του Χρήστη τον οποίο ελέγχουμε.

Επιστρεπτέες τιμές: bool true ή false ανάλογα με το αν ο Χρήστης έχει ενεργό Διαβατήριο.

Τύπος: Συνάρτηση τύπου view, που σημαίνει ότι δεν απαιτεί αλλαγή του εσωτερικού αποθηκευτικού χώρου του smart contract, κι έτσι μπορεί να εκτελεστεί δωρεάν (zero gas fee).

5. function initPassport

Λειτουργία: Εκκινεί και αρχικοποιεί ένα ενεργό, κενό Διαβατήριο για έναν Χρήστη.

Παράμετροι: string memory nickname, ένα βοηθητικό ψευδώνυμο/identifier του Διαβατηρίου, για εύκολη αναζήτση και αναγνώριση από τους Χρήστες.

Επιστρεπτέες τιμές: Πλειάδα 2-διαστάσεων, tuple (string, address) όπου περιέχει το ψευδώνυμο του Διαβατηρίου που μόλις χρησιμοποιήθηκε, καθώς και την διεύθυνση/πορτοφόλι του Χρήστη που το δημιούργησε.

Τύπος: Κανονική συνάρτηση. Προκαλεί αλλαγές στον αποθηκευτικό χώρο του smart contract, κι έτσι η εκτέλεσή της φέρει κόστος (gas fee = gas_price * gas_limit).

Σημείωση: Κατά την initPassport(), ο αρχικός διαχειριστής (controller) του Διαβατηρίου θέτεται ως αυτός που το δημιούργησε. Αυτή η παραδοχή δεν είναι απαραίτητα αληθής κατά τη συνέχεια της λειτουργίας του συστήματος, αφού δίνεται η δυνατότητα σε έναν Χρήστη να αναθέσει τον έλεγχο του Διαβατηρίου του σε άλλους.

6. function addIDFileToPassport

Λειτουργία: Προσθέτει ένα νέο Έγγραφο Ταυτοποίησης σε ένα ενεργό Διαβατήριο του Χρήστη.

Παράμετροι:

address passport_id, η διεύθυνση/αναγνωριστικό του Διαβατηρίου στο οποίο θα προσθέσουμε το νέο Έγγραφο Ταυτοποίησης
bytes32 id_file, το fingerprint του Εγγράφου. Η συνάρτηση δέχεται οποιοδήποτε document digest/fingerprint των 32 byte (256 bit) — η μέθοδος που χρησιμοποίησε η Ομάδα μας και προτείνουμε, για την παραγωγή ισχυρών document fingerprints προς εισαγωγή στο Bluechain SSI, είναι ο KECCAK algorithm σε spec SHA3-256 .

Επιστρεπτέες τιμές: Πλειάδα 3-διαστάσεων, tuple (address, bytes32, uint) όπου η 1η συνιστώσα (address) είναι η διεύθυνση του Χρήστη και Διαχειριστή του Διαβατηρίου που μόλις πρόσθεσε το Έγγραφο, η 2η (bytes32) είναι το fingerprint του Εγγράφου που μόλις προστέθηκε, και η 3η (uint) είναι το trust score του νεοεισηχθέντος Εγγράφου — θα πρέπει να είναι 1!

7. function voteForDocInPassport

Λειτουργία: Εντοπίζει ένα συγκεκριμένο Έγγραφο Ταυτοποίησης στο δοθέν αναγνωριστικό Διαβατηρίου, και αυξάνει το σκορ εμπιστόσυνης (trust score) του Εγγράφου κατά +1. Εκτελείται απαραιτήτως από Χρήστη διαφορετικό του ιδιοκτήτη του Διαβατηρίου.

Παράμετροι:

address passport_id, η διεύθυνση/αναγνωριστικό του Διαβατηρίου στο οποίο θα ψάξουμε για το Έγγραφο Ταυτοποίησης.
bytes32 doc_id, το fingerprint του Εγγράφου που θα αναζητήσουμε στο προηγούμενο Διαβατήριο και του οποίου το trust score θα αυξήσουμε με +1, διά "ψήφου εμπιστοσύνης". Υπακούει στο ίδιο cryptography standard (KECCAK256) όπως και η function addIDFileToPassport.

Επιστρεπτέες τιμές: Πλειάδα 3-διαστάσεων, tuple (address, bytes32, uint) όπου η 1η συνιστώσα (address) είναι η διεύθυνση του Χρήστη που μόλις ψήφισε μέσω της συνάρτησης, η 2η (bytes32) είναι το fingerprint του Εγγράφου που μόλις ψηφίστηκε θετικά, και η 3η (uint) είναι το trust score του Εγγράφου πλέον — θα πρέπει να είναι άνω του 1!

8. function PassportExists

Λειτουργία: Βοηθητική, ελέγχει αν ένα Διαβατήριο υπάρχει (είναι ενεργό, έχει αρχικοποιηθεί) ή όχι.

Παράμετροι: address passport_id, η διεύθυνση/αναγνωριστικό του Διαβατηρίου.

Επιστρεπτέες τιμές: bool true ή false ανάλογα με το αν το Διαβατήριο υπάρχει.

9. function DocExistsInPassport

Λειτουργία: Βοηθητική, ελέγχει αν ένα Έγγραφο Ταυτοποίησης υπάρχει σε ένα ενεργό Διαβατήριο κάποιου Χρήστη.

Παράμετροι:

Passport storage p, η δομή Passport, έτοιμα δοσμένη, μέσα στην οποία θα αναζητήσουμε το Έγγραφο.
bytes32 doc_id, το fingerprint του Εγγράφου που θα αναζητήσουμε μέσα στο Διαβατήριο p. Ξανά, είναι της ίδιας μορφής (KECCAK, 256 bits) όπως και στην function addIDFileToPassport.

Επιστρεπτέες τιμές: bool true ή false ανάλογα με το αν το Έγγραφο υπάρχει μέσα στο δοθέν Διαβατήριο.

Previous⛑️ Ατομικές δοκιμές (unit tests) & επιδόσεις (performance)NextΠαράρτημα: ο κώδικας των Έξυπνων Συμβολαίων του Bluechain SSI

Last updated 2 years ago