Auditor

Get ledger
GET /ledger
Description
Retrieve the ledger as raw HyperLedger Fabric blocks in one of the three modes:
Get a block with its block number (blockNumber)
Get latest blocks after a block height (oldBlockHeight)
Get blocks between two block numbers, inclusively (start, end)
One can verify the integrity of the ledger by verifying that:
1.dataHash in the block header matches with the hash of the block data; and
2.previousHash in the block header matches with the hahs of the previous block header for every block; and
3.the Trustee attestations match with the ledger Check out the code samples for Auditors for more details.
Parameters
Name
In
Type
Required
Description
blockNumber
query
​BlockNumber​
false
none
oldblockHeight
query
​BlockHeight​
false
none
start
query
​BlockNumber​
false
none
end
query
​BlockNumber​
false
none
Example 1
GET /ledger?blockNumber=3
Example 2
GET /ledger?start=1&end=2
Responses
Status
Meaning
Description
Schema
200
​OK​
Succeeded
Inline
400
Bad Request
Missing or incorrect use of query parameters
​ApiResponse​
401
​Unauthorized​
API key is missing or invalid
​ApiResponse​
200 OK
Successfully retrieved the ledger blocks.
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
Query parameter is missing or misused. Suppose the ledger current height is h, then:
blockNumber should be in [0, h-1];
oldBlockHeight should be in [0, h];
start should be in [0, h-1] and end should be in [start, h-1].
Only one of blockNumber, oldBlockHeight or start/end should be used.
Example 1
{
   "ok": false,
   "message": "Missing oldBlockHeight or blockNumber or start/end in query",
}
Example 2
{
   "ok": false,
   "message": "start must be use in conjunction with end in query",
}
401 Unauthorized
API key is missing or incorrect.
Example
{
  "ok": false,
  "message": "Unauthorized",
}
Get Trustee attestations
GET /attestations
Description
Retrieve all the latest Trustee attestations in the instance. An attestation is a signed digest of the ledger (with a timestamp). See the Auditor code samples for how to verify integrity of the ledger by Trustee attestations.
Note that the trustee attestations may attest to the ledger at different height, since Trustees update their attestations once in a while.
Parameters
No parameter for this endpoint.
Responses
Status
Meaning
Description
Schema
200
​OK​
Succeeded
Inline
200 OK
Successfully retrieved the trustee attestations.
Schema
Name
Type
Required
Restrictions
Description
ok
boolean
true
none
none
attestations
dict<TrusteeId, TrusteeAttestation>
true
none
none
Example
{
   "ok": true,
   "attestations": {
      "trustee1": {
         "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==",
         },
      },
      "trustee2": {
         "ledgerDigest": "{\"ledgerId\":\"my-pad-1.0\",\"height\":8,\"currentHash\":\"854e0426ce76242087ecff0f8cebada226b9adb4806b6f93811879074312283a\",\"timestamp\":\"2021-09-19T12:41:17.368Z\"}",
         "signature": {
            "signerMetadata": {
               "id": "trustee2",
               "fullName": "Trustee-2",
               "role": "Trustee",
            },
            "payload": "MEYCIQCZ93GjVw4Vd1TJu3jagx5KCwQ3uXyClmKfUagdu4zwqwIhAI8nuJmdxD9Cum7KFYq0CnEQ6+OfcFakC3kpPCMgzlCC",
         },
      },
   },
}
Get ledger digest*
GET /digest
Description
Retrieve the current digest of the ledger. A digest is a succinct representation of the ledger, which consists of the ledger ID (same as the instance ID in current implementation), the block height, the hash of the latest block and the timestamp at which the digest is created.
*For reference only. The preferred way is to compute the digest with ledger blocks. Check out the Auditor sample code for this.
Parameters
No parameter for this endpoint.
Responses
Status
Meaning
Description
Schema
200
​OK​
Succeeded
Inline
200 OK
Schema
Name
Type
Required
Restrictions
Description
ok
boolean
true
none
none
digest
​LedgerDigest​
true
none
none
Example
{
   "ok": true,
   "digest": {
      "ledgerId": "my-pad-1.0",
      "height": 11,
      "currentHash": "b360336a86799863f5d7041fafc655a0df38e0738dae10eaed6546c9be7ecc17",
      "timestamp": "2021-09-19T12:45:42.165Z",
   },
}
Schemas
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
BlockHeight
Number of blocks on the ledger. For example, the digest of a ledger shows that the block height is 10, that means the ledger has 10 blocks.
It is also used to describe the status of a trustee/validator. When a trustee has finished processed a ledger of block height 10, the "block height of trustee" is 10. This indicates the trustee has processed 10 blocks from the ledger. In the mean time, the ledger itself could have a block height greater than 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
ApiResponse
Example
{
  "ok": true,
  "message": "string"
}
Schema
Name
Type
Required
Description
ok
boolean
true
The request is successful or not
message
string
true
none
TrusteeId
ID of a trustee. It contains only alphanumerical characters, underscores (_) and dashes (-). It has length inclusively between 3 and 30.
Example
my_trustee-1
Schema
Type
Restrictions
string
[a-zA-Z0-9-_]{3,30}
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
{
  "ledgerDigest": "{\"ledgerId\":\"my-pad-1.0\",\"height\":10,\"currentHash\":\"54c0639eb43fcc52cfc4d05546ee35984210a2d3d977e83600288aa\",\"timestamp\":\"2021-09-19T12:41:17.368Z\"}",
  "signature": {
    "signerMetadata": {
      "id": "string",
      "fullName": "string",
      "role": "Trustee"
    },
    "payload": "MEQCIDbFV8FH8ZTbM0wrKPHSk0lrkiIFsP3/GcU4htiGc6XOAiBOqJZgbeUKxPXgIOZGek6ryoJ+jhmwbcJh0+mSHsSiTQ=="
  }
}
Schema
Name
Type
Required
Restrictions
Description
ledgerDigest
string<LedgerDigest>
true
none
A succinct representation of the ledger
signature
​Signature​
true
none
A digital signature against ledgerDigest
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
{
    "ledgerId": "my-pad-1.0",
    "height": 10,
    "currentHash": "54c0639eb43fcc52cfc4d05546ee35984210a2d3d977e83600288aa",
    "timestamp":"2021-09-19T12:41:17.368Z",
}
Schema
Name
Type
Required
Restrictions
Description
ledgerId
​PadName​
true
none
The PAD instance's name
height
​BlockHeight​
true
none
Block height of the ledger
currentHash
​Sha256​
true
none
Hash of the block at height on the ledger
timestamp
​DateTime​
true
none
Time at which this digest is generated
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}/
Sha256
A Sha256 hash value as a hexidecimal string.
Example
"d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4"
Schema
Type
Restrictions
string
/[0-9a-fA-F]{64}/
DateTime
A timestamp in ISO 8601 format.
Example
"2021-05-05T13:53:19.275Z"
Schema
Type
Restrictions
string
-
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
Participant
Metadata of a participant in PAD. It can currently be used to describe a trustee or a validator.
Example
{
  "id": "my_trustee-1",
  "fullName": "Trustee-1",
  "role": "Trustee"
}
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
ValidatorId
ID of a validator. It contains only alphanumerical characters, underscores (_) and dashes (-). It has length inclusively between 3 and 30.
Example
my_validator-2
Schema
Type
Restrictions
string
[a-zA-Z0-9-_]{3,30}
Base64
A base64-encoded binary data.
Example
"aGVsbG8gd29ybGQ="
Schema
Type
Restrictions
string
none
Validator
Building a Find Me App With PAD
Last modified 8mo ago