feat(applying): ShelleyMA phase-1 validations

pallas-applying/docs/shelleyMA-validation-rules.md

@@ -0,0 +1,108 @@
+# ShelleyMA transaction validation rules
+
+This document covers the Shelley era, including its Allegra and Mary hard forks. We write *ShelleyMA* to refer to any of these ledger versions, and *Shelley*, *Allegra* or *Mary* when the discrimination is relevant. This document covers only the concepts, notation and validation rules realted to phase-1 validation in these ledger versions. For further information, refer to the corresponding white paper listed below:
+- [Shelley's ledger white paper](https://github.com/input-output-hk/cardano-ledger/releases/latest/download/shelley-ledger.pdf)
+- [Both Allegra's and Mary's ledger white paper](https://github.com/input-output-hk/cardano-ledger/releases/latest/download/mary-ledger.pdf)
+
+## Definitions and notation
+- **Scripts**:
+ - ***Script*** is the set of all possible native scripts.
+- **Transactions**:
+ - ***Tx*** is the set of ShelleyMA transactions, composed of a transaction body and the set of witnesses.
+ - ***TxBody*** is the type of ShelleyMA transaction bodies. Each transaction body is composed of a set of inputs and a list of outputs.
+ - ***txBody(tx)*** is the transaction body of the transaction.
+ - ***TxOut = Addr x TA*** is the set of transaction outputs, where
+ - ***Addr*** is the set of transaction output addresses.
+ - ***TA = ℕ*** in Shelley and Allegra, while ***TA = Value*** in Mary, where ***Value*** is the type of multi-asset Mary values.
+ - ***txOuts(txBody) ∈ P(TxOut)*** gives the set of transaction outputs of a transaction body.
+ - ***balance : P(TxOut) → TA*** gives the sum of all lovelaces in a set of transaction outputs in Shelley and Allegra, while it gives the sum of all assets in a set of transaction outputs in Mary. That is, ***TA = ℕ*** in Shelley and Allegra, and ***TA = Value*** in Mary.
+ - ***TxIn = TxId x Ix*** is the set of transaction inputs, where
+ - ***TxId*** is the set of transaction IDs.
+ - ***Ix = ℕ*** is the set of indices (used to refer to a specific transaction output).
+ - ***txIns(txBody) ∈ P(TxIn)*** gives the set of transaction inputs of the transaction.
+ - ***utxo : TxIn → TxOut*** is a (partial) map that gives the unspent transaction output (UTxO) associated with a transaction input.
+ - Given ***A ⊆ dom(utxo)***, we will write ***A ◁ utxo := {to ∈ TxOut / ∃ ti ∈ dom utxo: utxo(ti) = to}***. Thus, we will write ***txIns(tx) ◁ utxo := {to ∈ TxOut / ∃ ti ∈ dom(utxo): utxo(ti) = to}*** to express the set of unspent transaction outputs associated with the set of transaction inputs of the transaction ***tx***.
+ - ***txTTL(txBody) ∈ Slot*** is the time-to-live of the transaction.
+ - ***txSize(Tx) ∈ ℕ*** gives the size of the transaction.
+ - ***fee(txBody) ∈ ℕ*** gives the fee paid by a transaction.
+ - ***minted(txBody)*** is the multiasset value minted (or burned) in the transaction.
+ - ***txInsScript(txBody) ⊆ P(TxIn)*** is the list of script inputs in the transaction body.
+ - ***consumed(pps, utxo, txBody) ∈ ℤ*** is the *consumed value* of the transaction.
+ - In Shelley and Allegra, this equals the sum of all lovelace in the transaction inputs.
+ - In Mary, this equals the sum of all multiasset values in the transaction inputs.
+ - ***produced(pps, txBody) ∈ ℤ*** is the *produced value* of the transaction.
+ - In Shelley and Allegra, this equals the sum of all lovelace in the transaction outputs plus the transaction fee.
+ - In Mary, this equals the sum of all multiasset values in the outputs of the transaction plus the transaction fee plus the minted value.
+ - **Transaction metadata**:
+ - ***txMD(tx)*** is the metadata of the transaction.
+ - ***txMDHash(txBody)*** is the metadata hash contained within the transaction body.
+ - ***hashMD(md)*** is the result of hasing metadata ***md***.
+- **Addresses*:
+ - ***Addr*** is the set of all valid ShelleyMA addresses.
+ - ***netId(addr)*** is the network ID of the address.
+ - ***NetworkId*** is the global network ID.
+- ***Slots***:
+ - ***Slot ∈ ℕ*** is the set of slots. When necessary, we write ***slot ∈ Slot*** to refer to the slot associated to the current block.
+- **Serialization**:
+ - ***Bytes*** is the set of byte arrays (a.k.a. data, upon which signatures are built).
+ - ***⟦_⟧<sub>A</sub> : A -> Bytes*** takes an element of type ***A*** and returns a byte array resulting from serializing it.
+- **Hashing**:
+ - ***KeyHash ⊆ Bytes*** is the set of fixed-size byte arrays resulting from hashing processes.
+ - ***hash: Bytes -> KeyHash*** is the hashing function.
+ - ***paymentCredential<sub>utxo</sub>(txIn) ∈ KeyHash*** gets from ***txIn*** the associated transaction output in ***utxo***, extracts the address contained in it, and returns its hash. In other words, given ***utxo*** and transaction input ***txIn*** such that ***utxo(txIn) = (a, _)***, we have that ***paymentCredential<sub>utxo</sub>(txIn) = hash(a)***.
+- **Protocol Parameters**:
+ - We will write ***pps ∈ PParams*** to represent the set of (ShelleyMA) protocol parameters, with the following associated functions:
+ - ***minFees(pps, txBody) ∈ ℕ*** gives the minimum number of lovelace that must be paid for the transaction as fee.
+ - ***maxTxSize(pps) ∈ ℕ*** gives the (global) maximum transaction size.
+ - ***minUTxOValue(pps) ∈ ℕ***, the global minimum number of lovelace every UTxO must lock.
+- ***Witnesses***:
+ - ***VKey*** is the set of verification keys (a.k.a. public keys).
+ - ***SKey*** is the set of signing keys (a.k.a. private keys).
+ - ***Sig*** is the set of signatures (i.e., the result of signing a byte array using a signing key).
+ - ***sig : SKey x Bytes -> Sig*** is the signing function.
+ - ***verify : VKey x Sig x Bytes -> Bool*** assesses whether the verification key applied to the signature yields the byte array as expected.
+ - The assumption is that if ***sk*** and ***vk*** are, respectively, a pair of secret and verification keys associated with one another. Thus, if ***sig(sk, d) = σ***, then it must be that ***verify(vk, σ, d) = true***.
+ - ***txVKWits(tx) ∈ P(VKey x Sig)*** gives the list of pairs of verification keys and signatures of the transaction.
+ - ***txScriptWits(tx) ⊆ P(Script)*** is the set of script witnesses of the transaction.
+
+## Validation rules
+Let ***tx ∈ Tx*** be a ShelleyMA transaction whose body is ***txBody ∈ TxBody***. ***tx*** is a phase-1 valid transaction if and only if
+
+- **The set of transaction inputs is not empty**:
+
+ <code>txIns(txBody) ≠ ∅</code>
+- **All transaction inputs are in the set of (yet) unspent transaction outputs**:
+
+ <code>txIns(txBody) ⊆ dom(utxo)</code>
+- **The TTL limit of the transaction has not been exceeded**:
+
+ <code>slot ≥ txTTL(txBody)</code>
+- **The transaction size does not exceed the protocol limit**:
+
+ <code>txSize(tx) ≤ maxTxSize(pps)</code>
+- **All transaction outputs contain Lovelace values not under the minimum**:
+
+ <code>∀ (_, c) ∈ txOuts(txBody): minUTxOValue(pps) ≤ c</code>
+- **The preservation of value property holds**: Assuming no staking or delegation actions are involved, this property takes one of the two forms below:
+ - In Shelley and Allegra, the equation for the preservation of value is
+
+ <code>consumed(pps, utxo, txBody) = produced(pps, poolParams, txBody) + fee(txBody)</code>,
+ - In Mary, the equation is:
+
+ <code>consumed(pps, utxo, txBody) = produced(pps, poolParams, txBody) + fee(txBody) + minted(txBody) </code>,
+- **The fee paid by the transaction has to be greater than or equal to the minimum fee**:
+
+ <code>fee(txBody) ≥ minFees(pps, tx)</code>
+- **The network ID of each output matches the global network ID**:
+
+ <code>∀(_ -> (a, _)) ∈ txOuts(txBody): netId(a) = NetworkId</code>
+- **The metadata of the transaction is valid**:
+
+ <code>txMDHash(tx) = hashMD(txMD(tx))</code>
+- **Verification-key witnesses**: The owner of each transaction input signed the transaction. That is, given transaction ***tx*** with body ***txBody***, then for each ***txIn ∈ txIns(txBody)*** there must exist ***(vk, σ) ∈ txVKWits(tx)*** such that:
+
+ - <code>verify(vk, σ, ⟦txBody⟧<sub>TxBody</sub>)</code>
+ - <code>paymentCredential<sub>utxo</sub>(txIn) = hash(vk)</code>
+- **Script witnesses**: Each script address has a corresponding witness:
+
+ <code>∀ (script_hash, _) ∈ txInsScript(txBody) ◁ utxo : ∃ script ∈ txScriptWits(tx): hash(script) = script_hash</code>

pallas-applying/src/byron.rs

@@ -3,7 +3,9 @@
 use std::borrow::Cow;
 
 use crate::types::{
- ByronProtParams, MultiEraInput, MultiEraOutput, SigningTag, UTxOs, ValidationError,
+ ByronError::*,
+ ByronProtParams, MultiEraInput, MultiEraOutput, SigningTag, UTxOs,
+ ValidationError::{self, *},
  ValidationResult,
 };
 
@@ -30,34 +32,34 @@ pub fn validate_byron_tx(
  prot_magic: &u32,
 ) -> ValidationResult {
  let tx: &Tx = &mtxp.transaction;
- let size: u64 = get_tx_size(tx)?;
+ let size: &u64 = &get_tx_size(tx)?;
  check_ins_not_empty(tx)?;
  check_outs_not_empty(tx)?;
  check_ins_in_utxos(tx, utxos)?;
  check_outs_have_lovelace(tx)?;
- check_fees(tx, &size, utxos, prot_pps)?;
- check_size(&size, prot_pps)?;
+ check_fees(tx, size, utxos, prot_pps)?;
+ check_size(size, prot_pps)?;
  check_witnesses(mtxp, utxos, prot_magic)
 }
 
 fn check_ins_not_empty(tx: &Tx) -> ValidationResult {
  if tx.inputs.clone().to_vec().is_empty() {
- return Err(ValidationError::TxInsEmpty);
+ return Err(Byron(TxInsEmpty));
  }
  Ok(())
 }
 
 fn check_outs_not_empty(tx: &Tx) -> ValidationResult {
  if tx.outputs.clone().to_vec().is_empty() {
- return Err(ValidationError::TxOutsEmpty);
+ return Err(Byron(TxOutsEmpty));
  }
  Ok(())
 }
 
 fn check_ins_in_utxos(tx: &Tx, utxos: &UTxOs) -> ValidationResult {
  for input in tx.inputs.iter() {
  if !(utxos.contains_key(&MultiEraInput::from_byron(input))) {
- return Err(ValidationError::InputMissingInUTxO);
+ return Err(Byron(InputNotInUTxO));
  }
  }
  Ok(())
@@ -66,7 +68,7 @@ fn check_ins_in_utxos(tx: &Tx, utxos: &UTxOs) -> ValidationResult {
 fn check_outs_have_lovelace(tx: &Tx) -> ValidationResult {
  for output in tx.outputs.iter() {
  if output.amount == 0 {
- return Err(ValidationError::OutputWithoutLovelace);
+ return Err(Byron(OutputWithoutLovelace));
  }
  }
  Ok(())
@@ -84,7 +86,7 @@ fn check_fees(tx: &Tx, size: &u64, utxos: &UTxOs, prot_pps: &ByronProtParams) ->
  .and_then(MultiEraOutput::as_byron)
  {
  Some(byron_utxo) => inputs_balance += byron_utxo.amount,
- None => return Err(ValidationError::UnableToComputeFees),
+ None => return Err(Byron(UnableToComputeFees)),
  }
  }
  if only_redeem_utxos {
@@ -95,9 +97,9 @@ fn check_fees(tx: &Tx, size: &u64, utxos: &UTxOs, prot_pps: &ByronProtParams) ->
  outputs_balance += output.amount
  }
  let total_balance: u64 = inputs_balance - outputs_balance;
- let min_fees: u64 = prot_pps.min_fees_const + prot_pps.min_fees_factor * size;
+ let min_fees: u64 = prot_pps.fee_policy.summand + prot_pps.fee_policy.multiplier * size;
  if total_balance < min_fees {
- Err(ValidationError::FeesBelowMin)
+ Err(Byron(FeesBelowMin))
  } else {
  Ok(())
  }
@@ -119,7 +121,7 @@ fn is_redeem_utxo(input: &TxIn, utxos: &UTxOs) -> bool {
 
 fn check_size(size: &u64, prot_pps: &ByronProtParams) -> ValidationResult {
  if *size > prot_pps.max_tx_size {
- return Err(ValidationError::MaxTxSizeExceeded);
+ return Err(Byron(MaxTxSizeExceeded));
  }
  Ok(())
 }
@@ -128,7 +130,7 @@ fn get_tx_size(tx: &Tx) -> Result<u64, ValidationError> {
  let mut buff: Vec<u8> = Vec::new();
  match encode(tx, &mut buff) {
  Ok(()) => Ok(buff.len() as u64),
- Err(_) => Err(ValidationError::UnknownTxSize),
+ Err(_) => Err(Byron(UnknownTxSize)),
  }
 }
 
@@ -149,7 +151,7 @@ fn check_witnesses(mtxp: &MintedTxPayload, utxos: &UTxOs, prot_magic: &u32) -> V
  let data_to_verify: Vec<u8> = get_data_to_verify(sign, prot_magic, &tx_hash)?;
  let signature: Signature = get_signature(sign);
  if !public_key.verify(data_to_verify, &signature) {
- return Err(ValidationError::WrongSignature);
+ return Err(Byron(WrongSignature));
  }
  }
  Ok(())
@@ -165,7 +167,7 @@ fn tag_witnesses(wits: &[Twit]) -> Result<Vec<(&PubKey, TaggedSignature)>, Valid
  Twit::RedeemWitness(CborWrap((pk, sig))) => {
  res.push((pk, TaggedSignature::RedeemWitness(sig)));
  }
- _ => return Err(ValidationError::UnableToProcessWitnesses),
+ _ => return Err(Byron(UnableToProcessWitness)),
  }
  }
  Ok(res)
@@ -175,9 +177,9 @@ fn find_tx_out<'a>(input: &'a TxIn, utxos: &'a UTxOs) -> Result<&'a TxOut, Valid
  let key: MultiEraInput = MultiEraInput::Byron(Box::new(Cow::Borrowed(input)));
  utxos
  .get(&key)
- .ok_or(ValidationError::InputMissingInUTxO)?
+ .ok_or(Byron(InputNotInUTxO))?
  .as_byron()
- .ok_or(ValidationError::InputMissingInUTxO)
+ .ok_or(Byron(InputNotInUTxO))
 }
 
 fn find_raw_witness<'a>(
@@ -187,19 +189,19 @@ fn find_raw_witness<'a>(
  let address: ByronAddress = mk_byron_address(&tx_out.address);
  let addr_payload: AddressPayload = address
  .decode()
- .map_err(|_| ValidationError::UnableToProcessWitnesses)?;
+ .map_err(|_| Byron(UnableToProcessWitness))?;
  let root: AddressId = addr_payload.root;
  let attr: AddrAttrs = addr_payload.attributes;
  let addr_type: AddrType = addr_payload.addrtype;
  for (pub_key, sign) in witnesses {
  if redeems(pub_key, sign, &root, &attr, &addr_type) {
  match addr_type {
  AddrType::PubKey | AddrType::Redeem => return Ok((pub_key, sign)),
- _ => return Err(ValidationError::UnableToProcessWitnesses),
+ _ => return Err(Byron(UnableToProcessWitness)),
  }
  }
  }
- Err(ValidationError::MissingWitness)
+ Err(Byron(MissingWitness))
 }
 
 fn mk_byron_address(addr: &Address) -> ByronAddress {
@@ -250,17 +252,17 @@ fn get_data_to_verify(
  match sign {
  TaggedSignature::PkWitness(_) => {
  enc.encode(SigningTag::Tx as u64)
- .map_err(|_| ValidationError::UnableToProcessWitnesses)?;
+ .map_err(|_| Byron(UnableToProcessWitness))?;
  }
  TaggedSignature::RedeemWitness(_) => {
  enc.encode(SigningTag::RedeemTx as u64)
- .map_err(|_| ValidationError::UnableToProcessWitnesses)?;
+ .map_err(|_| Byron(UnableToProcessWitness))?;
  }
  }
  enc.encode(prot_magic)
- .map_err(|_| ValidationError::UnableToProcessWitnesses)?;
+ .map_err(|_| Byron(UnableToProcessWitness))?;
  enc.encode(tx_hash)
- .map_err(|_| ValidationError::UnableToProcessWitnesses)?;
+ .map_err(|_| Byron(UnableToProcessWitness))?;
  Ok(enc.into_writer().clone())
 }
 

pallas-applying/src/lib.rs

@@ -1,24 +1,41 @@
 //! Logic for validating and applying new blocks and txs to the chain state
 
 pub mod byron;
+pub mod shelley_ma;
 pub mod types;
 
 use byron::validate_byron_tx;
+use pallas_traverse::{Era, MultiEraTx};
+use shelley_ma::validate_shelley_ma_tx;
 
-use pallas_traverse::{MultiEraTx, MultiEraTx::Byron as ByronTxPayload};
-
-pub use types::{Environment, MultiEraProtParams, UTxOs, ValidationResult};
+pub use types::{
+ Environment, MultiEraProtParams, UTxOs, ValidationError::TxAndProtParamsDiffer,
+ ValidationResult,
+};
 
 pub fn validate(metx: &MultiEraTx, utxos: &UTxOs, env: &Environment) -> ValidationResult {
- match (metx, env) {
- (
- ByronTxPayload(mtxp),
- Environment {
- prot_params: MultiEraProtParams::Byron(bpp),
- prot_magic,
+ match env {
+ Environment {
+ prot_params: MultiEraProtParams::Byron(bpp),
+ prot_magic,
+ ..
+ } => match metx {
+ MultiEraTx::Byron(mtxp) => validate_byron_tx(mtxp, utxos, bpp, prot_magic),
+ _ => Err(TxAndProtParamsDiffer),
+ },
+ Environment {
+ prot_params: MultiEraProtParams::Shelley(spp),
+ block_slot,
+ network_id,
+ ..
+ } => match metx.era() {
+ Era::Shelley | Era::Allegra | Era::Mary => match metx.as_alonzo() {
+ Some(mtx) => {
+ validate_shelley_ma_tx(mtx, utxos, spp, block_slot, network_id, &metx.era())
+ }
+ None => Err(TxAndProtParamsDiffer),
  },
- ) => validate_byron_tx(mtxp, utxos, bpp, prot_magic),
- // TODO: implement the rest of the eras.
- _ => Ok(()),
+ _ => Err(TxAndProtParamsDiffer),
+ },
  }
 }