@blindmarket/sdk 0.1.4

package/test/crypto.aes.test.ts

@@ -0,0 +1,81 @@
+import * as fc from 'fast-check';
+import { describe, expect, it } from 'vitest';
+import { aesDecrypt, aesEncrypt, generateAesKey, sha256 } from '../src/crypto/index.js';
+import { CryptoError } from '../src/errors/index.js';
+
+describe('aes-256-gcm', () => {
+  it('encrypts then decrypts arbitrary bytes', async () => {
+    const key = await generateAesKey();
+    const pt = new TextEncoder().encode('hello bounty');
+    const ct = await aesEncrypt(pt, key);
+    expect(ct.byteLength).toBe(pt.byteLength + 12 + 16);
+    const rt = await aesDecrypt(ct, key);
+    expect(new TextDecoder().decode(rt)).toBe('hello bounty');
+  });
+
+  it('generates distinct keys each call', async () => {
+    const a = await generateAesKey();
+    const b = await generateAesKey();
+    expect(a.byteLength).toBe(32);
+    expect(b.byteLength).toBe(32);
+    expect(a).not.toEqual(b);
+  });
+
+  it('emits distinct ciphertexts for the same plaintext+key (random IV)', async () => {
+    const key = await generateAesKey();
+    const pt = new TextEncoder().encode('same text');
+    const c1 = await aesEncrypt(pt, key);
+    const c2 = await aesEncrypt(pt, key);
+    expect(c1).not.toEqual(c2);
+  });
+
+  it('rejects non-32-byte keys on encrypt', async () => {
+    const key = new Uint8Array(16);
+    await expect(aesEncrypt(new Uint8Array(4), key)).rejects.toBeInstanceOf(CryptoError);
+  });
+
+  it('rejects non-32-byte keys on decrypt', async () => {
+    const key = new Uint8Array(16);
+    await expect(aesDecrypt(new Uint8Array(32), key)).rejects.toBeInstanceOf(CryptoError);
+  });
+
+  it('rejects truncated blobs', async () => {
+    const key = await generateAesKey();
+    await expect(aesDecrypt(new Uint8Array(10), key)).rejects.toBeInstanceOf(CryptoError);
+  });
+
+  it('detects tampering (auth tag check)', async () => {
+    const key = await generateAesKey();
+    const ct = await aesEncrypt(new TextEncoder().encode('data'), key);
+    // biome-ignore lint/style/noNonNullAssertion: we just created the array
+    ct[ct.length - 1] = (ct[ct.length - 1]! ^ 0x01) & 0xff;
+    await expect(aesDecrypt(ct, key)).rejects.toBeInstanceOf(CryptoError);
+  });
+
+  it('round-trips zero-byte plaintext', async () => {
+    const key = await generateAesKey();
+    const ct = await aesEncrypt(new Uint8Array(0), key);
+    expect(ct.byteLength).toBe(28); // 12 IV + 16 tag + 0 ct
+    const rt = await aesDecrypt(ct, key);
+    expect(rt.byteLength).toBe(0);
+  });
+
+  it('property: arbitrary plaintext round-trips', async () => {
+    await fc.assert(
+      fc.asyncProperty(fc.uint8Array({ minLength: 0, maxLength: 4096 }), async (pt) => {
+        const key = await generateAesKey();
+        const rt = await aesDecrypt(await aesEncrypt(pt, key), key);
+        expect(Array.from(rt)).toEqual(Array.from(pt));
+      }),
+      { numRuns: 50 },
+    );
+  });
+});
+
+describe('sha256', () => {
+  it('matches a known vector', async () => {
+    const digest = await sha256(new TextEncoder().encode('abc'));
+    const hex = Array.from(digest, (b) => b.toString(16).padStart(2, '0')).join('');
+    expect(hex).toBe('ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad');
+  });
+});

package/test/crypto.compat.test.ts

@@ -0,0 +1,33 @@
+/**
+ * Wire-format compatibility: the SDK (Web Crypto) must decrypt blobs produced by
+ * backend/src/services/crypto.ts (Node crypto). The fixture at test/fixtures/crypto.json
+ * is generated by scripts/gen-crypto-fixtures.mjs using the same Node primitives
+ * as the backend — if this test fails, the SDK has diverged from the backend's
+ * byte layout and will break cross-stack encryption.
+ */
+import { describe, expect, it } from 'vitest';
+import fixture from './fixtures/crypto.json' with { type: 'json' };
+import { aesDecrypt, eciesDecrypt } from '../src/crypto/index.js';
+
+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;
+}
+
+describe('crypto cross-compat with backend wire format', () => {
+  it('SDK decrypts backend-produced AES blob', async () => {
+    const key = hexToBytes(fixture.aes.key);
+    const blob = hexToBytes(fixture.aes.blob);
+    const pt = await aesDecrypt(blob, key);
+    expect(new TextDecoder().decode(pt)).toBe(fixture.plaintext);
+  });
+
+  it('SDK decrypts backend-produced ECIES blob', async () => {
+    const blob = hexToBytes(fixture.ecies.blob);
+    const pt = await eciesDecrypt(blob, fixture.keypair.privateKey);
+    expect(new TextDecoder().decode(pt)).toBe(fixture.plaintext);
+  });
+});

package/test/crypto.ecies.test.ts

@@ -0,0 +1,64 @@
+import * as fc from 'fast-check';
+import { describe, expect, it } from 'vitest';
+import {
+  derivePublicKey,
+  eciesDecrypt,
+  eciesEncrypt,
+  generateKeyPair,
+} from '../src/crypto/index.js';
+import { CryptoError } from '../src/errors/index.js';
+
+describe('ecies secp256k1', () => {
+  it('round-trips', async () => {
+    const { privateKey, publicKey } = generateKeyPair();
+    const pt = new TextEncoder().encode('secret instructions');
+    const ct = await eciesEncrypt(pt, publicKey);
+    const rt = await eciesDecrypt(ct, privateKey);
+    expect(new TextDecoder().decode(rt)).toBe('secret instructions');
+  });
+
+  it('wire format: [65 ephemeral pubkey][12 IV][16 tag][ciphertext]', async () => {
+    const { publicKey } = generateKeyPair();
+    const ct = await eciesEncrypt(new Uint8Array([1, 2, 3]), publicKey);
+    expect(ct.byteLength).toBe(65 + 12 + 16 + 3);
+    // First byte of ephemeral pubkey must be 0x04 (uncompressed marker)
+    expect(ct[0]).toBe(0x04);
+  });
+
+  it('wrong private key fails', async () => {
+    const good = generateKeyPair();
+    const bad = generateKeyPair();
+    const ct = await eciesEncrypt(new Uint8Array([9]), good.publicKey);
+    await expect(eciesDecrypt(ct, bad.privateKey)).rejects.toBeInstanceOf(CryptoError);
+  });
+
+  it('rejects truncated blobs', async () => {
+    const { privateKey } = generateKeyPair();
+    await expect(eciesDecrypt(new Uint8Array(30), privateKey)).rejects.toBeInstanceOf(CryptoError);
+  });
+
+  it('rejects compressed / malformed recipient pubkey', async () => {
+    const bogus = '02' + '00'.repeat(32); // compressed form (33 bytes), not supported
+    await expect(eciesEncrypt(new Uint8Array([0]), bogus)).rejects.toBeInstanceOf(CryptoError);
+  });
+
+  it('derivePublicKey recovers the same pubkey used for encryption', async () => {
+    const { privateKey, publicKey } = generateKeyPair();
+    const recovered = derivePublicKey(privateKey);
+    expect(recovered.toLowerCase()).toBe(publicKey.toLowerCase());
+    const pt = new TextEncoder().encode('x');
+    const ct = await eciesEncrypt(pt, recovered);
+    expect(new TextDecoder().decode(await eciesDecrypt(ct, privateKey))).toBe('x');
+  });
+
+  it('property: arbitrary plaintext round-trips', async () => {
+    await fc.assert(
+      fc.asyncProperty(fc.uint8Array({ minLength: 0, maxLength: 1024 }), async (pt) => {
+        const { privateKey, publicKey } = generateKeyPair();
+        const rt = await eciesDecrypt(await eciesEncrypt(pt, publicKey), privateKey);
+        expect(Array.from(rt)).toEqual(Array.from(pt));
+      }),
+      { numRuns: 25 },
+    );
+  });
+});

package/test/envelope.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import {
+  aesDecrypt,
+  eciesDecrypt,
+  generateKeyPair,
+  openEvidenceAsAgent,
+  sealEvidence,
+  __internals,
+} from '../src/crypto/index.js';
+import { CryptoError } from '../src/errors/index.js';
+
+describe('evidence envelope', () => {
+  it('seal → agent-open round-trips', async () => {
+    const agent = generateKeyPair();
+    const enclave = generateKeyPair();
+    const evidence = new TextEncoder().encode('I did the photography task');
+    const { envelope } = await sealEvidence({
+      evidence,
+      agentPubKey: agent.publicKey,
+      enclavePubKey: enclave.publicKey,
+    });
+    const recovered = await openEvidenceAsAgent(envelope, agent.privateKey);
+    expect(new TextDecoder().decode(recovered)).toBe('I did the photography task');
+  });
+
+  it('enclave-wrapped key also decrypts to the same AES key', async () => {
+    const agent = generateKeyPair();
+    const enclave = generateKeyPair();
+    const evidence = new TextEncoder().encode('enclave-path');
+    const { envelope, aesKey } = await sealEvidence({
+      evidence,
+      agentPubKey: agent.publicKey,
+      enclavePubKey: enclave.publicKey,
+    });
+    const parsed = __internals.parse(envelope);
+    const keyFromEnclave = await eciesDecrypt(parsed.wrappedForEnclave, enclave.privateKey);
+    const keyFromAgent = await eciesDecrypt(parsed.wrappedForAgent, agent.privateKey);
+    expect(Array.from(keyFromEnclave)).toEqual(Array.from(aesKey));
+    expect(Array.from(keyFromAgent)).toEqual(Array.from(aesKey));
+    // And the key decrypts the AES portion independently
+    const pt = await aesDecrypt(parsed.aesCiphertext, keyFromEnclave);
+    expect(new TextDecoder().decode(pt)).toBe('enclave-path');
+  });
+
+  it('wrong magic bytes throw CRYPTO/INTEGRITY_CHECK', async () => {
+    const agent = generateKeyPair();
+    const enclave = generateKeyPair();
+    const { envelope } = await sealEvidence({
+      evidence: new Uint8Array([1, 2, 3]),
+      agentPubKey: agent.publicKey,
+      enclavePubKey: enclave.publicKey,
+    });
+    envelope[0] = 0xff;
+    await expect(openEvidenceAsAgent(envelope, agent.privateKey)).rejects.toBeInstanceOf(CryptoError);
+  });
+
+  it('unknown version throws CRYPTO/UNSUPPORTED_CIPHER', async () => {
+    const agent = generateKeyPair();
+    const enclave = generateKeyPair();
+    const { envelope } = await sealEvidence({
+      evidence: new Uint8Array([1, 2, 3]),
+      agentPubKey: agent.publicKey,
+      enclavePubKey: enclave.publicKey,
+    });
+    envelope[2] = 0x99;
+    await expect(openEvidenceAsAgent(envelope, agent.privateKey)).rejects.toMatchObject({
+      code: 'CRYPTO/UNSUPPORTED_CIPHER',
+    });
+  });
+
+  it('truncated envelope throws CRYPTO/INTEGRITY_CHECK', async () => {
+    const agent = generateKeyPair();
+    const enclave = generateKeyPair();
+    const { envelope } = await sealEvidence({
+      evidence: new Uint8Array([1, 2, 3]),
+      agentPubKey: agent.publicKey,
+      enclavePubKey: enclave.publicKey,
+    });
+    const short = envelope.slice(0, 10);
+    await expect(openEvidenceAsAgent(short, agent.privateKey)).rejects.toBeInstanceOf(CryptoError);
+  });
+});

package/test/errors.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import {
+  BlindMarketError,
+  ConfigError,
+  CryptoError,
+  StorageError,
+  ChainError,
+  ComputeError,
+  ApiError,
+  LifecycleError,
+  TimeoutError,
+} from '../src/errors/index.js';
+
+describe('BlindMarketError', () => {
+  it('preserves code, message, retriable, context, cause', () => {
+    const cause = new Error('root');
+    const err = new StorageError('STORAGE/UPLOAD_FAILED', 'upload blew up', {
+      retriable: true,
+      context: { attempt: 1 },
+      cause,
+    });
+    expect(err).toBeInstanceOf(BlindMarketError);
+    expect(err.name).toBe('StorageError');
+    expect(err.code).toBe('STORAGE/UPLOAD_FAILED');
+    expect(err.message).toBe('upload blew up');
+    expect(err.retriable).toBe(true);
+    expect(err.context).toEqual({ attempt: 1 });
+    expect(err.cause).toBe(cause);
+  });
+
+  it('defaults retriable to false', () => {
+    const err = new ConfigError('CONFIG/MISSING_SIGNER', 'no signer');
+    expect(err.retriable).toBe(false);
+  });
+
+  it('exposes a stable toJSON for telemetry (no secrets)', () => {
+    const err = new ApiError('API/VALIDATION', 'bad input', { context: { field: 'reward' } });
+    const j = err.toJSON();
+    expect(j).toMatchObject({
+      name: 'ApiError',
+      code: 'API/VALIDATION',
+      message: 'bad input',
+      retriable: false,
+      context: { field: 'reward' },
+    });
+    expect(j).not.toHaveProperty('cause');
+  });
+
+  it.each([
+    [ConfigError, 'CONFIG/MISSING_SIGNER'],
+    [CryptoError, 'CRYPTO/DECRYPT_FAILED'],
+    [StorageError, 'STORAGE/NOT_FOUND'],
+    [ChainError, 'CHAIN/TX_REVERTED'],
+    [ComputeError, 'COMPUTE/BROKER_UNREACHABLE'],
+    [ApiError, 'API/RATE_LIMITED'],
+    [LifecycleError, 'LIFECYCLE/ILLEGAL_TRANSITION'],
+    [TimeoutError, 'TIMEOUT'],
+  ] as const)('subclass %p accepts its canonical code', (Ctor, code) => {
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic ctor call for table test
+    const err = new (Ctor as any)(code, 'msg');
+    expect(err.code).toBe(code);
+    expect(err).toBeInstanceOf(BlindMarketError);
+  });
+});

package/test/events.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it, vi } from 'vitest';
+import { EventBus, type SdkEvents } from '../src/events/index.js';
+
+const txPayload = { hash: '0xabc' as `0x${string}`, from: '0x00' as `0x${string}`, to: '0x01' as `0x${string}` };
+
+describe('EventBus', () => {
+  it('delivers typed events to subscribers', () => {
+    const bus = new EventBus<SdkEvents>();
+    const fn = vi.fn();
+    bus.on('tx.sent', fn);
+    bus.emit('tx.sent', txPayload);
+    expect(fn).toHaveBeenCalledWith(txPayload);
+  });
+
+  it('once fires only once', () => {
+    const bus = new EventBus<SdkEvents>();
+    const fn = vi.fn();
+    bus.once('tx.sent', fn);
+    bus.emit('tx.sent', txPayload);
+    bus.emit('tx.sent', txPayload);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('off removes a specific listener', () => {
+    const bus = new EventBus<SdkEvents>();
+    const fn = vi.fn();
+    bus.on('tx.sent', fn);
+    bus.off('tx.sent', fn);
+    bus.emit('tx.sent', txPayload);
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('on returns an unsubscribe function', () => {
+    const bus = new EventBus<SdkEvents>();
+    const fn = vi.fn();
+    const unsubscribe = bus.on('tx.sent', fn);
+    unsubscribe();
+    bus.emit('tx.sent', txPayload);
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('isolates listener exceptions (all other listeners still fire)', () => {
+    const bus = new EventBus<SdkEvents>();
+    const bad = vi.fn(() => {
+      throw new Error('boom');
+    });
+    const good = vi.fn();
+    bus.on('tx.sent', bad);
+    bus.on('tx.sent', good);
+    bus.emit('tx.sent', txPayload);
+    expect(bad).toHaveBeenCalled();
+    expect(good).toHaveBeenCalled();
+  });
+
+  it('emit with no subscribers is a no-op', () => {
+    const bus = new EventBus<SdkEvents>();
+    expect(() => bus.emit('tx.sent', txPayload)).not.toThrow();
+  });
+});

package/test/fixtures/crypto.json

@@ -0,0 +1,16 @@
+{
+  "_note": "Generated by scripts/gen-crypto-fixtures.mjs using Node built-in crypto, matching backend/src/services/crypto.ts. If the SDK decrypts these back to the expected plaintext, wire-format compatibility is proven. Regenerate only on intentional format changes.",
+  "hkdf_info": "BlindMarket-ECIES-v1",
+  "keypair": {
+    "privateKey": "0d1ab8008ec2d77282500acb8e2c8cb237a64e0d2a474ab8f2a8415723e5fb87",
+    "publicKey": "04f797b44d169c83d53b444ff690df5233616f4d93bb234e49c48a84d8b256e8291701bdcf4fc608aa987029ddad03957957f97e2cc408a4e9f1fa7d8286cdbcaf"
+  },
+  "plaintext": "hello cross-compat",
+  "aes": {
+    "key": "5516bb862924cf891c6071c11a07b7286e149b4886db5beb392cca1181f565d9",
+    "blob": "70baf194291fcac086eb0e0ce5cce9a7af3ec485776d1605aaa7732cf5e15b5d4fbd79a4549b44ec9dd266462619"
+  },
+  "ecies": {
+    "blob": "0480f4dbacb4a2bb8575b9c7a7e5f5d47f6f8dc9c804a8d01cb3e9f7101e7040f5937dee7d7e8787033af1259e00d877ab785dcd89f8fc79d62f8f4bf6b51fac8ea72518b2d7845ca6c054e7fd152774852583fca8b71185f418ce6aa29d6d10a7d51c85d02dcfbaeea534d346c27c"
+  }
+}

package/test/keystore.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import { generateAesKey } from '../src/crypto/index.js';
+import { CryptoError } from '../src/errors/index.js';
+import { InMemoryKeyStore } from '../src/keystore/index.js';
+import type { Address, Hex, TaskKey } from '../src/types.js';
+
+async function mkKey(): Promise<TaskKey> {
+  return { aesKey: await generateAesKey(), createdAt: new Date() };
+}
+
+describe('InMemoryKeyStore', () => {
+  it('round-trips task keys', async () => {
+    const ks = new InMemoryKeyStore();
+    const tk = await mkKey();
+    await ks.putTaskKey(42n, tk);
+    const got = await ks.getTaskKey(42n);
+    expect(got).not.toBeNull();
+    expect(got?.aesKey).toEqual(tk.aesKey);
+    expect(got?.createdAt.getTime()).toBe(tk.createdAt.getTime());
+  });
+
+  it('returns null for missing task keys', async () => {
+    const ks = new InMemoryKeyStore();
+    expect(await ks.getTaskKey(999n)).toBeNull();
+  });
+
+  it('list enumerates stored task IDs', async () => {
+    const ks = new InMemoryKeyStore();
+    await ks.putTaskKey(1n, await mkKey());
+    await ks.putTaskKey(2n, await mkKey());
+    const all = await ks.list();
+    expect(all.map((r) => r.taskId).sort()).toEqual([1n, 2n]);
+  });
+
+  it('delete removes a task key', async () => {
+    const ks = new InMemoryKeyStore();
+    await ks.putTaskKey(7n, await mkKey());
+    await ks.delete(7n);
+    expect(await ks.getTaskKey(7n)).toBeNull();
+  });
+
+  it('peer pubkey cache', async () => {
+    const ks = new InMemoryKeyStore();
+    const addr = '0x0000000000000000000000000000000000000001' as Address;
+    const pub = ('0x04' + '11'.repeat(64)) as Hex;
+    expect(await ks.getPeerPubKey(addr)).toBeNull();
+    await ks.putPeerPubKey(addr, pub);
+    expect(await ks.getPeerPubKey(addr)).toBe(pub);
+  });
+
+  it('returned AES key is a copy (mutations do not leak back)', async () => {
+    const ks = new InMemoryKeyStore();
+    await ks.putTaskKey(1n, await mkKey());
+    const a = await ks.getTaskKey(1n);
+    const b = await ks.getTaskKey(1n);
+    // biome-ignore lint/style/noNonNullAssertion: returned by an earlier non-null assertion
+    a!.aesKey[0] = (a!.aesKey[0]! ^ 0xff) & 0xff;
+    expect(b?.aesKey).not.toEqual(a?.aesKey);
+  });
+
+  it('export/import round-trips with the same passphrase', async () => {
+    const src = new InMemoryKeyStore();
+    await src.putTaskKey(1n, await mkKey());
+    await src.putTaskKey(2n, await mkKey());
+    const addr = '0x0000000000000000000000000000000000000009' as Address;
+    const pub = ('0x04' + 'ab'.repeat(64)) as Hex;
+    await src.putPeerPubKey(addr, pub);
+
+    const exported = await src.export('correct-horse-battery-staple');
+    const dst = new InMemoryKeyStore();
+    await dst.import(exported, 'correct-horse-battery-staple');
+
+    const srcList = (await src.list()).map((r) => r.taskId).sort();
+    const dstList = (await dst.list()).map((r) => r.taskId).sort();
+    expect(dstList).toEqual(srcList);
+    expect((await dst.getTaskKey(1n))?.aesKey).toEqual((await src.getTaskKey(1n))?.aesKey);
+    expect(await dst.getPeerPubKey(addr)).toBe(pub);
+  });
+
+  it('import with wrong passphrase fails', async () => {
+    const src = new InMemoryKeyStore();
+    await src.putTaskKey(1n, await mkKey());
+    const exported = await src.export('goodpassphrase');
+    const dst = new InMemoryKeyStore();
+    await expect(dst.import(exported, 'wrongpassphrase')).rejects.toBeInstanceOf(CryptoError);
+  });
+
+  it('export rejects short passphrases', async () => {
+    const ks = new InMemoryKeyStore();
+    await expect(ks.export('short')).rejects.toBeInstanceOf(CryptoError);
+  });
+
+  it('import rejects invalid JSON', async () => {
+    const ks = new InMemoryKeyStore();
+    await expect(ks.import('not-json', 'any-passphrase')).rejects.toBeInstanceOf(CryptoError);
+  });
+
+  it('import rejects unknown format', async () => {
+    const ks = new InMemoryKeyStore();
+    const fake = JSON.stringify({ format: 'other-format', salt: '00', blob: '00' });
+    await expect(ks.import(fake, 'any-passphrase')).rejects.toBeInstanceOf(CryptoError);
+  });
+});

package/test/network.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { ConfigError } from '../src/errors/index.js';
+import { networks, resolveNetwork, type Network } from '../src/network/index.js';
+
+describe('networks', () => {
+  it('testnet preset matches 0G Galileo', () => {
+    expect(networks.testnet.chainId).toBe(16602n);
+    expect(networks.testnet.contracts.escrow).toMatch(/^0x[a-fA-F0-9]{40}$/);
+    expect(networks.testnet.contracts.registry).toMatch(/^0x[a-fA-F0-9]{40}$/);
+    expect(networks.testnet.contracts.reputation).toMatch(/^0x[a-fA-F0-9]{40}$/);
+    expect(networks.testnet.contracts.usdc).toMatch(/^0x[a-fA-F0-9]{40}$/);
+    expect(networks.testnet.rpc.length).toBeGreaterThan(0);
+    expect(networks.testnet.indexer).toBeTruthy();
+    expect(networks.testnet.broker).toBeTruthy();
+  });
+
+  it('testnet addresses match contracts/deployments/0g-testnet.json', () => {
+    expect(networks.testnet.contracts.escrow).toBe('0xFd4F93F5A7BE144c405D1D8fbEC63Fb776207681');
+    expect(networks.testnet.contracts.registry).toBe('0xeE52d780A47F77E8a4a1cEb236e3C65A48FbD828');
+    expect(networks.testnet.contracts.reputation).toBe('0x4A6374Fae37E19E69ba43E7cf6994AC15F63256e');
+    expect(networks.testnet.contracts.usdc).toBe('0x317227efcA18D004E12CA8046AEf7E1597458F25');
+  });
+
+  it('resolveNetwork accepts a preset name', () => {
+    const n = resolveNetwork('testnet');
+    expect(n.chainId).toBe(16602n);
+    expect(n.name).toBe('0g-galileo-testnet');
+  });
+
+  it('resolveNetwork rejects unknown preset with ConfigError', () => {
+    // biome-ignore lint/suspicious/noExplicitAny: intentional type escape to test runtime error path
+    expect(() => resolveNetwork('nope' as any)).toThrow(ConfigError);
+  });
+
+  it('resolveNetwork passes through a custom network object', () => {
+    const custom: Network = {
+      name: 'localhost',
+      chainId: 1337n,
+      rpc: ['http://localhost:8545'],
+      contracts: {
+        escrow: '0x0000000000000000000000000000000000000001',
+        registry: '0x0000000000000000000000000000000000000002',
+        reputation: '0x0000000000000000000000000000000000000003',
+        usdc: '0x0000000000000000000000000000000000000004',
+      },
+      indexer: '',
+      broker: '',
+    };
+    const resolved = resolveNetwork(custom);
+    expect(resolved).toBe(custom);
+    expect(resolved.chainId).toBe(1337n);
+  });
+});

package/test/signer.test.ts

@@ -0,0 +1,66 @@
+import { ethers } from 'ethers';
+import { describe, expect, it } from 'vitest';
+import { eciesDecrypt, eciesEncrypt } from '../src/crypto/index.js';
+import { EthersSigner, PrivateKeySigner } from '../src/signer/index.js';
+
+const FIXED_PK = '0x0123456789012345678901234567890123456789012345678901234567890123';
+const FIXED_ADDR = '0x14791697260E4c9A71f18484C9f997B308e59325';
+
+describe('PrivateKeySigner', () => {
+  it('derives the correct address from a known private key', async () => {
+    const signer = new PrivateKeySigner(FIXED_PK);
+    expect((await signer.getAddress()).toLowerCase()).toBe(FIXED_ADDR.toLowerCase());
+  });
+
+  it('accepts the private key with or without 0x prefix', async () => {
+    const a = new PrivateKeySigner(FIXED_PK);
+    const b = new PrivateKeySigner(FIXED_PK.slice(2));
+    expect(await a.getAddress()).toBe(await b.getAddress());
+  });
+
+  it('signMessage produces a signature that recovers to the signer address', async () => {
+    const signer = new PrivateKeySigner(FIXED_PK);
+    const msg = 'hello';
+    const sig = await signer.signMessage(msg);
+    const recovered = ethers.verifyMessage(msg, sig);
+    expect(recovered.toLowerCase()).toBe(FIXED_ADDR.toLowerCase());
+  });
+
+  it('getPublicKey returns the uncompressed key (65 bytes / 130 hex + 0x)', async () => {
+    const signer = new PrivateKeySigner(FIXED_PK);
+    const pub = await signer.getPublicKey();
+    expect(pub.startsWith('0x04')).toBe(true);
+    expect(pub.length).toBe(2 + 130);
+  });
+
+  it('pubkey from signer round-trips through ECIES', async () => {
+    const signer = new PrivateKeySigner(FIXED_PK);
+    const pub = await signer.getPublicKey();
+    const plaintext = new TextEncoder().encode('direct-to-signer-pubkey');
+    const blob = await eciesEncrypt(plaintext, pub);
+    const pt = await eciesDecrypt(blob, FIXED_PK);
+    expect(new TextDecoder().decode(pt)).toBe('direct-to-signer-pubkey');
+  });
+
+  it('getPublicKey is cached (returns identical string instance)', async () => {
+    const signer = new PrivateKeySigner(FIXED_PK);
+    const a = await signer.getPublicKey();
+    const b = await signer.getPublicKey();
+    expect(a).toBe(b);
+  });
+});
+
+describe('EthersSigner wrapping an arbitrary ethers.Signer', () => {
+  it('wraps a provider-less Wallet and passes through signMessage', async () => {
+    const wallet = new ethers.Wallet(FIXED_PK);
+    const signer = new EthersSigner(wallet);
+    const sig = await signer.signMessage('x');
+    expect(ethers.verifyMessage('x', sig).toLowerCase()).toBe(FIXED_ADDR.toLowerCase());
+  });
+
+  it('chainId throws ConfigError when no provider is attached', async () => {
+    const wallet = new ethers.Wallet(FIXED_PK);
+    const signer = new EthersSigner(wallet);
+    await expect(signer.chainId()).rejects.toMatchObject({ code: 'CONFIG/BAD_CONFIG' });
+  });
+});

package/test/smoke.test.ts

@@ -0,0 +1,7 @@
+import { describe, expect, it } from 'vitest';
+
+describe('smoke', () => {
+  it('vitest runs', () => {
+    expect(1 + 1).toBe(2);
+  });
+});