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

Author: phdargen

examples/go/clients/batch-settlement/README.md

@@ -1,6 +1,6 @@
 # Batch-Settlement Client (Go)
 
-Go port of [`examples/typescript/clients/batch-settlement`](../../../typescript/clients/batch-settlement). Sequential batch-settlement payment client. Opens a payment channel on the first request (deposit) and pays subsequent requests with off-chain vouchers that update the cumulative claimable amount.
+Sequential batch-settlement payment client. Opens a payment channel on the first request (deposit) and pays subsequent requests with off-chain vouchers that update the cumulative claimable amount.
 
 ## Run
 
@@ -11,7 +11,7 @@ cp .env-example .env
 go run .
 ```
 
-The companion server is in `examples/go/servers/batch-settlement` and the facilitator is in `examples/go/facilitator/batch-settlement`. The Go and TS clients share the same env keys, default route (`/weather`), and behavior — point the same `.env` at either binary.
+The companion server is in `examples/go/servers/batch-settlement` and the facilitator is in `examples/go/facilitator/batch-settlement`.
 
 ## Voucher Signer Delegation
 

examples/go/clients/batch-settlement/main.go

@@ -65,7 +65,7 @@ func main() {
 		Salt:              channelSalt,
 	}
 
-	// Optional dedicated voucher-signing key (matches TS EVM_VOUCHER_SIGNER_PRIVATE_KEY).
+	// Optional dedicated voucher-signing key.
 	if voucherKey := os.Getenv("EVM_VOUCHER_SIGNER_PRIVATE_KEY"); voucherKey != "" {
 		voucherSigner, err := evmsigners.NewClientSignerFromPrivateKey(voucherKey)
 		if err != nil {
@@ -171,7 +171,7 @@ func readJSON(resp *http.Response) (interface{}, error) {
 	return out, nil
 }
 
-func extractSettleResponse(resp *http.Response) (*map[string]interface{}, error) {
+func extractSettleResponse(resp *http.Response) (*x402.SettleResponse, error) {
 	header := resp.Header.Get("PAYMENT-RESPONSE")
 	if header == "" {
 		header = resp.Header.Get("X-PAYMENT-RESPONSE")
@@ -183,7 +183,7 @@ func extractSettleResponse(resp *http.Response) (*map[string]interface{}, error)
 	if err != nil {
 		return nil, err
 	}
-	var out map[string]interface{}
+	var out x402.SettleResponse
 	if err := json.Unmarshal(decoded, &out); err != nil {
 		return nil, err
 	}

examples/go/facilitator/batch-settlement/.env-example

@@ -4,5 +4,5 @@ EVM_RPC_URL=https://sepolia.base.org
 # Optional dedicated authorizer key (defaults to EVM_PRIVATE_KEY)
 EVM_RECEIVER_AUTHORIZER_PRIVATE_KEY=
 
-# Optional (default 4022). Same as examples/typescript/facilitator/batch-settlement.
+# Optional listen port (default 4022).
 PORT=

examples/go/facilitator/batch-settlement/README.md

@@ -23,8 +23,7 @@ cp .env-example .env
 go run .
 ```
 
-Listens on `http://localhost:4022` by default (`PORT` overrides; same as the
-TypeScript facilitator example).
+Listens on `http://localhost:4022` by default (`PORT` overrides).
 
 ## Environment
 

examples/go/servers/batch-settlement/README.md

@@ -1,6 +1,6 @@
 # Batch-Settlement Server (Go)
 
-Go port of [`examples/typescript/servers/batch-settlement`](../../../typescript/servers/batch-settlement). Demo resource server using the batch-settlement scheme: a client opens a payment channel with a single deposit; subsequent paid requests update an off-chain voucher. The `ChannelManager` periodically claims and settles onchain.
+Demo resource server using the batch-settlement scheme: a client opens a payment channel with a single deposit; subsequent paid requests update an off-chain voucher. The `ChannelManager` periodically claims and settles onchain.
 
 The route demonstrates **dynamic pricing**: the client authorizes up to `$0.01` per request, and the handler bills a random fraction of that via `Settlement-Overrides`.
 
@@ -15,18 +15,6 @@ go run .
 
 The server listens on `http://localhost:4021` and exposes `GET /weather`. Pair with `examples/go/clients/batch-settlement` and `examples/go/facilitator/batch-settlement`.
 
-### Cross-SDK local testing
-
-The Go and TS servers share the same `.env-example` keys, route (`GET /weather`), response shape (`{report: {weather, temperature}}`), and channel-manager cadences, so you can swap one for the other without changing client config:
-
-```bash
-# Go server
-EVM_ADDRESS=0x... FACILITATOR_URL=http://localhost:4022 go run .
-
-# TS server (same .env)
-cd examples/typescript/servers/batch-settlement && pnpm dev
-```
-
 ## Environment
 
 | Variable                              | Required | Description |
@@ -39,7 +27,7 @@ cd examples/typescript/servers/batch-settlement && pnpm dev
 
 ## Auto-settlement
 
-The example wires up a `ChannelManager` with the same triggers as the TS demo:
+The example wires up a `ChannelManager` with simple local-demo triggers:
 
 - **Claim** every 60 s.
 - **Settle** every 120 s (sweeps claimed funds to `payTo`).

examples/go/servers/batch-settlement/go.mod

@@ -35,6 +35,8 @@ require (
 	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
 	github.com/xeipuuv/gojsonschema v1.2.0 // indirect
 	golang.org/x/crypto v0.46.0 // indirect
+	golang.org/x/net v0.48.0 // indirect
 	golang.org/x/sync v0.19.0 // indirect
 	golang.org/x/sys v0.39.0 // indirect
+	golang.org/x/text v0.32.0 // indirect
 )

examples/go/servers/batch-settlement/go.sum

@@ -178,6 +178,8 @@ golang.org/x/crypto v0.46.0 h1:cKRW/pmt1pKAfetfu+RCEvjvZkA9RimPbh7bhFjGVBU=
 golang.org/x/crypto v0.46.0/go.mod h1:Evb/oLKmMraqjZ2iQTwDwvCtJkczlDuTmdJXoZVzqU0=
 golang.org/x/exp v0.0.0-20230626212559-97b1e661b5df h1:UA2aFVmmsIlefxMk29Dp2juaUSth8Pyn3Tq5Y5mJGME=
 golang.org/x/exp v0.0.0-20230626212559-97b1e661b5df/go.mod h1:FXUEEKJgO7OQYeo8N01OfiKP8RXMtf6e8aTskBGqWdc=
+golang.org/x/net v0.48.0 h1:zyQRTTrjc33Lhh0fBgT/H3oZq9WuvRR5gPC70xpDiQU=
+golang.org/x/net v0.48.0/go.mod h1:+ndRgGjkh8FGtu1w1FGbEC31if4VrNVMuKTgcAAnQRY=
 golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
 golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=

examples/go/servers/batch-settlement/main.go

@@ -21,7 +21,6 @@ import (
 	batchedserver "github.com/x402-foundation/x402/go/mechanisms/evm/batch-settlement/server"
 )
 
-// Mirrors examples/typescript/servers/batch-settlement/index.ts.
 const (
 	defaultPort = "4021"
 	network     = x402.Network("eip155:84532")
@@ -43,7 +42,7 @@ func main() {
 		os.Exit(1)
 	}
 
-	// TS code default: 86400 (1 day). Falls back to that when env unset.
+	// Default channel withdraw delay is 1 day when the env var is unset.
 	withdrawDelay := 86400
 	if v := os.Getenv("DEFERRED_WITHDRAW_DELAY_SECONDS"); v != "" {
 		if n, err := strconv.Atoi(v); err == nil {
@@ -83,7 +82,7 @@ func main() {
 		SettleIntervalSecs: 120,
 		RefundIntervalSecs: 180,
 		MaxClaimsPerBatch:  100,
-		// Refund channels after 3 minutes of inactivity (mirrors TS demo).
+		// Refund channels after 3 minutes of inactivity.
 		SelectRefundChannels: func(channels []*batchedserver.ChannelSession, ctx batchedserver.AutoSettlementContext) ([]*batchedserver.ChannelSession, error) {
 			out := make([]*batchedserver.ChannelSession, 0, len(channels))
 			for _, c := range channels {
@@ -114,7 +113,7 @@ func main() {
 		},
 	})
 
-	// SIGINT-only graceful shutdown (no SIGTERM), mirroring TS.
+	// Flush pending channel work during interactive shutdown.
 	sigCh := make(chan os.Signal, 1)
 	signal.Notify(sigCh, syscall.SIGINT)
 
@@ -135,8 +134,7 @@ func main() {
 
 	mux := http.NewServeMux()
 	mux.HandleFunc("GET /weather", func(w http.ResponseWriter, r *http.Request) {
-		// Bill a random fraction of maxPrice (1–100%) to demonstrate
-		// usage-based pricing. Mirrors TS demo verbatim.
+		// Bill a random fraction of maxPrice (1-100%) to demonstrate usage-based pricing.
 		chargedPercent := 1 + rand.Intn(100)
 		nethttpmw.SetSettlementOverrides(w, &x402.SettlementOverrides{
 			Amount: fmt.Sprintf("%d%%", chargedPercent),

go/SERVER.md

@@ -152,7 +152,7 @@ settleResult := httpServer.ProcessSettlement(ctx, payload, requirements, nil, &x
     Request:         &reqCtx,
     ResponseBody:    responseBody,
     ResponseHeaders: responseHeaders,
-})
+}, nil)
 ```
 
 ### 4. Facilitator Client

go/http/client.go

@@ -529,13 +529,50 @@ func decodePaymentRequiredHeader(header string) (x402.PaymentRequired, error) {
 
 // encodePaymentResponseHeader encodes a settlement response as base64
 func encodePaymentResponseHeader(response x402.SettleResponse) (string, error) {
+	response = withTypedChannelStateExtra(response)
 	data, err := json.Marshal(response)
 	if err != nil {
 		return "", fmt.Errorf("failed to marshal settle response: %w", err)
 	}
 	return base64.StdEncoding.EncodeToString(data), nil
 }
 
+type paymentResponseChannelStateExtra struct {
+	ChannelId               string      `json:"channelId,omitempty"`
+	Balance                 string      `json:"balance,omitempty"`
+	TotalClaimed            string      `json:"totalClaimed,omitempty"`
+	WithdrawRequestedAt     interface{} `json:"withdrawRequestedAt,omitempty"`
+	RefundNonce             string      `json:"refundNonce,omitempty"`
+	ChargedCumulativeAmount string      `json:"chargedCumulativeAmount,omitempty"`
+}
+
+func withTypedChannelStateExtra(response x402.SettleResponse) x402.SettleResponse {
+	raw, ok := response.Extra["channelState"].(map[string]interface{})
+	if !ok {
+		return response
+	}
+
+	extra := make(map[string]interface{}, len(response.Extra))
+	for key, value := range response.Extra {
+		extra[key] = value
+	}
+	extra["channelState"] = paymentResponseChannelStateExtra{
+		ChannelId:               stringField(raw, "channelId"),
+		Balance:                 stringField(raw, "balance"),
+		TotalClaimed:            stringField(raw, "totalClaimed"),
+		WithdrawRequestedAt:     raw["withdrawRequestedAt"],
+		RefundNonce:             stringField(raw, "refundNonce"),
+		ChargedCumulativeAmount: stringField(raw, "chargedCumulativeAmount"),
+	}
+	response.Extra = extra
+	return response
+}
+
+func stringField(data map[string]interface{}, key string) string {
+	value, _ := data[key].(string)
+	return value
+}
+
 // decodePaymentResponseHeader decodes a base64 payment response header
 func decodePaymentResponseHeader(header string) (*x402.SettleResponse, error) {
 	data, err := base64.StdEncoding.DecodeString(header)