@blindmarket/sdk 0.1.4

package/src/index.ts

@@ -0,0 +1,222 @@
+import { Wallet, ethers } from 'ethers';
+import { createCipheriv, randomBytes, createHash } from 'crypto';
+
+export interface BlindMarketConfig {
+  apiBase?: string;
+  apiKey: string;
+  rpcUrl?: string;
+}
+
+export interface DeployAgentParams {
+  name: string;
+  instructions: string;
+  provider: 'openai' | 'anthropic' | 'groq' | 'gemini';
+  model: string;
+  apiKey: string;
+  ownerAddress: string;
+  ownerPublicKey: string;
+  capabilities?: string[];
+  tools?: object[];
+}
+
+export interface PostTaskParams {
+  instructions: string;
+  category: string;
+  amount: string;       // wei as string
+  token: string;        // ERC-20 address
+  locationZone?: string;
+  duration?: string;    // seconds
+}
+
+export interface DeployedAgent {
+  id: string;
+  name: string;
+  walletAddress: string;
+  publicKey: string;
+  inftTokenId?: number;
+  status: string;
+}
+
+export interface PostedTask {
+  unsignedTx: object;
+  taskHash: string;
+  storageRoot: string;
+}
+
+export class BlindMarket {
+  private apiBase: string;
+  private apiKey: string;
+
+  constructor(config: BlindMarketConfig) {
+    this.apiBase = config.apiBase ?? 'http://localhost:3001';
+    this.apiKey = config.apiKey;
+  }
+
+  private async req<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const res = await fetch(`${this.apiBase}${path}`, {
+      method,
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this.apiKey}` },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const json = await res.json() as { success: boolean; data?: T; error?: { message: string } };
+    if (!json.success) throw new Error(json.error?.message ?? `HTTP ${res.status}`);
+    return json.data as T;
+  }
+
+  // ── Agent deployment ──────────────────────────────────────────────────────
+
+  /**
+   * Deploy a new agent. Generates a wallet, mints an INFT, returns the agent.
+   *
+   * @example
+   * const agent = await bb.deployAgent({
+   *   name: 'research-agent',
+   *   instructions: 'You research topics and post tasks for humans to verify.',
+   *   provider: 'anthropic',
+   *   model: 'claude-sonnet-4-5',
+   *   apiKey: process.env.ANTHROPIC_API_KEY!,
+   *   ownerAddress: wallet.address,
+   *   ownerPublicKey: wallet.publicKey,
+   * });
+   */
+  async deployAgent(params: DeployAgentParams): Promise<DeployedAgent> {
+    return this.req<DeployedAgent>('POST', '/api/v1/agents/deploy', params);
+  }
+
+  /**
+   * List all agents owned by an address.
+   */
+  async listAgents(ownerAddress: string): Promise<DeployedAgent[]> {
+    return this.req<DeployedAgent[]>('GET', `/api/v1/agents?owner=${ownerAddress}`);
+  }
+
+  // ── Task lifecycle ────────────────────────────────────────────────────────
+
+  /**
+   * Encrypt instructions and post a task. Returns an unsigned tx to sign + broadcast.
+   *
+   * @example
+   * const { unsignedTx, taskHash } = await bb.postTask({
+   *   instructions: 'Photograph the exterior of 42 Oak Street, NYC.',
+   *   category: 'photography',
+   *   amount: ethers.parseEther('30').toString(),
+   *   token: '0x317227efcA18D004E12CA8046AEf7E1597458F25',
+   *   locationZone: 'US-NY',
+   * });
+   * const receipt = await wallet.sendTransaction(unsignedTx);
+   */
+  async postTask(params: PostTaskParams): Promise<PostedTask> {
+    // Encrypt instructions
+    const key = randomBytes(32);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(params.instructions, 'utf8'), cipher.final()]);
+    const tag = (cipher as any).getAuthTag() as Buffer;
+    const blob = Buffer.concat([iv, tag, encrypted]).toString('base64');
+
+    // Upload to storage
+    const { rootHash } = await this.req<{ rootHash: string }>('POST', '/api/v1/storage/upload', { data: blob });
+
+    // taskHash = SHA-256 of ciphertext
+    const taskHash = '0x' + createHash('sha256').update(Buffer.concat([iv, tag, encrypted])).digest('hex');
+
+    // Build unsigned tx
+    const { unsignedTx } = await this.req<{ unsignedTx: object }>('POST', '/api/v1/tasks', {
+      taskHash,
+      token: params.token,
+      amount: params.amount,
+      category: params.category,
+      locationZone: params.locationZone ?? 'global',
+      duration: params.duration ?? '86400',
+    });
+
+    return { unsignedTx, taskHash, storageRoot: rootHash };
+  }
+
+  /**
+   * Assign a worker to a task. Returns an unsigned tx.
+   */
+  async assignWorker(taskId: string, worker: string): Promise<{ unsignedTx: object }> {
+    return this.req('POST', `/api/v1/tasks/${taskId}/assign`, { worker });
+  }
+
+  /**
+   * Trigger TEE verification for a task.
+   */
+  async verify(params: {
+    taskId: number;
+    requirements: string;
+    evidenceSummary: string;
+    category?: string;
+  }): Promise<{ passed: boolean; confidence: number; reasoning: string }> {
+    return this.req('POST', '/api/v1/verification/trigger', {
+      taskId: params.taskId,
+      taskCategory: params.category ?? 'general',
+      taskRequirements: params.requirements,
+      evidenceSummary: params.evidenceSummary,
+    });
+  }
+
+  /**
+   * Submit evidence for an assigned task.
+   */
+  async submitEvidence(params: { taskId: number; evidence: string }): Promise<{ unsignedTx: object }> {
+    const key = randomBytes(32);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(params.evidence, 'utf8'), cipher.final()]);
+    const tag = (cipher as any).getAuthTag() as Buffer;
+    const blob = Buffer.concat([iv, tag, encrypted]).toString('base64');
+
+    await this.req('POST', '/api/v1/storage/upload', { data: blob });
+    const evidenceHash = '0x' + createHash('sha256').update(Buffer.concat([iv, tag, encrypted])).digest('hex');
+
+    return this.req('POST', '/api/v1/submissions/submit', { taskId: params.taskId, evidenceHash });
+  }
+
+  /**
+   * Get task status.
+   */
+  async getTask(taskId: string): Promise<{ status: number; agent: string; worker: string; amount: string }> {
+    return this.req('GET', `/api/v1/tasks/${taskId}`);
+  }
+
+  /**
+   * List open tasks.
+   */
+  async listTasks(limit = 20): Promise<object[]> {
+    const { tasks } = await this.req<{ tasks: object[] }>('GET', `/api/v1/tasks?limit=${limit}`);
+    return tasks;
+  }
+
+  // ── Auth helper ───────────────────────────────────────────────────────────
+
+  /**
+   * Authenticate with a wallet and return a JWT.
+   * Use this to get the apiKey for the constructor.
+   *
+   * @example
+   * const wallet = new ethers.Wallet(privateKey);
+   * const apiKey = await BlindMarket.authenticate(wallet, 'http://localhost:3001');
+   * const bb = new BlindMarket({ apiKey });
+   */
+  static async authenticate(wallet: Wallet, apiBase = 'http://localhost:3001'): Promise<string> {
+    const nonceRes = await fetch(`${apiBase}/api/v1/auth/nonce`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ address: wallet.address }),
+    });
+    const { data: { nonce } } = await nonceRes.json() as { data: { nonce: string } };
+    const message = `Sign this message to authenticate with BlindMarket.\n\nNonce: ${nonce}`;
+    const signature = await wallet.signMessage(message);
+    const verifyRes = await fetch(`${apiBase}/api/v1/auth/verify`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ address: wallet.address, signature }),
+    });
+    const { data: { token } } = await verifyRes.json() as { data: { token: string } };
+    return token;
+  }
+}
+
+export { ethers };

package/src/keystore/InMemoryKeyStore.ts

@@ -0,0 +1,146 @@
+import { aesDecrypt, aesEncrypt, generateAesKey, hkdfSha256 } from '../crypto/index.js';
+import { CryptoError } from '../errors/index.js';
+import type { Address, Hex, TaskId, TaskKey, TaskKeyRef } from '../types.js';
+import type { KeyStore } from './KeyStore.js';
+
+const EXPORT_FORMAT = 'blindmarket.keystore.v1';
+const EXPORT_INFO = new TextEncoder().encode('BlindMarket-Keystore-Export-v1');
+
+interface Entry {
+  aesKey: Uint8Array;
+  createdAt: number;
+}
+
+interface ExportShape {
+  format: typeof EXPORT_FORMAT;
+  salt: string;
+  blob: string;
+}
+
+interface PlainExport {
+  keys: Array<{ taskId: string; aesKey: string; createdAt: number }>;
+  peers: Array<{ addr: Address; pubkey: Hex }>;
+}
+
+/**
+ * Default KeyStore. Non-persistent — keys live only for the process lifetime.
+ * Export/import is encrypted with a passphrase via HKDF-derived AES-256-GCM,
+ * so exported blobs are safe to move between processes.
+ */
+export class InMemoryKeyStore implements KeyStore {
+  private readonly keys = new Map<string, Entry>();
+  private readonly peers = new Map<Address, Hex>();
+
+  async putTaskKey(taskId: TaskId, key: TaskKey): Promise<void> {
+    this.keys.set(taskId.toString(), {
+      aesKey: copy(key.aesKey),
+      createdAt: key.createdAt.getTime(),
+    });
+  }
+
+  async getTaskKey(taskId: TaskId): Promise<TaskKey | null> {
+    const e = this.keys.get(taskId.toString());
+    if (!e) return null;
+    return { aesKey: copy(e.aesKey), createdAt: new Date(e.createdAt) };
+  }
+
+  async putPeerPubKey(addr: Address, pubkey: Hex): Promise<void> {
+    this.peers.set(addr, pubkey);
+  }
+
+  async getPeerPubKey(addr: Address): Promise<Hex | null> {
+    return this.peers.get(addr) ?? null;
+  }
+
+  async list(): Promise<TaskKeyRef[]> {
+    return Array.from(this.keys.entries()).map(([id, e]) => ({
+      taskId: BigInt(id),
+      createdAt: new Date(e.createdAt),
+    }));
+  }
+
+  async delete(taskId: TaskId): Promise<void> {
+    this.keys.delete(taskId.toString());
+  }
+
+  async export(passphrase: string): Promise<string> {
+    if (!passphrase || passphrase.length < 8) {
+      throw new CryptoError('CRYPTO/INVALID_KEY', 'passphrase must be ≥8 characters');
+    }
+    const salt = randomBytes(16);
+    const wrapKey = await deriveWrapKey(passphrase, salt);
+    const plain: PlainExport = {
+      keys: Array.from(this.keys.entries()).map(([taskId, e]) => ({
+        taskId,
+        aesKey: bytesToHex(e.aesKey),
+        createdAt: e.createdAt,
+      })),
+      peers: Array.from(this.peers.entries()).map(([addr, pubkey]) => ({ addr, pubkey })),
+    };
+    const blob = await aesEncrypt(new TextEncoder().encode(JSON.stringify(plain)), wrapKey);
+    const out: ExportShape = { format: EXPORT_FORMAT, salt: bytesToHex(salt), blob: bytesToHex(blob) };
+    return JSON.stringify(out);
+  }
+
+  async import(data: string, passphrase: string): Promise<void> {
+    let parsed: ExportShape;
+    try {
+      parsed = JSON.parse(data) as ExportShape;
+    } catch (cause) {
+      throw new CryptoError('CRYPTO/INTEGRITY_CHECK', 'keystore export is not valid JSON', { cause });
+    }
+    if (parsed.format !== EXPORT_FORMAT) {
+      throw new CryptoError(
+        'CRYPTO/UNSUPPORTED_CIPHER',
+        `unknown keystore export format: ${parsed.format ?? '(missing)'}`,
+      );
+    }
+    const salt = hexToBytes(parsed.salt);
+    const wrapKey = await deriveWrapKey(passphrase, salt);
+    const blob = hexToBytes(parsed.blob);
+    const plainBytes = await aesDecrypt(blob, wrapKey);
+    const plain = JSON.parse(new TextDecoder().decode(plainBytes)) as PlainExport;
+    this.keys.clear();
+    this.peers.clear();
+    for (const k of plain.keys) {
+      this.keys.set(k.taskId, { aesKey: hexToBytes(k.aesKey), createdAt: k.createdAt });
+    }
+    for (const p of plain.peers) {
+      this.peers.set(p.addr, p.pubkey);
+    }
+  }
+}
+
+function copy(u: Uint8Array): Uint8Array {
+  const c = new Uint8Array(u.byteLength);
+  c.set(u);
+  return c;
+}
+
+function randomBytes(n: number): Uint8Array {
+  const c = (globalThis as { crypto: Crypto }).crypto;
+  const out = new Uint8Array(n);
+  c.getRandomValues(out);
+  return out;
+}
+
+async function deriveWrapKey(passphrase: string, salt: Uint8Array): Promise<Uint8Array> {
+  const ikm = new TextEncoder().encode(passphrase);
+  return hkdfSha256(ikm, 32, EXPORT_INFO, salt);
+}
+
+function bytesToHex(u: Uint8Array): string {
+  return Array.from(u, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+// Tree-shakable helper kept here so we don't accidentally ship generateAesKey
+// from this module — it's re-exported from crypto only.
+export { generateAesKey };

package/src/keystore/KeyStore.ts

@@ -0,0 +1,19 @@
+import type { Address, Hex, TaskId, TaskKey, TaskKeyRef } from '../types.js';
+
+/**
+ * Per-session storage for task AES keys and cached peer public keys. The SDK
+ * never logs or serializes anything from here — this is the one place at-rest
+ * secrets live. Implementations MUST treat passphrase-protected exports as the
+ * only portable format.
+ */
+export interface KeyStore {
+  putTaskKey(taskId: TaskId, key: TaskKey): Promise<void>;
+  getTaskKey(taskId: TaskId): Promise<TaskKey | null>;
+  putPeerPubKey(addr: Address, pubkey: Hex): Promise<void>;
+  getPeerPubKey(addr: Address): Promise<Hex | null>;
+  list(): Promise<TaskKeyRef[]>;
+  delete(taskId: TaskId): Promise<void>;
+  /** Portable, encrypted-at-rest JSON export for backup/migration. */
+  export(passphrase: string): Promise<string>;
+  import(data: string, passphrase: string): Promise<void>;
+}

package/src/keystore/index.ts

@@ -0,0 +1,2 @@
+export * from './KeyStore.js';
+export * from './InMemoryKeyStore.js';

package/src/network/index.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './presets.js';
+export * from './resolve.js';

package/src/network/presets.ts

@@ -0,0 +1,27 @@
+import type { Network } from './types.js';
+
+/**
+ * Known-good network presets. Addresses pinned per SDK version so upgrading
+ * the SDK cannot silently move contracts under a consumer.
+ *
+ * testnet = 0G Galileo (chainId 16602) — addresses from
+ * contracts/deployments/0g-testnet.json (deployed 2026-04-15).
+ */
+export const networks = {
+  testnet: {
+    name: '0g-galileo-testnet',
+    chainId: 16602n,
+    rpc: ['https://evmrpc-testnet.0g.ai'],
+    contracts: {
+      escrow: '0xFd4F93F5A7BE144c405D1D8fbEC63Fb776207681',
+      registry: '0xeE52d780A47F77E8a4a1cEb236e3C65A48FbD828',
+      reputation: '0x4A6374Fae37E19E69ba43E7cf6994AC15F63256e',
+      usdc: '0x317227efcA18D004E12CA8046AEf7E1597458F25',
+    },
+    indexer: 'https://indexer-storage-testnet-turbo.0g.ai',
+    broker: 'https://broker.testnet.0g.ai',
+    explorer: 'https://chainscan-galileo.0g.ai',
+  },
+} as const satisfies Record<string, Network>;
+
+export type NetworkName = keyof typeof networks;

package/src/network/resolve.ts

@@ -0,0 +1,19 @@
+import { ConfigError } from '../errors/index.js';
+import { networks, type NetworkName } from './presets.js';
+import type { Network } from './types.js';
+
+/**
+ * Resolve a preset name or a literal Network object into the canonical
+ * Network used throughout the SDK. Throws ConfigError for unknown names.
+ */
+export function resolveNetwork(arg: NetworkName | Network): Network {
+  if (typeof arg === 'string') {
+    const preset = (networks as Record<string, Network | undefined>)[arg];
+    if (!preset) {
+      const known = Object.keys(networks).join(', ');
+      throw new ConfigError('CONFIG/INVALID_NETWORK', `unknown network '${arg}' (known: ${known})`);
+    }
+    return preset;
+  }
+  return arg;
+}

package/src/network/types.ts

@@ -0,0 +1,18 @@
+import type { Address } from '../types.js';
+
+export interface NetworkContracts {
+  escrow: Address;
+  registry: Address;
+  reputation: Address;
+  usdc: Address;
+}
+
+export interface Network {
+  name: string;
+  chainId: bigint;
+  rpc: string[];
+  contracts: NetworkContracts;
+  indexer: string;
+  broker: string;
+  explorer?: string;
+}

package/src/signer/EthersSigner.ts

@@ -0,0 +1,82 @@
+import { ethers } from 'ethers';
+import { ChainError, ConfigError } from '../errors/index.js';
+import type { Address, Hex } from '../types.js';
+import type { Signer, TxRequest, TypedDataDomain, TypedDataField } from './Signer.js';
+
+/**
+ * Wraps any ethers v6 Signer. The most common path — accepts ethers.Wallet,
+ * ethers.BrowserProvider signer, JsonRpcSigner, etc. Caches the recovered
+ * public key after the first successful getPublicKey() call.
+ */
+export class EthersSigner implements Signer {
+  private publicKeyCache: Hex | undefined;
+
+  constructor(private readonly inner: ethers.Signer) {}
+
+  async getAddress(): Promise<Address> {
+    return (await this.inner.getAddress()) as Address;
+  }
+
+  async chainId(): Promise<bigint> {
+    const provider = this.inner.provider;
+    if (!provider) {
+      throw new ConfigError('CONFIG/BAD_CONFIG', 'signer has no attached provider; cannot read chainId');
+    }
+    const net = await provider.getNetwork();
+    return net.chainId;
+  }
+
+  async signMessage(msg: string | Uint8Array): Promise<Hex> {
+    return (await this.inner.signMessage(msg)) as Hex;
+  }
+
+  async signTypedData(
+    domain: TypedDataDomain,
+    types: Record<string, TypedDataField[]>,
+    value: Record<string, unknown>,
+  ): Promise<Hex> {
+    return (await this.inner.signTypedData(domain, types, value)) as Hex;
+  }
+
+  async signTransaction(tx: TxRequest): Promise<Hex> {
+    try {
+      return (await this.inner.signTransaction({
+        to: tx.to,
+        ...(tx.from !== undefined ? { from: tx.from } : {}),
+        ...(tx.data !== undefined ? { data: tx.data } : {}),
+        ...(tx.value !== undefined ? { value: tx.value } : {}),
+        ...(tx.gasLimit !== undefined ? { gasLimit: tx.gasLimit } : {}),
+        ...(tx.nonce !== undefined ? { nonce: tx.nonce } : {}),
+        ...(tx.chainId !== undefined ? { chainId: tx.chainId } : {}),
+      })) as Hex;
+    } catch (cause) {
+      throw new ChainError('CHAIN/TX_REVERTED', 'signTransaction failed', { cause });
+    }
+  }
+
+  /**
+   * Recovers the uncompressed secp256k1 public key from the signer. For Wallet
+   * signers we can read it directly; for generic Signers we sign a canonical
+   * probe message once and recover from the signature.
+   */
+  async getPublicKey(): Promise<Hex> {
+    if (this.publicKeyCache) return this.publicKeyCache;
+
+    // Fast path: ethers.Wallet exposes signingKey.publicKey directly.
+    const maybeWallet = this.inner as unknown as { signingKey?: { publicKey: string } };
+    if (maybeWallet.signingKey?.publicKey) {
+      this.publicKeyCache = maybeWallet.signingKey.publicKey as Hex;
+      return this.publicKeyCache;
+    }
+
+    // Slow path: sign a probe message and recover the public key.
+    const probe = 'BlindMarket-PublicKey-Recovery-v1';
+    const sig = await this.inner.signMessage(probe);
+    const recovered = ethers.SigningKey.recoverPublicKey(
+      ethers.hashMessage(probe),
+      sig,
+    );
+    this.publicKeyCache = recovered as Hex;
+    return this.publicKeyCache;
+  }
+}

package/src/signer/PrivateKeySigner.ts

@@ -0,0 +1,19 @@
+import { ethers } from 'ethers';
+import { EthersSigner } from './EthersSigner.js';
+
+/**
+ * Convenience factory for Node / headless agents: builds an EthersSigner
+ * backed by a fresh ethers.Wallet from a raw private key (hex, with or
+ * without 0x prefix). Optionally attaches an RPC provider so chainId()
+ * and on-chain reads work.
+ *
+ * NEVER pass a private key you don't control — prefer KMS, browser wallet,
+ * or hardware signer for production.
+ */
+export class PrivateKeySigner extends EthersSigner {
+  constructor(privateKey: string, provider?: ethers.Provider) {
+    const pk = privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`;
+    const wallet = provider ? new ethers.Wallet(pk, provider) : new ethers.Wallet(pk);
+    super(wallet);
+  }
+}

package/src/signer/Signer.ts

@@ -0,0 +1,40 @@
+import type { Address, Hex } from '../types.js';
+
+export interface TxRequest {
+  to: Address;
+  from?: Address;
+  data?: Hex;
+  value?: bigint;
+  gasLimit?: bigint;
+  nonce?: number;
+  chainId?: bigint;
+}
+
+export interface TypedDataDomain {
+  name?: string;
+  version?: string;
+  chainId?: bigint | number;
+  verifyingContract?: Address;
+  salt?: Hex;
+}
+
+export type TypedDataField = { name: string; type: string };
+
+/**
+ * Uniform signing interface used across the SDK. Adapters wrap ethers Signer,
+ * raw private keys, EIP-1193 providers, or KMS. Implementations MUST return
+ * hex-encoded signatures (0x-prefixed) and addresses (0x-prefixed, 20 bytes).
+ */
+export interface Signer {
+  getAddress(): Promise<Address>;
+  chainId(): Promise<bigint>;
+  signMessage(msg: string | Uint8Array): Promise<Hex>;
+  signTypedData(
+    domain: TypedDataDomain,
+    types: Record<string, TypedDataField[]>,
+    value: Record<string, unknown>,
+  ): Promise<Hex>;
+  signTransaction(tx: TxRequest): Promise<Hex>;
+  /** Uncompressed secp256k1 public key, 0x04-prefixed (hex). */
+  getPublicKey(): Promise<Hex>;
+}

package/src/signer/index.ts

@@ -0,0 +1,3 @@
+export * from './Signer.js';
+export * from './EthersSigner.js';
+export * from './PrivateKeySigner.js';

package/src/storage/MemoryStorage.ts

@@ -0,0 +1,49 @@
+import { sha256 } from '../crypto/index.js';
+import { StorageError } from '../errors/index.js';
+import type { RootHash, UploadResult } from '../types.js';
+import type { Storage } from './Storage.js';
+
+/**
+ * In-process Storage for tests and local development. Deterministic: rootHash
+ * is the SHA-256 of the content (not a merkle root), so the same bytes always
+ * produce the same hash. Not for production — no replication, no integrity
+ * proofs beyond SHA-256.
+ */
+export class MemoryStorage implements Storage {
+  private readonly blobs = new Map<string, Uint8Array>();
+
+  async upload(bytes: Uint8Array): Promise<UploadResult> {
+    const rootHash = await this.hash(bytes);
+    this.blobs.set(rootHash, copy(bytes));
+    return { rootHash, size: bytes.byteLength };
+  }
+
+  async download(rootHash: RootHash): Promise<Uint8Array> {
+    const data = this.blobs.get(rootHash);
+    if (!data) {
+      throw new StorageError('STORAGE/NOT_FOUND', `no blob at ${rootHash}`);
+    }
+    return copy(data);
+  }
+
+  async hash(bytes: Uint8Array): Promise<RootHash> {
+    const digest = await sha256(bytes);
+    return ('0x' + Array.from(digest, (b) => b.toString(16).padStart(2, '0')).join('')) as RootHash;
+  }
+
+  /** Test helper: wipe all stored blobs. */
+  clear(): void {
+    this.blobs.clear();
+  }
+
+  /** Test helper: count of stored blobs. */
+  size(): number {
+    return this.blobs.size;
+  }
+}
+
+function copy(u: Uint8Array): Uint8Array {
+  const c = new Uint8Array(u.byteLength);
+  c.set(u);
+  return c;
+}

package/src/storage/Storage.ts

@@ -0,0 +1,15 @@
+import type { RootHash, UploadResult } from '../types.js';
+
+/**
+ * Abstraction over blob storage. Default implementation (ZgStorage) uses
+ * 0G Storage; MemoryStorage is for tests and local fallback. Consumers can
+ * provide their own adapter for IPFS, S3, etc.
+ */
+export interface Storage {
+  /** Upload bytes, return root hash + optional tx hash + size. */
+  upload(bytes: Uint8Array): Promise<UploadResult>;
+  /** Download bytes by root hash. Throws StorageError('STORAGE/NOT_FOUND') if absent. */
+  download(rootHash: RootHash): Promise<Uint8Array>;
+  /** Compute the canonical root hash without uploading. */
+  hash(bytes: Uint8Array): Promise<RootHash>;
+}