docs update

Author: mikekeke

CHANGELOG.md

@@ -7,6 +7,16 @@ This format is based on [Keep A Changelog](https://keepachangelog.com/en/1.0.0).
 - Wallets with Base Address support
 - Lookups for wallets in tasty integration
 
+## [1.3.1] - 2022-11-04
+
+### Fixed
+
+- collateral creation - happens now before user contract execution
+
+### Added
+
+- collateral handling documentation
+
 ## [1.3.0] - 2022-10-26
 
 ### Added

README.md

@@ -36,7 +36,11 @@ If your project is importing and making use of `Plutip`s library you will need t
 
 And the following ghc flag must to be set for the test execution: `-Wall -threaded -rtsopts`
 
-NOTE: This branch launches local network in `Vasil`. It was tested with node `1.35.3` (this node version used in nix environment as well). Please use appropriate node version when setting up own binaries in `PATH`.
+## NOTES
+
+⚠️ This branch launches local network in `Vasil`. It was tested with node `1.35.3` (this node version used in nix environment as well). Please use appropriate node version when setting up own binaries in `PATH`.
+
+⚠️ [Collateral handling](./docs/collateral-handling.md)
 
 ## Tutorials
 

contract-execution/Main.hs

@@ -41,9 +41,12 @@ main = do
       extraConf = def {ecSlotLength = slotLen}
       plutipConfig = def {extraConfig = extraConf}
 
+      addSomeWalletWithCollateral funds =
+        addSomeWallet (toAda 10 : funds)
+
   putStrLn "Starting cluster..."
   (st, _) <- startCluster plutipConfig $ do
-    w <- addSomeWallet [toAda 10]
+    w <- addSomeWalletWithCollateral [toAda 100]
     liftIO $ putStrLn "Waiting for wallets to be funded..."
     CI.awaitWalletFunded w slotLen
 

docs/collateral-handling.md

@@ -0,0 +1,38 @@
+# Collateral handling
+
+Before running *any* contract `Plutip` under the hood creates dedicated UTxO at "own" wallet address to be used *only* as collateral. This UTxO is created by submitting transaction and spending "own" wallet's funds . For collateral `Plutip` always uses **10 Ada** at this point and if wallet address already has UTxO with 10 Ada on it, then Plutip will use it as collateral.
+
+UTxO that was created or picked for collateral is stored in memory, so during Contract execution `Plutip` will always use this exact same UTxO. Collateral UTxO has special properties - to guard it from being consumed by accident it is not accessible from Contract. I.e. calls like `utxosAt` ***will not return*** UTxO used for collateral. This means, that users don't have to care really about collateral UTxO during contract execution.
+
+The only place where collateral "sticks out" is the moment of wallet creation. Ii is also visible for `cardano-cli` queries.
+
+## Cluster runner
+
+With [cluster runners](../local-cluster/README.md), when creating wallet with `addSomeWallet [100_000_000]`, if you want to have UTxO with exactly 100 Ada while running the Contract, you should add 10 Ada more to wallet's initial distribution, or UTxO with 100 Ada will be used to create collateral.
+
+E.g.:
+
+```haskell
+main :: IO ()
+main = do
+  let executeContract wallet contract =
+     ask >>= \cEnv -> runContract cEnv wallet contract
+     
+  (st, _) <- startCluster def $ do
+    w <- addSomeWallet [100_000_000, 10_000_000] -- 10 Ada will be used as collateral
+    awaitWalletFunded w 1
+    result <- executeContract w someContract
+    doSomething result
+  stopCluster st
+```
+
+Or just make helper function:
+
+```haskell
+addSomeWalletWithCollateral funds =
+  addSomeWallet (toAda 10 : funds)
+```
+
+## Tasty integration
+
+For collateral handling in tasty integration see [Collateral handling section](./tasty-integration.md#collateral-handling).

docs/tasty-integration.md

@@ -126,6 +126,8 @@ To assert the final `Value` which `wallet` will have after contract execution sp
 * `initAdaAssertValue [100] 133` - initialize `wallet` with single UTxO with 100 Ada and check that after contract execution final `Value` of all `wallet`'s UTxOs is equal to 133 Ada.
 * `initAndAssertLovelaceWith [1_000_000] VGt 2_000_000` - initialize `wallet` with single UTxO with 1000000 Lovelace and check that after contract execution final `Value` of all `wallet`'s UTxOs is *greater than* 2000000 Lovelace.
 
+#### Collateral handling
+
 ***One important note*** is that Plutip creates dedicated UTxO to be used *only* as collateral under the hood. This UTxO would normally be created by spending wallets funds, and the transaction fee and Ada amount used for collateral UTxO would mess up balance assertions. So when using any kind of assertions for `Value` it is advised to wrap `wallets` initialization with `withCollateral` function. This simply adds a small UTxO to the `wallets`'s balance during network setup that is then picked up for collateral instead avoiding the problem. Use it like so:
 
 ```haskell

local-cluster/Main.hs

@@ -79,8 +79,11 @@ main = do
         amt -> Right $ fromInteger . toInteger $ amt
 
     initWallets numWallets numUtxos amt dirWallets = do
+      let collateralAmount = 10_000_000
       replicateM (max 0 numWallets) $
-        addSomeWalletDir (replicate numUtxos amt) dirWallets
+        addSomeWalletDir
+          (collateralAmount : replicate numUtxos amt)
+          dirWallets
 
     printWallet (w, n) = do
       putStrLn $ "Wallet " ++ show n ++ " PKH: " ++ show (walletPkh w)

local-cluster/README.md

@@ -55,7 +55,7 @@ main = do
      ask >>= \cEnv -> runContract cEnv wallet contract
 
   (st, _) <- startCluster def $ do
-    w <- addSomeWallet [100_000_000]
+    w <- addSomeWallet [100_000_000, 10_000_000] -- 10 Ada will be used as collateral
     awaitWalletFunded w 1
     result <- executeContract w someContract
     doSomething result