From 5139a7c84a55a2d083e0693dc5f0b87291a1f019 Mon Sep 17 00:00:00 2001
From: Kunal Bhargava <kbhargava@jumptrading.com>
Date: Tue, 22 Oct 2024 15:09:18 +0000
Subject: [PATCH] update readme, part 1

---
 README.md | 84 +++++++++++++++++++++++++++----------------------------
 1 file changed, 42 insertions(+), 42 deletions(-)

diff --git a/README.md b/README.md
index c4a03f4..718c738 100644
--- a/README.md
+++ b/README.md
@@ -14,69 +14,69 @@ Clone this repository and run:
 source install.sh
 ```
 
-### (HIGHLY Recommended) Install auto-completion
+### Install auto-completion
 
 ```sh
 solana-test-suite --install-completion
 ```
 You will need to reload your shell + the `test_suite_env` venv to see the changes.
 
+## Currently Supported Harness Types
+`list-harness-types` will provide the most updated list.
+```
+$ solana-test-suite list-harness-types
+
+Available harness types:
+- ElfLoaderHarness
+- InstrHarness
+- SyscallHarness
+- CpiHarness
+- VmInterpHarness
+- VmValidateHarness
+- TxnHarness
+```
+
 ## Protobuf
 
-Each target must contain a `sol_compat_instr_execute_v1` function that takes in a `InstrContext` message and outputs a `InstrEffects` message (see [`proto/invoke.proto`](https://github.com/firedancer-io/protosol/blob/main/proto/invoke.proto)). See `utils.py:process_instruction` to see how the program interacts with shared libraries.
+Each target must contain a function entrypoint that takes in a Context input message and outputs a Effects message (see [`proto/invoke.proto`](https://github.com/firedancer-io/protosol/blob/main/proto/invoke.proto) as an example).
+
+```
+Function Entrypoints:
+- ElfLoaderHarness: sol_compat_elf_loader_v1
+- InstrHarness: sol_compat_instr_execute_v1
+- SyscallHarness: sol_compat_vm_syscall_execute_v1
+- CpiHarness: sol_compat_vm_cpi_syscall_v1
+- VmInterpHarness: sol_compat_vm_interp_v1
+- VmValidateHarness: sol_compat_vm_validate_v1
+- TxnHarness: sol_compat_txn_execute_v1
+```
 
 ### Updating definitions
-All message definitions are defined in [Protosol](https://github.com/firedancer-io/protosol/). You may need to periodically update these definitions with the following command:
+All message definitions are defined in [protosol](https://github.com/firedancer-io/protosol/). Anytime, protofuf definitions are updated in protosol, you will need to run the following command:
 
 ```sh
 ./fetch_and_generate.sh
 ```
+## Setting up Environment
+To setup the `solana-conformance` environment, run the following command and you will be all set:
+```
+source test_suite_env/bin/activate
+```
 
 ## Usage
-Run `solana-test-suite --help` to see the available commands. 
-Or, refer to the [commands.md](commands.md) for a list of available commands.
-
-### Note on [commands.md](commands.md)
-`commands.md` is automatically generated from the `typer utils docs` module.
-Help messages are dynamically generated based on the [currently set harness type](#selecting-the-correct-harness). Thus, descriptions specific to harness type (typically the Context, Effects, and Fixtures names) in `commands.md` refer to the harness type set during time of generation.
-
-When the desired [harness type is set](#selecting-the-correct-harness), the `--help` output in the CLI will reflect the correct names. Try it!
-
-### Selecting the correct harness
-The harness type should be specified by an environment variable `HARNESS_TYPE` and supports the following values (default is `InstrHarness` if not provided):
-- `InstrHarness`
-- `TxnHarness`
-- `SyscallHarness`
-- `CpiHarness`
-- `VmInterpHarness`
-- `VmValidateHarness`
-- `ElfLoaderHarness`
-
-`solana-test-suite list-harness-types` will provide the most updated list.
-
-
-### Data Preparation
-
-Before running tests, Context messages may be converted into Protobuf's text format, with all `bytes` fields base58-encoded (for human readability). This can be done with [decode-protobuf](commands.md#solana-test-suite-decode-protobuf) command.
-
-Optionally, context messages may also be left in the original Protobuf binary-encoded format.
-
-
-### Debugging
-
-For failing test cases, it may be useful to analyze what could have differed between Solana and Firedancer. You can execute a Protobuf message (human-readable or binary) through the desired client with the [`debug-instr`](commands.md#solana-test-suite-debug-instr) command.
-
-
-#### Alternative (and preferred) debugging solution
+Run the following to view all supported commands or refer to [commands.md](commands.md):
+```
+solana-test-suite --help
+```
 
-Use the following command instead if you want the ability to directly restart the program without having to restart GDB:
-```sh
+### Preferred Debugging
+Use the following command instead if you want the ability to debug in GDB:
+```
 <gdb / rust-gdb> --args python3.11 -m test_suite.test_suite exec-instr --input <input_file> --target <shared_lib>
 ```
-
 Refer to [`exec-instr`](commands.md#solana-test-suite-exec-instr) command for more information.
 
-Recommended usage is opening two terminals side by side, and running the above command on both with one having `--target` for Solana (`impl/lib/libsolfuzz_agave_v2.0.so`) and another for Firedancer (`impl/lib/libsolfuzz_firedancer.so`), and then stepping through the debugger for each corresponding test case.
+Recommended usage is opening two terminals side by side, and running the above command on the same output while changing the target parameter to the two desired targets and  stepping through the debugger for each corresponding test case.
 
 
 ### Uninstalling