Ανάπτυξη Προγραμμάτων

Αυτός ο οδηγός προϋποθέτει γνώση των ακόλουθων θεμάτων:

Loader-v3 και Loader-v4

Επί του παρόντος βρίσκεται σε εξέλιξη μια μετάβαση από το loader-v3 (εντολή program) στο loader-v4 (εντολή program -v4) καθώς το loader-v3 καταργείται.

Για νέες αναπτύξεις παρακαλούμε χρησιμοποιήστε το solana program-v4 deploy αντί για το solana program deploy.

Για να μεταφέρετε ένα υπάρχον πρόγραμμα (που ουσιαστικά είναι επανανάπτυξή του):

solana program migrate ./target/deploy/your_program-keypair.json

Προετοιμασία

Πρώτα, το πρόγραμμα πρέπει να δημιουργηθεί (μεταγλωττιστεί, συνδεθεί, απογυμνωθεί).

cargo +solana build --target sbpf-solana-solana --release

Αυτό το βήμα πρέπει να εκτελείται πριν από κάθε επανανάπτυξη/ανάπτυξη.

Ελέγξτε ότι υπάρχουν επαρκή κεφάλαια διαθέσιμα στον προεπιλεγμένο λογαριασμό πληρωμών ανάλογα με το μέγεθος του εκτελέσιμου:

du -h ./target/deploy/your_program.so
solana balance

Επιπλέον, κάθε πρόγραμμα έχει έναν λογαριασμό προγράμματος και ένα αναγνωριστικό προγράμματος, που είναι η διεύθυνση αυτού του λογαριασμού προγράμματος. Το ακόλουθο δημιουργεί ένα keypair για τον λογαριασμό προγράμματος:

solana-keygen new -o ./target/deploy/your_program-keypair.json

Αυτό πρέπει να εκτελείται μόνο μία φορά ανά πρόγραμμα και θα επαναχρησιμοποιηθεί για επανατοποθετήσεις του ίδιου προγράμματος αργότερα.

Η αλυσίδα εργαλείων περιείχε μια συντόμευση, ωστόσο αυτή καταργείται / απαξιώνεται:

cargo-build-sbf

Αρχική Ανάπτυξη

Τώρα το εκτελέσιμο μπορεί να μεταφορτωθεί στον λογαριασμό προγράμματος:

Loader-v3

Η παράμετρος ονομάζεται program-id παρόλο που αναμένει τη διαδρομή αρχείου ενός keypair:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Loader-v4

solana program-v4 deploy ./target/deploy/your_program.so --program-keypair ./target/deploy/your_program-keypair.json

Επανανάπτυξη

Η μεταφόρτωση ενός διαφορετικού εκτελέσιμου στον ίδιο λογαριασμό προγράμματος θα αντικαταστήσει το υπάρχον. Ωστόσο, για επανανάπτυξη, απαιτείται μόνο το αναγνωριστικό του προγράμματος (pubkey του keypair του προγράμματος), όχι ολόκληρο το keypair, επειδή ο υπογράφων είναι το keypair της αρχής αναβάθμισης.

Loader-v3

Αυτό είναι ακριβώς το ίδιο με την αρχική ανάπτυξη:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Εάν το παλιό εκτελέσιμο ήταν μικρότερο από το νέο, ίσως χρειαστεί πρώτα να αυξηθεί ο λογαριασμός programdata:

solana program extend ./target/deploy/your_program.so <ADDITIONAL_BYTES>

Loader-v4

Παρατηρήστε ότι η αρχική ανάπτυξη χρησιμοποίησε program-keypair, ενώ η επανανάπτυξη χρησιμοποιεί program-id αντί για αυτό:

solana program-v4 deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Προτεραιοποίηση μιας μεταφόρτωσης

Σε περιόδους συμφόρησης, υπάρχουν μερικές επιπλέον παράμετροι που μπορείτε να χρησιμοποιήσετε για να βοηθήσετε στην ανάπτυξη του προγράμματος:

--with-compute-unit-price: Ορίζει την τιμή μονάδας υπολογισμού για τη συναλλαγή, σε προσαυξήσεις των 0,000001 lamports (micro-lamports) ανά μονάδα υπολογισμού. Χρησιμοποιήστε το Priority Fee API by Helius για να λάβετε μια εκτίμηση της προτεραιότητας χρέωσης που πρέπει να οριστεί.
--use-rpc: Αποστέλλει συναλλαγές εγγραφής στο διαμορφωμένο RPC αντί για validator TPUs. Αυτή η παράμετρος απαιτεί μια σταθμισμένη με stake σύνδεση RPC όπως το Helius ή το Triton. Αυτή η παράμετρος μπορεί επίσης να διαμορφωθεί ως προεπιλογή χρησιμοποιώντας: solana config set --url <RPC_URL>.
--max-sign-attempts: Μέγιστος αριθμός προσπαθειών για υπογραφή ή επανυπογραφή συναλλαγών μετά τη λήξη του blockhash. Εάν οποιεσδήποτε συναλλαγές που αποστέλλονται κατά τη διάρκεια της ανάπτυξης του προγράμματος εξακολουθούν να μην επιβεβαιώνονται μετά τη λήξη του αρχικά επιλεγμένου πρόσφατου blockhash, αυτές οι συναλλαγές θα επανυπογραφούν με ένα νέο πρόσφατο blockhash και θα αποσταλούν ξανά. Χρησιμοποιήστε αυτή τη ρύθμιση για να προσαρμόσετε τον μέγιστο αριθμό επαναλήψεων υπογραφής συναλλαγών. Κάθε blockhash ισχύει για περίπου 60 δευτερόλεπτα, που σημαίνει ότι η χρήση της προεπιλεγμένης τιμής 5 θα οδηγήσει στην αποστολή συναλλαγών για τουλάχιστον 5 λεπτά ή μέχρι να επιβεβαιωθούν όλες οι συναλλαγές, όποιο συμβεί πρώτο.

Συνέχιση μιας μεταφόρτωσης

Είναι πιθανό μια μεταφόρτωση να κολλήσει ή να διακοπεί.

Loader-v3

Εάν η ανάπτυξη του προγράμματος αποτύχει, θα υπάρχει ένας εκκρεμής ενδιάμεσος λογαριασμός buffer που περιέχει μη μηδενικό υπόλοιπο. Για να ανακτήσετε αυτό το υπόλοιπο, μπορείτε να συνεχίσετε μια αποτυχημένη ανάπτυξη παρέχοντας τον ίδιο ενδιάμεσο buffer σε μια νέα κλήση στο deploy.

Οι αποτυχίες ανάπτυξης θα εμφανίσουν ένα μήνυμα σφάλματος που καθορίζει τη φράση seed που απαιτείται για την ανάκτηση του keypair του ενδιάμεσου buffer που δημιουργήθηκε:

==================================================================================
Recover the intermediate account's ephemeral keypair file with
`solana-keygen recover` and the following 12-word seed phrase:
==================================================================================
valley flat great hockey share token excess clever benefit traffic avocado athlete
==================================================================================
To resume a deploy, pass the recovered keypair as
the [BUFFER_SIGNER] to `solana program deploy` or `solana program write-buffer'.
Or to recover the account's lamports, pass it as the
[BUFFER_ACCOUNT_ADDRESS] argument to `solana program drain`.
==================================================================================

Για να ανακτήσετε το keypair:

solana-keygen recover -o ./target/deploy/buffer-keypair.json

Όταν σας ζητηθεί, εισάγετε τη φράση seed 12 λέξεων.

Στη συνέχεια, εκδώστε μια νέα εντολή deploy και καθορίστε τον buffer:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json --buffer ./target/deploy/buffer-keypair.json

Loader-v4

Είναι δυνατό να συνεχίσετε μια μεταφόρτωση από μια συγκεκριμένη θέση byte:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json --start-offset <BYTES_UPLOADED_SO_FAR>

Οριστικοποίηση

Αυτή είναι μια μη αναστρέψιμη ενέργεια.

Ένα πρόγραμμα μπορεί να γίνει αμετάβλητο αφαιρώντας την αρχή αναβάθμισής του.

Loader-v3

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --final

Loader-v4

solana program finalize --program-id ./target/deploy/your_program-keypair.json

Αντί να αντικαθιστάτε προγράμματα, είναι επίσης δυνατό να παρέχετε στους χρήστες την επιλογή ποια έκδοση ενός προγράμματος θέλουν να χρησιμοποιήσουν, δημιουργώντας μια συνδεδεμένη λίστα οριστικοποιημένων προγραμμάτων:

solana program finalize --program-id ./target/deploy/your_program-keypair.json --next-version ../your_newer_program/target/deploy/your_newer_program-keypair.json

Κλείσιμο

Για προγράμματα που αναπτύχθηκαν με το loader-v3, μόνο ο λογαριασμός programdata, οι λογαριασμοί buffer και τα κεφάλαια που είναι κλειδωμένα σε αυτούς μπορούν να ανακτηθούν. Ο λογαριασμός του προγράμματος μαζί με το αναγνωριστικό προγράμματος και τα κεφάλαια που είναι κλειδωμένα συγκεκριμένα στον λογαριασμό του προγράμματος παραμένουν δεσμευμένα.

Τα προγράμματα που αναπτύσσονται με το loader-v4 μπορούν να κλείσουν μαζί με τον λογαριασμό του προγράμματός τους, το αναγνωριστικό του προγράμματός τους και τα δεσμευμένα κεφάλαιά τους, τα οποία θα είναι και πάλι διαθέσιμα για άλλες χρήσεις.

Loader-v3

Αυτή είναι μια μη αναστρέψιμη ενέργεια για προγράμματα που αναπτύσσονται με το loader-v3.

Σημειώστε ότι μόλις κλείσει ένα πρόγραμμα, το αναγνωριστικό του προγράμματος δεν μπορεί να επαναχρησιμοποιηθεί. Η προσπάθεια ανάπτυξης ενός προγράμματος με ένα προηγουμένως κλεισμένο αναγνωριστικό προγράμματος θα οδηγήσει σε σφάλμα. Εάν χρειάζεται να επαναναπτύξετε ένα πρόγραμμα μετά το κλείσιμό του, πρέπει να δημιουργήσετε ένα νέο αρχείο keypair προγράμματος.

Για να κλείσετε έναν μεμονωμένο λογαριασμό programdata:

solana program close ./target/deploy/your_program-keypair.json

Για να κλείσετε όλους τους λογαριασμούς buffer που σχετίζονται με την τρέχουσα αρχή:

solana program close --buffers

Loader-v4

solana program-v4 close --program-id ./target/deploy/your_program-keypair.json

Επιθεώρηση μεταδεδομένων

Η υποεντολή show παραθέτει τα μεταδεδομένα ενός προγράμματος.

Ένα παράδειγμα εξόδου μοιάζει με:

Program Id: 3KS2k14CmtnuVv2fvYcvdrNgC94Y11WETBpMUGgXyWZL
Owner: BPFLoaderUpgradeab1e11111111111111111111111
ProgramData Address: EHsACWBhgmw8iq5dmUZzTA1esRqcTognhKNHUkPi4q4g
Authority: FwoGJNUaJN2zfVEex9BB11Dqb3NJKy3e9oY3KTh9XzCU
Last Deployed In Slot: 63890568
Data Length: 5216 (0x1460) bytes

Το Program Id είναι η διεύθυνση που μπορεί να αναφερθεί στο πεδίο program_id μιας εντολής κατά την επίκληση ενός προγράμματος.
Owner: Ο φορτωτής με τον οποίο αναπτύχθηκε αυτό το πρόγραμμα.
Το ProgramData Address είναι ο λογαριασμός programdata που σχετίζεται με τον λογαριασμό του προγράμματος που περιέχει το εκτελέσιμο του προγράμματος (μόνο για loader-v3).
Status: retracted, deployed ή finalized (μόνο για loader-v4).
Το Authority είναι η αρχή αναβάθμισης του προγράμματος.
Το Last Deployed In Slot είναι το slot στο οποίο αναπτύχθηκε τελευταία φορά το πρόγραμμα.
Το Data Length είναι το μέγεθος του χώρου που έχει δεσμευτεί για αναπτύξεις. Ο πραγματικός χώρος που χρησιμοποιείται από το τρέχον αναπτυγμένο πρόγραμμα μπορεί να είναι μικρότερος.

Loader-v3

Για να δείτε ένα συγκεκριμένο πρόγραμμα:

solana program show ./target/deploy/your_program-keypair.json

Για να δείτε τη λίστα των προγραμμάτων που αναπτύχθηκαν με την προεπιλεγμένη αρχή:

solana program show --programs

Για να εμφανίσετε όλους τους λογαριασμούς buffer ανεξάρτητα από την αρχή:

solana program show --buffers --all

Για να καθορίσετε μια διαφορετική αρχή:

solana program show --programs --buffer-authority ~/.config/solana/authority-keypair.json
solana program show --buffers --buffer-authority ~/.config/solana/authority-keypair.json

Loader-v4

Για να δείτε ένα συγκεκριμένο πρόγραμμα:

solana program-v4 show --program-id ./target/deploy/your_program-keypair.json

Για να δείτε τη λίστα των προγραμμάτων που έχουν αναπτυχθεί με την προεπιλεγμένη αρχή:

solana program-v4 show --all

Για να δείτε τη λίστα των προγραμμάτων που έχουν αναπτυχθεί με μια συγκεκριμένη αρχή:

solana program-v4 show --authority ~/.config/solana/authority-keypair.json

Λήψη του εκτελέσιμου αρχείου

Μερικές φορές είναι χρήσιμο να κατεβάσετε και να συγκρίνετε ένα πρόγραμμα για να βεβαιωθείτε ότι περιέχει ένα γνωστό εκτελέσιμο. Το αρχείο που κατεβάσατε μπορεί να περικοπεί, να κατακερματιστεί και να συγκριθεί με τον κατακερματισμό του αρχικού αρχείου προγράμματος.

Loader-v3

solana program dump ./target/deploy/your_program-keypair.json ./target/deploy/your_program.so

Loader-v4

solana program download ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Για προχωρημένους: Μεταφορά αρχής

Το δικαίωμα αλλαγής ενός συγκεκριμένου προγράμματος ανήκει στην αρχή του. Αυτή η αρχή μπορεί να μεταφερθεί σε άλλο keypair χωρίς να αλλάξει το keypair του προγράμματος, έτσι ώστε το αναγνωριστικό του προγράμματος να παραμείνει το ίδιο. Επιπλέον, μια μόνο αρχή μπορεί να ελέγχει πολλαπλούς λογαριασμούς προγραμμάτων.

Εάν δεν καθοριστεί ρητά κατά την αρχική ανάπτυξη, τότε χρησιμοποιείται το προεπιλεγμένο keypair ως αρχή. Αυτός είναι ο λόγος που η επανατοποθέτηση ενός προγράμματος στα παραπάνω βήματα δεν απαιτούσε να καθοριστεί ρητά μια αρχή.

Μια ρητή αρχή είναι χρήσιμη για υπογραφή εκτός σύνδεσης και προγράμματα που διέπονται από πολλαπλές οντότητες.

Πρώτα, πρέπει να δημιουργηθεί ένα keypair για την αρχή:

solana-keygen new -o ~/.config/solana/authority-keypair.json

Loader-v3

Η αρχή μπορεί να καθοριστεί κατά την ανάπτυξη:

solana program deploy ./target/deploy/your_program.so --upgrade-authority ~/.config/solana/authority-keypair.json

Ή μετά την ανάπτυξη και χρησιμοποιώντας το προεπιλεγμένο keypair ως την τρέχουσα αρχή:

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --new-upgrade-authority ~/.config/solana/authority-keypair.json

Ή μετά την ανάπτυξη και καθορίζοντας την τρέχουσα αρχή:

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --upgrade-authority ~/.config/solana/authority-keypair.json --new-upgrade-authority ~/.config/solana/new_authority-keypair.json

Loader-v4

Η αρχή μπορεί να καθοριστεί κατά τη διάρκεια της ανάπτυξης:

solana program-v4 deploy ./target/deploy/your_program.so --program-keypair ./target/deploy/your_program-keypair.json --authority ~/.config/solana/authority-keypair.json

Ή μετά την ανάπτυξη και χρησιμοποιώντας το προεπιλεγμένο keypair ως την τρέχουσα αρχή:

solana program-v4 transfer-authority --program-id ./target/deploy/your_program-keypair.json --new-authority ~/.config/solana/authority-keypair.json

Ή μετά την ανάπτυξη και καθορίζοντας την τρέχουσα αρχή:

solana program-v4 transfer-authority --program-id ./target/deploy/your_program-keypair.json --authority ~/.config/solana/authority-keypair.json --new-authority ~/.config/solana/new_authority-keypair.json

Για προχωρημένους: Επανανάπτυξη δύο βημάτων χρησιμοποιώντας Buffer

Αντί να γίνει απευθείας μεταφόρτωση στον λογαριασμό του προγράμματος, το εκτελέσιμο μπορεί να μεταφορτωθεί πρώτα σε έναν ενδιάμεσο λογαριασμό buffer και στη συνέχεια να μεταφερθεί στον λογαριασμό του προγράμματος σε ένα δεύτερο βήμα (η πραγματική επανανάπτυξη/ανάπτυξη). Αυτό είναι χρήσιμο για υπογραφή εκτός σύνδεσης και προγράμματα που διέπονται από πολλαπλές οντότητες, όπως μια ψηφοφορία DAO για την αποδοχή ή απόρριψη ενός μεταφορτωμένου εκτελέσιμου πριν από την πραγματική επανανάπτυξη.

Έχετε υπόψη ότι η χρήση λογαριασμών buffer περίπου διπλασιάζει τα απαιτούμενα κεφάλαια κατά τη διαδικασία μεταφόρτωσης, επειδή δύο λογαριασμοί διατηρούν από ένα εκτελέσιμο ταυτόχρονα.

Πρώτα, πρέπει να δημιουργηθεί ένα keypair για τον λογαριασμό buffer:

solana-keygen new -o ~/.config/solana/buffer-keypair.json

Ο λογαριασμός buffer μπορεί να επαναχρησιμοποιηθεί για διαφορετικές μεταφορτώσεις και δεν δεσμεύεται σε κανέναν συγκεκριμένο λογαριασμό προγράμματος.

Loader-v3

solana program write-buffer ./target/deploy/your_program.so --buffer ~/.config/solana/buffer-keypair.json
solana program deploy --program-id ./target/deploy/your_program-keypair.json --buffer ~/.config/solana/buffer-keypair.json

Loader-v4

solana program-v4 deploy ./target/deploy/your_program.so --buffer ~/.config/solana/buffer-keypair.json
solana program-v4 deploy --program-id ./target/deploy/your_program-keypair.json --buffer ~/.config/solana/buffer-keypair.json

Για προχωρημένους: Υπογραφή εκτός σύνδεσης

Ορισμένα μοντέλα ασφαλείας απαιτούν το διαχωρισμό της διαδικασίας υπογραφής από τη μετάδοση της συναλλαγής, έτσι ώστε τα κλειδιά υπογραφής να μπορούν να αποσυνδεθούν εντελώς από οποιοδήποτε δίκτυο, γνωστό και ως υπογραφή εκτός σύνδεσης.

Σημειώστε ότι μόνο οι επανεγκαταστάσεις μπορούν να πραγματοποιηθούν σε λειτουργία εκτός σύνδεσης. Η αρχική ανάπτυξη του προγράμματος πρέπει να πραγματοποιηθεί από μια συσκευή σε σύνδεση, και μόνο οι επακόλουθες επανεγκαταστάσεις προγραμμάτων μπορούν να αξιοποιήσουν την υπογραφή εκτός σύνδεσης.

Μια τυπική ρύθμιση θα αποτελούνταν από δύο διαφορετικούς υπογράφοντες:

υπογράφων σε σύνδεση (πληρωτής τελών και αρχή του λογαριασμού buffer)
υπογράφων εκτός σύνδεσης (αρχή του λογαριασμού προγράμματος)

Η γενική διαδικασία είναι μια επανεγκατάσταση δύο βημάτων με κάποιες επιπλέον ενέργειες:

(online) δημιουργία νέου προγράμματος
(online) μεταφορά της εξουσιοδότησης στον offline υπογράφοντα
(online) δημιουργία buffer και μεταφόρτωση ενός εκτελέσιμου σε αυτό
(προαιρετικά) επαλήθευση των περιεχομένων του buffer στην αλυσίδα
(offline) υπογραφή συναλλαγής για επανεγκατάσταση του προγράμματος χρησιμοποιώντας το buffer --blockhash <VALUE> --sign-only
(online) χρήση αυτής της υπογραφής για μετάδοση της συναλλαγής επανεγκατάστασης --blockhash <VALUE> --signer <OFFLINE_SIGNER_PUBKEY>:<OFFLINE_SIGNER_SIGNATURE>

Αναζητήστε ένα πρόσφατο blockhash και επικολλήστε το για να δημιουργήσετε την υπογραφή της offline συναλλαγής. Το blockhash λήγει μετά από ~60 δευτερόλεπτα. Αν δεν προλάβατε εγκαίρως - απλά πάρτε ένα νέο hash και επαναλάβετε μέχρι να πετύχετε, ή εξετάστε τη χρήση durable transaction nonces.

Πίνακας Περιεχομένων