x402/go/interfaces.go
Carson Roscoe 2b7914c72e
feat: batch settlement go sdk (#2230)
* feat: add batch-settlement implementation to Go SDK

* feat: add batch-settlement examples for go sdk

* feat: updated typescript examples to match go examples

* feat: add e2e testing for batch-settlement in go

* Batch-settlement: go-ts parity (#2227)

* fix PendingRequest and refund cleanup

* fix lint

* remove duplicate payer info from storage

* fix PAYMENT-RESPONSE field ordering

* clean up comments

* consolidate ProcessSettlementWithExtensions into ProcessSettlement

---------

Co-authored-by: phdargen <p.dargent@cern.ch>
2026-05-07 18:26:39 -07:00

291 lines
12 KiB
Go

package x402
import (
"context"
"github.com/x402-foundation/x402/go/types"
)
// MoneyParser is a function that converts a decimal amount to an AssetAmount
// If the parser cannot handle the conversion, it should return nil
// Multiple parsers can be registered and will be tried in order
// The default parser is always used as a fallback
//
// Args:
//
// amount: Decimal amount (e.g., 1.50 for $1.50)
// network: Network identifier
//
// Returns:
//
// AssetAmount or nil if this parser cannot handle the conversion
type MoneyParser func(amount float64, network Network) (*AssetAmount, error)
// ============================================================================
// V1 Interfaces (Legacy - explicitly versioned)
// ============================================================================
// SchemeNetworkClientV1 is implemented by client-side V1 payment mechanisms
type SchemeNetworkClientV1 interface {
Scheme() string
CreatePaymentPayload(ctx context.Context, requirements types.PaymentRequirementsV1) (types.PaymentPayloadV1, error)
}
// SchemeNetworkFacilitatorV1 is implemented by facilitator-side V1 payment mechanisms
type SchemeNetworkFacilitatorV1 interface {
Scheme() string
// CaipFamily returns the CAIP family pattern this facilitator supports.
// Used to group signers by blockchain family in the supported response.
//
// Examples:
// - EVM facilitators return "eip155:*"
// - SVM facilitators return "solana:*"
CaipFamily() string
// GetExtra returns mechanism-specific extra data for the supported kinds endpoint.
// This method is called when building the facilitator's supported response.
//
// For EVM schemes, return nil (no extra data needed).
// For SVM schemes, return map with feePayer address.
//
// Args:
// network: Network identifier for context
//
// Returns:
// Extra data map or nil if no extra data is needed
GetExtra(network Network) map[string]interface{}
// GetSigners returns signer addresses used by this facilitator for a given network.
// These are included in the supported response to help clients understand
// which addresses might sign/pay for transactions.
//
// Supports multiple addresses for load balancing, key rotation, and high availability.
//
// Args:
// network: Network identifier
//
// Returns:
// Array of signer addresses
//
// Examples:
// - EVM: Returns facilitator wallet addresses
// - SVM: Returns fee payer addresses
GetSigners(network Network) []string
Verify(ctx context.Context, payload types.PaymentPayloadV1, requirements types.PaymentRequirementsV1, fctx *FacilitatorContext) (*VerifyResponse, error)
Settle(ctx context.Context, payload types.PaymentPayloadV1, requirements types.PaymentRequirementsV1, fctx *FacilitatorContext) (*SettleResponse, error)
}
// Note: No SchemeNetworkServerV1 - new SDK servers are V2 only
// ============================================================================
// V2 Interfaces (Current - default, no version suffix)
// ============================================================================
// SchemeNetworkClient is implemented by client-side payment mechanisms (V2)
type SchemeNetworkClient interface {
Scheme() string
CreatePaymentPayload(ctx context.Context, requirements types.PaymentRequirements) (types.PaymentPayload, error)
}
// ExtensionAwareClient is an optional interface for schemes that can handle extensions.
// When a scheme implements this, x402Client will call CreatePaymentPayloadWithExtensions
// instead of CreatePaymentPayload, passing the server-declared extensions so the scheme
// can enrich the payload (e.g., EIP-2612 gas sponsoring).
type ExtensionAwareClient interface {
SchemeNetworkClient
CreatePaymentPayloadWithExtensions(ctx context.Context, requirements types.PaymentRequirements, extensions map[string]interface{}) (types.PaymentPayload, error)
}
// PaymentResponseContext is passed to PaymentResponseHandler implementations after
// the transport receives the response to a paid request. Exactly one of SettleResponse
// or PaymentRequired is populated:
//
// - SettleResponse: the request succeeded (HTTP 200) and the server returned a
// PAYMENT-RESPONSE header carrying the settle outcome.
// - PaymentRequired: the request was rejected (HTTP 402) with a corrective
// PAYMENT-REQUIRED header (e.g. cumulative_amount_mismatch).
//
// Mirrors the TS PaymentResponseContext shape consumed by SchemeClientHooks.onPaymentResponse.
type PaymentResponseContext struct {
PaymentPayload types.PaymentPayload
Requirements types.PaymentRequirements
SettleResponse *SettleResponse
PaymentRequired *types.PaymentRequired
}
// PaymentResponseResult is returned by PaymentResponseHandler.OnPaymentResponse.
// When Recovered is true, the transport may attempt one additional retry with a
// freshly built payment payload. Used to handle corrective 402 responses where
// the scheme has resynced its session state.
type PaymentResponseResult struct {
Recovered bool
}
// PaymentResponseHandler is an optional interface that SchemeNetworkClient
// implementations satisfy to reconcile local state after a paid response.
// The transport (PaymentRoundTripper) invokes this hook automatically — user
// code does not need to call ProcessSettleResponse manually.
//
// Mirrors the TS schemeHooks.onPaymentResponse field on SchemeClientHooks.
type PaymentResponseHandler interface {
OnPaymentResponse(ctx context.Context, prCtx PaymentResponseContext) (PaymentResponseResult, error)
}
// ClientExtension can enrich payment payloads on the client side.
// Client extensions are invoked after the scheme creates the base payload
// but before it is returned. This allows mechanism-specific logic (e.g., EVM EIP-2612
// permit signing) to enrich the payload's extensions data.
type ClientExtension interface {
// Key returns the unique extension identifier (e.g., "eip2612GasSponsoring").
// Must match the extension key used in PaymentRequired.Extensions.
Key() string
// EnrichPaymentPayload is called after payload creation when the extension key
// is present in paymentRequired.Extensions. Allows the extension to enrich the
// payload with extension-specific data (e.g., signing an EIP-2612 permit).
EnrichPaymentPayload(ctx context.Context, payload types.PaymentPayload, required types.PaymentRequired) (types.PaymentPayload, error)
}
// FacilitatorExtension is the base interface for extensions registered with x402Facilitator.
// Extensions are stored by key and made available to mechanism implementations via FacilitatorContext.
// Specific extensions embed this and add their own capabilities (e.g., a batch signer).
type FacilitatorExtension interface {
Key() string
}
// facilitatorExtension is a simple concrete implementation of FacilitatorExtension.
type facilitatorExtension struct {
key string
}
func (e facilitatorExtension) Key() string { return e.key }
// NewFacilitatorExtension creates a FacilitatorExtension with the given key.
func NewFacilitatorExtension(key string) FacilitatorExtension {
return facilitatorExtension{key: key}
}
// FacilitatorContext provides access to registered facilitator extensions.
// Passed to SchemeNetworkFacilitator.Verify/Settle so mechanism implementations
// can retrieve extension-provided capabilities.
type FacilitatorContext struct {
extensions map[string]FacilitatorExtension
}
// NewFacilitatorContext creates a FacilitatorContext from the given extensions map.
func NewFacilitatorContext(extensions map[string]FacilitatorExtension) *FacilitatorContext {
return &FacilitatorContext{extensions: extensions}
}
// GetExtension returns the extension registered under the given key, or nil.
func (c *FacilitatorContext) GetExtension(key string) FacilitatorExtension {
if c == nil || c.extensions == nil {
return nil
}
return c.extensions[key]
}
// SchemeNetworkServer is implemented by server-side payment mechanisms (V2)
type SchemeNetworkServer interface {
Scheme() string
ParsePrice(price Price, network Network) (AssetAmount, error)
EnhancePaymentRequirements(
ctx context.Context,
requirements types.PaymentRequirements,
supportedKind types.SupportedKind,
extensions []string,
) (types.PaymentRequirements, error)
}
// AssetDecimalsProvider is an optional interface that SchemeNetworkServer implementations
// can satisfy to report the decimal precision of the asset for a given network.
// SettlePayment uses this to convert dollar-format settlement overrides to atomic units.
// Falls back to 6 decimals when the scheme does not implement this interface.
type AssetDecimalsProvider interface {
GetAssetDecimals(asset string, network Network) int
}
// PaymentRequiredContext is passed to PaymentRequiredEnricher.EnrichPaymentRequiredResponse.
// PaymentPayload is non-nil only on the verify-failure branch.
type PaymentRequiredContext struct {
Requirements []types.PaymentRequirements
PaymentPayload *types.PaymentPayload
ResourceInfo *types.ResourceInfo
Error string
PaymentRequiredResponse *types.PaymentRequired
}
// PaymentRequiredEnricher is an optional interface for SchemeNetworkServer
// implementations that want to add per-scheme corrective state to the 402
// response. Invoked once per matching scheme during PaymentRequired construction;
// implementations may mutate ctx.Requirements entries in place.
type PaymentRequiredEnricher interface {
EnrichPaymentRequiredResponse(ctx PaymentRequiredContext)
}
// SchemeNetworkFacilitator is implemented by facilitator-side payment mechanisms (V2)
type SchemeNetworkFacilitator interface {
Scheme() string
// CaipFamily returns the CAIP family pattern this facilitator supports.
// Used to group signers by blockchain family in the supported response.
//
// Examples:
// - EVM facilitators return "eip155:*"
// - SVM facilitators return "solana:*"
CaipFamily() string
// GetExtra returns mechanism-specific extra data for the supported kinds endpoint.
// This method is called when building the facilitator's supported response.
//
// For EVM schemes, return nil (no extra data needed).
// For SVM schemes, return map with feePayer address.
//
// Args:
// network: Network identifier for context
//
// Returns:
// Extra data map or nil if no extra data is needed
GetExtra(network Network) map[string]interface{}
// GetSigners returns signer addresses used by this facilitator for a given network.
// These are included in the supported response to help clients understand
// which addresses might sign/pay for transactions.
//
// Supports multiple addresses for load balancing, key rotation, and high availability.
//
// Args:
// network: Network identifier
//
// Returns:
// Array of signer addresses
//
// Examples:
// - EVM: Returns facilitator wallet addresses
// - SVM: Returns fee payer addresses
GetSigners(network Network) []string
Verify(ctx context.Context, payload types.PaymentPayload, requirements types.PaymentRequirements, fctx *FacilitatorContext) (*VerifyResponse, error)
Settle(ctx context.Context, payload types.PaymentPayload, requirements types.PaymentRequirements, fctx *FacilitatorContext) (*SettleResponse, error)
}
// ============================================================================
// FacilitatorClient Interfaces (Network Boundary - uses bytes)
// ============================================================================
// FacilitatorClient interface for facilitators that support V1 and/or V2.
// Uses bytes at network boundary - SDK internal routing unmarshals and routes to typed mechanisms.
// Both modern facilitators (supporting V1+V2) and legacy facilitators (V1 only) implement this interface.
type FacilitatorClient interface {
// Verify a payment (detects version from bytes, routes internally)
Verify(ctx context.Context, payloadBytes []byte, requirementsBytes []byte) (*VerifyResponse, error)
// Settle a payment (detects version from bytes, routes internally)
Settle(ctx context.Context, payloadBytes []byte, requirementsBytes []byte) (*SettleResponse, error)
// GetSupported returns supported payment kinds in flat array format with x402Version in each element (backward compatible)
GetSupported(ctx context.Context) (SupportedResponse, error)
}