Documentation
¶
Overview ¶
Package payment implements blockchain payment services for USDC on EVM chains.
Index ¶
- Constants
- Variables
- func ValidateAddress(addr string) error
- type PaymentReceipt
- type PaymentRequest
- type Service
- func (s *Service) Balance(ctx context.Context) (string, error)
- func (s *Service) ChainID() int64
- func (s *Service) History(ctx context.Context, limit int) ([]TransactionInfo, error)
- func (s *Service) RecordX402Payment(ctx context.Context, record X402PaymentRecord) error
- func (s *Service) Send(ctx context.Context, req PaymentRequest) (*PaymentReceipt, error)
- func (s *Service) WalletAddress(ctx context.Context) (string, error)
- type TransactionInfo
- type TxBuilder
- type X402PaymentRecord
Constants ¶
const ( DefaultBaseFeeWei = 1_000_000_000 // 1 gwei DefaultMaxPriorityFeeWei = 1_500_000_000 // 1.5 gwei BaseFeeMultiplier = 2 EthAddressLength = 42 )
Gas fee defaults for EIP-1559 transactions.
const DefaultHistoryLimit = 20
DefaultHistoryLimit is the default number of transactions returned by History.
const DefaultMaxRetries = 3
DefaultMaxRetries is the default number of transaction submission attempts.
const DefaultReceiptTimeout = 2 * time.Minute
DefaultReceiptTimeout is the maximum time to wait for on-chain confirmation.
Variables ¶
var BalanceOfSelector = []byte{0x70, 0xa0, 0x82, 0x31}
BalanceOfSelector is the function selector for balanceOf(address).
var ERC20TransferMethodID = crypto.Keccak256([]byte("transfer(address,uint256)"))[:4]
ERC20TransferMethodID is the function selector for transfer(address,uint256).
Functions ¶
func ValidateAddress ¶
ValidateAddress checks if a string is a valid Ethereum address.
Types ¶
type PaymentReceipt ¶
type PaymentReceipt struct {
TxHash string `json:"txHash"`
Status string `json:"status"`
Amount string `json:"amount"`
From string `json:"from"`
To string `json:"to"`
ChainID int64 `json:"chainId"`
GasUsed uint64 `json:"gasUsed,omitempty"`
BlockNumber uint64 `json:"blockNumber,omitempty"`
Timestamp time.Time `json:"timestamp"`
}
PaymentReceipt is returned after a payment is confirmed on-chain.
type PaymentRequest ¶
type PaymentRequest struct {
// To is the recipient wallet address.
To string `json:"to"`
// Amount is the USDC amount as a decimal string (e.g. "1.50").
Amount string `json:"amount"`
// Purpose is a human-readable description of the payment.
Purpose string `json:"purpose,omitempty"`
// SessionKey is the agent session that initiated the payment.
SessionKey string `json:"sessionKey,omitempty"`
// X402URL is the URL that triggered an X402 payment (if applicable).
X402URL string `json:"x402Url,omitempty"`
// PaymentMethod indicates how the payment was made ("direct_transfer" or "x402_v2").
PaymentMethod string `json:"paymentMethod,omitempty"`
}
PaymentRequest describes a payment to be sent.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service orchestrates blockchain payment operations.
func NewService ¶
func NewService( wp wallet.WalletProvider, limiter wallet.SpendingLimiter, builder *TxBuilder, client *ent.Client, rpcClient *ethclient.Client, chainID int64, ) *Service
NewService creates a payment service.
func (*Service) RecordX402Payment ¶
func (s *Service) RecordX402Payment(ctx context.Context, record X402PaymentRecord) error
RecordX402Payment records an X402 automatic payment for audit trail. Unlike Send(), this does not build or submit a transaction — the SDK handles payment signing. This only creates the database record for tracking.
func (*Service) Send ¶
func (s *Service) Send(ctx context.Context, req PaymentRequest) (*PaymentReceipt, error)
Send executes a payment: limit check → build tx → sign → submit → record.
type TransactionInfo ¶
type TransactionInfo struct {
TxHash string `json:"txHash,omitempty"`
Status string `json:"status"`
Amount string `json:"amount"`
From string `json:"from"`
To string `json:"to"`
ChainID int64 `json:"chainId"`
Purpose string `json:"purpose,omitempty"`
X402URL string `json:"x402Url,omitempty"`
PaymentMethod string `json:"paymentMethod,omitempty"`
ErrorMessage string `json:"errorMessage,omitempty"`
CreatedAt time.Time `json:"createdAt"`
}
TransactionInfo combines a receipt with contextual information.
type TxBuilder ¶
type TxBuilder struct {
// contains filtered or unexported fields
}
TxBuilder constructs ERC-20 transfer transactions.
func NewTxBuilder ¶
NewTxBuilder creates a transaction builder for the given chain.
func (*TxBuilder) BuildTransferTx ¶
func (b *TxBuilder) BuildTransferTx(ctx context.Context, from common.Address, to common.Address, amount *big.Int) (*types.Transaction, error)
BuildTransferTx constructs an EIP-1559 ERC-20 transfer transaction. Returns the sighash (transaction hash to sign) and the unsigned transaction.
func (*TxBuilder) USDCContract ¶
USDCContract returns the configured USDC contract address.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package contracts provides canonical USDC contract addresses and on-chain verification utilities for supported EVM chains.
|
Package contracts provides canonical USDC contract addresses and on-chain verification utilities for supported EVM chains. |
|
Package eip3009 implements EIP-3009 transferWithAuthorization typed data building and signing for USDC gasless transfers.
|
Package eip3009 implements EIP-3009 transferWithAuthorization typed data building and signing for USDC gasless transfers. |