light-client API 1.1.0 Reference

Default Tide Disco API

GET payload

Routes

/default-tide-disco-api//payload/:height

Parameters

height

Integer

Description

Fetch a payload plus the VID common data needed to recompute and verify its hash.

GET namespace

Routes

/default-tide-disco-api//namespace/:height/:namespace

Parameters

namespace	Integer
height	Integer

Description

Fetch a namespace proof plus the VID common data needed to verify it.

The proof can be verified in order to extract all transactions in that namespace.

GET stake_table

Routes

/default-tide-disco-api//stake-table/:epoch

Parameters

epoch

Integer

Description

Get events needed to construct the stake table for the given epoch.

This endpoint assumes the client already has the full StakeTableState for epoch :epoch - 1. It returns just the list of events required to transform :epoch - 1 stake table into :epoch stake table.

The resulting stake table can be verified by computing its hash, fetching the header for the epoch root of :epoch, and comparing against the hash in the header.

Returns

[StakeTableEvent]

GET leaf

Routes

/default-tide-disco-api//leaf/:height

/default-tide-disco-api//leaf/:height/:finalized

/default-tide-disco-api//leaf/hash/:hash

/default-tide-disco-api//leaf/hash/:hash/:finalized

/default-tide-disco-api//leaf/block-hash/:block-hash

/default-tide-disco-api//leaf/block-hash/:block-hash/:finalized

/default-tide-disco-api//leaf/payload-hash/:payload-hash

/default-tide-disco-api//leaf/payload-hash/:payload-hash/:finalized

Parameters

finalized	Integer
payload-hash	TaggedBase64
block-hash	TaggedBase64
height	Integer
hash	TaggedBase64

Description

Fetch a leaf plus a proof of it’s finality (a chain of leaves leading from that leaf to either a chain of consecutive valid QCs or a known-finalized leaf).

:height and :finalized, if provided, must both be block numbers. If provided, :finalized must be greater than :height.

The returned proof contains the requested leaf along with sufficient other leaves/QCs to prove the requested leaf is finalized (possibly assuming that the leaf at height :finalized is already known to be finalized). This consists of a chain of valid leaves from the requested leaf until reaching either

a 2-chain of QCs (if the last leaf in the leaf chain is from HotShot >= 0.3)
a 3-chain of QCs (if the last leaf in the leaf chain is from HotShot < 0.3)
the assumed :finalized leaf

Returns

{
    "leaves": [Leaf],
    "proof": {
        // Finality proof for HotShot >= 0.3
        "HotStuff2": {
            "committing_qc": QC,
            "deciding_qc": QC
        } | undefined,

        // Finality proof for HotShot < 0.3
        "HotStuff": {
            "precommit_qc": QC,
            "committing_qc": QC,
            "deciding_qc": QC
        } | undefined,

        // Leaf chain ends in assumed-finalized leaf.
        "Assumption": {}
    }
}

GET namespace_range

Routes

/default-tide-disco-api//namespace/:start/:end/:namespace

Parameters

start	Integer
end	Integer
namespace	Integer

Description

Fetch a list of namespace proofs for each block in the rang [:start, end).

GET header

Routes

/default-tide-disco-api//header/:root/:height

/default-tide-disco-api//header/:root/hash/:hash

/default-tide-disco-api//header/:root/payload-hash/:payload-hash

Parameters

root	Integer
payload-hash	TaggedBase64
height	Integer
hash	TaggedBase64

Description

Fetch a header plus a proof of it’s inclusion in the blocks Merkle tree.

Returns the header identified by :height, :hash, or :payload-hash, plus a Merkle proof showing it belongs to the Merkle tree rooted in the header at height :root (:height < :root).

Returns

{
    "header": Header,
    "proof": MerkleProof
}