chainrpc

README

KernelFlow Chain RPC

The online companion to wallet-sdk: per-chain RPC handlers that read chain state, broadcast signed transactions, and inspect results. Where wallet-sdk is the offline signing core (it never touches the network), chain-rpc is the network plumbing (it never touches private keys).

Architecture

wallet-sdk   crypto + chain     offline signing, key-light, audited   ── trust anchor
   ▲
   │ require (one-way)
   │
chain-rpc    BasicChainHandler  online RPC: query + broadcast          ── network plumbing

The two halves are intentionally separate repos:

• Different dependency weight — chain-rpc pulls go-ethereum/ethclient and each chain's RPC client; the signing core stays lean.
• Different security profile — signing holds keys and is the audit target; RPC only talks to nodes.
• Different release cadence — RPC endpoints and parsing change often; signing is stable.

The contract

Every chain handler implements one interface:

type BasicChainHandler interface {
	GetHeight(ctx context.Context) (string, error)
	GetBalance(ctx context.Context, address, contractAddress, blockNumber string) (string, error)
	SendTx(ctx context.Context, signedHex string) (string, error)
	CheckTx(ctx context.Context, hash string) (*TxResult, error)
	CallContract(ctx context.Context, contractAddress, params, blockNumber string) ([]byte, error)
	InquireChain(ctx context.Context, instruction, params string) (string, error)
}

The root chainrpc package owns the shared result types (TxResult, Transfer, BalanceChange, EvmLog, TxTransfers, TokenInfo, BasicEvmTx) and the generic ERC-20 identifiers. It imports wallet-sdk/chain only for the cross-cutting constants (MagicContactAddressForNative, TxStatus*) and UtxoList.

Usage

import "github.com/KernelFlowLabs/chain-rpc/evm"

h, _ := evm.NewHandler("https://rpc.example.org", "1") // chainId 1
height, _ := h.GetHeight(ctx)
hash, _ := h.SendTx(ctx, signedHexFromWalletSDK)

Status

Chain	Handler
EVM	✅ reference
Solana	✅ ported
Tron	✅ ported
Aptos	✅ ported
Sui	✅ ported
Kaspa	✅ ported
Substrate	✅ ported
MultiversX	✅ ported
UTXO	✅ ported

The EVM package is the reference implementation that establishes the pattern: implement chainrpc.BasicChainHandler, import wallet-sdk/chain for shared constants, return chainrpc result types. Remaining chains are ported one by one against the same contract.

Development

go.mod uses a local replace pointing at a sibling wallet-sdk checkout while both are pre-publication. Remove it once wallet-sdk is tagged.

go build ./...
go test ./...

License

Apache License 2.0 — see LICENSE.

Documentation

Index

• Constants
• func GetJsonBody(body interface{}) (buf io.ReadWriter, err error)
• type BalanceChange
• type BasicChainHandler
• type BasicEvmTx
• type EvmLog
  • func (in *EvmLog) String() string
• type RateLimitError
  • func (e *RateLimitError) Error() string
• type Request
  • func NewRequest(baseUrl string, headers map[string]string) *Request
  • func (r *Request) Delete(ctx context.Context, result interface{}, path string) error
  • func (r *Request) Execute(ctx context.Context, method string, url string, body io.Reader, ...) error
  • func (r *Request) ExecuteRaw(ctx context.Context, method string, url string, body io.Reader, ...) error
  • func (r *Request) Get(ctx context.Context, result interface{}, path string, query url.Values) error
  • func (r *Request) GetBase(path string) string
  • func (r *Request) GetRaw(ctx context.Context, result *bytes.Buffer, path string, query url.Values) error
  • func (r *Request) Patch(ctx context.Context, result interface{}, path string, body interface{}) error
  • func (r *Request) Post(ctx context.Context, result interface{}, path string, body interface{}) error
  • func (r *Request) PostWithOutEncoded(ctx context.Context, result interface{}, path string, body interface{}) error
  • func (r *Request) PostWithPlain(ctx context.Context, result interface{}, path string, body io.Reader) error
  • func (r *Request) PostWithXWWWFormUrlencoded(ctx context.Context, result interface{}, path string, body interface{}) error
  • func (r *Request) SetBaseUrl(url string)
  • func (r *Request) SetHeader(k, v string)
• type TokenInfo
• type Transfer
• type TxResult
• type TxTransfers

Constants

const (
	TxStatusUnknown    = "Unknown"
	TxStatusPending    = "Pending"
	TxStatusVerified   = "Verified"
	TxStatusSucceeded  = "Succeeded"
	TxStatusFailed     = "Failed"
	TxStatusDropped    = "Dropped"
	TxStatusWaitVerify = "WaitVerify"
	TxStatusRefunding  = "Refunding"
	TxStatusRefunded   = "Refunded"
)

Functions

func GetJsonBody

func GetJsonBody(body interface{}) (buf io.ReadWriter, err error)

Types

type BalanceChange

type BalanceChange struct {
	Address         string `json:"address"`
	ContractAddress string `json:"contractAddress"`
	Change          string `json:"change"`
}

type BasicChainHandler

type BasicChainHandler interface {
	GetHeight(ctx context.Context) (string, error)
	GetBalance(ctx context.Context, address, contractAddress, blockNumber string) (string, error)
	SendTx(ctx context.Context, signedHex string) (string, error)
	CheckTx(ctx context.Context, hash string) (*TxResult, error)
	CallContract(ctx context.Context, contractAddress, params, blockNumber string) ([]byte, error)
	InquireChain(ctx context.Context, instruction, params string) (string, error)
}

type BasicEvmTx

type BasicEvmTx struct {
	Hash    string `json:"hash"`
	From    string `json:"from"`
	To      string `json:"to"`
	Payload string `json:"input"`
}

type EvmLog

type EvmLog struct {
	Address     string `json:"address"`
	Topics      string `json:"topics"`
	Data        string `json:"data"`
	BlockNumber uint64 `json:"blockNumber"`
	TxHash      string `json:"txHash,omitempty"`
}

func (*EvmLog) String

func (in *EvmLog) String() string

type RateLimitError

type RateLimitError struct {
	Method string
	URL    string
	Err    error
}

func (*RateLimitError) Error

func (e *RateLimitError) Error() string

type Request

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

func NewRequest

func NewRequest(baseUrl string, headers map[string]string) *Request

func (*Request) Delete

func (r *Request) Delete(ctx context.Context, result interface{}, path string) error

func (*Request) Execute

func (r *Request) Execute(ctx context.Context, method string, url string, body io.Reader, result interface{}) error

func (*Request) ExecuteRaw

func (r *Request) ExecuteRaw(ctx context.Context, method string, url string, body io.Reader, result *bytes.Buffer) error

func (*Request) Get

func (r *Request) Get(ctx context.Context, result interface{}, path string, query url.Values) error

func (*Request) GetBase

func (r *Request) GetBase(path string) string

func (*Request) GetRaw

func (r *Request) GetRaw(ctx context.Context, result *bytes.Buffer, path string, query url.Values) error

func (*Request) Patch

func (r *Request) Patch(ctx context.Context, result interface{}, path string, body interface{}) error

func (*Request) Post

func (r *Request) Post(ctx context.Context, result interface{}, path string, body interface{}) error

func (*Request) PostWithOutEncoded

func (r *Request) PostWithOutEncoded(ctx context.Context, result interface{}, path string, body interface{}) error

func (*Request) PostWithPlain

func (r *Request) PostWithPlain(ctx context.Context, result interface{}, path string, body io.Reader) error

func (*Request) PostWithXWWWFormUrlencoded

func (r *Request) PostWithXWWWFormUrlencoded(ctx context.Context, result interface{}, path string, body interface{}) error

func (*Request) SetBaseUrl

func (r *Request) SetBaseUrl(url string)

func (*Request) SetHeader

func (r *Request) SetHeader(k, v string)

type TokenInfo

type TokenInfo struct {
	Name     string `json:"name"`
	Symbol   string `json:"symbol"`
	Decimals string `json:"decimals"`
}

type Transfer

type Transfer struct {
	Sender          string `json:"sender"`
	Recipient       string `json:"recipient"`
	Amount          string `json:"amount"`
	ContractAddress string `json:"contractAddress"`
	Memo            string `json:"memo,omitempty"`
}

type TxResult

type TxResult struct {
	Status  string   `json:"status"`
	Height  string   `json:"height"`
	Time    string   `json:"time"`
	GasUsed string   `json:"gasUsed"`
	ErrMsg  string   `json:"errMsg"`
	Logs    []EvmLog `json:"logs,omitempty"`
}

type TxTransfers

type TxTransfers struct {
	Hash          string           `json:"hash"`
	Rejected      bool             `json:"rejected"`
	ErrMsg        string           `json:"errMsg"`
	Transfers     []*Transfer      `json:"transfers"`
	BalanceChange []*BalanceChange `json:"balanceChange"`
}