@mikeargento/bitgraph-audit 0.7.0 → 0.8.0

package/dist/settlement-blobs.d.ts

@@ -0,0 +1,131 @@
+import { type SettlementPointer } from "@mikeargento/bitgraph-verify";
+/** Base mainnet: block number = (timestamp - l2GenesisTime) / blockTime. */
+export declare const BASE_MAINNET_ROLLUP: Readonly<{
+    l2GenesisTime: 1686789347;
+    blockTime: 2;
+}>;
+export declare const BLOB_BYTES = 131072;
+/** OP Stack blob encoding version 0: (4 * 31 + 3) * 1024 - 4 bytes of data per blob. */
+export declare const MAX_BLOB_DATA_BYTES = 130044;
+export interface SettlementBlobsCheck {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+export interface SettlementLocated {
+    /** The Base block the batch places the transaction in, read from the batch's timestamp. */
+    baseBlockNumber: number;
+    baseBlockTimestamp: number;
+    /** The batch's parent_hash (the hash of the block before), when the batch form carries one. */
+    baseParentHash: string | null;
+    /** Index in the batch's transaction_list: the block's non-deposit transactions, in order. */
+    baseTxIndex: number;
+    txHash: string;
+    /** The transaction's exact bytes as the batch carries them, 0x hex. */
+    rawTx: string;
+    /** Whether the batch holding the block was complete in the decoded bytes (false past the end of a frame prefix). */
+    batchComplete: boolean;
+}
+export interface SettlementBlobsResult {
+    ok: boolean;
+    reason?: string;
+    checks: SettlementBlobsCheck[];
+    /** What was decoded: frames 0..framesDecoded-1 of the channel, whole or as a prefix. */
+    channel?: {
+        id: string;
+        framesDecoded: number;
+        /** The channel's frame count when known (complete, or stated by the pointer). */
+        framesTotal: number | null;
+        complete: boolean;
+        compression: "brotli" | "zlib";
+        decodedBytes: number;
+        /** Base blocks whose batches were complete in the decoded bytes. */
+        baseBlocks: number[];
+    };
+    located?: SettlementLocated;
+}
+export interface SettlementBlobsOptions {
+    /** How the rollup turns a batch timestamp into a block number. Base mainnet by default. */
+    rollup?: {
+        l2GenesisTime: number;
+        blockTime: number;
+    };
+    /** The L2 chain id, for rebuilding transactions out of span batches. Base mainnet by default. */
+    chainId?: bigint;
+    /** What the ceiling record says, each matched against what the batch says when given. */
+    expect?: {
+        /** The ceiling transaction to locate (else the pointer's `located.txHash`). */
+        txHash?: string;
+        /** Its exact bytes, 0x hex. */
+        rawTx?: string;
+        /** The Base block's parent hash, from the ceiling's carried header. */
+        baseParentHash?: string;
+    };
+}
+/**
+ * The data a blob carries: 4 field elements per round, each a 6-bit byte
+ * and 31 data bytes, the first round's first element holding the version
+ * and a 24-bit length. Padding past the length must be zero. A field
+ * element with its top two bits set is not a blob this encoding produced.
+ */
+export declare function decodeOpBlob(blob: Uint8Array): Uint8Array;
+export interface ChannelFrame {
+    channelId: string;
+    frameNumber: number;
+    frameData: Uint8Array;
+    isLast: boolean;
+}
+/** Frames out of a blob's data: derivation version 0, then channel_id(16) frame_number(2) length(4) data is_last(1), repeated. */
+export declare function parseFrames(data: Uint8Array): ChannelFrame[];
+export declare function decompressChannel(data: Uint8Array, complete: boolean): {
+    compression: "brotli" | "zlib";
+    bytes: Uint8Array;
+};
+export interface BatchTx {
+    raw: Uint8Array;
+    hash: string;
+}
+export interface DecodedBatch {
+    /** 0 singular, 1 span. */
+    type: number;
+    /** Offset of the batch's RLP item in the decompressed channel. */
+    offset: number;
+    /** Base blocks in this batch. A cut singular batch has one block with the transactions read so far. */
+    blocks: Array<{
+        number: number;
+        timestamp: number;
+        parentHash: string | null;
+        txs: BatchTx[];
+        complete: boolean;
+    }>;
+}
+/**
+ * Batches out of a decompressed channel. Each is an RLP byte string
+ * `batch_version ++ content`. When `complete` is false the stream may be cut:
+ * the last batch is then read as far as it goes and marked incomplete.
+ */
+export declare function decodeBatches(channel: Uint8Array, complete: boolean, rollup: {
+    l2GenesisTime: number;
+    blockTime: number;
+}, chainId: bigint): DecodedBatch[];
+/**
+ * A span batch (OP Stack Delta): prefix (rel_timestamp, l1_origin_num,
+ * parent_check, l1_origin_check) then payload (block_count, origin_bits,
+ * block_tx_counts, txs). Transactions are stored by column (signatures,
+ * recipients, data, nonces, gas limits, protected bits) and are rebuilt
+ * here into their raw form so they can be hashed.
+ */
+export declare function decodeSpanBatch(data: Uint8Array, rollup: {
+    l2GenesisTime: number;
+    blockTime: number;
+}, chainId: bigint): DecodedBatch["blocks"];
+/**
+ * Verify blob bytes against a settlement pointer and locate the ceiling
+ * transaction inside them. `blobBytesByVersionedHash` holds the bytes the
+ * caller has (keyed by 0x hex versioned hash, any case); blobs the pointer
+ * lists without bytes are skipped, and the channel is decoded from the
+ * frames that are present, as a whole when they are all there and as a
+ * prefix otherwise. Every check runs in order; the first failure is `reason`.
+ */
+export declare function verifySettlementBlobs(pointer: SettlementPointer, blobBytesByVersionedHash: ReadonlyMap<string, Uint8Array>, options?: SettlementBlobsOptions): Promise<SettlementBlobsResult>;
+//# sourceMappingURL=settlement-blobs.d.ts.map

package/dist/settlement-blobs.d.ts.map

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