Skip to main content
API docs by Redocly

Mithril Aggregator Server (0.1.39)

Download OpenAPI specification:Download

URL: https://github.com/input-output-hk/mithril License: BSD 3-Clause License Terms of Service

The REST API provided by a Mithril Aggregator Node in a Mithril network.

You can play with it here.

Get public specifications about the aggregator

Returns the specifications related to the aggregator:

  • Open API version
  • URL of Mithril documentation
  • Capabilities of the aggregator
  • Cardano transactions prover capabilities

Responses

Response samples

Content type
application/json
{
  • "open_api_version": "string",
  • "documentation_url": "string",
  • "capabilities": {
    }
}

Get information about the aggregator status

Returns the aggregator status information:

  • Current epoch
  • Current Cardano era
  • Current Mithril era
  • Cardano node version
  • Aggregator node version
  • Protocol parameters for current epoch
  • Protocol parameters for next epoch
  • Total number of signers for current epoch
  • Total number of signers for next epoch
  • Total stakes of signers for current epoch
  • Total stakes of signers for next epoch
  • Total of Cardano SPOs
  • Total stakes in Cardano

Responses

Response samples

Content type
application/json
{
  • "epoch": 0,
  • "cardano_era": "string",
  • "cardano_network": "string",
  • "mithril_era": "string",
  • "cardano_node_version": "string",
  • "aggregator_node_version": "string",
  • "protocol": {
    },
  • "next_protocol": {
    },
  • "total_signers": 0,
  • "total_next_signers": 0,
  • "total_stakes_signers": 0,
  • "total_next_stakes_signers": 0,
  • "total_cardano_spo": 0,
  • "total_cardano_stake": 0
}

Get current epoch settings

Returns the information related to the current epoch:

  • protocol parameters for current epoch
  • protocol parameters for next epoch (to setup cryptography, allowing signers to register)
  • signers for current epoch
  • signers for next epoch
  • cardano transactions signing configuration for current epoch
  • cardano transactions signing configuration for next epoch

Responses

Response samples

Content type
application/json
{
  • "epoch": 0,
  • "protocol": {
    },
  • "next_protocol": {
    },
  • "signer_registration_protocol": {
    },
  • "current_signers": [
    ],
  • "next_signers": [
    ],
  • "cardano_transactions_signing_config": {
    },
  • "next_cardano_transactions_signing_config": {
    }
}

Get current pending certificate information Deprecated

Returns the information related to the current pending certificate:

  • protocol parameters, for current and next epoch (to setup cryptography)
  • beacon information (where on the chain the pending certificate should be triggered)
  • entity type of the message that must be signed
  • verification keys of the signers, for current and next epoch

Responses

Response samples

Content type
application/json
{
  • "epoch": 0,
  • "beacon": {
    },
  • "entity_type": { },
  • "protocol": {
    },
  • "next_protocol": {
    },
  • "signers": [
    ],
  • "next_signers": [
    ]
}

Get most recent certificates

Returns the list of the most recent certificates

Responses

Response samples

Content type
application/json
{
  • "hash": "9dc998101590f733f7a50e7c03b5b336e69a751cc02d811395d49618db3ba3d7",
  • "previous_hash": "aa2ddfb87a17103bdf15bfb21a2941b3f3223a3c8d710910496c392b14f8c403",
  • "epoch": 329,
  • "signed_entity_type": {
    },
  • "metadata": {
    },
  • "protocol_message": {
    },
  • "signed_message": "07ed7c9e128744c1a4797b7eb34c54823cc7a21fc95c19876122ab4bb0fe796d6bba2bc",
  • "aggregate_verification_key": "7b232392c3130342c34392c35312c3130332c3136352c37364223a7b22726f6f74223a5b3137392c3135312c3135382c37332c37372c2c3135392c3226d745f636f6d6d69746d656e7"
}

Get certificate by hash

Returns the certificate identified by its hash

path Parameters
certificate_hash
required
string <bytes>
Examples:
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -

Hash of the certificate to retrieve

Responses

Response samples

Content type
application/json
{
  • "hash": "string",
  • "previous_hash": "string",
  • "epoch": 0,
  • "signed_entity_type": { },
  • "metadata": {
    },
  • "protocol_message": {
    },
  • "signed_message": "string",
  • "aggregate_verification_key": "string",
  • "multi_signature": "string",
  • "genesis_signature": "string"
}

Get most recent snapshots

Returns the list of the most recent snapshots

Responses

Response samples

Content type
application/json
{}

Get snapshot information

Returns the information of a snapshot and where to retrieve its binary content

path Parameters
digest
required
string <bytes>
Examples:
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -

Digest of the snapshot to retrieve

Responses

Response samples

Content type
application/json
{
  • "digest": "string",
  • "network": "string",
  • "beacon": {
    },
  • "certificate_hash": "string",
  • "size": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "locations": [
    ],
  • "compression_algorithm": "string",
  • "cardano_node_version": "string"
}

Download the snapshot

Returns the snapshot archive binary content

path Parameters
digest
required
string <bytes>
Examples:
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -

Digest of the snapshot to download

Responses

Response samples

Content type
application/json
{
  • "label": "string",
  • "message": "A"
}

Get most recent Cardano database snapshots

Returns the list of the most recent Cardano database snapshots

Responses

Response samples

Content type
application/json
{
  • "merkle_root": "c8224920b9f5ad7377594eb8a15f34f08eb3103cc5241d57cafc5638403ec7c6",
  • "beacon": {
    },
  • "certificate_hash": "f6c01b373bafc4e039844071d5da3ace4a9c0745b9e9560e3e2af01823e9abfb",
  • "total_db_size_uncompressed": 800796318,
  • "compression_algorithm": "gzip",
  • "cardano_node_version": "0.0.1",
  • "created_at": "2023-01-19T13:43:05.618857482Z"
}

Get Cardano database snapshot information

Returns the information of a Cardano database snapshot and where to retrieve its binary contents

path Parameters
merkle_root
required
string <bytes>
Examples:
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -

Merkle root of the Cardano database snapshot

Responses

Response samples

Content type
application/json
{
  • "merkle_root": "string",
  • "beacon": {
    },
  • "certificate_hash": "string",
  • "total_db_size_uncompressed": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "locations": {
    },
  • "compression_algorithm": "string",
  • "cardano_node_version": "string"
}

Get most recent Mithril stake distributions

Returns the list of the most recent Mithril stake distributions

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Mithril stake distribution information

Returns the information of a Mithril stake distribution

path Parameters
hash
required
string <bytes>
Examples:
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -

Hash of the Mithril stake distribution to retrieve

Responses

Response samples

Content type
application/json
{
  • "epoch": 0,
  • "hash": "string",
  • "certificate_hash": "string",
  • "signers": [
    ],
  • "created_at": "string",
  • "protocol_parameters": {
    }
}

Get most recent Cardano stake distributions

Returns the list of the most recent Cardano stake distributions

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Cardano stake distribution information

Returns the information of a Cardano stake distribution

path Parameters
hash
required
string <bytes>
Examples:
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -
  • -

Hash of the Cardano stake distribution to retrieve

Responses

Response samples

Content type
application/json
{
  • "epoch": 0,
  • "hash": "string",
  • "certificate_hash": "string",
  • "stake_distribution": {
    },
  • "created_at": "string"
}

Get Cardano stake distribution information for a specific epoch

Returns the information of a Cardano stake distribution at a given epoch

path Parameters
epoch
required
integer <int64>
Examples:

    Epoch of the Cardano stake distribution to retrieve

    Responses

    Response samples

    Content type
    application/json
    {
    • "epoch": 0,
    • "hash": "string",
    • "certificate_hash": "string",
    • "stake_distribution": {
      },
    • "created_at": "string"
    }

    Get most recent Cardano transactions set snapshots

    Returns the list of the most recent Cardano transactions set snapshots

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Get Cardano transactions set snapshot information

    Returns the information of a Cardano transactions set snapshot

    path Parameters
    hash
    required
    string <bytes>
    Examples:
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -

    Hash of the Cardano transactions set snapshot to retrieve

    Responses

    Response samples

    Content type
    application/json
    {
    • "hash": "string",
    • "certificate_hash": "string",
    • "merkle_root": "string",
    • "epoch": 0,
    • "block_number": 0,
    • "created_at": "string"
    }

    Get the proofs of a Cardano transaction list

    Returns the transaction hashes and the corresponding proofs

    query Parameters
    transaction_hashes
    required
    Array of strings <bytes> [ items <bytes > ]

    Hashes of the Cardano transactions to retrieve proofs for

    Responses

    Response samples

    Content type
    application/json
    {
    • "certificate_hash": "string",
    • "certified_transactions": [
      ],
    • "non_certified_transactions": [
      ],
    • "latest_block_number": 0
    }

    Get registered signers for an epoch

    Returns the signers that registered at a given Epoch

    path Parameters
    required
    "latest" (any) or integer

    Cardano Epoch at which the signer registrations are registered

    Responses

    Response samples

    Content type
    application/json
    {
    • "registered_at": 0,
    • "signing_at": 0,
    • "registrations": [
      ]
    }

    Get the signers known by the aggregator

    Returns the signers party id and, if available, their pool ticker

    Responses

    Response samples

    Content type
    application/json
    {
    • "network": "string",
    • "signers": [
      ]
    }

    Registers signer

    Registers a signer for the next certificate production

    Request Body schema: application/json
    required

    Signer information to register

    epoch
    integer <int64> (Epoch)

    Cardano chain epoch number

    party_id
    required
    string

    The unique identifier of the signer

    verification_key
    required
    string <byte>

    The public key used to authenticate signer signature

    verification_key_signature
    string <byte>

    The signature of the verification_key (signed by the Cardano node KES secret key)

    operational_certificate
    string <byte>

    The operational certificate of the stake pool operator attached to the signer node

    kes_period
    integer <int64>

    The number of updates of the KES secret key that signed the verification key

    property name*
    additional property
    any

    Responses

    Request samples

    Content type
    application/json
    {
    • "epoch": 0,
    • "party_id": "string",
    • "verification_key": "string",
    • "verification_key_signature": "string",
    • "operational_certificate": "string",
    • "kes_period": 0
    }

    Response samples

    Content type
    application/json
    {
    • "label": "string",
    • "message": "A"
    }

    Registers signatures

    Registers the single signatures from a signer participant for the pending certificate

    Request Body schema: application/json
    required

    List of signatures

    required
    object (SignedEntityType)

    Entity type of the message that is signed

    party_id
    required
    string

    The unique identifier of the signer

    signature
    required
    string <byte>

    The single signature of the digest

    indexes
    required
    Array of integers <int64> [ items <int64 > ]

    The indexes of the lottery won that lead to the single signature

    signed_message
    string <bytes>

    Hash of the protocol message that is signed by the signer

    Optional, allows the aggregator to store this signature for later if it has yet to start aggregating signatures for the message.

    Responses

    Request samples

    Content type
    application/json
    {
    • "entity_type": { },
    • "party_id": "string",
    • "signature": "string",
    • "indexes": [
      ],
    • "signed_message": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "label": "string",
    • "message": "A"
    }

    Records snapshot download event

    Records snapshot download event

    Request Body schema: application/json
    required

    Downloaded snapshot message

    digest
    required
    string <bytes>

    Digest that is signed by the signer participants

    network
    required
    string

    Cardano network

    required
    object (CardanoDbBeacon)

    A point in the Cardano chain at which a Mithril certificate of the Cardano Database should be produced

    size
    required
    integer <int64>

    Size of the snapshot file in Bytes

    locations
    required
    Array of strings

    Locations where the binary content of the snapshot can be retrieved

    compression_algorithm
    required
    string

    Compression algorithm for the snapshot archive

    cardano_node_version
    required
    string

    Version of the Cardano node which is used to create snapshot archives.

    Responses

    Request samples

    Content type
    application/json
    {
    • "digest": "string",
    • "network": "string",
    • "beacon": {
      },
    • "size": 0,
    • "locations": [
      ],
    • "compression_algorithm": "string",
    • "cardano_node_version": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "label": "string",
    • "message": "A"
    }