SwarmCommon.yaml

openapi: 3.0.3
info:
  version: 0.6.0
  title: Common Data Types
  description: |
    \*****bzzz*****

externalDocs:
  description: Browse the documentation @ the Swarm Docs
  url: "https://docs.swarm.eth"

paths: {}
components:
  schemas:
    Address:
      type: object
      properties:
        address:
          $ref: "#/components/schemas/SwarmAddress"

    Addresses:
      type: object
      properties:
        overlay:
          $ref: "#/components/schemas/SwarmAddress"
        underlay:
          type: array
          items:
            $ref: "#/components/schemas/P2PUnderlay"
        ethereum:
          $ref: "#/components/schemas/EthereumAddress"
        publicKey:
          $ref: "#/components/schemas/PublicKey"
        pssPublicKey:
          $ref: "#/components/schemas/PublicKey"

    BigInt:
      description: Numeric string that represents integer which might exceeds `Number.MAX_SAFE_INTEGER` limit (2^53-1)
      type: string
      example: "1000000000000000000"

    ReserveState:
      type: object
      properties:
        radius:
          type: integer
        available:
          type: integer
        outer:
          $ref: "#/components/schemas/BigInt"
        inner:
          $ref: "#/components/schemas/BigInt"

    ChainState:
      type: object
      properties:
        block:
          type: integer
        totalAmount:
          type: integer
        currentPrice:
          type: integer

    Balance:
      type: object
      properties:
        peer:
          $ref: "#/components/schemas/SwarmAddress"
        balance:
          $ref: "#/components/schemas/BigInt"

    Balances:
      type: object
      properties:
        balances:
          type: array
          items:
            $ref: "#/components/schemas/Balance"

    BzzTopology:
      type: object
      properties:
        baseAddr:
          $ref: "#/components/schemas/SwarmAddress"
        population:
          type: integer
        connected:
          type: integer
        timestamp:
          type: string
        nnLowWatermark:
          type: integer
        depth:
          type: integer
        bins:
          type: object
          additionalProperties:
            type: object
            properties:
              population:
                type: integer
              connected:
                type: integer
              disconnectedPeers:
                type: object
              connectedPeers:
                type: object

    Cheque:
      type: object
      properties:
        beneficiary:
          $ref: "#/components/schemas/EthereumAddress"
        chequebook:
          $ref: "#/components/schemas/EthereumAddress"
        payout:
          $ref: "#/components/schemas/BigInt"

    ChequeAllPeersResponse:
      type: object
      properties:
        lastcheques:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/ChequePeerResponse"

    ChequePeerResponse:
      type: object
      properties:
        peer:
          $ref: "#/components/schemas/SwarmAddress"
        lastreceived:
          $ref: "#/components/schemas/Cheque"
        lastsent:
          $ref: "#/components/schemas/Cheque"

    ChequebookBalance:
      type: object
      properties:
        totalBalance:
          $ref: "#/components/schemas/BigInt"
        availableBalance:
          $ref: "#/components/schemas/BigInt"

    ChequebookAddress:
      type: object
      properties:
        chequebookAddress:
          $ref: "#/components/schemas/EthereumAddress"

    DateTime:
      type: string
      format: date-time
      #pattern: '^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{7}\+\d{2}:\d{2})$'
      example: "2020-06-11T11:26:42.6969797+02:00"

    Duration:
      description: Go time.Duration format
      type: string
      example: "5.0018ms"

    EthereumAddress:
      type: string
      pattern: "^[A-Fa-f0-9]{40}$"
      example: "36b7efd913ca4cf880b8eeac5093fa27b0825906"

    FileName:
      type: string

    GasLimit:
      type: integer
      minimum: 0
      maximum: 18446744073709551615

    GasPrice:
      type: integer

    Hash:
      type: object
      properties:
        hash:
          $ref: "#/components/schemas/SwarmAddress"

    HexString:
      type: string
      pattern: "^([A-Fa-f0-9]+)$"
      example: "cf880b8eeac5093fa27b0825906c600685"

    MultiAddress:
      type: string

    NewTagRequest:
      type: object
      properties:
        address:
          $ref: "#/components/schemas/SwarmAddress"

    NewTagResponse:
      type: object
      properties:
        uid:
          $ref: "#/components/schemas/Uid"
        startedAt:
          $ref: "#/components/schemas/DateTime"
        total:
          type: integer
        processed:
          type: integer
        synced:
          type: integer

    NewTagDebugResponse:
      type: object
      properties:
        total:
          type: integer
        split:
          type: integer
        seen:
          type: integer
        stored:
          type: integer
        sent:
          type: integer
        synced:
          type: integer
        uid:
          $ref: "#/components/schemas/Uid"
        address:
          $ref: "#/components/schemas/SwarmAddress"
        startedAt:
          $ref: "#/components/schemas/DateTime"

    TagsList:
      type: object
      properties:
        tags:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/NewTagResponse"

    P2PUnderlay:
      type: string
      example: "/ip4/127.0.0.1/tcp/1634/p2p/16Uiu2HAmTm17toLDaPYzRyjKn27iCB76yjKnJ5DjQXneFmifFvaX"

    Peers:
      type: object
      properties:
        peers:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/Address"

    PssRecipient:
      type: string

    PssTargets:
      type: string

    PssTopic:
      type: string

    ProblemDetails:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer

    ReferenceResponse:
      type: object
      properties:
        reference:
          $ref: "#/components/schemas/SwarmReference"

    PostageBatchesResponse:
      type: object
      properties:
        stamps:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/PostageBatch"

    BatchIDResponse:
      type: object
      properties:
        batchID:
          $ref: "#/components/schemas/BatchID"

    Response:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer

    RttMs:
      type: object
      properties:
        rtt:
          $ref: "#/components/schemas/Duration"

    Status:
      type: object
      properties:
        status:
          type: string

    PostageBatch:
      type: object
      properties:
        batchID:
          $ref: "#/components/schemas/BatchID"
        utilization:
          type: integer
        label:
          type: string
        depth:
          type: integer
        amount:
          $ref: "#/components/schemas/BigInt"
        createdAt:
          type: integer

    Settlement:
      type: object
      properties:
        peer:
          $ref: "#/components/schemas/SwarmAddress"
        received:
          type: integer
        sent:
          type: integer

    Settlements:
      type: object
      properties:
        totalReceived:
          type: integer
        totalSent:
          type: integer
        settlements:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/Settlement"

    SwarmAddress:
      type: string
      pattern: "^[A-Fa-f0-9]{64}$"
      example: "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"

    PublicKey:
      type: string
      pattern: "^[A-Fa-f0-9]{66}$"
      example: "02ab7473879005929d10ce7d4f626412dad9fe56b0a6622038931d26bd79abf0a4"

    SwarmEncryptedReference:
      type: string
      pattern: "^[A-Fa-f0-9]{128}$"
      example: "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f2d2810619d29b5dbefd5d74abce25d58b81b251baddb9c3871cf0d6967deaae2"

    DomainName:
      type: string
      pattern: '^[A-Za-z0-9]+\.[A-Za-z0-9]+$'
      example: "swarm.eth"

    BatchID:
      pattern: "^[A-Fa-f0-9]{64}$"
      example: "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"

    SwarmOnlyReference:
      oneOf:
        - $ref: "#/components/schemas/SwarmAddress"
        - $ref: "#/components/schemas/SwarmEncryptedReference"

    SwarmOnlyReferencesList:
      type: object
      properties:
        addresses:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/SwarmOnlyReference"

    SwarmReference:
      oneOf:
        - $ref: "#/components/schemas/SwarmAddress"
        - $ref: "#/components/schemas/SwarmEncryptedReference"
        - $ref: "#/components/schemas/DomainName"

    SwapCashoutResult:
      type: object
      properties:
        recipient:
          $ref: "#/components/schemas/EthereumAddress"
        lastPayout:
          $ref: "#/components/schemas/BigInt"
        bounced:
          type: boolean

    SwapCashoutStatus:
      type: object
      properties:
        peer:
          $ref: "#/components/schemas/SwarmAddress"
        lastCashedCheque:
          $ref: "#/components/schemas/Cheque"
        transactionHash:
          $ref: "#/components/schemas/TransactionHash"
        result:
          $ref: "#/components/schemas/SwapCashoutResult"
        uncashedAmount:
          $ref: "#/components/schemas/BigInt"

    TagName:
      type: string

    TransactionHash:
      type: string
      pattern: "^[A-Fa-f0-9]{64}$"
      example: "e28a34ffe7b1710c1baf97ca6d71d81b7f159a9920910876856c8d94dd7be4ae"

    TransactionResponse:
      type: object
      properties:
        transactionHash:
          $ref: "#/components/schemas/TransactionHash"

    Uid:
      type: integer

    WelcomeMessage:
      type: object
      properties:
        welcomeMessage:
          type: string

    FeedType:
      type: string
      pattern: "^(sequence|epoch)$"

  headers:
    SwarmTag:
      description: "Tag UID"
      schema:
        $ref: "SwarmCommon.yaml#/components/schemas/Uid"

    SwarmFeedIndex:
      description: "The index of the found update"
      schema:
        $ref: "#/components/schemas/HexString"

    SwarmFeedIndexNext:
      description: "The index of the next possible update"
      schema:
        $ref: "#/components/schemas/HexString"

    SwarmRecoveryTargets:
      description: "The targets provided for recovery"
      schema:
        type: string

    ETag:
      description: |
        The RFC7232 ETag header field in a response provides the current entity-
        tag for the selected resource. An entity-tag is an opaque identifier for
        different versions of a resource over time, regardless whether multiple
        versions are valid at the same time. An entity-tag consists of an opaque
        quoted string, possibly prefixed by a weakness indicator.
      schema:
        type: string

  parameters:

    GasPriceParameter:
      in: header
      name: gas-price
      schema:
        $ref: "SwarmCommon.yaml#/components/schemas/GasPrice"
      required: false
      description: "Gas price for transaction"

    GasLimitParameter:
      in: header
      name: gas-limit
      schema:
        $ref: "SwarmCommon.yaml#/components/schemas/GasLimit"
      required: false
      description: "Gas limit for transaction"

    SwarmRecoveryTargetsParameter:
      in: query
      name: targets
      schema:
        type: string
      required: false
      description: Global pinning targets prefix

    SwarmTagParameter:
      in: header
      name: swarm-tag
      schema:
        $ref: "SwarmCommon.yaml#/components/schemas/Uid"
      required: false
      description: Associate upload with an existing Tag UID

    SwarmPinParameter:
      in: header
      name: swarm-pin
      schema:
        type: boolean
      required: false
      description: Represents the pinning state of the chunk

    SwarmEncryptParameter:
      in: header
      name: swarm-encrypt
      schema:
        type: boolean
      required: false
      description: Represents the encrypting state of the file

    ContentTypePreserved:
      in: header
      name: Content-Type
      schema:
        type: string
      description: The specified content-type is preserved for download of the asset

    SwarmIndexDocumentParameter:
      in: header
      name: swarm-index-document
      schema:
        type: string
        example: index.html
      required: false
      description: Default file to be referenced on path, if exists under that path

    SwarmErrorDocumentParameter:
      in: header
      name: swarm-error-document
      schema:
        type: string
        example: error.html
      required: false
      description: Configure custom error document to be returned when a specified path can not be found in collection

    SwarmCollection:
      in: header
      name: swarm-collection
      schema:
        type: boolean
      required: false
      description: Upload file/files as a collection

    SwarmPostageBatchId:
      in: header
      name: swarm-postage-batch-id
      description: "ID of Postage Batch that is used to upload data with"
      required: true
      schema:
        $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"

  responses:
    "204":
      description: The resource was deleted successfully.
    "400":
      description: Bad request
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    "401":
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    "402":
      description: Payment Required
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    "403":
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    "404":
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    "500":
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"