Язык и синтаксис

Это документация по языку txtx. Файлы Runbook, которые вы пишете, описывают, какие блокчейны и сети использовать, какие данные получать и какие транзакции транслировать. Язык txtx также позволяет определять зависимости между ресурсами и создавать несколько похожих конструкций из одного блока.

Синтаксис

Runbook содержат серию блоков кода, которые выглядят примерно так:

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

Входные данные манифеста и CLI

Входные данные можно передать в Runbook через CLI или указать в файле манифеста txtx.yml. Если одни и те же входные данные переданы и через CLI, и через манифест, приоритет будет у CLI. Для получения информации об использовании CLI обратитесь к документации по CLI. В манифесте входные данные можно группировать по ключу окружения, что позволяет легко использовать один и тот же 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 будут доступны в глобальной области видимости. При загрузке этого runbook в веб-интерфейсе первый элемент действия позволит выбрать нужное окружение. Выбор нового окружения перезагрузит текущий runbook с новыми переменными окружения, которые будут внедрены в процесс выполнения.

Управление состоянием

Surfpool может управлять состоянием между запусками Runbook. При развёртывании контрактов управление состоянием позволяет обнаруживать изменения в коде контракта и входных данных Runbook, чтобы определить, требуется ли повторное выполнение. Surfpool предотвратит повторное выполнение Runbook, если в коде контракта или входных данных Runbook не произошло никаких изменений.

Чтобы включить управление состоянием, укажите значение state и путь location для хранения файла состояния в txtx.yml:

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

Переменные

Переменные используются для хранения значений, которые могут применяться другими конструкциями и редактироваться пользователями в веб-интерфейсе. Если поле editable переменной не задано или установлено в false, переменная отобразится в веб-интерфейсе в разделе Variables Review как значение только для чтения, которое можно проверить. Если же поле editable установлено в true, переменная отобразится как редактируемое поле в веб-интерфейсе. Необязательное поле 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. Эти подписанты могут использоваться для подписи транзакций с помощью мнемоники или секретного ключа, для запроса пользователям подключить свой веб-кошелёк и выполнить вход в веб-интерфейсе Surfpool, для асинхронной подписи транзакций через защищённый анклав, для определения мультиподписных кошельков и других целей. Каждая реализация подписанта дополнения имеет собственные сценарии использования и документацию.

Ниже приведён пример использования подписанта:

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. Данное определение подписанта сформирует запрос в веб-интерфейсе для подключения кошелька, предоставления pubkey через подпись сообщения и подписи всех транзакций с использованием этого кошелька в качестве подписанта.

Действия

Действия — это многофункциональные конструкции, которые определяются аддонами и стандартной библиотекой. Каждое действие определяет собственный набор входных параметров (некоторые из которых являются необязательными, а некоторые — обязательными), которые можно передать действию, логику выполнения при каждом вызове, а также выходные данные, создаваемые действием, на которые могут ссылаться последующие команды.

Примеры типов действий включают выполнение HTTP-запросов с выводом результата, кодирование данных транзакции в соответствии с кодеком заданной цепочки, подписание транзакции с помощью кошелька с выводом байтов подписанной транзакции или трансляцию транзакции в сеть.

Ниже приведён пример действия:

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
}

Модули

Скоро появится.

Выходные данные

Команда вывода может использоваться для отображения данных по завершении выполнения сценария. Ниже приведён пример команды вывода:

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