wallet

Documentation

Overview

Package wallet handles all blockchain interactions for USDC transfers

Index

• Constants
• Variables
• func FormatUSDC(amount *big.Int) string
• func ParseUSDC(amount string) (*big.Int, error)
• type BalanceChecker
• type Config
• type EthClient
• type Option
  • func WithClient(client EthClient) Option
• type PaymentVerifier
• type Transactor
• type TransferError
  • func (e *TransferError) Error() string
  • func (e *TransferError) Unwrap() error
• type TransferResult
• type Wallet
  • func New(cfg Config, opts ...Option) (*Wallet, error)
  • func (w *Wallet) Address() string
  • func (w *Wallet) Balance(ctx context.Context) (string, error)
  • func (w *Wallet) BalanceOf(ctx context.Context, addr common.Address) (*big.Int, error)
  • func (w *Wallet) Close() error
  • func (w *Wallet) Transfer(ctx context.Context, to common.Address, amount *big.Int) (*TransferResult, error)
  • func (w *Wallet) VerifyPayment(ctx context.Context, from string, minAmount string, txHash string) (bool, error)
  • func (w *Wallet) WaitForConfirmation(ctx context.Context, txHash string, timeout time.Duration) (*TransferResult, error)
  • func (w *Wallet) WaitForConfirmationAny(ctx context.Context, txHash string, timeout time.Duration) (interface{}, error)
• type WalletService

Constants

const (
	// USDCDecimals is the decimal precision of USDC
	USDCDecimals = 6

	// DefaultGasLimit for ERC20 transfers
	DefaultGasLimit = uint64(100000)

	// DefaultConfirmationTimeout for waiting on transactions
	DefaultConfirmationTimeout = 30 * time.Second

	// ConfirmationPollInterval between receipt checks
	ConfirmationPollInterval = 2 * time.Second
)

Variables

var (
	ErrInvalidPrivateKey   = errors.New("wallet: invalid private key")
	ErrInvalidAddress      = errors.New("wallet: invalid address")
	ErrInvalidAmount       = errors.New("wallet: invalid amount")
	ErrInsufficientBalance = errors.New("wallet: insufficient balance")
	ErrTransactionFailed   = errors.New("wallet: transaction failed")
	ErrTimeout             = errors.New("wallet: operation timed out")
	ErrRPCConnection       = errors.New("wallet: RPC connection failed")
)

Functions

func FormatUSDC

func FormatUSDC(amount *big.Int) string

FormatUSDC converts raw USDC amount to human-readable string

func ParseUSDC

func ParseUSDC(amount string) (*big.Int, error)

ParseUSDC converts human-readable USDC string to raw amount

Types

type BalanceChecker

type BalanceChecker interface {
	BalanceOf(ctx context.Context, addr common.Address) (*big.Int, error)
}

BalanceChecker reads blockchain state

type Config

type Config struct {
	RPCURL       string
	PrivateKey   string // Hex string, no 0x prefix
	ChainID      int64
	USDCContract string
}

Config for creating a new wallet

type EthClient

type EthClient interface {
	PendingNonceAt(ctx context.Context, account common.Address) (uint64, error)
	SuggestGasPrice(ctx context.Context) (*big.Int, error)
	EstimateGas(ctx context.Context, call ethereum.CallMsg) (uint64, error)
	SendTransaction(ctx context.Context, tx *types.Transaction) error
	TransactionReceipt(ctx context.Context, txHash common.Hash) (*types.Receipt, error)
	CallContract(ctx context.Context, call ethereum.CallMsg, blockNumber *big.Int) ([]byte, error)
	NetworkID(ctx context.Context) (*big.Int, error)
	Close()
}

EthClient abstracts go-ethereum client for testing

type Option

type Option func(*Wallet)

Option configures the wallet

func WithClient

func WithClient(client EthClient) Option

WithClient sets a custom Ethereum client (useful for testing)

type PaymentVerifier

type PaymentVerifier interface {
	VerifyPayment(ctx context.Context, from string, minAmount string, txHash string) (bool, error)
}

PaymentVerifier verifies on-chain payments

type Transactor

type Transactor interface {
	Transfer(ctx context.Context, to common.Address, amount *big.Int) (*TransferResult, error)
	WaitForConfirmation(ctx context.Context, txHash string, timeout time.Duration) (*TransferResult, error)
}

Transactor executes blockchain transactions

type TransferError

type TransferError struct {
	Op     string // Operation that failed
	TxHash string // Transaction hash if available
	Err    error  // Underlying error
}

TransferError wraps transfer failures with context

func (*TransferError) Error

func (e *TransferError) Error() string

func (*TransferError) Unwrap

func (e *TransferError) Unwrap() error

type TransferResult

type TransferResult struct {
	TxHash      string
	From        string
	To          string
	Amount      string // Human-readable USDC amount
	AmountRaw   *big.Int
	BlockNumber uint64
	GasUsed     uint64
	Nonce       uint64
}

TransferResult contains details of a completed transfer

type Wallet

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

Wallet handles USDC transfers on Base

func New

func New(cfg Config, opts ...Option) (*Wallet, error)

New creates a new Wallet instance

func (*Wallet) Address

func (w *Wallet) Address() string

Address returns the wallet's address

func (*Wallet) Balance

func (w *Wallet) Balance(ctx context.Context) (string, error)

Balance returns the USDC balance as a human-readable string

func (*Wallet) BalanceOf

func (w *Wallet) BalanceOf(ctx context.Context, addr common.Address) (*big.Int, error)

BalanceOf returns the USDC balance of any address

func (*Wallet) Close

func (w *Wallet) Close() error

Close closes the client connection

func (*Wallet) Transfer

func (w *Wallet) Transfer(ctx context.Context, to common.Address, amount *big.Int) (*TransferResult, error)

Transfer sends USDC to a recipient amount is in human-readable format (e.g., "1.50" for $1.50)

func (*Wallet) VerifyPayment

func (w *Wallet) VerifyPayment(ctx context.Context, from string, minAmount string, txHash string) (bool, error)

VerifyPayment checks if a payment was received from a specific address

func (*Wallet) WaitForConfirmation

func (w *Wallet) WaitForConfirmation(ctx context.Context, txHash string, timeout time.Duration) (*TransferResult, error)

WaitForConfirmation waits for a transaction to be mined

func (*Wallet) WaitForConfirmationAny

func (w *Wallet) WaitForConfirmationAny(ctx context.Context, txHash string, timeout time.Duration) (interface{}, error)

WaitForConfirmationAny wraps WaitForConfirmation to satisfy interfaces that don't need the result type This is the Go-idiomatic way to handle interface adaptation

type WalletService

type WalletService interface {
	Transactor
	BalanceChecker
	PaymentVerifier
	Address() string
	Balance(ctx context.Context) (string, error)
	WaitForConfirmationAny(ctx context.Context, txHash string, timeout time.Duration) (interface{}, error)
	Close() error
}

Wallet combines all wallet operations