Define PlutusV4 script context

[lehins]

This ticket is created to track progress on PlutusV4 context that will include at least two CIPs:

• CIP-112 - Observe script type
• CIP-118 - Nested Transactions

Considering that CIP-112 will be required for CIP-118 it makes sense to start with it first.

• - Define PlutusV4 version in plutus-ledger-api:

  plutus/plutus-ledger-api/src/PlutusLedgerApi/Common/Versions.hs

  Lines 89 to 92 in fa5c9e6

  	data PlutusLedgerLanguage =
  	PlutusV1 -- ^ introduced in Alonzo HF
  	| PlutusV2 -- ^ introduced in Vasil HF
  	| PlutusV3 -- ^ introduced in Chang HF

• - Create V4 in plutus-ledger-api:PlutusLedgerApi that reuses as much stuff from V1-V3 as possible
• - Define TxInfo for PlutusV4
• - Add txInfoGuards :: [Credential] to TxInfo for PlutusV4 field and remove txInfoSignatories, since former supersedes the latter (Note that we will be using the term Guards in the implementation instead of Observers as CIP-112. CC @colll78 if you are still up to renaming the CIP to avoid confusion)
• - Add Guarding script purpose
• - Remove PointerAddress case for PlutusV4. See Fail PlutusV4 TxInfo translation when a Ptr is present in any of the outputs cardano-ledger#4832 for reference
• - TBD: CIP-118 related parts added to TxInfo.

I'd recommend creating a child ticket for each of the bullet points, so the progress can be tracked at more granular level, but I'll leave this up to the Plutus team.

[zliu41]

Two specific things to note

1. We'll add two new constructors to Data - Array and Value, and they will be used in Plutus V4 script context. The script context for V1-V3 will of course remain the same.
2. We are not yet sure whether we can implement https://cips.cardano.org/cip/CIP-0152 in time for Dijkstra. If we can, then that will also impact the script context.

[colll78]

I think a clear non-controversial change is to add a ownScriptHash field to the ScriptContext.

-- | The context that the currently-executing script can access.
data ScriptContext = ScriptContext
  { scriptContextTxInfo     :: TxInfo
  -- ^ information about the transaction the currently-executing script is included in
  , scriptContextRedeemer   :: V2.Redeemer
  -- ^ Redeemer for the currently-executing script
  , scriptContextScriptInfo :: ScriptInfo
  -- ^ the purpose of the currently-executing script, along with information associated
  -- with the purpose
  , scriptContextOwnScriptHash :: ScriptHash 
  -- ^ the hash of the currently-executing script. 
  }

[michele-nuzzi]

are there updates on the new ScriptContext for plutus v4? I can't find the defnition anywhere yet

[lehins]

are there updates on the new ScriptContext for plutus v4?

Not yet, but it is coming very soon, more specifically, in the next two weeks for sure.

[lehins]

Here is a preliminary changes to Plutus context for PlutusV4.
Nothing set in stone and feedback is welcomed:

-- | Diff: In TxCertRegStaking and TxCertUnRegStaking removal of Maybe
data TxCert
  = -- | Register staking credential with an optional deposit amount
    TxCertRegStaking V2.Credential V2.Lovelace
  | -- | Un-Register staking credential with an optional refund amount
    TxCertUnRegStaking V2.Credential V2.Lovelace
  | -- | Delegate staking credential to a Delegatee
    TxCertDelegStaking V2.Credential Delegatee
  | {-| Register and delegate staking credential to a Delegatee in one certificate. Note that
    deposit is mandatory. -}
    TxCertRegDeleg V2.Credential Delegatee V2.Lovelace
  | -- | Register a DRep with a deposit value. The optional anchor is omitted.
    TxCertRegDRep DRepCredential V2.Lovelace
  | -- | Update a DRep. The optional anchor is omitted.
    TxCertUpdateDRep DRepCredential
  | -- | UnRegister a DRep with mandatory refund value
    TxCertUnRegDRep DRepCredential V2.Lovelace
  | -- | A digest of the PoolParams
    TxCertPoolRegister
      V2.PubKeyHash
      -- ^ poolId
      V2.PubKeyHash
      -- ^ pool VFR
  | -- | The retirement certificate and the Epoch in which the retirement will take place
    TxCertPoolRetire V2.PubKeyHash Haskell.Integer
  | -- | Authorize a Hot credential for a specific Committee member's cold credential
    TxCertAuthHotCommittee ColdCommitteeCredential HotCommitteeCredential
  | TxCertResignColdCommittee ColdCommitteeCredential

-- | Diff:
--
-- * Rename: Rewarding -> Withdrawing
data ScriptPurpose
  = Minting V2.CurrencySymbol
  | Spending V3.TxOutRef
  | Withdrawing V2.Credential
  | Certifying
      Haskell.Integer
      -- ^ 0-based index of the given `TxCert` in `txInfoTxCerts`
      TxCert
  | Voting Voter
  | Proposing
      Haskell.Integer
      -- ^ 0-based index of the given `ProposalProcedure` in `txInfoProposalProcedures`
      ProposalProcedure
  | Guarding Haskell.Integer

-- | Diff:
--
-- * Rename: Rewarding -> Withdrawing
-- * Add: GuardingScript
data ScriptInfo
  = MintingScript V2.CurrencySymbol
  | SpendingScript V3.TxOutRef (Haskell.Maybe V2.Datum)
  | WithdrawingScript V2.Credential
  | CertifyingScript
      Haskell.Integer
      -- ^ 0-based index of the given `TxCert` in `txInfoTxCerts`
      TxCert
  | VotingScript Voter
  | ProposingScript
      Haskell.Integer
      -- ^ 0-based index of the given `ProposalProcedure` in `txInfoProposalProcedures`
      ProposalProcedure
  | GuardingScript
      Haskell.Integer -- (or ScriptHash? or Both?)
      -- | Datums supplied in `requiredTopLevelGuards` for that script. Nothing if Script was required, but Datum was not supplied.
      (Map TxId (Haskell.Maybe V2.Datum))

data AccountBalanceInterval
  = AccountBalanceLowerBound Lovelace
  | AccountBalanceUpperBound Lovelace
  | AccountBalanceBothBounds Lovelace Lovelace

newtype AccountBalanceIntervals
  = AccountBalanceIntervals (Map.Map Credential AccountBalanceInterval)

newtype SubTxInfo = SubTxInfo
  { subTxInfoRequiredTopLevelGuards :: Map Credential (Maybe Data)
  }

newtype TopTxInfo = TopTxInfo
  { topTxInfoSubTransactions :: [TxInfo]
  }

data TxInfoLevel
  = TxInfoSubTx SubTxInfo
  | TxInfoTopTx TopTxInfo

-- | Diff:
--
-- * Signatories:[PubKeyHash] -> Guards:[Credential]
-- * Fee -> Maybe Fee
-- * Add: DirectDeposits
-- * Add: AccountBalanceIntervals
-- * Rename: txInfoWdrl -> txInfoWithdrawals
--
-- * Alternative:
--   * Set Fee == 0, instead of making it a Nothing for SubTransactions
--   * Putting the fee into `TopTxInfo`, which is a bit more intrusive IMHO
data TxInfo = TxInfo
  { txInfoId :: V3.TxId
  , txInfoInputs :: [TxInInfo]
  , txInfoReferenceInputs :: [TxInInfo]
  , txInfoOutputs :: [V2.TxOut]
  , txInfoFee :: Maybe V2.Lovelace
  , txInfoMint :: V3.MintValue
  , txInfoTxCerts :: [TxCert]
  , txInfoWithdrawals :: Map V2.Credential V2.Lovelace
  , txInfoDirectDeposits :: Map V2.Credential V2.Lovelace
  , txInfoAccountBalanceIntervals :: AccountBalanceIntervals
  , txInfoValidRange :: V2.POSIXTimeRange
  , txInfoGuards :: [V2.Credential]
  , txInfoRedeemers :: Map ScriptPurpose V2.Redeemer
  , txInfoData :: Map V2.DatumHash V2.Datum
  , txInfoVotes :: Map Voter (Map GovernanceActionId Vote)
  , txInfoProposalProcedures :: [ProposalProcedure]
  , txInfoCurrentTreasuryAmount :: Haskell.Maybe V2.Lovelace
  , txInfoTreasuryDonation :: Haskell.Maybe V2.Lovelace
  , txInfoLevelSpecific :: TxInfoLevelSpecific
  }

[lehins]

We also had a discussion with @colll78 about having a simplified version of, where all monoid like fields from all sub-transactions are mconcated together:

newtype TopTxInfo = TopTxInfo
  { topTxInfoSubTransactions :: [TxInfo]
  }

But I'd like to have the full version implemented first and have wider discussion about this later, before we dive too deep into this idea.

[colll78]

The above is missing the definition of ScriptContext. Would it be:

-- | The context that the currently-executing script can access.
data ScriptContext = ScriptContext
  { scriptContextTxInfo     :: TxInfo
  -- ^ information about the transaction the currently-executing script is included in
  , scriptContextRedeemer   :: V2.Redeemer
  -- ^ Redeemer for the currently-executing script
  , scriptContextScriptInfo :: ScriptInfo
  -- ^ the purpose of the currently-executing script, along with information associated
  -- with the purpose
  , scriptContextOwnScriptHash :: ScriptHash 
  -- ^ the hash of the currently-executing script. 
  }

Also I think the current proposed form of TxInfo is not desirable.

Instead it should be:

data TxInfo = 
   TopLevelTxInfo
     { txInfoId :: V3.TxId
     , txInfoInputs :: [TxInInfo]
     , txInfoReferenceInputs :: [TxInInfo]
     , txInfoOutputs :: [V2.TxOut]
     , txInfoFee :: Maybe V2.Lovelace
     , txInfoMint :: V3.MintValue
     , txInfoTxCerts :: [TxCert]
     , txInfoWithdrawals :: Map V2.Credential V2.Lovelace
     , txInfoDirectDeposits :: Map V2.Credential V2.Lovelace
     , txInfoAccountBalanceIntervals :: AccountBalanceIntervals
     , txInfoValidRange :: V2.POSIXTimeRange
     , txInfoGuards :: [V2.Credential]
     , txInfoRedeemers :: Map ScriptPurpose V2.Redeemer
     , txInfoData :: Map V2.DatumHash V2.Datum
     , txInfoVotes :: Map Voter (Map GovernanceActionId Vote)
     , txInfoProposalProcedures :: [ProposalProcedure]
     , txInfoCurrentTreasuryAmount :: Haskell.Maybe V2.Lovelace
     , txInfoTreasuryDonation :: Haskell.Maybe V2.Lovelace
     , topTxInfoSubTransactions :: [TxInfo]
     }
  | SubTxTxInfo 
      { txInfoId :: V3.TxId
      , txInfoInputs :: [TxInInfo]
      , txInfoReferenceInputs :: [TxInInfo]
      , txInfoOutputs :: [V2.TxOut]
      , txInfoFee :: Maybe V2.Lovelace
      , txInfoMint :: V3.MintValue
      , txInfoTxCerts :: [TxCert]
      , txInfoWithdrawals :: Map V2.Credential V2.Lovelace
      , txInfoDirectDeposits :: Map V2.Credential V2.Lovelace
      , txInfoAccountBalanceIntervals :: AccountBalanceIntervals
      , txInfoValidRange :: V2.POSIXTimeRange
      , txInfoGuards :: [V2.Credential]
      , txInfoRedeemers :: Map ScriptPurpose V2.Redeemer
      , txInfoData :: Map V2.DatumHash V2.Datum
      , txInfoVotes :: Map Voter (Map GovernanceActionId Vote)
      , txInfoProposalProcedures :: [ProposalProcedure]
      , txInfoCurrentTreasuryAmount :: Haskell.Maybe V2.Lovelace
      , txInfoTreasuryDonation :: Haskell.Maybe V2.Lovelace
      , txInfoRequiredTopLevelGuards :: Map Credential (Maybe Data)
    }

In the current proposed model, for a script to determine whether it is running in a top-level transaction, or a sub-transaction, it must traverse the entire script context and then pattern match on the TxInfoLevelSpecific field. This creates a lot of room for subtle exploits where script authors fail to account for this distinction, and the script succeeds only because it is executed in the wrong context. If we force script authors to pattern match on the TxInfo, then there is no room for such issues, they must consider whether the script is executing inside a sub-transaction or in a top-level transaction.

[michele-nuzzi]

I would personally prefer if signatories and "observer" scripts were in different lists, instead of having credentials of them

so no txInfoGuards instead preserve "required signers" and add an "observers" field

reason being that comparing only the hash is more efficient than comparing data (or even destructuring and then comparing).

It would be very rare to check for both script guards and pkh guards, and even then, it can be done checking the 2 lists instead of having to destructure every element of the guards list

especially with nested transacitons, it would be much more likely I'm only interested in checking for a given guard and ignore any pkh that could be there, and then eventually the guard would only check for pkh and ignore other guards

2 lists of hashes seem the only correct way to structure it imho