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