|
10 | 10 | {-# LANGUAGE UndecidableInstances #-} |
11 | 11 |
|
12 | 12 | module Cardano.Api.Internal.Experimental.Tx |
13 | | - ( UnsignedTx (..) |
| 13 | + ( -- * Creating transactions using the new API |
| 14 | + |
| 15 | + -- | |
| 16 | + -- Both the old and new APIs can be used to create transactions, and |
| 17 | + -- it is possible to transform a transaction from one format to the other |
| 18 | + -- as they share the same representation. However, the focus will shift |
| 19 | + -- towards using the new API, while the old API will be deprecated to ensure |
| 20 | + -- simplicity, closer alignment with the ledger, and easier maintenance. |
| 21 | + -- |
| 22 | + -- In both the new and old APIs, constructing a transaction requires creating |
| 23 | + -- a 'TxBodyContent', along with at least one witness (for example, a |
| 24 | + -- 'ShelleyWitnessSigningKey') to sign the transaction. |
| 25 | + -- This process remains unchanged. |
| 26 | + -- |
| 27 | + -- To learn how to create a transaction using the old API, see the |
| 28 | + -- "Cardano.Api.Internal.Tx.Body" documentation. |
| 29 | + -- |
| 30 | + -- In the examples below, the following qualified modules are used: |
| 31 | + -- |
| 32 | + -- @ |
| 33 | + -- import qualified Cardano.Api as Api -- the general `cardano-api` exports (including the old API) |
| 34 | + -- import qualified Cardano.Api.Script as Script -- types related to scripts (Plutus and native) |
| 35 | + -- import qualified Cardano.Api.Ledger as Ledger -- cardano-ledger re-exports |
| 36 | + -- import qualified Cardano.Api.Experimental as Exp -- the experimental API |
| 37 | + -- @ |
| 38 | + -- |
| 39 | + -- For instructions on how to do this, refer to the @Test.Cardano.Api.Experimental@ documentation. |
| 40 | + |
| 41 | + -- ** Creating a 'TxBodyContent' |
| 42 | + |
| 43 | + -- | |
| 44 | + -- Regardless of whether the experimental or the traditional API is used, creating a 'TxBodyContent' |
| 45 | + -- is necessary. |
| 46 | + -- |
| 47 | + -- You can see how to do this in the documentation of the "Cardano.Api.Internal.Tx.Body" module. |
| 48 | + |
| 49 | + -- ** Balancing a transaction |
| 50 | + |
| 51 | + -- | |
| 52 | + -- If a UTXO has exactly 12 ada, the transaction could be constructed as described in |
| 53 | + -- "Cardano.Api.Internal.Tx.Body", and it would be valid. However: |
| 54 | + -- |
| 55 | + -- * Ada may be wasted |
| 56 | + -- * The UTXO that we intend to spend may not contain exactly 12 ada |
| 57 | + -- * The transaction may not be this simple. |
| 58 | + -- |
| 59 | + -- For these reasons, it is recommended to balance the transaction before proceeding with |
| 60 | + -- signing and submitting. |
| 61 | + -- |
| 62 | + -- For instructions on how to balance a transaction, refer to the "Cardano.Api.Internal.Fees" documentation. |
| 63 | + |
| 64 | + -- ** Creating a 'ShelleyWitnessSigningKey' |
| 65 | + |
| 66 | + -- | |
| 67 | + -- Signing a transaction requires a witness, such as a 'ShelleyWitnessSigningKey'. |
| 68 | + -- |
| 69 | + -- For instructions on creating a 'ShelleyWitnessSigningKey' refer to the "Cardano.Api.Internal.Tx.Sign" documentation. |
| 70 | + |
| 71 | + -- ** Creating a transaction using the new API |
| 72 | + |
| 73 | + -- | |
| 74 | + -- This section outlines how to create a transaction using the new API. First, |
| 75 | + -- create an 'UnsignedTx' using the 'makeUnsignedTx' function and the 'Era' and |
| 76 | + -- 'TxBodyContent' that we defined earlier: |
| 77 | + -- |
| 78 | + -- @ |
| 79 | + -- let (Right unsignedTx) = Exp.makeUnsignedTx era txBodyContent |
| 80 | + -- @ |
| 81 | + -- |
| 82 | + -- Next, use the key witness to sign the unsigned transaction with the 'makeKeyWitness' function: |
| 83 | + -- |
| 84 | + -- @ |
| 85 | + -- let transactionWitness = Exp.makeKeyWitness era unsignedTx (Api.WitnessPaymentKey signingKey) |
| 86 | + -- @ |
| 87 | + -- |
| 88 | + -- Finally, sign the transaction using the 'signTx' function: |
| 89 | + -- |
| 90 | + -- @ |
| 91 | + -- let newApiSignedTx :: Ledger.Tx (Exp.LedgerEra Exp.ConwayEra) = Exp.signTx era [] [transactionWitness] unsignedTx |
| 92 | + -- @ |
| 93 | + -- |
| 94 | + -- The empty list represents the bootstrap witnesses, which are not needed in this case. |
| 95 | + -- |
| 96 | + -- The transaction is now signed. |
| 97 | + |
| 98 | + -- ** Converting a transaction from the new API to the old API |
| 99 | + |
| 100 | + -- | |
| 101 | + -- A transaction created with the new API can be easily converted to the old API by |
| 102 | + -- wrapping it with the 'ShelleyTx' constructor: |
| 103 | + -- |
| 104 | + -- @ |
| 105 | + -- let oldStyleTx :: Api.Tx Api.ConwayEra = ShelleyTx sbe newApiSignedTx |
| 106 | + -- @ |
| 107 | + |
| 108 | + -- ** Inspecting transactions |
| 109 | + |
| 110 | + -- | |
| 111 | + -- When using a 'Tx' created with the experimental API, the 'TxBody' and |
| 112 | + -- 'TxWits' can be extracted using the 'txBody' and 'txWits' lenses from |
| 113 | + -- "Cardano.Api.Ledger" respectively. |
| 114 | + |
| 115 | + -- * Contents |
| 116 | + UnsignedTx (..) |
14 | 117 | , UnsignedTxError (..) |
15 | 118 | , makeUnsignedTx |
16 | 119 | , makeKeyWitness |
@@ -47,7 +150,7 @@ import GHC.Stack |
47 | 150 | import Lens.Micro |
48 | 151 |
|
49 | 152 | -- | A transaction that can contain everything |
50 | | --- except key witnesses |
| 153 | +-- except key witnesses. |
51 | 154 | newtype UnsignedTx era |
52 | 155 | = UnsignedTx (Ledger.Tx (LedgerEra era)) |
53 | 156 |
|
|
0 commit comments