Skip to content

Commit c445941

Browse files
rimrakhimovk1rill-fedoseev
rimrakhimov
and
k1rill-fedoseev
authored
Update README for services (#864)
* Update Readme for the root directory - extract common information into root. Update Readme for smart-contract-verifier * Update envs table format * Add a link to swagger * Add info about env generation convention. Add a note about justfiles. Add a note about some projects do not utilizing '-logic' suffix * Fix using SMART_CONTRACT_VERIFIER instead of {SERVICE_NAME} in common-envs * Update smart-contract-verifier/README.md Co-authored-by: Kirill Fedoseev <[email protected]> * Update smart-contract-verifier/README.md Co-authored-by: Kirill Fedoseev <[email protected]> --------- Co-authored-by: Kirill Fedoseev <[email protected]>
1 parent a345d35 commit c445941

File tree

4 files changed

+183
-83
lines changed

4 files changed

+183
-83
lines changed

‎README.md

+50-3
Original file line numberDiff line numberDiff line change
@@ -21,16 +21,63 @@ A set of services used by [Blockscout](https://blockscout.com/) blockchain explo
2121

2222
## Services
2323

24-
1. [smart-contract-verifier](smart-contract-verifier/) - provides API for ethereum contract verification written in Solidity and Vyper
24+
1. [blockscout-ens](blockscout-ens) - indexed data of domain name service for blockscout instances.
25+
26+
1. [da-indexer](da-indexer) - collects blobs from different DA solutions (e.g, Celestia)
27+
28+
2. [eth-bytecode-db](eth-bytecode-db/) - Ethereum Bytecode Database. Cross-chain smart-contracts database used for automatic contracts verification
29+
30+
1. [proxy-verifier](proxy-verifier) - backend for the standalone multi-chain verification service
31+
32+
1. [scoutcloud](scoutcloud) - API to deploy and manage blockscout instances
2533

2634
2. [sig-provider](sig-provider/) - aggregator of ethereum signatures for transactions and events
2735

28-
3. [multichain-search](multichain-search/) - service for searching transactions, blocks, tokens, etc in all blockscout instances. Contains frontend and backend parts.
36+
3. [smart-contract-verifier](smart-contract-verifier/) - smart-contracts verification
37+
38+
1. [stats](stats) - service designed to calculate and present statistical information from a Blockscout instance
39+
40+
1. [user-ops-indexer](user-ops-indexer) - service designed to index, decode and serve user operations as per the ERC-4337 standard
2941

3042
4. [visualizer](visualizer/) - service for evm visualization such as:
3143
1. Solidity contract visualization using [sol2uml](https://www.npmjs.com/package/sol2uml)
3244

33-
5. [eth-bytecode-db](eth-bytecode-db/) - Ethereum Bytecode Database. Verifies smart-contracts and searches for the sources via bytecodes
45+
## Running and configuring services
46+
47+
Services are distributed as docker images. For each service you can find information about packages and their recent releases
48+
inside service directories.
49+
50+
You can configure your app by passing necessary environment variables when starting the container.
51+
Configuration variables common for all services can be found [here](docs/common-envs.md).
52+
See full list of ENVs and their description inside service directories.
53+
54+
```shell
55+
docker run -p 8050:8050 --env-file <path-to-your-env-file> ghcr.io/blockscout/{service-name}:latest
56+
```
57+
58+
Alternatively, you can build your own docker images or compile them directly from sources.
59+
Some of such options are described in [build](docs/build.md).
60+
61+
## Project Layouts
62+
63+
Most of the projects consist of 3 main parts:
64+
1. `{service-name}-proto` - defines the gRPC proto file with all API related data.
65+
Defines mapping HTTP/JSON requests and their parameters to those gRPC methods.
66+
2. `{service-name}-logic` - the crate with the implementation of the main business logic.
67+
68+
_Note: previously the logic crate was named as `{service-name}`;
69+
some services still use that convention_
70+
71+
3. `{service-name}-server` - initialize the server using the defined API.
72+
Using the methods from “{service-name}-logic” to handle incoming requests.
73+
74+
The separation on "logic" and "server" crates is designed to separate functional and transport layers.
75+
For now, "server" crates contain gRPC and HTTP as the transport layer.
76+
It was assumed, that users may want to implement their own APIs, for which the library with functional logic might be used.
77+
78+
Crates that require database connection may also have additional sea-orm defined crates:
79+
1. `{service-name}-migration` - contains migrations for the database
80+
2. `{service-name}-entity` - contains the entity files generated from the schema
3481

3582
## Contributing
3683

‎docs/build.md

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Build
2+
3+
## Using docker
4+
Each service contains a Dockerfile in the service root directory.
5+
6+
## Building from source
7+
8+
### Preparation
9+
10+
1. Install rustup from [[rustup.rs](https://rustup.rs/)].
11+
12+
2. Make sure that openssl is installed:
13+
14+
- macOS:
15+
16+
`$ brew install [email protected]`
17+
18+
- Arch Linux
19+
20+
`$ sudo pacman -S pkg-config openssl`
21+
22+
- Debian and Ubuntu
23+
24+
`$ sudo apt-get install pkg-config libssl-dev`
25+
26+
- Fedora
27+
28+
`$ sudo dnf install pkg-config openssl-devel`
29+
30+
3. Make sure protobuf is installed and the version (`$ protoc --version`) is at least `v3.15.0`.
31+
32+
If protobuf version is too old, you may see the following error: `Explicit 'optional' labels are disallowed in the Proto3 syntax.`
33+
34+
4. Install [`protoc-gen-openapiv2`](https://github.com/grpc-ecosystem/grpc-gateway#installation).
35+
You may find useful the following [Action](https://github.com/blockscout/blockscout-rs/blob/main/.github/actions/deps/action.yml#L21)
36+
we use in our Github pipeline.
37+
38+
If not installed, you may see the following error: `Error: Custom { kind: Other, error: "protoc failed: Unknown flag: --openapiv2_opt\n" }`
39+
40+
### Build
41+
1. Clone the repository and enter the service directory
42+
```shell
43+
git clone [email protected]:blockscout/blockscout-rs.git
44+
cd blockscout-rs/{service-name}
45+
```
46+
47+
2. Build the release version:
48+
```shell
49+
cargo build --release --bin {service-name}-server
50+
```
51+
52+
3. You can find the built binary in `target/release/` folder.
53+
54+
## Installing through cargo
55+
56+
Another way to install the binary without cloning the repository is to use cargo straightway:
57+
58+
```console
59+
cargo install --git https://github.com/blockscout/blockscout-rs {service-name}-server
60+
```
61+
62+
In that case, you can run the binary using just `{service-name}-server`.
63+
64+
## Justfile
65+
66+
Most of the services contain `justfile`s inside root directories (https://github.com/casey/just).
67+
Sometimes using that during development may make your a little easier.

‎docs/common-envs.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Common Environment Variables
2+
3+
By convention each env has a `{SERVICE_NAME}` (e.g, `{SMART_CONTRACT_VERIFIER}`) as a prefix,
4+
and uses `__` as a separator between internal identifiers.
5+
6+
| Variable | Required | Description | Default value |
7+
|----------------------------------------------------------------|----------|----------------------------------------------------------------------------------|------------------------------------------|
8+
| `{SERVICE_NAME}__SERVER__HTTP__ENABLED` | | Enable HTTP API server | `true` |
9+
| `{SERVICE_NAME}__SERVER__HTTP__ADDR` | | HTTP API listening interface | `0.0.0.0:8050` |
10+
| `{SERVICE_NAME}__SERVER__HTTP__MAX_BODY_SIZE` | | Max HTTP body size for incoming API requests | `2097152` |
11+
| `{SERVICE_NAME}__SERVER__HTTP__CORS__ENABLED` | | Enable CORS middleware for incoming HTTP requests | `false` |
12+
| `{SERVICE_NAME}__SERVER__HTTP__CORS__ALLOWED_ORIGIN` | | Origins allowed to make requests | |
13+
| `{SERVICE_NAME}__SERVER__HTTP__CORS__ALLOWED_METHODS` | | A list of methods which allowed origins can perform | `PUT, GET, POST, OPTIONS, DELETE, PATCH` |
14+
| `{SERVICE_NAME}__SERVER__HTTP__CORS__ALLOWED_CREDENTIALS` | | Allow users to make authenticated requests | `true` |
15+
| `{SERVICE_NAME}__SERVER__HTTP__CORS__MAX_AGE` | | Sets a maximum time (in seconds) for which this CORS request may be cached | `3600` |
16+
| `{SERVICE_NAME}__SERVER__HTTP__CORS__BLOCK_ON_ORIGIN_MISMATCH` | | Configures whether requests should be pre-emptively blocked on mismatched origin | `false` |
17+
| `{SERVICE_NAME}__SERVER__GRPC__ENABLED` | | Enable GRPC API server | `false` |
18+
| `{SERVICE_NAME}__SERVER__GRPC__ADDR` | | GRPC API listening interface | `0.0.0.0:8051` |
19+
| `{SERVICE_NAME}__METRICS__ENABLED` | | Enable metrics collection endpoint | `false` |
20+
| `{SERVICE_NAME}__METRICS__ADDR` | | Metrics collection listening interface | `0.0.0.0:6060` |
21+
| `{SERVICE_NAME}__METRICS__ROUTE` | | Metrics collection API route | `/metrics` |
22+
| `{SERVICE_NAME}__TRACING__ENABLED` | | Enable tracing log module | `true` |
23+
| `{SERVICE_NAME}__TRACING__FORMAT` | | Tracing format. `default` / `json` | `default` |
24+
| `{SERVICE_NAME}__JAEGER__ENABLED` | | Enable Jaeger tracing | `false` |
25+
| `{SERVICE_NAME}__JAEGER__AGENT_ENDPOINT` | | Jaeger tracing listening interface | `localhost:6831` |

‎smart-contract-verifier/README.md

+41-80
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,43 @@
11
# <h1 align="center"> Smart-contract Verifier </h1>
22

3-
**Smart-contract-verifier** - service for verification of EVM based contracts. Ideologically, it accepts bytecode to be verified and potential source files as input and returns whether those files and bytecode correspond to each other.
4-
5-
The service consists of 2 parts, a verification library and a transport layer that serves requests:
6-
7-
+ [smart-contract-verifier](./smart-contract-verifier) - implements actual verification logic as a library and exposes an interface to be used by the transport layer;
8-
+ A transport layer that implements some APIs over the service ([smart-contract-verifier-server](./smart-contract-verifier-server/)).
9-
10-
For now, GRPC and REST API over HTTP services are available as the transport layer. However, the transport protocol is not limited to our implementation, and you could implement your own APIs using the library crate.
11-
12-
## Build
13-
There are several ways to run the service discussed below.
14-
15-
**Note:** for our description we will use an HTTP/GRPC server implementation; in case of a custom API implementation, you should change `smart-contract-verifier-server` to your values.
16-
17-
18-
### Using docker
19-
You can build the provided sources using [Dockerfile](./smart-contract-verifier-server/Dockerfile) or [docker-compose](./smart-contract-verifier-server/docker-compose.yml) files.
20-
21-
Alternatively, you can use docker images from our [registry](https://github.com/blockscout/blockscout-rs/pkgs/container/smart-contract-verifier)
22-
23-
### Building from source
24-
25-
**Preparation:**
26-
27-
1. Install rustup from rustup.rs.
28-
29-
1. Make sure that openssl is installed:
30-
31-
- macOS:
32-
33-
`$ brew install [email protected]`
34-
35-
- Arch Linux
36-
37-
`$ sudo pacman -S pkg-config openssl`
38-
39-
- Debian and Ubuntu
40-
41-
`$ sudo apt-get install pkg-config libssl-dev`
42-
43-
- Fedora
44-
45-
`$ sudo dnf install pkg-config openssl-devel`
46-
47-
1. Make sure protobuf is installed and the version (`$ protoc --version`) is at least `v3.15.0`.
48-
49-
If protobuf version is too old, you may see the following error: `Explicit 'optional' labels are disallowed in the Proto3 syntax.`
50-
51-
1. Install [`protoc-gen-openapiv2`](https://github.com/grpc-ecosystem/grpc-gateway#installation).
52-
You may find useful the following [Action](https://github.com/blockscout/blockscout-rs/blob/main/.github/actions/deps/action.yml#L21)
53-
we use in our Github pipeline.
54-
55-
If not installed, you may see the following error: `Error: Custom { kind: Other, error: "protoc failed: Unknown flag: --openapiv2_opt\n" }`
56-
57-
---
58-
59-
Build blockscout smart-contract-verifier:
60-
61-
```console
62-
git clone [email protected]:blockscout/blockscout-rs.git
63-
cd blockscout-rs/smart-contract-verifier
64-
cargo build --release --bin smart-contract-verifier-server
65-
```
66-
67-
You can find the built binary in `target/release/` folder.
68-
69-
### Installing through cargo
70-
71-
Another way to install the binary without cloning the repository is to use cargo straightway:
72-
73-
```console
74-
cargo install --git https://github.com/blockscout/blockscout-rs smart-contract-verifier-server
75-
```
76-
77-
In that case, you can run the binary using just `smart-contract-verifier-server`.
78-
79-
## Start
80-
For the details of how to run the service, go into corresponding
81-
transport protocol layer description:
82-
- [smart-contract-verifier-server](./smart-contract-verifier-server/README.md)
3+
**Smart-contract verifier** is a service for verifying EVM-based contracts. The primary function of this service is to receive bytecode and potential source files as inputs and determine whether the files and the bytecode correspond to each other.
4+
5+
This service serves as the core component for all activities related to smart-contract verification in BlockScout. It is essential for enabling smart-contract verification functionality on your instance.
6+
7+
## Requirements
8+
No additional dependencies
9+
10+
## How to enable
11+
Set the following ENVs on blockscout instance:
12+
- `MICROSERVICE_SC_VERIFIER_ENABLED=true`
13+
- `MICROSERVICE_SC_VERIFIER_URL={service_url}`
14+
- `MICROSERVICE_SC_VERIFIER_TYPE=sc_verifier`
15+
16+
## Envs
17+
Here, we describe variables specific to this service. Variables common to all services can be found [here](../docs/common-envs.md).
18+
19+
[anchor]: <> (anchors.envs.start)
20+
21+
| Variable | Required | Description | Default value |
22+
|----------------------------------------------------------------|----------|-------------------------------------------------------------------------|------------------------------------------------------------------------------|
23+
| `SMART_CONTRACT_VERIFIER__SOLIDITY__ENABLED` | | Enable Solidity verification endpoints | `true` |
24+
| `SMART_CONTRACT_VERIFIER__SOLIDITY__FETCHER__LIST__LIST_URL` | | Url that contains a list available Solidity compilers | `https://solc-bin.ethereum.org/linux-amd64/list.json` |
25+
| `SMART_CONTRACT_VERIFIER__SOLIDITY__REFRESH_VERSIONS_SCHEDULE` | | Cron-format schedule to update the list of available Solidity compilers | `0 0 * * * * *` |
26+
| `SMART_CONTRACT_VERIFIER__SOLIDITY__COMPILERS_DIR` | | Directory where Solidity compilers will be downloaded | `/tmp/solidity-compilers` |
27+
| `SMART_CONTRACT_VERIFIER__VYPER__ENABLED` | | Enable Vyper verification endpoints | `true` |
28+
| `SMART_CONTRACT_VERIFIER__VYPER__FETCHER__LIST__LIST_URL` | | Url that contains a list of available Vyper compilers | `https://raw.githubusercontent.com/blockscout/solc-bin/main/vyper.list.json` |
29+
| `SMART_CONTRACT_VERIFIER__VYPER__REFRESH_VERSIONS_SCHEDULE` | | Cron-format schedule to update the list of available Vyper compilers | `0 0 * * * * *` |
30+
| `SMART_CONTRACT_VERIFIER__VYPER__COMPILERS_DIR` | | Directory where Vyper compilers will be downloaded | `/tmp/vyper-compilers` |
31+
| `SMART_CONTRACT_VERIFIER__SOURCIFY__ENABLED` | | Enable Soucify verification endpoint | `true` |
32+
| `SMART_CONTRACT_VERIFIER__SOURCIFY__API_URL` | | Sourcify API url | `https://sourcify.dev/server/` |
33+
| `SMART_CONTRACT_VERIFIER__SOURCIFY__VERIFICATION_ATTEMPTS` | | Number of attempts the server makes to Sourcify API. Must be at least 1 | `3` |
34+
| `SMART_CONTRACT_VERIFIER__SOURCIFY__REQUEST_TIMEOUT` | | Timeout in seconds for a single request to Sourcify API | `15` |
35+
| `SMART_CONTRACT_VERIFIER__COMPILERS__MAX_THREADS` | | Maximum number of concurrent compilations | `8` |
36+
37+
[anchor]: <> (anchors.envs.end)
38+
39+
## Links
40+
- Demo - https://http.sc-verifier.services.blockscout.com
41+
- [Swagger](https://blockscout.github.io/swaggers/services/smart-contract-verifier/index.html)
42+
- [Packages](https://github.com/blockscout/blockscout-rs/pkgs/container/smart-contract-verifier)
43+
- [Releases](https://github.com/blockscout/blockscout-rs/releases?q=smart-contract-verifier&expanded=true)

0 commit comments

Comments
 (0)