Create a UTxO RPC client connected to a UTxO RPC service. Provide a UtxorpcClientLogger to perform automated logging.

Call any method of a UTxO RPC service through the functions contained in a UtxorpcClient. Obtain a client by calling one of the client-creating functions:

1. simpleUtxorpcClient ➤ connect to a service using the bare minimum required information.

   1. See quick-start.

2. utxorpcClient ➤ connect to a service using a UtxorpcInfo record.

   1. See example.
3. utxorpcClientWith ➤ provide a GrpcClientConfig for fine grained configuration.

Access the functions of a UtxorpcClient through record access:

fetchBlock (syncClient client)

Close the connection throught client's close function:

close client

To call a UTxO RPC method, you will need a record of the relevant Message instance. Build a Message with defMessage and set its fields with lens operators.

import Control.Lens.Operators ((&), (.~))
import Data.ProtoLens.Message (Message (defMessage))
import qualified Data.Text.Encoding as T
import Proto.Utxorpc.V1.Sync.Sync (FetchBlockRequest)
import Proto.Utxorpc.V1.Sync.Sync_Fields (hash, index)

fetchBlockRequest :: FetchBlockRequest
fetchBlockRequest =
defMessage
    & ref .~
    [ defMessage
        & index .~ 116541970
        & hash .~ T.encodeUtf8 "9d5abce5b1a7d94b141a597fd621a1ff9dcd46579ff1939664364311cd1be338"
    ]

Note that calling a server-stream method requires an input-stream function and initial input-stream state. The input-stream function is of type (a -> HeaderList -> o -> IO a), where a is the initial input-stream state and o is the type of message streamed by the server. The input-stream function folds over its state until the stream is closed.

This SDK supports automated logging through the UtxorpcClientLogger type. It is a record of one user-defined logging function for each of the following events:

1. Request sent.
2. Reply received.
3. Server stream data received.
4. Server stream ended.

For more information, see Logged and the examples.

There are two examples included in the project. There are two provided examples:

1. `/quick-start` shows the bare minimum required to make a single unary request.

stack run client-quick-start -- -p 443

2. `/example` shows a more involved example that uses one of the following two logger implementations:

   1. `exampleSimpleLogger.hs` is a simple logger implementation that prints human-readable output.

      stack run client-example
      Usage: [--katip] <hostName> <port> <tlsEnabled> <useGzip> [<headerKey>:<headerValue> [...]]
      stack run client-example -- "localhost" 443 True False

   2. `exampleKatipLogger.hs` is a more involved logger that demonstrates how to use logging functions that run in a transformer stack. Run the example with `--katip` to use this logger.

      stack run client-example -- --katip "localhost" 443 True False