TON HTTP API C++

The HTTP API C++ for The Open Network is a real-time API to connect to TON blockchain lite servers via ADNL protocol and enable access to lite servers through HTTP requests.

This service is the improved version of original TON HTTP API, written entirely in C++ to achieve outstanding performance and effecient comnsuming of hardware resources.

Features

TON HTTP API C++ provides following features:

• Load balances requests to TON nodes
• Checks availability of Lite Servers, disables unavailable and out-of-synced nodes.
• Additionally parses data returned by original TONLib.
• Based on userver, service provides detailed and Prometheus-compatible usage statistics.

Key differences from toncenter/ton-http-api

• C++ version consumes significantly less CPU and memory resources.
• 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.
• Cache now is integrated in service, no separate Redis is required to enable caching feature.

Hardware Requirements

• OS: Linux or MacOS (Windows is not supported).
• CPU: 2 vCPU, x86_64 or arm64 architecture.
• RAM: minimum 2GB, 8GB recommended for caching.

Deploy

There are two main ways to run TON HTTP API:

• Docker Compose: flexible configuration, recommended for production environments, works on any x86_64 and arm64 OS with Docker available.
• Local (experimental): only for development purposes.

Docker Compose

• (First time) Install required tools: docker, docker-compose, curl.
  • For Ubuntu: run scripts/setup.sh from the root of the repo.
  • For MacOS and Windows: install Docker Desktop.
  • Note: we recommend to use Docker Compose V2.
• Download TON configuration files to private folder:

  mkdir private
  curl -sL https://ton-blockchain.github.io/global.config.json > private/mainnet.json
  curl -sL https://ton-blockchain.github.io/testnet-global.config.json > private/testnet.json

• Copy service configuration file and adjust params:

  cp config/config_vars.yaml private/config_vars.yaml
  nano private/config_vars.yaml

  • To run testnet version or connect to your private TON node, please specify:

  export THACPP_TONLIB_CONFIG_PATH=private/testnet.json
  # or
  echo "THACPP_TONLIB_CONFIG_PATH=private/testnet.json" > .env
  

  • To build an image using custom TON monorepo:

  export BUILD_WITH_TON_REPO=https://github.com/ton-blockchain/ton
  export BUILD_WITH_TON_BRANCH=testnet
  # or 
  echo "BUILD_WITH_TON_REPO=https://github.com/ton-blockchain/ton" >> .env
  echo "BUILD_WITH_TON_BRANCH=testnet" >> .env
  

• Pull or build docker image:

  docker compose pull
  # or 
  docker compose build

• Run service:

  docker compose up -d
  # or
  docker compose up

• Additionally check service logs:

  docker compose logs http-api-cpp
  # or 
  docker compose logs -n 100 http-api-cpp
  # or 
  docker compose logs -f -n 100 http-api-cpp

Configure via environment variables

Instead of using config_vars.yaml file, you can also configure service via environment variables. To do this you need to set environment variables before starting the service and use the following command:

docker compose -f docker-compose.env-vars.yaml up -d

List of available environment variables:

• THACPP_TONLIB_CONFIG_PATH - TON global config path (default: /run/secrets/ton-global-config)
• THACPP_TONLIB_KEYSTORE_PATH - TONlib keystore path (default: /tmp/keystore/)
• THACPP_TONLIB_BOC_ENDPOINTS - Endpoints to duplicate incoming BOCs; should be a list of comma-separated quoted strings like ["http://127.0.0.1:8080", "https://endpoint.com/postBoc"] (default: [])
• THACPP_TONLIB_THREADS - number of threads for TONlib multiclient (default: 4)
• THACPP_PORT - API port in container (default: 8081)
• THACPP_MONITOR_PORT - Monitoring port in container (default: 8082)
• THACPP_MAIN_WORKER_THREADS - number of threads to serve HTTP requests (default: 4)
• THACPP_FS_WORKER_THREADS - number of threads for I/O operations (default: 1)
• THACPP_HTTP_WORKER_THREADS - number of threads for HTTP client (used to duplicate BOCs on external service) (default: 2)
• THACPP_LOG_LEVEL - api v2 log level (default: warning)
• THACPP_LOG_PATH - log output destination (@stdout, @stderr, @null, or /path/to/file) (default: "@stdout")
• THACPP_SYSTEM_LOG_LEVEL - userver system logs level (default: warning)
• THACPP_SYSTEM_LOG_PATH - userver system log path (default: "@stdout")
• THACPP_JSONRPC_LOG_LEVEL - jsonrpc endpoint log level (default: warning)
• THACPP_JSONRPC_LOG_PATH - jsonrpc endpoint log path (default: "@stdout")
• THACPP_LOG_FORMAT - logs format (tskv, ltsv, json) (default: json)
• THACPP_HTTP_WORKER_USER_AGENT - HTTP user agent sent to BOC endpoint (default: empty)
• THACPP_STATIC_CONTENT_DIR - directory for static content served by API (default: "/static/")
• THACPP_MAX_STACK_ENTRY_DEPTH - max stack entry depth for runGetMethod (higher values increase memory usage) (default: 256)

Local run

• Install dependencies:

  • For Ubuntu:

  apt update -y
  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
  
  # for ubuntu 22.04 check https://userver.tech/de/d9c/md_en_2deps_2ubuntu-22_804.html

  • For MacOS:

  brew install [email protected] 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

• Build:

  mkdir build
  cd build
  cmake -DCMAKE_BUILD_TYPE=Release ..
  make -j$(nproc) ton-http-api-cpp
  # optional
  make install

• Run:

  ./build/ton-http-api/ton-http-api-cpp --config ./config/static_config.yaml --config_vars ./private/config_vars.yaml

License

TON HTTP API C++ is licensed under the MIT License.