Skip to content

v0.6.0
Compare
Choose a tag to compare
@sourabhxyz sourabhxyz released this 29 Aug 12:42
· 231 commits to main since this release
v0.6.0
b05a986
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Migration guide

The changes introduced by v0.6.0 are huge and we attempt our best to describe a migration guide in this section, which should also introduce some of the new features that have been added.

General changes

  • Atlas' GYTxMonad has been revamped, with details in this PR (please visit the linked PR as it describes the design of new monads! Same is also provided in the appendix of this release document). In particular, to handle these changes, you might need to do following changes in your codebase:

    • Use runGYTxQueryMonadIO in place of runGYTxQueryMonadNode. I'll use runGYTxQueryMonadNode -> runGYTxQueryMonadIO to denote such a change.

    • GYTxQueryMonadNode -> GYTxQueryMonadIO.

    • GYTxMonadNode -> GYTxBuilderMonadIO.

    • GYTxBuildResult Identity -> GYTxBuildResult.

    • GYTxMonad can likely be replaced with GYTxUserQueryMonad in your code.

    • Some of the old functions such as runGYTxMonadNode are removed but these can be defined like so:

      runGYTxMonadNode :: GYNetworkId -> GYProviders -> [GYAddress] -> GYAddress -> Maybe (GYTxOutRef, Bool) -> GYTxBuilderMonadIO (GYTxSkeleton v) -> IO GYTxBody
runGYTxMonadNode nid providers addrs change collateral act = runGYTxBuilderMonadIO nid providers addrs change collateral $ act >>= buildTxBody

runGYTxMonadNodeF :: forall t v. Traversable t => GYCoinSelectionStrategy -> GYNetworkId -> GYProviders -> [GYAddress] -> GYAddress -> Maybe (GYTxOutRef, Bool) -> GYTxBuilderMonadIO (t (GYTxSkeleton v)) -> IO (t GYTxBody)
runGYTxMonadNodeF strat nid providers addrs change collateral act = runGYTxBuilderMonadIO nid providers addrs change collateral $ act >>= traverse (buildTxBodyWithStrategy strat)

runGYTxMonadNodeParallel :: GYNetworkId -> GYProviders -> [GYAddress] -> GYAddress -> Maybe (GYTxOutRef, Bool) -> GYTxBuilderMonadIO [GYTxSkeleton v] -> IO GYTxBuildResult
runGYTxMonadNodeParallel nid providers addrs change collateral act = runGYTxBuilderMonadIO nid providers addrs change collateral $ act >>= buildTxBodyParallel

runGYTxMonadNodeParallelWithStrategy :: GYCoinSelectionStrategy -> GYNetworkId -> GYProviders -> [GYAddress] -> GYAddress -> Maybe (GYTxOutRef, Bool) -> GYTxBuilderMonadIO [GYTxSkeleton v] -> IO GYTxBuildResult
runGYTxMonadNodeParallelWithStrategy strat nid providers addrs change collateral act = runGYTxBuilderMonadIO nid providers addrs change collateral $ act >>= buildTxBodyParallelWithStrategy strat

    • GYTxQueryMonadIO and GYTxBuilderMonadIO do not have MonadIO instance, but these can be defined as shown:

      import           GeniusYield.Unsafe                    (unsafeIOToQueryMonad, unsafeIOToTxBuilderMonad)

instance MonadIO GYTxQueryMonadIO where
    liftIO = unsafeIOToQueryMonad

instance MonadIO GYTxBuilderMonadIO where
    liftIO = unsafeIOToTxBuilderMonad

    • utxoRefScript field inside GYUTxO is updated to Maybe GYAnyScript where GYAnyScript encapsulates both simple (native) scripts and plutus scripts (Atlas now supports simple scripts, yay!).

As an example, you can see how we migrated our dex-contracts-api codebase here.

Privnet

How to run?

To run the privnet tests, first one needs to install cardano-node & cardano-cli like so:

cabal install --package-env=$(pwd) --overwrite-policy=always cardano-cli cardano-node

Then the tests can be ran, like for Atlas: cabal run atlas-privnet-tests -- -j1 --hide-successes

How to structure?

  • Due to redesign of monads related to transaction building & query, functions such as ctxRunI are no longer present, but they (and some of the related utilities) can be implemented like so:
ctxRunI :: Ctx -> User -> GYTxBuilderMonadIO (GYTxSkeleton v) -> IO GYTxBody
ctxRunI ctx user act = ctxRunBuilder ctx user $ act >>= buildTxBody

ctxRunC :: Ctx -> User -> GYTxBuilderMonadIO a -> IO a
ctxRunC = ctxRunBuilder

ctxRunF :: Traversable t => Ctx -> User -> GYTxBuilderMonadIO (t (GYTxSkeleton v)) -> IO (t GYTxBody)
ctxRunF ctx user act = ctxRunBuilder ctx user $ act >>= traverse buildTxBody

submitTxCtx :: Ctx -> User -> GYTxBody -> IO GYTxId
submitTxCtx ctx user txBody = ctxRun ctx user $ signAndSubmitConfirmed txBody

submitTxCtx' :: Ctx -> User -> GYTx -> IO GYTxId
submitTxCtx' ctx user tx = ctxRun ctx user $ submitTxConfirmed tx

addRefScriptCtx :: Ctx -> User -> GYScript PlutusV2 -> IO GYTxOutRef
addRefScriptCtx ctx user script = ctxRun ctx user $ addRefScriptToLimbo script

  • Earlier the tests might expect the argument IO Setup but now only Setup is required which can be generated with following continuation: withPrivnet cardanoDefaultTestnetOptionsConway $ \setup. Please see privnet tests structured inside Atlas here for examples.

  • Arguments of withSetup are flipped, so instead of withSetup setup info, now withSetup info setup is required but you can use withSetupOld instead.

  • Use userChangeAddress (or first element of userAddresses) instead of userAddr. Note that there is pattern synonym User' defined to access old fields such as userAddr.

  • submitTx is removed, can use above submitTxCtx function.

  • In case you were catching of BuildTxException (now renamed to GYBuildTxError and it no longer has instance for Exception), since now these are made part of GYBuildTxException constructor inside GYTxMonadException type, catch for those instead. For example:

    - isTxBodyScriptExecutionError :: BuildTxException -> Bool
- isTxBodyScriptExecutionError (BuildTxBodyErrorAutoBalance (Api.TxBodyScriptExecutionError _)) = True
- isTxBodyScriptExecutionError _                                                                = False
+ isTxBodyScriptExecutionError :: GYTxMonadException -> Bool
+ isTxBodyScriptExecutionError (GYBuildTxException (GYBuildTxBodyErrorAutoBalance (Api.TxBodyScriptExecutionError _))) = True
+ isTxBodyScriptExecutionError _                                                                  = False

  • GYPrivnet now has an additional field to store of the network information used internally, you can largely ignore those.

  • Note that these privnet run against Conway era and protocol parameters can be check like so:

      pp <- ctxRunQuery ctx protocolParams
  info $ printf "Protocol parameters: %s" (show pp)

Let us know if you think some of these should be changed!

CLB (cardano-ledger-backend, replacement of plutus-simple-model employed earlier) & new testing mechanism

Note that we now have unified testing in place, i.e., same test file can be ran against multiple backend interpreters, i.e., either utilising CLB, private testnet machinery or any of cardano network (testnet/mainnet).

It is best to see tests-unified directory to see how to structure these. In particular you don't need to write privnet tests separately!

  • There is no longer Wallet type, use User instead.

  • If you earlier had

    runWallet w1 $ withWalletBalancesCheckSimple walletDiffList $ do ...

    You should instead do

    withWalletBalancesCheckSimple walletDiffList $ asUser w1 $ do ...

  • Note that since the testing mechanism is unified, you should no longer require to import types such as GYTxMonadClb in your backend code. I.e., if you had

    myTrace :: SomeParameters -> Wallets -> GYTxMonadClb ()

    You should instead do

    myTrace :: GYTxGameMonad m => SomeParameters -> Wallets -> m ()

    Note that GYTxGameMonad constraint should be added if you are employing asUser in your trace, otherwise make use of GYTxMonad etc.

  • Use ownChangeAddress instead of ownAddress.

  • Instead of fail ... use throwAppError $ someBackendError $ ....

  • sendSkeleton and sendSkeleton' can be defined like so:

    -- | This is simply defined as @buildTxBody skeleton >>= signAndSubmitConfirmed@.
sendSkeleton :: GYTxMonad m => GYTxSkeleton v -> m GYTxId
sendSkeleton skeleton = snd <$> sendSkeleton' skeleton

sendSkeleton' :: GYTxMonad m => GYTxSkeleton v -> m (GYTxBody, GYTxId)
sendSkeleton' skeleton = buildTxBody skeleton >>= \tx -> signAndSubmitConfirmed tx >>= \txId -> pure (tx, txId)

Appendix

Monad redesign summary

This is a long overdue redesign of GYTxMonad. It adds the ability to submit transactions to the monad and splits it into a more lawful hierarchy. In particular:

  • GYTxQueryMonad - For common utxo and similar queries

    Instance: GYTxQueryMonadIO

  • GYTxQueryMonad => GYTxSpecialQueryMonad - For uncommon queries such as protocol parameters, era history etc. (this could potentially be removed, see note below)

    Instance: GYTxQueryMonadIO

  • GYTxQueryMonad => GYTxUserQueryMonad - For queries while acting as a user (having access to own wallet for querying purposes not signing purposes)

    Instance: GYTxBuilderMonadIO - see below.

  • (GYTxSpecialQueryMonad, GYTxUserQueryMonad, Default (TxBuilderStrategy)) => GYTxBuilderMonad - For building transactions while acting as a user. This allows different instances to choose their own transaction building method. If TxBuilderStrategy is set to GYCoinSelectionStrategy (default), the implementation defaults to the pre-existing transaction building methods. Therefore, simply anyclass deriving this class will be enough to use the transaction building unchanged.

    instance: GYTxBuilderMonadIO

  • GYTxBuilderMonad => GYTxMonad - For interacting with the blockchain in a way that mutates its state. E.g building and submitting transactions etc. Also is able to sign as a user.

    Instance: GYTxMonadIO

  • (GYTxMonad (TxMonadOf m), GYTxSpecialQueryMonad m) => GYTxGameMonad m - This is an entirely new feature. This allows simulating multiple users interacting in an environment, building and submitting transactions etc. This is extremely useful in testing. Where we model an environment with many users interacting, waiting for events etc.

    Each "game' monad has its own "tx" monad. The tx monad code can be lifted into the "game" monad and assigned a user to perform it as.

    Instance: GYTxGameMonadIO

Note the distinction between a TxQuery monad and the Tx monad. The query monad classes are meant to be non-mutating. In other words, if you are given a GYTxUserQueryMonad m => m a for example, and you run it (using a relevant interpreter) - you can be sure that it did not mutate anything on the chain. However, that guarantee does not exist for GYTxMonad.

This sort of a lawful type classes helps in "coloring" functions with types to define their expected behavior.

This makes running the monad instances (e.g GYTxMonadIO, renamed from GYTxMonadNode) much simpler. There is no traversable hack anymore. It's a simple monad interpreter. As you'd expect from any other proper monad in the ecosystem. As a result, transaction defining, building, signing, and submitting - all under one monad feels much more ergonomic.

Full Changelog: v0.5.0...v0.6.0

Assets 2
Loading