fix: reconcile docs for rename and updates

Signed-off-by: Sam Stuewe <[email protected]>

docs/parsec_architecture.md

@@ -25,7 +25,7 @@ Therefore transaction throughput is horizontally scalable with additional server
 For example, in contrast to the Ethereum blockchain, this system executes native value transfers and smart contract transactions (e.g. [ERC20 token](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/) transfers) in parallel for independent addresses.
 
 # Architecture Diagram
-![Architecture Diagram](PArSEC_architecture_diagram.svg)
+![Architecture Diagram](parsec_architecture_diagram.svg)
 
 # System Components
 ### Agent (Transaction Coordinator)

docs/parsec_user_guide.md

@@ -1,21 +1,22 @@
 # PArSEC User Guide
 
-This guide runs through setting up the PArSEC system with the EVM runner, and then interacting with it using Hardhat and MetaMask. This assumes that the system has been set up as described in the [README](https://github.com/mit-dci/opencbdc-tx#readme).
+This guide runs through setting up the PArSEC system with the EVM runner, and then interacting with it using Hardhat and MetaMask.
+This assumes that the system has been set up as described in the [README](https://github.com/mit-dci/opencbdc-tx#readme).
 
 ## Prerequisites
 
 Make sure you have [NodeJS installed](https://github.com/nodesource/distributions/blob/master/README.md).
 We recommend using `v18` or `v20`, as Hardhat [actively supports these versions](https://github.com/nodejs/release#release-schedule) currently.
-We also provide a [.nvmrc](https://github.com/mit-dci/opencbdc-tx/blob/trunk/.nvmrc).
+We also provide a [.nvmrc](../.nvmrc).
 ## Running the Server
 ### Run with Docker
 
-Spawns an agent running the EVM runner by default.  
-Lua runner may be used by modifying the --runner_type flag in the command keyed by agent0, in the file [`docker-compose-PArSEC.yml`](https://github.com/mit-dci/opencbdc-tx/blob/trunk/docker-compose-PArSEC.yml).
+Spawns an agent running the EVM runner by default.
+Lua runner may be used by modifying the --runner_type flag in the command keyed by agent0, in the file [`docker-compose-parsec.yml`](https://github.com/mit-dci/opencbdc-tx/blob/trunk/docker-compose-parsec.yml).
 
 ### Start it up
 ```console
-# docker compose -f docker-compose-PArSEC.yml up -d
+# docker compose -f docker-compose-parsec.yml up -d
 ```
 
 The agent is now available on `http://localhost:8080/`.
@@ -27,7 +28,7 @@ If you are using MacOS or an Ubuntu-like distribution, you can run the system wi
 Build and run the system:
 ```console
 $ ./scripts/build.sh
-$ ./scripts/PArSEC-run-local.sh [OPTIONS]  # use --help flag for help
+$ ./scripts/parsec-run-local.sh [OPTIONS]  # use --help flag for help
 ```
 The agent is now available on the specified IP address and port (defaults to localhost:8888).
 
@@ -37,12 +38,13 @@ Follow below for a demo.
 
 ### Setup Hardhat environment
 
-Go to a new separate directory and run `npm init` and `npm install --save-dev hardhat @nomiclabs/hardhat-waffle`:
+Go to a new separate directory and run the following:
 
 ```console
-$ mkdir PArSEC-playground && cd PArSEC-playground
-$ npm init   # all fields may be left as defaults (or blank)
-$ npm install --save-dev hardhat @nomiclabs/hardhat-waffle
+$ mkdir parsec-playground && cd parsec-playground
+$ npm -y init   # `-y` keeps all defaults
+$ npm install @nomicfoundation/hardhat-ethers ethers
+$ npm install hardhat
 ```
 
 Finish with initializing Hardhat using:
@@ -51,17 +53,19 @@ Finish with initializing Hardhat using:
 $ npx hardhat
 ```
 
-Select to create a JavaScript project. All default values are sufficient for instantiating this project.
+Select to create a JavaScript project.
+All default values are sufficient for instantiating this project.
 
 Note: This will create new subdirectories and files in this directory.
-These can all be overwritten for the purpose of this guide.  
+These can all be overwritten for the purpose of this guide.
 However, to use the Hardhat compiler, all Solidity files should be stored in the
 `contracts` subdirectory.
 
-Copy the example [hardhat.config.js](https://github.com/mit-dci/opencbdc-tx/blob/trunk/scripts/hardhat.config.js) into this directory.
+Copy the example [hardhat.config.js](../scripts/hardhat.config.js) into this directory.
 
-Edit the `url:` value in the `hardhat.config.js` file to correspond with the url of the agent RPC server.  
-Using Docker this will be `http://localhost:8080/`. If running outside of Docker, use the IP and port specified when running `./scripts/PArSEC-run-local.sh` (default is `http://localhost:8888/`).
+Edit the `url:` value in the `hardhat.config.js` file to correspond with the url of the agent RPC server.
+Using Docker this will be `http://localhost:8080/`.
+If running outside of Docker, use the IP and port specified when running `./scripts/parsec-run-local.sh` (default is `http://127.0.0.1:8888/`).
 
 Note: the value in the `accounts` array is the private key of one of the hard-coded, pre-minted accounts in PArSEC/EVM.
 
@@ -77,7 +81,8 @@ browse the [Hardhat getting started guide](https://hardhat.org/hardhat-runner/do
 
 ### Using the MetaMask Web3 Client
 
-Install [MetaMask](https://metamask.io/) as a browser add-on. After initialization with seed phrases and all, [add a custom network](https://metamask.zendesk.com/hc/en-us/articles/360043227612-How-to-add-a-custom-network-RPC).
+Install [MetaMask](https://metamask.io/) as a browser add-on.
+After initialization with seed phrases and all, [add a custom network](https://metamask.zendesk.com/hc/en-us/articles/360043227612-How-to-add-a-custom-network-RPC).
 
 | Parameter       | Value                                     |
 | --------------- | ------------------------------------------|
@@ -86,21 +91,22 @@ Install [MetaMask](https://metamask.io/) as a browser add-on. After initializati
 | New RPC URL     | `http://<agent IP address>:<agent port>/` |
 | Currency symbol | `CBDC`                                    |
 
-The agent IP address and agent port are the IP address and port specified for the agent when spawning the system.  
-Using Docker, this defaults to {IP: localhost, port: 8080}  
+The agent IP address and agent port are the IP address and port specified for the agent when spawning the system.
+Using Docker, this defaults to {IP: localhost, port: 8080}
 Running outside of Docker, this defaults to {IP: localhost, port:8888}.
 ### Funding MetaMask
 
-Once you have MetaMask set up, there will be "Account 1" with a trucated address up top, with a button to copy the address. You can use that to send yourself some coins:
+Once you have MetaMask set up, there will be "Account 1" with a trucated address up top, with a button to copy the address.
+You can use that to send yourself some coins:
 
-To issue yourself native tokens, execute the following commands:  
+To issue yourself native tokens, execute the following commands:
 Note: the `>` symbol is the Hardhat prompt.
 ```console
 $ npx hardhat console
 
 > const signers = await ethers.getSigners()
 undefined
-> await signers[0].sendTransaction({to:"0x08293b196E8F1c5552e455CFD10B642EC7a809A7", value:ethers.utils.parseUnits("500.99").toHexString()});
+> await signers[0].sendTransaction({to:"0x08293b196E8F1c5552e455CFD10B642EC7a809A7", value:ethers.toBeHex(ethers.parseUnits("500.99"))});
 {
     ...
 }
@@ -111,50 +117,51 @@ You should see the balance appear after a few moments.
 
 ### Try deploying en ERC20 token!
 
-An example ERC20 token contract is provided at [opencbdc-tx/contracts/MITCoin.sol](https://github.com/mit-dci/opencbdc-tx/blob/trunk/contracts/MITCoin.sol). Use this file as a basis, or create one [from scratch](https://dev.to/yakult/a-concise-hardhat-tutorial-part-2-writing-erc20-2jpm).   
+An example ERC20 token contract is provided at [opencbdc-tx/contracts/MITCoin.sol](../contracts/MITCoin.sol).
+Use this file as a basis, or create one [from scratch](https://dev.to/yakult/a-concise-hardhat-tutorial-part-2-writing-erc20-2jpm).
 Follow the below directions to deploy your token.
 
 Note: To compile the example contract, `@openzeppelin/contracts` is a required install.
 ```console
 $ npm install @openzeppelin/contracts
 ```
-Create a deploy script for the token. An example is provided in [opencbdc-tx/scripts/deploy.js](https://github.com/mit-dci/opencbdc-tx/blob/trunk/docs/PArSEC_user_guide.md).  
-As written, this script requires the name of the ERC20 token to be changed to match the name of the token which is to be deployed.  
+Create a deploy script for the token. An example is provided in [opencbdc-tx/scripts/deploy.js](../scripts/deploy.js).
+As written, this script requires the name of the ERC20 token to be changed to match the name of the token which is to be deployed.
 
 Note: When the Hardhat project was initialized, a `scripts/deploy.js` file was created.
 It corresponds to the file `contracts/Lock.sol` that was also created upon initialization.
 For the purposes of this guide, that script can be overwritten, and we do not require `contracts/Lock.sol`.
 
-Spawn the system using above instructions, then run:
+To deploy [opencbdc-tx/contracts/MITCoin.sol](../contracts/MITCoin.sol), spawn the system using above instructions, then run:
 
 ```console
+$ cp <path_to_local_opencbdc-tx_clone>/contracts/MITCoin.sol contracts
 $ npx hardhat compile
-$ npx hardhat run *deploy-script*.js
+$ npx hardhat run <path_to_local_opencbdc-tx_clone>/scripts/deploy.js
 Deploying contracts with the account: 0x01A151CC5ED14d110cc0e6b64360913DE9f453F1
-Account balance: 1000000.0
-Contract Information: {
-  to: null,
-  from: '0x01A151CC5ED14d110cc0e6b64360913DE9f453F1'
-  contractAddress: ...
-  ...
-}
+Contract Address: 0x610d7e7AF709BA7e235214Bd56af888Cd5FDb477
 ```
 
-*Take note of the value labeled contractAddress*
+*Take note of the Contract Address.*
+Unless manually modified, the token name for the provided example contract is `MITCoin`.
 
-The token is now deployed on the network! Issue some to your metamask account:
+The token is now deployed on the network!
+Issue some to your metamask account:
 
 *The below example assumes that the ERC20 has a function `mint(address, amount)`*
 
+
 ```console
 $ npx hardhat console
-> const yourToken = await (await ethers.getContractFactory("*yourTokenName*")).attach("*yourContactAddress noted above*");
+> const yourToken = await (await ethers.getContractFactory("yourTokenName")).attach("yourContractAddress");
 undefined
-> await yourToken.mint("*your metamask address*", ethers.utils.parseUnits("5000"))
+> await yourToken.mint("your metamask address", ethers.parseUnits("5000"))
 {
   hash: '0x12056b3043c7201c4475eacfebcb4b7d4a64fba25c3b3e8262dbe5e42d215cd8',
   ...
 }
->
 ```
+
+In MetaMask, you can now click `Import tokens`, and paste the Contract Address reported above; the other two fields should populate automatically.
+
 This is the end of the guide, but we encourage you to try deploying new and unique contracts to the system!

scripts/deploy.js

@@ -3,16 +3,9 @@ async function main() {
 
     console.log("Deploying contracts with the account:", deployer.address);
 
-    const weiAmount = (await deployer.getBalance()).toString();
-
-    console.log("Account balance:", (await ethers.utils.formatEther(weiAmount)));
-
     // fill in your token name here
-    const Token = await ethers.getContractFactory("MITCoin");
-    const token = await Token.deploy();
-
-    const info = await token.deployTransaction.wait();
-    console.log("Contract Information:", info);
+    const token = await ethers.deployContract("MITCoin", []);
+    console.log("Contract Address:", await token.getAddress());
   }
 
   main()
@@ -21,3 +14,4 @@ async function main() {
       console.error(error);
       process.exit(1);
   });
+

scripts/hardhat.config.js

@@ -1,4 +1,4 @@
-require("@nomiclabs/hardhat-waffle");
+require("@nomicfoundation/hardhat-ethers");
 
 // You need to export an object to set up your config
 // Go to https://hardhat.org/config/ to learn more
@@ -17,7 +17,10 @@ module.exports = {
   defaultNetwork: "opencbdc",
   networks: {
     opencbdc: {
-      url: "http://localhost:8888/",
+      // This URL is the PArSEC agent Node endpoint
+      // NOTE: "localhost" (instead of 127.0.0.1) may work on some systems
+      url: "http://127.0.0.1:8888/",
+      // Private key corresponding to a pre-minted PArSEC account
       accounts: ["32a49a8408806e7a2862bca482c7aabd27e846f673edc8fb0000000000000000"]
     }
   }

src/parsec/agent/runners/lua/server.hpp

@@ -22,7 +22,7 @@ namespace cbdc::parsec::agent::rpc {
         /// \param srv pointer to an asynchronous RPC server.
         /// \param broker broker instance.
         /// \param log log instance.
-        /// \param cfg system configuration options.
+        ///  \param cfg system configuration options.
         server(std::unique_ptr<server_type> srv,
                std::shared_ptr<broker::interface> broker,
                std::shared_ptr<logging::log> log,

src/uhs/sentinel/interface.hpp

@@ -90,15 +90,17 @@ namespace cbdc::sentinel {
         /// \return the response from the sentinel or std::nullopt if
         ///         processing failed.
         virtual auto execute_transaction(transaction::full_tx tx)
-            -> std::optional<execute_response> = 0;
+            -> std::optional<execute_response>
+            = 0;
 
         /// Validate transaction and generate a sentinel attestation if the
         /// transaction is valid.
         /// \param tx transaction to validate and attest to.
         /// \return sentinel attestation for the given transaction, or
         ///         std::nullopt if the transaction is invalid.
         virtual auto validate_transaction(transaction::full_tx tx)
-            -> std::optional<validate_response> = 0;
+            -> std::optional<validate_response>
+            = 0;
     };
 }
 

src/uhs/twophase/locking_shard/interface.hpp

@@ -51,7 +51,8 @@ namespace cbdc::locking_shard {
         ///         txs in the input vector had their relevant input hashes
         ///         locked by the shard. Otherwise std::nullopt.
         virtual auto lock_outputs(std::vector<tx>&& txs, const hash_t& dtx_id)
-            -> std::optional<std::vector<bool>> = 0;
+            -> std::optional<std::vector<bool>>
+            = 0;
 
         /// Completes a previous lock operation by deleting input hashes and
         /// creating output hashes, or unlocking input hashes.

src/uhs/twophase/locking_shard/locking_shard.hpp

@@ -88,7 +88,7 @@ namespace cbdc::locking_shard {
         ///                     from the previous lock operation the shard
         ///                     should apply (`true`), and which it should
         ///                     cancel (`false`). Must have the same size and
-        ///                     order as txs from lock.
+        ///                      order as txs from lock.
         /// \param dtx_id distributed transaction ID of the previous lock
         ///               operation.
         /// \return true if the apply operation succeeded.

src/uhs/twophase/locking_shard/status_interface.hpp

@@ -29,15 +29,17 @@ namespace cbdc::locking_shard {
         /// \return true if the UHS ID is unspent, or std::nullopt if the query
         ///         failed.
         [[nodiscard]] virtual auto check_unspent(const hash_t& uhs_id)
-            -> std::optional<bool> = 0;
+            -> std::optional<bool>
+            = 0;
 
         /// Queries whether the given TX ID is confirmed in the cache of
         /// recently confirmed TX IDs.
         /// \param tx_id TX ID to query.
         /// \return true if the TX ID is present in the cache, or std::nullopt
         ///         if the query failed.
         [[nodiscard]] virtual auto check_tx_id(const hash_t& tx_id)
-            -> std::optional<bool> = 0;
+            -> std::optional<bool>
+            = 0;
     };
 }
 

src/util/raft/index_comparator.cpp

@@ -5,6 +5,7 @@
 
 #include "index_comparator.hpp"
 
+#include <cstdint>
 #include <cstring>
 #include <leveldb/slice.h>
 

src/util/rpc/async_server.hpp

@@ -127,9 +127,8 @@ namespace cbdc::rpc {
 
         using server_type = server<Request, Response, InBuffer, OutBuffer>;
 
-        static constexpr auto raw_mode
-            = std::is_same_v<Request,
-                             buffer> && std::is_same_v<Response, buffer>;
+        static constexpr auto raw_mode = std::is_same_v<Request, buffer>
+                                      && std::is_same_v<Response, buffer>;
     };
 
     /// \brief Asynchronous pass-through RPC server.

src/util/rpc/client.hpp

@@ -115,7 +115,8 @@ namespace cbdc::rpc {
         virtual auto call_raw(cbdc::buffer request_buf,
                               request_id_type request_id,
                               std::chrono::milliseconds timeout)
-            -> std::optional<response_type> = 0;
+            -> std::optional<response_type>
+            = 0;
 
         virtual auto call_raw(cbdc::buffer request_buf,
                               request_id_type request_id,

src/util/serialization/format.hpp

@@ -365,8 +365,8 @@ namespace cbdc {
         -> serializer& {
         using S = uint8_t;
         static_assert(
-            std::variant_size_v<std::remove_reference_t<decltype(var)>> < std::
-                numeric_limits<S>::max());
+            std::variant_size_v<std::remove_reference_t<decltype(var)>>
+            < std::numeric_limits<S>::max());
         auto idx = static_cast<S>(var.index());
         ser << idx;
         std::visit(
@@ -385,8 +385,8 @@ namespace cbdc {
                             serializer&> {
         using S = uint8_t;
         static_assert(
-            std::variant_size_v<std::remove_reference_t<decltype(var)>> < std::
-                numeric_limits<S>::max());
+            std::variant_size_v<std::remove_reference_t<decltype(var)>>
+            < std::numeric_limits<S>::max());
         S idx{};
         deser >> idx;
         auto var_idx = static_cast<size_t>(idx);