feat: add exact OBOL Permit2 buy-side path

.agents/skills/obol-stack-dev/SKILL.md

@@ -209,6 +209,35 @@ obol kubectl exec -i -n openclaw-<id> deploy/openclaw -c openclaw -- python3 - <
 - Delegate or accept broad "review the architecture" findings without converting them into concrete file-level checks and reproducible tests.
 - Push `codex/`-prefixed branches to GitHub from this repository.
 
+## Adding a New Payment Token
+
+The `--token` flag (`obol sell inference`, `obol sell http`) selects the payment token from a whitelist registry in `internal/x402/tokens.go`. To add support for a new ERC-20 token:
+
+1. **Add registry entry** in `internal/x402/tokens.go` — one entry per (token, chain) pair:
+   ```go
+   "WETH": {
+       "base": {Address: "0x4200000000000000000000000000000000000006", Symbol: "WETH", Decimals: 18, TransferMethod: "permit2", EIP712Name: "Wrapped Ether", EIP712Version: "1"},
+   },
+   ```
+
+2. **Determine the transfer method**:
+   - `eip3009` — token natively implements `transferWithAuthorization` (USDC, EURC)
+   - `permit2` — uses Uniswap Permit2 (`0x000000000022D473030F116dDEE9F6B43aC78BA3`) for authorization; works with any ERC-20
+
+3. **Per-chain considerations**:
+   - Verify the token contract is deployed on each target chain (the buy-side validates this via `eth_getCode` before signing)
+   - Verify the EIP-712 domain name/version match the on-chain contract — wrong values produce invalid signatures
+   - The x402 facilitator must have the target chain configured (check `obol-infrastructure/helm-charts/x402-facilitator/templates/configmap.yaml` for `eip155:<chainId>` entries)
+   - The x402 ExactPermit2Proxy (`0x402085c248EeA27D92E8b30b2C58ed07f9E20001`) must be deployed on the chain for Permit2 tokens
+
+4. **Add tests** in `internal/x402/tokens_test.go`:
+   - Verify `ResolveToken("WETH", "base")` returns the correct entry
+   - Verify `ResolveToken("WETH", "ethereum")` returns false if not registered there
+
+5. **No CLI changes needed** — `--token WETH` resolves automatically from the registry.
+
+6. **buy.py handles both paths** — it reads `extra.assetTransferMethod` from the 402 response and auto-selects the ERC-3009 or Permit2 signing flow. Contract existence is validated before signing.
+
 ## Sell-Side Monetize Lifecycle
 
 ### Architecture

CLAUDE.md

@@ -76,13 +76,13 @@ Components: eRPC (`erpc` ns), Frontend (`obol-frontend` ns), Cloudflared (`traef
 
 ## Monetize Subsystem
 
-Payment-gated access to cluster services via x402 (HTTP 402 micropayments, USDC on Base/Base Sepolia, Traefik ForwardAuth).
+Payment-gated access to cluster services via x402 (HTTP 402 micropayments, Traefik ForwardAuth). Supports USDC (EIP-3009) and OBOL (Permit2) via `--token [USDC|OBOL]` flag; default is USDC on Base Mainnet. Token registry in `internal/x402/tokens.go`.
 
 **Sell-side flow**: `obol sell http` → creates ServiceOffer CR → serviceoffer-controller reconciles ModelReady → UpstreamHealthy → PaymentGateReady (x402 Middleware) → RoutePublished (HTTPRoute) → Registered (RegistrationRequest + optional ERC-8004 side effects) → Ready. Traefik routes `/services/<name>/*` through ForwardAuth to upstream.
 
-**Buy-side flow**: `buy.py probe` sees 402 pricing → `buy.py buy` pre-signs ERC-3009 auths into ConfigMaps → LiteLLM serves static `paid/<remote-model>` aliases through the in-pod `x402-buyer` sidecar → each paid request spends one auth and forwards to the remote seller.
+**Buy-side flow**: `buy.py probe` sees 402 pricing → `buy.py buy` validates token contract exists on-chain → pre-signs payment auths (ERC-3009 for USDC, Permit2 for OBOL) into ConfigMaps → LiteLLM serves static `paid/<remote-model>` aliases through the in-pod `x402-buyer` sidecar → each paid request spends one auth and forwards to the remote seller.
 
-**CLI**: `obol sell pricing --wallet --chain`, `obol sell inference <name> --model --price|--per-mtok`, `obol sell http <name> --wallet --chain --price|--per-request|--per-mtok --upstream --port --namespace --health-path`, `obol sell list|status|stop|delete`, `obol sell register --name --private-key-file`.
+**CLI**: `obol sell pricing --wallet --chain`, `obol sell inference <name> --model --price|--per-mtok [--token USDC|OBOL]`, `obol sell http <name> --wallet --chain --price|--per-request|--per-mtok --upstream --port --namespace --health-path [--token USDC|OBOL]`, `obol sell list|status|stop|delete`, `obol sell register --name --private-key-file`.
 
 **ServiceOffer CRD** (`obol.org`): Source of truth for monetized service intent. Spec fields — `type` (inference|fine-tuning|http), `model{name,runtime}`, `upstream{service,namespace,port,healthPath}`, `payment{scheme,network,payTo,price{perRequest,perMTok,perHour}}`, `path`, `registration{enabled,name,description,image,skills,domains,supportedTrust}`.
 

cmd/obol/sell.go

@@ -101,6 +101,11 @@ Examples:
 				Usage: "Payment chain (base, base-sepolia, ethereum)",
 				Value: "base",
 			},
+			&cli.StringFlag{
+				Name:  "token",
+				Usage: "Payment token (USDC, OBOL)",
+				Value: "USDC",
+			},
 			&cli.StringFlag{
 				Name:  "facilitator",
 				Usage: "x402 facilitator URL",
@@ -258,7 +263,13 @@ Examples:
 				}
 			}
 
-			chain, err := x402verifier.ResolveChainInfo(cmd.String("chain"))
+			chainName := cmd.String("chain")
+			assetTerms, err := resolveAssetTerms(cmd, &chainName)
+			if err != nil {
+				return err
+			}
+
+			chain, err := x402verifier.ResolveChainInfo(chainName)
 			if err != nil {
 				return err
 			}
@@ -281,7 +292,7 @@ Examples:
 				WalletAddress:   wallet,
 				PricePerRequest: perRequest,
 				PricePerMTok:    priceTable.PerMTok,
-				Chain:           cmd.String("chain"),
+				Chain:           chainName,
 				FacilitatorURL:  cmd.String("facilitator"),
 				VMMode:          cmd.Bool("vm"),
 				VMImage:         cmd.String("vm-image"),
@@ -347,7 +358,7 @@ Examples:
 					d.NoPaymentGate = false
 				} else {
 					// Create a ServiceOffer CR pointing at the host service.
-					soSpec, err := buildInferenceServiceOfferSpec(d, priceTable, svcNs, port)
+					soSpec, err := buildInferenceServiceOfferSpec(d, priceTable, svcNs, port, assetTerms)
 					if err != nil {
 						return err
 					}
@@ -412,6 +423,11 @@ Example:
 				Usage: "Payment chain (base, base-sepolia, ethereum)",
 				Value: "base",
 			},
+			&cli.StringFlag{
+				Name:  "token",
+				Usage: "Payment token (USDC, OBOL)",
+				Value: "USDC",
+			},
 			&cli.StringFlag{
 				Name:  "price",
 				Usage: "Per-request price in USDC (e.g. 0.001)",
@@ -580,10 +596,10 @@ Example:
 			ns := cmd.String("namespace")
 
 			if cmd.String("upstream") == "" {
-				return fmt.Errorf("upstream service name required: use --upstream <service-name>\n\n  Example: obol sell http %s --upstream my-svc --port 8080 --wallet 0x... --chain base --price 0.001", name)
+				return fmt.Errorf("upstream service name required: use --upstream <service-name>\n\n  Example: obol sell http %s --upstream my-svc --port 8080 --wallet 0x... --chain base-sepolia --price 0.001", name)
 			}
 			if cmd.Int("port") == 0 {
-				return fmt.Errorf("upstream port required: use --port <port-number>\n\n  Example: obol sell http %s --upstream my-svc --port 8080 --wallet 0x... --chain base --price 0.001", name)
+				return fmt.Errorf("upstream port required: use --port <port-number>\n\n  Example: obol sell http %s --upstream my-svc --port 8080 --wallet 0x... --chain base-sepolia --price 0.001", name)
 			}
 
 			priceTable, err := resolvePriceTable(cmd, true)
@@ -602,6 +618,12 @@ Example:
 				price["perHour"] = priceTable.PerHour
 			}
 
+			chainName := cmd.String("chain")
+			assetTerms, err := resolveAssetTerms(cmd, &chainName)
+			if err != nil {
+				return err
+			}
+
 			spec := map[string]any{
 				"type": "http",
 				"upstream": map[string]any{
@@ -612,12 +634,15 @@ Example:
 				},
 				"payment": map[string]any{
 					"scheme":            "exact",
-					"network":           cmd.String("chain"),
+					"network":           chainName,
 					"payTo":             wallet,
 					"maxTimeoutSeconds": cmd.Int("max-timeout"),
 					"price":             price,
 				},
 			}
+			if !assetTerms.IsZero() {
+				spec["payment"].(map[string]any)["asset"] = assetTerms
+			}
 
 			if path := cmd.String("path"); path != "" {
 				spec["path"] = path
@@ -701,7 +726,7 @@ Example:
 			}
 			u.Successf("ServiceOffer %s/%s %s (type: http)", ns, name, action)
 			if priceTable.PerMTok != "" {
-				u.Infof("Requests will be charged at %s", formatPriceTableSummary(priceTable))
+				u.Infof("Requests will be charged at %s", formatPriceTableSummary(priceTable, assetTerms.Symbol))
 			}
 			u.Infof("The agent will reconcile: health-check → payment gate → route")
 			u.Infof("Check status: obol sell status %s -n %s", name, ns)
@@ -840,7 +865,7 @@ func sellStatusCommand(cfg *config.Config) *cli.Command {
 				u.Printf("Local Inference Gateways:")
 				for _, d := range deployments {
 					u.Printf("  %-20s %s → %s  %s  chain=%s",
-						d.Name, d.ListenAddr, d.UpstreamURL, formatInferencePriceSummary(d), d.Chain)
+						d.Name, d.ListenAddr, d.UpstreamURL, formatInferencePriceSummary(d, ""), d.Chain)
 				}
 			}
 
@@ -926,7 +951,7 @@ func sellStatusGlobalJSON(cfg *config.Config, u *ui.UI) error {
 			Name:        d.Name,
 			ListenAddr:  d.ListenAddr,
 			UpstreamURL: d.UpstreamURL,
-			Price:       formatInferencePriceSummary(d),
+			Price:       formatInferencePriceSummary(d, ""),
 			Chain:       d.Chain,
 		})
 	}
@@ -1276,7 +1301,7 @@ registration on networks that offer it (e.g. ethereum mainnet).
 
 Examples:
   obol sell register                                    # interactive, defaults to base
-  obol sell register --chain base-sepolia               # register on base-sepolia
+  obol sell register --chain base                       # register on base
   obol sell register --chain mainnet,base               # register on multiple chains
   obol sell register --chain mainnet --sponsored        # zero-gas on ethereum mainnet`,
 		Flags: []cli.Flag{
@@ -1760,7 +1785,7 @@ func sellInfoCommand(cfg *config.Config) *cli.Command {
 			u.Printf("Listen:       %s", d.ListenAddr)
 			u.Printf("Upstream:     %s", d.UpstreamURL)
 			u.Printf("Wallet:       %s", d.WalletAddress)
-			u.Printf("Price:        %s", formatInferencePriceSummary(d))
+			u.Printf("Price:        %s", formatInferencePriceSummary(d, ""))
 			u.Printf("Chain:        %s", d.Chain)
 			u.Printf("Facilitator:  %s", d.FacilitatorURL)
 			u.Printf("Created:      %s", d.CreatedAt)
@@ -1874,52 +1899,122 @@ func resolvePriceTable(cmd *cli.Command, allowPerHour bool) (schemas.PriceTable,
 		if allowPerHour {
 			return schemas.PriceTable{}, errors.New("price required: use --price, --per-request, --per-mtok, or --per-hour")
 		}
-
 		return schemas.PriceTable{}, errors.New("price required: use --price, --per-request, or --per-mtok")
 	}
 }
 
-func formatPriceTableSummary(priceTable schemas.PriceTable) string {
+func resolveAssetTerms(cmd *cli.Command, chainName *string) (schemas.AssetTerms, error) {
+	tokenName := strings.ToUpper(strings.TrimSpace(cmd.String("token")))
+
+	// USDC = chain default — no asset override needed.
+	if tokenName == "USDC" {
+		return schemas.AssetTerms{}, nil
+	}
+
+	if chainName == nil {
+		return schemas.AssetTerms{}, fmt.Errorf("internal error: chain name pointer is nil")
+	}
+
+	// For non-default tokens, default to ethereum when --chain is not explicit.
+	if !cmd.IsSet("chain") {
+		if envChain := strings.TrimSpace(os.Getenv("OBOL_TOKEN_CHAIN")); envChain != "" {
+			*chainName = envChain
+		} else {
+			*chainName = "ethereum"
+		}
+	}
+
+	// Env var overrides bypass the registry — used for test deployments on
+	// chains where the token isn't officially deployed (e.g., fork-local OBOL
+	// on Base Sepolia via OBOL_TOKEN_ADDRESS).
+	if addr := strings.TrimSpace(os.Getenv("OBOL_TOKEN_ADDRESS")); addr != "" {
+		return schemas.AssetTerms{
+			Address:        addr,
+			Symbol:         envOrDefault("OBOL_TOKEN_SYMBOL", "OBOL"),
+			Decimals:       18,
+			TransferMethod: schemas.AssetTransferMethodPermit2,
+			EIP712Name:     envOrDefault("OBOL_TOKEN_NAME", "Obol Network"),
+			EIP712Version:  envOrDefault("OBOL_TOKEN_VERSION", "1"),
+		}, nil
+	}
+
+	// Registry lookup.
+	entry, ok := x402verifier.ResolveToken(tokenName, *chainName)
+	if !ok {
+		return schemas.AssetTerms{}, fmt.Errorf(
+			"--token %s is not available on chain %s (supported tokens: %s)",
+			tokenName, *chainName, strings.Join(x402verifier.SupportedTokens(), ", "),
+		)
+	}
+
+	return schemas.AssetTerms{
+		Address:        entry.Address,
+		Symbol:         entry.Symbol,
+		Decimals:       entry.Decimals,
+		TransferMethod: entry.TransferMethod,
+		EIP712Name:     entry.EIP712Name,
+		EIP712Version:  entry.EIP712Version,
+	}, nil
+}
+
+func envOrDefault(key, fallback string) string {
+	if v := strings.TrimSpace(os.Getenv(key)); v != "" {
+		return v
+	}
+	return fallback
+}
+
+func formatPriceTableSummary(priceTable schemas.PriceTable, symbol string) string {
+	if symbol == "" {
+		symbol = "USDC"
+	}
 	switch {
 	case priceTable.PerRequest != "":
-		return priceTable.PerRequest + " USDC/request"
+		return fmt.Sprintf("%s %s/request", priceTable.PerRequest, symbol)
 	case priceTable.PerMTok != "":
-		return fmt.Sprintf("%s USDC/request (approx from %s USDC/MTok @ %d tok/request)",
-			priceTable.EffectiveRequestPrice(),
-			priceTable.PerMTok,
+		return fmt.Sprintf("%s %s/request (approx from %s %s/MTok @ %d tok/request)",
+			priceTable.EffectiveRequestPrice(), symbol,
+			priceTable.PerMTok, symbol,
 			schemas.ApproxTokensPerRequest,
 		)
 	case priceTable.PerHour != "":
-		return fmt.Sprintf("%s USDC/request (approx from %s USDC/hour @ %d min/request)",
-			priceTable.EffectiveRequestPrice(),
-			priceTable.PerHour,
+		return fmt.Sprintf("%s %s/request (approx from %s %s/hour @ %d min/request)",
+			priceTable.EffectiveRequestPrice(), symbol,
+			priceTable.PerHour, symbol,
 			schemas.ApproxMinutesPerRequest,
 		)
 	default:
-		return "0 USDC/request"
+		return fmt.Sprintf("0 %s/request", symbol)
 	}
 }
 
 func formatRoutePriceSummary(route x402verifier.RouteRule) string {
+	symbol := route.AssetSymbol
+	if symbol == "" {
+		symbol = "USDC"
+	}
 	if route.PriceModel == "perMTok" && route.PerMTok != "" && route.ApproxTokensPerRequest > 0 {
-		return fmt.Sprintf("%s USDC/request (approx from %s USDC/MTok @ %d tok/request)",
-			route.Price, route.PerMTok, route.ApproxTokensPerRequest)
+		return fmt.Sprintf("%s %s/request (approx from %s %s/MTok @ %d tok/request)",
+			route.Price, symbol, route.PerMTok, symbol, route.ApproxTokensPerRequest)
 	}
 
 	if route.Price != "" {
-		return route.Price + " USDC/request"
+		return fmt.Sprintf("%s %s/request", route.Price, symbol)
 	}
 
-	return "0 USDC/request"
+	return fmt.Sprintf("0 %s/request", symbol)
 }
 
-func formatInferencePriceSummary(d *inference.Deployment) string {
+func formatInferencePriceSummary(d *inference.Deployment, symbol string) string {
+	if symbol == "" {
+		symbol = "USDC"
+	}
 	if d.PricePerMTok != "" && d.ApproxTokensPerRequest > 0 {
-		return fmt.Sprintf("%s USDC/request (approx from %s USDC/MTok @ %d tok/request)",
-			d.PricePerRequest, d.PricePerMTok, d.ApproxTokensPerRequest)
+		return fmt.Sprintf("%s %s/request (approx from %s %s/MTok @ %d tok/request)",
+			d.PricePerRequest, symbol, d.PricePerMTok, symbol, d.ApproxTokensPerRequest)
 	}
 
-	return d.PricePerRequest + " USDC/request"
+	return fmt.Sprintf("%s %s/request", d.PricePerRequest, symbol)
 }
 
 // loadProvenance reads a provenance JSON file and returns the parsed struct.
@@ -2036,7 +2131,7 @@ func resolveHostIP(cfg *config.Config) (string, error) {
 
 // buildInferenceServiceOfferSpec builds a ServiceOffer spec for a host-side
 // inference gateway routed through the cluster's x402 flow.
-func buildInferenceServiceOfferSpec(d *inference.Deployment, pt schemas.PriceTable, ns, port string) (map[string]any, error) {
+func buildInferenceServiceOfferSpec(d *inference.Deployment, pt schemas.PriceTable, ns, port string, asset schemas.AssetTerms) (map[string]any, error) {
 	portNum, err := strconv.Atoi(port)
 	if err != nil || portNum < 1 || portNum > 65535 {
 		return nil, fmt.Errorf("invalid port %q: must be a number between 1 and 65535", port)
@@ -2057,6 +2152,9 @@ func buildInferenceServiceOfferSpec(d *inference.Deployment, pt schemas.PriceTab
 		},
 		"path": "/services/" + d.Name,
 	}
+	if !asset.IsZero() {
+		spec["payment"].(map[string]any)["asset"] = asset
+	}
 
 	price := spec["payment"].(map[string]any)["price"].(map[string]any)
 	if pt.PerMTok != "" {

cmd/obol/sell_test.go

@@ -177,14 +177,15 @@ func TestSellInference_Flags(t *testing.T) {
 	flags := flagMap(inf)
 
 	requireFlags(t, flags,
-		"model", "wallet", "price", "per-request", "per-mtok", "chain", "facilitator",
+		"model", "wallet", "price", "per-request", "per-mtok", "chain", "token", "facilitator",
 		"listen", "upstream", "enclave-tag",
 		"vm", "vm-image", "vm-cpus", "vm-memory", "vm-host-port",
 		"tee", "model-hash",
 	)
 
 	assertStringDefault(t, flags, "price", "0.001")
 	assertStringDefault(t, flags, "chain", "base")
+	assertStringDefault(t, flags, "token", "USDC")
 	assertStringDefault(t, flags, "listen", ":8402")
 	assertStringDefault(t, flags, "upstream", "http://localhost:11434")
 	assertStringDefault(t, flags, "facilitator", "https://x402.gcp.obol.tech")
@@ -201,13 +202,14 @@ func TestSellHTTP_Flags(t *testing.T) {
 	flags := flagMap(http)
 
 	requireFlags(t, flags,
-		"wallet", "chain", "price", "per-request", "per-mtok", "per-hour",
+		"wallet", "chain", "token", "price", "per-request", "per-mtok", "per-hour",
 		"namespace", "upstream", "port", "health-path", "path",
 		"max-timeout",
 		"register", "register-name", "register-description", "register-image",
 	)
 
 	assertStringDefault(t, flags, "chain", "base")
+	assertStringDefault(t, flags, "token", "USDC")
 	assertStringDefault(t, flags, "namespace", "default")
 	assertStringDefault(t, flags, "health-path", "/health")
 	assertIntDefault(t, flags, "port", 8080)

contracts/fork-obol/foundry.toml

@@ -0,0 +1,5 @@
+[profile.default]
+src = "src"
+out = "out"
+libs = []
+solc_version = "0.8.24"