tapimo 0.9.0 → 0.10.1

package/src/internal/Store.test.ts

@@ -389,6 +389,39 @@ describe('durableObject', () => {
     `)
   })
 
+  test('preserves bigint values and collision-shaped strings', async () => {
+    const { namespace } = TestStore.durableObjectNamespace()
+    const store = Store.durableObject<{
+      value: { bigint: bigint; legacyMarker: string; valueMarker: string }
+    }>(namespace)
+    const value = {
+      bigint: 42n,
+      legacyMarker: '123#__bigint',
+      valueMarker: 'tempo-api:store:value:bigint:123',
+    }
+
+    await store.put('value', value)
+    await store.update('value', (current) => ({
+      op: 'set',
+      result: undefined,
+      value: { ...current!, bigint: current!.bigint + 1n },
+    }))
+
+    expect(await store.get('value')).toEqual({ ...value, bigint: 43n })
+  })
+
+  test('reads typed values written with the legacy codec', async () => {
+    const { getState, namespace } = TestStore.durableObjectNamespace()
+    await getState('channel').put('channel', 'tempo-api:store:json:v1:{"spent":"42#__bigint"}')
+    const store = Store.durableObject<TypedItems>(namespace)
+
+    expect(await store.get('channel')).toMatchInlineSnapshot(`
+      {
+        "spent": 42n,
+      }
+    `)
+  })
+
   test('keeps typed updates linearizable', async () => {
     const { namespace } = TestStore.durableObjectNamespace()
     const storeA = Store.durableObject<TypedItems>(namespace)
@@ -439,11 +472,11 @@ describe('durableObject', () => {
 
   test('rejects typed values written with an unknown codec version', async () => {
     const { getState, namespace } = TestStore.durableObjectNamespace()
-    await getState('channel').put('channel', 'tempo-api:store:json:v2:{}')
+    await getState('channel').put('channel', 'tempo-api:store:json:v3:{}')
     const store = Store.durableObject<TypedItems>(namespace)
 
     await expect(store.get('channel')).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[Store.DurableObjectCodecError: Unsupported Durable Object store codec version: v2]`,
+      `[Store.DurableObjectCodecError: Unsupported Durable Object store codec version: v3]`,
     )
   })
 
@@ -744,11 +777,9 @@ describe('memoize', () => {
     const values = await Promise.all(requests)
 
     expect(calls).toMatchInlineSnapshot(`1`)
-    expect(JSON.parse((await store.get('memo:test')) ?? 'null')).toMatchInlineSnapshot(`
-      {
-        "value": "fresh",
-      }
-    `)
+    expect(await store.get('memo:test')).toMatchInlineSnapshot(
+      `"tempo-api:store:json:v2:{"value":"fresh"}"`,
+    )
     expect(values).toMatchInlineSnapshot(`
       [
         {
@@ -805,8 +836,65 @@ describe('memoize', () => {
     `)
   })
 
+  test('preserves bigint values and collision-shaped strings on cache hits', async () => {
+    const store = Store.memory()
+    let calls = 0
+    const fetch = async () => {
+      calls += 1
+      return {
+        bigint: 42n,
+        legacyMarker: '123#__bigint',
+        valueMarker: 'tempo-api:store:value:bigint:123',
+      }
+    }
+
+    const first = await Store.memoize(fetch, { key: 'memo:test', store, ttl: 60_000 })
+    const second = await Store.memoize(fetch, { key: 'memo:test', store, ttl: 60_000 })
+
+    expect(first).toEqual(second)
+    expect(second).toEqual({
+      bigint: 42n,
+      legacyMarker: '123#__bigint',
+      valueMarker: 'tempo-api:store:value:bigint:123',
+    })
+    expect(calls).toBe(1)
+  })
+
+  test('does not cache undefined results', async () => {
+    const store = Store.memory()
+    let calls = 0
+    const fetch = async () => {
+      calls += 1
+      return undefined
+    }
+
+    const first = await Store.memoize(fetch, { key: 'memo:test', store, ttl: 60_000 })
+    const second = await Store.memoize(fetch, { key: 'memo:test', store, ttl: 60_000 })
+
+    expect(first).toBeUndefined()
+    expect(second).toBeUndefined()
+    expect(await store.get('memo:test')).toBeNull()
+    expect(calls).toBe(2)
+  })
+
+  test('refreshes legacy untagged cache entries', async () => {
+    const store = Store.memory({ entries: [['memo:test', '{"value":"123#__bigint"}']] })
+    let calls = 0
+
+    const value = await Store.memoize(
+      async () => {
+        calls += 1
+        return { value: '123#__bigint' }
+      },
+      { key: 'memo:test', store, ttl: 60_000 },
+    )
+
+    expect(value).toEqual({ value: '123#__bigint' })
+    expect(calls).toBe(1)
+  })
+
   test('refreshes corrupt cache entries', async () => {
-    const store = Store.memory({ entries: [['memo:test', 'not-json']] })
+    const store = Store.memory({ entries: [['memo:test', 'tempo-api:store:json:v2:not-json']] })
 
     const value = await Store.memoize(async () => ({ value: 'fresh' }), {
       key: 'memo:test',
@@ -819,11 +907,9 @@ describe('memoize', () => {
         "value": "fresh",
       }
     `)
-    expect(JSON.parse((await store.get('memo:test')) ?? 'null')).toMatchInlineSnapshot(`
-      {
-        "value": "fresh",
-      }
-    `)
+    expect(await store.get('memo:test')).toMatchInlineSnapshot(
+      `"tempo-api:store:json:v2:{"value":"fresh"}"`,
+    )
   })
 })
 

package/src/internal/Store.ts

@@ -578,7 +578,8 @@ export declare namespace durableObject {
 /**
  * Wraps an async producer with store-backed caching. Returns the cached value if
  * present and valid; otherwise runs `fetch`, stores the JSON-encoded result
- * under `key` with `ttl` milliseconds, and returns it.
+ * under `key` with `ttl` milliseconds, and returns it. Undefined results are
+ * returned without being cached.
  */
 export async function memoize<value>(
   fetch: () => Promise<value>,
@@ -587,9 +588,11 @@ export async function memoize<value>(
   const { key, store, ttl } = options
 
   const raw = await store.get(key)
-  if (raw) {
+  // Old cache entries used ambiguous untagged bigint strings. Refresh them
+  // instead of guessing whether a matching string was originally a bigint.
+  if (raw?.startsWith(jsonCodecPrefix)) {
     try {
-      return Json.parse(raw) as value
+      return jsonDecode(raw) as value
     } catch {
       // Corrupt entries are treated as misses so the next call refreshes.
     }
@@ -604,7 +607,8 @@ export async function memoize<value>(
   // fetch is still in flight.
   const flight = (async () => {
     const value = await fetch()
-    await store.put(key, Json.stringify(value), { ttl })
+    if (value === undefined) return value
+    await store.put(key, jsonEncode(value), { ttl })
     return value
   })()
   flights.set(key, flight)
@@ -721,24 +725,55 @@ async function durableObjectRetry<value>(call: () => Promise<value>): Promise<va
   }
 }
 
-const durableObjectCodecRoot = 'tempo-api:store:json:'
-const durableObjectCodecVersion = 'v1'
-const durableObjectCodecPrefix = `${durableObjectCodecRoot}${durableObjectCodecVersion}:`
+const jsonCodecRoot = 'tempo-api:store:json:'
+const jsonCodecVersion = 'v2'
+const jsonCodecPrefix = `${jsonCodecRoot}${jsonCodecVersion}:`
+const jsonValuePrefix = 'tempo-api:store:value:'
+const legacyDurableObjectCodecPrefix = `${jsonCodecRoot}v1:`
+
+function jsonEncode(value: unknown): string {
+  const encoded = JSON.stringify(value, (_key, item) => {
+    if (typeof item === 'bigint') return `${jsonValuePrefix}bigint:${item}`
+    if (typeof item === 'string' && item.startsWith(jsonValuePrefix))
+      return `${jsonValuePrefix}string:${item}`
+    return item
+  })
+  if (encoded === undefined) throw new TypeError('Store value is not serializable')
+  return `${jsonCodecPrefix}${encoded}`
+}
+
+function jsonDecode(value: string): unknown {
+  return JSON.parse(value.slice(jsonCodecPrefix.length), (_key, item) => {
+    if (typeof item !== 'string' || !item.startsWith(jsonValuePrefix)) return item
+    if (item.startsWith(`${jsonValuePrefix}string:`))
+      return item.slice(`${jsonValuePrefix}string:`.length)
+    if (item.startsWith(`${jsonValuePrefix}bigint:`)) {
+      const bigint = item.slice(`${jsonValuePrefix}bigint:`.length)
+      if (!/^-?\d+$/.test(bigint)) throw new TypeError('Store bigint is malformed')
+      return BigInt(bigint)
+    }
+    throw new TypeError('Store value tag is unsupported')
+  })
+}
 
 function durableObjectEncode(value: unknown): string {
-  if (typeof value === 'string' && !value.startsWith(durableObjectCodecRoot)) return value
-  const encoded = Json.stringify(value)
-  if (encoded === undefined) throw new TypeError('Durable Object store value is not serializable')
-  return `${durableObjectCodecPrefix}${encoded}`
+  if (typeof value === 'string' && !value.startsWith(jsonCodecRoot)) return value
+  try {
+    return jsonEncode(value)
+  } catch (cause) {
+    throw new TypeError('Durable Object store value is not serializable', {
+      cause,
+    })
+  }
 }
 
 function durableObjectDecode(value: null | string): unknown {
-  if (value === null || !value.startsWith(durableObjectCodecRoot)) return value
-  if (!value.startsWith(durableObjectCodecPrefix)) {
-    const [version] = value.slice(durableObjectCodecRoot.length).split(':')
-    throw new DurableObjectCodecError(version)
-  }
-  return Json.parse(value.slice(durableObjectCodecPrefix.length))
+  if (value === null || !value.startsWith(jsonCodecRoot)) return value
+  if (value.startsWith(jsonCodecPrefix)) return jsonDecode(value)
+  if (value.startsWith(legacyDurableObjectCodecPrefix))
+    return Json.parse(value.slice(legacyDurableObjectCodecPrefix.length))
+  const [version] = value.slice(jsonCodecRoot.length).split(':')
+  throw new DurableObjectCodecError(version)
 }
 
 function cloudflareKvExpirationTtl(ttl: number | undefined) {

package/src/internal/Tidx.test.ts

@@ -330,9 +330,9 @@ describe('resolve', () => {
   test('passes Zone metadata to the resolver', () => {
     expect(
       Tidx.resolve(({ zone }) => ({ baseUrl: zone ? 'http://tidx:8080' : undefined }), {
-        chainId: Zones.zoneE.id,
+        chainId: Zones.zoneModeratoInternal.id,
         principal: null,
-        zone: Zones.zoneE,
+        zone: Zones.zoneModeratoInternal,
       }),
     ).toMatchInlineSnapshot(`
       {
@@ -469,7 +469,7 @@ describe('getClient', () => {
     )
     try {
       const client = Tidx.getClient({
-        chainId: Zones.zoneE.id,
+        chainId: Zones.zoneModeratoInternal.id,
         tidx: {
           baseUrl: 'https://internal.indexer',
           zoneHeaders: {
@@ -477,7 +477,7 @@ describe('getClient', () => {
             'CF-Access-Client-Secret': 'client-secret',
           },
         },
-        zone: Zones.zoneE,
+        zone: Zones.zoneModeratoInternal,
       })
       await client.fetch({ query: 'select 1' })
 

package/src/internal/Tidx.ts

@@ -92,9 +92,7 @@ export function getClient(options: getClient.Options): Client {
  * output (`baseUrl` + auth + `chainId`), not the principal, so a resolver
  * `tidx` may branch on any principal field while client cardinality stays
  * bounded by the number of distinct upstreams — callers that resolve to the same
- * upstream share a client. Shared by `data()` (per-request reads) and
- * `Webhooks.createPoller` (the scheduled poller) so the resolver logic lives in
- * one place.
+ * upstream share a client.
  */
 export function createGetClient(options: createGetClient.Options = {}): GetClient {
   const { defaultChainId = Viem.defaultChainId, tidx } = options

package/src/internal/Value.test.ts

@@ -1,5 +1,30 @@
 import * as Value from './Value.js'
 
+describe('blockToIso', () => {
+  test('prefers the millisecond timestamp on a raw header', () => {
+    expect(
+      Value.blockToIso({ timestamp: '0x6a7b5571', timestampMillis: '0x19ff1c5c312' }),
+    ).toMatchInlineSnapshot(`"2026-08-11T17:01:37.426Z"`)
+  })
+
+  test('falls back to whole seconds when the millisecond timestamp is absent', () => {
+    expect(Value.blockToIso({ timestamp: '0x6a7b5571' })).toMatchInlineSnapshot(
+      `"2026-08-11T17:01:37.000Z"`,
+    )
+  })
+
+  test('reads a viem-formatted header', () => {
+    expect(
+      Value.blockToIso({ timestamp: 1_786_467_697n, timestampMillis: '0x19ff1c5c312' }),
+    ).toMatchInlineSnapshot(`"2026-08-11T17:01:37.426Z"`)
+  })
+
+  test('returns undefined without a usable timestamp', () => {
+    expect(Value.blockToIso(undefined)).toMatchInlineSnapshot(`undefined`)
+    expect(Value.blockToIso({ timestamp: null })).toMatchInlineSnapshot(`undefined`)
+  })
+})
+
 describe('tokenAmount', () => {
   test('renders a self-contained token quantity', () => {
     expect(

package/src/internal/Value.ts

@@ -111,6 +111,35 @@ export function hexSecondsToIso(value: unknown): string | undefined {
   return seconds === undefined ? undefined : new Date(seconds * 1000).toISOString()
 }
 
+/**
+ * Read a block's timestamp as epoch milliseconds, preferring Tempo's
+ * `timestampMillis` over the second-granularity `timestamp`. Accepts hex
+ * quantities (raw RPC) and bigint/number (viem-formatted).
+ */
+function blockToMillis(block: unknown): number | undefined {
+  if (typeof block !== 'object' || block === null) return undefined
+  const { timestamp, timestampMillis } = block as {
+    timestamp?: unknown
+    timestampMillis?: unknown
+  }
+  const millis = quantity(timestampMillis)
+  if (millis !== undefined) return millis
+  const seconds = quantity(timestamp)
+  return seconds === undefined ? undefined : seconds * 1_000
+}
+
+/** Convert a block's timestamp to an ISO 8601 datetime string, preserving milliseconds. */
+export function blockToIso(block: unknown): string | undefined {
+  const millis = blockToMillis(block)
+  return millis === undefined ? undefined : new Date(millis).toISOString()
+}
+
+/** Narrows a quantity that may arrive hex-encoded (raw RPC) or decoded (viem). */
+function quantity(value: unknown): number | undefined {
+  const number = toNumber(value)
+  return number === undefined || !Number.isFinite(number) ? undefined : number
+}
+
 /**
  * Coerce a TIDX timestamp column (Date / epoch seconds / epoch ms / ISO string)
  * to an ISO 8601 datetime string. Returns undefined when the value cannot be

package/src/internal/Viem.test.ts

@@ -220,6 +220,14 @@ describe('resolveRpc', () => {
 })
 
 describe('getClient', () => {
+  test('disables multicall for Zones', () => {
+    const l1Client = Viem.getClient({ chainId: 4217 })
+    const zoneClient = Viem.getClient({ chainId: zone.id, zone })
+
+    expect(l1Client.batch?.multicall).toEqual({ deployless: true })
+    expect(zoneClient.batch?.multicall).toBe(false)
+  })
+
   test('sends inferred Bearer auth', async () => {
     const fetch = vi
       .spyOn(globalThis, 'fetch')

package/src/internal/Viem.ts

@@ -163,7 +163,8 @@ export function getClient(options: getClient.Options): getClient.ReturnType {
     // (e.g. `balanceOf` across many tokens) and pay one RPC round-trip.
     // Deployless mode bytecode-injects multicall3 so Tempo, which doesn't
     // configure a deployed multicall3, can still serve the aggregated call.
-    batch: { multicall: { deployless: true } },
+    // Zones disable multicall entirely and issue concurrent direct `eth_call`s instead.
+    batch: { multicall: zone ? false : { deployless: true } },
     chain: { ...tempoMainnet, id: chainId },
     transport: http(rpcUrl, fetchOptions ? { fetchOptions } : {}),
   })

package/src/internal/WebhookDestination.test.ts

@@ -93,6 +93,26 @@ describe('from', () => {
   })
 })
 
+describe('isRetryable', () => {
+  test.each([
+    ['success', { ok: true, status: 204 }, false],
+    ['redirect', { error: 'redirect rejected (302)', ok: false, status: 302 }, false],
+    ['bad request', { error: 'non-2xx response (400)', ok: false, status: 400 }, false],
+    ['request timeout', { error: 'non-2xx response (408)', ok: false, status: 408 }, true],
+    ['rate limited', { error: 'non-2xx response (429)', ok: false, status: 429 }, true],
+    ['server error', { error: 'non-2xx response (503)', ok: false, status: 503 }, true],
+    ['opaque redirect', { error: 'redirect rejected (0)', ok: false }, false],
+    ['timeout', { error: 'timed out after 10000ms', ok: false }, true],
+    ['network error', { error: 'TypeError: fetch failed', ok: false }, true],
+    ['unknown error', { ok: false }, true],
+  ] satisfies readonly [string, WebhookDestination.Result, boolean][])(
+    '%s',
+    (_label, result, retryable) => {
+      expect(WebhookDestination.isRetryable(result)).toBe(retryable)
+    },
+  )
+})
+
 describe('url().deliver', () => {
   test('signs the body and POSTs a 2xx as success', async () => {
     let captured:

package/src/internal/WebhookDestination.ts

@@ -100,6 +100,16 @@ export type Result = {
   status?: number | undefined
 }
 
+/** Returns whether another delivery attempt could plausibly succeed. */
+export function isRetryable(result: Result): boolean {
+  if (result.ok) return false
+  if (result.status !== undefined)
+    return result.status === 408 || result.status === 429 || result.status >= 500
+  // Workers exposes rejected redirects as an opaque response without a status.
+  if (result.error && /redirect/i.test(result.error)) return false
+  return true
+}
+
 /**
  * Canonical constructor: normalizes a value into a validated {@link Instance} by
  * delegating to the matching builder (`url`, `slack`, `betterStack`), each of

package/src/internal/WebhookTransfer.test.ts

@@ -0,0 +1,89 @@
+import type { Hex } from 'ox'
+
+import * as WebhookTransfer from './WebhookTransfer.js'
+
+const token: Hex.Hex = '0x20c0000000000000000000000000000000000001'
+const sender: Hex.Hex = `0x${'aa'.repeat(20)}`
+const recipient: Hex.Hex = `0x${'bb'.repeat(20)}`
+const other: Hex.Hex = `0x${'cc'.repeat(20)}`
+const transactionHash = `0x${'ef'.repeat(32)}`
+const transferTopic = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
+const timestamp = '2026-01-01T00:00:00.000Z'
+
+const addressTopic = (address: string) => `0x${'0'.repeat(24)}${address.slice(2)}`
+
+function transferLog(overrides: Record<string, unknown> = {}) {
+  return {
+    address: token,
+    blockNumber: '0x7b',
+    data: `0x${(10n ** 18n).toString(16).padStart(64, '0')}`,
+    logIndex: '0x4',
+    topics: [transferTopic, addressTopic(sender), addressTopic(recipient)],
+    transactionHash,
+    transactionIndex: '0x0',
+    ...overrides,
+  } as never
+}
+
+describe('decode', () => {
+  test('decodes a strict TIP-20 Transfer log', () => {
+    expect(WebhookTransfer.decode(transferLog(), timestamp)).toMatchInlineSnapshot(`
+      {
+        "address": "0x20c0000000000000000000000000000000000001",
+        "amount": "1000000000000000000",
+        "blockNumber": 123,
+        "logIndex": 4,
+        "recipient": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        "sender": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "timestamp": "2026-01-01T00:00:00.000Z",
+        "transactionHash": "0xefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef",
+      }
+    `)
+  })
+
+  test('rejects non-TIP-20 addresses and malformed payloads', () => {
+    const cases: readonly Record<string, unknown>[] = [
+      // Outside the deterministic TIP-20 address range.
+      { address: other },
+      // Missing recipient topic.
+      { topics: [transferTopic, addressTopic(sender)] },
+      // Wrong event selector.
+      { topics: [`0x${'12'.repeat(32)}`, addressTopic(sender), addressTopic(recipient)] },
+      // Sender topic without the address left-padding.
+      { topics: [transferTopic, `0x${'ff'.repeat(32)}`, addressTopic(recipient)] },
+      // Amount payload is not one word.
+      { data: '0x01' },
+      // Pending-log positions cannot form a cursor.
+      { blockNumber: null },
+      { logIndex: null },
+    ]
+    for (const overrides of cases)
+      expect(
+        WebhookTransfer.decode(transferLog(overrides), timestamp),
+        JSON.stringify(overrides),
+      ).toBeUndefined()
+  })
+})
+
+describe('matches', () => {
+  const data = WebhookTransfer.decode(transferLog(), timestamp)!
+
+  test('AND-combines side, either-side address, and token filters', () => {
+    const cases: readonly [WebhookTransfer.Filters, boolean][] = [
+      [{}, true],
+      [{ sender }, true],
+      [{ sender: recipient }, false],
+      [{ recipient }, true],
+      [{ recipient: sender }, false],
+      [{ address: sender }, true],
+      [{ address: recipient }, true],
+      [{ address: other }, false],
+      [{ token }, true],
+      [{ token: '0x20c0000000000000000000000000000000000002' }, false],
+      [{ recipient, sender, token }, true],
+      [{ recipient: sender, sender, token }, false],
+    ]
+    for (const [filters, expected] of cases)
+      expect(WebhookTransfer.matches(data, filters), JSON.stringify(filters)).toBe(expected)
+  })
+})