asyncapi: '2.6.0'
info:
  title: EventZR Blockchain Service Events
  version: 2.0.0
  description: |
    Kafka event interface for blockchain-svc.
    All events follow the CloudEvents 1.0 specification.
    Partition key: tenantId (except gas-price events which use chain_id).
  contact:
    name: EventZR Engineering
    email: engineering@eventzr.com
  license:
    name: PROPRIETARY

servers:
  staging:
    url: boot-gpm4u49z.c2.kafka-serverless.us-east-1.amazonaws.com:9098
    protocol: kafka-secure
    description: Amazon MSK Serverless (Staging)
  localhost:
    url: localhost:9092
    protocol: kafka
    description: Local development

defaultContentType: application/json

channels:
  # ========================================================================
  # PRODUCED EVENTS (blockchain-svc publishes)
  # ========================================================================

  # --- BlockchainEventsProducer (via @eventzr/kafka KafkaService) ---

  eventzr.blockchain.ticket.minted.v1:
    description: Published when an NFT ticket is minted on-chain after a ticket purchase.
    publish:
      operationId: publishTicketMinted
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/TicketMinted'

  eventzr.blockchain.ticket.transferred.v1:
    description: Published when NFT ticket ownership is transferred between wallet addresses.
    publish:
      operationId: publishTicketTransferred
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/TicketTransferred'

  eventzr.blockchain.ticket.validated.v1:
    description: Published when a ticket is validated at an event gate (QR scan or NFC tap).
    publish:
      operationId: publishTicketValidated
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/TicketValidated'

  eventzr.blockchain.ticket.revoked.v1:
    description: Published when a ticket is revoked by an organizer or admin (e.g. fraud, cancellation).
    publish:
      operationId: publishTicketRevoked
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/TicketRevoked'

  eventzr.blockchain.poap.minted.v1:
    description: Published when a Proof of Attendance Protocol (POAP) NFT is minted for an attendee.
    publish:
      operationId: publishPOAPMinted
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/POAPMinted'

  eventzr.blockchain.listing.created.v1:
    description: Published when a ticket holder creates a secondary-market resale listing.
    publish:
      operationId: publishListingCreated
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/ListingCreated'

  eventzr.blockchain.listing.sold.v1:
    description: Published when a resale listing is purchased by a buyer.
    publish:
      operationId: publishListingSold
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/ListingSold'

  eventzr.blockchain.revenue.distributed.v1:
    description: Published when revenue from ticket sales or resale royalties is distributed to stakeholders.
    publish:
      operationId: publishRevenueDistributed
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/RevenueDistributed'

  eventzr.blockchain.contract.deployed.v1:
    description: Published when a smart contract is deployed on-chain (via BlockchainEventsProducer).
    publish:
      operationId: publishContractDeployed
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/ContractDeployed'

  eventzr.blockchain.wristband.linked.v1:
    description: Published when a physical NFC wristband is linked to a ticket NFT.
    publish:
      operationId: publishWristbandLinked
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/WristbandLinked'

  eventzr.blockchain.wristband.tapped.v1:
    description: Published when a wristband NFC tap is processed at an event checkpoint.
    publish:
      operationId: publishWristbandTapped
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/WristbandTapped'

  eventzr.blockchain.gas.sponsored.v1:
    description: Published when a gas-sponsored (meta) transaction is executed on behalf of a user.
    publish:
      operationId: publishGasSponsored
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/GasSponsored'

  eventzr.blockchain.loyalty.tier_changed.v1:
    description: Published when a user's on-chain loyalty tier changes based on activity.
    publish:
      operationId: publishLoyaltyTierChanged
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/LoyaltyTierChanged'

  # --- ContractEventProducer (standalone KafkaJS producer) ---

  eventzr.blockchain.contract.events.v1:
    description: >
      Contract deployment events published by ContractEventProducer.
      Full CloudEvents envelope with detailed deployment metadata.
    publish:
      operationId: publishContractDeployedDetailed
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/ContractDeployedCloudEvent'

  # --- MintEventProducer (standalone KafkaJS producer) ---

  eventzr.blockchain.nft.events.v1:
    description: >
      NFT minting events published by MintEventProducer.
      Full CloudEvents envelope with batch-mint and recipient details.
    publish:
      operationId: publishNftMintedDetailed
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/NftMintedCloudEvent'

  # --- TransactionEventProducer ---

  eventzr.blockchain.transaction.events.v1:
    description: Published when a blockchain transaction is confirmed on-chain.
    publish:
      operationId: publishTransactionConfirmed
      bindings:
        kafka:
          key:
            type: string
            description: tenant_id
      message:
        $ref: '#/components/messages/TransactionConfirmedCloudEvent'

  # --- GasPriceEventProducer ---

  eventzr.blockchain.gas.updated.v1:
    description: Published periodically with updated gas price estimates per chain.
    publish:
      operationId: publishGasPriceUpdated
      bindings:
        kafka:
          key:
            type: string
            description: chain_id
      message:
        $ref: '#/components/messages/GasPriceUpdatedCloudEvent'

  # --- QuotaEventProducer ---

  eventzr.blockchain.quota.events.v1:
    description: Published when a user exceeds their blockchain operation quota for their subscription tier.
    publish:
      operationId: publishQuotaExceeded
      bindings:
        kafka:
          key:
            type: string
            description: tenantId
      message:
        $ref: '#/components/messages/QuotaExceededCloudEvent'

  # --- KGEventProducer (Neptune Knowledge Graph) ---

  eventzr.kg.blockchain:
    description: >
      Knowledge Graph events for Neptune ingestion.
      Creates/updates entity nodes and relationships in the graph.
    publish:
      operationId: publishKGEvent
      bindings:
        kafka:
          key:
            type: string
            description: tenant_id
      message:
        oneOf:
          - $ref: '#/components/messages/KGContractCreated'
          - $ref: '#/components/messages/KGNftMinted'
          - $ref: '#/components/messages/KGOwnershipChanged'

  # ========================================================================
  # CONSUMED EVENTS (blockchain-svc subscribes)
  # ========================================================================

  ticketing-events:
    description: >
      Events from ticketing-svc. Triggers NFT minting on ticket purchase,
      batch minting on bulk purchase, and burn on cancellation.
    subscribe:
      operationId: consumeTicketingEvents
      bindings:
        kafka:
          groupId: blockchain-svc-ticketing-consumer
      message:
        oneOf:
          - $ref: '#/components/messages/TicketPurchased'
          - $ref: '#/components/messages/TicketBatchPurchased'
          - $ref: '#/components/messages/TicketReserved'
          - $ref: '#/components/messages/TicketCancelled'

  user-events:
    description: >
      Events from user-svc. Handles tier upgrades/downgrades which affect
      blockchain quota limits and feature access.
    subscribe:
      operationId: consumeUserEvents
      bindings:
        kafka:
          groupId: blockchain-svc-user-consumer
      message:
        oneOf:
          - $ref: '#/components/messages/UserTierUpgraded'
          - $ref: '#/components/messages/UserTierDowngraded'

  billing-events:
    description: >
      Events from billing/subscriptions services. Handles subscription
      renewals (quota resets), expirations, and quota reset cycles.
      Consumed by the same consumer group as user-events.
    subscribe:
      operationId: consumeBillingEvents
      bindings:
        kafka:
          groupId: blockchain-svc-user-consumer
      message:
        oneOf:
          - $ref: '#/components/messages/SubscriptionRenewed'
          - $ref: '#/components/messages/SubscriptionExpired'
          - $ref: '#/components/messages/QuotaReset'

  wallet-events:
    description: >
      Events from wallet-svc. Syncs wallet address mappings, tracks
      balance updates, and records transaction confirmations.
    subscribe:
      operationId: consumeWalletEvents
      bindings:
        kafka:
          groupId: blockchain-svc-wallet-consumer
      message:
        oneOf:
          - $ref: '#/components/messages/WalletCreated'
          - $ref: '#/components/messages/WalletImported'
          - $ref: '#/components/messages/WalletBalanceUpdated'
          - $ref: '#/components/messages/WalletTransactionConfirmed'

components:
  messages:
    # ====================================================================
    # PRODUCED MESSAGES
    # ====================================================================

    TicketMinted:
      name: TicketMinted
      title: NFT Ticket Minted
      contentType: application/json
      headers:
        type: object
        properties:
          tenant-id:
            type: string
            format: uuid
      payload:
        $ref: '#/components/schemas/TicketMintedPayload'

    TicketTransferred:
      name: TicketTransferred
      title: NFT Ticket Transferred
      contentType: application/json
      headers:
        type: object
        properties:
          tenant-id:
            type: string
            format: uuid
      payload:
        $ref: '#/components/schemas/TicketTransferredPayload'

    TicketValidated:
      name: TicketValidated
      title: Ticket Validated at Gate
      contentType: application/json
      headers:
        type: object
        properties:
          tenant-id:
            type: string
            format: uuid
      payload:
        $ref: '#/components/schemas/TicketValidatedPayload'

    TicketRevoked:
      name: TicketRevoked
      title: Ticket Revoked
      contentType: application/json
      headers:
        type: object
        properties:
          tenant-id:
            type: string
            format: uuid
      payload:
        $ref: '#/components/schemas/TicketRevokedPayload'

    POAPMinted:
      name: POAPMinted
      title: POAP Minted
      contentType: application/json
      headers:
        type: object
        properties:
          tenant-id:
            type: string
            format: uuid
      payload:
        $ref: '#/components/schemas/POAPMintedPayload'

    ListingCreated:
      name: ListingCreated
      title: Resale Listing Created
      contentType: application/json
      headers:
        type: object
        properties:
          tenant-id:
            type: string
            format: uuid
      payload:
        $ref: '#/components/schemas/ListingCreatedPayload'

    ListingSold:
      name: ListingSold
      title: Resale Listing Sold
      contentType: application/json
      headers:
        type: object
        properties:
          tenant-id:
            type: string
            format: uuid
      payload:
        $ref: '#/components/schemas/ListingSoldPayload'

    RevenueDistributed:
      name: RevenueDistributed
      title: Revenue Distributed
      contentType: application/json
      headers:
        type: object
        properties:
          tenant-id:
            type: string
            format: uuid
      payload:
        $ref: '#/components/schemas/RevenueDistributedPayload'

    ContractDeployed:
      name: ContractDeployed
      title: Smart Contract Deployed
      contentType: application/json
      headers:
        type: object
        properties:
          tenant-id:
            type: string
            format: uuid
      payload:
        $ref: '#/components/schemas/ContractDeployedPayload'

    WristbandLinked:
      name: WristbandLinked
      title: Wristband Linked to Ticket
      contentType: application/json
      headers:
        type: object
        properties:
          tenant-id:
            type: string
            format: uuid
      payload:
        $ref: '#/components/schemas/WristbandLinkedPayload'

    WristbandTapped:
      name: WristbandTapped
      title: Wristband NFC Tap Processed
      contentType: application/json
      headers:
        type: object
        properties:
          tenant-id:
            type: string
            format: uuid
      payload:
        $ref: '#/components/schemas/WristbandTappedPayload'

    GasSponsored:
      name: GasSponsored
      title: Gas-Sponsored Transaction Executed
      contentType: application/json
      headers:
        type: object
        properties:
          tenant-id:
            type: string
            format: uuid
      payload:
        $ref: '#/components/schemas/GasSponsoredPayload'

    LoyaltyTierChanged:
      name: LoyaltyTierChanged
      title: Loyalty Tier Changed
      contentType: application/json
      headers:
        type: object
        properties:
          tenant-id:
            type: string
            format: uuid
      payload:
        $ref: '#/components/schemas/LoyaltyTierChangedPayload'

    ContractDeployedCloudEvent:
      name: ContractDeployedCloudEvent
      title: Contract Deployed (detailed, via ContractEventProducer)
      contentType: application/json
      headers:
        type: object
        properties:
          ce-specversion:
            type: string
            const: '1.0'
          ce-type:
            type: string
            const: com.eventzr.blockchain.contract.deployed
          ce-source:
            type: string
            const: blockchain-svc
          ce-id:
            type: string
          ce-time:
            type: string
            format: date-time
          content-type:
            type: string
            const: application/json
      payload:
        $ref: '#/components/schemas/ContractDeployedDetailedEvent'

    NftMintedCloudEvent:
      name: NftMintedCloudEvent
      title: NFT Minted (detailed, via MintEventProducer)
      contentType: application/json
      headers:
        type: object
        properties:
          ce-specversion:
            type: string
            const: '1.0'
          ce-type:
            type: string
            const: com.eventzr.blockchain.nft.minted
          ce-source:
            type: string
            const: blockchain-svc
          ce-id:
            type: string
          ce-time:
            type: string
            format: date-time
          content-type:
            type: string
            const: application/json
      payload:
        $ref: '#/components/schemas/NftMintedDetailedEvent'

    TransactionConfirmedCloudEvent:
      name: TransactionConfirmedCloudEvent
      title: Transaction Confirmed
      contentType: application/json
      headers:
        type: object
        properties:
          ce-specversion:
            type: string
            const: '1.0'
          ce-type:
            type: string
            const: com.eventzr.blockchain.transaction.confirmed
          ce-source:
            type: string
            const: blockchain-svc
          ce-id:
            type: string
          ce-time:
            type: string
            format: date-time
          content-type:
            type: string
            const: application/json
      payload:
        $ref: '#/components/schemas/TransactionConfirmedDetailedEvent'

    GasPriceUpdatedCloudEvent:
      name: GasPriceUpdatedCloudEvent
      title: Gas Price Updated
      contentType: application/json
      headers:
        type: object
        properties:
          ce-specversion:
            type: string
            const: '1.0'
          ce-type:
            type: string
            const: com.eventzr.blockchain.gasprice.updated
          ce-source:
            type: string
            const: blockchain-svc
          ce-id:
            type: string
          ce-time:
            type: string
            format: date-time
          content-type:
            type: string
            const: application/json
      payload:
        $ref: '#/components/schemas/GasPriceUpdatedDetailedEvent'

    QuotaExceededCloudEvent:
      name: QuotaExceededCloudEvent
      title: Quota Exceeded
      contentType: application/json
      headers:
        type: object
        properties:
          ce-specversion:
            type: string
            const: '1.0'
          ce-type:
            type: string
            const: com.eventzr.blockchain.quota.exceeded
          ce-source:
            type: string
            const: blockchain-svc
          ce-id:
            type: string
          ce-time:
            type: string
            format: date-time
          content-type:
            type: string
            const: application/json
      payload:
        $ref: '#/components/schemas/QuotaExceededDetailedEvent'

    KGContractCreated:
      name: KGContractCreated
      title: KG Contract Created (Neptune)
      contentType: application/json
      payload:
        $ref: '#/components/schemas/KGCloudEvent'

    KGNftMinted:
      name: KGNftMinted
      title: KG NFT Minted (Neptune)
      contentType: application/json
      payload:
        $ref: '#/components/schemas/KGCloudEvent'

    KGOwnershipChanged:
      name: KGOwnershipChanged
      title: KG Ownership Changed (Neptune)
      contentType: application/json
      payload:
        $ref: '#/components/schemas/KGCloudEvent'

    # ====================================================================
    # CONSUMED MESSAGES
    # ====================================================================

    TicketPurchased:
      name: TicketPurchased
      title: Ticket Purchased (from ticketing-svc)
      description: Triggers single NFT mint for the purchased ticket.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/TicketPurchasedEvent'

    TicketBatchPurchased:
      name: TicketBatchPurchased
      title: Batch Ticket Purchased (from ticketing-svc)
      description: Triggers batch NFT mint for multiple tickets.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/TicketBatchPurchasedEvent'

    TicketReserved:
      name: TicketReserved
      title: Ticket Reserved (from ticketing-svc)
      description: Optionally pre-mints NFT for a reserved ticket.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/TicketReservedEvent'

    TicketCancelled:
      name: TicketCancelled
      title: Ticket Cancelled (from ticketing-svc)
      description: Triggers NFT burn if ticket was already minted.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/TicketCancelledEvent'

    UserTierUpgraded:
      name: UserTierUpgraded
      title: User Tier Upgraded (from user-svc)
      description: Resets quotas to new tier limits and unlocks tier features.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/UserTierUpgradedEvent'

    UserTierDowngraded:
      name: UserTierDowngraded
      title: User Tier Downgraded (from user-svc)
      description: Enforces lower tier limits and disables gated features.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/UserTierDowngradedEvent'

    SubscriptionRenewed:
      name: SubscriptionRenewed
      title: Subscription Renewed (from billing-svc)
      description: Resets monthly blockchain operation quotas.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SubscriptionRenewedEvent'

    SubscriptionExpired:
      name: SubscriptionExpired
      title: Subscription Expired (from billing-svc)
      description: Marks subscription as expired; disables API access after grace period.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SubscriptionExpiredEvent'

    QuotaReset:
      name: QuotaReset
      title: Quota Reset (from user-svc)
      description: Resets monthly or daily blockchain operation quotas.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/QuotaResetEvent'

    WalletCreated:
      name: WalletCreated
      title: Wallet Created (from wallet-svc)
      description: Creates a wallet-to-user mapping in blockchain-svc database.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/WalletCreatedEvent'

    WalletImported:
      name: WalletImported
      title: Wallet Imported (from wallet-svc)
      description: Registers an imported external wallet for blockchain operations.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/WalletImportedEvent'

    WalletBalanceUpdated:
      name: WalletBalanceUpdated
      title: Wallet Balance Updated (from wallet-svc)
      description: Updates cached balance; triggers low-balance alerts.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/WalletBalanceUpdatedEvent'

    WalletTransactionConfirmed:
      name: WalletTransactionConfirmed
      title: Wallet Transaction Confirmed (from wallet-svc)
      description: Records external transaction confirmations and gas costs.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/WalletTransactionConfirmedEvent'

  schemas:
    # ====================================================================
    # PRODUCED SCHEMAS
    # ====================================================================

    # --- CloudEvents base (reused via allOf) ---

    CloudEventsEnvelope:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
        source:
          type: string
          const: blockchain-svc
        id:
          type: string
          description: Unique event identifier (UUID)
        time:
          type: string
          format: date-time

    # --- BlockchainEventsProducer payloads ---

    TicketMintedPayload:
      allOf:
        - $ref: '#/components/schemas/CloudEventsEnvelope'
        - type: object
          properties:
            type:
              const: com.eventzr.blockchain.ticket.minted
            data:
              type: object
              required:
                - ticketId
                - tenantId
                - eventId
                - ticketType
                - ownerAddress
              properties:
                ticketId:
                  type: string
                  format: uuid
                tenantId:
                  type: string
                  format: uuid
                eventId:
                  type: string
                  format: uuid
                ticketType:
                  type: string
                  description: 'e.g. general_admission, vip, backstage'
                ownerAddress:
                  type: string
                  description: Ethereum/EVM wallet address of the ticket owner

    TicketTransferredPayload:
      allOf:
        - $ref: '#/components/schemas/CloudEventsEnvelope'
        - type: object
          properties:
            type:
              const: com.eventzr.blockchain.ticket.transferred
            data:
              type: object
              required:
                - ticketId
                - tenantId
                - fromAddress
                - toAddress
                - transferCount
              properties:
                ticketId:
                  type: string
                  format: uuid
                tenantId:
                  type: string
                  format: uuid
                fromAddress:
                  type: string
                  description: Previous owner wallet address
                toAddress:
                  type: string
                  description: New owner wallet address
                transferCount:
                  type: integer
                  description: Total number of transfers for this ticket

    TicketValidatedPayload:
      allOf:
        - $ref: '#/components/schemas/CloudEventsEnvelope'
        - type: object
          properties:
            type:
              const: com.eventzr.blockchain.ticket.validated
            data:
              type: object
              required:
                - ticketId
                - tenantId
                - eventId
                - valid
                - validationType
              properties:
                ticketId:
                  type: string
                  format: uuid
                tenantId:
                  type: string
                  format: uuid
                eventId:
                  type: string
                  format: uuid
                valid:
                  type: boolean
                  description: Whether the ticket passed validation
                validationType:
                  type: string
                  description: 'Validation method (e.g. qr_scan, nfc_tap, manual)'

    TicketRevokedPayload:
      allOf:
        - $ref: '#/components/schemas/CloudEventsEnvelope'
        - type: object
          properties:
            type:
              const: com.eventzr.blockchain.ticket.revoked
            data:
              type: object
              required:
                - ticketId
                - tenantId
                - reason
                - revokedBy
              properties:
                ticketId:
                  type: string
                  format: uuid
                tenantId:
                  type: string
                  format: uuid
                reason:
                  type: string
                  description: Reason for revocation
                revokedBy:
                  type: string
                  description: User ID or system identifier that performed the revocation

    POAPMintedPayload:
      allOf:
        - $ref: '#/components/schemas/CloudEventsEnvelope'
        - type: object
          properties:
            type:
              const: com.eventzr.blockchain.poap.minted
            data:
              type: object
              required:
                - poapId
                - tenantId
                - userId
                - eventId
                - loyaltyPointsEarned
              properties:
                poapId:
                  type: string
                  format: uuid
                tenantId:
                  type: string
                  format: uuid
                userId:
                  type: string
                  format: uuid
                eventId:
                  type: string
                  format: uuid
                loyaltyPointsEarned:
                  type: integer
                  description: Loyalty points awarded for attendance

    ListingCreatedPayload:
      allOf:
        - $ref: '#/components/schemas/CloudEventsEnvelope'
        - type: object
          properties:
            type:
              const: com.eventzr.blockchain.listing.created
            data:
              type: object
              required:
                - listingId
                - tenantId
                - ticketId
                - price
              properties:
                listingId:
                  type: string
                  format: uuid
                tenantId:
                  type: string
                  format: uuid
                ticketId:
                  type: string
                  format: uuid
                price:
                  type: string
                  description: Listing price in native token (wei/gwei string)

    ListingSoldPayload:
      allOf:
        - $ref: '#/components/schemas/CloudEventsEnvelope'
        - type: object
          properties:
            type:
              const: com.eventzr.blockchain.listing.sold
            data:
              type: object
              required:
                - listingId
                - tenantId
                - buyerAddress
                - salePrice
              properties:
                listingId:
                  type: string
                  format: uuid
                tenantId:
                  type: string
                  format: uuid
                buyerAddress:
                  type: string
                  description: Buyer wallet address
                salePrice:
                  type: string
                  description: Final sale price in native token

    RevenueDistributedPayload:
      allOf:
        - $ref: '#/components/schemas/CloudEventsEnvelope'
        - type: object
          properties:
            type:
              const: com.eventzr.blockchain.revenue.distributed
            data:
              type: object
              required:
                - configId
                - tenantId
                - eventId
                - amount
                - distributionCount
              properties:
                configId:
                  type: string
                  format: uuid
                  description: Revenue share configuration ID
                tenantId:
                  type: string
                  format: uuid
                eventId:
                  type: string
                  format: uuid
                amount:
                  type: string
                  description: Total amount distributed
                distributionCount:
                  type: integer
                  description: Number of stakeholders that received a share

    ContractDeployedPayload:
      allOf:
        - $ref: '#/components/schemas/CloudEventsEnvelope'
        - type: object
          properties:
            type:
              const: com.eventzr.blockchain.contract.deployed
            data:
              type: object
              required:
                - contractId
                - tenantId
              properties:
                contractId:
                  type: string
                  format: uuid
                tenantId:
                  type: string
                  format: uuid

    WristbandLinkedPayload:
      allOf:
        - $ref: '#/components/schemas/CloudEventsEnvelope'
        - type: object
          properties:
            type:
              const: com.eventzr.blockchain.wristband.linked
            data:
              type: object
              required:
                - wristbandId
                - tenantId
              properties:
                wristbandId:
                  type: string
                  format: uuid
                tenantId:
                  type: string
                  format: uuid

    WristbandTappedPayload:
      allOf:
        - $ref: '#/components/schemas/CloudEventsEnvelope'
        - type: object
          properties:
            type:
              const: com.eventzr.blockchain.wristband.tapped
            data:
              type: object
              required:
                - wristbandId
                - tenantId
              properties:
                wristbandId:
                  type: string
                  format: uuid
                tenantId:
                  type: string
                  format: uuid

    GasSponsoredPayload:
      allOf:
        - $ref: '#/components/schemas/CloudEventsEnvelope'
        - type: object
          properties:
            type:
              const: com.eventzr.blockchain.gas.sponsored
            data:
              type: object
              required:
                - sponsorshipId
                - tenantId
              properties:
                sponsorshipId:
                  type: string
                  format: uuid
                tenantId:
                  type: string
                  format: uuid

    LoyaltyTierChangedPayload:
      allOf:
        - $ref: '#/components/schemas/CloudEventsEnvelope'
        - type: object
          properties:
            type:
              const: com.eventzr.blockchain.loyalty.tier_changed
            data:
              type: object
              required:
                - userId
                - tenantId
              properties:
                userId:
                  type: string
                  format: uuid
                tenantId:
                  type: string
                  format: uuid

    # --- Detailed CloudEvents (standalone producers with full schemas) ---

    ContractDeployedDetailedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: com.eventzr.blockchain.contract.deployed
        source:
          type: string
          const: blockchain-svc
        id:
          type: string
          format: uuid
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          const: application/json
        data:
          type: object
          required:
            - tenantId
            - contract_id
            - contract_address
            - contract_type
            - chain_id
            - deployment_tx_hash
            - deployer_address
            - deployed_by_user_id
            - deployment_gas_used
            - deployment_gas_cost_eth
            - deployment_gas_cost_usd
            - contract_name
            - contract_symbol
            - deployed_at
          properties:
            tenantId:
              type: string
              format: uuid
            contract_id:
              type: string
              format: uuid
            contract_address:
              type: string
              description: On-chain contract address (0x...)
            contract_type:
              type: string
              description: 'e.g. ERC721, ERC1155, ERC20'
            chain_id:
              type: string
              description: 'Chain identifier (e.g. 1, 137, 42161)'
            deployment_tx_hash:
              type: string
              description: Deployment transaction hash
            deployer_address:
              type: string
              description: Deployer wallet address
            deployed_by_user_id:
              type: string
              format: uuid
            deployment_gas_used:
              type: string
            deployment_gas_cost_eth:
              type: string
            deployment_gas_cost_usd:
              type: string
            contract_name:
              type: string
            contract_symbol:
              type: string
            royalty_recipient:
              type: string
              nullable: true
            royalty_basis_points:
              type: integer
              nullable: true
            max_supply:
              type: integer
              nullable: true
            deployed_at:
              type: string
              format: date-time

    NftMintedDetailedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: com.eventzr.blockchain.nft.minted
        source:
          type: string
          const: blockchain-svc
        id:
          type: string
          format: uuid
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          const: application/json
        data:
          type: object
          required:
            - tenantId
            - mint_request_id
            - contract_id
            - contract_address
            - contract_type
            - chain_id
            - tx_hash
            - minted_by_user_id
            - total_minted
            - recipients
            - is_batch_mint
            - is_ai_generated
            - is_gas_sponsored
            - gas_cost_eth
            - gas_cost_usd
            - user_payment_usd
            - idempotency_key
            - minted_at
          properties:
            tenantId:
              type: string
              format: uuid
            mint_request_id:
              type: string
              format: uuid
            contract_id:
              type: string
              format: uuid
            contract_address:
              type: string
            contract_type:
              type: string
            chain_id:
              type: string
            tx_hash:
              type: string
            minted_by_user_id:
              type: string
              format: uuid
            total_minted:
              type: integer
            recipients:
              type: array
              items:
                type: object
                required:
                  - recipient
                  - quantity
                properties:
                  recipient:
                    type: string
                    description: Recipient wallet address or user ID
                  quantity:
                    type: integer
                  token_ids:
                    type: array
                    items:
                      type: string
            is_batch_mint:
              type: boolean
            is_ai_generated:
              type: boolean
            is_gas_sponsored:
              type: boolean
            gas_cost_eth:
              type: string
            gas_cost_usd:
              type: string
            user_payment_usd:
              type: string
            transfer_policy:
              type: string
              nullable: true
              description: 'e.g. transferable, non_transferable, one_transfer'
            idempotency_key:
              type: string
            minted_at:
              type: string
              format: date-time

    TransactionConfirmedDetailedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: com.eventzr.blockchain.transaction.confirmed
        source:
          type: string
          const: blockchain-svc
        id:
          type: string
          format: uuid
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          const: application/json
        data:
          type: object
          required:
            - tenant_id
            - transaction_id
            - tx_hash
            - chain_id
            - operation_type
            - from_address
            - to_address
            - block_number
            - confirmations
            - gas_used
            - gas_price
            - value
            - status
            - confirmed_at
          properties:
            tenant_id:
              type: string
              format: uuid
            transaction_id:
              type: string
              format: uuid
            tx_hash:
              type: string
            chain_id:
              type: string
            operation_type:
              type: string
              description: 'e.g. mint, transfer, burn, deploy'
            from_address:
              type: string
            to_address:
              type: string
            block_number:
              type: integer
            confirmations:
              type: integer
            gas_used:
              type: string
            gas_price:
              type: string
            value:
              type: string
              description: Transaction value in wei
            status:
              type: string
              description: 'e.g. confirmed, reverted'
            confirmed_at:
              type: string
              format: date-time

    GasPriceUpdatedDetailedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: com.eventzr.blockchain.gasprice.updated
        source:
          type: string
          const: blockchain-svc
        id:
          type: string
          format: uuid
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          const: application/json
        data:
          type: object
          required:
            - chain_id
            - slow_gwei
            - standard_gwei
            - fast_gwei
            - slow_usd
            - standard_usd
            - fast_usd
            - eth_price_usd
            - updated_at
          properties:
            chain_id:
              type: string
            slow_gwei:
              type: string
            standard_gwei:
              type: string
            fast_gwei:
              type: string
            slow_usd:
              type: string
            standard_usd:
              type: string
            fast_usd:
              type: string
            eth_price_usd:
              type: string
            base_fee_gwei:
              type: string
              nullable: true
              description: EIP-1559 base fee (null for non-EIP-1559 chains)
            priority_fee_gwei:
              type: string
              nullable: true
              description: EIP-1559 priority fee (null for non-EIP-1559 chains)
            updated_at:
              type: string
              format: date-time

    QuotaExceededDetailedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: com.eventzr.blockchain.quota.exceeded
        source:
          type: string
          const: blockchain-svc
        id:
          type: string
          format: uuid
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          const: application/json
        data:
          type: object
          required:
            - tenantId
            - user_id
            - subscription_tier
            - quota_type
            - current_usage
            - limit
            - requested_amount
            - reset_at
            - operation_type
            - exceeded_at
          properties:
            tenantId:
              type: string
              format: uuid
            user_id:
              type: string
              format: uuid
            subscription_tier:
              type: string
              description: 'e.g. BASE, STUDENT, STARTUP, PRO, PROMAX, ENTERPRISE, CUSTOM'
            quota_type:
              type: string
              description: 'e.g. NFT_MINTS_MONTHLY, NFT_MINTS_DAILY, CUSTOM_CONTRACTS'
            current_usage:
              type: integer
            limit:
              type: integer
            requested_amount:
              type: integer
            reset_at:
              type: string
              format: date-time
              description: When the quota resets
            recommended_tier:
              type: string
              nullable: true
              description: Suggested upgrade tier
            operation_type:
              type: string
              description: The operation that was blocked
            exceeded_at:
              type: string
              format: date-time

    # --- KG (Knowledge Graph / Neptune) ---

    KGCloudEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          description: >
            One of: eventzr.kg.blockchain.contract.created.v1,
            eventzr.kg.blockchain.nft.minted.v1,
            eventzr.kg.blockchain.ownership.changed.v1
        source:
          type: string
          const: blockchain-svc
        id:
          type: string
          format: uuid
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          const: application/json
        data:
          $ref: '#/components/schemas/KGEventData'

    KGEventData:
      type: object
      required:
        - entity_type
        - entity_id
        - tenant_id
        - relationships
        - properties
        - timestamp
      properties:
        entity_type:
          type: string
          description: 'e.g. ContractDeployment, NftMetadata'
        entity_id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        relationships:
          type: array
          items:
            $ref: '#/components/schemas/KGRelationship'
        properties:
          type: object
          description: Entity-specific properties (contract_address, token_id, etc.)
        timestamp:
          type: string
          format: date-time

    KGRelationship:
      type: object
      required:
        - type
        - target_entity_type
        - target_entity_id
      properties:
        type:
          type: string
          description: >
            Relationship label, e.g. DEPLOYED_BY_USER, DEPLOYED_ON_CHAIN,
            DEPLOYED_BY_TEAM, MINTED_BY_USER, FROM_CONTRACT, OWNED_BY,
            NFT_FOR_EVENT, PREVIOUSLY_OWNED_BY
        target_entity_type:
          type: string
          description: 'Target node type: User, Team, Chain, ContractDeployment, Event'
        target_entity_id:
          type: string
          format: uuid
        properties:
          type: object
          description: Optional edge properties (e.g. tx_hash)

    # ====================================================================
    # CONSUMED SCHEMAS
    # ====================================================================

    # --- ticketing-events ---

    TicketPurchasedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: ticketing.ticket.purchased
        source:
          type: string
          const: ticketing-svc
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          const: application/json
        data:
          type: object
          required:
            - ticketId
            - eventId
            - userId
            - tier
            - chain
            - metadata
            - purchasedAt
          properties:
            tenantId:
              type: string
              format: uuid
            ticketId:
              type: string
              format: uuid
            eventId:
              type: string
              format: uuid
            userId:
              type: string
              format: uuid
            tier:
              type: string
              description: Subscription tier (BASE, STUDENT, STARTUP, PRO, PROMAX, ENTERPRISE, CUSTOM)
            chain:
              type: string
              description: 'Target chain ID (e.g. 1, 137, 42161)'
            contractAddress:
              type: string
              description: Optional pre-deployed contract address
            metadata:
              type: object
              properties:
                ticketType:
                  type: string
                seatNumber:
                  type: string
                section:
                  type: string
                row:
                  type: string
                eventName:
                  type: string
                eventDate:
                  type: string
                venue:
                  type: string
            purchasedAt:
              type: string
              format: date-time

    TicketBatchPurchasedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: ticketing.ticket.batch.purchased
        source:
          type: string
          const: ticketing-svc
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object
          required:
            - batchId
            - eventId
            - userId
            - tier
            - chain
            - tickets
            - purchasedAt
          properties:
            tenantId:
              type: string
              format: uuid
            batchId:
              type: string
              format: uuid
            eventId:
              type: string
              format: uuid
            userId:
              type: string
              format: uuid
            tier:
              type: string
            chain:
              type: string
            contractAddress:
              type: string
            tickets:
              type: array
              items:
                type: object
                required:
                  - ticketId
                  - metadata
                properties:
                  ticketId:
                    type: string
                    format: uuid
                  metadata:
                    type: object
            purchasedAt:
              type: string
              format: date-time

    TicketReservedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: ticketing.ticket.reserved
        source:
          type: string
          const: ticketing-svc
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object
          required:
            - ticketId
            - eventId
            - userId
          properties:
            tenantId:
              type: string
              format: uuid
            ticketId:
              type: string
              format: uuid
            eventId:
              type: string
              format: uuid
            userId:
              type: string
              format: uuid
            tier:
              type: string
            chain:
              type: string

    TicketCancelledEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: ticketing.ticket.cancelled
        source:
          type: string
          const: ticketing-svc
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object
          required:
            - ticketId
          properties:
            tenantId:
              type: string
              format: uuid
            ticketId:
              type: string
              format: uuid
            eventId:
              type: string
              format: uuid
            reason:
              type: string

    # --- user-events ---

    UserTierUpgradedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: user.tier.upgraded
        source:
          type: string
          const: user-svc
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object
          required:
            - userId
            - tenantId
            - previousTier
            - newTier
            - effectiveDate
            - upgradedAt
          properties:
            userId:
              type: string
              format: uuid
            tenantId:
              type: string
              format: uuid
            email:
              type: string
              format: email
            previousTier:
              type: string
              description: 'e.g. BASE, STUDENT, STARTUP, PRO, PROMAX, ENTERPRISE, CUSTOM'
            newTier:
              type: string
            effectiveDate:
              type: string
              format: date-time
            upgradedAt:
              type: string
              format: date-time

    UserTierDowngradedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: user.tier.downgraded
        source:
          type: string
          const: user-svc
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object
          required:
            - userId
            - tenantId
            - previousTier
            - newTier
            - effectiveDate
            - downgradedAt
          properties:
            userId:
              type: string
              format: uuid
            tenantId:
              type: string
              format: uuid
            email:
              type: string
              format: email
            previousTier:
              type: string
            newTier:
              type: string
            effectiveDate:
              type: string
              format: date-time
            downgradedAt:
              type: string
              format: date-time
            reason:
              type: string

    # --- billing-events ---

    SubscriptionRenewedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: user.subscription.renewed
        source:
          type: string
          const: billing-svc
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object
          required:
            - userId
            - tenantId
            - tier
            - renewedAt
            - nextBillingDate
          properties:
            userId:
              type: string
              format: uuid
            tenantId:
              type: string
              format: uuid
            tier:
              type: string
            renewedAt:
              type: string
              format: date-time
            nextBillingDate:
              type: string
              format: date-time

    SubscriptionExpiredEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: user.subscription.expired
        source:
          type: string
          const: billing-svc
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object
          required:
            - userId
            - tenantId
            - tier
            - expiredAt
          properties:
            userId:
              type: string
              format: uuid
            tenantId:
              type: string
              format: uuid
            tier:
              type: string
            expiredAt:
              type: string
              format: date-time
            gracePeriodEnds:
              type: string
              format: date-time
              description: If set, API access remains until this date

    QuotaResetEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: user.quota.reset
        source:
          type: string
          const: user-svc
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object
          required:
            - userId
            - tenantId
            - tier
            - quotaType
            - resetAt
          properties:
            userId:
              type: string
              format: uuid
            tenantId:
              type: string
              format: uuid
            tier:
              type: string
            quotaType:
              type: string
              enum:
                - monthly
                - daily
            resetAt:
              type: string
              format: date-time

    # --- wallet-events ---

    WalletCreatedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: wallet.created
        source:
          type: string
          const: wallet-svc
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object
          required:
            - walletAddress
            - userId
            - chain
          properties:
            walletAddress:
              type: string
              description: Blockchain wallet address (0x...)
            userId:
              type: string
              format: uuid
            chain:
              type: string
              description: 'Chain ID (e.g. 1, 137, 42161)'
            walletType:
              type: string
              description: 'e.g. eoa, smart_wallet, multisig'
            createdAt:
              type: string
              format: date-time

    WalletImportedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: wallet.imported
        source:
          type: string
          const: wallet-svc
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object
          required:
            - walletAddress
            - userId
            - chain
          properties:
            walletAddress:
              type: string
            userId:
              type: string
              format: uuid
            chain:
              type: string
            chains:
              type: array
              items:
                type: string
              description: Multiple chains if wallet is multi-chain
            importedAt:
              type: string
              format: date-time

    WalletBalanceUpdatedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: wallet.balance.updated
        source:
          type: string
          const: wallet-svc
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object
          required:
            - walletAddress
            - userId
            - chain
            - balance
          properties:
            walletAddress:
              type: string
            userId:
              type: string
              format: uuid
            chain:
              type: string
            balance:
              type: string
              description: Token balance (wei string)
            nativeBalance:
              type: string
              description: Native token balance (ETH/MATIC/etc.)
            nativeBalanceUSD:
              type: string
              description: Native balance in USD
            tokenAddress:
              type: string
              description: ERC-20 token contract address (null for native)
            updatedAt:
              type: string
              format: date-time

    WalletTransactionConfirmedEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - data
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          const: wallet.transaction.confirmed
        source:
          type: string
          const: wallet-svc
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object
          required:
            - walletAddress
            - userId
            - chain
            - txHash
            - status
          properties:
            walletAddress:
              type: string
            userId:
              type: string
              format: uuid
            chain:
              type: string
            txHash:
              type: string
            transactionHash:
              type: string
              description: Alternative field name for txHash
            status:
              type: string
              description: 'e.g. confirmed, failed'
            gasCostUSD:
              type: number
              description: Gas cost in USD
            confirmedAt:
              type: string
              format: date-time
