From c1915a0bf04fe9354befdb7dfccfa0095300e730 Mon Sep 17 00:00:00 2001
From: brain-marchine <152466993+brain-marchine@users.noreply.github.com>
Date: Sun, 12 Jul 2026 17:16:37 +0800
Subject: [PATCH] docs: document centralized request validation rules

Fixes #14
---
 docs/validation.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 docs/validation.md

diff --git a/docs/validation.md b/docs/validation.md
new file mode 100644
index 0000000..5937af2
--- /dev/null
+++ b/docs/validation.md
@@ -0,0 +1,22 @@
+# Request validation
+
+StableRoute backend validates inbound payloads inline at route handlers.
+Pair metadata PATCH routes share a descriptor table in `src/index.ts` that
+centralizes field names, validators, and cross-field checks:
+
+| Route suffix | Field | Validator summary |
+|--------------|-------|-------------------|
+| `liquidity` | `liquidity` | Non-negative integer string (≤39 digits) |
+| `max` | `maxAmount` | Positive integer string |
+| `min` | `minAmount` | Non-negative integer string; must be ≤ max/liquidity |
+| `fee_bps` | `feeBps` | Integer in `[0, 1000]` |
+| `rate` | `rate` | Positive decimal string, max 8 fractional digits |
+
+Webhook registration validates:
+
+- `url` must be `http(s)` with length ≤ 2048 and pass SSRF checks (`isSafeWebhookUrl`)
+- `events` must be a non-empty string array with deduplicated entries
+
+Unknown JSON keys on mutating routes are rejected via `rejectUnknownKeys`.
+
+See OpenAPI (`openapi.yaml`) for the public contract and error envelope shape.