# IPFS Integration Service

Manages decentralized storage workflows for Lilith content. The service pins
JSON/file payloads to IPFS, orchestrates replication across providers,
implements cache-aware retrieval with gateway fallbacks, and emits analytics +
audit events for observability.

## Pipeline

1. **Hash calculator** – computes deterministic digests for payloads prior to
   pinning.
2. **IPFS client** – uploads JSON/files and retrieves content from primary
   nodes.
3. **Pinning service** – ensures content is pinned across configured providers &
   gateways.
4. **Gateway resolver** – supplies fallback reads when primary IPFS retrieval
   fails.
5. **Cache layer** – memoizes recently retrieved content for low-latency
   lookups.
6. **Analytics + audit** – records storage, retrieval, and replication events.
7. **Event Bus** – broadcasts replication notifications for downstream
   consumers.

## Usage

```ts
import { createIpfsIntegrationService } from './service';

const service = createIpfsIntegrationService({
  ipfsClient,
  gatewayResolver,
  pinningService,
  hashCalculator,
  analyticsReporter,
  auditLog,
  cache,
});

const stored = await service.storeJsonContent({
  payload: { title: 'Emerald Meditation', body: 'Light arises...' },
  metadata: { contentId: 'content_emerald_light' },
  pinProviders: ['pinata'],
  redundantGateways: ['https://gateway.lilith.ai/ipfs'],
});

const content = await service.retrieveJson({
  cid: stored.cid,
  allowGatewayFallback: true,
});
```

## Tests

```bash
npx jest --config apps/lilith/svc-ipfs-integration/jest.config.cjs --runInBand
```