Merge pull request #5394 from IntersectMBO/aniketd/certificate-cddl

CDDL: Consolidate certificates and pool params

Author: lehins

eras/allegra/impl/CHANGELOG.md

@@ -13,6 +13,7 @@
 
 ### `testlib`
 
+* Add CDDL definitions for int64 types: `int64`, `min_int64`, `max_int64`, `negative_int64`, `positive_int64`, `nonzero_int64`
 * Rename `native_script` -> `allegra_native_script` in CDDL
 * Add `auxiliary_data_array` to CDDL for simplification
 * Remove `metadata` redefinition in CDDL

eras/allegra/impl/cddl-files/allegra.cddl

@@ -38,14 +38,18 @@ vrf_vkey = bytes .size 32
 vrf_cert = [bytes, bytes .size 80]
 
 operational_cert = 
-  ( hot_vkey        : kes_vkey    
-  , sequence_number : uint .size 8
-  , kes_period      : uint        
-  , sigma           : signature   
+  ( hot_vkey        : kes_vkey       
+  , sequence_number : sequence_number
+  , kes_period      : kes_period     
+  , sigma           : signature      
   )
 
 kes_vkey = bytes .size 32
 
+sequence_number = uint .size 8
+
+kes_period = uint .size 8
+
 signature = bytes .size 64
 
 protocol_version = (major_protocol_version, uint)
@@ -121,18 +125,18 @@ address =
 coin = uint
 
 certificate = 
-  [  stake_registration
-  // stake_deregistration
-  // stake_delegation
-  // pool_registration
-  // pool_retirement
-  // genesis_key_delegation
+  [  account_registration_cert
+  // account_unregistration_cert
+  // delegation_to_stake_pool_cert
+  // pool_registration_cert
+  // pool_retirement_cert
+  // genesis_delegation_cert
   // move_instantaneous_rewards_cert
   ]
 
 
-; This will be deprecated in a future era
-stake_registration = (0, stake_credential)
+; This certificate will be deprecated in a future era
+account_registration_cert = (0, stake_credential)
 
 stake_credential = credential
 
@@ -153,14 +157,14 @@ hash28 = bytes .size 28
 ;   "\x04" for Plutus V4 scripts
 script_hash = hash28
 
-; This will be deprecated in a future era
-stake_deregistration = (1, stake_credential)
+; This certificate will be deprecated in a future era
+account_unregistration_cert = (1, stake_credential)
 
-stake_delegation = (2, stake_credential, pool_keyhash)
+delegation_to_stake_pool_cert = (2, stake_credential, pool_keyhash)
 
 pool_keyhash = hash28
 
-pool_registration = (3, pool_params)
+pool_registration_cert = (3, pool_params)
 
 pool_params = 
   ( operator       : pool_keyhash      
@@ -219,11 +223,11 @@ pool_metadata = [url, bytes]
 
 url = text .size (0 .. 64)
 
-pool_retirement = (4, pool_keyhash, epoch)
+pool_retirement_cert = (4, pool_keyhash, epoch)
 
 epoch = uint .size 8
 
-genesis_key_delegation = (5, genesis_hash, genesis_delegate_hash, vrf_keyhash)
+genesis_delegation_cert = (5, genesis_hash, genesis_delegate_hash, vrf_keyhash)
 
 genesis_hash = hash28
 
@@ -278,7 +282,7 @@ positive_int = 1 .. max_word64
 
 max_word64 = 18446744073709551615
 
-nonce = [0// 1, bytes .size 32]
+nonce = [0// 1, hash32]
 
 auxiliary_data_hash = hash32
 

eras/allegra/impl/testlib/Test/Cardano/Ledger/Allegra/CDDL.hs

@@ -13,17 +13,27 @@
 module Test.Cardano.Ledger.Allegra.CDDL (
   module Test.Cardano.Ledger.Shelley.CDDL,
   allegraCDDL,
+
+  -- * 64-bit integers
+  int64,
+  nonzero_int64,
+
+  -- * Transaction
   transaction_witness_set,
+
+  -- * Auxiliary data
   auxiliary_data,
   auxiliary_data_array,
-  auxiliary_scripts,
+
+  -- * Native scripts
   allegra_native_script,
 ) where
 
 import Cardano.Ledger.Allegra (AllegraEra)
 import Cardano.Ledger.Core (Era)
 import Codec.CBOR.Cuddle.Huddle
 import Data.Function (($))
+import GHC.Num (Integer)
 import Test.Cardano.Ledger.Shelley.CDDL
 import Text.Heredoc
 
@@ -34,6 +44,25 @@ allegraCDDL =
     , HIRule $ transaction @AllegraEra
     ]
 
+min_int64 :: Rule
+min_int64 = "min_int64" =:= (-9223372036854775808 :: Integer)
+
+max_int64 :: Rule
+max_int64 = "max_int64" =:= (9223372036854775807 :: Integer)
+
+negative_int64 :: Rule
+negative_int64 = "negative_int64" =:= min_int64 ... (-1 :: Integer)
+
+positive_int64 :: Rule
+positive_int64 = "positive_int64" =:= (1 :: Integer) ... max_int64
+
+nonzero_int64 :: Rule
+nonzero_int64 = "nonzero_int64" =:= negative_int64 / positive_int64
+
+-- | 64-bit signed integers for native script timelock thresholds.
+int64 :: Rule
+int64 = "int64" =:= min_int64 ... max_int64
+
 allegra_native_script :: Rule
 allegra_native_script =
   comment
@@ -84,12 +113,14 @@ auxiliary_data_array =
       , "auxiliary_scripts" ==> auxiliary_scripts
       ]
 
+-- | Adds auxiliary_data_array format for batching native scripts with metadata.
 auxiliary_data :: Rule
 auxiliary_data =
   "auxiliary_data"
     =:= metadata
     / auxiliary_data_array
 
+-- | Adds validity interval start (index 8) for timelock script support.
 transaction_body :: forall era. Era era => Rule
 transaction_body =
   comment
@@ -127,6 +158,7 @@ transaction =
       , a (auxiliary_data / VNil)
       ]
 
+-- | Uses allegra_native_script with timelock support (invalid_before/hereafter).
 transaction_witness_set :: Rule
 transaction_witness_set =
   "transaction_witness_set"

eras/alonzo/impl/CHANGELOG.md

@@ -38,6 +38,7 @@
 
 ### `testlib`
 
+* Add CDDL definitions for Plutus V1 types: `big_int`, `big_uint`, `big_nint`, `bounded_bytes`
 * Rename `plutus_script` -> `plutus_v1_script` in CDDL
 * Add `plutus_v1_script` to CDDL exports
 * Add `auxiliary_data_map` to CDDL for simplification

eras/alonzo/impl/cddl-files/alonzo.cddl

@@ -47,14 +47,18 @@ vrf_vkey = bytes .size 32
 vrf_cert = [bytes, bytes .size 80]
 
 operational_cert = 
-  ( hot_vkey        : kes_vkey    
-  , sequence_number : uint .size 8
-  , kes_period      : uint        
-  , sigma           : signature   
+  ( hot_vkey        : kes_vkey       
+  , sequence_number : sequence_number
+  , kes_period      : kes_period     
+  , sigma           : signature      
   )
 
 kes_vkey = bytes .size 32
 
+sequence_number = uint .size 8
+
+kes_period = uint .size 8
+
 signature = bytes .size 64
 
 protocol_version = (major_protocol_version, uint)
@@ -166,33 +170,33 @@ hash28 = bytes .size 28
 asset_name = bytes .size (0 .. 32)
 
 certificate = 
-  [  stake_registration
-  // stake_deregistration
-  // stake_delegation
-  // pool_registration
-  // pool_retirement
-  // genesis_key_delegation
+  [  account_registration_cert
+  // account_unregistration_cert
+  // delegation_to_stake_pool_cert
+  // pool_registration_cert
+  // pool_retirement_cert
+  // genesis_delegation_cert
   // move_instantaneous_rewards_cert
   ]
 
 
-; This will be deprecated in a future era
-stake_registration = (0, stake_credential)
+; This certificate will be deprecated in a future era
+account_registration_cert = (0, stake_credential)
 
 stake_credential = credential
 
 credential = [0, addr_keyhash// 1, script_hash]
 
 addr_keyhash = hash28
 
-; This will be deprecated in a future era
-stake_deregistration = (1, stake_credential)
+; This certificate will be deprecated in a future era
+account_unregistration_cert = (1, stake_credential)
 
-stake_delegation = (2, stake_credential, pool_keyhash)
+delegation_to_stake_pool_cert = (2, stake_credential, pool_keyhash)
 
 pool_keyhash = hash28
 
-pool_registration = (3, pool_params)
+pool_registration_cert = (3, pool_params)
 
 pool_params = 
   ( operator       : pool_keyhash      
@@ -251,11 +255,11 @@ pool_metadata = [url, bytes]
 
 url = text .size (0 .. 64)
 
-pool_retirement = (4, pool_keyhash, epoch)
+pool_retirement_cert = (4, pool_keyhash, epoch)
 
 epoch = uint .size 8
 
-genesis_key_delegation = (5, genesis_hash, genesis_delegate_hash, vrf_keyhash)
+genesis_delegation_cert = (5, genesis_hash, genesis_delegate_hash, vrf_keyhash)
 
 genesis_hash = hash28
 
@@ -341,7 +345,7 @@ positive_int = 1 .. max_word64
 
 max_word64 = 18446744073709551615
 
-nonce = [0// 1, bytes .size 32]
+nonce = [0// 1, hash32]
 
 cost_models = {* language => cost_model}
 

eras/alonzo/impl/testlib/Test/Cardano/Ledger/Alonzo/CDDL.hs

@@ -11,15 +11,26 @@
 module Test.Cardano.Ledger.Alonzo.CDDL (
   module Test.Cardano.Ledger.Mary.CDDL,
   alonzoCDDL,
-  certificates,
-  required_signers,
-  network_id,
+
+  -- * Plutus V1 data types
+  big_int,
+  bounded_bytes,
+
+  -- * Plutus V1 scripts
   plutus_v1_script,
-  redeemers,
   constr,
+
+  -- * Execution units
   ex_unit_prices,
   ex_units,
   positive_interval,
+
+  -- * Redeemers
+  redeemers,
+
+  -- * Transaction
+  required_signers,
+  network_id,
 ) where
 
 import Cardano.Ledger.Alonzo (AlonzoEra)
@@ -180,9 +191,6 @@ script_data_hash =
         |]
     $ "script_data_hash" =:= hash32
 
-certificates :: Rule
-certificates = "certificates" =:= arr [0 <+ a certificate]
-
 protocol_param_update :: Rule
 protocol_param_update =
   comment
@@ -244,9 +252,12 @@ proposed_protocol_parameter_updates =
   "proposed_protocol_parameter_updates"
     =:= mp [0 <+ asKey genesis_hash ==> protocol_param_update]
 
+-- | Adds Plutus protocol parameters: cost models, execution units, collateral settings (indices 16-24).
+-- Ref: CIP-28
 update :: Rule
 update = "update" =:= arr [a proposed_protocol_parameter_updates, a epoch]
 
+-- | Adds Plutus V1 scripts (index 3), datums (index 4), and redeemers (index 5) for smart contracts.
 transaction_witness_set :: Rule
 transaction_witness_set =
   comment
@@ -269,6 +280,31 @@ transaction_witness_set =
 redeemers :: Rule
 redeemers = "redeemers" =:= arr [0 <+ a redeemer]
 
+big_int :: Rule
+big_int = "big_int" =:= VInt / big_uint / big_nint
+
+big_uint :: Rule
+big_uint = "big_uint" =:= tag 2 bounded_bytes
+
+big_nint :: Rule
+big_nint = "big_nint" =:= tag 3 bounded_bytes
+
+bounded_bytes :: Rule
+bounded_bytes =
+  comment
+    [str|The real bounded_bytes does not have this limit. it instead has
+        |a different limit which cannot be expressed in CDDL.
+        |
+        |The limit is as follows:
+        | - bytes with a definite-length encoding are limited to size 0..64
+        | - for bytes with an indefinite-length CBOR encoding, each chunk is
+        |   limited to size 0..64
+        | ( reminder: in CBOR, the indefinite-length encoding of
+        | bytestrings consists of a token #2.31 followed by a sequence
+        | of definite-length encoded bytestrings and a stop code )
+        |]
+    $ "bounded_bytes" =:= VBytes `sized` (0 :: Word64, 64 :: Word64)
+
 plutus_v1_script :: Rule
 plutus_v1_script =
   comment
@@ -370,6 +406,7 @@ auxiliary_data_map =
           ]
       )
 
+-- | Adds auxiliary_data_map format (tag 259).
 auxiliary_data :: Rule
 auxiliary_data =
   comment
@@ -383,6 +420,7 @@ auxiliary_data =
       / auxiliary_data_array
       / auxiliary_data_map
 
+-- | Updates header_body to use Alonzo protocol_version.
 header :: Rule
 header = "header" =:= arr [a header_body, "body_signature" ==> kes_signature]