Debugging AVM Execution

Debugging executions and the artifacts (e.g. events, state changes, messages) they generate is an important part of the development process. It allows you to identify and fix bugs in your code before it's deployed to the Firechain network. This page provides an overview of how to debug your decentralized applications on Firechain.

Debugging Executions

When you spin up a local RPC node, you can specify a debug flag. When this flag is set to true, the node will run in debug mode. This means that the entity will be executed in a sandboxed environment that allows you to step through the execution and inspect events, messages and state changes along the way. This is a great way to debug your logic before you deploy it to the Firechain network.

Debug mode is useful, but it's quite slow. It's also quite limited at the moment. For example, it's currently not possible to debug scheduled executions or those that are triggered by events. We're working on improving the debugging experience, so stay tuned!

In addition to an RPC node, you'll also need a client that supports debugging. The Firechain CLI is the only client that currently supports this feature. You can use the CLI to step through the execution of a entity and inspect the state of the entity's account at each step. We're also working on a VS Code extension that will provide a more seamless debugging experience for IDE users.

Using Firechain CLI

The Firechain CLI provides a simple interface for debugging entity execution. It allows you to step through the execution of a entity and inspect the state at each step. You can also use the CLI to inspect the events generated by the entity.

Step Through Executions

To step through the execution of a entity, use the debug command. This command takes a entity ID and a list of arguments. It will then simulate the execution, pausing to allow inspection of the stack and state changes at each step.

firechain debug <entity-id> <arg1> <arg2> ...

For example, let's say you have a entity that adds two numbers together. You can use the debug command to step through the execution of this entity.

firechain debug $ADDRESS 1 2

In the example above, $ADDRESS is the address of the entity. The entity will be executed with the arguments 1 and 2. The CLI will then step through the execution, pausing at each step to allow inspection of the stack and state changes.

Simulating execution
====================

CALLER: <...>
BALANCE: <...>

INSTRUCTION:
  PUSH 1

What would you like to do? Type 'help' for a list of commands.
> quit

Cleaning up execution context... Done.

The CLI will print the address of the caller, the origin of the transaction and the balance of the sender's account. It will then accept commands from the user. The following commands are available:

• help - Print a list of available commands.
• step - Step through the execution of the entity.
• step-over - Step through the execution of the entity, skipping over any function calls.
• step-out - Step out of the current function.
• continue - Continue execution until the entity returns.
• stack - Print the current stack.
• state - Print the current state of the entity's account.
• events - Print the events generated in the previous step.
• quit - Quit the debugger.

Step Through Executions

You can use the step command to step through the execution of the entity, line by line. It's important to note that the step command will pause at each step, including both local and remote function calls. This means that you'll need to use the step-over command to step through the execution of a function. You can use the step-out command to step out of the current function. Finally, you can use the continue command to continue execution until the function returns.

Inspect the Stack

The stack command prints the current stack. The stack is a list of values that are used to pass arguments to functions and return values from functions. The stack is also used to store local variables.

Inspect the State

The state command prints the current state of the entity's account. The state is a list of key-value pairs that are stored in the entity's account. The state is used to store persistent data.

Inspect Events

The events command prints the events generated in the previous step. Events are generated by the emit function. They are used to notify other entities that something has happened.

Quit the Debugger

The quit command quits the debugger.