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

Example 1

GET /ledger?blockNumber=3

Example 2

GET /ledger?start=1&end=2

Responses

200 OK

Successfully retrieved the ledger blocks.

Schema

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

200 OK

Successfully retrieved the trustee attestations.

Schema

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

200 OK

Schema

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

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

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

ApiResponse

Example

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

Schema

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

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

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

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

Sha256

A Sha256 hash value as a hexidecimal string.

Example

"d033713dd14552c060c55746afdb989cfee8e624ae94a932d79fd25630f728a4"

Schema

DateTime

A timestamp in ISO 8601 format.

Example

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

Schema

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

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

Enumerated Values

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

Base64

A base64-encoded binary data.

Example

"aGVsbG8gd29ybGQ="

Schema

Last updated