feat(keys): build on-chain metadata sync service for creator key contracts (#986)

[bamiebot-maker]

Summary

Implements a background on-chain metadata synchronization service for creator key contracts, addressing #986. The service synchronizes on-chain metadata (name, symbol, description, image_cid) into the off-chain API metadata cache, resolves IPFS CIDs to Pinata gateway URLs, triggers automatic sync on key creation and on MetadataUpdated contract events, and exposes GET /keys/:keyId/metadata with an accurate stale flag when synchronization is delayed.

Key Changes

1. Key Metadata Storage Model:

   • Added KeyMetadata model in prisma/schema/key-metadata.prisma storing keyId, keyAddress, name, symbol, description, imageCid, imageUrl, lastSyncedAt, contractUpdatedAt, txHash, and ledger.

2. IPFS / Pinata Gateway URL Resolution:

   • Implemented resolvePinataGatewayUrl(imageCid, gatewayBaseUrl) handling raw CIDs (Qm..., bafy...), ipfs:// protocol URIs, and /ipfs/ prefixes, mapping to configured PINATA_GATEWAY_URL (https://gateway.pinata.cloud/ipfs/${cid}).

3. Background On-Chain Metadata Synchronization Service:

   • Implemented syncKeyMetadata(keyIdentifier, onChainData?, eventContext?) in src/modules/keys/key-metadata-sync.service.ts.
   • Supports pluggable contract metadata readers (setOnChainMetadataFetcher) and fallback to contract storage readers.
   • Upserts synced records into the database and refreshes Redis cache.

4. Event-Driven Synchronization Triggers:

   • Key creation: Subscribes to key_registered events via initKeyCreationMetadataSync() on server boot to automatically initiate metadata synchronization upon key contract registration.
   • MetadataUpdated chain event: Implemented handleMetadataUpdatedChainEvent and processMetadataUpdatedEvents in src/modules/indexer/key-metadata-indexer.service.ts to trigger / schedule re-sync within 60 seconds of on-chain event receipt.

5. Metadata API Endpoint (GET /api/v1/keys/:keyId/metadata):

   • Added endpoint in src/modules/keys/keys.routes.ts returning synced metadata.
   • Dynamically evaluates staleness based on Date.now() - lastSyncedAt > METADATA_STALENESS_THRESHOLD_MS (default: 10 minutes) and includes stale: boolean in response.
   • Returns 404 with standard API error format when key metadata is not found.

6. Configuration:

   • Added PINATA_GATEWAY_URL and METADATA_STALENESS_THRESHOLD_MS to src/config.schema.ts.

7. Automated Testing:

   • Added unit test suite in src/modules/keys/key-metadata-sync.service.test.ts (12 tests) verifying gateway resolution, sync execution, staleness detection, event handling, and key registration listeners.
   • Added route tests in src/modules/keys/key-metadata.routes.test.ts (3 tests) verifying 200 responses, stale flag detection, and 404 handling.

Verification

• pnpm test src/modules/keys/key-metadata-sync.service.test.ts src/modules/keys/key-metadata.routes.test.ts: 15/15 tests passing.
• pnpm build: TypeScript compilation succeeded with 0 errors.
• pnpm eslint ...: Lint checks passed with 0 errors.

Closes #986

[drips-wave]

@bamiebot-maker Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits