Język i składnia

To jest dokumentacja języka txtx. Pliki Runbook, które tworzysz, określają, których blockchainów i sieci używać, jakie dane pobierać oraz jakie transakcje rozgłaszać. Język txtx umożliwia również definiowanie zależności między zasobami oraz tworzenie wielu podobnych konstrukcji z jednego bloku.

Składnia

Runbooki zawierają serię bloków kodu, które wyglądają mniej więcej tak:

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
}

Każdy blok ma typ polecenia (w tym przykładzie variable, action oraz output), nazwę referencyjną ("query_path", "http_query" oraz "status_code") oraz dane wewnętrzne bloku (wszystko pomiędzy { ... }). Niektóre typy poleceń wymagają również podania konkretnego polecenia ("std::send_http_request"). Dane wewnętrzne bloku są określane przez typ polecenia i polecenie, które zostały wskazane.

Odwołania do poleceń

Jedno polecenie może odwoływać się do wyników innego polecenia, tworząc łańcuch zależnych poleceń. Podczas wykonywania Runbooka surfpool tworzy graf wszystkich poleceń, aby zapewnić ich wykonanie we właściwej kolejności. Oznacza to, że podczas tworzenia Runbooka należy unikać cykli zależności.

Do wyniku innego polecenia można odwołać się w bloku za pomocą command_type.ref_name.output_name. Oto kilka przykładów:

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`
}

Funkcje

The standard library udostępnia funkcje, które można zapisywać w tekście, zamiast pisać pełne bloki poleceń z nazwanymi argumentami. Funkcje te można rozszerzać za pomocą dodatków.

Funkcje te mogą wyglądać jak jawne wywołania funkcji (np. add_uint(1, 3)) lub jak operacje arytmetyczne w tekście (np. 1 + 3). Funkcje mogą odwoływać się do wyników innych poleceń lub być przechowywane jako nowe wyniki poleceń. Oto przykład z wykorzystaniem kilku funkcji:

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)
}

Dane wejściowe manifestu i CLI

Dane wejściowe można przekazać do Runbooka poprzez podanie ich jako dane wejściowe CLI lub przez określenie ich w pliku manifestu txtx.yml. Jeśli te same dane wejściowe zostały podane zarówno w CLI, jak i w manifeście, dane z CLI mają pierwszeństwo. Aby dowiedzieć się więcej o korzystaniu z CLI, zapoznaj się z dokumentacją CLI. W manifeście te dane wejściowe można grupować według klucza środowiskowego, co ułatwia korzystanie z tego samego Runbooka w wielu środowiskach.

Oto przykładowa konfiguracja ze zmiennymi środowiskowymi:

---
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

We wszystkich plikach .tx załadowanych przez ten runbook dane wejściowe input.network_id i input.rpc_api_url będą dostępne w zakresie globalnym. Gdy interfejs Web UI załaduje ten runbook, pierwszy element akcji umożliwi wybór środowiska do załadowania. Wybranie nowego środowiska spowoduje ponowne załadowanie bieżącego runbooka z nowymi zmiennymi środowiskowymi wstrzykniętymi do wykonania.

Zarządzanie stanem

Surfpool może zarządzać stanem w trakcie kolejnych wykonań Runbooka. Podczas wdrażania kontraktów zarządzanie stanem może być używane do wykrywania wszelkich zmian w kodzie kontraktu i danych wejściowych Runbooka w celu określenia, czy Runbook musi zostać ponownie wykonany. Surfpool zapobiegnie ponownemu wykonaniu Runbooka, jeśli nie ma żadnych zmian w kodzie kontraktu ani w danych wejściowych Runbooka.

Aby włączyć zarządzanie stanem, podaj wartość state oraz location do przechowywania pliku stanu w txtx.yml:

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

Zmienne

Zmienne mogą być używane do przechowywania wartości, które mogą być używane przez inne konstrukcje i które mogą być edytowane przez użytkowników w interfejsie Web UI. Jeśli pole editable zmiennej nie jest określone lub ustawione na false, zmienna pojawi się w interfejsie Web UI w sekcji Variables Review jako wartość tylko do odczytu, którą można zweryfikować. Jeśli jednak pole editable jest ustawione na true, zmienna pojawi się jako edytowalne pole w interfejsie Web UI. Opcjonalne pole description można podać, aby dodać dodatkowy kontekst do zmiennej. Oto przykładowa zmienna:

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

Dodatki i wartości domyślne

Bloki dodatków pozwalają określić, jakie dodatki będą używane przez Runbook. Wszystkie pola zadeklarowane wewnątrz bloku dodatku mogą być odwoływane przez dowolne akcje będące częścią tego dodatku. Pozwala to pominąć pola podczas korzystania z niestandardowych akcji tego dodatku. Poniższy przykład deklaruje dodatek svm i ustawia pola network_id oraz rpc_api_url jako wartości domyślne:

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

Po dodaniu tej wartości domyślnej do pliku .tx, wszystkie akcje z dodatku SVM mogą pomijać zarówno pole network_id, jak i rpc_api_url.

Przepływy

Przepływy umożliwiają wielokrotne wykonywanie Runbooka z różnymi danymi wejściowymi dla każdego wykonania. Wszystkie pola określone w bloku przepływu mogą być odwoływane przez dowolne akcje należące do tego przepływu za pomocą flow.field_name. Można to wykorzystać w połączeniu z blokiem addon na wiele użytecznych sposobów:

// 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

Sygnatariusze

Dodatki mogą definiować sygnatariuszy zapewniających różne sposoby podpisywania transakcji podczas korzystania z surfpool. Ci sygnatariusze mogą być używani do podpisywania transakcji za pomocą mnemoniki lub klucza tajnego, do monitowania użytkowników o podłączenie portfela internetowego i podpisywanie w interfejsie webowym Surfpool, do asynchronicznego podpisywania transakcji za pomocą bezpiecznej enklawy, do definiowania portfeli multisig i nie tylko. Każda implementacja sygnatariusza dodatku będzie miała własne przypadki użycia i dokumentację.

Oto przykład użycia sygnatariusza:

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

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

Ten przykład definiuje sygnatariusza o nazwie alice, który korzysta z sygnatariusza svm::web_wallet. Ta definicja sygnatariusza wygeneruje monit w interfejsie webowym o podłączenie portfela, udostępnienie pubkey za pomocą podpisu wiadomości oraz podpisywanie wszystkich transakcji przy użyciu tego portfela jako sygnatariusza.

Akcje

Akcje to wielofunkcyjne konstrukty definiowane przez dodatki oraz przez bibliotekę standardową. Każda akcja definiuje własny zestaw danych wejściowych (niektóre opcjonalne, niektóre wymagane), które można przekazać do akcji, określa, co dzieje się podczas każdego jej wywołania, oraz jakie dane wyjściowe są przez nią tworzone — mogą być one następnie wykorzystywane przez kolejne polecenia.

Przykłady typów akcji obejmują wykonywanie żądań HTTP i zwracanie wyników, kodowanie danych transakcji zgodnie z kodekiem danego łańcucha, podpisywanie transakcji przy użyciu portfela i zwracanie bajtów podpisanej transakcji lub rozgłaszanie transakcji do sieci.

Poniżej znajduje się przykładowa akcja:

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
}

Moduły

Wkrótce dostępne.

Dane wyjściowe

Polecenie output służy do wyświetlania danych po zakończeniu wykonywania runbooka. Poniżej znajduje się przykład użycia polecenia output:

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