Skip to content

Commit

Permalink
docs(#98): update endpoints & other sections
Browse files Browse the repository at this point in the history
  • Loading branch information
@sourabhxyz
sourabhxyz committed Dec 13, 2024
1 parent ccd7e85 commit cf69351
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 47 deletions.
65 changes: 33 additions & 32 deletions src/pages/getting-started/endpoints.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The approach here would be
We'll use [Servant](https://docs.servant.dev/en/stable/) to create our endpoints and one may understand it by following their easy to understand tutorial [here](https://docs.servant.dev/en/stable/tutorial/index.html).

<Callout>
Do note that we can also sign the transactions in server using the `signTx` function defined in [`GeniusYield.Types.TxBody`](https://haddock.atlas-app.io/GeniusYield-Types-TxBody.html) module.
Do note that we can also sign the transactions in server using the `signGYTxBody` function defined in [`GeniusYield.Types.TxBody`](https://haddock.atlas-app.io/GeniusYield-Types-TxBody.html) module.
</Callout>

## Providing Data Provider
Expand Down Expand Up @@ -137,9 +137,9 @@ We then see the use of an interesting function `withCfgProviders`. It's type is
Entire code for it is available [here](https://github.com/geniusyield/atlas-examples/tree/main/bet-ref/server-lib/BetRef/Api/Context.hs)
</Callout>

Our endpoints would need an information for our provider, thus we have created the type for it, called `Ctx`. It's usage is made clear by function defined next, `runQuery` which in essence correspond to `ctxRunC` we saw in section on [Integration Tests](./integration-tests.mdx). Reasoning for `runTxI` & `runTxF` follows similarly.
Our endpoints would need an information for our provider, thus we have created the type for it, called `Ctx`. It's usage is made clear by function defined next, `runQuery` and `runTx`.

Note about our handling of collateral: Browser wallets usually have the option to set for collateral, in such a case wallets would create an UTxO specifically to be used as collateral and such an UTxO will be reserved, i.e., wallet won't be spending it. [CIP 40](https://cips.cardano.org/cips/cip40/) changed the properties related to collateral and therefore we can safely take even that UTxO as collateral which has large amounts of ada and it could also contain multiple assets. Therefore if there is no collateral set by browser wallet, framework is capable of choosing suitable UTxO as collateral (and also sets for return collateral & total collateral fields appropriately) and in that case it is also free to spend it, if required by transaction builder. But if however there is a 5-ada collateral set by wallet, then framework would use it as collateral and would also reserve it, i.e., it won't pick to spend it unless explicitly mentioned by transaction skeleton. Also note that, we'll use browser wallet's `getCollateral()` method to get for collateral. This method usually returns a list of ada-only UTxOs in wallet within a specific range (like in case of Nami, it is those with ada less than or equal to 50). We would send first element of this list (if exists) to backend and framework would check if the value contained in this UTxO is exactly 5 ada or not (like Nami's `getCollateral` method returns only a singleton list if collateral is set in wallet), if not, framework would ignore this (i.e., would not reserve for it) and would itself pick suitable UTxO as collateral. If however you want this to be reserved (& of course used as collateral) regardless of it's value, see the comment in call to `runGYTxMonadNodeF` in `runTxF` function.
Note about our handling of collateral: Browser wallets usually have the option to set for collateral, in such a case wallets would create an UTxO specifically to be used as collateral and such an UTxO will be reserved, i.e., wallet won't be spending it. [CIP 40](https://cips.cardano.org/cips/cip40/) changed the properties related to collateral and therefore we can safely take even that UTxO as collateral which has large amounts of ada and it could also contain multiple assets. Therefore if there is no collateral set by browser wallet, framework is capable of choosing suitable UTxO as collateral (and also sets for return collateral & total collateral fields appropriately) and in that case it is also free to spend it, if required by transaction builder. But if however there is a 5-ada collateral set by wallet, then framework would use it as collateral and would also reserve it, i.e., it won't pick to spend it unless explicitly mentioned by transaction skeleton. Also note that, we'll use browser wallet's `getCollateral()` method to get for collateral. This method usually returns a list of ada-only UTxOs in wallet within a specific range (like in case of Nami, it is those with ada less than or equal to 50). We would send first element of this list (if exists) to backend and framework would check if the value contained in this UTxO is exactly 5 ada or not (like Nami's `getCollateral` method returns only a singleton list if collateral is set in wallet), if not, framework would ignore this (i.e., would not reserve for it) and would itself pick suitable UTxO as collateral. If however you want this to be reserved (& of course used as collateral) regardless of it's value, see the comment in call to `runGYTxBuilderMonadIO` in `runTx` function.

```haskell
-- | Our Context.
Expand All @@ -149,39 +149,40 @@ data Ctx = Ctx
}

-- | To run for simple queries, the one which don't requiring building for transaction skeleton.
runQuery :: Ctx -> GYTxQueryMonadNode a -> IO a
runQuery :: Ctx -> GYTxQueryMonadIO a -> IO a
runQuery ctx q = do
let nid = cfgNetworkId $ ctxCoreCfg ctx
let nid = cfgNetworkId $ ctxCoreCfg ctx
providers = ctxProviders ctx
runGYTxQueryMonadNode nid providers q

-- | Wraps our skeleton under `Identity` and calls `runTxF`.
runTxI :: Ctx
-> [GYAddress] -- ^ User's used addresses.
-> GYAddress -- ^ User's change address.
-> Maybe GYTxOutRefCbor -- ^ Browser wallet's reserved collateral (if set).
-> GYTxMonadNode (GYTxSkeleton v)
-> IO GYTxBody
runTxI = coerce (runTxF @Identity)

-- | Tries to build for given skeletons wrapped under traversable structure.
runTxF :: Traversable t
=> Ctx
-> [GYAddress] -- ^ User's used addresses.
-> GYAddress -- ^ User's change address.
-> Maybe GYTxOutRefCbor -- ^ Browser wallet's reserved collateral (if set).
-> GYTxMonadNode (t (GYTxSkeleton v))
-> IO (t GYTxBody)
runTxF ctx addrs addr collateral skeleton = do
let nid = cfgNetworkId $ ctxCoreCfg ctx
runGYTxQueryMonadIO nid providers q

-- | Tries to build for given skeleton.
runTx ::
Ctx ->
-- | User's used addresses.
[GYAddress] ->
-- | User's change address.
GYAddress ->
-- | Browser wallet's reserved collateral (if set).
Maybe GYTxOutRefCbor ->
GYTxBuilderMonadIO (GYTxSkeleton v) ->
IO GYTxBody
runTx ctx addrs addr collateral skeleton = do
let nid = cfgNetworkId $ ctxCoreCfg ctx
providers = ctxProviders ctx
runGYTxMonadNodeF GYRandomImproveMultiAsset nid providers addrs addr
(collateral >>=
(\c -> Just (getTxOutRefHex c,
True -- Make this as `False` to not do 5-ada-only check for value in this given UTxO to be used as collateral.
runGYTxBuilderMonadIO
nid
providers
addrs
addr
( collateral
>>= ( \c ->
Just
( getTxOutRefHex c
, True -- Make this as `False` to not do 5-ada-only check for value in this given UTxO to be used as collateral.
)
)
) skeleton
)
)
(skeleton >>= buildTxBody)
```

## Submit Endpoint
Expand Down
17 changes: 2 additions & 15 deletions src/pages/getting-started/testing.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,8 @@ Mind you we are using [`tasty`](https://hackage.haskell.org/package/tasty) to wr
Our objective here would be to write test cases for one of two main operations
from the `bet-ref` example - namely for placing bet operation.

The test-suite given can be executed with `cabal run betref-tests` command. Do note that, in the initial setup, you would notice an initial test failure, this is due to a quirk in the workings of [`cardano-testnet`](https://github.com/IntersectMBO/cardano-node/tree/master/cardano-testnet) when spinning up private testnet and should be ignored. Note that before running this command, make sure that you have required version of `cardano-cli` & `cardano-node` installed and available inside your path, use `cabal install --package-env=$(pwd) --overwrite-policy=always cardano-cli cardano-node` from the root of the `atlas-examples` repository to achieve that.

### Testing environment

Unified testing hides implementation details specific to ledger backends under
Expand Down Expand Up @@ -343,14 +345,6 @@ firstBetTest' = firstBetTest
(valueFromLovelace 20_000_000)
```

Use the following command to observe test's results (being granted you are inside a Nix
shell):

```bash
$ cabal run atlas-unified-tests -- -p 'Emulator.Place bet.Placing first bet'
```


### Multiple bets test

Now let's write a slightly more involved test. This time we want to make sure
Expand Down Expand Up @@ -472,13 +466,6 @@ mkMultipleBetsTest betUntil betReveal betStep bets ws = do
(show vAfter)
```

Use the following command to observe the test's results (being granted you are inside a Nix
shell):

```bash
$ cabal run atlas-unified-tests -- -p 'Emulator.Place bet.Multiple bets'
```

### Writing negative tests

But sometimes we want a test to fail! What happens if the newly placed bet is
Expand Down

0 comments on commit cf69351

Please sign in to comment.