@proof-labs/trading-sdk 9.1.0 → 10.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/README.md +11 -15
  2. package/dist/block-header.d.ts +13 -0
  3. package/dist/block-header.d.ts.map +1 -0
  4. package/dist/block-header.js +29 -0
  5. package/dist/block-header.js.map +1 -0
  6. package/dist/block-results-window.d.ts +71 -0
  7. package/dist/block-results-window.d.ts.map +1 -0
  8. package/dist/block-results-window.js +170 -0
  9. package/dist/block-results-window.js.map +1 -0
  10. package/dist/bounded-read.d.ts +47 -0
  11. package/dist/bounded-read.d.ts.map +1 -0
  12. package/dist/bounded-read.js +288 -0
  13. package/dist/bounded-read.js.map +1 -0
  14. package/dist/chain-evidence.d.ts +37 -0
  15. package/dist/chain-evidence.d.ts.map +1 -0
  16. package/dist/chain-evidence.js +123 -0
  17. package/dist/chain-evidence.js.map +1 -0
  18. package/dist/client.d.ts +3 -2
  19. package/dist/client.d.ts.map +1 -1
  20. package/dist/client.js +3 -4
  21. package/dist/client.js.map +1 -1
  22. package/dist/codec-adapter.d.ts +0 -2
  23. package/dist/codec-adapter.d.ts.map +1 -1
  24. package/dist/codec-adapter.js +4 -23
  25. package/dist/codec-adapter.js.map +1 -1
  26. package/dist/committed-transaction.d.ts +34 -0
  27. package/dist/committed-transaction.d.ts.map +1 -0
  28. package/dist/committed-transaction.js +58 -0
  29. package/dist/committed-transaction.js.map +1 -0
  30. package/dist/errors.d.ts +16 -9
  31. package/dist/errors.d.ts.map +1 -1
  32. package/dist/errors.js +45 -32
  33. package/dist/errors.js.map +1 -1
  34. package/dist/finalized-account-reads.d.ts +75 -0
  35. package/dist/finalized-account-reads.d.ts.map +1 -0
  36. package/dist/finalized-account-reads.js +199 -0
  37. package/dist/finalized-account-reads.js.map +1 -0
  38. package/dist/finalized-oracle-read.d.ts +10 -0
  39. package/dist/finalized-oracle-read.d.ts.map +1 -0
  40. package/dist/finalized-oracle-read.js +25 -0
  41. package/dist/finalized-oracle-read.js.map +1 -0
  42. package/dist/finalized-orderbook.d.ts +23 -0
  43. package/dist/finalized-orderbook.d.ts.map +1 -0
  44. package/dist/finalized-orderbook.js +92 -0
  45. package/dist/finalized-orderbook.js.map +1 -0
  46. package/dist/finalized-state-reads.d.ts +21 -0
  47. package/dist/finalized-state-reads.d.ts.map +1 -0
  48. package/dist/finalized-state-reads.js +66 -0
  49. package/dist/finalized-state-reads.js.map +1 -0
  50. package/dist/financial-state.d.ts.map +1 -1
  51. package/dist/financial-state.js +12 -56
  52. package/dist/financial-state.js.map +1 -1
  53. package/dist/governance-query.d.ts.map +1 -1
  54. package/dist/governance-query.js +0 -1
  55. package/dist/governance-query.js.map +1 -1
  56. package/dist/index.d.ts +13 -1
  57. package/dist/index.d.ts.map +1 -1
  58. package/dist/index.js +3 -1
  59. package/dist/index.js.map +1 -1
  60. package/dist/market-snapshot.d.ts +3 -0
  61. package/dist/market-snapshot.d.ts.map +1 -1
  62. package/dist/market-snapshot.js +16 -38
  63. package/dist/market-snapshot.js.map +1 -1
  64. package/dist/oracle-permissions.d.ts +14 -30
  65. package/dist/oracle-permissions.d.ts.map +1 -1
  66. package/dist/oracle-permissions.js +29 -65
  67. package/dist/oracle-permissions.js.map +1 -1
  68. package/dist/read-values.d.ts +49 -0
  69. package/dist/read-values.d.ts.map +1 -0
  70. package/dist/read-values.js +88 -0
  71. package/dist/read-values.js.map +1 -0
  72. package/dist/trade-history.d.ts +50 -0
  73. package/dist/trade-history.d.ts.map +1 -0
  74. package/dist/trade-history.js +135 -0
  75. package/dist/trade-history.js.map +1 -0
  76. package/dist/typed-gateway-reads.d.ts +58 -0
  77. package/dist/typed-gateway-reads.d.ts.map +1 -0
  78. package/dist/typed-gateway-reads.js +98 -0
  79. package/dist/typed-gateway-reads.js.map +1 -0
  80. package/dist/types.d.ts +29 -83
  81. package/dist/types.d.ts.map +1 -1
  82. package/dist/types.js +8 -12
  83. package/dist/types.js.map +1 -1
  84. package/dist/wasm/proof_trading_sdk_wasm_bg.wasm +0 -0
  85. package/package.json +1 -6
  86. package/dist/testing.d.ts +0 -16
  87. package/dist/testing.d.ts.map +0 -1
  88. package/dist/testing.js +0 -21
  89. package/dist/testing.js.map +0 -1
package/README.md CHANGED
@@ -230,18 +230,16 @@ durable journal, nonce allocation, retries or cutover authority.
230
230
 
231
231
  `queryOraclePermissions(market)` reads one underlying perp's committed oracle
232
232
  policy, calendar epoch and verdict at an exact finalized height. It preserves
233
- u64 values as `bigint`, and returns `Legacy` with no permission claim while the
234
- new policy is inactive. `Satisfied` covers only this oracle dependency, not all
233
+ u64 values as `bigint`; with no committed verdict the read is `Unavailable`
234
+ with an `Unavailable` permission. `Satisfied` covers only this oracle dependency, not all
235
235
  portfolio dependencies or other trading checks. It never reads provider/observer
236
236
  health; feeder freshness is a separate operational read, described below.
237
237
 
238
- Nodes running the primary-with-fallback policy (exchange#831) serve a
239
- fourteen-field verdict: `format: 3`, the `selected` slot (`"Primary"` or
240
- `"Fallback"`) and a `diagnostics` bitset (`diagnosticFlags`: `OnFallback`,
238
+ The verdict carries the `selected` slot (`"Primary"` or `"Fallback"`) and a
239
+ `diagnostics` bitset (`diagnosticFlags`: `OnFallback`,
241
240
  `PrimaryRefusedDivergence`, `DivergenceUnchecked`, `FallbackUnusable`), which
242
- are monitoring signals rather than faults. Older nodes serve the twelve-field
243
- `format: 2` verdict, with `selected` null. Both formats share one `faults` bit
244
- layout (`ORACLE_FAULT_BITS`, named in `faultReasons`); `Disagreement` and
241
+ are monitoring signals rather than faults. `faults` follows
242
+ `ORACLE_FAULT_BITS`, named in `faultReasons`; `Disagreement` and
245
243
  `PairTimeMismatch` keep their bits but are no longer produced.
246
244
 
247
245
  ### Trading No on an event's binary book
@@ -481,13 +479,11 @@ keep operator actions out of autocomplete. `submitTx` still accepts the full
481
479
 
482
480
  #### Operator actions (privileged)
483
481
 
484
- `OperatorAction` covers oracle-relay / composite-CEX-feeder / relayer-admin
485
- actions — e.g. `OracleUpdate`, `OracleUpdateComposite`, `UpdateMarketFees`,
486
- `CreateMarket`. **A trading integration never needs these.** Each is gated by a
487
- dedicated engine allowlist, so codec availability grants nothing without an
488
- operator-provisioned key. See [AGENTS.md](AGENTS.md) → "Operator actions" for
489
- usage (e.g. driving the BE-31 multi-source mark via `OracleUpdateComposite` +
490
- `UpdateMarketFees` `markSourceMode`).
482
+ `OperatorAction` covers oracle-feeder / relayer-admin actions — e.g.
483
+ `SubmitOracleObservation`, `UpdateMarketFees`, `CreateMarket`. **A trading
484
+ integration never needs these.** Each is gated by a dedicated engine allowlist
485
+ or the market's oracle policy, so codec availability grants nothing without an
486
+ operator-provisioned key. See [AGENTS.md](AGENTS.md) → "Operator actions".
491
487
 
492
488
  #### Governance actions (admin multisig)
493
489
 
@@ -0,0 +1,13 @@
1
+ import type { Hash32Hex } from "./read-values.js";
2
+ export interface BlockEvidenceHeader {
3
+ hash: Hash32Hex;
4
+ chainId: string;
5
+ height: bigint;
6
+ parentHash: Hash32Hex | null;
7
+ time: string;
8
+ /** Header H contains the app hash after H-1, not after H. */
9
+ appHash: Hash32Hex | null;
10
+ }
11
+ /** Internal common header decoder; does not verify validator signatures. */
12
+ export declare function decodeBlockEvidenceHeader(response: Record<string, unknown>, height: bigint, chain: Uint8Array): BlockEvidenceHeader;
13
+ //# sourceMappingURL=block-header.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"block-header.d.ts","sourceRoot":"","sources":["../src/block-header.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;CAC3B;AAED,4EAA4E;AAC5E,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,UAAU,GAChB,mBAAmB,CA4BrB"}
@@ -0,0 +1,29 @@
1
+ import { I64_MAX, blockTime, hash, invalid, object, same, uint, } from "./chain-evidence.js";
2
+ import { chainIdFromString } from "./crypto.js";
3
+ /** Internal common header decoder; does not verify validator signatures. */
4
+ export function decodeBlockEvidenceHeader(response, height, chain) {
5
+ const block = object(response.block, "block");
6
+ const header = object(block.header, "block header");
7
+ if (uint(header.height, I64_MAX, "block height") !== height)
8
+ invalid("block height mismatch", "binding");
9
+ if (typeof header.chain_id !== "string" ||
10
+ header.chain_id.length === 0 ||
11
+ header.chain_id.length > 128 ||
12
+ !same(chainIdFromString(header.chain_id), chain))
13
+ invalid("block chain mismatch", "binding");
14
+ const previous = object(header.last_block_id, "previous block ID").hash;
15
+ const parentHash = height === 1n && previous === ""
16
+ ? null
17
+ : hash(previous, "parent block hash");
18
+ return {
19
+ hash: hash(object(response.block_id, "block ID").hash, "block hash"),
20
+ chainId: header.chain_id,
21
+ height,
22
+ parentHash,
23
+ time: blockTime(header.time),
24
+ appHash: height === 1n && header.app_hash === ""
25
+ ? null
26
+ : hash(header.app_hash, "block app hash"),
27
+ };
28
+ }
29
+ //# sourceMappingURL=block-header.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"block-header.js","sourceRoot":"","sources":["../src/block-header.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,SAAS,EACT,IAAI,EACJ,OAAO,EACP,MAAM,EACN,IAAI,EACJ,IAAI,GACL,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAWhD,4EAA4E;AAC5E,MAAM,UAAU,yBAAyB,CACvC,QAAiC,EACjC,MAAc,EACd,KAAiB;IAEjB,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,cAAc,CAAC,KAAK,MAAM;QACzD,OAAO,CAAC,uBAAuB,EAAE,SAAS,CAAC,CAAC;IAC9C,IACE,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;QACnC,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAC5B,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,GAAG;QAC5B,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;QAEhD,OAAO,CAAC,sBAAsB,EAAE,SAAS,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAAC,IAAI,CAAC;IACxE,MAAM,UAAU,GACd,MAAM,KAAK,EAAE,IAAI,QAAQ,KAAK,EAAE;QAC9B,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC;IAC1C,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,IAAI,EAAE,YAAY,CAAC;QACpE,OAAO,EAAE,MAAM,CAAC,QAAkB;QAClC,MAAM;QACN,UAAU;QACV,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,OAAO,EACL,MAAM,KAAK,EAAE,IAAI,MAAM,CAAC,QAAQ,KAAK,EAAE;YACrC,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;KAC9C,CAAC;AACJ,CAAC"}
@@ -0,0 +1,71 @@
1
+ import { type BlockEvidenceHeader } from "./block-header.js";
2
+ import { type Hash32Hex } from "./read-values.js";
3
+ import { type BoundedReadOptions } from "./bounded-read.js";
4
+ import { type TransactionEvidenceEvent } from "./chain-evidence.js";
5
+ import type { ExchangeHttpTransport } from "./http-transport.js";
6
+ interface BlockResultsBudgets {
7
+ /** Maximum backward-scanned heights, 1..128. Default 32. No partial success. */
8
+ maxHeights?: number;
9
+ /** Caller may reduce these aggregate ceilings, never exceed them. */
10
+ maxDecodedBytes?: number;
11
+ maxTransactions?: number;
12
+ maxEvents?: number;
13
+ maxAttributes?: number;
14
+ }
15
+ export interface BlockResultsWindowSelection extends BlockResultsBudgets {
16
+ /** Fixed half-open wall-clock window, in exact epoch milliseconds. */
17
+ fromMs: number;
18
+ toMs: number;
19
+ /** Explicit last height to inspect; its block time must reach toMs. */
20
+ throughHeight: bigint;
21
+ }
22
+ export interface BlockResultsRangeSelection extends BlockResultsBudgets {
23
+ /** Exact inclusive bounds. No timestamp-based selection or extra boundary block. */
24
+ fromHeight: bigint;
25
+ throughHeight: bigint;
26
+ }
27
+ /** One block transaction and its same-index execution result. */
28
+ export interface BlockTransactionEvidence {
29
+ index: number;
30
+ hash: Hash32Hex;
31
+ signedBytes: Uint8Array;
32
+ code: number;
33
+ events: TransactionEvidenceEvent[];
34
+ }
35
+ export interface BlockResultsEvidence {
36
+ header: BlockEvidenceHeader;
37
+ postAppHash: Hash32Hex;
38
+ /** Every block transaction and its same-index result, including rejections. */
39
+ transactions: BlockTransactionEvidence[];
40
+ /** All system events, including any trades outside user transactions. */
41
+ finalizeBlockEvents: TransactionEvidenceEvent[];
42
+ }
43
+ /** Complete bounded responses from one configured trusted gateway, NOT a
44
+ * validator-signature or cryptographic event proof. Comet's results hash does
45
+ * not include event strings. Node trust remains essential. Height continuity,
46
+ * chain, result counts, times, each block's transaction list against its
47
+ * header `data_hash`, and post-state/header bindings are checked. Block hashes
48
+ * are not recomputed from headers, so a coherently lying gateway is not caught.
49
+ * Range bounds are inclusive; equal and sub-millisecond block times are retained. */
50
+ export interface BlockResultsRange {
51
+ source: "trusted-gateway";
52
+ fromHeight: bigint;
53
+ throughHeight: bigint;
54
+ /** H+1 header binding the final scanned block's post-state hash. */
55
+ anchor: BlockEvidenceHeader;
56
+ /** Ascending heights; no missing or skipped blocks within this range. */
57
+ blocks: BlockResultsEvidence[];
58
+ }
59
+ /** Blocks include the lower-boundary block (before fromMs, or genesis) and may
60
+ * include end-boundary blocks. Consumers must apply [fromMs,toMs) themselves. */
61
+ export interface BlockResultsWindow extends BlockResultsRange {
62
+ fromMs: number;
63
+ toMs: number;
64
+ }
65
+ /** Internal bounded scan. At most 2*maxHeights+1 GETs; each response <=1 MiB,
66
+ * retained decoded JSON <=8 MiB, and all reads share one deadline. */
67
+ export declare function readBlockResultsWindow(gatewayUrl: string, expectedChainId: Uint8Array, selection: BlockResultsWindowSelection, options: BoundedReadOptions, transport: ExchangeHttpTransport): Promise<BlockResultsWindow>;
68
+ /** The same bounded decoder as the window read, selected by inclusive heights. */
69
+ export declare function readBlockResultsRange(gatewayUrl: string, expectedChainId: Uint8Array, selection: BlockResultsRangeSelection, options: BoundedReadOptions, transport: ExchangeHttpTransport): Promise<BlockResultsRange>;
70
+ export {};
71
+ //# sourceMappingURL=block-results-window.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"block-results-window.d.ts","sourceRoot":"","sources":["../src/block-results-window.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EASL,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE,UAAU,mBAAmB;IAC3B,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,2BAA4B,SAAQ,mBAAmB;IACtE,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,0BAA2B,SAAQ,mBAAmB;IACrE,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,iEAAiE;AACjE,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,UAAU,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,wBAAwB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,WAAW,EAAE,SAAS,CAAC;IACvB,+EAA+E;IAC/E,YAAY,EAAE,wBAAwB,EAAE,CAAC;IACzC,yEAAyE;IACzE,mBAAmB,EAAE,wBAAwB,EAAE,CAAC;CACjD;AAED;;;;;;qFAMqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,MAAM,EAAE,mBAAmB,CAAC;IAC5B,yEAAyE;IACzE,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAED;iFACiF;AACjF,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AASD;sEACsE;AACtE,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,UAAU,EAC3B,SAAS,EAAE,2BAA2B,EACtC,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,qBAAqB,GAC/B,OAAO,CAAC,kBAAkB,CAAC,CAmB7B;AAED,kFAAkF;AAClF,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,UAAU,EAC3B,SAAS,EAAE,0BAA0B,EACrC,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,qBAAqB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAS5B"}
@@ -0,0 +1,170 @@
1
+ import { decodeBlockEvidenceHeader, } from "./block-header.js";
2
+ import { hash32, readDeadline, rfc3339, MAX_DATE_MS, } from "./read-values.js";
3
+ import { GatewayReadError } from "./errors.js";
4
+ import { sha256 } from "@noble/hashes/sha2.js";
5
+ import { boundedGatewayJson } from "./bounded-read.js";
6
+ import { I64_MAX, bindBlockTransactions, bytes, events, invalid, object, rpcResult, uint, } from "./chain-evidence.js";
7
+ import { bytesToHex } from "./crypto.js";
8
+ const WINDOW_DEFAULT_HEIGHTS = 32;
9
+ const WINDOW_MAX_HEIGHTS = 128;
10
+ const WINDOW_MAX_DECODED_BYTES = 8 * 1024 * 1024;
11
+ const WINDOW_MAX_TRANSACTIONS = 10_000;
12
+ const WINDOW_MAX_EVENTS = 16_384;
13
+ const WINDOW_MAX_ATTRIBUTES = 65_536;
14
+ /** Internal bounded scan. At most 2*maxHeights+1 GETs; each response <=1 MiB,
15
+ * retained decoded JSON <=8 MiB, and all reads share one deadline. */
16
+ export async function readBlockResultsWindow(gatewayUrl, expectedChainId, selection, options, transport) {
17
+ const { fromMs, toMs } = selection;
18
+ const range = await readBlockResults(gatewayUrl, expectedChainId, selection, { kind: "window", fromMs, toMs }, options, transport);
19
+ return {
20
+ source: range.source,
21
+ fromMs,
22
+ toMs,
23
+ fromHeight: range.fromHeight,
24
+ throughHeight: range.throughHeight,
25
+ anchor: range.anchor,
26
+ blocks: range.blocks,
27
+ };
28
+ }
29
+ /** The same bounded decoder as the window read, selected by inclusive heights. */
30
+ export async function readBlockResultsRange(gatewayUrl, expectedChainId, selection, options, transport) {
31
+ return readBlockResults(gatewayUrl, expectedChainId, selection, { kind: "range", fromHeight: selection.fromHeight }, options, transport);
32
+ }
33
+ async function readBlockResults(gatewayUrl, expectedChainId, selection, boundary, options, transport) {
34
+ const { throughHeight } = selection;
35
+ const deadline = readDeadline(options);
36
+ const budget = (value, ceiling, field) => {
37
+ const n = value ?? ceiling;
38
+ if (!Number.isSafeInteger(n) || n < 1 || n > ceiling)
39
+ throw new GatewayReadError("configuration", field);
40
+ return n;
41
+ };
42
+ const maxHeights = budget(selection.maxHeights ?? WINDOW_DEFAULT_HEIGHTS, WINDOW_MAX_HEIGHTS, `${boundary.kind} heights`);
43
+ const maxBytes = budget(selection.maxDecodedBytes, WINDOW_MAX_DECODED_BYTES, `${boundary.kind} bytes`);
44
+ const maxTransactions = budget(selection.maxTransactions, WINDOW_MAX_TRANSACTIONS, `${boundary.kind} transactions`);
45
+ const maxEvents = budget(selection.maxEvents, WINDOW_MAX_EVENTS, `${boundary.kind} events`);
46
+ const maxAttributes = budget(selection.maxAttributes, WINDOW_MAX_ATTRIBUTES, `${boundary.kind} attributes`);
47
+ if (boundary.kind === "window" &&
48
+ (!Number.isSafeInteger(boundary.fromMs) ||
49
+ boundary.fromMs < 0 ||
50
+ !Number.isSafeInteger(boundary.toMs) ||
51
+ boundary.toMs <= boundary.fromMs ||
52
+ boundary.toMs > MAX_DATE_MS))
53
+ invalid("fixed window");
54
+ if (typeof throughHeight !== "bigint" ||
55
+ throughHeight < 1n ||
56
+ throughHeight >= I64_MAX)
57
+ invalid("through height");
58
+ if (boundary.kind === "range") {
59
+ if (typeof boundary.fromHeight !== "bigint" ||
60
+ boundary.fromHeight < 1n ||
61
+ boundary.fromHeight > throughHeight)
62
+ invalid("from height");
63
+ if (throughHeight - boundary.fromHeight + 1n > BigInt(maxHeights))
64
+ invalid("height budget", "limit");
65
+ }
66
+ if (!(expectedChainId instanceof Uint8Array) || expectedChainId.length !== 32)
67
+ invalid("pinned chain");
68
+ const chain = Uint8Array.from(expectedChainId);
69
+ const base = gatewayUrl.replace(/\/+$/, "");
70
+ let decodedBytes = 0;
71
+ let transactionCount = 0;
72
+ let eventCount = 0;
73
+ let attributeCount = 0;
74
+ const read = async (path) => {
75
+ const raw = await boundedGatewayJson(`${base}${path}`, transport, deadline.remaining());
76
+ decodedBytes += new TextEncoder().encode(JSON.stringify(raw)).length;
77
+ if (decodedBytes > maxBytes)
78
+ invalid(`${boundary.kind} byte budget`, "limit");
79
+ deadline.remaining();
80
+ return rpcResult(raw);
81
+ };
82
+ const decodeEvents = (value) => {
83
+ // Enforce the remaining aggregate budget before allocating decoded lists.
84
+ // A busy block must not inherit the single-transaction evidence limits.
85
+ const decoded = events(value, {
86
+ maxEvents: maxEvents - eventCount,
87
+ maxAttributes: maxAttributes - attributeCount,
88
+ });
89
+ eventCount += decoded.length;
90
+ attributeCount += decoded.reduce((total, event) => total + (event.attributes?.length ?? 0), 0);
91
+ return decoded;
92
+ };
93
+ const anchor = decodeBlockEvidenceHeader(await read(`/v1/block?height=${throughHeight + 1n}`), throughHeight + 1n, chain);
94
+ const fromNs = boundary.kind === "window" ? BigInt(boundary.fromMs) * 1000000n : null;
95
+ const toNs = boundary.kind === "window" ? BigInt(boundary.toMs) * 1000000n : null;
96
+ const blocks = [];
97
+ let next = anchor;
98
+ for (let height = throughHeight; blocks.length < maxHeights && height >= 1n; height--) {
99
+ const response = await read(`/v1/block?height=${height}`);
100
+ const header = decodeBlockEvidenceHeader(response, height, chain);
101
+ if (next.parentHash !== header.hash)
102
+ invalid("parent hash continuity");
103
+ if (rfc3339(header.time).nanos > rfc3339(next.time).nanos)
104
+ invalid("block time continuity");
105
+ if (height === throughHeight &&
106
+ toNs !== null &&
107
+ rfc3339(header.time).nanos < toNs)
108
+ invalid("source has not reached window end");
109
+ const rawTransactions = object(object(response.block, "block").data, "block data").txs;
110
+ // Go's non-omitempty slices encode a genuine empty list as null or [].
111
+ if (rawTransactions !== null && !Array.isArray(rawTransactions))
112
+ invalid("block transactions");
113
+ const txs = (rawTransactions ?? []);
114
+ transactionCount += txs.length;
115
+ if (transactionCount > maxTransactions)
116
+ invalid(`${boundary.kind} transaction budget`, "limit");
117
+ const blockTransactions = txs.map((value) => bytes(value, "block transaction bytes"));
118
+ bindBlockTransactions(response, blockTransactions);
119
+ const result = await read(`/v1/block_results?height=${height}`);
120
+ if (uint(result.height, I64_MAX, "results height") !== height)
121
+ invalid("results height mismatch", "binding");
122
+ if (result.txs_results !== null && !Array.isArray(result.txs_results))
123
+ invalid("transaction results");
124
+ const txResults = (result.txs_results ?? []);
125
+ if (txResults.length !== txs.length)
126
+ invalid("transaction result count");
127
+ if (result.finalize_block_events !== null &&
128
+ !Array.isArray(result.finalize_block_events))
129
+ invalid("finalize block events");
130
+ const postState = bytes(result.app_hash, "results app hash");
131
+ if (postState.length !== 32)
132
+ invalid("results app hash length");
133
+ const postAppHash = hash32(bytesToHex(postState), "results app hash");
134
+ if (next.appHash === null || postAppHash !== next.appHash)
135
+ invalid("post-state/header binding");
136
+ const transactions = blockTransactions.map((signedBytes, index) => {
137
+ const execution = object(txResults[index], "transaction result");
138
+ return {
139
+ index,
140
+ hash: hash32(bytesToHex(sha256(signedBytes))),
141
+ signedBytes,
142
+ code: Number(uint(execution.code === undefined ? 0 : execution.code, 0xffffffffn, "execution code")),
143
+ events: decodeEvents(execution.events),
144
+ };
145
+ });
146
+ blocks.push({
147
+ header,
148
+ postAppHash,
149
+ transactions,
150
+ finalizeBlockEvents: decodeEvents(result.finalize_block_events ?? []),
151
+ });
152
+ deadline.remaining();
153
+ const complete = boundary.kind === "range"
154
+ ? height === boundary.fromHeight
155
+ : (fromNs !== null && rfc3339(header.time).nanos < fromNs) ||
156
+ height === 1n;
157
+ if (complete) {
158
+ return {
159
+ source: "trusted-gateway",
160
+ fromHeight: height,
161
+ throughHeight,
162
+ anchor,
163
+ blocks: blocks.reverse(),
164
+ };
165
+ }
166
+ next = header;
167
+ }
168
+ throw new GatewayReadError("limit", "height budget", `Block-results ${boundary.kind} exceeds height budget; no complete ${boundary.kind} available`);
169
+ }
170
+ //# sourceMappingURL=block-results-window.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"block-results-window.js","sourceRoot":"","sources":["../src/block-results-window.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,47 @@
1
+ import { type Hash32Hex } from "./read-values.js";
2
+ import { type ExchangeHttpTransport } from "./http-transport.js";
3
+ /** Deadline covers queueing, headers and the entire bounded response body. */
4
+ export interface BoundedReadOptions {
5
+ signal?: AbortSignal;
6
+ /** Default 5 seconds, matching existing reads; explicit maximum 60 seconds. */
7
+ timeoutMs?: number;
8
+ }
9
+ /** The gateway's assertion of the finalized state a read was served from, NOT
10
+ * validator signatures or a cryptographic event proof. How far a payload is
11
+ * checked against it varies per read: some payloads carry no height or owner
12
+ * to compare, and then the gateway's word is the only binding. verifyWitness
13
+ * binds the height and app hash to a chain-qualified H+1 header, which proves
14
+ * nothing beyond the gateway's word when that header came from the same
15
+ * gateway. This is not freshness, solvency, or authorization to trade. */
16
+ export interface FinalizedReadWitness {
17
+ version: 1;
18
+ nodeId: string;
19
+ height: bigint;
20
+ finalizedBlockTimeMs: bigint;
21
+ appHash: Hash32Hex;
22
+ }
23
+ export declare function decodeFinalizedReadWitness(value: unknown, expectedHeight?: bigint, expectedTimeMs?: bigint): FinalizedReadWitness;
24
+ /** Run a decoder that throws plain `Error`s, re-throwing them as a malformed
25
+ * `GatewayReadError` with the same message so callers can branch on `kind`. */
26
+ export declare function asReadError<T>(field: string, decode: () => T): T;
27
+ /** Compare a witness with an H+1 header. The check is only as strong as the
28
+ * header's source: `reads().evidence.blockHeader` asks the same gateway that
29
+ * served the witness and does not check validator signatures, so pairing the
30
+ * two shows the gateway is self-consistent, not that the state is authentic.
31
+ * H+1's timestamp is NOT H's timestamp, so it is deliberately not compared. */
32
+ export declare function verifyWitness(witness: FinalizedReadWitness, nextHeader: {
33
+ height: bigint;
34
+ chainId: string;
35
+ appHash: string | null;
36
+ }, chainId: string | Uint8Array): void;
37
+ export declare function parseBoundedJson(text: string): unknown;
38
+ /** Transport lane, plus setup that must finish inside the same deadline. */
39
+ export interface BoundedReadRequest {
40
+ /** Owner-scoped reads take the account lane, like the unwitnessed reads. */
41
+ purpose?: "account" | "query";
42
+ /** Awaited after the deadline and cancellation are armed, e.g. `ready()`. */
43
+ prepare?: () => Promise<void>;
44
+ }
45
+ /** Internal one-shot SDK read. No retry, alternate endpoint or cached fallback. */
46
+ export declare function boundedGatewayJson(url: string, transport: ExchangeHttpTransport, options: BoundedReadOptions, request?: BoundedReadRequest): Promise<unknown>;
47
+ //# sourceMappingURL=bounded-read.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bounded-read.d.ts","sourceRoot":"","sources":["../src/bounded-read.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAe,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE9E,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AACD;;;;;;0EAM0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB,EAAE,MAAM,CAAC;IAC7B,OAAO,EAAE,SAAS,CAAC;CACpB;AACD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,cAAc,CAAC,EAAE,MAAM,EACvB,cAAc,CAAC,EAAE,MAAM,GACtB,oBAAoB,CAiDtB;AACD;+EAC+E;AAC/E,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAYhE;AACD;;;;+EAI+E;AAC/E,wBAAgB,aAAa,CAC3B,OAAO,EAAE,oBAAoB,EAC7B,UAAU,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACvE,OAAO,EAAE,MAAM,GAAG,UAAU,GAC3B,IAAI,CAyCN;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAqCtD;AAED,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AA8BD,mFAAmF;AACnF,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,qBAAqB,EAChC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,OAAO,CAAC,CAiLlB"}