Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: improve README docs with project and service structure #155

Merged
merged 3 commits into from
Apr 16, 2024
Merged

docs: improve README docs with project and service structure #155

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8d5b3ab
Improve `README` docs
acuarica Apr 15, 2024
bd72ec6
Add more docs
acuarica Apr 15, 2024
f7ce8b3
Reorder sections
acuarica Apr 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 105 additions & 55 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,22 @@ Tools for verifying Hedera smart contracts using standard open source libraries.

## Prerequisites

Install:
Install

- [node](https://nodejs.org/en/about/)
- [npm](https://www.npmjs.com/)
- [`node`](https://nodejs.org/en/about/) and [`npm`](https://www.npmjs.com/)
- [Docker](https://docs.docker.com/engine/reference/commandline/docker/)

Make sure the repository submodule h5ai-nginx is present:
Make sure the repository submodule `h5ai-nginx` is present

- `git submodule update --init --recursive`
```sh
git submodule update --init --recursive
```

Apply the Hedera patch to the `h5ai-nginx` submodule (execute this only once).
Apply the Hedera patch to the `h5ai-nginx` submodule **(execute this only once)**

- `./scripts/hedera-apply-h5ai-nginx-patch.sh`
```sh
./scripts/hedera-apply-h5ai-nginx-patch.sh
```

## Local build for development

Expand All @@ -46,18 +49,58 @@ From the root of the project workspace:

### Sanity check the configuration

This assumes the default ports (per .env.dev.hedera) are used:
This assumes the default ports (per `environments/.env.dev.hedera`) are used:

- `Open http://localhost:10000`. This should open the Repository select-contract-form. The options available for the Chain should be the 3 Hedera networks (mainnet, testnet, previewnet).
- `Open http://localhost:5002/chains`. This should return a JSON value containing the 3 Hedera networks
- `Open http://localhost:5555/files/contracts/296`. This should return a JSON value containing the addresses of all contracts verified on testnet (or report error "_Contracts have not been found!_" if nothing has been verified yet)
- `Open http://localhost:3000`. This should bring up the Verifier page.
- Open <http://localhost:10000>.
This should open the Repository `select-contract-form`. The options available for the Chain should be the 3 Hedera networks (mainnet, testnet, previewnet).
- Open <http://localhost:5002/chains>.
This should return a JSON value containing the 3 Hedera networks
- Open <http://localhost:5555/files/contracts/296>.
This should return a JSON value containing the addresses of all contracts verified on testnet (or report error `"Contracts have not been found!"` if nothing has been verified yet)
- Open <http://localhost:3000>.
This should bring up the Verifier page.

## Use Docker images

You can either use pre-built Docker images from the GitHub container repository
or build the images locally.

Hedera verification service uses 3 images

- [`server`](#server-service) **[Verifier Server]**. This service provides the actual verification of Smart Contracts.
Its main task is to compile input Solidity sources and check compiler results.
It checks compilers results against the bytecode retrieved from an Ethereum-compatible network, _e.g._, JSON-RPC Relay.
Other services interact with it through its REST API.
You can inspect the endpoints provided by visiting `/api-docs` (OpenAPI generated docs) on the `server`, _e.g._, <https://server-verify.hashscan.io/api-docs/>.
A successful verification stores the contracts sources under _Repository Volume_.
- [`repository`](#repository-service) **[Repository]**. Provides a verified Smart Contract front end lookup and explorer. It reads verified smart contracts from the _Repository Volume_.
- [`ui`](#ui-service) **[Verifier UI]**. A user frontend to verify and lookup Smart Contracts.

> [!NOTE]
> Note that unlike Sourcify, we do not use the [`monitor`](https://docs.sourcify.dev/docs/running-monitor/) service given that we do not use IPFS verification.

```mermaid
C4Container
title Container Diagram for Smart Contract Verification System

Container_Boundary(scvs, "Smart Contract Verification System") {
Container(ui, "Verifier UI", "JavaScript, React", "Customized Sourcify Verifier front-end")
Container(server, "Verifier Server", "JavaScript, Node", "Provides the REST API that enables verification of Smart Contracts, includes a Solidity compiler")
Container(repo, "Repository", "nginx", "Provides a front-end to lookup and view verified Smart Contracts")
ContainerDb_Ext(repo_vol, "Repository Volume", "File System Volume", "Stores verified smart contracts")
}

System_Ext(eth, "Ethereum-compatible Network (json-rpc-relay)", "Provides the source of truth to fetch Smart Contract bytecode")

Rel(server, eth, "Uses", "JSON-RPC `eth_getCode`")
UpdateRelStyle(server, eth, $offsetY="-50", $offsetX="-140")

Rel(ui, server, "Uses", "REST")

Rel(server, repo_vol, "Mounts, read&write", "/tmp/sourcify/repository")
Rel_Back(repo, repo_vol, "Mounts, read", "/data")
```

### Set-up

1. `cp environments/.env.docker.hedera environments/.env`
Expand All @@ -83,65 +126,45 @@ or build the images locally.
### Run

1. Run `docker-compose -f environments/docker-compose-hedera.yaml up -d repository server ui`
2. `Open http://localhost:1234` to bring up the Verifier page.
2. Open <http://localhost:1234> to bring up the Verifier page.

### Stop

- Run `docker-compose -f environments/docker-compose-hedera.yaml down`

### Reset network

- To reset **testnet**:
`docker exec server-latest /home/app/hedera-reset-docker.sh testnet`

- To reset **previewnet**:
`docker exec server-latest /home/app/hedera-reset-docker.sh previewnet`
### Reset networks

## Test

### Basic non-regression server test

1. Make sure the variables HEDERA_NETWORK, OPERATOR_ACCOUNT_ID and OPERATOR_KEY are defined in `environments/.env`
2. Run `hedera start --network local -d`
3. Run `npm run server:start`
4. Run `npm run test:hedera`

Moreover, to run the server tests against a local Ganache instance run
To reset **testnet**

```sh
npm run test:server
docker exec server-latest /home/app/hedera-reset-docker.sh testnet
```

> Note that there is no need to spin up a Ganache instance separately.
> It is automatically started and stopped by the server test.
>
> We use the `USE_LOCAL_NODE` environment variable to enable Ganache as a local chain.

### Unit Tests
To reset **previewnet**

Under `packages/` there are dependencies that are used by the verification services and need to be unit-tested separately.
To test them run `cd packages/<package> && npm run test`.
The corresponding job that runs these tests in CI is `unit-tests`.
```sh
docker exec server-latest /home/app/hedera-reset-docker.sh previewnet
```

## Configuration

The following tables describe the configuration items used by the different services

### _ui_ module
### _ui_ service

The _ui_ service is a single page application based on React. As such, it cannot be configured by environment variables at runtime.
It reads it configuration from a file located at the following path: `/usr/share/nginx/html/config.json`
In deployment, the actual configuration can be provided to the container via a mount point.

Example contents for `config.json`:
Example contents for `config.json`

```config.json
```json
{
"SERVER_URL": "https://server.sourcify-integration.hedera-devops.com",
"REPOSITORY_SERVER_URL": "https://repository.sourcify-integration.hedera-devops.com",
"EXPLORER_URL": "http://localhost:8080",
"BRAND_PRODUCT_LOGO_URL": "http://example.com/path/to/my-logo.jpg",
"TERMS_OF_SERVICE_URL": http://example.com/path/to/my-terms.html"",
"TERMS_OF_SERVICE_URL": "http://example.com/path/to/my-terms.html",
"REMOTE_IMPORT": false,
"GITHUB_IMPORT": false,
"CONTRACT_IMPORT": false,
Expand All @@ -151,7 +174,7 @@ Example contents for `config.json`:
}
```

The following properties can be provided in config.json
The following properties can be provided in `config.json`

| Name | Description |
|-----------------------------|-------------------------------------------------------------------------------------------------|
Expand All @@ -173,7 +196,7 @@ The favicon may be modified by providing alternative versions of the 3 following

This can be done for instance by adding the following to the definition of the `ui` service in the `docker-compose` yaml file used:

```
```yaml
volumes:
- type: bind
source: ./manifest.json
Expand All @@ -189,7 +212,7 @@ volumes:
target: /usr/share/nginx/html/favicon-32x32.png`
```

### _server_ module
### _server_ service

The following environment variables are needed by the _server_ at runtime:

Expand All @@ -209,7 +232,7 @@ The following environment variables are needed by the _server_ at runtime:
| `TESTING` | false | DO NOT CHANGE |
| `TAG` | latest | Added to the docker image tags (e.g. ui-latest, server-latest, repository-latest) |

### _repository_ module
### _repository_ service

The _repository_ service encompasses a single page application based on React and a web server.

Expand All @@ -222,13 +245,40 @@ even though the only useful item for the _repository_ is the following:

| Name | Example value | Description |
|-----------------------------------|-----------------------|----------------------------------------------------------------------------------------|
| `REPOSITORY_PATH` | ../../data/repository | Path of the contract repository on the host. |
| `REPOSITORY_SERVER_EXTERNAL_PORT` | 10000 | HTTP port exposed by container |
| `UI_DOMAIN_NAME` | example.com | Fully qualified domain name of the host running the ui |
| `TESTING` | false | DO NOT CHANGE |
| `TAG` | latest | Added to the docker image tags (e.g. ui-latest, server-latest, repository-latest) |
| `REPOSITORY_PATH` | `../../data/repository` | Path of the contract repository on the host. |
| `REPOSITORY_SERVER_EXTERNAL_PORT` | `10000` | HTTP port exposed by container |
| `UI_DOMAIN_NAME` | `example.com` | Fully qualified domain name of the host running the ui |
| `TESTING` | `false` | DO NOT CHANGE |
| `TAG` | `latest` | Added to the docker image tags (e.g. ui-latest, server-latest, repository-latest) |

## Test

### Basic non-regression server test

1. Make sure the variables `HEDERA_NETWORK`, `OPERATOR_ACCOUNT_ID` and `OPERATOR_KEY` are defined in `environments/.env`
2. Run `hedera start --network local -d`
3. Run `npm run server:start`
4. Run `npm run test:hedera`

Moreover, to run the server tests against a local Ganache instance run

```sh
npm run test:server
```

> [!NOTE]
> Note that there is no need to spin up a Ganache instance separately.
> It is automatically started and stopped by the server test.
>
> We use the `USE_LOCAL_NODE` environment variable to enable Ganache as a local chain.

### Unit Tests

Under `packages/` there are dependencies that are used by the verification services and need to be unit-tested separately.
To test them run `cd packages/<package> && npm run test`.
The corresponding job that runs these tests in CI is `unit-tests`.

## Release
## Releases

The repo has Github Actions automation to generate docker images based on the latest changes in a branch.
To initiate the release for version `x.y.z` simply checkout branch `release/x.y` and run the following commands
Expand Down Expand Up @@ -260,6 +310,6 @@ to [[email protected]](mailto:[email protected]).

[Apache License 2.0](LICENSE)

# 🔐 Security
## 🔐 Security

Please do not file a public ticket mentioning the vulnerability. Refer to the security policy defined in the [SECURITY.md](https://github.com/hashgraph/hedera-sourcify/blob/main/SECURITY.md).
Loading