Skip to content

Commit d449090

Browse files
kdimentionaltreekdimentionaltree
committed
updated readme
1 parent c945eaf commit d449090

6 files changed

Lines changed: 202 additions & 56 deletions

File tree

‎Dockerfile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ COPY CMakeLists.txt /app/CMakeLists.txt
2727
WORKDIR /app/build
2828
RUN cmake -DCMAKE_BUILD_TYPE=Release -DPORTABLE=1 .. && make -j$(nproc) && make install
2929
COPY config/static_config.yaml /app/static_config.yaml
30+
31+
RUN apt update && apt install -y gdb && mkdir -p /root/.config/gdb
32+
RUN echo "set auto-load safe-path /" > /root/.config/gdb/gdbinit
3033
ENTRYPOINT [ "ton-http-api-cpp" ]
3134

3235
# FROM ubuntu:24.04

‎README.md‎

Lines changed: 108 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,114 @@
1-
# TONlib Multiclient
1+
# TON HTTP API C++
22

3-
The TONlib Multi Client is crafted with modern C++ to serve as a robust and flexible tool for seamless communication with multiple TON blockchain lite servers. It's engineered for efficiency, allowing for streamlined request handling across a diverse array of server endpoints.
3+
[![Docker - Image Version](https://img.shields.io/docker/v/toncenter/ton-http-api-cpp?label=docker&sort=semver)](https://hub.docker.com/repository/docker/toncenter/ton-http-api-cpp)
4+
[![Docker - Image Size](https://img.shields.io/docker/image-size/toncenter/ton-http-api-cpp?label=docker&sort=semver)](https://hub.docker.com/repository/docker/toncenter/ton-http-api-cpp)
5+
![Github last commit](https://img.shields.io/github/last-commit/toncenter/ton-http-api-cpp)
46

5-
## Features
6-
7-
- Multi-threaded Design: Enhances the ability to handle concurrent connections and requests efficiently.
8-
- Flexible Request Handling: Supports a variety of request types, ensuring robust interaction with blockchain lite servers.
9-
- Dynamic Request Creation: Allows for the creation of customizable requests, enabling tailored blockchain queries and operations.
10-
- Advanced Configuration Options: Offers detailed settings for requests, including server selection and archival data queries, providing users with control over their blockchain interactions.
11-
12-
## Requirements
13-
14-
- CMake: Version 3.15 or newer.
15-
- C++ Compiler: Must support the C++20 standard or more recent.
16-
- Python: Version 3.9 or above is required for utilizing Python bindings.
17-
18-
## Usage
19-
20-
Examples could be found in the `examples` directory.
21-
22-
## Building
7+
The HTTP API C++ for [The Open Network](https://ton.org) is a real-time API to connect to TON blockchain lite servers via ADNL protocol and enable access to lite servers through HTTP requests.
238

24-
```bash
25-
mkdir build
26-
cd build
27-
cmake ..
28-
cmake --build .
29-
```
9+
This service is the improved version of original [TON HTTP API](https://github.com/toncenter/ton-http-api), written entirely in C++ to achieve outstanding performance and effecient comnsuming of hardware resources.
3010

31-
Build with Python bindings, pass `-DPY_TONLIB_MULTICLIENT:BOOL=TRUE` to CMake:
3211

33-
```bash
34-
cmake -DPY_TONLIB_MULTICLIENT:BOOL=TRUE ..
35-
cmake --build .
36-
```
37-
38-
To use built python binding you need to copy `tonlib_multiclient` dynamic lib (.so) from `build/py` directory to your python project.
39-
```bash
40-
cp build/py/tonlib_multiclient.so /path/to/your/python/project
41-
```
42-
43-
## Requests
44-
45-
### Request<T>
46-
This structure is suitable for general request operations where the response type is known and directly utilized.
47-
48-
### RequestFunction<T>
49-
A specialized version of Request for cases where `TonlibClient::make_request` cannot process the request (`raw_getAccountState` etc).
50-
51-
### RequestCallback
52-
Designed for advanced use cases where the user must initialize and manage the response through your own global callback. Requires explicit setup for callback handling.
12+
## Features
5313

54-
### RequestJson
55-
Enables sending requests in raw JSON format, requiring minimal configuration besides the JSON string itself and the standard request parameters.
14+
TON HTTP API C++ provides following features:
15+
* Load balances requests to TON nodes
16+
* Checks availability of Lite Servers, disables unavailable and out-of-synced nodes.
17+
* Additionally parses data returned by original TONLib.
18+
* Based on [userver](https://github.com/userver-framework/userver), service provides detailed and Prometheus-compatible usage statistics.
19+
20+
21+
### Key differences from [toncenter/ton-http-api](https://github.com/toncenter/ton-http-api)
22+
23+
* C++ version consumes significantly less CPU and memory resources.
24+
* C++ version uses single instance of TONlib for each Lite server, meanwhile Python version TONLib instances number for each Lite server was equal to number of Gunicorn workers. This significantly decreases the number of healthcheck requests to Lite servers.
25+
* Cache now is integrated in service, no separate Redis is required to enable caching feature.
26+
27+
28+
## Hardware Requirements
29+
30+
- OS: Linux or MacOS (Windows is not supported).
31+
- CPU: 2 vCPU, x86_64 or arm64 architecture.
32+
- RAM: minimum 2GB, 8GB recommended for caching.
33+
34+
## Deploy
35+
36+
There are two main ways to run TON HTTP API:
37+
- __Docker Compose__: flexible configuration, recommended for production environments, works on any x86_64 and arm64 OS with Docker available.
38+
- __Local__ *(experimental)*: only for development purposes.
39+
40+
### Docker Compose
41+
42+
- (First time) Install required tools: `docker`, `docker-compose`, `curl`.
43+
- For Ubuntu: run `scripts/setup.sh` from the root of the repo.
44+
- For MacOS and Windows: install [Docker Desktop](https://www.docker.com/products/docker-desktop/).
45+
- **Note:** we recommend to use Docker Compose V2.
46+
- Download TON configuration files to private folder:
47+
```bash
48+
mkdir private
49+
curl -sL https://ton-blockchain.github.io/global.config.json > private/mainnet.json
50+
curl -sL https://ton-blockchain.github.io/testnet-global.config.json > private/testnet.json
51+
```
52+
- Copy service configuration file and adjust params:
53+
```bash
54+
cp config/config_vars.yaml private/config_vars.yaml
55+
nano private/config_vars.yaml
56+
```
57+
- To run testnet version or connect to your private TON node, please specify:
58+
```
59+
export THACPP_GLOBAL_CONFIG_PATH=private/testnet.json
60+
# or
61+
echo "THACPP_GLOBAL_CONFIG_PATH=private/testnet.json" > .env
62+
- Pull or build docker image:
63+
```bash
64+
docker compose pull
65+
# or
66+
docker compose build
67+
```
68+
- Run service:
69+
```bash
70+
docker compose up -d
71+
# or
72+
docker compose up
73+
```
74+
- Additionally check service logs:
75+
```bash
76+
docker compose logs http-api-cpp
77+
# or
78+
docker compose logs -n 100 http-api-cpp
79+
# or
80+
docker compose logs -f -n 100 http-api-cpp
81+
```
82+
83+
### Local run
84+
85+
- Install dependencies:
86+
- For Ubuntu:
87+
```bash
88+
apt update -y
89+
apt install -y wget curl build-essential cmake clang openssl libssl-dev zlib1g-dev gperf wget git ninja-build libsodium-dev libmicrohttpd-dev liblz4-dev pkg-config autoconf automake libtool libjemalloc-dev lsb-release software-properties-common gnupg libabsl-dev libbenchmark-dev libboost-context1.83-dev libboost-coroutine1.83-dev libboost-filesystem1.83-dev libboost-iostreams1.83-dev libboost-locale1.83-dev libboost-program-options1.83-dev libboost-regex1.83-dev libboost-stacktrace1.83-dev libboost1.83-dev libbson-dev libbz2-dev libc-ares-dev libcctz-dev libcrypto++-dev libcurl4-openssl-dev libdouble-conversion-dev libev-dev libfmt-dev libgflags-dev libgmock-dev libgtest-dev libhiredis-dev libidn11-dev libjemalloc2 libjemalloc-dev libkrb5-dev libldap2-dev liblz4-dev libnghttp2-dev libpugixml-dev libsnappy-dev libsasl2-dev libssl-dev libxxhash-dev libyaml-cpp0.8 libyaml-cpp-dev libzstd-dev libssh2-1-dev netbase python3-dev python3-jinja2 python3-venv python3-yaml ragel yasm zlib1g-dev liblzma-dev libre2-dev clang-format ccache gcc g++ gdb
90+
91+
# for ubuntu 22.04 check https://userver.tech/de/d9c/md_en_2deps_2ubuntu-22_804.html
92+
```
93+
94+
- For MacOS:
95+
```bash
96+
brew install boost@1.89 c-ares ccache cctz clang-format clickhouse-cpp cmake coreutils cryptopp cyrus-sasl fmt gdb git google-benchmark googletest hiredis icu4c jemalloc krb5 libev librdkafka mariadb mongo-c-driver@1 nghttp2 ninja openldap openssl postgresql@16 pugixml rocksdb unixodbc yaml-cpp zlib sqlite pkg-config automake libtool autoconf texinfo lz4 openssl@3 libsodium zlib libmicrohttpd
97+
```
98+
- Build:
99+
```bash
100+
mkdir build
101+
cd build
102+
cmake -DCMAKE_BUILD_TYPE=Release ..
103+
make -j$(nproc) ton-http-api-cpp
104+
# optional
105+
make install
106+
```
107+
- Run:
108+
```bash
109+
./build/ton-http-api/ton-http-api-cpp --config ./config/static_config.yaml --config_vars ./private/config_vars.yaml
110+
```
111+
112+
## License
113+
114+
TON HTTP API C++ is licensed under the MIT License.

‎config/config_vars.yaml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# TONlib parameters
2+
tonlib_config_path: /run/secrets/ton-global-config # TON global config path
3+
tonlib_keystore_path: /tmp/keystore/ # TONlib keystore path
4+
tonlib_boc_endpoints: [] # Endpoints to duplicate incoming BOCs
5+
tonlib_threads: 4 # number of threads for TONlib multiclient
6+
7+
server_port: 8081 # API port in container,
8+
# to change exposed port set THACPP_PORT env variable
9+
monitor_port: 8082 # Monitoring port in container,
10+
# to change exposed port set THACPP_MONITOR_PORT env variable
11+
12+
main_worker_threads: 4 # number of threads to serve HTTP requests
13+
fs_worker_threads: 1 # number of threads for I/O operations, f.e. logging
14+
http_worker_threads: 2 # number of threads for http client
15+
# to duplicate BOCs on external service
16+
17+
log_level: warning # api v2 log level
18+
log_path: "@stdout" # log destination, available options:
19+
# @stdout
20+
# @stderr
21+
# @null - don't log
22+
# /path/to/file - log to file
23+
# Note: if you log into file,
24+
# logs will be deleted after deploying new container
25+
log_format: json # logs format, one of `tskv`, `ltsv`, `json`
26+
system_log_level: warning # userver system logs
27+
system_log_path: "@null"
28+
29+
http_worker_user_agent: empty # http user agent to set in request to boc endpoint

‎config/static_config.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ components_manager:
66
fs-task-processor:
77
thread_name: blocking_thread
88
worker_threads: $fs_worker_threads
9-
worker_threads#fallback: 2
9+
worker_threads#fallback: 1
1010
monitor-task-processor:
1111
thread_name: monitor_thread
1212
worker_threads: $monitor_worker_threads
@@ -69,7 +69,7 @@ components_manager:
6969
pool-statistics-disable: false
7070
thread-name-prefix: http-client
7171
threads: $http_worker_threads
72-
threads#fallback: 8
72+
threads#fallback: 2
7373
fs-task-processor: fs-task-processor
7474
destination-metrics-auto-max-size: 100
7575
user-agent: $http_worker_user_agent

‎docker-compose.yaml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,16 @@ services:
66
dockerfile: Dockerfile
77
command: --config /app/static_config.yaml --config_vars /run/secrets/config-vars
88
ports:
9-
- ${SERVER_PORT:-8081}:8081
10-
- ${MONITOR_PORT:-8082}:8082
9+
- ${THACPP_PORT:-8081}:8081
10+
- ${THACPP_MONITOR_PORT:-8082}:8082
1111
restart: unless-stopped
1212
secrets:
1313
- ton-global-config
1414
- config-vars
1515
ulimits:
16-
memlock: 4194304
16+
memlock: -1
1717
secrets:
1818
ton-global-config:
19-
file: ${TON_BLOCKCHAIN_CONFIG_PATH:-private/private-config.json}
19+
file: ${THACPP_GLOBAL_CONFIG_PATH:-private/mainnet.json}
2020
config-vars:
21-
file: ${TON_SERVICE_CONFIG_PATH:-private/config-vars.yaml}
21+
file: ${THACPP_CONFIG_VARS:-private/config_vars.yaml}

‎examples/README.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# TONlib Multiclient
2+
3+
The TONlib Multi Client is crafted with modern C++ to serve as a robust and flexible tool for seamless communication with multiple TON blockchain lite servers. It's engineered for efficiency, allowing for streamlined request handling across a diverse array of server endpoints.
4+
5+
## Features
6+
7+
- Multi-threaded Design: Enhances the ability to handle concurrent connections and requests efficiently.
8+
- Flexible Request Handling: Supports a variety of request types, ensuring robust interaction with blockchain lite servers.
9+
- Dynamic Request Creation: Allows for the creation of customizable requests, enabling tailored blockchain queries and operations.
10+
- Advanced Configuration Options: Offers detailed settings for requests, including server selection and archival data queries, providing users with control over their blockchain interactions.
11+
12+
## Requirements
13+
14+
- CMake: Version 3.15 or newer.
15+
- C++ Compiler: Must support the C++20 standard or more recent.
16+
- Python: Version 3.9 or above is required for utilizing Python bindings.
17+
18+
## Usage
19+
20+
Examples could be found in the `examples` directory.
21+
22+
## Building
23+
24+
```bash
25+
mkdir build
26+
cd build
27+
cmake ..
28+
cmake --build .
29+
```
30+
31+
Build with Python bindings, pass `-DPY_TONLIB_MULTICLIENT:BOOL=TRUE` to CMake:
32+
33+
```bash
34+
cmake -DPY_TONLIB_MULTICLIENT:BOOL=TRUE ..
35+
cmake --build .
36+
```
37+
38+
To use built python binding you need to copy `tonlib_multiclient` dynamic lib (.so) from `build/py` directory to your python project.
39+
```bash
40+
cp build/py/tonlib_multiclient.so /path/to/your/python/project
41+
```
42+
43+
## Requests
44+
45+
### Request<T>
46+
This structure is suitable for general request operations where the response type is known and directly utilized.
47+
48+
### RequestFunction<T>
49+
A specialized version of Request for cases where `TonlibClient::make_request` cannot process the request (`raw_getAccountState` etc).
50+
51+
### RequestCallback
52+
Designed for advanced use cases where the user must initialize and manage the response through your own global callback. Requires explicit setup for callback handling.
53+
54+
### RequestJson
55+
Enables sending requests in raw JSON format, requiring minimal configuration besides the JSON string itself and the standard request parameters.

0 commit comments

Comments
 (0)