Crate novax_executor

novax-executor is a crate designed to facilitate the interaction between your Rust application and a blockchain network. Its main purpose is to be used by other “novax” crates like “novax”, however, it’s designed in a way that developers can also use it for mocking purposes during testing. It abstracts the complexities involved in querying the blockchain, executing transactions, and deploying smart contracts, thereby providing a streamlined interface for developers.

The crate offers several core abstractions and implementations to interact with a blockchain:

• Executor Abstractions:

  • QueryExecutor: An asynchronous trait for executing queries on the blockchain.
  • TransactionExecutor: An asynchronous trait for executing transactions on the blockchain.
  • DeployExecutor: An asynchronous trait for deploying smart contracts on the blockchain.

• Network Interaction:

  • BlockchainInteractor: A trait abstracting over a blockchain interactor to allow mocking.
  • BlockchainProxy: A trait abstracting the communication proxy to allow mocking, providing methods to interact with the blockchain gateway.
  • ProxyQueryExecutor and QueryNetworkExecutor: Implementations for executing queries on the blockchain.
  • NetworkExecutor and BaseTransactionNetworkExecutor: Implementations for executing transactions on the blockchain.

• Mocking Framework:

  • MockExecutor: A structure to help mock blockchain interactions during testing using the MultiversX Rust Testing Framework.
  • StandardMockExecutor: An extension of MockExecutor providing standard mocking behaviors.

• Dummy Framework:

  • DummyExecutor, DummyTransactionExecutor, and DummyDeployExecutor: Implementations to assist in testing and development without actual blockchain interaction.

• Utility Types and Traits:

  • SendableTransaction and SendableTransactionConvertible: Utility types and traits to facilitate transaction handling.

• Error Handling:

  • ExecutorError: A comprehensive enumeration of errors that could occur during blockchain interaction, encompassing data errors, network query errors, and mock deploy errors.

The abstraction layers provided by this crate are designed to make it easy to implement mock or dummy executors, allowing for thorough testing and development without requiring a live blockchain network. This is especially helpful in early stages of development or in testing scenarios where the blockchain’s state or behavior needs to be controlled precisely.

The architecture also allows for the easy extension of the executor framework to support additional blockchain networks or custom interaction patterns.

Features

• async-trait: This crate uses the async-trait crate to allow for async trait methods, enabling asynchronous blockchain interaction.

Error Handling

Error handling in novax-executor is comprehensive and designed to cover a range of issues that might arise while interacting with the blockchain. See ExecutorError, NetworkQueryError, and MockDeployError for more details.

Structs

• Account
• BaseSimulationNetworkExecutor
  A struct for executing transactions in a simulated blockchain environment. It interacts with a blockchain network for transaction simulation purposes.
• BaseTransactionNetworkExecutor
  A struct representing the executor for handling transactions in a real blockchain environment.
• DummyExecutor
  A structure for capturing transaction details without performing actual blockchain transactions. It is designed for testing scenarios, especially to fetch SendableTransaction details from interactions.
• MockExecutor
  A structure to execute smart contract queries, transactions, and deployments in a mocked blockchain environment.
• QueryNetworkExecutor
  A structure to execute smart contract queries on a real blockchain environment via a specified gateway.
• ScCallStep
• ScDeployStep
• ScQueryStep
• ScenarioWorld
  A facade for contracts tests.
• SendableTransaction
  Represents a transaction that is ready to be sent to the blockchain.
• SetStateStep
• SimulationGatewayRequest
  A convenient struct in NovaX used to accumulate information necessary for creating a transaction simulation request. This struct is internally converted into SimulationGatewayRequestBody when sending the request to the gateway.
• TxQuery
• TxResponse
  The response of a transaction.
• TypedResponse
• TypedScCall
  SCCallStep with explicit return type.
• TypedScDeploy
  ScDeployStep with explicit return type.
• TypedScQuery

Enums

• ExecutorError
  An enumeration representing the various types of errors that can be encountered within the executor context.
• GatewayError
  An enumeration representing various types of errors that can occur during interactions with the MultiversX gateway.
• MockDeployError
  An enumeration representing the various errors that can occur when deploying through the MockExecutor.
• NetworkQueryError
  An enumeration representing the various errors that can occur during network query operations.
• SimulationError
  An enumeration representing errors that can occur during the simulation of transactions or contract executions. These errors are specific to the logic or processing of the transaction/contract, rather than network communication or data formatting issues.

Traits

• BlockchainInteractor
  A trait defining the interaction interface with the blockchain. This trait abstracts the blockchain interaction, enabling developers to either use the provided Interactor struct from the multiversx-sdk crate or mock it for testing purposes.
• BlockchainProxy
  The BlockchainProxy trait provides an abstraction over the CommunicationProxy struct from the multiversx-sdk crate. The main goal of this abstraction is to allow developers to mock the CommunicationProxy struct for testing purposes, by providing a set of common behaviors required for interacting with the blockchain gateway.
• DeployExecutor
  A trait defining the contract for executing smart contract deployment operations asynchronously.
• QueryExecutor
  A trait representing the execution of smart contract queries.
• SendableTransactionConvertible
  A trait for converting a type into a SendableTransaction.
• TransactionExecutor
  A trait defining the necessary operations for executing smart contract transactions.

Type Aliases

• DummyDeployExecutor
  A type alias for DummyExecutor handling ScDeployStep.
• DummyTransactionExecutor
  A type alias for DummyExecutor handling ScCallStep.
• NetworkExecutor
  Alias for the BaseTransactionNetworkExecutor struct, parameterized with the Interactor type.
• ProxyQueryExecutor
  A convenient type alias for QueryNetworkExecutor with CommunicationProxy as the generic type.
• SimulationGatewayResponse
  Type alias for GatewayResponse specialized for simulation responses. It encapsulates the data specific to the simulation of blockchain transactions.
• SimulationNetworkExecutor
  Type alias for BaseSimulationNetworkExecutor with the String type as the generic Client.
• StandardMockExecutor
  A convenient type alias for MockExecutor with String as the generic type.