pushcore

Documentation

Overview

Package pushcore provides a client for interacting with Push Chain gRPC endpoints. It implements a fan-out pattern that tries multiple endpoints in round-robin order to provide high availability and fault tolerance.

Index

• func CreateGRPCConnection(endpoint string) (*grpc.ClientConn, error)
• func ExtractHostnameFromURL(grpcURL string) (string, error)
• type Client
  • func New(urls []string, logger zerolog.Logger) (*Client, error)
  • func (c *Client) BroadcastTx(ctx context.Context, txBytes []byte) (*tx.BroadcastTxResponse, error)
  • func (c *Client) Close() error
  • func (c *Client) GetAccount(ctx context.Context, address string) (*authtypes.QueryAccountResponse, error)
  • func (c *Client) GetAllChainConfigs(ctx context.Context) ([]*uregistrytypes.ChainConfig, error)
  • func (c *Client) GetAllUniversalValidators(ctx context.Context) ([]*uvalidatortypes.UniversalValidator, error)
  • func (c *Client) GetCurrentKey(ctx context.Context) (*utsstypes.TssKey, error)
  • func (c *Client) GetGasPrice(ctx context.Context, chainID string) (*big.Int, error)
  • func (c *Client) GetGranteeGrants(ctx context.Context, granteeAddr string) (*authz.QueryGranteeGrantsResponse, error)
  • func (c *Client) GetLatestBlock(ctx context.Context) (uint64, error)
  • func (c *Client) GetTxsByEvents(ctx context.Context, eventQuery string, minHeight, maxHeight uint64, ...) ([]*TxResult, error)
• type TxResult

Functions

func CreateGRPCConnection

func CreateGRPCConnection(endpoint string) (*grpc.ClientConn, error)

CreateGRPCConnection creates a gRPC connection with appropriate transport security. It automatically detects whether to use TLS based on the URL scheme.

The function handles:

• https:// URLs: Uses TLS with default credentials
• http:// or no scheme: Uses insecure connection
• Automatically adds default port 9090 if no port is specified

Parameters:

• endpoint: gRPC endpoint URL (scheme is optional, port defaults to 9090)

Returns:

• *grpc.ClientConn: gRPC client connection
• error: Error if connection fails

func ExtractHostnameFromURL

func ExtractHostnameFromURL(grpcURL string) (string, error)

ExtractHostnameFromURL extracts the hostname from a URL string. It handles various URL formats including full URLs with scheme, URLs without scheme, and plain hostnames.

Parameters:

• grpcURL: URL string in any format (with or without scheme/port)

Returns:

• string: Hostname without port or scheme
• error: Error if hostname cannot be extracted

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a fan-out client that connects to multiple Push Chain gRPC endpoints. It implements round-robin failover, trying each endpoint in sequence until one succeeds.

func New

func New(urls []string, logger zerolog.Logger) (*Client, error)

New creates a new Client by dialing the provided gRPC URLs. It attempts to connect to all endpoints and skips any that fail to dial. At least one endpoint must succeed, otherwise an error is returned.

Parameters:

• urls: List of gRPC endpoint URLs (schemes are automatically detected)
• logger: Logger instance for client operations

Returns:

• *Client: A configured client instance, or nil on error
• error: Error if all endpoints fail to connect

func (*Client) BroadcastTx

func (c *Client) BroadcastTx(ctx context.Context, txBytes []byte) (*tx.BroadcastTxResponse, error)

BroadcastTx broadcasts a signed transaction to the chain. It tries each endpoint in round-robin order until one succeeds.

Parameters:

• ctx: Context for the request
• txBytes: Signed transaction bytes

Returns:

• *tx.BroadcastTxResponse: Broadcast response containing tx hash and result
• error: Error if all endpoints fail

func (*Client) Close

func (c *Client) Close() error

Close gracefully closes all gRPC connections owned by the client. Returns the first error encountered, if any.

func (*Client) GetAccount

func (c *Client) GetAccount(ctx context.Context, address string) (*authtypes.QueryAccountResponse, error)

GetAccount retrieves account information for a given address. It tries each endpoint in round-robin order until one succeeds.

Parameters:

• ctx: Context for the request
• address: Bech32 address of the account

Returns:

• *authtypes.QueryAccountResponse: Account response
• error: Error if all endpoints fail

func (*Client) GetAllChainConfigs

func (c *Client) GetAllChainConfigs(ctx context.Context) ([]*uregistrytypes.ChainConfig, error)

GetAllChainConfigs retrieves all chain configurations from Push Chain. It tries each endpoint in round-robin order until one succeeds.

Parameters:

• ctx: Context for the request

Returns:

• []*uregistrytypes.ChainConfig: List of chain configurations
• error: Error if all endpoints fail

func (*Client) GetAllUniversalValidators

func (c *Client) GetAllUniversalValidators(ctx context.Context) ([]*uvalidatortypes.UniversalValidator, error)

GetAllUniversalValidators retrieves all universal validators from Push Chain. It tries each endpoint in round-robin order until one succeeds.

Parameters:

• ctx: Context for the request

Returns:

• []*uvalidatortypes.UniversalValidator: List of universal validators
• error: Error if all endpoints fail

func (*Client) GetCurrentKey

func (c *Client) GetCurrentKey(ctx context.Context) (*utsstypes.TssKey, error)

GetCurrentKey retrieves the current TSS key from Push Chain. It tries each endpoint in round-robin order until one succeeds.

Parameters:

• ctx: Context for the request

Returns:

• *utsstypes.TssKey: TSS key
• error: Error if all endpoints fail or no key exists

func (*Client) GetGasPrice

func (c *Client) GetGasPrice(ctx context.Context, chainID string) (*big.Int, error)

GetGasPrice retrieves the median gas price for a specific chain from the on-chain oracle. The gas price is voted on by universal validators and stored on-chain.

Parameters:

• ctx: Context for the request
• chainID: Chain identifier in CAIP-2 format (e.g., "eip155:84532" for Base Sepolia)

Returns:

• *big.Int: Median gas price in the chain's native unit (Wei for EVM chains, lamports for Solana)
• error: Error if all endpoints fail or chainID is invalid

func (*Client) GetGranteeGrants

func (c *Client) GetGranteeGrants(ctx context.Context, granteeAddr string) (*authz.QueryGranteeGrantsResponse, error)

GetGranteeGrants queries AuthZ grants for a grantee using round-robin logic. This function only queries and returns raw grant data; it does not perform validation or processing.

Parameters:

• ctx: Context for the request
• granteeAddr: Address of the grantee to query grants for

Returns:

• *authz.QueryGranteeGrantsResponse: Raw grant response from the chain
• error: Error if all endpoints fail

func (*Client) GetLatestBlock

func (c *Client) GetLatestBlock(ctx context.Context) (uint64, error)

GetLatestBlock retrieves the latest block from Push Chain. It tries each endpoint in round-robin order until one succeeds.

Parameters:

• ctx: Context for the request

Returns:

• uint64: Latest block height
• error: Error if all endpoints fail

func (*Client) GetTxsByEvents

func (c *Client) GetTxsByEvents(ctx context.Context, eventQuery string, minHeight, maxHeight uint64, limit uint64) ([]*TxResult, error)

GetTxsByEvents queries transactions matching the given event query. The query should follow Cosmos SDK event query format, e.g., "tss_process_initiated.process_id EXISTS".

Parameters:

• ctx: Context for the request
• eventQuery: Cosmos SDK event query string
• minHeight: Minimum block height to search (0 means no minimum)
• maxHeight: Maximum block height to search (0 means no maximum)
• limit: Maximum number of results to return (0 defaults to 100)

Returns:

• []*TxResult: List of matching transaction results
• error: Error if all endpoints fail

type TxResult

type TxResult struct {
	TxHash     string            // Transaction hash
	Height     int64             // Block height where the transaction was included
	TxResponse *tx.GetTxResponse // Full transaction response from the chain
}

TxResult represents a transaction result with its associated events and metadata.