readme improvements

Signed-off-by: eolesinski <[email protected]>

README.md

@@ -1,5 +1,13 @@
+<h1 align="center">
+<img src="docs/opencbdc-banner-out.svg" width="400">
+</h1><br>
+
 ![CI Status](https://github.com/mit-dci/opencbdc-tx/actions/workflows/ci.yml/badge.svg)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](docs/code_of_conduct.md)
+[![](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://opencbdc.zulipchat.com/register/)
+[![MIT License](https://img.shields.io/badge/License-MIT-green)](https://opensource.org/licenses/MIT)
+![GitHub Stars](https://img.shields.io/github/stars/mit-dci/opencbdc-tx?style=social)
+
 
 # Introduction
 
@@ -13,9 +21,9 @@ For higher-level conceptual explanations, as well as findings and conclusions re
 Initially, we focused our work on achieving high transaction throughput, low latency, and resilience against multiple geographical datacenter outages without significant downtime or any data loss.
 The design decisions we made to achieve these goals will help inform policy makers around the world about the spectrum of tradeoffs and available options for CBDC design.
 
-# Important News
+# News
 
-**NOTE:** In cases where there are significant changes to the repository that might need manual intervention down-stream (or other important updates), we will [make a NEWS post](NEWS.md).
+If there are significant changes to the repository that may require manual downstream intervention (or other important updates), we will make a [NEWS post](NEWS.md).
 
 # Architecture
 We have explored several architectures under two broad categories as follows:
@@ -54,81 +62,100 @@ The architecture is composed of two layers:
 - Unmodified smart contracts from the Ethereum ecosystem can be deployed directly onto our EVM implementation.
 
 Read the [PArSEC Architecture Guide](docs/parsec_architecture.md) for more details.
-# Contributing
+# Contributing and Discussion
 
-You can [sign up](https://dci.mit.edu/opencbdc-interest) to receive updates from technical working groups and to learn more about our work.
+You can join the [OpenCBDC mailing list](https://dci.mit.edu/opencbdc-interest) to receive updates from technical working groups and learn more about our work.
 If you would like to join our technical discussions and help workshop proposals, you can join our [Zulip chat](https://opencbdc.zulipchat.com/register/).
 
 For more information on how to contribute, please see our [Contribution Guide](docs/contributing.md)!
 
 If you want to dive straight in, take a look at our issue tracker's list of [good first issues](https://github.com/mit-dci/opencbdc-tx/labels/difficulty%2F01-good-first-issue).
 
-# Get the Code
+# Setup
+
+If you would like to install OpenCBDC and run it on your local machine, follow the steps below:
+
+## Get the Code
 
 1. [Install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
-1. Clone the repository (including submodules)
-    - `git clone --recurse-submodules https://github.com/mit-dci/opencbdc-tx`
+1. Clone the repository (including the submodules using: `--recurse-submodules`)
 
-# Setup the build envirnoment
+    ```
+    git clone --recurse-submodules https://github.com/mit-dci/opencbdc-tx
+    ```
 
-Use these directions if you want to build the source on your machine.
-If you just want to run the system, see "Run the Code" below.
+## Setup the build environment
+
+Use these directions if you would like to build the source code on your machine.
+Alternatively, if you just want to run the system, skip to the [Run the Code](#run-the-code) section below.
+
+1. Setup the build-environment
 
-1. Setup the build-environment.
    Note that this script is just a convenience to install system-wide dependencies we expect.
    As a result, it uses the system package manager, requires `sudo`, and should only be run **once**.
    ```console
    # ./scripts/install-build-tools.sh
    ```
 1. Setup project dependencies
-   This script builds and installs a local copy of several build-dependencies which are not widely packaged.
-   Because it installs to a local, configurable prefix (defaulting to `./prefix`), it does not need root permissions to run.
-   Furthermore, it should always be safe to delete `prefix` and rerun this script.
+
+   This script builds and installs a local copy of several build-dependencies that are not widely packaged.
+   Because the installation is done in a user-specific location (`./prefix` by default) rather than a system-wide one, you do not need root permission to run the script.
+   Additionally, if you want to remove the installed build-dependencies or restart the installation process, you can safely delete the `prefix` directory and rerun this script.
    ```console
    $ ./scripts/setup-dependencies.sh
    ```
-1. Run the build
+1. Run the build script
    ```console
    $ ./scripts/build.sh
    ```
 
-## macOS
-Note that if you have not already installed the xcode cli tools you will need to:
+### macOS
+Note: If you have not already installed the Xcode CLI tools, you will need to do so:
 
 ```console
 # xcode-select --install
 ```
-# Run the Code
+# Documentation
 
-The API Reference is now housed in [an external repository](https://github.com/mit-dci/opencbdc-tx-pages/).
-See the [live deployment](https://mit-dci.github.io/opencbdc-tx-pages/) to browse.
+Github Pages hosts the official copy of the OpenCBDC [API Reference](https://mit-dci.github.io/opencbdc-tx-pages/).
 
-## UHS-based Architectures (2PC & Atomizer)
+This reference is housed in [an external repository](https://github.com/mit-dci/opencbdc-tx-pages/).
+
+## Running the Code
+
+### UHS-based Architectures (2PC & Atomizer)
 See the [2PC & Atomizer User Guide](docs/2pc_atomizer_user_guide.md)
-## PArSEC Architecture
+### PArSEC Architecture
 See the [PArSEC User Guide](docs/parsec_user_guide.md)
+
 # Testing
 
-Running Unit & Integration Tests
+Users can verify the setup by running both unit/integration and end-to-end tests on OpenCBDC.
+
+## Unit and Integration Tests
+
+### Running the tests:
+
+1. Build all Docker images
 
-1. Build all docker images
    ```console
    $ ./scripts/build-docker.sh
    ```
-1. Run Unit & Integration Tests
+1. Run Unit and Integration Tests
+
    ```console
    $ docker run -ti opencbdc-tx-builder ./scripts/test.sh
    ```
 
 ## E2E Testing with Kubernetes
 
-### Requirements
+### Requirements:
 - Go (go test library used to run tests)
 - Minikube
 - Helm
 - Kubectl
 
-### Running tests
+### Running the tests:
 
 1. `./scripts/build-docker.sh`
 1. `./scripts/test-e2e-minikube.sh`