content: {-# LANGUAGE DerivingVia #-}
  {-# LANGUAGE StrictData  #-}
  module Plutus.PAB.Events.Contract(
    -- $contract-events
    ContractInstanceId(..)
    , IterationID
    ) where
  
  import Plutus.Contract.Resumable (IterationID)
  
  import Wallet.Types (ContractInstanceId (..))
  
  -- $contract-events
  -- The events that compiled Plutus contracts are concerned with. For each type
  -- of event there is a request constructor in 'ContractRequest' and a response
  -- constructor in 'ContractResponse'.
  
  {- Note [Contract Events]
  
  Each contract instance has two event queues in the PAB: One for the requests
  it makes, typed 'ContractOutboxMessage', and one for the responses it receives,
  typed 'ContractInboxMessage'.
  
  -}
  
  {- Note [Contract Iterations]
  
  Contracts are executed iteratively:
  
  * We look at the current state of the contract to see which requests (hooks)
    it wants to make
  * We process one of those requests and feed the result to the contract
  * The contract produces a new state, which we again inspect to get the hooks
    that are currently active
  
  In each iteration we only feed one event to the contract, so if there is more
  than one hook then the other ones will be un-answered.  If the contract had
  been waiting for the first of several possible events, then the other hooks
  will disappear from the set of active hooks. But if it had been waiting for
  all of those events to happen then the remaining hooks will appear in the
  result, and we handle them in the next iteration.
  
  So each iteration begins with a set of requests from the contract and ends with
  one of those requests being handled.
  
  -}
  