Skip to content
BranchesTags

Repository files navigation

The qubic http service

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

Building from source

go build -o "server" "./app/grpc_server"

Running the service

qubic-http requires an instance of qubic-nodes for fetching reliable node addresses.

Configuration

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

Required parameters

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"

Optional parameters

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_SERVER_MAX_BATCH_IDENTITIES: (default: 15)

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)

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 thequbic-nodes GitHub.
We assume that qubic-nodes is running locally on port 8080.

Export the required environment variables:

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:

./server

Available endpoints

Information related endpoints

/tick-info

curl http://localhost:8000/tick-info
{
  "tickInfo": {
    "tick": 13692242,
    "duration": 7,
    "epoch": 107,
    "initialTick": 13680000
  }
}

/block-height

curl http://localhost:8000/block-height
{
  "blockHeight": {
    "tick": 13692267,
    "duration": 0,
    "epoch": 107,
    "initialTick": 13680000
  }
}

/balances/{identity}

curl http://localhost:8000/balances/PKXGRCNOEEDLEGTLAZOSXMEYZIEDLGMSPNTJJJBHIBJISHFFYBBFDVGHRJQF
{
  "balance": {
    "id": "PKXGRCNOEEDLEGTLAZOSXMEYZIEDLGMSPNTJJJBHIBJISHFFYBBFDVGHRJQF",
    "balance": "0",
    "validForTick": 13692275,
    "latestIncomingTransferTick": 0,
    "latestOutgoingTransferTick": 0
  }
}

Transaction related endpoints

/broadcast-transaction

curl -X POST http://localhost:8000/broadcast-transaction -d '{"encodedTransaction": "..."}'
{
    "peersBroadcasted": 3,
    "encodedTransaction": "...",
    "transactionId": "oxmqdbynwbisqcjgphyaexhlknmaanipiyxpulatkdjxpdqsqtiovjhcxqkd"
}

Asset related endpoints

/assets/{identity}/issued

curl localhost:8000/assets/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB/issued
{
  "issuedAssets": [
    {
      "data": {
        "issuerIdentity": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB",
        "type": 1,
        "name": "RANDOM",
        "numberOfDecimalPlaces": 0,
        "unitOfMeasurement": [0, 0, 0, 0, 0, 0, 0]
      },
      "info": {
        "tick": 14057739,
        "universeIndex": 0
      }
    },
    {
      "data": {
        "issuerIdentity": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB",
        "type": 1,
        "name": "QX",
        "numberOfDecimalPlaces": 0,
        "unitOfMeasurement": [0, 0, 0, 0, 0, 0, 0]
      },
      "info": {
        "tick": 14057739,
        "universeIndex": 0
      }
    },
    {
      "data": {
        "issuerIdentity": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB",
        "type": 1,
        "name": "QTRY",
        "numberOfDecimalPlaces": 0,
        "unitOfMeasurement": [0, 0, 0, 0, 0, 0, 0]
      },
      "info": {
        "tick": 14057739,
        "universeIndex": 0
      }
    },
    {
      "data": {
        "issuerIdentity": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB",
        "type": 1,
        "name": "QUTIL",
        "numberOfDecimalPlaces": 0,
        "unitOfMeasurement": [0, 0, 0, 0, 0, 0, 0]
      },
      "info": {
        "tick": 14057739,
        "universeIndex": 0
      }
    }
  ]
}

/assets/{identity}/owned

curl localhost:8000/assets/IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC/owned
{
  "ownedAssets": [
    {
      "data": {
        "ownerIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
        "type": 2,
        "padding": 0,
        "managingContractIndex": 1,
        "issuanceIndex": 0,
        "numberOfUnits": "2",
        "issuedAsset": {
          "issuerIdentity": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB",
          "type": 1,
          "name": "RANDOM",
          "numberOfDecimalPlaces": 0,
          "unitOfMeasurement": [0, 0, 0, 0, 0, 0, 0]
        }
      },
      "info": {
        "tick": 14057652,
        "universeIndex": 0
      }
    },
    {
      "data": {
        "ownerIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
        "type": 2,
        "padding": 0,
        "managingContractIndex": 1,
        "issuanceIndex": 1,
        "numberOfUnits": "1",
        "issuedAsset": {
          "issuerIdentity": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB",
          "type": 1,
          "name": "QX",
          "numberOfDecimalPlaces": 0,
          "unitOfMeasurement": [0, 0, 0, 0, 0, 0, 0]
        }
      },
      "info": {
        "tick": 14057652,
        "universeIndex": 0
      }
    },
    {
      "data": {
        "ownerIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
        "type": 2,
        "padding": 0,
        "managingContractIndex": 1,
        "issuanceIndex": 9284980,
        "numberOfUnits": "186685601",
        "issuedAsset": {
          "issuerIdentity": "QWALLETSGQVAGBHUCVVXWZXMBKQBPQQSHRYKZGEJWFVNUFCEDDPRMKTAUVHA",
          "type": 1,
          "name": "QWALLET",
          "numberOfDecimalPlaces": 0,
          "unitOfMeasurement": [0, -48, 0, -48, 35, 24, 21]
        }
      },
      "info": {
        "tick": 14057652,
        "universeIndex": 0
      }
    },
    {
      "data": {
        "ownerIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
        "type": 2,
        "padding": 0,
        "managingContractIndex": 1,
        "issuanceIndex": 2741973,
        "numberOfUnits": "10",
        "issuedAsset": {
          "issuerIdentity": "TFUYVBXYIYBVTEMJHAJGEJOOZHJBQFVQLTBBKMEHPEVIZFXZRPEYFUWGTIWG",
          "type": 1,
          "name": "QFT",
          "numberOfDecimalPlaces": 0,
          "unitOfMeasurement": [84, 79, 75, 69, 78, 0, 0]
        }
      },
      "info": {
        "tick": 14057652,
        "universeIndex": 0
      }
    }
  ]
}

/assets/{identity}/possessed

curl localhost:8000/assets/IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC/possessed
{
  "possessedAssets": [
    {
      "data": {
        "possessorIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
        "type": 3,
        "padding": 0,
        "managingContractIndex": 1,
        "issuanceIndex": 9707976,
        "numberOfUnits": "2",
        "ownedAsset": {
          "ownerIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
          "type": 2,
          "padding": 0,
          "managingContractIndex": 1,
          "issuanceIndex": 9707976,
          "numberOfUnits": "2",
          "issuedAsset": {
            "issuerIdentity": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB",
            "type": 1,
            "name": "RANDOM",
            "numberOfDecimalPlaces": 0,
            "unitOfMeasurement": [0, 0, 0, 0, 0, 0, 0]
          }
        }
      },
      "info": {
        "tick": 14057759,
        "universeIndex": 0
      }
    },
    {
      "data": {
        "possessorIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
        "type": 3,
        "padding": 0,
        "managingContractIndex": 1,
        "issuanceIndex": 9707978,
        "numberOfUnits": "1",
        "ownedAsset": {
          "ownerIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
          "type": 2,
          "padding": 0,
          "managingContractIndex": 1,
          "issuanceIndex": 9707978,
          "numberOfUnits": "1",
          "issuedAsset": {
            "issuerIdentity": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB",
            "type": 1,
            "name": "QX",
            "numberOfDecimalPlaces": 0,
            "unitOfMeasurement": [0, 0, 0, 0, 0, 0, 0]
          }
        }
      },
      "info": {
        "tick": 14057759,
        "universeIndex": 0
      }
    },
    {
      "data": {
        "possessorIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
        "type": 3,
        "padding": 0,
        "managingContractIndex": 1,
        "issuanceIndex": 9707980,
        "numberOfUnits": "186685601",
        "ownedAsset": {
          "ownerIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
          "type": 2,
          "padding": 0,
          "managingContractIndex": 1,
          "issuanceIndex": 9707980,
          "numberOfUnits": "186685601",
          "issuedAsset": {
            "issuerIdentity": "QWALLETSGQVAGBHUCVVXWZXMBKQBPQQSHRYKZGEJWFVNUFCEDDPRMKTAUVHA",
            "type": 1,
            "name": "QWALLET",
            "numberOfDecimalPlaces": 0,
            "unitOfMeasurement": [0, -48, 0, -48, 35, 24, 21]
          }
        }
      },
      "info": {
        "tick": 14057759,
        "universeIndex": 0
      }
    },
    {
      "data": {
        "possessorIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
        "type": 3,
        "padding": 0,
        "managingContractIndex": 1,
        "issuanceIndex": 9707982,
        "numberOfUnits": "10",
        "ownedAsset": {
          "ownerIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
          "type": 2,
          "padding": 0,
          "managingContractIndex": 1,
          "issuanceIndex": 9707982,
          "numberOfUnits": "10",
          "issuedAsset": {
            "issuerIdentity": "TFUYVBXYIYBVTEMJHAJGEJOOZHJBQFVQLTBBKMEHPEVIZFXZRPEYFUWGTIWG",
            "type": 1,
            "name": "QFT",
            "numberOfDecimalPlaces": 0,
            "unitOfMeasurement": [84, 79, 75, 69, 78, 0, 0]
          }
        }
      },
      "info": {
        "tick": 14057759,
        "universeIndex": 0
      }
    }
  ]
}

/assets (batch)

Fetches the assets owned and possessed by several identities at once. The requests are pipelined over a single node connection, so one call costs roughly one round trip for the whole set instead of one per identity. Prefer this over calling /assets/{identity}/owned and /assets/{identity}/possessed in a loop.

Results are returned in the order the identities were given, and every requested identity appears in the response, with empty lists if it holds no assets. The list must contain between 1 and QUBIC_API_SIDECAR_SERVER_MAX_BATCH_IDENTITIES (default 15) identities, with no duplicates. All identities are validated before any node call, so a single malformed entry fails the whole request without fetching anything.

curl -X POST localhost:8000/assets \
  -H 'Content-Type: application/json' \
  -d '{"identities":["IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC"]}'
{
  "assets": [
    {
      "identity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
      "ownedAssets": [
        {
          "data": {
            "ownerIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
            "type": 2,
            "padding": 0,
            "managingContractIndex": 1,
            "issuanceIndex": 9707976,
            "numberOfUnits": "2",
            "issuedAsset": {
              "issuerIdentity": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB",
              "type": 1,
              "name": "RANDOM",
              "numberOfDecimalPlaces": 0,
              "unitOfMeasurement": [0, 0, 0, 0, 0, 0, 0]
            }
          },
          "info": {
            "tick": 14057759,
            "universeIndex": 0
          }
        }
      ],
      "possessedAssets": [
        {
          "data": {
            "possessorIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
            "type": 3,
            "padding": 0,
            "managingContractIndex": 1,
            "issuanceIndex": 9707976,
            "numberOfUnits": "2",
            "ownedAsset": {
              "ownerIdentity": "IGJQYTMFLVNIMEAKLANHKGNGZPFCFJGSMVOWMNGLWCZWKFHANHGCBYODMKBC",
              "type": 2,
              "padding": 0,
              "managingContractIndex": 1,
              "issuanceIndex": 9707976,
              "numberOfUnits": "2",
              "issuedAsset": {
                "issuerIdentity": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB",
                "type": 1,
                "name": "RANDOM",
                "numberOfDecimalPlaces": 0,
                "unitOfMeasurement": [0, 0, 0, 0, 0, 0, 0]
              }
            }
          },
          "info": {
            "tick": 14057759,
            "universeIndex": 0
          }
        }
      ]
    }
  ]
}

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

3 stars

Watchers

3 watching

Forks

5 forks
Report repository

Releases

Packages

Used by

Contributors

Languages