You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Dec 26, 2022. It is now read-only.
The structure of this information deisseminating network is based on MQTT protocol which consists of three components. `Connectivity Endpoint`, `tangle-accelerator` and `Parser`
3
+
4
+
### 1. Connectivity Endpoint
5
+
This is a client implemented with any possible lightweight computing node (such as Raspberry Pi) and a communication module (i.e. NB-IoT module). There are some modems allowing users to send MQTT message with AT-command-like command, so for these kinds of modems, they don't need to run a `mosquitto`-dependent programs on the lightweight computing node.
6
+
For the `Connectivity Endpoint` which uses a modem provides AT-command-like commands, few things they need to do are choosing the right topic (we use different topics to simulate RESTful methodology) and serializing the data/message into the demanded format which contains `Device ID` for TA requests. After the message is serialized into the demanded format, we can send this message with modem provided command as simple as we send a http request with Python.
7
+
8
+
### 2. tangle-accelerator
9
+
TA (tangle-accelerator) plays a role of server which receives requests from communication module and processes the requests. However, under the structure of this MQTT information deisseminating network, both `tangle-accelerator` and `Connectivity Endpoint` are MQTT client. We must take care that `tangle-accelerator` is not a broker under this topology of MQTT information disseminating network.
10
+
`tangle-accelerator` runs as a MQTT subscriber and publisher at the same time which listen to the requests on several different topics and respond the requests according to respective request result. We treat each topic as different URL path of http protocol does.
11
+
12
+
### 3. Parser
13
+
The `Parser` plays a role of both subscriber and publisher simultaneously; thus, we will implement this `Parser`, which is a duplex client by modifying `mosquitto`'s client source code.
14
+
Sometimes, it might necessitate parsing MQTT messages, since the messages which are sent from multifarious modems may vary from one to another. In order to support a wide range of modems from different manufactures, we can use a duplex client to revise the messages which are sent from modems into the regulated format, then send the message in regulated format to a specific topic which contains only requests follow TA's request format.
15
+
16
+
## Communication structure
17
+
`<root>` is the host operator defined root path. It can be used if we want to choose a certain host of a cluster.
18
+
19
+
#### 1. Communication Endpoint sends message
20
+
Communication endpoint would send message on topic `<root>/<API>/raw/<parser type ID>`
21
+
On this topic, the messages are in raw types whose formats depend on the modems users chose.
22
+
And the sub-topic, `<parser type ID>`, aims to pass the message to a appropriate parser (the work that parser should
23
+
do is corresponding to multifarious manufacturers or even different modems).
24
+
25
+
The message should contain the `Device ID` of the `Communication Endpoint`, since the `Device ID` will be used in returning data for `tangle-accelerator`. Once the message is published, Communication Endpoint will start to listen the topic, `<root>/<API>/<Device ID>`. The resonse will be published into this topic
26
+
#### 2. Parser parses raw message
27
+
Parser parses messages came from topic `<root>/<API>/raw/<parser type ID>` into regulted format of TA.
28
+
#### 3. Parser sends neat messages
29
+
Parser sends parsed, neat, regulated format messages to topic `<root>/<API>`, and the messages contain `Device ID` of source devices as well.
30
+
#### 3. TA receives the message
31
+
TA receive the message from topic `<root>/<API>`, and then it starts to process the requests.
32
+
The responses will be sent onto topic `<root>/<API>/<Device ID>`.
`Tangle-accelerator` is a caching proxy server for [IOTA](https://www.iota.org/), which
6
6
can cache API requests and rewrite their responses as needed to be routed through full
7
-
nodes. Thus, one instance of `Tangle-accelerator` can serve thousands of Tangle requests
8
-
at once without accessing remote full nodes frequently.
7
+
nodes. In other words, one instance of `Tangle-accelerator` can serve thousands of IOTA
8
+
requests at once without accessing remote full nodes frequently, that improves the
9
+
scalability and usability of [Tangle network](https://www.iota.org/research/meet-the-tangle).
10
+
11
+
Being at the edge as a key-value store, an edge-caching node powered by `Tangle-accelerator`
12
+
does not have to communicate to typical [IOTA](https://www.iota.org/) full nodes for every API
13
+
calls. Instead, the cached transaction data being sought is available as needed.
9
14
10
15
As an intermediate server accelerateing interactions with the Tangle, it faciliates
11
16
[dcurl](https://github.com/DLTcollab/dcurl) to perform hardware-accelerated PoW operations
12
17
on edge devices. In the meanwhile, `Tangle-accelerator` provides shortcuts for certain
13
-
use scenarios such as MAM and [TangleID](https://github.com/TangleID).
18
+
use scenarios such as MAM and [TangleID](https://tangleid.github.io/).
14
19
15
20
At the moment, it is not feasible to host fully-functioned full nodes on Raspberry Pi class
16
21
Arm devices, but Raspberry Pi 3 is known to be capable to execute `Tangle-accelerator`
@@ -43,6 +48,28 @@ both footprint and startup time are behaved pretty well.
43
48
44
49
```
45
50
51
+
### Transaction reattachment
52
+
53
+
`Tangle-accelerator` helps to reattach pending transactions were attached from `Tangle-accelerator`.
54
+
Reattachment increases chances of confirmation and prevents messages being pruned when full nodes perform snapshot.
55
+
Clients should provide a uniqle ID as the identifier to each message and it's corresponding transaction hash since a new transaction hash will be generated after reattachement.
56
+
57
+
`Tangle-accelerator` uses ScyllaDB to store each transaction's ID, hash and status(Pending or confirmed). `Tangle-accelerator` will periodically check the status of pending transactions and reattach transactions which have been pended too long. Confirmed transactions will be stored into permanodes.
58
+
59
+
Clients can find the transaction alone with wanted message by using the ID to query.
60
+
61
+
## Connectivity
62
+
63
+
`Tangle-accelerator`, at this moment, supports the following TCP/IP derived protocols:
64
+
*`HTTP`
65
+
*`MQTT`
66
+
67
+
### HTTP
68
+
`HTTP` can be used in the normal internet service. User can use RESTful APIs to interact with `tangle-accelerator`.
69
+
70
+
### MQTT
71
+
`MQTT` is a lightweight communication protocol which can be used in the IoT scenarios. `Tangle-accelerator`'s support to `MQTT` allows embedded devices to write data on IOTA internet with relative low quality hardware devices. We hope this will speed up DLT into our daily life.
72
+
46
73
## Documentation
47
74
48
75
This page contains basic instructions for setting up tangle-accelerator, You can generate full documentation and API reference via Doxygen. The documentation is under `docs/` after generated:
@@ -71,7 +98,7 @@ Before running tangle-accelerator, please edit binding address/port of accelerat
71
98
$ make && bazel run //accelerator
72
99
```
73
100
74
-
### Build from docker
101
+
### Optional: Build Docker Images
75
102
76
103
If you prefer building a docker image, tangle-accelerator also provides build rules for it. Note that you still have to edit configurations in `accelerator/config.h`.
77
104
@@ -82,7 +109,73 @@ $ make && bazel run //accelerator:ta_image
82
109
There's also an easier option to pull image from docker hub then simply run with default configs. Please do remember a redis-server is still required in this way.
83
110
84
111
```
85
-
$ docker run -d --net=host --name tangle-accelerator wusyong/tangel-accelerator:latest
112
+
$ docker run -d --net=host --name tangle-accelerator dltcollab/tangle-accelerator
113
+
```
114
+
115
+
### Optional: Build and Push Docker Image to Docker Hub
116
+
117
+
Before pushing the docker image to Docker Hub, you need to log in the docker registry:
118
+
119
+
```
120
+
$ docker login
121
+
```
122
+
123
+
Then you could push the docker image with the following command:
124
+
125
+
```
126
+
$ make && bazel run //accelerator:push_docker
127
+
```
128
+
129
+
If you get the following error message:
130
+
131
+
```
132
+
SyntaxError: invalid syntax
133
+
----------------
134
+
Note: The failure of target @containerregistry//:digester (with exit code 1) may have been caused by the fact that it is running under Python 3 instead of Python 2. Examine the error to determine if that appears to be the problem. Since this target is built in the host configuration, the only way to change its version is to set --host_force_python=PY2, which affects the entire build.
135
+
136
+
If this error started occurring in Bazel 0.27 and later, it may be because the Python toolchain now enforces that targets analyzed as PY2 and PY3 run under a Python 2 and Python 3 interpreter, respectively. See https://github.com/bazelbuild/bazel/issues/7899 for more information.
137
+
------------
138
+
```
139
+
140
+
Use the `--host_force_python=PY2` parameter to force the Bazel to use the Python2 in entire build.
141
+
142
+
```
143
+
$ make && bazel run //accelerator:push_docker --host_force_python=PY2
144
+
```
145
+
146
+
### Optional: Enable MQTT connectivity
147
+
MQTT connectivity is an optional feature allowing IoT endpoint devices to collaborate with `Tangle-Accelerator`.
148
+
149
+
```
150
+
make MQTT && bazel run //accelerator:accelerator_mqtt
151
+
```
152
+
153
+
Note you may need to set up the `MQTT_HOST` and `TOPIC_ROOT` in `config.h` to connect to a MQTT broker.
154
+
For more information for MQTT connectivity of `tangle-accelerator`, you could read `connectivity/mqtt/usage.md`.
155
+
156
+
### Optional: Enable external database for transaction reattachment
157
+
Transaction reattachment is an optional feature.
158
+
159
+
You can enable it in the build time by adding option : `--define db=enable`
160
+
161
+
Transaction reattachment relies on ScyllDB, you need to install the dependency by following commands.
@@ -111,14 +204,35 @@ Buildifier can be installed with `bazel` or `go`
111
204
2. change directory to `buildtools`
112
205
3. build it with bazel command, `$ bazel build //buildifier`
113
206
The executable file will be located under `path/to/buildtools/bazel-bin`
114
-
4. make a soft link
207
+
4. make a soft link or move the executable file under `/usr/bin`
115
208
116
209
### clang-format
117
210
clang-format can be installed by command:
118
211
- Debian/Ubuntu based systems: `$ sudo apt-get install clang-format`
119
212
- macOS: `$ brew install clang-format`
120
213
121
214
215
+
## Usage
216
+
`Tangle-accelerator` currently supports two categories of APIs
217
+
* direct API: check [wiki page](https://github.com/DLTcollab/tangle-accelerator/wiki) for details.
218
+
* Proxy API to IRI core functionalities
219
+
220
+
### IRI Porxy API
221
+
`tangle-accelerator` allows the use of IRI core APIs. The calling process does not have to be aware of the destination machine running IRI. With the exactly same format of IRI API, `tangle-accelerator` would help users forward the request to IRI and forward the response back to users.
222
+
We support two way to forward Proxy APIs to IRI:
223
+
1. Bypass Proxy APIs directly to IRI.
224
+
2. Process the Proxy APIs, then transmit them to IRI.
225
+
226
+
The user can choose which way they want with CLI argument `--proxy_passthrough`.
227
+
All the Proxy APIs are supported with the first way.
228
+
However, the second way currently only supports the followings Proxy APIs:
229
+
* checkConsistency
230
+
* findTransactions
231
+
* getBalances
232
+
* getInclusionStates
233
+
* getNodeInfo
234
+
* getTrytes
235
+
122
236
## Licensing
123
237
`Tangle-accelerator` is freely redistributable under the MIT License. Use of this source
124
238
code is governed by a MIT-style license that can be found in the `LICENSE` file.
0 commit comments