Arwen is the WASM-based Virtual Machine for running Elrond Smart Contracts.
The VM is launched as a child process of the Elrond Node.
IPC communication with the Node
The parent process communicates with Arwen by means of pipes (in-memory
. The main components involved in the communication flow are:
- Arwen Driver - used by Node to manage Arwen’s process)
- Node Part - contains Node’s main loop of messages; the node starts a message loop for each contract request (deployment / execution)
- Arwen Part - Arwen’s forever loop of messages
This hook is implemented directly in Arwen. There is no cross-process communication involved in executing functions of the
Any function call against the
BlockchainHook, which may happen during the execution of a smart contract results in the following:
- The function call is forwarded to
BlockchainGatewaysends a request message to the Node, via a
Messenger, through the pipe
BlockchainGatewaywaits indefinitely until a response message comes from the Node through the pipe
NodePartreceives the request message from Arwen, via its own
Messengerand resolves the request against the actual
BlockchainHookimplementation (within the appropriate blockchain replier).
- The result of the
BlockchainHookcall is wrapped in a message and sent to Arwen, through the pipe
- The control returns to
BlockchainGatewayand then to the smart contract.
Pipes - the communication takes place through these pipes:
arwenInit- Arwen initialization parameters (arguments) are passed through this pipe.
nodeToArwen- used to transport contract requests (deployment and execution) towards Arwen and also to respond on Arwen’s blockchain hook calls.
arwenToNode- used to transport blockchain hook calls from Arwen to the Node and also to respond with contract deployment / execution results.
A dialogue between the Node and Arwen starts with the deployment or execution of a smart contract and consists of a sequence of messages.
Messenger component sends a
Message, it labels it with a dialogue nonce (an increasing integer). The dialogue ends (resets) when the deployment or execution is finished (the nonce is also reset at this very time).
Both Arwen’s Messenger and Node’s Messenger check the dialogue nonces of the incoming messages to ensure the correctness of the dialogue (safety net).
When a Messenger needs to send a message, it first sends a preamble, and then the payload.
When a Messenger needs to receive a message, it first reads the preamble from the pipe, and then the payload.
The preamble consists in:
- The length of the payload (4 bytes integer)
- The kind of the message to be sent (4 bytes integer, corresponding to the type
Currently, JSON format is used to format the messages before sending them through the pipe.
The Arwen Part contains an infinite message loop. When the loop is broken (in case of a critical error), Arwen stops. The Node Part starts a message loop for each contract request it needs to send to Arwen. The message loop ends when the response is received (or in case of a critical error).
Messenger components perform blocking reads against the pipes. Read timeout is set by means of
SetDeadline calls. See
Caught critical errors end Arwen’s main loop and Arwen’s process - the process will be restarted on the very next contract request - see
Panics in Arwen’s process lead to a restart - performed by
Path of Arwen’s binary
Arwen Driver will first look for the Arwen binary in Node’s current directory. If the binary isn’t found, it will look at the path specified by the environment variable
Logs are sent from Arwen to the Node through pipes as well. The Arwen Driver also captures Arwen’s
Loggers defined on Arwen’s part:
Loggers defined on Node’s part: