tapimo 0.13.0 → 0.15.0

package/src/internal/EarnSharePrices.ts

@@ -0,0 +1,313 @@
+import {
+  type Address,
+  ContractFunctionExecutionError,
+  ContractFunctionRevertedError,
+  ContractFunctionZeroDataError,
+} from 'viem'
+
+import type * as Tidx from './Tidx.js'
+import * as Ttl from './Ttl.js'
+import * as Value from './Value.js'
+import type * as Viem from './Viem.js'
+
+/** Only interval supported by historical Earn share prices. */
+export const interval = 'day' as const
+
+/** Maximum observations returned by one historical share-price request. */
+export const maxPoints = 31
+
+const maxShareDecimals = 77
+// The TIDX proxy rejects deeper nested UNION ALL probes.
+const tidxChunkSize = 3
+const tidxWaveSize = 4
+
+/** Reads daily historical share prices for one Earn vault. */
+export async function resolve(options: resolve.Options): Promise<readonly Point[]> {
+  const shareAmount = quoteShareAmount({ shareDecimals: options.shareDecimals })
+  const requested = timestamps({ from: options.from, to: options.to })
+  const blocks = await getBlocks(options.getTidx(options.chainId), { timestamps: requested })
+  const client = options.getClient(options.chainId)
+  const points = await Promise.all(
+    blocks.map((block) =>
+      client.earn
+        .getRedeemQuote({
+          blockNumber: BigInt(block.number),
+          shareAmount,
+          vault: options.vault,
+        })
+        .then(
+          (amount) => ({ amount, timestamp: block.requestedAt }),
+          (error) => {
+            if (isUnavailable(error)) return undefined
+            throw error
+          },
+        ),
+    ),
+  )
+  return points.flatMap((point) => (point === undefined ? [] : [point]))
+}
+
+export declare namespace resolve {
+  /** Inputs selecting one Earn vault share-price series. */
+  type Options = {
+    /** Chain containing the Earn vault. */
+    chainId: number
+    /** First inclusive daily observation, as an ISO 8601 timestamp. */
+    from: string
+    /** Resolves the chain RPC client used for historical quotes. */
+    getClient: Viem.GetClient
+    /** Resolves the chain indexer client used for block boundaries. */
+    getTidx: Tidx.GetClient
+    /** Decimal places used by the vault share token. */
+    shareDecimals: number
+    /** Inclusive upper bound for daily observations, as an ISO 8601 timestamp. */
+    to: string
+    /** Earn vault contract address. */
+    vault: Address
+  }
+}
+
+/** Returns one whole share in base units when it fits in a `uint256`. */
+export function quoteShareAmount(options: quoteShareAmount.Options): bigint {
+  if (options.shareDecimals > maxShareDecimals)
+    throw new UnsupportedShareDecimalsError(options.shareDecimals)
+  return 10n ** BigInt(options.shareDecimals)
+}
+
+export declare namespace quoteShareAmount {
+  /** Share-token metadata used to derive one whole share. */
+  type Options = {
+    /** Decimal places used by the vault share token. */
+    shareDecimals: number
+  }
+}
+
+/** One historical share-price observation. */
+export type Point = {
+  /** Assets returned for one whole vault share, in the asset token's base unit. */
+  amount: bigint
+  /** Requested daily observation timestamp in ISO 8601 format. */
+  timestamp: string
+}
+
+/** Returns daily observation timestamps anchored to the requested start. */
+export function timestamps(options: timestamps.Options): readonly string[] {
+  const from = Date.parse(options.from)
+  const to = Date.parse(options.to)
+  return Array.from({ length: Math.floor((to - from) / Ttl.days(1)) + 1 }, (_, index) =>
+    new Date(from + index * Ttl.days(1)).toISOString(),
+  )
+}
+
+export declare namespace timestamps {
+  /** Range covered by daily observations. */
+  type Options = {
+    /** First inclusive daily observation, as an ISO 8601 timestamp. */
+    from: string
+    /** Inclusive upper bound for daily observations, as an ISO 8601 timestamp. */
+    to: string
+  }
+}
+
+/** Returns whether a historical quote is unavailable from contract execution. */
+export function isUnavailable(error: unknown): boolean {
+  if (!(error instanceof ContractFunctionExecutionError)) return false
+  return Boolean(
+    error.walk(
+      (cause) =>
+        cause instanceof ContractFunctionRevertedError ||
+        cause instanceof ContractFunctionZeroDataError,
+    ),
+  )
+}
+
+/** Resolves one indexed block at or before every requested observation. */
+async function getBlocks(tidx: Tidx.Client, options: getBlocks.Options): Promise<readonly Block[]> {
+  const last = options.timestamps.at(-1)
+  if (last) await assertCoverage(tidx, last)
+
+  const chunks = Array.from(
+    { length: Math.ceil(options.timestamps.length / tidxChunkSize) },
+    (_, index) => options.timestamps.slice(index * tidxChunkSize, (index + 1) * tidxChunkSize),
+  )
+  const results: Block[][] = []
+  // Bound concurrent queries so long ranges do not fan out into a wide indexer burst.
+  for (let index = 0; index < chunks.length; index += tidxWaveSize) {
+    const wave = await Promise.allSettled(
+      chunks.slice(index, index + tidxWaveSize).map(async (timestamps) => {
+        const boundaries = timestamps.map((requestedAt) => {
+          const timestamp = requestedAt.replace('T', ' ').replace(/Z$/, '')
+          return `
+          SELECT
+            'boundary' AS kind,
+            '${timestamp}' AS requested_at,
+            toString(num) AS num,
+            toString(timestamp) AS timestamp
+          FROM (
+            SELECT num, timestamp
+            FROM blocks
+            WHERE timestamp <= '${timestamp}'
+            ORDER BY timestamp DESC, num DESC
+            LIMIT 1
+          )
+        `
+        })
+        const result = await tidx
+          .fetch({
+            engine: 'clickhouse',
+            // SAFETY: Zod restricts every timestamp to ISO 8601 before this function is called.
+            query: `
+            ${boundaries.join('\nUNION ALL\n')}
+          ` as string,
+          })
+          .catch((cause) => {
+            throw new TidxRequestError(cause)
+          })
+        return parseBlocks({ rows: result.rows, timestamps })
+      }),
+    )
+    const failure = wave.find((result) => result.status === 'rejected')
+    if (failure) throw failure.reason
+    results.push(...wave.flatMap((result) => (result.status === 'fulfilled' ? [result.value] : [])))
+  }
+  return results.flat()
+}
+
+async function assertCoverage(tidx: Tidx.Client, timestamp: string): Promise<void> {
+  const result = await tidx
+    .fetch({
+      engine: 'clickhouse',
+      query: `
+        SELECT toString(timestamp) AS timestamp
+        FROM blocks
+        ORDER BY timestamp DESC, num DESC
+        LIMIT 1
+      ` as string,
+    })
+    .catch((cause) => {
+      throw new TidxRequestError(cause)
+    })
+  parseCoverage({ row: result.rows[0], timestamp })
+}
+
+/** Validates that indexed block timestamps cover a requested observation. */
+export function parseCoverage(options: parseCoverage.Options): void {
+  const indexedAt = Value.toIsoDateTime(options.row?.timestamp)
+  if (indexedAt === undefined)
+    throw new MalformedResponseError('TIDX returned no indexed coverage timestamp.')
+  if (Date.parse(indexedAt) < Date.parse(options.timestamp))
+    throw new IndexedCoverageError(options.timestamp)
+}
+
+export declare namespace parseCoverage {
+  /** Indexed timestamp and requested observation to compare. */
+  type Options = {
+    /** Latest indexed block by timestamp. */
+    row: Row | undefined
+    /** Requested observation timestamp. */
+    timestamp: string
+  }
+}
+
+declare namespace getBlocks {
+  /** Daily observations that need indexed blocks. */
+  type Options = {
+    timestamps: readonly string[]
+  }
+}
+
+type Block = {
+  /** Indexed block number used for the historical quote. */
+  number: number
+  /** Requested observation timestamp represented by this block. */
+  requestedAt: string
+  /** Actual timestamp of the indexed block. */
+  timestamp: string
+}
+
+/** Decodes daily historical boundaries from TIDX rows. */
+export function parseBlocks(options: parseBlocks.Options) {
+  const boundaries = new Map<string, Block>()
+  for (const row of options.rows) {
+    const number = Value.toNumber(row.num)
+    const requestedAt = Value.toIsoDateTime(row.requested_at)
+    const timestamp = Value.toIsoDateTime(row.timestamp)
+    if (
+      row.kind !== 'boundary' ||
+      number === undefined ||
+      !Number.isSafeInteger(number) ||
+      number < 0 ||
+      requestedAt === undefined ||
+      timestamp === undefined
+    )
+      throw new MalformedResponseError('TIDX returned a malformed share-price boundary.')
+    boundaries.set(requestedAt, { number, requestedAt, timestamp })
+  }
+  return options.timestamps.map((requestedAt) => {
+    const block = boundaries.get(requestedAt)
+    if (!block) throw new IndexedBlockNotFoundError(requestedAt)
+    return block
+  })
+}
+
+export declare namespace parseBlocks {
+  /** Indexed rows and requested daily observations. */
+  type Options = {
+    /** Rows containing the requested boundaries. */
+    rows: readonly Row[]
+    /** Observation timestamps represented by the supplied boundary rows. */
+    timestamps: readonly string[]
+  }
+}
+
+type Row = {
+  kind?: unknown
+  num?: unknown
+  requested_at?: unknown
+  timestamp?: unknown
+}
+
+/** Thrown when no indexed block exists for a requested observation. */
+export class IndexedBlockNotFoundError extends Error {
+  override name = 'EarnSharePrices.IndexedBlockNotFoundError'
+
+  constructor(timestamp: string) {
+    super(`No indexed block exists at or before ${timestamp}.`)
+  }
+}
+
+/** Thrown when the indexer has not reached a requested observation. */
+export class IndexedCoverageError extends Error {
+  override name = 'EarnSharePrices.IndexedCoverageError'
+
+  constructor(timestamp: string) {
+    super(`Indexed history does not yet cover ${timestamp}.`)
+  }
+}
+
+/** Thrown when TIDX returns malformed historical share-price data. */
+export class MalformedResponseError extends Error {
+  override name = 'EarnSharePrices.MalformedResponseError'
+
+  constructor(message: string) {
+    super(message)
+  }
+}
+
+/** Thrown when a TIDX request fails before historical rows can be decoded. */
+export class TidxRequestError extends Error {
+  override name = 'EarnSharePrices.TidxRequestError'
+
+  constructor(cause: unknown) {
+    super('TIDX could not resolve historical share-price blocks.', { cause })
+  }
+}
+
+/** Thrown when one whole share cannot be represented as a `uint256`. */
+export class UnsupportedShareDecimalsError extends Error {
+  override name = 'EarnSharePrices.UnsupportedShareDecimalsError'
+
+  constructor(decimals: number) {
+    super(`Share tokens with ${decimals} decimals cannot represent one whole share as a uint256.`)
+  }
+}

package/src/internal/EarnVaults.test.ts

@@ -81,6 +81,27 @@ describe('classifyEngineType', () => {
   })
 })
 
+describe('isReusableWhitelistPolicy', () => {
+  test('accepts only simple whitelists with a live administrator', () => {
+    expect([
+      EarnVaults.isReusableWhitelistPolicy(0, '0x0000000000000000000000000000000000000001'),
+      EarnVaults.isReusableWhitelistPolicy(0, '0x0000000000000000000000000000000000000000'),
+      EarnVaults.isReusableWhitelistPolicy(1, '0x0000000000000000000000000000000000000001'),
+    ]).toStrictEqual([true, false, false])
+  })
+})
+
+describe('isExitSafeCompoundPolicy', () => {
+  test('requires open senders and one nonzero recipient policy', () => {
+    expect([
+      EarnVaults.isExitSafeCompoundPolicy(1n, 3n, 3n),
+      EarnVaults.isExitSafeCompoundPolicy(2n, 3n, 3n),
+      EarnVaults.isExitSafeCompoundPolicy(1n, 0n, 0n),
+      EarnVaults.isExitSafeCompoundPolicy(1n, 3n, 4n),
+    ]).toStrictEqual([true, false, false, false])
+  })
+})
+
 describe('resolve', () => {
   test.runIf(Runtime.get().mode === 'testnet')(
     'reads the current Moderato Earn v1 vault',

package/src/internal/EarnVaults.ts

@@ -5,6 +5,7 @@ import {
   ContractFunctionZeroDataError,
   isAddressEqual,
   parseAbi,
+  zeroAddress,
 } from 'viem'
 import type { Address, Chain } from 'viem'
 import { Abis, Addresses } from 'viem/tempo'
@@ -157,7 +158,7 @@ export namespace schema {
       ),
       vaultAddress: Schema.Address.check(
         z.describe('Earn vault contract address.'),
-        z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
+        z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
       ),
     })
     .check(z.describe('Onchain identity of an Earn vault.'))
@@ -167,7 +168,7 @@ export namespace schema {
     .strictObject({
       chainId: Schema.ChainId.check(
         z.describe('Private Zone chain id.'),
-        z.meta({ examples: [1424310003] }),
+        z.meta({ examples: [421700001] }),
       ),
       deploymentBlock: z
         .number()
@@ -175,11 +176,11 @@ export namespace schema {
           z.int(),
           z.nonnegative(),
           z.describe('Parent-chain block that deployed the Earn router.'),
-          z.meta({ examples: [31730087] }),
+          z.meta({ examples: [35822949] }),
         ),
       earnRouter: Schema.Address.check(
         z.describe('Parent-chain router for this Zone and Earn vault.'),
-        z.meta({ examples: ['0xebedc74ffeead186acc6cac05eb82fb9e093a7c7'] }),
+        z.meta({ examples: ['0x8117e0ba6239b9695f780deb010f72a2fa4bdfb6'] }),
       ),
     })
     .check(z.describe('Curated Earn route through one private Zone.'))
@@ -239,7 +240,7 @@ export namespace schema {
       state,
       vaultAddress: Schema.Address.check(
         z.describe('Earn vault contract address.'),
-        z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
+        z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
       ),
     })
     .check(z.describe('Live state resolved from an Earn vault.'))
@@ -791,25 +792,30 @@ async function readAccess(
   const existing = flights.get(transferPolicyId)
   if (existing) return existing
   const pending = (async () => {
-    const [senderPolicyId, recipientPolicyId, mintRecipientPolicyId] = await client.readContract({
+    const [policyType, administrator] = await client.readContract({
       abi: Abis.tip403Registry,
       address: Addresses.tip403Registry,
       args: [transferPolicyId],
-      functionName: 'compoundPolicyData',
+      functionName: 'policyData',
     })
-    if (
-      senderPolicyId === 0n ||
-      recipientPolicyId === 0n ||
-      mintRecipientPolicyId === 0n ||
-      senderPolicyId !== 1n ||
-      recipientPolicyId !== mintRecipientPolicyId
-    )
+    const supported = await (async () => {
+      if (policyType === 0) return isReusableWhitelistPolicy(policyType, administrator)
+      if (policyType !== 2) return false
+      const [senderPolicyId, recipientPolicyId, mintRecipientPolicyId] = await client.readContract({
+        abi: Abis.tip403Registry,
+        address: Addresses.tip403Registry,
+        args: [transferPolicyId],
+        functionName: 'compoundPolicyData',
+      })
+      return isExitSafeCompoundPolicy(senderPolicyId, recipientPolicyId, mintRecipientPolicyId)
+    })()
+    if (!supported)
       throw new VerificationError({
         issues: [
           {
             actual: transferPolicyId.toString(),
             code: 'policy-unsupported',
-            message: 'Share token does not use a supported exit-safe compound policy.',
+            message: 'Share token does not use a supported allowlist policy.',
           },
         ],
         snapshot: {},
@@ -826,6 +832,22 @@ async function readAccess(
   }
 }
 
+/** Whether TIP-403 policy metadata identifies a reusable simple whitelist. */
+export function isReusableWhitelistPolicy(policyType: number, administrator: Address): boolean {
+  return policyType === 0 && !isAddressEqual(administrator, zeroAddress)
+}
+
+/** Whether compound TIP-403 metadata preserves unrestricted exits and one recipient allowlist. */
+export function isExitSafeCompoundPolicy(
+  senderPolicyId: bigint,
+  recipientPolicyId: bigint,
+  mintRecipientPolicyId: bigint,
+): boolean {
+  return (
+    senderPolicyId === 1n && recipientPolicyId !== 0n && recipientPolicyId === mintRecipientPolicyId
+  )
+}
+
 async function readVaultBindings(client: Client, vaultAddress: Address): Promise<VaultBindings> {
   const vault = await client.earn.getVault({ vault: vaultAddress })
   return {

package/src/internal/Email.ts

@@ -0,0 +1,54 @@
+import type { Context, Hono } from 'hono'
+
+const registry = new WeakMap<Hono<any, any>, Sender>()
+
+/** Transactional email sender shared by authentication and route groups. */
+export type Sender = {
+  /** Console URL embedded in email links. Defaults to the hosted console. */
+  consoleUrl?: string | undefined
+  /** Sender address for transactional emails. */
+  from: string
+  /** Sends one message. */
+  send: (message: Message) => Promise<unknown>
+}
+
+/** One transactional email message. */
+export type Message = {
+  /** Sender address. */
+  from: string
+  /** HTML body. */
+  html?: string | undefined
+  /** Subject line. */
+  subject: string
+  /** Plain-text body. */
+  text: string
+  /** Recipient address. */
+  to: string
+}
+
+/** Hono environment variables for transactional email delivery. */
+export type Variables = {
+  /** Transactional email sender; undefined when dispatch is disabled. */
+  email: Sender | undefined
+}
+
+/** Attaches a legacy group-level sender for `App.create` to collect on mount. */
+export function attach<const app extends Hono<any, any>>(
+  app: app,
+  sender: Sender | undefined,
+): app {
+  if (sender) registry.set(app, sender)
+  return app
+}
+
+/** Returns the app's transactional email sender, when configured. */
+export function get<environment extends { Variables: Variables }>(
+  c: Context<environment>,
+): Sender | undefined {
+  return c.get('email')
+}
+
+/** Returns a group-level sender attached for backward compatibility. */
+export function read(app: Hono<any, any>): Sender | undefined {
+  return registry.get(app)
+}

package/src/internal/Idempotency.test.ts

@@ -49,9 +49,9 @@ describe('create', () => {
       requests.claim({ identity: { ...identity, inputHash: `0x${'22'.repeat(32)}` }, state }),
     ).resolves.toEqual({ type: 'mismatch' })
 
-    await requests.complete({ identity, response: { id: 'ftr_test' }, state, token: claimed.token })
+    await requests.complete({ identity, response: { id: 'rtr_test' }, state, token: claimed.token })
     await expect(requests.claim({ identity, state })).resolves.toEqual({
-      response: { id: 'ftr_test' },
+      response: { id: 'rtr_test' },
       type: 'replay',
     })
   })

package/src/internal/Log.test-d.ts

@@ -1,10 +1,10 @@
-import type * as FundingProvider from './funding/Provider.js'
+import type * as RoutesProvider from './routes/Provider.js'
 import type * as Log from './Log.js'
 
-test('accepts deployment-supplied funding provider identifiers', () => {
-  const provider = null as never as FundingProvider.ProviderId
-  const id: Log.FundingProviderAttempt['id'] = provider
-  const provider_roundTrip: FundingProvider.ProviderId = id
+test('accepts deployment-supplied route provider identifiers', () => {
+  const provider = null as never as RoutesProvider.ProviderId
+  const id: Log.RoutesProviderAttempt['id'] = provider
+  const provider_roundTrip: RoutesProvider.ProviderId = id
   void provider_roundTrip
 
   const attempt = {
@@ -12,15 +12,16 @@ test('accepts deployment-supplied funding provider identifiers', () => {
     id: 'relay',
     operation: 'getQuote',
     outcome: 'available',
-  } satisfies Log.FundingProviderAttempt
+  } satisfies Log.RoutesProviderAttempt
   void attempt
 
-  const custom: Log.FundingProviderAttempt['id'] = 'custom-bridge'
+  const custom: Log.RoutesProviderAttempt['id'] = 'custom-bridge'
   void custom
 })
 
 test('bounds sponsorship diagnostics', () => {
   const reasons = [
+    'attribution_id_invalid',
     'api_key_forbidden',
     'api_key_required',
     'billing_past_due',
@@ -29,6 +30,8 @@ test('bounds sponsorship diagnostics', () => {
     'fee_token_unsupported',
     'internal_error',
     'production_api_key_required',
+    'project_id_invalid',
+    'project_id_required',
     'spend_limit_exceeded',
     'tx_fee_limit_exceeded',
   ] as const satisfies readonly Log.SponsorshipReason[]