Skip to content

Commit 4ec548a

Browse files
palaspalas
committed
Apply suggestions by @olgahryniuk 
1 parent db62111 commit 4ec548a

File tree

1 file changed

+72
-70
lines changed
  • cardano-api/src/Cardano/Api/Internal

1 file changed

+72
-70
lines changed

‎cardano-api/src/Cardano/Api/Internal/IPC.hs‎

Lines changed: 72 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -13,23 +13,23 @@
1313

1414
-- | Node IPC protocols
1515
--
16-
-- This module provides the client side of the node-to-client IPC protocol
17-
-- used to communicate with a local Cardano node. This can be used to
18-
-- query the node for information, to submit transactions, and even to
19-
-- get historical information about the chain by using the
20-
-- 'ChainSync' protocol.
16+
-- This module provides the client side of the node-to-client interprocess
17+
-- communication (IPC) for interacting with a local Cardano node. It supports
18+
-- querying the node for information, submitting transactions, and retrieving
19+
-- historical chain data using the @ChainSync@ protocol.
2120
module Cardano.Api.Internal.IPC
2221
( -- * Examples
2322

24-
-- | In this section, we show two examples: one for querying the node
25-
-- and obtain some basic information, and another one for submitting a
26-
-- transaction to the node.
23+
-- | This section provides two examples:
2724
--
28-
-- To find out about how to create a transaction, see the documentation
29-
-- in "Cardano.Api.Internal.Tx.Body".
25+
-- 1. Querying the node to obtain basic information
26+
-- 2. Submitting a transaction to the node.
3027
--
31-
-- For the following examples we will use the following qualified imports
32-
-- from @cardano-api@:
28+
-- For details on how to create a transaction, see the
29+
-- "Cardano.Api.Internal.Tx.Body" documentation.
30+
--
31+
-- The following qualified imports from @cardano-api@ are
32+
-- used in the examples below:
3333
--
3434
-- @
3535
-- import qualified Cardano.Api as Api
@@ -38,42 +38,42 @@ module Cardano.Api.Internal.IPC
3838
-- import qualified Cardano.Api.Shelley as Shelley
3939
-- @
4040
--
41-
-- We will also use the following explicit import from @base@:
41+
-- The following explicit import from @base@ is also required:
4242
--
4343
-- @
4444
-- import Control.Monad.Except (runExceptT)
4545
-- @
4646
--
47-
-- And we will assume we are working on top of the @IO@ monad and that
48-
-- we have unqualified access to the @Prelude@ module.
47+
-- The examples assume the use of the @IO@ monad and unqualified
48+
-- access to the @Prelude@ module.
4949

5050
-- ** Constructing connection information
5151

52-
-- | Independently of whether we want to query the node or submit transactions,
53-
-- the first thing we need to do is to gather the connection information.
52+
-- | Regardless of whether the goal is to query the node or submit transactions,
53+
-- the first step is to gather the connection information.
5454
--
55-
-- We need three pieces of information:
55+
-- The following information is required:
5656
--
57-
-- * The number of slots per epoch for the network the node is connected to.
58-
-- We can obtain this information by looking for the @epochLength@ key in
59-
-- the @shelley-genesis.json@ file that the node is using to connect to the
60-
-- network. For the preview network, at the time of writing, it is @86_400@,
61-
-- but it can change. This value, and other genesis parameters, can also be
62-
-- queried by using the 'QueryGenesisParameters' query.
63-
-- * In the case we are connecting to a testnet, we also need to find out
64-
-- the network identifier for the network the node is connected to. This can be
65-
-- obtained by looking for the @networkMagic@ key in the @shelley-genesis.json@
66-
-- file that the node is using to connect to the network. For the preview
67-
-- network, the network identifier is currently @2@.
68-
-- * The path to the socket file of the node. This can be set when starting the
69-
-- node by using the @--socket-path@ parameter. By default it can usually be
70-
-- found in the @db@ subfolder of the node's working directory.
57+
-- * __The number of slots per epoch__. This value depends on the network the
58+
-- node is connected to. It can be obtained by inspecting the @epochLength@
59+
-- key in the @shelley-genesis.json@ file used by the node. On the preview
60+
-- network, the value is, at the time of writing, @86_400@, but it can
61+
-- change. This value and other genesis parameters can also be obtained
62+
-- using the 'QueryGenesisParameters' query.
63+
-- * __Network identifier__. When connecting to a testnet, the network identifier
64+
-- is also required. It can be obtained by looking for the @networkId@
65+
-- obtained by looking up the @networkMagic@ key in the @shelley-genesis.json@
66+
-- file that the node is uses to connect to the network. For the preview
67+
-- network, the current identifier is @2@.
68+
-- * __Socket path__. The path to the node's socket file. It can be set using
69+
-- the @--socket-path@ parameter when starting the node. By default, it is
70+
-- typically located in the @db@ subfolder of the node's working directory.
7171
--
72-
-- Then, we gather all the information into a 'LocalNodeConnectInfo' value.
72+
-- Then, combine all the required information into a 'LocalNodeConnectInfo' value.
7373
--
74-
-- For example, let's assume we are connecting to the preview network, and that the
75-
-- socket file is located at @\/home\/user\/cardano-node\/db\/node.socket@. We could
76-
-- then create the 'LocalNodeConnectInfo' value as follows:
74+
-- For example, assume the node is connected to the preview network and the socket
75+
-- file is located at @\/home\/user\/cardano-node\/db\/node.socket@. The
76+
-- 'LocalNodeConnectInfo' value can then be constructed as follows:
7777
--
7878
-- @
7979
-- let connectionInfo =
@@ -84,37 +84,38 @@ module Cardano.Api.Internal.IPC
8484
-- }
8585
-- @
8686

87-
-- ** Querying the node for the UTxO set
87+
-- ** Querying the node for the UTXO set
8888

89-
-- | Let's imagine we want to obtain the set of transaction outputs that
90-
-- are currently unspent in the network (UTxO set).
89+
-- | To obtain the set of unspent transaction outputs (UTXO set) from the network,
90+
-- the current era must first be determined.
9191

9292
-- *** Obtaining the current era
9393

94-
-- | Depending on the type of query we want to perform, we usually need
95-
-- to know what era the node is currently in. We can hardcode this
96-
-- information by using one of the constructors of the 'ShelleyBasedEra' type.
97-
-- But we can also obtain this information from the node, as follows:
94+
-- | Many queries require knowing the current era. This can be hardcoded using one of
95+
-- the 'ShelleyBasedEra' constructors, but it is also possible to retreive it from
96+
-- the node:
9897
--
9998
-- @
10099
-- eEra <- runExceptT $ Api.queryNodeLocalState connectionInfo Network.VolatileTip Api.QueryCurrentEra
101100
-- @
102101
--
103-
-- Here, 'VolatileTip' means we want to get the information out of the most recent block that the
104-
-- node is aware of. The disadvantage is that the information we get may potentially be rolled back
105-
-- and stop being valid. We need to account for this. Alternatively, we can use 'ImmutableTip' to
106-
-- obtain the information from the most recent block that is assumed by the consensus algorithm
107-
-- to be final, and that won't be rolled back. But this information is not so recent, in mainnet
108-
-- this is about 36 hours in the past.
102+
-- 'VolatileTip' requests information from the most recent block the node is aware of.
103+
-- It is important to note that this information is not guaranteed to remain valid, as
104+
-- it may be rolled back.
105+
--
106+
-- Alternatively, 'ImmutableTip' can be used to obtain information from the most recent
107+
-- block considered as final by the consensus algorithm. While this data is stable and will
108+
-- not be rolled back, it is less recent – on mainnet, it is typically about 36 hours
109+
-- begind the current time.
109110
--
110-
-- 'QueryCurrentEra' is the constructor of the query we want to run. In this case, we want to
111-
-- obtain the current era of the node.
111+
-- 'QueryCurrentEra' is the constructor of the query that retrieves the node's current
112+
-- era.
112113
--
113-
-- The result of the query is an 'ExceptT' monad, which we can run by using the 'runExceptT'
114-
-- function, which in turn gives us a @eEra@ value of type @Either AcquiringFailure AnyCardanoEra@.
114+
-- The query returns an 'ExceptT' monad, which can be run using the 'runExceptT'
115+
-- function. This yields an @eEra@ value of type @Either AcquiringFailure AnyCardanoEra@.
115116
--
116-
-- This is an example of how to unwrap this value into a 'ShelleyBasedEra' based era, assuming the node
117-
-- is not still running Byron:
117+
-- Below is an example of how to unwrap this value into a 'ShelleyBasedEra' based era, assuming the node
118+
-- is not running Byron:
118119
--
119120
-- @
120121
-- Api.AnyShelleyBasedEra sbe :: Api.AnyShelleyBasedEra <- case eEra of
@@ -127,12 +128,13 @@ module Cardano.Api.Internal.IPC
127128
-- Left Shelley.AFPointNotOnChain -> error "Error, point queried is not on chain!"
128129
-- @
129130
--
130-
-- 'AFPointToolOld' and 'AFPointNotOnChain' should not happen either with 'VolatileTip' or 'ImmutableTip'.
131+
-- 'AFPointToolOld' and 'AFPointNotOnChain' errors should not occur when querying with
132+
-- either 'VolatileTip' or 'ImmutableTip'.
131133

132-
-- *** Obtaining the UTxO set
134+
-- *** Obtaining the UTXO set
133135

134-
-- | Now that we know the current era, we can query the node for the UTxO set similarly
135-
-- by using the 'QueryUTxO' query as follow:
136+
-- | After determining the current era, the node can be queried for the UTXO set using
137+
-- the 'QueryUTxO' query as follows:
136138
--
137139
-- @
138140
-- eUtxo <-
@@ -143,8 +145,8 @@ module Cardano.Api.Internal.IPC
143145
-- (Api.QueryInEra (Api.QueryInShelleyBasedEra sbe (Api.QueryUTxO Api.QueryUTxOWhole)))
144146
-- @
145147
--
146-
-- This time, @eUtxo@ has a nested type of @Either AcquiringFailure (Either EraMismatch (UTxO era))@.
147-
-- So we can unwrap it as follows:
148+
-- This returns, a nested type of @Either AcquiringFailure (Either EraMismatch (UTXO era))@.
149+
-- You can unwrap it as follows:
148150
--
149151
-- @
150152
-- utxo <- case eUtxo of
@@ -161,33 +163,33 @@ module Cardano.Api.Internal.IPC
161163
-- Left Shelley.AFPointNotOnChain -> error "Error, point queried is not on chain!"
162164
-- @
163165
--
164-
-- Alternatively, to avoid having nested result types, we can also use the convenience
166+
-- Alternatively, to avoid nested result types, you can use convenience
165167
-- functions and types from "Cardano.Api.Internal.Convenience.Query".
166-
-- The obtained @utxo@ is a standard @Map@ of type @Map TxIn (TxOut CtxUTxO era)@.
168+
-- The obtained @utxo@ variable is a standard @Map@ of type @Map TxIn (TxOut CtxUTxO era)@.
167169

168170
-- ** Submitting a transaction
169171

170-
-- | Let's assume we have a signed transaction of the latest era that we want to submit to the node,
171-
-- and that it is in the variable @signedTx@ of type @Tx era@.
172+
-- | Assume there is a signed transaction in the latest era that you would like to submit
173+
-- to the node. Assume it is stored in the variable @signedTx@ of type @Tx era@.
172174
--
173-
-- You can find out how to make such a transaction by looking at the documentation of the
174-
-- "Cardano.Api.Internal.Tx.Body" module.
175+
-- For details on how to create such a transaction, see the "Cardano.Api.Internal.Tx.Body"
176+
-- documentation.
175177
--
176-
-- We can send it to the node by using the 'submitTxToNodeLocal' function as follows:
178+
-- To submit the transaction to the node, use the 'submitTxToNodeLocal' function as follows:
177179
--
178180
-- @
179181
-- result <- Api.submitTxToNodeLocal connectionInfo (Api.TxInMode sbe signedTx)
180182
-- @
181183
--
182-
-- The result of the submission is a 'SubmitResult' value, which can be inspected as follows:
184+
-- The result is a 'SubmitResult' value, which can be inspected as follows:
183185
--
184186
-- @
185187
-- case result of
186188
-- Api.SubmitSuccess -> putStrLn "Transaction submitted successfully!"
187189
-- Api.SubmitFail reason -> error $ "Error submitting transaction: " ++ show reason
188190
-- @
189191
--
190-
-- If the command succeeds, then the transaction will be on the node's mempool ready
192+
-- If the command succeeds, the transaction gets into the node's mempool, ready
191193
-- to be included in a block.
192194

193195
-- * Node interaction

0 commit comments

Comments
 (0)