pragmaxim / ergo-uexplorer

Supplementary ergo chain explorer/analyzer with Scala/ZIO

Pragmaxim

👷 I enjoy being useful

ergo-uexplorer's Issues

REST API Specifications

Info

Endpoint:

get /info/

Response

{
  version: number,
  mode: "full" | "light",
  height: number,                  // indexed height
  additionalIndexes: {             // only return this if mode == "light"
    contracts: string[],
    contractTemplates: string[],
    tokenIds: string[]
  } | null
}

Block Info and Statistics

Endpoints

GET /blocks/
GET /blocks/{headerId:HexString}/
GET /blocks/at/{height:int}/

URL queries

skip: int
take: int

Boxes

Endpoints

GET  /boxes/{spent|unspent|all}/{boxId:HexString}/
GET  /boxes/{spent|unspent|all}/tokens/{tokenId:HexString}/
GET  /boxes/{spent|unspent|all}/addresses/{address:string}/
GET  /boxes/{spent|unspent|all}/contracts/{contract:HexString}/
GET  /boxes/{spent|unspent|all}/contracts/templates/{template:HexString}/

URL queries

skip: int
take: int

tokenId: HexString | "empty"

R4: HexString | "empty"
R5: HexString | "empty"
R6: HexString | "empty"
R7: HexString | "empty"
R8: HexString | "empty"
R9: HexString | "empty"

confirmed: boolean

• If confirmed is omitted or equal to null, then confirmed and unconfirmed boxes must be merged. Which means that new unconfirmed boxes must be added to returning array and confirmed boxes that are being spent in the mempool must be removed from the returning array.
• If a default ordering is needed for take and skip, I suggest using creationHeight and boxId, as creationHeight solely is not unique.

Custom query endpoint

dApp constantly need to query for multiple contracts/addresses/templates/tokens, to potentially reduce the amount of roundtrips, I propose a custom query endpoint as described below.

Endpoint

POST /boxes/query/

Body

{
  spent: boolean | null,

  addresses: string[] | null,
  contracts: HexString[] | null,
  templates: HexString[] | null,
  contractHashes: HexString[] | null,
  templateHashes: HexString[] | null,

  tokens: HexString[] | null,

  registers: {
    R4: HexString | "empty" | null,
    R5: HexString | "empty" | null,
    R6: HexString | "empty" | null,
    R7: HexString | "empty" | null,
    R8: HexString | "empty" | null,
    R9: HexString | "empty" | null
  } | null,

  skip: number | null,
  take: number | null
}

• addresses, contracts, templates, contractHashes, and templateHashes are exclusive.
• At least one of addresses, contracts, templates, contractHashes, templateHashes, or tokens needs to be defined for the query to be considered valid.

Response

Array<{
  boxId: HexString,
  transactionId: HexString,
  index: number,
  ergoTree: HexString,
  creationHeight: number,
  value: string,
  assets: { tokenId: HexString, amount: string }[]
  additionalRegisters: {
    R4?: HexString,
    R5?: HexString,
    R6?: HexString,
    R7?: HexString,
    R8?: HexString,
    R9?: HexString,
  },
  state: {
    confirmed: boolean,
    spent: boolean,
  }
}>

• JavaScript doesn't work well with JSON and long numbers, so box.value and box.assets.amounts must be typed as string, for improved compatibility.

Tokens

Endpoints

GET /tokens/{tokenId}/                // parsed token metadata
GET /tokens/{tokenId}/minting-box/

Node Relay Endpoints

The following endpoint will serve as proxy endpoint for the node behind running uexplorer instance.

Endpoints

GET  /node/headers/last/{count:int}/  // --> node's GET  /blocks/lastHeaders/{count}/ endpoint
GET  /node/info/                      // --> node's GET  /info/ endpoint
POST /node/transaction/               // --> node's POST /transactions/ endpoint
POST /node/transaction/check/         // --> node's POST /transactions/check/ endpoint

Data model for lightweight mode on MvStorage

Schema for embedded database

Finding out if any box related data have been spent or not in query time puts huge pressure on DB
=> let's do that at indexing time so that queries are real-time !

Shared

headerIdsByHeight:  Map[Height, Set[HeaderId]] // more than one in case of a fork-in-progress
blockByHeaderId:    Map[HeaderId, Block] // arbitrary block data (depends on performance)

Unspent/NonEmpty

utxosByAddress:     Map[Address, Map[BoxId, Value]] // this would be a clone of Node's utxo state
addressByUtxo:      Map[BoxId, Address] // non-empty address by utxo

Spent

allBoxesByCustomAddress:     Map[Address, Set[BoxId]] // all boxes for a configured address by a dApp developer

There can be many of these indexes, please provide your suggestions and use-cases!

Facts to consider :

• some bare minimum of data like UtxoState is going to be indexed for all data
• arbitrary data, especially spent inputs (tens of millions of records) could be configurable for specific addresses
  so that dApps developers can customize the explorer for their needs

Eventually the Http API will allow for retrieving anything that can be put together from these persistent Maps.

Problematic queries on current explorer schema

• Unspent boxes by address or ErgoTree
• Unspent boxes by tokenId
• Unspent boxes by register
• Transactions by address or ErgoTree