openapi: 3.0.0
info:
  title: V2 allocation off-ledger API
  description: |
    Implemented by token registries to support wallets and apps that use and manage
    allocations while orchestrating the settlement of asset transfers.
  version: 1.0.0
paths:
  /registry/allocation/v2/settlement-factory:
    post:
      summary: "POST /registry/allocation/v2/settlement-factory"
      operationId: getSettlementFactory
      description: |
        Get the factory and choice context for settling allocations using the
        `SettlementFactory_SettleBatch` choice.

        Registries MAY limit the size of the settlement requests that they support.

        To ensure wide compatibility with apps, registries MUST support all
        settlement requests that involve at most 25 transfer legs. In a worst
        case scenario this means supporting a settlement request involving:

        - 25 transfer legs
        - 25 distinct instrument ids
        - 50 allocations
        - 50 distinct accounts
        - 100 distinct parties

        Registries MAY support larger settlement requests.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetFactoryRequest'
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FactoryWithChoiceContext'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
  /registry/allocations/v2/{allocationId}/choice-contexts/withdraw:
    post:
      summary: "POST /registry/allocations/v2/:allocationId/choice-contexts/withdraw"
      operationId: getAllocationWithdrawContext
      description: |
        Get the choice context to withdraw an allocation.
      parameters:
        - name: allocationId
          description: The contract ID of the allocation to withdraw.
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetChoiceContextRequest'
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChoiceContext'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
  /registry/allocations/v2/{allocationId}/choice-contexts/cancel:
    post:
      summary: "POST /registry/allocations/v2/:allocationId/choice-contexts/cancel"
      operationId: getAllocationCancelContext
      description: |
        Get the choice context to cancel an allocation.
      parameters:
        - name: allocationId
          description: The contract ID of the allocation to cancel.
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetChoiceContextRequest'
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChoiceContext'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
components:
  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'
    '409':
      description: conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    GetFactoryRequest:
      type: object
      properties:
        choiceArguments:
          type: object
          description: |
            The arguments that are intended to be passed to the choice provided by the factory.
            To avoid repeating the Daml type definitions, they are specified as JSON objects.
            However the concrete format is given by how the choice arguments are encoded using the Daml JSON API
            (with the `extraArgs.context` and `extraArgs.meta` fields set to the empty object).

            The choice arguments are provided so that the registry can also provide choice-argument
            specific contracts, e.g., the configuration for a specific instrument-id.
        excludeDebugFields:
          description: If set to true, the response will not include fields prefixed with 'debug'. Useful to save bandwidth.
          default: false
          type: boolean
      required:
        - choiceArguments
    FactoryWithChoiceContext:
      description: |
        A factory contract together with the choice context required to exercise the choice
        provided by the factory. Typically used to implement the generic initiation of on-ledger workflows
        via a Daml interface.

        Clients SHOULD avoid reusing the same `FactoryWithChoiceContext` for exercising multiple choices,
        as the choice context MAY be specific to the choice being exercised.
      type: object
      properties:
        factoryId:
          description: The contract ID of the contract implementing the factory interface.
          type: string
        choiceContext:
          $ref: '#/components/schemas/ChoiceContext'
      required:
        - factoryId
        - choiceContext
    GetChoiceContextRequest:
      description: |
        A request to get the context for executing a choice on a contract.
      type: object
      properties:
        meta:
          description: |
            Metadata that will be passed to the choice, and should be incorporated
            into the choice context. Provided for extensibility.
          type: object
          additionalProperties:
            type: string
        excludeDebugFields:
          description: If set to true, the response will not include fields prefixed with 'debug'. Useful to save bandwidth.
          default: false
          type: boolean
    ChoiceContext:
      description: |
        The context required to exercise a choice on a contract via an interface.
        Used to retrieve additional reference data that is passed in via disclosed contracts,
        which are in turn referred to via their contract ID in the `choiceContextData`.

        Asset implementations SHOULD avoid that this value depends on contract-ids passed
        in the choice arguments, so that clients can prefetch choice contexts when chaining
        multiple token standard actions together in a single Daml transaction.
      type: object
      properties:
        choiceContextData:
          description: The additional data to use when exercising the choice.
          type: object
        disclosedContracts:
          description: |
            The contracts that are required to be disclosed to the participant node for exercising
            the choice.
          type: array
          items:
            $ref: '#/components/schemas/DisclosedContract'
      required:
        - choiceContextData
        - disclosedContracts
    DisclosedContract:
      type: object
      properties:
        templateId:
          description: The fully qualified template identifier of the disclosed contract.
          type: string
        contractId:
          description: The contract ID of the disclosed contract.
          type: string
        createdEventBlob:
          description: |
            The serialized created event of the disclosed contract, forwarded unchanged as retrieved
            from the JSON Ledger API.
          type: string
        synchronizerId:
          description: |
            The synchronizer to which the contract is currently assigned.
            If the contract is in the process of being reassigned, then a "409" response is returned.
          type: string
        debugPackageName:
          description: |
            The name of the Daml package that was used to create the contract.
            Use this data only if you trust the provider, as it might not match the data in the
            `createdEventBlob`.
          type: string
        debugPayload:
          description: |
            The contract arguments that were used to create the contract.
            Use this data only if you trust the provider, as it might not match the data in the
            `createdEventBlob`.
          type: object
        debugCreatedAt:
          description: |
            The ledger effective time at which the contract was created.
            Use this data only if you trust the provider, as it might not match the data in the
            `createdEventBlob`.
          type: string
          format: date-time
      required:
        - templateId
        - contractId
        - createdEventBlob
        - synchronizerId
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string