schemas

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 6, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

Documentation

Overview

Package schemas provides shared type definitions aligned with the x402 and ERC-8004 ecosystems. These types are the canonical source for ServiceOffer CRD fields, verifier config, CLI flag mapping, and reconciler logic.

Field names are chosen to match the x402 PaymentRequirements wire format where possible (payTo, network, scheme, maxTimeoutSeconds). Human-friendly values (e.g., "base-sepolia" instead of CAIP-2 "eip155:84532") are used in CRD specs; the reconciler translates to wire format at runtime.

Index

Constants

View Source 
const (
	AssetTransferMethodEIP3009 = "eip3009"
	AssetTransferMethodPermit2 = "permit2"
)
View Source 
const ApproxMinutesPerRequest = 5

ApproxMinutesPerRequest is the temporary phase-1 time estimate used to convert per-hour pricing into an x402 per-request charge. Based on the autoresearch 5-minute experiment budget.

View Source 
const ApproxTokensPerRequest = 1000

ApproxTokensPerRequest is the temporary phase-1 token estimate used to convert per-million-token pricing into an x402 per-request charge.

Variables

View Source 
var ServiceCatalogJSONSchema string

ServiceCatalogJSONSchema is the JSON Schema for the public /api/services.json catalog served by sellers.

Functions

func ApproximateRequestPriceFromPerHour 

func ApproximateRequestPriceFromPerHour(perHour string) (string, error)

ApproximateRequestPriceFromPerHour converts a per-hour price into a temporary per-request x402 charge using ApproxMinutesPerRequest (default 5 min, matching the autoresearch experiment budget). Formula: perRequest = perHour * (minutesPerRequest / 60)

func ApproximateRequestPriceFromPerMTok 

func ApproximateRequestPriceFromPerMTok(perMTok string) (string, error)

ApproximateRequestPriceFromPerMTok converts a per-million-token price into a temporary per-request x402 charge using ApproxTokensPerRequest.

Types

type AssetTerms added in v0.9.0 

type AssetTerms struct {
	// Address is the ERC-20 contract address.
	Address string `json:"address,omitempty" yaml:"address,omitempty"`

	// Symbol is a human-friendly token symbol (e.g. USDC, OBOL).
	Symbol string `json:"symbol,omitempty" yaml:"symbol,omitempty"`

	// Decimals is the token precision in atomic units.
	Decimals int `json:"decimals,omitempty" yaml:"decimals,omitempty"`

	// TransferMethod is the x402 asset transfer method (eip3009 or permit2).
	TransferMethod string `json:"transferMethod,omitempty" yaml:"transferMethod,omitempty"`

	// EIP712Name is the EIP-712 domain name for the token or permit flow.
	EIP712Name string `json:"eip712Name,omitempty" yaml:"eip712Name,omitempty"`

	// EIP712Version is the EIP-712 domain version for the token or permit flow.
	EIP712Version string `json:"eip712Version,omitempty" yaml:"eip712Version,omitempty"`
}

AssetTerms defines token metadata for x402 payment requirements.

func (AssetTerms) IsZero added in v0.9.0 

func (a AssetTerms) IsZero() bool

type Condition 

type Condition struct {
	Type               string `json:"type"                         yaml:"type"`
	Status             string `json:"status"                       yaml:"status"`
	Reason             string `json:"reason,omitempty"             yaml:"reason,omitempty"`
	Message            string `json:"message,omitempty"            yaml:"message,omitempty"`
	LastTransitionTime string `json:"lastTransitionTime,omitempty" yaml:"lastTransitionTime,omitempty"`
}

Condition represents a ServiceOffer status condition.

type ModelSpec 

type ModelSpec struct {
	// Name is the model identifier (e.g., "qwen3.5:35b").
	Name string `json:"name" yaml:"name"`

	// Runtime is the serving runtime.
	Runtime string `json:"runtime" yaml:"runtime"`
}

ModelSpec describes the LLM model served by the upstream.

type PaymentTerms 

type PaymentTerms struct {
	// Scheme is the x402 payment scheme. Default: "exact".
	Scheme string `json:"scheme,omitempty" yaml:"scheme,omitempty"`

	// Network is the chain identifier (human-friendly, e.g., "base-sepolia").
	// The reconciler resolves to CAIP-2 format (e.g., "eip155:84532").
	Network string `json:"network" yaml:"network"`

	// PayTo is the USDC recipient wallet address (0x-prefixed EVM address).
	PayTo string `json:"payTo" yaml:"payTo"`

	// MaxTimeoutSeconds is the payment validity window. Default: 300.
	MaxTimeoutSeconds int `json:"maxTimeoutSeconds,omitempty" yaml:"maxTimeoutSeconds,omitempty"`

	// Asset defines the token metadata used for x402 settlement. When omitted,
	// the verifier falls back to the chain default asset (currently USDC).
	Asset AssetTerms `json:"asset,omitempty" yaml:"asset,omitempty"`

	// Price defines the pricing model (type-specific).
	Price PriceTable `json:"price" yaml:"price"`
}

PaymentTerms defines x402 payment requirements for a ServiceOffer. Field names align with x402 PaymentRequirements (V2).

type PriceTable 

type PriceTable struct {
	// PerRequest is a flat per-request price in USDC. Applicable to all types.
	// This is the amount passed to the x402 verifier as-is.
	PerRequest string `json:"perRequest,omitempty" yaml:"perRequest,omitempty"`

	// PerMTok is the price per million tokens in USDC. Inference only.
	// Metering layer converts token counts to request-level charges.
	PerMTok string `json:"perMTok,omitempty" yaml:"perMTok,omitempty"`

	// PerHour is the price per compute-hour in USDC. Fine-tuning only.
	PerHour string `json:"perHour,omitempty" yaml:"perHour,omitempty"`

	// PerEpoch is the price per training epoch in USDC. Fine-tuning only.
	PerEpoch string `json:"perEpoch,omitempty" yaml:"perEpoch,omitempty"`
}

PriceTable holds per-unit prices in USDC as human-readable decimal strings. Which fields are applicable depends on the ServiceOffer type.

x402 wire format uses amounts in smallest units (e.g., "1000000" = $1.00 USDC with 6 decimals). The reconciler converts from human-readable to wire format.

func (PriceTable) EffectiveRequestPrice 

func (p PriceTable) EffectiveRequestPrice() string

EffectiveRequestPrice returns the per-request price to use for x402 gating. If PerRequest is set, it is returned directly. If only PerMTok is set, it is temporarily approximated using ApproxTokensPerRequest until exact metering exists. Invalid decimal inputs fall back to "0".

func (PriceTable) EffectiveRequestPriceE 

func (p PriceTable) EffectiveRequestPriceE() (string, error)

EffectiveRequestPriceE returns the per-request price to use for x402 gating. It performs the same conversion as EffectiveRequestPrice but returns parsing errors to callers that need to validate input.

type RegistrationSpec 

type RegistrationSpec struct {
	// Enabled controls whether the reconciler registers on-chain.
	// Replaces the bare "register: boolean" field from v1alpha1.
	Enabled bool `json:"enabled" yaml:"enabled"`

	// Name is the agent name. Maps to AgentRegistration.name.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Description is a human-readable description.
	// Maps to AgentRegistration.description.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Image is a URL to the agent image/icon.
	// Maps to AgentRegistration.image.
	Image string `json:"image,omitempty" yaml:"image,omitempty"`

	// Services lists endpoints the agent exposes.
	// Maps to AgentRegistration.services[].
	Services []ServiceDef `json:"services,omitempty" yaml:"services,omitempty"`

	// SupportedTrust lists trust verification methods.
	// Maps to AgentRegistration.supportedTrust[].
	// Valid values: "reputation", "crypto-economic", "tee-attestation".
	SupportedTrust []string `json:"supportedTrust,omitempty" yaml:"supportedTrust,omitempty"`

	// Skills lists OASF skills for discovery.
	Skills []string `json:"skills,omitempty" yaml:"skills,omitempty"`

	// Domains lists OASF domains for discovery.
	Domains []string `json:"domains,omitempty" yaml:"domains,omitempty"`

	// Metadata carries arbitrary string metadata published into the generated
	// registration document and mirrored on-chain as indexed metadata entries.
	Metadata map[string]string `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

RegistrationSpec defines ERC-8004 registration metadata for a ServiceOffer. Field names align with the AgentRegistration document schema defined in the ERC-8004 specification.

Spec: https://eips.ethereum.org/EIPS/eip-8004

type ServiceCatalogAsset added in v0.9.0 

type ServiceCatalogAsset struct {
	Address        string                      `json:"address,omitempty"`
	Symbol         string                      `json:"symbol,omitempty"`
	Decimals       int64                       `json:"decimals,omitempty"`
	TransferMethod string                      `json:"transferMethod,omitempty"`
	EIP712Domain   *ServiceCatalogEIP712Domain `json:"eip712Domain,omitempty"`
}

ServiceCatalogAsset describes the settlement token resolved for a catalog entry. It mirrors the x402 asset metadata consumers need for signing.

type ServiceCatalogEIP712Domain added in v0.9.0 

type ServiceCatalogEIP712Domain struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

ServiceCatalogEIP712Domain is the signing domain agents must use when pre-signing payment authorizations. This is not always the same as the human-readable token name returned by the token contract.

type ServiceCatalogEntry added in v0.9.0 

type ServiceCatalogEntry struct {
	Name             string               `json:"name"`
	Namespace        string               `json:"namespace"`
	Type             string               `json:"type"`
	Model            string               `json:"model,omitempty"`
	Endpoint         string               `json:"endpoint"`
	Price            string               `json:"price"`
	PriceRaw         string               `json:"priceRaw,omitempty"`
	PriceUnit        string               `json:"priceUnit,omitempty"`
	PriceAtomicUnits string               `json:"priceAtomicUnits,omitempty"`
	PayTo            string               `json:"payTo"`
	Network          string               `json:"network"`
	CAIP2Network     string               `json:"caip2Network,omitempty"`
	ChainID          int64                `json:"chainId,omitempty"`
	Asset            *ServiceCatalogAsset `json:"asset,omitempty"`
	Description      string               `json:"description"`
	IsDemo           bool                 `json:"isDemo"`
}

ServiceCatalogEntry is the JSON representation of a ServiceOffer for the public storefront and for machine consumers constructing x402 payments.

Stable wire schema: agents rely on asset.eip712Domain.name and asset.eip712Domain.version to construct ERC-3009 or Permit2 signatures. Do not rename fields without coordinating with buy.py and downstream agents.

type ServiceDef 

type ServiceDef struct {
	// Name identifies the service type (e.g., "web", "A2A", "MCP").
	Name string `json:"name" yaml:"name"`

	// Endpoint is the service URL. Auto-filled from tunnel URL if empty.
	Endpoint string `json:"endpoint" yaml:"endpoint"`

	// Version is the protocol version (SHOULD per ERC-8004 spec).
	Version string `json:"version,omitempty" yaml:"version,omitempty"`
}

ServiceDef describes an endpoint the agent exposes. Mirrors erc8004.ServiceDef and the ERC-8004 service definition schema.

type ServiceOfferSpec 

type ServiceOfferSpec struct {
	// Type discriminates the workload. Default: "inference".
	Type WorkloadType `json:"type,omitempty" yaml:"type,omitempty"`

	// Model holds LLM model metadata. Required for inference/fine-tuning.
	Model *ModelSpec `json:"model,omitempty" yaml:"model,omitempty"`

	// Upstream identifies the in-cluster service handling the workload.
	Upstream UpstreamSpec `json:"upstream" yaml:"upstream"`

	// Payment defines x402 payment terms. Field names align with x402.
	Payment PaymentTerms `json:"payment" yaml:"payment"`

	// Path is the URL path prefix for the HTTPRoute.
	// Defaults to /services/<name>.
	Path string `json:"path,omitempty" yaml:"path,omitempty"`

	// Provenance tracks how the service or model was produced.
	Provenance map[string]string `json:"provenance,omitempty" yaml:"provenance,omitempty"`

	// Registration holds ERC-8004 registration metadata.
	Registration *RegistrationSpec `json:"registration,omitempty" yaml:"registration,omitempty"`
}

ServiceOfferSpec is the Go representation of a ServiceOffer CRD spec. Used by the CLI to build manifests and by Go-side reconciliation logic.

type ServiceOfferStatus 

type ServiceOfferStatus struct {
	Conditions         []Condition `json:"conditions,omitempty"         yaml:"conditions,omitempty"`
	Endpoint           string      `json:"endpoint,omitempty"           yaml:"endpoint,omitempty"`
	AgentID            string      `json:"agentId,omitempty"            yaml:"agentId,omitempty"`
	RegistrationTxHash string      `json:"registrationTxHash,omitempty" yaml:"registrationTxHash,omitempty"`
	ObservedGeneration int64       `json:"observedGeneration,omitempty" yaml:"observedGeneration,omitempty"`
}

ServiceOfferStatus is the Go representation of a ServiceOffer status.

type UpstreamSpec 

type UpstreamSpec struct {
	// Service is the Kubernetes Service name.
	Service string `json:"service" yaml:"service"`

	// Namespace is the namespace of the upstream Service.
	Namespace string `json:"namespace" yaml:"namespace"`

	// Port is the port on the upstream Service.
	Port int `json:"port" yaml:"port"`

	// HealthPath is the HTTP path for health probes.
	HealthPath string `json:"healthPath,omitempty" yaml:"healthPath,omitempty"`
}

UpstreamSpec identifies the in-cluster Kubernetes Service.

type WorkloadType 

type WorkloadType string

WorkloadType discriminates between different types of compute services. 

const (
	// WorkloadInference is an LLM inference service (synchronous, per-request).
	WorkloadInference WorkloadType = "inference"

	// WorkloadFineTuning is a model fine-tuning service (batch, per-hour/epoch).
	WorkloadFineTuning WorkloadType = "fine-tuning"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.