When writing check:construction
tests to test with the mesh-cli
tool, it’s best to write them in the Mesh Constructor Domain-Specific Language (DSL).
The Mesh DSL allows you to write Workflows for the constructor
package.
This DSL is most commonly used for writing check:construction
tests for the mesh-cli
tool. The Mesh DSL filename’s extension is .ros
.
mesh-cli
tool’s check:construction
test. For more information, see How to Write a Configuration File for mesh-cli Testing.create_account
and transfer
workflows include this value. Using any other curve types will cause test failures with the mesh-cli
tool.request_funds
workflow requires the use of an account with test funds. You can provide that with a pre-funded account or with a URL to an account with test funds. See the Account Funding section for more information.The mesh-cli
tool’s check:construction
test uses the following hierarchy of concerns:
Workflows contain collections of Scenarios to execute. Scenarios are executed atomically in database transactions (rolled back if execution fails) and culminate in an optional broadcast. This means that a single Workflow could contain multiple broadcasts (which can be useful for orchestrating staking-related transactions that affect a single account).
To perform a Workflow, you create a Job. The Job has a unique identifier and stores the state for all Scenarios in the Workflow. The state is shared across an entire Job so that Actions in a Scenario can access the output of Actions in other Scenarios. The syntax for accessing this shared state is called GJSON Path.
Actions are discrete operations that can be performed in the context of a Scenario. You can find a full list of all the Actions that can be performed in the Mesh SDK’s ActionType package.
If you have suggestions to add more actions, you can open an issue in the mesh-sdk-go
repository.
When broken down into simple elements, the Mesh DSL syntax looks like the following example:
line comment
- Follows the JavaScript single-line comment notation of two slashes (//
) at the start of a line or at the end of a line of code.workflow name
- Your name for the workflow. For example, create_account
.
concurrency
- The order in which you want the workflow to run. You must provide a concurrency
value when you define a workflow.scenario name
- Your name for the scenarios you’d like to add to the workflow.
output path
- This variable stores the results of a scenario for later use.action type
- The reason why you want to run this scenario.input
- The input for all functions is a JSON blob that will be evaluated by the Worker
.
{{var}}
where var
must follow the GJSON syntax. The Mesh DSL compiler will automatically check that referenced variables are previously defined.If you plan to run the check:construction
test in continuous integration (CI), we recommend that you provide a value for prefunded accounts
when running the test. Otherwise, you would need to manually fund generated accounts.
Optionally, you can also provide a return_funds
workflow that will be invoked when exiting check:construction
. This can be useful in CI when you want to return all funds to a single account or faucet (instead of black-holing them in all the addresses created during testing).
To use the check:construction
test without prefunded accounts, you must implement two required Workflows:
- If you don’t implement these Workflows, processing could stall.
- Please note that
create_account
can contain a transaction broadcast if on-chain origination is required for new accounts on your blockchain.
If you’d like to broadcast a transaction at the end of a Scenario, you must populate the following fields:
<scenario>.network
<scenario>.operations
<scenario>.confirmation_depth
(allows for stake-related transactions to complete before marking as a success)Optionally, you can populate the <scenario>.preprocess_metadata
field.
Once a transaction is confirmed on-chain (after the provided <scenario>.confirmation_depth
), check:construction
stores it at <scenario>.transaction
for access by other Scenarios in the same Job.
In UTXO-based blockchains, it may be necessary to amend the operations
stored in <scenario>.operations
based on the suggested_fee
returned in /construction/metadata
. The check:construction
test supports running a dry run of a transaction broadcast if you set the <scenario>.dry_run
field to true
. The suggested fee will then be stored as <scenario>.suggested_fee
for use by other Scenarios in the same Job. You can find an example of this in the Bitcoin config).
If you do not populate this field or set it to
false
, the transaction will be constructed, signed, and broadcast.
In the Mesh DSL, it is possible to invoke functions, where the function name is written as an action type (Action.Type
).
math
and set_variable
action types. Read the Native Invocation section below for details.;
).types.go
file lists all the available functions.It is not possible to invoke a function from the input of another function. There MUST be exactly one function call per line. For example, this syntax is not allowed:
Adding this incorrect syntax to your code will produce errors.
The Mesh DSL provides optional “native invocation” support for the math
and set_variable
action types. “Native invocation” in this case means that the caller does not need to invoke the action type in the normal format:
You can invoke math
with the following syntax:
A native invocation of a simple addition would look like the following code:
The normal invocation would look like the following code:
You can invoke set_variable
with the following syntax:
A native invocation of the set_variable code would look like:
The normal invocation would look like the following code:
Workflows are part of a Mesh API implementation, which you can test with the rosetta.cli
tool.
This Workflow is required if you are testing without prefunded accounts.
The following example is for a Workflow to create an account. It includes the create_account
scenario and the save_account
scenario. For more information, read the source file.
This Workflow is required if you are testing without prefunded accounts.
The following example is for a Workflow to request funds. It includes the find_account
scenario and the request
scenario. For more information, read the source file.
The following example is for a Workflow to transfer funds. It includes the transfer
scenario. For more information, read the source file.
The following example is for a DSL file to test whether the Mesh implementation supports destination tags. It includes the request_funds
, create_account
, and transfer
workflows. For more information, read the Testing Destination Tag Blockchains section in the How to Test your Mesh Implementation document.