feat: use custom HTTP clients (#163)

Author: MicBun

README.md

@@ -20,6 +20,46 @@ If you need help, don't hesitate to [open an issue](https://github.com/trufnetwo
 go get github.com/trufnetwork/sdk-go
 ```
 
+### Advanced Configuration
+
+#### Custom Transport (Optional)
+
+The SDK supports custom transport implementations for specialized environments. By default, the SDK uses `HTTPTransport` with standard `net/http`, but you can provide alternative transports:
+
+```go
+// Default usage (HTTPTransport automatically created)
+client, err := tnclient.NewClient(ctx, endpoint,
+    tnclient.WithSigner(signer),
+)
+
+// Advanced: Custom transport for specialized environments
+// (e.g., Chainlink Runtime Environment)
+customTransport := &MyCustomTransport{...}
+client, err := tnclient.NewClient(ctx, endpoint,
+    tnclient.WithSigner(signer),
+    tnclient.WithTransport(customTransport),
+)
+```
+
+**When to use custom transports:**
+- Chainlink Runtime Environment (CRE) workflows
+- Testing with mock transports
+- Custom HTTP client requirements
+- Alternative RPC protocols
+
+**Advanced API Access:**
+
+For advanced use cases requiring direct `GatewayClient` access (HTTP transport only):
+
+```go
+if gwClient := client.GetKwilClient(); gwClient != nil {
+    // Direct low-level access for advanced scenarios
+    result, err := gwClient.Call(ctx, "", "custom_action", args)
+}
+```
+
+> **Note**: For most use cases, prefer the high-level Client methods (`ListStreams`, `DeployStream`, etc.) which are transport-agnostic and work with any transport implementation.
+
 ## Local Node Testing
 
 ### Setting Up a Local Node

core/tnclient/client.go

@@ -6,7 +6,6 @@ import (
 
 	"github.com/go-playground/validator/v10"
 	"github.com/pkg/errors"
-	kwilClientType "github.com/trufnetwork/kwil-db/core/client/types"
 	"github.com/trufnetwork/kwil-db/core/crypto/auth"
 	"github.com/trufnetwork/kwil-db/core/gatewayclient"
 	"github.com/trufnetwork/kwil-db/core/log"
@@ -20,10 +19,9 @@ import (
 )
 
 type Client struct {
-	Signer      auth.Signer `validate:"required"`
-	logger      *log.Logger
-	kwilClient  *gatewayclient.GatewayClient `validate:"required"`
-	kwilOptions *gatewayclient.GatewayOptions
+	signer    auth.Signer `validate:"required"`
+	logger    *log.Logger
+	transport Transport   `validate:"required"`
 }
 
 var _ clientType.Client = (*Client)(nil)
@@ -32,21 +30,28 @@ type Option func(*Client)
 
 func NewClient(ctx context.Context, provider string, options ...Option) (*Client, error) {
 	c := &Client{}
-	c.kwilOptions = &gatewayclient.GatewayOptions{
-		Options: *kwilClientType.DefaultOptions(),
-	}
+
+	// Apply user-provided options
 	for _, option := range options {
 		option(c)
 	}
 
-	kwilClient, err := gatewayclient.NewClient(ctx, provider, c.kwilOptions)
-	if err != nil {
-		return nil, errors.WithStack(err)
+	// Create default HTTPTransport if no transport was provided via options
+	if c.transport == nil {
+		var logger log.Logger
+		if c.logger != nil {
+			logger = *c.logger
+		}
+
+		transport, err := NewHTTPTransport(ctx, provider, c.signer, logger)
+		if err != nil {
+			return nil, errors.Wrap(err, "failed to create default HTTP transport")
+		}
+		c.transport = transport
 	}
-	c.kwilClient = kwilClient
 
 	// Validate the client
-	if err = c.Validate(); err != nil {
+	if err := c.Validate(); err != nil {
 		return nil, errors.WithStack(err)
 	}
 
@@ -60,28 +65,64 @@ func (c *Client) Validate() error {
 
 func WithSigner(signer auth.Signer) Option {
 	return func(c *Client) {
-		c.kwilOptions.Signer = signer
-		c.Signer = signer
+		c.signer = signer
 	}
 }
 
 func WithLogger(logger log.Logger) Option {
 	return func(c *Client) {
 		c.logger = &logger
-		c.kwilOptions.Logger = logger
+	}
+}
+
+// WithTransport configures the client to use a custom transport implementation.
+//
+// By default, the SDK uses HTTPTransport which communicates via standard net/http.
+// This option allows you to substitute a different transport (e.g., for Chainlink CRE,
+// mock testing, or custom protocols).
+//
+// Example:
+//
+//	transport, _ := NewHTTPTransport(ctx, endpoint, signer, logger)
+//	client, err := NewClient(ctx, endpoint,
+//	    tnclient.WithTransport(transport),
+//	)
+//
+// Note: When using WithTransport, the provider URL passed to NewClient is ignored
+// since the transport is already configured.
+func WithTransport(transport Transport) Option {
+	return func(c *Client) {
+		c.transport = transport
 	}
 }
 
 func (c *Client) GetSigner() auth.Signer {
-	return c.kwilClient.Signer()
+	return c.transport.Signer()
 }
 
 func (c *Client) WaitForTx(ctx context.Context, txHash kwilType.Hash, interval time.Duration) (*kwilType.TxQueryResponse, error) {
-	return c.kwilClient.WaitTx(ctx, txHash, interval)
+	return c.transport.WaitTx(ctx, txHash, interval)
 }
 
+// GetKwilClient returns the underlying GatewayClient if using HTTPTransport.
+//
+// This method provides direct access to the GatewayClient for advanced use cases
+// that require low-level control. For most scenarios, prefer using the Client's
+// high-level methods (ListStreams, DeployStream, etc.) which are transport-agnostic.
+//
+// Returns nil if using a non-HTTP transport (e.g., CRE transport).
+//
+// Example:
+//
+//	if gwClient := client.GetKwilClient(); gwClient != nil {
+//	    // Direct GatewayClient access for advanced use cases
+//	    result, err := gwClient.Call(ctx, "", "custom_action", args)
+//	}
 func (c *Client) GetKwilClient() *gatewayclient.GatewayClient {
-	return c.kwilClient
+	if httpTransport, ok := c.transport.(*HTTPTransport); ok {
+		return httpTransport.gatewayClient
+	}
+	return nil
 }
 
 func (c *Client) DeployStream(ctx context.Context, streamId util.StreamId, streamType clientType.StreamType) (types.Hash, error) {
@@ -101,31 +142,31 @@ func (c *Client) DestroyStream(ctx context.Context, streamId util.StreamId) (typ
 
 func (c *Client) LoadActions() (clientType.IAction, error) {
 	return tn_api.LoadAction(tn_api.NewActionOptions{
-		Client: c.kwilClient,
+		Client: c.GetKwilClient(),
 	})
 }
 
 func (c *Client) LoadPrimitiveActions() (clientType.IPrimitiveAction, error) {
 	return tn_api.LoadPrimitiveActions(tn_api.NewActionOptions{
-		Client: c.kwilClient,
+		Client: c.GetKwilClient(),
 	})
 }
 
 func (c *Client) LoadComposedActions() (clientType.IComposedAction, error) {
 	return tn_api.LoadComposedActions(tn_api.NewActionOptions{
-		Client: c.kwilClient,
+		Client: c.GetKwilClient(),
 	})
 }
 
 func (c *Client) LoadRoleManagementActions() (clientType.IRoleManagement, error) {
 	return tn_api.LoadRoleManagementActions(tn_api.NewRoleManagementOptions{
-		Client: c.kwilClient,
+		Client: c.GetKwilClient(),
 	})
 }
 
 func (c *Client) LoadAttestationActions() (clientType.IAttestationAction, error) {
 	return tn_api.LoadAttestationActions(tn_api.AttestationActionOptions{
-		Client: c.kwilClient,
+		Client: c.GetKwilClient(),
 	})
 }
 
@@ -140,7 +181,7 @@ func (c *Client) LoadAttestationActions() (clientType.IAttestationAction, error)
 //	txEvent, err := txActions.GetTransactionEvent(ctx, ...)
 func (c *Client) LoadTransactionActions() (clientType.ITransactionAction, error) {
 	return tn_api.LoadTransactionActions(tn_api.TransactionActionOptions{
-		Client: c.kwilClient,
+		Client: c.GetKwilClient(),
 	})
 }
 
@@ -152,7 +193,7 @@ func (c *Client) OwnStreamLocator(streamId util.StreamId) clientType.StreamLocat
 }
 
 func (c *Client) Address() util.EthereumAddress {
-	addr, err := auth.EthSecp256k1Authenticator{}.Identifier(c.kwilClient.Signer().CompactID())
+	addr, err := auth.EthSecp256k1Authenticator{}.Identifier(c.transport.Signer().CompactID())
 	if err != nil {
 		// should never happen
 		logging.Logger.Panic("failed to get address from signer", zap.Error(err))

core/tnclient/list_streams.go

@@ -18,7 +18,7 @@ func (c *Client) ListStreams(ctx context.Context, input types.ListStreamsInput)
 	args = append(args, input.OrderBy)
 	args = append(args, input.BlockHeight)
 
-	result, err := c.kwilClient.Call(ctx, "", "list_streams", args)
+	result, err := c.transport.Call(ctx, "", "list_streams", args)
 	if err != nil || result.Error != nil {
 		if err != nil {
 			return nil, errors.WithStack(err)

core/tnclient/transport.go

@@ -0,0 +1,95 @@
+package tnclient
+
+import (
+	"context"
+	"time"
+
+	clientType "github.com/trufnetwork/kwil-db/core/client/types"
+	"github.com/trufnetwork/kwil-db/core/crypto/auth"
+	"github.com/trufnetwork/kwil-db/core/types"
+)
+
+// Transport abstracts the communication layer for TRUF Network operations.
+// This interface allows using different transport implementations without changing SDK code.
+//
+// The default implementation (HTTPTransport) uses standard net/http via kwil-db's
+// GatewayClient. Custom implementations can use different protocols such as:
+//   - Chainlink CRE's HTTP client (for workflows in CRE environments)
+//   - gRPC or other RPC protocols
+//   - Mock implementations for testing
+//
+// Example custom transport usage:
+//
+//	type MyTransport struct { ... }
+//
+//	func (t *MyTransport) Call(ctx context.Context, namespace string, action string, inputs []any) (*types.CallResult, error) {
+//	    // Custom implementation
+//	    return &types.CallResult{...}, nil
+//	}
+//
+//	// Use custom transport
+//	client, err := tnclient.NewClient(ctx, endpoint,
+//	    tnclient.WithSigner(signer),
+//	    tnclient.WithTransport(myTransport),
+//	)
+//
+// All SDK methods internally use the Transport interface, making the entire SDK
+// adaptable to different execution environments without code changes.
+type Transport interface {
+	// Call executes a read-only action and returns results.
+	// Namespace is typically "" for global actions.
+	//
+	// Parameters:
+	//   - ctx: Context for cancellation and timeouts
+	//   - namespace: Schema namespace (typically "" for global procedures)
+	//   - action: The procedure/action name to call
+	//   - inputs: Action input parameters as a slice of any
+	//
+	// Returns:
+	//   - CallResult containing the query results
+	//   - Error if the call fails or returns an application error
+	Call(ctx context.Context, namespace string, action string, inputs []any) (*types.CallResult, error)
+
+	// Execute performs a write action and returns the transaction hash.
+	// Inputs is a slice of argument arrays for batch operations.
+	// Options can include nonce, fee, and other transaction parameters.
+	//
+	// Parameters:
+	//   - ctx: Context for cancellation and timeouts
+	//   - namespace: Schema namespace (typically "" for global procedures)
+	//   - action: The procedure/action name to execute
+	//   - inputs: Batch of input parameter arrays ([][]any for multiple calls)
+	//   - opts: Optional transaction options (nonce, fee, etc.)
+	//
+	// Returns:
+	//   - Transaction hash for tracking the transaction
+	//   - Error if the execution fails
+	Execute(ctx context.Context, namespace string, action string, inputs [][]any, opts ...clientType.TxOpt) (types.Hash, error)
+
+	// WaitTx polls for transaction confirmation with the specified interval.
+	// Blocks until the transaction is confirmed or the context is cancelled.
+	//
+	// Parameters:
+	//   - ctx: Context for cancellation and timeouts
+	//   - txHash: The transaction hash to wait for
+	//   - interval: Polling interval between status checks
+	//
+	// Returns:
+	//   - TxQueryResponse containing the transaction status and result
+	//   - Error if the wait fails or transaction is rejected
+	WaitTx(ctx context.Context, txHash types.Hash, interval time.Duration) (*types.TxQueryResponse, error)
+
+	// ChainID returns the network chain identifier.
+	// This is used to ensure transactions are sent to the correct network.
+	//
+	// Returns:
+	//   - Chain ID string (e.g., "truf-mainnet")
+	ChainID() string
+
+	// Signer returns the cryptographic signer used for transaction authentication.
+	// Returns nil if no signer is configured (read-only mode).
+	//
+	// Returns:
+	//   - Signer instance for transaction signing
+	Signer() auth.Signer
+}