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

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

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

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

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

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

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

Ανάγνωση του διακομιστή RPC

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

Ανάγνωση του μηχανισμού επικύρωσης

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

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

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

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

Προσθήκη plugin συναλλαγών

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

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

Δοκιμές

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

cargo test -p tests --test <target>

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