tapimo 0.7.2 → 0.9.0

package/src/analytics/Analytics.ts

@@ -359,9 +359,13 @@ export class ConfigError extends Error {
 
 /** Failed ClickHouse insert (non-2xx HTTP response). */
 export class InsertError extends Error {
+  /** HTTP response status returned by ClickHouse. */
+  status: number
+
   constructor(status: number, body: string) {
     super(`ClickHouse insert failed with status ${status}: ${body.slice(0, 500)}`)
     this.name = 'Analytics.InsertError'
+    this.status = status
   }
 }
 

package/src/apps/composition.test.ts

@@ -1,5 +1,5 @@
 import { App, Store } from 'tapimo'
-import { data, management, mpp, relay } from 'tapimo/apps'
+import { data, funding, management, mpp, relay } from 'tapimo/apps'
 import { Hono } from 'hono'
 import { describeRoute } from 'hono-openapi'
 import * as TestApp from '../../test/App.js'
@@ -14,8 +14,16 @@ async function document(app: { request: (path: string) => Promise<Response> | Re
   const res = await app.request('/openapi.json')
   return (await res.json()) as {
     components: { securitySchemes: Record<string, unknown> }
-    paths: Record<string, unknown>
-    tags: readonly { description: string; name: string }[]
+    paths: Record<
+      string,
+      Partial<Record<'get' | 'post', { operationId: string; tags?: readonly string[] | undefined }>>
+    >
+    tags: readonly {
+      description: string
+      name: string
+      'x-displayName'?: string | undefined
+      'x-pagePath'?: string | undefined
+    }[]
     webhooks?: Record<string, unknown> | undefined
     'x-tagGroups'?: readonly { name: string; tags: readonly string[] }[] | undefined
   }
@@ -146,10 +154,12 @@ describe('data()', () => {
     expect(keys.some((path) => path.startsWith('/v1/blocks'))).toBe(true)
     expect(keys.some((path) => path.startsWith('/v1/orgs'))).toBe(false)
     expect(keys.some((path) => path.startsWith('/v1/me'))).toBe(false)
+    expect(keys.some((path) => path.startsWith('/v1/funding'))).toBe(false)
 
     // The omitted management route resolves to a 404 (never mounted), not a 401.
     const orgs = await app.request('/v1/orgs')
     expect(orgs.status).toBe(404)
+    expect((await app.request('/v1/funding/chains')).status).toBe(404)
   })
 
   test('inherits shared chain context', async () => {
@@ -272,6 +282,123 @@ describe('data()', () => {
   })
 })
 
+describe('funding()', () => {
+  test('mounts the Funding & Bridge API independently', async () => {
+    const group = funding()
+    expectTypeOf(App.funding).toEqualTypeOf<typeof funding>()
+    expectTypeOf(group).toEqualTypeOf<App.FundingApp>()
+    const app = App.create({ auth: false, db: TestApp.database() }).route('/', group)
+    const spec = await document(app)
+
+    expect(
+      Object.keys(spec.paths)
+        .filter((path) => path.startsWith('/v1/funding'))
+        .sort(),
+    ).toEqual(
+      [
+        '/v1/funding/chains',
+        '/v1/funding/deposit-addresses',
+        '/v1/funding/deposit-addresses/{id}',
+        '/v1/funding/deposit-addresses/{id}/reconcile',
+        '/v1/funding/deposits',
+        '/v1/funding/deposits/{id}',
+        '/v1/funding/providers',
+        '/v1/funding/quotes',
+        '/v1/funding/transfers',
+        '/v1/funding/transfers/vault',
+        '/v1/funding/transfers/zone',
+        '/v1/funding/transfers/{id}',
+      ].sort(),
+    )
+    expect(Object.keys(spec.paths).some((path) => path.startsWith('/v1/tokens'))).toBe(false)
+    expect(spec.paths['/webhooks/funding/{providerId}']).toBeUndefined()
+    expect(spec['x-tagGroups']).toEqual([
+      {
+        name: 'Funding & Bridge API',
+        tags: ['Chains', 'Deposit Addresses', 'Providers', 'Quotes', 'Funding Transfers'],
+      },
+    ])
+    expect(
+      Object.values(spec.paths).flatMap((path) =>
+        [path.get, path.post].flatMap((operation) =>
+          operation?.tags?.includes('Deposit Addresses') ? [operation.operationId] : [],
+        ),
+      ),
+    ).toEqual([
+      'createFundingDepositAddress',
+      'reconcileFundingDepositAddress',
+      'getFundingDepositAddress',
+      'getFundingDeposit',
+      'listFundingDeposits',
+    ])
+    expect((await app.request('/v1/tokens')).status).toBe(404)
+  })
+
+  test('keeps data and funding transfers separate with the same display name', async () => {
+    const app = App.create({ auth: false, db: TestApp.database() })
+      .route('/', data())
+      .route('/', funding())
+    const spec = await document(app)
+    const operationTag = (path: string, method: 'get' | 'post') =>
+      (spec.paths[path] as Record<string, { tags?: readonly string[] | undefined } | undefined>)[
+        method
+      ]?.tags
+
+    expect({
+      chains: operationTag('/v1/funding/chains', 'get'),
+      depositAddress: operationTag('/v1/funding/deposit-addresses', 'post'),
+      deposits: operationTag('/v1/funding/deposits', 'get'),
+      providers: operationTag('/v1/funding/providers', 'get'),
+      quotes: operationTag('/v1/funding/quotes', 'get'),
+      tokenTransfers: operationTag('/v1/transfers', 'get'),
+      transfers: operationTag('/v1/funding/transfers', 'get'),
+      vault: operationTag('/v1/funding/transfers/vault', 'post'),
+      zone: operationTag('/v1/funding/transfers/zone', 'post'),
+    }).toEqual({
+      chains: ['Chains'],
+      depositAddress: ['Deposit Addresses'],
+      deposits: ['Deposit Addresses'],
+      providers: ['Providers'],
+      quotes: ['Quotes'],
+      tokenTransfers: ['Transfers'],
+      transfers: ['Funding Transfers'],
+      vault: ['Funding Transfers'],
+      zone: ['Funding Transfers'],
+    })
+
+    const groups = Object.fromEntries(
+      (spec['x-tagGroups'] ?? []).map((group) => [group.name, group.tags]),
+    )
+    expect(groups['Data API']).toContain('Transfers')
+    expect(groups['Data API']).not.toContain('Funding Transfers')
+    expect(groups['Funding & Bridge API']).toContain('Funding Transfers')
+    expect(groups['Funding & Bridge API']).not.toContain('Transfers')
+    expect(spec.tags.filter((tag) => tag.name === 'Transfers')).toHaveLength(1)
+    expect(spec.tags.filter((tag) => tag.name === 'Funding Transfers')).toEqual([
+      {
+        description: 'Inbound funding transfers.',
+        name: 'Funding Transfers',
+        'x-displayName': 'Transfers',
+        'x-pagePath': 'funding/transfers',
+      },
+    ])
+    expect(
+      Object.fromEntries(
+        (groups['Funding & Bridge API'] ?? []).map((name) => {
+          const tag = spec.tags.find((tag) => tag.name === name)
+          return [tag?.['x-displayName'] ?? tag?.name, tag?.['x-pagePath']]
+        }),
+      ),
+    ).toEqual({
+      Chains: 'funding/chains',
+      'Deposit Addresses': 'funding/deposit-addresses',
+      Providers: 'funding/providers',
+      Quotes: 'funding/quotes',
+      Transfers: 'funding/transfers',
+    })
+  })
+})
+
 describe('relay()', () => {
   test('mounts the relay after data() without documenting RPC routes', async () => {
     const composed = App.create({ db: TestApp.database() }).route('/', data()).route('/', relay())

package/src/apps/data/App.test.ts

@@ -386,18 +386,6 @@ describe('zone chain gate', () => {
     expect((await privateApp.request(path)).status).toBe(403)
   })
 
-  test('public chains remain edge-cacheable on a Zone deployment', async () => {
-    const store = Store.memory()
-    const app = TestApp.create({ auth: false, cache: { store }, zones: [zoneOptions(zone)] })
-    const path = '/v1/funding/chains'
-
-    const first = await app.request(path)
-    const second = await app.request(path)
-    expect(first.status).toBe(200)
-    expect(second.status).toBe(200)
-    expect(second.headers.get('cache-control')).toContain('public')
-  })
-
   test('serves anonymous token lists from the edge cache on public chains', async () => {
     const store = Store.memory()
     const app = TestApp.create({ auth: false, cache: { store }, zones: [zoneOptions(zone)] })

package/src/apps/data/App.ts

@@ -25,7 +25,6 @@ import { coingecko } from './routes/coingecko.js'
 import { earn } from './routes/earn.js'
 import { exchanges } from './routes/exchanges.js'
 import { feeAmm } from './routes/fee-amm.js'
-import { funding } from './routes/funding.js'
 import { indexer } from './routes/indexer.js'
 import { receipts } from './routes/receipts.js'
 import { rpc } from './routes/rpc.js'
@@ -217,7 +216,6 @@ export function data(options: data.Options = {}) {
     .route('/', earn_routes)
     .route('/', exchanges({ fx: options.fx }))
     .route('/', feeAmm())
-    .route('/', funding())
     .route('/', indexer_routes)
     .route('/', receipts({ fx: options.fx }))
     .route('/', tokenlist())
@@ -375,13 +373,12 @@ const openapi = {
     { name: 'Earn', description: 'Vaults that earn yield from assets deposited on Tempo.' },
     { name: 'Exchange', description: "Tempo's built-in stablecoin exchange: pairs, swaps, orders, prices." }, // prettier-ignore
     { name: 'Fee AMM', description: 'Pools that convert stablecoins to pay fees.' },
-    {
-      name: 'Funding',
-      description: 'Quote, transfer, and deposit management for funding Tempo from other chains.',
-    },
     { name: 'Tokens', description: 'TIP-20 token details, supply, and holders.' },
     { name: 'Transactions', description: 'Transactions submitted to Tempo, and their receipts.' },
-    { name: 'Transfers', description: 'Token movements from executing transactions.' },
+    {
+      name: 'Transfers',
+      description: 'Token movements from executing transactions.',
+    },
     { name: 'Verified Tokens', description: 'A curated, trusted list of TIP-20 tokens.' },
     { name: 'Webhooks', description: 'Get signed callbacks when onchain events happen.' },
     { name: 'Zones', description: 'Private chain operations anchored to Tempo.' },
@@ -399,7 +396,6 @@ const openapi = {
         'Earn',
         'Exchange',
         'Fee AMM',
-        'Funding',
         'Tokens',
         'Transactions',
         'Transfers',

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

@@ -3,6 +3,7 @@
 import { Schema } from 'tapimo'
 import { FxOracle } from 'tapimo/apps'
 import { Value as core_Value } from 'ox'
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 import { Actions } from 'viem/tempo'
 
 import * as TestApp from '../../../../test/App.js'
@@ -469,3 +470,44 @@ describe('GET /addresses/:address/balances', () => {
     expect(body.meta!.totalCount).toBeGreaterThanOrEqual(body.data.length)
   })
 })
+
+describe('GET /v1/addresses/:address/balances/:token', () => {
+  test('returns one live balance without indexed holder discovery', async () => {
+    const client = app()
+    const holder = await holderWithBalance
+    const response = await client.v1.addresses[':address'].balances[':token'].$get(
+      {
+        param: { address: holder, token: TestApp.tokenWithHolders },
+        query: {},
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalance.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.id).toBe(TestApp.tokenWithHolders)
+    expect(body.token.address).toBe(TestApp.tokenWithHolders)
+    expect(body.amount).toMatch(/^\d+$/)
+    expect(core_Value.from(body.formatted, body.decimals)).toBe(BigInt(body.amount))
+    expect(body.valuation).toEqual({ amount: body.formatted, currency: 'USD' })
+  })
+
+  test('returns zero for a token the account does not hold', async () => {
+    const client = app()
+    const response = await client.v1.addresses[':address'].balances[':token'].$get(
+      {
+        param: {
+          address: privateKeyToAccount(generatePrivateKey()).address,
+          token: TestApp.tokenWithHolders,
+        },
+        query: {},
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalance.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.amount).toBe('0')
+    expect(body.formatted).toBe('0')
+  })
+})

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

@@ -181,102 +181,235 @@ export namespace schema {
       })
       .check(z.describe('A page of TIP-20 token balances held by this account.'))
   }
+
+  /** Schemas for the getAddressBalance operation. */
+  export namespace getAddressBalance {
+    /** Path parameters for a single address balance request. */
+    export const Params = z
+      .object({
+        address: Schema.Address.check(
+          z.describe('The account address whose token balance you want to read.'),
+        ),
+        token: Schema.TokenAddress.check(z.describe('The TIP-20 token contract address.')),
+      })
+      .check(z.describe('Path parameters for reading one account token balance.'))
+
+    /** Query parameters for a single address balance request. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        'valuation.currency': Schema.Denomination,
+      })
+      .check(z.describe('Query parameters for reading one account token balance.'))
+
+    /** A single TIP-20 token balance held by an address. */
+    export const Response = getAddressBalances.Balance.check(
+      z.describe('One TIP-20 token balance held by this account.'),
+    )
+  }
 }
 
 /**
  * Creates address-scoped balance handlers, mounted under the `/addresses`
- * composer. Exposes `GET /:address/balances`, the held-balance page.
+ * composer. Exposes the held-balance page and individual token balances.
  */
 export function addresses(options: addresses.Options = {}) {
   const oracle = options.fx?.oracle ?? FxOracle.ecb()
-  return new Hono<App.Environment>().get(
-    '/v1/addresses/:address/balances',
-    Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
-    OpenApi.validate('param', schema.getAddressBalances.Params, {
-      code: 'address_invalid',
-      message: 'Invalid account address',
-    }),
-    OpenApi.validate('query', schema.getAddressBalances.Query, {
-      code: 'query_invalid',
-      message: 'Invalid query parameters',
-    }),
-    OpenApi.describeRoute({
-      description:
-        'Lists how much of each TIP-20 token an account holds, ordered from largest to smallest balance. Amounts are returned in raw base units and human-readable form, and each verified holding carries its nominal value in the requested denomination.',
-      operationId: 'getAddressBalances',
-      responses: OpenApi.responses({
-        errors: { 502: 'Could not read balance or token data from an upstream service.' },
-        success: {
-          description: 'A page of token balances for this account.',
-          schema: schema.getAddressBalances.Response,
-        },
+  return new Hono<App.Environment>()
+    .get(
+      '/v1/addresses/:address/balances',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getAddressBalances.Params, {
+        code: 'address_invalid',
+        message: 'Invalid account address',
       }),
-      summary: 'List address balances',
-      tags: ['Balances'],
-    }),
-    Cache.response<App.Environment>({
-      cacheControl: Cache.policies.noStore,
-      name: 'tempo-api:addresses:v1',
-      key: (c) => Cache.urlKey(c, schema.getAddressBalances.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')
+      OpenApi.validate('query', schema.getAddressBalances.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Lists how much of each TIP-20 token an account holds, ordered from largest to smallest balance. Amounts are returned in raw base units and human-readable form, and each verified holding carries its nominal value in the requested denomination.',
+        operationId: 'getAddressBalances',
+        responses: OpenApi.responses({
+          errors: { 502: 'Could not read balance or token data from an upstream service.' },
+          success: {
+            description: 'A page of token balances for this account.',
+            schema: schema.getAddressBalances.Response,
+          },
+        }),
+        summary: 'List address balances',
+        tags: ['Balances'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.noStore,
+        name: 'tempo-api:addresses:v1',
+        key: (c) => Cache.urlKey(c, schema.getAddressBalances.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 {
+        try {
+          const chainId = query.chainId ?? c.get('chainId')
+          // `currency` only makes sense against verified tokens, so it implies
+          // `verified=true` from the caller's perspective.
+          const verified = query.verified || query.currency !== undefined
+          const feeEligible = query.feeEligible ?? false
+
+          // The fee-token set powers both the per-row `feeEligible` flag (always)
+          // and the optional `feeEligible=true` page restriction. It is memoized
+          // per chain (a near-constant), so one read feeds the page, the count,
+          // and the row enrichment. It is a best-effort enrichment: a lookup
+          // failure omits `feeEligible` rather than failing the page — unless the
+          // caller explicitly asked to filter by `feeEligible`, where the filter
+          // can't be honored, so the failure surfaces as the declared `502`.
+          const feeTokens = await FeeAmm.feeTokenSet(c, chainId).catch((cause) => {
+            if (feeEligible) throw cause
+            return undefined
+          })
+
+          const balances = await getAddressBalances(c, {
+            address,
+            chainId,
+            currency: query.currency,
+            cursor: query.cursor,
+            denomination: query['valuation.currency'] ?? 'USD',
+            feeEligible,
+            feeTokens,
+            includeTotalCount: query.include.includes('totalCount'),
+            limit: query.limit,
+            oracle,
+            page: query.page,
+            verified,
+          })
+
+          return c.json(Response.validated(schema.getAddressBalances.Response, balances), 200)
+        } catch (cause) {
+          if (cause instanceof Valuation.UnsupportedDenominationError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/addresses/:address/balances/:token',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getAddressBalance.Params, {
+        code: 'address_invalid',
+        message: 'Invalid address or token address',
+      }),
+      OpenApi.validate('query', schema.getAddressBalance.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Returns the live balance of one TIP-20 token held by an account, including token metadata and a human-readable amount.',
+        operationId: 'getAddressBalance',
+        responses: OpenApi.responses({
+          errors: {
+            404: {
+              description: 'The token is not a registered TIP-20 token.',
+              codes: ['token_not_found'],
+            },
+            502: 'Could not read balance or token data from an upstream service.',
+          },
+          success: {
+            description: 'The requested token balance for this account.',
+            schema: schema.getAddressBalance.Response,
+          },
+        }),
+        summary: 'Get address balance',
+        tags: ['Balances'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.noStore,
+        name: 'tempo-api:addresses:v1',
+        key: (c) => Cache.urlKey(c, schema.getAddressBalance.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, token } = c.req.valid('param')
+        const query = c.req.valid('query')
         const chainId = query.chainId ?? c.get('chainId')
-        // `currency` only makes sense against verified tokens, so it implies
-        // `verified=true` from the caller's perspective.
-        const verified = query.verified || query.currency !== undefined
-        const feeEligible = query.feeEligible ?? false
-
-        // The fee-token set powers both the per-row `feeEligible` flag (always)
-        // and the optional `feeEligible=true` page restriction. It is memoized
-        // per chain (a near-constant), so one read feeds the page, the count,
-        // and the row enrichment. It is a best-effort enrichment: a lookup
-        // failure omits `feeEligible` rather than failing the page — unless the
-        // caller explicitly asked to filter by `feeEligible`, where the filter
-        // can't be honored, so the failure surfaces as the declared `502`.
-        const feeTokens = await FeeAmm.feeTokenSet(c, chainId).catch((cause) => {
-          if (feeEligible) throw cause
-          return undefined
-        })
-
-        const balances = await getAddressBalances(c, {
-          address,
-          chainId,
-          currency: query.currency,
-          cursor: query.cursor,
-          denomination: query['valuation.currency'] ?? 'USD',
-          feeEligible,
-          feeTokens,
-          includeTotalCount: query.include.includes('totalCount'),
-          limit: query.limit,
-          oracle,
-          page: query.page,
-          verified,
-        })
 
-        return c.json(Response.validated(schema.getAddressBalances.Response, balances), 200)
-      } catch (cause) {
-        if (cause instanceof Valuation.UnsupportedDenominationError)
-          return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
-        return Response.upstream(c, cause)
-      }
-    },
-  )
+        try {
+          const snapshot = await VerifiedTokens.snapshot(c, chainId)
+          const [balance, resolvedToken] = await Promise.all([
+            Timing.time(c, 'balance_rpc', async () => {
+              const result = await Actions.token.getBalance(c.get('getClient')(chainId), {
+                account: address,
+                token,
+              })
+              return result.amount
+            }),
+            Timing.time(c, 'token', () =>
+              Tokens.resolveToken(c, { address: token, chainId, include: [], snapshot }),
+            ),
+          ])
+          const denomination = query['valuation.currency'] ?? 'USD'
+          const rates = await Valuation.ratesFor(c, {
+            currencies: snapshot.byAddress.has(token) ? [resolvedToken.currency] : [],
+            denomination,
+            oracle,
+          })
+          const feeTokens = await FeeAmm.feeTokenSet(c, chainId).catch(() => undefined)
+
+          return c.json(
+            Response.validated(schema.getAddressBalance.Response, {
+              amount: balance.toString(),
+              currency: resolvedToken.currency,
+              decimals: resolvedToken.decimals,
+              ...(feeTokens ? { feeEligible: feeTokens.has(token) } : {}),
+              formatted: core_Value.format(balance, resolvedToken.decimals),
+              id: token,
+              token: resolvedToken,
+              valuation: Valuation.valuationFor({
+                amount: balance,
+                denomination,
+                rates,
+                token: snapshot.byAddress.get(token),
+              }),
+            }),
+            200,
+          )
+        } catch (cause) {
+          if (Tokens.isTokenNotFound(cause))
+            return Response.error(c, {
+              code: 'token_not_found',
+              message: 'Token not found',
+              status: 404,
+            })
+          if (cause instanceof Valuation.UnsupportedDenominationError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          return Response.upstream(c, cause)
+        }
+      },
+    )
 }
 
 export declare namespace addresses {