Αρχιτεκτονική

Το Kora είναι ένα Rust workspace με τρία crates:

• Το kora-lib περιέχει τη βασική λογική και τον διακομιστή RPC,
• το kora-cli δημιουργεί το δυαδικό αρχείο kora που εκτελούν οι διαχειριστές, και
• το kora-deploy είναι ένα εξειδικευμένο εργαλείο ανάπτυξης προγραμμάτων, με ξεχωριστή έκδοση. Όσα αναφέρονται παρακάτω βρίσκονται στο crates/lib/src, εκτός αν αναφέρεται διαφορετικά.

Ο κύκλος ζωής του αιτήματος

Το διάγραμμα παρακάτω απεικονίζει τη γενική ροή μιας συναλλαγής μέσα από το Kora. Η κατανόηση της διαδρομής των κλήσεων είναι σημαντική για τη ρύθμιση ενός κόμβου Kora και την προσθήκη νέων λειτουργιών.

Πού βρίσκεται κάθε στάδιο

Δύο ακόμη αρχεία που πρέπει να γνωρίζετε: το config.rs ορίζει ολόκληρο το σχήμα του kora.toml, και το state.rs διατηρεί τη δεσμευμένη (deserialized) ρύθμιση σε καθολική κατάσταση της διεργασίας.

Μελέτη του διακομιστή RPC

Το rpc.rs είναι ένα λεπτό επίπεδο δρομολόγησης, με μία μέθοδο ανά endpoint JSON-RPC, και ο γρηγορότερος τρόπος για να δείτε ολόκληρο το API. Η λογική κάθε μεθόδου βρίσκεται στο δικό της αρχείο στον φάκελο rpc_server/method/. Διαβάστε το sign_transaction.rs από την αρχή ως το τέλος· οι υπόλοιπες μέθοδοι υπογραφής αποτελούν παραλλαγές του.

Μελέτη του validator

Τα transaction_validator.rs και transaction/instruction_util.rs περιέχουν τη λογική για την επικύρωση συναλλαγών και εντολών. Επιπλέον, περιλαμβάνονται τα property tests ασφαλείας της fee-payer-policy, τα οποία βρίσκονται σε ένα αρχείο ανά προστατευμένο πρόγραμμα στον φάκελο validator/transaction_validator/fee_payer_policy_props/.

Συμβάσεις που αξίζει να γνωρίζετε

Προεπιλεγμένη επικύρωση. Κάθε σημαία (flag) κάτω από το [validation.fee_payer_policy] έχει προεπιλογή false, και τα structs της πολιτικής φέρουν το #[serde(default)]. Αυτός ο συνδυασμός είναι σκόπιμος: η προσθήκη μιας νέας εντολής υπό έλεγχο δεν πρέπει να χαλάει τη υπάρχουσα ρύθμιση ενός διαχειριστή και πρέπει να καταλήγει σε άρνηση αντί για κατά λάθος επιτρεπτή ενέργεια. Διατηρήστε και τα δύο όταν προσθέτετε μια σημαία.

Επικυρώνετε την επιλυμένη συναλλαγή, ποτέ την ακατέργαστη. Η ακατέργαστη VersionedTransaction εκθέτει μόνο στατικά κλειδιά λογαριασμών, οπότε η επικύρωση ή η τιμολόγηση μιας συναλλαγής V0 από αυτήν παραλείπει σιωπηλά τους λογαριασμούς των lookup tables και χρεώνει λιγότερο από όσο πρέπει. Η VersionedTransactionResolved::from_transaction επιλύει αυτές τις διευθύνσεις εξαρχής, γι' αυτό και κάθε επόμενο στάδιο δέχεται τον επιλυμένο τύπο.

Προσθήκη πρόσθετου συναλλαγών

Τα πρόσθετα υλοποιούν το trait TransactionPlugin στο plugin/mod.rs. Διαθέτει δύο μεθόδους: η validate εκτελείται για κάθε συναλλαγή κατά τις ροές υπογραφής και η validate_config εκτελείται μία φορά κατά την εκκίνηση και επιστρέφει σφάλματα και προειδοποιήσεις για τον διαχειριστή. Ένα PluginExecutionContext ενημερώνει το πρόσθετο ποια από τις τέσσερις μεθόδους υπογραφής το κάλεσε.

Η TransactionPluginRunner::from_config κάνει αντιστοίχιση (match) στο TransactionPluginType, που ορίζεται στο config.rs. Ένα νέο ενσωματωμένο πρόσθετο είναι μια νέα παραλλαγή (variant) εκεί, συν έναν νέο κλάδο match στο runner. Τα δύο πρόσθετα που διατίθενται σήμερα είναι τα gas_swap και deploy_authority.

Δοκιμές

Το Kora διατηρεί τη ρύθμιση σε καθολική κατάσταση της διεργασίας, γι' αυτό το tests/ δηλώνει έναν στόχο [[test]] ανά φάση, και κάθε στόχος εκκινεί το δικό του ενσωματωμένο surfnet μαζί με κόμβο Kora, με δεδομένα που ξεκινούν από το μηδέν. Μία ρύθμιση ανά δυαδικό αρχείο: μια νέα φάση χρειάζεται νέο στόχο, όχι νέο module σε υπάρχον.

cargo test -p tests --test <target>

Όλα τα υπόλοιπα συνδέονται μέσω του justfile. Διαβάστε το αντί να ανασυνθέτετε τις εντολές με το χέρι.