@trustbaseai/protocol 0.1.0

package/dist/canonical.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * 规范化 JSON (canonical JSON) —— `bundle_hash` 的唯一算法，跨侧冻结。
+ *
+ * ## 为什么需要它
+ *
+ * 链上 `x/endpoint` 只校验两件事：`bundle_hash` 是 32 字节、且等于当前指针里的哈希
+ * （长度校验 `x/endpoint/keeper/msg_server.go:44`(轮换) / `:142`(见证)，
+ * 哈希相等校验 `msg_server.go:161`）。**链码不强制算法本身** —— 也就是说：
+ *
+ *   链上写指针的是 A 方，投见证票的是 B 方，浏览器 PWA 算 `endpoint_hash` 的是 C 方。
+ *   三方任何一方把同一个 bundle 算成不同字节 → 所有见证票被拒、链上永远没票，
+ *   而链上只会回 `bundle_hash must equal current pointer` 这种看起来像"对方写错"的错。
+ *
+ * 所以这份规则是**红线**：换算法 = 破坏兼容，必须链上/索引器/PWA 三方同时升级，
+ * 并且必须 bump `CANONICALIZATION_VERSION`（写进协议版本，旧包直接拒收）。
+ *
+ * ## 规则（`trustbase-canonical-json-v1`）
+ *
+ * | # | 规则 |
+ * |---|---|
+ * | 1 | 只接受 JSON 数据模型：null / boolean / 整数 / 字符串 / 数组 / 纯对象 |
+ * | 2 | 对象键按 **Unicode 码点升序**（不是 UTF-16 码元序；两者仅对增补平面字符不同） |
+ * | 3 | 数字**必须是整数**且 `|n| <= 2^53-1`；`NaN` / `±Infinity` / 浮点 / `-0` / 超大整数一律抛错 |
+ * | 4 | 字符串按 UTF-8 编码；非 ASCII **不转义**（中文原样输出）；只转义 `"` `\` 与 C0 控制符；拒绝落单的代理项 |
+ * | 5 | 数组**保序**；拒绝稀疏数组与数组上的非下标属性 |
+ * | 6 | 对象只读 **enumerable own 属性**；拒绝 accessor (getter)、symbol 键 |
+ * | 7 | 输出**无任何空白**：`{"a":1,"b":[1,2]}` |
+ * | 8 | 拒绝 `undefined` / bigint / symbol / function / 循环引用 / 深度 > 64 |
+ *
+ * **与 `JSON.stringify` 的三个差异**（踩过就知道疼）：
+ * - 不调用 `toJSON()`（Date 之类会直接被拒，而不是悄悄变成 ISO 字符串）
+ * - 不做 `-0 → 0` 的静默归一，直接拒（否则两份"相等"的输入算出不同 hash 取决于谁先归一）
+ * - 不做 `undefined` 键的静默丢弃，直接拒（丢键会让"少写一个字段"看起来像正常数据）
+ *
+ * **跨语言实现要点**：Go 用 `sort.Strings`（== UTF-8 字节序 == 码点序，天然一致）；
+ * Python 用默认 `sorted()`（码点序）；JS 必须用本文件的 `compareByCodePoint`，
+ * 因为 JS 默认 `sort()` 是 UTF-16 码元序，遇到 emoji 这类增补平面字符会排错。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CanonicalizationError = exports.MAX_CANONICAL_DEPTH = exports.CANONICALIZATION_VERSION = void 0;
+exports.compareByCodePoint = compareByCodePoint;
+exports.canonicalize = canonicalize;
+const errors_1 = require("./errors");
+const validation_1 = require("./validation");
+/** 规则集版本。换算法必须 bump 这个值（会进协议握手/广播包，旧版本直接拒收）。 */
+exports.CANONICALIZATION_VERSION = 'trustbase-canonical-json-v1';
+/** 最大嵌套深度。防递归爆栈 / 防对方构造深树打爆内存。 */
+exports.MAX_CANONICAL_DEPTH = 64;
+class CanonicalizationError extends errors_1.ProtocolError {
+    /** 出错位置，JSONPath 风格，如 `$.endpoints[0].hints` */
+    path;
+    constructor(code, message, path) {
+        super(code, `${message} (at ${path})`);
+        this.name = 'CanonicalizationError';
+        this.path = path;
+    }
+}
+exports.CanonicalizationError = CanonicalizationError;
+/**
+ * 码点升序比较器（跨语言一致）。
+ *
+ * 不能用 `a < b`：JS 的字符串比较是 UTF-16 码元序，`'\u{1F600}' < '\uFFFD'` 的结果
+ * 与码点序相反，而 Go/Python 都是码点序。这类差异只在少数键上暴露，是典型的
+ * "本地测试全绿、跨端全红"。
+ */
+function compareByCodePoint(a, b) {
+    const ia = a[Symbol.iterator]();
+    const ib = b[Symbol.iterator]();
+    for (;;) {
+        const na = ia.next();
+        const nb = ib.next();
+        if (na.done === true && nb.done === true)
+            return 0;
+        if (na.done === true)
+            return -1;
+        if (nb.done === true)
+            return 1;
+        const ca = na.value.codePointAt(0) ?? 0;
+        const cb = nb.value.codePointAt(0) ?? 0;
+        if (ca !== cb)
+            return ca < cb ? -1 : 1;
+    }
+}
+/** 落单的代理项（lone surrogate）不是合法 UTF-8，跨端编码结果会不一致 → 拒。 */
+function assertWellFormedUnicode(value, path) {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+            if (next < 0xdc00 || next > 0xdfff) {
+                throw new CanonicalizationError('lone_surrogate', 'string contains an unpaired high surrogate (invalid UTF-8)', path);
+            }
+            i += 1; // 成对，跳过低位代理
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            throw new CanonicalizationError('lone_surrogate', 'string contains an unpaired low surrogate (invalid UTF-8)', path);
+        }
+    }
+}
+function writeNumber(value, path) {
+    if (!Number.isFinite(value)) {
+        throw new CanonicalizationError('non_finite_number', `number must be finite, got ${String(value)}`, path);
+    }
+    if (!Number.isInteger(value)) {
+        throw new CanonicalizationError('non_integer_number', `only integers are allowed in canonical JSON, got ${String(value)} (encode decimals as strings)`, path);
+    }
+    if (Object.is(value, -0)) {
+        throw new CanonicalizationError('negative_zero', '-0 is rejected: runtimes serialize it inconsistently (JSON.stringify(-0) === "0")', path);
+    }
+    if (!Number.isSafeInteger(value)) {
+        throw new CanonicalizationError('unsafe_integer', `${String(value)} exceeds Number.MAX_SAFE_INTEGER; encode it as a decimal string`, path);
+    }
+    return String(value);
+}
+function writeString(value, path) {
+    assertWellFormedUnicode(value, path);
+    // JSON.stringify 只转义 " \ 与 C0 控制符，非 ASCII 原样保留 —— 正是我们要的。
+    return JSON.stringify(value);
+}
+function writeArray(value, path, depth, seen) {
+    const ownKeys = Object.keys(value);
+    for (const key of ownKeys) {
+        if (!/^(0|[1-9][0-9]*)$/.test(key)) {
+            throw new CanonicalizationError('array_extra_property', `arrays must not carry extra properties, found "${key}"`, path);
+        }
+    }
+    const parts = [];
+    for (let i = 0; i < value.length; i++) {
+        if (!Object.prototype.hasOwnProperty.call(value, i)) {
+            throw new CanonicalizationError('sparse_array', `sparse arrays are not allowed (missing index ${i})`, `${path}[${i}]`);
+        }
+        parts.push(writeValue(value[i], `${path}[${i}]`, depth + 1, seen));
+    }
+    return `[${parts.join(',')}]`;
+}
+function writeObject(value, path, depth, seen) {
+    const symbols = Object.getOwnPropertySymbols(value);
+    if (symbols.length > 0) {
+        throw new CanonicalizationError('symbol_key', 'symbol keys cannot be represented in JSON', path);
+    }
+    const keys = Object.keys(value).sort(compareByCodePoint);
+    const parts = [];
+    for (const key of keys) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor !== undefined && (descriptor.get !== undefined || descriptor.set !== undefined)) {
+            throw new CanonicalizationError('accessor_property', `accessor property "${key}" is not allowed: its value is not reproducible`, `${path}.${key}`);
+        }
+        parts.push(`${writeString(key, `${path}.${key}`)}:${writeValue(value[key], `${path}.${key}`, depth + 1, seen)}`);
+    }
+    return `{${parts.join(',')}}`;
+}
+function writeValue(value, path, depth, seen) {
+    if (depth > exports.MAX_CANONICAL_DEPTH) {
+        throw new CanonicalizationError('too_deep', `nesting deeper than ${exports.MAX_CANONICAL_DEPTH} levels is rejected`, path);
+    }
+    switch (typeof value) {
+        case 'object': {
+            if (value === null)
+                return 'null';
+            if (Array.isArray(value)) {
+                if (seen.has(value)) {
+                    throw new CanonicalizationError('circular_reference', 'circular reference detected', path);
+                }
+                seen.add(value);
+                try {
+                    return writeArray(value, path, depth, seen);
+                }
+                finally {
+                    seen.delete(value);
+                }
+            }
+            if (!(0, validation_1.isPlainObject)(value)) {
+                const name = Object.prototype.toString.call(value);
+                throw new CanonicalizationError('not_plain_object', `only plain objects are allowed, got ${name} (convert it explicitly first)`, path);
+            }
+            if (seen.has(value)) {
+                throw new CanonicalizationError('circular_reference', 'circular reference detected', path);
+            }
+            seen.add(value);
+            try {
+                return writeObject(value, path, depth, seen);
+            }
+            finally {
+                seen.delete(value);
+            }
+        }
+        case 'string':
+            return writeString(value, path);
+        case 'number':
+            return writeNumber(value, path);
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'undefined':
+            throw new CanonicalizationError('undefined_value', 'undefined is rejected: keys must be present with a real value (use null if intentional)', path);
+        case 'bigint':
+            throw new CanonicalizationError('unsupported_type', 'bigint is rejected: encode large integers as decimal strings', path);
+        case 'function':
+        case 'symbol':
+            throw new CanonicalizationError('unsupported_type', `${typeof value} cannot be canonicalized`, path);
+        default:
+            throw new CanonicalizationError('unsupported_type', `unsupported value type`, path);
+    }
+}
+/**
+ * 规范化 JSON：把任意值写成**字节唯一**的字符串表示。
+ *
+ * 同一个逻辑值无论键序、来源、运行时，输出必须逐字节相同。
+ *
+ * @throws {CanonicalizationError} 输入不满足 canonical JSON 数据模型时
+ */
+function canonicalize(value) {
+    return writeValue(value, '$', 0, new Set());
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;;;AA6BH,gDAaC;AAkMD,oCAEC;AA5OD,qCAAyC;AACzC,6CAA6C;AAE7C,gDAAgD;AACnC,QAAA,wBAAwB,GAAG,6BAA6B,CAAC;AAEtE,kCAAkC;AACrB,QAAA,mBAAmB,GAAG,EAAE,CAAC;AAEtC,MAAa,qBAAsB,SAAQ,sBAAa;IACtD,gDAAgD;IACvC,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe,EAAE,IAAY;QACrD,KAAK,CAAC,IAAI,EAAE,GAAG,OAAO,QAAQ,IAAI,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AATD,sDASC;AAED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAC,CAAS,EAAE,CAAS;IACrD,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IAChC,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IAChC,SAAS,CAAC;QACR,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;QACrB,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;QACrB,IAAI,EAAE,CAAC,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO,CAAC,CAAC;QACnD,IAAI,EAAE,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO,CAAC,CAAC,CAAC;QAChC,IAAI,EAAE,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO,CAAC,CAAC;QAC/B,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED,uDAAuD;AACvD,SAAS,uBAAuB,CAAC,KAAa,EAAE,IAAY;IAC1D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QACjC,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;YACrC,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAChE,IAAI,IAAI,GAAG,MAAM,IAAI,IAAI,GAAG,MAAM,EAAE,CAAC;gBACnC,MAAM,IAAI,qBAAqB,CAC7B,gBAAgB,EAChB,4DAA4D,EAC5D,IAAI,CACL,CAAC;YACJ,CAAC;YACD,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY;QACtB,CAAC;aAAM,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;YAC5C,MAAM,IAAI,qBAAqB,CAC7B,gBAAgB,EAChB,2DAA2D,EAC3D,IAAI,CACL,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,KAAa,EAAE,IAAY;IAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,qBAAqB,CAC7B,mBAAmB,EACnB,8BAA8B,MAAM,CAAC,KAAK,CAAC,EAAE,EAC7C,IAAI,CACL,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,qBAAqB,CAC7B,oBAAoB,EACpB,oDAAoD,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAChG,IAAI,CACL,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,qBAAqB,CAC7B,eAAe,EACf,mFAAmF,EACnF,IAAI,CACL,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,qBAAqB,CAC7B,gBAAgB,EAChB,GAAG,MAAM,CAAC,KAAK,CAAC,iEAAiE,EACjF,IAAI,CACL,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,WAAW,CAAC,KAAa,EAAE,IAAY;IAC9C,uBAAuB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACrC,0DAA0D;IAC1D,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,UAAU,CAAC,KAAgB,EAAE,IAAY,EAAE,KAAa,EAAE,IAAiB;IAClF,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,qBAAqB,CAC7B,sBAAsB,EACtB,kDAAkD,GAAG,GAAG,EACxD,IAAI,CACL,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,qBAAqB,CAC7B,cAAc,EACd,gDAAgD,CAAC,GAAG,EACpD,GAAG,IAAI,IAAI,CAAC,GAAG,CAChB,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAChC,CAAC;AAED,SAAS,WAAW,CAClB,KAA8B,EAC9B,IAAY,EACZ,KAAa,EACb,IAAiB;IAEjB,MAAM,OAAO,GAAG,MAAM,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC;IACpD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,qBAAqB,CAC7B,YAAY,EACZ,2CAA2C,EAC3C,IAAI,CACL,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IACzD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,UAAU,GAAG,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC/D,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,GAAG,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,KAAK,SAAS,CAAC,EAAE,CAAC;YAC/F,MAAM,IAAI,qBAAqB,CAC7B,mBAAmB,EACnB,sBAAsB,GAAG,iDAAiD,EAC1E,GAAG,IAAI,IAAI,GAAG,EAAE,CACjB,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,IAAI,GAAG,EAAE,EAAE,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IACnH,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAChC,CAAC;AAED,SAAS,UAAU,CAAC,KAAc,EAAE,IAAY,EAAE,KAAa,EAAE,IAAiB;IAChF,IAAI,KAAK,GAAG,2BAAmB,EAAE,CAAC;QAChC,MAAM,IAAI,qBAAqB,CAC7B,UAAU,EACV,uBAAuB,2BAAmB,qBAAqB,EAC/D,IAAI,CACL,CAAC;IACJ,CAAC;IAED,QAAQ,OAAO,KAAK,EAAE,CAAC;QACrB,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,MAAM,CAAC;YAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzB,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;oBACpB,MAAM,IAAI,qBAAqB,CAAC,oBAAoB,EAAE,6BAA6B,EAAE,IAAI,CAAC,CAAC;gBAC7F,CAAC;gBACD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBAChB,IAAI,CAAC;oBACH,OAAO,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;gBAC9C,CAAC;wBAAS,CAAC;oBACT,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC;YACD,IAAI,CAAC,IAAA,0BAAa,EAAC,KAAK,CAAC,EAAE,CAAC;gBAC1B,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACnD,MAAM,IAAI,qBAAqB,CAC7B,kBAAkB,EAClB,uCAAuC,IAAI,gCAAgC,EAC3E,IAAI,CACL,CAAC;YACJ,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpB,MAAM,IAAI,qBAAqB,CAAC,oBAAoB,EAAE,6BAA6B,EAAE,IAAI,CAAC,CAAC;YAC7F,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAChB,IAAI,CAAC;gBACH,OAAO,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;YAC/C,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;QACD,KAAK,QAAQ;YACX,OAAO,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAClC,KAAK,QAAQ;YACX,OAAO,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAClC,KAAK,SAAS;YACZ,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;QAClC,KAAK,WAAW;YACd,MAAM,IAAI,qBAAqB,CAC7B,iBAAiB,EACjB,yFAAyF,EACzF,IAAI,CACL,CAAC;QACJ,KAAK,QAAQ;YACX,MAAM,IAAI,qBAAqB,CAC7B,kBAAkB,EAClB,8DAA8D,EAC9D,IAAI,CACL,CAAC;QACJ,KAAK,UAAU,CAAC;QAChB,KAAK,QAAQ;YACX,MAAM,IAAI,qBAAqB,CAAC,kBAAkB,EAAE,GAAG,OAAO,KAAK,0BAA0B,EAAE,IAAI,CAAC,CAAC;QACvG;YACE,MAAM,IAAI,qBAAqB,CAAC,kBAAkB,EAAE,wBAAwB,EAAE,IAAI,CAAC,CAAC;IACxF,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,YAAY,CAAC,KAAc;IACzC,OAAO,UAAU,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,GAAG,EAAU,CAAC,CAAC;AACtD,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,200 @@
+/**
+ * 跨侧常量 —— 每一条都标注出处，改这里的值等于改协议。
+ *
+ * 纪律：**这些值全部是事实核对出来的，不是拍脑袋定的**。凡是从代码里核到的，
+ * 都在注释里写明 `文件:行号`；凡是"设计文档里有、代码里还没有"的，明确标 `待实现`。
+ */
+/**
+ * 默认 chain-id。
+ *
+ * 出处：`trustbase-seller-backend/routes/chain-writes.js:58`
+ *      `process.env.CHAIN_ID || 'trustchain-1'`；
+ *      `trustchain-relmerge/indexer/src/config/manager.ts:179` 同值，
+ *       且 `:225-227` 显式把历史误配 `trustchain-local` 纠正为 `trustchain-1`。
+ *
+ * ⚠️ 仓库里还存在另外两个值（见 `packages/protocol/README.md` §9 事实核对发现）：
+ *    `trustchain-local`（index.js:334 / run-relationship.js:22 / run-unified.js:283,298 / mcp/server.js:19）
+ *    `trustchain`（routes/order.js:151 等 CLI 示例）
+ *    本 SDK 以 `trustchain-1` 为准；调用方仍可用 `CHAIN_ID` env 覆盖。
+ */
+export declare const DEFAULT_CHAIN_ID = "trustchain-1";
+/**
+ * bech32 地址前缀。
+ * 出处：`trustbase-seller-backend/core/chain-signer.js:117`
+ *      `DirectSecp256k1HdWallet.fromMnemonic(mnemonic, { prefix: 'tct' })`；
+ *      `mcp/standalone-server.js:58` 明确「bech32 prefix 是链协议常量（'tct'），不允许 env 覆盖」。
+ *      （部署环境常把 CHAIN_ID=trustchain-1 误当 prefix 传，是同类踩坑记录。）
+ *
+ * ⚠️ 引用外部在研仓库的**行号会漂移**（这些仓库有人在改）。行号是本文件校对时的值，
+ *    以符号名（函数/常量名）为准；`proto/` 的出处由 `tools/check-proto-citations.cjs` 机器校验。
+ */
+export declare const BECH32_PREFIX = "tct";
+/** HD 派生路径：cosmjs `DirectSecp256k1HdWallet` 默认值，链侧同款 */
+export declare const HD_PATH = "m/44'/118'/0'/0/0";
+/** 基本 denom（链上 `sdk.DefaultBondDenom`，见 `routes/chain-writes-pledge.js:25`） */
+export declare const DENOM_UTCT = "utct";
+/** 显示单位名（人类可读），链上不出现 */
+export declare const DENOM_TCT_DISPLAY = "TCT";
+/** 小数位：1 TCT = 10^6 utct（micro TCT） */
+export declare const TCT_DECIMALS = 6;
+/**
+ * 1 TCT 等于多少 utct。
+ *
+ * 出处（两处独立核对，一致）：
+ *   - `trustbase-seller-backend/routes/onboard.js:85`
+ *     `if (utct >= grant.expected_tct * 1000000)` —— 引导金 tct → utct 判等
+ *   - `trustbase-seller-backend/routes/chain-writes-products.js:227-228`
+ *     「链上 params.min_stake_per_unit=1000000 (1 TCT, 反垃圾)」
+ */
+export declare const UTCT_PER_TCT = 1000000;
+/**
+ * USD → microTCT 的**默认**换算率。
+ *
+ * 出处：`trustbase-seller-backend/routes/chain-writes.js:65`
+ *      `usdToMicroTct: process.env.CHAIN_USD_TO_MICROTCT_RATE || '1000000'`
+ *
+ * ⚠️ 这是**可配置的展示/定价参数，不是链协议常量**：它随汇率与运营口径变动，
+ * 链上不校验。SDK 只提供默认值与类型，不要把它当不变量用。
+ */
+export declare const DEFAULT_USD_TO_MICRO_TCT_RATE = "1000000";
+/**
+ * 指针状态。链上**只持久化 ACTIVE / UNUSABLE**；
+ * EXPIRED 是按高度实时算出来的（不落链），NONE 表示该卖家没有指针。
+ *
+ * 出处：`x/endpoint/types/keys.go:33-36`（常量定义）、
+ *      `x/endpoint/keeper/keeper.go:168-174`（EXPIRED 实时判定）、
+ *      `proto/trustchain/endpoint/v1/endpoint.proto:36-38`（注释同口径）。
+ */
+export declare const PointerState: {
+    readonly ACTIVE: "ACTIVE";
+    readonly UNUSABLE: "UNUSABLE";
+    readonly EXPIRED: "EXPIRED";
+    readonly NONE: "NONE";
+};
+export type PointerState = (typeof PointerState)[keyof typeof PointerState];
+/** 会落链的指针状态（EXPIRED / NONE 是计算值，不落链） */
+export declare const ON_CHAIN_POINTER_STATES: readonly PointerState[];
+/**
+ * `MsgAttestEndpoint.latency_ms` 的编译期上限。
+ * 出处：`x/endpoint/types/keys.go:44` `MaxLatencyMs uint64 = 3_600_000`（1 小时）。
+ * 超上限链上直接拒（`msg_server.go:145-146`），客户端校验可以省一次失败交易。
+ */
+export declare const MAX_LATENCY_MS = 3600000;
+/**
+ * `region_hint` 的默认字节上限。
+ * 出处：`proto/trustchain/endpoint/v1/params.proto:31-32` 注释「默认 16」；
+ *      实际取值受链上 params 约束，可能被治理改（读 params 为准，这里只是默认）。
+ */
+export declare const DEFAULT_MAX_REGION_HINT_LEN = 16;
+/** `endpoint` 模块事件类型（链上 emit 的 EventType，索引器按它建索引） */
+export declare const EndpointEventType: {
+    readonly POINTER_UPDATED: "endpoint_pointer_updated";
+    readonly POINTER_UNUSABLE: "endpoint_pointer_unusable";
+    readonly POINTER_RECOVERED: "endpoint_pointer_recovered";
+    readonly WITNESS_ATTESTED: "endpoint_witness_attested";
+    readonly WITNESS_EVICTED: "endpoint_witness_evicted";
+    readonly WITNESSES_SUPERSEDED: "endpoint_witnesses_superseded";
+};
+export type EndpointEventType = (typeof EndpointEventType)[keyof typeof EndpointEventType];
+/** 出处：`x/endpoint/types/events.go:4-14` */
+export declare const ENDPOINT_EVENT_TYPES: readonly EndpointEventType[];
+/**
+ * WS 查询参数上限 —— **与索引器实现逐字段对齐**，不要在这里另行造数。
+ *
+ * 出处：`trustchain-relmerge/indexer/src/core/ws-query-provider.ts`  的 `WS_QUERY_LIMITS`
+ *      （`:17-25`，服务端校验用的就是这一份）。
+ * 校验位置：`indexer/src/core/websocket.ts` 的 `validateQueryArgs()`（`:115` 起）
+ *          与 `handleQuery()`（`:553` 起，id / q / args 校验）。
+ *
+ * 另外两项（`maxPendingQueries` / `queryTimeoutMs`）出自同文件 `DEFAULT_WEBSOCKET_CONFIG`
+ * （`:64-72`）；`maxTopics` / `maxTopicLength` 出自 `extractTopics()`（`:100`）里的字面量。
+ *
+ * ⚠️ 索引器行号**会随其自身演进漂移**（本文件校对时的值），以符号名为准。
+ */
+export declare const WS_QUERY_LIMITS: {
+    /** catalog.limit 上限（默认 20） */
+    readonly maxLimit: 100;
+    readonly defaultLimit: 20;
+    /** catalog.offset 上限 */
+    readonly maxOffset: 1000000;
+    /** catalog.q 关键字长度上限 */
+    readonly maxKeywordLength: 200;
+    /** product.id / endpoints.seller 长度上限 */
+    readonly maxIdLength: 200;
+    /** query.id 长度上限（请求/响应配对用） */
+    readonly maxQueryIdLength: 128;
+    /** 单条 WS 消息字节上限（超出回 `message_too_large`） */
+    readonly maxMessageBytes: number;
+    /** 单连接并发查询上限（超出回 `too_many_requests`） */
+    readonly maxPendingQueries: 8;
+    /** 单条查询超时（毫秒，超时回 `timeout`） */
+    readonly queryTimeoutMs: 5000;
+    /** subscribe/unsubscribe 单次 topic 数上限，以及单个 topic 长度上限 */
+    readonly maxTopics: 64;
+    readonly maxTopicLength: 64;
+};
+/**
+ * 查询名白名单。
+ * 出处：`indexer/src/core/ws-query-provider.ts:28`
+ *      `WS_QUERY_NAMES = ['health','catalog','product','endpoints']`。
+ */
+export declare const WS_QUERY_NAMES: readonly ["health", "catalog", "product", "endpoints"];
+export type WsQueryName = (typeof WS_QUERY_NAMES)[number];
+/**
+ * 订阅 topic（= 事件类型）。
+ *
+ * 出处：`indexer/src/core/websocket.ts` 的 `handleConnection()`（`:468`
+ *      `subscriptions: new Set(['block','transaction','product','order'])`，连接建立即默认全订），
+ *      广播类型见同文件 `broadcastBlockEvent` / `broadcastTransactionEvent` /
+ *      `broadcastProductEvent` / `broadcastOrderEvent`（`:377` 起）。
+ *
+ * ⚠️ `endpoint` topic 出现在《PWA设计》§6.1 的示例里，但**索引器当前尚未实现**
+ *    （grep 全仓无 `endpoint` topic 的广播路径）→ 见 `PLANNED_WS_TOPICS`。
+ */
+export declare const WS_TOPICS: readonly ["block", "transaction", "product", "order"];
+export type WsTopic = (typeof WS_TOPICS)[number];
+/** 设计文档里有、代码里还没有的 topic（订阅它不会有任何推送，别当特性用） */
+export declare const PLANNED_WS_TOPICS: readonly ["endpoint"];
+/**
+ * WS 清单文件与端口约定（安装器 / 索引器 / doctor 三方契约）。
+ * 出处：《PWA设计》§6.1.1 表格。
+ */
+export declare const WS_PORT_ENV = "INDEXER_WS_PORT";
+export declare const WS_PORT_MANIFEST_FILE = "ws-port.json";
+export declare const WS_PORT_RANGE: readonly [number, number];
+/** 挂载模式的默认路径；独立入口不占这个路径 */
+export declare const DEFAULT_INDEXER_WS_PATH = "/ws/indexer";
+/** 索引器 HTTP 端口 env（与卖家后端的 PORT 是两个进程，不能共用） */
+export declare const INDEXER_HTTP_PORT_ENV = "PORT";
+/**
+ * 端点广播的 gossip topic。
+ * 出处：《PWA设计》§6.2 标题「gossip topic `trustbase/endpoints/v1`」。
+ * 状态：⚠️ 待实现 —— `trustchain-relmerge` 内 grep 无 `trustbase/endpoints/v1`、
+ *      无 `endpoint_announce` / `probe_report`，P2 阶段才落地。
+ */
+export declare const GOSSIP_TOPIC_ENDPOINTS = "trustbase/endpoints/v1";
+/** 广播包 / 背书包的协议版本（`v` 字段）。出处：同上 §6.2 / §6.3 示例中的 `"v": 1` */
+export declare const GOSSIP_PROTOCOL_VERSION = 1;
+/** 端点包签名域里的 `type` 值 */
+export declare const ANNOUNCE_TYPE = "endpoint_announce";
+/** 探测背书包的 `type` 值 */
+export declare const PROBE_REPORT_TYPE = "probe_report";
+/** 端点类型（descriptor.kind） */
+export declare const EndpointKind: {
+    readonly WEBRTC: "webrtc";
+    readonly WEBTRANSPORT: "webtransport";
+    readonly WSS: "wss";
+};
+export type EndpointKind = (typeof EndpointKind)[keyof typeof EndpointKind];
+/** 出处：《PWA设计》§6.2 的 endpoints[] 示例三种 kind */
+export declare const ENDPOINT_KINDS: readonly EndpointKind[];
+/**
+ * 探测背书计权上限（**约定，不在 SDK 里实现计权逻辑**）。
+ * 出处：《PWA设计》§6.3「单设备权重上限低（例如 ≤1 票）；
+ *      只有负票才需要多源一致（≥3 个独立来源）才降权」。
+ * 链侧同口径：`x/endpoint/types/keys.go` 见证 weight 默认 1、
+ * `params.min_witnesses_for_negative` 默认 3（`proto/trustchain/endpoint/v1/params.proto:26-28`）。
+ */
+export declare const MAX_WEIGHT_PER_DEVICE = 1;
+export declare const MIN_INDEPENDENT_SOURCES_FOR_NEGATIVE = 3;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}

package/dist/constants.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * 跨侧常量 —— 每一条都标注出处，改这里的值等于改协议。
+ *
+ * 纪律：**这些值全部是事实核对出来的，不是拍脑袋定的**。凡是从代码里核到的，
+ * 都在注释里写明 `文件:行号`；凡是"设计文档里有、代码里还没有"的，明确标 `待实现`。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_INDEPENDENT_SOURCES_FOR_NEGATIVE = exports.MAX_WEIGHT_PER_DEVICE = exports.ENDPOINT_KINDS = exports.EndpointKind = exports.PROBE_REPORT_TYPE = exports.ANNOUNCE_TYPE = exports.GOSSIP_PROTOCOL_VERSION = exports.GOSSIP_TOPIC_ENDPOINTS = exports.INDEXER_HTTP_PORT_ENV = exports.DEFAULT_INDEXER_WS_PATH = exports.WS_PORT_RANGE = exports.WS_PORT_MANIFEST_FILE = exports.WS_PORT_ENV = exports.PLANNED_WS_TOPICS = exports.WS_TOPICS = exports.WS_QUERY_NAMES = exports.WS_QUERY_LIMITS = exports.ENDPOINT_EVENT_TYPES = exports.EndpointEventType = exports.DEFAULT_MAX_REGION_HINT_LEN = exports.MAX_LATENCY_MS = exports.ON_CHAIN_POINTER_STATES = exports.PointerState = exports.DEFAULT_USD_TO_MICRO_TCT_RATE = exports.UTCT_PER_TCT = exports.TCT_DECIMALS = exports.DENOM_TCT_DISPLAY = exports.DENOM_UTCT = exports.HD_PATH = exports.BECH32_PREFIX = exports.DEFAULT_CHAIN_ID = void 0;
+// ---------------------------------------------------------------------------
+// 链身份
+// ---------------------------------------------------------------------------
+/**
+ * 默认 chain-id。
+ *
+ * 出处：`trustbase-seller-backend/routes/chain-writes.js:58`
+ *      `process.env.CHAIN_ID || 'trustchain-1'`；
+ *      `trustchain-relmerge/indexer/src/config/manager.ts:179` 同值，
+ *       且 `:225-227` 显式把历史误配 `trustchain-local` 纠正为 `trustchain-1`。
+ *
+ * ⚠️ 仓库里还存在另外两个值（见 `packages/protocol/README.md` §9 事实核对发现）：
+ *    `trustchain-local`（index.js:334 / run-relationship.js:22 / run-unified.js:283,298 / mcp/server.js:19）
+ *    `trustchain`（routes/order.js:151 等 CLI 示例）
+ *    本 SDK 以 `trustchain-1` 为准；调用方仍可用 `CHAIN_ID` env 覆盖。
+ */
+exports.DEFAULT_CHAIN_ID = 'trustchain-1';
+/**
+ * bech32 地址前缀。
+ * 出处：`trustbase-seller-backend/core/chain-signer.js:117`
+ *      `DirectSecp256k1HdWallet.fromMnemonic(mnemonic, { prefix: 'tct' })`；
+ *      `mcp/standalone-server.js:58` 明确「bech32 prefix 是链协议常量（'tct'），不允许 env 覆盖」。
+ *      （部署环境常把 CHAIN_ID=trustchain-1 误当 prefix 传，是同类踩坑记录。）
+ *
+ * ⚠️ 引用外部在研仓库的**行号会漂移**（这些仓库有人在改）。行号是本文件校对时的值，
+ *    以符号名（函数/常量名）为准；`proto/` 的出处由 `tools/check-proto-citations.cjs` 机器校验。
+ */
+exports.BECH32_PREFIX = 'tct';
+/** HD 派生路径：cosmjs `DirectSecp256k1HdWallet` 默认值，链侧同款 */
+exports.HD_PATH = "m/44'/118'/0'/0/0";
+// ---------------------------------------------------------------------------
+// 金额
+// ---------------------------------------------------------------------------
+/** 基本 denom（链上 `sdk.DefaultBondDenom`，见 `routes/chain-writes-pledge.js:25`） */
+exports.DENOM_UTCT = 'utct';
+/** 显示单位名（人类可读），链上不出现 */
+exports.DENOM_TCT_DISPLAY = 'TCT';
+/** 小数位：1 TCT = 10^6 utct（micro TCT） */
+exports.TCT_DECIMALS = 6;
+/**
+ * 1 TCT 等于多少 utct。
+ *
+ * 出处（两处独立核对，一致）：
+ *   - `trustbase-seller-backend/routes/onboard.js:85`
+ *     `if (utct >= grant.expected_tct * 1000000)` —— 引导金 tct → utct 判等
+ *   - `trustbase-seller-backend/routes/chain-writes-products.js:227-228`
+ *     「链上 params.min_stake_per_unit=1000000 (1 TCT, 反垃圾)」
+ */
+exports.UTCT_PER_TCT = 1_000_000;
+/**
+ * USD → microTCT 的**默认**换算率。
+ *
+ * 出处：`trustbase-seller-backend/routes/chain-writes.js:65`
+ *      `usdToMicroTct: process.env.CHAIN_USD_TO_MICROTCT_RATE || '1000000'`
+ *
+ * ⚠️ 这是**可配置的展示/定价参数，不是链协议常量**：它随汇率与运营口径变动，
+ * 链上不校验。SDK 只提供默认值与类型，不要把它当不变量用。
+ */
+exports.DEFAULT_USD_TO_MICRO_TCT_RATE = '1000000';
+// ---------------------------------------------------------------------------
+// x/endpoint 状态与上限（proto: trustchain/endpoint/v1/*）
+// ---------------------------------------------------------------------------
+/**
+ * 指针状态。链上**只持久化 ACTIVE / UNUSABLE**；
+ * EXPIRED 是按高度实时算出来的（不落链），NONE 表示该卖家没有指针。
+ *
+ * 出处：`x/endpoint/types/keys.go:33-36`（常量定义）、
+ *      `x/endpoint/keeper/keeper.go:168-174`（EXPIRED 实时判定）、
+ *      `proto/trustchain/endpoint/v1/endpoint.proto:36-38`（注释同口径）。
+ */
+exports.PointerState = {
+    ACTIVE: 'ACTIVE',
+    UNUSABLE: 'UNUSABLE',
+    EXPIRED: 'EXPIRED',
+    NONE: 'NONE',
+};
+/** 会落链的指针状态（EXPIRED / NONE 是计算值，不落链） */
+exports.ON_CHAIN_POINTER_STATES = [
+    exports.PointerState.ACTIVE,
+    exports.PointerState.UNUSABLE,
+];
+/**
+ * `MsgAttestEndpoint.latency_ms` 的编译期上限。
+ * 出处：`x/endpoint/types/keys.go:44` `MaxLatencyMs uint64 = 3_600_000`（1 小时）。
+ * 超上限链上直接拒（`msg_server.go:145-146`），客户端校验可以省一次失败交易。
+ */
+exports.MAX_LATENCY_MS = 3_600_000;
+/**
+ * `region_hint` 的默认字节上限。
+ * 出处：`proto/trustchain/endpoint/v1/params.proto:31-32` 注释「默认 16」；
+ *      实际取值受链上 params 约束，可能被治理改（读 params 为准，这里只是默认）。
+ */
+exports.DEFAULT_MAX_REGION_HINT_LEN = 16;
+/** `endpoint` 模块事件类型（链上 emit 的 EventType，索引器按它建索引） */
+exports.EndpointEventType = {
+    POINTER_UPDATED: 'endpoint_pointer_updated',
+    POINTER_UNUSABLE: 'endpoint_pointer_unusable',
+    POINTER_RECOVERED: 'endpoint_pointer_recovered',
+    WITNESS_ATTESTED: 'endpoint_witness_attested',
+    WITNESS_EVICTED: 'endpoint_witness_evicted',
+    WITNESSES_SUPERSEDED: 'endpoint_witnesses_superseded',
+};
+/** 出处：`x/endpoint/types/events.go:4-14` */
+exports.ENDPOINT_EVENT_TYPES = Object.values(exports.EndpointEventType);
+// ---------------------------------------------------------------------------
+// 索引器 WS 协议（= PWA 查询门）
+// ---------------------------------------------------------------------------
+/**
+ * WS 查询参数上限 —— **与索引器实现逐字段对齐**，不要在这里另行造数。
+ *
+ * 出处：`trustchain-relmerge/indexer/src/core/ws-query-provider.ts`  的 `WS_QUERY_LIMITS`
+ *      （`:17-25`，服务端校验用的就是这一份）。
+ * 校验位置：`indexer/src/core/websocket.ts` 的 `validateQueryArgs()`（`:115` 起）
+ *          与 `handleQuery()`（`:553` 起，id / q / args 校验）。
+ *
+ * 另外两项（`maxPendingQueries` / `queryTimeoutMs`）出自同文件 `DEFAULT_WEBSOCKET_CONFIG`
+ * （`:64-72`）；`maxTopics` / `maxTopicLength` 出自 `extractTopics()`（`:100`）里的字面量。
+ *
+ * ⚠️ 索引器行号**会随其自身演进漂移**（本文件校对时的值），以符号名为准。
+ */
+exports.WS_QUERY_LIMITS = {
+    /** catalog.limit 上限（默认 20） */
+    maxLimit: 100,
+    defaultLimit: 20,
+    /** catalog.offset 上限 */
+    maxOffset: 1_000_000,
+    /** catalog.q 关键字长度上限 */
+    maxKeywordLength: 200,
+    /** product.id / endpoints.seller 长度上限 */
+    maxIdLength: 200,
+    /** query.id 长度上限（请求/响应配对用） */
+    maxQueryIdLength: 128,
+    /** 单条 WS 消息字节上限（超出回 `message_too_large`） */
+    maxMessageBytes: 64 * 1024,
+    /** 单连接并发查询上限（超出回 `too_many_requests`） */
+    maxPendingQueries: 8,
+    /** 单条查询超时（毫秒，超时回 `timeout`） */
+    queryTimeoutMs: 5_000,
+    /** subscribe/unsubscribe 单次 topic 数上限，以及单个 topic 长度上限 */
+    maxTopics: 64,
+    maxTopicLength: 64,
+};
+/**
+ * 查询名白名单。
+ * 出处：`indexer/src/core/ws-query-provider.ts:28`
+ *      `WS_QUERY_NAMES = ['health','catalog','product','endpoints']`。
+ */
+exports.WS_QUERY_NAMES = ['health', 'catalog', 'product', 'endpoints'];
+/**
+ * 订阅 topic（= 事件类型）。
+ *
+ * 出处：`indexer/src/core/websocket.ts` 的 `handleConnection()`（`:468`
+ *      `subscriptions: new Set(['block','transaction','product','order'])`，连接建立即默认全订），
+ *      广播类型见同文件 `broadcastBlockEvent` / `broadcastTransactionEvent` /
+ *      `broadcastProductEvent` / `broadcastOrderEvent`（`:377` 起）。
+ *
+ * ⚠️ `endpoint` topic 出现在《PWA设计》§6.1 的示例里，但**索引器当前尚未实现**
+ *    （grep 全仓无 `endpoint` topic 的广播路径）→ 见 `PLANNED_WS_TOPICS`。
+ */
+exports.WS_TOPICS = ['block', 'transaction', 'product', 'order'];
+/** 设计文档里有、代码里还没有的 topic（订阅它不会有任何推送，别当特性用） */
+exports.PLANNED_WS_TOPICS = ['endpoint'];
+/**
+ * WS 清单文件与端口约定（安装器 / 索引器 / doctor 三方契约）。
+ * 出处：《PWA设计》§6.1.1 表格。
+ */
+exports.WS_PORT_ENV = 'INDEXER_WS_PORT';
+exports.WS_PORT_MANIFEST_FILE = 'ws-port.json';
+exports.WS_PORT_RANGE = [10_000, 60_000];
+/** 挂载模式的默认路径；独立入口不占这个路径 */
+exports.DEFAULT_INDEXER_WS_PATH = '/ws/indexer';
+/** 索引器 HTTP 端口 env（与卖家后端的 PORT 是两个进程，不能共用） */
+exports.INDEXER_HTTP_PORT_ENV = 'PORT';
+// ---------------------------------------------------------------------------
+// P2P gossip（端点广播 / 探测背书）
+// ---------------------------------------------------------------------------
+/**
+ * 端点广播的 gossip topic。
+ * 出处：《PWA设计》§6.2 标题「gossip topic `trustbase/endpoints/v1`」。
+ * 状态：⚠️ 待实现 —— `trustchain-relmerge` 内 grep 无 `trustbase/endpoints/v1`、
+ *      无 `endpoint_announce` / `probe_report`，P2 阶段才落地。
+ */
+exports.GOSSIP_TOPIC_ENDPOINTS = 'trustbase/endpoints/v1';
+/** 广播包 / 背书包的协议版本（`v` 字段）。出处：同上 §6.2 / §6.3 示例中的 `"v": 1` */
+exports.GOSSIP_PROTOCOL_VERSION = 1;
+/** 端点包签名域里的 `type` 值 */
+exports.ANNOUNCE_TYPE = 'endpoint_announce';
+/** 探测背书包的 `type` 值 */
+exports.PROBE_REPORT_TYPE = 'probe_report';
+/** 端点类型（descriptor.kind） */
+exports.EndpointKind = {
+    WEBRTC: 'webrtc',
+    WEBTRANSPORT: 'webtransport',
+    WSS: 'wss',
+};
+/** 出处：《PWA设计》§6.2 的 endpoints[] 示例三种 kind */
+exports.ENDPOINT_KINDS = Object.values(exports.EndpointKind);
+/**
+ * 探测背书计权上限（**约定，不在 SDK 里实现计权逻辑**）。
+ * 出处：《PWA设计》§6.3「单设备权重上限低（例如 ≤1 票）；
+ *      只有负票才需要多源一致（≥3 个独立来源）才降权」。
+ * 链侧同口径：`x/endpoint/types/keys.go` 见证 weight 默认 1、
+ * `params.min_witnesses_for_negative` 默认 3（`proto/trustchain/endpoint/v1/params.proto:26-28`）。
+ */
+exports.MAX_WEIGHT_PER_DEVICE = 1;
+exports.MIN_INDEPENDENT_SOURCES_FOR_NEGATIVE = 3;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}