Figure out definitions of types and interface for top level vs sub-transactions

[lehins]

We need to create a new concept of a sub-transaction while avoiding unnecessary duplication.

The reason reason why this distinction is necessary is because sub-transaction have slight differences when comparing to the top level transaction. Here is an incomplete list of features that are different in sub-transactions:

• Missing collateral inputs and collateral return
• Missing fee field
• Redeemers are different
• sub-transactions are not allowed in sub-transactions
• sub-transactions will have requiredTopLevelObservers field

[lehins]

Here is an proof-of-concept definition of Tx related types that also includes CIP-112 as well as CIP-118

SubTx will be very similar to regular transaction, but will have different definitions for SubTxBody and SubTxWits. TxAuxData field is unchanged and isValid will likely be removed as unnecessary

data SubTx era = SubTx
    { txBody :: !(SubTxBody era)
    , txWits :: !(SubTxWits era)
    , -- , isValid :: !IsValid -- removed for sub transactions
      txAuxData :: !(StrictMaybe (TxAuxData era))
    }

SubTxBody has a few fields removed and one added: reTopLevelObservers:

data SubTxBody era = SubTxBody
    { inputs :: !(Set TxIn)
    , collateralInputs :: !(Set TxIn)
    , referenceInputs :: !(Set TxIn)
    , outputs :: !(StrictSeq (Sized (TxOut era)))
    , -- , collateralReturn :: !(StrictMaybe (Sized (TxOut era))) -- removed for sub transactions
      -- , totalCollateral :: !(StrictMaybe Coin) -- removed for sub transactions
      certs :: !(OSet.OSet (TxCert era))
    , withdrawals :: !Withdrawals
    , -- , fee :: !Coin -- Disabled
      vldt :: !ValidityInterval
    , -- , reqSignerHashes :: !(Set (KeyHash 'Witness)) -- deprecated in favor of `reqObservers`
      mint :: !MultiAsset
    , scriptIntegrityHash :: !(StrictMaybe ScriptIntegrityHash)
    , auxDataHash :: !(StrictMaybe TxAuxDataHash)
    , networkId :: !(StrictMaybe Network)
    , votingProcedures :: !(VotingProcedures era)
    , proposalProcedures :: !(OSet.OSet (ProposalProcedure era))
    , currentTreasuryValue :: !(StrictMaybe Coin)
    , treasuryDonation :: !Coin
    , -- New
      reqObservers :: [Credential 'Observer] -- CIP-112
    , reqTopLevelObservers :: [ReqObserver] -- new for the SubTxBody only
    }

ReqObserver can be either limited to only plutus scripts:

data ReqObserver = ReqObserver
    { reqObserver :: !ScriptHash
    -- ^ Hash of a plutus. Enforced by ledger to not be a native script
    , reqScriptData :: !Data
    -- ^ Argument that will be passed to the script

    -- With some changes to TxDats we could reduce potential duplication and use (Either DataHash Data) instead.
    }

or we could allow a full blown Credential, which would open some more use cases when CIP-112 is also utilized:

data ReqObserver = ReqObserver
    { reqObserver :: !(Credential 'Observer)
    -- ^ Key hash, or script hash of a plutus or native script
    , reqScriptData :: !(Maybe Data)
    -- ^ In case of a native script or a key hash it is a failure to supply this argument. In case of
    -- a plutus script this is an optional argument. If data is supplied for a plutus script then it
    -- will be executed as `SubTxObserverPurpose` otherwise it will have to be included 
    -- in the `reqObservers` of top level transaction, by the top level Tx builder
    }

TopTxBody is the same as before, except with changes specified in CIP-112 applied by adding reqObservers and subTransactions for CIP-118

data TopTxBody era = TopTxBody
    { inputs :: !(Set TxIn)
    , collateralInputs :: !(Set TxIn)
    , referenceInputs :: !(Set TxIn)
    , outputs :: !(StrictSeq (Sized (TxOut era)))
    , collateralReturn :: !(StrictMaybe (Sized (TxOut era)))
    , totalCollateral :: !(StrictMaybe Coin)
    , certs :: !(OSet.OSet (TxCert era))
    , withdrawals :: !Withdrawals
    , fee :: !Coin
    , vldt :: !ValidityInterval
    , -- , reqSignerHashes :: !(Set (KeyHash 'Witness)) -- replaced by a superior `reqObservers`
      mint :: !MultiAsset
    , scriptIntegrityHash :: !(StrictMaybe ScriptIntegrityHash)
    , auxDataHash :: !(StrictMaybe TxAuxDataHash)
    , networkId :: !(StrictMaybe Network)
    , votingProcedures :: !(VotingProcedures era)
    , proposalProcedures :: !(OSet.OSet (ProposalProcedure era))
    , currentTreasuryValue :: !(StrictMaybe Coin)
    , treasuryDonation :: !Coin
    , -- New
      reqObservers :: [Credential 'Observer] -- new for CIP-112
    , subTransactions :: [SubTx era] -- new for 'CIP-118 Nested Transactions'
    }

Only the type for Redeemers will need to change for sub-transactions, because there will be one extra plutus purpose for the top level transaction:

data SubTxWits era = SubTxWits
    { addrTxWits :: !(Set (WitVKey 'Witness))
    , bootAddrTxWits :: !(Set BootstrapWitness)
    , scriptTxWits :: !(Map ScriptHash (Script era))
    , datsTxWits :: !(TxDats era) -- Question?! Could we split extra and required into separate fields
    , rdmrsTxWits :: !(SubTxRedeemers era) -- Different from TopTx
    }

data SubTxRedeemers era = SubTxRedeemers
    { unRedeemers :: Map (BasePlutusPurpose AsIx era) (Data era, ExUnits)
    }

-- PlutusPurpose for subtransactions
data BasePlutusPurpose f era
    = BaseSpending !(f Word32 TxIn)
    | BaseMinting !(f Word32 PolicyID)
    | BaseCertifying !(f Word32 (TxCert era))
    | BaseRewarding !(f Word32 RewardAccount)
    | BaseVoting !(f Word32 Voter)
    | BaseProposing !(f Word32 (ProposalProcedure era))
    | BaseObservers !(f Word32 (Credential 'Observer)) -- New due to CIP-112

With respect to top level transaction, other than changes to the TxBody we only need to add one more PlutusPurpose, that will not be available for any of the sub-transactions:

-- Index of a sub-transaction in the `subTransactions` field.
type SubTxIx = Word32

-- The only part of the witnesses that will change is the definition of PlutusPurpose in the Redeemers.
data PlutusPurpose f era
    = BasePlutusPurpose !(BasePlutusPurpose f era)
    | SubTxReqObserver !SubTxIx !(f Word32 (Credential 'Observer))

Serialization

One important part that is worth noting about Nested Transactions is Serialization

Top Level Transaction

Changes to top level transaction will be backwards compatible when comparing to Conway era, aside from the new additions of functionality

Sub-Transactions

They will be mostly compatible at the serialization level, aside from semantic differences, like missing collateral inputs, missing fee field, etc. This will be done in order to improve reusability of the existing tooling for building sub-transactions.