以太坊与波场接入实战

// Package ogwebhook 提供 OG 通知接收边界：验签、事件分流、事务提交后回签。
// 用 NewHandler 将它接入你们的 HTTP 服务；数据库和账务由 commit 实现。
package ogwebhook

import (
	"bytes"
	"context"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"errors"
	"io"
	"math/big"
	"net/http"
	"regexp"
	"strconv"
	"time"
	"unicode/utf8"

	"walletprotocol/quota"
)

const maxBody = 1 << 20 // 本示例的接收端上限：1 MiB。

// Event 保留原始 JSON 字段；金额、链 ID、订单号等不能转为浮点数。
// Family 是 deposit 或 withdrawal；提现所属链和玩家从本地原订单获取。
type Event struct {
	Family string
	Type   string
	ID     string
	Fields map[string]json.RawMessage
}

// String 只读取 JSON 字符串，数字/null/缺失字段均返回 false。
func (e Event) String(name string) (string, bool) {
	var value string
	err := json.Unmarshal(e.Fields[name], &value)
	return value, err == nil && value != ""
}

// NewHandler 必须传入独立的通知凭据和真实的事务处理函数，不能使用空实现。
// commit 的职责（详见配套接入文档）：
//   - 按当前 OpenAPI 验证完整字段、玩家/链/合约及本地原订单金额。
//   - v2 rejected 独立核对可信 environment/accessNamespace、原请求全部身份与 eventId，
//     三渠道共用事务；仅无受理/付款证据的原 held 可转 released 一次。保存原 bytes/摘要/决定，
//     同 ID 异文、不同决定、受理或付款冲突须持久隔离，不覆盖原证据；不能放进通用 RELEASE。
//   - 同一事务持久化通知、按 eventId 去重、按 txRef/withdrawOrderId 幂等改账。
//   - 进度不改余额；充值确认按 txRef 入账；提现成功确认预扣，失败/退款释放预扣。
//   - 拒绝旧进度覆盖终态；异常和终态冲突持久化核查；失效充值恢复先查询复核。
//   - 事务 COMMIT 成功后才返回 nil；合法重复也须核对并确认已持久化，再返回 nil。
//   - 无法自动结账的异常可持久化到待核查表，保持余额不变，提交后返回 nil。
//     此时 ACK 仅代表可靠接收，不代表充值已入账或提现已结账。
//
// 不要启动 goroutine 后立即返回 nil，不要只写内存；失败返回 error，接收端不会回签。
// 建议服务端设置超时，并保证事务和响应在发送方的 5 秒超时内完成。
func NewHandler(accessKey, secret string, commit func(context.Context, Event, []byte) error) (http.Handler, error) {
	if accessKey == "" || secret == "" || commit == nil {
		return nil, errors.New("通知 access key、secret 和事务 commit 均不能为空")
	}
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if r.Method != http.MethodPost {
			w.Header().Set("Allow", http.MethodPost)
			http.Error(w, "POST required", http.StatusMethodNotAllowed)
			return
		}
		key, keyOK := singleHeader(r, "X-Access-Key")
		timestamp, timeOK := singleHeader(r, "X-Timestamp")
		signature, sigOK := singleHeader(r, "X-Signature")
		unix, err := strconv.ParseInt(timestamp, 10, 64)
		now := time.Now().Unix()
		if !keyOK || !timeOK || !sigOK || !hmac.Equal([]byte(key), []byte(accessKey)) ||
			!digits.MatchString(timestamp) || err != nil || unix < now-300 || unix > now+300 ||
			!lowerSignature.MatchString(signature) {
			http.Error(w, "invalid authentication", http.StatusUnauthorized)
			return
		}
		raw, err := io.ReadAll(http.MaxBytesReader(w, r.Body, maxBody))
		if err != nil {
			var tooLarge *http.MaxBytesError
			if errors.As(err, &tooLarge) {
				http.Error(w, "body too large", http.StatusRequestEntityTooLarge)
			} else {
				http.Error(w, "cannot read body", http.StatusBadRequest)
			}
			return
		}
		// 使用 HTTP 请求的原始路径、查询串与正文；反向代理须保留外部路径前缀。
		// 登记的通知 URL 目前不允许 query，因此实际投递 RawQuery 通常为空。
		// 仍保留 QUERY 段及分隔符。不要用 URL.Path、解码后的 query 或重序列化 JSON。
		mac := hmac.New(sha256.New, []byte(secret))
		mac.Write([]byte(r.Method + "|" + r.URL.EscapedPath() + "|" + timestamp + "|" + r.URL.RawQuery + "|"))
		mac.Write(raw)
		expected := mac.Sum(nil)
		provided, _ := hex.DecodeString(signature) // 上面的格式检查已限定 64 个小写 hex。
		if !hmac.Equal(expected, provided) {
			http.Error(w, "invalid authentication", http.StatusUnauthorized)
			return
		}
		event, err := parseEvent(raw)
		if err != nil {
			http.Error(w, "invalid event", http.StatusBadRequest)
			return
		}
		// 重复通知也执行 commit，由数据库唯一约束和事务完成幂等处理。
		if err := commit(r.Context(), event, raw); err != nil {
			http.Error(w, "transaction not committed", http.StatusServiceUnavailable)
			return
		}
		// 签原通知请求，绝不签下面的响应正文；恰好返回一份签名。
		w.Header().Set("X-Signature", hex.EncodeToString(expected))
		w.Header().Set("Content-Type", "application/json")
		w.WriteHeader(http.StatusOK)
		_, _ = io.WriteString(w, "{}")
	}), nil
}

func singleHeader(r *http.Request, name string) (string, bool) {
	values := r.Header.Values(name)
	if len(values) != 1 || values[0] == "" {
		return "", false
	}
	return values[0], true
}

var (
	digits         = regexp.MustCompile(`^[0-9]+$`)
	positiveAmount = regexp.MustCompile(`^[1-9][0-9]*$`)
	orderID        = regexp.MustCompile(`^[0-9]{30}$`)
	lowerSignature = regexp.MustCompile(`^[0-9a-f]{64}$`)
)

type eventRule struct {
	family, status string
	progress       bool
}

// 充值和提现是独立流程，两类均由同一接收地址接收 Webhook。
var eventRules = map[string]eventRule{
	"deposit_detected":            {"deposit", "deposit_detected", true},
	"deposit_confirming":          {"deposit", "deposit_confirming", true},
	"deposit_confirmed":           {"deposit", "confirmed", false},
	"withdrawal_accepted":         {"withdrawal", "accepted", true},
	"withdrawal_sending":          {"withdrawal", "sending", true},
	"withdrawal_confirming":       {"withdrawal", "confirming", true},
	"withdrawal_held":             {"withdrawal", "held", true},
	"withdrawal_manual_pending":   {"withdrawal", "manual_pending", true},
	"withdrawal_auto_sending":     {"withdrawal", "auto_sending", true},
	"withdrawal_voucher_checking": {"withdrawal", "voucher_checking", true},
	"withdrawal_voucher_failed":   {"withdrawal", "voucher_failed", true},
	"withdrawal_succeeded":        {"withdrawal", "succeeded", false},
	"withdrawal_failed":           {"withdrawal", "failed", false},
	"withdrawal_refunded":         {"withdrawal", "refunded", false},
}

// 这里校验分流所需最小字段，不替代完整的 OpenAPI 校验与业务核对。
func parseEvent(raw []byte) (Event, error) {
	var event Event
	bad := errors.New("invalid event")
	// Unmarshal 保留原有的单对象、语法和 10000 层深度边界，再拒绝各层重复键。
	if !utf8.Valid(raw) || json.Unmarshal(raw, &event.Fields) != nil || event.Fields == nil || !uniqueJSONKeys(raw) {
		return event, bad
	}
	event.ID, _ = event.String("eventId")
	event.Type, _ = event.String("type")
	statusValue, _ := event.String("status")
	v2 := false
	for _, key := range []string{"schemaVersion", "decisionId", "quota", "final", "paymentInitiated", "retryMode", "accepted", "broadcast"} {
		if _, present := event.Fields[key]; present {
			v2 = true
		}
	}
	if v2 || event.Type == "withdrawal_rejected" || statusValue == "rejected" {
		// 共享 Go codec 是完整 v2 wire 的唯一权威；原单/scope 仍须 commit 从可信记录绑定。
		rejection, err := quota.DecodeRejection(raw)
		if err != nil {
			return event, bad
		}
		event.Family, event.Type, event.ID = "withdrawal", rejection.Type, rejection.EventID
		return event, nil
	}
	status, _ := event.String("status")
	amount, _ := event.String("amount")
	rule, known := eventRules[event.Type]
	if !known || event.ID == "" || status != rule.status || len(amount) > 78 || !positiveAmount.MatchString(amount) {
		return event, bad
	}
	n, validAmount := new(big.Int).SetString(amount, 10)
	if !validAmount || n.BitLen() > 256 {
		return event, bad
	}
	event.Family = rule.family
	phase, _ := event.String("phase")
	_, hasPhase := event.Fields["phase"]
	if (rule.progress && phase != "progress") || (!rule.progress && hasPhase) {
		return event, bad // 终态必须省略 phase；null 也不接受。
	}
	if event.Family == "deposit" {
		for _, field := range []string{"playerId", "chainName", "chainId", "txHash", "logIndex", "tokenContract", "blockNumber", "txRef"} {
			if _, ok := event.String(field); !ok {
				return event, bad
			}
		}
		if rule.progress && (!integerAtLeast(event.Fields["confirmations"], 0) || !integerAtLeast(event.Fields["confirmationsRequired"], 1)) {
			return event, bad
		}
	} else {
		id, _ := event.String("withdrawOrderId")
		if !orderID.MatchString(id) {
			return event, bad
		}
		if event.Type == "withdrawal_succeeded" {
			if _, ok := event.String("txHash"); !ok {
				stage, _ := event.String("verificationStage")
				var details map[string]json.RawMessage
				if stage != "payments_succeeded" || json.Unmarshal(event.Fields["paymentDetails"], &details) != nil || details == nil {
					return event, bad
				}
				// Complete arithmetic and frozen-order binding belong to durable commit.
			}
		}
	}
	return event, nil
}

// 只检查键的唯一性，不改写参与验签和持久化的原始正文。
func uniqueJSONKeys(raw []byte) bool {
	decoder := json.NewDecoder(bytes.NewReader(raw))
	decoder.UseNumber()
	var value func() error
	value = func() error {
		token, err := decoder.Token()
		if err != nil {
			return err
		}
		switch token {
		case json.Delim('{'):
			seen := map[string]bool{}
			for decoder.More() {
				key, err := decoder.Token()
				if err != nil {
					return err
				}
				name, ok := key.(string)
				if !ok || seen[name] {
					return errors.New("重复 JSON 键")
				}
				seen[name] = true
				if err := value(); err != nil {
					return err
				}
			}
			_, err = decoder.Token()
		case json.Delim('['):
			for decoder.More() {
				if err := value(); err != nil {
					return err
				}
			}
			_, err = decoder.Token()
		}
		return err
	}
	if value() != nil {
		return false
	}
	_, err := decoder.Token()
	return err == io.EOF
}

func integerAtLeast(raw json.RawMessage, minimum int64) bool {
	var value int64
	return string(raw) != "null" && json.Unmarshal(raw, &value) == nil && value >= minimum
}

import com.fasterxml.jackson.core.JsonFactory;
import com.fasterxml.jackson.core.StreamReadFeature;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.math.BigInteger;
import java.nio.ByteBuffer;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Clock;
import java.util.HexFormat;
import java.util.List;
import java.util.Map;

/**
 * 目的：把 ETH / TRON 的充值、提现通知安全交给 OG 的业务事务，提交完成才回签。
 * Java 17 + Jackson；框架无关。充值与提现是独立业务，提现不要求先发生充值。
 * 旧14事件验证最小包络，v2 拒绝验证完整 wire；业务绑定和账务由必填 Commit 实现。
 */
public final class OgWebhook {
    public record Header(String name, String value) {}
    public record HttpResult(int status, Map<String, String> headers, byte[] body) {}

    @FunctionalInterface
    public interface Commit {
        /**
         * 返回前必须完成持久事务；抛错会得到 503 且不回签。
         * 事务须绑定 OG/环境，验证玩家、链、资产、原订单金额及各事件必需字段；
         * 按 eventId 保存原文摘要、检测同 ID 异文，并按 txRef / withdrawOrderId 幂等改账。
         * 充值进度不入账；confirmed 入账一次，失效/冲正后恢复须先查询复核。
         * 提现进度（含 voucher_failed）保留预扣；succeeded 确认扣款一次；
         * failed / refunded 释放原预扣一次；乱序进度不得覆盖终态，冲突终态须核查。
         * 重复已提交事件可直接返回；异常事实也可持久化隔离、安排核查后返回，不改余额。
         * v2 rejected 必须另绑定可信 scope、原请求全部身份与 eventId；三渠道共用事务，
         * 仅无 accepted/付款证据的原 held 可转 released 一次。原 bytes/摘要/决定同次保存，
         * 同 ID 异文/不同决定/付款冲突持久隔离，不覆盖首次证据，不纳入通用 RELEASE。
         * 禁止用空实现、内存集合或日志替代持久事务后就返回成功。
         */
        void save(JsonNode event, byte[] originalBody) throws Exception;
    }

    private record Rule(String status, boolean progress) {}
    private static final Map<String, Rule> RULES = Map.ofEntries(
        Map.entry("deposit_detected", new Rule("deposit_detected", true)),
        Map.entry("deposit_confirming", new Rule("deposit_confirming", true)),
        Map.entry("deposit_confirmed", new Rule("confirmed", false)),
        Map.entry("withdrawal_accepted", new Rule("accepted", true)),
        Map.entry("withdrawal_sending", new Rule("sending", true)),
        Map.entry("withdrawal_confirming", new Rule("confirming", true)),
        Map.entry("withdrawal_held", new Rule("held", true)),
        Map.entry("withdrawal_manual_pending", new Rule("manual_pending", true)),
        Map.entry("withdrawal_auto_sending", new Rule("auto_sending", true)),
        Map.entry("withdrawal_voucher_checking", new Rule("voucher_checking", true)),
        Map.entry("withdrawal_voucher_failed", new Rule("voucher_failed", true)),
        Map.entry("withdrawal_succeeded", new Rule("succeeded", false)),
        Map.entry("withdrawal_failed", new Rule("failed", false)),
        Map.entry("withdrawal_refunded", new Rule("refunded", false))
    );
    private static final ObjectMapper JSON = new ObjectMapper(JsonFactory.builder()
        .enable(StreamReadFeature.STRICT_DUPLICATE_DETECTION).build())
        .enable(DeserializationFeature.FAIL_ON_TRAILING_TOKENS);
    private final byte[] accessKey, secret;
    private final Clock clock;

    /** 传入独立 Webhook 凭据；不能传 OG 调用平台 API 的密钥。配置不完整时拒绝启动。 */
    public OgWebhook(String webhookAccessKey, String webhookSecret, Clock clock) {
        if (webhookAccessKey == null || webhookAccessKey.isBlank()
                || webhookSecret == null || webhookSecret.isEmpty()
                || webhookAccessKey.startsWith("REPLACE_") || webhookSecret.startsWith("REPLACE_")
                || clock == null) throw new IllegalArgumentException("Webhook configuration required");
        this.accessKey = bytes(webhookAccessKey);
        this.secret = bytes(webhookSecret);
        this.clock = clock;
    }

    /**
     * rawTarget = 原始转义路径 + 可选 '?' + 原始 query；不能 URL 解码、排序或重新编码。
     * Spring/Servlet 适配时用 getRequestURI() 和 getQueryString() 保留原样，
     * 不要使用 getParameterMap()；代理也必须保留签名时的外部路径与 query。
     * headers 必须保留每个头的全部值（getHeaders），不能用单值 Map 隐藏重复头。
     * rawBody 从输入流按最多 1 MiB + 1 字节读取；超限立即拒绝，不能先无限读取。
     * 先传原字节进来验签，不能让框架解析 JSON 后再序列化。
     */
    public HttpResult receive(String method, String rawTarget, List<Header> headers,
                              byte[] rawBody, Commit commit) {
        if (!"POST".equals(method)) return reject(405);
        if (rawBody == null || headers == null) return reject(400);
        if (rawBody.length > 1_048_576) return reject(413);
        if (commit == null) return reject(503);
        if (rawTarget == null || !rawTarget.startsWith("/")
                || !rawTarget.matches("[\\x21-\\x7e]+") || rawTarget.contains("#")) return reject(400);
        String key, timestamp, supplied;
        try {
            key = unique(headers, "X-Access-Key");
            timestamp = unique(headers, "X-Timestamp");
            supplied = unique(headers, "X-Signature");
        } catch (IllegalArgumentException e) { return reject(401); }
        if (!MessageDigest.isEqual(accessKey, bytes(key))
                || !timestamp.matches("[0-9]{1,20}") || !supplied.matches("[0-9a-f]{64}")) return reject(401);
        try {
            long ts = Long.parseLong(timestamp), now = clock.instant().getEpochSecond();
            if (ts < now - 300 || ts > now + 300) return reject(401);
        } catch (NumberFormatException e) { return reject(401); }

        int mark = rawTarget.indexOf('?');
        String path = mark < 0 ? rawTarget : rawTarget.substring(0, mark);
        String query = mark < 0 ? "" : rawTarget.substring(mark + 1);
        byte[] body = rawBody.clone();
        byte[] expected;
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(secret, "HmacSHA256"));
            mac.update(bytes(method + "|" + path + "|" + timestamp + "|" + query + "|"));
            expected = mac.doFinal(body);
        } catch (java.security.GeneralSecurityException e) { return reject(503); }
        if (!MessageDigest.isEqual(expected, HexFormat.of().parseHex(supplied))) return reject(401);

        JsonNode event;
        try {
            // 协议正文为 UTF-8；先严格解码，避免 Jackson 自动识别并接受 UTF-16 等编码。
            String utf8 = StandardCharsets.UTF_8.newDecoder()
                .onMalformedInput(CodingErrorAction.REPORT).onUnmappableCharacter(CodingErrorAction.REPORT)
                .decode(ByteBuffer.wrap(body)).toString();
            event = JSON.readTree(utf8);
            if (event != null && event.isObject() && (event.has("schemaVersion") || event.has("decisionId") || event.has("quota")
                    || event.has("final") || event.has("paymentInitiated") || event.has("retryMode")
                    || event.has("accepted") || event.has("broadcast")
                    || "withdrawal_rejected".equals(event.path("type").textValue())
                    || "rejected".equals(event.path("status").textValue()))) {
                event = QuotaRejection.decode(body);
            } else {
                if (event == null || !event.isObject() || !text(event, "eventId")
                        || !text(event, "type") || !text(event, "status") || !text(event, "amount")
                        || !event.get("amount").textValue().matches("[1-9][0-9]{0,77}")
                        || new BigInteger(event.get("amount").textValue()).bitLength() > 256) return reject(400);
                String type = event.get("type").textValue();
                Rule rule = RULES.get(type);
                if (rule == null || !rule.status().equals(event.get("status").textValue())) return reject(400);
                // 终态 phase 必须整个字段缺失；null 或空字符串也不接受。
                if (rule.progress() ? !"progress".equals(event.path("phase").textValue()) : event.has("phase"))
                    return reject(400);
                if (type.startsWith("deposit_")) {
                    for (String field : List.of("playerId", "chainName", "chainId", "txHash", "logIndex", "tokenContract", "blockNumber", "txRef")) {
                        if (!text(event, field)) return reject(400);
                    }
                    if (rule.progress() && (!event.path("confirmations").isIntegralNumber() || event.path("confirmations").bigIntegerValue().signum() < 0
                        || !event.path("confirmationsRequired").isIntegralNumber() || event.path("confirmationsRequired").bigIntegerValue().signum() <= 0)) return reject(400);
                } else if (!text(event, "withdrawOrderId")
                        || !event.get("withdrawOrderId").textValue().matches("[0-9]{30}")) return reject(400);
                if (type.equals("withdrawal_succeeded") && !text(event, "txHash")
                        && !("payments_succeeded".equals(event.path("verificationStage").textValue()) && event.path("paymentDetails").isObject())) return reject(400);
            }
        } catch (java.io.IOException | IllegalArgumentException e) { return reject(400); }

        try { commit.save(event, body); }
        catch (Exception e) { return reject(503); } // 可记录固定错误分类；不要记录密钥或原始敏感正文。
        // 回签覆盖「本次原请求」，不签 '{}'；只发送一个 X-Signature，用 setHeader 而非 addHeader。
        return new HttpResult(200, Map.of("Content-Type", "application/json",
            "X-Signature", HexFormat.of().formatHex(expected)), bytes("{}"));
    }

    private static String unique(List<Header> headers, String name) {
        String value = null;
        for (Header h : headers) {
            if (h == null || h.name() == null) throw new IllegalArgumentException("Invalid header");
            if (name.equalsIgnoreCase(h.name())) {
                if (value != null || h.value() == null || h.value().isEmpty())
                    throw new IllegalArgumentException("Missing or repeated signature header");
                value = h.value();
            }
        }
        if (value == null) throw new IllegalArgumentException("Missing signature header");
        return value;
    }
    private static boolean text(JsonNode event, String name) {
        return event.has(name) && event.get(name).isTextual() && !event.get(name).textValue().isEmpty();
    }
    private static byte[] bytes(String value) { return value.getBytes(StandardCharsets.UTF_8); }
    private static HttpResult reject(int status) {
        return new HttpResult(status, Map.of("Content-Type", "application/json"), bytes("{}"));
    }
}

"""OG Webhook 协议接收器：验签、校验事件包络、调用业务事务、提交后回签。

Python 3.10+，需配套 og_quota.py，两者只用标准库。它不启动 HTTP 服务，也不包含假账本。
从现有框架取得原始 body、未解码的 path/query、保留重复项的请求头后调用 receive。
commit(event, raw_body) 必须校验业务并持久提交后才正常返回；失败必须抛异常。
"""

from dataclasses import dataclass
import hashlib
import hmac
import inspect
import json
import re
import time
import sys
from pathlib import Path

# 完整下载包保留仓库相对布局，或将 og_quota.py 与本文件放在同一目录。
try:
    from og_quota import decode_rejection
except ModuleNotFoundError as error:
    if error.name != "og_quota":
        raise
    sys.path.insert(0, str(Path(__file__).resolve().parents[4] / "scripts"))
    from og_quota import decode_rejection
from typing import Callable


# type -> (status, phase)。None 表示字段必须缺失，不能为 null。
EVENTS = {
    "deposit_detected": ("deposit_detected", "progress"),
    "deposit_confirming": ("deposit_confirming", "progress"),
    "deposit_confirmed": ("confirmed", None),
    "withdrawal_accepted": ("accepted", "progress"),
    "withdrawal_sending": ("sending", "progress"),
    "withdrawal_confirming": ("confirming", "progress"),
    "withdrawal_held": ("held", "progress"),
    "withdrawal_manual_pending": ("manual_pending", "progress"),
    "withdrawal_auto_sending": ("auto_sending", "progress"),
    "withdrawal_voucher_checking": ("voucher_checking", "progress"),
    "withdrawal_voucher_failed": ("voucher_failed", "progress"),
    "withdrawal_succeeded": ("succeeded", None),
    "withdrawal_failed": ("failed", None),
    "withdrawal_refunded": ("refunded", None),
}
MAX_BODY = 1024 * 1024


@dataclass(frozen=True)
class Event:
    family: str  # deposit 或 withdrawal；与链无关，不硬编码 ETH/TRON。
    event_id: str
    type: str
    fields: dict


@dataclass(frozen=True)
class HttpResult:
    status: int
    headers: dict[str, str]
    body: bytes = b"{}"


def _object(pairs):
    """拒绝重复 JSON 键，避免不同解析器对同一正文产生不同解释。"""
    result = {}
    for key, value in pairs:
        if key in result:
            raise ValueError("重复 JSON 键")
        result[key] = value
    return result


class WebhookReceiver:
    def __init__(self, access_key: str, secret: str, commit: Callable[[Event, bytes], None]):
        if (not access_key or not secret or not callable(commit)
                or inspect.iscoroutinefunction(commit)
                or inspect.iscoroutinefunction(getattr(commit, "__call__", None))):
            raise ValueError("必须提供独立 Webhook 凭据和已实现的同步 commit")
        self.access_key = access_key
        self.secret = secret.encode("utf-8")
        self.commit = commit

    def receive(self, method: str, raw_target: str,
                headers: list[tuple[str, str]], raw_body: bytes) -> HttpResult:
        """raw_target 包含实际转义路径及原 query；禁止传框架已解码的 path。"""
        reject = lambda status: HttpResult(status, {"Content-Type": "application/json"})
        if method != "POST":
            return reject(405)
        if not isinstance(raw_body, bytes) or len(raw_body) > MAX_BODY:
            return reject(413)
        if not isinstance(raw_target, str) or not raw_target.startswith("/") or "#" in raw_target:
            return reject(400)
        try:
            selected = {}
            for name in ("x-access-key", "x-timestamp", "x-signature"):
                values = [value for key, value in headers if key.lower() == name]
                if len(values) != 1 or not isinstance(values[0], str):
                    return reject(401)
                selected[name] = values[0]
            stamp = selected["x-timestamp"]
            signature = selected["x-signature"]
            if (selected["x-access-key"] != self.access_key
                    or not re.fullmatch(r"[0-9]{1,20}", stamp)
                    or abs(int(time.time()) - int(stamp)) > 300
                    or not re.fullmatch(r"[0-9a-f]{64}", signature)):
                return reject(401)
            path, _, query = raw_target.partition("?")
            prefix = f"POST|{path}|{stamp}|{query}|".encode("ascii")
            expected = hmac.new(self.secret, prefix + raw_body, hashlib.sha256).hexdigest()
            if not hmac.compare_digest(signature, expected):
                return reject(401)
        except (ValueError, TypeError, UnicodeError):
            return reject(401)

        try:
            def invalid_constant(_value):
                raise ValueError("不是合法 JSON 数值")
            fields = json.loads(raw_body.decode("utf-8"), object_pairs_hook=_object,
                                parse_constant=invalid_constant)
            if not isinstance(fields, dict):
                return reject(400)
            if (any(key in fields for key in ("schemaVersion", "decisionId", "quota", "final", "paymentInitiated", "retryMode", "accepted", "broadcast"))
                    or fields.get("type") == "withdrawal_rejected"
                    or fields.get("status") == "rejected"):
                fields = decode_rejection(raw_body)
                family = "withdrawal"
            else:
                for field in ("eventId", "type", "status", "amount"):
                    if not isinstance(fields.get(field), str) or not fields[field].strip():
                        return reject(400)
                pair = EVENTS.get(fields["type"])
                if pair is None or fields["status"] != pair[0]:
                    return reject(400)
                if (pair[1] is None and "phase" in fields) or (pair[1] is not None and fields.get("phase") != pair[1]):
                    return reject(400)
                if not re.fullmatch(r"[1-9][0-9]{0,77}", fields["amount"]) or int(fields["amount"]) >= 2**256:
                    return reject(400)
                family = "deposit" if fields["type"].startswith("deposit_") else "withdrawal"
                if family == "deposit":
                    if any(not isinstance(fields.get(k), str) or not fields[k].strip() for k in ("playerId", "chainName", "chainId", "txHash", "logIndex", "tokenContract", "blockNumber", "txRef")):
                        return reject(400)
                    if pair[1] == "progress" and any(type(fields.get(k)) is not int or fields[k] < floor for k, floor in (("confirmations", 0), ("confirmationsRequired", 1))):
                        return reject(400)
                elif not isinstance(fields.get("withdrawOrderId"), str) or not re.fullmatch(r"[0-9]{30}", fields["withdrawOrderId"]):
                    return reject(400)
                if fields["type"] == "withdrawal_succeeded" and not (isinstance(fields.get("txHash"), str) and fields["txHash"].strip()):
                    if fields.get("verificationStage") != "payments_succeeded" or not isinstance(fields.get("paymentDetails"), dict):
                        return reject(400)
        except (ValueError, UnicodeError, RecursionError):
            return reject(400)

        event = Event(family, fields["eventId"], fields["type"], fields)
        try:
            # 必须接真实业务事务：完整字段/玩家/资产/原单核对，eventId 与业务键防重，
            # 事件和账务一起提交。重复事件也进入此函数，由事务确认已处理。
            # v2 拒绝须另绑定可信 scope、原请求及 eventId；无 accepted/付款证据的 held
            # 才能转 released 一次。三渠道共用事务，同 ID 异文/不同决定/付款冲突持久隔离。
            # 异常事实已持久隔离且未改账时可正常返回；ACK 不代表该笔已结账。
            # 不要把此回调实现成 pass、后台提交或仅写日志。
            result = self.commit(event, raw_body)
            # 同步组件不能把未 await 的事务当成成功，装饰器返回 awaitable 也拒绝。
            if inspect.isawaitable(result):
                if inspect.iscoroutine(result):
                    result.close()
                return reject(503)
        except Exception:
            return reject(503)  # 不输出凭据或原文；无 X-Signature，平台可按策略重试。
        return HttpResult(200, {"Content-Type": "application/json", "X-Signature": expected})