tapimo 0.0.0 → 0.0.2

package/src/apps/verified-tokens.test.ts

@@ -0,0 +1,114 @@
+import { Store } from 'cadent'
+
+import * as TestApp from '../../test/App.js'
+import * as Runtime from '../../test/runtime.js'
+import * as VerifiedTokens from '../internal/VerifiedTokens.js'
+import * as Verified from './verified-tokens.js'
+
+// Mutations live in the admin API (`cadent/admin`) and are covered in
+// `../admin/apps/verified-tokens.test.ts`; these tests cover the public reads,
+// seeded by publishing a snapshot through the same core module the admin
+// writes use.
+
+/** Reader key for the data routes. */
+const reader = {
+  id: 'key_reader',
+  orgId: 'org_test',
+  scopes: ['data:read'],
+  token: 'secret_reader',
+} satisfies TestApp.source.Key
+
+/** An address not present in the seed list. */
+const unknownAddress = '0x20c00000000000000000000000000000000000ff'
+
+/** A known list published into the store before exercising the read endpoints. */
+const seedList = [
+  { address: '0x20c0000000000000000000000000000000000001', currency: 'USD', decimals: 6, logoUri: 'https://example.com/susd.svg', name: 'Seed USD', symbol: 'sUSD' }, // prettier-ignore
+  { address: '0x20c0000000000000000000000000000000000002', currency: 'EUR', decimals: 2, name: 'Seed EUR', symbol: 'sEUR' }, // prettier-ignore
+  { address: '0x20c0000000000000000000000000000000000003', currency: 'USD', decimals: 6, name: 'Seed USD Two', symbol: 'sUSD2' }, // prettier-ignore
+] as const
+const chainId = Runtime.get().chainId
+
+/** RequestInit carrying a bearer token for the given key. */
+function as(key: { token: string }) {
+  return { headers: { authorization: `Bearer ${key.token}` } } as const
+}
+
+/** Client whose verified-token store holds a published {@link seedList} snapshot. */
+async function seeded() {
+  const store = Store.memory()
+  await VerifiedTokens.replace(store, chainId, seedList)
+  return TestApp.client({
+    auth: { source: TestApp.source({ keys: [reader] }) },
+    verifiedTokens: { store },
+  })
+}
+
+describe('GET /verified-tokens', () => {
+  test('returns the verified list', async () => {
+    const response = await (await seeded()).v1['verified-tokens'].$get({ query: {} }, as(reader))
+    expect(response.status).toBe(200)
+    const body = await TestApp.json(response, Verified.schema.listVerifiedTokens.Response)
+    expect(body.data.map((token) => token.address)).toEqual(seedList.map((token) => token.address))
+    // The curated `logoUri` rides along when set, and is absent otherwise.
+    expect(body.data[0]?.logoUri).toBe('https://example.com/susd.svg')
+    expect(body.data[1]?.logoUri).toBeUndefined()
+  })
+
+  test('filters by currency (case-insensitive)', async () => {
+    const response = await (
+      await seeded()
+    ).v1['verified-tokens'].$get({ query: { currency: 'usd' } }, as(reader))
+    const body = await TestApp.json(response, Verified.schema.listVerifiedTokens.Response)
+    expect(body.data.length).toBe(2)
+    expect(body.data.every((token) => token.currency.toLowerCase() === 'usd')).toBe(true)
+  })
+
+  test('returns 304 for a matching If-None-Match', async () => {
+    const client = await seeded()
+    const first = await client.v1['verified-tokens'].$get({ query: {} }, as(reader))
+    const etag = first.headers.get('ETag')
+    expect(etag).toBeTruthy()
+    const second = await client.v1['verified-tokens'].$get(
+      { query: {} },
+      { headers: { 'if-none-match': etag! } },
+    )
+    expect(second.status).toBe(304)
+  })
+})
+
+describe('GET /verified-tokens/currencies', () => {
+  test('returns the sorted distinct currencies', async () => {
+    const response = await (
+      await seeded()
+    ).v1['verified-tokens'].currencies.$get({ query: {} }, as(reader))
+    const body = await TestApp.json(response, Verified.schema.getVerifiedTokenCurrencies.Response)
+    expect([...body.data]).toEqual(['EUR', 'USD'])
+  })
+})
+
+describe('GET /verified-tokens/:address', () => {
+  test('returns a seeded entry', async () => {
+    const client = await seeded()
+    const address = seedList[0].address
+    const response = await client.v1['verified-tokens'][':address'].$get(
+      { param: { address }, query: {} },
+      as(reader),
+    )
+    expect(response.status).toBe(200)
+    const body = await TestApp.json(response, Verified.schema.Token)
+    expect(body.address).toBe(address)
+  })
+
+  test('returns 404 for an unknown address', async () => {
+    const response = await (
+      await seeded()
+    ).v1['verified-tokens'][':address'].$get(
+      { param: { address: unknownAddress }, query: {} },
+      as(reader),
+    )
+    expect(response.status).toBe(404)
+    const body = (await response.json()) as { error?: { code?: string } }
+    expect(body.error?.code).toBe('verified_token_not_found')
+  })
+})

package/src/apps/verified-tokens.ts

@@ -0,0 +1,295 @@
+import { type Context, Hono } from 'hono'
+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 VerifiedTokens from '../internal/VerifiedTokens.js'
+
+/** Zod schemas owned by the verified-tokens resource. */
+export namespace schema {
+  // Shared, validated entry fields (everything but the address). Reused across
+  // the response entry, the create body, and the bulk-replace body.
+  const fields = {
+    currency: z
+      .string()
+      .check(
+        z.minLength(1),
+        z.describe(
+          'The currency label for this token, such as `USD` for USD-denominated stablecoins.',
+        ),
+      ),
+    decimals: z
+      .number()
+      .check(
+        z.int(),
+        z.gte(0),
+        z.lte(255),
+        z.describe(
+          'The number of decimal places the token uses; Tempo stablecoins typically use 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.')),
+    symbol: z
+      .string()
+      .check(
+        z.minLength(1),
+        z.describe('The short ticker symbol wallets and apps show for this token.'),
+      ),
+  }
+
+  /**
+   * Verified-token write/input fields, without the server-derived `id`. Reused
+   * as the base for the create body, the patch body, and the bulk-replace body
+   * so clients never supply `id` (it is always derived from `address`).
+   */
+  export const Input = Schema.describe(
+    z.object({
+      address: Schema.Address.check(z.describe('The TIP-20 token contract address on Tempo.')),
+      currency: fields.currency,
+      decimals: fields.decimals,
+      logoUri: fields.logoUri,
+      name: fields.name,
+      symbol: fields.symbol,
+    }),
+    'The fields used to create or update a curated verified TIP-20 token entry.',
+  )
+
+  /**
+   * A curated verified TIP-20 token entry (response shape). The `id` is the
+   * stable resource id, always derived server-side from `address`.
+   */
+  export const Token = Schema.describe(
+    z.extend(Input, {
+      id: z
+        .string()
+        .check(z.describe('A stable resource ID for this token, equal to its contract address.')),
+    }),
+    'One curated, verified TIP-20 token that wallets and apps can present as trusted.',
+  )
+
+  /** Path parameters addressing a single verified token. */
+  export const Params = z
+    .object({
+      address: Schema.TokenAddress.check(z.describe('The TIP-20 token contract address on Tempo.')),
+    })
+    .check(z.describe('Path parameters for looking up one verified token.'))
+
+  /** Schemas for the listVerifiedTokens operation. */
+  export namespace listVerifiedTokens {
+    /** Query parameters for the verified-token list. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        currency: z.optional(z.string()).check(
+          z.meta({ examples: VerifiedTokens.currencies }),
+          z.describe('Only include verified tokens denominated in this currency, such as `USD`. Matching is case-insensitive.'), // prettier-ignore
+        ),
+      })
+      .check(z.describe('Query parameters for listing verified tokens.'))
+
+    /** Non-paginated list of curated verified tokens. */
+    export const Response = Schema.describe(
+      z.object({ data: z.array(Token).check(z.describe('The curated verified TIP-20 tokens.')) }),
+      'A non-paginated list of curated, verified TIP-20 tokens.',
+    )
+  }
+
+  /** Schemas for the getVerifiedTokenCurrencies operation. */
+  export namespace getVerifiedTokenCurrencies {
+    /** Query parameters for the verified-token currencies endpoint. */
+    export const Query = z
+      .strictObject({ chainId: Schema.ChainIdQuery })
+      .check(z.describe('Query parameters for listing currencies used by verified tokens.'))
+
+    /** Sorted, distinct currencies present in a chain's verified list. */
+    export const Response = Schema.describe(
+      z.object({
+        data: z
+          .array(z.string())
+          .check(
+            z.describe('The sorted, unique currency labels used by tokens in the verified list.'),
+          ),
+      }),
+      'The distinct currencies present in a chain’s verified token list.',
+    )
+  }
+
+  /** Schemas for the getVerifiedToken operation. */
+  export namespace getVerifiedToken {
+    /** Query parameters for a single verified token. */
+    export const Query = z
+      .strictObject({ chainId: Schema.ChainIdQuery })
+      .check(z.describe('Query parameters for looking up one verified token.'))
+  }
+}
+
+/**
+ * Mounts the `/verified-tokens` resource (public reads). Mutations live in the
+ * admin API (`tapimo/admin`), which manages the same store these reads serve
+ * their snapshots from.
+ */
+export function verifiedTokens() {
+  return new Hono<App.Environment>()
+    .get(
+      '/',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('query', schema.listVerifiedTokens.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        hide: true,
+        operationId: 'listVerifiedTokens',
+        responses: OpenApi.responses({
+          success: {
+            description: 'The curated verified TIP-20 tokens.',
+            schema: schema.listVerifiedTokens.Response,
+          },
+        }),
+        summary: 'List verified tokens',
+        tags: ['Verified Tokens'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.stable,
+        name: 'tempo-api:verified-tokens:v1',
+        key: (c) => Cache.urlKey(c, schema.listVerifiedTokens.Query),
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid query parameters',
+          })
+
+        const query = c.req.valid('query')
+        const chainId = query.chainId ?? c.get('chainId')
+        try {
+          const snapshot = await VerifiedTokens.snapshot(c, chainId)
+          const data = query.currency
+            ? (snapshot.byCurrency.get(query.currency.toLowerCase()) ?? [])
+            : snapshot.list
+          return c.json(Response.validated(schema.listVerifiedTokens.Response, { data }), 200)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/currencies',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('query', schema.getVerifiedTokenCurrencies.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        hide: true,
+        operationId: 'getVerifiedTokenCurrencies',
+        responses: OpenApi.responses({
+          success: {
+            description: 'The distinct currencies used by verified tokens.',
+            schema: schema.getVerifiedTokenCurrencies.Response,
+          },
+        }),
+        summary: 'List verified currencies',
+        tags: ['Verified Tokens'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.stable,
+        name: 'tempo-api:verified-tokens:v1',
+        key: (c) => Cache.urlKey(c, schema.getVerifiedTokenCurrencies.Query),
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid query parameters',
+          })
+
+        const query = c.req.valid('query')
+        const chainId = query.chainId ?? c.get('chainId')
+        try {
+          const snapshot = await VerifiedTokens.snapshot(c, chainId)
+          return c.json(
+            Response.validated(schema.getVerifiedTokenCurrencies.Response, {
+              data: snapshot.currencies,
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/:address',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.Params, {
+        code: 'address_invalid',
+        message: 'Invalid token address',
+      }),
+      OpenApi.validate('query', schema.getVerifiedToken.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        hide: true,
+        operationId: 'getVerifiedToken',
+        responses: OpenApi.responses({
+          errors: { 404: 'No verified token was found for this address.' },
+          success: {
+            description: 'One verified TIP-20 token from Tempo’s curated list.',
+            schema: schema.Token,
+          },
+        }),
+        summary: 'Get verified token',
+        tags: ['Verified Tokens'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.stable,
+        name: 'tempo-api:verified-tokens:v1',
+        key: (c) => Cache.urlKey(c, schema.getVerifiedToken.Query),
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'address_invalid',
+            message: 'Invalid token address',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid query parameters',
+          })
+
+        const { address } = c.req.valid('param')
+        const query = c.req.valid('query')
+        const chainId = query.chainId ?? c.get('chainId')
+        try {
+          const snapshot = await VerifiedTokens.snapshot(c, chainId)
+          const token = snapshot.byAddress.get(address.toLowerCase())
+          if (!token) return notFound(c)
+          return c.json(Response.validated(schema.Token, token), 200)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+}
+
+function notFound(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'verified_token_not_found',
+    message: 'Verified token not found',
+    status: 404,
+  })
+}