From ec985065938f8e353af039bd24c7eadcd1c58da5 Mon Sep 17 00:00:00 2001 From: sourabhxyz Date: Sat, 5 Oct 2024 18:46:27 +0530 Subject: [PATCH] docs: add documentation for blueprint feature --- src/pages/_meta.json | 4 +-- src/pages/additional-features/_meta.json | 3 ++ src/pages/additional-features/blueprint.mdx | 34 +++++++++++++++++++++ src/pages/getting-started/_meta.json | 8 ++++- 4 files changed, 46 insertions(+), 3 deletions(-) create mode 100644 src/pages/additional-features/_meta.json create mode 100644 src/pages/additional-features/blueprint.mdx diff --git a/src/pages/_meta.json b/src/pages/_meta.json index 1eda6ac..c63ceec 100644 --- a/src/pages/_meta.json +++ b/src/pages/_meta.json @@ -13,11 +13,11 @@ }, "introduction": "Introduction", "getting-started": "Getting Started", + "additional-features": "Additional Features", "more-tutorials": "More Tutorials", "haddock": { "title": "API Reference (Haddock) ⬈", "href": "https://haddock.atlas-app.io/", "newWindow": true } -} - +} \ No newline at end of file diff --git a/src/pages/additional-features/_meta.json b/src/pages/additional-features/_meta.json new file mode 100644 index 0000000..bd8e7cc --- /dev/null +++ b/src/pages/additional-features/_meta.json @@ -0,0 +1,3 @@ +{ + "blueprint": "Blueprint" +} \ No newline at end of file diff --git a/src/pages/additional-features/blueprint.mdx b/src/pages/additional-features/blueprint.mdx new file mode 100644 index 0000000..f9e2e79 --- /dev/null +++ b/src/pages/additional-features/blueprint.mdx @@ -0,0 +1,34 @@ +import { Callout } from 'nextra-theme-docs' + +# Blueprint + +Plutus Contract Blueprint, as introduced by [CIP-57](https://cips.cardano.org/cip/CIP-0057) is an effective way of communicating desired structure of validator's associated types such as datum & redeemer to your off-chain code. + +With Atlas, you can easily have these types generated for you based on provided schema, along with some helper utilities, yay! + + + +If your validator is parameterised, parameters must be "data" encoded (instead of scott or sums-of-products encoding[^1]) as blueprint notation desires it (data) to be primary binary interface. This is not an issue for datums & redeemers as they are required to be data encoded anyway. + +Validators written by tools such as Aiken uses data encoding for validator parameters. + + +[Here](https://github.com/geniusyield/atlas/blob/main/tests/aiken/bar/validators/baz.ak) we have a parameterised Aiken validator. Mainly, it checks that sum of integers and length of bytestrings given in parameters, datum & redeemer sum up to a specific value. + +For it, we have a simple off-chain code [here](https://github.com/geniusyield/atlas/blob/main/tests-privnet/GeniusYield/Test/Privnet/Blueprint.hs), have a look at it and we provide some description for it below. + +We first use Template Haskell to splice declarations from [`makeBPTypes`](https://haddock.atlas-app.io/GeniusYield-Types-Blueprint-TH.html#v:makeBPTypes) and [`uponBPTypes`](https://haddock.atlas-app.io/GeniusYield-Types-Blueprint-TH.html#v:uponBPTypes). `makeBPTypes` introduces types from definitions given in blueprint file and `uponBPTypes` creates data related instances such as [`ToData`](https://plutus.cardano.intersectmbo.org/haddock/latest/plutus-ledger-api/PlutusLedgerApi-Common.html#t:ToData), [`FromData`](https://plutus.cardano.intersectmbo.org/haddock/latest/plutus-ledger-api/PlutusLedgerApi-Common.html#t:FromData) for these types[^2]. + +It is useful to see generated Template Haskell code to know for type and provided utility names which can be done via `-ddump-splices` GHC flag. You may combine this with `-ddump-to-file` to save the output to a file. If you are using cabal, see [this](https://stackoverflow.com/questions/24717500/viewing-core-when-compiling-with-cabal/69678961#69678961) answer on where one can find dumped splice files. + +Now we can apply parameters (whose types have been generated by Atlas) to our validator with provided `applyParamsToBPValidator_baz_baz_spend` function and obtain `GYScript` from it using `scriptFromBPSerialisedScript` function. Likewise we have types generated for our datum & redeemer, sweet! + +Rest of the off-chain code just tries to interact with the validator by creating a UTxO towards it and then later consuming from it. + + + +To interact with blueprint file, you'll usually just need to import [`GeniusYield.Types.Blueprint.TH`](https://haddock.atlas-app.io/GeniusYield-Types-Blueprint-TH.html) module (which is exposed by `GeniusYield.Types` module), however if you want to inspect the parsed blueprint file, you can use [`readBlueprint`](https://haddock.atlas-app.io/GeniusYield-Types-Blueprint.html#v:readBlueprint). + + +[^1]: See [CIP-85](https://cips.cardano.org/cip/CIP-0085) to understand about different encodings used. +[^2]: We could however achieve both in single splice, however, since we are using utilities from PlutusTx to derive `ToData` etc. instances, they require type to be in scope first. \ No newline at end of file diff --git a/src/pages/getting-started/_meta.json b/src/pages/getting-started/_meta.json index 8fbc555..05c7480 100644 --- a/src/pages/getting-started/_meta.json +++ b/src/pages/getting-started/_meta.json @@ -4,5 +4,11 @@ "operations": "Operations over Contract", "testing": "Testing", "endpoints": "Creating Endpoints", - "browser-integration": "Browser Integration" + "browser-integration": "Browser Integration", + "unit-tests": { + "display": "hidden" + }, + "integration-tests": { + "display": "hidden" + } } \ No newline at end of file