# Token Access Service

Token-gated access orchestrator for Lilith premium features and content. The
service evaluates token holdings across chains, persists entitlements, anchors
policy decisions, and emits analytics for downstream systems.

## Pipeline

1. **Policy registry** – stores access policies with required token sets and
   usage scope.
2. **Token gateway** – fetches wallet holdings and verifies thresholds on
   configured chains.
3. **Entitlement store** – persists issued entitlements and revocations for
   auditing.
4. **Anchor registry** – records policy, entitlement, and revocation anchors
   on-chain.
5. **Compliance guard** – validates policy definitions and entitlement requests.
6. **Analytics + event bus** – surfaces metrics and events for platform
   telemetry.
7. **Audit log** – captures policy/entitlement lifecycle actions for compliance
   teams.

## Usage

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

const service = createTokenAccessService({
  policyRegistry,
  tokenGateway,
  entitlementStore,
  anchorRegistry,
  analyticsReporter,
  eventBus,
  complianceGuard,
  auditLog,
});

const policy = await service.createAccessPolicy({
  name: 'Premium Meditation Gate',
  chainId: 137,
  requiredTokens: [
    {
      tokenId: 'premium_subscription',
      contractAddress: '0xsubscription',
      minBalance: 1,
    },
  ],
  usageScope: {
    contentIds: ['content_emerald_light'],
    featureFlags: ['live_retreats'],
  },
  grantType: 'subscription',
  createdBy: 'guardian-aurelia',
});

const entitlement = await service.evaluateEntitlements({
  policyId: policy.policyId,
  walletAddress: '0xuser',
  chainId: 137,
  requestedContentId: 'content_emerald_light',
});
```

## Tests

```bash
npx jest --config apps/lilith/svc-token-access/jest.config.cjs --runInBand
```