sdk

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 9, 2025 License: Apache-2.0 Imports: 41 Imported by: 2

Documentation

Overview

package sdk provides functionality to interact with SourceHub

package sdk provides custom helpers and utility types to interact with SourceHub and reexport useful and common types used to interact with SourceHub. These types are used to query state accross SourceHub modules (GRPC Query Clients), build and broadcast Txs, listen and await for Txs and interacts with general cosmos-sdk chains.

TODO add example

Index

Constants

View Source 
const (
	Testnet1            = "sourcehub-testnet-1"
	TestnetLatest       = Testnet1
	DefaultChainID      = TestnetLatest
	DefaultGRPCAddr     = "localhost:9090"
	DefaultCometRPCAddr = "tcp://localhost:26657"
)

Variables

View Source 
var ErrTxFailed = errors.New("tx failed")

Functions

func NewCmdBuilder 

func NewCmdBuilder(ctx context.Context, client *Client) (*signed_policy_cmd.CmdBuilder, error)

NewCmdBuilder returns a builder for PolicyCmd objects from a client.

The client is used to fetch the latest ACP module params from SourceHub and as a block height fetcher.

Types

type Client 

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

Client abstracts a set of connections to a SourceHub node. The Client type provides access to module specific clients and functionalities to interact with SourceHub such as performing module Queries (GRPC), Broadcast Txs and interact with CometBFT

func NewClient 

func NewClient(opts ...Opt) (*Client, error)

NewClient returns a new SourceHub SDK client

func (*Client) ACPQueryClient 

func (c *Client) ACPQueryClient() acptypes.QueryClient

ACPQueryClient returns a Query Client for the ACP module

func (*Client) AuthQueryClient 

func (c *Client) AuthQueryClient() authtypes.QueryClient

AuthQueryClient returns a Query Client for the Auth module

func (*Client) AwaitTx 

func (c *Client) AwaitTx(ctx context.Context, txHash string) (*TxExecResult, error)

func (*Client) BankQueryClient 

func (c *Client) BankQueryClient() banktypes.QueryClient

BankQueryClient returns a Query Client for the Bank module

func (*Client) BroadcastTx 

func (b *Client) BroadcastTx(ctx context.Context, tx xauthsigning.Tx) (*sdk.TxResponse, error)

BroadcastTx broadcasts a signed Tx to a SourceHub node and returns the node's response. Callers can use TxResponse.TxHash to await or listen until the Tx is accepted and executed.

func (*Client) BulletinQueryClient 

func (c *Client) BulletinQueryClient() bulletintypes.QueryClient

BulletinQueryClient returns a Query Client for the Bulletin module

func (*Client) Close 

func (b *Client) Close()

Close terminates the Client, freeing up resources and connections

func (*Client) CometBFTRPCClient 

func (c *Client) CometBFTRPCClient() cometclient.Client

CometBFTRPCClient returns a Comet RPC Client

func (*Client) FeeGrantQueryClient 

func (c *Client) FeeGrantQueryClient() feegrant.QueryClient

FeegrantQueryClient returns a Query Client for the Feegrant module

func (*Client) GetTx 

func (c *Client) GetTx(ctx context.Context, txHash string) (*TxExecResult, error)

func (*Client) ListenForTx 

func (c *Client) ListenForTx(ctx context.Context, txHash string) <-chan *ListenResult

func (*Client) TxListener 

func (c *Client) TxListener() TxListener

TxListener returns a TxListener

type Event 

type Event struct {
	Height    int64     `json:"height"`
	Index     uint32    `json:"index"`
	Tx        []byte    `json:"tx"`
	Code      uint32    `json:"code"`
	Log       string    `json:"log"`
	Info      string    `json:"info"`
	GasWanted int64     `json:"gas_wanted"`
	GasUsed   int64     `json:"gas_used"`
	Codespace string    `json:"codespace"`
	Responses []sdk.Msg `json:"responses"`
}

Event models a Cometbft Tx event with unmarsheled Msg responses

type ListenResult 

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

ListenResult represents the result of waiting for a Tx to be executed by SourceHub Can either error, meaning timeout or network error, or return the Tx object queried from the chain state

func (*ListenResult) Error 

func (r *ListenResult) Error() error

Error return the error of the WaitResult, returns nil if sucessful

func (*ListenResult) GetTxResult 

func (r *ListenResult) GetTxResult() *TxExecResult

GetTxResult returns the outcome of the executed Tx by SourceHub

type Mapper 

type Mapper[T sdk.Msg] struct {
	// contains filtered or unexported fields
}

Mapper processes a CometBFT Tx Event from a specific Tx and maps into a payload. Mapper is bound to a msgIdx within the Tx

func (*Mapper[T]) Map 

func (e *Mapper[T]) Map(msg *comettypes.ResultTx) (T, error)

Map receives a CometBFT Tx Event Result and maps it into a T or errors if invalid

type MsgSet 

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

MsgSet acts as set of Msgs to be added to a Tx Each added Msg returns a Mapper which can be used to extract associated data from the events emitted after Tx execution

func (*MsgSet) GetMsgs 

func (b *MsgSet) GetMsgs() []sdk.Msg

func (*MsgSet) WithBearerPolicyCmd 

func (b *MsgSet) WithBearerPolicyCmd(msg *acptypes.MsgBearerPolicyCmd) Mapper[*acptypes.MsgBearerPolicyCmdResponse]

func (*MsgSet) WithCheckAccess 

func (b *MsgSet) WithCheckAccess(msg *acptypes.MsgCheckAccess) Mapper[*acptypes.MsgCheckAccessResponse]

WithCheckAccess includes a MsgCheckAcces to the Tx

func (*MsgSet) WithCreatePolicy 

func (b *MsgSet) WithCreatePolicy(msg *acptypes.MsgCreatePolicy) Mapper[*acptypes.MsgCreatePolicyResponse]

WithCreatePolicy includes a MsgCreatePolicy to the Tx

func (*MsgSet) WithCreatePost 

func (b *MsgSet) WithCreatePost(msg *bulletintypes.MsgCreatePost) Mapper[*bulletintypes.MsgCreatePostResponse]

WithCreatePost includes a MsgCreatePost to the Tx

func (*MsgSet) WithDirectPolicyCmd 

func (b *MsgSet) WithDirectPolicyCmd(msg *acptypes.MsgDirectPolicyCmd) Mapper[*acptypes.MsgDirectPolicyCmdResponse]

func (*MsgSet) WithEditPolicy 

func (b *MsgSet) WithEditPolicy(msg *acptypes.MsgEditPolicy) Mapper[*acptypes.MsgEditPolicyResponse]

WithEditPolicy includes a MsgEditPolicy to the Tx

func (*MsgSet) WithSignedPolicyCmd 

func (b *MsgSet) WithSignedPolicyCmd(msg *acptypes.MsgSignedPolicyCmd) Mapper[*acptypes.MsgSignedPolicyCmdResponse]

WithSignedPolicyCmd includes a MsgSignedPolicyCmd to the Tx

type Opt 

type Opt func(*Client) error

Opt configures the construction of a Client

func WithCometRPCAddr 

func WithCometRPCAddr(addr string) Opt

WithGRPCAddr sets the CometBFT RPC Address of a SourceHub node which the Client will connect to. If not set defaults to DefaultCometHTTPAddr

func WithGRPCAddr 

func WithGRPCAddr(addr string) Opt

WithGRPCAddr sets the GRPC Address of a SourceHub node which the Client will connect to. If not specified defaults to DefaultGRPCAddr Note: Cosmos queries are not verifiable therefore only trusted RPC nodes should be used.

func WithGRPCOpts 

func WithGRPCOpts(opts ...grpc.DialOption) Opt

WithGRPCOpts specifies the dial options which will be used to dial SourceHub's GRPC (queries) service

type TxBuilder 

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

func NewTxBuilder 

func NewTxBuilder(opts ...TxBuilderOpt) (TxBuilder, error)

func (*TxBuilder) Build 

func (b *TxBuilder) Build(ctx context.Context, signer TxSigner, set *MsgSet) (xauthsigning.Tx, error)

Build builds a SourceHub Tx containing msgs in MsgSet. The returned Tx can then be broadcast.

func (*TxBuilder) BuildFromMsgs 

func (b *TxBuilder) BuildFromMsgs(ctx context.Context, signer TxSigner, msgs ...sdk.Msg) (xauthsigning.Tx, error)

BuildFromMsgs builds a SourceHub Tx containing msgs. The returned Tx can then be broadcast.

type TxBuilderOpt 

type TxBuilderOpt func(*TxBuilder) error

TxBuilderOpt is a constructor option to initialize a TxBuilder

func WithAuthQueryClient 

func WithAuthQueryClient(client authtypes.QueryClient) TxBuilderOpt

WithGRPCConnection sets the GRPC Connection to be used in the Builder. The connection should point to a trusted SourceHub node which will be used to perform Cosmos Query client queries. Note: Cosmos queries are not verifiable therefore only trusted RPC nodes should be used.

func WithBearerToken added in v0.4.0 

func WithBearerToken(token string) TxBuilderOpt

WithBearerToken sets a JWS bearer token for DID-based authorization. The bearer token will be added as an extension option to the transaction.

func WithChainID 

func WithChainID(id string) TxBuilderOpt

WithChainID specifies the ChainID to which the Tx will be signed to. Defaults to the most recent SourceHub chain deployment

func WithFeeAmount 

func WithFeeAmount(fee int64) TxBuilderOpt

WithFeeToken specifies the fee value

func WithFeeGranter 

func WithFeeGranter(acc string) TxBuilderOpt

WithFeeGranter sets the fee granter for the Tx. The fee granter pays for the executed Tx. Fee grants are configured by cosmos x/feegrant module. See: https://pkg.go.dev/github.com/cosmos/cosmos-sdk/x/feegrant#section-readme

func WithFeeToken 

func WithFeeToken(denom string) TxBuilderOpt

WithFeeToken specifies the token denominator to use for the fee

func WithGasLimit 

func WithGasLimit(limit uint64) TxBuilderOpt

WithGasLimit configures the maxium

func WithMicroCredit 

func WithMicroCredit() TxBuilderOpt

WithMicroCredit configures TxBuilder to build Txs paid using credits

func WithMicroOpen 

func WithMicroOpen() TxBuilderOpt

WithMicroOpen configures TxBuilder to build Txs paid using open tokens

func WithSDKClient 

func WithSDKClient(client *Client) TxBuilderOpt

WithClient uses an SDK Client to retrieve the required connections.

func WithTestnetChainID 

func WithTestnetChainID() TxBuilderOpt

WithTestnetChainID specifies the ChainID to be SourceHub's latest test net

type TxExecResult 

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

TxExecResult models the outcome of a Tx evaluated by SourceHub. The Tx was either successfuly included or an error happened while handling one of its Msgs.

func (*TxExecResult) Error 

func (r *TxExecResult) Error() error

Error returns whether the error message if the Tx execution failed

func (*TxExecResult) TxPayload 

func (r *TxExecResult) TxPayload() *rpctypes.ResultTx

TxPayload returns the payload of the executed Tx

type TxListener 

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

TxListener is a client which subscribes to Tx events in SourceHub's cometbft socket and parses the received events into version with unmarshaled Msg Responses.

func NewTxListener 

func NewTxListener(client cometclient.Client) TxListener

NewTxListener creates a new listenver from a comet client

func (*TxListener) Close 

func (l *TxListener) Close()

Close stops listening for events and cleans up

func (*TxListener) Done 

func (l *TxListener) Done() <-chan struct{}

Done returns a channel which will be closed when the connection fails

func (*TxListener) ListenAsync added in v0.4.0 

func (l *TxListener) ListenAsync(ctx context.Context, cb func(*Event, error)) error

ListenAsync spawns a go routine and listens for txs asyncrhonously, until the comet client closes the connection, the context is cancelled. or the listener is closed. Callback is called each time an event or an error is received Returns an error if connection to commet fails

func (*TxListener) ListenTxs 

func (l *TxListener) ListenTxs(ctx context.Context) (<-chan Event, <-chan error, error)

ListenTxs spawns a go routine which continously listens for Tx events from a cometbft connection. The received events are returned into the Events channel, all errors are sent to the errors channel.

If ListenTxs fails to connect to the comet client, returns an error and nil channels.

type TxSigner 

type TxSigner interface {
	GetAccAddress() string
	GetPrivateKey() cryptotypes.PrivKey
}

TxSigner models an entity capable of providing signatures for a Tx.

Effectively, it can be either a secp256k1 cosmos-sdk key or a pointer to a secp256k1 key in a cosmos-sdk like keyring.

func NewTxSignerFromAccountAddress 

func NewTxSignerFromAccountAddress(keyring keyring.Keyring, address string) (TxSigner, error)

NewTxSignerFromAccountAddress takes a cosmos keyring and an account address and returns a TxSigner capable of signing Txs. If there are no keys matching the given address, returns an error.

In order to sign Txs, the key must be of type secp256k1, as it's the only supported Tx signing key in CosmosSDK. See https://docs.cosmos.network/main/learn/beginner/accounts#keys-accounts-addresses-and-signatures

Note: The adapter does not access the private key bytes directly, instead delegating the signing to the keyring itself. As such, any attempt to dump the bytes of the priv key will cause a panic

func NewTxSignerFromKeyringKey 

func NewTxSignerFromKeyringKey(keyring keyring.Keyring, name string) (TxSigner, error)

NewTxSignerFromKeyringKey receives a cosmos keyring and a named key in the keyring and returns a TxSigner capable of signing Txs. In order to sign Txs, the key must be of type secp256k1, as it's the only supported Tx signing key in CosmosSDK. See https://docs.cosmos.network/main/learn/beginner/accounts#keys-accounts-addresses-and-signatures

Note: The adapter does not access the private key bytes directly, instead delegating the signing to the keyring itself. As such, any attempt to dump the bytes of the priv key will cause a panic

func TxSignerFromCosmosKey 

func TxSignerFromCosmosKey(priv cryptotypes.PrivKey) TxSigner

TxSignerFromCosmosKey returns a TxSigner from a cosmos PrivKey

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.