Skip to content

Releases: geniusyield/atlas

v0.6.0

29 Aug 12:42
b05a986
Compare
Choose a tag to compare

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 bu...

Read more

v0.5.0

23 May 04:21
7d0536b
Compare
Choose a tag to compare

What's Changed

  • Handle all balancing errors failure in parallel tx build logic by @sourabhxyz in #269.
    Earlier only BalancingErrorInsufficientFunds was returned for in BuildTxBalancingError but now all of BalancingError are accounted for in it.
  • Support for GYStakeAddressBech32 + upstreamed few types, instances & utilities by @sourabhxyz in #273.
  • Ability to use Maestro's turbo tx submission by @sourabhxyz in #274.
    Now an optional turboSubmit field can be included when specifying Maestro provider configuration as explained in this section of the documentation.
  • Add support for stake signing keys by @sourabhxyz in #280.
    This adds support in Atlas for stake keys. In particular, support is provided to load private stake signing keys from file and ability to require stake key hash in transaction skeleton. Attempt has been made to keep breaking changes at minimal, in particular two changes are breaking:
    • newTempUserCtx now accepts a configuration instead of a boolean.
    • Fields of User type have been updated.
    • GYPaymentCredentialByKey now requires GYPaymentKeyHash instead of GYPubKeyHash.
  • Adds functions into Wallet module, improves api interface... by @sourabhxyz in #284.
  • Improve swagger instances, provide helper utilities... by @sourabhxyz in #288.
  • Add improvements to tx metadata api by @sourabhxyz in #293.
  • Add provider support to query utxos at multiple payment credent… by @sourabhxyz in #291.
  • Add a way to add transaction metadata by @ajuggler in #285.
  • Add support of stake validators by @sourabhxyz in #295.
    This also added support of stake key related certificates, such as it's registration, delegation and deregistration. Support of withdrawal is also added. Head over to this section of the documentation for more information on it.

New Contributors

Full Changelog: v0.4.0...v0.5.0

v0.4.0

20 Dec 08:51
887633f
Compare
Choose a tag to compare

What's Changed

Dependencies Bump: Please note the commit of dependencies used in cabal.project file as some of them have been updated b/w v0.3.0 & v0.4.0.

Full Changelog: v0.3.0...v0.4.0

v0.3.0

13 Sep 11:35
9e80824
Compare
Choose a tag to compare

What's Changed

  • Feat 129: Update to PSM test suite to have memory of paid lovelaces for fees & min ada requirements by @sourabhxyz in #131 - This is useful to not hard-code these extra involved ada in the PSM tests. Example at https://atlas-app.io/getting-started/unit-tests would be soon updated to illustrate for it.
  • Feat 128: Change package name to atlas-cardano by @sourabhxyz in #133 - This was mainly done as there is already a package named atlas in Hackage.
  • Feat 126: Blockfrost provider for tests by @sourabhxyz in #127 - Atlas now also has a Blockfrost provider. However, for some of the provider functions (the ones which allow getting datum information of the UTxO in case UTxO only has hash of the datum) provided by Atlas, it's usage is not optimal. As mentioned, Atlas has a provider function to query for UTxOs at address(s) along with their datum information. Maestro (see resolve_datums query parameter) allows getting datums for the asked UTxOs in the same request, however, for Blockfrost, we would have to hit datums for each of the returned UTxO having the datum hash, which is clearly not optimal. Having said this, having an option of one more remote provider is useful to test results of Maestro provider, etc.
  • Feat 152: Transaction requirements for interoperability with hardware wallets @sourabhxyz in
    • #153 (sort for integer keys in map & also simplify outputs to legacy_transaction_output format)

    • #180 (sort for more type of keys)

    • #174 (ensure no indefinite-length terms are present in CBOR encoding of transaction)

      These were done in accordance CIP-21. Now the generated transaction body should work well with hardware wallets.

  • Feat 155: Multi-Sig support by @sourabhxyz in #156 - Kindly see the transaction signing functions here.
  • Feat 130: Integrate Maestro SDK, Feat 135: Extending GYTxQueryMonad with utxosAtAddressesWithDatums & Feat 139: Providers mashup test by @sourabhxyz in #134 - Haskell Maestro SDK was integrated. Few more functions were added to our provider abstraction in the GYTxQueryMonad class to allow for querying of UTxOs along with their datums. This is useful for providers which provide optimal support for such an request.
  • Allow multi sigs in test by @piyushthapa in #158 - Allows signing with multiple wallets in unit tests written using our plutus-simple-model provider with the help of sendSkeletonWithWallets function.
  • Feat 159: Bug fix in coin selection by @sourabhxyz in #160 - Internal bug fix.
  • Feat 141: Better error messages by @sourabhxyz in #142 - Now BuildTxExUnitsTooBig, BuildTxSizeTooBig also give the corresponding bounds as mentioned in the protocol parameters. BuildTxCollateralShortFall also mentions the transaction collateral requirement besides the shortfall.
  • runGyTxMonadParallel with strategy by @piyushthapa in #164 - new function runGYTxMonadNodeParallelWithStrategy which allows running runGYTxMonadNodeParallelF with given strategy.
  • Feat 140: Quick Jump haddock fix by @sourabhxyz in #165 - Fixes "Quick Jump" header for our haddock documentation.
  • Feat 143: Improve coin selection by @sourabhxyz in #163 - Brings various internal improvements into our coin selection computation.
  • Feat 170: Remove over-bound for change address as we already know it's value by @sourabhxyz in #171 - Internal coin selection improvement.
  • Feat 161: Return built transaction bodies in same order as given by @sourabhxyz in #162.
  • Fixes availableUTxOs function to use optimized utxosAtAddresses endpoint by @Micrograx in #183.
  • Feat 181: Maestro V1 endpoints support by @sourabhxyz in #182 - Maestro recently released V1 family of endpoints, correspondingly Atlas was updated for the same.
  • Feat 175: Pure variant of utxosDatums, Feat 177: utxosAtTxOutRefsWithDatums provider method by @sourabhxyz in #176 - In case you already have datum information for your UTxOs (say by using utxosAtAddressesWithDatums) you can call utxosDatumsPure instead of utxosDatums.
  • Feat 190: Latest era type for Tx Witness by @sourabhxyz in #191 - Our witness parser was from ShellyMA era which was sufficient for witnesses returned by browser wallet's signTx CIP-30 method. However, Eternl at times gave witness with more information, hence we updated this parser.
  • Add some JSON key instances (and swagger paramschema) for GYMintingPolicyId and GYAssetClass by @TotallyNotChase in #192.
  • Feat 193: Reference script support for minting policies by @sourabhxyz in #198 - Earlier, we were only supporting creation of outputs (& likewise referring to them later for witness) containing validators, but now Atlas is extended to also support minting policies.
  • Add Support for Maestro Preview Network by @Dr-Mazen-Khaddaj in #214.
  • Feat 216: Forwarding correct UTxO information to avoid it being overridden by @sourabhxyz in #217 - This is an internal bug fix.
  • Feat 207: Avoid simplifying outputs to pre-babbage format by @sourabhxyz in #208 - We were earlier simplifying outputs of generated transaction body to legacy_transaction_output whenever possible. But this is now no longer done.
  • Feat 186: Query by payment credential by @sourabhxyz in #188 - A new GYTxQueryMonad method is added to allow query for UTxOs at a payment credential. It's named utxosAtPaymentCredential.
  • Feat 166 & 167: Update to latest node 8.1.1 & GHC v9.2.8 support by @sourabhxyz in #202 - Big PR integrating all the latest changes from the involved Cardano libraries to make Atlas up to date. With this, we dropped the support of GHC 8.10.7 (plutus-tx-plugin requires higher GHC version) and now instead support GHC 9.2.8. Our PSM fork was updated with changes mentioned here. Also, the privnet is changed to work with latest node (8.1.2) here. Since writing smart contract is slightly different in latest haskell Plutus libraries, https://atlas-app.io/getting-started/smart-contract-intro would soon be updated to illustrate for it, likewise https://atlas-app.io/getting-started/integration-tests would be updated to illustrate usage of privnet against node 8.1.2.
  • Adding ref-script to the script map for PSM to work. by @alegadea in #227 - In case the mentioned reference input (via mustHaveRefInput) is also have a script in it, i.e., if the UTxO mentioned as reference input was also having a script, our plutus-simple-provider was throwing an error, which is resolved for in this PR.
  • Feat 199: Add awaitTxConfirmation function by @alegadea in #203 - This feature allows to wait until submitted transaction is seen on chain, under the constraints of specified GYAwaitTxParameters.
  • Feat [219, 220, 221]: Make privnet submitTx robust, rename gyGetCurrentSlot, disable cache option by @sourabhxyz in #222 - This breaking change renames currentSlot method of GYTxQueryMonad to slotOfCurrentBlock to clarify it's intent as it gives the slot of the chain tip, i.e., the most recent block. Also, now whenever a transaction is submitted for in privnet, the submitTx function would return only when it sees that the submitted transaction is successfully onchain, using the feature introduced in #203 to await for transaction. Also, Atlas had an undocumented support of experimental "cache" feature. As this feature is still in development, it's decided to not expose it to end users.
  • Feat 224: Fixed wrong calculation of executi...
Read more

v0.2.0

05 May 12:05
28f7d47
Compare
Choose a tag to compare

Breaking Framework Changes

  • Test suite to test against private network has undergone following changes:
    • Type to represent context's user now doesn't have collateral (in PR #108), see it's fields here.
    • Context now has one funder and 8 other users, these other users (ctxUser2 to ctxUser9) start with the same amount of funds and funder (ctxUserF) in contrast starts with a lot more ada (done in PR #96). See more details about exact funds in our guide for it, here.
    • Redundant type UserIdx is removed (in PR #87), changing the interface of functions in Ctx.hs, again refer to our guide to see use of latest interface.
    • Function assertUserFunds has been changed to check against exact transaction fees rather than in window in PR #100.
  • Framework now has support for multi-asset collateral (PR #97 & PR #108), removing the need for dapps to require a UTxO for collateral as framework is capable for selecting suitable UTxO for it. For more details, see these two pages of our guide, Creating Endpoints & Browser Integration. This has led to interface of functions in Node.hs to change where instead of requiring reference to collateral UTxO, it's now a tuple inside Maybe value where Nothing represents that framework is to choose for collateral (if required) and in Just case we get a tuple of reference to collateral with a boolean, if this boolean is False, given collateral is taken as collateral to build transaction and framework doesn't spend it (unless explicitly mentioned by transaction skeleton) and if the boolean is True, framework checks if the given collateral UTxO has exactly 5 ada or not, if yes, behavior is like False case and if no, behavior is as Nothing case, i.e., framework picks suitable UTxO to use as collateral and is also free to spend it.
  • someUTxO now takes parameter to denote for script language (changed for in PR #114) and only returns UTxO which is translatable to that language, i.e., usable by script of that language.
    • In particular, there is additions to GYTxMonad, namely, ownAddresses & availableUTxOs (in PR #124) which would help in writing custom version of someUTxO if required, such as one done in someUTxOWithoutRefScript.

Other Framework Features

  • Earlier, when performing browser integration, there was need to use a library such as CML to add for witness (obtained from wallet api's signTx method) to our transaction body, which just misses this key witness. Besides complication involved in using & understanding another library, this led to issues where transaction hash was getting modified due to different representation of CBOR for involved structures in such libraries. Adding for this is now possible to be done entirely using Atlas (done in PR #99), as illustrated in Creating Endpoints & Browser Integration section of guide.

All PR's involved in this Change

  • Issue #45: Remove redundant UserIdx type by @sourabhxyz in #87
  • Function to assert for exact fee in privnet by @sourabhxyz in #100
  • Remove redundant constraints in cabal.project by @iburzynski in #89
  • Replaced ctxUser1 usage with ctxUserF and creating new users - all having same status by @sourabhxyz in #96
  • Feat 98: Support to add witness (obtained from api.signTx) to original tx cbor by @sourabhxyz in #99
  • add logging to GYTxQueryMonad by @piyushthapa in #76
  • Feat 95: Multi asset collateral support by @sourabhxyz in #97
  • Feat 104: Utilize multi asset collateral support to not explicitly require collateral by @sourabhxyz in #108
  • Update CODEOWNERS by @MatD9 in #116
  • Add Pr template #17 by @Haluk-GeniusYield in #117
  • Logging skeletons before building the Txs by @alegadea in #111
  • Fix incorrect links in Readme file by @sourabhxyz in #115
  • Feat 109 & 113: Parametric someUTxO by @sourabhxyz in #114
  • Feat 123 & 125: Adding method to Node's monad to get for usable UTxOs & own addresses by @sourabhxyz in #124
  • Feat 105: Elaborate cabal file & include version bounds by @sourabhxyz in #112
  • support darwin arch by @piyushthapa in #120

New Contributors

  • @Haluk-GeniusYield made their first contribution in #117

Full Changelog: v0.1.0...v0.2.0

v0.1.0

06 Apr 16:57
c0754d2
Compare
Choose a tag to compare

What's Changed

  • Updated README.md - Turn logos into links by @4TT1L4 in #2
  • Initial commit by @Vardominator in #3
  • [DOCS] Wrong workflow link for GitHub Actions Badge by @4TT1L4 in #7
  • Create Security file by @MatD9 in #4
  • Move haskell-pre-commit-hooks to the Atlas repo#12 by @4TT1L4 in #14
  • Setup and deploy Haddock documentation page by @4TT1L4 in #11
  • Incorporate doctests into CI pipeline by @4TT1L4 in #9
  • Move haskell-pre-commit-hooks to the Atlas repo #12 by @4TT1L4 in #15
  • Add pre-commit hook to prevent commits to main#13 by @4TT1L4 in #16
  • add pre commit hook to prevent commits to main by @4TT1L4 in #55
  • capitalize badge titles and add build status badge by @4TT1L4 in #58
  • [TODO] Create issues for the TODO comments by @4TT1L4 in #41
  • Warning Tab character found in Gift.hs #60 by @4TT1L4 in #61
  • use Latest haskell.nix in flake.nix by @piyushthapa in #52
  • Generate haddock documentation on GitHub Actions by @4TT1L4 in #73
  • Adding new testing utility functions by @alegadea in #72
  • Update CODEOWNERS by @MatD9 in #79
  • Setup and deploy Haddock documentation page #10 by @4TT1L4 in #77
  • Update haddock links in README #80 by @4TT1L4 in #81
  • Issue #47: Add Reference Script in UTxO entry for PSM by @sourabhxyz in #74
  • [Issue #44] Prevent coin balancer from picking reference input UTxO from the set of additional UTxOs by @sourabhxyz in #59
  • Dynamic version in GH workflows by @4TT1L4 in #83
  • Update haddock links in README #80 by @4TT1L4 in #85
  • Remove duplicate cardano-address package from cabal.project by @iburzynski in #90
  • Removed unneeded additional version component by @sourabhxyz in #91
  • 19 release workflow by @4TT1L4 in #88

New Contributors

Full Changelog: https://github.com/geniusyield/atlas/commits/v0.1.0