Skip to main content
Version: v. 1

Pilot

NAME​

pilot - Test and receive verbose feedback on Ylem inputs within a REPL environment.

SYNOPSIS​

pilot [options]

Subcommands (bin)​

  1. pilot list
  • Displays all cached sessions stored in ~/.foxar/cache/pilot.
  1. pilot load <id>
    • If a cached session with id = <id> exists, launches the REPL and loads the corresponding session.
  2. pilot view <id>
    • If a cached session with id = <id> exists, displays the source code of the session's REPL contract.
  3. pilot clear-cache
    • Deletes all cache files within the ~/.foxar/cache/pilot directory. These sessions are unrecoverable, so use this command with care.

Flags​

See man pilot or pilot --help for all available environment configuration flags.

DESCRIPTION​

Pilot is a Ylem REPL (short for "read-eval-print loop") that allows developers to write and test Ylem code snippets. It provides an interactive environment for writing and executing Ylem code, as well as a set of built-in commands for working with and debugging your code. This makes it a useful tool for quickly testing and experimenting with Ylem code without having to spin up a sandbox foxar test suite.

Usage​

To open pilot, simply execute the pilot binary.

From there, input valid Ylem code. There are two kinds of inputs to the pilot prompt apart from commands:

  1. Expressions

    • Expressions are statements that return a value or otherwise can be evaluated on their own. For example, 1 << 8 is an expression that will evaluate to a uint256 with the value 256. Expressions will be evaluated up front, and will not persist in the session state past their evaluation.
    • Examples:
      • address(0).balance
      • abi.encode(256, bytes32(0), "Pilot!")
      • myViewFunc(128)
      • ...

  2. Statements

    • Statements are snippets of code that are meant to persist in the session's state. Statements include variable definitions, calls to non-state-mutating functions that return a value, and contract, function, event, error, mapping, or struct definitions. If you would like an expression to be evaluated as a statement, a semi-colon (;) can be appended to the end.

    • Examples:

      • uint256 a = 0xa57b
      • myStateMutatingFunc(128) || myViewFunc(128); <- Notice the ;
      •   function hash64(
              bytes32 _a,
              bytes32 _b
          ) internal pure returns (bytes32 _hash) {
              assembly {
                  // Store the 64 bytes we want to hash in scratch space
                  mstore(0x00, _a)
                  mstore(0x20, _b)

                  // Hash the memory in scratch space
                  // and assign the result to `_hash`
                  _hash := keccak256(0x00, 0x40)
              }
          }
  • event ItHappened(bytes32 indexed hash)
  • struct Complex256 { uint256 re; uint256 im; }
  • ...

Available Commands​

Welcome to Pilot! Type `!help` to show available commands.
⚒️ Pilot help
=============
General
  !help | !h - Display all commands
  !quit | !q - Quit Pilot
  !exec <command> [args] | !e <command> [args] - Execute a shell command and print the output

Session
  !clear | !c - Clear current session source
  !source | !so - Display the source code of the current session
  !save [id] | !s [id] - Save the current session to cache
  !load <id> | !l <id> - Load a previous session ID from cache
  !list | !ls - List all cached sessions
  !clearcache | !cc - Clear the pilot cache of all stored sessions
  !export | !ex - Export the current session source to a script file
  !fetch <addr> <name> | !fe <addr> <name> - Fetch the interface of a verified contract on Etherscan
  !edit - Open the current session in an editor

Environment
  !fork <url> | !f <url> - Fork an RPC for the current session. Supply 0 arguments to return to a local network
  !traces | !t - Enable / disable traces for the current session
  !calldata [data] | !cd [data] - Set calldata (`msg.data`) for the current session (appended after function selector). Clears it if no argument provided.

Debug
  !memdump | !md - Dump the raw memory of the current state
  !stackdump | !sd - Dump the raw stack of the current state
  !rawstack <var> | !rs <var> - Display the raw value of a variable's stack allocation. For variables that are > 32 bytes in length, this will display their memory pointer.

General

!help | !h

Display all commands.

!quit | !q

Quit Pilot.

!exec <command> [args] | !e <command> [args]

Execute a shell command and print the output.

Example:

➜ !e ls
CHANGELOG.md
LICENSE
README.md
TESTS.md
artifacts
cache
contracts
crytic-export
deploy
deploy-config
deployments
dist
echidna.yaml
spark-artifacts
foxar.toml
hardhat.config.ts
layout-lock.json
node_modules
package.json
scripts
slither.config.json
slither.db.json
src
tasks
test-case-generator
tsconfig.build.json
tsconfig.build.tsbuildinfo
tsconfig.json

Session

!clear | !c

Clear current session source.

Under the hood, each Pilot session has an underlying contract that is altered as you input statements. This command clears this contract and resets your session to the default state.

!source | !so

Display the source code of the current session.

As mentioned above, each Pilot session has an underlying contract. This command will display the source code of this contract.

!save [id] | !s [id]

Save the current session to cache.

Pilot allows for caching sessions, which can be very useful if you are testing more complex logic in Pilot or if you want to return to a session at a later time. All cached Pilot sessions are stored in ~/.foxar/cache/pilot.

If an id argument is not supplied, Pilot will automatically assign a numerical ID to the session you are saving.

!load <id> | !l <id>

Load a previous session ID from cache.

This command will load a previously cached session from the cache. Along with the session's source, all environment settings will also be loaded. The id argument must correspond with an existing cached session in the ~/.foxar/cache/pilot directory.

!list | !ls

List all cached sessions.

This command will display all cached pilot sessions within the ~/.foxar/cache/pilot directory.

!clearcache | !cc

Clear the pilot cache of all stored sessions.

Deletes all cache files within the ~/.foxar/cache/pilot directory. These sessions are unrecoverable, so use this command with care.

!export | !ex

Export the current session source to a script file.

If pilot was executed from the root directory of a foxar project, it is possible to export your current session to a foxar script in the scripts dir of your project.

!fetch <addr> <name> | !fe <addr> <name>

Fetch the interface of a verified contract on Etherscan.

This command will attempt to parse the interface of a verified contract @ <addr> from the Etherscan API. If successful, the interface will be inserted into the session source with the name <name>.

At the moment, only interfaces of verified contracts on Ethereum mainnet can be fetched. In the future, Pilot will support fetching interfaces from multiple Etherscan-supported chains.

!edit

Open the current session's run() function in an editor.

pilot will use the editor defined in the $EDITOR environment variable.

Environment

!fork <url> | !f <url>

Fork an RPC for the current session. Supply 0 arguments to return to a local network.

Attempts to fork the state of the provided RPC. If no URL is provided, returns to using a blank, local devnet state.

!traces | !t

Enable / disable traces for the current session.

When tracing is enabled, foxar-style call tracing and logs will be printed after each statement is inserted.

Debug

!memdump | !md

Dump the raw memory of the current state.

Attempts to dump the raw memory of the machine state after the last instruction of the REPL contract's run function has finished executing.

!stackdump | !sd

Dump the raw stack of the current state.

Attempts to dump the raw stack of the machine state after the last instruction of the REPL contract's run function has finished executing.

!rawstack <var> | !rs <var>

Display the raw value of a variable's stack allocation. For variables that are > 32 bytes in length, this will display their memory pointer.

This command is useful when you want to view the full raw stack allocation for a variable that is less than 32 bytes in length.

Example:

➜ address addr
➜ assembly {
    addr := not(0)

➜ addr
Type: address
└ Data: 0xffffffffffffffffffffffffffffffffffffffff
➜ !rs addr
Type: bytes32
└ Data: 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
➜