docs(flashtestations-sdk): prepare SDK for initial public release wit… (#427)

Author: Melvillian

sdks/flashtestations-sdk/.gitignore

@@ -2,3 +2,5 @@
 .DS_Store
 node_modules
 dist
+
+.claude-output/

sdks/flashtestations-sdk/README.md

@@ -1,29 +1,22 @@
-import { createRpcClient } from '../src/rpc/client';
+import { getFlashtestationEvent } from '../src/index';
 
 /**
- * Example: Check if a transaction is a flashtestation transaction
+ * Example: Check if a block contains a flashtestation transaction
  *
  * This example demonstrates how to:
- * 1. Create an RPC client for Unichain Sepolia (chain ID 1301)
- * 2. Check if a transaction emitted the BlockBuilderProofVerified event
- * 3. Retrieve the full transaction data if it's a flashtestation transaction
- * 4. Handle the case where the transaction is not a flashtestation
+ * 1. Use the getFlashtestationEvent function to fetch flashtestation data from a block
+ * 2. Retrieve the full flashtestation event data if present
+ * 3. Handle the case where the block does not contain a flashtestation transaction
  */
 async function main() {
   try {
-    // Create RPC client for Unichain Sepolia (chain ID 1301)
-    const client = createRpcClient({
+    // Fetch flashtestation transaction from the latest block on Unichain Sepolia
+    const tx = await getFlashtestationEvent('latest', {
       chainId: 1301, // Unichain Sepolia testnet
       // Optional: provide custom RPC URL
       // rpcUrl: 'https://sepolia.unichain.org',
-      // Optional: configure retry behavior
-      // maxRetries: 3,
-      // initialRetryDelay: 1000,
     });
 
-    // Check if this transaction is a flashtestation
-    const tx = await client.getFlashtestationTx('latest');
-
     if (tx) {
       // This is a flashtestation transaction
       console.log('\n✓ This is a flashtestation transaction!\n');
@@ -37,10 +30,8 @@ async function main() {
       console.log(`Source Locators: ${tx.sourceLocators.length > 0 ? tx.sourceLocators.join(', ') : 'None'}`);
     } else {
       // This is not a flashtestation transaction
-      console.log('\n✗ This is not a flashtestation transaction.');
-      console.log('\nThe transaction either:');
-      console.log('  1. Does not exist');
-      console.log('  2. Did not emit the BlockBuilderProofVerified event');
+      console.log('\n✗ This is not a flashtestation transaction');
+      console.log('\nThe transaction did not emit the BlockBuilderProofVerified event');
     }
 
   } catch (error) {

sdks/flashtestations-sdk/examples/getBlock.ts

@@ -1,4 +1,4 @@
-import { verifyFlashtestationInBlock } from '../src/verification/service';
+import { verifyFlashtestationInBlock } from '../src/index';
 
 /**
  * Example: Verify if a block was built by a specific TEE workload
@@ -43,19 +43,27 @@ async function main() {
 
     if (result.isBuiltByExpectedTee) {
       console.log('\n✓ Block was built by the specified TEE workload!\n');
-      console.log(`Workload ID: ${result.workloadId}`);
-      console.log(`Commit Hash: ${result.commitHash}`);
-      console.log(`Builder Address: ${result.builderAddress}`);
-      console.log(`Version: ${result.version}`);
-      console.log(`Source Locators: ${result.sourceLocators && result.sourceLocators.length > 0 ? result.sourceLocators.join(', ') : 'None'}`)
+      console.log(`Workload ID: ${result.workloadMetadata.workloadId}`);
+      console.log(`Commit Hash: ${result.workloadMetadata.commitHash}`);
+      console.log(`Builder Address: ${result.workloadMetadata.builderAddress}`);
+      console.log(`Version: ${result.workloadMetadata.version}`);
+      console.log(`Source Locators: ${result.workloadMetadata.sourceLocators && result.workloadMetadata.sourceLocators.length > 0 ? result.workloadMetadata.sourceLocators.join(', ') : 'None'}`)
       if (result.blockExplorerLink) {
         console.log(`Block Explorer: ${result.blockExplorerLink}`);
       }
     } else {
-      console.log('\n✗ Block was NOT built by the specified TEE workload.\n');
-      console.log('The block either:');
-      console.log('  1. Does not contain a flashtestation transaction');
-      console.log('  2. Contains a flashtestation from a different workload');
+      console.log('\n✗ Block was NOT built by the specified TEE workload\n');
+
+      if (result.workloadMetadata) {
+        console.log('Block was built by a different TEE workload:');
+        console.log(`Workload ID: ${result.workloadMetadata.workloadId}`);
+        console.log(`Commit Hash: ${result.workloadMetadata.commitHash}`);
+        console.log(`Builder Address: ${result.workloadMetadata.builderAddress}`);
+        console.log(`Version: ${result.workloadMetadata.version}`);
+        console.log(`Source Locators: ${result.workloadMetadata.sourceLocators.length > 0 ? result.workloadMetadata.sourceLocators.join(', ') : 'None'}`)
+      } else {
+        console.log('The block does not contain a flashtestation transaction')
+      }
     }
 
     // You can also verify specific blocks:

sdks/flashtestations-sdk/examples/getFlashtestationTx.ts

@@ -6,7 +6,8 @@
   "keywords": [
     "flashteststations",
     "ethereum",
-    "flashbots"
+    "flashbots",
+    "unichain"
   ],
   "version": "0.1.0",
   "license": "MIT",

sdks/flashtestations-sdk/examples/getTransactionReceipt.ts

@@ -1,7 +1,38 @@
-// TODO: Remove this
-export const sum = (a: number, b: number) => {
-  if ('development' === process.env.NODE_ENV) {
-    console.log('boop');
-  }
-  return a + b;
-};
+/**
+ * Flashtestations SDK - Verify TEE-built blocks on Unichain
+ *
+ * This SDK provides tools to verify whether blockchain blocks were built by
+ * Trusted Execution Environments (TEEs) running specific workload software.
+ */
+
+// Main verification function
+export { verifyFlashtestationInBlock, getFlashtestationEvent } from './verification/service';
+
+
+// Core types
+export type {
+  VerificationResult,
+  WorkloadMeasureRegisters,
+  BlockParameter,
+  FlashtestationEvent,
+  ChainConfig,
+  ClientConfig,
+} from './types';
+
+// Error classes for programmatic error handling
+export {
+  NetworkError,
+  BlockNotFoundError,
+  ValidationError,
+  ChainNotSupportedError,
+} from './types';
+
+// Chain configuration utilities
+export {
+  getSupportedChains,
+  isChainSupported,
+  getChainConfig,
+} from './config/chains';
+
+// Workload ID computation utility
+export { computeWorkloadId } from './crypto/workload';

sdks/flashtestations-sdk/examples/verifyBlock.ts

@@ -304,7 +304,7 @@ export class RpcClient {
    * @returns FlashtestationEvent data if it's a flashtestation tx, null otherwise
    * @throws NetworkError if RPC connection fails
    */
-  async getFlashtestationTx(
+  async getFlashtestationEvent(
     blockParameter: BlockParameter = 'latest'
   ): Promise<FlashtestationEvent | null> {
     return retry(

sdks/flashtestations-sdk/package.json

@@ -1,23 +1,32 @@
-/**
- * Result of flashtestation verification
- */
-export interface VerificationResult {
-  /** Whether the block was built by a TEE running the specified workload */
-  isBuiltByExpectedTee: boolean;
-  /** workload ID of the TEE workload, null if not TEE-built */
-  workloadId: string | null;
-  /** Commit hash of the TEE workload source code, null if not TEE-built */
-  commitHash: string | null;
-  /** Block explorer link for the block, null if not TEE-built */
-  blockExplorerLink: string | null;
+export type WorkloadMetadata = {
+  /** workload ID of the TEE workload*/
+  workloadId: string;
+  /** Commit hash of the TEE workload source code */
+  commitHash: string;
   /** Address of the block builder, optional */
-  builderAddress?: string;
+  builderAddress: string;
   /** Version of the flashtestation protocol, optional */
   version: number;
   /** Source locators (e.g., GitHub URLs) for the workload source code, optional for backwards compatibility */
-  sourceLocators?: string[];
+  sourceLocators: string[];
 }
 
+/**
+ * Result of flashtestation verification
+ */
+export type VerificationResult = | {
+  /** Block was built by the expected TEE workload */
+  isBuiltByExpectedTee: true;
+  blockExplorerLink: string | null;
+  workloadMetadata: WorkloadMetadata;
+}
+| {
+  /** Block was NOT built by the expected TEE workload */
+  isBuiltByExpectedTee: false;
+  blockExplorerLink: string | null;
+  workloadMetadata: WorkloadMetadata | null;
+};
+
 /**
  * TEE workload measurement registers used for workload ID computation
  */
@@ -74,6 +83,16 @@ export interface ChainConfig {
   blockExplorerUrl: string;
 }
 
+/**
+ * Minimal configuration options for the JSON-RPC client to interact with the blockchain
+ */
+export interface ClientConfig {
+  /** Chain ID to network */
+  chainId: number;
+  /** Optional custom RPC URL (overrides default) */
+  rpcUrl?: string;
+}
+
 /**
  * Block parameter for identifying blocks
  */