feat(ssa): SSA CLI

[aakoshh]

Description

Problem*

Resolves #8503

Summary*

Adds a noir-ssa CLI tool. There are two main sub-commands:

• transform applies SSA pass(es) and prints the resulting SSA
• interpret takes a TOML formatted input file and runs it with the SSA interpreter

Both take SSA from a file or stdin, so it is possible to chain multiple commands with by piping the output, for example:

cat ./initial.ssa \
  | noir-ssa transform --ssa-pass "Remove Unreachable Instructions" \
  | noir-ssa transform --ssa-pass mem2reg --ssa-pass "Dead Instruction elimination" \
  | noir-ssa interpret --input-path ./inputs.toml 

We can specify multiple --ssa-pass options, which is a bit less verbose than piping, and saves re-parsing the SSA after each pass. The passes are executed in the order of appearance, unlike with nargo interpret, where they are just a filter to tell at which point the SSA should be interpreted, while it goes through the whole pipeline.

We can also use the --show-ssa and --show-ssa-pass options to see the SSA along the way, but only the last state is printed to stdout, so that it can be piped to interpret for example; the interim states go to stderr.

The inputs for the circuit are expected to be in JSON or TOML format, with the same syntax as the ABI values in a typical Prover.toml, but using the SSA variable IDs for parameter names. For example if we have this Noir function:

fn main(a: [[u8; 2]; 2], b: bool, c: u32) { ... }

and it's turned into this SSA:

acir(inline) fn main f0 {
  b0(v0: [[u8; 2]; 2], v1: u1, v2: u32):
...

then we can interpret it with the following inputs:

v0 = [[1, 2], [3, 4]]
v1 = true
v2 = 0

The way it works is that we generate an artificial ABI from SSA, and use that ABI to parse the input file. (For this we are reusing some existing utilities that are a bit scattered around. There is already a ticket to move them: #8707).

The inputs can come from a file with --input-path, or for quick and simple cases it can be specified on the CLI using --input-toml or --input-json. When using --input-toml, we can use ; to define multiple keys, like v0 = 1; v1 = [2,3].

interpret prints the output to stdout, but not the SSA source. This could potentially be useful if we wanted to alternate transforming and interpreting, but it's probably an overkill. Easy to add later anyway.

Additional Context

For more information about this error, try `rustc --explain E0602`.
CLI tool to work with SSA independently of any Noir program

Usage: noir-ssa [OPTIONS] <COMMAND>

Commands:
  list       List the SSA passes we can apply
  check      Parse and (optionally) validate the SSA
  interpret  Parse the input SSA and it arguments, run the SSA interpreter, then write the return values to stdout
  transform  Parse the input SSA, run some SSA passes on it, then write the output SSA
  help       Print this message or the help of the given subcommand(s)

Options:
  -s, --source-path <SOURCE_PATH>
          Path to the source SSA.
          
          If empty, the SSA will be read from stdin.

      --no-validate
          Turn off validation of the source SSA.
          
          This can be used to test how invalid input behaves.

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Follow up ideas

Interactive mode

For quickly trying out some SSA. Maybe it could ask for the SSA, then the TOML, which the user would copy-paste or type in.

Currently this works for example like this:

pbpaste | cargo run -q -p noir_ssa_cli -- transform --ssa-pass mem2reg
pbpaste | cargo run -q -p noir_ssa_cli -- interpret --input-toml "v0 = false; v1=100"

Render the CFG

We often use pen and paper to draw out a CFG to better follow the jumps. It would be great to visualise it with Mermaid for example.

Documentation*

Check one:

• No documentation needed.
• Documentation included in this PR.
• [For Experimental Features] Documentation to be submitted in a separate PR.

PR Checklist*

• I have tested the changes locally.
• I have formatted the changes with Prettier and/or cargo fmt on default settings.

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Test Suite Duration'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.

Benchmark suite	Current: 254542e	Previous: 35b7c14	Ratio
test_report_zkpassport_noir-ecdsa_	2 s	1 s	2

This comment was automatically generated by workflow using github-action-benchmark.

CC: @TomAFrench

[asterite]

Looks great!

[vezenovm]

Really nice tool!

[aakoshh]

It just occurred to me that checkshould print the normalized SSA so it helps with the parameter name matching problem @asterite encountered

[Savio-Sou]

Who could be relevant users of this new tool? (E.g. us internal engineers, auditors, tooling engineers, app developers...)

[aakoshh]

Internal engineers and auditors I think.