@hivemind-os/collective-core 0.2.0

package/tests/walrus-spike.test.ts

@@ -0,0 +1,100 @@
+import { createHash, randomBytes } from 'node:crypto';
+
+import { describe, expect, it } from 'vitest';
+
+import { WalrusBlobStore } from '../src/index.js';
+import {
+  DEFAULT_WALRUS_AGGREGATOR_URL,
+  DEFAULT_WALRUS_PUBLISHER_URL,
+  WalrusNetworkError,
+  fetchBlobFromWalrus,
+  moveVectorToWalrusBlobId,
+  storeBlobOnWalrus,
+  walrusBlobIdToMoveVector,
+} from '../src/blobstore/walrus-spike.js';
+
+const runWalrusTestnet = process.env.RUN_WALRUS_TESTNET === '1';
+const describeWalrus = runWalrusTestnet ? describe : describe.skip;
+
+function sha256(data: Uint8Array): string {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+describe('Walrus spike helpers', () => {
+  it('round-trips Walrus blob IDs through Move-friendly bytes', () => {
+    const blobId = 'a7wmADgKiwLDFnpjyu6NBTkCS-1zLblj3TfmXZWxnew';
+
+    const moveBytes = walrusBlobIdToMoveVector(blobId);
+
+    expect(moveBytes).toHaveLength(32);
+    expect(moveVectorToWalrusBlobId(moveBytes)).toBe(blobId);
+  });
+
+  it('wraps network errors', async () => {
+    const data = new TextEncoder().encode('offline');
+
+    await expect(
+      storeBlobOnWalrus(data, {
+        fetchImpl: async () => {
+          throw new TypeError('network offline');
+        },
+      }),
+    ).rejects.toBeInstanceOf(WalrusNetworkError);
+  });
+
+  it('explains why delete is unsupported', async () => {
+    const store = new WalrusBlobStore({
+      publisherUrl: DEFAULT_WALRUS_PUBLISHER_URL,
+      aggregatorUrl: DEFAULT_WALRUS_AGGREGATOR_URL,
+    });
+
+    await expect(store.delete('ignored')).rejects.toThrow(/public HTTP API/i);
+  });
+});
+
+describeWalrus('Walrus testnet spike', () => {
+  const publisherUrl = process.env.WALRUS_PUBLISHER_URL ?? DEFAULT_WALRUS_PUBLISHER_URL;
+  const aggregatorUrl = process.env.WALRUS_AGGREGATOR_URL ?? DEFAULT_WALRUS_AGGREGATOR_URL;
+  const epochs = Number(process.env.WALRUS_EPOCHS ?? '1');
+
+  it('stores and fetches a small blob with matching SHA-256', async () => {
+    const data = new TextEncoder().encode(`Hello, Walrus! ${Date.now()}`);
+    const result = await storeBlobOnWalrus(data, {
+      publisherUrl,
+      aggregatorUrl,
+      epochs,
+      permanent: true,
+    });
+
+    const fetched = await fetchBlobFromWalrus(result.blobId, { aggregatorUrl });
+
+    expect(result.blobId).toMatch(/^[A-Za-z0-9_-]{43}$/);
+    expect(result.storeMs).toBeGreaterThan(0);
+    expect(result.checksum).toBe(sha256(data));
+    expect(result.deletable).toBe(false);
+    expect(Buffer.from(fetched ?? [])).toEqual(Buffer.from(data));
+    expect(sha256(fetched ?? new Uint8Array())).toBe(result.checksum);
+  }, 120_000);
+
+  it('stores and fetches a 1 MiB blob through WalrusBlobStore', async () => {
+    const data = randomBytes(1024 * 1024);
+    const store = new WalrusBlobStore({ publisherUrl, aggregatorUrl, epochs });
+
+    const stored = await store.store(data);
+    const fetched = await store.fetch(stored.blobId);
+
+    expect(stored.blobId).toMatch(/^walrus:[A-Za-z0-9_-]{43}:[a-f0-9]{64}$/);
+    expect(stored.checksum).toBe(sha256(data));
+    expect(Buffer.from(fetched ?? [])).toEqual(Buffer.from(data));
+    expect(await store.exists(stored.blobId)).toBe(true);
+  }, 180_000);
+
+  it('returns null for a missing valid blob ID and errors for malformed IDs', async () => {
+    const store = new WalrusBlobStore({ publisherUrl, aggregatorUrl, epochs });
+    const missingBlobId = Buffer.alloc(32, 0x11).toString('base64url');
+
+    await expect(store.fetch(missingBlobId)).resolves.toBeNull();
+    await expect(store.exists(missingBlobId)).resolves.toBe(false);
+    await expect(store.fetch('not-a-real-id')).rejects.toThrow(/Invalid Walrus blob ID/);
+  }, 60_000);
+});

package/tests/walrus-store.test.ts

@@ -0,0 +1,196 @@
+import { createHash } from 'node:crypto';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  BlobIntegrityError,
+  WalrusBlobStore,
+  WalrusBlobTooLargeError,
+  WalrusHttpError,
+  WalrusResponseError,
+  WalrusTimeoutError,
+  createWalrusBlobReference,
+} from '../src/index.js';
+
+type FetchImpl = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+const encoder = new TextEncoder();
+const walrusStorageBlobId = Buffer.alloc(32, 0x11).toString('base64url');
+
+function sha256(data: Uint8Array): string {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+function createStore(fetchImpl: typeof fetch): WalrusBlobStore {
+  return new WalrusBlobStore({
+    publisherUrl: 'https://publisher.example.com',
+    aggregatorUrl: 'https://aggregator.example.com',
+    epochs: 5,
+    retryAttempts: 3,
+    retryDelayMs: 1,
+    timeoutMs: 10,
+    fetchImpl,
+  });
+}
+
+describe('WalrusBlobStore', () => {
+  it('stores blobs with the Walrus publisher API', async () => {
+    const data = encoder.encode('store me');
+    const fetchImpl = vi.fn<FetchImpl>().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          newlyCreated: {
+            blobObject: {
+              id: '0xblob-object',
+              blobId: walrusStorageBlobId,
+              size: data.byteLength,
+              deletable: false,
+              storage: { endEpoch: 12 },
+            },
+          },
+        }),
+        { status: 200, headers: { 'content-type': 'application/json' } },
+      ),
+    );
+    const store = createStore(fetchImpl);
+
+    const result = await store.store(data);
+    const [url, init] = fetchImpl.mock.calls[0] ?? [];
+    const parsedUrl = new URL(String(url));
+
+    expect(parsedUrl.origin).toBe('https://publisher.example.com');
+    expect(parsedUrl.pathname).toBe('/v1/blobs');
+    expect(parsedUrl.searchParams.get('epochs')).toBe('5');
+    expect(parsedUrl.searchParams.get('permanent')).toBe('true');
+    expect(init?.method).toBe('PUT');
+    expect(init?.headers).toMatchObject({ 'content-type': 'application/octet-stream' });
+    expect(result).toMatchObject({
+      blobId: createWalrusBlobReference(walrusStorageBlobId, sha256(data)),
+      hash: sha256(data),
+      checksum: sha256(data),
+      contentHash: sha256(data),
+      size: data.byteLength,
+      storageBlobId: walrusStorageBlobId,
+      objectId: '0xblob-object',
+    });
+  });
+
+  it('fetches blobs from the Walrus aggregator API', async () => {
+    const data = encoder.encode('fetch me');
+    const blobId = createWalrusBlobReference(walrusStorageBlobId, sha256(data));
+    const fetchImpl = vi.fn<FetchImpl>().mockResolvedValue(new Response(data, { status: 200 }));
+    const store = createStore(fetchImpl);
+
+    const fetched = await store.fetch(blobId);
+    const [url, init] = fetchImpl.mock.calls[0] ?? [];
+
+    expect(String(url)).toBe(`https://aggregator.example.com/v1/blobs/${walrusStorageBlobId}`);
+    expect(init?.method).toBe('GET');
+    expect(Buffer.from(fetched ?? [])).toEqual(Buffer.from(data));
+  });
+
+  it('retries transient failures', async () => {
+    const data = encoder.encode('retry me');
+    const fetchImpl = vi
+      .fn<FetchImpl>()
+      .mockResolvedValueOnce(new Response('temporary outage', { status: 503 }))
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            newlyCreated: {
+              blobObject: {
+                id: '0xblob-object',
+                blobId: walrusStorageBlobId,
+                size: data.byteLength,
+                deletable: false,
+              },
+            },
+          }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        ),
+      );
+    const store = createStore(fetchImpl);
+
+    const result = await store.store(data);
+
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+    expect(result.hash).toBe(sha256(data));
+  });
+
+  it('fails fast on permanent errors', async () => {
+    const fetchImpl = vi.fn<FetchImpl>().mockResolvedValue(new Response('bad request', { status: 400 }));
+    const store = createStore(fetchImpl);
+
+    await expect(store.store(encoder.encode('boom'))).rejects.toBeInstanceOf(WalrusHttpError);
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+
+  it('treats malformed publisher responses as permanent protocol errors', async () => {
+    const fetchImpl = vi.fn<FetchImpl>().mockResolvedValue(new Response('not-json', { status: 200 }));
+    const store = createStore(fetchImpl);
+
+    await expect(store.store(encoder.encode('boom'))).rejects.toBeInstanceOf(WalrusResponseError);
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+
+  it('enforces the size limit before upload', async () => {
+    const fetchImpl = vi.fn<FetchImpl>();
+    const store = new WalrusBlobStore({
+      publisherUrl: 'https://publisher.example.com',
+      aggregatorUrl: 'https://aggregator.example.com',
+      maxBlobSize: 4,
+      fetchImpl,
+    });
+
+    await expect(store.store(encoder.encode('oversized'))).rejects.toBeInstanceOf(WalrusBlobTooLargeError);
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it('times out stalled requests', async () => {
+    const fetchImpl = vi.fn<FetchImpl>().mockImplementation(async (_url, init) => {
+      await new Promise((_resolve, reject) => {
+        init?.signal?.addEventListener('abort', () => {
+          reject(new DOMException('The operation was aborted.', 'AbortError'));
+        });
+      });
+      return new Response(null, { status: 500 });
+    });
+    const store = new WalrusBlobStore({
+      publisherUrl: 'https://publisher.example.com',
+      aggregatorUrl: 'https://aggregator.example.com',
+      timeoutMs: 5,
+      retryAttempts: 1,
+      retryDelayMs: 1,
+      fetchImpl,
+    });
+
+    await expect(store.store(encoder.encode('slow'))).rejects.toBeInstanceOf(WalrusTimeoutError);
+  });
+
+  it('verifies content integrity on fetch', async () => {
+    const data = encoder.encode('safe payload');
+    const corrupted = encoder.encode('corrupted payload');
+    const fetchImpl = vi
+      .fn<FetchImpl>()
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            newlyCreated: {
+              blobObject: {
+                id: '0xblob-object',
+                blobId: walrusStorageBlobId,
+                size: data.byteLength,
+                deletable: false,
+              },
+            },
+          }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        ),
+      )
+      .mockResolvedValueOnce(new Response(corrupted, { status: 200 }));
+    const store = createStore(fetchImpl);
+    const stored = await store.store(data);
+
+    await expect(store.fetch(stored.blobId)).rejects.toBeInstanceOf(BlobIntegrityError);
+  });
+});

package/tests/x402/client.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+import { decodePaymentSignatureHeader, encodePaymentRequiredHeader } from '@x402/core/http';
+import { hexToBytes } from 'viem';
+
+import { EvmWallet, USDC_ADDRESS, X402Client, type X402PaymentRequest } from '../../src/index.js';
+
+const PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+const PAYER_ADDRESS = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266';
+const PAY_TO = '0x0000000000000000000000000000000000000abc';
+
+function createClient() {
+  const wallet = new EvmWallet(hexToBytes(PRIVATE_KEY), { network: 'base-sepolia' });
+  return new X402Client(wallet);
+}
+
+function createManualRequest(overrides: Partial<X402PaymentRequest> = {}): X402PaymentRequest {
+  return {
+    paymentAddress: PAY_TO,
+    amount: '1000000',
+    currency: 'USDC',
+    network: 'base-sepolia',
+    nonce: 'nonce-123',
+    expiresAt: Date.now() + 60_000,
+    ...overrides,
+  };
+}
+
+describe('X402Client', () => {
+  it('parses PAYMENT-REQUIRED headers into a payment request', () => {
+    const client = createClient();
+    const header = encodePaymentRequiredHeader({
+      x402Version: 2,
+      resource: { url: 'https://relay.example.com/task' },
+      accepts: [
+        {
+          scheme: 'exact',
+          network: 'eip155:84532',
+          asset: USDC_ADDRESS['base-sepolia'],
+          amount: '1000000',
+          payTo: PAY_TO,
+          maxTimeoutSeconds: 300,
+          extra: {
+            assetTransferMethod: 'permit2',
+            currency: 'USDC',
+          },
+        },
+      ],
+    });
+
+    const request = client.parse402Response({ 'PAYMENT-REQUIRED': header });
+
+    expect(request).toMatchObject({
+      paymentAddress: PAY_TO,
+      amount: '1000000',
+      currency: 'USDC',
+      network: 'base-sepolia',
+    });
+    expect(request.expiresAt).toBeGreaterThan(Date.now());
+  });
+
+  it('signs and verifies payment authorizations', async () => {
+    const client = createClient();
+    const request = createManualRequest();
+
+    const signature = await client.signPayment(request);
+
+    expect(signature.payerAddress).toBe(PAYER_ADDRESS);
+    await expect(client.verifyPayment(signature, request)).resolves.toBe(true);
+    await expect(client.verifyPayment(signature, { ...request, amount: '2000000' })).resolves.toBe(false);
+  });
+
+  it('creates a standard PAYMENT-SIGNATURE header for x402 challenges', async () => {
+    const client = createClient();
+    const request = client.parse402Response({
+      'payment-required': encodePaymentRequiredHeader({
+        x402Version: 2,
+        resource: { url: 'https://relay.example.com/task' },
+        accepts: [
+          {
+            scheme: 'exact',
+            network: 'eip155:84532',
+            asset: USDC_ADDRESS['base-sepolia'],
+            amount: '1000000',
+            payTo: PAY_TO,
+            maxTimeoutSeconds: 300,
+            extra: {
+              assetTransferMethod: 'permit2',
+              currency: 'USDC',
+            },
+          },
+        ],
+      }),
+    });
+
+    const header = await client.createPaymentHeader(request);
+    const decoded = decodePaymentSignatureHeader(header);
+
+    expect(decoded.x402Version).toBe(2);
+    expect(decoded.accepted.payTo).toBe(PAY_TO);
+    expect(decoded.accepted.amount).toBe('1000000');
+    expect(decoded.payload).toHaveProperty('signature');
+  });
+
+  it('rejects invalid or expired payment authorizations', async () => {
+    const client = createClient();
+    const request = createManualRequest();
+    const signature = await client.signPayment(request);
+
+    await expect(
+      client.verifyPayment({ ...signature, signature: `0x${'0'.repeat(130)}` }, request),
+    ).resolves.toBe(false);
+    await expect(
+      client.signPayment({ ...request, expiresAt: Date.now() - 1 }),
+    ).rejects.toThrow('Payment challenge has expired.');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "dist",
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "vitest.config.ts", "tsup.config.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  target: 'es2022',
+  external: ['keytar'],
+});

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    passWithNoTests: false,
+  },
+});