Skip to content

Commit

Permalink
fix: reconcile docs for rename and updates
Browse files Browse the repository at this point in the history
Signed-off-by: Sam Stuewe <[email protected]>
  • Loading branch information
HalosGhost committed Jul 31, 2023
1 parent eefcdf2 commit 6ed25e4
Show file tree
Hide file tree
Showing 13 changed files with 75 additions and 65 deletions.
2 changes: 1 addition & 1 deletion docs/parsec_architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
83 changes: 45 additions & 38 deletions docs/parsec_user_guide.md
Original file line number Diff line number Diff line change
@@ -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/`.
Expand All @@ -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).

Expand All @@ -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:
Expand All @@ -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.

Expand All @@ -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 |
| --------------- | ------------------------------------------|
Expand All @@ -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"))});
{
...
}
Expand All @@ -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!
12 changes: 3 additions & 9 deletions scripts/deploy.js
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand All @@ -21,3 +14,4 @@ async function main() {
console.error(error);
process.exit(1);
});

7 changes: 5 additions & 2 deletions scripts/hardhat.config.js
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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"]
}
}
Expand Down
2 changes: 1 addition & 1 deletion src/parsec/agent/runners/lua/server.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
6 changes: 4 additions & 2 deletions src/uhs/sentinel/interface.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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;
};
}

Expand Down
3 changes: 2 additions & 1 deletion src/uhs/twophase/locking_shard/interface.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion src/uhs/twophase/locking_shard/locking_shard.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
6 changes: 4 additions & 2 deletions src/uhs/twophase/locking_shard/status_interface.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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;
};
}

Expand Down
1 change: 1 addition & 0 deletions src/util/raft/index_comparator.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@

#include "index_comparator.hpp"

#include <cstdint>
#include <cstring>
#include <leveldb/slice.h>

Expand Down
5 changes: 2 additions & 3 deletions src/util/rpc/async_server.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 2 additions & 1 deletion src/util/rpc/client.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
8 changes: 4 additions & 4 deletions src/util/serialization/format.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand All @@ -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);
Expand Down

0 comments on commit 6ed25e4

Please sign in to comment.