Rename QueryHandle and QueryBackend to Provider variants

CHANGELOG.md

@@ -91,6 +91,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ### Changed
 
 - `cardano-serialization-lib` has been updated to `v13.2.0` ([#1656](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1656))
+- `QueryHandle` has been renamed to `Provider`
+  - `QueryBackend` renamed to `ProviderBackend`
+  - `QueryBackendParams` renamed to `ProviderBackendParams`
+  - `queryHandleFor*Backend` renamed to `providerFor*Backend`
+  - `getQueryHandle` renamed to `getProvider`
+  - `mkQueryHandle` renamed to `mkProvider`
+  - Also multiple corresponding file names have changed replacing the `QueryHandle` names to `Provider` ones
 
 ### Fixed
 

doc/blockfrost.md

@@ -132,7 +132,7 @@ See [this example](../test/Blockfrost/Contract.purs), which can be executed with
 
 On production, the environment should be configured on PureScript side (environment variables are not respected).
 
-`mkBlockfrostBackendParams` can be called on a populated `BlockfrostBackendParams` record to create a `QueryBackendParams` value. `backendParams` field of `ContractParams` uses a value of this type. And `ContractParams` can in turn be used with `runContract`.
+`mkBlockfrostBackendParams` can be called on a populated `BlockfrostBackendParams` record to create a `ProviderBackendParams` value. `backendParams` field of `ContractParams` uses a value of this type. And `ContractParams` can in turn be used with `runContract`.
 
 ```purescript
 type BlockfrostBackendParams =

doc/comparisons.md

@@ -45,7 +45,7 @@ For a more in-depth explanation of the differences between PAB and CTL (with cod
 
 ### Query layer differences
 
-Lucid uses a [`Provider` class](https://deno.land/x/[email protected]/mod.ts?s=Provider) that defines all available queries. CTL query methods are defined in [`QueryHandle`](https://github.com/Plutonomicon/cardano-transaction-lib/blob/develop/src/Internal/Contract/QueryHandle/Type.purs#L36).
+Lucid uses a [`Provider` class](https://deno.land/x/[email protected]/mod.ts?s=Provider) that defines all available queries. CTL query methods are defined in [`Provider`](https://github.com/Plutonomicon/cardano-transaction-lib/blob/develop/src/Internal/Contract/Provider/Type.purs#L36).
 
 CTL supports the following queries that Lucid does not:
 
@@ -63,7 +63,7 @@ Lucid, on the other hand, provides a way to get a UTxO that contains a specified
 
 - Both CTL and Lucid support [Blockfrost](./blockfrost.md) and [Kupo+Ogmios](./runtime.md)
 - Lucid also supports [Maestro](https://www.gomaestro.org/)
-- Both CTL and Lucid allow for custom backends - Lucid via `Provider` interface implementation, and CTL via a custom `QueryHandle`.
+- Both CTL and Lucid allow for custom backends - Lucid via `Provider` interface implementation, and CTL via a custom `Provider`.
 
 ### Staking support
 

doc/custom-query-layers.md

@@ -16,15 +16,15 @@
 
 CTL can be extended with custom (user) query layers if needed. At this moment it can be done by forking.
 
-Every query CTL uses, except of backend-specific ones, goes through a [query handle](https://github.com/Plutonomicon/cardano-transaction-lib/blob/10a88faa2e6237aafc90568e3488f3421517af63/src/Internal/Contract/QueryHandle/Type.purs#L36).
+Every query CTL uses, except of backend-specific ones, goes through a [query handle](https://github.com/Plutonomicon/cardano-transaction-lib/blob/10a88faa2e6237aafc90568e3488f3421517af63/src/Internal/Contract/Provider/Type.purs#L36).
 
-A new [backend option](https://github.com/Plutonomicon/cardano-transaction-lib/blob/10a88faa2e6237aafc90568e3488f3421517af63/src/Internal/Contract/QueryBackend.purs#L57) should be added, with corresponding [initialization code](https://github.com/Plutonomicon/cardano-transaction-lib/blob/develop/src/Internal/Contract/QueryHandle.purs)
+A new [backend option](https://github.com/Plutonomicon/cardano-transaction-lib/blob/10a88faa2e6237aafc90568e3488f3421517af63/src/Internal/Contract/ProviderBackend.purs#L57) should be added, with corresponding [initialization code](https://github.com/Plutonomicon/cardano-transaction-lib/blob/develop/src/Internal/Contract/Provider.purs)
 
 ## Replacing some queries in existing backend
 
 Substituting the query layer for a few functions only (assuming the original backend remains available for initial connection) can be done without forking CTL.
 
-`ContractEnv` contains a QueryHandle (inside a `Reader`), so a [`local`](https://pursuit.purescript.org/packages/purescript-transformers/6.0.0/docs/Control.Monad.Reader.Class#v:local) call with a function that replaces some `QueryHandle` record entries will just work.
+`ContractEnv` contains a Provider (inside a `Reader`), so a [`local`](https://pursuit.purescript.org/packages/purescript-transformers/6.0.0/docs/Control.Monad.Reader.Class#v:local) call with a function that replaces some `Provider` record entries will just work.
 
 # Configuring CTL's default query layer (Kupo/Ogmios)
 

src/Contract/Config.purs

@@ -34,20 +34,20 @@ import Ctl.Internal.Contract.Monad
   , ContractSynchronizationParams
   , ContractTimeParams
   ) as X
-import Ctl.Internal.Contract.QueryBackend
+import Ctl.Internal.Contract.ProviderBackend
   ( BlockfrostBackendParams
   , CtlBackend
   , CtlBackendParams
-  , QueryBackend(BlockfrostBackend, CtlBackend)
-  , QueryBackendParams(BlockfrostBackendParams, CtlBackendParams)
+  , ProviderBackend(BlockfrostBackend, CtlBackend)
+  , ProviderBackendParams(BlockfrostBackendParams, CtlBackendParams)
   , defaultConfirmTxDelay
   , getBlockfrostBackend
   , getCtlBackend
   , mkBlockfrostBackendParams
   , mkCtlBackendParams
   , mkSelfHostedBlockfrostBackendParams
   ) as X
-import Ctl.Internal.Contract.QueryBackend (mkCtlBackendParams)
+import Ctl.Internal.Contract.ProviderBackend (mkCtlBackendParams)
 import Ctl.Internal.ServerConfig
   ( Host
   , ServerConfig

src/Contract/PlutusData.purs

@@ -81,7 +81,7 @@ import Cardano.Types.RedeemerDatum (RedeemerDatum(RedeemerDatum)) as X
 import Cardano.Types.RedeemerDatum as Redeemer
 import Contract.Monad (Contract)
 import Control.Parallel (parTraverse)
-import Ctl.Internal.Contract.Monad (getQueryHandle)
+import Ctl.Internal.Contract.Monad (getProvider)
 import Data.Either (Either(Left, Right), hush)
 import Data.Map (Map)
 import Data.Map as Map
@@ -93,8 +93,8 @@ import Prim.TypeError (class Warn, Text)
 -- | Retrieve the full resolved datum associated to a given datum hash.
 getDatumByHash :: DataHash -> Contract (Maybe PlutusData)
 getDatumByHash dataHash = do
-  queryHandle <- getQueryHandle
-  liftAff $ join <<< hush <$> queryHandle.getDatumByHash dataHash
+  provider <- getProvider
+  liftAff $ join <<< hush <$> provider.getDatumByHash dataHash
 
 -- | Retrieve full resolved datums associated with given datum hashes.
 -- | The resulting `Map` will only contain datums that have been successfully
@@ -108,9 +108,9 @@ getDatumsByHashes hashes =
 getDatumsByHashesWithErrors
   :: Array DataHash -> Contract (Map DataHash (Either String PlutusData))
 getDatumsByHashesWithErrors hashes = do
-  queryHandle <- getQueryHandle
+  provider <- getProvider
   liftAff $ Map.fromFoldable <$> flip parTraverse hashes
-    \dh -> queryHandle.getDatumByHash dh <#> Tuple dh <<< case _ of
+    \dh -> provider.getDatumByHash dh <#> Tuple dh <<< case _ of
       Right (Just datum) -> Right datum
       Right Nothing -> Left "Datum not found"
       Left err -> Left $ show err

src/Contract/Scripts.purs

@@ -32,7 +32,7 @@ import Cardano.Types.PlutusScript as PlutusScript
 import Cardano.Types.ScriptRef (ScriptRef)
 import Contract.Monad (Contract)
 import Control.Parallel (parTraverse)
-import Ctl.Internal.Contract.Monad (getQueryHandle)
+import Ctl.Internal.Contract.Monad (getProvider)
 import Ctl.Internal.Service.Error (ClientError)
 import Data.Either (Either)
 import Data.Map (Map)
@@ -45,17 +45,17 @@ import Prim.TypeError (class Warn, Text)
 -- | Retrieve a `ScriptRef` given the hash
 getScriptByHash :: ScriptHash -> Contract (Either ClientError (Maybe ScriptRef))
 getScriptByHash hash = do
-  queryHandle <- getQueryHandle
-  liftAff $ queryHandle.getScriptByHash hash
+  provider <- getProvider
+  liftAff $ provider.getScriptByHash hash
 
 -- | Retrieve `ScriptRef`s given their hashes
 getScriptsByHashes
   :: Array ScriptHash
   -> Contract (Map ScriptHash (Either ClientError (Maybe ScriptRef)))
 getScriptsByHashes hashes = do
-  queryHandle <- getQueryHandle
+  provider <- getProvider
   liftAff $ Map.fromFoldable <$> flip parTraverse hashes
-    \sh -> queryHandle.getScriptByHash sh <#> Tuple sh
+    \sh -> provider.getScriptByHash sh <#> Tuple sh
 
 -- | Deprecated. Use `Cardano.Types.PlutusScript`
 type Validator = PlutusScript

src/Contract/Staking.purs

@@ -17,7 +17,7 @@ import Cardano.Types
   )
 import Contract.Monad (Contract)
 import Control.Monad.Reader (asks)
-import Ctl.Internal.Contract.Monad (getQueryHandle)
+import Ctl.Internal.Contract.Monad (getProvider)
 import Ctl.Internal.Types.DelegationsAndRewards (DelegationsAndRewards)
 import Ctl.Internal.Types.DelegationsAndRewards (DelegationsAndRewards) as X
 import Data.Either (either)
@@ -29,9 +29,9 @@ import Effect.Exception (throw)
 
 getPoolIds :: Contract (Array PoolPubKeyHash)
 getPoolIds = do
-  queryHandle <- getQueryHandle
+  provider <- getProvider
   liftAff $
-    queryHandle.getPoolIds
+    provider.getPoolIds
       >>= either (liftEffect <<< throw <<< show) pure
 
 getStakeCredentialDelegationsAndRewards
@@ -47,20 +47,20 @@ getPubKeyHashDelegationsAndRewards
   :: Ed25519KeyHash
   -> Contract (Maybe DelegationsAndRewards)
 getPubKeyHashDelegationsAndRewards stakePubKeyHash = do
-  queryHandle <- getQueryHandle
+  provider <- getProvider
   networkId <- asks _.networkId
   liftAff do
-    queryHandle.getPubKeyHashDelegationsAndRewards networkId
+    provider.getPubKeyHashDelegationsAndRewards networkId
       (wrap stakePubKeyHash)
       >>= either (liftEffect <<< throw <<< show) pure
 
 getValidatorHashDelegationsAndRewards
   :: ScriptHash
   -> Contract (Maybe DelegationsAndRewards)
 getValidatorHashDelegationsAndRewards stakeValidatorHash = do
-  queryHandle <- getQueryHandle
+  provider <- getProvider
   networkId <- asks _.networkId
   liftAff do
-    queryHandle.getValidatorHashDelegationsAndRewards networkId
+    provider.getValidatorHashDelegationsAndRewards networkId
       stakeValidatorHash
       >>= either (liftEffect <<< throw <<< show) pure

src/Contract/Test/Blockfrost.purs

@@ -13,7 +13,7 @@ import Contract.Config
   , CtlBackendParams
   , PrivatePaymentKeySource(PrivatePaymentKeyFile)
   , PrivateStakeKeySource(PrivateStakeKeyFile)
-  , QueryBackendParams(BlockfrostBackendParams)
+  , ProviderBackendParams(BlockfrostBackendParams)
   , ServerConfig
   , WalletSpec(UseKeys)
   )

src/Contract/Time.purs

@@ -23,7 +23,7 @@ import Contract.Log (logInfo')
 import Contract.Monad (Contract, liftContractM, liftedE)
 import Control.Monad.Reader.Class (asks)
 import Ctl.Internal.Contract (getChainTip)
-import Ctl.Internal.Contract.Monad (getQueryHandle)
+import Ctl.Internal.Contract.Monad (getProvider)
 import Ctl.Internal.Helpers (liftM)
 import Ctl.Internal.QueryM.Ogmios (CurrentEpoch(CurrentEpoch))
 import Ctl.Internal.QueryM.Ogmios
@@ -173,8 +173,8 @@ normalizeTimeInterval = case _ of
 -- | Get the current Epoch.
 getCurrentEpoch :: Contract Epoch
 getCurrentEpoch = do
-  queryHandle <- getQueryHandle
-  CurrentEpoch bigNum <- liftAff $ queryHandle.getCurrentEpoch
+  provider <- getProvider
+  CurrentEpoch bigNum <- liftAff $ provider.getCurrentEpoch
   map Epoch $ liftM (error "Unable to convert CurrentEpoch")
     $ UInt.fromString
     $ BigNum.toString (bigNum :: BigNum)
@@ -187,8 +187,8 @@ getCurrentEpoch = do
 -- | https://docs.blockfrost.io/#tag/Cardano-Network/paths/~1network~1eras/get
 getEraSummaries :: Contract EraSummaries
 getEraSummaries = do
-  queryHandle <- getQueryHandle
-  liftedE $ liftAff $ queryHandle.getEraSummaries
+  provider <- getProvider
+  liftedE $ liftAff $ provider.getEraSummaries
 
 -- | Get the current system start time.
 getSystemStart :: Contract SystemStart

src/Contract/Transaction.purs

@@ -96,9 +96,9 @@ import Ctl.Internal.Contract.AwaitTxConfirmed
   , isTxConfirmed
   ) as X
 import Ctl.Internal.Contract.MinFee (calculateMinFee) as X
-import Ctl.Internal.Contract.Monad (getQueryHandle)
-import Ctl.Internal.Contract.QueryHandle.Error (GetTxMetadataError)
-import Ctl.Internal.Contract.QueryHandle.Error
+import Ctl.Internal.Contract.Monad (getProvider)
+import Ctl.Internal.Contract.Provider.Error (GetTxMetadataError)
+import Ctl.Internal.Contract.Provider.Error
   ( GetTxMetadataError
       ( GetTxMetadataTxNotFoundError
       , GetTxMetadataMetadataEmptyOrMissingError
@@ -171,8 +171,8 @@ submitE
   :: Transaction
   -> Contract (Either ClientError TransactionHash)
 submitE tx = do
-  queryHandle <- getQueryHandle
-  eiTxHash <- liftAff $ queryHandle.submitTx tx
+  provider <- getProvider
+  eiTxHash <- liftAff $ provider.submitTx tx
   void $ asks (_.hooks >>> _.onSubmit) >>=
     traverse \hook -> liftEffect $ void $ try $ hook tx
   pure eiTxHash
@@ -322,8 +322,8 @@ getTxAuxiliaryData
   :: TransactionHash
   -> Contract (Either GetTxMetadataError AuxiliaryData)
 getTxAuxiliaryData txHash = do
-  queryHandle <- getQueryHandle
-  liftAff $ queryHandle.getTxAuxiliaryData txHash
+  provider <- getProvider
+  liftAff $ provider.getTxAuxiliaryData txHash
 
 -- | Builds an expected utxo set from transaction outputs. Predicts output
 -- | references (`TransactionInput`s) for each output by calculating the

src/Contract/Utxos.purs

@@ -15,7 +15,7 @@ import Cardano.Types.TransactionInput (TransactionInput)
 import Contract.Log (logWarn')
 import Contract.Monad (Contract, liftedE)
 import Ctl.Internal.BalanceTx.Sync (getControlledAddresses, isCip30Wallet)
-import Ctl.Internal.Contract.Monad (getQueryHandle)
+import Ctl.Internal.Contract.Monad (getProvider)
 import Data.Maybe (Maybe)
 import Data.Set (member) as Set
 import Effect.Aff.Class (liftAff)
@@ -33,7 +33,7 @@ utxosAt
   :: Address
   -> Contract UtxoMap
 utxosAt address = do
-  queryHandle <- getQueryHandle
+  provider <- getProvider
   whenM isCip30Wallet do
     walletAddresses <- getControlledAddresses
     when (address `Set.member` walletAddresses) do
@@ -44,13 +44,13 @@ utxosAt address = do
           <> "that are available on wallet addresses are actually spendable. "
           <> "See the docs for UTxO locking in `doc/query-layers.md`. Using "
           <> "`getWalletUtxos` is a way to avoid the potential problems."
-  liftedE $ liftAff $ queryHandle.utxosAt address
+  liftedE $ liftAff $ provider.utxosAt address
 
 -- | Queries for an utxo given a transaction input.
 -- | Returns `Nothing` if the output has already been spent.
 getUtxo
   :: TransactionInput
   -> Contract (Maybe TransactionOutput)
 getUtxo oref = do
-  queryHandle <- getQueryHandle
-  liftedE $ liftAff $ queryHandle.getUtxoByOref oref
+  provider <- getProvider
+  liftedE $ liftAff $ provider.getUtxoByOref oref

src/Internal/BalanceTx/BalanceTx.purs

@@ -105,7 +105,7 @@ import Ctl.Internal.BalanceTx.Types
 import Ctl.Internal.BalanceTx.UtxoMinAda (utxoMinAdaValue)
 import Ctl.Internal.CoinSelection.UtxoIndex (UtxoIndex, buildUtxoIndex)
 import Ctl.Internal.Contract (getProtocolParameters)
-import Ctl.Internal.Contract.Monad (Contract, filterLockedUtxos, getQueryHandle)
+import Ctl.Internal.Contract.Monad (Contract, filterLockedUtxos, getProvider)
 import Ctl.Internal.Contract.Wallet
   ( getChangeAddress
   , getWalletCollateral
@@ -198,14 +198,14 @@ balanceTxWithConstraints transaction extraUtxos constraintsBuilder =
             Wallet.getWalletUtxos
         -- Use UTxOs from source addresses
         Just srcAddrs -> do
-          queryHandle <- getQueryHandle
+          provider <- getProvider
           -- Even though some of the addresses may be controlled by the wallet,
           -- we can't query the wallet for available UTxOs, because there's no
           -- way to tell it to return UTxOs only from specific subset of the
           -- addresses controlled by a CIP-30 wallet.
           -- `utxosAt` calls are expensive when there are a lot of addresses to
           -- check.
-          parTraverse (queryHandle.utxosAt >>> liftAff >>> map hush) srcAddrs
+          parTraverse (provider.utxosAt >>> liftAff >>> map hush) srcAddrs
             <#> traverse (note CouldNotGetUtxos)
               >>> map (foldr Map.union Map.empty) -- merge all utxos into one map
 

src/Internal/BalanceTx/ExUnitsAndMinFee.purs

@@ -46,7 +46,7 @@ import Ctl.Internal.BalanceTx.Types
   , liftContract
   )
 import Ctl.Internal.Contract.MinFee (calculateMinFee) as Contract.MinFee
-import Ctl.Internal.Contract.Monad (getQueryHandle)
+import Ctl.Internal.Contract.Monad (getProvider)
 import Ctl.Internal.Helpers (liftEither, unsafeFromJust)
 import Ctl.Internal.QueryM.Ogmios
   ( AdditionalUtxoSet
@@ -103,10 +103,10 @@ evalTxExecutionUnits tx = do
 
   worker :: Ogmios.AdditionalUtxoSet -> BalanceTxM Ogmios.TxEvaluationResult
   worker additionalUtxos = do
-    queryHandle <- liftContract getQueryHandle
+    provider <- liftContract getProvider
     evalResult <-
       unwrap <$> liftContract
-        (liftAff $ queryHandle.evaluateTx tx additionalUtxos)
+        (liftAff $ provider.evaluateTx tx additionalUtxos)
     case evalResult of
       Right a -> pure a
       Left (Ogmios.AdditionalUtxoOverlap overlappingUtxos) ->

src/Internal/BalanceTx/Sync.purs

@@ -28,7 +28,7 @@ import Control.Monad.Reader.Class (asks)
 import Control.Parallel (parOneOf, parTraverse, parallel, sequential)
 import Ctl.Internal.Contract.Monad
   ( ContractSynchronizationParams
-  , getQueryHandle
+  , getProvider
   )
 import Ctl.Internal.Contract.Wallet
   ( getChangeAddress
@@ -135,7 +135,7 @@ syncWalletWithTransaction txHash = whenM isCip30Wallet do
       <> " in use in the wallet. Consider increasing "
       <> "`timeParams.syncWallet.timeout` in `ContractParams`. "
       <> "See `doc/query-layers.md` for more info."
-  queryHandle <- getQueryHandle
+  provider <- getProvider
   let
     sync :: Contract Unit
     sync = do
@@ -157,7 +157,7 @@ syncWalletWithTransaction txHash = whenM isCip30Wallet do
   ownAddresses /\ outputAddresses <- sequential do
     Tuple <$> parallel getControlledAddresses <*> parallel do
       liftAff $ liftEither =<< do
-        queryHandle.getOutputAddressesByTxHash txHash <#>
+        provider.getOutputAddressesByTxHash txHash <#>
           bimap (error <<< show) Set.fromFoldable
   if Set.isEmpty (Set.intersection ownAddresses outputAddresses) then do
     logWarn' $ "syncWalletWithTransaction: "
@@ -249,8 +249,8 @@ disabledSynchronizationParams =
 -- | A version without plutus conversion for internal use.
 getUtxo' :: TransactionInput -> Contract (Maybe TransactionOutput)
 getUtxo' oref = do
-  queryHandle <- getQueryHandle
-  liftedE $ liftAff $ queryHandle.getUtxoByOref oref
+  provider <- getProvider
+  liftedE $ liftAff $ provider.getUtxoByOref oref
 
 -- | Get all addresses contolled by a wallet:
 -- | `getUsedAddresses`, `getUnusedAddresses` and `getChangeAddress` combined.