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