tapimo 0.0.2 → 0.2.0

package/src/db/tables/sponsoredTransactions.test.ts

@@ -0,0 +1,218 @@
+import { nanoid } from 'nanoid'
+
+import { postgresUrl } from '../../../test/containers.js'
+import * as Db from '../Db.js'
+import * as SponsoredTransactions from './sponsoredTransactions.js'
+
+const create = () => Db.postgres({ connectionString: postgresUrl, schema: `t_${nanoid()}` })
+
+/** Baseline insert input; tests override per case. */
+const input = {
+  apiKeyId: 'key_1',
+  billable: true,
+  chainId: 42431,
+  environment: 'production',
+  orgId: 'org_1',
+  projectId: 'prj_1',
+  signPayload: `0x${'bb'.repeat(32)}`,
+  transaction: `0x76${'cc'.repeat(16)}`,
+  transactionHash: `0x${'aa'.repeat(32)}`,
+} satisfies SponsoredTransactions.upsert.Input
+
+/** Redacts nondeterministic row fields (generated nanoid ids, timestamps). */
+function redact(record: SponsoredTransactions.Record) {
+  return {
+    ...record,
+    createdAt: '<timestamp>',
+    finalizedAt: record.finalizedAt === null ? null : '<timestamp>',
+    id: /^stx_[\w-]{21}$/.test(record.id) ? 'stx_<id>' : record.id,
+  }
+}
+
+describe('upsert', () => {
+  test('behavior: records a pending sponsorship with a generated id', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await SponsoredTransactions.upsert(db, input)
+    expect(record.id).toMatch(/^stx_/)
+    expect(redact(record)).toMatchInlineSnapshot(`
+      {
+        "apiKeyId": "key_1",
+        "billable": true,
+        "chainId": 42431,
+        "createdAt": "<timestamp>",
+        "environment": "production",
+        "feeAmount": null,
+        "feeToken": null,
+        "finalizedAt": null,
+        "id": "stx_<id>",
+        "orgId": "org_1",
+        "projectId": "prj_1",
+        "signPayload": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        "status": "pending",
+        "transaction": "0x76cccccccccccccccccccccccccccccccc",
+        "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      }
+    `)
+    expect(await SponsoredTransactions.get(db, record.id)).toStrictEqual(record)
+    await db.close()
+  })
+
+  test('behavior: preserves an explicit fee token', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await SponsoredTransactions.upsert(db, { ...input, feeToken: `0x${'fe'.repeat(20)}` }) // prettier-ignore
+    expect(record.feeToken).toMatchInlineSnapshot(`"0xfefefefefefefefefefefefefefefefefefefefe"`)
+    await db.close()
+  })
+
+  test('behavior: records fill intents without a transaction hash', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...intent } = input
+    const record = await SponsoredTransactions.upsert(db, intent)
+    expect(record.transactionHash).toBeNull()
+    expect(record.status).toMatchInlineSnapshot(`"pending"`)
+    await db.close()
+  })
+
+  test('behavior: a raw submission upgrades a fill intent in place', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...intent } = input
+    const first = await SponsoredTransactions.upsert(db, intent)
+    const second = await SponsoredTransactions.upsert(db, input)
+
+    // Same commitment, one row: the raw record fills the intent's hash.
+    expect(second.id).toBe(first.id)
+    expect(second.transactionHash).toMatchInlineSnapshot(
+      `"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"`,
+    )
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(1)
+    await db.close()
+  })
+
+  test('behavior: a raw submission reopens a failed fill intent', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...intent } = input
+    const first = await SponsoredTransactions.upsert(db, intent)
+    await SponsoredTransactions.fail(db, first.id, '2026-01-01T00:00:00.000Z')
+
+    const second = await SponsoredTransactions.upsert(db, input)
+
+    expect(second.id).toBe(first.id)
+    expect(second.status).toMatchInlineSnapshot(`"pending"`)
+    expect(second.finalizedAt).toBeNull()
+    expect(second.transactionHash).toMatchInlineSnapshot(
+      `"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"`,
+    )
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(1)
+    await db.close()
+  })
+
+  test('behavior: a duplicate intent never clears a known hash', async () => {
+    const db = create()
+    await db.migrate()
+    const first = await SponsoredTransactions.upsert(db, input)
+    const { transactionHash: _, ...intent } = input
+    const second = await SponsoredTransactions.upsert(db, intent)
+
+    expect(second.id).toBe(first.id)
+    expect(second.transactionHash).toMatchInlineSnapshot(
+      `"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"`,
+    )
+    await db.close()
+  })
+})
+
+describe('listPending', () => {
+  test('behavior: returns only pending rows, capped by limit', async () => {
+    const db = create()
+    await db.migrate()
+    await SponsoredTransactions.upsert(db, { ...input, signPayload: `0x${'b1'.repeat(32)}`, transactionHash: `0x${'a1'.repeat(32)}` }) // prettier-ignore
+    const second = await SponsoredTransactions.upsert(db, { ...input, signPayload: `0x${'b2'.repeat(32)}`, transactionHash: `0x${'a2'.repeat(32)}` }) // prettier-ignore
+    await SponsoredTransactions.upsert(db, { ...input, signPayload: `0x${'b3'.repeat(32)}`, transactionHash: `0x${'a3'.repeat(32)}` }) // prettier-ignore
+    await SponsoredTransactions.finalize(db, second.id, {
+      feeAmount: '100',
+      finalizedAt: new Date().toISOString(),
+    })
+
+    const pending = await SponsoredTransactions.listPending(db)
+    // Inserts can share a millisecond, so assert membership, not order.
+    expect(pending.map((row) => row.transactionHash).sort()).toMatchInlineSnapshot(`
+      [
+        "0xa1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
+        "0xa3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3a3",
+      ]
+    `)
+    expect(await SponsoredTransactions.listPending(db, { limit: 1 })).toHaveLength(1)
+    await db.close()
+  })
+})
+
+describe('assignTransactionHash', () => {
+  test('behavior: reopens a failed intent when reconciliation finds its hash', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...intent } = input
+    const record = await SponsoredTransactions.upsert(db, intent)
+    await SponsoredTransactions.fail(db, record.id, '2026-01-01T00:00:00.000Z')
+
+    await SponsoredTransactions.assignTransactionHash(db, record.id, input.transactionHash)
+
+    const assigned = await SponsoredTransactions.get(db, record.id)
+    expect(assigned?.status).toMatchInlineSnapshot(`"pending"`)
+    expect(assigned?.finalizedAt).toBeNull()
+    expect(assigned?.transactionHash).toMatchInlineSnapshot(
+      `"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"`,
+    )
+    await db.close()
+  })
+})
+
+describe('finalize', () => {
+  test('behavior: transitions pending → finalized with the actual fee', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await SponsoredTransactions.upsert(db, input)
+    await SponsoredTransactions.finalize(db, record.id, {
+      feeAmount: '21000',
+      finalizedAt: '2026-01-01T00:00:00.000Z',
+    })
+    const finalized = await SponsoredTransactions.get(db, record.id)
+    expect(finalized?.status).toMatchInlineSnapshot(`"finalized"`)
+    expect(finalized?.feeAmount).toMatchInlineSnapshot(`"21000"`)
+    expect(finalized?.finalizedAt).toMatchInlineSnapshot(`"2026-01-01T00:00:00.000Z"`)
+    await db.close()
+  })
+
+  test('behavior: no-op on rows that are no longer pending', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await SponsoredTransactions.upsert(db, input)
+    await SponsoredTransactions.fail(db, record.id, '2026-01-01T00:00:00.000Z')
+    await SponsoredTransactions.finalize(db, record.id, {
+      feeAmount: '21000',
+      finalizedAt: '2026-01-02T00:00:00.000Z',
+    })
+    const row = await SponsoredTransactions.get(db, record.id)
+    expect(row?.status).toMatchInlineSnapshot(`"failed"`)
+    expect(row?.feeAmount).toBeNull()
+    await db.close()
+  })
+})
+
+describe('fail', () => {
+  test('behavior: transitions pending → failed without a fee', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await SponsoredTransactions.upsert(db, input)
+    await SponsoredTransactions.fail(db, record.id, '2026-01-01T00:00:00.000Z')
+    const failed = await SponsoredTransactions.get(db, record.id)
+    expect(failed?.status).toMatchInlineSnapshot(`"failed"`)
+    expect(failed?.feeAmount).toBeNull()
+    expect(failed?.finalizedAt).toMatchInlineSnapshot(`"2026-01-01T00:00:00.000Z"`)
+    await db.close()
+  })
+})

package/src/db/tables/sponsoredTransactions.ts

@@ -0,0 +1,236 @@
+import type { ExpressionBuilder, Selectable } from 'kysely'
+import { sql } from 'kysely'
+import { nanoid } from 'nanoid'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `sponsored_transactions` table, derived from `Schema.SponsoredTransaction`. */
+export type Table = db_Schema.SponsoredTransaction
+
+/** A stored sponsored-transaction row. */
+export type Record = Selectable<Table>
+
+/**
+ * Records one sponsorship commitment as `pending`, keyed by its fee-payer
+ * sign payload. Written after fee-payer signing and before any broadcast, so
+ * no sponsored transaction goes unrecorded; a later recording site for the
+ * same envelope (raw submission after a fill intent) upgrades the row with
+ * its transaction hash, reopening failed rows for finalization.
+ *
+ * @param db - The database.
+ * @param input - Attribution and envelope facts captured at signing time.
+ * @returns The stored record.
+ */
+export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
+  const record: Record = {
+    apiKeyId: input.apiKeyId,
+    billable: input.billable,
+    chainId: input.chainId,
+    createdAt: new Date().toISOString(),
+    environment: input.environment,
+    feeAmount: null,
+    feeToken: input.feeToken ?? null,
+    finalizedAt: null,
+    id: `stx_${nanoid()}`,
+    orgId: input.orgId,
+    projectId: input.projectId,
+    signPayload: input.signPayload,
+    status: 'pending',
+    transaction: input.transaction,
+    transactionHash: input.transactionHash ?? null,
+  }
+  return await db.kysely
+    .insertInto('sponsored_transactions')
+    .values(record)
+    .onConflict((oc) =>
+      oc.column('signPayload').doUpdateSet((eb) => ({
+        // A raw submission fills the intent's hash; a duplicate intent never
+        // clears an already-known hash.
+        transactionHash: eb.fn.coalesce(
+          eb.ref('excluded.transactionHash'),
+          eb.ref('sponsored_transactions.transactionHash'),
+        ),
+        createdAt: sql`CASE WHEN ${eb.ref('sponsored_transactions.status')} = 'failed' THEN ${eb.ref('excluded.createdAt')} ELSE ${eb.ref('sponsored_transactions.createdAt')} END`,
+        finalizedAt: sql`CASE WHEN ${eb.ref('sponsored_transactions.status')} = 'failed' THEN NULL ELSE ${eb.ref('sponsored_transactions.finalizedAt')} END`,
+        status: sql`CASE WHEN ${eb.ref('sponsored_transactions.status')} = 'failed' THEN 'pending' ELSE ${eb.ref('sponsored_transactions.status')} END`,
+      })),
+    )
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+export declare namespace upsert {
+  /** Attribution and envelope facts recorded at sponsorship time. */
+  type Input = {
+    /** API key id (`key_…`) that requested sponsorship. */
+    apiKeyId: string
+    /** Whether the sponsorship accrues billable spend; false for sandbox. */
+    billable: boolean
+    /** Chain the sponsored transaction targets. */
+    chainId: number
+    /** Key environment the sponsorship was requested under. */
+    environment: Table['environment']
+    /** Fee token the sponsorship resolved, when known. */
+    feeToken?: string | undefined
+    /** Organization id (`org_…`) the spend attributes to. */
+    orgId: string
+    /** Project id (`prj_…`) the spend attributes to. */
+    projectId: string
+    /** Fee-payer sign payload — a stable identity for the sponsored envelope. */
+    signPayload: string
+    /** Serialized sponsored transaction, kept for observability beyond log retention. */
+    transaction: string
+    /** Transaction hash; omit for fill intents, whose senders have not signed yet. */
+    transactionHash?: string | undefined
+  }
+}
+
+/**
+ * Reads one sponsorship row by id.
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @returns The record, or `undefined` when absent.
+ */
+export function get(db: Db.Db, id: string): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('sponsored_transactions')
+    .selectAll()
+    .where('id', '=', id)
+    .executeTakeFirst()
+}
+
+/**
+ * Lists pending sponsorships, oldest first, for the finalization job.
+ *
+ * @param db - The database.
+ * @param options - Paging options.
+ * @returns The pending records.
+ */
+export function listPending(db: Db.Db, options: listPending.Options = {}): Promise<Record[]> {
+  let query = db.kysely
+    .selectFrom('sponsored_transactions')
+    .selectAll()
+    .where('status', '=', 'pending')
+    // `id` breaks same-millisecond `createdAt` ties for a deterministic scan.
+    .orderBy('createdAt', 'asc')
+    .orderBy('id', 'asc')
+  if (options.limit !== undefined) query = query.limit(options.limit)
+  return query.execute()
+}
+
+export declare namespace listPending {
+  /** Options for {@link listPending}. */
+  type Options = {
+    /** Maximum rows to return. */
+    limit?: number | undefined
+  }
+}
+
+/**
+ * Lists hash-less fill intents, oldest first, for the reconciliation pass.
+ * Failed intents are included only when the caller supplies a recovery floor.
+ *
+ * @param db - The database.
+ * @param options - Paging options.
+ * @returns The pending intents.
+ */
+export function listIntents(db: Db.Db, options: listIntents.Options = {}): Promise<Record[]> {
+  let query = db.kysely
+    .selectFrom('sponsored_transactions')
+    .selectAll()
+    .where(intentStatus(options.failedSince))
+    .where('transactionHash', 'is', null)
+    // `pending` sorts after `failed`; descending keeps active intents first.
+    .orderBy('status', 'desc')
+    .orderBy('createdAt', 'asc')
+    .orderBy('id', 'asc')
+  if (options.limit !== undefined) query = query.limit(options.limit)
+  return query.execute()
+}
+
+export declare namespace listIntents {
+  /** Options for {@link listIntents}. */
+  type Options = listPending.Options & {
+    /** Include failed intents whose terminal timestamp is at or after this ISO timestamp. */
+    failedSince?: string | undefined
+  }
+}
+
+/**
+ * Fills a reconciled intent's transaction hash and reopens failed intents.
+ * A no-op once another pass already assigned the hash.
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @param transactionHash - The matched on-chain transaction hash.
+ */
+export async function assignTransactionHash(
+  db: Db.Db,
+  id: string,
+  transactionHash: string,
+): Promise<void> {
+  await db.kysely
+    .updateTable('sponsored_transactions')
+    .set({ finalizedAt: null, status: 'pending', transactionHash })
+    .where('id', '=', id)
+    .where('status', 'in', ['failed', 'pending'])
+    .where('transactionHash', 'is', null)
+    .execute()
+}
+
+/**
+ * Transitions a pending sponsorship to `finalized` with the receipt's actual
+ * fee. A no-op when the row is no longer pending (idempotent re-runs).
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @param input - The finalized fee facts.
+ */
+export async function finalize(db: Db.Db, id: string, input: finalize.Input): Promise<void> {
+  await db.kysely
+    .updateTable('sponsored_transactions')
+    .set({ feeAmount: input.feeAmount, finalizedAt: input.finalizedAt, status: 'finalized' })
+    .where('id', '=', id)
+    .where('status', '=', 'pending')
+    .execute()
+}
+
+export declare namespace finalize {
+  /** Fee facts resolved from the transaction receipt. */
+  type Input = {
+    /** Actual fee paid in fee-token base units. */
+    feeAmount: string
+    /** When the sponsorship finalized (ISO 8601). */
+    finalizedAt: string
+  }
+}
+
+/**
+ * Transitions a pending sponsorship to `failed` (never landed within the
+ * pending TTL). A no-op when the row is no longer pending.
+ *
+ * @param db - The database.
+ * @param id - The sponsored-transaction id (`stx_…`).
+ * @param finalizedAt - When the sponsorship was marked failed (ISO 8601).
+ */
+export async function fail(db: Db.Db, id: string, finalizedAt: string): Promise<void> {
+  await db.kysely
+    .updateTable('sponsored_transactions')
+    .set({ finalizedAt, status: 'failed' })
+    .where('id', '=', id)
+    .where('status', '=', 'pending')
+    .execute()
+}
+
+/** Intent status predicate; failed rows are recovery candidates only briefly. */
+function intentStatus(failedSince: string | undefined) {
+  return (eb: ExpressionBuilder<Db.Database, 'sponsored_transactions'>) => {
+    if (failedSince === undefined) return eb('status', '=', 'pending')
+    return eb.or([
+      eb('status', '=', 'pending'),
+      eb.and([eb('status', '=', 'failed'), eb('finalizedAt', '>=', failedSince)]),
+    ])
+  }
+}

package/src/db/tables/users.ts

@@ -0,0 +1,85 @@
+import type { Selectable } from 'kysely'
+import { nanoid } from 'nanoid'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `users` table, derived from `Schema.User`. */
+export type Table = db_Schema.User
+
+/** A stored user row. */
+export type Record = Selectable<Table>
+
+/**
+ * Reads a user by id (`usr_…`).
+ *
+ * @param db - The database.
+ * @param id - The user id.
+ * @returns The record, or `undefined` when absent.
+ */
+export function get(db: Db.Db, id: string): Promise<Record | undefined> {
+  return db.kysely.selectFrom('users').selectAll().where('id', '=', id).executeTakeFirst()
+}
+
+/**
+ * Reads a user by wallet address (compared lowercase).
+ *
+ * @param db - The database.
+ * @param address - The wallet address.
+ * @returns The record, or `undefined` when absent.
+ */
+export function getByAddress(db: Db.Db, address: string): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('users')
+    .selectAll()
+    .where('address', '=', address.toLowerCase())
+    .executeTakeFirst()
+}
+
+/**
+ * Inserts a user for `address` when absent and returns the stored record.
+ * Existing users are returned unchanged, so repeated sign-ins are idempotent.
+ *
+ * @param db - The database.
+ * @param input - The user to ensure.
+ * @returns The stored record.
+ */
+export async function upsertByAddress(db: Db.Db, input: upsertByAddress.Input): Promise<Record> {
+  const address = input.address.toLowerCase()
+  const now = new Date().toISOString()
+  const inserted = await db.kysely
+    .insertInto('users')
+    .values({ address, createdAt: now, email: null, id: `usr_${nanoid()}`, updatedAt: now })
+    .onConflict((oc) => oc.column('address').doNothing())
+    .returningAll()
+    .executeTakeFirst()
+  if (inserted) return inserted
+  return db.kysely
+    .selectFrom('users')
+    .selectAll()
+    .where('address', '=', address)
+    .executeTakeFirstOrThrow()
+}
+
+export declare namespace upsertByAddress {
+  /** Fields accepted when ensuring a user. */
+  type Input = {
+    /** Wallet address that signed in (stored lowercase). */
+    address: string
+  }
+}
+
+/**
+ * Sets a user's verified email, bumping `updatedAt`.
+ *
+ * @param db - The database.
+ * @param id - The user id (`usr_…`).
+ * @param email - The verified email.
+ */
+export async function setEmail(db: Db.Db, id: string, email: string): Promise<void> {
+  await db.kysely
+    .updateTable('users')
+    .set({ email, updatedAt: new Date().toISOString() })
+    .where('id', '=', id)
+    .execute()
+}

package/src/db/tables/verifiedTokens.ts

@@ -0,0 +1,111 @@
+import type { Selectable } from 'kysely'
+import type { Hex } from 'ox'
+
+import type * as VerifiedTokens from '../../internal/VerifiedTokens.js'
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `verified_tokens` table, derived from `Schema.VerifiedToken`. */
+export type Table = db_Schema.VerifiedToken
+
+/** Columns of the `verified_token_lists` table, derived from `Schema.VerifiedTokenList`. */
+export type ListTable = db_Schema.VerifiedTokenList
+
+/** A stored verified-token row. */
+export type Row = Selectable<Table>
+
+/** A chain's list-level metadata. */
+export type Meta = Selectable<ListTable>
+
+/**
+ * Reads a chain's list metadata — the "head" the soft-refresh cache compares
+ * versions against.
+ *
+ * @param db - The database.
+ * @param chainId - The chain id.
+ * @returns The metadata, or `undefined` when the chain has no list yet.
+ */
+export function head(db: Db.Db, chainId: number): Promise<Meta | undefined> {
+  return db.kysely
+    .selectFrom('verified_token_lists')
+    .selectAll()
+    .where('chainId', '=', chainId)
+    .executeTakeFirst()
+}
+
+/**
+ * Reads a chain's tokens in canonical list order.
+ *
+ * @param db - The database.
+ * @param chainId - The chain id.
+ * @returns The rows.
+ */
+export function list(db: Db.Db, chainId: number): Promise<Row[]> {
+  return db.kysely
+    .selectFrom('verified_tokens')
+    .selectAll()
+    .where('chainId', '=', chainId)
+    .orderBy('position')
+    .execute()
+}
+
+/**
+ * Publishes a chain's whole list: replaces its token rows (positions rewritten
+ * wholesale) and bumps the list metadata. Callers run this inside the
+ * per-chain publish lock/transaction, so the rewrite is atomic.
+ *
+ * @param db - The database (a transaction-scoped handle).
+ * @param chainId - The chain id.
+ * @param input - The validated list and its new version metadata.
+ */
+export async function publish(db: Db.Db, chainId: number, input: publish.Input): Promise<void> {
+  await db.kysely.deleteFrom('verified_tokens').where('chainId', '=', chainId).execute()
+  if (input.tokens.length > 0)
+    await db.kysely
+      .insertInto('verified_tokens')
+      .values(
+        input.tokens.map((token, position) => ({
+          address: token.address,
+          chainId,
+          currency: token.currency,
+          decimals: token.decimals,
+          logoUri: token.logoUri ?? null,
+          name: token.name,
+          position,
+          symbol: token.symbol,
+        })),
+      )
+      .execute()
+  await db.kysely
+    .insertInto('verified_token_lists')
+    .values({ chainId, updatedAt: input.updatedAt, version: input.version })
+    .onConflict((oc) =>
+      oc.column('chainId').doUpdateSet({ updatedAt: input.updatedAt, version: input.version }),
+    )
+    .execute()
+}
+
+export declare namespace publish {
+  /** A validated list to publish. */
+  type Input = {
+    /** Tokens in canonical order (addresses lowercased by the domain layer). */
+    tokens: readonly VerifiedTokens.Token[]
+    /** ISO timestamp of the publish. */
+    updatedAt: string
+    /** New opaque list version. */
+    version: string
+  }
+}
+
+/** Maps a stored row to the domain token (null `logoUri` → absent field). */
+export function toToken(row: Row): VerifiedTokens.Token {
+  return {
+    address: row.address as Hex.Hex,
+    currency: row.currency,
+    decimals: row.decimals,
+    id: row.address as Hex.Hex,
+    name: row.name,
+    symbol: row.symbol,
+    ...(row.logoUri === null ? {} : { logoUri: row.logoUri }),
+  }
+}