Trustee
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. Trustees 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
Example
GET /data-requests?oldBlockHeight=1
Responses
200 OK
Successfully retrieved the blocks and block data which contain data requests.
Schema
Example
400 Bad Request
Request is malformed. Make sure:
oldBlockHeight
is present in query parameteroldBlockHeight
is a non-negative numberoldBlockHeight
is an integeroldBlockHeight
is valid - no larger than the current block height of the ledger
Example 1
Example 2
401 Unauthorized
API key is missing or incorrect.
Example
Get encrypted trustee share in an Encryption
Encryption
GET /encryptions/{token-hash}/encrypted-trustee-shares/{trustee-id}
Description
Retrieves a encrypted trustee share from an Encryption
. After detecting a new data request, a trustee should use this endpoint to get its encrypted share from the corresponding Encryption
, decrypt it with its decryption key, then post the result with postTrusteeResponse.
Parameters
Example
GET /encryptions/d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4/encrypted-trustee-shares/trustee1
Responses
200 OK
Successfully retrieved the encrypted trustee share.
Schema
Example
400 Bad Request
Trustee does not exist or does not reference this PAD instance.
Example
401 Unauthorized
API key is missing or incorrect.
Example
404 Not Found
The encryption does not exist.
Example
Post trustee response
POST /data-requests/{token}/trustee-responses
Description
Posts a trustee response to the ledger.
After retrieving and finish decrypting its share, the trustee needs to post the result back to the ledger so that eventually, the decryptor can decrypt a secret.
Parameters
Example
POST /data-requests/e3b0c44298fc1c149afbf4c8996fb924/trustee-responses
Responses
200 OK
The trustee response is successfully posted.
Example
400 Bad request
Request is invalid. Make sure that :
padName
inTrusteeResponse
is consistent with the PAD instance to which the API key is pointingtoken
in path andTrusteeResponse
are consistenttrusteeId
inTrusteeResponse
andsignature
are consistentrole
isTrustee
insignature
signature in
signature
is consistent with the payloadTrusteeResponse
Example 1
example 2
example 3
401 Unauthorized
Api key is missing or invalid.
Example
403 Forbidden
The trustee is not part of the instance. Recall that the list of trustees is determined by the Operator at instance creation time.
Example
404 Not Found
The server cannot find a data request pointed by the token in the path parameter.
Example
409 Conflict
A response from the same trustee has been made for the same data request before.
Example
Post trustee attestation
PUT /trustee-attestations/{trustee-id}
Description
Trustee posts its view of the ledger* with a digital signature. This allows other users to convince themselves that they are seeing the same ledger as trustees, who are the ones handling the data requests. Trustees should attest to the ledger regularly even there is no update on the ledger.
*The ledger view of the trustee includes the ID/name of the PAD instance, the height of the ledger, the current block hash of the ledger and a timestamp when the trustee construct the attestation.
Parameters
Example
PUT /trustee-attestations/trustee1
Responses
200 OK
Successfully posted trustee attestation.
Example
400 Bad request
Request is malformed. Check that:
Trustee IDs in attestation and path parameter are consistent.
padName
in attestation is consistent with the PAD instance to which the API key is pointingThe signature is correct
The attestation is correct, in the sense that:
The block height is non-negative and at most even with the ledger
currentHash
is the block hash atheight
Example 1
Example 2
Example 3
401 Unauthorized
Api key is missing or invalid.
Example
403 Forbidden
The trustee is not part of the instance. Recall that the list of trustees is determined by the Operator at instance creation time.
Example
Schemas
ApiResponse
Example
Schema
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
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
Example 2
Schema
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
Example 2
Schema
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
Schema
Base64
A base64-encoded binary data.
Example
Schema
Sha256
A Sha256 hash value as a hexidecimal string.
Example
Schema
TrusteeId
ID of a trustee. It contains only alphanumerical characters, underscores (_) and dashes (-). It has length inclusively between 3 and 30.
Example
Schema
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
Schema
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
Schema
TrusteeResponse
A trustee response to a data request. It contains the decrypted trustee share for the decryptor to perform a full decryption on a secret. It also consists of metadata for identifying the corresponding data request.
Example
Schema
Enumerated Values
SignedTrusteeResponse
A trustee response attached with a digital signature for everyone to validate the response's integrity.
Note that the trustee response is represented as a string (instead of an object). This ensures that there is a unified way to verify the signature.
Example
Schema
Participant
Metadata of a participant in PAD. It can currently be used to describe a trustee or a validator.
Example
Schema
Enumerated Values
Signature
A digital signature. It consists of the metadata of the signer, including its ID, and the signature payload encoded in base64.
Schema
Schema
DateTime
A timestamp in ISO 8601 format.
Example
Schema
LedgerDigest
A succinct representation of the ledger, which consists of the PAD instance name, the height and the then block hash of its ledger, and the timestamp when this digest is generated.
Example
Schema
TrusteeAttestation
A trustee's succinct view of the ledger, along with a digital signature of it. The succinct view consists of the PAD instance ID, height and latest block hash of its ledger, and the latest timestamp when the attestation is created.
A collection of trustee attestations proves to a user that she and the trustees are seeing the same ledger.
Note that the ledger digest is represented as a string (instead of an object). This ensures that there is a unified way to verify the signature.
Example
Schema
Last updated