Γλώσσα & Σύνταξη

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

Σύνταξη

Τα Runbooks περιέχουν μια σειρά από μπλοκ κώδικα που μοιάζουν κάπως έτσι:

variable "query_path" {
  description = "An input that can be edited in the web UI!"
  value = "details"
  editable = true
}

action "http_query" "std::send_http_request" {
  description = "This action will make a GET request to the specified URL!"
  url = "https://example.com/${variable.my_var.query_path}"
}

output "status_code" {
  description = "This output will be displayed in the Outputs section of the web UI!"
  value = action.http_query.status_code
}

Κάθε μπλοκ έχει έναν τύπο εντολής (σε αυτό το παράδειγμα variable, action και output), ένα όνομα αναφοράς ("query_path", "http_query" και "status_code"), και τα εσωτερικά δεδομένα του μπλοκ (όλα όσα βρίσκονται μεταξύ { ... }). Ορισμένοι τύποι εντολών απαιτούν επίσης τον καθορισμό μιας εντολής ("std::send_http_request"). Τα εσωτερικά δεδομένα του μπλοκ υπαγορεύονται από τον τύπο εντολής και την εντολή που έχουν καθοριστεί.

Αναφορές Εντολών

Μια εντολή μπορεί να αναφέρεται στις εξόδους μιας άλλης εντολής για να δημιουργήσει μια αλυσίδα εξαρτημένων εντολών. Όταν εκτελείτε ένα Runbook, το surfpool δημιουργεί ένα γράφημα όλων των εντολών για να διασφαλίσει ότι εκτελούνται πάντα με τη σωστή σειρά. Αυτό σημαίνει ότι πρέπει να αποφεύγονται κύκλοι εξαρτήσεων κατά τη δημιουργία ενός Runbook.

Η έξοδος μιας άλλης εντολής μπορεί να αναφερθεί σε ένα μπλοκ χρησιμοποιώντας command_type.ref_name.output_name. Ακολουθούν μερικά παραδείγματα:

variable "my_var" {
  description = variable.another_var.value // references the `value` output of a `variable` named `another_var`
  value = action.my_action.data // references the `data` output of an `action` named `my_action`
}

Συναρτήσεις

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

Αυτές οι συναρτήσεις μπορούν να μοιάζουν με ρητές κλήσεις συναρτήσεων (π.χ. add_uint(1, 3)), ή μπορούν να μοιάζουν με ενσωματωμένες αριθμητικές πράξεις (π.χ. 1 + 3). Οι συναρτήσεις μπορούν να αναφέρονται σε εξόδους άλλων εντολών, ή μπορούν να αποθηκευτούν σε νέες εξόδους εντολών. Ακολουθεί ένα παράδειγμα που χρησιμοποιεί μερικές συναρτήσεις:

variable "one" {
  value = 1
}
variable "two" {
  value = 2
}
variable "addem_up" {
  value = variable.one + variable.two
}
output "add_some_more" {
  value = add_uint(variable.addem_up + variable.one, variable.two)
}

Εισροές Manifest & CLI

Οι εισροές μπορούν να παρέχονται στο Runbook είτε μέσω CLI είτε ορίζοντάς τες σε ένα αρχείο manifest txtx.yml. Εάν η ίδια εισροή παρέχεται τόσο στο CLI όσο και σε ένα manifest, η εισροή του CLI θα έχει προτεραιότητα. Για πληροφορίες σχετικά με τη χρήση του CLI, δείτε την τεκμηρίωση CLI. Στο manifest, αυτές οι εισροές μπορούν να ομαδοποιηθούν με ένα κλειδί περιβάλλοντος, διευκολύνοντας τη χρήση του ίδιου Runbook σε πολλά περιβάλλοντα.

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

---
name: protocol-deployment
runbooks:
  - name: Deploy Protocol
    description: This runbook deploys the protocol.
    location: ./deployment
environments:
  development:
    network_id: localnet
    rpc_api_url: http://localhost:8899
  devnet:
    network_id: devnet
    rpc_api_url: https://api.devnet.solana.com
  mainnet:
    network_id: mainnet
    rpc_api_url: https://api.mainnet-beta.solana.com

Σε οποιοδήποτε από τα αρχεία .tx που φορτώνονται από αυτό το runbook, οι εισροές input.network_id και input.rpc_api_url θα είναι διαθέσιμες στο καθολικό πεδίο εφαρμογής. Όταν το Web UI φορτώνει αυτό το runbook, το πρώτο στοιχείο ενέργειας θα σας επιτρέψει να επιλέξετε ποιο περιβάλλον θα φορτωθεί. Η επιλογή νέου περιβάλλοντος θα επαναφορτώσει το τρέχον runbook με τις νέες μεταβλητές περιβάλλοντος να εισάγονται στην εκτέλεση.

Διαχείριση Κατάστασης

Το Surfpool μπορεί να διαχειρίζεται την κατάσταση μεταξύ εκτελέσεων Runbook. Κατά την εκτέλεση αναπτύξεων συμβολαίων, η διαχείριση κατάστασης μπορεί να χρησιμοποιηθεί για τον εντοπισμό τυχόν αλλαγών στον κώδικα του συμβολαίου και στις εισροές Runbook, προκειμένου να καθοριστεί εάν το Runbook χρειάζεται να επανεκτελεστεί. Το Surfpool θα αποτρέψει την επανεκτέλεση ενός Runbook εάν δεν υπάρχουν αλλαγές στον κώδικα του συμβολαίου ή στις εισροές Runbook.

Για να ενεργοποιήσετε τη διαχείριση κατάστασης, παρέχετε την τιμή state και ένα location για την αποθήκευση του αρχείου κατάστασης στο txtx.yml:

runbooks:
  - name: Deploy Protocol
    location: ./deployment
    state:
      location: states

Μεταβλητές

Οι μεταβλητές μπορούν να χρησιμοποιηθούν για την αποθήκευση τιμών που μπορούν να χρησιμοποιηθούν από άλλες δομές και να επεξεργαστούν από χρήστες στο Web UI. Εάν το πεδίο editable της μεταβλητής δεν έχει οριστεί ή έχει οριστεί σε false, η μεταβλητή θα εμφανιστεί στο Web UI στην ενότητα Variables Review ως τιμή μόνο για ανάγνωση που μπορεί να επαληθευτεί. Εάν το πεδίο editable οριστεί σε true, ωστόσο, η μεταβλητή θα εμφανιστεί ως επεξεργάσιμο πεδίο στο Web UI. Το προαιρετικό πεδίο description μπορεί να παρέχεται για την προσθήκη επιπλέον πλαισίου στη μεταβλητή. Ακολουθεί ένα παράδειγμα μεταβλητής:

variable "my_var" {
  description = "Enter your birthday"
  value = "MM/DD/YYYY"
  editable = true
}

Πρόσθετα & Προεπιλογές

Τα μπλοκ πρόσθετων σάς επιτρέπουν να καθορίσετε ποια πρόσθετα θα χρησιμοποιηθούν από το Runbook. Οποιαδήποτε πεδία δηλώνονται μέσα στο μπλοκ πρόσθετου μπορούν να αναφερθούν από οποιεσδήποτε ενέργειες που αποτελούν μέρος αυτού του πρόσθετου. Αυτό θα σας επιτρέψει να παραλείψετε πεδία κατά τη χρήση προσαρμοσμένων ενεργειών από αυτό το πρόσθετο. Το παρακάτω παράδειγμα δηλώνει το πρόσθετο svm και ορίζει τα πεδία network_id και rpc_api_url ως προεπιλογές:

addon "svm" {
  network_id = input.network_id
  rpc_api_url = input.rpc_api_url
}

Με αυτήν την προεπιλογή προστιθέμενη σε ένα αρχείο .tx, οποιεσδήποτε ενέργειες από το πρόσθετο SVM μπορούν να παραλείψουν τόσο τα πεδία network_id όσο και rpc_api_url.

Ροές

Οι ροές σάς επιτρέπουν να εκτελέσετε ένα Runbook πολλές φορές με διαφορετικές εισόδους για κάθε εκτέλεση. Οποιαδήποτε πεδία καθορίζονται στο μπλοκ ροής μπορούν να αναφερθούν από οποιεσδήποτε ενέργειες που αποτελούν μέρος αυτής της ροής μέσω flow.field_name. Αυτό μπορεί να χρησιμοποιηθεί σε συνδυασμό με το μπλοκ addon με χρήσιμους τρόπους:

// declare some flows
flow "solana" {
  rpc_api_url "https://api.mainnet-beta.solana.com"
}
flow "eclipse" {
  rpc_api_url "https://mainnetbeta-rpc.eclipse.xyz"
}
// declare the evm addon with
addon "svm" {
  network_id = "mainnet"
  rpc_api_url = flow.rpc_api_url
}
// the rest of the runbook can now use the svm addon without specifying chain_id or rpc_api_url,
// and will be executed once for each flow

Υπογράφοντες

Τα πρόσθετα μπορούν να ορίσουν υπογράφοντες που παρέχουν διάφορους τρόπους υπογραφής συναλλαγών κατά τη χρήση του surfpool. Αυτοί οι υπογράφοντες μπορούν να χρησιμοποιηθούν για την υπογραφή συναλλαγών μέσω mnemonics ή μυστικού κλειδιού, για να ζητήσουν από τους χρήστες να συνδέσουν το web wallet τους και να υπογράψουν στο Web UI του Surfpool, για ασύγχρονη υπογραφή συναλλαγών μέσω ασφαλούς θύλακα, για τον ορισμό politransig wallets και πολλά άλλα. Κάθε υλοποίηση υπογράφοντα πρόσθετου θα έχει τις δικές της περιπτώσεις χρήσης και τεκμηρίωση.

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

signer "alice" "svm::web_wallet" {
  expected_address = input.expected_address
}

action "my_tx" "svm::process_instructions" {
  ... instruction data
  signers = [signer.alice]
}

Αυτό το παράδειγμα ορίζει έναν υπογράφοντα με το όνομα alice, ο οποίος χρησιμοποιεί τον υπογράφοντα svm::web_wallet. Αυτός ο ορισμός υπογράφοντα θα δημιουργήσει μια προτροπή στο Web UI για σύνδεση πορτοφολιού, παροχή pubkey μέσω υπογραφής μηνύματος και υπογραφή όλων των συναλλαγών χρησιμοποιώντας αυτό το πορτοφόλι ως υπογράφοντα.

Ενέργειες

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

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

Ακολουθεί ένα παράδειγμα ενέργειας:

action "deploy_hello_world" "svm::deploy_program" {
    description = "Deploy the hello_world program"
    program = svm::get_program_from_anchor_project("hello_world")
    authority = signer.authority
    payer = signer.payer
}
output "signature" {
  value = action.deploy_hello_world.signature
}

Ενότητες

Σύντομα διαθέσιμο.

Έξοδοι

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

output "my_output" {
  description = "An example output. I hope it equals 8."
  value = 4 + 4
}