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. 1.
    dataHash in the block header matches with the hash of the block data; and
  2. 2.
    previousHash in the block header matches with the hahs of the previous block header for every block; and
  3. 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
false
none
oldblockHeight
query
false
none
start
query
false
none
end
query
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
401
API key is missing or invalid

200 OK

Successfully retrieved the ledger blocks.
Schema
Name
Type
Required
Restrictions
Description
ok
boolean
true
none
none
blocks
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
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
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
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
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
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
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