Build in API Queries

The following build-in queries are by default available for the Server. The Validana Client assumes these functions are available for some of its higher level functions and it is recommended that any extensions to the Server also support these functions, which can be added using addBasics(MyRequestHandler).

Get transaction:

Description: Get information about a transaction that has been done.

Type: transaction

Request data (object):

• txId (string): The hexadecimal id of the transaction you want to know about.
• wait (boolean | undefined): Whether you want to wait with the response till the transaction is processed.
• push (boolean | undefined): Whether you want to receive a push update once the transaction is available if (and only if) it is not currently available. If wait is set to true this will be ignored.

Response data (object | undefined): None if the transaction does not exist and not using wait, otherwise:

• id (string): The hexadecimal id of the transaction.
• contractHash (string): The hexadecimal smart contract hash the transaction invoked.
• payload (string): The payload the transaction to invoke the smart contract with.
• publicKey (string): The hexadecimal public key of the one who created this transaction.
• signature (string): The hexadecimal signature used to sign this transaction.
• status ("accepted" | "rejected" | "invalid"): The status of the transaction.
• createTs (number | undefined | null): The time at which the transaction was created according to the creator of the transaction or null if the creator did not specify a time. Only available for the processor, will be undefined for any nodes.
• sender (string | null): The address of the sender or null if the transaction is invalid.
• blockId (number | null): The block the transaction is in or null if it is invalid.
• positionInBlock (number | null): The position in the block it is in or null if it is invalid.
• processedTs (number): The time at which the transaction has been processed (seconds since 1970).
• receiver (string | null): The receiver of the transaction or null if it has no receiver or is invalid.
• thirdParty (string | null): The third party involved in the transaction or null if it has no third party or is invalid.
• contractType (string | null): The name of the smart contract this transaction invoked or null of it is invalid. (Could also be along the lines of "Unknown contract" if it tries to invoke a non-existing contract.)
• message (string): The message about how this transaction has been processed. "OK" in case the transaction has been processed successfully, or otherwise a description of what was wrong.

Push type: None if the transaction did exist, "transaction" otherwise. (See below for push types.)

Example request:

{
    "txId": "5e44b4b647709017f8541a618058914d"
}

Example response (Note that the this is just sample data and does not have a valid signature):

{
    "id": "5e44b4b647709017f8541a618058914d",
    "contractHash": "fa8ee58a65d5b0a3ba1e79fd32981de4639ec543d0511ab6be8e5fa7ed3dc038",
    "payload": "{\"receiver\":\"1DeBrPno16P67xgUz5cfQeCLCwhjH58rZp\"}",
    "publicKey": "02cfcc9a66a51bf6cafd0e7670d3c86d20241aa59e998af92cb30ee9750e8e481b",
    "signature": "1bedf26c2acff31c2f24daea52de17bf852f5116944a0c46288958114b346ab36f17177b20a0cd01c52228c8245727e09e5dc0fff5f30eaa39fc0be6eabb32683a",
    "status": "accepted",
    "createTs": 1526376762586,
    "sender": "1PC89qCx4ZP8EtxTTghEqFRdVQkr4dBs9N",
    "blockId": 64,
    "positionInBlock": 0,
    "processedTs": 1526376766,
    "receiver": "1DeBrPno16P67xgUz5cfQeCLCwhjH58rZp",
    "thirdParty": null
    "contractType": "Something",
    "message": "OK"
}

Get transaction status:

Description: Get the status of a transaction.

Type: txStatus

Request data (object):

• txId (string | undefined): The hexadecimal id of the transaction you want to know about.
• wait (boolean | undefined): Whether you want to wait with the response till the transaction is processed.
• push (boolean| undefined): Whether you want to receive a push update once the transaction is available if (and only if) it is not currently available. If wait is set to true this will be ignored.

Response data (string | None): The status of the transaction or none if the transaction does not exist or is not yet processed.

Push type: None if the transaction did exist, "transaction" otherwise. (See below for push types.)

Example request:

{
    "txId": "5e44b4b647709017f8541a618058914d"
}

Example response: "accepted"

Get smart contracts:

Description: Get a list of all smart contracts available for this blockchain including what data they expect.

Type: contracts

Request data: none | string (contract type)

Response data (object array):

• type (string): The type of contract, for example "Institution". If a contract type is provided in the request only contracts with that type are returned.
• hash (string): Hex encoded hash of the contract.
• version (string): The version of the contract.
• description (string): A description of the contract
• template (object): key
  • type (string): The type of field, for example "addr" or "int" or "bool".
  • desc (string): A (suggested) description for this key.
  • name (string): A (suggested) name for this key.
• validanaVersion (number): The version of Validana this contract was created for.

Example response:

[
    {
        "type": "Something",
        "hash": "fa8ee58a65d5b0a3ba1e79fd32981de4639ec543d0511ab6be8e5fa7ed3dc038",
        "version": "1.0",
        "description": "Does something.",
        "template": {
            "receiver": {
                "type": "addr",
                "description": "The receiver of something.",
                "name": "Receiver"
            }
        },
        "validanaVersion": 2
    }
]

Get time

Description: Get the time of the latest block that has been processed.

Type: time

Request data: None

Response data (number): The time that last block available was processed (milliseconds since unix epoch). Note that this is likely earlier than the current time, as it takes some time for blocks to propagate the network.

Example response: 12345

Process Transaction

Description: Add a transaction to the blockchain to be processed.

Type: process

Request data (object):

• base64tx (string): A base64 encoded transaction, which exists of:
  • The total length of the data below (4 bytes little endian uint)
  • The transaction version (1 bytes uint)
  • The transactionId (16 bytes random data)
  • The contractHash (32 bytes)
  • Valid till (little endian double)
  • The payload
  • The signature: Should be an elliptic curve signature (using the secp256k1 curve) of the sha256 of the sha256 hash (yes, twice) of the above listed data except for the total length, prefixed with a unique string, in this case: (utf8): example, (hex): 6578616d706c65. The signature should be formatted as 32 bytes r followed by 32 bytes s.
  • The publicKey: ECDSA public key in compressed form (33 bytes).
• createTs (number | undefined): A timestamp at which this transaction was created (Unix timestamp in milliseconds). It is used to determine the order transactions are processed in.
• wait (boolean | undefined): Whether to wait till the transaction is processed before returning. If set to true a 200 or 422 status code will be returned depending on success, as well as returning the processed transaction. Otherwise a 202 status code is returned.

Response data: None or same as get transaction if wait is set to true.

Example transaction:

• transaction version: 1
  • hex: 01
• transactionId: A randomly generated 16 bytes of data (use a good random to prevent collisions, as your transaction will be denied).
  • hex: 1dc4b0e0227744926ee3328abaf9b22a
• contractHash: As obtained from the get contracts request.
  • hex: fa8ee58a65d5b0a3ba1e79fd32981de4639ec543d0511ab6be8e5fa7ed3dc038
• validTill: Any time you want the transaction to be valid till, in this case 1 (millisecond after unix epoch):
  • hex: 000000000000f03f
• payload: What you want to do with the contract.
  • utf8: {"receiver":"1DeBrPno16P67xgUz5cfQeCLCwhjH58rZp"}
  • hex: 7b227265636569766572223a223144654272506e6f31365036377867557a3563665165434c4377686a483538725a70227d
• Data to hash (hex): 6578616d706c65 01 1dc4b0e0227744926ee3328abaf9b22a 000000000000f03f 7b227265636569766572223a223144654272506e6f31365036377867557a3563665165434c4377686a483538725a70227d
• 2x sha256 hash of data (hex): f64ae382a2961e3f193209d86db18c4e8e9cc96bdccf587a98f01ee4630362ee
• Key used for signing:
  • Private (wif): L2YMT1PbeXgscMYX2SCEncc36XNU14ebKVWhB7tRU9jF1otAsCVz
  • Public (hex): 02cfcc9a66a51bf6cafd0e7670d3c86d20241aa59e998af92cb30ee9750e8e481b
• Generated signature (r followed by s) (hex)  (Note that signature is random, do not expect the exact same result): 553b76b0738ba6932960834e75910ce78c2be3610ccd97544af26583064948470f5ba6749e20a955a8d262ea2596a1ac1ec74b222f53924eebe3bb6972f22bca
• Total length of all data: 171 bytes
  • hex: ab000000
• Data in base64 transaction: ab000000 01 1dc4b0e0227744926ee3328abaf9b22a 000000000000f03f 7b227265636569766572223a223144654272506e6f31365036377867557a3563665165434c4377686a483538725a70227d 553b76b0738ba6932960834e75910ce78c2be3610ccd97544af26583064948470f5ba6749e20a955a8d262ea2596a1ac1ec74b222f53924eebe3bb6972f22bca 02cfcc9a66a51bf6cafd0e7670d3c86d20241aa59e998af92cb30ee9750e8e481b

Example request:

{
    "base64tx": "qwAAAAEdxLDgIndEkm7jMoq6+bIqAAAAAAAA8D97InJlY2VpdmVyIjoiMURlQnJQbm8xNlA2N3hnVXo1Y2ZRZUNMQ3doakg1OHJacCJ9VTt2sHOLppMpYINOdZEM54wr42EMzZdUSvJlgwZJSEcPW6Z0niCpVajSYuollqGsHsdLIi9Tkk7r47tpcvIrygLPzJpmpRv2yv0OdnDTyG0gJBqlnpmK+SyzDul1Do5IGw==",
    "createTs": 1519636250
}

Get metrics:

Description: Get metrics collected by the server. Only available if METRICSINTERVAL and METRICSTOKEN are defined in the config.

Type: metrics

Request data: (object):

• format (string): The format to receive the metrics in. Build-in formats are 'json' and 'prometheus'.
• token (string): Must match the token provided in the config.

Response data: Depends on requested format.