Skip to content

Commit 6df5c02

Browse files
vahid1402aleksej-paschenko
vahid1402
authored and
aleksej-paschenko
committed
Add initial technical documentation
1 parent 9ac4151 commit 6df5c02

File tree

3 files changed

+204
-0
lines changed

3 files changed

+204
-0
lines changed

‎docs/01_OVERVIEW.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Overview
2+
3+
## Introduction
4+
This technical documentation is designed for developers and enthusiasts who want to set up and run the source code locally, understand how the project works both at a high-level and in detail, contribute to the development of this repository or customize it for specific use cases, and deep dive into the architecture and inner workings of each package.
5+
6+
## Purpose of the Documentation
7+
This documentation serves as a comprehensive guide that includes:
8+
9+
1. **Setup Instructions**: Step-by-step guidance for setting up and running the source code.
10+
2. **Package Details**: A complete breakdown of the repository’s modular structure and its key components.
11+
3. **Development Insights**: Detailed explanations of how different packages work and their responsibilities within the application.
12+
4. **Learning Resources**: Insights for developers who wish to learn from the codebase or use it as a reference for their own projects.
13+
14+
## Who Should Use This Documentation?
15+
- **Developers** interested in deploying or customizing the repository.
16+
- **Contributors** aiming to enhance the functionality or resolve issues within the code.
17+
- **Learners** seeking to explore the design patterns and implementation strategies used in this project.
18+
19+
20+
## How to Navigate
21+
- Begin with **[02_SETUP_AND_RUN.md](./02_SETUP_AND_RUN.md)** to get the application up and running on your local environment.
22+
- Refer to **[03_STRUCTURE.md](./03_STRUCTURE.md)** for a high-level overview of the project structure and packages.

‎docs/02_SETUP_AND_RUN.md

+134
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Setup and Run
2+
3+
This section provides step-by-step instructions for setting up and running the **OpenTonAPI** project locally. You can choose one of the following methods:
4+
5+
1. **Running via Docker**
6+
2. **Running from Source Code with Go**
7+
8+
## Running via Docker
9+
10+
To run the project using Docker, follow these steps:
11+
12+
### 1. Clone the repository
13+
```bash
14+
git clone https://github.com/tonkeeper/opentonapi.git
15+
```
16+
17+
### 2. Build the Docker image
18+
Navigate into the project directory:
19+
```bash
20+
cd opentonapi
21+
```
22+
23+
Then, build the Docker image:
24+
```bash
25+
docker build -t myopentonapi .
26+
```
27+
28+
### 3. Run the Docker container
29+
After the image is built, run the container with the following command:
30+
```bash
31+
docker run -d -p 8081:8081 myopentonapi
32+
```
33+
34+
This command will run the container in the background, exposing port **8081** on your local machine. You can access the API through this port.
35+
36+
Open the following URL in your browser to ensure that the application is running:
37+
```
38+
http://localhost:8081/v2/status
39+
```
40+
41+
You can also [set environment](#environment-variables) variables when running the Docker container.
42+
```
43+
docker run -d -p 8081:8081 -e LOG_LEVEL=DEBUG myopentonapi
44+
```
45+
46+
47+
## Running from Source Code with Go
48+
To run the project using Go directly from the source code, follow these steps:
49+
50+
### 1. Make sure you have the latest version of Go
51+
Ensure that you have the latest stable version of Go installed on your system. You can check the version of Go using the following command:
52+
```bash
53+
go version
54+
```
55+
56+
### 2. Clone the repository
57+
Clone the OpenTonAPI repository:
58+
59+
```bash
60+
git clone https://github.com/tonkeeper/opentonapi.git
61+
```
62+
63+
Navigate into the project directory:
64+
```bash
65+
cd opentonapi
66+
```
67+
68+
### 3. Download libemulator
69+
For the project to run properly, you need to add **libemulator**, a shared library from the [TON blockchain release repository](https://github.com/ton-blockchain/ton/releases). On a Linux system, follow these steps (on a Windows system, the process is the same, but you must download the appropriate libemulator):
70+
71+
72+
Create the required directory (you can create it wherever you prefer on your system):
73+
```bash
74+
mkdir -p /app/lib
75+
```
76+
77+
Download the `libemulator.so` library (download the library and store it in the folder you created in the previous step):
78+
```bash
79+
wget -O /app/lib/libemulator.so https://github.com/ton-blockchain/ton/releases/download/v2024.08/libemulator-linux-x86_64.so
80+
```
81+
82+
Configure the library path for running the project:
83+
```bash
84+
export LD_LIBRARY_PATH=/app/lib/
85+
```
86+
87+
Run the application
88+
Now, you're ready to run the application using the following Go command:
89+
90+
```bash
91+
go run cmd/api/main.go
92+
```
93+
This command will start the OpenTonAPI and you can access it on the default port **8081**.
94+
95+
Open the following URL in your browser to ensure that the application is running:
96+
```
97+
http://localhost:8081/v2/status
98+
```
99+
100+
You can also [set environment](#environment-variables) variables when start the OpenTonAPI.
101+
```
102+
PORT=8080 LOG_LEVEL=DEBUG go run cmd/api/main.go
103+
```
104+
105+
106+
107+
## Environment Variables
108+
109+
OpenTonAPI supports several environment variables to customize its behavior during startup. These variables allow you to define API configurations, logging, TON Lite Server connections, and other app-level settings. The environment variables are loaded and managed in the [`config.go`](../pkg/config/config.go) file, where you can find detailed parsing logic and default value definitions.
110+
111+
112+
113+
| Environment Variable | Default Value | Description |
114+
|---------------------------|-----------------------|-----------------------------------------------------------------------------------------------------------------------|
115+
| `PORT` | `8081` | Defines the port on which the HTTP API server listens for incoming connections. |
116+
| `LOG_LEVEL` | `INFO` | Sets the logging level (`DEBUG`, `INFO`, `WARN`, `ERROR`). |
117+
| `METRICS_PORT` | `9010` | Port used to expose the `/metrics` endpoint for Prometheus metrics. |
118+
| `LITE_SERVERS` | `-` | A comma-separated list of TON Lite Servers in the format `ip:port:public-key`. |
119+
| | | Example: `127.0.0.1:14395:6PGkPQSbyFp12esf1NqmDOaLoFA8i9+Mp5+cAx5wtTU=` |
120+
| `SENDING_LITE_SERVERS` | `-` | A comma-separated list of additional Lite Servers dedicated to transaction processing. Format is identical to `LITE_SERVERS`. |
121+
| `IS_TESTNET` | `false` | A flag indicating whether the application should operate in testnet mode (`true` or `false`). |
122+
| `ACCOUNTS` | `-` | A comma-separated list of account addresses to monitor. |
123+
| `TON_CONNECT_SECRET` | `-` | Secret used for TonConnect integration. |
124+
125+
### Notes
126+
**`LITE_SERVERS`**: If no Lite Server is set, the application will default to using a random public Lite Server. [`Lite Servers`](https://docs.ton.org/v3/documentation/infra/nodes/node-types) in the TON network are categorized into Full nodes and Archive nodes. If no Lite Server is set, by default, the application may use a Full node Lite Server, which does not provide access to historical data. To access historical data, you need to explicitly set an Archive node. You can find public Archive nodes available for use at the [`global-config.json`](https://ton.org/global-config.json).
127+
128+
129+
130+
131+
## Next Steps
132+
Read [`03_STRUCTURE.md`](./03_STRUCTURE.md), where you will find details about the project structure and the various packages used within the application. It will give you a better understanding of how everything is organized and how the individual packages work together.
133+
134+

‎docs/03_STRUCTURE.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
## Packages and Structure
2+
3+
This project utilizes [`OpenAPI Generator`](https://github.com/ogen-go/ogen) (`ogen`), a tool for generating Go code from OpenAPI v3 specifications, and the [`Tongo`](https://github.com/tonkeeper/tongo) package, a Golang SDK developed by the Tonkeeper team for working with the TON blockchain. These two libraries are central to how the project communicates with the TON blockchain and manages APIs. In addition to these, there are several other packages developed specifically for this project, which we will explain in more detail throughout this document.
4+
5+
## Entry Point
6+
The entry point for running the application is located in the `cmd/api/main.go` file. it's where the application starts when executed.
7+
8+
## Project Structure
9+
The breakdown of the root structure:
10+
11+
- `api` - Contains configuration files for Ogen to generate API interfaces and other API-related configuration files.
12+
- `cmd` - Contains the main entry point and execution command for the application.
13+
- `internal` - Internal packages for utility functions and helpers.
14+
- `pkg` - Core packages for various functionalities in the application.
15+
- `gen.go` - Generates code based on the OGEN specification.
16+
- `go.mod` - Go module dependencies and configuration.
17+
- `go.sum` - Go checksum dependencies.
18+
- `ogen.yaml` - OpenAPI configuration for generating code using OGEN.
19+
20+
21+
22+
23+
## pkg Folder
24+
The `pkg` directory contains all the core packages that implement the functionality of this application. Below is an overview of the important packages that exist within the pkg folder:
25+
26+
- `addressbook` - This package provides the main functionality for managing the known addresses, jettons, NFT collections, and their manual configurations.
27+
- `api` - Handles the core business logic behind the API endpoints for interacting with the system's features, such as querying address information, transactions, and blockchain-related tasks.
28+
- `app` - Provides application-level functionalities such as logging configuration.
29+
- `bath` -
30+
- `blockchain` - Handles sending payloads and transactions to lite servers and serves as an indexer for retrieving the latest block in real-time.
31+
- `cache` - Manages caching mechanisms to enhance performance.
32+
- `chainstate` - Manages the state of the blockchain, including tracking APY and managing banned accounts.
33+
- `config` - Manages the application's configuration through environment variables, ensuring correct parsing and loading of configurations, including paths for accounts, collections, and jettons.
34+
- `core` -
35+
- `gasless` - Handles gasless operations allowing users to perform transactions without the need for TON for gas fees.
36+
- `image` - Handles image preview generation by providing functionality to create image URLs with specified dimensions.
37+
- `litestorage` - Deals with storage and management of data on LiteServers.
38+
- `oas` - Contains utilities related to OpenAPI Specification (OAS) processing.
39+
- `pusher` - Handles real-time communication using a pushing mechanism, sending updates and notifications to subscribed users or services.
40+
- `rates` - Handles functionality related to fetch, convert, and display market prices for TON tokens across various services.
41+
- `references` -
42+
- `score` -
43+
- `sentry` - Manages error tracking and reporting via Sentry.
44+
- `spam` - Provides functionality for detecting and filtering spammy or scam-related actions based on predefined rules, specifically for TON transfers, Jetton transfers, and NFT transactions.
45+
- `testing` -
46+
- `verifier` -
47+
- `wallet` -
48+

0 commit comments

Comments
 (0)