openapi: "3.0.0"
info:
  # The protocol version is embedded in the code as constant in the
  # `mithril-common/src/lib.rs` file. If you plan to update it
  # here to reflect changes in the API, please also update the constant in the
  # Rust file.
  version: 0.1.27
  title: Mithril Aggregator Server
  description: |
    The REST API provided by a Mithril Aggregator Node in a Mithril network.

    You can play with it [here](https://mithril.network/openapi-ui/).
  termsOfService: http://swagger.io/terms/
  contact:
    name: Mithril Team
    url: https://github.com/input-output-hk/mithril
  license:
    name: BSD 3-Clause License
    url: https://github.com/input-output-hk/mithril/blob/main/LICENSE
servers:
  - url: https://aggregator.release-preprod.api.mithril.network/aggregator
  - url: https://aggregator.pre-release-preview.api.mithril.network/aggregator
  - url: https://aggregator.testing-preview.api.mithril.network/aggregator
  - url: http://localhost:8080/aggregator
paths:
  /:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get public specifications about the aggregator
      description: |
        Returns the specifications related to the aggregator:
          * Open API version
          * URL of Mithril documentation
          * Capabilities of the aggregator
          * Cardano transactions prover capabilities
      responses:
        "200":
          description: root found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AggregatorFeaturesMessage"
        "412":
          description: API version mismatch
        default:
          description: root error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /epoch-settings:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get current epoch settings
      description: |
        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)
      responses:
        "200":
          description: epoch settings found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EpochSettingsMessage"
        "412":
          description: API version mismatch
        default:
          description: epoch settings error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /certificate-pending:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get current pending certificate information
      description: |
        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:
        "200":
          description: pending certificate found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CertificatePendingMessage"
        "204":
          description: no pending certificate available
        "412":
          description: API version mismatch
        default:
          description: pending certificate error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /certificates:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get most recent certificates
      description: |
        Returns the list of the most recent certificates
      responses:
        "200":
          description: certificates found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CertificateListMessage"
        "412":
          description: API version mismatch
        default:
          description: certificates retrieval error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /certificate/{certificate_hash}:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get certificate by hash
      description: |
        Returns the certificate identified by its hash
      parameters:
        - name: certificate_hash
          in: path
          description: Hash of the certificate to retrieve
          required: true
          schema:
            type: string
            format: bytes
          example: "7905e83ab5d7bc082c1bbc3033bfd19c539078830d19080d1f241c70aa532572"
      responses:
        "200":
          description: certificate found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CertificateMessage"
        "404":
          description: certificate not found
        "412":
          description: API version mismatch
        default:
          description: pending certificate error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /artifact/snapshots:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get most recent snapshots
      description: |
        Returns the list of the most recent snapshots
      responses:
        "200":
          description: snapshots found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SnapshotListMessage"
        "412":
          description: API version mismatch
        default:
          description: snapshots retrieval error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /artifact/snapshot/{digest}:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get snapshot information
      description: |
        Returns the information of a snapshot and where to retrieve its binary content
      parameters:
        - name: digest
          in: path
          description: Digest of the snapshot to retrieve
          required: true
          schema:
            type: string
            format: bytes
          example: "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732"
      responses:
        "200":
          description: snapshot found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SnapshotMessage"
        "404":
          description: snapshot not found
        "412":
          description: API version mismatch
        default:
          description: snapshot retrieval error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /artifact/snapshot/{digest}/download:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Download the snapshot
      description: |
        Returns the snapshot archive binary content
      parameters:
        - name: digest
          in: path
          description: Digest of the snapshot to download
          required: true
          schema:
            type: string
            format: bytes
          example: "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732"
      responses:
        "200":
          description: snapshot found
          content:
            application/gzip:
              schema:
                type: string
                format: binary
        "404":
          description: snapshot not found
        "412":
          description: API version mismatch
        default:
          description: snapshot retrieval error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /artifact/mithril-stake-distributions:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get most recent Mithril stake distributions
      description: |
        Returns the list of the most recent Mithril stake distributions
      responses:
        "200":
          description: Mithril stake distribution found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MithrilStakeDistributionListMessage"
        "412":
          description: API version mismatch
        default:
          description: Mithril stake distribution retrieval error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /artifact/mithril-stake-distribution/{hash}:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get Mithril stake distribution information
      description: |
        Returns the information of a Mithril stake distribution
      parameters:
        - name: hash
          in: path
          description: Hash of the Mithril stake distribution to retrieve
          required: true
          schema:
            type: string
            format: bytes
          example: "6da2b104ed68481ef829d72d72c2f6a20142916d17985e01774b14ed49f0fea1"
      responses:
        "200":
          description: Mithril stake distribution found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MithrilStakeDistributionMessage"
        "404":
          description: Mithril stake distribution not found
        "412":
          description: API version mismatch
        default:
          description: Mithril stake distribution retrieval error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /artifact/cardano-transactions:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get most recent Cardano transactions set snapshots
      description: |
        Returns the list of the most recent Cardano transactions set snapshots
      responses:
        "200":
          description: Cardano transactions set snapshots found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CardanoTransactionSnapshotListMessage"
        "412":
          description: API version mismatch
        default:
          description: Cardano transactions set snapshots retrieval error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /artifact/cardano-transaction/{hash}:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get Cardano transactions set snapshot information
      description: |
        Returns the information of a Cardano transactions set snapshot
      parameters:
        - name: hash
          in: path
          description: Hash of the Cardano transactions set snapshot to retrieve
          required: true
          schema:
            type: string
            format: bytes
          example: "6da2b104ed68481ef829d72d72c2f6a20142916d17985e01774b14ed49f0fea1"
      responses:
        "200":
          description: Cardano transactions set snapshot found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CardanoTransactionSnapshotMessage"
        "404":
          description: Cardano transactions set snapshot not found
        "412":
          description: API version mismatch
        default:
          description: Cardano transactions set snapshot retrieval error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /proof/cardano-transaction:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get the proofs of a Cardano transaction list
      description: |
        Returns the transaction hashes and the corresponding proofs
      parameters:
        - name: transaction_hashes
          in: query
          description: Hashes of the Cardano transactions to retrieve proofs for
          required: true
          schema:
            type: array
            items:
              type: string
              format: bytes
              example: "6dbb104ed68481ef829a26a20142916d17985e01774d72d72c2f"
          explode: false
      responses:
        "200":
          description: Cardano transaction proofs found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CardanoTransactionProofMessage"
        "404":
          description: No Cardano transactions were ever signed
        "412":
          description: API version mismatch
        default:
          description: Cardano transaction proofs retrieval error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /signers/registered/{epoch}:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get registered signers for an epoch
      description: |
        Returns the signers that registered at a given Epoch
      parameters:
        - name: epoch
          in: path
          description: Cardano Epoch at which the signer registrations are registered
          required: true
          schema:
            type: integer
            format: int64
          example: 419
      responses:
        "200":
          description: Registered Signers found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignerRegistrationsMessage"
        "404":
          description: Registered Signers not found
        "412":
          description: API version mismatch
        default:
          description: Registered Signers retrieval error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /signers/tickers:
    get:
      tags:
        - "Cardano » Mithril"
      summary: Get the signers known by the aggregator
      description: |
        Returns the signers party id and, if available, their pool ticker
      responses:
        "200":
          description: Signers found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignersTickersMessage"
        "412":
          description: API version mismatch
        default:
          description: Signers retrieval error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /register-signer:
    post:
      summary: Registers signer
      description: |
        Registers a signer for the next certificate production
      requestBody:
        description: Signer information to register
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterSignerMessage"
      responses:
        "201":
          description: signer registration succeeded
        "400":
          description: signer registration bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "412":
          description: API version mismatch
        "503":
          description: signer registration is unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: signer registration error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /register-signatures:
    post:
      summary: Registers signatures
      description: |
        Registers the single signatures from a signer participant for the pending certificate
      requestBody:
        description: List of signatures
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterSingleSignatureMessage"
      responses:
        "201":
          description: signatures registration succeeded
        "400":
          description: signatures registration bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: open message not found
        "410":
          description: signatures registration done too late
        "412":
          description: API version mismatch
        default:
          description: signatures registration error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /statistics/snapshot:
    post:
      summary: Records snapshot download event
      description: Records snapshot download event
      requestBody:
        description: Downloaded snapshot message
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SnapshotDownloadMessage"
      responses:
        "201":
          description: Event successfully recorded
        "400":
          description: Record event bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "412":
          description: API version mismatch
        default:
          description: Record event error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    AggregatorFeaturesMessage:
      description: Represents general information about Aggregator public information and signing capabilities
      type: object
      additionalProperties: false
      required:
        - open_api_version
        - documentation_url
        - capabilities
      properties:
        open_api_version:
          description: Open API version
          type: string
          format: byte
        documentation_url:
          description: Mithril documentation
          type: string
          format: byte
        capabilities:
          description: Capabilities of the aggregator
          type: object
          additionalProperties: false
          required:
            - signed_entity_types
          properties:
            signed_entity_types:
              description: Signed entity types that are signed by the aggregator
              type: array
              minItems: 1
              items:
                description: Signed entity types that can be signed
                type: string
                enum:
                  - MithrilStakeDistribution
                  - CardanoStakeDistribution
                  - CardanoImmutableFilesFull
                  - CardanoTransactions
            cardano_transactions_prover:
              description: Cardano transactions prover capabilities
              type: object
              additionalProperties: false
              required:
                - max_hashes_allowed_by_request
              properties:
                max_hashes_allowed_by_request:
                  description: Maximum number of hashes allowed for a single request
                  type: integer
                  format: int64
      example:
        {
          "open_api_version": "0.1.17",
          "documentation_url": "https://mithril.network",
          "capabilities":
            {
              "signed_entity_types":
                [
                  "MithrilStakeDistribution",
                  "CardanoImmutableFilesFull",
                  "CardanoTransactions",
                ],
              "cardano_transactions_prover":
                { "max_hashes_allowed_by_request": 100 },
            },
        }

    Epoch:
      description: Cardano chain epoch number
      type: integer
      format: int64

    EpochSettingsMessage:
      description: Epoch settings
      type: object
      additionalProperties: false
      required:
        - epoch
        - protocol
        - next_protocol
      properties:
        epoch:
          $ref: "#/components/schemas/Epoch"
        protocol:
          $ref: "#/components/schemas/ProtocolParameters"
        next_protocol:
          $ref: "#/components/schemas/ProtocolParameters"
      example:
        {
          "epoch": 329,
          "protocol": { "k": 857, "m": 6172, "phi_f": 0.2 },
          "next_protocol": { "k": 2422, "m": 20973, "phi_f": 0.2 },
        }

    ProtocolParameters:
      description: Protocol cryptographic parameters
      type: object
      additionalProperties: true
      required:
        - k
        - m
        - phi_f
      properties:
        k:
          description: Quorum parameter
          type: integer
          format: int64
        m:
          description: Security parameter (number of lotteries)
          type: integer
          format: int64
        phi_f:
          description: f in phi(w) = 1 - (1 - f)^w, where w is the stake of a participant
          type: number
          format: double
      example: { "k": 857, "m": 6172, "phi_f": 0.2 }

    CardanoDbBeacon:
      description: A point in the Cardano chain at which a Mithril certificate of the Cardano Database should be produced
      type: object
      additionalProperties: true
      required:
        - network
        - epoch
        - immutable_file_number
      properties:
        network:
          description: Cardano network
          type: string
        epoch:
          $ref: "#/components/schemas/Epoch"
        immutable_file_number:
          description: Number of the last immutable file that should be included the snapshot
          type: integer
          format: int64
      example:
        { "network": "mainnet", "epoch": 329, "immutable_file_number": 7060000 }

    SignedEntityType:
      description: Entity type of the message that is signed
      type: object
      additionalProperties: true
      example: { "MithrilStakeDistribution": 246 }

    CertificatePendingMessage:
      description: CertificatePendingMessage represents all the information related to the certificate currently expecting to receive quorum of single signatures
      type: object
      additionalProperties: false
      required:
        - epoch
        - entity_type
        - protocol
        - next_protocol
        - signers
        - next_signers
      properties:
        epoch:
          $ref: "#/components/schemas/Epoch"
        beacon:
          deprecated: true
          allOf:
            - $ref: "#/components/schemas/CardanoDbBeacon"
        entity_type:
          $ref: "#/components/schemas/SignedEntityType"
        protocol:
          $ref: "#/components/schemas/ProtocolParameters"
        next_protocol:
          $ref: "#/components/schemas/ProtocolParameters"
        signers:
          type: array
          items:
            $ref: "#/components/schemas/Signer"
        next_signers:
          type: array
          items:
            $ref: "#/components/schemas/Signer"
      example:
        {
          "epoch": 329,
          "beacon":
            {
              "network": "mainnet",
              "epoch": 329,
              "immutable_file_number": 7060000,
            },
          "entity_type": { "MithrilStakeDistribution": 246 },
          "protocol": { "k": 857, "m": 6172, "phi_f": 0.2 },
          "next_protocol": { "k": 2422, "m": 20973, "phi_f": 0.2 },
          "signers":
            [
              {
                "party_id": "1234567890",
                "verification_key": "7b12766b223a5c342b39302c32392c39392c39382c3131313138342c32252c32352c31353",
                "verification_key_signature": "7b5473693727369676d61223a7b227369676d6d61223a7b261223a9b227369676d61213a",
                "operational_certificate": "5b73136372c38302c37342c3136362c313535b5b3232352c3230332c3235352c313030262c38322c39382c32c39332c3138342c3135362c3136362c32312c3131312c3232312c36332c3137372c3232332c3232332c31392c3537",
                "kes_period": 123,
              },
              {
                "party_id": "2345678900",
                "verification_key": "7b392c39392c13131312766b223a5c39382c313342b39302c252c32352c31353328342c32",
                "verification_key_signature": "2c33302c3133312c3138322c34362c3133352c372c3139302c3235322c35352c32322c39",
                "operational_certificate": "3231342c3137372c37312c3232352c3233332c3135335d2c322c3139322c5b3133352c34312c3230332c3131332c3c33352c3234302c3230392c312c32392c3233332c33342c3138382c3134312c3130342c3234382c3231392c3",
                "kes_period": 456,
              },
            ],
          "next_signers":
            [
              {
                "party_id": "3456789000",
                "verification_key": "7b22766b223a5b3133382c32392c3137332c3134342c36332c3233352c39372c3138302c3",
                "verification_key_signature": "7b227369676d61223a7b227369676d61223a7b227369676d61223a7b227369676d612239",
                "operational_certificate": "5b5b5b3232352c3230332c3235352c3130302c3136372c38302c37342c3136362c3135362c38322c39382c3232312c36332c3137372c3232332c3232332c31392c35372c39332c312c35302c3133392c3233342c3137332c32352",
                "kes_period": 789,
              },
              {
                "party_id": "4567890000",
                "verification_key": "34302c3132332c3139302c3134352c3132342c35342c3133302c37302c3136332c3139332",
                "verification_key_signature": "302c3230312c38362c3139312c36302c3234352c3138332c3134342c3139392c3130335f",
                "operational_certificate": "2c38382c3138372c3233332c34302c37322c31362c36365d2c312c3132332c5b31362c3136392c3134312c3138332c32322c3137342c3131312c33322c36342c35322c2c3232382c37392c3137352c32395312c3838282c323030",
                "kes_period": 876,
              },
            ],
        }

    Stake:
      description: Stake represents the stakes of a participant in the Cardano chain
      type: object
      additionalProperties: true
      required:
        - stake
      properties:
        stake:
          description: Stake share as computed in the 'stake distribution' by the Cardano Node, multiplied by a billion (1.0e9)
          type: integer
          format: int64
      example: { "stake": 1234 }

    Signer:
      description: Signer represents a signing participant in the network
      type: object
      additionalProperties: true
      required:
        - party_id
        - verification_key
      properties:
        party_id:
          description: The unique identifier of the signer
          type: string
        verification_key:
          description: The public key used to authenticate signer signature
          type: string
          format: byte
        verification_key_signature:
          description: The signature of the verification_key (signed by the Cardano node KES secret key)
          type: string
          format: byte
        operational_certificate:
          description: The operational certificate of the stake pool operator attached to the signer node
          type: string
          format: byte
        kes_period:
          description: The number of updates of the KES secret key that signed the verification key
          type: integer
          format: int64
      example:
        {
          "party_id": "1234567890",
          "verification_key": "7b12766b223a5c342b39302c32392c39392c39382c3131313138342c32252c32352c31353",
          "verification_key_signature": "7b5473693727369676d61223a7b227369676d6d61223a7b261223a9b227369676d61213a",
          "operational_certificate": "5b73136372c38302c37342c3136362c313535b5b3232352c3230332c3235352c313030262c38322c39382c32c39332c3138342c3135362c3136362c32312c3131312c3232312c36332c3137372c3232332c3232332c31392c3537",
          "kes_period": 123,
        }

    RegisterSignerMessage:
      description: This message represents a signing participant in the network.
      additionalProperties: true
      properties:
        epoch:
          $ref: "#/components/schemas/Epoch"
      allOf:
        - $ref: "#/components/schemas/Signer"
      example:
        {
          "epoch": 329,
          "party_id": "1234567890",
          "verification_key": "7b12766b223a5c342b39302c32392c39392c39382c3131313138342c32252c32352c31353",
          "verification_key_signature": "7b5473693727369676d61223a7b227369676d6d61223a7b261223a9b227369676d61213a",
          "operational_certificate": "5b73136372c38302c37342c3136362c313535b5b3232352c3230332c3235352c313030262c38322c39382c32c39332c3138342c3135362c3136362c32312c3131312c3232312c36332c3137372c3232332c3232332c31392c3537",
          "kes_period": 123,
        }

    SignerWithStake:
      description: Signer represents a signing party in the network (including its stakes)
      additionalProperties: true
      allOf:
        - $ref: "#/components/schemas/Signer"
        - $ref: "#/components/schemas/Stake"
      example:
        {
          "party_id": "1234567890",
          "verification_key": "7b12766b223a5c342b39302c32392c39392c39382c3131313138342c32252c32352c31353",
          "verification_key_signature": "7b5473693727369676d61223a7b227369676d6d61223a7b261223a9b227369676d61213a",
          "operational_certificate": "5b73136372c38302c37342c3136362c313535b5b3232352c3230332c3235352c313030262c38322c39382c32c39332c3138342c3135362c3136362c32312c3131312c3232312c36332c3137372c3232332c3232332c31392c3537",
          "kes_period": 123,
          "stake": 1234,
        }

    StakeDistributionParty:
      description: |
        Signer registered to a signature round.
      type: object
      additionalProperties: true
      properties:
        party_id:
          description: The unique identifier of the signer
          type: string
        stake:
          description: Stake share as computed in the 'stake distribution' by the Cardano Node, multiplied by a billion (1.0e9)
          type: integer
          format: int64
      example: { "party_id": "1234567890", "stake": 1234 }

    SignerRegistrationsMessage:
      description: |
        This message holds the registered signers at a given epoch.
      type: object
      additionalProperties: false
      properties:
        registered_at:
          $ref: "#/components/schemas/Epoch"
        signing_at:
          $ref: "#/components/schemas/Epoch"
        registrations:
          type: array
          items:
            $ref: "#/components/schemas/SignerRegistrationsListItemMessage"
      example:
        {
          "registered_at": 420,
          "signing_at": 422,
          "registrations": [{ "party_id": "1234567890", "stake": 1234 }],
        }

    SignerRegistrationsListItemMessage:
      description: represents an item of a SignerRegistrationsMessage registration
      type: object
      additionalProperties: true
      allOf:
        - $ref: "#/components/schemas/Stake"
      properties:
        party_id:
          description: The unique identifier of the signer
          type: string

    SignersTickersMessage:
      description: represents the list of signers known by the aggregator
      type: object
      required:
        - network
        - signers
      properties:
        network:
          description: Cardano network of the aggregator
          type: string
          format: bytes
        signers:
          description: Known signers
          items:
            $ref: "#/components/schemas/SignerTickerListItemMessage"
      example:
        {
          "network": "mainnet",
          "signers":
            [
              {
                "party_id": "pool1234567890",
                "pool_ticker": "[Pool_Name]",
                "has_registered": true,
              },
              { "party_id": "pool0987654321", "has_registered": false },
            ],
        }

    SignerTickerListItemMessage:
      description: represents a known signer with its pool ticker
      type: object
      additionalProperties: true
      required:
        - party_id
        - has_registered
      properties:
        party_id:
          description: The unique identifier of the signer
          type: string
        pool_ticker:
          description: The signer pool ticker
          type: string
        has_registered:
          description: The signer has registered at least once
          type: boolean
      example:
        {
          "party_id": "pool1234567890",
          "pool_ticker": "[Pool_Name]",
          "has_registered": true,
        }

    RegisterSingleSignatureMessage:
      description: |
        This message holds a Signer Single Signature with the
        list of won indexes in the lottery.
      type: object
      additionalProperties: false
      required:
        - entity_type
        - party_id
        - signature
        - indexes
      properties:
        entity_type:
          $ref: "#/components/schemas/SignedEntityType"
        party_id:
          description: The unique identifier of the signer
          type: string
        signature:
          description: The single signature of the digest
          type: string
          format: byte
        indexes:
          description: The indexes of the lottery won that lead to the single signature
          type: array
          items:
            type: integer
            format: int64
      example:
        {
          "entity_type": { "MithrilStakeDistribution": 246 },
          "party_id": "1234567890",
          "signature": "7b2c36322c3130352c3232322c31302c3131302c33312c37312c39372c22766b223a5b3136342c2c31393137352c313834",
          "indexes": [25, 35],
        }

    ProtocolMessageParts:
      description: ProtocolMessage represents a message that is signed (or verified) by the Mithril protocol
      type: object
      additionalProperties: true
      required:
        - next_aggregate_verification_key
      properties:
        snapshot_digest:
          description: Digest of the snapshot archive
          type: string
          format: bytes
        next_aggregate_verification_key:
          description: Aggregate verification key (AVK) that will be used to create the next multi signature
          type: string
          format: bytes
        latest_block_number:
          description: The latest signed block number
          type: string
      example:
        {
          "snapshot_digest": "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
          "next_aggregate_verification_key": "b132362c3232352c36392c31373133352c31323235392c3235332c3233342c34226d745f636f6d6d69746d656e74223a7b22726f6f74223a5b33382c3382c3138322c3231322c2c363",
          "latest_block_number": "123456",
        }

    ProtocolMessage:
      description: ProtocolMessage represents a message that is signed (or verified) by the Mithril protocol
      type: object
      additionalProperties: false
      required:
        - message_parts
      properties:
        message_parts:
          $ref: "#/components/schemas/ProtocolMessageParts"
      example:
        {
          "message_parts":
            {
              "snapshot_digest": "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
              "next_aggregate_verification_key": "b132362c3232352c36392c31373133352c31323235392c3235332c3233342c34226d745f636f6d6d69746d656e74223a7b22726f6f74223a5b33382c3382c3138322c3231322c2c363",
            },
        }

    CertificateListItemMessageMetadata:
      description: CertificateListItemMessageMetadata represents the metadata associated to a CertificateListItemMessage
      type: object
      additionalProperties: false
      required:
        - network
        - version
        - parameters
        - initiated_at
        - sealed_at
        - total_signers
      properties:
        network:
          description: Cardano network
          type: string
        version:
          description: Version of the protocol
          type: string
          format: bytes
        parameters:
          $ref: "#/components/schemas/ProtocolParameters"
        initiated_at:
          description: Date and time at which the certificate was initialized and ready to accept single signatures from signers
          type: string
          format: date-time
        sealed_at:
          description: Date and time at which the certificate was sealed (when the quorum of single signatures was reached so that a multi signature could be aggregated from them)
          type: string
          format: date-time
        total_signers:
          description: The number of the signers with their stakes and verification keys
          type: integer
          format: int64
      example:
        {
          "network": "mainnet",
          "version": "0.1.0",
          "parameters": { "k": 5, "m": 100, "phi_f": 0.65 },
          "initiated_at": "2022-07-17T18:51:23.192811338Z",
          "sealed_at": "2022-07-17T18:51:35.830832580Z",
          "total_signers": 3,
        }

    CertificateListMessage:
      description: CertificateListMessage represents a list of Mithril certificates
      type: array
      items:
        $ref: "#/components/schemas/CertificateListItemMessage"
      example:
        [
          {
            "hash": "9dc998101590f733f7a50e7c03b5b336e69a751cc02d811395d49618db3ba3d7",
            "previous_hash": "aa2ddfb87a17103bdf15bfb21a2941b3f3223a3c8d710910496c392b14f8c403",
            "epoch": 329,
            "beacon":
              {
                "network": "mainnet",
                "epoch": 329,
                "immutable_file_number": 7060000,
              },
            signed_entity_type: { "MithrilStakeDistribution": 246 },
            "metadata":
              {
                "network": "mainnet",
                "version": "0.1.0",
                "parameters": { "k": 5, "m": 100, "phi_f": 0.65 },
                "initiated_at": "2022-07-17T18:51:23.192811338Z",
                "sealed_at": "2022-07-17T18:51:35.830832580Z",
                "total_signers": 3,
              },
            "protocol_message":
              {
                "message_parts":
                  {
                    "snapshot_digest": "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
                    "next_aggregate_verification_key": "b132362c3232352c36392c31373133352c31323235392c3235332c3233342c34226d745f636f6d6d69746d656e74223a7b22726f6f74223a5b33382c3382c3138322c3231322c2c363",
                  },
              },
            "signed_message": "07ed7c9e128744c1a4797b7eb34c54823cc7a21fc95c19876122ab4bb0fe796d6bba2bc",
            "aggregate_verification_key": "7b232392c3130342c34392c35312c3130332c3136352c37364223a7b22726f6f74223a5b3137392c3135312c3135382c37332c37372c2c3135392c3226d745f636f6d6d69746d656e7",
          },
        ]

    CertificateListItemMessage:
      description: CertificateListItemMessage represents an item of a list of Mithril certificates
      type: object
      additionalProperties: false
      required:
        - hash
        - previous_hash
        - epoch
        - signed_entity_type
        - metadata
        - protocol_message
        - signed_message
        - aggregate_verification_key
      properties:
        hash:
          description: Hash of the current certificate
          type: string
          format: bytes
        previous_hash:
          description: Hash of the previous certificate
          type: string
          format: bytes
        epoch:
          $ref: "#/components/schemas/Epoch"
        beacon:
          deprecated: true
          allOf:
            - $ref: "#/components/schemas/CardanoDbBeacon"
        signed_entity_type:
          $ref: "#/components/schemas/SignedEntityType"
        metadata:
          $ref: "#/components/schemas/CertificateListItemMessageMetadata"
        protocol_message:
          $ref: "#/components/schemas/ProtocolMessage"
        signed_message:
          description: Hash of the protocol message that is signed by the signer participants
          type: string
          format: bytes
        aggregate_verification_key:
          description: Aggregate verification key used to verify the multi signature
          type: string
          format: bytes
      example:
        {
          "hash": "9dc998101590f733f7a50e7c03b5b336e69a751cc02d811395d49618db3ba3d7",
          "previous_hash": "aa2ddfb87a17103bdf15bfb21a2941b3f3223a3c8d710910496c392b14f8c403",
          "epoch": 32,
          "beacon":
            {
              "network": "mainnet",
              "epoch": 329,
              "immutable_file_number": 7060000,
            },
          signed_entity_type: { "MithrilStakeDistribution": 246 },
          "metadata":
            {
              "network": "mainnet",
              "version": "0.1.0",
              "parameters": { "k": 5, "m": 100, "phi_f": 0.65 },
              "initiated_at": "2022-07-17T18:51:23.192811338Z",
              "sealed_at": "2022-07-17T18:51:35.830832580Z",
              "total_signers": 3,
            },
          "protocol_message":
            {
              "message_parts":
                {
                  "snapshot_digest": "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
                  "next_aggregate_verification_key": "b132362c3232352c36392c31373133352c31323235392c3235332c3233342c34226d745f636f6d6d69746d656e74223a7b22726f6f74223a5b33382c3382c3138322c3231322c2c363",
                },
            },
          "signed_message": "07ed7c9e128744c1a4797b7eb34c54823cc7a21fc95c19876122ab4bb0fe796d6bba2bc",
          "aggregate_verification_key": "7b232392c3130342c34392c35312c3130332c3136352c37364223a7b22726f6f74223a5b3137392c3135312c3135382c37332c37372c2c3135392c3226d745f636f6d6d69746d656e7",
        }

    CertificateMetadata:
      description: CertificateMetadata represents the metadata associated to a Certificate
      type: object
      additionalProperties: false
      required:
        - network
        - version
        - parameters
        - initiated_at
        - sealed_at
        - signers
      properties:
        network:
          description: Cardano network
          type: string
        version:
          description: Version of the protocol
          type: string
          format: bytes
        parameters:
          $ref: "#/components/schemas/ProtocolParameters"
        initiated_at:
          description: Date and time at which the certificate was initialized and ready to accept single signatures from signers
          type: string
          format: date-time
        sealed_at:
          description: Date and time at which the certificate was sealed (when the quorum of single signatures was reached so that a multi signature could be aggregated from them)
          type: string
          format: date-time
        signers:
          description: The list of the signers identifiers with their stakes and verification keys
          type: array
          items:
            $ref: "#/components/schemas/StakeDistributionParty"
      example:
        {
          "network": "mainnet",
          "version": "0.1.0",
          "parameters": { "k": 5, "m": 100, "phi_f": 0.65 },
          "initiated_at": "2022-07-17T18:51:23.192811338Z",
          "sealed_at": "2022-07-17T18:51:35.830832580Z",
          "signers":
            [
              { "party_id": "1234567890", "stake": 1234 },
              { "party_id": "2345678900", "stake": 2345 },
            ],
        }

    CertificateMessage:
      description: Certificate represents a Mithril certificate embedding a Mithril STM multi signature
      type: object
      additionalProperties: false
      required:
        - hash
        - previous_hash
        - epoch
        - signed_entity_type
        - metadata
        - protocol_message
        - signed_message
        - aggregate_verification_key
        - multi_signature
        - genesis_signature
      properties:
        hash:
          description: Hash of the current certificate
          type: string
          format: bytes
        previous_hash:
          description: Hash of the previous certificate
          type: string
          format: bytes
        epoch:
          $ref: "#/components/schemas/Epoch"
        beacon:
          deprecated: true
          allOf:
            - $ref: "#/components/schemas/CardanoDbBeacon"
        signed_entity_type:
          $ref: "#/components/schemas/SignedEntityType"
        metadata:
          $ref: "#/components/schemas/CertificateMetadata"
        protocol_message:
          $ref: "#/components/schemas/ProtocolMessage"
        signed_message:
          description: Hash of the protocol message that is signed by the signer participants
          type: string
          format: bytes
        aggregate_verification_key:
          description: Aggregate verification key used to verify the multi signature
          type: string
          format: bytes
        multi_signature:
          description: STM multi signature created from a quorum of single signatures from the signers
          type: string
          format: bytes
        genesis_signature:
          description: Genesis signature created to bootstrap the certificate chain with the Cardano Genesis Keys
          type: string
          format: bytes
      example:
        {
          "hash": "9dc998101590f733f7a50e7c03b5b336e69a751cc02d811395d49618db3ba3d7",
          "previous_hash": "aa2ddfb87a17103bdf15bfb21a2941b3f3223a3c8d710910496c392b14f8c403",
          "epoch": 329,
          "beacon":
            {
              "network": "mainnet",
              "epoch": 329,
              "immutable_file_number": 7060000,
            },
          signed_entity_type: { "MithrilStakeDistribution": 246 },
          "metadata":
            {
              "network": "mainnet",
              "version": "0.1.0",
              "parameters": { "k": 5, "m": 100, "phi_f": 0.65 },
              "initiated_at": "2022-07-17T18:51:23.192811338Z",
              "sealed_at": "2022-07-17T18:51:35.830832580Z",
              "signers":
                [
                  {
                    "party_id": "1234567890",
                    "verification_key": "7b12766b223a5c342b39302c32392c39392c39382c3131313138342c32252c32352c31353",
                    "verification_key_signature": "7b5473693727369676d61223a7b227369676d6d61223a7b261223a9b227369676d61213a",
                    "operational_certificate": "5b73136372c38302c37342c3136362c313535b5b3232352c3230332c3235352c313030262c38322c39382c32c39332c3138342c3135362c3136362c32312c3131312c3232312c36332c3137372c3232332c3232332c31392c3537",
                    "kes_period": 123,
                    "stake": 1234,
                  },
                  {
                    "party_id": "2345678900",
                    "verification_key": "7b392c39392c13131312766b223a5c39382c313342b39302c252c32352c31353328342c32",
                    "verification_key_signature": "2c33302c3133312c3138322c34362c3133352c372c3139302c3235322c35352c32322c39",
                    "operational_certificate": "3231342c3137372c37312c3232352c3233332c3135335d2c322c3139322c5b3133352c34312c3230332c3131332c3c33352c3234302c3230392c312c32392c3233332c33342c3138382c3134312c3130342c3234382c3231392c3",
                    "kes_period": 456,
                    "stake": 2345,
                  },
                ],
            },
          "protocol_message":
            {
              "message_parts":
                {
                  "snapshot_digest": "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
                  "next_aggregate_verification_key": "b132362c3232352c36392c31373133352c31323235392c3235332c3233342c34226d745f636f6d6d69746d656e74223a7b22726f6f74223a5b33382c3382c3138322c3231322c2c363",
                },
            },
          "signed_message": "07ed7c9e128744c1a4797b7eb34c54823cc7a21fc95c19876122ab4bb0fe796d6bba2bc",
          "aggregate_verification_key": "7b232392c3130342c34392c35312c3130332c3136352c37364223a7b22726f6f74223a5b3137392c3135312c3135382c37332c37372c2c3135392c3226d745f636f6d6d69746d656e7",
          "multi_signature": "7bc3139392c3135392c3235342c3231392c3133362c3132392c38342c353227369676e617475726573223a5b5b7b227369676d61223a5b3135312c362c3131222c33382c3135382c3137312c3137312c3234392c32342c3232382c3133302c38352c32362c38382c3135382c32303c323337322c323339362c32342c313530342c313532302c3135323737302c323830372c323831392c323834302c323834342c323836302c323837322c323838362c323839312c323839382c3239333533332c343538352c343632342c343634322c343634372c343636362c334312c31343636382c31343637352c31343639352c31343639392c31343730312c31343730352c31343733302c31343733382c31343733392c31343734362c31343735342c31343736312c31343738362c31343739352c31343739362c31343832362c31343835392c31343836302c31343836322c31343837312c31343837322c31343837392c31343838392c31343839332c31343839372c31343839392c31343932362c31343937372c31343939312c31353032332c31353033382c31353034342c31353036332c31353039312c31353039322c31353039382c31353131392c31353132312c31353136362c31353139362c31353230322c31353231302c31353231392c31353233392c31353234362c31353235322c31353237352c31353238312c31353334372c31353335372c31353338372c31353431372c31353434352c31353434382c31353435332c31353435342c31353530382c31353534352c31353536302c31353537302c31353538392c31353631302c31353631312c31353631322c31353632382c31353633302c31353633392c31353636302c31353636312c31353637392c31353731372c31353731392c31353732362c31353733382c31353734382c31353735392c31353736312c31353739312c31353830312c31353830332c31353831342c31353831392c31353832372c31353832392c31353834392c31353835332c31353835372c31353835392c31353836372c31353839362c31353930312c31353930372c31353931302c31353931332c31353931352c31353935352c31353937362c31353938372c31363031372c31363036332c31363131382c31363132382c31363135352c31363136372c31363230312c31363230362c31363231392c31363232312c31363232392c31363233342c31363234362c31363333302c31363335302c31363336362c31353739312c31353830312c31353830332c31353831342c31353831392c31353832372c31353832392c31353834392c31353835332c31353835372c31353835392c31353836372c31353839362c31353930312c31353930372c31353931302c31353931332c31353931352c31353935352c31353937362c31353938372c31363031372c31363036332c31363131382c31363132382c31363135352c31363136372c31363230312c31363230362c31363231392c31363232312c31363232392c31363233342c31363234362c31363333302c31363335302c31363336362c31363339302c31363430342c31363435342c31363437392c31363533302c31363533382c31363534372c31363535322c31363630382c31363631312c31363631382c31363633312c31363635382c31363637312c31363639352c31363730302c31363731332c31363732372c31363733312c31363733322c31363734322c31363736302c31363737342c31363739322c31363739362c31363739382c31363830342c31363831302c31363834302c31363834382c31363835392c31363836332c31363838362c31363838382c31363930302c31363932372c31363932382c31363932392c31363933372c31363934302c31363934362c31363935302c31363936312c31363938312c31373033302c31373035332c31373036322c31373038322c31373130312c31373130332c31373130352c31373130362c31373132302c31373132312c31373133322c31373133332c31373135312c31373135392c31373138332c31373232302c31373239322c31373331312c31373331332c31373332362c31373333362c31373334352c31373334392c31373335372c31373337352c31373338332c31373338352c31373430302c31373430362c31373431342c31373432322c31373434362c31373435312c31373436362c31373530322c31373531392c31373535382c31373536352c31373537332c31373538302c31373630362c31373632332c31373636382c31373639352c31373732392c31373733312c31373733352c31373733372c31373734342c31373734352c31373734372c31373736382c31373737302c31373737332c31373737352c31373739362c31373830342c31373831302c31373831332c31373832332c31373834352c31373834362c31373838382c31373839342c31373930352c31373931302c31373935372c31373936372c31373938372c31373939342c31383030322c31383030332c31383031312c31383032302c31383032392c31383034362c31383036382c31383037322c31383131372c31383133372c31383134302c31383134332c31383136322c31383137302c31383137342c31383138342c31383138392c31383139392c31383230382c31383232302c31383235312c31383235332c31383237392c31383238312c31383239312c31383239382c31383330312c31383331362c31383332382c31383334312c31383336332c31383337342c31383338352c31383338372c31383434392c31383437362c31383438322c31383439382c31383530352c31383530362c31383531342c31383532362c31383532382c31383533382c31383535322c31383535382c31383537342c31383538342c31383539322c31383631392c32c3832392c3834382c3835312c3835342c3836352c3838332c3838342c3839332c3839372c3930392c3937312c3938362c3939352c313032312c313032362c313035312c313036322c313036382c313038322c313038332c313038352c313133312c313134392c313135392c313136342c313137322c313137332c313231372c313231382c313234372c313239332c313330382c313331352c313333302c313335302c313336342c313337392c313430302c313430362c313432372c313434392c313436342c313436362c313436372c313437362c313530312c313530342c313532302c313532352c313533322c313534322c313536372c313537362c313538322c313538332c313632362c313633322c313633332c313634312c313635322c313730302c313732392c313831322c313832302c313834322c313835392c313837312c313930352c313930372c313931322c313931332c313935362c313936302c313937342c323030302c323031302c323033322c323033372c323037372c323038372c323039382c323130372c323131382c323133322c323133382c323135312c323230332c323230392c323231312c323233372c323234382c323235332c323237372c323238302c323330382c323331342c323333322c323334332c323334382c373535362c373535382c373537372c373630392c373631382c373633392c373635342c373635352c373731392c373732322c373732332c373830342c373832372c373833362c373833372c373835302c373835332c373835362c373837382c373839362c373931392c373933312c373933332c373934332c373934362c373935342c383030302c383031302c383031342c383033302c383034332c383035352c383036342c383036382c383037362c383132322c383134332c383134382c383136362c383139302c383234372c383235312c383236302c383237352c383238312c383238352c383330362c383332352c383337332c383337372c383338372c383339372c383339382c383431362c383433312c383436362c383436372c383437372c383438332c383438392c383439322c383439382c383531372c383533302c383533352c383534302c383536392c383539392c383631322c383634322c383635322c383637302c383730312c383733342c383738382c383739312c383832372c383834352c383835312c383836312c383837362c383932392c383933372c383935322c383937362c393031362c393032302c393032372c393032392c393034382c393036302c393038392c393130332c393130362c393131312c393131322c393131382c393133342c393134392c393137372c393137382c393231312c393231322c393232392c393234332c393236312c393236322c393238362c393239372c393331382c393333392c393338312c393339352c393339362c393431372c393433302c393436332c393439322c393532342c393633332c393633352c393634322c393639322c393731382c393732342c393732362c393733352c393735362c393738302c393738322c393739332c393831332c393837312c393839382c393931382c393932332c393932362c393934312c393934392c393935322c393935382c393936312c393936342c393937352c31303030362c31303032362c31303032392c31303035382c31303037342c31303037392c31303131302c31303132332c31303133392c31303134382c31303135362c31303136392c31303230362c31303235352c31303235372c31303235382c31303237332c31303237342c31303239312c31303239332c31303239342c31303330352c31303334312c31303334332c31303338322c31303338332c31303430342c31303431312c31303431332c31303432302c31303434322c31303434342c31303435372c31303436302c31303437322c31303438372c31303532322c31303535312c31303536342c31303636352c31303638352c31303730302c31303730362c31303733322c31303734332c31303737322c31303831352c31303833332c31303834332c31303836362c31303839322c31303930382c31303938382c31313033362c31313034312c31313037312c31313038322c31313039322c31313039392c31313130392c31313131352c31313134362c31313139332c31313230302c31313232382c31313232392c31313235342c31313236372c31313238302c31313239332c31313239352c31313331312c31313331382c31313332322c31313334302c31313334342c31313335322c31313335342c31313335352c31313335362c31313338352c31313430322c31313431332c31313433342c31313434322c31313436382c31313437322c31313437372c31313439362c31313439392c31313530362c31313531302c31313532342c31313532372c31313534342c31313538312c31313539322c31313630342c31313633352c31313635382c31313733332c31313733362c31313735342c31313739342c31313831332c31313831392c31313832342c31313832372c31313836392c31313837312c31313931342c31313937302c31313937342c31323031362c31323031392c31323034302c31323034342c31323035342c31323036382c31323037302c31323037372c31323039392c31323130342c31323133302c31323133392c31323135302c31323135392c31323136302c31323137352c31323230302c31323230322c31323232382c31323233392c31323330352c31323336382c31323337352c31323337392c31323338392c31323430372c31323431302c31323433322c31323434302c31323434312c31323437352c31323530362c31323531322c31323531332c31323531372c31323532312c31323533302c31323538302c31323633362c31323636392c31323637322c31323637362c31323637372c31323638332c31323638372c31323730352c31323732342c31323734362c31323734382c31323737362c31323739392c31323838352c31323839392c31323930372c31323933302c31323933322c31323935382c31323939332c31333030332c31333033302c31333036312c31333038302c31333038332c31333130352c31333132372c31333133312c31333136392c31333138312c31333138322c31333138352c3133323231231333236352c31333238362c31333234322cc31333239342c3131333438362c1e233332362c31333333392c31333336352c31333337332c31333338352c31333339392c31333433332c31333435312c31333437382c3",
          "genesis_signature": "",
        }

    SnapshotListMessage:
      description: SnapshotListMessage represents a list of snapshots
      type: array
      items:
        $ref: "#/components/schemas/Snapshot"
      example:
        [
          {
            "digest": "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
            "beacon":
              {
                "network": "mainnet",
                "epoch": 329,
                "immutable_file_number": 7060000,
              },
            "certificate_hash": "7905e83ab5d7bc082c1bbc3033bfd19c539078830d19080d1f241c70aa532572",
            "size": 26058531636,
            "created_at": "2022-07-21T17:32:28Z",
            "locations":
              [
                "https://mithril-cdn-us.iohk.io/snapshot/6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
                "https://mithril-cdn-eu.iohk.io/snapshot/6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
                "magnet:?xt=urn:sha1:YNCKHTQCWBTRNJIV4WNAE52SJUQCZO5C",
                "ipfs:QmPXME1oRtoT627YKaDPDQ3PwA8tdP9rWuAAweLzqSwAWT",
              ],
          },
        ]

    Snapshot:
      description: Snapshot represents a snapshot file and its metadata
      type: object
      additionalProperties: false
      required:
        - digest
        - beacon
        - certificate_hash
        - size
        - created_at
        - locations
      properties:
        digest:
          description: Digest that is signed by the signer participants
          type: string
          format: bytes
        beacon:
          $ref: "#/components/schemas/CardanoDbBeacon"
        certificate_hash:
          description: Hash of the associated certificate
          type: string
          format: bytes
        size:
          description: Size of the snapshot file in Bytes
          type: integer
          format: int64
        created_at:
          description: Date and time at which the snapshot was created
          type: string
          format: date-time
        locations:
          description: Locations where the binary content of the snapshot can be retrieved
          type: array
          items:
            type: string
        compression_algorithm:
          description: Compression algorithm for the snapshot archive
          type: string
        cardano_node_version:
          description: Version of the Cardano node which is used to create snapshot archives.
          type: string
      example:
        {
          "digest": "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
          "beacon":
            {
              "network": "mainnet",
              "epoch": 329,
              "immutable_file_number": 7060000,
            },
          "certificate_hash": "7905e83ab5d7bc082c1bbc3033bfd19c539078830d19080d1f241c70aa532572",
          "size": 26058531636,
          "created_at": "2022-07-21T17:32:28Z",
          "locations":
            [
              "https://mithril-cdn-us.iohk.io/snapshot/6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
              "https://mithril-cdn-eu.iohk.io/snapshot/6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
              "magnet:?xt=urn:sha1:YNCKHTQCWBTRNJIV4WNAE52SJUQCZO5C",
              "ipfs:QmPXME1oRtoT627YKaDPDQ3PwA8tdP9rWuAAweLzqSwAWT",
            ],
          "compression_algorithm": "zstandard",
          "cardano_node_version": "1.0.0",
        }

    SnapshotMessage:
      description: This message represents a snapshot file and its metadata.
      allOf:
        - $ref: "#/components/schemas/Snapshot"
      example:
        {
          "digest": "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
          "beacon":
            {
              "network": "mainnet",
              "epoch": 329,
              "immutable_file_number": 7060000,
            },
          "certificate_hash": "7905e83ab5d7bc082c1bbc3033bfd19c539078830d19080d1f241c70aa532572",
          "size": 26058531636,
          "created_at": "2022-07-21T17:32:28Z",
          "locations":
            [
              "https://mithril-cdn-us.iohk.io/snapshot/6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
              "https://mithril-cdn-eu.iohk.io/snapshot/6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
              "magnet:?xt=urn:sha1:YNCKHTQCWBTRNJIV4WNAE52SJUQCZO5C",
              "ipfs:QmPXME1oRtoT627YKaDPDQ3PwA8tdP9rWuAAweLzqSwAWT",
            ],
          "compression_algorithm": "zstandard",
          "cardano_node_version": "1.0.0",
        }

    SnapshotDownloadMessage:
      description: SnapshotDownloadMessage represents a downloaded snapshot event
      type: object
      additionalProperties: false
      required:
        - digest
        - beacon
        - size
        - locations
        - compression_algorithm
        - cardano_node_version
      properties:
        digest:
          description: Digest that is signed by the signer participants
          type: string
          format: bytes
        beacon:
          $ref: "#/components/schemas/CardanoDbBeacon"
        size:
          description: Size of the snapshot file in Bytes
          type: integer
          format: int64
        locations:
          description: Locations where the binary content of the snapshot can be retrieved
          type: array
          items:
            type: string
        compression_algorithm:
          description: Compression algorithm for the snapshot archive
          type: string
        cardano_node_version:
          description: Version of the Cardano node which is used to create snapshot archives.
          type: string
      example:
        {
          "digest": "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
          "beacon":
            {
              "network": "mainnet",
              "epoch": 329,
              "immutable_file_number": 7060000,
            },
          "size": 26058531636,
          "locations":
            [
              "https://mithril-cdn-us.iohk.io/snapshot/6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
              "https://mithril-cdn-eu.iohk.io/snapshot/6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
              "magnet:?xt=urn:sha1:YNCKHTQCWBTRNJIV4WNAE52SJUQCZO5C",
              "ipfs:QmPXME1oRtoT627YKaDPDQ3PwA8tdP9rWuAAweLzqSwAWT",
            ],
          "compression_algorithm": "zstandard",
          "cardano_node_version": "1.0.0",
        }

    MithrilStakeDistributionListMessage:
      description: MithrilStakeDistributionListMessage represents a list of Mithril stake distribution
      type: array
      items:
        type: object
        additionalProperties: false
        required:
          - epoch
          - hash
          - created_at
        properties:
          epoch:
            $ref: "#/components/schemas/Epoch"
          hash:
            description: Hash of the Mithril stake distribution
            type: string
            format: bytes
          certificate_hash:
            description: Hash of the associated certificate
            type: string
            format: bytes
          created_at:
            description: Date and time at which the Mithril stake distribution was created
            type: string
            format: date-time,
        example:
          {
            "epoch": 123,
            "hash": "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
            "certificate_hash": "7905e83ab5d7bc082c1bbc3033bfd19c539078830d19080d1f241c70aa532572",
            "created_at": "2022-06-14T10:52:31Z",
          }

    MithrilStakeDistributionMessage:
      description: This message represents a Mithril stake distribution.
      type: object
      additionalProperties: false
      required:
        - epoch
        - hash
        - signers
        - created_at
        - protocol_parameters
      properties:
        epoch:
          $ref: "#/components/schemas/Epoch"
        hash:
          description: Hash of the Mithril stake distribution
          type: string
          format: bytes
        certificate_hash:
          description: Hash of the associated certificate
          type: string
          format: bytes
        signers:
          description: The list of the signers with their stakes and verification keys
          type: array
          items:
            $ref: "#/components/schemas/SignerWithStake"
        created_at:
          description: Date and time of the entity creation
          type: string
          format: date-time,
        protocol_parameters:
          $ref: "#/components/schemas/ProtocolParameters"
      example:
        {
          "epoch": 123,
          "hash": "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
          "certificate_hash": "7905e83ab5d7bc082c1bbc3033bfd19c539078830d19080d1f241c70aa532572",
          "signers":
            [
              {
                "party_id": "1234567890",
                "verification_key": "7b12766b223a5c342b39302c32392c39392c39382c3131313138342c32252c32352c31353",
                "verification_key_signature": "7b5473693727369676d61223a7b227369676d6d61223a7b261223a9b227369676d61213a",
                "operational_certificate": "5b73136372c38302c37342c3136362c313535b5b3232352c3230332c3235352c313030262c38322c39382c32c39332c3138342c3135362c3136362c32312c3131312c3232312c36332c3137372c3232332c3232332c31392c3537",
                "kes_period": 123,
                "stake": 1234,
              },
              {
                "party_id": "2345678900",
                "verification_key": "7b392c39392c13131312766b223a5c39382c313342b39302c252c32352c31353328342c32",
                "verification_key_signature": "2c33302c3133312c3138322c34362c3133352c372c3139302c3235322c35352c32322c39",
                "operational_certificate": "3231342c3137372c37312c3232352c3233332c3135335d2c322c3139322c5b3133352c34312c3230332c3131332c3c33352c3234302c3230392c312c32392c3233332c33342c3138382c3134312c3130342c3234382c3231392c3",
                "kes_period": 456,
                "stake": 2345,
              },
            ],
          "created_at": "2022-06-14T10:52:31Z",
          "protocol_parameters": { "k": 5, "m": 100, "phi_f": 0.65 },
        }

    CardanoTransactionSnapshotListMessage:
      description: CardanoTransactionSnapshotListMessage represents a list of Cardano transactions set snapshots
      type: array
      items:
        type: object
        additionalProperties: false
        required:
          - hash
          - certificate_hash
          - merkle_root
          - epoch
          - block_number
          - created_at
        properties:
          hash:
            description: Hash of the Cardano transactions set
            type: string
            format: bytes
          certificate_hash:
            description: Hash of the associated certificate
            type: string
            format: bytes
          merkle_root:
            description: Merkle root of the Cardano transactions set
            type: string
            format: bytes
          epoch:
            $ref: "#/components/schemas/Epoch"
          block_number:
            description: Cardano block number
            type: integer
            format: int64
          created_at:
            description: Date and time at which the Cardano transactions set was created
            type: string
            format: date-time,
        example:
          {
            "hash": "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
            "certificate_hash": "7905e83ab5d7bc082c1bbc3033bfd19c539078830d19080d1f241c70aa532572",
            "merkle_root": "33bfd17bc082ab5dd1fc0788241c70aa5325241c70aa532530d190809c5391bbc307905e8372",
            "epoch": 123,
            "block_number": 1234,
            "created_at": "2022-06-14T10:52:31Z",
          }

    CardanoTransactionSnapshotMessage:
      description: This message represents a Cardano transactions set snapshot.
      type: object
      additionalProperties: false
      required:
        - hash
        - certificate_hash
        - merkle_root
        - epoch
        - block_number
        - created_at
      properties:
        hash:
          description: Hash of the Cardano transactions set
          type: string
          format: bytes
        certificate_hash:
          description: Hash of the associated certificate
          type: string
          format: bytes
        merkle_root:
          description: Merkle root of the Cardano transactions set
          type: string
          format: bytes
        epoch:
          $ref: "#/components/schemas/Epoch"
        block_number:
          description: Cardano block number
          type: integer
          format: int64
        created_at:
          description: Date and time at which the Cardano transactions set was created
          type: string
          format: date-time,
      example:
        {
          "hash": "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
          "certificate_hash": "7905e83ab5d7bc082c1bbc3033bfd19c539078830d19080d1f241c70aa532572",
          "merkle_root": "33bfd17bc082ab5dd1fc0788241c70aa5325241c70aa532530d190809c5391bbc307905e8372",
          "epoch": 123,
          "block_number": 1234,
          "created_at": "2022-06-14T10:52:31Z",
        }

    CardanoTransactionProofMessage:
      description: This message represents proofs for Cardano Transactions.
      type: object
      additionalProperties: false
      required:
        - certificate_hash
        - certified_transactions
        - non_certified_transactions
        - latest_block_number
      properties:
        certificate_hash:
          description: Hash of the certificate that validate the merkle root of this proof
          type: string
          format: bytes
        certified_transactions:
          description: Proofs for certified Cardano transactions
          type: array
          items:
            type: object
            required:
              - transactions_hashes
              - proof
            properties:
              transactions_hashes:
                type: array
                items:
                  description: Hash of the Cardano transactions
                  type: string
                  format: bytes
              proof:
                description: Proof for the Cardano transactions
                type: string
                format: bytes
        non_certified_transactions:
          type: array
          items:
            description: Hash of the non certified Cardano transactions
            type: string
            format: bytes
        latest_block_number:
          description: Last block number
          type: integer
          format: int64
      example:
        {
          "certificate_hash": "7905e83ab5d7bc082c1bbc3033bfd19c539078830d19080d1f241c70aa532572",
          "certified_transactions":
            [
              {
                "transactions_hashes":
                  [
                    "6367ee65d0d1272e6e70736a1ea2cae34015874517f6328364f6b73930966732",
                    "5d0d1272e6e70736a1ea2cae34015876367ee64517f6328364f6b73930966732",
                  ],
                "proof": "5b73136372c38302c37342c3136362c313535b5b323136362c313535b5b3232352c3230332c3235352c313030262c38322c39382c32c39332c3138342c313532352c3230332c3235352c313030262c33136362c313535b5b3232352c3230332c3235352c313030262c38322c39382c32c39332c3138342c31358322c39382c32c39332c3138342c3135362c3136362c32312c3131312c3232312c36332c3137372c3232332c3232332c31392c3537",
              },
            ],
          "non_certified_transactions":
            ["732d0d1272e6e70736367ee6f6328364f6b739309666a1ea2cae34015874517"],
          "latest_block_number": 7060000,
        }

    Error:
      description: Internal error representation
      type: object
      additionalProperties: false
      required:
        - message
      properties:
        label:
          description: optional label
          type: string
        message:
          description: error message
          type: string
          example: "An error occurred, the operation could not be completed"
      example:
        {
          "label": "Internal error",
          "message": "An error occurred, the operation could not be completed",
        }