og-fe-tee-verification 0.0.1

package/README.md

@@ -0,0 +1,97 @@
+# og-fe-settlement-verify
+
+A small frontend-friendly client for fetching Walrus blobs from the Sui Core aggregator.
+
+## Installation
+
+```bash
+pnpm install og-fe-settlement-verify
+```
+
+## Quick Start
+
+```ts
+import { fetchWalrusBlobText } from "og-fe-settlement-verify";
+
+const blobText = await fetchWalrusBlobText("your-walrus-blob-id");
+console.log(blobText);
+```
+
+## API
+
+### `getWalrusBlobUrl(blobId, options?)`
+
+Builds the aggregator URL for a blob ID.
+
+### `fetchWalrusBlob(blobId, options?)`
+
+Fetches the raw blob `Response`.
+
+### `fetchWalrusBlobBytes(blobId, options?)`
+
+Fetches the blob and returns an `ArrayBuffer`.
+
+### `fetchWalrusBlobText(blobId, options?)`
+
+Fetches the blob and returns a string.
+
+### `fetchWalrusBlobJson<T>(blobId, options?)`
+
+Fetches the blob and parses the body as JSON.
+
+### `fetchWalrusBatchTree(blobId, options?)`
+
+Fetches a batch Merkle tree blob and returns the decoded items for UI use.
+
+### `DEFAULT_WALRUS_VERIFIER_CONTRACT_ADDRESS`
+
+The default verifier contract address:
+`0xa06dAFA3D713b74e4e1E74B34bd1588C9FD6C290`
+
+### `DEFAULT_WALRUS_RPC_URL`
+
+The default RPC URL:
+`https://ogevmdevnet.opengradient.ai`
+
+### `verifyWalrusBatchTreeItemSignature(args)`
+
+Calls `verifySignatureNoTimestamp(teeId, inputHash, outputHash, timestamp, signature)` for a
+single batch item. `args.verifierContractAddress` is optional and defaults to
+`DEFAULT_WALRUS_VERIFIER_CONTRACT_ADDRESS`.
+
+### `verifyWalrusBatchTreeSignatures(args)`
+
+Runs `verifySignatureNoTimestamp(...)` for every item in a fetched Walrus batch tree.
+`args.verifierContractAddress` is optional and defaults to
+`DEFAULT_WALRUS_VERIFIER_CONTRACT_ADDRESS`.
+
+### `createWalrusClient(options?)`
+
+Creates a reusable client with a shared base URL and fetch implementation.
+
+## Example
+
+```ts
+import { createWalrusClient } from "og-fe-settlement-verify";
+
+const walrus = createWalrusClient({
+  baseUrl: "https://aggregator.suicore.com",
+});
+
+const imageBytes = await walrus.fetchBlobBytes("your-walrus-blob-id");
+```
+
+## Batch Tree Notes
+
+- The current facilitator batch tree stores raw `tee_signature` bytes in each leaf.
+- That means the UI can call onchain `verifySignatureNoTimestamp(...)` directly for every item in
+  the blob.
+- The current batch leaf order is `tee_id, input_hash, output_hash, tee_signature, tee_timestamp`.
+
+## Notes
+
+- The default aggregator is `https://aggregator.suicore.com`.
+- The default verifier contract is `0xa06dAFA3D713b74e4e1E74B34bd1588C9FD6C290`.
+- The default RPC URL is `https://ogevmdevnet.opengradient.ai`.
+- Walrus aggregators return the raw blob bytes from `GET /v1/blobs/<blob-id>`.
+- Blob IDs are URL-encoded before the request is made.

package/dist/cjs/index.d.ts

@@ -0,0 +1,230 @@
+import { StandardMerkleTree } from '@openzeppelin/merkle-tree';
+import { Hex } from 'viem';
+
+declare const DEFAULT_WALRUS_AGGREGATOR_URL = "https://aggregator.suicore.com";
+declare const DEFAULT_WALRUS_VERIFIER_CONTRACT_ADDRESS: Hex;
+declare const DEFAULT_WALRUS_RPC_URL = "https://ogevmdevnet.opengradient.ai";
+declare const WALRUS_BATCH_LEAF_ENCODING: readonly ["bytes32", "bytes32", "bytes32", "bytes", "uint256"];
+declare const verifierContractAbi: readonly [{
+    readonly type: "function";
+    readonly name: "verifySignatureNoTimestamp";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "teeId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "inputHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "outputHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "timestamp";
+        readonly type: "uint256";
+    }, {
+        readonly name: "signature";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}];
+/**
+ * Shared client options for Walrus blob requests.
+ */
+interface WalrusClientOptions {
+    /**
+     * Base aggregator URL.
+     *
+     * @defaultValue "https://aggregator.suicore.com"
+     */
+    baseUrl?: string;
+    /**
+     * Fetch implementation to use. Defaults to `globalThis.fetch`.
+     */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Request options for blob fetches.
+ */
+interface FetchWalrusBlobOptions extends Omit<RequestInit, "body" | "method">, WalrusClientOptions {
+}
+type WalrusBatchLeafTuple = [Hex, Hex, Hex, Hex, string];
+type WalrusBatchTreeDump = {
+    format: "standard-v1";
+    leafEncoding: string[];
+    tree: Hex[];
+    values: Array<{
+        value: WalrusBatchLeafTuple;
+        treeIndex: number;
+        hash: Hex;
+    }>;
+};
+type WalrusBatchTreeItem = {
+    index: number;
+    tee_id: Hex;
+    input_hash: Hex;
+    output_hash: Hex;
+    tee_signature: Hex;
+    tee_timestamp: string;
+    tuple: WalrusBatchLeafTuple;
+};
+type LoadedWalrusBatchTree = {
+    blobId: string;
+    merkleRoot: Hex;
+    tree: StandardMerkleTree<WalrusBatchLeafTuple>;
+    dump: WalrusBatchTreeDump;
+    items: WalrusBatchTreeItem[];
+};
+type WalrusSignatureEncoding = "auto" | "hex" | "utf8" | "base64";
+type WalrusSignatureVerificationClient = {
+    readContract(args: {
+        address: Hex;
+        abi: typeof verifierContractAbi;
+        functionName: "verifySignatureNoTimestamp";
+        args: readonly [Hex, Hex, Hex, bigint, Hex];
+    }): Promise<boolean>;
+};
+type VerifyWalrusBatchTreeItemSignatureArgs = {
+    item: WalrusBatchTreeItem;
+    verifierContractAddress?: Hex;
+    publicClient: WalrusSignatureVerificationClient;
+};
+type VerifyWalrusBatchTreeSignaturesArgs = {
+    blobId?: string;
+    tree?: LoadedWalrusBatchTree;
+    verifierContractAddress?: Hex;
+    publicClient: WalrusSignatureVerificationClient;
+    aggregatorUrl?: string;
+    fetch?: typeof globalThis.fetch;
+};
+type WalrusBatchTreeItemVerification = {
+    item: WalrusBatchTreeItem;
+    verified: boolean | null;
+    error?: string;
+};
+type WalrusBatchTreeVerificationResult = {
+    blobId: string;
+    merkleRoot: Hex;
+    results: WalrusBatchTreeItemVerification[];
+};
+/**
+ * Thrown when a Walrus blob request fails.
+ */
+declare class WalrusBlobFetchError extends Error {
+    readonly blobId: string;
+    readonly status: number;
+    readonly statusText: string;
+    readonly url: string;
+    /**
+     * Creates a new Walrus blob fetch error.
+     *
+     * @param blobId - The blob ID that was requested.
+     * @param response - The failed HTTP response.
+     * @param url - The resolved blob URL.
+     */
+    constructor(blobId: string, response: Response, url: string);
+}
+/**
+ * Type guard for Walrus blob fetch errors.
+ *
+ * @param error - Unknown thrown value.
+ * @returns Whether the value is a WalrusBlobFetchError.
+ */
+declare function isWalrusBlobFetchError(error: unknown): error is WalrusBlobFetchError;
+/**
+ * Builds the Sui Core aggregator URL for a Walrus blob ID.
+ *
+ * @param blobId - Walrus blob ID.
+ * @param options - Optional URL settings.
+ * @returns The full blob URL.
+ */
+declare function getWalrusBlobUrl(blobId: string, options?: Pick<WalrusClientOptions, "baseUrl">): string;
+/**
+ * Fetches a Walrus blob and returns the raw HTTP response.
+ *
+ * @param blobId - Walrus blob ID.
+ * @param options - Optional request configuration.
+ * @returns The successful blob response.
+ */
+declare function fetchWalrusBlob(blobId: string, options?: FetchWalrusBlobOptions): Promise<Response>;
+/**
+ * Fetches a Walrus blob and returns its bytes.
+ *
+ * @param blobId - Walrus blob ID.
+ * @param options - Optional request configuration.
+ * @returns The blob bytes.
+ */
+declare function fetchWalrusBlobBytes(blobId: string, options?: FetchWalrusBlobOptions): Promise<ArrayBuffer>;
+/**
+ * Fetches a Walrus blob and returns its text content.
+ *
+ * @param blobId - Walrus blob ID.
+ * @param options - Optional request configuration.
+ * @returns The blob body as text.
+ */
+declare function fetchWalrusBlobText(blobId: string, options?: FetchWalrusBlobOptions): Promise<string>;
+/**
+ * Fetches a Walrus blob and parses it as JSON.
+ *
+ * @param blobId - Walrus blob ID.
+ * @param options - Optional request configuration.
+ * @returns The parsed JSON payload.
+ */
+declare function fetchWalrusBlobJson<T>(blobId: string, options?: FetchWalrusBlobOptions): Promise<T>;
+/**
+ * Fetches and parses a Walrus batch Merkle tree blob.
+ *
+ * @param blobId - Walrus batch blob ID.
+ * @param options - Optional request configuration.
+ * @returns The loaded tree plus decoded batch items.
+ */
+declare function fetchWalrusBatchTree(blobId: string, options?: FetchWalrusBlobOptions): Promise<LoadedWalrusBatchTree>;
+/**
+ * Parses a Walrus batch Merkle tree payload into strongly typed items.
+ *
+ * @param blobId - Walrus batch blob ID.
+ * @param dump - Raw tree dump JSON.
+ * @returns The loaded tree plus decoded batch items.
+ */
+declare function parseWalrusBatchTree(blobId: string, dump: WalrusBatchTreeDump): LoadedWalrusBatchTree;
+/**
+ * Encodes a raw tee signature into bytes calldata for the onchain verifySignatureNoTimestamp call.
+ *
+ * @param signature - Raw signature value.
+ * @param encoding - Signature encoding strategy.
+ * @returns Encoded bytes calldata.
+ */
+declare function encodeWalrusSignature(signature: string, encoding?: WalrusSignatureEncoding): Hex;
+/**
+ * Calls verifySignatureNoTimestamp for a single Walrus batch item.
+ *
+ * @param args - Verification inputs for one batch item.
+ * @returns Whether the onchain verifySignatureNoTimestamp call returned true.
+ */
+declare function verifyWalrusBatchTreeItemSignature(args: VerifyWalrusBatchTreeItemSignatureArgs): Promise<boolean>;
+/**
+ * Calls verifySignatureNoTimestamp for every item in a Walrus batch tree.
+ *
+ * @param args - Verification inputs for the whole Walrus batch tree.
+ * @returns Per-item verification results.
+ */
+declare function verifyWalrusBatchTreeSignatures(args: VerifyWalrusBatchTreeSignaturesArgs): Promise<WalrusBatchTreeVerificationResult>;
+/**
+ * Creates a reusable Walrus client.
+ *
+ * @param options - Shared client options.
+ * @returns Bound Walrus helper methods.
+ */
+declare function createWalrusClient(options?: WalrusClientOptions): {
+    getBlobUrl(blobId: string): string;
+    fetchBlob(blobId: string, requestInit?: FetchWalrusBlobOptions): Promise<Response>;
+    fetchBlobBytes(blobId: string, requestInit?: FetchWalrusBlobOptions): Promise<ArrayBuffer>;
+    fetchBlobText(blobId: string, requestInit?: FetchWalrusBlobOptions): Promise<string>;
+    fetchBlobJson<T>(blobId: string, requestInit?: FetchWalrusBlobOptions): Promise<T>;
+    fetchBatchTree(blobId: string, requestInit?: FetchWalrusBlobOptions): Promise<LoadedWalrusBatchTree>;
+    verifyBatchTreeSignatures(args: Omit<VerifyWalrusBatchTreeSignaturesArgs, "blobId" | "fetch">): Promise<WalrusBatchTreeVerificationResult>;
+};
+
+export { DEFAULT_WALRUS_AGGREGATOR_URL, DEFAULT_WALRUS_RPC_URL, DEFAULT_WALRUS_VERIFIER_CONTRACT_ADDRESS, type FetchWalrusBlobOptions, type LoadedWalrusBatchTree, type VerifyWalrusBatchTreeItemSignatureArgs, type VerifyWalrusBatchTreeSignaturesArgs, WALRUS_BATCH_LEAF_ENCODING, type WalrusBatchLeafTuple, type WalrusBatchTreeDump, type WalrusBatchTreeItem, type WalrusBatchTreeItemVerification, type WalrusBatchTreeVerificationResult, WalrusBlobFetchError, type WalrusClientOptions, type WalrusSignatureEncoding, type WalrusSignatureVerificationClient, createWalrusClient, encodeWalrusSignature, fetchWalrusBatchTree, fetchWalrusBlob, fetchWalrusBlobBytes, fetchWalrusBlobJson, fetchWalrusBlobText, getWalrusBlobUrl, isWalrusBlobFetchError, parseWalrusBatchTree, verifyWalrusBatchTreeItemSignature, verifyWalrusBatchTreeSignatures };