Technical description of the platform

REST API: methods of the data service

https://img.shields.io/badge/auth-required-orange.svg

Following API methods are available for the data service:

Assets method group

The methods of the Assets group are used for obtaining of data about token sets (assets).

GET /assets

The method is used for obtaining the blockchain available assets list. The list consists of transactions for emission of the corresponding assets.

Response example:

GET /assets:
[
  {
    "index": 0,
    "id": "string",
    "name": "string",
    "description": "string",
    "reissuable": true,
    "quantity": 0,
    "decimals": 0
  }
]

POST /assets/count

The method returns a number of available assets in the blockchain.

Response example:

POST /assets/count:
{
  "count": 0
}

GET /assets/{id}

The method returns information about an available asset according to its {id}.

The response of the method contains following data:

  • index – asset index number;

  • id – asset identifier;

  • name – asset name;

  • description – asset description;

  • reissuable – reissuability of an asset;

  • quantity – the number of tokens in an asset;

  • decimals – number of decimal places in a used token (WEST – 8)

Response example:

GET /assets/{id}:
{
  "index": 14,
  "id": "12nx0qnhjd83",
  "name": "Demo asset",
  "description": "Demo asset",
  "reissuable": true,
  "quantity": 400,
  "decimals": 8
}

Blocks method group

GET /blocks/at/{height}

The method returns content of a block at a defined height.

The response of the method contains following parameters:

  • reference – block hash sum;

  • blocksize – size of a block;

  • featuresfeatures activated at the moment of block generation;

  • signature – block signature;

  • fee – total fee for the transactions included in a block;

  • generator – block creator address;

  • transactionCount – number of transactions included in a block;

  • transactions – array with bodies of transactions included in a block;

  • version – block version;

  • poa-consensus.overall-skipped-rounds – number of skipped mining rounds in case the PoA consensus algorithm is used;

  • timestamp – block Unix Timestamp (in milliseconds);

  • height – height of block generation.

Response example:

GET /blocks/at/{height}:
{
  "reference": "hT5RcPT4jDVoNspfZkNhKqfGuMbrizjpG4vmPecVfWgWaGMoAn5hgPBJpC9696TL8wGDKJzkwewiqe8m26C4aPd",
  "blocksize": 226,
  "features": [],
  "signature": "5GAM7jfQScw4g3g7PCNNtz5xG3JzjJnW4Ap2soThirSx1AmUQHQMjz8VMtkFEzK7L447ouKHfj2gMvZyP5u94Rps",
  "fee": 0,
  "generator": "3Mv79dyPX2cvLtRXn1MDDWiCZMBrkw9d97c",
  "transactionCount": 0,
  "transactions": [],
  "version": 3,
  "poa-consensus": {
    "overall-skipped-rounds": 1065423
  },
  "timestamp": 1615816767694,
  "height": 1826
}

Contracts method group

Methods of the Contracts group are used for obtaining of information about smart contracts of the blockchain.

GET /contracts

The method returns information about all smart contracts installed in the network. For each smart contract, following parameters are returned:

  • contractId – smart contract identifier;

  • image – name of a smart contract Docker image or its absolute path in its registry;

  • imageHash – smart contract hash sum;

  • version – smart contract version;

  • active – smart contract status at the moment of the query: true – working, false – not working.

Example of an answer for one smart contract:

GET /contracts:
[
  {
    "contractId": "dmLT1ippM7tmfSC8u9P4wU6sBgHXGYy6JYxCq1CCh8i",
    "image": "registry.wvservices.com/wv-sc/may14_1:latest",
    "imageHash": "ff9b8af966b4c84e66d3847a514e65f55b2c1f63afcd8b708b9948a814cb8957",
    "version": 1,
    "active": false
   }
 ]

GET /contracts/count

The method returns a number of smart contracts on a blockchain that correspond with defined provisions and filters.

Response example:

GET /contracts/count:
{
  "count": 19
}

GET /contracts/info/{contractId}

The method returns information about a smart contract with a definite {contractId}.

Response example:

GET /contracts/id/{id}:
{
  "creator": "9yxe6Kw9eiCD2mTNvKdrcQ1EoQqzMy7p52USZftBtQhp",
  "contractId": "7zcrHAFZmcZ3EGs7JWL5jCrbizCppu2rcpDDuChNTF6K",
  "image": "registry.wvservices.com/waves-enterprise-public/east-contract:v1.2",
  "imageHash": "baef03e82e4ecc723b85876111cbe25ed390ad7c62169e8a3ba142b6a2ad3000",
  "version": 5,
  "active": true,
  "validationPolicy": {
     "type": "majority_with_one_of",
     "addresses": [
       "3NyJPnLBdEQiPdHoHHgQAYX6UVj6GKMxgMx",
       "3NmHrYoC8S2SUosy6UJp47bBwq2Cr2X6Yq1",
       "3NrKDuHjUG7vSCiMMD259msBKcPRm4MvaJu"
     ]
  },
  "apiVersion": "1.0"
}

GET /contracts/id/{id}/versions

The method returns version history of a smart contract with a definite {id}.

Example of a response for one version:

GET /contracts/id/{id}/versions:
[
  {
    "version": 0,
    "image": "string",
    "imageHash": "string",
    "timestamp": "string"
  }
]

GET /contacts/history/{id}/key/{key}

Returns a history of changes of a {key} key for a smart contract with a definite {id}.

Example of a response for one key:

GET /contacts/history/{id}/key/{key}:
{
  "total": 777,
  "data": [
    {
      "key": "some_key",
      "type": "integer",
      "value": "777",
      "timestamp": 1559347200000,
      "height": 14024
    }
  ]
}

GET /contracts/senders-count

The method returns a number of unique participants that send transactions 104 for smart contract calls.

Response example:

GET /contracts/senders-count:
{
  "count": 777
}

GET /contracts/calls

The method returns a list of 104 transactions for smart contract calls with their parameters and results.

Example of a response for one transaction:

GET /contracts/calls:
[
  {
    "id": "string",
    "type": 0,
    "height": 0,
    "fee": 0,
    "sender": "string",
    "senderPublicKey": "string",
    "signature": "string",
    "timestamp": 0,
    "version": 0,
    "contract_id": "string",
    "contract_name": "string",
    "contract_version": "string",
    "image": "string",
    "fee_asset": "string",
    "finished": "string",
    "params": [
      {
        "tx_id": "string",
        "param_key": "string",
        "param_type": "string",
        "param_value_integer": 0,
        "param_value_boolean": true,
        "param_value_binary": "string",
        "param_value_string": "string",
        "position_in_tx": 0,
        "contract_id": "string",
        "sender": "string"
      }
    ],
    "results": [
      {
        "tx_id": "string",
        "result_key": "string",
        "result_type": "string",
        "result_value_integer": 0,
        "result_value_boolean": true,
        "result_value_binary": "string",
        "result_value_string": "string",
        "position_in_tx": 0,
        "contract_id": "string",
        "time_stamp": "string"
      }
    ]
  }
]

Privacy method group

Methods of the Privacy group are used for obtaining of information about confidential data groups.

GET /privacy/groups

The method returns a list of confidential data groups in the blockchain.

Example of a response for one group:

GET /privacy/groups:
[
  {
    "id": "string",
    "name": 0,
    "description": "string",
    "createdAt": "string"
  }
]

GET /privacy/groups/count

The method returns a number of confidential data groups in the blockchain.

Response example:

GET /privacy/groups/count:
{
  "count": 2
}

GET /privacy/groups/{address}

The method returns a list of confidential data groups that include a defined {address}.

Example of a response for one group:

GET /privacy/groups/{address}:
[
  {
    "id": "string",
    "name": 0,
    "description": "string",
    "createdAt": "string"
  }
]

GET /privacy/groups/by-recipient/{address}

The method returns a list of privacy data groups that include a defined {address} as a recipient of data.

Example of a response for one group:

GET /privacy/groups/by-recipient/{address}:
[
  {
    "id": "string",
    "name": 0,
    "description": "string",
    "createdAt": "string"
  }
]

GET /privacy/groups/{address}/count

The method returns a number of confidential data groups that include a defined {address}.

Response example:

GET /privacy/groups/{address}/count:
{
  "count": 1
}

GET /privacy/groups/id/{id}

The method returns information about a privacy data group with a definite {id}.

Response example:

GET /privacy/groups/id/{id}:
{
  "id": "string",
  "name": 0,
  "description": "string",
  "createdAt": "string"
}

GET /privacy/groups/id/{id}/history

The method returns a history of changes of a confidential data access group with a definite {id}. The history is returned as a list of sent 112-114 transactions with their descriptions.

Example of a response for one transaction:

GET /privacy/groups/id/{id}/history:
{
  "id": "string",
  "name": 0,
  "description": "string",
  "createdAt": "string"
}

GET /privacy/groups/id/{id}/history/count

The method returns a number of 112-114 transactions sent for changing of an access group with a definite {id}.

Response example:

GET /privacy/groups/id/{id}/history/count:
{
  "count": 0
}

GET /privacy/nodes

The method returns a list of available nodes in the blockchain.

Example of a response for one node:

GET /privacy/nodes:
[
  {
    "id": "string",
    "name": 0,
    "description": "string",
    "createdAt": "string"
  }
]

GET /privacy/nodes/count

The method returns a number of available nodes in the blockchain.

Response example:

GET /privacy/nodes/count:
{
  "count": 0
}

GET /privacy/nodes/publicKey/{targetPublicKey}

The method returns information about a node according to its {targetPublicKey}.

Response example:

GET /privacy/nodes/publicKey/{targetPublicKey}:
[
  {
    "id": "string",
    "name": 0,
    "description": "string",
    "createdAt": "string"
  }
]

GET /privacy/nodes/address/{address}

The method returns information about a node according to its {address}.

Response example:

GET /privacy/nodes/address/{address}:
[
  {
    "id": "string",
    "name": 0,
    "description": "string",
    "createdAt": "string"
  }
]

Transactions method group

Methods of the Transactions group are used for obtaining of information about transactions in the blockchain.

GET /transactions

The method returns a list of transactions corresponding with provisions of a search query and applied filters.

Important

The GET /transactions method returns not more than 500 transactions for one query.

Example of a response for one transaction:

GET /transactions:
[
 {
    "id": "string",
    "type": 0,
    "height": 0,
    "fee": 0,
    "sender": "string",
    "senderPublicKey": "string",
    "signature": "string",
    "timestamp": 0,
    "version": 0
 }

GET /transactions/count

The method returns a number of transactions corresponding with provisions of a search query and applied filters.

Response example:

GET /transactions/count:
{
"count": "116"
}

GET /transactions/{id}

The method returns a transaction according to its {id}.

Response example:

GET /transactions/{id}:
{
"id": "string",
"type": 0,
"height": 0,
"fee": 0,
"sender": "string",
"senderPublicKey": "string",
"signature": "string",
"timestamp": 0,
"version": 0
}

Users method group

Methods of the Users group are used for obtaining information about participants of the blockchain network.

GET /users

The method returns a list of participants corresponding with provisions of a search query and applied filters.

Example of a response for one participant:

GET /users:
[
  {
    "address": "string",
    "aliases": [
      "string"
    ],
    "registration_date": "string",
    "permissions": [
      "string"
    ]
  }
]

GET /users/count

The method returns a number of participants corresponding with filters applied in the query.

Example of a response for one participant:

GET /users/count:
{
  "count": 1198
}

GET /users/{userAddressOrAlias}

The method returns information about a participants according to his address or alias.

Response example:

GET /users/{userAddressOrAlias}:
{
  "address": "string",
  "aliases": [
    "string"
  ],
  "registration_date": "string",
  "permissions": [
    "string"
  ]
}

GET /users/contract-id/{contractId}

The method returns a list of participants that have ever called a smart contract with a definite {contractId}.

Example of a response for one participant:

GET /users/contract-id/{contractId}:
{
  "address": "string",
  "aliases": [
    "string"
  ],
  "registration_date": "string",
  "permissions": [
    "string"
  ]
}

POST /users/by-addresses

The method returns a list of participants for a definite set of addresses.

Example of a response for one participant:

POST /users/by-addresses:
{
  "address": "string",
  "aliases": [
    "string"
  ],
  "registration_date": "string",
  "permissions": [
    "string"
  ]
}

Methods for obtaining of information about data transactions (12)

This group of methods is called via the /api/v1/txIds/ route.

GET /api/v1/txIds/{key}

The method returns a list of identifiers for data transactions that include the defined {key}.

Example of a response for one transaction:

GET /api/v1/txIds/{key}:
[
  {
    "id": "string"
  }
]

GET /api/v1/txIds/{key}/{value}

The method returns a list of identifiers for data transactions that include defined {key} and {value}.

Example of a response for one transaction:

GET /api/v1/txIds/{key}/{value}:
[
  {
        "id": "string"
  }
]

GET /api/v1/txData/{key}

The method returns bodies of data transactions that include a defined {key}.

Example of a response for one transaction:

GET /api/v1/txData/{key}:
[
  {
    "id": "string",
    "type": "string",
    "height": 0,
    "fee": 0,
    "sender": "string",
    "senderPublicKey": "string",
    "signature": "string",
    "timestamp": 0,
    "version": 0,
    "key": "string",
    "value": "string",
    "position_in_tx": 0
  }
]

GET /api/v1/txData/{key}/{value}

The method returns bodies of data transactions that include defined {key} and {value}.

Example of a response for one transaction:

GET /api/v1/txData/{key}/{value}:
[
  {
    "id": "string",
    "type": "string",
    "height": 0,
    "fee": 0,
    "sender": "string",
    "senderPublicKey": "string",
    "signature": "string",
    "timestamp": 0,
    "version": 0,
    "key": "string",
    "value": "string",
    "position_in_tx": 0
  }
]

Leasing method group

GET /leasing/calc

The method returns a total sum for leasing of tokens in a specified block interval.

Response example:

GET /leasing/calc:
{
  "payouts": [
    {
      "leaser": "3P1EiJnPxFxGyhN9sucXfB2rhQ1ws4cmuS5",
      "payout": 234689
    }
  ],
  "totalSum": 4400000,
  "totalBlocks": 1600
}

Stats method group

Methods of the Stats group are used for obtaining statistical data and blockchain monitoring.

GET /stats/transactions

The method returns information about transactions that have been send within a specified time period.

Response example:

GET /stats/transactions:
{
  "aggregation": "day",
  "data": [
    {
      "date": "2020-03-01T00:00:00.000Z",
      "transactions": [
        {
          "type": 104,
          "count": 100
        }
      ]
    }
  ]
}

GET /stats/contracts

The method returns information about transactions 104 within a specified time period.

Response example:

GET /stats/contracts:
{
  "aggregation": "day",
  "data": [
    {
      "date": "2020-03-01T00:00:00.000Z",
      "transactions": [
        {
          "type": 104,
          "count": 100
        }
      ]
    }
  ]
}

GET /stats/tokens

The method returns information about turnover of tokens in the blockchain within a specified time period.

Response example:

GET /stats/tokens:
{
  "aggregation": "day",
  "data": [
    {
      "date": "2020-03-01T00:00:00.000Z",
      "sum": "12000.001"
    }
  ]
}

GET /stats/addresses-active

The method returns addresses that have been active within a specified time period.

Response example:

GET /stats/addresses-active:
{
  "aggregation": "day",
  "data": [
    {
      "date": "2020-03-01T00:00:00.000Z",
      "senders": "12",
      "recipients": "12"
    }
  ]
}

GET /stats/addresses-top

The method returns addresses that have been the most active senders or recipients within a specified time period.

Response example:

GET /stats/addresses-top:
{
  "aggregation": "day",
  "data": [
    {
      "date": "2020-03-01T00:00:00.000Z",
      "senders": "12",
      "recipients": "12"
    }
  ]
}

GET /stats/nodes-top

The method returns addresses of nodes that have created the largest number of blocks within a specified time period.

Response example:

GET /stats/nodes-top:
{
  "limit": "10",
  "data": [
    {
      "generator": "3NdPsjaFC7NeioGVF6X4J5A8FVaxdtKvAba",
      "count": "120",
      "node_name": "Genesis Node #5"
    }
  ]
}

GET /stats/contract-calls

The method returns a list of smart contracts that have been mostly called within a specified time period.

Response example:

GET /stats/contract-calls:
{
  "limit": "5",
  "data": [
    {
      "contract_id": "Cm9MDf7vpETuzUCsr1n2MVHsEGk4rz3aJp1Ua2UbWBq1",
      "count": "120",
      "contract_name": "oracle_contract",
      "last_call": "60.321"
    }
  ]
}

GET /stats/contract-last-calls

The method returns a list of last smart contract calls according to their IDs and names.

Response example:

GET /stats/contract-last-calls:
{
  "limit": "5",
  "data": [
    {
      "contract_id": "Cm9MDf7vpETuzUCsr1n2MVHsEGk4rz3aJp1Ua2UbWBq1",
      "contract_name": "oracle_contract",
      "last_call": "60.321"
    }
  ]
}

GET /stats/contract-types

The method returns a list of blockchain smart contracts according to their images and hashes.

Response example:

GET /stats/contract-types:
{
  "limit": "5",
  "data": [
    {
      "id": "Cm9MDf7vpETuzUCsr1n2MVHsEGk4rz3aJp1Ua2UbWBq1",
      "image": "registry.wvservices.com/waves-enterprise-public/oracle-contract:v0.1",
      "image_hash": "936f10207dee466d051fe09669d5688e817d7cdd81990a7e99f71c1f2546a660",
      "count": "60",
      "sum": "6000"
    }
  ]
}

GET /stats/monitoring

The method returns general information about the network.

Response example:

GET /stats/monitoring:
{
  "tps": "5",
  "blockAvgSize": "341.391",
  "senders": "50",
  "nodes": "50",
  "blocks": "500000"
}

Anchoring method group

Methods of the Anchoring group are used for obtaining of information about anchoring rounds.

GET /anchoring/rounds

The method returns a list of transactions that have been sent in anchoring rounds in accordance with specified provisions and filters.

Response example:

GET /anchoring/rounds:
[
  {
    "height": 0,
    "sideChainTxIds": [
      "string"
    ],
    "mainNetTxIds": [
      "string"
    ],
    "status": "string",
    "errorCode": 0
  }
]

GET /anchoring/round/at/{height}

The method returns information about an anchoring round at a specified block {height}.

Response example:

GET /anchoring/round/at/{height}:
{
  "height": 0,
  "sideChainTxIds": [
    "string"
  ],
  "mainNetTxIds": [
    "string"
  ],
  "status": "string",
  "errorCode": 0
}

GET /anchoring/info

The method returns information about the blockchain anchoring.

Response example:

GET /anchoring/info:
{
  "height": 0,
  "sideChainTxIds": [
    "string"
  ],
  "mainNetTxIds": [
    "string"
  ],
  "status": "string",
  "errorCode": 0
}

Auxiliary methods of the data service

GET /info

The method returns information about a data service in use.

Response example:

GET /info:
{
  "version": "string",
  "buildId": "string",
  "gitCommit": "string"
}

GET /status

The method returns information about status of the data service.

Response example:

GET /status:
{
  "status": "string"
}
See also