@1001-digital/ponder-artifacts

Server-side artifact metadata caching for Ponder indexers. Resolves NFT token and collection metadata (ERC721 + ERC1155) on demand, caches it with a 30-day TTL, and serves it via ready-to-mount Hono API routes.

Works with both PostgreSQL and PGlite (Ponder's default embedded database) — no Postgres required for development.

Why offchain?

Ponder rebuilds its onchain tables from scratch on every reindex. Token metadata (names, images, descriptions) doesn't change often, but fetching it from IPFS/Arweave on every page load is slow and redundant across clients.

This package stores artifact metadata in a separate offchain table that persists across reindexes. Metadata is resolved lazily on first request and cached with a 30-day TTL. Many concurrent requests for the same token result in a single RPC + IPFS lookup — not one per client.

Install

pnpm add @1001-digital/ponder-artifacts

Peer dependencies (your ponder app should already have these):

pnpm add drizzle-orm hono viem

Quick start

1. Mount the routes

// src/api/index.ts
import { db, publicClients } from "ponder:api";
import schema from "ponder:schema";
import { Hono } from "hono";
import { client, graphql } from "ponder";
import {
  createArtifactRoutes,
  createOffchainDb,
} from "@1001-digital/ponder-artifacts";

const { db: artifactDb } = await createOffchainDb();

const app = new Hono();

app.route(
  "/artifacts",
  createArtifactRoutes({
    client: publicClients["ethereum"],
    db: artifactDb,
  }),
);

app.use("/sql/*", client({ db, schema }));
app.use("/", graphql({ db, schema }));

export default app;

That's it. You now have:

| Method | Path | Behavior | |--------|------|----------| | GET | /artifacts/:address | Returns cached collection info, refreshes if stale (>30 days) | | POST | /artifacts/:address | Force refresh collection from chain | | GET | /artifacts/:collection/:tokenId | Returns cached token metadata, refreshes if stale | | POST | /artifacts/:collection/:tokenId | Force refresh token from chain |

On fetch failure, stale cache is returned if available; 500 otherwise.

How createOffchainDb works

createOffchainDb() auto-detects your database setup:

• With DATABASE_URL (or DATABASE_PRIVATE_URL): connects to PostgreSQL, creates the offchain schema and tables if they don't exist.
• Without DATABASE_URL: uses PGlite (Postgres-in-WASM), stores data in .ponder/artifacts/ by default.

// Auto-detect (recommended)
const { db } = await createOffchainDb();

// Explicit Postgres
const { db } = await createOffchainDb({ databaseUrl: "postgresql://..." });

// Explicit PGlite with custom directory
const { db } = await createOffchainDb({ dataDir: ".data/artifacts" });

Using the service directly

For metadata resolution outside of API routes (e.g. in scripts), use createArtifactService:

import {
  createArtifactService,
  createOffchainDb,
} from "@1001-digital/ponder-artifacts";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const client = createPublicClient({ chain: mainnet, transport: http() });
const { db } = await createOffchainDb();

const artifacts = createArtifactService({ client, db });

// Fetch cached token (returns null if not yet cached)
const token = await artifacts.fetchToken("0xbc4c...", "42");

// Update token metadata from chain + IPFS
await artifacts.updateToken("0xbc4c...", "42");

// Fetch cached collection
const collection = await artifacts.fetchCollection("0xbc4c...");

// Update collection metadata from chain
await artifacts.updateCollection("0xbc4c...");

// Check if a cached timestamp is still fresh
artifacts.isFresh(token?.updatedAt ?? null);

Bring your own database

If you manage your own offchain database, skip createOffchainDb and pass your drizzle instance directly:

import { createArtifactRoutes } from "@1001-digital/ponder-artifacts";
import { getOffchainDb } from "./services/database";

app.route(
  "/artifacts",
  createArtifactRoutes({
    client: publicClients["ethereum"],
    db: getOffchainDb(),
  }),
);

The package exports the schema for your drizzle config:

// offchain.schema.ts
export { artifactToken, artifactCollection } from "@1001-digital/ponder-artifacts";

Token standard detection

The service detects ERC721 vs ERC1155 via ERC165 supportsInterface:

• ERC721 (0x80ac58cd): calls tokenURI(tokenId)
• ERC1155 (0xd9b67a26): calls uri(tokenId), replaces {id} with zero-padded hex token ID
• Unknown: falls back to ERC721 tokenURI

URI resolution

Token and collection URIs are resolved inline (no external dependency):

• ipfs://... — resolved via IPFS gateway (default: https://ipfs.io/ipfs/)
• ar://... — resolved via Arweave gateway (default: https://arweave.net/)
• Qm... / baf... — treated as raw IPFS hashes
• data:application/json;base64,... — decoded inline
• data:application/json,... — URL-decoded inline
• Everything else — fetched as-is

Custom gateways can be passed via config:

createArtifactRoutes({
  client: publicClients["ethereum"],
  db: artifactDb,
  ipfsGateway: "https://my-gateway.io/ipfs/",
  arweaveGateway: "https://my-arweave.io/",
});

Configuration

| Option | Type | Description | |--------|------|-------------| | client | viem PublicClient | Client for on-chain reads (ERC165, tokenURI, contractURI, etc.) | | db | drizzle instance | For reading and writing metadata. Use createOffchainDb() or bring your own. | | cacheTtl | number (ms) | Cache freshness window. Defaults to 30 days. | | ipfsGateway | string | IPFS gateway URL. Defaults to https://ipfs.io/ipfs/. | | arweaveGateway | string | Arweave gateway URL. Defaults to https://arweave.net/. |

Data structures

Token

{
  collection: string;      // Lowercase hex address
  tokenId: string;         // String representation of bigint
  tokenStandard: string;   // "erc721" | "erc1155" | "unknown"
  tokenUri: string | null; // Raw URI from contract
  name: string | null;
  description: string | null;
  image: string | null;
  animationUrl: string | null;
  data: object | null;     // Full raw metadata blob
  updatedAt: number;       // Unix timestamp (seconds)
}

Collection

{
  collection: string;       // Lowercase hex address
  tokenStandard: string;    // "erc721" | "erc1155" | "unknown"
  name: string | null;      // From on-chain name() or contractURI
  symbol: string | null;    // From on-chain symbol() or contractURI
  owner: string | null;     // From on-chain owner()
  contractUri: string | null;
  description: string | null;
  image: string | null;
  data: object | null;      // Full raw contractURI metadata blob
  updatedAt: number;        // Unix timestamp (seconds)
}