components.yml

openapi: "3.0.0"
info:
  title: Indexd types
  version: 1.0.0
paths: {}

components:
  schemas:
    #############################
    #
    # Core types
    #
    #############################

    Address:
      allOf:
        - $ref: "#/components/schemas/Hash256"
        - description: The hash of a set of UnlockConditions

    BlockID:
      allOf:
        - $ref: "#/components/schemas/Hash256"
        - description: A unique identifier for a block

    ChainIndex:
      type: object
      properties:
        height:
          allOf:
            - $ref: "#/components/schemas/BlockHeight"
            - description: The height of the block in the blockchain
        id:
          allOf:
            - $ref: "#/components/schemas/BlockID"
            - description: The ID of the block

    Currency:
      type: string
      pattern: "^\\d+$"
      maxLength: 39 # fits 2^128 - 1
      description: An unsigned amount of Hastings, the smallest unit of currency in Sia. 1 Siacoin (SC) equals 10^24 Hastings (H).

    EncryptionKey:
      type: string
      pattern: ^(key|skey):[0-9a-fA-F]{64}$
      description: A key used to encrypt and decrypt data. The key is either a regular key (key) or a salted key (skey). The latter requires a seed to be used for encryption and decryption.

    Event:
      type: object
      description: A transaction or other event that affects the wallet including miner payouts, siafund claims, and file contract payouts.
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/Hash256"
            - description: The event's ID
        index:
          allOf:
            - $ref: "#/components/schemas/ChainIndex"
            - description: Information about the block that triggered the creation of this event
        confirmations:
          type: integer
          format: uint64
          description: The number of blocks on top of the block that triggered the creation of this event
        type:
          type: string
          enum:
            - miner
            - foundation
            - siafundClaim
            - v1Transaction
            - v1ContractResolution
            - v2Transaction
            - v2ContractResolution
          description: The type of the event
        data:
          type: object
        maturityHeight:
          allOf:
            - $ref: "#/components/schemas/BlockHeight"
            - description: The block height at which the payout matures.
        timestamp:
          type: string
          format: date-time
          description: The time the event was created
        relevant:
          type: array
          items:
            $ref: "#/components/schemas/Address"

    FileContractID:
      type: string
      pattern: "^fcid:[0-9a-fA-F]{64}$"
      description: A unique identifier for a file contract

    Hash256:
      type: string
      pattern: ^[0-9a-fA-F]{64}$
      description: A 256-bit blake2b hash

    HostPrices:
      type: object
      properties:
        contractPrice:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: Cost to the renter for forming, renewing, or refreshing a contract. Paid up front and covers the cost of the revision and storage proof transaction the host broadcasts at the end of the contract.
        collateral:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The amount of Hastings the host will risk per byte of storage per block.
        storagePrice:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: Cost per byte of storage per block.
        ingressPrice:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: Cost per byte of data uploaded from the host
        egressPrice:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: Cost per byte of data downloaded from the host
        tipHeight:
          type: integer
          format: uint64
          description: The height at which the prices were last updated
        validUntil:
          type: string
          format: date-time
          description: The time at which these prices will no longer be honored by the host.
        signature:
          $ref: "#/components/schemas/Signature"

    HostSettings:
      type: object
      properties:
        protocolVersion:
          $ref: "#/components/schemas/SemVer"
        release:
          type: string
          description: Release tag of the host software
          example: "hostd 1.0.0"
        walletAddress:
          $ref: "#/components/schemas/Address"
        acceptingContracts:
          type: boolean
          description: Whether the host is accepting new contracts
        maxCollateral:
          $ref: "#/components/schemas/Currency"
        maxContractDuration:
          type: integer
          format: uint64
          description: Maximum allowed contract duration
        remainingStorage:
          type: integer
          format: uint64
          description: Amount of storage the host has remaining
        totalStorage:
          type: integer
          format: uint64
          description: Total amount of storage space
        prices:
          $ref: "#/components/schemas/HostPrices"

    IPNet:
      type: object
      properties:
        ip:
          type: string
          description: The IP address in CIDR notation
          example: 100.82.250.91
        mask:
          type: string
          description: The subnet mask in CIDR notation
          example: 24

    NetAddress:
      type: object
      properties:
        address:
          type: string
          description: The network address of the host, typically in the format "host:port".
          example: "example.com:9980"
        protocol:
          type: string
          enum:
            - siamux
            - quic
          description: The protocol used by the host

    SealedObject:
      type: object
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/Hash256"
            - description: The object's unique ID
        encryptedDataKey:
          type: string
          format: byte
          description: The encrypted data key used to encrypt and decrypt the object's data
        slabs:
          type: array
          items:
            $ref: "#/components/schemas/SlabSlice"
          description: The list of slabs that make up the object
        dataSignature:
          $ref: "#/components/schemas/Signature"
          description: The signature of the object's data
        encryptedMetadataKey:
          type: string
          format: byte
          description: The encrypted metadata key used to encrypt and decrypt the object's metadata
        encryptedMetadata:
          type: string
          format: byte
          description: Optional metadata stored on the object
        metadataSignature:
          $ref: "#/components/schemas/Signature"
        createdAt:
          type: string
          format: date-time
          description: The time the object was created
        updatedAt:
          type: string
          format: date-time
          description: The time the object was last updated

    # A shared object contains all information required to retrieve
    # and decrypt an object without additional account context.
    SharedObject:
      type: object
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/Hash256"
            - description: The shared object's unique ID
        slabs:
          type: array
          description: The list of slabs that make up the shared object
          items:
            $ref: "#/components/schemas/SlabSlice"

    # A sector pinned to a host.
    PinnedSector:
      type: object
      properties:
        root:
          allOf:
            - $ref: "#/components/schemas/Hash256"
            - description: The Merkle root of the sector
        hostKey:
          allOf:
            - $ref: "#/components/schemas/PublicKey"
            - description: The public key of the host storing the sector

    ObjectSlab:
      type: object
      description: A reference to a previously pinned slab that is part of an object
      required:
        - id
        - offset
        - length
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/SlabID"
            - description: The ID of the pinned slab
        offset:
          type: integer
          format: uint32
          description: The offset within the slab where the slice starts
        length:
          type: integer
          format: uint32
          description: The length of the slice

    PinObjectRequest:
      type: object
      description: The request body for creating or updating an object. Slabs must already be pinned to the indexer.
      required:
        - id
        - encryptedDataKey
        - slabs
        - dataSignature
        - metadataSignature
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/Hash256"
            - description: The object's ID, computed as a hash of its slabs. The server validates this matches the computed value.
        encryptedDataKey:
          type: string
          format: byte
          description: The encrypted data key used to encrypt and decrypt the object's data (base64-encoded in JSON)
        slabs:
          type: array
          items:
            $ref: "#/components/schemas/ObjectSlab"
          description: The list of previously pinned slabs that make up the object
        dataSignature:
          allOf:
            - $ref: "#/components/schemas/Signature"
            - description: A signature of blake2b(object ID, encrypted_data_key) attesting that the object data has not been tampered with
        encryptedMetadataKey:
          type: string
          format: byte
          description: The encrypted metadata key used to encrypt and decrypt the object's metadata (base64-encoded in JSON)
        encryptedMetadata:
          type: string
          format: byte
          description: Optional metadata stored as a byte array (base64-encoded in JSON, max 1024 bytes)
        metadataSignature:
          allOf:
            - $ref: "#/components/schemas/Signature"
            - description: A signature of blake2b(object ID, metadata key, encrypted_metadata) attesting that the metadata has not been tampered with

    ObjectEvent:
      type: object
      properties:
        key:
          allOf:
            - $ref: "#/components/schemas/Hash256"
            - description: The object's unique ID
        deleted:
          type: boolean
          description: Whether the object was deleted or not
        updatedAt:
          type: string
          format: date-time
          description: Last time the object was created, updated, or deleted.
        object:
          allOf:
            - $ref: "#/components/schemas/SealedObject"
            - description: The object, if it exists

    PublicKey:
      type: string
      pattern: "^ed25519:[0-9a-fA-F]{64}$"
      description: A ed25519 public key

    SemVer:
      type: array
      description: "Represents a semantic version as an array of three unsigned 8-bit integers: [major, minor, patch]"
      minItems: 3
      maxItems: 3
      items:
        type: integer
        format: uint8
        minimum: 0
        maximum: 255
      example: [1, 2, 3]

    Signature:
      type: string
      format: byte
      pattern: "[0-9a-fA-F]{64}"
      description: A ed25519 signature

    SlabSlice:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/SlabID"
        encryptionKey:
          $ref: "#/components/schemas/EncryptionKey"
        minShards:
          type: integer
          format: uint64
          description: Minimum number of shards required to reconstruct the slab
        sectors:
          type: array
          description: The list of sectors composing the slab
          items:
            $ref: "#/components/schemas/PinnedSector"
        offset:
          type: integer
          format: uint32
          description: The offset within the slab where the slice starts
        length:
          type: integer
          format: uint32
          description: The length of the slice

    TransactionID:
      allOf:
        - $ref: "#/components/schemas/Hash256"
        - description: Unique identifier for a transaction.

    #############################
    #
    # Helper types
    #
    #############################

    BlockHeight:
      type: integer
      format: uint64
      description: The height of a block
      example: 92813

    BuildState:
      type: object
      properties:
        buildTime:
          type: string
          format: date-time
          description: The build time of the build
        commit:
          type: string
          description: The commit hash of the build
        version:
          type: string
          description: The version of the build
        os:
          type: string
          description: The operating system of the build

    SyncerAddress:
      type: string
      description: The address of the syncer
      example: "118.92.232.145:9981"

    Explorer:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether we use the explorer to get exchange rates or not.
        url:
          type: string
          format: uri
          description: The base URL of the explorer API

    Severity:
      type: string
      enum: [info, warning, error, critical]

    Alert:
      type: object
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/Hash256"
            - description: The unique identifier for the alert.
        severity:
          allOf:
            - $ref: "#/components/schemas/Severity"
            - description: The severity of the alert.
        message:
          type: string
          description: Human-readable message describing the alert.
        data:
          type: object
          description: Map of arbitrary data that can be used to provide additional context to the alert
        timestamp:
          type: string
          format: date-time
          description: Time the alert was generated.

    Account:
      type: object
      properties:
        accountKey:
          allOf:
            - $ref: "#/components/schemas/PublicKey"
            - description: Public key of the account
        connectKey:
          type: string
          description: The connect key associated with the account.
        maxPinnedData:
          type: number
          format: uint64
          description: Maximum amount of pinned data in bytes for this app account.
        quotaMaxPinnedData:
          type: number
          format: uint64
          description: Maximum amount of pinned data in bytes allowed by the quota.
        connectKeyPinnedData:
          type: number
          format: uint64
          description: Current amount of pinned data in bytes used across all apps sharing the same connect key, before redundancy.
        pinnedData:
          type: number
          format: uint64
          description: Current amount of pinned data in bytes before redundancy.
        pinnedSize:
          type: number
          format: uint64
          description: Current amount of pinned data in bytes including redundancy.
        ready:
          type: boolean
          description: Whether the account is ready to be used. This only returns 'false' after an account is created. Once an account is ready it will remain ready. Getting ready can take up to a few minutes
        app:
          $ref: "#/components/schemas/AppMeta"
        lastUsed:
          type: string
          format: date-time
          description: The last time the account was used. Updated when pinning a slab or retrieving a slab.

    AppAccountResponse:
      type: object
      properties:
        accountKey:
          $ref: "#/components/schemas/Account/properties/accountKey"
        maxPinnedData:
          type: number
          format: uint64
          description: >
            Effective maximum amount of pinned data in bytes for this app
            account, equal to the lower of the account's maxPinnedData and
            quotaMaxPinnedData.
        remainingStorage:
          type: number
          format: uint64
          description: Remaining amount of data in bytes that can still be pinned, after applying both the app account limit and current quota.
        pinnedData:
          $ref: "#/components/schemas/Account/properties/pinnedData"
        pinnedSize:
          $ref: "#/components/schemas/Account/properties/pinnedSize"
        ready:
          $ref: "#/components/schemas/Account/properties/ready"
        app:
          $ref: "#/components/schemas/Account/properties/app"
        lastUsed:
          $ref: "#/components/schemas/Account/properties/lastUsed"

    AppMeta:
      type: object
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/Hash256"
            - description: The app's unique identifier
        name:
          type: string
          description: Name of the app
        description:
          type: string
          description: Description of the app
        logoURL:
          type: string
          format: uri
          description: The URL to the logo of the app
        serviceURL:
          type: string
          format: uri
          description: The homepage of the app

    Contract:
      type: object
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/FileContractID"
            - description: The unique identifier for the file contract.
        hostKey:
          allOf:
            - $ref: "#/components/schemas/PublicKey"
            - description: The public key of the host.
        formation:
          type: string
          format: date-time
          description: The time when the contract was formed.
        renewedFrom:
          allOf:
            - $ref: "#/components/schemas/FileContractID"
            - description: The ID of the contract this one was renewed from, if applicable.

        nextPrune:
          type: string
          description: The time when the contract will be pruned next.
          format: date-time
        lastBroadcastAttempt:
          type: string
          description: The time of the last revision broadcast attempt for the contract.
          format: date-time

        revisionNumber:
          allOf:
            - $ref: "#/components/schemas/RevisionNumber"
            - description: The current revision number of the contract
        proofHeight:
          allOf:
            - $ref: "#/components/schemas/BlockHeight"
            - description: The start of the contract's proof window
        expirationHeight:
          allOf:
            - $ref: "#/components/schemas/BlockHeight"
            - description: The end of the contract's proof window
        capacity:
          type: integer
          format: uint64
          description: The amount of data that is paid for already. This is always larger or equal than the size of the contract.
        size:
          type: integer
          format: uint64
          description: The size of the contract in bytes
        initialAllowance:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The initial funds locked in the contract.
        remainingAllowance:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The remaining funds in the contract.
        totalCollateral:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The total amount of collateral locked in the contract.

        renewedTo:
          allOf:
            - $ref: "#/components/schemas/FileContractID"
            - description: The ID of the contract this one was renewed to, if applicable.
        usedCollateral:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The amount of collateral that is already used.
        contractPrice:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The price of forming the contract.
        minerFee:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The miner fee spent on the formation transaction.

        good:
          type: boolean
          description: Whether the contract is considered healthy and usable. If the contract is bad its data will be migrated to another contract.
        state:
          type: string
          description: The state of the contract
          enum:
            - pending
            - active
            - resolved
            - expired
            - rejected
        spending:
          allOf:
            - $ref: "#/components/schemas/ContractSpending"
            - description: Costs and spending details of the contract.

    ContractSpending:
      type: object
      properties:
        appendSector:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: Total amount spent on appending sectors to a contract
        freeSector:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: Total amount spent on freeing sectors in a contract
        fundAccount:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: Total amount spent on funding ephemeral accounts
        sectorRoots:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: Total amount spent on retrieving sector roots

    Host:
      type: object
      properties:
        publicKey:
          $ref: "#/components/schemas/PublicKey"
        lastAnnouncement:
          type: string
          format: date-time
          description: The time the host last announced itself
        lastFailedScan:
          type: string
          format: date-time
          description: The time the host last failed a scan
        lastSuccessfulScan:
          type: string
          format: date-time
          description: The time the host last successfully scanned
        nextScan:
          type: string
          format: date-time
          description: The time the host is scheduled to be scanned next
        consecutiveFailedScans:
          type: integer
          format: uint64
          description: The number of consecutive failed scans
        recentUptime:
          type: string
          format: float64
          description: The recent uptime of the host as a number between 0 and 1, where 1 means 100% uptime
        addresses:
          type: array
          items:
            $ref: "#/components/schemas/NetAddress"
        settings:
          $ref: "#/components/schemas/HostSettings"
        usability:
          $ref: "#/components/schemas/HostUsability"
        blocked:
          type: boolean
          description: Whether the host is blocked
        blockedReasons:
          type: array
          items:
            type: string
          description: The reasons why the host is blocked
          example: ["Uptime"]
        lostSectors:
          type: integer
          format: uint64
          description: The number of sectors the host lost
        unpinnedSectors:
          type: integer
          format: uint64
          description: The number of unpinned sectors on the host
        fundsSpent:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The total amount of funds spent on this host
        countryCode:
          type: string
          description: The ISO 3166-1 A-2 country code of the host inferred from its IP address.
        latitude:
          type: number
          format: float
          description: Approximate latitude of the host inferred from its IP address.
        longitude:
          type: number
          format: float
          description: Approximate longitude of the host inferred from its IP address.

    HostInfo:
      type: object
      properties:
        publicKey:
          $ref: "#/components/schemas/PublicKey"
        addresses:
          type: array
          items:
            $ref: "#/components/schemas/NetAddress"
        countryCode:
          type: string
          description: The ISO 3166-1 A-2 country code of the host inferred from its IP address.
        latitude:
          type: number
          format: float
          description: Approximate latitude of the host inferred from its IP address.
        longitude:
          type: number
          format: float
          description: Approximate longitude of the host inferred from its IP address.
        goodForUpload:
          type: boolean
          description: Whether the host is good for uploading data. False if the host is stuck or out of storage.

    HostUsability:
      type: object
      properties:
        uptime:
          type: boolean
          description: Whether the host matches a minimum uptime requirement
        maxContractDuration:
          type: boolean
          description: Whether the host supports the maximum contract duration
        maxCollateral:
          type: boolean
          description: Whether the host supports the maximum collateral
        protocolVersion:
          type: boolean
          description: Whether the host supports the required minimum protocol version
        priceValidity:
          type: boolean
          description: Whether the host's prices validity exceeds the minimum required validity
        acceptingContracts:
          type: boolean
          description: Whether the host is currently accepting new contracts
        quic:
          type: boolean
          description: Whether the host supports QUIC on a valid port
        siamux:
          type: boolean
          description: Whether the host supports the SiaMux protocol
        contractPrice:
          type: boolean
          description: Whether the host's contract price is below the maximum contract price
        collateral:
          type: boolean
          description: Whether the host's collateral is above the minimum collateral
        storagePrice:
          type: boolean
          description: Whether the host's storage price is below the maximum storage price
        ingressPrice:
          type: boolean
          description: Whether the host's ingress price is below the maximum ingress price
        egressPrice:
          type: boolean
          description: Whether the host's egress price is below the maximum egress price
        freeSectorPrice:
          type: boolean
          description: Whether the host's free sector price is below the maximum free sector price

    MaintenanceSettings:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether contract maintenance is enabled
          default: false
        wantedContracts:
          type: integer
          format: uint64
          description: The minimum number of contracts to form
          default: 0
        period:
          type: integer
          format: uint64
          description: The length of a contract's period in blocks (1 block being 10 minutes on average)
          default: 0
        renewWindow:
          type: integer
          format: uint64
          description: The number of blocks before the end of a contract that a contract should be renewed
          default: 0

    PinnedSettings:
      type: object
      properties:
        currency:
          type: string
          description: The currency used for price pinning. If this is empty price pinning is disabled.
          example: "usd"
        maxEgressPrice:
          type: number
          format: float
          description: The maximum egress price a host can charge, in the specified currency. This pin is disabled if the value is 0.
        maxIngressPrice:
          type: number
          format: float
          description: The maximum ingress price a host can charge, in the specified currency. This pin is disabled if the value is 0.
        maxStoragePrice:
          type: number
          format: float
          description: The maximum storage price a host can charge, in the specified currency. This pin is disabled if the value is 0.
        minCollateral:
          type: number
          format: float
          description: The minimum collateral a host must put up, in the specified currency. This pin is disabled if the value is 0.

    RevisionNumber:
      type: integer
      format: uint64
      description: The revision number of the contract
      example: 246

    SlabID:
      type: string
      pattern: ^[0-9a-fA-F]{64}$
      description: A unique identifier for a slab, which is a collection of data shards stored on hosts.

    UsabilitySettings:
      type: object
      properties:
        maxEgressPrice:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The maximum egress price a host can charge
        maxIngressPrice:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The maximum ingress price a host can charge
        maxStoragePrice:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The maximum storage price a host can charge
        minCollateral:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The minimum collateral a host must put up
        minProtocolVersion:
          allOf:
            - $ref: "#/components/schemas/SemVer"
            - description: "The minimum protocol version the host must have to be considered usable. The version is represented as an array of three unsigned 8-bit integers: [major, minor, patch]"

    RegisterAppResponse:
      type: object
      properties:
        responseURL:
          type: string
          format: uri
          description: URL where the application can complete connection
        statusURL:
          type: string
          format: uri
          description: URL to poll for connection request status
        registerURL:
          type: string
          format: uri
          description: URL to complete registration after approval using a signed request
        expiration:
          type: string
          format: date-time
          description: Expiration time of the request

    AuthConnectStatusResponse:
      type: object
      properties:
        approved:
          type: boolean
          description: The status of an application connection request.
        reconnecting:
          type: boolean
          description: Whether the user has previously connected the app. Only set when the request is approved.
        userSecret:
          allOf:
            - $ref: "#/components/schemas/Hash256"
            - description: Secret required to derive the application key. Only returned when the request is approved.

    AccountStatsResponse:
      type: object
      properties:
        registered:
          type: integer
          format: uint64
          description: Number of accounts currently registered on the indexer
        active:
          type: integer
          format: uint64
          description: Number of accounts active in the last week.

    ConnectKeyQuotaStats:
      type: object
      properties:
        quota:
          $ref: "#/components/schemas/QuotaKey"
        total:
          type: integer
          format: uint64
          description: Number of connect keys associated with this quota

    ConnectKeyStatsResponse:
      type: object
      properties:
        total:
          type: integer
          format: uint64
          description: Total number of connect keys
        quotas:
          type: array
          items:
            $ref: "#/components/schemas/ConnectKeyQuotaStats"
          description: Breakdown of connect keys by quota

    AppStatsResponse:
      type: array
      items:
        type: object
        properties:
          appID:
            allOf:
              - $ref: "#/components/schemas/Hash256"
              - description: The app's ID
          name:
            type: string
            description: Name of the app
          accounts:
            type: integer
            format: uint64
            description: Total number of accounts belonging to this app
          active:
            type: integer
            format: uint64
            description: Number of accounts active in the last week
          pinnedData:
            type: integer
            format: uint64
            description: Total pinned data in bytes before redundancy across all accounts in this app
          pinnedSize:
            type: integer
            format: uint64
            description: Total pinned data in bytes including redundancy across all accounts in this app

    ContractsStatsResponse:
      type: object
      properties:
        contracts:
          type: integer
          format: int64
          description: Total number of active contracts managed by this instance
        badContracts:
          type: integer
          format: int64
          description: Total number of active, bad contracts managed by this instance
        renewing:
          type: integer
          format: int64
          description: Number of contracts currently within their renew window
        totalCapacity:
          type: integer
          format: int64
          description: Total capacity of all active contracts
        totalSize:
          type: integer
          format: int64
          description: Total size of all active contracts

    HostsStatsResponse:
      type: array
      items:
        type: object
        properties:
          accountUsage:
            allOf:
              - $ref: "#/components/schemas/Currency"
              - description: Total amount spent on ephemeral accounts
          activeContractsSize:
            type: integer
            format: int64
            description: Total size of all active contracts on this host
          publicKey:
            allOf:
              - $ref: "#/components/schemas/PublicKey"
              - description: The public key of the host
          lostSectors:
            type: integer
            format: int64
            description: Total number of sectors lost on this host
          unpinnedSectors:
            type: integer
            format: int64
            description: Total number of unpinned sectors on this host
          totalUsage:
            allOf:
              - $ref: "#/components/schemas/Currency"
              - description: Total amount spent on this host
          scans:
            type: integer
            format: int64
            description: Number of times this host has been scanned
          scansFailed:
            type: integer
            format: int64
            description: Number of times this host has been unsuccessfully scanned
          blocked:
            type: boolean
            description: Whether the host is currently blocked
          blockedReasons:
            type: array
            items:
              type: string
            description: Reasons why the host was blocked, if any
          stuckSince:
            type: string
            format: date-time
            nullable: true
            description: Timestamp when the host became stuck.
          usable:
            type: boolean
            description: Whether the host is considered usable
          goodForUpload:
            type: boolean
            description: Whether the host is usable, not stuck, and has remaining storage

    AggregatedHostStatsResponse:
      type: object
      properties:
        active:
          type: integer
          format: uint64
          description: Number of hosts that are not stuck and have a good contract
        goodForUpload:
          type: integer
          format: uint64
          description: Number of hosts that are good for uploading to (hosts that are usable, not stuck and have remaining storage)
        totalScans:
          type: integer
          format: int64
          description: Total number of host scans performed
        failedScans:
          type: integer
          format: int64
          description: Total number of failed host scans

    SectorStatsResponse:
      type: object
      properties:
        slabs:
          type: integer
          format: int64
          description: Number of slabs currently pinned by this instance
        migrated:
          type: integer
          format: int64
          description: Total number of sectors that have been migrated
        pinned:
          type: integer
          format: int64
          description: Number of sectors currently pinned to a contract by this instance
        unpinnable:
          type: integer
          format: int64
          description: Number of unpinnable sectors that were pruned because they could not be pinned to a contract in due time
        unpinned:
          type: integer
          format: int64
          description: Number of sectors currently not pinned to any contract by this instance
        lost:
          type: integer
          format: int64
          description: Number of sectors that have been marked as lost.
        checked:
          type: integer
          format: int64
          description: Total sectors that have been integrity checked.
        checkFailed:
          type: integer
          format: int64
          description: Number of sectors that have had failed integrity checks.

    QuotaKey:
      type: string
      description: Unique identifier for a quota
      pattern: "^[a-zA-Z0-9_-]{1,32}$"
      minLength: 1
      maxLength: 32

    Quota:
      type: object
      properties:
        key:
          $ref: "#/components/schemas/QuotaKey"
        description:
          type: string
          description: Human-readable description of the quota
        maxPinnedData:
          type: integer
          format: uint64
          description: Maximum number of bytes that may be pinned by accounts using this quota
        totalUses:
          type: integer
          description: Total number of accounts that can be created using connect keys with this quota
        fundTargetBytes:
          type: integer
          format: uint64
          description: Funding target in bytes per host used to calculate how much data equivalent funds to fund accounts with. 0 means no funding.

    UpdateAccountRequest:
      type: object
      properties:
        maxPinnedData:
          type: integer
          format: uint64
          description: Maximum number of bytes that may be pinned by this account

    PutQuotaRequest:
      type: object
      properties:
        description:
          type: string
          description: Human-readable description of the quota
        maxPinnedData:
          type: integer
          format: uint64
          description: Maximum number of bytes that may be pinned by accounts using this quota
        totalUses:
          type: integer
          minimum: 0
          description: Total number of accounts that can be created using connect keys with this quota
        fundTargetBytes:
          type: integer
          format: uint64
          minimum: 0
          description: Funding target in bytes per host used to calculate how much data equivalent funds to fund accounts with. 0 means no funding.

    ConnectKey:
      type: object
      properties:
        key:
          type: string
          description: App key/ID
        description:
          type: string
          description: App description
        quota:
          $ref: "#/components/schemas/QuotaKey"
        remainingUses:
          type: integer
          description: Remaining number of times this key can be used to create accounts
        dateCreated:
          type: string
          format: date-time
          description: Date this key was created
        lastUpdated:
          type: string
          format: date-time
          description: Last time this key was updated
        lastUsed:
          type: string
          format: date-time
          description: Last time this key was used to register an account
        pinnedData:
          type: integer
          format: uint64
          description: Sum of all the pinned data before redundancy of the accounts associated with this key
        pinnedSize:
          type: integer
          format: uint64
          description: Sum of all the pinned data including redundancy of the accounts associated with this key

    AppConnectKeyRequest:
      type: object
      required:
        - quota
      properties:
        key:
          type: string
          description: App key/ID
        description:
          type: string
          description: App description
        quota:
          $ref: "#/components/schemas/QuotaKey"