Improve documentation on deploying a UPLC script

[ana-pantilie]

Plutus Core Meetup Dogfooding

At the 2024 Plutus Core Meetup we had a dogfooding session aimed at deploying a UPLC script to the Preview Cardano chain. The following is a summary of my experience with this, and the problems I encountered.

Problems

1. There is a discrepancy between the first instructions on https://plutus.cardano.intersectmbo.org/docs/getting-started-plutus-tx#overview-of-creating-a-validator-script-using-the-template-repo and the instructions in https://github.com/IntersectMBO/plutus-tx-template?tab=readme-ov-file#plutus-tx-template. We need to clarify this.
2. Point no. 5: Using cardano-cli, generate a pubKeyHash. does not mention how one gets access to cardano-cli and how one can use it!

My attempts to acquire cardano-cli (or to find a workaround)

1. Running the executables downloaded from the cardano-node repository releases does not work, I get ./cardano-cli-x86_64-linux: error while loading shared libraries: libblst.so: cannot open shared object file: No such file or directory
2. Couldn't fix ^, trying to install cardano-cli and cardano-node with nix
3. No instructions on how to do ^, reading https://github.com/IntersectMBO/plutus-tx-template/blob/main/app/QUICKSTART.md now
4. Lucid from ^ does not have good docs, I don't understand how to use it!
5. I'm now trying to follow https://meshjs.dev/guides/standalone
6. I need to install Node, so doing https://nodejs.org/en/download/package-manager
7. ^ Doesn't work, it can install nvm but then the shell doesn't find the executable!
8. ^ It does work, but you need to restart the shell and not be in the Nix shell
9. Did all that but got stuck at "generate a new mnemonic key from the Mesh website.", link doesn't work!

What I would expect

Being a developer of the Cardano stack, I would expect to have a way to easily build cardano-cli via nix, in order to include it into my development environment which is already nix-based.

If I were an external user, I'd probably like to be able to use something more streamlined and higher level. Meshjs seems a good candidate, but we need to add clear instructions on how to get it working here in the user documentation.

My proposed solution

Two "Getting started" sections in the documentation:

1. For regular users who probably don't want to use Nix, we should add instructions on how to get the example from the Plutus repository deployed with Meshjs and other user-friendly platforms
2. For developers, instructions on how to pull in the right dependencies (cardano-cli) inside the nix dev environment, and how to use it

[effectfully]

Point no. 5: Using cardano-cli, generate a pubKeyHash. does not mention how one gets access to cardano-cli and how one can use it!

@zliu41 this is what I meant when I said that our docs say one needs to use cardano-cli without specifying what that is or how to do what is required.

Other related issues include

• docs on cardano.org also tell the user to use cardano-cli. Do we control these docs? Do they need to exist and essentially compete with https://plutus.cardano.intersectmbo.org ?
• the IntersectMBO docs have multiple references to plutus-apps, e.g. see here, but nobody maintains the repo
• plutus-tx-template uses V2, we should either update it to use V3 or to maintain both V2 and V3 versions
• plutus-tx-template starts with "From the command line:" which reads like one should go ahead and run the command, but this is just one possible option and others are listed below, so I think this should be changed to "From the command line run either:"
• plutus-tx-template tells the user to reader to use lucid instead of mesh
• it is not particularly clear how to get test ADA to use on testnet and for some reason https://docs.cardano.org/cardano-testnets/tools/faucet has refused to give me test ADA for Preview Testnet, only Preprod Testnet