Skip to content

Commit

Permalink
Update README.md documentation and docker-compose.yml
Browse files Browse the repository at this point in the history
  • Loading branch information
@LINCKODE
LINCKODE committed May 2, 2024
1 parent c5d5f9b commit 7f90d93
Show file tree
Hide file tree
Showing 2 changed files with 121 additions and 201 deletions.
298 changes: 109 additions & 189 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,217 +1,137 @@
<br /><br />
# The qubic http service

qubic-http
The `qubic-http` service acts as a bridge to the qubic network.
Some of its features include:
- Checking balances
- Broadcasting transactions
- Tick information
- Block height

<br /><br />

## Building the app binary:
```bash
$ go build -o "server" "./app/server"
```
## Building from source

## Running the server:
```bash
$ ./server --qubic-node-ips="65.21.10.217;148.251.184.163" --opensearch-host="http://93.190.139.223:9200"
2023/11/20 20:05:05 main: Config :
--web-host=0.0.0.0:8080
--web-read-timeout=5s
--web-write-timeout=5s
--web-shutdown-timeout=5s
--qubic-node-ips=[65.21.10.217 148.251.184.163]
--qubic-node-port=21841
--opensearch-host=http://93.190.139.223:9200
2023/11/20 20:05:05 main: API listening on 0.0.0.0:8080
```shell
go build -o "server" "./app/server"
```

## Docker usage:
```bash
$ docker build -t ghcr.io/qubic/qubic-http:latest .
$ docker run -p 8080:8080 -e QUBIC_API_SIDECAR_QUBIC_NODE_IPS="65.21.10.217;148.251.184.163" -e QUBIC_API_SIDECAR_OPENSEARCH_HOST="http://93.190.139.223:9200" ghcr.io/qubic/qubic-http:latest
```
## Running the service

## Getting identity info:
```bash
$ curl "localhost:8080/v1/address/PKXGRCNOEEDLEGTLAZOSXMEYZIEDLGMSPNTJJJBHIBJISHFFYBBFDVGHRJQF"
{
"public_key": "4f27dc1b6a1a76d479833e5f1bed0d6d77c705a0290a632de94794dbee670dfa",
"tick": 10894487,
"balance": 10000,
"incoming_amount": 1479299940,
"outgoing_amount": 1479289940,
"number_of_incoming_transfers": 125981,
"number_of_outgoing_transfers": 2612,
"latest_incoming_transfer_tick": 10894487,
"latest_outgoing_transfer_tick": 11330319,
"siblings": [
"2a5af1c66af3ef4a294e09f27aed030d3faeffb9a1910012468b9c7f3e46bd9f",
...
]
}
```
`qubic-http` requires an instance of [qubic-nodes](https://github.com/qubic/go-qubic-nodes) for fetching reliable node addresses.

## Getting tx by id:
```bash
$ curl "localhost:8080/v1/tx/qdnwqignkprgrbkdlbpsrprikjagdnzaafsbxngbtfczcfjnsvgelivfxoem"
{
"bxid": "bacab66e7cbbb950c8b80facef94c5f0bf478ee3ab8ac270f541b1aba71cb8a7",
"utime": "1704973083",
"epoch": "91",
"tick": "11963307",
"type": "0",
"src": "AMITKEPEADJMEBOKSXLFNNCQLQTCAAWIDNCKTDZGYEUCYCNOEEDJHMACPPTG",
"dest": "DCHWKUZLNYTDYBFZTELHWEDQDQCBBKTKYUITIKCDKACHDUBFYRHGDZSFQLBG",
"amount": "7357247517",
"extra": "",
"sig": "b6f330e9713047321de9ff3506078726a06119115ab27e8d805a9ebd2828a8189e96bd1a31d1a72702ba1ee5abebd130cf43e25ee68109f01c6f9cc42d100f00"
}
### Configuration

The service can be configured either by CLI parameters or environment variables.
The current configuration will be printed at startup.

#### Required parameters

```shell
QUBIC_API_SIDECAR_SERVER_HTTPS_HOST: "0.0.0.0:8000"
QUBIC_API_SIDECAR_SERVER_GRPC_HOST: "0.0.0.0:8001"
QUBIC_API_SIDECAR_SERVER_MAX_TICK_FETCH_URL: "http://127.0.0.1:8080/max-tick"

QUBIC_API_SIDECAR_POOL_NODE_FETCHER_URL: "http://127.0.0.1:8080/status"
```

## Getting bx by id:
```bash
$ curl "localhost:8080/v1/bx/bacab66e7cbbb950c8b80facef94c5f0bf478ee3ab8ac270f541b1aba71cb8a7"
{
"utime": "1704973097",
"epoch": "91",
"tick": "11963307",
"type": "1",
"src": "AMITKEPEADJMEBOKSXLFNNCQLQTCAAWIDNCKTDZGYEUCYCNOEEDJHMACPPTG",
"dest": "DCHWKUZLNYTDYBFZTELHWEDQDQCBBKTKYUITIKCDKACHDUBFYRHGDZSFQLBG",
"amount": "7357247517"
}
#### Optional parameters
```shell
QUBIC_API_SIDECAR_SERVER_READ_TIMEOUT: (default: 5s)
QUBIC_API_SIDECAR_SERVER_WRITE_TIMEOUT: (default: 5s)
QUBIC_API_SIDECAR_SERVER_SHUTDOWN_TIMEOUT: (default: 5s)

QUBIC_API_SIDECAR_POOL_NODE_FETCHER_TIMEOUT: (default: 2s)
QUBIC_API_SIDECAR_POOL_INITIAL_CAP: (default: 5)
QUBIC_API_SIDECAR_POOL_MAX_IDLE: (default: 20)
QUBIC_API_SIDECAR_POOL_MAX_CAP: (default: 30)
QUBIC_API_SIDECAR_POOL_IDLE_TIMEOUT: (default: 15s)
```

## Getting status:
```bash
$ curl "localhost:8080/v1/status"
{
"epoch": 91,
"bxid": [
91,
12017682
],
"txid": [
91,
12017336
],
"quorum": [
91,
12017688
],
"tick": [
91,
12017336
]
}
### Docker (recommended)
A `docker-compose.yml` file is provided in this repository. You can run it as-is using `docker compose up -d`.
This will start a `qubic-nodes` service alongside `qubic-http`.
> It may be necessary to configure `qubic-nodes` with an up-to-date list of peers if the service fails to start.
### Standalone
Setting up a `qubic-nodes` instance is outside the scope of this documentation, but you can learn about it on the`qubic-nodes` [GitHub](https://github.com/qubic/go-qubic-nodes).
We assume that `qubic-nodes` is running locally on port 8080.

Export the required environment variables:
```shell
export QUBIC_API_SIDECAR_SERVER_HTTPS_HOST="0.0.0.0:8000"
export QUBIC_API_SIDECAR_SERVER_GRPC_HOST="0.0.0.0:8001"
export QUBIC_API_SIDECAR_SERVER_MAX_TICK_FETCH_URL="http://127.0.0.1:8080/max-tick"
export QUBIC_API_SIDECAR_POOL_NODE_FETCHER_URL="http://127.0.0.1:8080/status"
```
You can now start the service:
```shell
./server
```


## Available endpoints

### Information related endpoints

## Getting tick data:
```bash
$ curl "localhost:8080/v1/tick-data/11356544"
#### /tick-info

```shell
curl http://localhost:8000/tick-info
```
```json
{
"computor_index": 420,
"epoch": 86,
"tick": 11356544,
"millisecond": 0,
"second": 4,
"minute": 16,
"hour": 15,
"day": 12,
"month": 12,
"year": 23,
"hex_union_data": "00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"hex_timelock": "7262190d095c8507d9077688d1892683236857c8c7bd556a1c26cc47f098d778",
"transaction_digests": [
"25a9a37da318564cae50aa67bf9af04948685736d2710338dc71467426c8a6ef",
...
],
"contract_fees": null,
"signature": "ae1e9cbbae7dc7895659d44c2828c77bca9e61b2de8c2a07e4df2e19dcad40b2fdf79b878c6decf8868d557105cc0a552688cc9e03f08e6b0d8e846844fa2700",
"potentialBx": [
{
"index": 35,
"dest": "YOANRGAZNOPBCBYTYQFBFYEARPKDZEEIBYZORWQTTDOKCIEGLZZMACGDOEKA",
"amount": "1203390386"
}
]
"tickInfo": {
"tick": 13692242,
"duration": 7,
"epoch": 107,
"initialTick": 13680000
}
}
```

## Getting quorum data by tick
```bash
$ curl "localhost:8080/v1/quorum/12023688"
#### /block-height

```shell
curl http://localhost:8000/block-height
```
```json
{
"computor": 542,
"epoch": 91,
"tick": 12023688,
"time": [
0,
26,
5,
7,
16,
1,
24
],
"prevRTD": "12250904539969688494",
"saltRTD": "5465134535200475419",
"digests": [
"a2cecdc3110116a22c654501e23261480ccb07f52e34f5ab19861da21bb658f1",
"34a98e98d893e3a22db055ded34e71702d1f6b38bf43627dc592a199fe819ef6",
"c9df65d2c2053559c6259fc9f58e88086ad84aedacd9d5bd6981b2dba09ad769",
"f7e2fd47adb07b334c2c30ee6fb5d844ee4d707f17e8bc3b84d960447b96f654",
"e217aa9e67ee3e5319a8feb5004d0ebc26a61cc2434b87d5810ea59dc18512c7",
"d1216643b9279c9d0b6278d05c22e1bd95616c283e4a3f85eb6d9a8e6a6cdd5a",
"07d621e3bc092473eb0e06c7fed4b3cb7f82cb77cfa3372002252f131c01f68f",
"9a4076ba1e30e76a5e7ecdcf1f58bb8ca8ec4a62251a006e0ad463bd2e104c26"
],
"sig": "56ea4b6f4fe2cb2e1728a3f6aa9b6b21343b17fdd42b046e67e0a7f9ade479079925e53f5f880d93e123539a8124d8c603d54e7d5c21f7278320bfa31b7c1600",
"diffs": [
{
"computor": 3,
"saltRTD": "13747147356733467208",
"digests": [
"47da2aeebb85fade0c4abb953d56eebee0f294b99e14f5b9efb4714219fca992",
"33c8368920dd6d59c436a09ff88e06b98320676db6be94e0d1f2e870a980ab08",
"fe1744396133c5dc6a02ad9170db69d6cd404ba7a7381ba595e6e5a71242ed82",
"9a4076ba1e30e76a5e7ecdcf1f58bb8ca8ec4a62251a006e0ad463bd2e104c26"
],
"sig": "a0f99dd2ae753da54edacfb4d6dc5022f1e7e33c44e1ee51eb0714781dc1dc6b6a5c7c560c813f98173de48a09f58c03e1276238ca8fa149ca3b162c9db50600"
},
{
"computor": 4,
"saltRTD": "16517841960992476753",
"digests": [
"3a9d7318e20b91bc6e82d5b15349ecb683c47e58caecd59ca9849d70c1b910cf",
"7ccbf8bfa4c1ce6d6147ebe5d03b16b8a5b783f032104e7259a04dcae0e36567",
"fb21ff0b75f90fe1aa81ce54cce91b64eee439ed87316ab64a7816a935a0c710",
"9a4076ba1e30e76a5e7ecdcf1f58bb8ca8ec4a62251a006e0ad463bd2e104c26"
],
"sig": "514e5699ddf35c02351d6643b540573db103135b2f64a606bfddad5985f48d43756ebe9eba92a7cbe7d01a6134397aba5a3ca18793386301bfb09ac6e5fe1300"
}
],
"numvotes": 603
"blockHeight": {
"tick": 13692267,
"duration": 0,
"epoch": 107,
"initialTick": 13680000
}
}
```

## Getting list computors per epoch
```bash
$ curl "localhost:8080/v1/computors/90"
#### /balances/{id}

```shell
curl http://localhost:8000/balances/PKXGRCNOEEDLEGTLAZOSXMEYZIEDLGMSPNTJJJBHIBJISHFFYBBFDVGHRJQF
```
```json
{
"epoch": "90",
"pubkeys": [
"LVMMXNAABKUVYGFUSPUTVPVABARALIUZGNLQJZLXEEOAIKBNGDKUIZICAUFE",
"WJWPMUQJURGNNBWDGXJSJFPSHCTCGPWFHJKBKICWHBBYPNHSCEKISCJANXAL",
"CKXIZTMVOVZJMBXNKPNCGYKDPVICAMWJLNDMMWZMCEJJSMLNGGWTRXOFZPSI",
"AFBSWFLTLNVAKEGWXNVKLTOCEPCAOEGEGJTHQWVONERINRARRQKIMESFNOGM",
],
"sig": "d1a036931ba8066e5817492ccf0af146f091857e83f2f2c388d11fb7b6c47b0891ec7aa46dbcd0d047d48a155c7f0e962a8e3f8d438425ee27ad88deafcb0d00"
"balance": {
"id": "PKXGRCNOEEDLEGTLAZOSXMEYZIEDLGMSPNTJJJBHIBJISHFFYBBFDVGHRJQF",
"balance": "0",
"validForTick": 13692275,
"latestIncomingTransferTick": 0,
"latestOutgoingTransferTick": 0
}
}
```

## Send raw tx:
```bash
$ curl "localhost:8080/v1/send-raw-tx" --json '{"hex_raw_tx": "C872E68E1C0ECCCE3BC6A87BC32E187C59BBA99AB81D7CC37E7D22F7423672A70E4EAF16A2218457BA8B46991B5CCA63E65AE65FF65C575A06743E40E8DA982A0100000000000000C60DAE0000000000A1C0B21A5C15D72275F7968D30A4F0520075F85A0232E180A5FC6C0137CC414F402404CF40773F444A25BCF30B6455B18A18FF7DD105F3223EECA8C566781A00"}'
```

### Transaction related endpoints

#### /broadcast-transaction

```shell
curl -X POST http://localhost:8000/broadcast-transaction -d '{"encodedTransaction": "..."}'
```
```json
{
"peersBroadcasted": 3,
"encodedTransaction": "...",
"transactionId": "oxmqdbynwbisqcjgphyaexhlknmaanipiyxpulatkdjxpdqsqtiovjhcxqkd"
}
```
24 changes: 12 additions & 12 deletions docker-compose.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,35 +2,35 @@ version: '3'

services:
qubic-http:
image: ghcr.io/qubic/qubic-http:v0.4.0
image: ghcr.io/qubic/qubic-http:v0.5.0
container_name: qubic-http
environment:
QUBIC_API_SIDECAR_SERVER_HTTP_HOST: "0.0.0.0:8000"
QUBIC_API_SIDECAR_SERVER_GRPC_HOST: "0.0.0.0:8001"
QUBIC_API_SIDECAR_POOL_NODE_FETCHER_URL: "http://qubic-node-fetcher:8080/peers"
QUBIC_API_SIDECAR_SERVER_MAX_TICK_FETCH_URL: "http://qubic-nodes:8080/max-tick"
QUBIC_API_SIDECAR_POOL_NODE_FETCHER_URL: "http://qubic-nodes:8080/status"
QUBIC_API_SIDECAR_POOL_NODE_FETCHER_TIMEOUT: "20s"
networks:
- qubic
ports:
- "127.0.0.1:8000:8000"
depends_on:
qubic-node-fetcher:
qubic-nodes:
condition: service_healthy
restart: always

qubic-node-fetcher:
image: ghcr.io/qubic/go-node-fetcher:v0.3.0
container_name: qubic-node-fetcher
qubic-nodes:
image: ghcr.io/qubic/qubic-nodes:v1.0.2
container_name: qubic-nodes
ports:
- "127.0.0.1:8080:8080"
environment:
NODE_FETCHER_QUBIC_FIXED_PEER_LIST: true
NODE_FETCHER_QUBIC_STARTING_PEERS_IP: "185.70.186.149;185.70.186.153"
volumes:
- ./store/node-fetcher:/app/store
QUBIC_NODES_QUBIC_PEER_LIST: "5.39.222.64;82.197.173.130;82.197.173.129"
networks:
- qubic
healthcheck:
test: ["CMD", "wget", "-q", "--spider", "http://qubic-node-fetcher:8080/peers"]
interval: 30s
test: [ "CMD", "wget", "-q", "--spider", "http://127.0.0.1:8080/status" ]
interval: 5s
timeout: 5s
retries: 5
restart: always
Expand Down

0 comments on commit 7f90d93

Please sign in to comment.