openapi: 3.1.1
info:
  title: EnergyGift
  version: '2.0'
  description: Gift parameters for P2P energy gifting. Enables a prosumer (gifter) to make an energy offer
    available at 0 price on the catalog, discoverable by the SHA-256 hash of the recipient's phone number
    and claimable via a secret shared out-of-band from the gifter to the recipient.
components:
  schemas:
    EnergyGift:
      type: object
      additionalProperties: false
      required:
      - lookupHash
      - claimVerifier
      - expiresAt
      x-tags:
      - energy-trade
      - p2p-trading
      - gifting
      x-jsonld:
        '@context': ./context.jsonld
        '@type': EnergyGift
      properties:
        lookupHash:
          type: string
          pattern: ^[A-Fa-f0-9]{64}$
          description: 'SHA-256 hash of the recipient''s phone number (E.164 format, e.g. +919876543210).
            Used for privacy-preserving discovery — the catalog can be searched by this hash so that only
            the intended recipient finds the gift offer.

            '
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
          x-jsonld:
            '@id': lookupHash
        claimVerifier:
          type: string
          pattern: ^[A-Fa-f0-9]{64}$
          description: 'SHA-256 hash of a claim secret shared out-of-band from the gifter to the recipient.
            The recipient proves ownership by presenting the pre-image (the original secret) which is
            hashed and compared to this value during claim validation.

            '
          example: f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5
          x-jsonld:
            '@id': claimVerifier
        expiresAt:
          type: string
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
          description: 'Gift expiration timestamp in UTC (ISO 8601 with Z suffix). After this time the
            gift offer is no longer claimable and may be removed from the catalog.

            '
          example: '2025-07-01T00:00:00Z'
          x-jsonld:
            '@id': expiresAt