From fbe5a3e32c0fcd2889659ab4f6dfa1bf284658e3 Mon Sep 17 00:00:00 2001 From: Ziyang Liu Date: Wed, 23 Oct 2024 10:49:53 -0700 Subject: [PATCH] Link to the auction example and remove the quickstart guide --- README.md | 26 ++++++++++---------- app/QUICKSTART.md | 60 ----------------------------------------------- 2 files changed, 13 insertions(+), 73 deletions(-) delete mode 100644 app/QUICKSTART.md diff --git a/README.md b/README.md index 8d19664..d6c16d7 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,14 @@ A template repository for your `plutus-tx` smart contract project. ### 1. Create the repository -- From the command line: - +- From the command line: + ``` gh repo create my-project --private --template IntersectMBO/plutus-tx-template ``` -- Or from the [GitHub web page](https://github.com/IntersectMBO/plutus-tx-template), click the top-right green button: - +- Or from the [GitHub web page](https://github.com/IntersectMBO/plutus-tx-template), click the top-right green button: + `Use this template -> Create new repository` - Or just fork/clone `plutus-tx-template` (but note that this is a template repository) @@ -23,28 +23,28 @@ A template repository for your `plutus-tx` smart contract project. ### 2. Setup your development environment - With Nix (**recommended**) - + Follow [these instructions](https://github.com/input-output-hk/cardano-node-wiki/blob/main/docs/getting-started/install.md) to install and configure nix, even if you already have it installed. - Then enter the shell using `nix develop`. + Then enter the shell using `nix develop`. The nix files inside this template follow the [`iogx` flake](https://github.com/input-output-hk/iogx), but you can delete and replace them with your own. In that case, you might want to include the [`devx` flake](https://github.com/input-output-hk/devx/issues) in your flake inputs as a starting point to supply all the necessary dependencies, making sure to use one of the `-iog` flavours. - With Docker / Devcontainers / Codespaces - - From the [GitHub web page](https://github.com/IntersectMBO/plutus-tx-template), click the top-right green button: - + + From the [GitHub web page](https://github.com/IntersectMBO/plutus-tx-template), click the top-right green button: + `Use this template -> Open in a codespace` - + Or let VSCode create a local codespace for you when you open this project. You can modify your [`devcontainer.json`](./.devcontainer/devcontainer.json) file to customize the container (more info [here](https://github.com/input-output-hk/devx?tab=readme-ov-file#vscode-devcontainer--github-codespace-support)). - + Or using your local docker installation (change the `/path/to/my-project` accordingly): ``` docker run \ -v /path/to/my-project:/workspaces/my-project \ - -it ghcr.io/input-output-hk/devx-devcontainer:x86_64-linux.ghc96-iog + -it ghcr.io/input-output-hk/devx-devcontainer:x86_64-linux.ghc96-iog ``` When using this approach, you can ignore/delete/replace the nix files entirely. @@ -57,4 +57,4 @@ A template repository for your `plutus-tx` smart contract project. ### 3. Run the example application -Run `cabal update` first, then read [app/QUICKSTART.md](./app/QUICKSTART.md) to get started. \ No newline at end of file +Run `cabal update` first, then read [Example: An Auction Smart Contract](https://plutus.cardano.intersectmbo.org/docs/category/example-an-auction-smart-contract) to get started. diff --git a/app/QUICKSTART.md b/app/QUICKSTART.md deleted file mode 100644 index 4805314..0000000 --- a/app/QUICKSTART.md +++ /dev/null @@ -1,60 +0,0 @@ -# Writing the On-Chain Validator - -The `main` function in `Main.hs` does two things: - -* Instantiate the validator by providing the `AuctionParams` of a specific auction -* Serialise the instantiated validator and write it to a file - - -Replace `apSeller` with the seller's [PubKeyHash](https://plutus.cardano.intersectmbo.org/haddock/master/plutus-ledger-api/PlutusLedgerApi-V2.html#t:PubKeyHash), which can be generated using Cardano CLI, Cardano API or an off-chain library for Cardano. - -Replace `apEndTime` with your desired [POSIXTime](https://plutus.cardano.intersectmbo.org/haddock/master/plutus-ledger-api/PlutusLedgerApi-V2.html#t:POSIXTime). - -Now, build it: -``` -cabal build plutus-tx-template -``` - -Then, run the executable with: -``` -cabal exec plutus-tx-template -``` - -This should succeed and will write the serialised validator to `validator.uplc`. - -Congratulations - you've successfully created a Plutus validator script. - -### Creating and Submitting Transactions using an Off-Chain Framework - -Once you have the validator, you can proceed with deploying and interacting with a smart contract that uses this validator. -To do so, you'll need the ability to perform operations like the following: - -* Generating key pairs -* Querying available UTXOs that satisfy certain criteria and can be used as the input of a transaction -* Building transactions and calculating transaction fees -* Signing and submitting transactions - -These can be done using low-level Cardano CLI commands or the Cardano API library functions. -A better way is to use high-level off-chain libraries and frameworks, such as: - -* [Lucid](https://lucid.spacebudz.io/), a JavaScript off-chain library for Cardano -* [Kuber](hhttps://github.com/dQuadrant/kuber), which provides a Haskell library and a JSON API for working with Cardano transactions -* [cardano-transaction-lib](https://github.com/Plutonomicon/cardano-transaction-lib), a PureScript library for building Cardano transactions - -These frameworks either consume compiled validators in serialised form (such as the one you just made), or depend on the Plutus Tx library and compile the on-chain code from source. -Refer to their respective documentation for more details about how to use them. - -A good way to quickly deploy and test a smart contract is to do it on a public testnet, such as Preview. -Generate a key pair, go to the [faucet](https://docs.cardano.org/cardano-testnet/tools/faucet/) for the testnet you are using to request some funds, submit a transaction to lock the funds in your smart contract validator script, and off you go to have all the fun with it. -Read [Simple Example](https://plutus.readthedocs.io/en/latest/simple-example.html#life-cycle-of-the-auction-smart-contract) if you need to understand how one can submit transactions to interact with the auction smart contract. - -### Interfacing between Plutus Tx and Off-Chain Frameworks - -At this time, interfacing between Plutus Tx and most off-chain frameworks (especially non-Haskell ones) isn't very well supported. -What this means is that you may run into inconveniences like these: - -* An off-chain framework may expect serialised validators to be in a format different than that produced by Plutus Tx. -* The redeemer type is defined in Haskell (e.g., `AuctionRedeemer` in `AuctionValidator.hs`), but needs to be redefined in another language when using a non-Haksell off-chain framework. - For instance, when using Lucid, you'll need to define an object in JavaScript corresponding to `AuctionRedeemer` in order to construct your redeemer. - -These inconveniences will be addressed once Plutus contract blueprints, as outlined in [CIP-0057](https://developers.cardano.org/docs/governance/cardano-improvement-proposals/cip-0057/), are adopted and implemented by us as well as the off-chain frameworks.