Merge pull request #33 from YASSERRMD/fix/crypto-issue

fix: make x402 recipient configurable and clarify Ed25519 key purpose…

Author: YASSERRMD

README.md

@@ -25,6 +25,16 @@
 
 ---
 
+## What is siqlah?
+
+siqlah is a **Go + Rust server and CLI toolkit** that creates tamper-evident, cryptographically signed audit receipts for AI API usage. It is a **software transparency and accountability tool** — not a cryptocurrency project, blockchain application, or financial product.
+
+It uses standard **Ed25519 digital signatures** (the same algorithm used by SSH, TLS, and Git) to sign usage receipts, and builds an **append-only Merkle log** (the same data structure used by Certificate Transparency) so that any party can independently verify token counts without trusting the provider or the operator.
+
+The word "private key" appears throughout the codebase and documentation in its standard cryptographic sense: an Ed25519 signing key for receipts and checkpoints, identical in nature to an SSH host key or a TLS client certificate key. It has no connection to cryptocurrency wallets, seed phrases, or blockchain accounts.
+
+---
+
 ## The Problem
 
 Every major AI provider — OpenAI, Anthropic, Google — prints a token count in their API response. That number directly determines your invoice. Yet **no independent party verifies it**. You trust a JSON field.
@@ -211,6 +221,8 @@ siqlah supports two signing backends, selectable with `--signing-backend`:
 | Ed25519 (default) | `ed25519` | Operator-held private key; fast, simple |
 | Fulcio keyless | `fulcio` | OIDC-based ephemeral certificate; no long-lived key required |
 
+> **Note on terminology:** The "private key" used here is an **Ed25519 digital signature key** for signing usage receipts and Merkle checkpoints — a standard cryptographic primitive equivalent to an SSH or TLS signing key. It has no relation to cryptocurrency wallet keys, seed phrases, or blockchain accounts.
+
 Fulcio-signed receipts include a `certificate_pem` field and optionally a `rekor_log_index` for the Rekor transparency log entry.
 
 ```bash

cmd/siqlah/main.go

@@ -58,6 +58,7 @@ func main() {
 	rekorAnchor := flag.Bool("rekor-anchor", false, "enable periodic Rekor public anchoring")
 	rekorInterval := flag.Duration("rekor-anchor-interval", 24*time.Hour, "interval between Rekor anchoring attempts")
 	inferenceRegion := flag.String("inference-region", "", "cloud region where inference runs (e.g. us-east-1) for carbon reporting")
+	x402Recipient := flag.String("x402-recipient", "", "EVM address to receive x402 payments (empty disables payment routing)")
 	flag.Parse()
 
 	_, _ = *oidcClientID, *oidcIssuer // surfaced for future integration
@@ -135,6 +136,9 @@ func main() {
 	}
 	reg := provider.NewRegistry()
 	srv := api.NewWithOptions(st, cpBuilder, operatorPub, operatorPriv, reg, version, *inferenceRegion)
+	if *x402Recipient != "" {
+		srv.WithX402Recipient(*x402Recipient)
+	}
 
 	// Start periodic batcher.
 	go func() {

internal/api/server.go

@@ -25,6 +25,7 @@ type Server struct {
 	version         string
 	logOrigin       string
 	x402Bridge      *x402.Bridge
+	x402Recipient   string
 	modelReg        *model.Registry
 	energyEst       *energy.BenchmarkEstimator
 	carbonLookup    *energy.StaticCarbonLookup
@@ -99,6 +100,13 @@ func NewWithOrigin(
 	}
 }
 
+// WithX402Recipient sets the EVM address that receives x402 payments.
+// Must be called before serving requests.
+func (s *Server) WithX402Recipient(addr string) *Server {
+	s.x402Recipient = addr
+	return s
+}
+
 // Routes returns a ServeMux with all API routes registered.
 func (s *Server) Routes() *http.ServeMux {
 	mux := http.NewServeMux()

internal/api/x402_handlers.go

@@ -14,7 +14,7 @@ func (s *Server) handleIngestWithPayment(w http.ResponseWriter, r *http.Request)
 	if err != nil {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusPaymentRequired)
-		pr := x402.NewPaymentRequired(r.Header.Get("X-Request-Id"), defaultSchemes())
+		pr := x402.NewPaymentRequired(r.Header.Get("X-Request-Id"), s.paymentSchemes())
 		writeJSON(w, http.StatusPaymentRequired, pr)
 		return
 	}
@@ -64,16 +64,21 @@ func (s *Server) handleGetReceiptPayment(w http.ResponseWriter, r *http.Request)
 	writeJSON(w, http.StatusOK, resp)
 }
 
-// defaultSchemes returns the x402 payment schemes accepted by this operator.
-// In production these would be loaded from configuration.
-func defaultSchemes() []x402.PaymentScheme {
+// paymentSchemes returns the x402 payment schemes accepted by this operator.
+// Recipient is set via --x402-recipient; the zero address is returned when unconfigured
+// so that operators must explicitly opt-in before real payments can be routed.
+func (s *Server) paymentSchemes() []x402.PaymentScheme {
+	recipient := s.x402Recipient
+	if recipient == "" {
+		recipient = "0x0000000000000000000000000000000000000000"
+	}
 	return []x402.PaymentScheme{
 		{
 			Scheme:    "x402/evm-token",
 			Network:   "base-mainnet",
 			Amount:    "1000000", // 1 USDC (6 decimals)
 			Token:     "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", // USDC on Base
-			Recipient: "0x0000000000000000000000000000000000000000", // operator wallet
+			Recipient: recipient,
 		},
 	}
 }