openapi: 3.0.3
info:
  title: ISO-20022 Combo Flow Orchestrator API
  description: |
    API for orchestrating multi-step financial workflows combining DeFi protocols and traditional banking rails (ISO-20022).
    Supports hybrid adapters (DeFi + Fiat/DTL), optional simulation, and compliance integration.
  version: 2.0.0
  contact:
    name: API Support
    email: api-support@example.com

servers:
  - url: https://api.example.com/v2
    description: Production server
  - url: https://staging-api.example.com/v2
    description: Staging server
  - url: http://localhost:8080/v2
    description: Local development server

tags:
  - name: Plans
    description: Execution plan management
  - name: Simulation
    description: Optional workflow simulation (for advanced users)
  - name: Compliance
    description: Compliance checks and identity verification
  - name: Adapters
    description: Adapter registry and management
  - name: Notary
    description: Notarization and audit trail
  - name: Execution
    description: Plan execution and coordination
  - name: Receipts
    description: Execution receipts and audit logs

paths:
  /plans:
    post:
      tags:
        - Plans
      summary: Create a new execution plan
      description: Creates a new execution plan from user-defined steps. Validates plan structure and compliance requirements.
      operationId: createPlan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlanRequest'
      responses:
        '201':
          description: Plan created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
        '400':
          description: Invalid plan structure or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Compliance requirements not met
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{planId}:
    get:
      tags:
        - Plans
      summary: Get plan details
      description: Retrieves detailed information about a specific execution plan
      operationId: getPlan
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Plan details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
        '404':
          description: Plan not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{planId}/signature:
    post:
      tags:
        - Plans
      summary: Add user signature to plan
      description: Adds cryptographic signature from user's wallet to the execution plan
      operationId: addSignature
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignatureRequest'
      responses:
        '200':
          description: Signature added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
        '400':
          description: Invalid signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{planId}/simulate:
    post:
      tags:
        - Simulation
      summary: Simulate plan execution (optional)
      description: |
        Runs a dry-run simulation of the plan execution. Optional feature for advanced users.
        Estimates gas costs, slippage, liquidity checks, and predicts potential failures.
      operationId: simulatePlan
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                includeGasEstimate:
                  type: boolean
                  default: true
                includeSlippageAnalysis:
                  type: boolean
                  default: true
                includeLiquidityCheck:
                  type: boolean
                  default: true
      responses:
        '200':
          description: Simulation results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationResult'
        '400':
          description: Invalid plan or simulation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{planId}/execute:
    post:
      tags:
        - Execution
      summary: Execute plan
      description: |
        Initiates execution of a signed plan. Coordinates atomic execution across DLT and banking rails.
        Supports 2PC (two-phase commit) pattern for atomicity.
      operationId: executePlan
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                atomicityMode:
                  type: string
                  enum: [2PC, HTLC, NOTARY_CONDITIONAL]
                  default: 2PC
      responses:
        '202':
          description: Execution initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionResponse'
        '400':
          description: Plan not ready for execution (missing signature, invalid state)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Plan already executing or executed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{planId}/status:
    get:
      tags:
        - Execution
      summary: Get execution status
      description: Retrieves real-time execution status of a plan
      operationId: getExecutionStatus
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Execution status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionStatus'
        '404':
          description: Plan not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{planId}/abort:
    post:
      tags:
        - Execution
      summary: Abort plan execution
      description: Aborts an in-progress plan execution and triggers rollback
      operationId: abortPlan
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Plan aborted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionStatus'
        '400':
          description: Plan cannot be aborted (already completed or failed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /compliance/status:
    get:
      tags:
        - Compliance
      summary: Get compliance status
      description: Retrieves current user's compliance status (LEI, DID, KYC, AML)
      operationId: getComplianceStatus
      parameters:
        - name: userId
          in: query
          required: false
          schema:
            type: string
          description: User ID (defaults to authenticated user)
      responses:
        '200':
          description: Compliance status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /compliance/check:
    post:
      tags:
        - Compliance
      summary: Check compliance for workflow
      description: Validates compliance requirements for a specific workflow
      operationId: checkWorkflowCompliance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowComplianceRequest'
      responses:
        '200':
          description: Compliance check results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceCheckResult'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /adapters:
    get:
      tags:
        - Adapters
      summary: List available adapters
      description: |
        Lists all available adapters (DeFi protocols + Fiat/DTL rails).
        Supports filtering by type (DeFi, Fiat/DTL), whitelist status, and search.
      operationId: listAdapters
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [DEFI, FIAT_DTL, ALL]
            default: ALL
        - name: whitelistedOnly
          in: query
          schema:
            type: boolean
            default: false
        - name: search
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of adapters
          content:
            application/json:
              schema:
                type: object
                properties:
                  adapters:
                    type: array
                    items:
                      $ref: '#/components/schemas/Adapter'

  /adapters/{adapterId}:
    get:
      tags:
        - Adapters
      summary: Get adapter details
      description: Retrieves detailed information about a specific adapter
      operationId: getAdapter
      parameters:
        - name: adapterId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Adapter details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Adapter'
        '404':
          description: Adapter not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /notary/register:
    post:
      tags:
        - Notary
      summary: Register plan with notary
      description: Registers an execution plan with the notary service for audit trail
      operationId: registerPlan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotaryRegistrationRequest'
      responses:
        '201':
          description: Plan registered with notary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotaryProof'
        '400':
          description: Invalid plan or registration failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /notary/proof/{planId}:
    get:
      tags:
        - Notary
      summary: Get notary proof
      description: Retrieves notary proof for a specific plan
      operationId: getNotaryProof
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Notary proof
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotaryProof'
        '404':
          description: Proof not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /receipts/{planId}:
    get:
      tags:
        - Receipts
      summary: Get execution receipts
      description: Retrieves all execution receipts (DLT transactions, ISO messages, notary proofs) for a plan
      operationId: getReceipts
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Execution receipts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipts'
        '404':
          description: Plan not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /connectors:
    get:
      tags:
        - Execution
      summary: Get connector status
      description: Retrieves status of all connectors (DLT, banking, compliance, liquidity)
      operationId: getConnectorStatus
      responses:
        '200':
          description: Connector status
          content:
            application/json:
              schema:
                type: object
                properties:
                  connectors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConnectorStatus'

components:
  schemas:
    CreatePlanRequest:
      type: object
      required:
        - steps
        - creator
      properties:
        steps:
          type: array
          items:
            $ref: '#/components/schemas/PlanStep'
        creator:
          type: string
          description: User identifier (LEI or DID)
        maxRecursion:
          type: integer
          default: 3
          description: Maximum recursion depth for borrow operations
        maxLTV:
          type: number
          default: 0.6
          description: Maximum loan-to-value ratio

    PlanStep:
      type: object
      discriminator:
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/BorrowStep'
        - $ref: '#/components/schemas/SwapStep'
        - $ref: '#/components/schemas/RepayStep'
        - $ref: '#/components/schemas/PayStep'

    BorrowStep:
      type: object
      required:
        - type
        - asset
        - amount
        - collateralRef
      properties:
        type:
          type: string
          enum: [borrow]
        asset:
          type: string
          example: CBDC_USD
        amount:
          type: number
          example: 100000
        collateralRef:
          type: string
          example: tokenX:123

    SwapStep:
      type: object
      required:
        - type
        - from
        - to
        - amount
      properties:
        type:
          type: string
          enum: [swap]
        from:
          type: string
          example: CBDC_USD
        to:
          type: string
          example: CBDC_EUR
        amount:
          type: number
          example: 100000
        minRecv:
          type: number
          description: Minimum receive amount (slippage protection)

    RepayStep:
      type: object
      required:
        - type
        - asset
        - amount
      properties:
        type:
          type: string
          enum: [repay]
        asset:
          type: string
          example: CBDC_USD
        amount:
          type: number
          example: 20000

    PayStep:
      type: object
      required:
        - type
        - asset
        - amount
        - beneficiary
      properties:
        type:
          type: string
          enum: [pay]
        asset:
          type: string
          example: EUR
        amount:
          type: number
          example: 78000
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'

    Beneficiary:
      type: object
      required:
        - IBAN
      properties:
        IBAN:
          type: string
          example: DE89370400440532013000
        name:
          type: string
          example: Example Corp Ltd.

    Plan:
      type: object
      required:
        - plan_id
        - creator
        - steps
        - maxRecursion
        - maxLTV
      properties:
        plan_id:
          type: string
          format: uuid
        creator:
          type: string
        steps:
          type: array
          items:
            $ref: '#/components/schemas/PlanStep'
        maxRecursion:
          type: integer
        maxLTV:
          type: number
        signature:
          type: string
          nullable: true
          description: User's cryptographic signature
        notary_proof:
          type: string
          nullable: true
          description: Notary proof hash

    SignatureRequest:
      type: object
      required:
        - signature
        - messageHash
        - signerAddress
      properties:
        signature:
          type: string
          description: Cryptographic signature (hex)
        messageHash:
          type: string
          description: Hash of the plan that was signed
        signerAddress:
          type: string
          description: Wallet address that signed

    SimulationResult:
      type: object
      properties:
        planId:
          type: string
          format: uuid
        status:
          type: string
          enum: [SUCCESS, FAILURE, PARTIAL]
        steps:
          type: array
          items:
            $ref: '#/components/schemas/SimulationStepResult'
        gasEstimate:
          type: integer
          description: Estimated gas cost
        estimatedCost:
          type: number
          description: Estimated cost in USD
        slippageAnalysis:
          $ref: '#/components/schemas/SlippageAnalysis'
        liquidityCheck:
          $ref: '#/components/schemas/LiquidityCheck'
        warnings:
          type: array
          items:
            type: string
        errors:
          type: array
          items:
            type: string

    SimulationStepResult:
      type: object
      properties:
        stepIndex:
          type: integer
        stepType:
          type: string
        status:
          type: string
          enum: [SUCCESS, FAILURE, WARNING]
        message:
          type: string
        estimatedOutput:
          type: object

    SlippageAnalysis:
      type: object
      properties:
        expectedSlippage:
          type: number
          description: Expected slippage percentage
        riskLevel:
          type: string
          enum: [LOW, MEDIUM, HIGH]
        liquidityDepth:
          type: number

    LiquidityCheck:
      type: object
      properties:
        sufficient:
          type: boolean
        poolDepth:
          type: number
        warnings:
          type: array
          items:
            type: string

    ExecutionResponse:
      type: object
      properties:
        planId:
          type: string
          format: uuid
        executionId:
          type: string
          format: uuid
        status:
          type: string
          enum: [PENDING, IN_PROGRESS, COMPLETE, FAILED, ABORTED]
        estimatedDuration:
          type: integer
          description: Estimated duration in seconds

    ExecutionStatus:
      type: object
      properties:
        planId:
          type: string
          format: uuid
        status:
          type: string
          enum: [PENDING, IN_PROGRESS, COMPLETE, FAILED, ABORTED]
        currentPhase:
          type: string
          enum: [PREPARE, EXECUTE_DLT, BANK_INSTRUCTION, COMMIT]
        phases:
          type: array
          items:
            $ref: '#/components/schemas/PhaseStatus'
        dltTxHash:
          type: string
          nullable: true
        isoMessageId:
          type: string
          nullable: true
        error:
          type: string
          nullable: true

    PhaseStatus:
      type: object
      properties:
        phase:
          type: string
        status:
          type: string
          enum: [PENDING, IN_PROGRESS, COMPLETE, FAILED]
        timestamp:
          type: string
          format: date-time

    ComplianceStatus:
      type: object
      properties:
        userId:
          type: string
        lei:
          type: string
          nullable: true
        did:
          type: string
          nullable: true
        kyc:
          $ref: '#/components/schemas/KYCStatus'
        aml:
          $ref: '#/components/schemas/AMLStatus'
        valid:
          type: boolean

    KYCStatus:
      type: object
      properties:
        level:
          type: integer
        provider:
          type: string
        verified:
          type: boolean
        expiresAt:
          type: string
          format: date-time
          nullable: true

    AMLStatus:
      type: object
      properties:
        passed:
          type: boolean
        provider:
          type: string
        lastCheck:
          type: string
          format: date-time
        riskLevel:
          type: string
          enum: [LOW, MEDIUM, HIGH]

    WorkflowComplianceRequest:
      type: object
      required:
        - steps
      properties:
        steps:
          type: array
          items:
            $ref: '#/components/schemas/PlanStep'

    ComplianceCheckResult:
      type: object
      properties:
        valid:
          type: boolean
        required:
          type: array
          items:
            type: string
            enum: [LEI, DID, KYC, AML]
        missing:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string

    Adapter:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum: [DEFI, FIAT_DTL]
        description:
          type: string
        version:
          type: string
        whitelisted:
          type: boolean
        status:
          type: string
          enum: [APPROVED, DEPRECATED, RESTRICTED]
        protocol:
          type: string
          nullable: true
        chainIds:
          type: array
          items:
            type: integer

    NotaryRegistrationRequest:
      type: object
      required:
        - planId
        - planHash
      properties:
        planId:
          type: string
          format: uuid
        planHash:
          type: string
        participants:
          type: array
          items:
            type: string

    NotaryProof:
      type: object
      properties:
        planId:
          type: string
          format: uuid
        proofHash:
          type: string
        timestamp:
          type: string
          format: date-time
        notarySignature:
          type: string

    Receipts:
      type: object
      properties:
        planId:
          type: string
          format: uuid
        dltTransactions:
          type: array
          items:
            $ref: '#/components/schemas/DLTReceipt'
        isoMessages:
          type: array
          items:
            $ref: '#/components/schemas/ISOMessageReceipt'
        notaryProofs:
          type: array
          items:
            $ref: '#/components/schemas/NotaryProof'

    DLTReceipt:
      type: object
      properties:
        txHash:
          type: string
        chainId:
          type: integer
        blockNumber:
          type: integer
        timestamp:
          type: string
          format: date-time

    ISOMessageReceipt:
      type: object
      properties:
        messageId:
          type: string
        messageType:
          type: string
          enum: [pacs.008, pacs.009, camt.052, camt.053, camt.056]
        status:
          type: string
          enum: [PENDING, ACCEPTED, SETTLED, REJECTED]
        timestamp:
          type: string
          format: date-time

    ConnectorStatus:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [DLT, BANKING, COMPLIANCE, LIQUIDITY]
        status:
          type: string
          enum: [ONLINE, OFFLINE, DEGRADED]
        lastHealthCheck:
          type: string
          format: date-time

    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
        message:
          type: string
        code:
          type: string
        details:
          type: object

security:
  - bearerAuth: []

securitySchemes:
  bearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT
    description: JWT token from authentication service