Added examples of transaction creation to Haddock #698
Conversation
palas
requested review from
dcoutts,
Jimbo4350,
erikd,
newhoggy,
carbolymer,
smelc,
kevinhammond,
CarlosLopezDeLara and
disassembler
as code owners
| -- let sbe = Api.shelleyBasedEra :: Api.ShelleyBasedEra Api.ConwayEra | ||
| -- @ | ||
| -- | ||
| -- We can also derive it from 'ConwayEra' from 'Cardano.Api.Experimental' by using the 'convert' function: |
There was a problem hiding this comment.
So I think this is a bad UI. We should have a defaultTxBodyContent defined in an experimental module:
defaultTxBodyContent
:: ()
=> Era era
-> TxBodyContent BuildTx era
We want to avoid mixing the old api and the new api (but obviously allow for migration e.g via convert).
These haddocks are excellent but what we should do is have haddocks strictly describing the old api, the new api and how to migrate from the old to the new.
Co-authored-by: Clément Hurlin <[email protected]>
palas
force-pushed
the
haddock-for-experimental-api
branch
from
ec017ee to
bd4f6ba
Compare
palas
added
documentation
palas
force-pushed
the
haddock-for-experimental-api
branch
from
0ddace3 to
c9d390f
Compare
| ( parseTxId | ||
|
|
||
| -- * Transaction bodies | ||
| ( -- * Creating a 'TxBodyContent' |
There was a problem hiding this comment.
Let's leave out mention of the experimental api in this section. You can add a separate section at the bottom mentioning the small tweak:
We can also derive it from [ConwayEra](https://github.com/IntersectMBO/cardano-api/pull/698/Cardano-Api-Eras-Core.html#t:ConwayEra) from [Experimental](https://github.com/IntersectMBO/cardano-api/pull/698/Cardano-Api.html#v:Experimental) by using the [convert](https://github.com/IntersectMBO/cardano-api/pull/698/Cardano-Api-Eon-Convert.html#v:convert) function:
let era = Exp.ConwayEra
let sbe = Api.convert era
Currently how the imports listed make it seem like you need:
import qualified Cardano.Api.Experimental as Exp -- the experimental API
| -- ** Balancing a transaction | ||
|
|
||
| -- | | ||
| -- If we have a UTxO with exactly 12 ADA, and 2 ADA is enough for the fees, we could just construct |
There was a problem hiding this comment.
We can word this better and we should think of this in terms of consumption and production (see preservation of value in the Shelley spec) if we want to be thorough. This is in the Shelley spec:
You would need to look through the other specs to confirm if these functions have been modified (likely with the introduction of multi-assets). We should say something like:
"A transaction is considered balanced if the value consumed is equivalent to the value produced. In the simplest terms a transaction that simply spends lovelace needs to be concerned with the total lovelace that exists at the inputs, the output(s) and the transaction fee. In other words:
inputs = outputs + fee"
You can then walk through the simple example of manually balancing a tx and point out that although the transaction is valid, you are overpaying for fees.
Overpaying for fees is not an invalid transaction.
| -- | ||
| -- We could do it analogously if we wanted to use an extended key, for example, using 'AsPaymentExtendedKey' and 'WitnessPaymentExtendedKey'. | ||
|
|
||
| -- ** Creating a transaction using the old API |
There was a problem hiding this comment.
I would put this section in the old API.
| -- let oldStyleTx :: Api.Tx Api.ConwayEra = ShelleyTx sbe newApiSignedTx | ||
| -- @ | ||
|
|
||
| -- ** Inspecting transactions |
There was a problem hiding this comment.
Same here. If it doesn't have to do with the new api, move it to the old api modules. The only thing we should be talking about with respect to the old api is how to convert between transactions from old and new.
| -- | | ||
| -- The documentation of the "Cardano.Api.Tx.Body" module shows how to create a 'TxBodyContent' for a | ||
| -- transaction that takes 12 ADA and sends 10 ADA to an address, and spends 2 ADA on fees. If we have a | ||
| -- UTxO with exactly 12 ADA, and 2 ADA is enough for the fees, this could be a valid transaction. But still, |
There was a problem hiding this comment.
Not could be, it is a valid transaction. This working will be confusing to newcomers. 2 ADA is more than enough for fees on mainnet so I would talk about it in that context, say the transaction is valid but you are overspending on fees. You also need to talk about tx outputs to make the explanation clearer.
| -- finding this balance can be quite tricky. But fortunately, we have functions that help achieve this. | ||
| -- | ||
| -- This module provides several different ways of calculating the fees for a transaction or altogether | ||
| -- balancing a draft transaciton, which require different amounts of information, and provide different levels |
| -- * The map of all deposits for drep credentials that are being unregistered in this transaction. | ||
| -- * Plutus script execution units for all script witness we are used in the transaction. | ||
| -- | ||
| -- For this example, we are assuming we are doing nothing like that and using not scripts, |
There was a problem hiding this comment.
"we are assuming we are only spending key locked UTxOs and so we can ignore the above"
| -- | ||
| -- 5. Counts for: | ||
| -- | ||
| -- * The collateral amount we are depositing. This is only required for transactions that |
There was a problem hiding this comment.
that have plutus scripts.
| -- exampleChangeAddress | ||
| -- @ | ||
| -- | ||
| -- This will give us a balanced transaction, with the fees calculated, and the change output. |
There was a problem hiding this comment.
A balanced transaction body, that still needs to be signed.
Changelog
Context
Prompted by this slack discussion
How to trust this PR
Have a read of the haddock.
Checklist