tapimo 0.5.2 → 0.6.0

package/src/apps/data/routes/valuation.ts

@@ -0,0 +1,423 @@
+import { Hono, type Context } from 'hono'
+import { Value as core_Value } from 'ox'
+import { BaseError, ContractFunctionRevertedError, ContractFunctionZeroDataError } from 'viem'
+import { Actions } from 'viem/tempo'
+import * as z from 'zod/mini'
+
+import type * as App from '../../../App.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as Cache from '../../../internal/Cache.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Response from '../../../internal/Response.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as Store from '../../../internal/Store.js'
+import * as Timing from '../../../internal/Timing.js'
+import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
+import * as FxOracle from '../FxOracle.js'
+
+// How many balance reads to fan out per batch. Concurrent reads in one
+// macrotask collapse into a single deployless multicall; small chunks keep
+// each call under the Tempo RPC's per-call size limit.
+const tokenReadChunkSize = 20
+
+/** Zod schemas owned by the valuation handlers. */
+export namespace schema {
+  /** A holding's nominal value in the requested denomination. */
+  export const Value = z
+    .object({
+      amount: z
+        .string()
+        .check(
+          z.regex(/^\d+(\.\d+)?$/),
+          z.describe('The holding’s nominal value, as a decimal string in `currency`.'),
+          z.meta({ examples: ['1.50'] }),
+        ),
+      currency: z
+        .string()
+        .check(
+          z.describe('The denomination currency of this value.'),
+          z.meta({ examples: ['USD'] }),
+        ),
+    })
+    .check(z.describe('The holding’s nominal value in the requested denomination.'))
+
+  /** Rate provenance for a converted valuation. */
+  export const Pricing = z
+    .object({
+      asOf: z
+        .string()
+        .check(
+          z.describe('Publication date of the rate set used for conversion.'),
+          z.meta({ examples: ['2026-07-20'] }),
+        ),
+      basis: z
+        .literal('nominal')
+        .check(
+          z.describe('Valuation basis: one token unit counts as one unit of its display currency.'),
+          z.meta({ examples: ['nominal'] }),
+        ),
+      source: z
+        .string()
+        .check(
+          z.describe('FX rate oracle that supplied the conversion rates.'),
+          z.meta({ examples: ['ecb'] }),
+        ),
+    })
+    .check(z.describe('Rate provenance for a converted valuation.'))
+
+  /** Schemas for the getAddressValuation operation. */
+  export namespace getAddressValuation {
+    /** Path parameters for address valuation requests. */
+    export const Params = z
+      .object({
+        address: Schema.Address.check(
+          z.describe('The account address whose holdings you want to value.'),
+        ),
+      })
+      .check(z.describe('Path parameters for valuing an account’s verified holdings.'))
+
+    /** Query parameters for address valuation requests. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        denomination: Schema.Denomination,
+      })
+      .check(z.describe('Query parameters for valuing an account’s verified holdings.'))
+
+    /** The nominal valuation of an account's verified holdings. */
+    export const Response = z
+      .object({
+        address: Schema.Address.check(z.describe('The account address this valuation covers.')),
+        amount: z
+          .string()
+          .check(
+            z.regex(/^\d+(\.\d+)?$/),
+            z.describe(
+              'The total value of the account’s verified holdings, as a decimal string in `currency`.',
+            ),
+            z.meta({ examples: ['160.50'] }),
+          ),
+        currency: z
+          .string()
+          .check(
+            z.describe('The denomination currency of `amount`.'),
+            z.meta({ examples: ['USD'] }),
+          ),
+        id: z
+          .string()
+          .check(
+            z.describe('A stable resource ID for this valuation, equal to the account address.'),
+            z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
+          ),
+        pricing: z
+          .nullable(Pricing)
+          .check(
+            z.describe(
+              'Rate provenance, or `null` when every valued holding was already denominated in `currency`.',
+            ),
+          ),
+        unpriced: z
+          .array(z.string())
+          .check(
+            z.describe(
+              'Display currencies excluded from `amount` because the FX oracle has no rate for them.',
+            ),
+            z.meta({ examples: [['BTC']] }),
+          ),
+      })
+      .check(z.describe('The nominal valuation of an account’s verified token holdings.'))
+  }
+}
+
+/**
+ * Creates address-scoped valuation handlers, mounted under the `/addresses`
+ * composer. Exposes `GET /:address/valuation`, the holdings valuation.
+ */
+export function addresses(options: addresses.Options = {}) {
+  const oracle = options.fx?.oracle ?? FxOracle.ecb()
+  return new Hono<App.Environment>().get(
+    '/v1/addresses/:address/valuation',
+    Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+    OpenApi.validate('param', schema.getAddressValuation.Params, {
+      code: 'address_invalid',
+      message: 'Invalid account address',
+    }),
+    OpenApi.validate('query', schema.getAddressValuation.Query, {
+      code: 'query_invalid',
+      message: 'Invalid query parameters',
+    }),
+    OpenApi.describeRoute({
+      description:
+        'Values every verified TIP-20 token an account holds as one unit of its display currency, converts each currency into the requested denomination using the configured FX rates, and returns the total.',
+      operationId: 'getAddressValuation',
+      responses: OpenApi.responses({
+        errors: { 502: 'Could not read balances or exchange rates from an upstream service.' },
+        success: {
+          description: 'The valuation of this account’s verified holdings.',
+          schema: schema.getAddressValuation.Response,
+        },
+      }),
+      summary: 'Get address valuation',
+      tags: ['Balances'],
+    }),
+    Cache.response<App.Environment>({
+      cacheControl: Cache.policies.noStore,
+      name: 'tempo-api:addresses:v1',
+      key: (c) => Cache.urlKey(c, schema.getAddressValuation.Query),
+    }),
+    async (c) => {
+      if (Auth.narrowAccess) return Auth.paidAccessError(c)
+      if (OpenApi.narrowValidation)
+        return OpenApi.validationError(c, {
+          code: 'address_invalid',
+          message: 'Invalid request parameters',
+        })
+      if (OpenApi.narrowValidation)
+        return OpenApi.validationError(c, {
+          code: 'query_invalid',
+          message: 'Invalid request parameters',
+        })
+
+      const { address } = c.req.valid('param')
+      const query = c.req.valid('query')
+
+      try {
+        const valuation = await getAddressValuation(c, {
+          address,
+          chainId: query.chainId ?? c.get('chainId'),
+          denomination: query.denomination ?? 'USD',
+          oracle,
+        })
+        return c.json(Response.validated(schema.getAddressValuation.Response, valuation), 200)
+      } catch (cause) {
+        if (cause instanceof UnsupportedDenominationError)
+          return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+        return Response.upstream(c, cause)
+      }
+    },
+  )
+}
+
+export declare namespace addresses {
+  /** Options for the address-scoped valuation handlers. */
+  type Options = {
+    /** FX configuration backing currency conversion. */
+    fx?: Fx | undefined
+  }
+
+  /** FX configuration for valuation handlers. */
+  type Fx = {
+    /** FX rate oracle. Defaults to `FxOracle.ecb()`. */
+    oracle?: FxOracle.Oracle | undefined
+  }
+}
+
+async function getAddressValuation(
+  c: Context<App.Environment>,
+  options: getAddressValuation.Options,
+) {
+  const { address, chainId, denomination, oracle } = options
+  const [set, ratesCause] = await rateSet(c, oracle).then(
+    (set) => [set, undefined] as const,
+    (cause: unknown) => [undefined, cause] as const,
+  )
+  if (set && denomination !== set.base && set.rates[denomination] === undefined)
+    throw new UnsupportedDenominationError(denomination, oracle.name)
+  const snapshot = await VerifiedTokens.snapshot(c, chainId)
+
+  type Holding = { amount: bigint; token: VerifiedTokens.Snapshot['list'][number] }
+  const holdings = await Timing.time(c, 'valuation_balances', async () => {
+    const client = c.get('getClient')(chainId)
+    if (snapshot.list.length === 0) return []
+    // Pin every chunk to one chain-state snapshot.
+    const blockNumber = await client.getBlockNumber({ cacheTime: 0 })
+    const rows: Holding[] = []
+    for (let index = 0; index < snapshot.list.length; index += tokenReadChunkSize) {
+      const group = snapshot.list.slice(index, index + tokenReadChunkSize)
+      // Concurrent reads enter viem's shared batch window and become one
+      // deployless multicall. A failed read fails the request rather than
+      // serving a partial total.
+      const results = await Promise.all(
+        group.map(async (token) => {
+          try {
+            const { amount } = await Actions.token.getBalance(client, {
+              account: address,
+              blockNumber,
+              decimals: token.decimals,
+              token: token.address,
+            })
+            return amount === 0n ? undefined : { amount, token }
+          } catch (error) {
+            // A verified token that is undeployed (zero data) or uninitialized
+            // on this chain cannot be held; count it as an empty holding
+            // rather than failing the valuation.
+            const empty =
+              error instanceof BaseError &&
+              error.walk(
+                (cause) =>
+                  cause instanceof ContractFunctionZeroDataError ||
+                  (cause instanceof ContractFunctionRevertedError &&
+                    cause.data?.errorName === 'Uninitialized'),
+              )
+            if (empty) return undefined
+            throw error
+          }
+        }),
+      )
+      rows.push(...results.filter((row) => row !== undefined))
+    }
+    return rows
+  })
+
+  // Aggregate holdings by display currency at a shared 18-dp scale so tokens
+  // with different decimals sum exactly.
+  type Group = { currency: string; sum: bigint }
+  const groups = new Map<string, Group>()
+  for (const { amount, token } of holdings) {
+    const group = groups.get(token.currency.toLowerCase()) ?? { currency: token.currency, sum: 0n }
+    group.sum +=
+      token.decimals <= FxOracle.precision
+        ? amount * 10n ** BigInt(FxOracle.precision - token.decimals)
+        : amount / 10n ** BigInt(token.decimals - FxOracle.precision)
+    groups.set(token.currency.toLowerCase(), group)
+  }
+
+  let total = 0n
+  const unpriced: string[] = []
+  let pricing: z.output<typeof schema.Pricing> | null = null
+
+  const pending = [...groups.values()].filter(
+    (group) => group.currency.toUpperCase() !== denomination,
+  )
+  for (const group of groups.values())
+    if (group.currency.toUpperCase() === denomination) total += group.sum
+
+  if (pending.length > 0) {
+    if (!set) throw ratesCause
+    for (const group of pending) {
+      const rate = FxOracle.rate(set, { from: group.currency.toUpperCase(), to: denomination })
+      if (rate === undefined) unpriced.push(group.currency)
+      else total += (group.sum * rate) / 10n ** BigInt(FxOracle.precision)
+    }
+    pricing = { asOf: set.asOf, basis: 'nominal', source: oracle.name }
+  }
+  unpriced.sort()
+
+  return {
+    address,
+    // Floor to 6 dp, the TIP-20 native precision; same-currency sums stay exact.
+    amount: core_Value.format(total / 10n ** BigInt(FxOracle.precision - 6), 6),
+    currency: denomination,
+    id: address,
+    pricing,
+    unpriced,
+  }
+}
+
+declare namespace getAddressValuation {
+  type Options = {
+    address: z.output<typeof Schema.Address>
+    chainId: z.output<typeof Schema.ChainId>
+    /** Currency the valuation is denominated in (uppercase). */
+    denomination: string
+    /** FX rate oracle backing currency conversion. */
+    oracle: FxOracle.Oracle
+  }
+}
+
+/** Loads the oracle's rate set through the request's store cache. */
+export function rateSet(c: Context<App.Environment>, oracle: FxOracle.Oracle) {
+  return Timing.time(c, 'valuation_rates', () =>
+    Store.memoize(() => oracle.rates(), {
+      key: `fx:v1:${oracle.name}`,
+      store: c.get('store'),
+      ttl: oracle.ttl,
+    }),
+  )
+}
+
+/**
+ * Loads rates best-effort to validate the denomination and value a page.
+ * Returns `undefined` when unavailable or unnecessary; a known unsupported denomination still throws.
+ */
+export async function ratesFor(
+  c: Context<App.Environment>,
+  options: ratesFor.Options,
+): Promise<FxOracle.RateSet | undefined> {
+  const { denomination, oracle } = options
+  const rates = await rateSet(c, oracle).catch(() => undefined)
+  if (!rates) return undefined
+  if (denomination !== rates.base && rates.rates[denomination] === undefined)
+    throw new UnsupportedDenominationError(denomination, oracle.name)
+  const conversion = [...options.currencies].some(
+    (currency) => currency.toUpperCase() !== denomination,
+  )
+  if (!conversion) return undefined
+  return rates
+}
+
+export declare namespace ratesFor {
+  /** Options for loading a page's valuation rates. */
+  type Options = {
+    /** Display currencies of the curated holdings appearing on the page. */
+    currencies: Iterable<string>
+    /** Currency values are denominated in (uppercase). */
+    denomination: string
+    /** FX rate oracle backing currency conversion. */
+    oracle: FxOracle.Oracle
+  }
+}
+
+/** Builds the `pricing` provenance block for a consulted rate set. */
+export function pricing(rates: FxOracle.RateSet, oracle: FxOracle.Oracle) {
+  return { asOf: rates.asOf, basis: 'nominal' as const, source: oracle.name }
+}
+
+/**
+ * Values one holding in the requested denomination via its curated display
+ * currency. Returns `null` when the token is unverified, its currency has no
+ * rate, or the rate set is unavailable.
+ */
+export function valuationFor(options: valuationFor.Options) {
+  const { amount, denomination, rates, token } = options
+  if (!token) return null
+  const rate = (() => {
+    if (token.currency.toUpperCase() === denomination) return 10n ** BigInt(FxOracle.precision)
+    if (!rates) return undefined
+    return FxOracle.rate(rates, { from: token.currency.toUpperCase(), to: denomination })
+  })()
+  if (rate === undefined) return null
+
+  // Normalize to the shared 18-dp scale, convert, then floor to 6 dp.
+  const scaled =
+    token.decimals <= FxOracle.precision
+      ? amount * 10n ** BigInt(FxOracle.precision - token.decimals)
+      : amount / 10n ** BigInt(token.decimals - FxOracle.precision)
+  const value = (scaled * rate) / 10n ** BigInt(FxOracle.precision)
+  return {
+    amount: core_Value.format(value / 10n ** BigInt(FxOracle.precision - 6), 6),
+    currency: denomination,
+  }
+}
+
+export declare namespace valuationFor {
+  /** Options for valuing one holding. */
+  type Options = {
+    /** Holding amount in the token's base units. */
+    amount: bigint
+    /** Currency the value is denominated in (uppercase). */
+    denomination: string
+    /** Oracle rate set, when loaded. */
+    rates: FxOracle.RateSet | undefined
+    /** Display currency and decimal scale backing the holding, when known. */
+    token: Pick<VerifiedTokens.Snapshot['list'][number], 'currency' | 'decimals'> | undefined
+  }
+}
+
+/** Thrown when the requested denomination is not priced by the FX oracle. */
+export class UnsupportedDenominationError extends Error {
+  override name = 'Valuation.UnsupportedDenominationError'
+  constructor(denomination: string, oracle: string) {
+    super(`Denomination "${denomination}" is not priced by the "${oracle}" FX oracle`)
+  }
+}

package/src/apps/data/routes/verified-tokens.ts

@@ -21,6 +21,7 @@ export namespace schema {
         z.describe(
           'The currency label for this token, such as `USD` for USD-denominated stablecoins.',
         ),
+        z.meta({ examples: ['USD'] }),
       ),
     decimals: z
       .number()
@@ -31,16 +32,27 @@ export namespace schema {
         z.describe(
           'The number of decimal places the token uses; Tempo stablecoins typically use 6.',
         ),
+        z.meta({ examples: [6] }),
       ),
     logoUri: z
       .optional(z.url({ protocol: /^https$/ }))
-      .check(z.describe('The curated HTTPS URL for this token’s logo image, when one is set.')),
-    name: z.string().check(z.minLength(1), z.describe('The token’s human-readable name.')),
+      .check(
+        z.describe('The curated HTTPS URL for this token’s logo image, when one is set.'),
+        z.meta({ examples: ['https://assets.tempo.xyz/icons/usdc.svg'] }),
+      ),
+    name: z
+      .string()
+      .check(
+        z.minLength(1),
+        z.describe('The token’s human-readable name.'),
+        z.meta({ examples: ['USD Coin'] }),
+      ),
     symbol: z
       .string()
       .check(
         z.minLength(1),
         z.describe('The short ticker symbol wallets and apps show for this token.'),
+        z.meta({ examples: ['USDC'] }),
       ),
   }
 

package/src/apps/data/routes/webhooks.test.ts

@@ -1,4 +1,5 @@
 import { type Db, Webhooks as Core } from 'tapimo'
+import * as z from 'zod/mini'
 
 import * as Tidx from '../../../internal/Tidx.js'
 import * as Viem from '../../../internal/Viem.js'
@@ -8,6 +9,9 @@ import * as Runtime from '../../../../test/runtime.js'
 import * as Tempo from '../../../../test/Tempo.js'
 import * as Webhooks from './webhooks.js'
 
+/** Humanized transaction payload delivered by transaction webhooks. */
+type TransactionEvent = z.output<typeof Webhooks.schema.TransactionEvent>
+
 /** API key with both webhook scopes, owned by `org_test`. */
 const writer = {
   id: 'key_writer',
@@ -336,23 +340,24 @@ describe('subscription limits', () => {
   test('rejects creation past the configured per-owner cap with 403 limit_exceeded', async () => {
     const app = TestApp.client({
       auth: { keys: [writer, other] },
-      webhook: { maxPerOwner: 2 },
+      webhook: { maxPerOwner: 2, supportedChainIds: [4217, 42431] },
     })
+    const request = { chainId: 4217, ...validBody }
 
     // Fill the writer's quota.
     for (let i = 0; i < 2; i++) {
-      const ok = await app.v1.webhooks.$post({ json: validBody }, as(writer))
+      const ok = await app.v1.webhooks.$post({ json: request }, as(writer))
       expect(ok.status).toMatchInlineSnapshot(`200`)
     }
 
     // The third create is over the cap.
-    const over = await app.v1.webhooks.$post({ json: validBody }, as(writer))
+    const over = await app.v1.webhooks.$post({ json: request }, as(writer))
     expect(over.status).toMatchInlineSnapshot(`403`)
     const body = (await over.json()) as { error?: { code?: string } }
     expect(body.error?.code).toMatchInlineSnapshot(`"limit_exceeded"`)
 
     // The cap is per-owner: a different org is unaffected.
-    const otherOrg = await app.v1.webhooks.$post({ json: validBody }, as(other))
+    const otherOrg = await app.v1.webhooks.$post({ json: request }, as(other))
     expect(otherOrg.status).toMatchInlineSnapshot(`200`)
   })
 })
@@ -671,6 +676,36 @@ describe('slack destination', () => {
     expect(response.status).toMatchInlineSnapshot(`400`)
     expect(body.error?.code).toMatchInlineSnapshot(`"url_invalid"`)
   })
+
+  test('requires recreation before changing a provider destination to a URL', async () => {
+    const app = client([writer])
+    const created = await app.v1.webhooks.$post(
+      {
+        json: {
+          destination: {
+            type: 'slack',
+            url: 'https://hooks.slack.com/services/T000/B000/xxxx',
+          },
+          eventType: 'token:transfer',
+        },
+      },
+      as(writer),
+    )
+    const { id } = await TestApp.json(created, Webhooks.schema.createWebhook.Response)
+
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].$patch(
+      {
+        json: { destination: { type: 'url', url: 'https://example.com/webhooks' } },
+        param: { id },
+      },
+      as(writer),
+    )
+
+    expect(response.status).toBe(400)
+    expect(await response.json()).toMatchObject({
+      error: { code: 'destination_transition_invalid' },
+    })
+  })
 })
 
 describe('betterstack destination', () => {
@@ -1729,11 +1764,18 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
     })
 
     expect(result.scanned).toMatchInlineSnapshot(`1`)
-    const tx = dispatched[0]?.envelope.data as { hash: string; sender: string } | undefined
+    const tx = dispatched[0]?.envelope.data as TransactionEvent | undefined
     expect(tx?.hash).toMatchInlineSnapshot(
       `"0x3d24a706cc2f6f4c96620bef1f61ddb23040ff77c22c8db42918c7c424bbf9d3"`,
     )
     expect(tx?.sender).toBe(windowSender)
+    if (tx?.meta.rpc.feeToken) {
+      expect(tx.feeToken?.address).toBe(tx.meta.rpc.feeToken)
+      expect(typeof tx.feeToken?.currency).toBe('string')
+      expect(typeof tx.feeToken?.decimals).toBe('number')
+      expect(typeof tx.feeToken?.name).toBe('string')
+      expect(typeof tx.feeToken?.symbol).toBe('string')
+    } else expect(tx?.feeToken).toBeUndefined()
   })
 
   test('transaction:included matches exact empty calldata through the poller', async () => {
@@ -1821,13 +1863,19 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
     })
 
     expect(result.scanned).toMatchInlineSnapshot(`1`)
-    const data = dispatched[0]?.envelope.data as
-      | { hash: string; meta?: { receipt?: { status: string; transactionHash: string } } }
-      | undefined
+    const data = dispatched[0]?.envelope.data as TransactionEvent | undefined
     // The receipt is embedded under `meta.receipt`, matching the read endpoint's
     // `include=receipt` shape, and refers to the same transaction.
     expect(data?.meta?.receipt?.status).toMatchInlineSnapshot(`"success"`)
     expect(data?.meta?.receipt?.transactionHash).toBe(data?.hash)
+    const receipt = data?.meta.receipt
+    if (receipt?.meta.rpc.feeToken) {
+      expect(receipt.feeToken?.address).toBe(receipt.meta.rpc.feeToken)
+      expect(typeof receipt.feeToken?.currency).toBe('string')
+      expect(typeof receipt.feeToken?.decimals).toBe('number')
+      expect(typeof receipt.feeToken?.name).toBe('string')
+      expect(typeof receipt.feeToken?.symbol).toBe('string')
+    } else expect(receipt?.feeToken).toBeUndefined()
   })
 
   // End-to-end through the *default* transport: `poll` with no injected