@1001-digital/ponder-artifacts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 1001.digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,433 @@
+import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
+import { Hono } from 'hono';
+
+declare const offchainSchema: drizzle_orm_pg_core.PgSchema<"offchain">;
+declare const artifactToken: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "artifact_token";
+    schema: "offchain";
+    columns: {
+        collection: drizzle_orm_pg_core.PgColumn<{
+            name: "collection";
+            tableName: "artifact_token";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tokenId: drizzle_orm_pg_core.PgColumn<{
+            name: "token_id";
+            tableName: "artifact_token";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tokenStandard: drizzle_orm_pg_core.PgColumn<{
+            name: "token_standard";
+            tableName: "artifact_token";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tokenUri: drizzle_orm_pg_core.PgColumn<{
+            name: "token_uri";
+            tableName: "artifact_token";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: drizzle_orm_pg_core.PgColumn<{
+            name: "name";
+            tableName: "artifact_token";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        description: drizzle_orm_pg_core.PgColumn<{
+            name: "description";
+            tableName: "artifact_token";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        image: drizzle_orm_pg_core.PgColumn<{
+            name: "image";
+            tableName: "artifact_token";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        animationUrl: drizzle_orm_pg_core.PgColumn<{
+            name: "animation_url";
+            tableName: "artifact_token";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        data: drizzle_orm_pg_core.PgColumn<{
+            name: "data";
+            tableName: "artifact_token";
+            dataType: "json";
+            columnType: "PgJson";
+            data: Record<string, unknown>;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "artifact_token";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+declare const artifactCollection: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "artifact_collection";
+    schema: "offchain";
+    columns: {
+        collection: drizzle_orm_pg_core.PgColumn<{
+            name: "collection";
+            tableName: "artifact_collection";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tokenStandard: drizzle_orm_pg_core.PgColumn<{
+            name: "token_standard";
+            tableName: "artifact_collection";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: drizzle_orm_pg_core.PgColumn<{
+            name: "name";
+            tableName: "artifact_collection";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        symbol: drizzle_orm_pg_core.PgColumn<{
+            name: "symbol";
+            tableName: "artifact_collection";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        owner: drizzle_orm_pg_core.PgColumn<{
+            name: "owner";
+            tableName: "artifact_collection";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        contractUri: drizzle_orm_pg_core.PgColumn<{
+            name: "contract_uri";
+            tableName: "artifact_collection";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        description: drizzle_orm_pg_core.PgColumn<{
+            name: "description";
+            tableName: "artifact_collection";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        image: drizzle_orm_pg_core.PgColumn<{
+            name: "image";
+            tableName: "artifact_collection";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        data: drizzle_orm_pg_core.PgColumn<{
+            name: "data";
+            tableName: "artifact_collection";
+            dataType: "json";
+            columnType: "PgJson";
+            data: Record<string, unknown>;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "artifact_collection";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+
+type TokenStandard = "erc721" | "erc1155" | "unknown";
+type ArtifactToken = {
+    collection: string;
+    tokenId: string;
+    tokenStandard: TokenStandard;
+    tokenUri: string | null;
+    name: string | null;
+    description: string | null;
+    image: string | null;
+    animationUrl: string | null;
+    data: Record<string, unknown> | null;
+    updatedAt: number;
+};
+type ArtifactCollection = {
+    collection: string;
+    tokenStandard: TokenStandard;
+    name: string | null;
+    symbol: string | null;
+    owner: string | null;
+    contractUri: string | null;
+    description: string | null;
+    image: string | null;
+    data: Record<string, unknown> | null;
+    updatedAt: number;
+};
+type ArtifactPluginConfig = {
+    /** Viem public client for on-chain reads. */
+    client: {
+        readContract: (args: {
+            address: `0x${string}`;
+            abi: readonly unknown[];
+            functionName: string;
+            args?: readonly unknown[];
+        }) => Promise<unknown>;
+    };
+    /** Drizzle DB instance. Use createOffchainDb() or provide your own. */
+    db: any;
+    /** Cache TTL in milliseconds. Defaults to 30 days. */
+    cacheTtl?: number;
+    /** IPFS gateway URL. Defaults to https://ipfs.io/ipfs/ */
+    ipfsGateway?: string;
+    /** Arweave gateway URL. Defaults to https://arweave.net/ */
+    arweaveGateway?: string;
+};
+
+declare function createArtifactService(config: ArtifactPluginConfig): {
+    fetchToken: (collection: string, tokenId: string) => Promise<ArtifactToken | null>;
+    updateToken: (collection: string, tokenId: string) => Promise<void>;
+    fetchCollection: (address: string) => Promise<ArtifactCollection | null>;
+    updateCollection: (address: string) => Promise<void>;
+    isFresh: (timestamp: number | null) => boolean;
+};
+
+declare function createArtifactRoutes(config: ArtifactPluginConfig): Hono;
+
+declare function createOffchainDb(options?: {
+    databaseUrl?: string;
+    dataDir?: string;
+}): Promise<{
+    db: any;
+}>;
+
+interface ResolveUriOptions {
+    ipfsGateway?: string;
+    arweaveGateway?: string;
+}
+declare function resolveUri(uri?: string | null, options?: ResolveUriOptions): string;
+declare function fetchJson(uri: string, options?: ResolveUriOptions): Promise<Record<string, unknown>>;
+
+export { type ArtifactCollection, type ArtifactPluginConfig, type ArtifactToken, type TokenStandard, artifactCollection, artifactToken, createArtifactRoutes, createArtifactService, createOffchainDb, fetchJson, offchainSchema, resolveUri };

package/dist/index.js

@@ -0,0 +1,376 @@
+// src/schema.ts
+import { pgSchema, text, integer, json, primaryKey } from "drizzle-orm/pg-core";
+var offchainSchema = pgSchema("offchain");
+var artifactToken = offchainSchema.table(
+  "artifact_token",
+  {
+    collection: text("collection").notNull(),
+    tokenId: text("token_id").notNull(),
+    tokenStandard: text("token_standard").notNull(),
+    tokenUri: text("token_uri"),
+    name: text("name"),
+    description: text("description"),
+    image: text("image"),
+    animationUrl: text("animation_url"),
+    data: json("data").$type(),
+    updatedAt: integer("updated_at").notNull()
+  },
+  (table) => [primaryKey({ columns: [table.collection, table.tokenId] })]
+);
+var artifactCollection = offchainSchema.table(
+  "artifact_collection",
+  {
+    collection: text("collection").primaryKey(),
+    tokenStandard: text("token_standard").notNull(),
+    name: text("name"),
+    symbol: text("symbol"),
+    owner: text("owner"),
+    contractUri: text("contract_uri"),
+    description: text("description"),
+    image: text("image"),
+    data: json("data").$type(),
+    updatedAt: integer("updated_at").notNull()
+  }
+);
+
+// src/service.ts
+import { eq, and } from "drizzle-orm";
+import { parseAbi } from "viem";
+
+// src/uri.ts
+var DEFAULT_IPFS_GATEWAY = "https://ipfs.io/ipfs/";
+var DEFAULT_ARWEAVE_GATEWAY = "https://arweave.net/";
+function resolveUri(uri, options) {
+  if (!uri) return "";
+  const ipfs = options?.ipfsGateway || DEFAULT_IPFS_GATEWAY;
+  const ar = options?.arweaveGateway || DEFAULT_ARWEAVE_GATEWAY;
+  if (uri.startsWith("data:")) return uri;
+  if (uri.startsWith("ipfs://")) return ipfs + uri.replace("ipfs://", "");
+  if (uri.startsWith("ar://")) return ar + uri.replace("ar://", "");
+  if (uri.startsWith("Qm") || uri.startsWith("baf")) return ipfs + uri;
+  return uri;
+}
+async function fetchJson(uri, options) {
+  const resolved = resolveUri(uri, options);
+  if (resolved.startsWith("data:application/json;base64,")) {
+    const base64Data = resolved.split(",")[1];
+    return JSON.parse(atob(base64Data));
+  }
+  if (resolved.startsWith("data:application/json")) {
+    const jsonStr = decodeURIComponent(resolved.split(",")[1]);
+    return JSON.parse(jsonStr);
+  }
+  const response = await fetch(resolved);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${resolved}: ${response.status}`);
+  }
+  return response.json();
+}
+
+// src/service.ts
+var DEFAULT_CACHE_TTL = 30 * 24 * 60 * 60 * 1e3;
+var ERC721_ABI = parseAbi([
+  "function tokenURI(uint256 tokenId) view returns (string)",
+  "function supportsInterface(bytes4 interfaceId) view returns (bool)"
+]);
+var ERC1155_ABI = parseAbi([
+  "function uri(uint256) view returns (string)",
+  "function supportsInterface(bytes4 interfaceId) view returns (bool)"
+]);
+var COLLECTION_ABI = parseAbi([
+  "function name() view returns (string)",
+  "function symbol() view returns (string)",
+  "function owner() view returns (address)",
+  "function contractURI() view returns (string)"
+]);
+var ERC721_INTERFACE_ID = "0x80ac58cd";
+var ERC1155_INTERFACE_ID = "0xd9b67a26";
+function createArtifactService(config) {
+  const { client, db } = config;
+  const cacheTtl = config.cacheTtl ?? DEFAULT_CACHE_TTL;
+  const uriOptions = {
+    ipfsGateway: config.ipfsGateway,
+    arweaveGateway: config.arweaveGateway
+  };
+  function isFresh(timestamp) {
+    if (!timestamp) return false;
+    return Date.now() - timestamp * 1e3 < cacheTtl;
+  }
+  async function detectStandard(address) {
+    const isERC721 = await client.readContract({
+      address,
+      abi: ERC721_ABI,
+      functionName: "supportsInterface",
+      args: [ERC721_INTERFACE_ID]
+    }).catch(() => false);
+    if (isERC721) return "erc721";
+    const isERC1155 = await client.readContract({
+      address,
+      abi: ERC1155_ABI,
+      functionName: "supportsInterface",
+      args: [ERC1155_INTERFACE_ID]
+    }).catch(() => false);
+    if (isERC1155) return "erc1155";
+    return "unknown";
+  }
+  async function fetchTokenUri(address, tokenId, standard) {
+    if (standard === "erc1155") {
+      const uri = await client.readContract({
+        address,
+        abi: ERC1155_ABI,
+        functionName: "uri",
+        args: [tokenId]
+      });
+      const tokenIdHex = tokenId.toString(16).padStart(64, "0");
+      return uri.replace("{id}", tokenIdHex);
+    }
+    return await client.readContract({
+      address,
+      abi: ERC721_ABI,
+      functionName: "tokenURI",
+      args: [tokenId]
+    });
+  }
+  async function fetchToken(collection, tokenId) {
+    const result = await db.select().from(artifactToken).where(
+      and(
+        eq(artifactToken.collection, collection.toLowerCase()),
+        eq(artifactToken.tokenId, tokenId)
+      )
+    ).limit(1);
+    return result[0] ?? null;
+  }
+  async function updateToken(collection, tokenId) {
+    const address = collection.toLowerCase();
+    const tokenIdBigInt = BigInt(tokenId);
+    const tokenStandard = await detectStandard(address);
+    const tokenUri = await fetchTokenUri(
+      address,
+      tokenIdBigInt,
+      tokenStandard
+    ).catch(() => null);
+    let name = null;
+    let description = null;
+    let image = null;
+    let animationUrl = null;
+    let data = null;
+    if (tokenUri) {
+      try {
+        const metadata = await fetchJson(tokenUri, uriOptions);
+        data = metadata;
+        name = metadata.name ?? null;
+        description = metadata.description ?? null;
+        image = metadata.image ?? null;
+        animationUrl = metadata.animation_url ?? null;
+      } catch {
+      }
+    }
+    const row = {
+      tokenStandard,
+      tokenUri,
+      name,
+      description,
+      image,
+      animationUrl,
+      data,
+      updatedAt: Math.floor(Date.now() / 1e3)
+    };
+    await db.insert(artifactToken).values({
+      collection: address,
+      tokenId,
+      ...row
+    }).onConflictDoUpdate({
+      target: [artifactToken.collection, artifactToken.tokenId],
+      set: row
+    });
+  }
+  async function fetchCollection(address) {
+    const result = await db.select().from(artifactCollection).where(eq(artifactCollection.collection, address.toLowerCase())).limit(1);
+    return result[0] ?? null;
+  }
+  async function updateCollection(address) {
+    const normalized = address.toLowerCase();
+    const [name, symbol, owner, contractUri, tokenStandard] = await Promise.all([
+      client.readContract({
+        address: normalized,
+        abi: COLLECTION_ABI,
+        functionName: "name"
+      }).catch(() => null),
+      client.readContract({
+        address: normalized,
+        abi: COLLECTION_ABI,
+        functionName: "symbol"
+      }).catch(() => null),
+      client.readContract({
+        address: normalized,
+        abi: COLLECTION_ABI,
+        functionName: "owner"
+      }).catch(() => null),
+      client.readContract({
+        address: normalized,
+        abi: COLLECTION_ABI,
+        functionName: "contractURI"
+      }).catch(() => null),
+      detectStandard(normalized)
+    ]);
+    let description = null;
+    let image = null;
+    let data = null;
+    if (contractUri) {
+      try {
+        const metadata = await fetchJson(contractUri, uriOptions);
+        data = metadata;
+        description = metadata.description ?? null;
+        image = metadata.image ?? null;
+      } catch {
+      }
+    }
+    const row = {
+      tokenStandard,
+      name: name ?? data?.name ?? null,
+      symbol: symbol ?? data?.symbol ?? null,
+      owner: owner?.toLowerCase() ?? null,
+      contractUri,
+      description: description ?? null,
+      image: image ?? null,
+      data,
+      updatedAt: Math.floor(Date.now() / 1e3)
+    };
+    await db.insert(artifactCollection).values({
+      collection: normalized,
+      ...row
+    }).onConflictDoUpdate({
+      target: artifactCollection.collection,
+      set: row
+    });
+  }
+  return {
+    fetchToken,
+    updateToken,
+    fetchCollection,
+    updateCollection,
+    isFresh
+  };
+}
+
+// src/routes.ts
+import { Hono } from "hono";
+function createArtifactRoutes(config) {
+  const {
+    fetchToken,
+    updateToken,
+    fetchCollection,
+    updateCollection,
+    isFresh
+  } = createArtifactService(config);
+  const app = new Hono();
+  app.get("/token/:collection/:tokenId", async (c) => {
+    const collection = c.req.param("collection");
+    const tokenId = c.req.param("tokenId");
+    const cached = await fetchToken(collection, tokenId);
+    if (cached && isFresh(cached.updatedAt)) {
+      return c.json(cached);
+    }
+    try {
+      await updateToken(collection, tokenId);
+      return c.json(await fetchToken(collection, tokenId));
+    } catch {
+      if (cached) return c.json(cached);
+      return c.json({ error: "Failed to fetch token metadata" }, 500);
+    }
+  });
+  app.post("/token/:collection/:tokenId", async (c) => {
+    const collection = c.req.param("collection");
+    const tokenId = c.req.param("tokenId");
+    try {
+      await updateToken(collection, tokenId);
+      return c.json(await fetchToken(collection, tokenId));
+    } catch {
+      const cached = await fetchToken(collection, tokenId);
+      if (cached) return c.json(cached);
+      return c.json({ error: "Failed to fetch token metadata" }, 500);
+    }
+  });
+  app.get("/collection/:address", async (c) => {
+    const address = c.req.param("address");
+    const cached = await fetchCollection(address);
+    if (cached && isFresh(cached.updatedAt)) {
+      return c.json(cached);
+    }
+    try {
+      await updateCollection(address);
+      return c.json(await fetchCollection(address));
+    } catch {
+      if (cached) return c.json(cached);
+      return c.json({ error: "Failed to fetch collection metadata" }, 500);
+    }
+  });
+  app.post("/collection/:address", async (c) => {
+    const address = c.req.param("address");
+    try {
+      await updateCollection(address);
+      return c.json(await fetchCollection(address));
+    } catch {
+      const cached = await fetchCollection(address);
+      if (cached) return c.json(cached);
+      return c.json({ error: "Failed to fetch collection metadata" }, 500);
+    }
+  });
+  return app;
+}
+
+// src/db.ts
+var INIT_SQL = `
+  CREATE SCHEMA IF NOT EXISTS offchain;
+  CREATE TABLE IF NOT EXISTS offchain.artifact_token (
+    collection TEXT NOT NULL,
+    token_id TEXT NOT NULL,
+    token_standard TEXT NOT NULL,
+    token_uri TEXT,
+    name TEXT,
+    description TEXT,
+    image TEXT,
+    animation_url TEXT,
+    data JSON,
+    updated_at INTEGER NOT NULL,
+    PRIMARY KEY (collection, token_id)
+  );
+  CREATE TABLE IF NOT EXISTS offchain.artifact_collection (
+    collection TEXT PRIMARY KEY,
+    token_standard TEXT NOT NULL,
+    name TEXT,
+    symbol TEXT,
+    owner TEXT,
+    contract_uri TEXT,
+    description TEXT,
+    image TEXT,
+    data JSON,
+    updated_at INTEGER NOT NULL
+  );
+`;
+async function createOffchainDb(options) {
+  const databaseUrl = options?.databaseUrl ?? process.env.DATABASE_PRIVATE_URL ?? process.env.DATABASE_URL;
+  if (databaseUrl) {
+    const { default: pg } = await import("pg");
+    const { drizzle: drizzle2 } = await import("drizzle-orm/node-postgres");
+    const pool = new pg.Pool({ connectionString: databaseUrl });
+    await pool.query(INIT_SQL);
+    return { db: drizzle2(pool) };
+  }
+  const dataDir = options?.dataDir ?? ".ponder/artifacts";
+  const { PGlite } = await import("@electric-sql/pglite");
+  const { drizzle } = await import("drizzle-orm/pglite");
+  const client = new PGlite(dataDir);
+  await client.exec(INIT_SQL);
+  return { db: drizzle(client) };
+}
+export {
+  artifactCollection,
+  artifactToken,
+  createArtifactRoutes,
+  createArtifactService,
+  createOffchainDb,
+  fetchJson,
+  offchainSchema,
+  resolveUri
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@1001-digital/ponder-artifacts",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "drizzle-orm": ">=0.38.0",
+    "hono": ">=4.0.0",
+    "viem": ">=2.0.0",
+    "pg": ">=8.0.0",
+    "@electric-sql/pglite": ">=0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    },
+    "@electric-sql/pglite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.2.13",
+    "@types/pg": "^8.11.0",
+    "drizzle-orm": "^0.38.0",
+    "hono": "^4.5.0",
+    "pg": "^8.13.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.2.0",
+    "viem": "^2.21.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}