Utxorpc.Client

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

How to use this library

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

Building Messages

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"
    ]

Server Stream Methods

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.

Logging

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 UtxorpcClientLogger and the examples.

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

Creating a UtxorpcClient

data UtxorpcInfo m

Configuration info for a UTxO RPC Client. For more fine-grained control, use GrpcClientConfig and utxorpcClientWith

Constructors

UtxorpcInfo

Fields

• _hostName :: HostName

  Host name of the service.

• _portNumber :: PortNumber

  Port number of the service.

• _tlsEnabled :: UseTlsOrNot

  Whether or not to use TLS.

• _useGzip :: Bool

  Whether or not to use gzip compression.

• _clientHeaders :: [(ByteString, ByteString)]

  Headers to include in each request (e.g., API key/authorization).

• _logger :: Maybe (UtxorpcClientLogger m)

  Log all RPC events.

simpleUtxorpcClient

Arguments

:: HostName

Host name of the service.

-> PortNumber

Port number of the service.

-> UseTlsOrNot

Whether or not to use TLS.

-> IO (Either ClientError UtxorpcClient)

Make a connection to a UTxO RPC service with the minimum required information. No compression is used, no headers are added, and no logging is performed. For more configurability, use utxorpcClient or utxorpcClientWith.

utxorpcClient :: UtxorpcInfo m -> IO (Either ClientError UtxorpcClient)

Connect to a UTxO RPC service from a UtxorpcInfo. Provides more configurability than simpleUtxorpcClient but less than utxorpcClientWith.

utxorpcClientWith :: GrpcClientConfig -> Maybe (UtxorpcClientLogger m) -> IO (Either ClientError UtxorpcClient)

Connect to a UTxO RPC from a GrpcClientConfig. For a simpler interface with less configurability, use utxorpcClient or simpleUtxorpcClient.

The UtxorpcClient

data UtxorpcClient

Methods for each module in UTxO RPC.

>>> fetchBlock (queryClient client) defMessage

Constructors

UtxorpcClient

Fields

• queryClient :: QueryClient

  Query module service methods.

• submitClient :: SubmitClient

  Submit module service methods.

• syncClient :: SyncClient

  Sync module service methods.

• watchClient :: WatchClient

  Watch module service methods.

• close :: IO (Either ClientError ())

  Closes the gRPC connection.

data QueryClient

Methods of the Query module

Constructors

QueryClient

Fields

• readParams :: ReadParamsRequest -> UnaryReply ReadParamsResponse
• readUtxos :: ReadUtxosRequest -> UnaryReply ReadUtxosResponse
• searchUtxos :: SearchUtxosRequest -> UnaryReply SearchUtxosResponse
• streamUtxos :: ServerStreamCall ReadUtxosRequest ReadUtxosResponse

data SubmitClient

Methods of the Submit module

Constructors

SubmitClient

Fields

• submitTx :: SubmitTxRequest -> UnaryReply SubmitTxResponse
• readMempool :: ReadMempoolRequest -> UnaryReply ReadMempoolResponse
• waitForTx :: ServerStreamCall WaitForTxRequest WaitForTxResponse
• watchMempool :: ServerStreamCall WatchMempoolRequest WatchMempoolResponse

data SyncClient

Methods of the Sync module

Constructors

SyncClient

Fields

• fetchBlock :: FetchBlockRequest -> UnaryReply FetchBlockResponse
• dumpHistory :: DumpHistoryRequest -> UnaryReply DumpHistoryResponse
• followTip :: ServerStreamCall FollowTipRequest FollowTipResponse

newtype WatchClient

Methods of the watch module

Constructors

WatchClient

Fields

• watchTx :: ServerStreamCall WatchTxRequest WatchTxResponse

RPC call function types

type ServerStreamCall i o

Arguments

 = forall a. a

The initial state for the stream processing function.

-> i

The request message to send to the service.

-> (a -> HeaderList -> o -> IO a)

The stream processing function. It is a fold over some state a with stream messages o.

-> ServerStreamReply a

The final state of the stream processing function, or an error.

Type definition for functions that make calls to server stream methods. Note that the stream state, a, can be different for each call.

type ServerStreamReply a = IO (Either ClientError (Either TooMuchConcurrency (a, HeaderList, HeaderList)))

The type returned by calls to server stream methods. a is the final state of the stream processing function.

type UnaryReply o = IO (Either ClientError (Either TooMuchConcurrency (RawReply o)))

The type returned by calls to unary service methods.

Logging

data UtxorpcClientLogger m

Logging functions to log requests, replies, server stream messages, and server stream endings. A UUID is generated for each request and passed downstream to the other logging functions.

Constructors

UtxorpcClientLogger

Fields

• requestLogger :: RequestLogger m

  Log outgoing requests.

• replyLogger :: ReplyLogger m

  Log incoming unary replies.

• serverStreamLogger :: ServerStreamLogger m

  Log incoming server stream messages.

• serverStreamEndLogger :: ServerStreamEndLogger m

  Log the end of a server stream.

• unlift :: forall x. m x -> IO x

  Provided here as a convenience to allow logging functions to be written in any monadic stack without having to apply the unlift function to each logging function individually.

type RequestLogger m

Arguments

 = forall i. (Show i, Message i)

=> ByteString

The RPC path

-> GrpcClient

Included because it contains useful information such as the server address.

-> UUID

Generated for this request, and passed to other logging functions for other RPC events generated by this request. E.g., A unary request and its reply both have the same UUID.

-> i

The request message being sent.

-> m ()

Log outgoing requests of all types (i.e., unary requests and server stream requests).

type ReplyLogger m

Arguments

 = forall o. (Show o, Message o)

=> ByteString

The RPC path

-> GrpcClient

Included because it contains useful information such as the server address.

-> UUID

Generated for the request that this reply is associated with.

-> Either ClientError (Either TooMuchConcurrency (RawReply o))

Message received from the service (with headers) or an error.

-> m ()

Log unary replies.

type ServerStreamLogger m

Arguments

 = forall o. (Show o, Message o)

=> ByteString

The RPC path

-> GrpcClient

Included because it contains useful information such as the server address.

-> (UUID, Int)

The UUID was generated for the request that caused this reply, the Int is the index of this message in the stream.

-> o

Message received from the service.

-> m ()

Log server stream messages.

type ServerStreamEndLogger m

Arguments

 = ByteString

The RPC path

-> GrpcClient

Included because it contains useful information such as the server address.

-> (UUID, Int)

The UUID was generated for the request that caused this reply, the Int is the total number of messages received in the stream.

-> (HeaderList, HeaderList)

Headers and Trailers.

-> m ()