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

prisma/schema/key-metadata.prisma

@@ -0,0 +1,22 @@
+// prisma/schema/key-metadata.prisma
+
+model KeyMetadata {
+  id             String    @id @default(cuid())
+  keyId          String    @unique
+  keyAddress     String?
+  name           String
+  symbol         String
+  description    String?
+  imageCid       String?   @map("image_cid")
+  imageUrl       String?   @map("image_url")
+  lastSyncedAt   DateTime  @default(now()) @map("last_synced_at")
+  contractUpdatedAt DateTime? @map("contract_updated_at")
+  txHash         String?   @map("tx_hash")
+  ledger         Int?
+  createdAt      DateTime  @default(now()) @map("created_at")
+  updatedAt      DateTime  @updatedAt @map("updated_at")
+
+  @@index([keyId])
+  @@index([keyAddress])
+  @@map("key_metadata")
+}

src/config.schema.ts

@@ -421,6 +421,13 @@ export const envSchema = z
          .positive()
          .default(60),
 
+      // Creator key on-chain metadata sync (#986)
+      PINATA_GATEWAY_URL: z.string().default('https://gateway.pinata.cloud/ipfs'),
+      METADATA_STALENESS_THRESHOLD_MS: z.coerce
+         .number()
+         .int()
+         .positive()
+         .default(10 * 60 * 1000), // 10 minutes
    })
    .superRefine((data, ctx) => {
       if (data.MODE === 'production' && data.STELLAR_NETWORK === 'testnet') {

src/modules/indexer/key-metadata-indexer.service.ts

@@ -0,0 +1,67 @@
+// src/modules/indexer/key-metadata-indexer.service.ts
+/**
+ * Indexes `MetadataUpdated` events emitted by creator key contracts (#986).
+ *
+ * Keeps the off-chain metadata cache synchronized with on-chain contract state.
+ */
+
+import { logger } from '../../utils/logger.utils';
+import {
+   processIndexerChainEvents,
+   IndexerChainEvent,
+   getChainEventId,
+} from '../../utils/indexer-event-processor.utils';
+import {
+   handleMetadataUpdatedChainEvent,
+} from '../keys/key-metadata-sync.service';
+
+export interface ContractMetadataUpdatedEvent extends IndexerChainEvent {
+   eventType: 'MetadataUpdated' | 'METADATA_UPDATED';
+   keyAddress?: string;
+   creatorId?: string;
+   keyId?: string;
+   name?: string;
+   symbol?: string;
+   description?: string;
+   image_cid?: string;
+}
+
+/**
+ * Applies MetadataUpdated events to the database and re-syncs the metadata cache.
+ */
+export async function processMetadataUpdatedEvents(
+   events: IndexerChainEvent[]
+): Promise<void> {
+   await processIndexerChainEvents(events, async (event) => {
+      if (
+         event.eventType !== 'MetadataUpdated' &&
+         event.eventType !== 'METADATA_UPDATED'
+      ) {
+         return;
+      }
+
+      const metaEvent = event as ContractMetadataUpdatedEvent;
+      const keyId = metaEvent.keyAddress || metaEvent.creatorId || metaEvent.keyId;
+
+      if (!keyId) {
+         logger.warn(
+            { eventId: getChainEventId(event) },
+            'Skipping MetadataUpdated event with missing key identifier'
+         );
+         return;
+      }
+
+      await handleMetadataUpdatedChainEvent({
+         eventType: metaEvent.eventType,
+         keyAddress: metaEvent.keyAddress,
+         creatorId: metaEvent.creatorId,
+         keyId: metaEvent.keyId,
+         name: metaEvent.name,
+         symbol: metaEvent.symbol,
+         description: metaEvent.description,
+         image_cid: metaEvent.image_cid,
+         txHash: event.txHash,
+         ledger: event.ledger,
+      });
+   });
+}