PLT-313 Add ownAddresses request in Contract API which will replace o…

…wnPaymentPubKeyHash.

* `ownPaymentPubKeyHash` is marked as deprecated

* All plutus-use-cases examples replace usage of `ownPaymentPubKeyHash` with `ownAddresses`

* Fix plutus-pab-local-cluster which wasn't working because the chain-index wasn't in sync with the PAB

doc/plutus/tutorials/EscrowImpl.hs

@@ -70,7 +70,7 @@ import Plutus.V1.Ledger.Contexts (ScriptContext (ScriptContext, scriptContextTxI
 
 import Plutus.Contract (AsContractError (_ContractError), Contract, ContractError, Endpoint, HasEndpoint, Promise,
                         adjustUnbalancedTx, awaitTime, currentTime, endpoint, mapError, mkTxConstraints,
-                        ownPaymentPubKeyHash, promiseMap, selectList, submitUnbalancedTx, type (.\/), utxosAt,
+                        ownFirstPaymentPubKeyHash, promiseMap, selectList, submitUnbalancedTx, type (.\/), utxosAt,
                         waitNSlots)
 import Plutus.Contract.Typed.Tx qualified as Typed
 import PlutusTx qualified
@@ -267,7 +267,7 @@ pay ::
     -- ^ How much money to pay in
     -> Contract w s e TxId
 pay inst escrow vl = do
-    pk <- ownPaymentPubKeyHash
+    pk <- ownFirstPaymentPubKeyHash
     let tx = Constraints.mustPayToTheScript pk vl
           <> Constraints.mustValidateIn (Ledger.interval 1 (escrowDeadline escrow))
     utx <- mkTxConstraints (Constraints.typedValidatorLookups inst) tx >>= adjustUnbalancedTx
@@ -336,7 +336,7 @@ refund ::
     -> EscrowParams Datum
     -> Contract w s EscrowError RefundSuccess
 refund inst escrow = do
-    pk <- ownPaymentPubKeyHash
+    pk <- ownFirstPaymentPubKeyHash
     unspentOutputs <- utxosAt (Scripts.validatorAddress inst)
     let flt _ ciTxOut = either id Scripts.datumHash (Tx._ciTxOutDatum ciTxOut) == Scripts.datumHash (Datum (PlutusTx.toBuiltinData pk))
         tx' = Typed.collectFromScriptFilter flt unspentOutputs Refund

playground-common/src/Playground/Contract.hs

@@ -42,6 +42,9 @@ module Playground.Contract
     , type (.\/)
     , interval
     , ownPaymentPubKeyHash
+    , ownFirstPaymentPubKeyHash
+    , ownPaymentPubKeyHashes
+    , ownAddresses
     , awaitSlot
     , modifiesUtxoSet
     , utxosAt
@@ -66,8 +69,9 @@ import Playground.Interpreter.Util
 import Playground.Schema (endpointsToSchemas)
 import Playground.TH (ensureKnownCurrencies, mkFunction, mkFunctions, mkKnownCurrencies, mkSchemaDefinitions)
 import Playground.Types (Expression, FunctionSchema, KnownCurrency (KnownCurrency), adaCurrency)
-import Plutus.Contract (AsContractError, Contract, Endpoint, awaitSlot, endpoint, ownPaymentPubKeyHash, submitTx,
-                        type (.\/), utxosAt, watchAddressUntilSlot)
+import Plutus.Contract (AsContractError, Contract, Endpoint, awaitSlot, endpoint, ownAddresses,
+                        ownFirstPaymentPubKeyHash, ownPaymentPubKeyHash, ownPaymentPubKeyHashes, submitTx, type (.\/),
+                        utxosAt, watchAddressUntilSlot)
 import Plutus.Contract.Trace (TraceError (..))
 import Schema (FormSchema, ToArgument, ToSchema)
 import Wallet.Emulator.Types (Wallet (..))

plutus-chain-index-core/src/Plutus/ChainIndex/Types.hs

@@ -162,6 +162,8 @@ data Tip =
     deriving stock (Eq, Show, Generic)
     deriving anyclass (ToJSON, FromJSON, OpenApi.ToSchema)
 
+makePrisms ''Tip
+
 -- | When performing a rollback the chain sync protocol does not provide a block
 --   number where to resume from.
 data Point =

plutus-contract/src/Plutus/Contract.hs

@@ -62,8 +62,12 @@ module Plutus.Contract(
     , Request.utxosAt
     , Request.utxosTxOutTxFromTx
     , Request.getTip
-    -- * Wallet's own public key
+    -- * Wallet's information
     , Request.ownPaymentPubKeyHash
+    , Request.ownPaymentPubKeyHashes
+    , Request.ownFirstPaymentPubKeyHash
+    , Request.ownAddresses
+    , Request.ownUtxos
     -- * Contract instance Id
     , Wallet.Types.ContractInstanceId
     , Request.ownInstanceId

plutus-contract/src/Plutus/Contract/Effects.hs

@@ -18,7 +18,7 @@ module Plutus.Contract.Effects( -- TODO: Move to Requests.Internal
     _AwaitTxStatusChangeReq,
     _AwaitTxOutStatusChangeReq,
     _OwnContractInstanceIdReq,
-    _OwnPaymentPublicKeyHashReq,
+    _OwnAddressesReq,
     _ChainIndexQueryReq,
     _BalanceTxReq,
     _WriteBalancedTxReq,
@@ -52,7 +52,7 @@ module Plutus.Contract.Effects( -- TODO: Move to Requests.Internal
     _AwaitTxStatusChangeResp',
     _AwaitTxOutStatusChangeResp,
     _OwnContractInstanceIdResp,
-    _OwnPaymentPublicKeyHashResp,
+    _OwnAddressesResp,
     _ChainIndexQueryResp,
     _BalanceTxResp,
     _WriteBalancedTxResp,
@@ -91,7 +91,6 @@ import Data.List.NonEmpty (NonEmpty)
 import Data.OpenApi.Schema qualified as OpenApi
 import Data.String (fromString)
 import GHC.Generics (Generic)
-import Ledger (PaymentPubKeyHash)
 import Ledger.Constraints.OffChain (UnbalancedTx)
 import Ledger.Credential (Credential)
 import Ledger.Scripts (Validator)
@@ -124,7 +123,7 @@ data PABReq =
     | CurrentSlotReq
     | CurrentTimeReq
     | OwnContractInstanceIdReq
-    | OwnPaymentPublicKeyHashReq
+    | OwnAddressesReq
     | ChainIndexQueryReq ChainIndexQuery
     | BalanceTxReq UnbalancedTx
     | WriteBalancedTxReq CardanoTx
@@ -146,7 +145,7 @@ instance Pretty PABReq where
     AwaitTxStatusChangeReq txid             -> "Await tx status change:" <+> pretty txid
     AwaitTxOutStatusChangeReq ref           -> "Await txout status change:" <+> pretty ref
     OwnContractInstanceIdReq                -> "Own contract instance ID"
-    OwnPaymentPublicKeyHashReq              -> "Own public key"
+    OwnAddressesReq                         -> "Own addresses"
     ChainIndexQueryReq q                    -> "Chain index query:" <+> pretty q
     BalanceTxReq utx                        -> "Balance tx:" <+> pretty utx
     WriteBalancedTxReq tx                   -> "Write balanced tx:" <+> onCardanoTx pretty (fromString . show) tx
@@ -166,7 +165,7 @@ data PABResp =
     | CurrentSlotResp Slot
     | CurrentTimeResp POSIXTime
     | OwnContractInstanceIdResp ContractInstanceId
-    | OwnPaymentPublicKeyHashResp PaymentPubKeyHash
+    | OwnAddressesResp (NonEmpty Address)
     | ChainIndexQueryResp ChainIndexResponse
     | BalanceTxResp BalanceTxResponse
     | WriteBalancedTxResp WriteBalancedTxResponse
@@ -188,7 +187,7 @@ instance Pretty PABResp where
     AwaitTxStatusChangeResp txid status      -> "Status of" <+> pretty txid <+> "changed to" <+> pretty status
     AwaitTxOutStatusChangeResp ref status    -> "Status of" <+> pretty ref <+> "changed to" <+> pretty status
     OwnContractInstanceIdResp i              -> "Own contract instance ID:" <+> pretty i
-    OwnPaymentPublicKeyHashResp k            -> "Own public key:" <+> pretty k
+    OwnAddressesResp addrs                   -> "Own addresses:" <+> pretty addrs
     ChainIndexQueryResp rsp                  -> pretty rsp
     BalanceTxResp r                          -> "Balance tx:" <+> pretty r
     WriteBalancedTxResp r                    -> "Write balanced tx:" <+> pretty r
@@ -208,7 +207,7 @@ matches a b = case (a, b) of
   (AwaitTxStatusChangeReq i, AwaitTxStatusChangeResp i' _) -> i == i'
   (AwaitTxOutStatusChangeReq i, AwaitTxOutStatusChangeResp i' _) -> i == i'
   (OwnContractInstanceIdReq, OwnContractInstanceIdResp{})  -> True
-  (OwnPaymentPublicKeyHashReq, OwnPaymentPublicKeyHashResp{})                    -> True
+  (OwnAddressesReq, OwnAddressesResp {}) -> True
   (ChainIndexQueryReq r, ChainIndexQueryResp r')           -> chainIndexMatches r r'
   (BalanceTxReq{}, BalanceTxResp{})                        -> True
   (WriteBalancedTxReq{}, WriteBalancedTxResp{})            -> True

plutus-contract/src/Plutus/Contract/Request.hs

@@ -76,8 +76,12 @@ module Plutus.Contract.Request(
     , endpointDescription
     , endpointReq
     , endpointResp
-    -- ** Public key hashes
+    -- ** Wallet information
     , ownPaymentPubKeyHash
+    , ownPaymentPubKeyHashes
+    , ownFirstPaymentPubKeyHash
+    , ownAddresses
+    , ownUtxos
     -- ** Submitting transactions
     , adjustUnbalancedTx
     , submitUnbalancedTx
@@ -116,8 +120,8 @@ import Data.Void (Void)
 import GHC.Generics (Generic)
 import GHC.Natural (Natural)
 import GHC.TypeLits (Symbol, symbolVal)
-import Ledger (AssetClass, DiffMilliSeconds, POSIXTime, PaymentPubKeyHash, Slot, TxId, TxOutRef, Value,
-               addressCredential, fromMilliSeconds, txOutRefId)
+import Ledger (AssetClass, DiffMilliSeconds, POSIXTime, PaymentPubKeyHash (PaymentPubKeyHash), Slot, TxId, TxOutRef,
+               Value, addressCredential, fromMilliSeconds, txOutRefId)
 import Ledger.Constraints (TxConstraints)
 import Ledger.Constraints.OffChain (ScriptLookups, UnbalancedTx)
 import Ledger.Constraints.OffChain qualified as Constraints
@@ -130,21 +134,25 @@ import Plutus.V1.Ledger.Api (Address, Datum, DatumHash, MintingPolicy, MintingPo
 import PlutusTx qualified
 
 import Plutus.Contract.Effects (ActiveEndpoint (ActiveEndpoint, aeDescription, aeMetadata),
-                                PABReq (AdjustUnbalancedTxReq, AwaitSlotReq, AwaitTimeReq, AwaitTxOutStatusChangeReq, AwaitTxStatusChangeReq, AwaitUtxoProducedReq, AwaitUtxoSpentReq, BalanceTxReq, ChainIndexQueryReq, CurrentSlotReq, CurrentTimeReq, ExposeEndpointReq, OwnContractInstanceIdReq, OwnPaymentPublicKeyHashReq, WriteBalancedTxReq, YieldUnbalancedTxReq),
+                                PABReq (AdjustUnbalancedTxReq, AwaitSlotReq, AwaitTimeReq, AwaitTxOutStatusChangeReq, AwaitTxStatusChangeReq, AwaitUtxoProducedReq, AwaitUtxoSpentReq, BalanceTxReq, ChainIndexQueryReq, CurrentSlotReq, CurrentTimeReq, ExposeEndpointReq, OwnAddressesReq, OwnContractInstanceIdReq, WriteBalancedTxReq, YieldUnbalancedTxReq),
                                 PABResp (ExposeEndpointResp))
 import Plutus.Contract.Effects qualified as E
 import Plutus.Contract.Logging (logDebug)
 import Plutus.Contract.Schema (Input, Output)
 import Wallet.Types (ContractInstanceId, EndpointDescription (EndpointDescription),
                      EndpointValue (EndpointValue, unEndpointValue))
 
+import Data.Foldable (fold)
+import Data.List.NonEmpty qualified as NonEmpty
 import Plutus.ChainIndex (ChainIndexTx, Page (nextPageQuery, pageItems), PageQuery, txOutRefs)
 import Plutus.ChainIndex.Api (IsUtxoResponse, TxosResponse, UtxosResponse (page), paget)
 import Plutus.ChainIndex.Types (RollbackState (Unknown), Tip, TxOutStatus, TxStatus)
 import Plutus.Contract.Error (AsContractError (_ChainIndexContractError, _ConstraintResolutionContractError, _EndpointDecodeContractError, _ResumableContractError, _TxToCardanoConvertContractError, _WalletContractError))
 import Plutus.Contract.Resumable (prompt)
 import Plutus.Contract.Types (Contract (Contract), MatchingError (WrongVariantError), Promise (Promise), mapError,
                               runError, throwError)
+import Plutus.V1.Ledger.Address (toPubKeyHash)
+import Wallet.Emulator.Error (WalletAPIError (NoPaymentPubKeyHashError))
 
 -- | Constraints on the contract schema, ensuring that the labels of the schema
 --   are unique.
@@ -424,6 +432,12 @@ foldUtxoRefsAt f ini addr = go ini (Just def)
       newAcc <- f acc page
       go newAcc (nextPageQuery page)
 
+-- | Get all utxos belonging to the wallet that runs this contract.
+ownUtxos :: forall w s e. (AsContractError e) => Contract w s e (Map TxOutRef ChainIndexTxOut)
+ownUtxos = do
+    addrs <- ownAddresses
+    fold <$> mapM utxosAt (NonEmpty.toList addrs)
+
 -- | Get the unspent transaction outputs at an address.
 utxosAt ::
     forall w s e.
@@ -785,6 +799,7 @@ endpointWithMeta meta f = Promise $ do
 endpointDescription :: forall l. KnownSymbol l => Proxy l -> EndpointDescription
 endpointDescription = EndpointDescription . symbolVal
 
+{-# DEPRECATED ownPaymentPubKeyHash "Use ownFirstPaymentPubKeyHash, ownPaymentPubKeyHashes or ownAddresses instead" #-}
 -- | Get the hash of a public key belonging to the wallet that runs this contract.
 --   * Any funds paid to this public key hash will be treated as the wallet's own
 --     funds
@@ -794,7 +809,30 @@ endpointDescription = EndpointDescription . symbolVal
 --   * There is a 1-n relationship between wallets and public keys (although in
 --     the mockchain n=1)
 ownPaymentPubKeyHash :: forall w s e. (AsContractError e) => Contract w s e PaymentPubKeyHash
-ownPaymentPubKeyHash = pabReq OwnPaymentPublicKeyHashReq E._OwnPaymentPublicKeyHashResp
+ownPaymentPubKeyHash = ownFirstPaymentPubKeyHash
+
+-- | Get the addresses belonging to the wallet that runs this contract.
+--   * Any funds paid to one of these addresses will be treated as the wallet's own
+--     funds
+--   * The wallet is able to sign transactions with the private key of one of its
+--     public key, for example, if the public key is added to the
+--     'requiredSignatures' field of 'Tx'.
+--   * There is a 1-n relationship between wallets and addresses (although in
+--     the mockchain n=1)
+ownAddresses :: forall w s e. (AsContractError e) => Contract w s e (NonEmpty Address)
+ownAddresses = pabReq OwnAddressesReq E._OwnAddressesResp
+
+ownPaymentPubKeyHashes :: forall w s e. (AsContractError e) => Contract w s e [PaymentPubKeyHash]
+ownPaymentPubKeyHashes = do
+    addrs <- ownAddresses
+    pure $ fmap PaymentPubKeyHash $ mapMaybe toPubKeyHash $ NonEmpty.toList addrs
+
+ownFirstPaymentPubKeyHash :: forall w s e. (AsContractError e) => Contract w s e PaymentPubKeyHash
+ownFirstPaymentPubKeyHash = do
+    pkhs <- ownPaymentPubKeyHashes
+    case pkhs of
+      []      -> throwError $ review _WalletContractError NoPaymentPubKeyHashError
+      (pkh:_) -> pure pkh
 
 -- | Send an unbalanced transaction to be balanced and signed. Returns the ID
 --    of the final transaction when the transaction was submitted. Throws an

plutus-contract/src/Plutus/Contract/StateMachine.hs

@@ -80,8 +80,8 @@ import Ledger.Value qualified as Value
 import Plutus.ChainIndex (ChainIndexTx (_citxInputs))
 import Plutus.Contract (AsContractError (_ConstraintResolutionContractError, _ContractError), Contract, ContractError,
                         Promise, adjustUnbalancedTx, awaitPromise, isSlot, isTime, logWarn, mapError, never,
-                        ownPaymentPubKeyHash, promiseBind, select, submitTxConfirmed, utxoIsProduced, utxoIsSpent,
-                        utxosAt, utxosTxOutTxFromTx)
+                        ownFirstPaymentPubKeyHash, ownUtxos, promiseBind, select, submitTxConfirmed, utxoIsProduced,
+                        utxoIsSpent, utxosAt, utxosTxOutTxFromTx)
 import Plutus.Contract.Request (mkTxContract)
 import Plutus.Contract.StateMachine.MintingPolarity (MintingPolarity (Burn, Mint))
 import Plutus.Contract.StateMachine.OnChain (State (State, stateData, stateValue),
@@ -432,8 +432,7 @@ runInitialiseWith ::
     -> Contract w schema e state
 runInitialiseWith customLookups customConstraints StateMachineClient{scInstance} initialState initialValue =
     mapError (review _SMContractError) $ do
-      ownPK <- ownPaymentPubKeyHash
-      utxo <- utxosAt (Ledger.pubKeyHashAddress ownPK Nothing)
+      utxo <- ownUtxos
       let StateMachineInstance{stateMachine, typedValidator} = scInstance
           constraints = mustPayToTheScript initialState (initialValue <> SM.threadTokenValueOrZero scInstance)
               <> foldMap ttConstraints (smThreadToken stateMachine)
@@ -493,7 +492,7 @@ runGuardedStepWith ::
 runGuardedStepWith userLookups userConstraints smc input guard =
   mapError (review _SMContractError) $ mkStep smc input >>= \case
     Right StateMachineTransition{smtConstraints,smtOldState=State{stateData=os}, smtNewState=State{stateData=ns}, smtLookups} -> do
-        pk <- ownPaymentPubKeyHash
+        pk <- ownFirstPaymentPubKeyHash
         let lookups = smtLookups { Constraints.slOwnPaymentPubKeyHash = Just pk }
         utx <- either (throwing _ConstraintResolutionContractError)
                       pure

plutus-contract/src/Plutus/Contract/Trace.hs

@@ -27,7 +27,7 @@ module Plutus.Contract.Trace
     , handleAdjustUnbalancedTx
     , handleSlotNotifications
     , handleTimeNotifications
-    , handleOwnPaymentPubKeyHashQueries
+    , handleOwnAddressesQueries
     , handleCurrentSlotQueries
     , handleCurrentTimeQueries
     , handleTimeToSlotConversions
@@ -175,13 +175,13 @@ handleChainIndexQueries =
                E.ChainIndexQueryResp
                RequestHandler.handleChainIndexQueries
 
-handleOwnPaymentPubKeyHashQueries ::
+handleOwnAddressesQueries ::
     ( Member (LogObserve (LogMessage Text)) effs
     , Member WalletEffect effs
     )
     => RequestHandler effs PABReq PABResp
-handleOwnPaymentPubKeyHashQueries =
-    generalise (preview E._OwnPaymentPublicKeyHashReq) E.OwnPaymentPublicKeyHashResp RequestHandler.handleOwnPaymentPubKeyHash
+handleOwnAddressesQueries =
+    generalise (preview E._OwnAddressesReq) E.OwnAddressesResp RequestHandler.handleOwnAddresses
 
 handleOwnInstanceIdQueries ::
     ( Member (LogObserve (LogMessage Text)) effs

plutus-contract/src/Plutus/Contract/Trace/RequestHandler.hs

@@ -18,7 +18,7 @@ module Plutus.Contract.Trace.RequestHandler(
     , generalise
     -- * handlers for common requests
     , handleAdjustUnbalancedTx
-    , handleOwnPaymentPubKeyHash
+    , handleOwnAddresses
     , handleSlotNotifications
     , handleCurrentSlot
     , handleTimeNotifications
@@ -48,14 +48,16 @@ import Plutus.Contract.Resumable (Request (Request, itID, rqID, rqRequest),
                                   Response (Response, rspItID, rspResponse, rspRqID))
 
 import Control.Monad.Freer.Extras.Log (LogMessage, LogMsg, LogObserve, logDebug, logWarn, surroundDebug)
-import Ledger (POSIXTime, POSIXTimeRange, Params (..), PaymentPubKeyHash, Slot, SlotRange)
+import Data.List.NonEmpty (NonEmpty)
+import Ledger (POSIXTime, POSIXTimeRange, Params (..), Slot, SlotRange)
 import Ledger.Constraints.OffChain (UnbalancedTx, adjustUnbalancedTx)
 import Ledger.TimeSlot qualified as TimeSlot
 import Ledger.Tx (CardanoTx, ToCardanoError)
 import Plutus.ChainIndex (ChainIndexQueryEffect)
 import Plutus.ChainIndex.Effects qualified as ChainIndexEff
 import Plutus.Contract.Effects (ChainIndexQuery (..), ChainIndexResponse (..))
 import Plutus.Contract.Wallet qualified as Wallet
+import Plutus.V1.Ledger.Api (Address)
 import Wallet.API (WalletAPIError)
 import Wallet.Effects (NodeClientEffect, WalletEffect)
 import Wallet.Effects qualified
@@ -112,15 +114,15 @@ maybeToHandler f = RequestHandler $ maybe empty pure . f
 
 -- handlers for common requests
 
-handleOwnPaymentPubKeyHash ::
+handleOwnAddresses ::
     forall a effs.
     ( Member WalletEffect effs
     , Member (LogObserve (LogMessage Text)) effs
     )
-    => RequestHandler effs a PaymentPubKeyHash
-handleOwnPaymentPubKeyHash =
+    => RequestHandler effs a (NonEmpty Address)
+handleOwnAddresses =
     RequestHandler $ \_ ->
-        surroundDebug @Text "handleOwnPaymentPubKeyHash" Wallet.Effects.ownPaymentPubKeyHash
+        surroundDebug @Text "handleOwnAddresses" Wallet.Effects.ownAddresses
 
 handleSlotNotifications ::
     forall effs.

plutus-contract/src/Plutus/Contract/Wallet.hs

@@ -114,7 +114,7 @@ handleTx = balanceTx >=> either throwError WAPI.signTxAndSubmit
 -- | Get an unspent output belonging to the wallet.
 getUnspentOutput :: AsContractError e => Contract w s e TxOutRef
 getUnspentOutput = do
-    ownPkh <- Contract.ownPaymentPubKeyHash
+    ownPkh <- Contract.ownFirstPaymentPubKeyHash
     let constraints = mustPayToPubKey ownPkh (Ada.lovelaceValueOf 1)
     utx <- either (throwing _ConstraintResolutionContractError) pure (mkTx @Void mempty constraints)
     tx <- Contract.adjustUnbalancedTx utx >>= Contract.balanceTx
@@ -281,7 +281,7 @@ toExportTxInput networkId Plutus.TxOutRef{Plutus.txOutRefId, Plutus.txOutRefIdx}
     ExportTxInput
         <$> CardanoAPI.toCardanoTxId txOutRefId
         <*> pure (C.TxIx $ fromInteger txOutRefIdx)
-        <*> CardanoAPI.toCardanoAddress networkId txOutAddress
+        <*> CardanoAPI.toCardanoAddressInEra networkId txOutAddress
         <*> pure (C.selectLovelace cardanoValue)
         <*> sequence (CardanoAPI.toCardanoScriptDataHash <$> txOutDatumHash)
         <*> pure otherQuantities

plutus-contract/src/Plutus/Trace/Emulator/ContractInstance.hs

@@ -250,7 +250,7 @@ handleBlockchainQueries =
     RequestHandler.handleUnbalancedTransactions
     <> RequestHandler.handlePendingTransactions
     <> RequestHandler.handleChainIndexQueries
-    <> RequestHandler.handleOwnPaymentPubKeyHashQueries
+    <> RequestHandler.handleOwnAddressesQueries
     <> RequestHandler.handleOwnInstanceIdQueries
     <> RequestHandler.handleSlotNotifications
     <> RequestHandler.handleCurrentSlotQueries