Documentation
¶
Overview ¶
Package paygate implements a payment gate that checks tool pricing and verifies EIP-3009 payment authorizations between the firewall and tool executor in the P2P protocol.
Package paygate implements trust-based payment tier routing.
Index ¶
Constants ¶
const DefaultPostPayThreshold = 0.7
DefaultPostPayThreshold is the minimum trust score for a peer to qualify for post-pay (pay-after-execution). This constant is shared between paygate and team payment modules to avoid threshold drift.
const DefaultQuoteExpiry = 5 * time.Minute
DefaultQuoteExpiry is the validity window for a price quote.
Variables ¶
var ParseUSDC = wallet.ParseUSDC
ParseUSDC delegates to wallet.ParseUSDC. Kept as a package-level alias for backward compatibility within the paygate package.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
PricingFn PricingFunc
ReputationFn ReputationFunc
TrustCfg TrustConfig
LocalAddr string
ChainID int64
USDCAddr common.Address
RPCClient *ethclient.Client
Logger *zap.SugaredLogger
}
Config holds construction parameters for a Gate.
type DeferredEntry ¶ added in v0.4.0
type DeferredEntry struct {
ID string `json:"id"`
PeerDID string `json:"peerDid"`
ToolName string `json:"toolName"`
Price string `json:"price"`
CreatedAt time.Time `json:"createdAt"`
Settled bool `json:"settled"`
TxHash string `json:"txHash,omitempty"`
}
DeferredEntry tracks a post-pay obligation that is settled asynchronously after tool execution completes.
type DeferredLedger ¶ added in v0.4.0
type DeferredLedger struct {
// contains filtered or unexported fields
}
DeferredLedger is an in-memory ledger tracking post-pay obligations. It is safe for concurrent use.
func NewDeferredLedger ¶ added in v0.4.0
func NewDeferredLedger() *DeferredLedger
NewDeferredLedger creates an empty deferred ledger.
func (*DeferredLedger) Add ¶ added in v0.4.0
func (l *DeferredLedger) Add(peerDID, toolName, price string) string
Add records a new deferred payment obligation and returns the entry ID.
func (*DeferredLedger) Cleanup ¶ added in v0.4.0
func (l *DeferredLedger) Cleanup() int
Cleanup removes all settled entries from the ledger, freeing memory. Returns the number of entries removed.
func (*DeferredLedger) Pending ¶ added in v0.4.0
func (l *DeferredLedger) Pending() []*DeferredEntry
Pending returns all unsettled entries.
func (*DeferredLedger) PendingByPeer ¶ added in v0.4.0
func (l *DeferredLedger) PendingByPeer(peerDID string) []*DeferredEntry
PendingByPeer returns unsettled entries for a specific peer.
func (*DeferredLedger) Settle ¶ added in v0.4.0
func (l *DeferredLedger) Settle(id, txHash string) bool
Settle marks an entry as settled with the given transaction hash. Returns false if the entry does not exist.
type Gate ¶
type Gate struct {
// contains filtered or unexported fields
}
Gate sits between the firewall and the tool executor, enforcing payment requirements for paid tools.
func (*Gate) BuildQuote ¶
func (g *Gate) BuildQuote(toolName, price string) *PriceQuote
BuildQuote creates a PriceQuote for the given tool and price.
func (*Gate) Check ¶
Check evaluates whether a tool invocation should proceed. It looks up the tool price, and if payment is required, validates the EIP-3009 authorization embedded in the payload. High-trust peers (score > PostPayMinScore) are granted post-pay: the tool executes first, settlement happens asynchronously.
func (*Gate) Ledger ¶ added in v0.4.0
func (g *Gate) Ledger() *DeferredLedger
Ledger returns the deferred payment ledger for post-pay tracking.
type PriceQuote ¶
type PriceQuote struct {
ToolName string `json:"toolName"`
Price string `json:"price"`
Currency string `json:"currency"`
USDCContract string `json:"usdcContract"`
ChainID int64 `json:"chainId"`
SellerAddr string `json:"sellerAddr"`
QuoteExpiry int64 `json:"quoteExpiry"`
}
PriceQuote tells a buyer what to pay for a tool invocation.
type PricingFunc ¶
PricingFunc returns the price (decimal USDC string like "0.50") and whether the tool is free.
type ReputationFunc ¶ added in v0.4.0
ReputationFunc returns the trust score for a peer. The score is in [0, 1].
type Result ¶
type Result struct {
Status ResultStatus `json:"status"`
Auth *eip3009.Authorization `json:"auth,omitempty"`
PriceQuote *PriceQuote `json:"priceQuote,omitempty"`
Reason string `json:"reason,omitempty"`
SettlementID string `json:"settlementId,omitempty"`
}
Result describes the outcome of a payment gate check.
type ResultStatus ¶
type ResultStatus string
ResultStatus describes the outcome of a payment gate check.
const ( // StatusFree means the tool is free; no payment required. StatusFree ResultStatus = "free" // StatusVerified means a valid payment authorization was provided. StatusVerified ResultStatus = "verified" // StatusPaymentRequired means the tool is paid but no authorization was // provided; the PriceQuote tells the caller what to pay. StatusPaymentRequired ResultStatus = "payment_required" // StatusInvalid means the provided payment authorization is invalid. StatusInvalid ResultStatus = "invalid" // StatusPostPayApproved means the peer has high enough trust to defer // payment until after tool execution (post-pay). StatusPostPayApproved ResultStatus = "postpay_approved" )
type TrustConfig ¶ added in v0.4.0
type TrustConfig struct {
// PostPayMinScore is the minimum score to qualify for post-pay.
PostPayMinScore float64
}
TrustConfig holds thresholds for trust-based payment tier decisions.
func DefaultTrustConfig ¶ added in v0.4.0
func DefaultTrustConfig() TrustConfig
DefaultTrustConfig returns a TrustConfig with production defaults.
Source Files