Merge pull request #2883 from input-output-hk/jordan/plutus-minting-docs

Add Plutus minting script doc

Author: Jimbo4350

doc/reference/plutus/plutus-minting-script-example.md

@@ -0,0 +1,80 @@
+# Plutus Minting Scripts
+
+## What is a Plutus minting script?
+
+A Plutus minting script is required to validate the minting of multi-asset tokens. Unlike Mary-era scripts, Plutus scripts support more logic beyond required signatures and timelocks.
+
+### An example of using a Plutus minting script
+
+Below is an example that shows how to use a Plutus minting script. This is a step-by-step
+process involving:
+
++ the creation of the `AlwaysSucceeds` Plutus minting script (i.e. anybody can mint)
++ the creation of a transaction that mints multi-assets using the `AlwaysSucceeds` Plutus minting script
+
+In this example we will use the [anyone can mint](../../../plutus-example/plutus-example/src/Cardano/PlutusExample/MintingScript.hs) Plutus minting script. To execute it, we require the following:
+
+- Collateral tx input(s) that are provided and forfeited if the Plutus script fails to execute.
+- Serialization of the Plutus script in the text envelope format (required for cardano-cli).
+- A redeemer.
+
+#### Creating the `AlwaysSucceeds` Plutus minting script
+
+The plutus-example executable will automagically generate several Plutus scripts in the CLI-compatible text envelope format.
+
+Run the following commands:
+
+```bash
+cd plutus-example
+
+cabal run exe:plutus-example
+```
+
+This will output `anyone-can-mint.plutus` in the `generated-plutus-scripts` dir.
+
+#### Setting up a local Alonzo node cluster
+
+First follow the [install doc](../../../doc/getting-started/install.md) if you haven't. This convenient script will set up an Alonzo cluster immediately on your local machine:
+
+```bash
+./scripts/byron-to-alonzo/mkfiles.sh alonzo
+```
+
+Follow the instructions displayed in the terminal to start your Alonzo cluster.
+
+#### Minting multi-assets using the Plutus minting script
+
+To mint a multi-asset, you need the Plutus script policy ID and a redeemer. Because this minting script always succeeds, you can use any redeemer:
+
+```
+$ cardano-cli transaction policyid --script-file scripts/plutus/scripts/anyone-can-mint.plutus
+> $policyid
+```
+
+You can find an example redeemer at: `scripts/plutus/data/42.redeemer`
+
+For more information regarding `tx-in-collateral` see [here](plutus-spending-script-example.md).
+
+```bash
+cardano-cli transaction build \
+  --babbage-era \
+  --cardano-mode \
+  --tx-in "$txin" \
+  --tx-in-collateral "$txinCollateral" \
+  --mint "5 $policyid.4D696C6C6172436F696E0A" \
+  --mint-script-file "scripts/plutus/scripts/anyone-can-mint.plutus" \
+  --mint-redeemer-file "scripts/plutus/data/42.redeemer" \
+  --tx-out "$dummyaddress+$spendable + 5 $policyid.4D696C6C6172436F696E0A" \
+  --protocol-params-file pparams.json \
+  --out-file "plutusmint.body"
+
+cardano-cli transaction sign \
+  --tx-body-file "plutusmint.body" \
+  --testnet-magic 42 \
+  --signing-key-file "$skey" \
+  --out-file "plutusmint.tx"
+```
+
+You can use the [simple-minting-policy.sh](../../../scripts/plutus/simple-minting-policy.sh) in conjunction with the [mkfiles.sh alonzo](../../../scripts/byron-to-alonzo/mkfiles.sh) script to automagically run the `AlwaysSucceeds` minting script.
+
+

plutus-example/example-scripts/anyone-can-mint.plutus

@@ -0,0 +1,5 @@
+{
+    "type": "PlutusScriptV1",
+    "description": "",
+    "cborHex": "59156959156601000032003320020033320020020033333320020020020020020032003332002002003320020032003332002002003200333200200200332002003200333333332002002002002002002002003200320033200200320033333200200200200200320032003200333320020020020032003200332002003200332002003200332002003200320032003332002002003200320032003200320033200200320032003200320032003200320033200200320032003200320032003200320032003200320032003200320032003200320032003320020032003320020032003320020032003320020032003200320033500130631200001200200064120020020020033353506933504200400220020033353506b300800320020033353067330070040022000632003500a063062200350080610602003500605f05e120062003333335306800120020050672002002003335350710022005069200200200333535074002200506c200200200333535077002200333530683306700a48000800ccd4d41bcc03c020800800ccd4d41c4c14401c800800d41d4cc04801000880141cc19880141c419080141c018c80080080141c418817c170800801419c800801419c800801419c1648008004800cc00400c008800004800cccccd4c1940048008014190800800800ccd4d41b80088014198800800800ccd4d41c400880141a4800800800ccd4d41d000880141b0800800800ccd4d41dc00880141bc800800800ccd4d41e800880141c8800800800ccd4d41f400880141d4800800800ccd4d42000400880141e0800800800ccd4d420c0400880141ec800800800ccd4d42180400880141f8800800800ccd4d422404008801420404800800800ccd4d423004008800ccd4c1f4cc1f0089200020033333353088010202002005087012002002005088012002005087012002003335350860133355530391200001303f12000010290022002003333335308c01021200200508b01200200200508c01200200508b0120020033353508a01333555303d1200001304312000010300022002003333335309001022200200508f01200200200509001200200508f0120020033353508e0133355530411200001304712000013037120000100220020033333353094010232002005093012002002005094012002005093012002003335350920133355530451200001304b1200001303b120000100220020033333353098010242002005097012002002005098012002005097012002003335350960133355530491200001304f1200001080010022002003333335309c01025200200509b01200200200509c01200200509b0120020033353509a01333555304d1200001305312000013355052306012000013058120000100220020033353509c0133506b30691200001026200200333333530a20102520020050a10120020020050a20120020050a1012002003335350a0013335553053120000130591200001061002200200333333530a60102620020050a50120020020050a60120020050a5012002003335350a40133355530571200001305d1200001335505c3064120000130830112000010022002003335350a601308f01027200200350aa01333333333304a02201e01a01601200e00c00800400220050a80109b0120050a6010990120020050a5010970120050a2010950120020050a10109301200509e0109101200509c0108f01200200509b0108d0120050980108b0120020050970108901200509401087012002005093010850120050900108301200200508f0108101200508c0107f200200508b0107d20050880107b20020050870107920050850107820020020050860107707407106e06b06806506205f05c0592002005064200200506420020050640562002002002002002002002002002001200333333333300100b00a00900800700600500400300220000120033333353062001200200506120020020033353506b002200506320020020033353506e0022005066200200200333535071002200333530623306100a48000800ccd4d41a4c13c020800800ccd4d41acc04401c800800d41bccc04801000880141b418080141ac17880141a817480080080141ac17016415880080141848008014184800801418414c8008004800cc00400c008800004800cccccd4c17c0048008014178800800800ccd4d41a00088014180800800800ccd4d41ac008801418c800800800ccd4d41b80088014198800800800ccd4d41c4008800ccd4c188cc1840352000200333535069302b00b2002003333335306f00a200200506e200200200506f200200506e20020033353506d33355530201200001302612000013016120000100220020033353506f335034302f120000100b200200350733330190080040022005071064200506f062200200506e060200506b05e200506a05d200200200506b05c059056053200200505e200200505e200200505e0502002002001200333001004003002200001200335501030171200001300212000012003355003300212000013015120000120033505505f017112002003350553355003002001335500800200111200200200305c335530061200001335500400300200111200200200353550620012002003305f48000d407c4800800cc008cd402001c010cc008cd402001800c0044800d4d4140004800800008d40048000044800c004d5417c80080044800800ccd4d41780048014184800800800cd4188c01400ccd54c01c480000401400812444800800800cccccd4c154004800801415080080080141548008014150800800ccd554c0184800004c0304800004cd5402c0140100088008014150118d40048000044800c004d54170800800444800800800ccd4d4170004800d4d4020011417c800800800cd54d402c018cd54d40300194180c01400cccd554c020480000401801400811c4800d4d40180048008008000084800d4d40140048008008000044800d4d401000480080080000c44800800800cccccd4c13c0048008014138800800800ccd4d41600088014140800800800ccd4d416c008801414c800800800ccd4d4178008800ccd4c13ccc138029200020033353505633502f00e00820020033353505833503100f0072002003505c3355068004002200505a04d200505804b200505704a2002002005058049046043200200504e200200504e200200504e040200333500300404a005120020020012003330010040030021200001112002003335350460012002003504a3004002200504803b112002003335350450022002003335350470032002003504b3004002200504903c200504703a20033504204a01120033504104b00320033504004a0022003333335304400120020035044002200200200504420020050432002005043200200504303520033333353043001200200504220020020033353504c002200504420020020033353504f0022005047200200200333535052002200333530433304200a48000800ccd4d4128c04c020800800ccd4d4130cd4044c048480000401c800800d4140cc048010008801413810480141300fc801412c0f880080080141300f40e80dc8008014108800801410880080141080d08008004800cc00400c0088000044800800cccccd4c1040048008014100800800800ccd4d4128008800ccd4c0eccc0e80112002200350445043200504303620020020033353504d0022003335303e3303d00748000800ccd4d4114cd4078028014800800d4124d4124008801411c0e880141180e4800800801411c0e00d48008014100800801410080080141000c8800cd40e80080b8800cd4c0c0004800cc10d20003500312002003300230460030012002002003304548008d40144800800cc008c118014cc008c118010cc008c11800c0044800cd400541114114800cccccd4c0f000480080140ec800800800ccd4d411400880140f4800800800ccd4d4120008800ccd4c0e4cc0e001d20002003333335304400520020035044300e00220020020050442002005043200200504320020050430352003335303a3303900848008800cccccd4c114018800800d4114c03800880080080141148008014110800801411080080141100d880141080d40d080080080141080cc0c080080140ec80080140ec80080140ec0b48004800800c00800c8004800800c00400c800004800cd40cc0ec008800cccccd4c0dc00480080140d880080080140dc800800d40dc00880080140d880080140d80a04800800cccccd4c0dc00480080140d8800800800ccd4d410000880140e0800800800ccd4d410c00880140ec800800800ccd4d4118008800ccd4c0dccc0d8029200020033353503e33501000d00820020033353504033501500f0072002003504433501300400220050420352005040033200503f032200200200504003102e02b20020050362002005036200200503602812002001200330010030021200001120020033333353034001200200503320020020033353503d00220050352002002003335350400022005038200200200333535043002200333530343303300a48000800ccd4d40eccd404c034020800800ccd4d40f4c06c01c800800d4104cd404c01000880140fc0c880140f40c080140f00bc80080080140f40b80ac0a080080140cc80080140cc80080140cc09448008004800cc00400c00848000044800800cccccd4c0c400480080140c0800800800ccd4d40e800880140c8800800800ccd4d40f400880140d4800800800ccd4d4100008800ccd4c0c4cc0c0029200020033353503833501000d00820020033353503a30180072002003503e335013004002200503c02f200503a02d200503902c200200200503a02b0280252002005030200200503020020050300221200200120033001003002120000112002003333335302e001200200502d200200200333535037002200333530283302700448000800d40c5402c800ccd4c0a4cc0a0015200420035032500b200503102402320020020033353503a0022003335302b3302a00748008800ccd4d40c8cd402c028014800800d40d8d404400880140d009c80140cc09880080080140d009408880080140b480080140b480080140b407c4800d4d409800480080000448004800800800c00c01044800800800008448008008000044800004800cccccd4c09c0048008014098800800800ccd4d40c0008800ccd4c084cc08001120002003502a023200333530223302100548008800d40ac09480140a807407080080080140a806c800801409880080140988008014098060800cd40840954090800cccccd4c0940048008014090800800800ccd4d40b80088014098800800800ccd4d40c4008800ccd4c088cc08401d20002003333335302d0052002003502d300f002200200200502d200200502c200200502c200200502c01e200333530233302200848008800ccd4d40a8c040018800800d40b8c03800880140b007c800ccd4c090cc08c025200420033353502b301e0072002003502f3010002200502d020200333530253302400a48018800ccd4d40b0c058020800800d40c0c04c00880140b808480140b408007c07807480080080140ac0700648008014090800801409080080140900588004800800800800c0100148004800800800800c00c0148004800800800800c0080148004800800800800c004014800004800cccccd4c07c0048008014078800800800ccd4d40a00088014080800800800ccd4d40ac008801408c800800800ccd4d40b8008800ccd4c07ccc0780292000200333535026300f0082002003333335302c007200200502b200200200502c2002003502c33012004002200200502b200200502b01d200502801b200502701a2002002005028019016013200200501e200200501e200200501e0102002001200330010030022000012003333335301c001200200501b200200200333535025002200501d200200200333535028002200333530193301800748000800cccccd4c090014800800d40900088008008014090800801408c800801408c800801408c0548014084050800800801408804c040800801406c800801406c800801406c034800cccccd4c06c0048008014068800800800ccd4d4090008800ccd4c054cc050011200a2003501e00b200333530163301500548030800d407c02c8014078044040800800800ccd4d409c008800ccd4c060cc05c01d200020033353501f30120052002003502330110022005021014200333530193301800848008800ccd4d4080c04c018800800d4090c0500088014088054801408405004c800800800ccd4d40a8008800ccd4c06ccc06802920042003335350223015008200200333333530280072002003502833017004002200200200502820020050272002005027200200502701920050240172003335301c3301b00b48018800cccccd4c09c024800800cccccd4c0a4020800800d40a4cc05001000880080080140a480080140a080080140a080080140a0068800800801409c800801409880080140988008014098060800ccd4c074cc07003120082003333335302800a2002003333335302a0092002005029200200200502a2002003502a330140040022002005029200200502901b20020020050282002005027200200502720020050270192005025018017016200200200502401501200f200200501a200200501a200200501a00c20012002002002002002002003007008200200120020020020020020020033006009008200120020020020020020020030050081200200200200200200200004120020020020020020020000320020012002002002002002002003300200900820020012002002002002002002003300100900820000120033333353012001200200501120020020033353501b002200501320020020033353501e0022003335300f3300e00748000800cccccd4c068014800800d4068c040008800800801406880080140648008014064800801406402c801405c028800800800ccd4d40840088014064800800800ccd4d4090008800ccd4c054cc05003520022003333335302000b200200501f20020020050202002003333335302200a200200502120020020050222002003333335302400920020050232002002005024200200350243330190060040022002005023200200502301520020050212002005021013200200501f200200501f011200501d010200200200501e00f00c0090062002005011200200501120020050110031200001200001200120020030020032002002001200200333001005004003200001200200320033357a80080300299ba400800448008000084800800004800004800cd400c01d401848008004800cc00400c008480000448004800800c00800c4480080000448000048000048004800800800800800c0140188008004800800800800800cc01001c0188004800800800800800c00c0188004800800800800800c0080188004800800800800800c0040188000044480080000848008004800800cc00401000c4800004448008004800cc00400c0084480000444800c800c004004800800cc00cc800c004004008005"
+}

scripts/plutus/simple-minting-policy.sh

@@ -24,10 +24,10 @@ plutusscriptinuse="scripts/plutus/scripts/$PV/anyone-can-mint.plutus"
 utxovkey=example/utxo-keys/utxo1.vkey
 utxoskey=example/utxo-keys/utxo1.skey
 utxoaddr=$(cardano-cli address build --testnet-magic 42 --payment-verification-key-file $utxovkey)
-cardano-cli query utxo --address $utxoaddr --cardano-mode --testnet-magic 42 --out-file utxo.json
-txin=$(jq -r 'keys[]' utxo.json)
+cardano-cli query utxo --address $utxoaddr --cardano-mode --testnet-magic 42 --out-file "$work/utxo.json"
+txin=$(jq -r 'keys[]' "$work/utxo.json")
 
-lovelaceattxin=$(jq -r ".[\"$txin\"].value.lovelace" utxo.json)
+lovelaceattxin=$(jq -r ".[\"$txin\"].value.lovelace" "$work/utxo.json")
 lovelaceattxindiv3=$(expr $lovelaceattxin / 3)
 
 cardano-cli address key-gen \