openapi: 3.0.0
info:
  title: Validator API
  version: 0.0.1
servers:
  - url: https://example.com/api/validator
tags:
  - name: validator
paths:
  /v0/scan-proxy/dso-party-id:
    get:
      summary: "GET /v0/scan-proxy/dso-party-id"
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: getDsoPartyId
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDsoPartyIdResponse'
  /v0/scan-proxy/dso:
    get:
      summary: "GET /v0/scan-proxy/dso"
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: getDsoInfo
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDsoInfoResponse'
  /v0/scan-proxy/featured-apps/{provider_party_id}:
    get:
      summary: "GET /v0/scan-proxy/featured-apps/:provider_party_id"
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: lookupFeaturedAppRight
      parameters:
        - name: provider_party_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupFeaturedAppRightResponse'
  /v0/scan-proxy/open-and-issuing-mining-rounds:
    get:
      summary: "GET /v0/scan-proxy/open-and-issuing-mining-rounds"
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: getOpenAndIssuingMiningRounds
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOpenAndIssuingMiningRoundsProxyResponse'
  /v0/scan-proxy/amulet-rules:
    get:
      summary: "GET /v0/scan-proxy/amulet-rules"
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: getAmuletRules
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAmuletRulesProxyResponse'
  /v0/scan-proxy/ans-entries/by-party/{party}:
    get:
      summary: "GET /v0/scan-proxy/ans-entries/by-party/:party"
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: lookupAnsEntryByParty
      parameters:
        - name: party
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupEntryByPartyResponse'
        '404':
          $ref: '#/components/responses/404'
  /v0/scan-proxy/ans-entries:
    get:
      summary: "GET /v0/scan-proxy/ans-entries"
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: listAnsEntries
      parameters:
        - name: name_prefix
          in: query
          schema:
            type: string
        - name: page_size
          in: query
          required: true
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEntriesResponse'
  /v0/scan-proxy/ans-entries/by-name/{name}:
    get:
      summary: "GET /v0/scan-proxy/ans-entries/by-name/:name"
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: lookupAnsEntryByName
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupEntryByNameResponse'
        '404':
          $ref: '#/components/responses/404'
  /v0/scan-proxy/ans-rules:
    post:
      summary: "POST /v0/scan-proxy/ans-rules"
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: getAnsRules
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetAnsRulesRequest'
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAnsRulesResponse'
  /v0/scan-proxy/transfer-preapprovals/by-party/{party}:
    get:
      summary: "GET /v0/scan-proxy/transfer-preapprovals/by-party/:party"
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: lookupTransferPreapprovalByParty
      parameters:
        - name: party
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupTransferPreapprovalByPartyResponse'
        '404':
          $ref: '#/components/responses/404'
  /v0/scan-proxy/transfer-command-counter/{party}:
    get:
      summary: "GET /v0/scan-proxy/transfer-command-counter/:party"
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: lookupTransferCommandCounterByParty
      parameters:
        - name: party
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupTransferCommandCounterByPartyResponse'
        '404':
          description: No TransferCommandCounter exists for this party. This means the nonce that should be used is 0.
          $ref: '#/components/responses/404'
  /v0/scan-proxy/transfer-command/status:
    get:
      summary: "GET /v0/scan-proxy/transfer-command/status"
      description: Retrieve the status of all transfer commands of the given sender for the specified nonce.
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: lookupTransferCommandStatus
      parameters:
        - name: sender
          in: query
          required: true
          schema:
            type: string
        - name: nonce
          in: query
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupTransferCommandStatusResponse'
        '404':
          description: No TransferCommand exists with this contract id within the last 24h
          $ref: '#/components/responses/404'
  /v0/scan-proxy/holdings/summary:
    post:
      summary: "POST /v0/scan-proxy/holdings/summary"
      deprecated: true
      tags:
        - deprecated
      x-jvm-package: scanproxy
      operationId: getHoldingsSummaryAt
      description: |
        Deprecated. Please use /v1/scan-proxy/holdings/summary instead. Returns the summary of active amulet contracts for a given migration id and record time, for the given parties.
        This is an aggregate of `/v0/holdings/state` by owner party ID with better performance than client-side computation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HoldingsSummaryRequest'
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HoldingsSummaryResponse'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /v1/scan-proxy/holdings/summary:
    post:
      summary: "POST /v1/scan-proxy/holdings/summary"
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: getHoldingsSummaryAtV1
      description: |
        Returns the summary of active amulet contracts for a given migration id and record time, for the given parties.
        This is an aggregate of `/v0/holdings/state` by owner party ID with better performance than client-side computation.
        Unlike /v0/scan-proxy/holdings/summary, this version does not include holding fee fields
        as they do not express a meaningful aggregate value.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HoldingsSummaryRequestV1'
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HoldingsSummaryResponseV1'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /v0/scan-proxy/unclaimed-development-fund-coupons:
    get:
      summary: "GET /v0/scan-proxy/unclaimed-development-fund-coupons"
      tags:
        - scan-proxy
      x-jvm-package: scanproxy
      operationId: listUnclaimedDevelopmentFundCoupons
      description: |
        List all unclaimed development fund coupons.
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUnclaimedDevelopmentFundCouponsResponse'
components:
  schemas:
    GetOpenAndIssuingMiningRoundsProxyResponse:
      type: object
      required:
        - open_mining_rounds
        - issuing_mining_rounds
      properties:
        open_mining_rounds:
          type: array
          items:
            $ref: '#/components/schemas/ContractWithState'
        issuing_mining_rounds:
          type: array
          items:
            $ref: '#/components/schemas/ContractWithState'
    GetAmuletRulesProxyResponse:
      type: object
      required:
        - amulet_rules
      properties:
        amulet_rules:
          $ref: '#/components/schemas/ContractWithState'
    GetDsoPartyIdResponse:
      type: object
      required:
        - dso_party_id
      properties:
        dso_party_id:
          type: string
    Contract:
      type: object
      properties:
        template_id:
          type: string
        contract_id:
          type: string
        payload:
          type: object
        created_event_blob:
          type: string
        created_at:
          type: string
      required:
        - template_id
        - contract_id
        - payload
        - created_event_blob
        - created_at
    ContractWithState:
      type: object
      properties:
        contract:
          $ref: '#/components/schemas/Contract'
        domain_id:
          type: string
      required:
        - contract
    GetDsoInfoResponse:
      type: object
      required:
        - sv_user
        - sv_party_id
        - dso_party_id
        - voting_threshold
        - latest_mining_round
        - amulet_rules
        - dso_rules
        - sv_node_states
      properties:
        sv_user:
          description: User ID representing the SV
          type: string
        sv_party_id:
          description: Party representing the SV
          type: string
        dso_party_id:
          description: |
            Party representing the whole DSO; for Scan only, also returned by
            `/v0/dso-party-id`
          type: string
        voting_threshold:
          description: |
            Threshold required to pass vote requests; also known as the
            "governance threshold", it is always derived from the number of
            `svs` in `dso_rules`
          type: integer
        latest_mining_round:
          description: |
            Contract of the Daml template `Splice.Round.OpenMiningRound`, the
            one with the highest round number on the ledger that has been signed
            by `dso_party_id`. The round may not be usable as it may not be
            opened yet, in accordance with its `opensAt` template field
          $ref: '#/components/schemas/ContractWithState'
        amulet_rules:
          description: |
            Contract of the Daml template `Splice.AmuletRules.AmuletRules`,
            including the full schedule of `AmuletConfig` changes approved by
            the DSO. Callers should not assume that `initialValue` is up-to-date,
            and should instead search `futureValues` for the latest configuration
            valid as of now
          $ref: '#/components/schemas/ContractWithState'
        dso_rules:
          description: |
            Contract of the Daml template `Splice.DsoRules.DsoRules`, listing
            the governance rules approved by the DSO governing this Splice network.
          $ref: '#/components/schemas/ContractWithState'
        sv_node_states:
          description: |
            For every one of `svs` listed in `dso_rules`, a contract of the Daml
            template `Splice.DSO.SvState.SvNodeState`. This does not include
            states for offboarded SVs, though they may still have an on-ledger
            state contract
          type: array
          items:
            $ref: '#/components/schemas/ContractWithState'
        initial_round:
          description: |
            Initial round from which the network bootstraps
          type: string
    LookupFeaturedAppRightResponse:
      description: |
        If defined, a contract of Daml template `Splice.Amulet.FeaturedAppRight`.
      type: object
      properties:
        featured_app_right:
          $ref: '#/components/schemas/Contract'
    AnsEntry:
      type: object
      required:
        - user
        - name
        - url
        - description
      properties:
        contract_id:
          description: |
            If present, Daml contract ID of template `Splice.Ans:AnsEntry`.
            If absent, this is a DSO-provided entry for either the DSO or an SV.
          type: string
        user:
          description: Owner party ID of this ANS entry.
          type: string
        name:
          description: The ANS entry name.
          type: string
        url:
          description: Either empty, or an http/https URL supplied by the `user`.
          type: string
        description:
          description: Arbitrary description text supplied by `user`; may be empty.
          type: string
        expires_at:
          description: |
            Time after which this ANS entry expires; if renewed, it will have a
            new `contract_id` and `expires_at`.
            If `null` or absent, does not expire; this is the case only for
            special entries provided by the DSO.
          type: string
          format: date-time
    LookupEntryByPartyResponse:
      type: object
      required:
        - entry
      properties:
        entry:
          $ref: '#/components/schemas/AnsEntry'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    ListEntriesResponse:
      type: object
      required:
        - entries
      properties:
        entries:
          type: array
          items:
            $ref: '#/components/schemas/AnsEntry'
    LookupEntryByNameResponse:
      type: object
      required:
        - entry
      properties:
        entry:
          $ref: '#/components/schemas/AnsEntry'
    ContractId:
      type: string
    GetAnsRulesRequest:
      type: object
      properties:
        cached_ans_rules_contract_id:
          $ref: '#/components/schemas/ContractId'
        cached_ans_rules_domain_id:
          type: string
    MaybeCachedContractWithState:
      type: object
      properties:
        contract:
          $ref: '#/components/schemas/Contract'
        domain_id:
          type: string
    GetAnsRulesResponse:
      description: |
        A contract state update of Daml template `Splice.Ans.AnsRules`.
      type: object
      properties:
        ans_rules_update:
          $ref: '#/components/schemas/MaybeCachedContractWithState'
      required:
        - ans_rules_update
    LookupTransferPreapprovalByPartyResponse:
      description: A Daml contract of template `Splice.AmuletRules:TransferPreapproval`.
      type: object
      required:
        - transfer_preapproval
      properties:
        transfer_preapproval:
          $ref: '#/components/schemas/ContractWithState'
    LookupTransferCommandCounterByPartyResponse:
      description: A Daml contract of template `Splice.ExternalPartyAmuletRules:TransferCommandCounter`.
      type: object
      required:
        - transfer_command_counter
      properties:
        transfer_command_counter:
          $ref: '#/components/schemas/ContractWithState'
    BaseLookupTransferCommandStatusResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: |
            The status of the transfer command.
            created:
              The transfer command has been created and is waiting for automation to complete it.
            sent:
              The transfer command has been completed and the transfer to the receiver has finished.
            failed:
              The transfer command has failed permanently and nothing has been transferred. Refer to
              failure_reason for details. A new transfer command can be created.
    TransferCommandCreatedResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/BaseLookupTransferCommandStatusResponse'
    TransferCommandSentResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/BaseLookupTransferCommandStatusResponse'
    TransferCommandFailedResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/BaseLookupTransferCommandStatusResponse'
        - type: object
          required:
            - failure_kind
            - reason
          properties:
            failure_kind:
              type: string
              description: |
                The reason for the failure of the TransferCommand.
                failed:
                  Completing the transfer failed, check the reason for details.
                withdrawn:
                  The sender has withdrawn the TransferCommand before it could be completed.
                expired:
                  The expiry time on the TransferCommand was reached before it could be completed.
              enum:
                - failed
                - expired
                - withdrawn
            reason:
              type: string
              description: |
                Human readable description of the failure
    TransferCommandContractStatus:
      type: object
      oneOf:
        - $ref: '#/components/schemas/TransferCommandCreatedResponse'
        - $ref: '#/components/schemas/TransferCommandSentResponse'
        - $ref: '#/components/schemas/TransferCommandFailedResponse'
      discriminator:
        propertyName: status
        mapping:
          created: '#/components/schemas/TransferCommandCreatedResponse'
          sent: '#/components/schemas/TransferCommandSentResponse'
          failed: '#/components/schemas/TransferCommandFailedResponse'
    TransferCommandContractWithStatus:
      description: |
        A contract of Daml template `Splice.ExternalPartyAmuletRules:TransferCommand`,
        and its status determined by the latest transactions.
      type: object
      required:
        - contract
        - status
      properties:
        contract:
          $ref: '#/components/schemas/Contract'
        status:
          $ref: '#/components/schemas/TransferCommandContractStatus'
    TransferCommandMap:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/TransferCommandContractWithStatus'
    LookupTransferCommandStatusResponse:
      type: object
      required:
        - transfer_commands_by_contract_id
      properties:
        transfer_commands_by_contract_id:
          $ref: '#/components/schemas/TransferCommandMap'
    HoldingsSummaryRequest:
      type: object
      required:
        - migration_id
        - record_time
        - owner_party_ids
      properties:
        migration_id:
          type: integer
          format: int64
          description: |
            The migration id for which to return the summary.
        record_time:
          type: string
          format: date-time
          description: |
            The timestamp at which the contract set was active.
            This needs to be an exact timestamp, i.e.,
            needs to correspond to a timestamp reported by `/v0/state/acs/snapshot-timestamp` if `record_time_match` is set to `exact` (which is the default).
            If `record_time_match` is set to `at_or_before`, this can be any timestamp, and the most recent snapshot at or before the given `record_time` will be returned.
        record_time_match:
          type: string
          description: |
            How to match the record_time. "exact" requires the record_time to match exactly.
            "at_or_before" finds the most recent snapshot at or before the given record_time.
          enum:
            - exact
            - at_or_before
          default: exact
        owner_party_ids:
          type: array
          items:
            type: string
          minItems: 1
          description: |
            The owners for which to compute the summary.
        as_of_round:
          type: integer
          format: int64
          description: |
            Compute holding fees as of this round. Defaults to the earliest open mining round.
    HoldingsSummary:
      description: Aggregate Amulet totals for a particular owner party ID.
      type: object
      required:
        - party_id
        - total_unlocked_coin
        - total_locked_coin
        - total_coin_holdings
        - accumulated_holding_fees_unlocked
        - accumulated_holding_fees_locked
        - accumulated_holding_fees_total
        - total_available_coin
      properties:
        party_id:
          description: |
            Owner party ID of the amulet. Guaranteed to be unique among `summaries`.
          type: string
        total_unlocked_coin:
          description: |
            Sum of unlocked amulet at time of reception, not counting holding
            fees deducted since.
          type: string
        total_locked_coin:
          description: |
            Sum of locked amulet at time of original amulet reception, not
            counting holding fees deducted since.
          type: string
        total_coin_holdings:
          description: |
            `total_unlocked_coin` + `total_locked_coin`.
          type: string
        accumulated_holding_fees_unlocked:
          description: |
            Sum of holding fees as of `computed_as_of_round` that apply to
            unlocked amulet.
          type: string
        accumulated_holding_fees_locked:
          description: |
            Sum of holding fees as of `computed_as_of_round` that apply to
            locked amulet, including fees applied since the amulet's creation
            round.
          type: string
        accumulated_holding_fees_total:
          description: |
            Same as `accumulated_holding_fees_unlocked` + `accumulated_holding_fees_locked`.
          type: string
        total_available_coin:
          description: Same as `total_unlocked_coin` - `accumulated_holding_fees_unlocked`.
          type: string
    HoldingsSummaryResponse:
      type: object
      required:
        - record_time
        - migration_id
        - computed_as_of_round
        - summaries
      properties:
        record_time:
          description: The same `record_time` as in the request.
          type: string
          format: date-time
        migration_id:
          description: The same `migration_id` as in the request.
          type: integer
          format: int64
        computed_as_of_round:
          description: The same `as_of_round` as in the request, with the same default.
          type: integer
          format: int64
        summaries:
          type: array
          items:
            $ref: '#/components/schemas/HoldingsSummary'
    HoldingsSummaryRequestV1:
      type: object
      required:
        - migration_id
        - record_time
        - owner_party_ids
      properties:
        migration_id:
          type: integer
          format: int64
          description: |
            The migration id for which to return the summary.
        record_time:
          type: string
          format: date-time
          description: |
            The timestamp at which the contract set was active.
            This needs to be an exact timestamp, i.e.,
            needs to correspond to a timestamp reported by `/v0/state/acs/snapshot-timestamp` if `record_time_match` is set to `exact` (which is the default).
            If `record_time_match` is set to `at_or_before`, this can be any timestamp, and the most recent snapshot at or before the given `record_time` will be returned.
        record_time_match:
          type: string
          description: |
            How to match the record_time. "exact" requires the record_time to match exactly.
            "at_or_before" finds the most recent snapshot at or before the given record_time.
          enum:
            - exact
            - at_or_before
          default: exact
        owner_party_ids:
          type: array
          items:
            type: string
          minItems: 1
          description: |
            The owners for which to compute the summary.
    HoldingsSummaryV1:
      description: Aggregate Amulet totals for a particular owner party ID.
      type: object
      required:
        - party_id
        - total_unlocked_coin
        - total_locked_coin
        - total_coin_holdings
      properties:
        party_id:
          description: |
            Owner party ID of the amulet. Guaranteed to be unique among `summaries`.
          type: string
        total_unlocked_coin:
          description: |
            Sum of unlocked amulet initial amounts, not counting holding
            fees deducted since.
          type: string
        total_locked_coin:
          description: |
            Sum of locked amulet initial amounts, not
            counting holding fees deducted since.
          type: string
        total_coin_holdings:
          description: |
            `total_unlocked_coin` + `total_locked_coin`.
          type: string
    HoldingsSummaryResponseV1:
      type: object
      required:
        - record_time
        - migration_id
        - summaries
      properties:
        record_time:
          description: The same `record_time` as in the request.
          type: string
          format: date-time
        migration_id:
          description: The same `migration_id` as in the request.
          type: integer
          format: int64
        summaries:
          type: array
          items:
            $ref: '#/components/schemas/HoldingsSummaryV1'
    ListUnclaimedDevelopmentFundCouponsResponse:
      type: object
      required:
        - unclaimed-development-fund-coupons
      properties:
        unclaimed-development-fund-coupons:
          description: |
            Contracts of the Daml template `Splice.Amulet:UnclaimedDevelopmentFundCoupon`.
          type: array
          items:
            $ref: '#/components/schemas/ContractWithState'
  responses:
    '400':
      description: bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '404':
      description: not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '500':
      description: internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'