@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.
- package/README.md +11 -15
- package/dist/block-header.d.ts +13 -0
- package/dist/block-header.d.ts.map +1 -0
- package/dist/block-header.js +29 -0
- package/dist/block-header.js.map +1 -0
- package/dist/block-results-window.d.ts +71 -0
- package/dist/block-results-window.d.ts.map +1 -0
- package/dist/block-results-window.js +170 -0
- package/dist/block-results-window.js.map +1 -0
- package/dist/bounded-read.d.ts +47 -0
- package/dist/bounded-read.d.ts.map +1 -0
- package/dist/bounded-read.js +288 -0
- package/dist/bounded-read.js.map +1 -0
- package/dist/chain-evidence.d.ts +37 -0
- package/dist/chain-evidence.d.ts.map +1 -0
- package/dist/chain-evidence.js +123 -0
- package/dist/chain-evidence.js.map +1 -0
- package/dist/client.d.ts +3 -2
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +3 -4
- package/dist/client.js.map +1 -1
- package/dist/codec-adapter.d.ts +0 -2
- package/dist/codec-adapter.d.ts.map +1 -1
- package/dist/codec-adapter.js +4 -23
- package/dist/codec-adapter.js.map +1 -1
- package/dist/committed-transaction.d.ts +34 -0
- package/dist/committed-transaction.d.ts.map +1 -0
- package/dist/committed-transaction.js +58 -0
- package/dist/committed-transaction.js.map +1 -0
- package/dist/errors.d.ts +16 -9
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +45 -32
- package/dist/errors.js.map +1 -1
- package/dist/finalized-account-reads.d.ts +75 -0
- package/dist/finalized-account-reads.d.ts.map +1 -0
- package/dist/finalized-account-reads.js +199 -0
- package/dist/finalized-account-reads.js.map +1 -0
- package/dist/finalized-oracle-read.d.ts +10 -0
- package/dist/finalized-oracle-read.d.ts.map +1 -0
- package/dist/finalized-oracle-read.js +25 -0
- package/dist/finalized-oracle-read.js.map +1 -0
- package/dist/finalized-orderbook.d.ts +23 -0
- package/dist/finalized-orderbook.d.ts.map +1 -0
- package/dist/finalized-orderbook.js +92 -0
- package/dist/finalized-orderbook.js.map +1 -0
- package/dist/finalized-state-reads.d.ts +21 -0
- package/dist/finalized-state-reads.d.ts.map +1 -0
- package/dist/finalized-state-reads.js +66 -0
- package/dist/finalized-state-reads.js.map +1 -0
- package/dist/financial-state.d.ts.map +1 -1
- package/dist/financial-state.js +12 -56
- package/dist/financial-state.js.map +1 -1
- package/dist/governance-query.d.ts.map +1 -1
- package/dist/governance-query.js +0 -1
- package/dist/governance-query.js.map +1 -1
- package/dist/index.d.ts +13 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -1
- package/dist/index.js.map +1 -1
- package/dist/market-snapshot.d.ts +3 -0
- package/dist/market-snapshot.d.ts.map +1 -1
- package/dist/market-snapshot.js +16 -38
- package/dist/market-snapshot.js.map +1 -1
- package/dist/oracle-permissions.d.ts +14 -30
- package/dist/oracle-permissions.d.ts.map +1 -1
- package/dist/oracle-permissions.js +29 -65
- package/dist/oracle-permissions.js.map +1 -1
- package/dist/read-values.d.ts +49 -0
- package/dist/read-values.d.ts.map +1 -0
- package/dist/read-values.js +88 -0
- package/dist/read-values.js.map +1 -0
- package/dist/trade-history.d.ts +50 -0
- package/dist/trade-history.d.ts.map +1 -0
- package/dist/trade-history.js +135 -0
- package/dist/trade-history.js.map +1 -0
- package/dist/typed-gateway-reads.d.ts +58 -0
- package/dist/typed-gateway-reads.d.ts.map +1 -0
- package/dist/typed-gateway-reads.js +98 -0
- package/dist/typed-gateway-reads.js.map +1 -0
- package/dist/types.d.ts +29 -83
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +8 -12
- package/dist/types.js.map +1 -1
- package/dist/wasm/proof_trading_sdk_wasm_bg.wasm +0 -0
- package/package.json +1 -6
- package/dist/testing.d.ts +0 -16
- package/dist/testing.d.ts.map +0 -1
- package/dist/testing.js +0 -21
- 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
|
|
234
|
-
|
|
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
|
-
|
|
239
|
-
|
|
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.
|
|
243
|
-
`
|
|
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-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
operator-provisioned key. See [AGENTS.md](AGENTS.md) → "Operator actions"
|
|
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"}
|