# Trustee

## Get latest data requests <a href="#op-get-data-requests" id="op-get-data-requests"></a>

`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

| Name           | In    | Type    | Required | Description                                        |
| -------------- | ----- | ------- | -------- | -------------------------------------------------- |
| oldBlockHeight | query | integer | true     | Number of blocks the trustee has already processed |

**Example**

`GET /data-requests?oldBlockHeight=1`

### Responses

| Status | Meaning                                                         | Description                   | Schema                              |
| ------ | --------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)         | Succeeded                     | Inline                              |
| 400    | Bad Request                                                     | Request is invalid            | [ApiResponse](#schema-api-response) |
| 401    | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | API key is missing or invalid | [ApiResponse](#schema-api-response) |

#### 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](#schema-block-number), [Block](#schema-block)> | true     | none         | none        |

**Example**

```json
{
    "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**

```json
{
    "ok": false,
    "message": "query.oldBlockHeight must be a non-negative integer",
}
```

**Example 2**

```json
{
    "ok": false,
    "message": "Invalid valid at query.oldBlockHeight. Expected: <=5; given: 10",
}
```

#### 401 Unauthorized

API key is missing or incorrect.

**Example**

```json
{
    "ok": false,
    "message": "Unauthorized",
}
```

## Get encrypted trustee share in an `Encryption` <a href="#op-get-encrypted-trustee-share" id="op-get-encrypted-trustee-share"></a>

`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](#opPostTrusteeResponse).

### Parameters

| Name       | In   | Type                            | Required | Description             |
| ---------- | ---- | ------------------------------- | -------- | ----------------------- |
| token-hash | path | [Sha256](#schema-sha256)        | true     | Hash value of the token |
| trustee-id | path | [TrusteeId](#schema-trustee-id) | true     | Trustee's ID            |

**Example**

`GET /encryptions/d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4/encrypted-trustee-shares/trustee1`

### Responses

| Status | Meaning                                                         | Description                   | Schema                              |
| ------ | --------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)         | Succeeded                     | Inline                              |
| 400    | Bad Request                                                     | Request is invalid            | [ApiResponse](#schema-api-response) |
| 401    | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | API key is missing or invalid | [ApiResponse](#schema-api-response) |
| 404    | Not Found                                                       | Encryption not found          | [ApiResponse](#schema-api-response) |

#### 200 OK

Successfully retrieved the encrypted trustee share.

**Schema**

| Name                  | Type                     | Required | Description                 |
| --------------------- | ------------------------ | -------- | --------------------------- |
| ok                    | boolean                  | true     | none                        |
| encryptedTrusteeShare | [Base64](#schema-base64) | true     | The encrypted trustee share |

**Example**

```json
{
  "ok": true,
  "encryptedTrusteeShare": "base64_encoded_data"
}
```

#### 400 Bad Request

Trustee does not exist or does not reference this PAD instance.

**Example**

```json
{
    "ok": false,
    "message": "Trustee with ID trustee1 does not exist in the PAD instance",
}
```

#### 401 Unauthorized

API key is missing or incorrect.

**Example**

```json
{
    "ok": false,
    "message": "Unauthorized",
}
```

#### 404 Not Found

The encryption does not exist.

**Example**

```json
{
    "ok": false,
    "message": "Encryption with token hash d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4 not found",
}
```

## Post trustee response <a href="#op-post-trustee-response" id="op-post-trustee-response"></a>

`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

| Name  | In   | Type                                                     | Required | Description                                                                          |
| ----- | ---- | -------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
| token | path | [Token](#schema-token)                                   | true     | ID of the data request                                                               |
| -     | body | [SignedTrusteeResponse](#schema-signed-trustee-response) | true     | The decrypted share, along with a digital signature of the trustee and some metadata |

**Example**

`POST /data-requests/e3b0c44298fc1c149afbf4c8996fb924/trustee-responses`

```json
{
  "trusteeResponse": "{\"padName\":\"my-pad-1.0\",\"token\":\"e3b0c44298fc1c149afbf4c8996fb924\",\"trusteeShare\":\"0110\",\"type\":\"trustee_response\",\"trusteeId\":\"trustee1\"}",
  "signature": {
    "signerMetadata": {
      "id": "trustee1",
      "fullName": "Trustee-1",
      "role": "Trustee"
    },
    "payload": "MEQCIDbFV8FH8ZTbM0wrKPHSk0lrkiIFsP3/GcU4htiGc6XOAiBOqJZgbeUKxPXgIOZGek6ryoJ+jhmwbcJh0+mSHsSiTQ=="
  }
}
```

### Responses

| Status | Meaning                                                         | Description                                        | Schema                              |
| ------ | --------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------- |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)         | Succeeded                                          | [ApiResponse](#schema-api-response) |
| 400    | Bad Request                                                     | Data request and trustee response are inconsistent | [ApiResponse](#schema-api-response) |
| 401    | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | API key is missing or invalid                      | [ApiResponse](#schema-api-response) |
| 403    | Forbidden                                                       | Trustee is not in the instance                     | [ApiResponse](#schema-api-response) |
| 404    | Not found                                                       | Data request not found                             | [ApiResponse](#schema-api-response) |
| 409    | Conflict                                                        | Response has been made before                      | [ApiResponse](#schema-api-response) |

#### 200 OK

The trustee response is successfully posted.

**Example**

```json
{
    "ok": true,
    "message": "Successfully posted trustee response",
}
```

#### 400 Bad request

Request is invalid. Make sure that :

* `padName` in `TrusteeResponse` is consistent with the PAD instance to which the API key is pointing
* `token` in path and `TrusteeResponse` are consistent
* `trusteeId` in `TrusteeResponse` and `signature` are consistent
* `role` is `Trustee` in `signature`
* signature in `signature` is consistent with the payload `TrusteeResponse`

**Example 1**

```json
{
    "ok": false,
    "message": "Inconsistent trustee ID",
}
```

**example 2**

```json
{
    "ok": false,
    "message": "Inconsistent PAD instance name",
}
```

**example 3**

```json
{
    "ok": false,
    "message": "Invalid signature",
}
```

#### 401 Unauthorized

Api key is missing or invalid.

**Example**

```json
{
    "ok": false,
    "message": "Unauthorized",
}
```

#### 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**

```json
{
    "ok": false,
    "message": "Not a trustee of the instance",
}
```

#### 404 Not Found

The server cannot find a data request pointed by the token in the path parameter.

**Example**

```json
{
    "ok": false,
    "message": "Data request not found",
}
```

#### 409 Conflict

A response from the same trustee has been made for the same data request before.

**Example**

```json
{
    "ok": false,
    "message": "Trustee response has been made for this request",
}
```

## Post trustee attestation <a href="#op-post-trustee-attestation" id="op-post-trustee-attestation"></a>

`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

| Name       | In   | Type                                              | Required | Description                                                                          |
| ---------- | ---- | ------------------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
| trustee-id | path | [TrusteeId](#schema-trustee-id)                   | true     | ID of the trustee                                                                    |
| -          | body | [TrusteeAttestation](#schema-trustee-attestation) | true     | The decrypted share, along with a digital signature of the trustee and some metadata |

**Example**

`PUT /trustee-attestations/trustee1`

```json
{
  "ledgerDigest": "{\"ledgerId\":\"my-pad-1.0\",\"height\":10,\"currentHash\":\"54c0639eb43fcc52cfc4d05546ee35984210a2d3d977e83600288aa\",\"timestamp\":\"2021-09-19T12:41:17.368Z\"}",
  "signature": {
    "signerMetadata": {
      "id": "trustee1",
      "fullName": "Trustee-1",
      "role": "Trustee"
    },
    "payload": "MEQCIDbFV8FH8ZTbM0wrKPHSk0lrkiIFsP3/GcU4htiGc6XOAiBOqJZgbeUKxPXgIOZGek6ryoJ+jhmwbcJh0+mSHsSiTQ=="
  }
}
```

### Responses

| Status | Meaning                                                         | Description                                        | Schema                              |
| ------ | --------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------- |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)         | Succeeded                                          | [ApiResponse](#schema-api-response) |
| 400    | Bad Request                                                     | Data request and trustee response are inconsistent | [ApiResponse](#schema-api-response) |
| 401    | [Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | API key is missing or invalid                      | [ApiResponse](#schema-api-response) |
| 403    | Forbidden                                                       | Trustee is not in the instance                     | [ApiResponse](#schema-api-response) |

#### 200 OK

Successfully posted trustee attestation.

**Example**

```json
{
    "ok": true,
    "message": "Successfully posted trustee attestation",
}
```

#### 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 pointing
* The 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 at `height`

**Example 1**

```json
{
    "ok": false,
    "message": "Inconsistent trustee ID"
}
```

**Example 2**

```json
{
    "ok": false,
    "message": "height (10) in attestation is too large; Expected <= 5"
}
```

**Example 3**

```json
{
    "ok": false,
    "message": "currentHash in attestation is <some_hash>; Expected <some_other_hash>"
}
```

#### 401 Unauthorized

Api key is missing or invalid.

**Example**

```json
{
    "ok": false,
    "message": "Unauthorized",
}
```

#### 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**

```json
{
    "ok": false,
    "message": "Not a trustee of the instance",
}
```

***

## Schemas

### ApiResponse <a href="#schema-api-response" id="schema-api-response"></a>

**Example**

```json
{
  "ok": true,
  "message": "string"
}
```

#### Schema

| Name    | Type    | Required | Description                      |
| ------- | ------- | -------- | -------------------------------- |
| ok      | boolean | true     | The request is successful or not |
| message | string  | true     | none                             |

### BlockNumber <a href="#schema-block-number" id="schema-block-number"></a>

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 <a href="#schema-block" id="schema-block"></a>

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**

```json
{
    "header": {
        "number": "1",
        "previousHash": "0ede53fd38d632f3a7d849f8ba8f70c851d772b53cecbc9d858fe7c8af03a858",
        "dataHash": "ee967360a911deb8f6bd77cbb49b334e1837c006c9b6cb2d59d8acd41964a6ac",
    },
}
```

**Example 2**

```json
{
    "header": {
        "number": "2",
        "previousHash": "78aecc3976f7b2151ce0574278f816b8e5983e18229fde7b6e7c3ebdf5147baf",
        "dataHash": "3ec339eae416289f4ddd7dc2b69e8edf12ac013089207732ad6156e02dc21fb5",
    },
    "data": {
        "data": ["datum1==", "datum2=="],
    },
}
```

#### Schema

| Name   | Type                                | Required | Description |
| ------ | ----------------------------------- | -------- | ----------- |
| header | [BlockHeader](#schema-block-header) | true     | none        |
| data   | [BlockData](#schema-block-data)     | false    | none        |

### BlockHeader <a href="#schema-block-header" id="schema-block-header"></a>

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**

```json
{
    "dataHash": "b24fd1a8c0c37f388f67ce6583710e3b1e5cfa79e652f764e92ee412299ac6c5",
}
```

**Example 2**

```json
{
    "number": "1",
    "previousHash": "0ede53fd38d632f3a7d849f8ba8f70c851d772b53cecbc9d858fe7c8af03a858",
    "dataHash": "ee967360a911deb8f6bd77cbb49b334e1837c006c9b6cb2d59d8acd41964a6ac",
}
```

#### Schema

| Name         | Type                                | Required | Description                         |
| ------------ | ----------------------------------- | -------- | ----------------------------------- |
| number       | [BlockNumber](#schema-block-number) | false    | Block number of the current block   |
| previousHash | [Sha256](#schema-sha256)            | false    | Hash of the previous block's header |
| dataHash     | [Sha256](#schema-sha256)            | true     | Hash of this block's data           |

### BlockData <a href="#schema-block-data" id="schema-block-data"></a>

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**

```json
{
    "data": ["datum1==", "datum2=="],
}
```

#### Schema

| Name | Type                            | Required | Description |
| ---- | ------------------------------- | -------- | ----------- |
| data | array<[Base64](#schema-base64)> | true     | none        |

### Base64

A base64-encoded binary data.

**Example**

```json
"aGVsbG8gd29ybGQ="
```

#### Schema

| Type   | Restrictions |
| ------ | ------------ |
| string | none         |

### Sha256

A Sha256 hash value as a hexidecimal string.

**Example**

```json
"d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4"
```

#### Schema

| Type   | Restrictions        |
| ------ | ------------------- |
| string | `/[0-9a-fA-F]{64}/` |

### TrusteeId <a href="#schema-trustee-id" id="schema-trustee-id"></a>

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}` |

### Token <a href="#schema-token" id="schema-token"></a>

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 <a href="#schema-pad-name" id="schema-pad-name"></a>

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**

```json
"my-pad-1.0"
```

#### Schema

| Type   | Restrictions              |
| ------ | ------------------------- |
| string | `/[a-z][a-z0-9.-]{3,29}/` |

### TrusteeResponse <a href="#schema-trustee-response" id="schema-trustee-response"></a>

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**

```json
{
    "padName": "my-pad-1.0",
    "token": "e3b0c44298fc1c149afbf4c8996fb924",
    "trusteeShare": "0110",
    "type": "trustee_response",
    "trusteeId": "trustee1",
}
```

#### Schema

| Name         | Type                            | Required | Restrictions | Description                                   |
| ------------ | ------------------------------- | -------- | ------------ | --------------------------------------------- |
| padName      | [PadName](#schema-pad-name)     | true     | none         | The instance where the data request is posted |
| token        | [Token](#schema-token)          | true     | none         | The ID of the data request                    |
| trusteeShare | [Base64](#schema-base64)        | true     | none         | The decrypted trustee share                   |
| type         | enum                            | true     | none         | Type of response                              |
| trusteeId    | [TrusteeId](#schema-trustee-id) | true     | none         | ID of the responding trustee                  |

#### Enumerated Values

| Property | Value                |
| -------- | -------------------- |
| type     | `"trustee_response"` |

### SignedTrusteeResponse <a href="#schema-signed-trustee-response" id="schema-signed-trustee-response"></a>

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**

```json
{
  "trusteeResponse": "{\"padName\":\"my-pad-1.0\",\"token\":\"e3b0c44298fc1c149afbf4c8996fb924\",\"trusteeShare\":\"0110\",\"type\":\"trustee_response\",\"trusteeId\":\"trustee1\"}",
  "signature": {
    "signerMetadata": {
      "id": "string",
      "fullName": "string",
      "role": "Trustee"
    },
    "payload": "MEQCIDbFV8FH8ZTbM0wrKPHSk0lrkiIFsP3/GcU4htiGc6XOAiBOqJZgbeUKxPXgIOZGek6ryoJ+jhmwbcJh0+mSHsSiTQ=="
  }
}
```

### Schema

| Name            | Type                                                | Required | Description |
| --------------- | --------------------------------------------------- | -------- | ----------- |
| trusteeResponse | string<[TrusteeResponse](#schema-trustee-response)> | true     | none        |
| signature       | [Signature](#schema-signature)                      | true     | none        |

### Participant <a href="#schema-participant" id="schema-participant"></a>

Metadata of a participant in PAD. It can currently be used to describe a trustee or a validator.

**Example**

```json
{
  "id": "trustee1",
  "fullName": "Trustee-1",
  "role": "Trustee"
}
```

#### Schema

| Name     | Type                                                                   | Required | Description                                              |
| -------- | ---------------------------------------------------------------------- | -------- | -------------------------------------------------------- |
| id       | [TrusteeId](#schema-trustee-id) or [ValidatorId](#schema-validator-id) | 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 href="#schema-signature" id="schema-signature"></a>

A digital signature. It consists of the metadata of the signer, including its ID, and the signature payload encoded in base64.

**Schema**

```json
{
  "signerMetadata": {
    "id": "string",
    "fullName": "string",
    "role": "Trustee",
  },
  "payload": "MEQCIDbFV8FH8ZTbM0wrKPHSk0lrkiIFsP3/GcU4htiGc6XOAiBOqJZgbeUKxPXgIOZGek6ryoJ+jhmwbcJh0+mSHsSiTQ==",
}
```

#### Schema

| Name           | Type                              | Required | Description |
| -------------- | --------------------------------- | -------- | ----------- |
| signerMetadata | [Participant](#schemaparticipant) | false    | none        |
| payload        | [Base64](#schema-base64)          | false    | none        |

### DateTime <a href="#schema-date-time" id="schema-date-time"></a>

A timestamp in ISO 8601 format.

**Example**

```json
"2021-05-05T13:53:19.275Z"
```

#### Schema

| Type   | Restrictions |
| ------ | ------------ |
| string | -            |

### LedgerDigest <a href="#schema-ledger-digest" id="schema-ledger-digest"></a>

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**

```json
{
    "ledgerId": "my-pad-1.0",
    "height": 10,
    "currentHash": "54c0639eb43fcc52cfc4d05546ee35984210a2d3d977e83600288aa",
    "timestamp":"2021-09-19T12:41:17.368Z",
}
```

#### Schema

| Name        | Type                                | Required | Restrictions | Description                                 |
| ----------- | ----------------------------------- | -------- | ------------ | ------------------------------------------- |
| ledgerId    | [PadName](#schema-pad-name)         | true     | none         | The PAD instance's name                     |
| height      | [BlockHeight](#schema-block-height) | true     | none         | Block height of the ledger                  |
| currentHash | [Sha256](#schema-sha256)            | true     | none         | Hash of the block at `height` on the ledger |
| timestamp   | [DateTime](#schema-date-time)       | true     | none         | Time at which this digest is generated      |

### TrusteeAttestation <a href="#schema-trustee-attestation" id="schema-trustee-attestation"></a>

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**

```json
{
  "ledgerDigest": "{\"ledgerId\":\"my-pad-1.0\",\"height\":10,\"currentHash\":\"54c0639eb43fcc52cfc4d05546ee35984210a2d3d977e83600288aa\",\"timestamp\":\"2021-09-19T12:41:17.368Z\"}",
  "signature": {
    "signerMetadata": {
      "id": "trustee1",
      "fullName": "Trustee-1",
      "role": "Trustee"
    },
    "payload": "MEQCIDbFV8FH8ZTbM0wrKPHSk0lrkiIFsP3/GcU4htiGc6XOAiBOqJZgbeUKxPXgIOZGek6ryoJ+jhmwbcJh0+mSHsSiTQ=="
  }
}
```

#### Schema

| Name         | Type                                          | Required | Restrictions | Description                                |
| ------------ | --------------------------------------------- | -------- | ------------ | ------------------------------------------ |
| ledgerDigest | string<[LedgerDigest](#schema-ledger-digest)> | true     | none         | A succinct representation of the ledger    |
| signature    | [Signature](#schemasignature)                 | true     | none         | A digital signature against `ledgerDigest` |