Validator

Get latest data requests
GET /data-requests
Description
Retrieve the latest block headers. If at least one data request is present in a block, the block data is also returned. The notion of "latest" is determined by the query parameter oldBlockHeight and the ledger's current height. Validators use this endpoint to get the latest relevant blocks, extract the data requests in them, and respond to the data requests accordingly.
Using the block data, one can compute the data hash and verify consistency of the block header. In addition, using the block headers, one can verify the blocks are chained.
Parameters
Name
In
Type
Required
Description
oldBlockHeight
query
integer
true
Number of blocks the validator has already processed
Example
GET /data-requests?oldBlockHeight=1
Responses
Status
Meaning
Description
Schema
200
​OK​
Succeeded
Inline
400
Bad Request
Request is invalid
​ApiResponse​
401
​Unauthorized​
API key is missing or invalid
​ApiResponse​
200 OK
Successfully retrieved the blocks and block data which contain data requests.
Schema
Name
Type
Required
Restrictions
Description
ok
boolean
true
none
none
blocks
dict<BlockNumber, Block>
true
none
none
Example
{
    "ok": true,
    "blocks": {
        "1": {
            "header": {
                "number": "1",
                "previousHash": "0ede53fd38d632f3a7d849f8ba8f70c851d772b53cecbc9d858fe7c8af03a858",
                "dataHash": "ee967360a911deb8f6bd77cbb49b334e1837c006c9b6cb2d59d8acd41964a6ac",
            },
        },
        "2": {
            "header": {
                "number": "2",
                "previousHash": "78aecc3976f7b2151ce0574278f816b8e5983e18229fde7b6e7c3ebdf5147baf",
                "dataHash": "3ec339eae416289f4ddd7dc2b69e8edf12ac013089207732ad6156e02dc21fb5",
            },
            "data": {
                "data": ["datum1==", "datum2=="],
            },
        },
    },
}
400 Bad Request
Request is malformed. Make sure:
oldBlockHeight is present in query parameter
oldBlockHeight is a non-negative number
oldBlockHeight is an integer
oldBlockHeight is valid - no larger than the current block height of the ledger
Example 1
{
    "ok": false,
    "message": "query.oldBlockHeight must be a non-negative integer",
}
Example 2
{
    "ok": false,
    "message": "Invalid valid at query.oldBlockHeight. Expected: <=5; given: 10",
}
401 Unauthorized
API key is missing or incorrect.
Example
{
    "ok": false,
    "message": "Unauthorized",
}
Get hashed trustee shares in an Encryption
GET /encryptions/{token-hash}/hashed-trustee-shares
Description
Retrieves all the hashed trustee share from an Encryption. After receiving a new data request, before the validator attempt to respond to it, it should check if the threshold number of trustees have correctly responded to the data request. It can do this by checking consistent the shares and their hashes uploaded by the encryptor at encryption time. The former are the return values of this endpoint.
Parameters
Name
In
Type
Required
Description
token-hash
path
​Sha256​
true
Hash value of the token
Example
GET /encryptions/d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4/hashed-trustee-shares
Responses
Status
Meaning
Description
Schema
200
​OK​
Succeeded
Inline
401
​Unauthorized​
API key is missing or invalid
​ApiResponse​
404
Not Found
Encryption not found
​ApiResponse​
200 OK
Successfully retrieved the hashed trustee shares.
Schema
Name
Type
Required
Description
ok
boolean
true
none
hashedTrusteeShare
dict<TrusteeId, Sha256>
true
A mapping from a trustee ID to its hashed share
Example
{
  "ok": true,
  "hashedTrusteeShare": {
      "trustee1": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
      "my_trustee-2": "486ea46224d1bb4fb680f34f7c9ad96a8f24ec88be73ea8e5a6c65260e9cb8a7",
  },
}
401 Unauthorized
API key is missing or incorrect.
Example
{
    "ok": false,
    "message": "Unauthorized",
}
404 Not Found
The encryption does not exist.
Example
{
    "ok": false,
    "message": "Encryption with token hash d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4 not found",
}
Get encrypted validator share in an Encryption
GET /encryptions/{token-hash}/encrypted-validator-shares/{validator-id}
Description
Retrieves an encrypted validator share from an Encryption. After receiving a new data request, a validator should use this endpoint to get its encrypted share from the corresponding Encryption, decrypt it with its decryption key, then post the result with postValidatorResponse.
Parameters
Name
In
Type
Required
Description
token-hash
path
​Sha256​
true
Hash value of the token
validator-id
path
​ValidatorId​
true
The validator's ID
Example
GET /encryptions/d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4/encrypted-validator-shares/validator1
Responses
Status
Meaning
Description
Schema
200
​OK​
Succeeded
Inline
400
Bad Request
Request is invalid
​ApiResponse​
401
​Unauthorized​
API key is missing or invalid
​ApiResponse​
404
Not Found
Encryption not found
​ApiResponse​
200 OK
Successfully retrieved the encrypted validator share.
Schema
Name
Type
Required
Description
ok
boolean
true
none
encryptedValidatorShare
​Base64​
true
The encrypted validator share
Example
{
  "ok": true,
  "encryptedValidatorShare": "base64_encoded_data"
}
400 Bad Request
Validator does not exist or does not reference this PAD instance.
Example
{
    "ok": false,
    "message": "Validator with ID validator1 does not exist in the PAD instance",
}
401 Unauthorized
API key is missing or incorrect.
Example
{
    "ok": false,
    "message": "Unauthorized",
}
404 Not Found
The encryption does not exist.
Example
{
    "ok": false,
    "message": "Encryption with token hash d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4 not found",
}
Post validator response
POST /data-requests/{token}/validator-responses
Description
Posts a validator response to the ledger.
After retrieving and finish decrypting its share, the validator needs to post the result back to the ledger so that eventually, the decryptor can decrypt a secret. The validator shares combining also reveals the identity of the decryptor.
Parameters
Name
In
Type
Required
Description
token
path
​Token​
true
ID of the data request
-
body
​SignedValidatorResponse​
true
The decrypted share, along with a digital signature of the validator and some metadata
Example
POST /data-requests/e3b0c44298fc1c149afbf4c8996fb924/validator-responses
{
  "validatorResponse": "{\"padName\":\"my-pad-1.0\",\"token\":\"e3b0c44298fc1c149afbf4c8996fb924\",\"validatorShare\":\"0110\",\"type\":\"validator_response\",\"validatorId\":\"validator1\"}",
  "signature": {
    "signerMetadata": {
      "id": "validator1",
      "fullName": "Validator-1",
      "role": "Validator"
    },
    "payload": "MEQCIDbFV8FH8ZTbM0wrKPHSk0lrkiIFsP3/GcU4htiGc6XOAiBOqJZgbeUKxPXgIOZGek6ryoJ+jhmwbcJh0+mSHsSiTQ=="
  }
}
Responses
Status
Meaning
Description
Schema
200
​OK​
Succeeded
​ApiResponse​
400
Bad Request
Data request and trustee response are inconsistent
​ApiResponse​
401
​Unauthorized​
API key is missing or invalid
​ApiResponse​
403
Forbidden
Trustee is not in the instance
​ApiResponse​
404
Not found
Data request not found
​ApiResponse​
409
Conflict
Response has been made before
​ApiResponse​
200 OK
Validator response is successfully post.
Example
{
    "ok": true,
    "message": "Successfully posted validator response",
}
400 Bad request
Request is invalid. Make sure that :
padName in ValidatorResponse is consistent with the PAD instance to which the API key is pointing
token in path and ValidatorResponse are consistent
validatorId in ValidatorResponse and signature are consistent
role is Validator in signature
signature in signature is consistent with the payload ValidatorResponse
Example 1
{
    "ok": false,
    "message": "Inconsistent validator ID",
}
example 2
{
    "ok": false,
    "message": "Inconsistent PAD instance name",
}
example 3
{
    "ok": false,
    "message": "Invalid signature",
}
401 Unauthorized
Api key is missing or invalid.
Example
{
    "ok": false,
    "message": "Unauthorized",
}
403 Forbidden
The validator is not part of the instance. Recall that the list of validators is determined by the Operator at instance creation time.
Example
{
    "ok": false,
    "message": "Not a validator of the instance",
}
404 Not Found
The server cannot find a data request pointed by the token in the path parameter.
Example
{
    "ok": false,
    "message": "Data request not found",
}
409 Conflict
A response from the same validator has been made for the same data request before.
Example
{
    "ok": false,
    "message": "Validator response has been made for this request",
}
Schemas
ApiResponse
Example
{
  "ok": true,
  "message": "string"
}
Schema
Name
Type
Required
Description
ok
boolean
true
The request is successful or not
message
string
true
none
BlockNumber
ID of a block. It is an incremental index starting from 0. For example, if a ledger has height 10, then it has blocks 0, 1, ..., 9. The next block has block number 10.
Schema
Type
Restrictions
integer
Non-negative
Block
Blocks are put sequentially as a blockchain to form a ledger. It consists of the header (which contains the chaining information) and optionally the data (from which data requests and trustee and validator responses can be extracted).
Example 1
{
    "header": {
        "number": "1",
        "previousHash": "0ede53fd38d632f3a7d849f8ba8f70c851d772b53cecbc9d858fe7c8af03a858",
        "dataHash": "ee967360a911deb8f6bd77cbb49b334e1837c006c9b6cb2d59d8acd41964a6ac",
    },
}
Example 2
{
    "header": {
        "number": "2",
        "previousHash": "78aecc3976f7b2151ce0574278f816b8e5983e18229fde7b6e7c3ebdf5147baf",
        "dataHash": "3ec339eae416289f4ddd7dc2b69e8edf12ac013089207732ad6156e02dc21fb5",
    },
    "data": {
        "data": ["datum1==", "datum2=="],
    },
}
Schema
Name
Type
Required
Description
header
​BlockHeader​
true
none
data
​BlockData​
false
none
BlockHeader
Block header contains metadata of a block. They are sufficient to prove the blocks form a chain without the need of block data, because the previousHash field in the schema refers to the hash of the previous block header, instead of the entire previous block. Thus, if the block data is irrelevant (for example not containing any data request when one is asking for them), it can be skipped.
If the block number is 0, the number and previousHash fields are empty. dataHash is computed with the same block's data. Refer to code samples on how to compute hash of a block header.
Example 1
{
    "dataHash": "b24fd1a8c0c37f388f67ce6583710e3b1e5cfa79e652f764e92ee412299ac6c5",
}
Example 2
{
    "number": "1",
    "previousHash": "0ede53fd38d632f3a7d849f8ba8f70c851d772b53cecbc9d858fe7c8af03a858",
    "dataHash": "ee967360a911deb8f6bd77cbb49b334e1837c006c9b6cb2d59d8acd41964a6ac",
}
Schema
Name
Type
Required
Description
number
​BlockNumber​
false
Block number of the current block
previousHash
​Sha256​
false
Hash of the previous block's header
dataHash
​Sha256​
true
Hash of this block's data
BlockData
Block data contains "transactions". In PAD, these are the data requests and trustee and validator responses. See code samples to see how block data are decoded.
Example
{
    "data": ["datum1==", "datum2=="],
}
Schema
Name
Type
Required
Description
data
array<Base64>
true
none
Base64
A base64-encoded binary data.
Example
"aGVsbG8gd29ybGQ="
Schema
Type
Restrictions
string
none
Sha256
A Sha256 hash value as a hexidecimal string.
Example
"d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4"
Schema
Type
Restrictions
string
/[0-9a-fA-F]{64}/
TrusteeId
ID of a trustee. It contains only alphanumerical characters, underscores (_) and dashes (-). It has length inclusively between 3 and 30.
Example
trustee1
Schema
Type
Restrictions
string
[a-zA-Z0-9-_]{3,30}
ValidatorId
ID of a validator. It contains only alphanumerical characters, underscores (_) and dashes (-). It has length inclusively between 3 and 30.
Example
validator1
Schema
Type
Restrictions
string
[a-zA-Z0-9-_]{3,30}
Token
A 128-bit random string kept secret between the encryptor and decryptor after encryption stage and before data request stage. It identifies a data request. Its hash value identifies an encryption. The decryptor posts it on the ledger at data request stage.
Example
"0fe5ff17c6ee6efa8ca385587b1e1ac2"
Schema
Type
Restrictions
string
/[0-9a-fA-Z]{32}/
PadName
ID of a PAD instance. Its length must be inclusively between 4 and 30. It should contains only lowercase letters, digits, periods (.) or dashes (-). It must start with a lowercase letter.
It is seldom used as a request parameter because the API key in the request already identifies a PAD instance.
Example
"my-pad-1.0"
Schema
Type
Restrictions
string
/[a-z][a-z0-9.-]{3,29}/
ValidatorResponse
A validator response to a data request. It contains the decrypted validator share for the decryptor to perform a full decryption on a secret. It also consists of metadata for identifying the corresponding data request.
Example
{
    "padName": "my-pad-1.0",
    "token": "e3b0c44298fc1c149afbf4c8996fb924",
    "validatorShare": "0110",
    "type": "validator_response",
    "validatorId": "validator1",
}
Schema
Name
Type
Required
Restrictions
Description
padName
​PadName​
true
none
The instance where the data request is posted
token
​Token​
true
none
The ID of the data request
validatorShare
​Base64​
true
none
The decrypted validator share
type
enum
true
none
Type of response
validatorId
​ValidatorId​
true
none
ID of the responding validator
Enumerated Values
Property
Value
type
"validator_response"
SignedValidatorResponse
A validator response attached with a digital signature for everyone to validate the response's integrity.
Note that the validator response is represented as a string (instead of an object). This ensures that there is a unified way to verify the signature.
Example
{
  "validatorResponse": "{\"padName\":\"my-pad-1.0\",\"token\":\"e3b0c44298fc1c149afbf4c8996fb924\",\"validatorShare\":\"0110\",\"type\":\"validator_response\",\"validatorId\":\"validator1\"}",
  "signature": {
    "signerMetadata": {
      "id": "validator1",
      "fullName": "Validator-1",
      "role": "Validator"
    },
    "payload": "MEQCIDbFV8FH8ZTbM0wrKPHSk0lrkiIFsP3/GcU4htiGc6XOAiBOqJZgbeUKxPXgIOZGek6ryoJ+jhmwbcJh0+mSHsSiTQ=="
  }
}
Schema
Name
Type
Required
Description
validatorResponse
string<ValidatorResponse>
true
none
signature
​Signature​
true
none
Participant
Metadata of a participant in PAD. It can currently be used to describe a trustee or a validator.
Example
{
  "id": "validator1",
  "fullName": "Validator-1",
  "role": "Validator"
}
Schema
Name
Type
Required
Description
id
​TrusteeId or ValidatorId​
true
/[0-9a-zA-Z-_]{3,30}/
fullName
string
true
/Trustee-[0-9a-zA-Z_]+/ or /Validator-[0-9a-zA-Z_]+/
role
enum
true
none
Enumerated Values
Property
Value
role
Trustee
role
Validator
role
Server
Signature
A digital signature. It consists of the metadata of the signer, including its ID, and the signature payload encoded in base64.
Schema
{
  "signerMetadata": {
    "id": "string",
    "fullName": "string",
    "role": "Trustee",
  },
  "payload": "MEQCIDbFV8FH8ZTbM0wrKPHSk0lrkiIFsP3/GcU4htiGc6XOAiBOqJZgbeUKxPXgIOZGek6ryoJ+jhmwbcJh0+mSHsSiTQ==",
}
Schema
Name
Type
Required
Description
signerMetadata
​Participant​
false
none
payload
​Base64​
false
none
Trustee
Auditor
Last modified 8mo ago