feat: hosted payment mode — pay for storage via gateway credits

.antd-version

@@ -1 +1 @@
-v0.12.0
+v0.13.0

Dockerfile

@@ -7,7 +7,7 @@
 # platform); keep ANTD_IMAGE in lockstep with .antd-version. release.yml
 # passes the pinned tag explicitly; this default keeps `docker compose
 # up --build` and bare `docker build` working out of the box.
-ARG ANTD_IMAGE=ghcr.io/withautonomi/antd:v0.12.0
+ARG ANTD_IMAGE=ghcr.io/withautonomi/antd:v0.13.0
 FROM ${ANTD_IMAGE} AS antd
 
 # Build frontend on the native arch — JS output is arch-independent.

README.md

@@ -75,7 +75,14 @@ data_dir = "./data"
 
 # Required
 jwt_secret = "your-secret-key-at-least-32-chars"
-wallet_encryption_key = "64-hex-char-key-for-aes-256-gcm"
+wallet_encryption_key = "64-hex-char-key-for-aes-256-gcm"   # local payment backend only; optional with payment_backend = "hosted"
+
+# Payments: "local" (default) signs uploads with a wallet you add in the admin UI;
+# "hosted" pays through the Autonomi Pay gateway from prepaid credits — no wallet,
+# no EVM RPC on this instance. Requires antd >= 0.13.0.
+# payment_backend = "hosted"
+# payment_gateway_url = "https://pay.example.com"
+# payment_gateway_api_key = "pgk_..."
 
 # Bootstrap admin — seeds the first admin on a fresh DB (self-registration is
 # off by default; the server won't start with no admin and no seed).
@@ -183,7 +190,10 @@ curl -X POST /api/v2/tokens \
 | `INDELIBLE_JWT_SECRET` | **Required.** Secret for JWT signing; **minimum 32 characters** (the server refuses to start below this). Generate with `openssl rand -hex 32` | -- |
 | `INDELIBLE_JWT_SECRET_PREVIOUS` | Comma-separated **verify-only** former JWT secrets, kept during a rotation so live sessions survive. New tokens always sign with `INDELIBLE_JWT_SECRET`; these only verify already-issued tokens until they expire. See [key-rotation guide](docs/guides/key-rotation.md#rotating-the-jwt-secret) | -- |
 | `INDELIBLE_JWT_SECRET_FILE` | Path to a file holding the JWT secret (Docker/K8s secrets); takes precedence over `INDELIBLE_JWT_SECRET` | -- |
-| `INDELIBLE_WALLET_ENCRYPTION_KEY` | **Required.** 64-char hex key for wallet encryption (AES-256-GCM) | -- |
+| `INDELIBLE_WALLET_ENCRYPTION_KEY` | **Required for the local payment backend.** 64-char hex key for wallet + OIDC client-secret encryption (AES-256-GCM). Optional with `INDELIBLE_PAYMENT_BACKEND=hosted` (no wallet exists); set it there only if you want OIDC login, whose client secrets it also encrypts | -- |
+| `INDELIBLE_PAYMENT_BACKEND` | Who pays for uploads: `local` (this instance's wallet signs) or `hosted` (the Autonomi Pay gateway pays from the tenant's prepaid credits; no wallet, no EVM RPC on this instance; antd >= 0.13.0). Unknown values refuse to start. Not to be confused with the upload API's `payment_mode` (`auto`/`merkle`/`single`), which is how a payment is structured on-chain | `local` |
+| `INDELIBLE_PAYMENT_GATEWAY_URL` | Gateway base URL. **Required** when the backend is `hosted` | -- |
+| `INDELIBLE_PAYMENT_GATEWAY_API_KEY` | Tenant API key issued by the gateway (Bearer). Required when the backend is `hosted` | -- |
 | `INDELIBLE_WALLET_ENCRYPTION_KEY_FILE` | Path to a file holding the wallet encryption key (Docker/K8s secrets); takes precedence over `INDELIBLE_WALLET_ENCRYPTION_KEY` | -- |
 | `INDELIBLE_WALLET_ENCRYPTION_KEY_PREVIOUS` | Comma-separated **decrypt-only** former wallet keys, so the running service can read rows not yet re-encrypted during a rotation. See [key-rotation guide](docs/guides/key-rotation.md#rotating-the-wallet-encryption-key) | -- |
 | `INDELIBLE_SECRETS_BACKEND` | Where key material is sourced from. `env` sources from env / config-file / `_FILE`. Other backends (Vault, cloud KMS) plug in behind the same provider seam | `env` |

cmd/indelible/main.go

@@ -85,6 +85,15 @@ func main() {
 	slog.SetDefault(logger)
 
 	slog.Info("starting indelible", "version", buildinfo.Version, "port", cfg.Port, "db_driver", cfg.DBDriver())
+	if cfg.PaymentBackend.Hosted() {
+		// V2-929: uploads are paid by the gateway from prepaid credits — no
+		// wallet record, no EVM RPC, and the wallet encryption key is optional
+		// (it only gates OIDC client-secret storage here).
+		slog.Info("payment backend: hosted — uploads paid by the gateway, no wallet or EVM RPC on this instance",
+			"gateway", cfg.PaymentGatewayURL, "wallet_key_configured", cfg.WalletKeyConfigured())
+	} else {
+		slog.Info("payment backend: local — uploads signed with the instance wallet", "network", cfg.Network)
+	}
 
 	// Managed antd
 	var antdMgr *managedantd.Manager

docs/docs.go

@@ -144,6 +144,157 @@ const docTemplate = `{
                 }
             }
         },
+        "/admin/billing": {
+            "get": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "Hosted-mode billing: gateway credits and credited top-up history",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Admin: Billing"
+                ],
+                "summary": "Billing summary",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Not in hosted payment mode",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/admin/billing/topup-checkout": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "Create a Stripe Checkout session at the gateway; returns the hosted payment page URL and the exact credit",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Admin: Billing"
+                ],
+                "summary": "Start a card top-up",
+                "parameters": [
+                    {
+                        "description": "Amount in USD cents and return URLs",
+                        "name": "body",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/internal_handlers.topupCheckoutRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "session_id, url, credit_atto",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "502": {
+                        "description": "Gateway unreachable",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/admin/billing/topup-sync": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "Ask the gateway to retrieve the Checkout session from Stripe and credit it if paid (idempotent; webhook-loss fallback)",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Admin: Billing"
+                ],
+                "summary": "Sync a top-up",
+                "parameters": [
+                    {
+                        "description": "Checkout session id",
+                        "name": "body",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/internal_handlers.topupSyncRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "credited, payment_status",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    "502": {
+                        "description": "Gateway unreachable",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            }
+        },
         "/admin/departments": {
             "get": {
                 "security": [
@@ -5663,7 +5814,7 @@ const docTemplate = `{
                         "BearerAuth": []
                     }
                 ],
-                "description": "Get an exact cost quote by sending the file bytes. antd runs self-encryption and queries the live network for chunk pricing — no estimation, no scaling. Returns a structured estimated_cost object with cost, chunk_count, gas, and payment_mode.",
+                "description": "Get an exact cost quote by sending the file bytes. antd runs self-encryption and queries the live network for chunk pricing — no estimation, no scaling. Returns a structured estimated_cost object with cost, chunk_count, gas, and payment_mode (antd's on-chain payment strategy: auto | merkle | single). With the hosted payment backend the gateway debits gross — batch total plus a per-batch network fee (V2-1098) — so the response additionally carries gateway_fee_per_batch_atto, estimated_batch_count, and estimated_total_with_fee_atto (V2-1113).",
                 "consumes": [
                     "multipart/form-data"
                 ],
@@ -7264,6 +7415,29 @@ const docTemplate = `{
                 }
             }
         },
+        "internal_handlers.topupCheckoutRequest": {
+            "type": "object",
+            "properties": {
+                "amount_usd_cents": {
+                    "type": "integer"
+                },
+                "cancel_url": {
+                    "type": "string"
+                },
+                "success_url": {
+                    "description": "Absolute URLs back into this instance's UI; validated by the gateway\n(http/https only). Stripe substitutes {CHECKOUT_SESSION_ID} in\nsuccess_url if the placeholder is present.",
+                    "type": "string"
+                }
+            }
+        },
+        "internal_handlers.topupSyncRequest": {
+            "type": "object",
+            "properties": {
+                "session_id": {
+                    "type": "string"
+                }
+            }
+        },
         "internal_handlers.updateGroupRequest": {
             "type": "object",
             "properties": {
@@ -7411,12 +7585,23 @@ const docTemplate = `{
                 "filename": {
                     "type": "string"
                 },
+                "gateway_fee_atto": {
+                    "description": "GatewayFeeAtto itemizes the gateway's per-batch network fee out of the\ngross actual_cost (V2-1098); absent when no fee was charged.",
+                    "type": "string"
+                },
+                "gateway_payment_key": {
+                    "type": "string"
+                },
                 "last_quoted_cost": {
                     "type": "string"
                 },
                 "original_filename": {
                     "type": "string"
                 },
+                "payment_backend": {
+                    "description": "Payment provenance (V2-1086): \"local\" (instance wallet) or \"hosted\"\n(gateway credits) + the gateway's batch key; absent when nothing was paid.",
+                    "type": "string"
+                },
                 "processing_at": {
                     "type": "string"
                 },