[Miner] feat: add TxClient

docs/pkg/client/README.md

@@ -1,99 +1,125 @@
 # Package `client`
 
-> Standardized interfaces facilitating interactions with blockchain functionalities.
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Architecture Overview](#architecture-overview)
+  - [Component Diagram Legend](#component-diagram-legend)
+  - [Clients Dependency Tree](#clients-dependency-tree)
+  - [Network Interaction](#network-interaction)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Example](#basic-example)
+  - [Advanced Usage](#advanced-usage)
+  - [Configuration](#configuration)
+- [API Reference](#api-reference)
+- [Best Practices](#best-practices)
+- [FAQ](#faq)
+
 
 ## Overview
 
-The `client` package serves as a foundational layer for applications aiming to integrate with various blockchain platforms. It abstracts the complexities of sending, receiving, and querying blockchain data, ensuring a consistent experience irrespective of the underlying blockchain:
+The `client` package exposes go APIs to facilitate interactions with the Pocket network.
+It includes lower-level interfaces for working with transactions and subscribing to events generally, as well as higher-level interfaces for tracking blocks and broadcasting protocol-specific transactions.
+
+## Features
 
-- **Simplifies Blockchain Interactions**: Provides a clear interface for initiating transactions and querying blockchain events without dealing with platform-specific quirks.
-- **Modular and Extendable**: Designed with separation of concerns in mind, allowing developers to customize or replace components as necessary.
-- **Unified Communication**: Regardless of the blockchain in use, the interfaces offer a standard way to communicate, streamlining the development process.
+| Interface               | Description                                                                                        |
+|-------------------------|----------------------------------------------------------------------------------------------------|
+| **`SupplierClient`**    | A high-level client for use by the "supplier" actor.                                               |
+| **`TxClient`**          | A high-level client used to build, sign, and broadcast transaction from cosmos-sdk messages.       |
+| **`TxContext`**         | Abstracts and encapsulates the transaction building, signing, encoding, and broadcasting concerns. |
+| **`BlockClient`**       | Exposes methods for receiving notifications about newly committed blocks.                          |
+| **`EventsQueryClient`** | Encapsulates blockchain event subscriptions in .                                                   |
+| **`Connection`**        | A transport agnostic communication channel for sending and receiving messages.                     |
+| **`Dialer`**            | Abstracts the establishment of connections.                                                        |
 
-## Architecture Diagrams
+## Architecture Overview
+
+```mermaid
+---
+title: Component Diagram Legend
+---
+flowchart
+
+c[Component]
+d[Dependency Component]
+s[[Subcomponent]]
+r[Remote Component]
+
+c --"direct usage via #DependencyMethod()"--> d
+c -."usage via network I/O".-> r
+c --> s
+```
 
-Visual representations often make it easier to understand the design and flow of a package. Diagrams specific to this package can be added here.
+> **Figure 1**: A legend for the component diagrams in this document.
 
 ```mermaid
 ---
 title: Clients Dependency Tree
 ---
 flowchart
 
-    sup[SupplierClient]
-    tx[TxClient]
-    bl[BlockClient]
-    evt[EventsQueryClient]
+sup[SupplierClient]
+tx[TxClient]
+txctx[[TxContext]]
+bl[BlockClient]
+evt[EventsQueryClient]
+conn[[Connection]]
+dial[[Dialer]]
+
+sup --"#SignAndBroadcast()"--> tx
 
-    sup --"#SignAndBroadcast()"--> tx
-
 tx --"#CommittedBlocksSequence()"--> bl
+tx --"#BroadcastTx"--> txctx
 tx --"#EventsBytes()"--> evt
 bl --"#EventsBytes()"--> evt
+evt --> conn
+evt --"#DialContext()"--> dial
+dial --(returns)--> conn
 ```
 
-> **Figure 1**: An overview diagram showing the interaction between the various interfaces and the blockchain.
+> **Figure 2**: An overview which articulates the dependency relationships between the various client interfaces and their subcompnents.
 
 ```mermaid
 ---
-title: TxClient Dependency Graph
+title: Network Interaction
 ---
-
-
 flowchart
 
-    subgraph tclient[TxClient]
-        tctx[TxContext]
-        builder[TxBuilder]
-        keyring[Keyring]
-
-        bclient[BlockClient]
-        eclient[EventsQueryClient]
+txctx[[TxContext]]
+conn[[Connection]]
+dial[[Dialer]]
 
-        tclient_internal((_))
-    end
+chain[Blockchain]
 
-    chain[Blockchain]
-
-    tctx --"#GetKeyring()"--> keyring
-tctx --"#SignTx()"--> builder
-tctx --"#EncodeTx()"--> builder
-tctx -."#BroadcastTx()".-> chain
-tctx -."#QueryTx()".-> chain
-
-eclient -."websocket connection".-> chain
-bclient --"committed  block subscription"--> eclient
-tclient_internal --"own tx subscription"--> eclient
+conn <-."subscribed events".-> chain
+dial -."RPC subscribe".-> chain
+txctx -."tx broadcast".-> chain
+txctx -."tx query".-> chain
 ```
 
-> **Figure 2**: A focused look at how `TxClient` functions and interacts with the underlying blockchain.
+> **Figure 3**: An overview of how client subcomponents interact with the network.
 
 ## Installation
 
 ```bash
 go get github.com/pokt-network/poktroll/pkg/client
 ```
 
-## Features
-
-- **TxClient Interface**: A streamlined way to sign and broadcast multiple messages as part of a blockchain transaction.
-- **BlockClient Interface**: Notifications about newly committed blocks and access to the latest block.
-- **EventsQueryClient**: Enables subscription to chain event messages.
-- **Connection Interface**: A transport agnostic communication channel for sending and receiving messages.
-- **Dialer**: Simplifies the establishment of connections.
-
 ## Usage
 
 ### Basic Example
 
 ```go
-// Code example showcasing the use of TxClient or any other primary interface.
+// TODO: Code example showcasing the use of TxClient or any other primary interface.
 ```
 
 ### Advanced Usage
 
 ```go
-// Example illustrating advanced features or edge cases of the package.
+// TODO: Example illustrating advanced features or edge cases of the package.
 ```
 
 ### Configuration

go.mod

@@ -9,7 +9,6 @@ require (
 	cosmossdk.io/math v1.0.1
 	github.com/cometbft/cometbft v0.37.2
 	github.com/cometbft/cometbft-db v0.8.0
-	github.com/cosmos/cosmos-proto v1.0.0-beta.2
 	github.com/cosmos/cosmos-sdk v0.47.3
 	github.com/cosmos/gogoproto v1.4.10
 	github.com/cosmos/ibc-go/v7 v7.1.0
@@ -27,7 +26,6 @@ require (
 	go.uber.org/multierr v1.11.0
 	golang.org/x/crypto v0.12.0
 	golang.org/x/sync v0.3.0
-	google.golang.org/genproto v0.0.0-20230410155749-daa745c078e1
 	google.golang.org/grpc v1.56.1
 	gopkg.in/yaml.v2 v2.4.0
 )
@@ -71,6 +69,7 @@ require (
 	github.com/containerd/cgroups v1.1.0 // indirect
 	github.com/coreos/go-systemd/v22 v22.5.0 // indirect
 	github.com/cosmos/btcutil v1.0.5 // indirect
+	github.com/cosmos/cosmos-proto v1.0.0-beta.2 // indirect
 	github.com/cosmos/go-bip39 v1.0.0 // indirect
 	github.com/cosmos/gogogateway v1.2.0 // indirect
 	github.com/cosmos/iavl v0.20.0 // indirect
@@ -135,7 +134,6 @@ require (
 	github.com/hashicorp/go-immutable-radix v1.3.1 // indirect
 	github.com/hashicorp/go-multierror v1.1.1 // indirect
 	github.com/hashicorp/go-safetemp v1.0.0 // indirect
-	github.com/hashicorp/go-uuid v1.0.2 // indirect
 	github.com/hashicorp/go-version v1.6.0 // indirect
 	github.com/hashicorp/golang-lru v0.5.5-0.20210104140557-80c98217689d // indirect
 	github.com/hashicorp/golang-lru/v2 v2.0.2 // indirect
@@ -266,6 +264,7 @@ require (
 	gonum.org/v1/gonum v0.11.0 // indirect
 	google.golang.org/api v0.122.0 // indirect
 	google.golang.org/appengine v1.6.7 // indirect
+	google.golang.org/genproto v0.0.0-20230410155749-daa745c078e1 // indirect
 	google.golang.org/protobuf v1.31.0 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect

go.sum

@@ -933,9 +933,8 @@ github.com/hashicorp/go-safetemp v1.0.0/go.mod h1:oaerMy3BhqiTbVye6QuFhFtIceqFoD
 github.com/hashicorp/go-sockaddr v1.0.0/go.mod h1:7Xibr9yA9JjQq1JpNB2Vw7kxv8xerXegt+ozgdvDeDU=
 github.com/hashicorp/go-syslog v1.0.0/go.mod h1:qPfqrKkXGihmCqbJM2mZgkZGvKG1dFdvsLplgctolz4=
 github.com/hashicorp/go-uuid v1.0.0/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
+github.com/hashicorp/go-uuid v1.0.1 h1:fv1ep09latC32wFoVwnqcnKJGnMSdBanPczbHAYm1BE=
 github.com/hashicorp/go-uuid v1.0.1/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
-github.com/hashicorp/go-uuid v1.0.2 h1:cfejS+Tpcp13yd5nYHWDI6qVCny6wyX2Mt5SGur2IGE=
-github.com/hashicorp/go-uuid v1.0.2/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
 github.com/hashicorp/go-version v1.2.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
 github.com/hashicorp/go-version v1.2.1/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
 github.com/hashicorp/go-version v1.6.0 h1:feTTfFNnjP967rlCxM/I9g701jU+RN74YKx2mOkIeek=

internal/testclient/testblock/client.go

@@ -1,12 +1,3 @@
-// Package testblock provides utilities and mock clients to facilitate testing
-// interactions with blockchain-related functionality. It includes tools for creating mock
-// BlockClients, Block observables, and mock blocks tailored for specific testing scenarios.
-// The package is designed to help ensure that tests around blockchain functionality are
-// robust, using mock implementations to replicate expected behaviors in controlled environments.
-//
-// Given its role in testing, the testblock package leverages several other testing
-// packages and libraries, such as gomock, testify, and internal testing clients
-// from the pocket project.
 package testblock
 
 import (
@@ -17,27 +8,16 @@ import (
 	"github.com/golang/mock/gomock"
 	"github.com/stretchr/testify/require"
 
-	"pocket/internal/mocks/mockclient"
-	"pocket/internal/testclient"
-	"pocket/internal/testclient/testeventsquery"
-	"pocket/pkg/client"
-	"pocket/pkg/client/block"
-	"pocket/pkg/observable/channel"
+	"github.com/pokt-network/poktroll/internal/mocks/mockclient"
+	"github.com/pokt-network/poktroll/internal/testclient"
+	"github.com/pokt-network/poktroll/internal/testclient/testeventsquery"
+	"github.com/pokt-network/poktroll/pkg/client"
+	"github.com/pokt-network/poktroll/pkg/client/block"
+	"github.com/pokt-network/poktroll/pkg/observable/channel"
 )
 
-// NewLocalnetClient creates and returns a new BlockClient for localnet testing
-// environments.
-//
-// Parameters:
-// - ctx: The context for creating the client.
-// - t: The testing.T instance for assertions.
-//
-// The function initializes a localnet query client, ensures its successful creation, and then
-// proceeds to set up the dependencies required to instantiate a new BlockClient.
-// The final BlockClient instance connects to the CometLocalWebsocketURL endpoint.
-//
-// Returns:
-// - A new instance of client.BlockClient configured for localnet interactions.
+// NewLocalnetClient creates and returns a new BlockClient that's configured for
+// use with the localnet sequencer.
 func NewLocalnetClient(ctx context.Context, t *testing.T) client.BlockClient {
 	t.Helper()
 
@@ -55,13 +35,7 @@ func NewLocalnetClient(ctx context.Context, t *testing.T) client.BlockClient {
 // This mock BlockClient will expect a call to CommittedBlocksSequence, and
 // when that call is made, it returns a new BlocksObservable that is notified of
 // blocks sent on the given blocksPublishCh.
-//
-// Parameters:
-// - t: *testing.T - The test instance.
-// - blocksPublishCh: chan client.Block - The channel from which blocks are published to the observable.
-//
-// Returns:
-// - *mockclient.MockBlockClient: The mock block client.
+// blocksPublishCh is the channel the caller can use to publish blocks the observable.
 func NewOneTimeCommittedBlocksSequenceBlockClient(
 	t *testing.T,
 	blocksPublishCh chan client.Block,
@@ -92,14 +66,6 @@ func NewOneTimeCommittedBlocksSequenceBlockClient(
 // NewAnyTimeLatestBlockBlockClient creates a mock BlockClient that expects
 // calls to the LatestBlock method any number of times. When the LatestBlock
 // method is called, it returns a mock Block with the provided hash and height.
-//
-// Parameters:
-// - t: *testing.T - The test instance.
-// - hash: []byte - The expected hash value that the mock Block should return.
-// - height: int64 - The expected block height that the mock Block should return.
-//
-// Returns:
-// - *mockclient.MockBlockClient: The mock block client.
 func NewAnyTimeLatestBlockBlockClient(
 	t *testing.T,
 	hash []byte,
@@ -121,14 +87,6 @@ func NewAnyTimeLatestBlockBlockClient(
 // NewAnyTimesBlock creates a mock Block that expects calls to Height and Hash
 // methods any number of times. When the methods are called, they return the
 // provided height and hash respectively.
-//
-// Parameters:
-// - t: *testing.T - The test instance.
-// - hash: []byte - The expected hash value that the mock Block should return.
-// - height: int64 - The expected block height that the mock Block should return.
-//
-// Returns:
-// - *mockclient.MockBlock: The mock block.
 func NewAnyTimesBlock(t *testing.T, hash []byte, height int64) *mockclient.MockBlock {
 	t.Helper()
 	ctrl := gomock.NewController(t)

internal/testclient/testblock/godoc.go

@@ -0,0 +1,4 @@
+// Package testblock provides helper functions for constructing real (e.g. localnet)
+// and mock BlockClient objects with pre-configured and/or parameterized call
+// arguments, return value(s), and/or expectations thereof. Intended for use in tests.
+package testblock