tapimo 0.0.2 → 0.2.0

package/src/internal/VerifiedTokens.ts

@@ -1,16 +1,18 @@
 import type { Context } from 'hono'
+import { sql } from 'kysely'
 import { Hex } from 'ox'
 import * as z from 'zod/mini'
 
 import type * as App from '../App.js'
+import * as Db from '../db/Db.js'
+import * as core_VerifiedTokens from '../db/tables/verifiedTokens.js'
 import * as Schema from './Schema.js'
-import * as Store from './Store.js'
 import * as Timing from './Timing.js'
 
 /** Chain id covered by the curated verified-token lists. */
 export type ChainId = z.output<typeof Schema.ChainId>
 
-/** Schema for a chain's verified token list (the value stored in KV). */
+/** Schema for a chain's verified token list (validated at the write boundary). */
 export const Data = z
   .array(
     z
@@ -68,7 +70,8 @@ export function compile(options: compile.Options): Snapshot {
   const { chainId, tokens, updatedAt, version } = options
   // Backfill the derived `id` (lowercased address) without re-parsing through
   // `Data`/`Schema.Address`, which would lowercase the stored `address` and
-  // drop its curated checksum casing. Callers (readBlob/normalize) own validation.
+  // drop its curated checksum casing. Validation happens at the write boundary
+  // (`normalize`); reads trust the typed columns.
   const list: SnapshotToken[] = tokens.map((token) => ({
     ...token,
     id: token.id ?? (token.address.toLowerCase() as Hex.Hex),
@@ -112,90 +115,34 @@ export declare namespace compile {
   }
 }
 
-// Storage layout: one head pointer + one whole-chain blob per version, so
-// reads are a single `get` by known key (no `list()` scans) and a publish is an
-// atomic flip of `head` to a new, already-written `snapshot:{version}`.
-const keyPrefix = 'verified-token:v1'
+// Storage layout: one `verified_tokens` row per curated token (ordered by
+// `position`) plus a per-chain `verified_token_lists` row carrying the opaque
+// list `version` the soft-refresh cache and `If-Match` preconditions compare.
 
-// Storage schema version stamped on every head/blob, so a future on-disk format
-// change can be detected and migrated.
-const storeSchema = 1
+/** A chain's list-level metadata (the "head" the cache compares against). */
+export type Head = core_VerifiedTokens.Meta
 
-/** Store key for a chain's head pointer (current version + metadata). */
-function headKey(chainId: ChainId): string {
-  return `${keyPrefix}:${chainId}:head`
-}
-
-/** Store key for a chain's immutable snapshot blob at a given version. */
-function snapshotKey(chainId: ChainId, version: string): string {
-  return `${keyPrefix}:${chainId}:snapshot:${version}`
-}
-
-// Head pointer: tiny, read once per soft-TTL window to detect version changes
-// without fetching the (much larger) token blob.
-const Head = z
-  .object({
-    chainId: z.number().check(z.int(), z.describe('Chain the head belongs to.')),
-    count: z.number().check(z.int(), z.nonnegative(), z.describe('Token count at this version.')),
-    schema: z.number().check(z.int(), z.describe('Storage schema version.')),
-    updatedAt: z.string().check(z.describe('ISO timestamp of the last publish.')),
-    version: z.string().check(z.describe('Current snapshot version.')),
-  })
-  .check(z.describe('Verified-token head pointer stored under the head key.'))
-
-// Immutable per-version blob holding the validated token list.
-const Blob = z
-  .object({
-    chainId: z.number().check(z.int(), z.describe('Chain the blob belongs to.')),
-    schema: z.number().check(z.int(), z.describe('Storage schema version.')),
-    tokens: Data,
-    updatedAt: z.string().check(z.describe('ISO timestamp of the last publish.')),
-    version: z.string().check(z.describe('Snapshot version this blob holds.')),
-  })
-  .check(z.describe('Verified-token snapshot blob stored under a versioned key.'))
-
-/** Parsed head pointer for a chain. */
-export type Head = z.output<typeof Head>
-
-/** Reads a chain's head pointer, or `null` when the chain has no head yet. */
-async function readHead(store: Store.State, chainId: ChainId): Promise<Head | null> {
-  const raw = await store.get(headKey(chainId))
-  if (!raw) return null
-  return Head.parse(JSON.parse(raw))
+/** Reads a chain's list metadata, or `null` when it has no list yet. */
+async function readHead(db: Db.Db, chainId: ChainId): Promise<Head | null> {
+  return (await core_VerifiedTokens.head(db, chainId)) ?? null
 }
 
 /**
- * Reads and compiles a chain's snapshot blob at a specific version. Throws
- * {@link TornStateError} when the blob is missing (a torn write that should
- * never happen given the write-blob-before-flip-head ordering).
+ * Reads and compiles a chain's current verified list. Returns `null` when the
+ * chain has none.
  */
-async function readBlob(store: Store.State, chainId: ChainId, version: string): Promise<Snapshot> {
-  const raw = await store.get(snapshotKey(chainId, version))
-  if (!raw) throw new TornStateError({ chainId, version })
-  const parsed = JSON.parse(raw)
-  const blob = Blob.parse({
-    ...parsed,
-    tokens: Array.isArray(parsed.tokens) ? withIds(parsed.tokens) : parsed.tokens,
-  })
+export async function read(db: Db.Db, chainId: ChainId): Promise<Snapshot | null> {
+  const head = await readHead(db, chainId)
+  if (!head) return null
+  const rows = await core_VerifiedTokens.list(db, chainId)
   return compile({
     chainId,
-    tokens: blob.tokens,
-    updatedAt: blob.updatedAt,
-    version: blob.version,
+    tokens: rows.map(core_VerifiedTokens.toToken),
+    updatedAt: head.updatedAt,
+    version: head.version,
   })
 }
 
-/**
- * Reads and compiles the snapshot a chain's head points at. Returns `null` when
- * the chain has no head. Throws {@link TornStateError} when `head` references a
- * missing snapshot blob.
- */
-export async function read(store: Store.State, chainId: ChainId): Promise<Snapshot | null> {
-  const head = await readHead(store, chainId)
-  if (!head) return null
-  return readBlob(store, chainId, head.version)
-}
-
 // Tracks the last epoch-ms used by `nextVersion` so versions stay strictly
 // monotonic even when multiple writes land in the same millisecond.
 let lastVersionMs = 0
@@ -246,48 +193,56 @@ function withIds(tokens: readonly unknown[]): unknown[] {
 // Returns the current authoritative list for a chain to read-modify-write
 // against: the durable snapshot, or an empty list when the chain has no head yet
 // (the first write starts the chain's list from scratch).
-async function currentList(
-  store: Store.State,
-  chainId: ChainId,
-): Promise<readonly SnapshotToken[]> {
-  return (await read(store, chainId))?.list ?? []
+async function currentList(db: Db.Db, chainId: ChainId): Promise<readonly SnapshotToken[]> {
+  return (await read(db, chainId))?.list ?? []
 }
 
-// Best-effort optimistic concurrency: when `ifMatch` is set, the caller's
-// expected version must equal the current head version. On KV the head
-// read can itself be stale, so this narrows — but does not eliminate — the
-// lost-update window under concurrent writers.
+// Optimistic concurrency: when `ifMatch` is set, the caller's expected version
+// must equal the current head version. Runs inside the publish lock, so —
+// unlike the old best-effort KV check — the compare-and-set actually holds.
 async function assertVersion(
-  store: Store.State,
+  db: Db.Db,
   chainId: ChainId,
   ifMatch: string | undefined,
 ): Promise<void> {
   if (ifMatch === undefined) return
-  const head = await readHead(store, chainId)
+  const head = await readHead(db, chainId)
   const actual = head?.version ?? emptyVersion
   if (actual !== ifMatch) throw new VersionMismatchError({ actual, chainId, expected: ifMatch })
 }
 
-// Write-modify-flip-prime: validate the whole list, write the immutable
-// blob, flip `head` to it, then prime this isolate for read-your-write. Writing
-// the blob before flipping head means a crash in between leaves the old head
-// valid (no torn state).
+/**
+ * Fixed first key for the per-chain publish advisory lock (the ASCII bytes of
+ * `"vtok"`); the chain id is the second key.
+ */
+const publishLockKey = 0x76746f6b
+
+// Runs a write's read-modify-publish inside one transaction holding a
+// per-chain advisory lock, serializing concurrent writers so `assertVersion`
+// and the read-modify-write can't interleave (the lock releases on commit).
+async function withPublishLock<value>(
+  db: Db.Db,
+  chainId: ChainId,
+  fn: (tx: Db.Db) => Promise<value>,
+): Promise<value> {
+  return db.transaction(async (tx) => {
+    await sql`SELECT pg_advisory_xact_lock(${publishLockKey}, ${chainId})`.execute(tx.kysely)
+    return fn(tx)
+  })
+}
+
+// Validate-replace-prime: validate the whole list, replace the chain's rows
+// and bump its list version (atomic inside the publish lock's transaction),
+// then prime this isolate for read-your-write.
 async function publish(
-  store: Store.State,
+  db: Db.Db,
   chainId: ChainId,
   tokens: readonly TokenInput[],
 ): Promise<Snapshot> {
   const list = normalize(chainId, tokens)
   const version = nextVersion()
   const updatedAt = new Date().toISOString()
-  await store.put(
-    snapshotKey(chainId, version),
-    JSON.stringify({ chainId, schema: storeSchema, tokens: list, updatedAt, version }),
-  )
-  await store.put(
-    headKey(chainId),
-    JSON.stringify({ chainId, count: list.length, schema: storeSchema, updatedAt, version }),
-  )
+  await core_VerifiedTokens.publish(db, chainId, { tokens: list, updatedAt, version })
   const snapshot = compile({ chainId, tokens: list, updatedAt, version })
   prime(chainId, snapshot)
   return snapshot
@@ -297,21 +252,23 @@ async function publish(
  * Appends a verified token to a chain's list and publishes a new snapshot.
  * Throws on a duplicate address or (case-insensitive) symbol.
  */
-export async function create(store: Store.State, input: create.Input): Promise<create.Result> {
+export async function create(db: Db.Db, input: create.Input): Promise<create.Result> {
   const { chainId, currency, decimals, logoUri, name, symbol } = input
   const address = input.address.toLowerCase() as Hex.Hex
-  const list = await currentList(store, chainId)
-  const token: Token = {
-    address,
-    currency,
-    decimals,
-    id: address,
-    name,
-    symbol,
-    ...(logoUri === undefined ? {} : { logoUri }),
-  }
-  const snapshot = await publish(store, chainId, [...list, token])
-  return { snapshot, token: snapshot.byAddress.get(address)! }
+  return withPublishLock(db, chainId, async (tx) => {
+    const list = await currentList(tx, chainId)
+    const token: Token = {
+      address,
+      currency,
+      decimals,
+      id: address,
+      name,
+      symbol,
+      ...(logoUri === undefined ? {} : { logoUri }),
+    }
+    const snapshot = await publish(tx, chainId, [...list, token])
+    return { snapshot, token: snapshot.byAddress.get(address)! }
+  })
 }
 
 export declare namespace create {
@@ -347,33 +304,35 @@ export declare namespace create {
  * absent, and the uniqueness errors when an edit collides with another entry.
  */
 export async function patch(
-  store: Store.State,
+  db: Db.Db,
   chainId: ChainId,
   address: string,
   input: patch.Input,
   options: patch.Options = {},
 ): Promise<create.Result> {
-  await assertVersion(store, chainId, options.ifMatch)
   const target = address.toLowerCase() as Hex.Hex
-  const list = await currentList(store, chainId)
-  const index = list.findIndex((token) => token.address.toLowerCase() === target)
-  if (index === -1) throw new NotFoundError({ address: target, chainId })
-  // Edit in place, overriding only the fields the patch supplies.
-  const next = list.map((token, i) => {
-    if (i !== index) return token
-    const logoUri = input.logoUri ?? token.logoUri
-    return {
-      address: target,
-      currency: input.currency ?? token.currency,
-      decimals: input.decimals ?? token.decimals,
-      id: target,
-      name: input.name ?? token.name,
-      symbol: input.symbol ?? token.symbol,
-      ...(logoUri === undefined ? {} : { logoUri }),
-    }
+  return withPublishLock(db, chainId, async (tx) => {
+    await assertVersion(tx, chainId, options.ifMatch)
+    const list = await currentList(tx, chainId)
+    const index = list.findIndex((token) => token.address.toLowerCase() === target)
+    if (index === -1) throw new NotFoundError({ address: target, chainId })
+    // Edit in place, overriding only the fields the patch supplies.
+    const next = list.map((token, i) => {
+      if (i !== index) return token
+      const logoUri = input.logoUri ?? token.logoUri
+      return {
+        address: target,
+        currency: input.currency ?? token.currency,
+        decimals: input.decimals ?? token.decimals,
+        id: target,
+        name: input.name ?? token.name,
+        symbol: input.symbol ?? token.symbol,
+        ...(logoUri === undefined ? {} : { logoUri }),
+      }
+    })
+    const snapshot = await publish(tx, chainId, next)
+    return { snapshot, token: snapshot.byAddress.get(target)! }
   })
-  const snapshot = await publish(store, chainId, next)
-  return { snapshot, token: snapshot.byAddress.get(target)! }
 }
 
 export declare namespace patch {
@@ -402,17 +361,19 @@ export declare namespace patch {
  * Throws {@link NotFoundError} when the address is absent.
  */
 export async function remove(
-  store: Store.State,
+  db: Db.Db,
   chainId: ChainId,
   address: string,
   options: patch.Options = {},
 ): Promise<remove.Result> {
-  await assertVersion(store, chainId, options.ifMatch)
   const target = address.toLowerCase()
-  const list = await currentList(store, chainId)
-  const next = list.filter((token) => token.address.toLowerCase() !== target)
-  if (next.length === list.length) throw new NotFoundError({ address: target, chainId })
-  return { snapshot: await publish(store, chainId, next) }
+  return withPublishLock(db, chainId, async (tx) => {
+    await assertVersion(tx, chainId, options.ifMatch)
+    const list = await currentList(tx, chainId)
+    const next = list.filter((token) => token.address.toLowerCase() !== target)
+    if (next.length === list.length) throw new NotFoundError({ address: target, chainId })
+    return { snapshot: await publish(tx, chainId, next) }
+  })
 }
 
 export declare namespace remove {
@@ -428,13 +389,15 @@ export declare namespace remove {
  * bulk-load the initial list and to roll back to a previous one.
  */
 export async function replace(
-  store: Store.State,
+  db: Db.Db,
   chainId: ChainId,
   tokens: readonly TokenInput[],
   options: patch.Options = {},
 ): Promise<remove.Result> {
-  await assertVersion(store, chainId, options.ifMatch)
-  return { snapshot: await publish(store, chainId, tokens) }
+  return withPublishLock(db, chainId, async (tx) => {
+    await assertVersion(tx, chainId, options.ifMatch)
+    return { snapshot: await publish(tx, chainId, tokens) }
+  })
 }
 
 // Sentinel version/time for the empty snapshot served before a chain has any
@@ -491,7 +454,7 @@ export function prime(chainId: ChainId, snapshot: Snapshot): void {
 // chain share one in-flight refresh.
 function refresh(
   c: Context<App.Environment>,
-  store: Store.State,
+  db: Db.Db,
   chainId: ChainId,
   cell: Cell | undefined,
 ): Promise<Snapshot> {
@@ -499,7 +462,7 @@ function refresh(
   if (existing) return existing
   const flight = (async () => {
     try {
-      return await refreshCell(c, store, chainId, cell)
+      return await refreshCell(c, db, chainId, cell)
     } finally {
       refreshes.delete(chainId)
     }
@@ -513,15 +476,15 @@ function refresh(
 // when the chain has no head yet).
 async function refreshCell(
   c: Context<App.Environment>,
-  store: Store.State,
+  db: Db.Db,
   chainId: ChainId,
   cell: Cell | undefined,
 ): Promise<Snapshot> {
-  // Cold: no prior snapshot. Load from store, or an empty snapshot when the
-  // chain has no head. A hard failure here propagates (we have nothing good to
-  // serve, and must not resurrect deleted tokens).
+  // Cold: no prior snapshot. Load from the database, or an empty snapshot when
+  // the chain has no head. A hard failure here propagates (we have nothing good
+  // to serve, and must not resurrect deleted tokens).
   if (!cell) {
-    const loaded = await Timing.time(c, 'verified_snapshot', () => read(store, chainId))
+    const loaded = await Timing.time(c, 'verified_snapshot', () => read(db, chainId))
     const snapshot = loaded ?? emptySnapshot(chainId)
     cells.set(chainId, { checkedAt: Date.now(), snapshot })
     return snapshot
@@ -530,16 +493,15 @@ async function refreshCell(
   // Soft-stale: serve the last good in-memory snapshot and log loudly on
   // failure rather than dropping to empty (no resurrection of deleted tokens).
   try {
-    const head = await Timing.time(c, 'verified_head', () => readHead(store, chainId))
+    const head = await Timing.time(c, 'verified_head', () => readHead(db, chainId))
     // Unchanged version (or head not yet present): keep snapshot, bump checkedAt.
     if (!head || head.version === cell.snapshot.version) {
       cells.set(chainId, { checkedAt: Date.now(), snapshot: cell.snapshot })
       return cell.snapshot
     }
-    // Version changed: load the new blob directly (head already in hand).
-    const snapshot = await Timing.time(c, 'verified_snapshot', () =>
-      readBlob(store, chainId, head.version),
-    )
+    // Version changed: reload the current list (kept on a racing delete).
+    const snapshot =
+      (await Timing.time(c, 'verified_snapshot', () => read(db, chainId))) ?? cell.snapshot
     cells.set(chainId, { checkedAt: Date.now(), snapshot })
     return snapshot
   } catch (error) {
@@ -553,32 +515,32 @@ async function refreshCell(
  * Returns the compiled verified-token {@link Snapshot} for a chain.
  *
  * When the verified-tokens feature is unconfigured, serves an empty snapshot.
- * When configured with a {@link Store.State}, serves a per-isolate snapshot
- * refreshed on a soft TTL: fresh lookups do zero store I/O; soft-stale
+ * When configured, serves a per-isolate snapshot backed by the app database,
+ * refreshed on a soft TTL: fresh lookups do zero database I/O; soft-stale
  * lookups return the current snapshot immediately and refresh in the background
  * (single-flight, head-only unless the version changed); a cold isolate loads
- * from the store (an empty snapshot when no head exists).
+ * from the database (an empty snapshot when no head exists).
  */
 export async function snapshot(c: Context<App.Environment>, chainId: ChainId): Promise<Snapshot> {
   return Timing.time(c, 'verified_tokens', () => {
     const config = c.get('verifiedTokens')
-    // Unconfigured: nothing is verified. No store, no cell.
+    // Unconfigured: nothing is verified. No reads, no cell.
     if (!config) return emptySnapshot(chainId)
 
     const refreshMs = config.refreshMs ?? defaultRefreshMs
     const cell = cells.get(chainId)
 
-    // Fresh: serve the in-memory snapshot with zero store I/O.
+    // Fresh: serve the in-memory snapshot with zero database I/O.
     if (cell && Date.now() - cell.checkedAt < refreshMs) return cell.snapshot
 
     // Soft-stale: serve immediately, refresh in the background. Never blocks.
     if (cell) {
-      void refresh(c, config.store, chainId, cell)
+      void refresh(c, Db.get(c.get('dbCached')), chainId, cell)
       return cell.snapshot
     }
 
     // Cold: must load before the first response.
-    return refresh(c, config.store, chainId, undefined)
+    return refresh(c, Db.get(c.get('dbCached')), chainId, undefined)
   })
 }
 
@@ -590,20 +552,6 @@ export async function snapshot(c: Context<App.Environment>, chainId: ChainId): P
  */
 export const currencies = ['EUR', 'USD']
 
-/**
- * Thrown when a chain's `head` points at a snapshot version whose blob is
- * missing from the store. The write path always writes the blob before flipping
- * the head, so this indicates a torn write or external tampering.
- */
-export class TornStateError extends Error {
-  override name = 'VerifiedTokens.TornStateError'
-  constructor(options: { chainId: number; version: string }) {
-    super(
-      `verified-token head for chain ${options.chainId} points at missing snapshot version "${options.version}".`,
-    )
-  }
-}
-
 /** Thrown when a write would introduce a duplicate address on a chain. */
 export class DuplicateAddressError extends Error {
   override name = 'VerifiedTokens.DuplicateAddressError'

package/src/internal/WebhookDestination.test.ts

@@ -3,7 +3,7 @@ import * as WebhookDestination from './WebhookDestination.js'
 const envelope = {
   chainId: 4217,
   createdAt: '2026-01-01T00:00:00.000Z',
-  data: { amount: '1000', token: '0xabc' },
+  data: { amount: '1000', token: `0x${'aa'.repeat(20)}` },
   id: 'evt_test',
   subscriptionId: 'wh_test',
   type: 'token:transfer',