Merge #2165

2165: Update simple script documentation with Allegra time locking scripts r=kevinhammond a=Jimbo4350



Co-authored-by: Jordan Millar <jordan.millar@iohk.io>

doc/reference/multisig.md → doc/reference/simple-scripts.md

@@ -1,6 +1,6 @@
-# Multi signatures
+# Multisignatures
 
-Multi signature (multisig) is a Cardano Shelley feature that consists of a set of schemes and a simple scripting language. Multisig schemes are used for payment and delegation purposes, specifying one or more combinations of cryptographic signatures needed to authorize a transaction. Multisig allows value addresses and stake addresses to use either keypairs or scripts to authorize and process a transaction.
+Multisignature (multisig) is a Cardano Shelley feature that consists of a set of schemes and a simple scripting language. Multisig schemes are used for payment and delegation purposes, specifying one or more combinations of cryptographic signatures needed to authorize a transaction. Multisig allows value addresses and stake addresses to use either keypairs or scripts to authorize and process a transaction.
 
 In Shelley, an address must provide information on how to spend ada and how to control the associated stake. For these reasons, there are two types of addresses: *payment addresses* and *stake addresses*.
 
@@ -9,7 +9,7 @@ Addresses are objects that have a user-facing binary representation, which means
 + **Key credential** - a credential can be constructed from a pair of a *signing key (sk)* and a corresponding *verification key (vk)*. The credential is a cryptographic hash of the verification key *H(vk)*. A witness for a key credential consists of the *vk* and a transaction signature of the *sk*.
 + **Script credential** - tokens and stake can also be controlled by a validator script, which can either succeed or fail to validate on a given input. In this case, the credential is the hash of the script. A witness for a script credential is the script itself, as well as a script input that makes it valid.
 
-## Multi signature scripts
+## Multisignature scripts
 
 In Shelley, multisig script credentials are used to require signatures from multiple parties to validate a transaction. Examples include M of N schemes, where a transaction can be authorized if at least *M* distinct keys, from a set of *N* keys, sign the transaction. With multisig script credentials, it is possible to require single or multiple signatures both for funds spending and stake delegation purposes. Using multisig scripts, a witness should include the validator script matching the hash in the script credential, and a set of witnesses for individual key credentials. The validator script will determine whether those witnesses are sufficient for the funds to be spent.
 
@@ -133,21 +133,21 @@ The `type` key's value `atLeast` indicates that in order to spend this tx output
 }
 ```
 
-### Example of using multi signature scripts
+### Example of using multisignature scripts
 
-Below is an example that specifies how to use a multi signature script. This is a step-by-step process involving:
+Below is an example that specifies how to use a multisignature script. This is a step-by-step process involving:
 
-+ the creation of a multi signature address
++ the creation of a multisignature address
 + sending ada to that address
-+ gathering required witnesses in order to spend ada from the multi signature address.
++ gathering required witnesses in order to spend ada from the multisignature address.
 
 The process is an example based on using the `all` script.
 
 #### Sending ada to a script address
 
-#### Step 1 - create a multi signature script
+#### Step 1 - create a multisignature script
 
-First, generate the keys that you require witnessing from using the `cardano-cli shelley address key-gen` command. Then, construct a multi signature script as described above. For this example, we will describe the process using an `all` multisig script (`allMultiSigScript`) as follows:
+First, generate the keys that you require witnessing from using the `cardano-cli shelley address key-gen` command. Then, construct a multisignature script as described above. For this example, we will describe the process using an `all` multisig script (`allMultiSigScript`) as follows:
 
 ```json
 {
@@ -169,9 +169,9 @@ First, generate the keys that you require witnessing from using the `cardano-cli
 }
 ```
 
-#### Step 2 - create a multi signature address
+#### Step 2 - create a multisignature address
 
-A multi signature address is required in order to use a multi signature script. Please note that network parameters must match with your personal network’s parameters (if you are on mainnet, use the `--mainnet flag`). Construct this as follows:
+A multisignature address is required in order to use a multisignature script. Please note that network parameters must match with your personal network’s parameters (if you are on mainnet, use the `--mainnet flag`). Construct this as follows:
 
 ```
 cardano-cli shelley address build-script
@@ -180,9 +180,9 @@ cardano-cli shelley address build-script
   --out-file script.addr
 ```
 
-#### Step 3 - construct and submit a transaction (tx) to the multi signature address
+#### Step 3 - construct and submit a transaction (tx) to the multisignature address
 
-To construct and submit a tx to send ada to the multi signature address, construct the tx body:
+To construct and submit a tx to send ada to the multisignature address, construct the tx body:
 
 ```bash
 cardano-cli shelley transaction build-raw
@@ -212,7 +212,7 @@ cardano-cli shelley transaction assemble
   --out-file allWitnessesTx
 ```
 
-After submitting the above tx, the inputs associated with the multi signature address will be "guarded" by the multi signature script.
+After submitting the above tx, the inputs associated with the multisignature address will be "guarded" by the multisignature script.
 
 ### Sending ada from a script address
 
@@ -271,3 +271,98 @@ cardano-cli shelley transaction assemble \
   --out-file spendMultiSig
 ```
 You can now submit this tx via `cardano-cli shelley transaction submit`!
+
+
+# Simple Script
+
+In the Allegra era, we introduce the ability to time lock your multisignature scripts. From now on we will refer to these scripts (collectively) as simple scripts and differentiate them based on the era they are present in and which features are available. That is, in the Shelley era we do not have time locking available in our scripts but in the Allegra era we do.
+
+NB: If you specify `"type": "any"` this will allow you to spend from your script address regardless of what time lock you have declared.
+
+## Bounds
+
+It is important to understand the bounds on a transaction and how they relate to the time locking scripts. Previously we had a `ttl` argument in the cli which was an upper bound on a transaction i.e the transaction was valid up until that slot number. This has been replaced with `--invalid-before` and `--invalid-hereafter` arguments as described below:
+
+```
+If you specify a lower bound on a transaction it is valid from the invalid-before slot (IBS):
+
+      [IBS, +infinity)
+
+If you specify an upper bound on a transaction it is valid to invalid-hereafter slot - 1 (IHS - 1):
+
+      (-infinity, IHS)
+
+If you specify both bounds the tx is valid from the IBS to the IHS - 1
+
+      [IBS, IHS)
+```
+Whichever bound you specify, the slot number in which you submit your transaction has to be within that bound. For example
+if you submit your transaction in slot 500 and you specify a `--invalid-before` slot of 600 then your transaction will be rejected.
+
+This also applies to time locking scripts. If you specify a time lock script with `after: 1000` you must specify a `--invalid-before` of at least 1000 and therefore also submit that transaction in or after slot 1000.
+
+Conversely, if you specify a time lock script with `before: 500` you must specify an `--invalid-hereafter` slot of at most 500 and submit the transaction before slot 500. NB: `before: 500` means the transaction is expired in slot 500.
+
+Once you have generated your time locked script you need to follow all the same steps above for a multisignature script with a slight modification of [step 1](#Step-1---construct-the-tx-body) which needs to be amended as follows:
+
+Examples of the time locking scripts are:
+
+## After
+
+```json
+{
+    "scripts": [
+        {
+            "keyHash": "966e394a544f242081e41d1965137b1bb412ac230d40ed5407821c37",
+            "type": "sig"
+        },
+        {
+            "slot": 1000,
+            "type": "after"
+        }
+    ],
+    "type": "all"
+}
+```
+For `after` scripts we must provide a `--invalid-before` slot that is greater than or equal to the specified slot number in our simple script. In the example above this means >= 1000.
+
+```bash
+cardano-cli shelley transaction build-raw \
+    --ttl 1000 \
+    --invalid-before 1000\
+    --fee 0 \
+    --tx-in (txin of script address)
+    --tx-out yourspecifiedtxout \
+    --out-file spendScriptTxBody
+```
+
+## Before
+
+```json
+{
+    "scripts": [
+        {
+            "keyHash": "966e394a544f242081e41d1965137b1bb412ac230d40ed5407821c37",
+            "type": "sig"
+        },
+        {
+            "slot": 3000,
+            "type": "before"
+        }
+    ],
+    "type": "all"
+}
+```
+
+For before scripts we must provide a `--invalid-hereafter` slot that is less than or equal to the specified slot number in our simple script. In the example above this means <= 3000:
+
+```bash
+cardano-cli shelley transaction build-raw \
+    --ttl 1000 \
+    --invalid-hereafter 3000\
+    --fee 0 \
+    --tx-in (txin of script address)
+    --tx-out yourspecifiedtxout \
+    --out-file spendScriptTxBody
+```
+